Function
The vn_open operation opens a file.
Input parameter format
vn_open (Token_structure,
OSI_structure,
Audit_structure,
Open_flags,
Return_value,
Return_code,
Reason_code)
Parameters
- Token_structure
- Supplied parameter
- Type:
- TOKSTR
- Length:
- Specified by TOKSTR.ts_hdr.cblen.
The Token_structure represents the file (vnode)
being operated on. It contains the PFS's initialization token, mount
token, and the file token. Refer to LFS/PFS control block structure for
a discussion of this structure, and to the TOKSTR typedef in BPXYPFSI
in Interface structures for C language servers and clients for its mapping.
- OSI_structure
- Supplied and returned parameter
- Type:
- OSI
- Length:
- Specified by OSI.osi_hdr.cblen.
The OSI_structure contains information used by the
OSI operations that may be called by the PFS. See OSI services for more information.
It also contains
MVS-specific information that needs to be passed to the PFS, including
SMF accounting fields, a work area, a recovery area, and an optional
pointer to an output ATTR structure. For more details on the OSI structure,
see The OSI structure.
This area is mapped by
the OSI typedef in BPXYPFSI in Interface structures for C language servers and clients.
- Audit_structure
- Supplied parameter
- Type:
- CRED
- Length:
- Specified by CRED.cred_hdr.cblen.
The Audit_structure contains information used by
the security product for access checks and auditing. It is passed
to most SAF routines that are invoked by the PFS.
Refer to Security responsibilities and considerations for a discussion of security processing,
and to the CRED typedef in BPXYPFSI in Interface structures for C language servers and clients for
the mapping of this structure.
- Open_flags
- Supplied parameter
- Type:
- Bit
- Length:
- Fullword
A fullword containing the binary flags that describe
how the file is to be opened. These flags are defined by fcntl.h.
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
A fullword where the vn_open operation returns
the results of the operation as one of the following:
- Return_value
- Meaning
- -1
- The operation was not successful. The Return_code and Reason_Code
values must be filled in by the PFS when Return_value is -1.
- 0
- The operation was successful.
- Return_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
A fullword in which the vn_open operation stores
the return code. The vn_open operation returns Return_code only if
Return_value is -1. See z/OS UNIX System Services Messages and Codes for
a complete list of supported return code values.
The vn_open operation should support at least the
following error values:
Return_code |
Explanation |
---|
EACCES |
The caller does not have permission for the requested (read
or write) access. |
ENOENT |
The file does not exist. |
EROFS |
An attempt was made to open a file for write in a read-only
file system. |
- Reason_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
A fullword where the vn_open operation stores the
reason code. The vn_open operation returns Reason_code only if Return_value
is -1. Reason_code further qualifies the Return_code
value. These reason codes are documented by the PFS.
Implementation notes
- Overview of vn_open processing
See Opening and closing files and first references to files for a discussion of open
processing.
For more information about the semantics of this
operation for a POSIX-conforming PFS, refer to the open() function
in the POSIX .1 standard (IEEE Std 1003.1-1990).
- Specific processing notes
- The O_RDONLY and O_WRONLY bits in the Open_flags control whether
the SAF Check Access callable service is called for a read, write,
or read and write access check.
- When the O_EXEC flag is ON in the Open_flags, the SAF Check Access
call must be made with a check for execute permission rather than
read or write permission. This bit is a z/OS UNIX extension
that is defined in Interface structures for C language servers and clients.
- When the O_TRUNC flag is ON in the Open_flags the PFS must truncate
the file to zero length.
- The LFS implements the semantics of the O_CREAT and O_EXCL flags.
- The Open_flags will be remembered by the LFS and passed to the
PFS on all read/write type operations that are related to this open.
The O_APPEND and O_NONBLOCK flags, for instance, are processed by
the PFS during those read/write operations from the flags passed to
it at that time. The O_SYNC flag is transferred by the LFS to the
UIO.u_sync flag for all read/write type operations so that this function
can be processed by the PFS the same way for both POSIX and NFS users.
- Serialization provided by the LFS
The
vn_open operation is invoked with an exclusive latch held on the vnode
of the file. Shared read support for the file being opened may be
modified in the OSI by the PFS upon returning from the vn_open operation.
- Security calls to be made by the PFS
The PFS is expected to invoke SAF's Check Access callable service
to check that the user has permission for the requested (read, write,
or execute) access.