Line data Source code
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) || defined(XP_WIN)
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, /* receive buffer size */
200 : PR_SockOpt_SendBufferSize, /* send 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_Reuseport, /* allow local address & port reuse on
215 : * platforms that support it */
216 : PR_SockOpt_Last
217 : } PRSockOption;
218 :
219 : typedef struct PRLinger {
220 : PRBool polarity; /* Polarity of the option's setting */
221 : PRIntervalTime linger; /* Time to linger before closing */
222 : } PRLinger;
223 :
224 : typedef struct PRMcastRequest {
225 : PRNetAddr mcaddr; /* IP multicast address of group */
226 : PRNetAddr ifaddr; /* local IP address of interface */
227 : } PRMcastRequest;
228 :
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;
254 :
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;
267 :
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;
281 :
282 : typedef enum PRSeekWhence {
283 : PR_SEEK_SET = 0,
284 : PR_SEEK_CUR = 1,
285 : PR_SEEK_END = 2
286 : } PRSeekWhence;
287 :
288 0 : NSPR_API(PRDescType) PR_GetDescType(PRFileDesc *file);
289 :
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 : */
305 :
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);
358 :
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 : };
400 :
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 : */
419 :
420 : typedef enum PRSpecialFD
421 : {
422 : PR_StandardInput, /* standard input */
423 : PR_StandardOutput, /* standard output */
424 : PR_StandardError /* standard error */
425 : } PRSpecialFD;
426 :
427 0 : NSPR_API(PRFileDesc*) PR_GetSpecialFD(PRSpecialFD id);
428 :
429 : #define PR_STDIN PR_GetSpecialFD(PR_StandardInput)
430 : #define PR_STDOUT PR_GetSpecialFD(PR_StandardOutput)
431 : #define PR_STDERR PR_GetSpecialFD(PR_StandardError)
432 :
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 : */
461 :
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
466 :
467 3 : NSPR_API(PRDescIdentity) PR_GetUniqueIdentity(const char *layer_name);
468 0 : NSPR_API(const char*) PR_GetNameForIdentity(PRDescIdentity ident);
469 0 : NSPR_API(PRDescIdentity) PR_GetLayersIdentity(PRFileDesc* fd);
470 170 : NSPR_API(PRFileDesc*) PR_GetIdentitiesLayer(PRFileDesc* fd_stack, PRDescIdentity id);
471 :
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 3 : NSPR_API(const PRIOMethods *) PR_GetDefaultIOMethods(void);
481 :
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 2 : NSPR_API(PRFileDesc*) PR_CreateIOLayerStub(
492 : PRDescIdentity ident, const PRIOMethods *methods);
493 :
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 0 : NSPR_API(PRFileDesc*) PR_CreateIOLayer(PRFileDesc* fd);
509 :
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 2 : NSPR_API(PRStatus) PR_PushIOLayer(
525 : PRFileDesc *fd_stack, PRDescIdentity id, PRFileDesc *layer);
526 :
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 2 : NSPR_API(PRFileDesc*) PR_PopIOLayer(PRFileDesc *fd_stack, PRDescIdentity id);
542 :
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 : */
586 :
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
596 :
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 : */
614 :
615 1273 : NSPR_API(PRFileDesc*) PR_Open(const char *name, PRIntn flags, PRIntn mode);
616 :
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 : */
626 :
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 */
640 :
641 1276 : NSPR_API(PRFileDesc*) PR_OpenFile(
642 : const char *name, PRIntn flags, PRIntn mode);
643 :
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 */
651 :
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 : */
671 :
672 1256 : NSPR_API(PRStatus) PR_Close(PRFileDesc *fd);
673 :
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 : */
706 :
707 1296 : NSPR_API(PRInt32) PR_Read(PRFileDesc *fd, void *buf, PRInt32 amount);
708 :
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 : */
730 :
731 159 : NSPR_API(PRInt32) PR_Write(PRFileDesc *fd,const void *buf,PRInt32 amount);
732 :
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 : */
762 :
763 : #define PR_MAX_IOVECTOR_SIZE 16 /* 'iov_size' must be <= */
764 :
765 0 : NSPR_API(PRInt32) PR_Writev(
766 : PRFileDesc *fd, const PRIOVec *iov, PRInt32 iov_size,
767 : PRIntervalTime timeout);
768 :
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 : */
785 :
786 0 : NSPR_API(PRStatus) PR_Delete(const char *name);
787 :
788 : /**************************************************************************/
789 :
790 : typedef enum PRFileType
791 : {
792 : PR_FILE_FILE = 1,
793 : PR_FILE_DIRECTORY = 2,
794 : PR_FILE_OTHER = 3
795 : } PRFileType;
796 :
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 : };
803 :
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 : };
810 :
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 : */
828 :
829 0 : NSPR_API(PRStatus) PR_GetFileInfo(const char *fn, PRFileInfo *info);
830 26 : NSPR_API(PRStatus) PR_GetFileInfo64(const char *fn, PRFileInfo64 *info);
831 :
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 */
838 :
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 : */
855 :
856 1 : NSPR_API(PRStatus) PR_GetOpenFileInfo(PRFileDesc *fd, PRFileInfo *info);
857 941 : NSPR_API(PRStatus) PR_GetOpenFileInfo64(PRFileDesc *fd, PRFileInfo64 *info);
858 :
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 : */
874 :
875 0 : NSPR_API(PRStatus) PR_Rename(const char *from, const char *to);
876 :
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 : */
900 :
901 : typedef enum PRAccessHow {
902 : PR_ACCESS_EXISTS = 1,
903 : PR_ACCESS_WRITE_OK = 2,
904 : PR_ACCESS_READ_OK = 3
905 : } PRAccessHow;
906 :
907 0 : NSPR_API(PRStatus) PR_Access(const char *name, PRAccessHow how);
908 :
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 : */
941 :
942 2 : NSPR_API(PROffset32) PR_Seek(PRFileDesc *fd, PROffset32 offset, PRSeekWhence whence);
943 11 : NSPR_API(PROffset64) PR_Seek64(PRFileDesc *fd, PROffset64 offset, PRSeekWhence whence);
944 :
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 : */
964 :
965 3 : NSPR_API(PRInt32) PR_Available(PRFileDesc *fd);
966 134 : NSPR_API(PRInt64) PR_Available64(PRFileDesc *fd);
967 :
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 : */
984 :
985 6 : NSPR_API(PRStatus) PR_Sync(PRFileDesc *fd);
986 :
987 : /************************************************************************/
988 :
989 : struct PRDirEntry {
990 : const char *name; /* name of entry, relative to directory name */
991 : };
992 :
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 */
999 :
1000 : #if !defined(NO_NSPR_10_SUPPORT)
1001 : #define PR_DirName(dirEntry) (dirEntry->name)
1002 : #endif
1003 :
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 : */
1023 :
1024 0 : NSPR_API(PRDir*) PR_OpenDir(const char *name);
1025 :
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 */
1032 :
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 : */
1055 :
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;
1063 :
1064 0 : NSPR_API(PRDirEntry*) PR_ReadDir(PRDir *dir, PRDirFlags flags);
1065 :
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 */
1072 :
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 : */
1089 :
1090 0 : NSPR_API(PRStatus) PR_CloseDir(PRDir *dir);
1091 :
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 */
1098 :
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 : */
1118 :
1119 0 : NSPR_API(PRStatus) PR_MkDir(const char *name, PRIntn mode);
1120 :
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 : */
1130 :
1131 0 : NSPR_API(PRStatus) PR_MakeDir(const char *name, PRIntn mode);
1132 :
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 : */
1150 :
1151 0 : NSPR_API(PRStatus) PR_RmDir(const char *name);
1152 :
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 : */
1169 :
1170 0 : NSPR_API(PRFileDesc*) PR_NewUDPSocket(void);
1171 :
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 : */
1188 :
1189 0 : NSPR_API(PRFileDesc*) PR_NewTCPSocket(void);
1190 :
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 : */
1208 :
1209 0 : NSPR_API(PRFileDesc*) PR_OpenUDPSocket(PRIntn af);
1210 :
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 : */
1228 :
1229 3 : NSPR_API(PRFileDesc*) PR_OpenTCPSocket(PRIntn af);
1230 :
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 : */
1256 :
1257 3 : NSPR_API(PRStatus) PR_Connect(
1258 : PRFileDesc *fd, const PRNetAddr *addr, PRIntervalTime timeout);
1259 :
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 : */
1291 :
1292 3 : NSPR_API(PRStatus) PR_ConnectContinue(PRFileDesc *fd, PRInt16 out_flags);
1293 :
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 : */
1321 :
1322 0 : NSPR_API(PRStatus) PR_GetConnectStatus(const PRPollDesc *pd);
1323 :
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 : */
1345 :
1346 0 : NSPR_API(PRFileDesc*) PR_Accept(
1347 : PRFileDesc *fd, PRNetAddr *addr, PRIntervalTime timeout);
1348 :
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 : */
1367 :
1368 0 : NSPR_API(PRStatus) PR_Bind(PRFileDesc *fd, const PRNetAddr *addr);
1369 :
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 : */
1389 :
1390 0 : NSPR_API(PRStatus) PR_Listen(PRFileDesc *fd, PRIntn backlog);
1391 :
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 : */
1413 :
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;
1420 :
1421 0 : NSPR_API(PRStatus) PR_Shutdown(PRFileDesc *fd, PRShutdownHow how);
1422 :
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 : */
1451 :
1452 : #define PR_MSG_PEEK 0x2
1453 :
1454 1 : NSPR_API(PRInt32) PR_Recv(PRFileDesc *fd, void *buf, PRInt32 amount,
1455 : PRIntn flags, PRIntervalTime timeout);
1456 :
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 : */
1484 :
1485 0 : NSPR_API(PRInt32) PR_Send(PRFileDesc *fd, const void *buf, PRInt32 amount,
1486 : PRIntn flags, PRIntervalTime timeout);
1487 :
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 : */
1519 :
1520 0 : NSPR_API(PRInt32) PR_RecvFrom(
1521 : PRFileDesc *fd, void *buf, PRInt32 amount, PRIntn flags,
1522 : PRNetAddr *addr, PRIntervalTime timeout);
1523 :
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 : */
1552 :
1553 0 : NSPR_API(PRInt32) PR_SendTo(
1554 : PRFileDesc *fd, const void *buf, PRInt32 amount, PRIntn flags,
1555 : const PRNetAddr *addr, PRIntervalTime timeout);
1556 :
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 : */
1592 :
1593 0 : NSPR_API(PRInt32) PR_TransmitFile(
1594 : PRFileDesc *networkSocket, PRFileDesc *sourceFile,
1595 : const void *headers, PRInt32 hlen, PRTransmitFileFlags flags,
1596 : PRIntervalTime timeout);
1597 :
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 : */
1631 :
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 : };
1643 :
1644 :
1645 0 : NSPR_API(PRInt32) PR_SendFile(
1646 : PRFileDesc *networkSocket, PRSendFileData *sendData,
1647 : PRTransmitFileFlags flags, PRIntervalTime timeout);
1648 :
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)))
1698 :
1699 0 : NSPR_API(PRInt32) PR_AcceptRead(
1700 : PRFileDesc *listenSock, PRFileDesc **acceptedSock,
1701 : PRNetAddr **peerAddr, void *buf, PRInt32 amount, PRIntervalTime timeout);
1702 :
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 0 : NSPR_API(PRStatus) PR_NewTCPSocketPair(PRFileDesc *fds[2]);
1724 :
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 3 : NSPR_API(PRStatus) PR_GetSockName(PRFileDesc *fd, PRNetAddr *addr);
1744 :
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 0 : NSPR_API(PRStatus) PR_GetPeerName(PRFileDesc *fd, PRNetAddr *addr);
1766 :
1767 0 : NSPR_API(PRStatus) PR_GetSocketOption(
1768 : PRFileDesc *fd, PRSocketOptionData *data);
1769 :
1770 11 : NSPR_API(PRStatus) PR_SetSocketOption(
1771 : PRFileDesc *fd, const PRSocketOptionData *data);
1772 :
1773 : /*
1774 : *********************************************************************
1775 : *
1776 : * File descriptor inheritance
1777 : *
1778 : *********************************************************************
1779 : */
1780 :
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 0 : NSPR_API(PRStatus) PR_SetFDInheritable(
1801 : PRFileDesc *fd,
1802 : PRBool inheritable);
1803 :
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 0 : NSPR_API(PRFileDesc *) PR_GetInheritedFD(const char *name);
1821 :
1822 : /*
1823 : *********************************************************************
1824 : *
1825 : * Memory-mapped files
1826 : *
1827 : *********************************************************************
1828 : */
1829 :
1830 : typedef struct PRFileMap PRFileMap;
1831 :
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;
1840 :
1841 107 : NSPR_API(PRFileMap *) PR_CreateFileMap(
1842 : PRFileDesc *fd,
1843 : PRInt64 size,
1844 : PRFileMapProtect prot);
1845 :
1846 : /*
1847 : * return the alignment (in bytes) of the offset argument to PR_MemMap
1848 : */
1849 1 : NSPR_API(PRInt32) PR_GetMemMapAlignment(void);
1850 :
1851 107 : 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);
1856 :
1857 101 : NSPR_API(PRStatus) PR_MemUnmap(void *addr, PRUint32 len);
1858 :
1859 101 : NSPR_API(PRStatus) PR_CloseFileMap(PRFileMap *fmap);
1860 :
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 0 : NSPR_API(PRStatus) PR_SyncMemMap(
1870 : PRFileDesc *fd,
1871 : void *addr,
1872 : PRUint32 len);
1873 :
1874 : /*
1875 : ******************************************************************
1876 : *
1877 : * Interprocess communication
1878 : *
1879 : ******************************************************************
1880 : */
1881 :
1882 : /*
1883 : * Creates an anonymous pipe and returns file descriptors for the
1884 : * read and write ends of the pipe.
1885 : */
1886 :
1887 3 : NSPR_API(PRStatus) PR_CreatePipe(
1888 : PRFileDesc **readPipe,
1889 : PRFileDesc **writePipe
1890 : );
1891 :
1892 : /************************************************************************/
1893 : /************** The following definitions are for poll ******************/
1894 : /************************************************************************/
1895 :
1896 : struct PRPollDesc {
1897 : PRFileDesc* fd;
1898 : PRInt16 in_flags;
1899 : PRInt16 out_flags;
1900 : };
1901 :
1902 : /*
1903 : ** Bit values for PRPollDesc.in_flags or PRPollDesc.out_flags. Binary-or
1904 : ** these together to produce the desired poll request.
1905 : */
1906 :
1907 : #if defined(_PR_POLL_BACKCOMPAT)
1908 :
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 */
1916 :
1917 : #else /* _PR_POLL_BACKCOMPAT */
1918 :
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 */
1925 :
1926 : #endif /* _PR_POLL_BACKCOMPAT */
1927 :
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 59 : NSPR_API(PRInt32) PR_Poll(
1969 : PRPollDesc *pds, PRIntn npds, PRIntervalTime timeout);
1970 :
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 : */
2011 :
2012 0 : NSPR_API(PRFileDesc *) PR_NewPollableEvent(void);
2013 :
2014 0 : NSPR_API(PRStatus) PR_DestroyPollableEvent(PRFileDesc *event);
2015 :
2016 0 : NSPR_API(PRStatus) PR_SetPollableEvent(PRFileDesc *event);
2017 :
2018 0 : NSPR_API(PRStatus) PR_WaitForPollableEvent(PRFileDesc *event);
2019 :
2020 : PR_END_EXTERN_C
2021 :
2022 : #endif /* prio_h___ */
|
