PageRenderTime 194ms CodeModel.GetById 106ms app.highlight 64ms RepoModel.GetById 1ms app.codeStats 1ms

/gecko_api/include/prio.h

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