Perform File System Operation (QP0LFLOP) API


  Required Parameter Group:


  Default Public Authority: *USE

  Threadsafe: No

The Perform File System Operation (QP0LFLOP) API performs miscellaneous file system operations.


Authorities and Locks

The authorities required vary for each operation:

(1) QP0L_RETRIEVE_NETGROUP_FILE_ENTRIES
  • The user must have execute (*X) data authority to the /etc directory (if it exists).
  • The user must have read (*R) data authority to the /etc/netgroup file (if it exists).

(2) QP0L_WRITE_NETGROUP_FILE_ENTRIES
  • The user must have write and execute (*WX) data authority to the /etc directory (if it exists).
  • The user must have read and write (*RW) data authority to the /etc/netgroup file (if it exists).

(3) QP0L_RETRIEVE_REMOTE_EXPORTS
No special authority required.

(4) QP0L_RETRIEVE_MOUNTED_FILE_SYSTEMS
No special authority required.

Start of change(5) QP0L_GET_LINK_INFO
see Usage Notes.End of change

Note: Adopted authority is not used.


Required Parameter Group

The following parameters are required.

File system operation
INPUT; BINARY(4), UNSIGNED

The desired file system operation to perform.

You can specify one of the following operations:

(1) QP0L_RETRIEVE_NETGROUP_FILE_ENTRIES
Returns information about all netgroup definitions currently defined in the /etc/netgroup file.

(2) QP0L_WRITE_NETGROUP_FILE_ENTRIES
Recreates the /etc/netgroup file with only the entries provided.

(3) QP0L_RETRIEVE_REMOTE_EXPORTS
Returns all of the Network File System (NFS) exports for a given server.

(4) QP0L_RETRIEVE_MOUNTED_FILE_SYSTEMS
Returns a list of mounted file systems for the local machine along with certain properties of each.

Start of change(5) QP0L_GET_LINK_INFO
Gets information about a link in a directory.End of change

Input buffer
INPUT; CHAR(*)

Information that is required for a given file system operation. The input buffer parameter should be set as follows:

(1) QP0L_RETRIEVE_NETGROUP_FILE_ENTRIES
NULL (no input buffer is required).

(2) QP0L_WRITE_NETGROUP_FILE_ENTRIES
FLOP0200 structure containing the new netgroup entries. For a detailed description of this structure, see Format of FLOP0200 Structure.

(3) QP0L_RETRIEVE_REMOTE_EXPORTS
FLOP0300_INPUT structure containing the remote Network File System (NFS) server name to query the exports from. For a detailed description of this structure, see Format of FLOP0300 Input Structure.

(4) QP0L_RETRIEVE_MOUNTED_FILE_SYSTEMS
FLOP0400_INPUT structure containing the selective filtering information for the mounted file systems requested. For a detailed description of this structure, see Format of FLOP0400 Input Structure.

Start of change(5) QP0L_GET_LINK_INFO
Qlg_Path_Name_T structure containing a path name or a pointer to a path name to the link for which information is required. For more information about the Qlg_Path_Name_T structure, see Path name format.End of change


Length of input buffer
INPUT;BINARY(4), UNSIGNED

The length of the input buffer provided. The length of the input buffer parameter may be specified up to the size of the input buffer area specified by the user program. The length of the input buffer should be 0 when the input buffer is NULL.

Output buffer
OUTPUT; CHAR(*)

Information that is provided by a given file system operation. The output buffer parameter should be set as follows:

(1) QP0L_RETRIEVE_NETGROUP_FILE_ENTRIES
FLOP0100 structure containing enough space to hold all netgroup entries in the /etc/netgroup file. For a detailed description of this structure, see FLOP0100 Structure Description. No partial entries will be returned. To determine if all of the entries were returned, the following semantics will be used:

  • If the /etc/netgroup file has no entries defined, bytes available and bytes returned will both be set to 12.
  • If the /etc/netgroup file has at least one entry defined, then the bytes available will be greater than 12.
  • If all of the defined entries in the /etc/netgroup file could not be returned, then the bytes available will not have the same value as bytes returned.

For example, if the /etc/netgroup file is empty, then bytes available and bytes returned would both be equal to 12. For a different example, if the /etc/netgroup file is not empty, but the length of the output buffer is less than what is required to hold all entries in the /etc/netgroup file, then bytes available would be greater than 12 and bytes returned would be set to 12.

(2) QP0L_WRITE_NETGROUP_FILE_ENTRIES
NULL (no output buffer is required).

(3) QP0L_RETRIEVE_REMOTE_EXPORTS
FLOP0300 structure containing enough space to hold all the export entries from the remote server. For a detailed description of this structure, see FLOP0300 Output Structure Description. No partial entries will be returned. To determine if all of the entries were returned, the following semantics will be used:

  • If the server has no exports to return, bytes available and bytes returned will both be set to 12.
  • If the server is returning at least one export, then the bytes available will be greater than 12.
  • If all of the exports given by the server could not be returned in the space provided, then the bytes available will not have the same value as bytes returned. To retrieve all the entries, the request should be made again using an output buffer of at least this size.

(4) QP0L_RETRIEVE_MOUNTED_FILE_SYSTEMS
FLOP0400 structure containing enough space to hold each of the returned mounted file system entries. For a detailed description of this structure, see FLOP0400 Output Structure Description. No partial entries will be returned. To determine if all of the entries were returned, the following semantics will be used:

  • If there are no mounted file systems meeting the request criteria, bytes available and bytes returned will both be set to 12.
  • If there exists mounted file systems that match the request criteria, then the bytes available will be greater than 12.
  • If all the mounted file system entries that match the request criteria could not fit in the buffer space given, then the bytes available will not have the same value as bytes returned. To retrieve all the entries, the request should be made again using an output buffer of at least this size.

Start of change(5) QP0L_GET_LINK_INFO
A stat64 structure, as defined in the <sys/stat.h> header file. See stat64()--Get File Information (Large File Enabled) for a description of this structure.End of change

Length of output buffer
INPUT; BINARY(4), UNSIGNED

The length of the output buffer provided. The length of the output buffer parameter may be specified up to the size of the output buffer area specified by the user program. The length of the output buffer should be 0 when the output buffer is NULL.

Error code
I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.


Output Buffer Description

The following tables describe the order and format of the data returned in the output buffer for each of the allowable file system operations. For a detailed description of each field, see Field Descriptions.


FLOP0100 Structure Description

This structure is used to return netgroup definitions taken from the /etc/netgroup file.



FLOP0300 Output Structure Description

This structure is used to return export entries given by an NFS server.


 

FLOP0400 Output Structure Description

This structure is used to return mounted file system entries.



Input Buffer Description

The following tables describe the order and format of the data given in the input buffer parameter for each of the allowable file system operations. For a detailed description of each field, see Field Descriptions.


Format of FLOP0200 Structure


 

Format of FLOP0300 Input Structure



Format of FLOP0400 Input Structure



Field Descriptions

Bytes available. The number of bytes of data available to be returned to the user in the output buffer. If all data is returned, bytes available is the same as the number of bytes returned. If the receiver variable was not large enough to contain all of the data, this value is set based on the total number of entries that could be returned.

Bytes returned. The number of bytes of data returned to the user in the output buffer.

CCSID of export item. The CCSID of the export item data. This may not be the same as the Preferred output CCSID if the data cannot be converted to that CCSID.

CCSID of export name. The CCSID of the export name data. This may not be the same as the Preferred output CCSID if the data cannot be converted to that CCSID.

CCSID of MFS name. The CCSID of the MFS name data. This may not be the same as the Preferred output CCSID if the data cannot be converted to that CCSID.

CCSID of mount options. The CCSID of the Mount options data. This may not be the same as the Preferred output CCSID if the data cannot be converted to that CCSID.

CCSID of mount over dir name. The CCSID of the mount over dir name data. This may not be the same as the Preferred output CCSID if the data cannot be converted to that CCSID.

CCSID of remote host name name. The CCSID of the remote host name data. This may not be the same as the Preferred output CCSID if the data cannot be converted to that CCSID.

CCSID of server name. The CCSID of the server name. A value of 0 indicates that the data is in the CCSID of the job.

Displacement to export items. The offset (in bytes) from the beginning of the export entry to the export items in the export entry.

Displacement to member names. The offset (in bytes) from the beginning of the netgroup entry to the member names in the netgroup entry.

Displacement to MFS name. The offset (in bytes) from the beginning of the mount entry to the mounted file system (MFS) name in the entry.

Displacement to mount options. The offset (in bytes) from the beginning of the mount entry to the mount options in the entry.

Displacement to mount over dir name. The offset (in bytes) from the beginning of the mount entry to the mount over dir name in the entry.

Displacement to remote host name. The offset (in bytes) from the beginning of the mount entry to the remote host name in the entry. If the value is 0, then there is no remote host name associated with the mount entry.

Expected CCSID. This value should contain the CCSID that the remote NFS server is expected to return string data in. A value of 0 means to calculate an ASCII CCSID based on the default CCSID of the job (recommended).

Export item. Information item that pertains to the current export. Export items are controlled by the NFS server, and it is not specified what they will contain. They are assumed to be strings and are converted into the Preferred output CCSID, if possible. Normally, an export item contains the hostname of a machine allowed to access or mount the export.

Export name. The pathname of the returned export.

File system id. A number uniquely identifying the mounted file system. Each returned mount entry should have a different file system id.

File system type. Identifies the type of the mounted file system. Refer to the different type values given under the file system type filter field description below.

File system type filter. An ORed value of flags to limit the types of mounted file systems to return. It must be a combination of the following file system type values:

Note: All Dynamic MFS includes all of the dynamically mounted file systems: Network File System (NFS) and User-Defined File Systems (UDFS). These file systems can be mounted on demand in different parts of the namespace.

Note: Netware is no longer supported when specified on input. If it is specified, error CPFB41F will be returned with a reason code of 18.

Length of export entry. The length (in bytes) of the current export entry. The length can be used to access the next entry.

Length of export item. The length (in bytes) of the export item.

Length of export item entry. The length (in bytes) of the current export item entry. The length can be used to access the next entry.

Length of export name. The length (in bytes) of the exported name (export pathname).

Length of member name. The length (in bytes) of the member name.

Length of member name entry. The length (in bytes) of this member name entry.

Length of MFS name. The length (in bytes) of the mounted file system name.

Length of mount entry. The length (in bytes) of the current mount entry. The length can be used to access the next entry.

Length of mount options. The length (in bytes) of the mount options.

Length of mount over dir name. The length (in bytes) of the mount over dir name.

Length of netgroup entry. The length (in bytes) of the current netgroup entry. The length can be used to access the next entry.

Length of netgroup name. The length (in bytes) of the netgroup name.

Length of remote host name. The length (in bytes) of the remote host name. This value will be 0 when the file system is not mounted from a remote host.

Length of server name. The length (in bytes) of the requested server name which follows. The maximum value for this field is 255.

Member name. The member name. This is assumed to be in the CCSID of the job.

Member name status. Describes the type of member name. Possible values follow:

(1) QP0L_MEMBER_IS_A_HOST_NAME
The member name refers to an individual host name.

(2) QP0L_MEMBER_IS_A_NETGROUP_NAME
The member name refers to a netgroup name.

(3) QP0L_MEMBER_IS_AN_IP_ADDRESS
The member name refers to an IP address in the form xxx.xxx.xxx.xxx (for example 123.4.56.78).


MFS name. The name of the mounted file system. This is normally the source path name.

Mount flags. An ORed value of flags that supplies information about how the file system is mounted.

Mount options. The string representation of the valid options used to mount the file system. Valid options vary by the type of the mounted file system.

Mount over dir name. The pathname of the directory that is mounted over by the mounted file system. This is where the mount is accessible in the local system's namespace if the mounted file system is visible.

Mount visibility. A value of 1 indicates this mount has not been mounted over and is accessible (visible) through the parent file system's namespace. A value of 0 indicates the mounted file system has itself been mounted over. Start of change A value of 0xFFFFFFFF indicates that the mounted file system's visibility has not been determined. End of change

Netgroup name. The netgroup name. This is assumed to be in the CCSID of the job.

Number of export entries. The number of complete export entries returned. A value of zero is used if there are no exports available on the server or if insufficient space was provided to hold even a single entry.

Number of export items. The number of export items for this export entry.

Number of member names. The number of member names in the netgroup entry.

Number of mount entries. The number of complete mounted file system entries returned. A value of zero is used if there are no mounts meeting the selection criteria or if insufficient space was provided to hold even a single entry.

Number of netgroup entries. The number of complete entries. A value of zero is used if there are no valid entries for the /etc/netgroup file or if the file does not exist.

Only visible mounts. A value of 1 requests that only visible (accessible, topmost) mounted file systems be retrieved. A value of 0 means to not limit the retrieved mounts based on visiblity. Start of change A value of 0xFFFFFFFF indicates that mount visibility should not be determined. Specifying this value can improve the performance of the operation where mount visibility information is not needed by the application. When this value is specified, the "Mount visibility" field for each retrieved mount will contain 0xFFFFFFFF. End of change

Preferred output CCSID. The CCSID into which the output will be converted. If a conversion failure occurs, the output may be returned in another CCSID. A value of 0 indicates that the data should be returned in the CCSID of the job.

Remote host name. The name of the host on which the source file system resides. This is the machine being mounted from and is only applicable for remote mounts. For local mounts, the value of Displacement to remote host name will be 0, and this value will not be returned.

Server name. The host name of the server to retrieve the Network File System (NFS) export entries from.

Time of mount. The time when the file system was mounted. This time is in seconds since the Epoch. The Epoch is the time 0 hours, 0 minutes, 0 seconds, January 1, 1970, Coordinated Universal Time. If the IBM® i date is set prior to 1970, the time value is zero.

Unique mount id. This value gives an indication of the order in which the file systems were mounted. For example, multiple file systems may be mounted over the same directory. The topmost one (and therefore the one that is visible) will be the one with the largest mount sequence number. The mount sequence numbers will be reset after any system processing which unmounts and mounts file systems, such as IPL and Reclaim Storage (RCLSTG). This value corresponds to the value returned by stat() and similar APIs in the st_vfs field.


Usage Notes

  1. The include file for this API is QP0LFLOP.

  2. If none of the required parameters are passed to this API, then message ID CPFB41F will be issued to the caller. This message lists all of the file operations currently available to the QP0LFLOP API.

  3. WARNING - When the (2) QP0L_WRITE_NETGROUP_FILE_ENTRIES file system operation is requested, the existing /etc/netgroup file will be completely rewritten resulting in a loss of the previous contents of the file.

  4. A netgroup is a way of defining one name (the netgroup name) to represent many other names. The names contained within a netgroup definition are called 'members' of that netgroup. A netgroup member can be either the name of a host system, the name of another netgroup, or an IP address. Netgroup definitions are stored in the /etc/netgroup file and are commonly used by the Network File System (NFS) support when a large group of host systems require common NFS access semantics.

  5. An export entry describes a remote file system or subdirectory in a file system residing on an Network File System (NFS) server that is mountable by an NFS client.

  6. Start of changeThe following considerations apply only to the (5) QP0L_GET_LINK_INFO file system operation:

    • This operation is nearly identical to the QlgLstat64()--Get File or Link Information (large file enabled and using NLS-enabled path name) API. See that API for authority requirements and other usage notes.

    • This operation is only supported for objects in the "root" (/), QOpenSys, and user-defined file systems. If the specified path is in any other file system, the caller will receive message ID CPFA0D4 (File system error occurred) with error number 3440 (ENOTSUP).

    • Most other error conditions will return message ID CPFA0D4 with different error numbers. The error number returned for a specific circumstance may be different than the error number returned by the QlgLstat64() API in that same circumstance.

    • The QP0L_GET_LINK_INFO file system operation gets link information for the specified object without accessing the object's storage by retrieving information from the parent directory of the object, where possible. The QlgLstat64() API always accesses the object's storage to get the information that it returns. This can cause a non-database page fault and negatively affect the performance of the application. In certain situations, the QP0L_GET_LINK_INFO operation can provide much better response time than the QlgLstat64() or related APIs. An application that uses QlgLstat64() to examine many objects and only further accesses a small percentage of those objects would likely benefit by changing to use this file system operation.

      Applications will likely see no benefit from such a change if they frequently perform some other operation on the object after calling the QlgLstat64() API, such as opening, renaming, or unlinking the object. Also, an application that only worked with a small set of objects would likely see no benefit from this file system operation. In both cases, it is possible that application performance would be degraded by using the QP0L_GET_LINK_INFO file system operation rather than the QlgLstat64() API. End of change


Error Messages


API introduced: V4R3