NSPR Reference: Chapter 9 I/O Types
Description: The Sun-Netscape Alliance, a strategic alliance formed by America Online and Sun Microsystems, Inc., is delivering iPlanet e-commerce software and enterprise solutions that enable companies to compete successfully in the Net Economy
Keywords: electronic commerce, ecommerce, ebusiness, e-business, e-commerce, enterprise software, net economy, Netscape, Sun Microsystems, Sun-Netscape Alliance, iPlanet, internet software

NSPR Reference Previous Contents Next

## Chapter 9 I/O Types

This chapter describes the most common NSPR types, enumerations, and structures used with the functions described in Chapter 10 "I/O Functions" and Chapter 11 "Network Addresses." These include the types used for system access, normal file I/O, and socket (network) I/O.

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 structure `PRDir` 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 type `PRFileDesc`. 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 as `PR_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:

    file_type
| Type of file represented (tos).
    close
| Close file and destroy descriptor.
    read
| Read up to the specified number of bytes into buffer.
    write
| Write specified number of bytes from buffer.
    available
| Determine number of bytes available for reading.
    available64
| Same as previous field, except 64-bit.
    fsync
| Flush all in-memory buffers of file to permanent store.
    seek
| Position the file pointer to the desired place.
    seek64
| Same as previous field, except 64-bit.
    fileInfo
| Get information about an open file.
    fileInfo64
| Same as previous field, except 64-bit.
    writev
| Write from a vector of buffers.
    connect
| Connect to the specified network address.
    accept
| Accept a connection from a network peer.
    bind
| Associate a network address with the file descriptor.
    listen
| Prepare to listen for network connections.
    shutdown
| Shut down a network connection.
    recv
| Receive up to the specified number of bytes.
    send
| Send all the bytes specified.
    recvfrom
| Receive up to the specified number of bytes and report network source.
    sendto
| Send bytes to specified network address.
    poll
| Test the file descriptor to see if it is ready for I/O.
    acceptread
| Accept and read from a new network file descriptor.
    transmitfile
| Transmit an entire file to the specified socket.
    getsockname
| Get network address associated with a file descriptor.
    getpeername
| Get peer's network address.
    getsockopt
| Get current setting of specified socket option.
    setsockopt
| Set value of specified socket option.

##### 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, the `write` 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 the `PRFilePrivate` 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 with `PR_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

The `PRFileInfo` 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 with `PR_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

The `PRFileInfo64` 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 the `type` 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:

    PR_FILE_FILE
| The information in the structure describes a file.
    PR_FILE_DIRECTORY
| The information in the structure describes a directory.
    PR_FILE_OTHER
| The information in the structure describes some other kind of file system object.

## 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:

    family
| Address family: `PR_AF_INET|PR_AF_INET6` for `raw.family`, `PR_AF_INET` for i`net.family`, `PR_AF_INET6` for `ipv6.family`.
    data
| Raw address data.
    port
| Port number of TCP or UDP, in network byte order.
    ip
| The actual 32 (for `inet.ip`) or 128 (for `ipv6.ip`) bits of IP address. The `inet.ip` field is in network byte order.
    pad
| Unused.
    flowinfo
| Routing information.

##### Description

The union `PRNetAddr` 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 the `ipv6.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 with `PR_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:

    ip_ttl
| IP time-to-live.
    mcast_ttl
| IP multicast time-to-live.
    tos
| IP type-of-service and precedence.
    non_blocking
| Nonblocking (network) I/O.
    reuse_addr
| Allow local address reuse.
    keep_alive
| Periodically test whether connection is still alive.
    mcast_loopback
| IP multicast loopback.
    no_delay
| Disable Nagle algorithm. Don't delay send to coalesce packets.
    max_segment
| TCP maximum segment size.
    recv_buffer_size
| Receive buffer size.
    send_buffer_size
| Send buffer size.
    linger
| Time to linger on close if data are present in socket send buffer.
    add_member
| Join an IP multicast group.
    drop_member
| Leave an IP multicast group.
    mcast_if
| IP multicast interface address.

##### 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 the `option` 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:

    PR_SockOpt_Nonblocking
| Nonblocking I/O.
    PR_SockOpt_Linger
| Time to linger on close if data is present in the socket send buffer.
    PR_SockOpt_Reuseaddr
| Allow local address reuse.
    PR_SockOpt_Keepalive
| Periodically test whether connection is still alive.
    PR_SockOpt_RecvBufferSize
| Receive buffer size.
    PR_SockOpt_SendBufferSize
| Send buffer size.
    PR_SockOpt_IpTimeToLive
| IP time-to-live.
    PR_SockOpt_IpTypeOfService
| IP type-of-service and precedence.
    PR_SockOpt_AddMember
| Join an IP multicast group.
    PR_SockOpt_DropMember
| Leave an IP multicast group.
    PR_SockOpt_McastInterface
| IP multicast interface address.
    PR_SockOpt_McastTimeToLive
| IP multicast time-to-live.
    PR_SockOpt_McastLoopback
| IP multicast loopback.
    PR_SockOpt_NoDelay
| Disable Nagle algorithm. Don't delay send to coalesce packets.
    PR_SockOpt_MaxSegment
| Maximum segment size.
    PR_SockOpt_Last
| Always one greater than the maximum valid socket option numerator.

##### Description

The `PRSockOption` 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 the `PR_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 the `PR_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

The `mcaddr` 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 by `PR_CreateFileMap` and passed to `PR_MemMap` and `PR_CloseFileMap`.

##### Syntax

    #include <prio.h>

    typedef struct PRFileMap PRFileMap;

##### Description

The opaque structure `PRFileMap` 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 the `offset` 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:

    PR_SEEK_SET
| Sets the file pointer to the value of the `offset` parameter.
    PR_SEEK_CUR
| Sets the file pointer to its current location plus the value of the `offset` parameter.
    PR_SEEK_END
| Sets the file pointer to the size of the file plus the value of the `offset` parameter.

Previous Contents Next

Last Updated May 18, 2001