The Tor Browser: nsprpub/pr/include/prio.h@6474c204b198 (annotated)

nsprpub/pr/include/prio.h@6474c204b198 (annotated)

nsprpub/pr/include/prio.h

Wed, 31 Dec 2014 06:09:35 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Wed, 31 Dec 2014 06:09:35 +0100
changeset 0: 6474c204b198
permissions: -rw-r--r--

Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.

 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
 /* This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 /*
  * File:     prio.h
  *
  * Description:    PR i/o related stuff, such as file system access, file
  *         i/o, socket i/o, etc.
  */
 #ifndef prio_h___
 #define prio_h___
 #include "prlong.h"
 #include "prtime.h"
 #include "prinrval.h"
 #include "prinet.h"
 PR_BEGIN_EXTERN_C
 /* Typedefs */
 typedef struct PRDir            PRDir;
 typedef struct PRDirEntry       PRDirEntry;
 #ifdef MOZ_UNICODE
 typedef struct PRDirUTF16       PRDirUTF16;
 typedef struct PRDirEntryUTF16  PRDirEntryUTF16;
 #endif /* MOZ_UNICODE */
 typedef struct PRFileDesc       PRFileDesc;
 typedef struct PRFileInfo       PRFileInfo;
 typedef struct PRFileInfo64     PRFileInfo64;
 typedef union  PRNetAddr        PRNetAddr;
 typedef struct PRIOMethods      PRIOMethods;
 typedef struct PRPollDesc       PRPollDesc;
 typedef struct PRFilePrivate    PRFilePrivate;
 typedef struct PRSendFileData   PRSendFileData;
 /*
 ***************************************************************************
 ** The file descriptor.
 ** This is the primary structure to represent any active open socket,
 ** whether it be a normal file or a network connection. Such objects
 ** are stackable (or layerable). Each layer may have its own set of
 ** method pointers and context private to that layer. All each layer
 ** knows about its neighbors is how to get to their method table.
 ***************************************************************************
 */
 typedef PRIntn PRDescIdentity;          /* see: Layering file descriptors */
 struct PRFileDesc {
     const PRIOMethods *methods;         /* the I/O methods table */
     PRFilePrivate *secret;              /* layer dependent data */
     PRFileDesc *lower, *higher;         /* pointers to adjacent layers */
     void (PR_CALLBACK *dtor)(PRFileDesc *fd);
                                         /* A destructor function for layer */
     PRDescIdentity identity;            /* Identity of this particular layer  */
 };
 /*
 ***************************************************************************
 ** PRTransmitFileFlags
 **
 ** Flags for PR_TransmitFile.  Pass PR_TRANSMITFILE_CLOSE_SOCKET to
 ** PR_TransmitFile if the connection should be closed after the file
 ** is transmitted.
 ***************************************************************************
 */
 typedef enum PRTransmitFileFlags {
     PR_TRANSMITFILE_KEEP_OPEN = 0,    /* socket is left open after file
                                        * is transmitted. */
     PR_TRANSMITFILE_CLOSE_SOCKET = 1  /* socket is closed after file
                                        * is transmitted. */
 } PRTransmitFileFlags;
 /*
 **************************************************************************
 ** Macros for PRNetAddr
 **
 ** Address families: PR_AF_INET, PR_AF_INET6, PR_AF_LOCAL
 ** IP addresses: PR_INADDR_ANY, PR_INADDR_LOOPBACK, PR_INADDR_BROADCAST
 **************************************************************************
 */
 #ifdef WIN32
 #define PR_AF_INET 2
 #define PR_AF_LOCAL 1
 #define PR_INADDR_ANY (unsigned long)0x00000000
 #define PR_INADDR_LOOPBACK 0x7f000001
 #define PR_INADDR_BROADCAST (unsigned long)0xffffffff
 #else /* WIN32 */
 #define PR_AF_INET AF_INET
 #define PR_AF_LOCAL AF_UNIX
 #define PR_INADDR_ANY INADDR_ANY
 #define PR_INADDR_LOOPBACK INADDR_LOOPBACK
 #define PR_INADDR_BROADCAST INADDR_BROADCAST
 #endif /* WIN32 */
 /*
 ** Define PR_AF_INET6 in prcpucfg.h with the same
 ** value as AF_INET6 on platforms with IPv6 support.
 ** Otherwise define it here.
 */
 #ifndef PR_AF_INET6
 #define PR_AF_INET6 100
 #endif
 #define PR_AF_INET_SDP 101
 #define PR_AF_INET6_SDP 102
 #ifndef PR_AF_UNSPEC
 #define PR_AF_UNSPEC 0
 #endif
 /*
 **************************************************************************
 ** A network address
 **
 ** Only Internet Protocol (IPv4 and IPv6) addresses are supported.
 ** The address family must always represent IPv4 (AF_INET, probably == 2)
 ** or IPv6 (AF_INET6).
 **************************************************************************
 *************************************************************************/
 struct PRIPv6Addr {
 	union {
 		PRUint8  _S6_u8[16];
 		PRUint16 _S6_u16[8];
 		PRUint32 _S6_u32[4];
 		PRUint64 _S6_u64[2];
 	} _S6_un;
 };
 #define pr_s6_addr		_S6_un._S6_u8
 #define pr_s6_addr16	_S6_un._S6_u16
 #define pr_s6_addr32	_S6_un._S6_u32
 #define pr_s6_addr64 	_S6_un._S6_u64
 typedef struct PRIPv6Addr PRIPv6Addr;
 union PRNetAddr {
     struct {
         PRUint16 family;                /* address family (0x00ff maskable) */
 #ifdef XP_BEOS
         char data[10];                  /* Be has a smaller structure */
 #else
         char data[14];                  /* raw address data */
 #endif
     } raw;
     struct {
         PRUint16 family;                /* address family (AF_INET) */
         PRUint16 port;                  /* port number */
         PRUint32 ip;                    /* The actual 32 bits of address */
 #ifdef XP_BEOS
         char pad[4];                    /* Be has a smaller structure */
 #else
         char pad[8];
 #endif
     } inet;
     struct {
         PRUint16 family;                /* address family (AF_INET6) */
         PRUint16 port;                  /* port number */
         PRUint32 flowinfo;              /* routing information */
         PRIPv6Addr ip;                  /* the actual 128 bits of address */
         PRUint32 scope_id;              /* set of interfaces for a scope */
     } ipv6;
 #if defined(XP_UNIX) || defined(XP_OS2)
     struct {                            /* Unix domain socket address */
         PRUint16 family;                /* address family (AF_UNIX) */
 #ifdef XP_OS2
         char path[108];                 /* null-terminated pathname */
                                         /* bind fails if size is not 108. */
 #else
         char path[104];                 /* null-terminated pathname */
 #endif
     } local;
 #endif
 };
 /*
 ***************************************************************************
 ** PRSockOption
 **
 ** The file descriptors can have predefined options set after they file
 ** descriptor is created to change their behavior. Only the options in
 ** the following enumeration are supported.
 ***************************************************************************
 */
 typedef enum PRSockOption
 {
     PR_SockOpt_Nonblocking,     /* nonblocking io */
     PR_SockOpt_Linger,          /* linger on close if data present */
     PR_SockOpt_Reuseaddr,       /* allow local address reuse */
     PR_SockOpt_Keepalive,       /* keep connections alive */
     PR_SockOpt_RecvBufferSize,  /* send buffer size */
     PR_SockOpt_SendBufferSize,  /* receive buffer size */
     PR_SockOpt_IpTimeToLive,    /* time to live */
     PR_SockOpt_IpTypeOfService, /* type of service and precedence */
     PR_SockOpt_AddMember,       /* add an IP group membership */
     PR_SockOpt_DropMember,      /* drop an IP group membership */
     PR_SockOpt_McastInterface,  /* multicast interface address */
     PR_SockOpt_McastTimeToLive, /* multicast timetolive */
     PR_SockOpt_McastLoopback,   /* multicast loopback */
     PR_SockOpt_NoDelay,         /* don't delay send to coalesce packets */
     PR_SockOpt_MaxSegment,      /* maximum segment size */
     PR_SockOpt_Broadcast,       /* enable broadcast */
     PR_SockOpt_Reuseport,       /* allow local address & port reuse on
                                  * platforms that support it */
     PR_SockOpt_Last
 } PRSockOption;
 typedef struct PRLinger {
 	PRBool polarity;		    /* Polarity of the option's setting */
 	PRIntervalTime linger;	    /* Time to linger before closing */
 } PRLinger;
 typedef struct PRMcastRequest {
 	PRNetAddr mcaddr;			/* IP multicast address of group */
 	PRNetAddr ifaddr;			/* local IP address of interface */
 } PRMcastRequest;
 typedef struct PRSocketOptionData
 {
     PRSockOption option;
     union
     {
         PRUintn ip_ttl;             /* IP time to live */
         PRUintn mcast_ttl;          /* IP multicast time to live */
         PRUintn tos;                /* IP type of service and precedence */
         PRBool non_blocking;        /* Non-blocking (network) I/O */
         PRBool reuse_addr;          /* Allow local address reuse */
         PRBool reuse_port;          /* Allow local address & port reuse on
                                      * platforms that support it */
         PRBool keep_alive;          /* Keep connections alive */
         PRBool mcast_loopback;      /* IP multicast loopback */
         PRBool no_delay;            /* Don't delay send to coalesce packets */
         PRBool broadcast;           /* Enable broadcast */
         PRSize max_segment;         /* Maximum segment size */
         PRSize recv_buffer_size;    /* Receive buffer size */
         PRSize send_buffer_size;    /* Send buffer size */
         PRLinger linger;            /* Time to linger on close if data present */
         PRMcastRequest add_member;  /* add an IP group membership */
         PRMcastRequest drop_member; /* Drop an IP group membership */
         PRNetAddr mcast_if;         /* multicast interface address */
     } value;
 } PRSocketOptionData;
 /*
 ***************************************************************************
 ** PRIOVec
 **
 ** The I/O vector is used by the write vector method to describe the areas
 ** that are affected by the ouput operation.
 ***************************************************************************
 */
 typedef struct PRIOVec {
     char *iov_base;
     int iov_len;
 } PRIOVec;
 /*
 ***************************************************************************
 ** Discover what type of socket is being described by the file descriptor.
 ***************************************************************************
 */
 typedef enum PRDescType
 {
     PR_DESC_FILE = 1,
     PR_DESC_SOCKET_TCP = 2,
     PR_DESC_SOCKET_UDP = 3,
     PR_DESC_LAYERED = 4,
     PR_DESC_PIPE = 5
 } PRDescType;
 typedef enum PRSeekWhence {
     PR_SEEK_SET = 0,
     PR_SEEK_CUR = 1,
     PR_SEEK_END = 2
 } PRSeekWhence;
 NSPR_API(PRDescType) PR_GetDescType(PRFileDesc *file);
 /*
 ***************************************************************************
 ** PRIOMethods
 **
 ** 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. If a layer provides
 ** no functionality, it should call the next lower(higher) function of the
 ** same name (e.g., return fd->lower->method->close(fd->lower));
 **
 ** Not all functions are implemented for all types of files. In cases where
 ** that is true, the function will return a error indication with an error
 ** code of PR_INVALID_METHOD_ERROR.
 ***************************************************************************
 */
 typedef PRStatus (PR_CALLBACK *PRCloseFN)(PRFileDesc *fd);
 typedef PRInt32 (PR_CALLBACK *PRReadFN)(PRFileDesc *fd, void *buf, PRInt32 amount);
 typedef PRInt32 (PR_CALLBACK *PRWriteFN)(PRFileDesc *fd, const void *buf, PRInt32 amount);
 typedef PRInt32 (PR_CALLBACK *PRAvailableFN)(PRFileDesc *fd);
 typedef PRInt64 (PR_CALLBACK *PRAvailable64FN)(PRFileDesc *fd);
 typedef PRStatus (PR_CALLBACK *PRFsyncFN)(PRFileDesc *fd);
 typedef PROffset32 (PR_CALLBACK *PRSeekFN)(PRFileDesc *fd, PROffset32 offset, PRSeekWhence how);
 typedef PROffset64 (PR_CALLBACK *PRSeek64FN)(PRFileDesc *fd, PROffset64 offset, PRSeekWhence how);
 typedef PRStatus (PR_CALLBACK *PRFileInfoFN)(PRFileDesc *fd, PRFileInfo *info);
 typedef PRStatus (PR_CALLBACK *PRFileInfo64FN)(PRFileDesc *fd, PRFileInfo64 *info);
 typedef PRInt32 (PR_CALLBACK *PRWritevFN)(
     PRFileDesc *fd, const PRIOVec *iov, PRInt32 iov_size,
     PRIntervalTime timeout);
 typedef PRStatus (PR_CALLBACK *PRConnectFN)(
     PRFileDesc *fd, const PRNetAddr *addr, PRIntervalTime timeout);
 typedef PRFileDesc* (PR_CALLBACK *PRAcceptFN) (
     PRFileDesc *fd, PRNetAddr *addr, PRIntervalTime timeout);
 typedef PRStatus (PR_CALLBACK *PRBindFN)(PRFileDesc *fd, const PRNetAddr *addr);
 typedef PRStatus (PR_CALLBACK *PRListenFN)(PRFileDesc *fd, PRIntn backlog);
 typedef PRStatus (PR_CALLBACK *PRShutdownFN)(PRFileDesc *fd, PRIntn how);
 typedef PRInt32 (PR_CALLBACK *PRRecvFN)(
     PRFileDesc *fd, void *buf, PRInt32 amount,
     PRIntn flags, PRIntervalTime timeout);
 typedef PRInt32 (PR_CALLBACK *PRSendFN) (
     PRFileDesc *fd, const void *buf, PRInt32 amount,
     PRIntn flags, PRIntervalTime timeout);
 typedef PRInt32 (PR_CALLBACK *PRRecvfromFN)(
     PRFileDesc *fd, void *buf, PRInt32 amount,
     PRIntn flags, PRNetAddr *addr, PRIntervalTime timeout);
 typedef PRInt32 (PR_CALLBACK *PRSendtoFN)(
     PRFileDesc *fd, const void *buf, PRInt32 amount,
     PRIntn flags, const PRNetAddr *addr, PRIntervalTime timeout);
 typedef PRInt16 (PR_CALLBACK *PRPollFN)(
     PRFileDesc *fd, PRInt16 in_flags, PRInt16 *out_flags);
 typedef PRInt32 (PR_CALLBACK *PRAcceptreadFN)(
     PRFileDesc *sd, PRFileDesc **nd, PRNetAddr **raddr,
     void *buf, PRInt32 amount, PRIntervalTime t);
 typedef PRInt32 (PR_CALLBACK *PRTransmitfileFN)(
      PRFileDesc *sd, PRFileDesc *fd, const void *headers,
      PRInt32 hlen, PRTransmitFileFlags flags, PRIntervalTime t);
 typedef PRStatus (PR_CALLBACK *PRGetsocknameFN)(PRFileDesc *fd, PRNetAddr *addr);
 typedef PRStatus (PR_CALLBACK *PRGetpeernameFN)(PRFileDesc *fd, PRNetAddr *addr);
 typedef PRStatus (PR_CALLBACK *PRGetsocketoptionFN)(
     PRFileDesc *fd, PRSocketOptionData *data);
 typedef PRStatus (PR_CALLBACK *PRSetsocketoptionFN)(
     PRFileDesc *fd, const PRSocketOptionData *data);
 typedef PRInt32 (PR_CALLBACK *PRSendfileFN)(
 	PRFileDesc *networkSocket, PRSendFileData *sendData,
 	PRTransmitFileFlags flags, PRIntervalTime timeout);
 typedef PRStatus (PR_CALLBACK *PRConnectcontinueFN)(
     PRFileDesc *fd, PRInt16 out_flags);
 typedef PRIntn (PR_CALLBACK *PRReservedFN)(PRFileDesc *fd);
 struct PRIOMethods {
     PRDescType file_type;           /* Type of file represented (tos)           */
     PRCloseFN close;                /* close file and destroy descriptor        */
     PRReadFN read;                  /* read up to specified bytes into buffer   */
     PRWriteFN write;                /* write specified bytes from buffer        */
     PRAvailableFN available;        /* determine number of bytes available      */
     PRAvailable64FN available64;    /*          ditto, 64 bit                   */
     PRFsyncFN fsync;                /* flush all buffers to permanent store     */
     PRSeekFN seek;                  /* position the file to the desired place   */
     PRSeek64FN seek64;              /*           ditto, 64 bit                  */
     PRFileInfoFN fileInfo;          /* Get information about an open file       */
     PRFileInfo64FN fileInfo64;      /*           ditto, 64 bit                  */
     PRWritevFN writev;              /* Write segments as described by iovector  */
     PRConnectFN connect;            /* Connect to the specified (net) address   */
     PRAcceptFN accept;              /* Accept a connection for a (net) peer     */
     PRBindFN bind;                  /* Associate a (net) address with the fd    */
     PRListenFN listen;              /* Prepare to listen for (net) connections  */
     PRShutdownFN shutdown;          /* Shutdown a (net) connection              */
     PRRecvFN recv;                  /* Solicit up the the specified bytes       */
     PRSendFN send;                  /* Send all the bytes specified             */
     PRRecvfromFN recvfrom;          /* Solicit (net) bytes and report source    */
     PRSendtoFN sendto;              /* Send bytes to (net) address specified    */
     PRPollFN poll;                  /* Test the fd to see if it is ready        */
     PRAcceptreadFN acceptread;      /* Accept and read on a new (net) fd        */
     PRTransmitfileFN transmitfile;  /* Transmit at entire file                  */
     PRGetsocknameFN getsockname;    /* Get (net) address associated with fd     */
     PRGetpeernameFN getpeername;    /* Get peer's (net) address                 */
     PRReservedFN reserved_fn_6;     /* reserved for future use */
     PRReservedFN reserved_fn_5;     /* reserved for future use */
     PRGetsocketoptionFN getsocketoption;
                                     /* Get current setting of specified option  */
     PRSetsocketoptionFN setsocketoption;
                                     /* Set value of specified option            */
     PRSendfileFN sendfile;			/* Send a (partial) file with header/trailer*/
     PRConnectcontinueFN connectcontinue;
                                     /* Continue a nonblocking connect */
     PRReservedFN reserved_fn_3;		/* reserved for future use */
     PRReservedFN reserved_fn_2;		/* reserved for future use */
     PRReservedFN reserved_fn_1;		/* reserved for future use */
     PRReservedFN reserved_fn_0;		/* reserved for future use */
 };
 /*
  **************************************************************************
  * FUNCTION: PR_GetSpecialFD
  * DESCRIPTION: Get the file descriptor that represents the standard input,
  *              output, or error stream.
  * INPUTS:
  *     PRSpecialFD id
  *         A value indicating the type of stream desired:
  *             PR_StandardInput: standard input
  *             PR_StandardOuput: standard output
  *             PR_StandardError: standard error
  * OUTPUTS: none
  * RETURNS: PRFileDesc *
  *     If the argument is valid, PR_GetSpecialFD returns a file descriptor
  *     that represents the corresponding standard I/O stream.  Otherwise,
  *     PR_GetSpecialFD returns NULL and sets error PR_INVALID_ARGUMENT_ERROR.
  **************************************************************************
  */
 typedef enum PRSpecialFD
 {
     PR_StandardInput,          /* standard input */
     PR_StandardOutput,         /* standard output */
     PR_StandardError           /* standard error */
 } PRSpecialFD;
 NSPR_API(PRFileDesc*) PR_GetSpecialFD(PRSpecialFD id);
 #define PR_STDIN	PR_GetSpecialFD(PR_StandardInput)
 #define PR_STDOUT	PR_GetSpecialFD(PR_StandardOutput)
 #define PR_STDERR	PR_GetSpecialFD(PR_StandardError)
 /*
  **************************************************************************
  * Layering file descriptors
  *
  * File descriptors may be layered. Each layer has it's own identity.
  * Identities are allocated by the runtime and are to be associated
  * (by the layer implementor) with all layers that are of that type.
  * It is then possible to scan the chain of layers and find a layer
  * that one recongizes and therefore predict that it will implement
  * a desired protocol.
  *
  * There are three well-known identities:
  *      PR_INVALID_IO_LAYER => an invalid layer identity, for error return
  *      PR_TOP_IO_LAYER     => the identity of the top of the stack
  *      PR_NSPR_IO_LAYER    => the identity used by NSPR proper
  * PR_TOP_IO_LAYER may be used as a shorthand for identifying the topmost
  * layer of an existing stack. Ie., the following two constructs are
  * equivalent.
  *
  *      rv = PR_PushIOLayer(stack, PR_TOP_IO_LAYER, my_layer);
  *      rv = PR_PushIOLayer(stack, PR_GetLayersIdentity(stack), my_layer)
  *
  * A string may be associated with the creation of the identity. It
  * will be copied by the runtime. If queried the runtime will return
  * a reference to that copied string (not yet another copy). There
  * is no facility for deleting an identity.
  **************************************************************************
  */
 #define PR_IO_LAYER_HEAD (PRDescIdentity)-3
 #define PR_INVALID_IO_LAYER (PRDescIdentity)-1
 #define PR_TOP_IO_LAYER (PRDescIdentity)-2
 #define PR_NSPR_IO_LAYER (PRDescIdentity)0
 NSPR_API(PRDescIdentity) PR_GetUniqueIdentity(const char *layer_name);
 NSPR_API(const char*) PR_GetNameForIdentity(PRDescIdentity ident);
 NSPR_API(PRDescIdentity) PR_GetLayersIdentity(PRFileDesc* fd);
 NSPR_API(PRFileDesc*) PR_GetIdentitiesLayer(PRFileDesc* fd_stack, PRDescIdentity id);
 /*
  **************************************************************************
  * PR_GetDefaultIOMethods: Accessing the default methods table.
  * You may get a pointer to the default methods table by calling this function.
  * You may then select any elements from that table with which to build your
  * layer's methods table. You may NOT modify the table directly.
  **************************************************************************
  */
 NSPR_API(const PRIOMethods *) PR_GetDefaultIOMethods(void);
 /*
  **************************************************************************
  * Creating a layer
  *
  * A new layer may be allocated by calling PR_CreateIOLayerStub(). The
  * file descriptor returned will contain the pointer to the methods table
  * provided. The runtime will not modify the table nor test its correctness.
  **************************************************************************
  */
 NSPR_API(PRFileDesc*) PR_CreateIOLayerStub(
     PRDescIdentity ident, const PRIOMethods *methods);
 /*
  **************************************************************************
  * Creating a layer
  *
  * A new stack may be created by calling PR_CreateIOLayer(). The
  * file descriptor returned will point to the top of the stack, which has
  * the layer 'fd' as the topmost layer.
  *
  * NOTE: This function creates a new style stack, which has a fixed, dummy
  * header. The old style stack, created by a call to PR_PushIOLayer,
  * results in modifying contents of the top layer of the stack, when
  * pushing and popping layers of the stack.
  **************************************************************************
  */
 NSPR_API(PRFileDesc*) PR_CreateIOLayer(PRFileDesc* fd);
 /*
  **************************************************************************
  * Pushing a layer
  *
  * A file descriptor (perhaps allocated using PR_CreateIOLayerStub()) may
  * be pushed into an existing stack of file descriptors at any point the
  * caller deems appropriate. The new layer will be inserted into the stack
  * just above the layer with the indicated identity.
  *
  * Note: Even if the identity parameter indicates the top-most layer of
  * the stack, the value of the file descriptor describing the original
  * stack will not change.
  **************************************************************************
  */
 NSPR_API(PRStatus) PR_PushIOLayer(
     PRFileDesc *fd_stack, PRDescIdentity id, PRFileDesc *layer);
 /*
  **************************************************************************
  * Popping a layer
  *
  * A layer may be popped from a stack by indicating the identity of the
  * layer to be removed. If found, a pointer to the removed object will
  * be returned to the caller. The object then becomes the responsibility
  * of the caller.
  *
  * Note: Even if the identity indicates the top layer of the stack, the
  * reference returned will not be the file descriptor for the stack and
  * that file descriptor will remain valid.
  **************************************************************************
  */
 NSPR_API(PRFileDesc*) PR_PopIOLayer(PRFileDesc *fd_stack, PRDescIdentity id);
 /*
  **************************************************************************
  * FUNCTION:    PR_Open
  * DESCRIPTION:    Open a file for reading, writing, or both.
  * INPUTS:
  *     const char *name
  *         The path name of the file to be opened
  *     PRIntn flags
  *         The file status flags.
  *         It is a bitwise OR of the following bit flags (only one of
  *         the first three flags below may be used):
  *		PR_RDONLY        Open for reading only.
  *		PR_WRONLY        Open for writing only.
  *		PR_RDWR          Open for reading and writing.
  *		PR_CREATE_FILE   If the file does not exist, the file is created
  *                              If the file exists, this flag has no effect.
  *      PR_SYNC          If set, each write will wait for both the file data
  *                              and file status to be physically updated.
  *		PR_APPEND        The file pointer is set to the end of
  *                              the file prior to each write.
  *		PR_TRUNCATE      If the file exists, its length is truncated to 0.
  *      PR_EXCL          With PR_CREATE_FILE, if the file does not exist,
  *                              the file is created. If the file already
  *                              exists, no action and NULL is returned
  *
  *     PRIntn mode
  *         The access permission bits of the file mode, if the file is
  *         created when PR_CREATE_FILE is on.
  * OUTPUTS:    None
  * RETURNS:    PRFileDesc *
  *     If the file is successfully opened,
  *     returns a pointer to the PRFileDesc
  *     created for the newly opened file.
  *     Returns a NULL pointer if the open
  *     failed.
  * SIDE EFFECTS:
  * RESTRICTIONS:
  * MEMORY:
  *     The return value, if not NULL, points to a dynamically allocated
  *     PRFileDesc object.
  * ALGORITHM:
  **************************************************************************
  */
 /* Open flags */
 #define PR_RDONLY       0x01
 #define PR_WRONLY       0x02
 #define PR_RDWR         0x04
 #define PR_CREATE_FILE  0x08
 #define PR_APPEND       0x10
 #define PR_TRUNCATE     0x20
 #define PR_SYNC         0x40
 #define PR_EXCL         0x80
 /*
 ** File modes ....
 **
 ** CAVEAT: 'mode' is currently only applicable on UNIX platforms.
 ** The 'mode' argument may be ignored by PR_Open on other platforms.
 **
 **   00400   Read by owner.
 **   00200   Write by owner.
 **   00100   Execute (search if a directory) by owner.
 **   00040   Read by group.
 **   00020   Write by group.
 **   00010   Execute by group.
 **   00004   Read by others.
 **   00002   Write by others
 **   00001   Execute by others.
 **
 */
 NSPR_API(PRFileDesc*) PR_Open(const char *name, PRIntn flags, PRIntn mode);
 /*
  **************************************************************************
  * FUNCTION: PR_OpenFile
  * DESCRIPTION:
  *     Open a file for reading, writing, or both.
  *     PR_OpenFile has the same prototype as PR_Open but implements
  *     the specified file mode where possible.
  **************************************************************************
  */
 /* File mode bits */
 #define PR_IRWXU 00700  /* read, write, execute/search by owner */
 #define PR_IRUSR 00400  /* read permission, owner */
 #define PR_IWUSR 00200  /* write permission, owner */
 #define PR_IXUSR 00100  /* execute/search permission, owner */
 #define PR_IRWXG 00070  /* read, write, execute/search by group */
 #define PR_IRGRP 00040  /* read permission, group */
 #define PR_IWGRP 00020  /* write permission, group */
 #define PR_IXGRP 00010  /* execute/search permission, group */
 #define PR_IRWXO 00007  /* read, write, execute/search by others */
 #define PR_IROTH 00004  /* read permission, others */
 #define PR_IWOTH 00002  /* write permission, others */
 #define PR_IXOTH 00001  /* execute/search permission, others */
 NSPR_API(PRFileDesc*) PR_OpenFile(
     const char *name, PRIntn flags, PRIntn mode);
 #ifdef MOZ_UNICODE
 /*
  * EXPERIMENTAL: This function may be removed in a future release.
  */
 NSPR_API(PRFileDesc*) PR_OpenFileUTF16(
     const PRUnichar *name, PRIntn flags, PRIntn mode);
 #endif /* MOZ_UNICODE */
 /*
  **************************************************************************
  * FUNCTION: PR_Close
  * DESCRIPTION:
  *     Close a file or socket.
  * INPUTS:
  *     PRFileDesc *fd
  *         a pointer to a PRFileDesc.
  * OUTPUTS:
  *     None.
  * RETURN:
  *     PRStatus
  * SIDE EFFECTS:
  * RESTRICTIONS:
  *     None.
  * MEMORY:
  *     The dynamic memory pointed to by the argument fd is freed.
  **************************************************************************
  */
 NSPR_API(PRStatus)    PR_Close(PRFileDesc *fd);
 /*
  **************************************************************************
  * FUNCTION: PR_Read
  * DESCRIPTION:
  *     Read bytes from a file or socket.
  *     The operation will block until either an end of stream indication is
  *     encountered, some positive number of bytes are transferred, or there
  *     is an error. No more than 'amount' bytes will be transferred.
  * INPUTS:
  *     PRFileDesc *fd
  *         pointer to the PRFileDesc object for the file or socket
  *     void *buf
  *         pointer to a buffer to hold the data read in.
  *     PRInt32 amount
  *         the size of 'buf' (in bytes)
  * OUTPUTS:
  * RETURN:
  *     PRInt32
  *         a positive number indicates the number of bytes actually read in.
  *         0 means end of file is reached or the network connection is closed.
  *         -1 indicates a failure. The reason for the failure is obtained
  *         by calling PR_GetError().
  * SIDE EFFECTS:
  *     data is written into the buffer pointed to by 'buf'.
  * RESTRICTIONS:
  *     None.
  * MEMORY:
  *     N/A
  * ALGORITHM:
  *     N/A
  **************************************************************************
  */
 NSPR_API(PRInt32) PR_Read(PRFileDesc *fd, void *buf, PRInt32 amount);
 /*
  ***************************************************************************
  * FUNCTION: PR_Write
  * DESCRIPTION:
  *     Write a specified number of bytes to a file or socket.  The thread
  *     invoking this function blocks until all the data is written.
  * INPUTS:
  *     PRFileDesc *fd
  *         pointer to a PRFileDesc object that refers to a file or socket
  *     const void *buf
  *         pointer to the buffer holding the data
  *     PRInt32 amount
  *         amount of data in bytes to be written from the buffer
  * OUTPUTS:
  *     None.
  * RETURN: PRInt32
  *     A positive number indicates the number of bytes successfully written.
  *     A -1 is an indication that the operation failed. The reason
  *     for the failure is obtained by calling PR_GetError().
  ***************************************************************************
  */
 NSPR_API(PRInt32) PR_Write(PRFileDesc *fd,const void *buf,PRInt32 amount);
 /*
  ***************************************************************************
  * FUNCTION: PR_Writev
  * DESCRIPTION:
  *     Write data to a socket.  The data is organized in a PRIOVec array. The
  *     operation will block until all the data is written or the operation
  *     fails.
  * INPUTS:
  *     PRFileDesc *fd
  *         Pointer that points to a PRFileDesc object for a socket.
  *     const PRIOVec *iov
  *         An array of PRIOVec.  PRIOVec is a struct with the following
  *         two fields:
  *             char *iov_base;
  *             int iov_len;
  *     PRInt32 iov_size
  *         Number of elements in the iov array. The value of this
  *         argument must not be greater than PR_MAX_IOVECTOR_SIZE.
  *         If it is, the method will fail (PR_BUFFER_OVERFLOW_ERROR).
  *     PRIntervalTime timeout
  *       Time limit for completion of the entire write operation.
  * OUTPUTS:
  *     None
  * RETURN:
  *     A positive number indicates the number of bytes successfully written.
  *     A -1 is an indication that the operation failed. The reason
  *     for the failure is obtained by calling PR_GetError().
  ***************************************************************************
  */
 #define PR_MAX_IOVECTOR_SIZE 16   /* 'iov_size' must be <= */
 NSPR_API(PRInt32) PR_Writev(
     PRFileDesc *fd, const PRIOVec *iov, PRInt32 iov_size,
     PRIntervalTime timeout);
 /*
  ***************************************************************************
  * FUNCTION: PR_Delete
  * DESCRIPTION:
  *     Delete a file from the filesystem. The operation may fail if the
  *     file is open.
  * INPUTS:
  *     const char *name
  *         Path name of the file to be deleted.
  * OUTPUTS:
  *     None.
  * RETURN: PRStatus
  *     The function returns PR_SUCCESS if the file is successfully
  *     deleted, otherwise it returns PR_FAILURE.
  ***************************************************************************
  */
 NSPR_API(PRStatus) PR_Delete(const char *name);
 /**************************************************************************/
 typedef enum PRFileType
 {
     PR_FILE_FILE = 1,
     PR_FILE_DIRECTORY = 2,
     PR_FILE_OTHER = 3
 } PRFileType;
 struct PRFileInfo {
     PRFileType type;        /* Type of file */
     PROffset32 size;        /* Size, in bytes, of file's contents */
     PRTime creationTime;    /* Creation time per definition of PRTime */
     PRTime modifyTime;      /* Last modification time per definition of PRTime */
 };
 struct PRFileInfo64 {
     PRFileType type;        /* Type of file */
     PROffset64 size;        /* Size, in bytes, of file's contents */
     PRTime creationTime;    /* Creation time per definition of PRTime */
     PRTime modifyTime;      /* Last modification time per definition of PRTime */
 };
 /****************************************************************************
  * FUNCTION: PR_GetFileInfo, PR_GetFileInfo64
  * DESCRIPTION:
  *     Get the information about the file with the given path name. This is
  *     applicable only to NSFileDesc describing 'file' types (see
  * INPUTS:
  *     const char *fn
  *         path name of the file
  * OUTPUTS:
  *     PRFileInfo *info
  *         Information about the given file is written into the file
  *         information object pointer to by 'info'.
  * RETURN: PRStatus
  *     PR_GetFileInfo returns PR_SUCCESS if file information is successfully
  *     obtained, otherwise it returns PR_FAILURE.
  ***************************************************************************
  */
 NSPR_API(PRStatus) PR_GetFileInfo(const char *fn, PRFileInfo *info);
 NSPR_API(PRStatus) PR_GetFileInfo64(const char *fn, PRFileInfo64 *info);
 #ifdef MOZ_UNICODE
 /*
  * EXPERIMENTAL: This function may be removed in a future release.
  */
 NSPR_API(PRStatus) PR_GetFileInfo64UTF16(const PRUnichar *fn, PRFileInfo64 *info);
 #endif /* MOZ_UNICODE */
 /*
  **************************************************************************
  * FUNCTION: PR_GetOpenFileInfo, PR_GetOpenFileInfo64
  * DESCRIPTION:
  *     Get information about an open file referred to by the
  *     given PRFileDesc object.
  * INPUTS:
  *     const PRFileDesc *fd
  *          A reference to a valid, open file.
  * OUTPUTS:
  *     Same as PR_GetFileInfo, PR_GetFileInfo64
  * RETURN: PRStatus
  *     PR_GetFileInfo returns PR_SUCCESS if file information is successfully
  *     obtained, otherwise it returns PR_FAILURE.
  ***************************************************************************
  */
 NSPR_API(PRStatus) PR_GetOpenFileInfo(PRFileDesc *fd, PRFileInfo *info);
 NSPR_API(PRStatus) PR_GetOpenFileInfo64(PRFileDesc *fd, PRFileInfo64 *info);
 /*
  **************************************************************************
  * FUNCTION: PR_Rename
  * DESCRIPTION:
  *     Rename a file from the old name 'from' to the new name 'to'.
  * INPUTS:
  *     const char *from
  *         The old name of the file to be renamed.
  *     const char *to
  *         The new name of the file.
  * OUTPUTS:
  *     None.
  * RETURN: PRStatus
  **************************************************************************
  */
 NSPR_API(PRStatus)    PR_Rename(const char *from, const char *to);
 /*
  *************************************************************************
  * FUNCTION: PR_Access
  * DESCRIPTION:
  *     Determine accessibility of a file.
  * INPUTS:
  *     const char *name
  *         path name of the file
  *     PRAccessHow how
  *         specifies which access permission to check for.
  *         It can be one of the following values:
  *             PR_ACCESS_READ_OK       Test for read permission
  *             PR_ACCESS_WRITE_OK      Test for write permission
  *             PR_ACCESS_EXISTS        Check existence of file
  * OUTPUTS:
  *     None.
  * RETURN: PRStatus
  *     PR_SUCCESS is returned if the requested access is permitted.
  *     Otherwise, PR_FAILURE is returned. Additional information
  *     regarding the reason for the failure may be retrieved from
  *     PR_GetError().
  *************************************************************************
  */
 typedef enum PRAccessHow {
     PR_ACCESS_EXISTS = 1,
     PR_ACCESS_WRITE_OK = 2,
     PR_ACCESS_READ_OK = 3
 } PRAccessHow;
 NSPR_API(PRStatus) PR_Access(const char *name, PRAccessHow how);
 /*
  *************************************************************************
  * FUNCTION: PR_Seek, PR_Seek64
  * DESCRIPTION:
  *     Moves read-write file offset
  * INPUTS:
  *     PRFileDesc *fd
  *         Pointer to a PRFileDesc object.
  *     PROffset32, PROffset64 offset
  *         Specifies a value, in bytes, that is used in conjunction
  *         with the 'whence' parameter to set the file pointer.  A
  *         negative value causes seeking in the reverse direction.
  *     PRSeekWhence whence
  *         Specifies how to interpret the 'offset' parameter in setting
  *         the file pointer associated with the 'fd' parameter.
  *         Values for the 'whence' parameter are:
  *             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.
  * OUTPUTS:
  *     None.
  * RETURN: PROffset32, PROffset64
  *     Upon successful completion, the resulting pointer location,
  *     measured in bytes from the beginning of the file, is returned.
  *     If the PR_Seek() function fails, the file offset remains
  *     unchanged, and the returned value is -1. The error code can
  *     then be retrieved via PR_GetError().
  *************************************************************************
  */
 NSPR_API(PROffset32) PR_Seek(PRFileDesc *fd, PROffset32 offset, PRSeekWhence whence);
 NSPR_API(PROffset64) PR_Seek64(PRFileDesc *fd, PROffset64 offset, PRSeekWhence whence);
 /*
  ************************************************************************
  * FUNCTION: PR_Available
  * DESCRIPTION:
  *     Determine the amount of data in bytes available for reading
  *     in the given file or socket.
  * INPUTS:
  *     PRFileDesc *fd
  *         Pointer to a PRFileDesc object that refers to a file or
  *         socket.
  * OUTPUTS:
  *     None
  * RETURN: PRInt32, PRInt64
  *     Upon successful completion, PR_Available returns the number of
  *     bytes beyond the current read pointer that is available for
  *     reading.  Otherwise, it returns a -1 and the reason for the
  *     failure can be retrieved via PR_GetError().
  ************************************************************************
  */
 NSPR_API(PRInt32) PR_Available(PRFileDesc *fd);
 NSPR_API(PRInt64) PR_Available64(PRFileDesc *fd);
 /*
  ************************************************************************
  * FUNCTION: PR_Sync
  * DESCRIPTION:
  *     Sync any buffered data for a fd to its backing device (disk).
  * INPUTS:
  *     PRFileDesc *fd
  *         Pointer to a PRFileDesc object that refers to a file or
  *         socket
  * OUTPUTS:
  *     None
  * RETURN: PRStatus
  *     PR_SUCCESS is returned if the requested access is permitted.
  *     Otherwise, PR_FAILURE is returned.
  ************************************************************************
  */
 NSPR_API(PRStatus)	PR_Sync(PRFileDesc *fd);
 /************************************************************************/
 struct PRDirEntry {
     const char *name;        /* name of entry, relative to directory name */
 };
 #ifdef MOZ_UNICODE
 struct PRDirEntryUTF16 {
     const PRUnichar *name;   /* name of entry in UTF16, relative to
                               * directory name */
 };
 #endif /* MOZ_UNICODE */
 #if !defined(NO_NSPR_10_SUPPORT)
 #define PR_DirName(dirEntry)	(dirEntry->name)
 #endif
 /*
  *************************************************************************
  * FUNCTION: PR_OpenDir
  * DESCRIPTION:
  *     Open the directory by the given name
  * INPUTS:
  *     const char *name
  *         path name of the directory to be opened
  * OUTPUTS:
  *     None
  * RETURN: PRDir *
  *     If the directory is sucessfully opened, a PRDir object is
  *     dynamically allocated and a pointer to it is returned.
  *     If the directory cannot be opened, a NULL pointer is returned.
  * MEMORY:
  *     Upon successful completion, the return value points to
  *     dynamically allocated memory.
  *************************************************************************
  */
 NSPR_API(PRDir*) PR_OpenDir(const char *name);
 #ifdef MOZ_UNICODE
 /*
  * EXPERIMENTAL: This function may be removed in a future release.
  */
 NSPR_API(PRDirUTF16*) PR_OpenDirUTF16(const PRUnichar *name);
 #endif /* MOZ_UNICODE */
 /*
  *************************************************************************
  * FUNCTION: PR_ReadDir
  * DESCRIPTION:
  * INPUTS:
  *     PRDir *dir
  *         pointer to a PRDir object that designates an open directory
  *     PRDirFlags flags
  *           PR_SKIP_NONE     Do not skip any files
  *           PR_SKIP_DOT      Skip the directory entry "." that
  *                            represents the current directory
  *           PR_SKIP_DOT_DOT  Skip the directory entry ".." that
  *                            represents the parent directory.
  *           PR_SKIP_BOTH     Skip both '.' and '..'
  *           PR_SKIP_HIDDEN   Skip hidden files
  * OUTPUTS:
  * RETURN: PRDirEntry*
  *     Returns a pointer to the next entry in the directory.  Returns
  *     a NULL pointer upon reaching the end of the directory or when an
  *     error occurs. The actual reason can be retrieved via PR_GetError().
  *************************************************************************
  */
 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;
 NSPR_API(PRDirEntry*) PR_ReadDir(PRDir *dir, PRDirFlags flags);
 #ifdef MOZ_UNICODE
 /*
  * EXPERIMENTAL: This function may be removed in a future release.
  */
 NSPR_API(PRDirEntryUTF16*) PR_ReadDirUTF16(PRDirUTF16 *dir, PRDirFlags flags);
 #endif /* MOZ_UNICODE */
 /*
  *************************************************************************
  * FUNCTION: PR_CloseDir
  * DESCRIPTION:
  *     Close the specified directory.
  * INPUTS:
  *     PRDir *dir
  *        The directory to be closed.
  * OUTPUTS:
  *     None
  * RETURN: PRStatus
  *        If successful, will return a status of PR_SUCCESS. Otherwise
  *        a value of PR_FAILURE. The reason for the failure may be re-
  *        trieved using PR_GetError().
  *************************************************************************
  */
 NSPR_API(PRStatus) PR_CloseDir(PRDir *dir);
 #ifdef MOZ_UNICODE
 /*
  * EXPERIMENTAL: This function may be removed in a future release.
  */
 NSPR_API(PRStatus) PR_CloseDirUTF16(PRDirUTF16 *dir);
 #endif /* MOZ_UNICODE */
 /*
  *************************************************************************
  * FUNCTION: PR_MkDir
  * DESCRIPTION:
  *     Create a new directory with the given name and access mode.
  * INPUTS:
  *     const char *name
  *        The name of the directory to be created. All the path components
  *        up to but not including the leaf component must already exist.
  *     PRIntn mode
  *        See 'mode' definiton in PR_Open().
  * OUTPUTS:
  *     None
  * RETURN: PRStatus
  *        If successful, will return a status of PR_SUCCESS. Otherwise
  *        a value of PR_FAILURE. The reason for the failure may be re-
  *        trieved using PR_GetError().
  *************************************************************************
  */
 NSPR_API(PRStatus) PR_MkDir(const char *name, PRIntn mode);
 /*
  *************************************************************************
  * FUNCTION: PR_MakeDir
  * DESCRIPTION:
  *     Create a new directory with the given name and access mode.
  *     PR_MakeDir has the same prototype as PR_MkDir but implements
  *     the specified access mode where possible.
  *************************************************************************
  */
 NSPR_API(PRStatus) PR_MakeDir(const char *name, PRIntn mode);
 /*
  *************************************************************************
  * FUNCTION: PR_RmDir
  * DESCRIPTION:
  *     Remove a directory by the given name.
  * INPUTS:
  *     const char *name
  *        The name of the directory to be removed. All the path components
  *        must already exist. Only the leaf component will be removed.
  * OUTPUTS:
  *     None
  * RETURN: PRStatus
  *        If successful, will return a status of PR_SUCCESS. Otherwise
  *        a value of PR_FAILURE. The reason for the failure may be re-
  *        trieved using PR_GetError().
  **************************************************************************
  */
 NSPR_API(PRStatus) PR_RmDir(const char *name);
 /*
  *************************************************************************
  * FUNCTION: PR_NewUDPSocket
  * DESCRIPTION:
  *     Create a new UDP socket.
  * INPUTS:
  *     None
  * OUTPUTS:
  *     None
  * RETURN: PRFileDesc*
  *     Upon successful completion, PR_NewUDPSocket returns a pointer
  *     to the PRFileDesc created for the newly opened UDP socket.
  *     Returns a NULL pointer if the creation of a new UDP socket failed.
  *
  **************************************************************************
  */
 NSPR_API(PRFileDesc*)    PR_NewUDPSocket(void);
 /*
  *************************************************************************
  * FUNCTION: PR_NewTCPSocket
  * DESCRIPTION:
  *     Create a new TCP socket.
  * INPUTS:
  *     None
  * OUTPUTS:
  *     None
  * RETURN: PRFileDesc*
  *     Upon successful completion, PR_NewTCPSocket returns a pointer
  *     to the PRFileDesc created for the newly opened TCP socket.
  *     Returns a NULL pointer if the creation of a new TCP socket failed.
  *
  **************************************************************************
  */
 NSPR_API(PRFileDesc*)    PR_NewTCPSocket(void);
 /*
  *************************************************************************
  * FUNCTION: PR_OpenUDPSocket
  * DESCRIPTION:
  *     Create a new UDP socket of the specified address family.
  * INPUTS:
  *     PRIntn af
  *       Address family
  * OUTPUTS:
  *     None
  * RETURN: PRFileDesc*
  *     Upon successful completion, PR_OpenUDPSocket returns a pointer
  *     to the PRFileDesc created for the newly opened UDP socket.
  *     Returns a NULL pointer if the creation of a new UDP socket failed.
  *
  **************************************************************************
  */
 NSPR_API(PRFileDesc*)    PR_OpenUDPSocket(PRIntn af);
 /*
  *************************************************************************
  * FUNCTION: PR_OpenTCPSocket
  * DESCRIPTION:
  *     Create a new TCP socket of the specified address family.
  * INPUTS:
  *     PRIntn af
  *       Address family
  * OUTPUTS:
  *     None
  * RETURN: PRFileDesc*
  *     Upon successful completion, PR_NewTCPSocket returns a pointer
  *     to the PRFileDesc created for the newly opened TCP socket.
  *     Returns a NULL pointer if the creation of a new TCP socket failed.
  *
  **************************************************************************
  */
 NSPR_API(PRFileDesc*)    PR_OpenTCPSocket(PRIntn af);
 /*
  *************************************************************************
  * FUNCTION: PR_Connect
  * DESCRIPTION:
  *     Initiate a connection on a socket.
  * INPUTS:
  *     PRFileDesc *fd
  *       Points to a PRFileDesc object representing a socket
  *     PRNetAddr *addr
  *       Specifies the address of the socket in its own communication
  *       space.
  *     PRIntervalTime timeout
  *       The function uses the lesser of the provided timeout and
  *       the OS's connect timeout.  In particular, if you specify
  *       PR_INTERVAL_NO_TIMEOUT as the timeout, the OS's connection
  *       time limit will be used.
  *
  * OUTPUTS:
  *     None
  * RETURN: PRStatus
  *     Upon successful completion of connection initiation, PR_Connect
  *     returns PR_SUCCESS.  Otherwise, it returns PR_FAILURE.  Further
  *     failure information can be obtained by calling PR_GetError().
  **************************************************************************
  */
 NSPR_API(PRStatus) PR_Connect(
     PRFileDesc *fd, const PRNetAddr *addr, PRIntervalTime timeout);
 /*
  *************************************************************************
  * FUNCTION: PR_ConnectContinue
  * DESCRIPTION:
  *     Continue a nonblocking connect.  After a nonblocking connect
  *     is initiated with PR_Connect() (which fails with
  *     PR_IN_PROGRESS_ERROR), one should call PR_Poll() on the socket,
  *     with the in_flags PR_POLL_WRITE | PR_POLL_EXCEPT.  When
  *     PR_Poll() returns, one calls PR_ConnectContinue() on the
  *     socket to determine whether the nonblocking connect has
  *     completed or is still in progress.  Repeat the PR_Poll(),
  *     PR_ConnectContinue() sequence until the nonblocking connect
  *     has completed.
  * INPUTS:
  *     PRFileDesc *fd
  *         the file descriptor representing a socket
  *     PRInt16 out_flags
  *         the out_flags field of the poll descriptor returned by
  *         PR_Poll()
  * RETURN: PRStatus
  *     If the nonblocking connect has successfully completed,
  *     PR_ConnectContinue returns PR_SUCCESS.  If PR_ConnectContinue()
  *     returns PR_FAILURE, call PR_GetError():
  *     - PR_IN_PROGRESS_ERROR: the nonblocking connect is still in
  *       progress and has not completed yet.  The caller should poll
  *       on the file descriptor for the in_flags
  *       PR_POLL_WRITE|PR_POLL_EXCEPT and retry PR_ConnectContinue
  *       later when PR_Poll() returns.
  *     - Other errors: the nonblocking connect has failed with this
  *       error code.
  */
 NSPR_API(PRStatus)    PR_ConnectContinue(PRFileDesc *fd, PRInt16 out_flags);
 /*
  *************************************************************************
  * THIS FUNCTION IS DEPRECATED.  USE PR_ConnectContinue INSTEAD.
  *
  * FUNCTION: PR_GetConnectStatus
  * DESCRIPTION:
  *     Get the completion status of a nonblocking connect.  After
  *     a nonblocking connect is initiated with PR_Connect() (which
  *     fails with PR_IN_PROGRESS_ERROR), one should call PR_Poll()
  *     on the socket, with the in_flags PR_POLL_WRITE | PR_POLL_EXCEPT.
  *     When PR_Poll() returns, one calls PR_GetConnectStatus on the
  *     PRPollDesc structure to determine whether the nonblocking
  *     connect has succeeded or failed.
  * INPUTS:
  *     const PRPollDesc *pd
  *         Pointer to a PRPollDesc whose fd member is the socket,
  *         and in_flags must contain PR_POLL_WRITE and PR_POLL_EXCEPT.
  *         PR_Poll() should have been called and set the out_flags.
  * RETURN: PRStatus
  *     If the nonblocking connect has successfully completed,
  *     PR_GetConnectStatus returns PR_SUCCESS.  If PR_GetConnectStatus()
  *     returns PR_FAILURE, call PR_GetError():
  *     - PR_IN_PROGRESS_ERROR: the nonblocking connect is still in
  *       progress and has not completed yet.
  *     - Other errors: the nonblocking connect has failed with this
  *       error code.
  */
 NSPR_API(PRStatus)    PR_GetConnectStatus(const PRPollDesc *pd);
 /*
  *************************************************************************
  * FUNCTION: PR_Accept
  * DESCRIPTION:
  *     Accept a connection on a socket.
  * INPUTS:
  *     PRFileDesc *fd
  *       Points to a PRFileDesc object representing the rendezvous socket
  *       on which the caller is willing to accept new connections.
  *     PRIntervalTime timeout
  *       Time limit for completion of the accept operation.
  * OUTPUTS:
  *     PRNetAddr *addr
  *       Returns the address of the connecting entity in its own
  *       communication space. It may be NULL.
  * RETURN: PRFileDesc*
  *     Upon successful acceptance of a connection, PR_Accept
  *     returns a valid file descriptor. Otherwise, it returns NULL.
  *     Further failure information can be obtained by calling PR_GetError().
  **************************************************************************
  */
 NSPR_API(PRFileDesc*) PR_Accept(
     PRFileDesc *fd, PRNetAddr *addr, PRIntervalTime timeout);
 /*
  *************************************************************************
  * FUNCTION: PR_Bind
  * DESCRIPTION:
  *    Bind an address to a socket.
  * INPUTS:
  *     PRFileDesc *fd
  *       Points to a PRFileDesc object representing a socket.
  *     PRNetAddr *addr
  *       Specifies the address to which the socket will be bound.
  * OUTPUTS:
  *     None
  * RETURN: PRStatus
  *     Upon successful binding of an address to a socket, PR_Bind
  *     returns PR_SUCCESS.  Otherwise, it returns PR_FAILURE.  Further
  *     failure information can be obtained by calling PR_GetError().
  **************************************************************************
  */
 NSPR_API(PRStatus) PR_Bind(PRFileDesc *fd, const PRNetAddr *addr);
 /*
  *************************************************************************
  * FUNCTION: PR_Listen
  * DESCRIPTION:
  *    Listen for connections on a socket.
  * INPUTS:
  *     PRFileDesc *fd
  *       Points to a PRFileDesc object representing a socket that will be
  *       used to listen for new connections.
  *     PRIntn backlog
  *       Specifies the maximum length of the queue of pending connections.
  * OUTPUTS:
  *     None
  * RETURN: PRStatus
  *     Upon successful completion of listen request, PR_Listen
  *     returns PR_SUCCESS.  Otherwise, it returns PR_FAILURE.  Further
  *     failure information can be obtained by calling PR_GetError().
  **************************************************************************
  */
 NSPR_API(PRStatus) PR_Listen(PRFileDesc *fd, PRIntn backlog);
 /*
  *************************************************************************
  * FUNCTION: PR_Shutdown
  * DESCRIPTION:
  *    Shut down part of a full-duplex connection on a socket.
  * INPUTS:
  *     PRFileDesc *fd
  *       Points to a PRFileDesc object representing a connected socket.
  *     PRIntn how
  *       Specifies the kind of disallowed operations on the socket.
  *           PR_SHUTDOWN_RCV - Further receives will be disallowed
  *           PR_SHUTDOWN_SEND - Further sends will be disallowed
  *           PR_SHUTDOWN_BOTH - Further sends and receives will be disallowed
  * OUTPUTS:
  *     None
  * RETURN: PRStatus
  *     Upon successful completion of shutdown request, PR_Shutdown
  *     returns PR_SUCCESS.  Otherwise, it returns PR_FAILURE.  Further
  *     failure information can be obtained by calling PR_GetError().
  **************************************************************************
  */
 typedef enum PRShutdownHow
 {
     PR_SHUTDOWN_RCV = 0,      /* disallow further receives */
     PR_SHUTDOWN_SEND = 1,     /* disallow further sends */
     PR_SHUTDOWN_BOTH = 2      /* disallow further receives and sends */
 } PRShutdownHow;
 NSPR_API(PRStatus)    PR_Shutdown(PRFileDesc *fd, PRShutdownHow how);
 /*
  *************************************************************************
  * FUNCTION: PR_Recv
  * DESCRIPTION:
  *    Receive a specified number of bytes from a connected socket.
  *     The operation will block until some positive number of bytes are
  *     transferred, a time out has occurred, or there is an error.
  *     No more than 'amount' bytes will be transferred.
  * INPUTS:
  *     PRFileDesc *fd
  *       points to a PRFileDesc object representing a socket.
  *     void *buf
  *       pointer to a buffer to hold the data received.
  *     PRInt32 amount
  *       the size of 'buf' (in bytes)
  *     PRIntn flags
  *       must be zero or PR_MSG_PEEK.
  *     PRIntervalTime timeout
  *       Time limit for completion of the receive operation.
  * OUTPUTS:
  *     None
  * RETURN: PRInt32
  *         a positive number indicates the number of bytes actually received.
  *         0 means the network connection is closed.
  *         -1 indicates a failure. The reason for the failure is obtained
  *         by calling PR_GetError().
  **************************************************************************
  */
 #define PR_MSG_PEEK 0x2
 NSPR_API(PRInt32)    PR_Recv(PRFileDesc *fd, void *buf, PRInt32 amount,
                 PRIntn flags, PRIntervalTime timeout);
 /*
  *************************************************************************
  * FUNCTION: PR_Send
  * DESCRIPTION:
  *    Send a specified number of bytes from a connected socket.
  *     The operation will block until all bytes are
  *     processed, a time out has occurred, or there is an error.
  * INPUTS:
  *     PRFileDesc *fd
  *       points to a PRFileDesc object representing a socket.
  *     void *buf
  *       pointer to a buffer from where the data is sent.
  *     PRInt32 amount
  *       the size of 'buf' (in bytes)
  *     PRIntn flags
  *        (OBSOLETE - must always be zero)
  *     PRIntervalTime timeout
  *       Time limit for completion of the send operation.
  * OUTPUTS:
  *     None
  * RETURN: PRInt32
  *     A positive number indicates the number of bytes successfully processed.
  *     This number must always equal 'amount'. A -1 is an indication that the
  *     operation failed. The reason for the failure is obtained by calling
  *     PR_GetError().
  **************************************************************************
  */
 NSPR_API(PRInt32)    PR_Send(PRFileDesc *fd, const void *buf, PRInt32 amount,
                                 PRIntn flags, PRIntervalTime timeout);
 /*
  *************************************************************************
  * FUNCTION: PR_RecvFrom
  * DESCRIPTION:
  *     Receive up to a specified number of bytes from socket which may
  *     or may not be connected.
  *     The operation will block until one or more bytes are
  *     transferred, a time out has occurred, or there is an error.
  *     No more than 'amount' bytes will be transferred.
  * INPUTS:
  *     PRFileDesc *fd
  *       points to a PRFileDesc object representing a socket.
  *     void *buf
  *       pointer to a buffer to hold the data received.
  *     PRInt32 amount
  *       the size of 'buf' (in bytes)
  *     PRIntn flags
  *        (OBSOLETE - must always be zero)
  *     PRNetAddr *addr
  *       Specifies the address of the sending peer. It may be NULL.
  *     PRIntervalTime timeout
  *       Time limit for completion of the receive operation.
  * OUTPUTS:
  *     None
  * RETURN: PRInt32
  *         a positive number indicates the number of bytes actually received.
  *         0 means the network connection is closed.
  *         -1 indicates a failure. The reason for the failure is obtained
  *         by calling PR_GetError().
  **************************************************************************
  */
 NSPR_API(PRInt32) PR_RecvFrom(
     PRFileDesc *fd, void *buf, PRInt32 amount, PRIntn flags,
     PRNetAddr *addr, PRIntervalTime timeout);
 /*
  *************************************************************************
  * FUNCTION: PR_SendTo
  * DESCRIPTION:
  *    Send a specified number of bytes from an unconnected socket.
  *    The operation will block until all bytes are
  *    sent, a time out has occurred, or there is an error.
  * INPUTS:
  *     PRFileDesc *fd
  *       points to a PRFileDesc object representing an unconnected socket.
  *     void *buf
  *       pointer to a buffer from where the data is sent.
  *     PRInt32 amount
  *       the size of 'buf' (in bytes)
  *     PRIntn flags
  *        (OBSOLETE - must always be zero)
  *     PRNetAddr *addr
  *       Specifies the address of the peer.
 .*     PRIntervalTime timeout
  *       Time limit for completion of the send operation.
  * OUTPUTS:
  *     None
  * RETURN: PRInt32
  *     A positive number indicates the number of bytes successfully sent.
  *     -1 indicates a failure. The reason for the failure is obtained
  *     by calling PR_GetError().
  **************************************************************************
  */
 NSPR_API(PRInt32) PR_SendTo(
     PRFileDesc *fd, const void *buf, PRInt32 amount, PRIntn flags,
     const PRNetAddr *addr, PRIntervalTime timeout);
 /*
 *************************************************************************
 ** FUNCTION: PR_TransmitFile
 ** DESCRIPTION:
 **    Transmitfile sends a complete file (sourceFile) across a socket
 **    (networkSocket).  If headers is non-NULL, the headers will be sent across
 **    the socket prior to sending the file.
 **
 **    Optionally, the PR_TRANSMITFILE_CLOSE_SOCKET flag may be passed to
 **    transmitfile.  This flag specifies that transmitfile should close the
 **    socket after sending the data.
 **
 ** INPUTS:
 **    PRFileDesc *networkSocket
 **        The socket to send data over
 **    PRFileDesc *sourceFile
 **        The file to send
 **    const void *headers
 **        A pointer to headers to be sent before sending data
 **    PRInt32       hlen
 **        length of header buffers in bytes.
 **    PRTransmitFileFlags       flags
 **        If the flags indicate that the connection should be closed,
 **        it will be done immediately after transferring the file, unless
 **        the operation is unsuccessful.
 .*     PRIntervalTime timeout
  *        Time limit for completion of the transmit operation.
 **
 ** RETURNS:
 **    Returns the number of bytes written or -1 if the operation failed.
 **    If an error occurs while sending the file, the PR_TRANSMITFILE_CLOSE_
 **    SOCKET flag is ignored. The reason for the failure is obtained
 **    by calling PR_GetError().
 **************************************************************************
 */
 NSPR_API(PRInt32) PR_TransmitFile(
     PRFileDesc *networkSocket, PRFileDesc *sourceFile,
     const void *headers, PRInt32 hlen, PRTransmitFileFlags flags,
     PRIntervalTime timeout);
 /*
 *************************************************************************
 ** FUNCTION: PR_SendFile
 ** DESCRIPTION:
 **    PR_SendFile sends data from a file (sendData->fd) across a socket
 **    (networkSocket).  If specified, a header and/or trailer buffer are sent
 **	  before and after the file, respectively. The file offset, number of bytes
 ** 	  of file data to send, the header and trailer buffers are specified in the
 **	  sendData argument.
 **
 **    Optionally, if the PR_TRANSMITFILE_CLOSE_SOCKET flag is passed, the
 **    socket is closed after successfully sending the data.
 **
 ** INPUTS:
 **    PRFileDesc *networkSocket
 **        The socket to send data over
 **    PRSendFileData *sendData
 **        Contains the FD, file offset and length, header and trailer
 **		  buffer specifications.
 **    PRTransmitFileFlags       flags
 **        If the flags indicate that the connection should be closed,
 **        it will be done immediately after transferring the file, unless
 **        the operation is unsuccessful.
 .*     PRIntervalTime timeout
  *        Time limit for completion of the send operation.
 **
 ** RETURNS:
 **    Returns the number of bytes written or -1 if the operation failed.
 **    If an error occurs while sending the file, the PR_TRANSMITFILE_CLOSE_
 **    SOCKET flag is ignored. The reason for the failure is obtained
 **    by calling PR_GetError().
 **************************************************************************
 */
 struct PRSendFileData {
 	PRFileDesc	*fd;			/* file to send							*/
 	PRUint32	file_offset;	/* file offset							*/
 	PRSize		file_nbytes;	/* number of bytes of file data to send	*/
 								/* if 0, send data from file_offset to	*/
 								/* end-of-file.							*/
 	const void	*header;		/* header buffer						*/
 	PRInt32		hlen;			/* header len							*/
 	const void	*trailer;		/* trailer buffer						*/
 	PRInt32		tlen;			/* trailer len							*/
 };
 NSPR_API(PRInt32) PR_SendFile(
     PRFileDesc *networkSocket, PRSendFileData *sendData,
 	PRTransmitFileFlags flags, PRIntervalTime timeout);
 /*
 *************************************************************************
 ** FUNCTION: PR_AcceptRead
 ** DESCRIPTION:
 **    AcceptRead accepts a new connection, returns the newly created
 **    socket's descriptor and also returns the connecting peer's address.
 **    AcceptRead, as its name suggests, also receives the first block of data
 **    sent by the peer.
 **
 ** INPUTS:
 **    PRFileDesc *listenSock
 **        A socket descriptor that has been called with the PR_Listen()
 **        function, also known as the rendezvous socket.
 **    void *buf
 **        A pointer to a buffer to receive data sent by the client.  This
 **        buffer must be large enough to receive <amount> bytes of data
 **        and two PRNetAddr structures, plus an extra 32 bytes. See:
 **        PR_ACCEPT_READ_BUF_OVERHEAD.
 **    PRInt32 amount
 **        The number of bytes of client data to receive.  Does not include
 **        the size of the PRNetAddr structures.  If 0, no data will be read
 **        from the client.
 **    PRIntervalTime timeout
 **        The timeout interval only applies to the read portion of the
 **        operation.  PR_AcceptRead will block indefinitely until the
 **        connection is accepted; the read will timeout after the timeout
 **        interval elapses.
 ** OUTPUTS:
 **    PRFileDesc **acceptedSock
 **        The file descriptor for the newly connected socket.  This parameter
 **        will only be valid if the function return does not indicate failure.
 **    PRNetAddr  **peerAddr,
 **        The address of the remote socket.  This parameter will only be
 **        valid if the function return does not indicate failure.  The
 **        returned address is not guaranteed to be properly aligned.
 **
 ** RETURNS:
 **     The number of bytes read from the client or -1 on failure.  The reason
 **     for the failure is obtained by calling PR_GetError().
 **************************************************************************
 **/
 /* define buffer overhead constant. Add this value to the user's
 ** data length when allocating a buffer to accept data.
 **    Example:
 **    #define USER_DATA_SIZE 10
 **    char buf[USER_DATA_SIZE + PR_ACCEPT_READ_BUF_OVERHEAD];
 **    bytesRead = PR_AcceptRead( s, fd, &a, &p, USER_DATA_SIZE, ...);
 */
 #define PR_ACCEPT_READ_BUF_OVERHEAD (32+(2*sizeof(PRNetAddr)))
 NSPR_API(PRInt32) PR_AcceptRead(
     PRFileDesc *listenSock, PRFileDesc **acceptedSock,
     PRNetAddr **peerAddr, void *buf, PRInt32 amount, PRIntervalTime timeout);
 /*
 *************************************************************************
 ** FUNCTION: PR_NewTCPSocketPair
 ** DESCRIPTION:
 **    Create a new TCP socket pair. The returned descriptors can be used
 **    interchangeably; they are interconnected full-duplex descriptors: data
 **    written to one can be read from the other and vice-versa.
 **
 ** INPUTS:
 **    None
 ** OUTPUTS:
 **    PRFileDesc *fds[2]
 **        The file descriptor pair for the newly created TCP sockets.
 ** RETURN: PRStatus
 **     Upon successful completion of TCP socket pair, PR_NewTCPSocketPair
 **     returns PR_SUCCESS.  Otherwise, it returns PR_FAILURE.  Further
 **     failure information can be obtained by calling PR_GetError().
 ** XXX can we implement this on windoze and mac?
 **************************************************************************
 **/
 NSPR_API(PRStatus) PR_NewTCPSocketPair(PRFileDesc *fds[2]);
 /*
 *************************************************************************
 ** FUNCTION: PR_GetSockName
 ** DESCRIPTION:
 **    Get socket name.  Return the network address for this socket.
 **
 ** INPUTS:
 **     PRFileDesc *fd
 **       Points to a PRFileDesc object representing the socket.
 ** OUTPUTS:
 **     PRNetAddr *addr
 **       Returns the address of the socket in its own communication space.
 ** RETURN: PRStatus
 **     Upon successful completion, PR_GetSockName returns PR_SUCCESS.
 **     Otherwise, it returns PR_FAILURE.  Further failure information can
 **     be obtained by calling PR_GetError().
 **************************************************************************
 **/
 NSPR_API(PRStatus)	PR_GetSockName(PRFileDesc *fd, PRNetAddr *addr);
 /*
 *************************************************************************
 ** FUNCTION: PR_GetPeerName
 ** DESCRIPTION:
 **    Get name of the connected peer.  Return the network address for the
 **    connected peer socket.
 **
 ** INPUTS:
 **     PRFileDesc *fd
 **       Points to a PRFileDesc object representing the connected peer.
 ** OUTPUTS:
 **     PRNetAddr *addr
 **       Returns the address of the connected peer in its own communication
 **       space.
 ** RETURN: PRStatus
 **     Upon successful completion, PR_GetPeerName returns PR_SUCCESS.
 **     Otherwise, it returns PR_FAILURE.  Further failure information can
 **     be obtained by calling PR_GetError().
 **************************************************************************
 **/
 NSPR_API(PRStatus)	PR_GetPeerName(PRFileDesc *fd, PRNetAddr *addr);
 NSPR_API(PRStatus)	PR_GetSocketOption(
     PRFileDesc *fd, PRSocketOptionData *data);
 NSPR_API(PRStatus)	PR_SetSocketOption(
     PRFileDesc *fd, const PRSocketOptionData *data);
 /*
  *********************************************************************
  *
  * File descriptor inheritance
  *
  *********************************************************************
  */
 /*
  ************************************************************************
  * FUNCTION: PR_SetFDInheritable
  * DESCRIPTION:
  *    Set the inheritance attribute of a file descriptor.
  *
  * INPUTS:
  *     PRFileDesc *fd
  *       Points to a PRFileDesc object.
  *     PRBool inheritable
  *       If PR_TRUE, the file descriptor fd is set to be inheritable
  *       by a child process.  If PR_FALSE, the file descriptor is set
  *       to be not inheritable by a child process.
  * RETURN: PRStatus
  *     Upon successful completion, PR_SetFDInheritable returns PR_SUCCESS.
  *     Otherwise, it returns PR_FAILURE.  Further failure information can
  *     be obtained by calling PR_GetError().
  *************************************************************************
  */
 NSPR_API(PRStatus) PR_SetFDInheritable(
     PRFileDesc *fd,
     PRBool inheritable);
 /*
  ************************************************************************
  * FUNCTION: PR_GetInheritedFD
  * DESCRIPTION:
  *    Get an inherited file descriptor with the specified name.
  *
  * INPUTS:
  *     const char *name
  *       The name of the inherited file descriptor.
  * RETURN: PRFileDesc *
  *     Upon successful completion, PR_GetInheritedFD returns the
  *     inherited file descriptor with the specified name.  Otherwise,
  *     it returns NULL.  Further failure information can be obtained
  *     by calling PR_GetError().
  *************************************************************************
  */
 NSPR_API(PRFileDesc *) PR_GetInheritedFD(const char *name);
 /*
  *********************************************************************
  *
  * Memory-mapped files
  *
  *********************************************************************
  */
 typedef struct PRFileMap PRFileMap;
 /*
  * protection options for read and write accesses of a file mapping
  */
 typedef enum PRFileMapProtect {
     PR_PROT_READONLY,     /* read only */
     PR_PROT_READWRITE,    /* readable, and write is shared */
     PR_PROT_WRITECOPY     /* readable, and write is private (copy-on-write) */
 } PRFileMapProtect;
 NSPR_API(PRFileMap *) PR_CreateFileMap(
     PRFileDesc *fd,
     PRInt64 size,
     PRFileMapProtect prot);
 /*
  * return the alignment (in bytes) of the offset argument to PR_MemMap
  */
 NSPR_API(PRInt32) PR_GetMemMapAlignment(void);
 NSPR_API(void *) PR_MemMap(
     PRFileMap *fmap,
     PROffset64 offset,  /* must be aligned and sized according to the
                          * return value of PR_GetMemMapAlignment() */
     PRUint32 len);
 NSPR_API(PRStatus) PR_MemUnmap(void *addr, PRUint32 len);
 NSPR_API(PRStatus) PR_CloseFileMap(PRFileMap *fmap);
 /*
  * Synchronously flush the given memory-mapped address range of the given open
  * file to disk. The function does not return until all modified data have
  * been written to disk.
  *
  * On some platforms, the function will call PR_Sync(fd) internally if it is
  * necessary for flushing modified data to disk synchronously.
  */
 NSPR_API(PRStatus) PR_SyncMemMap(
     PRFileDesc *fd,
     void *addr,
     PRUint32 len);
 /*
  ******************************************************************
  *
  * Interprocess communication
  *
  ******************************************************************
  */
 /*
  * Creates an anonymous pipe and returns file descriptors for the
  * read and write ends of the pipe.
  */
 NSPR_API(PRStatus) PR_CreatePipe(
     PRFileDesc **readPipe,
     PRFileDesc **writePipe
 );
 /************************************************************************/
 /************** The following definitions are for poll ******************/
 /************************************************************************/
 struct PRPollDesc {
     PRFileDesc* fd;
     PRInt16 in_flags;
     PRInt16 out_flags;
 };
 /*
 ** Bit values for PRPollDesc.in_flags or PRPollDesc.out_flags. Binary-or
 ** these together to produce the desired poll request.
 */
 #if defined(_PR_POLL_BACKCOMPAT)
 #include <poll.h>
 #define PR_POLL_READ    POLLIN
 #define PR_POLL_WRITE   POLLOUT
 #define PR_POLL_EXCEPT  POLLPRI
 #define PR_POLL_ERR     POLLERR     /* only in out_flags */
 #define PR_POLL_NVAL    POLLNVAL    /* only in out_flags when fd is bad */
 #define PR_POLL_HUP     POLLHUP     /* only in out_flags */
 #else  /* _PR_POLL_BACKCOMPAT */
 #define PR_POLL_READ    0x1
 #define PR_POLL_WRITE   0x2
 #define PR_POLL_EXCEPT  0x4
 #define PR_POLL_ERR     0x8         /* only in out_flags */
 #define PR_POLL_NVAL    0x10        /* only in out_flags when fd is bad */
 #define PR_POLL_HUP     0x20        /* only in out_flags */
 #endif  /* _PR_POLL_BACKCOMPAT */
 /*
 *************************************************************************
 ** FUNCTION:    PR_Poll
 ** DESCRIPTION:
 **
 ** The call returns as soon as I/O is ready on one or more of the underlying
 ** socket objects. A count of the number of ready descriptors is
 ** returned unless a timeout occurs in which case zero is returned.
 **
 ** PRPollDesc.fd should be set to a pointer to a PRFileDesc object
 ** representing a socket. This field can be set to NULL to indicate to
 ** PR_Poll that this PRFileDesc object should be ignored.
 ** PRPollDesc.in_flags should be set to the desired request
 ** (read/write/except or some combination). Upon successful return from
 ** this call PRPollDesc.out_flags will be set to indicate what kind of
 ** i/o can be performed on the respective descriptor. PR_Poll() uses the
 ** out_flags fields as scratch variables during the call. If PR_Poll()
 ** returns 0 or -1, the out_flags fields do not contain meaningful values
 ** and must not be used.
 **
 ** INPUTS:
 **      PRPollDesc *pds         A pointer to an array of PRPollDesc
 **
 **      PRIntn npds             The number of elements in the array
 **                              If this argument is zero PR_Poll is
 **                              equivalent to a PR_Sleep(timeout).
 **
 **      PRIntervalTime timeout  Amount of time the call will block waiting
 **                              for I/O to become ready. If this time expires
 **                              w/o any I/O becoming ready, the result will
 **                              be zero.
 **
 ** OUTPUTS:    None
 ** RETURN:
 **      PRInt32                 Number of PRPollDesc's with events or zero
 **                              if the function timed out or -1 on failure.
 **                              The reason for the failure is obtained by
 **                              calling PR_GetError().
 **************************************************************************
 */
 NSPR_API(PRInt32) PR_Poll(
     PRPollDesc *pds, PRIntn npds, PRIntervalTime timeout);
 /*
 **************************************************************************
 **
 ** Pollable events
 **
 ** 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 can't
 ** 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
 ** 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.
 **
 ** A new pollable event is created by a PR_NewPollableEvent
 ** call and is initially in the unset state.
 **
 ** PR_WaitForPollableEvent blocks the calling thread until
 ** the pollable event is set, and then it atomically unsets
 ** the pollable event before it returns.
 **
 ** To set a pollable event, call PR_SetPollableEvent.
 **
 ** One can call PR_Poll with the PR_POLL_READ flag on a pollable
 ** event.  When the pollable event is set, PR_Poll returns with
 ** the PR_POLL_READ flag set in the out_flags.
 **
 ** To close a pollable event, call PR_DestroyPollableEvent
 ** (not PR_Close).
 **
 **************************************************************************
 */
 NSPR_API(PRFileDesc *) PR_NewPollableEvent(void);
 NSPR_API(PRStatus) PR_DestroyPollableEvent(PRFileDesc *event);
 NSPR_API(PRStatus) PR_SetPollableEvent(PRFileDesc *event);
 NSPR_API(PRStatus) PR_WaitForPollableEvent(PRFileDesc *event);
 PR_END_EXTERN_C
 #endif /* prio_h___ */

The Tor Browser / annotate

nsprpub/pr/include/prio.h@6474c204b198 (annotated)

nsprpub/pr/include/prio.h