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