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