zCreate

Creates and optionally opens a file object.

Service:File System Services (64-Bit)
Version:OES 2

Syntax

#include <zPublics.h>

STATUS zCreate(
   Key_t        key,
   NINT         taskID,
   Xid_t        xid,
   NINT         nameSpace,
   const void  *path,
   NINT         fileType,
   QUAD         fileAttributes,
   NINT         createMode,
   NINT         requestedRights,
   Key_t       *retKey);

Parameters

key

(IN) Specifies who is creating the file. If the path is a relative path, it identifies the starting directory for resolving the pathname.

taskID

(IN) Specifies the task to which the returned key is bound.

xid

(IN) Specifies the transaction for which the file object is a part. The creation of the file object is part of this transaction. If the creation aborts, the file is deleted as if the creation never occurred. If there is no transaction, pass zNILXID.

nameSpace

(IN) Specifies the starting namespace for the path parameter. Only the long namespace should be used for normal file access.

In addition to the normal namespace identifiers (zNSPACE_DOS | zNSPACE_MAC | zNSPACE_UNIX | zNSPACE_LONG | zNSPACE_DATA_STREAM | zNSPACE_EXTENDED_ATTRIBUTE), the nameSpace parameter can be augmented by ORing the following mode bits:

  • zMODE_UTF8

    The default character set for the path is Unicode. However, by ORing zMODE_UTF8, UTF-8 character strings can be used.

  • zMODE_LINK

    If the last name in the path is a symbolic link, a junction, or a URL link, the scanning does not follow the link but acts on the link object itself.

path

(IN) Points to the path of the file object to be created. If the path is not fully qualified, the key must represent a directory for starting the path parsing. The default character set for the pathname is Unicode unless it is specified by the nameSpace parameter.

fileType

(IN) Specifies the type of the file to be created (see also File Type Values):

  • zFILE_REGULAR for normal files and directories.

  • zFILE_EXTENDED_ATTRIBUTE to create an extended attribute for a file.

  • zFILE_NAMED_DATA_STREAM to create a data stream.

If the file object already exists and if the createMode specifies to reuse the existing file object, fileType is ignored.

fileAttributes

(IN) Specifies a bit mask that identifies specific file attributes to be associated with the newly created file (see File Attributes Values). If the file object already exists and if createMode specifies to reuse the existing file object, fileAttributes is ignored. The file attributes are completely independent from the authorization system and take precedence over the effective rights granted via that authorization system.

createMode

(IN) Specifies the actions to take place if the file object being created already exists. If the file object exists and createMode is zero, the create fails and one of the following error statuses is returned:

zCREATE_OPEN_IF_ THERE

Opens the existing file, leaving its contents intact.

zCREATE_TRUNCATE_ IF_THERE

Opens the existing file but truncates the data stream. The old contents are lost and are not saved in the file salvage system.

zCREATE_DELETE_ IF_THERE

Truncates the existing file if the file has been opened with zRR_CANT_DELETE_WHILE_OPEN flag is set. Deletes the existing file and creates a new one from scratch. If salvage is enabled on the volume, the deleted file is moved to the file salvage system unless the zFA_IMMEDIATE_PURGE is set, in which case it is purged completely.
requestedRights

(IN) Specifies the rights to assign to retKey (see Requested Rights Values). If the file object is not being opened, requestedRights is ignored.

retKey

(IN/OUT) Points to whether a key should be returned:

NULL

The file should be created but not opened, and no key is returned.

non-NULL

A key is returned that gives the user access to the newly created and opened file object. Not only can this key can be used to read and write the created file, but it can be used to get and set information about this file by calling zGetInfo and zModifyInfo.

Return Values

zOK

The operation completed successfully.

non-0

An error occurred (see Section 4.1, Return Values for a description).

Remarks

zCreate can create many different types of file objects. Any file type specific information can be added later by either writing to the file object’s data stream or modifying the file object’s metadata.

Any necessary rights checking is done based on the requestedRights and key parameters.

If an error occurs, the file object is not created or opened.

See Also

zClose