w_getmntent (BPX1GMN, BPX4GMN) — Get information on mounted file systems

Function

The w_getmntent callable service gets information about mounted file systems.

Requirements

Parameters

Buffer_length

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the size of the specified buffer.

Buffer

Parameter supplied and returned

Type:

Structure

Length:

Specified by the Buffer_length parameter

The name of the buffer where the information about the mount entries is stored. The area consists of a header followed by a series of entries describing the file systems, all of which are mapped by BPXYMNTE. For information about the content of this area, see BPXYMNTE — Map response and element structure of w_getmntent.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the w_getmntent service returns the number of mount entries that were written to the buffer, or -1 if unsuccessful. A 0 indicates that no more mount entries were found.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the w_getmntent service stores the return code. The w_getmntent service returns Return_code only if Return_value is -1. For a complete list of possible return code values, see z/OS UNIX System Services Messages and Codes. The w_getmntent service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EINVAL	Parameter error; for example, the buffer is too short to hold one entry, or the mount header portion of the buffer was not cleared before the first call. The following reason codes can accompany the return code: JRBuffTooSmall, JRInvalidCursor, JRInvalidParms, and JRFilesysNotThere.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the w_getmntent service stores the reason code. The w_getmntent service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes.

Usage notes

1. Except for the situation that is described in Usage Note 5 or in Usage Note 7, before a program calls w_getmntent for the first time, the header part of the buffer must be cleared to zeros. For information about the format and length of this header, refer to BPXYMNTE — Map response and element structure of w_getmntent.
2. If more than one call is made to w_getmntent, use the same buffer on each call, because part of the information that is returned in the buffer tells the file system where to continue retrieving its information.
3. The w_getmntent call normally returns information about as many file systems as are mounted, or as many as fit in the passed buffer. The number of entries that are contained in the buffer is returned. The caller must have a buffer large enough to receive information about at least a single mount entry with each call. If a zero-length buffer is passed, no information is returned, but the return value contains the total number of mounted file systems. This value could then be used to get enough storage to retrieve information about all these file systems in one additional call.

   If no parameter was specified when the file system was mounted, MNTENTPARMLEN and MNTENTPARMOFFSET are each zero. If a parameter was specified, its address is the sum of the address of MNTE and the contents of MNTENTPARMOFFSET.

   If an entry together with its mount parameter does not fit in the buffer, the entry is returned without the mount parameter. In this case, MNTENTPARMLEN contains the length of the mount parameter, and MNTENTPARMOFFSET is zero. To ensure that at least one entry, including the mount parameter, is returned, you should allocate space for at least two entries.

   A device number of x40000000 can be provided to indicate the returned path name should be up to 64 bytes of the mount point path name at the time of the mount.

4. You could also retrieve all mount entries by setting up a loop that continues to call w_getmntent until a return value of either -1 (in an error) or 0 (no more entries found) is returned.
5. Information about a specific file system can be obtained if the device number of that file system is known. In this case, the device number can be filled into the header of the buffer along with the eye catcher for the buffer, and the w_getmntent call returns a single entry with information about that file system. Or a device number value of x40000000 can be used to indicate that the returned path name should be up to 64 bytes of the mount point path name at the time of the mount.
6. If the caller of w_getmntent lacks search authorization to one or more of the directories in the mount point, or if the file system is being mounted asynchronously, MNTENTMOUNTPOINT is returned empty. That is, MNTENTPATHLEN is zero and MNTENTMOUNTPOINT contains a null character as the first character. The lack of search authorization might be caused by permission bits, ACLs and the FSACESS class checks for each file system that is traversed.
7. If the caller of w_getmntent is requesting the additional information that is available in the expanded MNTE data structure, MNT2, the caller must construct the buffer according to the following rules:
   1. The buffer must be an appropriate size to hold the additional data that will be returned with the MNT2 version of the control block.
   2. The eye-catcher in the MNTE header must be filled in with the MNT2 value.
   3. The bodylength field, also in the header, must be set to the length of the MNTE2 body.
8. If an entry together with its system list does not fit in the buffer, the entry is returned without the system list. In this case, the MNTENTSYSLISTOFFSET is zero, and MNTENTSYSLISTLENGTH contains the length of the system list.
9. When an aggregate name is present for a file system, it is included in the output if there is room for it. The offset field is set to the offset of the name from the beginning of this mount entry, and the length field is set to the length of the name. If the offset is zero and the length is nonzero, this indicates that there is an aggregate name, but there was not enough space left in the output buffer to hold it. In this case, the length field tells the program how much more space is needed.

   Aggregate names are present for zFS file systems. They may be up to 44 characters long, and are returned in a string that is terminated by a null character. The returned length does not include the null terminator byte.

10. A value returned in the MNTENTROSECLABEL (read-only security label) indicates that the file system is protected with that security label. The absence of a value in this field indicates only that a read-only security label is not in effect for that file system, and does not mean that the file system contents are not protected with security labels.
11. Be aware that the size of the mount table could change (for instance, due to automount activity) in the interval between successive w_getmntent calls.

Related services

• mount (BPX1MNT) — Make a file system available
• umount (BPX1UMT, BPX4UMT) — Remove a virtual file system

Characteristics and restrictions

There are no restrictions on the use of the w_getmntent service.