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