Perform File System Operation (QP0LFLOP) API

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.

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.

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.

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.

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), User-Defined File Systems (UDFS), and Netware. These file systems can be mounted on demand in different parts of the namespace.

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 on 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 accessble (visible) through the parent file system's namespace. A value of 0 indicates the mounted file system has itself been mounted over.

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.

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.

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 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.

Error Messages