View source for IFS - FSD System Interfaces

{{IFSRef}}
{{IBM-Reprint}}

==Overview==
Installable file system entry points are called by the kernel as a result of action taken through the published standard file I/O application programming interface in OS/2 Version 2.0.

Installable file systems are installed as OS/2 dynamic link library modules. Unlike device drivers, they may include any number of segments, all of which will remain after initialization, unless the FSD itself takes some action to free them.

An FSD exports FS entries to the OS/2 kernel using standard PUBLIC declarations. Each FS entry is called directly. The OS/2 kernel manages the association between internal data structures and FSDs.

When a file system service is required, OS/2 assembles an argument list, and calls the appropriate FS entry for the relevant FSD. If a back-level FSD is loaded, the OS/2 kernel assures that all arguments passed and all structures passed are understood by the FSD.

Application program interfaces that are unsupported by an FSD receive an UNSUPPORTED FUNCTION error from the FSD.

Certain routines, for example, FS_PROCESSNAME, may provide no processing, no processing is needed, or processing does not make sense. These routines return no error, not ERROR_NOT_SUPPORTED.

==Data Structures==
OS/2 data structures that include a pointer to the file system driver, as well as file system specific data areas are:
*the CDS (current directory structure)
*the SFT (system file table entry),
*the VPB (volume parameter block)
*the file search structures.
File system service routines are generally passed pointers to two parameter areas, in addition to read-only parameters which are specific to each call. The FSD does not need to verify these pointers. The two parameter areas contain file-system-independent data which is maintained jointly by OS/2 and the file system driver and file-system-dependent data which is unused by OS/2 and which may be used in any way by the file system driver. The file system driver is generally permitted to use the file-system-dependent information in any way. The file-system- dependent information may contain all the information needed to describe the current state of the file or directory, or it may contain a handle which will direct it to other information about the file maintained within the FSD. Handles must be GDT selectors because any SFT, CDS, or VPB may be seen by more than one process. File-system-dependent and file-system-independent parameter areas are defined by data structures described in the remainder of this section.

===Disk media and file system layout===
are described by the following structures. The data which is provided to the file system may depend on the level of file system support provided by the device driver attached to the block device. These structures are relevant only for local file systems.
<PRE>
/* file system independent - volume parameters */

struct vpfsi {
    unsigned long  vpi_vid;        /* 32 bit volume ID */
    unsigned long  vpi_hDEV;       /* handle to device driver */
    unsigned short vpi_bsize;      /* sector size in bytes */
    unsigned long  vpi_totsec;     /* total number of sectors */
    unsigned short vpi_trksec;     /* sectors / track */
    unsigned short vpi_nhead;      /* number of heads */
    char           vpi_text[12];   /* ASCIIZ volume name */
    void far *     vpi_pDCS;       /* device capability structure */
    void far *     vpi_pVCS;       /* volume characteristics */
    unsigned char  vpi_drive;      /* drive (0=A) */
    unsigned char  vpi_unit;       /* unit code */
};

/* file system dependent - volume parameters */

struct vpfsd {
    char           vpd_work[36];   /* work area */
};
</PRE>

===Per-disk current directories===
are described by the following structures. These structures can only be modified by the FSD during FS_ATTACH and FS_CHDIR operations.
<PRE>
/* file system independent - current directories */

struct cdfsi {
    unsigned short cdi_hVPB;           /* VPB handle for associated device */
    unsigned short cdi_end;            /* offset to root of path */
    char           cdi_flags;          /* FS independent flags */
    char           cdi_curdir[260];    /* text of current directory */
};

/* file system dependent - current directories */

struct cdfsd {
    char           cdd_work[8];        /* work area */
};
</PRE>

===Open files===
are described by data initialized at file open time and discarded at the time of last close of all file handles which had been associated with that open instance of that file. There may be multiple open file references to the same file at any one time.

All time stamps on files are stamped and propagated to other SFTs by OS/2 when the file is closed or committed (flushed). For example, if a file is opened at time 1, written at time 2, and closed at time 3, the last write time is time 3. Subdirectories need only have creation time stamps because the last write and last read time stamps on subdirectories are either very difficult to implement (propagate up to parent subdirectories), or are not very useful. An FSD, however, may implement them. FSDs are required to support direct access opens. These are indicated by a bit set in the sffsi.sfi_mode field.
<PRE>
/* file system independent - file instance */

struct sffsi {
    unsigned long   sfi_mode;       /* access/sharing mode */
    unsigned short  sfi_hVPB;       /* volume info. */
    unsigned short  sfi_ctime;      /* file creation time */
    unsigned short  sfi_cdate;      /* file creation date */
    unsigned short  sfi_atime;      /* file access time */
    unsigned short  sfi_adate;      /* file access date */
    unsigned short  sfi_mtime;      /* file modification time */
    unsigned short  sfi_mdate;      /* file modification date */
    unsigned long   sfi_size;       /* size of file */
    unsigned long   sfi_position;   /* read/write pointer */

/* the following may be of use in sharing checks */

    unsigned short  sfi_UID;        /* user ID of initial opener */
    unsigned short  sfi_PID;        /* process ID of initial opener */
    unsigned short  sfi_PDB;        /* PDB (in 3.x box) of initial opener */
    unsigned short  sfi_selfsfn;    /* system file number of file instance */
    unsigned char   sfi_tstamp;     /* time stamp flags */
    unsigned short  sfi_type;       /* type of object opened */
    unsigned long   sfi_pPVDBFil;   /* performance counter data block pointer */
    unsigned char   sfi_DOSattr;    /* DOS file attributes D/S/A/H/R */
};

/* file system dependent - file instance */

struct sffsd {
    char            sfd_work[30];   /* work area */
};
</PRE>
The Program Data Block, or PDB (sfi_pdb), is the unit of sharing for DOS mode processes. For OS/2 mode processes, the unit of sharing is the Process ID, PID (sfi_pid). FSDs should use the combination PDB, PID, UID as indicating a distinct process.

===File search records===
<PRE>
/* file system independent - file search parameters */

struct fsfsi {
        unsigned short  fsi_hVPB;       /* volume info. */
};

/* file system dependent - file search parameters */

struct fsfsd {
        char            fsd_work[24];   /* work area */
};
</PRE>
Existing file systems that conform to the Standard Application Program Interface (Standard API) described in this section, may not necessarily support all the described information kept on a file basis. When this is the case, file system drivers are required to return to the application a null (zero) value for the unsupported parameter (when the unsupported data are a subset of the data returned by the API) or to return a ERROR_NOT_SUPPORTED error (when all of the data returned by the API is unsupported).

===Time Stamping===
All time stamps on files are stamped and propagated to other SFTs when the file is closed or committed (flushed). If a file is opened at time 1, written to at time 2, and closed at time 3, the last write time will be time 3. Subdirectories only have creation time stamps.

The sfi_tstamp field of the file instance structure sffsi contains six flags:
{|class="wikitable"
!Name||Value||Description
|-
|ST_SCREAT||1||stamp creation time
|-
|ST_PCREAT||2||propagate creation time
|-
|ST_SWRITE||4||stamp last write time
|-
|ST_PWRITE||8||propagate last write time
|-
|ST_SREAD||16||stamp last read time
|-
|ST_PREAD||32||propagate last read time
|}
These flags are cleared when an SFT is created, and some of them may eventually be set by a file system worker routine. They are examined when the file is closed or flushed.

For each time stamp, there are three meaningful actions:
{|class="wikitable"
!ST_Sxxx||ST_Pxxx||Action
|-
|clear||clear||don't do anything
|-
|set||set||stamp and propagate (to other SFTs and disk)
|-
|clear||set||don't stamp, but propagate existing value
|}

[[Category:IFS]]