home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / nspr30-e.zip / nspr30-e / include / prio.h < prev    next >
C/C++ Source or Header  |  1998-11-02  |  66KB  |  1,686 lines
  1. /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
  2. /*
  3.  * The contents of this file are subject to the Netscape Public License
  4.  * Version 1.0 (the "NPL"); you may not use this file except in
  5.  * compliance with the NPL.  You may obtain a copy of the NPL at
  6.  * http://www.mozilla.org/NPL/
  7.  * 
  8.  * Software distributed under the NPL is distributed on an "AS IS" basis,
  9.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL
  10.  * for the specific language governing rights and limitations under the
  11.  * NPL.
  12.  * 
  13.  * The Initial Developer of this code under the NPL is Netscape
  14.  * Communications Corporation.  Portions created by Netscape are
  15.  * Copyright (C) 1998 Netscape Communications Corporation.  All Rights
  16.  * Reserved.
  17.  */
  18.  
  19. /*
  20.  * File:     prio.h
  21.  *
  22.  * Description:    PR i/o related stuff, such as file system access, file
  23.  *         i/o, socket i/o, etc.
  24.  */
  25.  
  26. #ifndef prio_h___
  27. #define prio_h___
  28.  
  29. #include "prlong.h"
  30. #include "prtime.h"
  31. #include "prinrval.h"
  32. #include "prinet.h"
  33.  
  34. PR_BEGIN_EXTERN_C
  35.  
  36. /* Typedefs */
  37. typedef struct PRDir            PRDir;
  38. typedef struct PRDirEntry       PRDirEntry;
  39. typedef struct PRFileDesc       PRFileDesc;
  40. typedef struct PRFileInfo       PRFileInfo;
  41. typedef struct PRFileInfo64     PRFileInfo64;
  42. typedef union  PRNetAddr        PRNetAddr;
  43. typedef struct PRIOMethods      PRIOMethods;
  44. typedef struct PRPollDesc       PRPollDesc;
  45. typedef struct PRFilePrivate    PRFilePrivate;
  46.  
  47. /*
  48. ***************************************************************************
  49. ** The file descriptor.
  50. ** This is the primary structure to represent any active open socket,
  51. ** whether it be a normal file or a network connection. Such objects
  52. ** are stackable (or layerable). Each layer may have its own set of
  53. ** method pointers and context private to that layer. All each layer
  54. ** knows about its neighbors is how to get to their method table.
  55. ***************************************************************************
  56. */
  57.  
  58. typedef PRIntn PRDescIdentity;          /* see: Layering file descriptors */
  59.  
  60. struct PRFileDesc {
  61.     const PRIOMethods *methods;         /* the I/O methods table */
  62.     PRFilePrivate *secret;              /* layer dependent data */
  63.     PRFileDesc *lower, *higher;         /* pointers to adjacent layers */
  64.     void (PR_CALLBACK *dtor)(PRFileDesc *fd);
  65.                                         /* A destructor function for layer */
  66.     PRDescIdentity identity;            /* Identity of this particular layer  */
  67. };
  68.  
  69. /*
  70. ***************************************************************************
  71. ** PRTransmitFileFlags
  72. **
  73. ** Flags for PR_TransmitFile.  Pass PR_TRANSMITFILE_CLOSE_SOCKET to
  74. ** PR_TransmitFile if the connection should be closed after the file
  75. ** is transmitted.
  76. ***************************************************************************
  77. */
  78. typedef enum PRTransmitFileFlags {
  79.     PR_TRANSMITFILE_KEEP_OPEN = 0,    /* socket is left open after file
  80.                                        * is transmitted. */
  81.     PR_TRANSMITFILE_CLOSE_SOCKET = 1  /* socket is closed after file
  82.                                        * is transmitted. */
  83. } PRTransmitFileFlags;
  84.  
  85. /*
  86. **************************************************************************
  87. ** Macros for PRNetAddr
  88. **
  89. ** Address families: PR_AF_INET, PR_AF_INET6, PR_AF_LOCAL
  90. ** IP addresses: PR_INADDR_ANY, PR_INADDR_LOOPBACK, PR_INADDR_BROADCAST
  91. **************************************************************************
  92. */
  93.  
  94. #ifdef WIN32
  95.  
  96. #define PR_AF_INET 2
  97. #define PR_AF_LOCAL 1
  98. #define PR_INADDR_ANY (unsigned long)0x00000000
  99. #define PR_INADDR_LOOPBACK 0x7f000001
  100. #define PR_INADDR_BROADCAST (unsigned long)0xffffffff
  101.  
  102. #else /* WIN32 */
  103.  
  104. #define PR_AF_INET AF_INET
  105. #define PR_AF_LOCAL AF_UNIX
  106. #ifdef AF_INET6
  107. #define PR_AF_INET6 AF_INET6
  108. #endif
  109. #define PR_INADDR_ANY INADDR_ANY
  110. #define PR_INADDR_LOOPBACK INADDR_LOOPBACK
  111. #define PR_INADDR_BROADCAST INADDR_BROADCAST
  112.  
  113. #endif /* WIN32 */
  114.  
  115. /*
  116. **************************************************************************
  117. ** A network address
  118. **
  119. ** Only Internet Protocol (IPv4 and IPv6) addresses are supported.
  120. ** The address family must always represent IPv4 (AF_INET, probably == 2)
  121. ** or IPv6 (AF_INET6).
  122. **************************************************************************
  123. *************************************************************************/
  124. #if defined(_PR_INET6)
  125.  
  126. #if !defined(AF_INET6)
  127. #error "AF_INET6 is not defined"
  128. #endif
  129.  
  130. typedef struct in6_addr PRIPv6Addr;
  131.  
  132. #endif /* defined(_PR_INET6) */
  133.  
  134. union PRNetAddr {
  135.     struct {
  136.         PRUint16 family;                /* address family (0x00ff maskable) */
  137.         char data[14];                  /* raw address data */
  138.     } raw;
  139.     struct {
  140.         PRUint16 family;                /* address family (AF_INET) */
  141.         PRUint16 port;                  /* port number */
  142.         PRUint32 ip;                    /* The actual 32 bits of address */
  143.         char pad[8];
  144.     } inet;
  145. #if defined(_PR_INET6)
  146.     struct {
  147.         PRUint16 family;                /* address family (AF_INET6) */
  148.         PRUint16 port;                  /* port number */
  149.         PRUint32 flowinfo;              /* routing information */
  150.         PRIPv6Addr ip;                  /* the actual 128 bits of address */
  151.     } ipv6;
  152. #endif /* defined(_PR_INET6) */
  153. #if defined(XP_UNIX)
  154.     struct {                            /* Unix domain socket address */
  155.         PRUint16 family;                /* address family (AF_UNIX) */
  156.         char path[104];                 /* null-terminated pathname */
  157.     } local;
  158. #endif
  159. };
  160.  
  161. /*
  162. ** The PR_NETADDR_SIZE macro can only be called on a PRNetAddr union
  163. ** whose 'family' field is set.  It returns the size of the union
  164. ** member corresponding to the specified address family.
  165. */
  166.  
  167. #if defined(_PR_INET6)
  168.  
  169. #define PR_NETADDR_SIZE(_addr) PR_NetAddrSize(_addr)
  170.  
  171. #else
  172.  
  173. #if defined(XP_UNIX)
  174. #define PR_NETADDR_SIZE(_addr) \
  175.         ((_addr)->raw.family == AF_UNIX \
  176.         ? sizeof((_addr)->local) \
  177.         : sizeof((_addr)->inet))
  178. #else
  179. #define PR_NETADDR_SIZE(_addr) sizeof((_addr)->inet)
  180. #endif /* defined(XP_UNIX) */
  181.  
  182. #endif /* defined(_PR_INET6) */
  183.  
  184. /*
  185. ***************************************************************************
  186. ** PRSockOption
  187. **
  188. ** The file descriptors can have predefined options set after they file
  189. ** descriptor is created to change their behavior. Only the options in
  190. ** the following enumeration are supported.
  191. ***************************************************************************
  192. */
  193. typedef enum PRSockOption
  194. {
  195.     PR_SockOpt_Nonblocking,     /* nonblocking io */
  196.     PR_SockOpt_Linger,          /* linger on close if data present */
  197.     PR_SockOpt_Reuseaddr,       /* allow local address reuse */
  198.     PR_SockOpt_Keepalive,       /* keep connections alive */
  199.     PR_SockOpt_RecvBufferSize,  /* send buffer size */
  200.     PR_SockOpt_SendBufferSize,  /* receive buffer size */
  201.  
  202.     PR_SockOpt_IpTimeToLive,    /* time to live */
  203.     PR_SockOpt_IpTypeOfService, /* type of service and precedence */
  204.  
  205.     PR_SockOpt_AddMember,       /* add an IP group membership */
  206.     PR_SockOpt_DropMember,      /* drop an IP group membership */
  207.     PR_SockOpt_McastInterface,  /* multicast interface address */
  208.     PR_SockOpt_McastTimeToLive, /* multicast timetolive */
  209.     PR_SockOpt_McastLoopback,   /* multicast loopback */
  210.  
  211.     PR_SockOpt_NoDelay,         /* don't delay send to coalesce packets */
  212.     PR_SockOpt_MaxSegment,      /* maximum segment size */
  213.     PR_SockOpt_Last
  214. } PRSockOption;
  215.  
  216. typedef struct PRLinger {
  217.     PRBool polarity;            /* Polarity of the option's setting */
  218.     PRIntervalTime linger;        /* Time to linger before closing */
  219. } PRLinger;
  220.  
  221. typedef struct PRMcastRequest {
  222.     PRNetAddr mcaddr;            /* IP multicast address of group */
  223.     PRNetAddr ifaddr;            /* local IP address of interface */
  224. } PRMcastRequest;
  225.  
  226. typedef struct PRSocketOptionData
  227. {
  228.     PRSockOption option;
  229.     union
  230.     {
  231.         PRUintn ip_ttl;             /* IP time to live */
  232.         PRUintn mcast_ttl;          /* IP multicast time to live */
  233.         PRUintn tos;                /* IP type of service and precedence */
  234.         PRBool non_blocking;        /* Non-blocking (network) I/O */
  235.         PRBool reuse_addr;          /* Allow local address reuse */
  236.         PRBool keep_alive;          /* Keep connections alive */
  237.         PRBool mcast_loopback;      /* IP multicast loopback */
  238.         PRBool no_delay;            /* Don't delay send to coalesce packets */
  239.         PRSize max_segment;         /* Maximum segment size */
  240.         PRSize recv_buffer_size;    /* Receive buffer size */
  241.         PRSize send_buffer_size;    /* Send buffer size */
  242.         PRLinger linger;            /* Time to linger on close if data present */
  243.         PRMcastRequest add_member;  /* add an IP group membership */
  244.         PRMcastRequest drop_member; /* Drop an IP group membership */
  245.         PRNetAddr mcast_if;         /* multicast interface address */
  246.     } value;
  247. } PRSocketOptionData;
  248.  
  249. /*
  250. ***************************************************************************
  251. ** PRIOVec
  252. **
  253. ** The I/O vector is used by the write vector method to describe the areas
  254. ** that are affected by the ouput operation.
  255. ***************************************************************************
  256. */
  257. typedef struct PRIOVec {
  258.     char *iov_base;
  259.     int iov_len;
  260. } PRIOVec;
  261.  
  262. /*
  263. ***************************************************************************
  264. ** Discover what type of socket is being described by the file descriptor.
  265. ***************************************************************************
  266. */
  267. typedef enum PRDescType
  268. {
  269.     PR_DESC_FILE = 1,
  270.     PR_DESC_SOCKET_TCP = 2,
  271.     PR_DESC_SOCKET_UDP = 3,
  272.     PR_DESC_LAYERED = 4
  273. } PRDescType;
  274.  
  275. typedef enum PRSeekWhence {
  276.     PR_SEEK_SET = 0,
  277.     PR_SEEK_CUR = 1,
  278.     PR_SEEK_END = 2
  279. } PRSeekWhence;
  280.  
  281. PR_EXTERN(PRDescType) PR_GetDescType(PRFileDesc *file);
  282.  
  283. /*
  284. ***************************************************************************
  285. ** PRIOMethods
  286. **
  287. ** The I/O methods table provides procedural access to the functions of
  288. ** the file descriptor. It is the responsibility of a layer implementor
  289. ** to provide suitable functions at every entry point. If a layer provides
  290. ** no functionality, it should call the next lower(higher) function of the
  291. ** same name (e.g., return fd->lower->method->close(fd->lower));
  292. **
  293. ** Not all functions are implemented for all types of files. In cases where
  294. ** that is true, the function will return a error indication with an error
  295. ** code of PR_INVALID_METHOD_ERROR.
  296. ***************************************************************************
  297. */
  298.  
  299. typedef PRStatus (PR_CALLBACK *PRCloseFN)(PRFileDesc *fd);
  300. typedef PRInt32 (PR_CALLBACK *PRReadFN)(PRFileDesc *fd, void *buf, PRInt32 amount);
  301. typedef PRInt32 (PR_CALLBACK *PRWriteFN)(PRFileDesc *fd, const void *buf, PRInt32 amount);
  302. typedef PRInt32 (PR_CALLBACK *PRAvailableFN)(PRFileDesc *fd);
  303. typedef PRInt64 (PR_CALLBACK *PRAvailable64FN)(PRFileDesc *fd);
  304. typedef PRStatus (PR_CALLBACK *PRFsyncFN)(PRFileDesc *fd);
  305. typedef PRInt32 (PR_CALLBACK *PRSeekFN)(PRFileDesc *fd, PRInt32 offset, PRSeekWhence how);
  306. typedef PRInt64 (PR_CALLBACK *PRSeek64FN)(PRFileDesc *fd, PRInt64 offset, PRSeekWhence how);
  307. typedef PRStatus (PR_CALLBACK *PRFileInfoFN)(PRFileDesc *fd, PRFileInfo *info);
  308. typedef PRStatus (PR_CALLBACK *PRFileInfo64FN)(PRFileDesc *fd, PRFileInfo64 *info);
  309. typedef PRInt32 (PR_CALLBACK *PRWritevFN)(
  310.     PRFileDesc *fd, PRIOVec *iov, PRInt32 size, PRIntervalTime timeout);
  311. typedef PRStatus (PR_CALLBACK *PRConnectFN)(
  312.     PRFileDesc *fd, const PRNetAddr *addr, PRIntervalTime timeout);
  313. typedef PRFileDesc* (PR_CALLBACK *PRAcceptFN) (
  314.     PRFileDesc *fd, PRNetAddr *addr, PRIntervalTime timeout);
  315. typedef PRStatus (PR_CALLBACK *PRBindFN)(PRFileDesc *fd, const PRNetAddr *addr);
  316. typedef PRStatus (PR_CALLBACK *PRListenFN)(PRFileDesc *fd, PRIntn backlog);
  317. typedef PRStatus (PR_CALLBACK *PRShutdownFN)(PRFileDesc *fd, PRIntn how);
  318. typedef PRInt32 (PR_CALLBACK *PRRecvFN)(
  319.     PRFileDesc *fd, void *buf, PRInt32 amount,
  320.     PRIntn flags, PRIntervalTime timeout);
  321. typedef PRInt32 (PR_CALLBACK *PRSendFN) (
  322.     PRFileDesc *fd, const void *buf, PRInt32 amount,
  323.     PRIntn flags, PRIntervalTime timeout);
  324. typedef PRInt32 (PR_CALLBACK *PRRecvfromFN)(
  325.     PRFileDesc *fd, void *buf, PRInt32 amount,
  326.     PRIntn flags, PRNetAddr *addr, PRIntervalTime timeout);
  327. typedef PRInt32 (PR_CALLBACK *PRSendtoFN)(
  328.     PRFileDesc *fd, const void *buf, PRInt32 amount,
  329.     PRIntn flags, const PRNetAddr *addr, PRIntervalTime timeout);
  330. typedef PRInt16 (PR_CALLBACK *PRPollFN)(
  331.     PRFileDesc *fd, PRInt16 in_flags, PRInt16 *out_flags);
  332. typedef PRInt32 (PR_CALLBACK *PRAcceptreadFN)(
  333.     PRFileDesc *sd, PRFileDesc **nd, PRNetAddr **raddr,
  334.     void *buf, PRInt32 amount, PRIntervalTime t);
  335. typedef PRInt32 (PR_CALLBACK *PRTransmitfileFN)(
  336.      PRFileDesc *sd, PRFileDesc *fd, const void *headers,
  337.      PRInt32 hlen, PRTransmitFileFlags flags, PRIntervalTime t);
  338. typedef PRStatus (PR_CALLBACK *PRGetsocknameFN)(PRFileDesc *fd, PRNetAddr *addr);
  339. typedef PRStatus (PR_CALLBACK *PRGetpeernameFN)(PRFileDesc *fd, PRNetAddr *addr);
  340. typedef PRStatus (PR_CALLBACK *PRGetsockoptFN)(  /* OBSOLETE */
  341.     PRFileDesc *fd, PRSockOption optname, void* optval, PRInt32 *optlen);
  342. typedef PRStatus (PR_CALLBACK *PRSetsockoptFN)(  /* OBSOLETE */
  343.     PRFileDesc *fd, PRSockOption optname, const void* optval, PRInt32 optlen);
  344. typedef PRStatus (PR_CALLBACK *PRGetsocketoptionFN)(
  345.     PRFileDesc *fd, PRSocketOptionData *data);
  346. typedef PRStatus (PR_CALLBACK *PRSetsocketoptionFN)(
  347.     PRFileDesc *fd, const PRSocketOptionData *data);
  348.  
  349. struct PRIOMethods {
  350.     PRDescType file_type;           /* Type of file represented (tos)           */
  351.     PRCloseFN close;                /* close file and destroy descriptor        */
  352.     PRReadFN read;                  /* read up to specified bytes into buffer   */
  353.     PRWriteFN write;                /* write specified bytes from buffer        */
  354.     PRAvailableFN available;        /* determine number of bytes available      */
  355.     PRAvailable64FN available64;    /*          ditto, 64 bit                   */
  356.     PRFsyncFN fsync;                /* flush all buffers to permanent store     */
  357.     PRSeekFN seek;                  /* position the file to the desired place   */
  358.     PRSeek64FN seek64;              /*           ditto, 64 bit                  */
  359.     PRFileInfoFN fileInfo;          /* Get information about an open file       */
  360.     PRFileInfo64FN fileInfo64;      /*           ditto, 64 bit                  */
  361.     PRWritevFN writev;              /* Write segments as described by iovector  */
  362.     PRConnectFN connect;            /* Connect to the specified (net) address   */
  363.     PRAcceptFN accept;              /* Accept a connection for a (net) peer     */
  364.     PRBindFN bind;                  /* Associate a (net) address with the fd    */
  365.     PRListenFN listen;              /* Prepare to listen for (net) connections  */
  366.     PRShutdownFN shutdown;          /* Shutdown a (net) connection              */
  367.     PRRecvFN recv;                  /* Solicit up the the specified bytes       */
  368.     PRSendFN send;                  /* Send all the bytes specified             */
  369.     PRRecvfromFN recvfrom;          /* Solicit (net) bytes and report source    */
  370.     PRSendtoFN sendto;              /* Send bytes to (net) address specified    */
  371.     PRPollFN poll;                  /* Test the fd to see if it is ready        */
  372.     PRAcceptreadFN acceptread;      /* Accept and read on a new (net) fd        */
  373.     PRTransmitfileFN transmitfile;  /* Transmit at entire file                  */
  374.     PRGetsocknameFN getsockname;    /* Get (net) address associated with fd     */
  375.     PRGetpeernameFN getpeername;    /* Get peer's (net) address                 */
  376.     PRGetsockoptFN getsockopt;      /*             OBSOLETE                     */
  377.     PRSetsockoptFN setsockopt;      /*             OBSOLETE                     */
  378.     PRGetsocketoptionFN getsocketoption;
  379.                                     /* Get current setting of specified option  */
  380.     PRSetsocketoptionFN setsocketoption;
  381.                                     /* Set value of specified option            */
  382. };
  383.  
  384. /*
  385.  **************************************************************************
  386.  * FUNCTION: PR_GetSpecialFD
  387.  * DESCRIPTION: Get the file descriptor that represents the standard input,
  388.  *              output, or error stream.
  389.  * INPUTS:
  390.  *     PRSpecialFD id
  391.  *         A value indicating the type of stream desired:
  392.  *             PR_StandardInput: standard input
  393.  *             PR_StandardOuput: standard output
  394.  *             PR_StandardError: standard error
  395.  * OUTPUTS: none
  396.  * RETURNS: PRFileDesc *
  397.  *     If the argument is valid, PR_GetSpecialFD returns a file descriptor
  398.  *     that represents the corresponding standard I/O stream.  Otherwise,
  399.  *     PR_GetSpecialFD returns NULL and sets error PR_INVALID_ARGUMENT_ERROR.
  400.  **************************************************************************
  401.  */
  402.  
  403. typedef enum PRSpecialFD
  404. {
  405.     PR_StandardInput,          /* standard input */
  406.     PR_StandardOutput,         /* standard output */
  407.     PR_StandardError           /* standard error */
  408. } PRSpecialFD;
  409.  
  410. PR_EXTERN(PRFileDesc*) PR_GetSpecialFD(PRSpecialFD id);
  411.  
  412. #define PR_STDIN    PR_GetSpecialFD(PR_StandardInput)
  413. #define PR_STDOUT    PR_GetSpecialFD(PR_StandardOutput)
  414. #define PR_STDERR    PR_GetSpecialFD(PR_StandardError)
  415.  
  416. /*
  417.  **************************************************************************
  418.  * Layering file descriptors
  419.  *
  420.  * File descriptors may be layered. Each layer has it's own identity.
  421.  * Identities are allocated by the runtime and are to be associated
  422.  * (by the layer implementor) with all layers that are of that type.
  423.  * It is then possible to scan the chain of layers and find a layer
  424.  * that one recongizes and therefore predict that it will implement
  425.  * a desired protocol.
  426.  *
  427.  * There are three well-known identities:
  428.  *      PR_INVALID_IO_LAYER => an invalid layer identity, for error return
  429.  *      PR_TOP_IO_LAYER     => the identity of the top of the stack
  430.  *      PR_NSPR_IO_LAYER    => the identity used by NSPR proper
  431.  * PR_TOP_IO_LAYER may be used as a shorthand for identifying the topmost
  432.  * layer of an existing stack. Ie., the following two constructs are
  433.  * equivalent.
  434.  *
  435.  *      rv = PR_PushIOLayer(stack, PR_TOP_IO_LAYER, my_layer);
  436.  *      rv = PR_PushIOLayer(stack, PR_GetLayersIdentity(stack), my_layer)
  437.  *
  438.  * A string may be associated with the creation of the identity. It
  439.  * will be copied by the runtime. If queried the runtime will return
  440.  * a reference to that copied string (not yet another copy). There
  441.  * is no facility for deleting an identity.
  442.  **************************************************************************
  443.  */
  444.  
  445. #define PR_INVALID_IO_LAYER (PRDescIdentity)-1
  446. #define PR_TOP_IO_LAYER (PRDescIdentity)-2
  447. #define PR_NSPR_IO_LAYER (PRDescIdentity)0
  448.  
  449. PR_EXTERN(PRDescIdentity) PR_GetUniqueIdentity(const char *layer_name);
  450. PR_EXTERN(const char*) PR_GetNameForIdentity(PRDescIdentity ident);
  451. PR_EXTERN(PRDescIdentity) PR_GetLayersIdentity(PRFileDesc* fd);
  452. PR_EXTERN(PRFileDesc*) PR_GetIdentitiesLayer(PRFileDesc* stack, PRDescIdentity id);
  453.  
  454. /*
  455.  **************************************************************************
  456.  * PR_GetDefaultIOMethods: Accessing the default methods table.
  457.  * You may get a pointer to the default methods table by calling this function.
  458.  * You may then select any elements from that table with which to build your
  459.  * layer's methods table. You may NOT modify the table directly.
  460.  **************************************************************************
  461.  */
  462. PR_EXTERN(const PRIOMethods *) PR_GetDefaultIOMethods(void);
  463.  
  464. /*
  465.  **************************************************************************
  466.  * Creating a layer
  467.  *
  468.  * A new layer may be allocated by calling PR_CreateIOLayerStub(). The
  469.  * file descriptor returned will contain the pointer to the methods table
  470.  * provided. The runtime will not modify the table nor test its correctness.
  471.  **************************************************************************
  472.  */
  473. PR_EXTERN(PRFileDesc*) PR_CreateIOLayerStub(
  474.     PRDescIdentity ident, const PRIOMethods *methods);
  475.  
  476. /*
  477.  **************************************************************************
  478.  * Pushing a layer
  479.  *
  480.  * A file descriptor (perhaps allocated using PR_CreateIOLayerStub()) may
  481.  * be pushed into an existing stack of file descriptors at any point the
  482.  * caller deems appropriate. The new layer will be inserted into the stack
  483.  * just above the layer with the indicated identity.
  484.  *
  485.  * Note: Even if the identity parameter indicates the top-most layer of
  486.  * the stack, the value of the file descriptor describing the original
  487.  * stack will not change.
  488.  **************************************************************************
  489.  */
  490. PR_EXTERN(PRStatus) PR_PushIOLayer(
  491.     PRFileDesc *stack, PRDescIdentity id, PRFileDesc *layer);
  492.  
  493. /*
  494.  **************************************************************************
  495.  * Popping a layer
  496.  *
  497.  * A layer may be popped from a stack by indicating the identity of the
  498.  * layer to be removed. If found, a pointer to the removed object will
  499.  * be returned to the caller. The object then becomes the responsibility
  500.  * of the caller.
  501.  *
  502.  * Note: Even if the identity indicates the top layer of the stack, the
  503.  * reference returned will not be the file descriptor for the stack and
  504.  * that file descriptor will remain valid.
  505.  **************************************************************************
  506.  */
  507. PR_EXTERN(PRFileDesc*) PR_PopIOLayer(PRFileDesc *stack, PRDescIdentity id);
  508.  
  509. /*
  510.  **************************************************************************
  511.  * FUNCTION:    PR_Open
  512.  * DESCRIPTION:    Open a file for reading, writing, or both.
  513.  * INPUTS:
  514.  *     const char *name
  515.  *         The path name of the file to be opened
  516.  *     PRIntn flags
  517.  *         The file status flags.
  518.  *         It is a bitwise OR of the following bit flags (only one of
  519.  *         the first three flags below may be used):
  520.  *        PR_RDONLY        Open for reading only.
  521.  *        PR_WRONLY        Open for writing only.
  522.  *        PR_RDWR          Open for reading and writing.
  523.  *        PR_CREATE_FILE   If the file does not exist, the file is created
  524.  *                              If the file exists, this flag has no effect.
  525.  *      PR_SYNC          If set, each write will wait for both the file data
  526.  *                              and file status to be physically updated.
  527.  *        PR_APPEND        The file pointer is set to the end of
  528.  *                              the file prior to each write.
  529.  *        PR_TRUNCATE      If the file exists, its length is truncated to 0.
  530.  *
  531.  *     PRIntn mode
  532.  *         The access permission bits of the file mode, if the file is
  533.  *         created when PR_CREATE_FILE is on.
  534.  * OUTPUTS:    None
  535.  * RETURNS:    PRFileDesc *
  536.  *     If the file is successfully opened,
  537.  *     returns a pointer to the PRFileDesc
  538.  *     created for the newly opened file.
  539.  *     Returns a NULL pointer if the open
  540.  *     failed.
  541.  * SIDE EFFECTS:
  542.  * RESTRICTIONS:
  543.  * MEMORY:
  544.  *     The return value, if not NULL, points to a dynamically allocated
  545.  *     PRFileDesc object.
  546.  * ALGORITHM:
  547.  **************************************************************************
  548.  */
  549.  
  550. PR_EXTERN(PRFileDesc*) PR_Open(const char *name, PRIntn flags, PRIntn mode);
  551. /* Open flags */
  552. #define PR_RDONLY       0x01
  553. #define PR_WRONLY       0x02
  554. #define PR_RDWR         0x04
  555. #define PR_CREATE_FILE  0x08
  556. #define PR_APPEND       0x10
  557. #define PR_TRUNCATE     0x20
  558. #define PR_SYNC         0x40
  559.  
  560. /*
  561. ** File modes ....
  562. **
  563. ** CAVEAT: 'mode' is currently only applicable on UNIX platforms. We are
  564. ** still in the process of seeing how these apply to other file systems.
  565. **
  566. **   00400   Read by owner.
  567. **   00200   Write by owner.
  568. **   00100   Execute (search if a directory) by owner.
  569. **   00040   Read by group.
  570. **   00020   Write by group.
  571. **   00010   Execute by group.
  572. **   00004   Read by others.
  573. **   00002   Write by others
  574. **   00001   Execute by others.
  575. **
  576. */
  577.  
  578. /*
  579.  **************************************************************************
  580.  * FUNCTION: PR_Close
  581.  * DESCRIPTION:
  582.  *     Close a file or socket.
  583.  * INPUTS:
  584.  *     PRFileDesc *fd
  585.  *         a pointer to a PRFileDesc.
  586.  * OUTPUTS:
  587.  *     None.
  588.  * RETURN:
  589.  *     PRStatus
  590.  * SIDE EFFECTS:
  591.  * RESTRICTIONS:
  592.  *     None.
  593.  * MEMORY:
  594.  *     The dynamic memory pointed to by the argument fd is freed.
  595.  **************************************************************************
  596.  */
  597.  
  598. PR_EXTERN(PRStatus)    PR_Close(PRFileDesc *fd);
  599.  
  600. /*
  601.  **************************************************************************
  602.  * FUNCTION: PR_Read
  603.  * DESCRIPTION:
  604.  *     Read bytes from a file or socket.
  605.  *     The operation will block until either an end of stream indication is
  606.  *     encountered, some positive number of bytes are transferred, or there
  607.  *     is an error. No more than 'amount' bytes will be transferred.
  608.  * INPUTS:
  609.  *     PRFileDesc *fd
  610.  *         pointer to the PRFileDesc object for the file or socket
  611.  *     void *buf
  612.  *         pointer to a buffer to hold the data read in.
  613.  *     PRInt32 amount
  614.  *         the size of 'buf' (in bytes)
  615.  * OUTPUTS:
  616.  * RETURN:
  617.  *     PRInt32
  618.  *         a positive number indicates the number of bytes actually read in.
  619.  *         0 means end of file is reached or the network connection is closed.
  620.  *         -1 indicates a failure. The reason for the failure is obtained
  621.  *         by calling PR_GetError().
  622.  * SIDE EFFECTS:
  623.  *     data is written into the buffer pointed to by 'buf'.
  624.  * RESTRICTIONS:
  625.  *     None.
  626.  * MEMORY:
  627.  *     N/A
  628.  * ALGORITHM:
  629.  *     N/A
  630.  **************************************************************************
  631.  */
  632.  
  633. PR_EXTERN(PRInt32) PR_Read(PRFileDesc *fd, void *buf, PRInt32 amount);
  634.  
  635. /*
  636.  ***************************************************************************
  637.  * FUNCTION: PR_Write
  638.  * DESCRIPTION:
  639.  *     Write a specified number of bytes to a file or socket.  The thread
  640.  *     invoking this function blocks until all the data is written.
  641.  * INPUTS:
  642.  *     PRFileDesc *fd
  643.  *         pointer to a PRFileDesc object that refers to a file or socket
  644.  *     const void *buf
  645.  *         pointer to the buffer holding the data
  646.  *     PRInt32 amount
  647.  *         amount of data in bytes to be written from the buffer
  648.  * OUTPUTS:
  649.  *     None.
  650.  * RETURN: PRInt32
  651.  *     A positive number indicates the number of bytes successfully written.
  652.  *     A -1 is an indication that the operation failed. The reason
  653.  *     for the failure is obtained by calling PR_GetError().
  654.  ***************************************************************************
  655.  */
  656.  
  657. PR_EXTERN(PRInt32) PR_Write(PRFileDesc *fd,const void *buf,PRInt32 amount);
  658.  
  659. /*
  660.  ***************************************************************************
  661.  * FUNCTION: PR_Writev
  662.  * DESCRIPTION:
  663.  *     Write data to a socket.  The data is organized in a PRIOVec array. The
  664.  *     operation will block until all the data is written or the operation
  665.  *     fails.
  666.  * INPUTS:
  667.  *     PRFileDesc *fd
  668.  *         Pointer that points to a PRFileDesc object for a socket.
  669.  *     PRIOVec *iov
  670.  *         An array of PRIOVec.  PRIOVec is a struct with the following
  671.  *         two fields:
  672.  *             char *iov_base;
  673.  *             int iov_len;
  674.  *     PRInt32 iov_size
  675.  *         Number of elements in the iov array. The value of this
  676.  *         argument must not be greater than PR_MAX_IOVECTOR_SIZE.
  677.  *         If it is, the method will fail (PR_BUFFER_OVERFLOW_ERROR).
  678.  *     PRIntervalTime timeout
  679.  *       Time limit for completion of the entire write operation.
  680.  * OUTPUTS:
  681.  *     None
  682.  * RETURN:
  683.  *     A positive number indicates the number of bytes successfully written.
  684.  *     A -1 is an indication that the operation failed. The reason
  685.  *     for the failure is obtained by calling PR_GetError().
  686.  ***************************************************************************
  687.  */
  688.  
  689. #define PR_MAX_IOVECTOR_SIZE 16   /* 'size' must be <= */
  690.  
  691. PR_EXTERN(PRInt32) PR_Writev(
  692.     PRFileDesc *fd, PRIOVec *iov, PRInt32 size, PRIntervalTime timeout);
  693.  
  694. /*
  695.  ***************************************************************************
  696.  * FUNCTION: PR_Delete
  697.  * DESCRIPTION:
  698.  *     Delete a file from the filesystem. The operation may fail if the
  699.  *     file is open.
  700.  * INPUTS:
  701.  *     const char *name
  702.  *         Path name of the file to be deleted.
  703.  * OUTPUTS:
  704.  *     None.
  705.  * RETURN: PRStatus
  706.  *     The function returns PR_SUCCESS if the file is successfully
  707.  *     deleted, otherwise it returns PR_FAILURE.
  708.  ***************************************************************************
  709.  */
  710.  
  711. PR_EXTERN(PRStatus) PR_Delete(const char *name);
  712.  
  713. /**************************************************************************/
  714.  
  715. typedef enum PRFileType
  716. {
  717.     PR_FILE_FILE = 1,
  718.     PR_FILE_DIRECTORY = 2,
  719.     PR_FILE_OTHER = 3
  720. } PRFileType;
  721.  
  722. struct PRFileInfo {
  723.     PRFileType type;        /* Type of file */
  724.     PRUint32 size;          /* Size, in bytes, of file's contents */
  725.     PRTime creationTime;    /* Creation time per definition of PRTime */
  726.     PRTime modifyTime;      /* Last modification time per definition of PRTime */
  727. };
  728.  
  729. struct PRFileInfo64 {
  730.     PRFileType type;        /* Type of file */
  731.     PRUint64 size;          /* Size, in bytes, of file's contents */
  732.     PRTime creationTime;    /* Creation time per definition of PRTime */
  733.     PRTime modifyTime;      /* Last modification time per definition of PRTime */
  734. };
  735.  
  736. /****************************************************************************
  737.  * FUNCTION: PR_GetFileInfo, PR_GetFileInfo64
  738.  * DESCRIPTION:
  739.  *     Get the information about the file with the given path name. This is
  740.  *     applicable only to NSFileDesc describing 'file' types (see
  741.  * INPUTS:
  742.  *     const char *fn
  743.  *         path name of the file
  744.  * OUTPUTS:
  745.  *     PRFileInfo *info
  746.  *         Information about the given file is written into the file
  747.  *         information object pointer to by 'info'.
  748.  * RETURN: PRStatus
  749.  *     PR_GetFileInfo returns PR_SUCCESS if file information is successfully
  750.  *     obtained, otherwise it returns PR_FAILURE.
  751.  ***************************************************************************
  752.  */
  753.  
  754. PR_EXTERN(PRStatus) PR_GetFileInfo(const char *fn, PRFileInfo *info);
  755. PR_EXTERN(PRStatus) PR_GetFileInfo64(const char *fn, PRFileInfo64 *info);
  756.  
  757. /*
  758.  **************************************************************************
  759.  * FUNCTION: PR_GetOpenFileInfo, PR_GetOpenFileInfo64
  760.  * DESCRIPTION:
  761.  *     Get information about an open file referred to by the
  762.  *     given PRFileDesc object.
  763.  * INPUTS:
  764.  *     const PRFileDesc *fd
  765.  *          A reference to a valid, open file.
  766.  * OUTPUTS:
  767.  *     Same as PR_GetFileInfo, PR_GetFileInfo64
  768.  * RETURN: PRStatus
  769.  *     PR_GetFileInfo returns PR_SUCCESS if file information is successfully
  770.  *     obtained, otherwise it returns PR_FAILURE.
  771.  ***************************************************************************
  772.  */
  773.  
  774. PR_EXTERN(PRStatus) PR_GetOpenFileInfo(PRFileDesc *fd, PRFileInfo *info);
  775. PR_EXTERN(PRStatus) PR_GetOpenFileInfo64(PRFileDesc *fd, PRFileInfo64 *info);
  776.  
  777. /*
  778.  **************************************************************************
  779.  * FUNCTION: PR_Rename
  780.  * DESCRIPTION:
  781.  *     Rename a file from the old name 'from' to the new name 'to'.
  782.  * INPUTS:
  783.  *     const char *from
  784.  *         The old name of the file to be renamed.
  785.  *     const char *to
  786.  *         The new name of the file.
  787.  * OUTPUTS:
  788.  *     None.
  789.  * RETURN: PRStatus
  790.  **************************************************************************
  791.  */
  792.  
  793. PR_EXTERN(PRStatus)    PR_Rename(const char *from, const char *to);
  794.  
  795. /*
  796.  *************************************************************************
  797.  * FUNCTION: PR_Access
  798.  * DESCRIPTION:
  799.  *     Determine accessibility of a file.
  800.  * INPUTS:
  801.  *     const char *name
  802.  *         path name of the file
  803.  *     PRAccessHow how
  804.  *         specifies which access permission to check for.
  805.  *         It can be one of the following values:
  806.  *             PR_ACCESS_READ_OK       Test for read permission
  807.  *             PR_ACCESS_WRITE_OK      Test for write permission
  808.  *             PR_ACCESS_EXISTS        Check existence of file
  809.  * OUTPUTS:
  810.  *     None.
  811.  * RETURN: PRStatus
  812.  *     PR_SUCCESS is returned if the requested access is permitted.
  813.  *     Otherwise, PR_FAILURE is returned. Additional information
  814.  *     regarding the reason for the failure may be retrieved from
  815.  *     PR_GetError().
  816.  *************************************************************************
  817.  */
  818.  
  819. typedef enum PRAccessHow {
  820.     PR_ACCESS_EXISTS = 1,
  821.     PR_ACCESS_WRITE_OK = 2,
  822.     PR_ACCESS_READ_OK = 3
  823. } PRAccessHow;
  824.  
  825. PR_EXTERN(PRStatus) PR_Access(const char *name, PRAccessHow how);
  826.  
  827. /*
  828.  *************************************************************************
  829.  * FUNCTION: PR_Seek, PR_Seek64
  830.  * DESCRIPTION:
  831.  *     Moves read-write file offset
  832.  * INPUTS:
  833.  *     PRFileDesc *fd
  834.  *         Pointer to a PRFileDesc object.
  835.  *     PRInt32, PRInt64 offset
  836.  *         Specifies a value, in bytes, that is used in conjunction
  837.  *         with the 'whence' parameter to set the file pointer.  A
  838.  *         negative value causes seeking in the reverse direction.
  839.  *     PRSeekWhence whence
  840.  *         Specifies how to interpret the 'offset' parameter in setting
  841.  *         the file pointer associated with the 'fd' parameter.
  842.  *         Values for the 'whence' parameter are:
  843.  *             PR_SEEK_SET  Sets the file pointer to the value of the
  844.  *                          'offset' parameter
  845.  *             PR_SEEK_CUR  Sets the file pointer to its current location
  846.  *                          plus the value of the offset parameter.
  847.  *             PR_SEEK_END  Sets the file pointer to the size of the
  848.  *                          file plus the value of the offset parameter.
  849.  * OUTPUTS:
  850.  *     None.
  851.  * RETURN: PRInt32, PRInt64
  852.  *     Upon successful completion, the resulting pointer location,
  853.  *     measured in bytes from the beginning of the file, is returned.
  854.  *     If the PR_Seek() function fails, the file offset remains
  855.  *     unchanged, and the returned value is -1. The error code can
  856.  *     then be retrieved via PR_GetError().
  857.  *************************************************************************
  858.  */
  859.  
  860. PR_EXTERN(PRInt32) PR_Seek(PRFileDesc *fd, PRInt32 offset, PRSeekWhence whence);
  861. PR_EXTERN(PRInt64) PR_Seek64(PRFileDesc *fd, PRInt64 offset, PRSeekWhence whence);
  862.  
  863. /*
  864.  ************************************************************************
  865.  * FUNCTION: PR_Available
  866.  * DESCRIPTION:
  867.  *     Determine the amount of data in bytes available for reading
  868.  *     in the given file or socket.
  869.  * INPUTS:
  870.  *     PRFileDesc *fd
  871.  *         Pointer to a PRFileDesc object that refers to a file or
  872.  *         socket.
  873.  * OUTPUTS:
  874.  *     None
  875.  * RETURN: PRInt32, PRInt64
  876.  *     Upon successful completion, PR_Available returns the number of
  877.  *     bytes beyond the current read pointer that is available for
  878.  *     reading.  Otherwise, it returns a -1 and the reason for the
  879.  *     failure can be retrieved via PR_GetError().
  880.  ************************************************************************
  881.  */
  882.  
  883. PR_EXTERN(PRInt32) PR_Available(PRFileDesc *fd);
  884. PR_EXTERN(PRInt64) PR_Available64(PRFileDesc *fd);
  885.  
  886. /*
  887.  ************************************************************************
  888.  * FUNCTION: PR_Sync
  889.  * DESCRIPTION:
  890.  *     Sync any buffered data for a fd to its backing device (disk).
  891.  * INPUTS:
  892.  *     PRFileDesc *fd
  893.  *         Pointer to a PRFileDesc object that refers to a file or
  894.  *         socket
  895.  * OUTPUTS:
  896.  *     None
  897.  * RETURN: PRStatus
  898.  *     PR_SUCCESS is returned if the requested access is permitted.
  899.  *     Otherwise, PR_FAILURE is returned.
  900.  ************************************************************************
  901.  */
  902.  
  903. PR_EXTERN(PRStatus)    PR_Sync(PRFileDesc *fd);
  904.  
  905. /************************************************************************/
  906.  
  907. struct PRDirEntry {
  908.     const char *name;        /* name of entry, relative to directory name */
  909. };
  910.  
  911. #if !defined(NO_NSPR_10_SUPPORT)
  912. #define PR_DirName(dirEntry)    (dirEntry->name)
  913. #endif
  914.  
  915. /*
  916.  *************************************************************************
  917.  * FUNCTION: PR_OpenDir
  918.  * DESCRIPTION:
  919.  *     Open the directory by the given name
  920.  * INPUTS:
  921.  *     const char *name
  922.  *         path name of the directory to be opened
  923.  * OUTPUTS:
  924.  *     None
  925.  * RETURN: PRDir *
  926.  *     If the directory is sucessfully opened, a PRDir object is
  927.  *     dynamically allocated and a pointer to it is returned.
  928.  *     If the directory cannot be opened, a NULL pointer is returned.
  929.  * MEMORY:
  930.  *     Upon successful completion, the return value points to
  931.  *     dynamically allocated memory.
  932.  *************************************************************************
  933.  */
  934.  
  935. PR_EXTERN(PRDir*) PR_OpenDir(const char *name);
  936.  
  937. /*
  938.  *************************************************************************
  939.  * FUNCTION: PR_ReadDir
  940.  * DESCRIPTION:
  941.  * INPUTS:
  942.  *     PRDir *dir
  943.  *         pointer to a PRDir object that designates an open directory
  944.  *     PRDirFlags flags
  945.  *           PR_SKIP_NONE     Do not skip any files
  946.  *           PR_SKIP_DOT      Skip the directory entry "." that
  947.  *                            represents the current directory
  948.  *           PR_SKIP_DOT_DOT  Skip the directory entry ".." that
  949.  *                            represents the parent directory.
  950.  *           PR_SKIP_BOTH     Skip both '.' and '..'
  951.  *           PR_SKIP_HIDDEN   Skip hidden files
  952.  * OUTPUTS:
  953.  * RETURN: PRDirEntry*
  954.  *     Returns a pointer to the next entry in the directory.  Returns
  955.  *     a NULL pointer upon reaching the end of the directory or when an
  956.  *     error occurs. The actual reason can be retrieved via PR_GetError().
  957.  *************************************************************************
  958.  */
  959.  
  960. typedef enum PRDirFlags {
  961.     PR_SKIP_NONE = 0x0,
  962.     PR_SKIP_DOT = 0x1,
  963.     PR_SKIP_DOT_DOT = 0x2,
  964.     PR_SKIP_BOTH = 0x3,
  965.     PR_SKIP_HIDDEN = 0x4
  966. } PRDirFlags;
  967.  
  968. PR_EXTERN(PRDirEntry*) PR_ReadDir(PRDir *dir, PRDirFlags flags);
  969.  
  970. /*
  971.  *************************************************************************
  972.  * FUNCTION: PR_CloseDir
  973.  * DESCRIPTION:
  974.  *     Close the specified directory.
  975.  * INPUTS:
  976.  *     PRDir *dir
  977.  *        The directory to be closed.
  978.  * OUTPUTS:
  979.  *     None
  980.  * RETURN: PRStatus
  981.  *        If successful, will return a status of PR_SUCCESS. Otherwise
  982.  *        a value of PR_FAILURE. The reason for the failure may be re-
  983.  *        trieved using PR_GetError().
  984.  *************************************************************************
  985.  */
  986.  
  987. PR_EXTERN(PRStatus) PR_CloseDir(PRDir *dir);
  988.  
  989. /*
  990.  *************************************************************************
  991.  * FUNCTION: PR_MkDir
  992.  * DESCRIPTION:
  993.  *     Create a new directory with the given name and access mode.
  994.  * INPUTS:
  995.  *     const char *name
  996.  *        The name of the directory to be created. All the path components
  997.  *        up to but not including the leaf component must already exist.
  998.  *     PRIntn mode
  999.  *        See 'mode' definiton in PR_Open().
  1000.  * OUTPUTS:
  1001.  *     None
  1002.  * RETURN: PRStatus
  1003.  *        If successful, will return a status of PR_SUCCESS. Otherwise
  1004.  *        a value of PR_FAILURE. The reason for the failure may be re-
  1005.  *        trieved using PR_GetError().
  1006.  *************************************************************************
  1007.  */
  1008.  
  1009. PR_EXTERN(PRStatus) PR_MkDir(const char *name, PRIntn mode);
  1010.  
  1011. /*
  1012.  *************************************************************************
  1013.  * FUNCTION: PR_RmDir
  1014.  * DESCRIPTION:
  1015.  *     Remove a directory by the given name.
  1016.  * INPUTS:
  1017.  *     const char *name
  1018.  *        The name of the directory to be removed. All the path components
  1019.  *        must already exist. Only the leaf component will be removed.
  1020.  * OUTPUTS:
  1021.  *     None
  1022.  * RETURN: PRStatus
  1023.  *        If successful, will return a status of PR_SUCCESS. Otherwise
  1024.  *        a value of PR_FAILURE. The reason for the failure may be re-
  1025.  *        trieved using PR_GetError().
  1026.  **************************************************************************
  1027.  */
  1028.  
  1029. PR_EXTERN(PRStatus) PR_RmDir(const char *name);
  1030.  
  1031. PR_EXTERN(PRUintn) PR_NetAddrSize(const PRNetAddr* addr);
  1032.  
  1033. /*
  1034.  *************************************************************************
  1035.  * FUNCTION: PR_NewUDPSocket
  1036.  * DESCRIPTION:
  1037.  *     Create a new UDP network connection.
  1038.  * INPUTS:
  1039.  *     None
  1040.  * OUTPUTS:
  1041.  *     None
  1042.  * RETURN: PRFileDesc*
  1043.  *     Upon successful completion, PR_NewUDPSocket returns a pointer
  1044.  *     to the PRFileDesc created for the newly opened UDP socket.
  1045.  *     Returns a NULL pointer if the create of a new UDP connection failed.
  1046.  *
  1047.  **************************************************************************
  1048.  */
  1049.  
  1050. PR_EXTERN(PRFileDesc*)    PR_NewUDPSocket(void);
  1051.  
  1052. /*
  1053.  *************************************************************************
  1054.  * FUNCTION: PR_NewTCPSocket
  1055.  * DESCRIPTION:
  1056.  *     Create a new TCP network connection.
  1057.  * INPUTS:
  1058.  *     None
  1059.  * OUTPUTS:
  1060.  *     None
  1061.  * RETURN: PRFileDesc*
  1062.  *     Upon successful completion, PR_NewTCPSocket returns a pointer
  1063.  *     to the PRFileDesc created for the newly opened TCP socket.
  1064.  *     Returns a NULL pointer if the create of a new TCP connection failed.
  1065.  *
  1066.  **************************************************************************
  1067.  */
  1068.  
  1069. PR_EXTERN(PRFileDesc*)    PR_NewTCPSocket(void);
  1070.  
  1071. /*
  1072.  *************************************************************************
  1073.  * FUNCTION: PR_Connect
  1074.  * DESCRIPTION:
  1075.  *     Initiate a connection on a socket.
  1076.  * INPUTS:
  1077.  *     PRFileDesc *fd
  1078.  *       Points to a PRFileDesc object representing a socket
  1079.  *     PRNetAddr *addr
  1080.  *       Specifies the address of the socket in its own communication
  1081.  *       space.
  1082.  *     PRIntervalTime timeout
  1083.  *       Time limit for completion of the connect operation.
  1084.  * OUTPUTS:
  1085.  *     None
  1086.  * RETURN: PRStatus
  1087.  *     Upon successful completion of connection initiation, PR_Connect
  1088.  *     returns PR_SUCCESS.  Otherwise, it returns PR_FAILURE.  Further
  1089.  *     failure information can be obtained by calling PR_GetError().
  1090.  **************************************************************************
  1091.  */
  1092.  
  1093. PR_EXTERN(PRStatus) PR_Connect(
  1094.     PRFileDesc *fd, const PRNetAddr *addr, PRIntervalTime timeout);
  1095.  
  1096. /*
  1097.  *************************************************************************
  1098.  * FUNCTION: PR_GetConnectStatus
  1099.  * DESCRIPTION:
  1100.  *     Get the completion status of a nonblocking connect.  After
  1101.  *     a nonblocking connect is initiated with PR_Connect() (which
  1102.  *     fails with PR_IN_PROGRESS_ERROR), one should call PR_Poll()
  1103.  *     on the socket, with the in_flags PR_POLL_WRITE | PR_POLL_EXCEPT.
  1104.  *     When PR_Poll() returns, one calls PR_GetConnectStatus on the
  1105.  *     PRPollDesc structure to determine whether the nonblocking
  1106.  *     connect has succeeded or failed.
  1107.  * INPUTS:
  1108.  *     const PRPollDesc *pd
  1109.  *         Pointer to a PRPollDesc whose fd member is the socket,
  1110.  *         and in_flags must contain PR_POLL_WRITE and PR_POLL_EXCEPT.
  1111.  *         PR_Poll() should have been called and set the out_flags.
  1112.  * RETURN: PRStatus
  1113.  *     If the nonblocking connect has successfully completed,
  1114.  *     PR_GetConnectStatus returns PR_SUCCESS.  If PR_GetConnectStatus()
  1115.  *     returns PR_FAILURE, call PR_GetError():
  1116.  *     - PR_IN_PROGRESS_ERROR: the nonblocking connect is still in
  1117.  *       progress and has not completed yet.
  1118.  *     - Other errors: the nonblocking connect has failed with this
  1119.  *       error code.
  1120.  */
  1121.  
  1122. PR_EXTERN(PRStatus)    PR_GetConnectStatus(const PRPollDesc *pd);
  1123.  
  1124. /*
  1125.  *************************************************************************
  1126.  * FUNCTION: PR_Accept
  1127.  * DESCRIPTION:
  1128.  *     Accept a connection on a socket.
  1129.  * INPUTS:
  1130.  *     PRFileDesc *fd
  1131.  *       Points to a PRFileDesc object representing the rendezvous socket
  1132.  *       on which the caller is willing to accept new connections.
  1133.  *     PRIntervalTime timeout
  1134.  *       Time limit for completion of the accept operation.
  1135.  * OUTPUTS:
  1136.  *     PRNetAddr *addr
  1137.  *       Returns the address of the connecting entity in its own
  1138.  *       communication space. It may be NULL.
  1139.  * RETURN: PRFileDesc*
  1140.  *     Upon successful acceptance of a connection, PR_Accept
  1141.  *     returns a valid file descriptor. Otherwise, it returns NULL.
  1142.  *     Further failure information can be obtained by calling PR_GetError().
  1143.  **************************************************************************
  1144.  */
  1145.  
  1146. PR_EXTERN(PRFileDesc*) PR_Accept(
  1147.     PRFileDesc *fd, PRNetAddr *addr, PRIntervalTime timeout);
  1148.  
  1149. /*
  1150.  *************************************************************************
  1151.  * FUNCTION: PR_Bind
  1152.  * DESCRIPTION:
  1153.  *    Bind an address to a socket.
  1154.  * INPUTS:
  1155.  *     PRFileDesc *fd
  1156.  *       Points to a PRFileDesc object representing a socket.
  1157.  *     PRNetAddr *addr
  1158.  *       Specifies the address to which the socket will be bound.
  1159.  * OUTPUTS:
  1160.  *     None
  1161.  * RETURN: PRStatus
  1162.  *     Upon successful binding of an address to a socket, PR_Bind
  1163.  *     returns PR_SUCCESS.  Otherwise, it returns PR_FAILURE.  Further
  1164.  *     failure information can be obtained by calling PR_GetError().
  1165.  **************************************************************************
  1166.  */
  1167.  
  1168. PR_EXTERN(PRStatus) PR_Bind(PRFileDesc *fd, const PRNetAddr *addr);
  1169.  
  1170. /*
  1171.  *************************************************************************
  1172.  * FUNCTION: PR_Listen
  1173.  * DESCRIPTION:
  1174.  *    Listen for connections on a socket.
  1175.  * INPUTS:
  1176.  *     PRFileDesc *fd
  1177.  *       Points to a PRFileDesc object representing a socket that will be
  1178.  *       used to listen for new connections.
  1179.  *     PRIntn backlog
  1180.  *       Specifies the maximum length of the queue of pending connections.
  1181.  * OUTPUTS:
  1182.  *     None
  1183.  * RETURN: PRStatus
  1184.  *     Upon successful completion of listen request, PR_Listen
  1185.  *     returns PR_SUCCESS.  Otherwise, it returns PR_FAILURE.  Further
  1186.  *     failure information can be obtained by calling PR_GetError().
  1187.  **************************************************************************
  1188.  */
  1189.  
  1190. PR_EXTERN(PRStatus) PR_Listen(PRFileDesc *fd, PRIntn backlog);
  1191.  
  1192. /*
  1193.  *************************************************************************
  1194.  * FUNCTION: PR_Shutdown
  1195.  * DESCRIPTION:
  1196.  *    Shut down part of a full-duplex connection on a socket.
  1197.  * INPUTS:
  1198.  *     PRFileDesc *fd
  1199.  *       Points to a PRFileDesc object representing a connected socket.
  1200.  *     PRIntn how
  1201.  *       Specifies the kind of disallowed operations on the socket.
  1202.  *           PR_SHUTDOWN_RCV - Further receives will be disallowed
  1203.  *           PR_SHUTDOWN_SEND - Further sends will be disallowed
  1204.  *           PR_SHUTDOWN_BOTH - Further sends and receives will be disallowed
  1205.  * OUTPUTS:
  1206.  *     None
  1207.  * RETURN: PRStatus
  1208.  *     Upon successful completion of shutdown request, PR_Shutdown
  1209.  *     returns PR_SUCCESS.  Otherwise, it returns PR_FAILURE.  Further
  1210.  *     failure information can be obtained by calling PR_GetError().
  1211.  **************************************************************************
  1212.  */
  1213.  
  1214. typedef enum PRShutdownHow
  1215. {
  1216.     PR_SHUTDOWN_RCV = 0,      /* disallow further receives */
  1217.     PR_SHUTDOWN_SEND = 1,     /* disallow further sends */
  1218.     PR_SHUTDOWN_BOTH = 2      /* disallow further receives and sends */
  1219. } PRShutdownHow;
  1220.  
  1221. PR_EXTERN(PRStatus)    PR_Shutdown(PRFileDesc *fd, PRShutdownHow how);
  1222.  
  1223. /*
  1224.  *************************************************************************
  1225.  * FUNCTION: PR_Recv
  1226.  * DESCRIPTION:
  1227.  *    Receive a specified number of bytes from a connected socket.
  1228.  *     The operation will block until some positive number of bytes are 
  1229.  *     transferred, a time out has occurred, or there is an error. 
  1230.  *     No more than 'amount' bytes will be transferred.
  1231.  * INPUTS:
  1232.  *     PRFileDesc *fd
  1233.  *       points to a PRFileDesc object representing a socket.
  1234.  *     void *buf
  1235.  *       pointer to a buffer to hold the data received.
  1236.  *     PRInt32 amount
  1237.  *       the size of 'buf' (in bytes)
  1238.  *     PRIntn flags
  1239.  *        (OBSOLETE - must always be zero)
  1240.  *     PRIntervalTime timeout
  1241.  *       Time limit for completion of the receive operation.
  1242.  * OUTPUTS:
  1243.  *     None
  1244.  * RETURN: PRInt32
  1245.  *         a positive number indicates the number of bytes actually received.
  1246.  *         0 means the network connection is closed.
  1247.  *         -1 indicates a failure. The reason for the failure is obtained
  1248.  *         by calling PR_GetError().
  1249.  **************************************************************************
  1250.  */
  1251.  
  1252. PR_EXTERN(PRInt32)    PR_Recv(PRFileDesc *fd, void *buf, PRInt32 amount,
  1253.                 PRIntn flags, PRIntervalTime timeout);
  1254.  
  1255. /*
  1256.  *************************************************************************
  1257.  * FUNCTION: PR_Send
  1258.  * DESCRIPTION:
  1259.  *    Send a specified number of bytes from a connected socket.
  1260.  *     The operation will block until all bytes are 
  1261.  *     processed, a time out has occurred, or there is an error. 
  1262.  * INPUTS:
  1263.  *     PRFileDesc *fd
  1264.  *       points to a PRFileDesc object representing a socket.
  1265.  *     void *buf
  1266.  *       pointer to a buffer from where the data is sent.
  1267.  *     PRInt32 amount
  1268.  *       the size of 'buf' (in bytes)
  1269.  *     PRIntn flags
  1270.  *        (OBSOLETE - must always be zero)
  1271.  *     PRIntervalTime timeout
  1272.  *       Time limit for completion of the send operation.
  1273.  * OUTPUTS:
  1274.  *     None
  1275.  * RETURN: PRInt32
  1276.  *     A positive number indicates the number of bytes successfully processed.
  1277.  *     This number must always equal 'amount'. A -1 is an indication that the
  1278.  *     operation failed. The reason for the failure is obtained by calling
  1279.  *     PR_GetError().
  1280.  **************************************************************************
  1281.  */
  1282.  
  1283. PR_EXTERN(PRInt32)    PR_Send(PRFileDesc *fd, const void *buf, PRInt32 amount,
  1284.                                 PRIntn flags, PRIntervalTime timeout);
  1285.  
  1286. /*
  1287.  *************************************************************************
  1288.  * FUNCTION: PR_RecvFrom
  1289.  * DESCRIPTION:
  1290.  *     Receive up to a specified number of bytes from socket which may
  1291.  *     or may not be connected.
  1292.  *     The operation will block until one or more bytes are 
  1293.  *     transferred, a time out has occurred, or there is an error. 
  1294.  *     No more than 'amount' bytes will be transferred.
  1295.  * INPUTS:
  1296.  *     PRFileDesc *fd
  1297.  *       points to a PRFileDesc object representing a socket.
  1298.  *     void *buf
  1299.  *       pointer to a buffer to hold the data received.
  1300.  *     PRInt32 amount
  1301.  *       the size of 'buf' (in bytes)
  1302.  *     PRIntn flags
  1303.  *        (OBSOLETE - must always be zero)
  1304.  *     PRNetAddr *addr
  1305.  *       Specifies the address of the sending peer. It may be NULL.
  1306.  *     PRIntervalTime timeout
  1307.  *       Time limit for completion of the receive operation.
  1308.  * OUTPUTS:
  1309.  *     None
  1310.  * RETURN: PRInt32
  1311.  *         a positive number indicates the number of bytes actually received.
  1312.  *         0 means the network connection is closed.
  1313.  *         -1 indicates a failure. The reason for the failure is obtained
  1314.  *         by calling PR_GetError().
  1315.  **************************************************************************
  1316.  */
  1317.  
  1318. PR_EXTERN(PRInt32) PR_RecvFrom(
  1319.     PRFileDesc *fd, void *buf, PRInt32 amount, PRIntn flags,
  1320.     PRNetAddr *addr, PRIntervalTime timeout);
  1321.  
  1322. /*
  1323.  *************************************************************************
  1324.  * FUNCTION: PR_SendTo
  1325.  * DESCRIPTION:
  1326.  *    Send a specified number of bytes from an unconnected socket.
  1327.  *    The operation will block until all bytes are 
  1328.  *    sent, a time out has occurred, or there is an error. 
  1329.  * INPUTS:
  1330.  *     PRFileDesc *fd
  1331.  *       points to a PRFileDesc object representing an unconnected socket.
  1332.  *     void *buf
  1333.  *       pointer to a buffer from where the data is sent.
  1334.  *     PRInt32 amount
  1335.  *       the size of 'buf' (in bytes)
  1336.  *     PRIntn flags
  1337.  *        (OBSOLETE - must always be zero)
  1338.  *     PRNetAddr *addr
  1339.  *       Specifies the address of the peer.
  1340. .*     PRIntervalTime timeout
  1341.  *       Time limit for completion of the send operation.
  1342.  * OUTPUTS:
  1343.  *     None
  1344.  * RETURN: PRInt32
  1345.  *     A positive number indicates the number of bytes successfully sent.
  1346.  *     -1 indicates a failure. The reason for the failure is obtained
  1347.  *     by calling PR_GetError().
  1348.  **************************************************************************
  1349.  */
  1350.  
  1351. PR_EXTERN(PRInt32) PR_SendTo(
  1352.     PRFileDesc *fd, const void *buf, PRInt32 amount, PRIntn flags,
  1353.     const PRNetAddr *addr, PRIntervalTime timeout);
  1354.  
  1355. /*
  1356. *************************************************************************
  1357. ** FUNCTION: PR_TransmitFile
  1358. ** DESCRIPTION:
  1359. **    Transmitfile sends a complete file (sourceFile) across a socket 
  1360. **    (networkSocket).  If headers is non-NULL, the headers will be sent across
  1361. **    the socket prior to sending the file.
  1362. ** 
  1363. **    Optionally, the PR_TRANSMITFILE_CLOSE_SOCKET flag may be passed to
  1364. **    transmitfile.  This flag specifies that transmitfile should close the
  1365. **    socket after sending the data.
  1366. **
  1367. ** INPUTS:
  1368. **    PRFileDesc *networkSocket
  1369. **        The socket to send data over
  1370. **    PRFileDesc *sourceFile
  1371. **        The file to send
  1372. **    const void *headers
  1373. **        A pointer to headers to be sent before sending data
  1374. **    PRInt32       hlen
  1375. **        length of header buffers in bytes.
  1376. **    PRTransmitFileFlags       flags
  1377. **        If the flags indicate that the connection should be closed,
  1378. **        it will be done immediately after transferring the file, unless
  1379. **        the operation is unsuccessful. 
  1380. .*     PRIntervalTime timeout
  1381.  *        Time limit for completion of the transmit operation.
  1382. **
  1383. ** RETURNS:
  1384. **    Returns the number of bytes written or -1 if the operation failed.
  1385. **    If an error occurs while sending the file, the PR_TRANSMITFILE_CLOSE_
  1386. **    SOCKET flag is ignored. The reason for the failure is obtained
  1387. **    by calling PR_GetError().
  1388. **************************************************************************
  1389. */
  1390.  
  1391. PR_EXTERN(PRInt32) PR_TransmitFile(
  1392.     PRFileDesc *networkSocket, PRFileDesc *sourceFile,
  1393.     const void *headers, PRInt32 hlen, PRTransmitFileFlags flags,
  1394.     PRIntervalTime timeout);
  1395. /*
  1396. *************************************************************************
  1397. ** FUNCTION: PR_AcceptRead
  1398. ** DESCRIPTION:
  1399. **    AcceptRead accepts a new connection, returns the newly created
  1400. **    socket's descriptor and also returns the connecting peer's address.
  1401. **    AcceptRead, as its name suggests, also receives the first block of data 
  1402. **    sent by the peer.
  1403. **
  1404. ** INPUTS:
  1405. **    PRFileDesc *listenSock
  1406. **        A socket descriptor that has been called with the PR_Listen() 
  1407. **        function, also known as the rendezvous socket.
  1408. **    void *buf
  1409. **        A pointer to a buffer to receive data sent by the client.  This 
  1410. **        buffer must be large enough to receive <amount> bytes of data
  1411. **        and two PRNetAddr structures, plus an extra 32 bytes.
  1412. **    PRInt32 amount
  1413. **        The number of bytes of client data to receive.  Does not include
  1414. **        the size of the PRNetAddr structures.  If 0, no data will be read
  1415. **        from the client.
  1416. **    PRIntervalTime timeout
  1417. **        The timeout interval only applies to the read portion of the 
  1418. **        operation.  PR_AcceptRead will block indefinitely until the 
  1419. **        connection is accepted; the read will timeout after the timeout 
  1420. **        interval elapses.
  1421. ** OUTPUTS:
  1422. **    PRFileDesc **acceptedSock
  1423. **        The file descriptor for the newly connected socket.  This parameter
  1424. **        will only be valid if the function return does not indicate failure.
  1425. **    PRNetAddr  **peerAddr,
  1426. **        The address of the remote socket.  This parameter will only be
  1427. **        valid if the function return does not indicate failure.  The
  1428. **        returned address is not guaranteed to be properly aligned.
  1429. ** 
  1430. ** RETURNS:
  1431. **     The number of bytes read from the client or -1 on failure.  The reason 
  1432. **     for the failure is obtained by calling PR_GetError().
  1433. **************************************************************************
  1434. **/
  1435. PR_EXTERN(PRInt32) PR_AcceptRead(
  1436.     PRFileDesc *listenSock, PRFileDesc **acceptedSock,
  1437.     PRNetAddr **peerAddr, void *buf, PRInt32 amount, PRIntervalTime timeout);
  1438.  
  1439. /*
  1440. *************************************************************************
  1441. ** FUNCTION: PR_NewTCPSocketPair
  1442. ** DESCRIPTION:
  1443. **    Create a new TCP socket pair. The returned descriptors can be used
  1444. **    interchangeably; they are interconnected full-duplex descriptors: data
  1445. **    written to one can be read from the other and vice-versa.
  1446. **
  1447. ** INPUTS:
  1448. **    None
  1449. ** OUTPUTS:
  1450. **    PRFileDesc *fds[2]
  1451. **        The file descriptor pair for the newly created TCP sockets.
  1452. ** RETURN: PRStatus
  1453. **     Upon successful completion of TCP socket pair, PR_NewTCPSocketPair 
  1454. **     returns PR_SUCCESS.  Otherwise, it returns PR_FAILURE.  Further
  1455. **     failure information can be obtained by calling PR_GetError().
  1456. ** XXX can we implement this on windoze and mac?
  1457. **************************************************************************
  1458. **/
  1459. PR_EXTERN(PRStatus) PR_NewTCPSocketPair(PRFileDesc *fds[2]);
  1460.  
  1461. /*
  1462. *************************************************************************
  1463. ** FUNCTION: PR_GetSockName
  1464. ** DESCRIPTION:
  1465. **    Get socket name.  Return the network address for this socket.
  1466. **
  1467. ** INPUTS:
  1468. **     PRFileDesc *fd
  1469. **       Points to a PRFileDesc object representing the socket.
  1470. ** OUTPUTS:
  1471. **     PRNetAddr *addr
  1472. **       Returns the address of the socket in its own communication space.
  1473. ** RETURN: PRStatus
  1474. **     Upon successful completion, PR_GetSockName returns PR_SUCCESS.  
  1475. **     Otherwise, it returns PR_FAILURE.  Further failure information can 
  1476. **     be obtained by calling PR_GetError().
  1477. **************************************************************************
  1478. **/
  1479. PR_EXTERN(PRStatus)    PR_GetSockName(PRFileDesc *fd, PRNetAddr *addr);
  1480.  
  1481. /*
  1482. *************************************************************************
  1483. ** FUNCTION: PR_GetPeerName
  1484. ** DESCRIPTION:
  1485. **    Get name of the connected peer.  Return the network address for the 
  1486. **    connected peer socket.
  1487. **
  1488. ** INPUTS:
  1489. **     PRFileDesc *fd
  1490. **       Points to a PRFileDesc object representing the connected peer.
  1491. ** OUTPUTS:
  1492. **     PRNetAddr *addr
  1493. **       Returns the address of the connected peer in its own communication
  1494. **       space.
  1495. ** RETURN: PRStatus
  1496. **     Upon successful completion, PR_GetPeerName returns PR_SUCCESS.  
  1497. **     Otherwise, it returns PR_FAILURE.  Further failure information can 
  1498. **     be obtained by calling PR_GetError().
  1499. **************************************************************************
  1500. **/
  1501. PR_EXTERN(PRStatus)    PR_GetPeerName(PRFileDesc *fd, PRNetAddr *addr);
  1502.  
  1503. PR_EXTERN(PRStatus)    PR_GetSocketOption(
  1504.     PRFileDesc *fd, PRSocketOptionData *data);
  1505.  
  1506. PR_EXTERN(PRStatus)    PR_SetSocketOption(
  1507.     PRFileDesc *fd, const PRSocketOptionData *data);
  1508.  
  1509. /*
  1510.  *********************************************************************
  1511.  *
  1512.  * Memory-mapped files
  1513.  *
  1514.  *********************************************************************
  1515.  */
  1516.  
  1517. typedef struct PRFileMap PRFileMap;
  1518.  
  1519. /*
  1520.  * protection options for read and write accesses of a file mapping
  1521.  */
  1522. typedef enum PRFileMapProtect {
  1523.     PR_PROT_READONLY,     /* read only */
  1524.     PR_PROT_READWRITE,    /* readable, and write is shared */
  1525.     PR_PROT_WRITECOPY     /* readable, and write is private (copy-on-write) */
  1526. } PRFileMapProtect;
  1527.  
  1528. PR_EXTERN(PRFileMap *) PR_CreateFileMap(
  1529.     PRFileDesc *fd,
  1530.     PRInt64 size,
  1531.     PRFileMapProtect prot);
  1532.  
  1533. PR_EXTERN(void *) PR_MemMap(
  1534.     PRFileMap *fmap,
  1535.     PRInt64 offset,  /* must be aligned and sized to whole pages */
  1536.     PRUint32 len);
  1537.  
  1538. PR_EXTERN(PRStatus) PR_MemUnmap(void *addr, PRUint32 len);
  1539.  
  1540. PR_EXTERN(PRStatus) PR_CloseFileMap(PRFileMap *fmap);
  1541.  
  1542. /*
  1543.  ******************************************************************
  1544.  *
  1545.  * Interprocess communication
  1546.  *
  1547.  ******************************************************************
  1548.  */
  1549.  
  1550. /*
  1551.  * Creates an anonymous pipe and returns file descriptors for the
  1552.  * read and write ends of the pipe.
  1553.  */
  1554.  
  1555. PR_EXTERN(PRStatus) PR_CreatePipe(
  1556.     PRFileDesc **readPipe,
  1557.     PRFileDesc **writePipe
  1558. );
  1559.  
  1560. /************************************************************************/
  1561. /************** The following definitions are for poll ******************/
  1562. /************************************************************************/
  1563.  
  1564. struct PRPollDesc {
  1565.     PRFileDesc* fd;
  1566.     PRInt16 in_flags;
  1567.     PRInt16 out_flags;
  1568. };
  1569.  
  1570. /*
  1571. ** Bit values for PRPollDesc.in_flags or PRPollDesc.out_flags. Binary-or
  1572. ** these together to produce the desired poll request.
  1573. */
  1574.  
  1575. #if defined(_PR_POLL_BACKCOMPAT)
  1576.  
  1577. #include <poll.h>
  1578. #define PR_POLL_READ    POLLIN
  1579. #define PR_POLL_WRITE   POLLOUT
  1580. #define PR_POLL_EXCEPT  POLLPRI
  1581. #define PR_POLL_ERR     POLLERR     /* only in out_flags */
  1582. #define PR_POLL_NVAL    POLLNVAL    /* only in out_flags when fd is bad */
  1583. #define PR_POLL_HUP     POLLHUP     /* only in out_flags */
  1584.  
  1585. #else  /* _PR_POLL_BACKCOMPAT */
  1586.  
  1587. #define PR_POLL_READ    0x1
  1588. #define PR_POLL_WRITE   0x2
  1589. #define PR_POLL_EXCEPT  0x4
  1590. #define PR_POLL_ERR     0x8         /* only in out_flags */
  1591. #define PR_POLL_NVAL    0x10        /* only in out_flags when fd is bad */
  1592. #define PR_POLL_HUP     0x20        /* only in out_flags */
  1593.  
  1594. #endif  /* _PR_POLL_BACKCOMPAT */
  1595.  
  1596. /*
  1597. *************************************************************************
  1598. ** FUNCTION:    PR_Poll
  1599. ** DESCRIPTION:
  1600. **
  1601. ** The call returns as soon as I/O is ready on one or more of the underlying
  1602. ** file/socket objects. A count of the number of ready descriptors is
  1603. ** returned unless a timeout occurs in which case zero is returned.
  1604. **
  1605. ** PRPollDesc.in_flags should be set to the desired request
  1606. ** (read/write/except or some combination). Upon return from this call
  1607. ** PRPollDesc.out_flags will be set to indicate what kind of i/o can be
  1608. ** performed on the respective descriptor.
  1609. **
  1610. ** INPUTS:
  1611. **      PRPollDesc *pds         A pointer to an array of PRPollDesc
  1612. **
  1613. **      PRIntn npds             The number of elements in the array
  1614. **                              If this argument is zero PR_Poll is
  1615. **                              equivalent to a PR_Sleep(timeout).
  1616. **
  1617. **      PRIntervalTime timeout  Amount of time the call will block waiting
  1618. **                              for I/O to become ready. If this time expires
  1619. **                              w/o any I/O becoming ready, the result will
  1620. **                              be zero.
  1621. **
  1622. ** OUTPUTS:    None
  1623. ** RETURN:
  1624. **      PRInt32                 Number of PRPollDesc's with events or zero
  1625. **                              if the function timed out or -1 on failure.
  1626. **                              The reason for the failure is obtained by calling 
  1627. **                              PR_GetError().
  1628. ** XXX can we implement this on windoze and mac?
  1629. **************************************************************************
  1630. */
  1631. PR_EXTERN(PRInt32) PR_Poll(
  1632.     PRPollDesc *pds, PRIntn npds, PRIntervalTime timeout);
  1633.  
  1634. /*
  1635. **************************************************************************
  1636. **
  1637. ** Pollable events
  1638. **
  1639. ** A pollable event is a special kind of file descriptor.
  1640. ** The only I/O operation you can perform on a pollable event
  1641. ** is to poll it with the PR_POLL_READ flag.  You can't
  1642. ** read from or write to a pollable event.
  1643. **
  1644. ** The purpose of a pollable event is to combine event waiting
  1645. ** with I/O waiting in a single PR_Poll call.  Pollable events
  1646. ** are implemented using a pipe or a pair of TCP sockets
  1647. ** connected via the loopback address, therefore setting and
  1648. ** waiting for pollable events are expensive operating system
  1649. ** calls.  Do not use pollable events for general thread
  1650. ** synchronization. Use condition variables instead.
  1651. **
  1652. ** A pollable event has two states: set and unset.  Events
  1653. ** are not queued, so there is no notion of an event count.
  1654. ** A pollable event is either set or unset.
  1655. **
  1656. ** A new pollable event is created by a PR_NewPollableEvent
  1657. ** call and is initially in the unset state.
  1658. **
  1659. ** PR_WaitForPollableEvent blocks the calling thread until
  1660. ** the pollable event is set, and then it atomically unsets
  1661. ** the pollable event before it returns.
  1662. **
  1663. ** To set a pollable event, call PR_SetPollableEvent.
  1664. **
  1665. ** One can call PR_Poll with the PR_POLL_READ flag on a pollable
  1666. ** event.  When the pollable event is set, PR_Poll returns with
  1667. ** the PR_POLL_READ flag set in the out_flags.
  1668. **
  1669. ** To close a pollable event, call PR_DestroyPollableEvent
  1670. ** (not PR_Close).
  1671. **
  1672. **************************************************************************
  1673. */
  1674.  
  1675. PR_EXTERN(PRFileDesc *) PR_NewPollableEvent(void);
  1676.  
  1677. PR_EXTERN(PRStatus) PR_DestroyPollableEvent(PRFileDesc *event);
  1678.  
  1679. PR_EXTERN(PRStatus) PR_SetPollableEvent(PRFileDesc *event);
  1680.  
  1681. PR_EXTERN(PRStatus) PR_WaitForPollableEvent(PRFileDesc *event);
  1682.  
  1683. PR_END_EXTERN_C
  1684.  
  1685. #endif /* prio_h___ */
  1686.