|
FunctionThe v_create service creates a
new file in the directory that is represented by Directory_vnode_token.
The file can be a regular, FIFO, or character special file. The input
Attr is used to define the attributes of the new file. A token that
represents the new file is returned in File_vnode_token.
RequirementsOperation |
Environment |
---|
Authorization: |
Supervisor state or problem state, any PSW key |
Dispatchable unit mode: |
Task |
Cross memory mode: |
PASN = HASN |
AMODE (BPX1VCR): |
31-bit |
AMODE (BPX4VCR): |
64-bit |
ASC mode: |
Primary mode |
Interrupt status: |
Enabled for interrupts |
Locks: |
Unlocked |
Control parameters: |
All parameters must be addressable by the caller and in the
primary address space. |
FormatCALL BPX1VCR,(Directory_vnode_token,
OSS,
Name_length,
Name,
Attr_length,
Attr,
File_vnode_token,
Return_value,
Return_code,
Reason_code)
AMODE 64 callers use BPX4VCR with the same parameters.
Parameters- Directory_vnode_token
- Supplied parameter
- Type:
- Token
- Length:
- 8 bytes
The name of an 8-byte area that contains a vnode
token that represents the directory in which the v_create service
creates the new file that is named in the Name parameter.
- OSS
- Supplied and returned parameter
- Type:
- Structure
- Length:
- OSS#LENGTH (from the BPXYOSS macro)
The name of an area that contains operating-system-specific
parameters. This area is mapped by the BPXYOSS macro (see BPXYOSS — Map operating system specific information).
- Name_length
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword that contains the length
of the filename that is to be created. The name can be up to 255 bytes
long.
- Name
- Supplied parameter
- Type:
- Character string
- Length:
- Specified by Name_length parameter
The name of an area, of length Name_length, that
contains the filename that is to be created. It must not contain null
characters (X'00').
- Attr_length
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword that contains the length
of the area that is passed in the Attr parameter. To determine the
value of Attr_length, use the ATTR structure (see BPXYATTR — Map file attributes for v_ system calls).
- Attr
- Supplied and returned parameter
- Type:
- Structure
- Length:
- Specified by the Attr_length parameter
The name of an area, of length Attr_length, that
is to be used by the v_create service to set the attributes of the
file that is to be created. The attributes of the file that is created
are also returned in this area. This area is mapped by the ATTR structure
(see BPXYATTR — Map file attributes for v_ system calls).
- File_vnode_token
- Returned parameter
- Type:
- Token
- Length:
- 8 bytes
The name of an 8-byte area in which the v_create
service returns a Vnode_token of the file created.
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword where the v_create service
returns 0 if the request is successful, or -1 if
it is not successful.
- Return_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the v_create service
stores the return code. The v_create service returns Return_code only
if Return_value is -1. See z/OS UNIX System Services Messages and Codes
for a complete list of possible return code values. The
v_create service can return one of the following values in the Return_code
parameter: Return_code |
Explanation |
---|
EACCES |
The calling process does not have permission to write in the
directory that was specified. |
EEXIST |
The named file exists. |
EFBIG |
The file size limit for the process is set to zero, which means
files cannot be created. |
EINVAL |
Parameter error; for example, a supplied area was too small. The
following reason codes can accompany the return code: JRSmallAttr,
JRInvalidAttr, JrNoName, JrNullInPath, JRVTokenFreed, JRWrongPID,
JRStaleVnodeTok, JRInvalidVnodeTok, JRInvalidOSS.
|
EMFILE |
The maximum number of vnode tokens have been created. |
ENAMETOOLONG |
The name is longer than 255 characters. |
ENFILE |
An error occurred while storage was being obtained for a vnode
token. |
ENOTDIR |
The supplied token did not represent a directory. |
EPERM |
The operation is not permitted. The caller of the service is
not registered as a server. |
EROFS |
The Directory_vnode_token is a file on a read-only file system. |
- Reason_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the v_create service
stores the reason code. The v_create service returns a Reason_code
only if Return_value is -1. Reason_code further
qualifies the Return_code value. See z/OS UNIX System Services Messages and Codes
for the reason codes.
Usage notes- The following ATTR fields are provided by the caller:
- Attr.at_hdr.cbid
- Contains Attr#ID (from the ATTR structure).
- AttrLen
- Specifies the length of the ATTR structure.
- AttrMode
- Specifies the file mode permission bits. See Mapping
macros in z/OS UNIX System Services Programming: Assembler Callable Services Referencefor
the mapping of this field.
- AttrType
- Specifies the file type: regular, FIFO, or character special.
See Mapping macros in z/OS UNIX System Services Programming: Assembler Callable Services Referencefor
the mapping of this field.
- AttrMajorNumber
- Specifies the major number for character special files.
- AttrMinorNumber
- Specifies the minor number for character special files.
- AttrCVerSet
- Indicates whether the Creation Verifier (AttrCVer) is present.
- AttrCVer
- Specifies the Creation Verifier for the file. When the AttrCVerSet
bit is on and the create is successful, the PFS saves the Creation
Verifier, and the server can retrieve it with v_lookup. The Creation
Verifier allows the server to determine whether a v_create that returns
EEXIST should be considered successful or not. If AttrCVerSet is on,
AttrCVer is returned, and the server can compare the file's Creation
Verifier with the input Creation Verifier on the v_create. If they
are the same, it considers the v_create successful; that is, it is
a duplicate of an earlier successful request.
Other fields in the ATTR area should be set to
zeros.
- If the file that is named in the Name parameter exists, the v_create
service returns a failing return code, and no File_vnode_token is
returned.
- Vnode tokens that are returned by the v_create service are not
inherited across a fork callable service.
- The caller is responsible for freeing vnode tokens that are returned
by the v_create service by calling to the v_rel service when they
are no longer needed.
- If the file size limit for the process is set to zero, files cannot
be created and file creation fails with EFBIG.
- The value set by umask() for the process
does not affect the setting of the mode permission bits.
|