This chapter describes the NSPR functions used to perform operations such as system access, normal file I/O, and socket (network) I/O.
For sample code that illustrates basic I/O operations, see Introduction to NSPR. For information about the types most commonly used with the functions described in this chapter, see I/O Types.
A file or directory in a file system is specified by its pathname. NSPR uses Unix-style pathnames, which are null-terminated character strings. Only the ASCII character set is supported. The forward slash (/) separates the directories in a pathname. NSPR converts the slashes in a pathname to the directory separator of the native OS--for example, backslash (\) on Windows and colon (:) on Mac OS--before passing it to the native system calls.
Some file systems also differentiate drives or volumes.
PR_ClosePR_ReadPR_WritePR_WritevPR_GetOpenFileInfoPR_GetOpenFileInfo64PR_Seek PR_Seek64PR_AvailablePR_Available64PR_SyncPR_GetDescTypePR_GetSpecialFDPR_CreatePipeThe network programming interface presented here is a socket API modeled after the popular Berkeley sockets. Differences include the following:
PR_TransmitFile and PR_AcceptRead, can exploit the new system calls of some operating systems for higher performance.List of functions:
PR_OpenUDPSocketPR_NewUDPSocket PR_OpenTCPSocketPR_NewTCPSocket PR_ImportTCPSocketPR_ConnectPR_ConnectContinuePR_AcceptPR_BindPR_ListenPR_ShutdownPR_RecvPR_SendPR_RecvFromPR_SendToPR_TransmitFilePR_AcceptReadPR_GetSockNamePR_GetPeerNamePR_GetSocketOptionPR_SetSocketOptionThe memory-mapped I/O functions allow sections of a file to be mapped to memory regions, allowing read-write accesses to the file to be accomplished by normal memory accesses.
Memory-mapped I/O functions are currently implemented for Unix, Linux, Mac OS X, and Win32 only.
This section describes two of the most important polling functions provided by NSPR:
A pollable event is a special kind of file descriptor. The only I/O operation you can perform on a pollable event is to poll it with the PR_POLL_READ flag. You cannot read from or write to a pollable event.
The purpose of a pollable event is to combine event waiting with I/O waiting in a single PR_Poll call. Pollable events are implemented using a pipe or a pair of TCP sockets connected via the loopback address, therefore setting and/or waiting for pollable events are expensive operating system calls. Do not use pollable events for general thread synchronization; use condition variables instead.
A pollable event has two states: set and unset. Events are not queued, so there is no notion of an event count. A pollable event is either set or unset.
One can call PR_Poll with the PR_POLL_READ flag on a pollable event. Whe the pollable event is set, PR_Poll returns the the PR_POLL_READ flag set in the out_flags.
File descriptors may be layered. For example, SSL is a layer on top of a reliable bytestream layer such as TCP.
Each type of layer has a unique identity, which is allocated by the runtime. The layer implementor should associate the identity with all layers of that type. It is then possible to scan the chain of layers and find a layer that one recognizes and therefore predict that it will implement a desired protocol.
A layer can be pushed onto or popped from an existing stack of layers. The file descriptor of the top layer can be passed to NSPR I/O functions, which invoke the appropriate version of the I/O methods polymorphically.
NSPR defines three identities:
#define PR_INVALID_IO_LAYER (PRDescIdentity)-1 #define PR_TOP_IO_LAYER (PRDescIdentity)-2 #define PR_NSPR_IO_LAYER (PRDescIdentity)0
PR_INVALID_IO_LAYER: An invalid layer identify (for error return).PR_TOP_IO_LAYER: The identity of the top of the stack.PR_NSPR_IO_LAYER: The identity for the layer implemented by NSPR.PR_TOP_IO_LAYER may be used as a shorthand for identifying the topmost layer of an existing stack. For example, the following lines of code are equivalent:
rv = PR_PushIOLayer(stack, PR_TOP_IO_LAYER, my_layer);
rv = PR_PushIOLayer(stack, PR_GetLayersIdentity(stack), my_layer);