zOpen

Opens a file object.

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

Syntax

#include <zPublics.h>

STATUS zOpen(
   Key_t        key,
   NINT         taskID,
   NINT         nameSpace,
   const void  *path,
   NINT         requestedRights,
   Key_t       *retKey);

Parameters

key

(IN) Specifies who is opening the file. If the path is a relative path, the key identifies the starting directory for pathname resolution.

taskID

(IN) Specifies the task the returned key will be bound to.

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), nameSpace 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_DELETED

    Changes the name scanning to look for deleted files in the salvage system, which effectively purges the file.

  • 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 opened. If the path is not fully qualified, the key must represent a directory where the path parsing should begin. The default character set for the pathname is Unicode unless it is specified by nameSpace.

requestedRights

(IN) Specifies the rights that are requested for this instance of an open file structure (see Requested Rights Values).

retKey

(OUT) Points to a key that gives the user access to the open file object. This key can be used to open data streams, extend attributes relative to this file, and get information about this file (in addition to reading and writing).

Return Values

zOK

The operation completed successfully.

non-0

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

Remarks

If an error occurs, the file object is not opened. Before opening the file object, the object is queried to find out if it can be opened. A file object has the right to refuse to be opened.

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

The requestedRights are associated with the returned key.

See Also

zClose, zCreate, zDIORead, zDIOWrite, zRead, zSetEOF, zWrite