NXFileOpenSpec_t

Structure

  #include <nks/fsio.h>
  
  typedef struct 
  {
     NXPathCtx_t      fosPathCtx;
     const void      *fosPathname;
     NXMode_t         fosMode;
     NXOFlags_t       fosOFlags;
     NXShareMode_t    fosShareMode;
     size_t           fosExtentSize;
     uint32_t         reserved1;
     NXDelegType_t    fosDelegType;
     NXDataStream_t   fosDataStream;
     NXFsUpCall_t     fosUpCallFunc;
     struct {
        NXMode_t        actionTaken;
        NXDelegType_t   delegType;
        NXFid_t         fid;
        NXTime_t        accessTime;
        NXTime_t        modifyTime;
        NXTime_t        creationTime;
        NXTime_t        archiveTime;
        NXOffset_t      length;
     }                  fosResult;
     uint32_t           reserved2;
     uint32_t           reserved3;
  } NXFileOpenSpec_t;
  

Fields

fosPathCtx

Specifies a file system path context. Along with the fosPathname parameter, it specifies the file to open.

fosPathname

Points to a null-terminated Unicode, UTF-8, or ASCII string that specifies the name of the file (relative to pathCtx) to open or create.

fosMode

Specifies if the file is to be opened for reading, writing, or both. See NKS Open Modes.

fosOFlags

Specifies various modes in which to open the file (depending on how it will be accessed or used). These specifiers are hints to NKS that allow special treatments of files (such as time of backup) or features (such as direct file access). Some of these flags are mutually exclusive (such as for backup and restore).

Open Flags	Value	Description
NX_OFLAG_DIRECTIO	0x00010000	Not implemented yet.Opens the file in direct file I/O mode. File operations are direct and unbuffered by the file system. Additional restrictions can exist.
NX_OFLAG_CRONLY	0x00020000	Creates the file, but does not open it.
NX_OFLAG_BACKUP	0x00040000	Not implemented yet. Opens the file for archiving, which means that the last accessed time stamp must not be changed and that all data streams are to be flattened when the file is read or written. Reading straight through the file results in traversing every byte of every data stream. However, the data is tagged for recognition when it is rewritten using the restore flag. This flag bypasses any share mode restrictions due to the file being already open with NX_SHARE_DENYRD or NX_SHARE_DENYALL. This flag is incompatible with NX_O_WRONLY.
NX_OFLAG_RESTORE	0x00080000	Not implemented yet. Unflattens tagged data when written. This flag is incompatible with NX_O_RDONLY.
NX_OFLAG_EXTEND	0x00100000	Not implemented yet.
NX_OFLAG_SYNCWR	0x00200000	Makes the writing synchronous with respect to the file. Every write is flushed, and the call blocks until the flush has completed. This flag is incompatible with NX_O_RDONLY.
NX_OFLAG_ATOMIC_RW	0x00400000	Automatically performs read and write operations.
NX_OFLAG_NOTRAVERSE_LINK	0x00800000	Not relevant on NetWare. If this file is merely a link, do not traverse it to the real file.
NX_OFLAG_BACKUPNOTIFY		Not implemented yet. Notifies an application by up call when a backup or a snapshot are about to happen. The application can flush the required buffers and return from the up call, which allows the backup to proceed. This flag can be used as a hint that it is time to flush the file and not to modify it until the up call with NX_UPCALL_BACKUPDONE is received.

fosShareMode

Indicates how a file being opened is to be shared with an already opened instance and other, subsequent instances in the same or different VM. This functionality provides a file-level locking facility. You must still use byte-range locks to ensure file consistency when the file is shared. See Shared Modes.

fosExtentSize

Provides a hint to the file system on the size of extents (sets of contiguous file system blocks) to be used when allocating new blocks to the file. This is ignored if the underlying file system implementation does not support it.

reserved1

Reserved.

fosDelegType

Specifies the type of delegation request the caller wants on the file. The type of delegation actually granted is returned after opening.

This is for use by server applications that handle multiple clients for performance improvement and cache consistency. Special privileges are required by applications to use this field.

fosDataStream

Indicates which data stream if this is not part of the pathname proper. This structure has two fields:

• name Specifies the generic file system name
• macintoshId Specifies the Macintosh data stream (data or resource fork)

fosUpCallFunc

If it exists, specifies a function to be called by NKS when the delegation granted is revoked.

This is for use by server applications that handle multiple clients for performance improvement and cache consistency. Special privileges are required by applications to use this field.

actionTaken

Returns the mode in which the file was opened. This may be a subset of the modes requested.

delegType

Returns the delegation type actually granted.

fid

Returns the FID of the opened file.

accessTime

Returns the last date and time the opened file was accessed prior to being opened.

modifyTime

Returns the last date and time the file was modified.

creationTime

Returns the creation date and time of the file.

archiveTime

Returns the last date and time the file was backed up.

length

Returns the length of the file at open.

reserved2

Reserved.

reserved3

Reserved.

Remarks

The fosResult structure contains the state of the create or open operation after completion.

The fosShareMode and fosMode options of an open instance of a file determine whether another open request with a specific fosShareMode and fosMode on the same file can be allowed. The fosShareMode and fosMode options specified by an open instance are used for this check only as long as that instance is still in effect. The following matrix explains this for the share modes (DENYALL, DENYWR, DENYRD, and DENTNO) and the open modes (RD, RW, and WR).

Read and write operations that are performed on the open file are not atomic by default, which means that multiple writes to the same file can be interleaved. Atomic read and/or write operations can be requested by specifying the open flag, NX_OFLAG_ATOMIC_RW. However, this feature is available only if the underlying file system implementation supports it.

By default, read and write operations on an opened file are buffered by the file system.