libraries/source/spidermonkey/include-win32-release/nspr/prio.h

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