Mercurial > trustbridge > nss-cmake-static

comparison nspr/pr/include/prio.h @ 0:1e5118fa0cb1

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