If you have selected to use the NKS functions for accessing NetWare files and directories, this documentation assumes that you have a NetWare administrator's knowledge of the NetWare file systems. The following table lists the topics that you need to understand and provides links to the NetWare 6.5 documentation for an explanation.
|
Topic |
Source |
|---|---|
|
NetWare file and directory rights |
|
|
NSS file system |
|
|
Traditional file system |
|
|
Boot partition |
The following sections describe those concepts that are particular to the NKS functions and that allow you to effectively use these functions. It covers the following topics:
A path context is similar to the concept of a current working directory, which points to a specific directory in the file system, relative to the root. However, a path context contains more information than a path to a directory. It also specifies format and authentication information. This section covers the following topics:
On the first call into the file system, the pathCtx parameter should be 0 and the pathname parameter should specify the full path of the directory to open, including the volume name. On subsequent calls to create a path context, the pathname parameter can be used in conjunction with the path context parameter to specify a subdirectory.
The format parameter determines which characters are valid and the type of separator to use between components of the path in the pathname parameter. On the first call into the file system, you should specify, in the format parameter, the format that matches your pathname string. For more information, see Format.
On the first call to create a path context to a remote server, the pathname parameter must include a server name and a volume name; directory and subdirectory names are optional.
For information on how the path context works with the pathname parameter on calls into the file system, see Path Contexts and File System Paths.
The format parameter specifies the name space information to be used with the new path context. Name space is the ability of directory entries to store names and attributes in the conventions of multiple operating systems (such as NT, Unix, and Macintosh). NetWare volumes (traditional and NSS) gain this functionality when the network administrator adds a specified name space to the volume.
The format in a path context implies the following features:
Set of valid characters for a pathname
Case sensitivity of any characters (if applicable)
Maximum and minimum length of any path element such as file and directory names
Set of valid path separators
File system semantics such as ACL format, access control checks, and file system attributes
The format you specify should match the format you use in the pathname string. Currently, four formats are supported:
NKS—This name space is case insensitive, supports 255-character filenames, and uses a backslash as a path separator for directory components. It is the format to specify for Windows clients accessing NetWare volumes. The NetWare format, with its character sets, limits, and separators, is defined in the limits.h and nks/dirio.h files. For example: “sys:\public\nls”
DOS—This is the 8.3 filename format that is used on the NetWare boot partition. For example: “c:\server”
Unix—This name space is case sensitive, supports 256-character filenames, and uses forward slashes for path separators. For example: “/Public/NLS”
Macintosh—This name space is case insensitive, supports 255-character filenames, uses colons for path separators. For example: “::public:nls”
The path context contains a security badge, which is also called an identity. This identity gives you the credentials to use the file system. On the local NetWare server where your NLM™ is running, you can pass NULL as the securityBadge parameter, which is equivalent to logging into the server on “connection 0” and using the same connection as other NLM applications without identities.
However, if you want to perform remote file system operations on other NetWare servers, you are required to call create_identity to set up an identity, which is then passed as the securityBadge parameter when you create a path context to that remote server.
Path contexts work in combination with pathnames to identify a file system object or entry including files and directories. By itself, the path context (pathCtx parameter) indicates a root or subdirectory relative to which the pathname parameter of a function operates. The two can be combined in the following ways:
A path context of zero plus a full, hierarchical path to the object.
A path context plus a NULL path, which can only indicate a directory.
A path context plus a name where the path context indicates the immediate parent of the file system entry (whether file or directory).
A path context plus a hierarchical path; the path context indicates a directory at some depth at which the path starts and finishes the specification.
The following tables better illustrate this. The first table explains the conventions for files.
The table below explains the conventions for directories.
Anywhere a path context is required, a 0 may be used. When a path context is 0, no user identity is carried and only the NKS pathname format can be inferred. Consequently, a 0 path context may often be inadequate for file system operations involving notions of user identity or a specific name space format.
You use the following functions to create a path context:
NXCreatePathContext
NXCreatePathContextWithFid
Because a path context represents both a path and a connection, remember to delete the following before exiting your application:
File descriptors for accessed file objects with NXClose
Path context with NXFreePathContext
Identity with delete_identity
LibC does not contain an NKS function that takes a path context object (NXPathCtx_t) and returns a full path. However, this information is available either from the current working directory or from the object's attributes.
CWD Method. To use the current working directory, you must first set the cwd to the path context with either setcwd or setcwd2. Both of these functions accept a path context object. The difference between the functions is that setcwd sets the cwd for all threads in a virtual machine and setcwd2 sets the cwd for only the calling thread. You can then use getcwd or getcwdpath to obtain the full path of the path context object. The getcwd is the standard POSIX function; getcwdpath is a Novell addition that returns the server and volume name in the full path.
Attribute Method. You can use NXGetAttr with a pathCtx and pathname set to NULL. If you set level to NX_DELEVEL_NAME_ONLY, the function returns an NXDirAttrWithName_t structure that contains the name of the path context. The name does not include the server or volume.
All I/O operations including opening, reading, writing, and closing different file system objects such as files, consoles, devices, and FIFOs can be performed using the same interfaces and semantics. For example, while there are separate functions to open and create these different object types, there is only one function (NXClose) to close them.
The I/O services can support 64 bit file offsets.
The following object types are supported:
Besides the I/O operations, this file system interface provides functions for the following types of file operations:
The functions dealing with filenames accept Unicode* strings or ASCII strings in the current locale.
This file system interface provides functions for the following types of directory operations
The functions dealing with directory names accept Unicode strings or ASCII strings in the current locale.
First-in/first-out files form the basis for free-form interprocess communication (IPC) in NKS. All FIFOs are named and opened from any virtual machine, but no method of discovery is provided. FIFO descriptors are opened for read or for write, but not for both though it is possible to open both from the same application. The FIFO provides an untyped, half-duplex communication channel between NLM applications.
On NetWare, the name of a FIFO is not persistent. FIFOs need to be opened or created for each session.
A FIFO has two ends. To use a FIFO, one end is opened only for read operations and the other end is opened only for write operations. An attempt to perform the reverse operation on the reverse end results in an error.
The writer can write data to and the reader can read data from an FIFO by calling standard file I/O functions. The data written by the writer is available for reading to the reader. Any data that is read by the reader is removed from the FIFO immediately and is not available subsequently. A FIFO's data can be read only sequentially.
Once opened, the read and write ends can have multiple threads reading and writing simultaneously from the FIFO. To support this multi-thread functionality, FIFO operations are defined to be atomic (as long as the size of the data being read or written is not more than the size defined by NX_FIFO_BUFSIZE), which ensures that data from multiple writers does not get intertwined.
A reader or writer is notified about the closure of the opposite end only during a read or write operation. To prevent unexpected surprises due to one end getting closed and reopened without the other end's knowledge, the FIFO cannot be subsequently opened from the same end once that end of the FIFO is closed. Once you close one end of the FIFO, you break the pipe and must close the other end before opening the FIFO again
Each time a FIFO is opened, mode flags are used to determine whether the open is for reading or writing and whether it is in blocking mode (see NKS Open Modes).
The following table explains the behavior of a FIFO:
On NetWare, the console is the only supported device. The NKS interface supports access to the console and its keyboard.
You can open the console with the NXDeviceOpen function or use the NXConsoleOpen macro. The macro always opens the console in a shareable, deny none mode.