|
|
[Contents] [Previous] [Next] [Last]
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 Chapter 9, "I/O Types."
Functions that Operate on Pathnames
Functions that Act on File Descriptors
Directory I/O Functions
Socket Manipulation Functions
Converting Between Host and Network Addresses
Memory-Mapped I/O Functions
Anonymous Pipe Function
Polling Function
Manipulating Layers
Functions that Operate on Pathnames
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_Open
PR_Delete
PR_GetFileInfo
PR_GetFileInfo64
PR_Rename
PR_Access
PR_Open
Opens a file for reading, writing, or both. Also used to create a file.
Syntax
#include <prio.h>
PRFileDesc* PR_Open(
const char *name,
PRIntn flags,
PRIntn mode);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
PR_Open creates a file descriptor (PRFileDesc) for the file with the pathname name and sets the file status flags of the file descriptor according to the value of flags. If a new file is created as a result of the PR_Open call, its file mode bits are set according to the mode parameter.
PR_Delete
Deletes a file.
Syntax
#include <prio.h>
PRStatus PR_Delete(const char *name);
Parameter
The function has the following parameter:
Returns
One of the following values:
Description
Deletes a file from the file system. The operation may fail if the file is already open.
PR_GetFileInfo
Gets information about a file with a specified pathname. File size is expressed as a 32-bit integer.
Syntax
#include <prio.h>
PRStatus PR_GetFileInfo(
const char *fn,
PRFileInfo *info);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
PR_GetFileInfo stores information about the file with the specified pathname in the PRFileInfo structure pointed to by info. The file size is returned as an unsigned 32-bit integer.
See also
For the 64-bit version of this function, see PR_GetFileInfo64. To get equivalent information on a file that's already open, use PR_GetOpenFileInfo.
PR_GetFileInfo64
Gets information about a file with a specified pathname. File size is expressed as a 64-bit integer.
Syntax
#include <prio.h>
PRStatus PR_GetFileInfo64(
const char *fn,
PRFileInfo64 *info);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
PR_GetFileInfo64 stores information about the file with the specified pathname in the PRFileInfo64 structure pointed to by info. The file size is returned as an unsigned 64-bit integer.
See also
For the 32-bit version of this function, see PR_GetFileInfo. To get equivalent information on a file that's already open, use PR_GetOpenFileInfo64.
PR_Rename
Renames a file.
Syntax
#include <prio.h>
PRStatus PR_Rename(
const char *from,
const char *to);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
PR_Rename renames a file from its old name (from) to a new name (to). If a file with the new name already exists, PR_Rename fails with the error code PR_FILE_EXISTS_ERROR. In this case, PR_Rename does not overwrite the existing filename.
PR_Access
Determines the accessibility of a file.
Syntax
#include <prio.h>
PRStatus PR_Access(
const char *name,
PRAccessHow how);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
This is the declaration for the enumeration PRAccessHow, used in the how parameter:
typedef enum PRAccessHow {
PR_ACCESS_EXISTS = 1,
PR_ACCESS_WRITE_OK = 2,
PR_ACCESS_READ_OK = 3
} PRAccessHow;
Functions that Act on File Descriptors
PR_Close
PR_Read
PR_Write
PR_Writev
PR_GetOpenFileInfo
PR_GetOpenFileInfo64
PR_Seek
PR_Seek64
PR_Available
PR_Available64
PR_Sync
PR_GetDescType
PR_GetSpecialFD
PR_Close
Closes a file descriptor.
Syntax
#include <prio.h>
PRStatus PR_Close(PRFileDesc *fd);
Parameter
The function has the following parameter:
Returns
The function returns one of the following values:
Description
The file descriptor may represent a normal file, a socket, or an end point of a pipe. On successful return, PR_Close frees the dynamic memory and other resources identified by the fd parameter.
PR_Read
Reads bytes from a file or socket.
Syntax
#include <prio.h>
PRInt32 PR_Read(PRFileDesc *fd,
void *buf,
PRInt32 amount);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
The thread invoking PR_Read blocks until it encounters an end-of-stream indication, some positive number of bytes (but no more than amount bytes) are read in, or an error occurs.
PR_Write
Writes a buffer of data to a file or socket.
Syntax
#include <prio.h>
PRInt32 PR_Write(
PRFileDesc *fd,
const void *buf,
PRInt32 amount);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
The thread invoking PR_Write blocks until all the data is written or the write operation fails. Therefore, the return value is equal to either amount (success) or -1 (failure). Note that if PR_Write returns -1, some data (less than amount bytes) may have been written before an error occurred.
PR_Writev
Writes data to a file or socket from multiple buffers.
Syntax
#include <prio.h>
PRInt32 PR_Writev(
PRFileDesc *fd,
PRIOVec *iov,
PRInt32 size,
PRIntervalTime timeout);
#define PR_MAX_IOVECTOR_SIZE 16
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
The thread calling PR_Writev blocks until all the data is written or the write operation fails. Therefore, the return value is equal to either the sum of all the buffer lengths (on success) or -1 (on failure). Note that if PR_Writev returns -1, part of the data may have been written before an error occurred. If the timeout parameter is not PR_INTERVAL_NO_TIMEOUT and all the data cannot be written in the specified interval, PR_Writev returns -1 with the error code PR_IO_TIMEOUT_ERROR.
This is the type definition for PRIOVec:
typedef struct PRIOVec {
char *iov_base;
int iov_len;
} PRIOVec;
The PRIOVec structure has the following fields:
PR_GetOpenFileInfo
Gets an open file's information. File size is expressed as a 32-bit integer.
Syntax
#include <prio.h>
PRStatus PR_GetOpenFileInfo(
PRFileDesc *fd,
PRFileInfo *info);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
PR_GetOpenFileInfo obtains the file type (normal file, directory, or other), file size (as a 32-bit integer), and the file creation and modification times of the open file represented by the file descriptor.
See also
For the 64-bit version of this function, see PR_GetOpenFileInfo64. To get equivalent information on a file that's not already open, use PR_GetFileInfo.
PR_GetOpenFileInfo64
Gets an open file's information. File size is expressed as a 64-bit integer.
Syntax
#include <prio.h>
PRStatus PR_GetOpenFileInfo64(
PRFileDesc *fd,
PRFileInfo64 *info);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
PR_GetOpenFileInfo64 is the 64-bit version of PR_GetOpenFileInfo. It obtains the file type (normal file, directory, or other), file size (as a 64-bit integer), and the creation and modification times of the open file represented by the file descriptor.
See also
For the 32-bit version of this function, see PR_GetOpenFileInfo. To get equivalent information on a file that's not already open, use PR_GetFileInfo64.
PR_Seek
Moves the current read-write file pointer by an offset expressed as a 32-bit integer.
Syntax
#include <prio.h>
PRInt32 PR_Seek(
PRFileDesc *fd,
PRInt32 offset,
PRSeekWhence whence);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
Here's an idiom for obtaining the current location of the file pointer for the file descriptor in the fd parameter:
PR_Seek(fd, 0, PR_SEEK_CUR)
See also
If you need to move the file pointer by a large offset that's out of the range of a 32-bit integer, use PR_Seek64.
PR_Seek64
Moves the current read-write file pointer by an offset expressed as a 64-bit integer.
Syntax
#include <prio.h>
PRInt64 PR_Seek64(
PRFileDesc *fd,
PRInt64 offset,
PRSeekWhence whence);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
This is the idiom for obtaining the current location (expressed as a 64-bit integer) of the file pointer for the file descriptor in the fd parameter:
PR_Seek64(fd, 0, PR_SEEK_CUR)
If the native operating system is capable of handling only a 32-bit file offset, PR_Seek64 may fail with the error code PR_FILE_TOO_BIG_ERROR if the offset parameter is out of the range of a 32-bit integer.
See also
PR_Seek.
PR_Available
Determines the number of bytes (expressed as a 32-bit integer) that are available for reading beyond the current read-write pointer in a specified file or socket.
Syntax
#include <prio.h>
PRInt32 PR_Available(PRFileDesc *fd);
Parameter
The function has the following parameter:
Returns
The function returns one of the following values:
Description
PR_Available works on normal files and sockets. PR_Available does not work with pipes on Win32 platforms.
See also
If the number of bytes available for reading is out of the range of a 32-bit integer, use PR_Available64.
PR_Available64
Determines the number of bytes (expressed as a 64-bit integer) that are available for reading beyond the current read-write pointer in a specified file or socket.
Syntax
#include <prio.h>
PRInt64 PR_Available64(PRFileDesc *fd);
Parameter
The function has the following parameter:
Returns
The function returns one of the following values:
Description
PR_Available64 works on normal files and sockets. PR_Available does not work with pipes on Win32 platforms.
See also
If the number of bytes available for reading is within the range of a 32-bit integer, use PR_Available.
PR_Sync
Synchronizes any buffered data for a file descriptor to its backing device (disk).
Syntax
#include <prio.h>
PRStatus PR_Sync(PRFileDesc *fd);
Parameter
The function has the following parameter:
Returns
The function returns one of the following values:
Description
PR_Sync writes all the in-memory buffered data of the specified file to the disk.
PR_GetDescType
Describes what type of file is referenced by a specified file descriptor.
Syntax
#include <prio.h>
PRDescType PR_GetDescType(PRFileDesc *file);
Parameters
The function has the following parameters:
Returns
The function returns a PRDescType enumeration constant that describes the type of file.
Description
The PRDescType enumeration is defined as follows:
typedef enum PRDescType {
PR_DESC_FILE = 1,
PR_DESC_SOCKET_TCP = 2,
PR_DESC_SOCKET_UDP = 3,
PR_DESC_LAYERED = 4
} PRDescType;
The enumeration has the following enumerators:
PR_GetSpecialFD
Gets the file descriptor that represents the standard input, output, or error stream.
Syntax
#include <prio.h>
PRFileDesc* PR_GetSpecialFD(PRSpecialFD id);
Parameter
The function has the following parameter:
Returns
If the id parameter is valid, PR_GetSpecialFD returns a file descriptor that represents the corresponding standard I/O stream. Otherwise, PR_GetSpecialFD returns NULL and sets the error to PR_INVALID_ARGUMENT_ERROR.
Description
Type PRSpecialFD is defined as follows:
typedef enum PRSpecialFD{
PR_StandardInput,
PR_StandardOutput,
PR_StandardError
} PRSpecialFD;
#define PR_STDIN PR_GetSpecialFD(PR_StandardInput)
#define PR_STDOUT PR_GetSpecialFD(PR_StandardOutput)
#define PR_STDERR PR_GetSpecialFD(PR_StandardError)
File descriptors returned by PR_GetSpecialFD are owned by the runtime and should not be closed by the caller.
Directory I/O Functions
PR_OpenDir
PR_ReadDir
PR_CloseDir
PR_MkDir
PR_RmDir
PR_OpenDir
Opens the directory with the specified pathname.
Syntax
#include <prio.h>
PRDir* PR_OpenDir(const char *name);
Parameter
The function has the following parameter:
Returns
The function returns one of the following values:
Description
PR_OpenDir opens the directory specified by the pathname name and returns a pointer to a directory stream (a PRDir object) that can be passed to subsequent PR_ReadDir calls to get the directory entries (files and subdirectories) in the directory. The PRDir pointer should eventually be closed by a call to PR_CloseDir.
PR_ReadDir
Gets a pointer to the next entry in the directory.
Syntax
#include <prio.h>
PRDirEntry* PR_ReadDir(
PRDir *dir,
PRDirFlags flags);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
PR_ReadDir returns a pointer to a directory entry structure:
struct PRDirEntry {
const char *name;
};
typedef struct PRDirEntry PRDirEntry;
The structure has the following field:
The flags parameter is an enum of type PRDirFlags:
typedef enum PRDirFlags {
PR_SKIP_NONE = 0x0,
PR_SKIP_DOT = 0x1,
PR_SKIP_DOT_DOT = 0x2,
PR_SKIP_BOTH = 0x3,
PR_SKIP_HIDDEN = 0x4}
PRDirFlags;
The memory associated with the returned PRDirEntry structure is managed by NSPR. The caller must not free the PRDirEntry structure. Moreover, the PRDirEntry structure returned by each PR_ReadDir call is valid only until the next PR_ReadDir or PR_CloseDir call on the same PRDir object.
If the end of the directory is reached, PR_ReadDir returns NULL, and PR_GetError returns PR_NO_MORE_FILES_ERROR.
See also
PR_OpenDir
PR_CloseDir
Closes the specified directory.
Syntax
#include <prio.h>
PRStatus PR_CloseDir(PRDir *dir);
Parameter
The function has the following parameter:
Returns
The function returns one of the following values:
Description
When a PRDir object is no longer needed, it must be closed and freed with a call to PR_CloseDir call. Note that after a PR_CloseDir call, any PRDirEntry object returned by a previous PR_ReadDir call on the same PRDir object becomes invalid.
See also
PR_OpenDir
PR_MkDir
Creates a directory with a specified name and access mode.
Syntax
#include <prio.h>
PRStatus PR_MkDir(
const char *name,
PRIntn mode);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
PR_MkDir creates a new directory with the pathname name. All the path components up to but not including the leaf component must already exist. For example, if the pathname of the directory to be created is a/b/c/d, the directory a/b/c must already exist.
See also
PR_RmDir.
PR_RmDir
Removes a directory with a specified name.
Syntax
#include <prio.h>
PRStatus PR_RmDir(const char *name);
Parameter
The function has the following parameter:
Returns
The function returns one of the following values:
Description
PR_RmDir removes the directory specified by the pathname name. The directory must be empty. If the directory is not empty, PR_RmDir fails and PR_GetError returns the error code PR_DIRECTORY_NOT_EMPTY_ERROR.
See also
PR_MkDir.
Socket Manipulation Functions
The network programming interface presented here is a socket API modeled after the popular Berkeley sockets. Differences include the following:
For a useful supplement to the NSPR documentation, see the textbook Unix Network Programming, 2nd Ed., Vol. 1: Networking APIs: Sockets and XTI, by W. Richard Stevens (Prentice Hall PTR, 1998).
PR_NewUDPSocket
PR_NewTCPSocket
PR_Connect
PR_Accept
PR_Bind
PR_Listen
PR_Shutdown
PR_Recv
PR_Send
PR_RecvFrom
PR_SendTo
PR_TransmitFile
PR_AcceptRead
PR_GetSockName
PR_GetPeerName
PR_GetSocketOption
PR_SetSocketOption
PR_NewUDPSocket
Creates a new UDP socket.
Syntax
#include <prio.h>
PRFileDesc* PR_NewUDPSocket(void);
Returns
The function returns one of the following values:
Description
UDP (User Datagram Protocol) is a connectionless, unreliable datagram protocol of the TCP/IP protocol suite. UDP datagrams may be lost or delivered in duplicates or out of sequence.
PR_NewUDPSocket creates a new UDP socket. The socket may be bound to a well-known port number with PR_Bind. Datagrams can be sent with PR_SendTo and received with PR_RecvFrom. When the socket is no longer needed, it should be closed with a call to PR_Close.
PR_NewTCPSocket
Creates a new TCP socket.
Syntax
#include <prio.h>
PRFileDesc* PR_NewTCPSocket(void);
Returns
The function returns one of the following values:
Description
TCP (Transmission Control Protocol) is a connection-oriented, reliable byte-stream protocol of the TCP/IP protocol suite. PR_NewTCPSocket creates a new TCP socket. A TCP connection is established by a passive socket (the server) accepting a connection setup request from an active socket (the client). Typically, the server binds its socket to a well-known port with PR_Bind, calls PR_Listen to start listening for connection setup requests, and calls PR_Accept to accept a connection. The client makes a connection request using PR_Connect.
After a connection is established, the client and server may send and receive data between each other. To receive data, one can call PR_Read or PR_Recv. To send data, one can call PR_Write, PR_Writev, PR_Send, or PR_TransmitFile. PR_AcceptRead is suitable for use by the server to accept a new client connection and read the client's first request in one function call.
A TCP connection can be shut down by PR_Shutdown, and the sockets should be closed by PR_Close.
PR_Connect
Initiates a connection on a specified socket.
Syntax
#include <prio.h>
PRStatus PR_Connect(
PRFileDesc *fd,
PRNetAddr *addr,
PRIntervalTime timeout);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
PR_Connect is usually invoked on a TCP socket, but it may also be invoked on a UDP socket. Both cases are discussed here.
If the socket is a TCP socket, PR_Connect establishes a TCP connection to the peer. If the socket is not bound, it will be bound to an arbitrary local address.
PR_Connect blocks until either the connection is successfully established or an error occurs. If the timeout parameter is not PR_INTERVAL_NO_TIMEOUT and the connection setup cannot complete before the time limit, PR_Connect fails with the error code PR_IO_TIMEOUT_ERROR.
If the socket is a TCP socket, there is no connection setup to speak of, since UDP is connectionless. If PR_Connect is invoked on a UDP socket, it has an overloaded meaning: PR_Connect merely saves the specified address as the default peer address for the socket, so that subsequently one can send and receive datagrams from the socket using PR_Send and PR_Recv instead of the usual PR_SendTo and PR_RecvFrom.
PR_Accept
Accepts a connection on a specified socket.
Syntax
#include <prio.h>
PRFileDesc* PR_Accept(
PRFileDesc *fd,
PRNetAddr *addr,
PRIntervalTime timeout);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
The socket fd is a rendezvous socket that has been bound to an address with PR_Bind and is listening for connections after a call to PR_Listen. PR_Accept accepts the first connection from the queue of pending connections and creates a new socket for the newly accepted connection. The rendezvous socket can still be used to accept more connections.
If the addr parameter is not NULL, PR_Accept stores the address of the connecting entity in the PRNetAddr object pointed to by addr.
PR_Accept blocks the calling thread until either a new connection is successfully accepted or an error occurs. If the timeout parameter is not PR_INTERVAL_NO_TIMEOUT and no pending connection can be accepted before the time limit, PR_Accept returns NULL with the error code PR_IO_TIMEOUT_ERROR.
PR_Bind
Binds an address to a specified socket.
Syntax
#include <prio.h>
PRStatus PR_Bind(
PRFileDesc *fd,
PRNetAddr *addr);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
When a new socket is created, it has no address bound to it. PR_Bind assigns the specified address (also known as name) to the socket. If you do not care about the exact IP address assigned to the socket, set the inet.ip field of PRNetAddr to PR_htonl(INADDR_ANY). If you do not care about the TCP/UDP port assigned to the socket, set the inet.port field of PRNetAddr to 0.
Note that if PR_Connect is invoked on a socket that is not bound, it implicitly binds an arbitrary address the socket.
Call PR_GetSockName to obtain the address (name) bound to a socket.
PR_Listen
Listens for connections on a specified socket.
Syntax
#include <prio.h>
PRStatus PR_Listen(
PRFileDesc *fd,
PRIntn backlog);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
PR_Listen turns the specified socket into a rendezvous socket. It creates a queue for pending connections and starts to listen for connection requests on the socket. The maximum size of the queue for pending connections is specified by the backlog parameter. Pending connections may be accepted by calling PR_Accept.
PR_Shutdown
Shuts down part of a full-duplex connection on a specified socket.
Syntax
#include <prio.h>
PRStatus PR_Shutdown(
PRFileDesc *fd,
PRShutdownHow how);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
The PRShutdownHow enumeration is defined as follows:
typedef enum PRShutdownHow{
PR_SHUTDOWN_RCV = 0,
PR_SHUTDOWN_SEND = 1,
PR_SHUTDOWN_BOTH = 2
} PRShutdownHow;
PR_Recv
Receives bytes from a connected socket.
Syntax
#include <prio.h>
PRInt32 PR_Recv(
PRFileDesc *fd,
void *buf,
PRInt32 amount,
PRIntn flags,
PRIntervalTime timeout);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
PR_Recv blocks until some positive number of bytes are transferred, a timeout occurs, or an error occurs. No more than amount bytes will be transferred.
PR_Send
Sends bytes from a connected socket.
Syntax
#include <prio.h>
PRInt32 PR_Send(
PRFileDesc *fd,
const void *buf,
PRInt32 amount,
PRIntn flags,
PRIntervalTime timeout);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
PR_Send blocks until all bytes are sent, a timeout occurs, or an error occurs.
PR_RecvFrom
Receives bytes from a socket and stores the sending peer's address.
Syntax
#include <prio.h>
PRInt32 PR_RecvFrom(
PRFileDesc *fd,
void *buf,
PRInt32 amount,
PRIntn flags,
PRNetAddr *addr,
PRIntervalTime timeout);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
PR_RecvFrom receives up to a specified number of bytes from socket, which may or may not be connected. The operation blocks until one or more bytes are transferred, a timeout has occurred, or there is an error. No more than amount bytes will be transferred. PR_RecvFrom is usually used with a UDP socket.
PR_SendTo
Sends bytes a socket to a specified destination.
Syntax
#include <prio.h>
PRInt32 PR_SendTo(
PRFileDesc *fd,
const void *buf,
PRInt32 amount,
PRIntn flags,
PRNetAddr *addr,
PRIntervalTime timeout);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
PR_SendTo sends a specified number of bytes from a socket to the specified destination address. The calling thread blocks until all bytes are sent, a timeout has occurred, or there is an error.
PR_TransmitFile
Sends a complete file across a connected socket.
Syntax
#include <prio.h>
PRInt32 PR_TransmitFile(
PRFileDesc *networkSocket,
PRFileDesc *sourceFile,
const void *headers,
PRInt32 hlen,
PRTransmitFileFlags flags,
PRIntervalTime timeout);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
The PR_TransmitFile function sends a complete file (sourceFile) across a connected socket (networkSocket). If headers is non-NULL, PR_TransmitFile sends the headers across the socket before sending the file.
The enumeration PRTransmitFileFlags, used in the flags parameter, is defined as follows:
typedef enum PRTransmitFileFlags {
PR_TRANSMITFILE_KEEP_OPEN = 0,
PR_TRANSMITFILE_CLOSE_SOCKET = 1
} PRTransmitFileFlags;
PR_AcceptRead
Accepts a new connection and receives a block of data.
Syntax
#include <prio.h>
PRInt32 PR_AcceptRead(
PRFileDesc *listenSock,
PRFileDesc **acceptedSock,
PRNetAddr **peerAddr,
void *buf,
PRInt32 amount,
PRIntervalTime timeout);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
PR_AcceptRead accepts a new connection and retrieves the newly created socket's descriptor and the connecting peer's address. Also, as its name suggests, PR_AcceptRead receives the first block of data sent by the peer.
PR_GetSockName
Gets network address for a specified socket.
Syntax
#include <prio.h>
PRStatus PR_GetSockName(
PRFileDesc *fd,
PRNetAddr *addr);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
PR_GetPeerName
Gets the network address of the connected peer.
Syntax
#include <prio.h>
PRStatus PR_GetPeerName(
PRFileDesc *fd,
PRNetAddr *addr);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
PR_GetSocketOption
Retrieves the socket options set for a specified socket.
Syntax
#include <prio.h>
PRStatus PR_GetSocketOption(
PRFileDesc *fd,
PRSocketOptionData *data);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
PR_SetSocketOption
Sets the socket options for a specified socket.
Syntax
#include <prio.h>
PRStatus PR_SetSocketOption(
PRFileDesc *fd,
PRSocketOptionData *data);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
On input, the caller must set both the option and value fields of the PRSocketOptionData object pointed to by the data parameter.
Converting Between Host and Network Addresses
PR_ntohs
PR_ntohl
PR_htons
PR_htonl
PR_FamilyInet
PR_ntohs
Performs 16-bit conversion from network byte order to host byte order.
Syntax
#include <prnetdb.h>
PRUint16 PR_ntohs(PRUint16 conversion);
Parameter
The function has the following parameter:
Returns
The value of the conversion parameter in host byte order.
PR_ntohl
Performs 32-bit conversion from network byte order to host byte order.
Syntax
#include <prnetdb.h>
PRUint32 PR_ntohl(PRUint32 conversion);
Parameter
The function has the following parameter:
Returns
The value of the conversion parameter in host byte order.
PR_htons
Performs 16 bit conversion from host byte order to network byte order.
Syntax
#include <prnetdb.h>
PRUint16 PR_htons(PRUint16 conversion);
Parameter
The function has the following parameter:
Returns
The value of the conversion parameter in network byte order.
PR_htonl
Performs 32-bit conversion from host byte order to network byte order.
Syntax
#include <prnetdb.h>
PRUint32 PR_htonl(PRUint32 conversion);
Parameter
The function has the following parameter:
Returns
The value of the conversion parameter in network byte order.
PR_FamilyInet
Gets the value of the address family for Internet Protocol.
Syntax
#include <prnetdb.h>
PRUint16 PR_FamilyInet(void);
Returns
The value of the address family for Internet Protocol. This is usually AF_INET, but can also be AF_INET6 if IPv6 is enabled. The returned value can be assigned to the inet.family field of a PRNetAddr object.
Memory-Mapped I/O Functions
The 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 and Win32 only.
PR_CreateFileMap
Creates a file mapping object.
Syntax
#include <prio.h>
PRFileMap* PR_CreateFileMap(
PRFileDesc *fd,
PRInt64 size,
PRFileMapProtect prot);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
The PRFileMapProtect enumeration used in the prot parameter is defined as follows:
typedef enum PRFileMapProtect {
PR_PROT_READONLY,
PR_PROT_READWRITE,
PR_PROT_WRITECOPY
} PRFileMapProtect;
PR_CreateFileMap only prepares for the mapping a file to memory. The returned file-mapping object must be passed to PR_MemMap to actually map a section of the file to memory.
The file-mapping object should be closed with a PR_CloseFileMap call when it is no longer needed.
PR_MemMap
Maps a section of a file to memory.
Syntax
#include <prio.h>
void* PR_MemMap(
PRFileMap *fmap,
PRInt64 offset,
PRUint32 len);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
- If the section of file is successfully mapped, the starting address
of the memory region to which the section of file is mapped.
- If the section of file is not successfully mapped,
NULL.
The error code can be retrieved via
PR_GetError.
Description
PR_MemMap maps a section of the file represented by the file mapping fmap to memory. The section of the file starts at offset and has the length len.
When the file-mapping memory region is no longer needed, it should be unmapped with a call to PR_MemUnmap.
PR_MemUnmap
Unmap a memory region that is backed by a memory-mapped file.
Syntax
#include <prio.h>
PRStatus PR_MemUnmap(
void *addr,
PRUint32 len);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
PR_MemUnmap removes the file mapping for the memory region (addr, addr + len). The parameter addr is the return value of an earlier call to PR_MemMap.
PR_CloseFileMap
Closes a file mapping.
Syntax
#include <prio.h>
PRStatus PR_CloseFileMap(PRFileMap *fmap);
Parameter
The function has the following parameter:
Returns
The function returns one of the following values:
Description
When a file mapping created with a call to PR_CreateFileMap is no longer needed, it should be closed with a call to PR_CloseFileMap.
Anonymous Pipe Function
PR_CreatePipe
Creates an anonymous pipe and retrieves file descriptors for the read and write ends of the pipe.
Syntax
#include <prio.h>
PRStatus PR_CreatePipe(
PRFileDesc **readPipe,
PRFileDesc **writePipe);
Parameters
The function has the following parameters:
Returns
The function returns one of these values:
Description
PR_CreatePipe creates an anonymous pipe. Data written into the write end of the pipe can be read from the read end of the pipe. Pipes are useful for interprocess communication between a parent and a child process. When the pipe is no longer needed, both ends should be closed with calls to PR_Close.
PR_CreatePipe is currently implemented on Unix and Win32 only.
Polling Function
PR_Poll
Detects when I/O is ready for a set of file descriptors.
Syntax
#include <prio.h>
PRInt32 PR_Poll(
PRPollDesc *pds,
PRIntn npds,
PRIntervalTime timeout);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
This function returns as soon as I/O is ready on one or more of the underlying file/socket objects. A count of the number of ready descriptors is returned unless a timeout occurs, in which case zero is returned.
The in_flags field of the PRPollDesc data structure should be set to the I/O events (readable, writable, exception, or some combination) that the caller is interested in. On return, the out_flags field of the PRPollDesc data structure is set to indicate what kind of I/O is ready on the respective descriptor.
The PRPollDesc structure is defined as follows:
typedef struct PRPollDesc {
PRFileDesc* fd;
PRInt16 in_flags;
PRInt16 out_flags;
} PRPollDesc;
The structure has the following fields:
Note: The PR_POLL_ERR and PR_POLL_NVAL flags are used only in out_flags. The PR_POLL_ERR and PR_POLL_NVAL events are always reported by PR_Poll.
Manipulating Layers
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_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);
PR_GetUniqueIdentity
PR_GetNameForIdentity
PR_GetLayersIdentity
PR_GetIdentitiesLayer
PR_GetDefaultIOMethods
PR_CreateIOLayerStub
PR_PushIOLayer
PR_PopIOLayer
PR_GetUniqueIdentity
Asks the runtime to allocate a unique identity for a layer identified by the layer's name.
Syntax
#include <prio.h>
PRDescIdentity PR_GetUniqueIdentity(const char *layer_name);
Parameter
The function has the following parameter:
Returns
The function returns one of the following values:
Description
A string may be associated with a layer when the layer is created. PR_GetUniqueIdentity allocates a unique layer identity and associates it with the string. The string can be subsequently passed to PR_CreateIOLayerStub to create a new file descriptor of that layer.
WARNING:
For any particular layer name, PR_GetUniqueIdentity can be only called once. Only
one identity is allocated for each name.
PR_GetNameForIdentity
Gets the string associated with a layer's unique identity.
Syntax
#include <prio.h>
const char* PR_GetNameForIdentity(PRDescIdentity ident);
Parameter
The function has the following parameter:
Returns
The function returns one of the following values:
Description
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 pointer to that copy.
PR_GetLayersIdentity
Gets the unique identity for the layer of the specified file descriptor
Syntax
#include <prio.h>
PRDescIdentity PR_GetLayersIdentity(PRFileDesc* fd);
Parameter
The function has the following parameter:
Returns
If successful, the function returns the PRDescIdentity for the layer of the specified file descriptor.
PR_GetIdentitiesLayer
Finds the layer with the specified identity in the specified stack of layers.
Syntax
#include <prio.h>
PRFileDesc* PR_GetIdentitiesLayer(
PRFileDesc* stack,
PRDescIdentity id);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
The stack of layers to be searched is specified by the fd parameter, which is a layer in the stack. Both the layers underneath fd and the layers above fd are searched to find the layer with the specified identity.
PR_GetDefaultIOMethods
Gets the default I/O methods table.
Syntax
#include <prio.h>
const PRIOMethods* PR_GetDefaultIOMethods(void);
Returns
If successful, the function returns a pointer to a PRIOMethods structure.
Description
After using PR_GetDefaultIOMethods to identify the default I/O methods table, you can select elements from that table with which to build your own layer's methods table. You may not modify the default I/O methods table directly. You can pass your own layer's methods table to PR_CreateIOLayerStub to create your new layer.
PR_CreateIOLayerStub
Creates a new layer.
Syntax
#include <prio.h>
PRFileDesc* PR_CreateIOLayerStub(
PRDescIdentity ident
PRIOMethods const *methods);
Parameter
The function has the following parameter:
Returns
A new file descriptor for the specified layer.
Description
A new layer may be allocated by calling PR_CreateIOLayerStub. The file descriptor returned contains the pointer to the I/O methods table provided. The runtime neither modifies the table nor tests its correctness.
The caller should override appropriate contents of the file descriptor returned before pushing it onto the protocol stack.
PR_PushIOLayer
Adds a layer onto the stack.
Syntax
#include <prio.h>
PRStatus PR_PushIOLayer(
PRFileDesc *stack,
PRDescIdentity id,
PRFileDesc *layer);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
A file descriptor for a layer (possibly allocated using PR_CreateIOLayerStub) may be pushed onto an existing stack of file descriptors at any time. The new layer is inserted into the stack just above the layer with the identity specified by id.
Even if the id parameter indicates the topmost layer of the stack, the value of the file descriptor describing the original stack will not change. In other words, stack continues to point to the top of the stack after the function returns.
Caution: Keeping the pointer to the stack even as layers are pushed onto
the top of the stack is accomplished by swapping the contentes of the file
descriptor being pushed and the stack's current top layer file descriptor.
The intent is that the pointer to the stack remain the stack's identity
even if someone (perhaps covertly) has pushed other layers. There are some subtle
ramifications.
The ownership of the storage pointed to by the caller's layer argument is
relinquished to the runtime. Accessing the object via the pointer is not permitted
while the runtime has ownership. The correct mechanism to access the object is to
get a pointer to it by calling PR_GetIdentitiesLayer().
The contents of the caller's object are swapped into another
container, including the reference to the object's destructor. If
the original container was allocated using a different mechanism than used
by the runtime, the default calling of the layer's destructor by the runtime
will fail (PR_CreateIOLayerStub()
is provided to allocate layer objects and template implementations). The destructor will be called on all layers when the stack is closed (see PR_Close()). If the containers are
allocated by some method other than PR_CreateIOLayerStub(), it may
be required that the stack have the layers popped off (in reverse
order that they were pushed) before calling PR_Close().
PR_PopIOLayer
Removes a layer from the stack.
Syntax
#include <prio.h>
PRFileDesc *PR_PopIOLayer(
PRFileDesc *stack,
PRDescIdentity id);
Parameters
The function has the following parameters:
Returns
The function returns one of the following values:
Description
PR_PopIOLayer pops the specified layer from the stack. If the object to be removed is found, PR_PopIOLayer returns a pointer to the removed object The object then becomes the responsibility of the caller.
Even if the identity indicates the top layer of the stack, the reference returned is not the file descriptor for the stack and that file descriptor remains valid. In other words, stack continues to point to the top of the stack after the function returns.
[Contents] [Previous] [Next] [Last]
Last Updated: Wed Jul 29 15:36:41 PDT 1998
Copyright © 1998
Netscape Communications Corporation
|
