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