Integrated File System APIs

The integrated file system is a part of i5/OS^(TM) that supports stream input/output and storage management similar to personal computer and UNIX^(R) operating systems while providing an integrating structure over all information stored in your server.

The stream file support is designed for efficient use in client/server applications. Stream files are particularly well suited for storing long continuous strings of data such as the text of documents, images, audio, and video.

The integrated file system provides a hierarchical directory structure that supports UNIX-based open system standards, such as Portable Operating System Interface for Computer Environments (POSIX)** and The Single UNIX^(R); Specification. This file and directory structure provides the users of PC operating systems with a familiar environment.

In addition to providing an interface for users and application to access stream files, the integrated file system also provides a common interface to access database files, documents and other objects stored on the server.

For more information, see the Integrated file system information in the Files and file systems topic.

The integrated file system APIs are:

• access() (Determine file accessibility) determines whether a file can be accessed in a particular manner.
• accessx() (Determine File Accessibility for a Class of Users) determines whether a file can be accessed by a specified class of users in a particular manner.
• chdir() (Change current directory) makes the directory named by path the new current directory.
• chmod() (Change file authorizations) changes the mode of the file or directory specified in path.
• chown() (Change owner and group of file) changes the owner and group of a file.
• close() (Close file descriptor) closes a descriptor, fildes.
• closedir() (Close directory) closes the directory stream indicated by dirp.
• creat() (Create new file or rewrite existing file) creates a new file or rewrites an existing file so that it is truncated to zero length.
• creat64() (Create new file or rewrite existing file (large file enabled)) creates a new file or rewrites an existing file so that it is truncated to zero length.
• DosSetFileLocks() (Lock and unlock a range of an open file) locks and unlocks a range of an open file.
• DosSetFileLocks64() (Lock and unlock a range of an open file (large file enabled)) locks and unlocks a range of an open file.
• DosSetRelMaxFH() (Change maximum number of file descriptors) requests that the system change the maximum number of file descriptors for the calling process (job).
• dup() (Duplicate open file descriptor) returns a new open file descriptor.
• dup2() (Duplicate open file descriptor to another descriptor) returns a descriptor with the value fildes2.
• faccessx() (Determine File Accessibility for a Class of Users) determines whether a file can be accessed by a specified class of users in a particular manner.
• fchdir() (Change Current Directory by Descriptor) makes the directory named by fildes the new current directory.
• fchmod() (Change file authorizations by descriptor) sets the file permission bits of the open file identified by fildes, its file descriptor.
• fchown() (Change owner and group of file by descriptor) changes the owner and group of a file.
• fclear() (Write (Binary Zeros) to Descriptor) clears a file.
• fclear64() (Write (Binary Zeros) to Descriptor (Large File Enabled)) clears a file.
• fcntl() (Perform file control command) performs various actions on open descriptors.
• fpathconf() (Get configurable path name variables by descriptor) determines the value of a configuration variable (name) associated with a particular file descriptor (file_descriptor).
• fstat() (Get file information by descriptor) gets status information about the file specified by the open file descriptor file_descriptor and stores the information in the area of memory indicated by the buf argument.
• fstat64() (Get file information by descriptor (large file enabled)) gets status information about the file specified by the open file descriptor file_descriptor and stores the information in the area of memory indicated by the buf argument.
• fstatvfs() (Get File System Information by Descriptor) gets status information about the file system that contains the file referenced by the open file descriptor fildes.
• fstatvfs64() (Get file system information by descriptor (64-bit enabled)) gets status information about the file system that contains the file referred to by the open file descriptor fildes.
• fsync() (Synchronize changes to file) transfers all data for the file indicated by the open file descriptor file_descriptor to the storage device associated with file_descriptor.
• ftruncate() (Truncate file) truncates the file indicated by the open file descriptor file_descriptor to the indicated length.
• ftruncate64() (Truncate file (large file enabled)) truncates the file indicated by the open file descriptor file_descriptor to the indicated length.
• getcwd() (Get Current Directory) determines the absolute path name of the current directory and stores it in buf.
• getegid (Get effective group ID) returns the effective group ID (gid) of the calling thread.
• geteuid() (Get effective user ID) returns the effective user ID (uid) of the calling thread.
• getgid() (Get real group ID) returns the real group ID (gid) of the calling thread.
• getgrgid() (Get group information using group ID) returns a pointer to an object of type struct group containing an entry from the user database with a matching gid.
• getgrgid_r() (Get group information using group ID) updates the group structure pointed to by grp and stores a pointer to that structure in the location pointed to by result.
• getgrgid_r_ts64() (Get group information using group ID) updates the group structure pointed to by grp and stores a pointer to that structure in the location pointed to by result.
• getgrnam() (Get group information using group name) returns a pointer to an object of type struct group containing an entry from the user database with a matching name.
• getgrnam_r() (Get group information using group name) updates the group structure pointed to by grp and stores a pointer to that structure in the location pointed to by result.
• getgrnam_r_ts64() (Get group information using group name) updates the group structure pointed to by grp and stores a pointer to that structure in the location pointed to by result.
• getgroups() (Get group IDs) returns the number of primary and supplementary group IDs associated with the calling thread without modifying the array pointed to by the grouplist argument.
• getpwnam() (Get user information for user name) returns a pointer to an object of type struct passwd containing an entry from the user database with a matching name.
• getpwnam_r() (Get User Information for User Name) updates thepasswdstructure pointed to bypwdand stores a pointer to that structure in the location pointed to byresult.
• getpwnam_r_ts64() (Get user information for user name) updates the passwd structure pointed to by pwd and stores a pointer to that structure in the location pointed to by result.
• getpwuid() (Get user information for user ID) returns a pointer to an object of type struct passwd containing an entry from the user database with a matching uid.
• getpwuid_r() (Get User Information for User ID) updates thepasswdstructure pointed to bypwdand stores a pointer to that structure in the location pointed to byresult.
• getpwuid_r_ts64() (Get user information for user ID) updates the passwd structure pointed to by pwd and stores a pointer to that structure in the location pointed to by result.
• getuid() (Get real user ID) returns the real user ID (uid) of the calling thread.
• ioctl() (Perform I/O control request) performs control functions (requests) on a file descriptor.
• lchown() (Change owner and group of symbolic link) changes the owner and group of a file. If the named file is a symbolic link, lchown() changes the owner or group of the link itself rather than the object to which the link points.
• link() (Create link to file) provides an alternative path name for the existing file, so that the file can be accessed by either the existing name or the new name.
• lseek() (Set file read/write offset) changes the current file offset to a new position in the file.
• lseek64() (Set file read/write offset (large file enabled)) changes the current file offset to a new position in the file.
• lstat() (Get file or link information) gets status information about a specified file and places it in the area of memory pointed to by buf.
• lstat64() (Get file or link information (large file enabled)) gets status information about a specified file and places it in the area of memory pointed to by buf.
• mkdir() (Make directory) creates a new, empty directory whose name is defined by path.
• mkfifo() (Make FIFO special file) creates a new FIFO special file (FIFO) whose name is defined by path.
• mmap() (Memory map a file) establishes a mapping between a process' address space and a stream file.
• mmap64() (Memory map a stream file (large file enabled)) is used to establish a memory mapping of a file.
• mprotect() (Change access protection for memory mapping) is used to change the access protection of a memory mapping to that specified by protection.
• msync() (Synchronize modified data with mapped file) can be used to write modified data from a shared mapping (created using the mmap() function) to non-volatile storage or invalidate privately mapped pages.
• munmap() (Remove memory mapping) removes addressability to a range of memory mapped pages of a process's address space.
• open() (Open file) opens a file and returns a number called a file descriptor.
• open64() (Open file (large file enabled)) opens a file and returns a number called a file descriptor.
• opendir() (Open directory) opens a directory so that it can be read with the readdir() function.
• pathconf() (Get configurable path name variables) lets an application determine the value of a configuration variable (name) associated with a particular file or directory (path).
• pipe() (Create interprocess channel) creates a data pipe and places two file descriptors, one each into the arguments fildes[0] and fildes[1], that refer to the open file descriptions for the read and write ends of the pipe, respectively.
• pread() (Read from Descriptor with Offset) readsnbytebytes of input into the memory area indicated bybuf.
• pread64() (Read from Descriptor with Offset (large file enabled)) readsnbytebytes of input into the memory area indicated bybuf.
• pwrite() (Write to Descriptor with Offset) writesnbytebytes frombufto the file associated withfile_descriptor.
• pwrite64() (Write to Descriptor with Offset (large file enabled)) writesnbytebytes frombufto the file associated withfile_descriptor.
• QlgAccess() (Determine file accessibility (using NLS-enabled path name)) determines whether a file can be accessed in a particular manner.
• QlgAccessx() (Determine File Accessibility for a Class of Users (using NLS-enabled path name)) determines whether a file can be accessed in a particular manner by a specified class of users.
• QlgChdir() (Change current directory (using NLS-enabled path name)) makes the directory named by path the new current directory.
• QlgChmod() (Change file authorizations (using NLS-enabled path name)) changes the mode of the file or directory specified in path.
• QlgChown() (Change owner and group of file (using NLS-enabled path name)) changes the owner and group of a file.
• QlgCreat() (Create or rewrite file (using NLS-enabled path name)) creates a new file or rewrites an existing file so that it is truncated to zero length.
• QlgCreat64() (Create or rewrite a file (large file enabled and using NLS-enabled path name)) creates a new file or rewrites an existing file so that it is truncated to zero length.
• QlgCvtPathToQSYSObjName() (Resolve integrated file system path name into QSYS object name (using NLS-enabled path name)) resolves a given integrated file system path name into the three-part QSYS.LIB file system name: library, object, and member.
• QlgGetAttr() (Get attributes (using NLS-enabled path name)) gets one or more attributes, on a single call, for the object that is referred to by the input Path_Name.
• QlgGetcwd() (Get current directory (using NLS-enabled path name)) determines the absolute path name of the current directory and returns a pointer to it.
• QlgGetPathFromFileID() (Get path name of object from its file ID (using NLS-enabled path name)) determines an absolute path name of the file identified by fileid and stores it in buf.
• QlgGetpwnam() (Get user information for user name (using NLS-enabled path name)) returns a pointer to an object of type struct qplg_passwd containing an entry from the user database with a matching name.
• QlgGetpwnam_r() (Get user information for user name (using NLS-enabled path name)) updates the qplg_passwd structure pointed to by pwd and stores a pointer to that structure in the location pointed to by result.
• QlgGetpwuid() (Get user information for user ID (using NLS-enabled path name)) returns a pointer to an object of type struct qplg_passwd containing an entry from the user database with a matching user ID (UID).
• QlgGetpwuid_r() (Get user information for user ID (using NLS-enabled path name)) updates the qplg_passwd structure pointed to by pwd and stores a pointer to that structure in the location pointed to by result.
• QlgLchown() (Change owner and group of symbolic link (using NLS-enabled path name)) changes the owner and group of a file.
• QlgLink() (Create link to file (using NLS-enabled path name)) provides an alternative path name for the existing file so that the file can be accessed by either the existing name or the new name.
• QlgLstat() (Get file or link information (using NLS-enabled path name)) gets status information about a specified file and places it in the area of memory pointed to by buf.
• QlgLstat64() (Get file or link information (large file enabled and using NLS-enabled path name)) gets status information about a specified file and places it in the area of memory pointed to by buf.
• QlgMkdir() (Make directory (using NLS-enabled path name)) creates a new, empty directory whose name is defined by path.
• QlgMkfifo() (Make FIFO special file (using NLS-enabled path name)) creates a new FIFO special file whose name is defined by path.
• QlgOpen() (Open a file (using NLS-enabled path name)) opens a file or creates a new, empty file whose name is defined by path and returns a number called a file descriptor.
• QlgOpen64() (Open file (large file enabled and using NLS-enabled path name)) opens a file and returns a number called a file descriptor.
• QlgOpendir() (Open directory (using NLS-enabled path name)) opens a directory so it can be read.
• QlgPathconf() (Get configurable path name variables (using NLS-enabled path name)) lets an application determine the value of a configuration variable (name) associated with a particular file or directory (path).
• QlgProcessSubtree() (Process a path name (using NLS-enabled path name)) searches the directory tree under a specific path name.
• QlgReaddir() (Read directory entry (using NLS-enabled path name)) returns a pointer to a structure describing the next directory entry in the directory stream associated with dirp.
• QlgReaddir_r() (Read directory entry (using NLS-enabled path name)) initializes a structure that is referenced by entry to represent the next directory entry in the directory stream that is associated with dirp.
• QlgReadlink() (Read value of symbolic link (using NLS-enabled path name)) places the contents of the symboliclink path in the buffer buf.
• QlgRenameKeep() (Rename file or directory, keep "new" if it exists (using NLS-enabled path name)) renames a file or a directory specified by old to the name given by new.
• QlgRenameUnlink() (Rename file or directory, unlink "new" if it exists (using NLS-enabled path name)) renames a file or a directory specified by old to the name given by new.
• QlgRmdir() (Remove directory (using NLS-enabled path name)) removes a directory, path, provided that the directory is empty; that is, the directory contains no entries other than 'dot' (.) or 'dot-dot' (..).
• QlgSaveStgFree() (Save Storage Free (using NLS-enabled path name)) calls a user-supplied exit program to save an *STMF iSeries object type and, upon successful completion of the exit program, frees the storage for the object and marks the object as storage freed.
• QlgSetAttr() (Set attributes (using NLS-enabled path name)) sets one of a set of defined attributes, on each call, for the object that is referred to by the input *Path_Name.
• QlgStat() (Get file information (using NLS-enabled path name)) gets status information about a specified file and places it in the area of memory pointed to by the buf argument.
• QlgStat64() (Get file information (large file enabled and using NLS-enabled path name)) gets status information about a specified file and places it in the area of memory pointed to by the buf argument.
• QlgStatvfs() (Get file system information (using NLS-enabled path name)) gets status information about the file system that contains the file named by the path argument.
• QlgStatvfs64() (Get file system information (64-bit enabled and using NLS-enabled path name)) gets status information about the file system that contains the file named by the path argument.
• QlgSymlink() (Make symbolic link (using NLS-enabled path name)) creates the symbolic link named by slink with the value specified by pname.
• QlgUnlink() (Remove link to file (using NLS-enabled path name)) removes a directory entry that refers to a file.
• QlgUtime() (Set file access and modification times (using NLS-enabled path name)) sets the access and modification times of path to the values in the utimbuf structure.
• QP0FPTOS (Perform Miscellaneous File System Functions) performs a variety of file system functions.
• QP0LCHSG (Change Scan Signature) changes the scan key signature associated with a specific scan key.
• Qp0lCvtPathToQSYSObjName() (Resolve integrated file system path name into QSYS object name) resolves a given integrated file system path name into the three-part QSYS.LIB file system name: library, object, and member.
• QP0LFLOP (Perform file system operation) performs miscellaneous file system operations.
• Qp0lGetAttr() (Get attributes) gets one or more attributes, on a single call, for the object that is referred to by the input Path_Name.
• Qp0lGetPathFromFileID() (Get path name of object from its file ID) determines an absolute path name of the file identified by fileid and stores it in buf.
• Qp0lOpen() (Open file) opens a file and returns a number called a file descriptor.
• Qp0lProcessSubtree() (Process a path name) searches the directory tree under a specific path name. It selects and passes objects, one at a time, to an exit program that is identified on its call. The exit program can be either a procedure or a program.
• Qp0lRenameKeep() (Rename file or directory, keepnewif it exists) renames a file or a directory specified by old to the name given by new.
• Qp0lRenameUnlink() (Rename file or directory, unlinknewif it exists) renames a file or a directory specified by old to the name given by new.
• QP0LROR (Retrieve Object References) retrieves information about integrated file system references on an object.
• QP0LRRO (Retrieve Referenced Objects) retrieves usage information about integrated file system objects that have been referenced by a specified job.
• QP0LRTSG (Retrieve Scan Signature) retrieves the scan key signature associated with a specific scan key.
• Qp0lSaveStgFree() (Save Storage Free) calls a user-supplied exit program to save an *STMF iSeries object type and, upon successful completion of the exit program, frees the storage for the object and marks the object as storage freed.
• Qp0lSetAttr() (Set attributes) renames a file or a directory specified by old to the name given by new.
• Qp0lUnlink() (Remove link to file) removes a directory entry that refers to a file.
• Qp0zPipe() (Create interprocess channel with sockets) creates a data pipe that can be used by two processes.
• qsygetgroups() (Get Supplemental Group IDs) returns the supplemental group IDs associated with the calling thread.
• qsysetegid() (Set effective group ID) sets the effective group ID to gid.
• qsyseteuid() (Set effective user ID) sets the effective user ID to uid.
• qsysetgid() (Set group ID) sets the real, effective and saved groups to gid.
• qsysetgroups() (Set Supplemental Group IDs) sets the supplementary group IDs of the calling thread.
• qsysetregid() (Set real and effective group IDs) is used to set the real and effective group IDs. The real and effective group IDs may be set to different values in the same call.
• qsysetreuid() (Set real and effective user IDs) sets the real and effective user IDs to the values specified by ruid and euid.
• qsysetuid() (Set user ID) sets the real, effective, and saved user ID to uid.
• QZNFRTVE (Retrieve network file system export entries) returns the list of Network File System (NFS) export entries for objects currently exported to NFS clients or for objects referenced in the /etc/exports file.
• read() (Read from Descriptor) reads nbyte bytes of input into the memory area indicated by buf.
• readdir() (Read directory entry) returns a pointer to a dirent structure describing the next directory entry in the directory stream associated with dirp.
• readdir_r() (Read directory entry) initializes the dirent structure that is referenced by entry to represent the next directory entry in the directory stream that is associated with dirp.
• readdir_r_ts64() (Read directory entry) initializes the dirent structure that is referenced by entry to represent the next directory entry in the directory stream that is associated with dirp.
• readlink() (Read value of symbolic link) places the contents of the symbolic link path in the buffer buf.
• readv() (Read from Descriptor Using Multiple Buffers) is used to receive data from a file or socket descriptor.
• rename() (Rename file or directory) is used to rename a file or directory with the semantics of Qp0lRenameUnlink() or Qp0lRenameKeep().
• rewinddir() (Reset directory stream) 'rewinds' the position of an open directory stream to the beginning.
• rmdir() (Remove directory) removes a directory, path, provided that the directory is empty; that is, the directory contains no entries other than 'dot' (.) or 'dot-dot' (..).
• stat() (Get file information) gets status information about a specified file and places it in the area of memory pointed to by the buf argument.
• stat64() (Get file information (large file enabled)) gets status information about a specified file and places it in the area of memory pointed to by the buf argument.
• statvfs() (Get file system information) gets status information about the file system that contains the file named by the path argument.
• statvfs64() (Get file system information (large file enabled)) gets status information about the file system that contains the file named by the path argument.
• symlink() (Make symbolic link) creates the symbolic link named by slink with the value specified by pname.
• sysconf() (Get system configuration variables) returns the value of a system configuration option.
• umask() (Set authorization mask for job) changes the value of the file creation mask for the current job to the value specified in cmask.
• unlink() (Remove link to file) removes a directory entry that refers to a file.
• utime() (Set file access and modification times) sets the access and modification times of path to the values in the utimbuf structure.
• write() (Write to Descriptor) writes nbyte bytes from buf to the file or socket associated with file_descriptor.
• writev() (Write to Descriptor Using Multiple Buffers) is used to write data to a file or socket descriptor.

The integrated file system exit programs are:

• Integrated File System Scan on Close exit program is called during close processing such as with the close()API. This exit program must be provided by the user.
• Integrated File System Scan on Open exit program is called during open processing such as with the open()API. This exit program must be provided by the user.
• Process a Path Name is called by the Qp0lProcessSubtree()API for each object in the API's search that meets the caller's selection criteria. This exit program must be provided by the user.
• Save Storage Free is called by the Qp0lSaveStgFree() API to save an *STMF iSeries object type.

In addition to the functions above, the following functions, which are described in the Sockets APIs, also can operate on files in the integrated file system.

Note: These functions use header (include) files from the library QSYSINC, which is optionally installable. Make sure QSYSINC is installed on your system before using any of the functions. See Header Files for UNIX-Type Functions) for the file and member name of each header file.

Many of the terms used in this chapter, such as current directory, file system, path name, and link, are explained in the Integrated file system information. The API Examples also shows an example of using several integrated file system functions.

To determine whether a particular function updates the access, change, and modification times of the object on which it performs an operation, see Integrated File System APIs--Time Stamp Updates.