|
NSPR Reference Previous Contents Next |
Chapter 9 I/O Types
Types unique to a particular function are described with the function itself.
For sample code that illustrates basic I/O operations, see Introduction to NSPR.
Directory Type
File Descriptor Types
File Info Types
Network Address Types
Types Used with Socket Options Functions
Type Used with Memory-Mapped I/O
Offset Interpretation for Seek Functions
Directory Type
PRDir
Directory structure used with Directory I/O Functions.Syntax
#include <prio.h>
typedef struct PRDir PRDir;
Description
The opaque structurePRDir represents an open directory in the file system. The
function PR_OpenDir opens a specified directory and returns a pointer to a PRDir
structure, which can be passed to PR_ReadDir repeatedly to obtain successive
entries (files or subdirectories in the open directory). To close the directory, pass
the PRDir pointer to PR_CloseDir.
File Descriptor Types
NSPR represents I/O objects, such as open files and sockets, by file descriptors of typePRFileDesc. This section introduces PRFileDesc and related types.
PRFileDesc
PRIOMethods
PRFilePrivate
PRDescIdentity
Note that the NSPR documentation follows the Unix convention of using the term files to refer to many kinds of I/O objects. To refer specifically to the files in a file system (that is, disk files), this documentation uses the term normal files.
PRFileDesc has an object-oriented flavor. An I/O function on a PRFileDesc
structure is carried out by invoking the corresponding "method" in the I/O
methods table (a structure of type PRIOMethods) of the PRFileDesc structure (the
"object"). Different kinds of I/O objects (such as files and sockets) have different
I/O methods tables, thus implementing different behavior in response to the same
I/O function call.
NSPR supports the implementation of layered I/O. Each layer is represented by a
PRFileDesc structure, and the PRFileDesc structures for the layers are chained
together. Each PRFileDesc structure has a field (of type PRDescIdentity) to
identify itself in the layers. For example, the Netscape implementation of the
Secure Sockets Layer (SSL) protocol is implemented as an I/O layer on top of
NSPR's socket layer.
PRFileDesc
A file descriptor used to represent any open file, such as a normal file, an end point of a pipe, or a socket (end point of network communication).Syntax
#include <prio.h>
struct PRFileDesc {
PRIOMethods *methods;
PRFilePrivate *secret;
PRFileDesc *lower, *higher;
void (*dtor)(PRFileDesc *fd);
PRDescIdentity identity;
};
typedef struct PRFileDesc PRFileDesc;
Fields
The structure has the following fields:
methods |
The I/O methods table. See PRIOMethods.
|
secret |
Layer-dependent implementation data. See PRFilePrivate.
|
lower |
Pointer to lower layer.
|
higher |
Pointer to higher layer.
|
dtor |
A destructor function for the layer.
|
identity |
Identity of this particular layer. See PRDescIdentity.
|
Description
The fields of this structure are significant only if you are implementing a layer on top of NSPR, such as SSL. Otherwise, you use functions such asPR_Open and
PR_NewTCPSocket to obtain a file descriptor, which you should treat as an opaque
structure.
For more details about the use of PRFileDesc and related structures, see File
Descriptor Types.
PRIOMethods
The table of I/O methods used in a file descriptor.Syntax
#include <prio.h>
struct PRIOMethods {
PRDescType file_type;
PRCloseFN close;
PRReadFN read;
PRWriteFN write;
PRAvailableFN available;
PRAvailable64FN available64;
PRFsyncFN fsync;
PRSeekFN seek;
PRSeek64FN seek64;
PRFileInfoFN fileInfo;
PRFileInfo64FN fileInfo64;
PRWritevFN writev;
PRConnectFN connect;
PRAcceptFN accept;
PRBindFN bind;
PRListenFN listen;
PRShutdownFN shutdown;
PRRecvFN recv;
PRSendFN send;
PRRecvfromFN recvfrom;
PRSendtoFN sendto;
PRPollFN poll;
PRAcceptreadFN acceptread;
PRTransmitfileFN transmitfile;
PRGetsocknameFN getsockname;
PRGetpeernameFN getpeername;
PRGetsockoptFN getsockopt;
PRSetsockoptFN setsockopt;
};
typedef struct PRIOMethods PRIOMethods;
Fields
The structure has the following fields:
Description
You don't need to know the type declaration for each function listed in the method table unless you are implementing a layer. For information about each function, see the corresponding function description in this document. For example, thewrite
method in PRIOMethods implements the PR_Write function. For type definition
details, see prio.h.
The I/O methods table provides procedural access to the functions of the file
descriptor. It is the responsibility of a layer implementor to provide suitable
functions at every entry point (that is, for every function in the I/O methods table).
If a layer provides no functionality, it should call the next lower (higher) function
of the same name (for example, the "close" method would return
fd->lower->method->close(fd->lower)).
Not all functions in the methods table are implemented for all types of files. For
example, the seek method is implemented for normal files but not for sockets. In
cases where this partial implementation occurs, the function returns an error
indication with an error code of PR_INVALID_METHOD_ERROR.
PRFilePrivate
Layer-dependent implementation data.Syntax
#include <prio.h>
typedef struct PRFilePrivate PRFilePrivate;
Description
A layer implementor should collect all the private data of the layer in thePRFilePrivate structure. Each layer has its own definition of PRFilePrivate,
which is hidden from other layers as well as from the users of the layer.
PRDescIdentity
The identity of a file descriptor's layer.Syntax
#include <prio.h>
typedef PRUintn PRDescIdentity;
Description
File descriptors may be layered. Each layer has it own identity. Identities are allocated by the runtime and are to be associated (by the layer implementor) with all file descriptors of that layer. It is then possible to scan the chain of layers and find a layer that one recognizes, then predict that it will implement a desired protocol.
A string may be associated with a layer when the layer is created. The string is
copied by the runtime, and PR_GetNameForIdentity returns a reference to that
copy. There is no way to delete a layer's identity after the layer is created.
File Info Types
PRFileInfo
PRFileInfo64
PRFileType
PRFileInfo
File information structure used withPR_GetFileInfo and PR_GetOpenFileInfo.
Syntax
#include <prio.h>
struct PRFileInfo {
PRFileType type;
PRUint32 size;
PRTime creationTime;
PRTime modifyTime;
};
typedef struct PRFileInfo PRFileInfo;
Fields
The structure has the following fields:
type |
Type of file. See PRFileType.
|
size |
Size, in bytes, of file's contents.
|
creationTime |
Creation time per definition of PRTime. See prtime.h.
|
modifyTime |
Last modification time per definition of PRTime. See
prtime.h.
|
Description
ThePRFileInfo structure provides information about a file, a directory, or some
other kind of file system object, as specified by the type field.
PRFileInfo64
File information structure used withPR_GetFileInfo64 and
PR_GetOpenFileInfo64.
Syntax
#include <prio.h>
struct PRFileInfo64 {
PRFileType type;
PRUint64 size;
PRTime creationTime;
PRTime modifyTime;
};
typedef struct PRFileInfo64 PRFileInfo64;
Fields
The structure has the following fields:
type |
Type of file. See PRFileType.
|
size |
64-bit size, in bytes, of file's contents.
|
creationTime |
Creation time per definition of PRTime. See prtime.h.
|
modifyTime |
Last modification time per definition of PRTime. See
prtime.h.
|
Description
ThePRFileInfo64 structure provides information about a file, a directory, or some
other kind of file system object, as specified by the type field.
PRFileType
Type for enumerators used in thetype field of the PRFileInfo and PRFileInfo64
structures.
Syntax
#include <prio.h>
typedef enum PRFileType{
PR_FILE_FILE = 1,
PR_FILE_DIRECTORY = 2,
PR_FILE_OTHER = 3
} PRFileType;
Enumerators
The enumeration has the following enumerators:
Network Address Types
PRNetAddr
PRIPv6Addr
PRNetAddr
Type used with Socket Manipulation Functions to specify a network address.Syntax
#include <prio.h>
union PRNetAddr {
struct {
PRUint16 family;
char data[14];
} raw;
struct {
PRUint16 family;
PRUint16 port;
PRUint32 ip;
char pad[8];
} inet;
#if defined(_PR_INET6)
struct {
PRUint16 family;
PRUint16 port;
PRUint32 flowinfo;
PRIPv6Addr ip;
} ipv6;
#endif /* defined(_PR_INET6) */
};
typedef union PRNetAddr PRNetAddr;
Fields
The structure has the following fields:
Description
The unionPRNetAddr represents a network address. NSPR supports only the
Internet address family. By default, NSPR is built to support only IPv4, but it's
possible to build the NSPR library to support both IPv4 and IPv6. Therefore, the
family field can be PR_AF_INET only for default NSPR, and can also be PR_AF_INET6 if the
binary supports IPv6.
PRNetAddr is binary-compatible with the socket address structures in the familiar
Berkeley socket interface, although this fact should not be relied upon. The raw
member of the union is equivalent to struct sockaddr, the inet member is
equivalent to struct sockaddr_in, and if the binary is built with IPv6 support,
the ipv6 member is equivalent to struct sockaddr_in6. (Note that PRNetAddr
does not have the length field that is present in struct sockaddr_in on some
Unix platforms.)
The macros PR_AF_INET, PR_AF_INET6, PR_INADDR_ANY, PR_INADDR_LOOPBACK are defined if
prio.h is included. PR_INADDR_ANY and PR_INADDR_LOOPBACK are special IPv4 addresses
in host byte order, so they must be converted to network byte order before being
assigned to the inet.ip field.
PRIPv6Addr
Type used in theipv6.ip field of the PRNetAddr structure.
Syntax
#include <prio.h>
#if defined(_PR_INET6)
typedef struct in6_addr PRIPv6Addr;
#endif /* defined(_PR_INET6) */
Description
PRIPv6Addr represents a 128-bit IPv6 address. It is equivalent to struct in6_addr
in the Berkeley socket interface. PRIPv6Addr is always manipulated as a byte array.
Unlike the IPv4 address (a 4-byte unsigned integer) or the port number (a 2-byte
unsigned integer), it has no network or host byte order.
Types Used with Socket Options Functions
PRSocketOptionData
PRSockOption
PRLinger
PRMcastRequest
PRSocketOptionData
Type for structure used withPR_GetSocketOption and PR_SetSocketOption to
specify options for file descriptors that represent sockets.
Syntax
#include <prio.h>
typedef struct PRSocketOptionData
{
PRSockOption option;
union
{
PRUintn ip_ttl;
PRUintn mcast_ttl;
PRUintn tos;
PRBool non_blocking;
PRBool reuse_addr;
PRBool keep_alive;
PRBool mcast_loopback;
PRBool no_delay;
PRSize max_segment;
PRSize recv_buffer_size;
PRSize send_buffer_size;
PRLinger linger;
PRMcastRequest add_member;
PRMcastRequest drop_member;
PRNetAddr mcast_if;
} value;
} PRSocketOptionData;
Fields
The structure has the following fields:
Description
PRSocketOptionData is a name-value pair for a socket option. The option field (of
enumeration type PRSockOption) specifies the name of the socket option, and the
value field (a union of all possible values) specifies the value of the option.
PRSockOption
Enumeration type used in theoption field of PRSocketOptionData to form the
name portion of a name-value pair.
Syntax
#include <prio.h>
typedef enum PRSockOption {
PR_SockOpt_Nonblocking,
PR_SockOpt_Linger,
PR_SockOpt_Reuseaddr,
PR_SockOpt_Keepalive,
PR_SockOpt_RecvBufferSize,
PR_SockOpt_SendBufferSize,
PR_SockOpt_IpTimeToLive,
PR_SockOpt_IpTypeOfService,
PR_SockOpt_AddMember,
PR_SockOpt_DropMember,
PR_SockOpt_McastInterface,
PR_SockOpt_McastTimeToLive,
PR_SockOpt_McastLoopback,
PR_SockOpt_NoDelay,
PR_SockOpt_MaxSegment,
PR_SockOpt_Last
} PRSockOption;
Enumerators
The enumeration has the following enumerators:
Description
ThePRSockOption enumeration consists of all the socket options supported by
NSPR. The option field of PRSocketOptionData should be set to an enumerator of
type PRSockOption.
PRLinger
Structure used with thePR_SockOpt_Linger socket option to specify the time
interval (in PRIntervalTime units) to linger on closing a socket if any data remain
in the socket send buffer.
Syntax
#include <prio.h>
typedef struct PRLinger {
PRBool polarity;
PRIntervalTime linger;
} PRLinger;
Fields
The structure has the following fields:
polarity |
Polarity of the option's setting: PR_FALSE means the option is off, in
which case the value of linger is ignored. PR_TRUE means the
option is on, and the value of linger will be used to determine how
long PR_Close waits before returning.
|
linger |
Time (in PRIntervalTime units) to linger before closing if any data
remain in the socket send buffer.
|
Description
By default,PR_Close returns immediately, but if there are any data remaining in
the socket send buffer, the system attempts to deliver the data to the peer. The
PR_SockOpt_Linger socket option, with a value represented by a structure of type
PRLinger, makes it possible to change this default as follows:
-
If
polarity is set to PR_FALSE, PR_Close returns immediately, but if there are
any data remaining in the socket send buffer, the runtime attempts to deliver
the data to the peer.
If polarity is set to PR_TRUE and linger is set to 0 (PR_INTERVAL_NO_WAIT),
the runtime aborts the connection when it is closed and discards any data
remaining in the socket send buffer.
If polarity is set to PR_TRUE and linger is nonzero, the runtime lingers when
the socket is closed. That is, if any data remains in the socket send buffer,
PR_Close blocks until either all the data is sent and acknowledged by the peer
or the interval specified by linger expires.
PRMcastRequest
Structure used to specify values for thePR_SockOpt_AddMember and
PR_SockOpt_DropMember socket options that define a request to join or leave a
multicast group.
Syntax
#include <prio.h>
struct PRMcastRequest {
PRNetAddr mcaddr;
PRNetAddr ifaddr;
};
typedef struct PRMcastRequest PRMcastRequest;
Fields
The structure has the following fields:
mcaddr |
IP multicast address of group.
|
ifaddr |
Local IP address of interface.
|
Description
Themcaddr and ifaddr fields are of the type PRNetAddr, but their port fields are
ignored. Only the IP address (inet.ip) fields are used.
Type Used with Memory-Mapped I/O
PRFileMap
Type returned byPR_CreateFileMap and passed to PR_MemMap and
PR_CloseFileMap.
Syntax
#include <prio.h>
typedef struct PRFileMap PRFileMap;
Description
The opaque structurePRFileMap represents a memory-mapped file object. Before
actually mapping a file to memory, you must create a memory-mapped file object
by calling PR_CreateFileMap, which returns a pointer to PRFileMap. Then sections
of the file can be mapped into memory by passing the PRFileMap pointer to
PR_MemMap. The memory-mapped file object is closed by passing the PRFileMap
pointer to PR_CloseFileMap.
Offset Interpretation for Seek Functions
PRSeekWhence
Specifies how to interpret theoffset parameter in setting the file pointer
associated with the fd parameter for the PR_Seek and PR_Seek64 functions.
Syntax
#include <prio.h>
typedef PRSeekWhence {
PR_SEEK_SET = 0,
PR_SEEK_CUR = 1,
PR_SEEK_END = 2
} PRSeekWhence;
Enumerators
The enumeration has the following enumerators:
Last Updated May 18, 2001