src/third_party/npapi/npspy/extern/nspr/prio.h

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