1	/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2	/* This Source Code Form is subject to the terms of the Mozilla Public
3	* License, v. 2.0. If a copy of the MPL was not distributed with this
4	* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
5
6	/*
7	* File: prio.h
8	*
9	* Description: PR i/o related stuff, such as file system access, file
10	* i/o, socket i/o, etc.
11	*/
12
13	#ifndef prio_h___
14	#define prio_h___
15
16	#include "prlong.h"
17	#include "prtime.h"
18	#include "prinrval.h"
19	#include "prinet.h"
20
21	PR_BEGIN_EXTERN_C
22
23	/* Typedefs */
24	typedef struct PRDir PRDir;
25	typedef struct PRDirEntry PRDirEntry;
26	#ifdef MOZ_UNICODE
27	typedef struct PRDirUTF16 PRDirUTF16;
28	typedef struct PRDirEntryUTF16 PRDirEntryUTF16;
29	#endif /* MOZ_UNICODE */
30	typedef struct PRFileDesc PRFileDesc;
31	typedef struct PRFileInfo PRFileInfo;
32	typedef struct PRFileInfo64 PRFileInfo64;
33	typedef union PRNetAddr PRNetAddr;
34	typedef struct PRIOMethods PRIOMethods;
35	typedef struct PRPollDesc PRPollDesc;
36	typedef struct PRFilePrivate PRFilePrivate;
37	typedef struct PRSendFileData PRSendFileData;
38
39	/*
40	***************************************************************************
41	** The file descriptor.
42	** This is the primary structure to represent any active open socket,
43	** whether it be a normal file or a network connection. Such objects
44	** are stackable (or layerable). Each layer may have its own set of
45	** method pointers and context private to that layer. All each layer
46	** knows about its neighbors is how to get to their method table.
47	***************************************************************************
48	*/
49
50	typedef PRIntn PRDescIdentity; /* see: Layering file descriptors */
51
52	struct PRFileDesc {
53	const PRIOMethods *methods; /* the I/O methods table */
54	PRFilePrivate *secret; /* layer dependent data */
55	PRFileDesc *lower, *higher; /* pointers to adjacent layers */
56	void (PR_CALLBACK *dtor)(PRFileDesc *fd);
57	/* A destructor function for layer */
58	PRDescIdentity identity; /* Identity of this particular layer */
59	};
60
61	/*
62	***************************************************************************
63	** PRTransmitFileFlags
64	**
65	** Flags for PR_TransmitFile. Pass PR_TRANSMITFILE_CLOSE_SOCKET to
66	** PR_TransmitFile if the connection should be closed after the file
67	** is transmitted.
68	***************************************************************************
69	*/
70	typedef enum PRTransmitFileFlags {
71	PR_TRANSMITFILE_KEEP_OPEN = 0, /* socket is left open after file
72	* is transmitted. */
73	PR_TRANSMITFILE_CLOSE_SOCKET = 1 /* socket is closed after file
74	* is transmitted. */
75	} PRTransmitFileFlags;
76
77	/*
78	**************************************************************************
79	** Macros for PRNetAddr
80	**
81	** Address families: PR_AF_INET, PR_AF_INET6, PR_AF_LOCAL
82	** IP addresses: PR_INADDR_ANY, PR_INADDR_LOOPBACK, PR_INADDR_BROADCAST
83	**************************************************************************
84	*/
85
86	#ifdef WIN32
87
88	#define PR_AF_INET 2
89	#define PR_AF_LOCAL 1
90	#define PR_INADDR_ANY (unsigned long)0x00000000
91	#define PR_INADDR_LOOPBACK 0x7f000001
92	#define PR_INADDR_BROADCAST (unsigned long)0xffffffff
93
94	#else /* WIN32 */
95
96	#define PR_AF_INET AF_INET
97	#define PR_AF_LOCAL AF_UNIX
98	#define PR_INADDR_ANY INADDR_ANY
99	#define PR_INADDR_LOOPBACK INADDR_LOOPBACK
100	#define PR_INADDR_BROADCAST INADDR_BROADCAST
101
102	#endif /* WIN32 */
103
104	/*
105	** Define PR_AF_INET6 in prcpucfg.h with the same
106	** value as AF_INET6 on platforms with IPv6 support.
107	** Otherwise define it here.
108	*/
109	#ifndef PR_AF_INET6
110	#define PR_AF_INET6 100
111	#endif
112
113	#define PR_AF_INET_SDP 101
114	#define PR_AF_INET6_SDP 102
115
116	#ifndef PR_AF_UNSPEC
117	#define PR_AF_UNSPEC 0
118	#endif
119
120	/*
121	**************************************************************************
122	** A network address
123	**
124	** Only Internet Protocol (IPv4 and IPv6) addresses are supported.
125	** The address family must always represent IPv4 (AF_INET, probably == 2)
126	** or IPv6 (AF_INET6).
127	**************************************************************************
128	*************************************************************************/
129
130	struct PRIPv6Addr {
131	union {
132	PRUint8 _S6_u8[16];
133	PRUint16 _S6_u16[8];
134	PRUint32 _S6_u32[4];
135	PRUint64 _S6_u64[2];
136	} _S6_un;
137	};
138	#define pr_s6_addr _S6_un._S6_u8
139	#define pr_s6_addr16 _S6_un._S6_u16
140	#define pr_s6_addr32 _S6_un._S6_u32
141	#define pr_s6_addr64 _S6_un._S6_u64
142
143	typedef struct PRIPv6Addr PRIPv6Addr;
144
145	union PRNetAddr {
146	struct {
147	PRUint16 family; /* address family (0x00ff maskable) */
148	#ifdef XP_BEOS
149	char data[10]; /* Be has a smaller structure */
150	#else
151	char data[14]; /* raw address data */
152	#endif
153	} raw;
154	struct {
155	PRUint16 family; /* address family (AF_INET) */
156	PRUint16 port; /* port number */
157	PRUint32 ip; /* The actual 32 bits of address */
158	#ifdef XP_BEOS
159	char pad[4]; /* Be has a smaller structure */
160	#else
161	char pad[8];
162	#endif
163	} inet;
164	struct {
165	PRUint16 family; /* address family (AF_INET6) */
166	PRUint16 port; /* port number */
167	PRUint32 flowinfo; /* routing information */
168	PRIPv6Addr ip; /* the actual 128 bits of address */
169	PRUint32 scope_id; /* set of interfaces for a scope */
170	} ipv6;
171	#if defined(XP_UNIX) || defined(XP_OS2)
172	struct { /* Unix domain socket address */
173	PRUint16 family; /* address family (AF_UNIX) */
174	#ifdef XP_OS2
175	char path[108]; /* null-terminated pathname */
176	/* bind fails if size is not 108. */
177	#else
178	char path[104]; /* null-terminated pathname */
179	#endif
180	} local;
181	#endif
182	};
183
184	/*
185	***************************************************************************
186	** PRSockOption
187	**
188	** The file descriptors can have predefined options set after they file
189	** descriptor is created to change their behavior. Only the options in
190	** the following enumeration are supported.
191	***************************************************************************
192	*/
193	typedef enum PRSockOption
194	{
195	PR_SockOpt_Nonblocking, /* nonblocking io */
196	PR_SockOpt_Linger, /* linger on close if data present */
197	PR_SockOpt_Reuseaddr, /* allow local address reuse */
198	PR_SockOpt_Keepalive, /* keep connections alive */
199	PR_SockOpt_RecvBufferSize, /* send buffer size */
200	PR_SockOpt_SendBufferSize, /* receive buffer size */
201
202	PR_SockOpt_IpTimeToLive, /* time to live */
203	PR_SockOpt_IpTypeOfService, /* type of service and precedence */
204
205	PR_SockOpt_AddMember, /* add an IP group membership */
206	PR_SockOpt_DropMember, /* drop an IP group membership */
207	PR_SockOpt_McastInterface, /* multicast interface address */
208	PR_SockOpt_McastTimeToLive, /* multicast timetolive */
209	PR_SockOpt_McastLoopback, /* multicast loopback */
210
211	PR_SockOpt_NoDelay, /* don't delay send to coalesce packets */
212	PR_SockOpt_MaxSegment, /* maximum segment size */
213	PR_SockOpt_Broadcast, /* enable broadcast */
214	PR_SockOpt_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	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	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	NSPR_API(PRDescIdentity) PR_GetUniqueIdentity(const char *layer_name);
468	NSPR_API(const char*) PR_GetNameForIdentity(PRDescIdentity ident);
469	NSPR_API(PRDescIdentity) PR_GetLayersIdentity(PRFileDesc* fd);
470	NSPR_API(PRFileDesc*) PR_GetIdentitiesLayer(PRFileDesc* fd_stack, PRDescIdentity id);
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	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	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	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	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	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	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	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	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	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	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	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	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	NSPR_API(PRStatus) PR_GetFileInfo(const char *fn, PRFileInfo *info);
830	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	NSPR_API(PRStatus) PR_GetOpenFileInfo(PRFileDesc *fd, PRFileInfo *info);
857	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	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	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	NSPR_API(PROffset32) PR_Seek(PRFileDesc *fd, PROffset32 offset, PRSeekWhence whence);
943	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	NSPR_API(PRInt32) PR_Available(PRFileDesc *fd);
966	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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	NSPR_API(PRStatus) PR_GetPeerName(PRFileDesc *fd, PRNetAddr *addr);
1766
1767	NSPR_API(PRStatus) PR_GetSocketOption(
1768	PRFileDesc *fd, PRSocketOptionData *data);
1769
1770	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	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	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	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	NSPR_API(PRInt32) PR_GetMemMapAlignment(void);
1850
1851	NSPR_API(void *) PR_MemMap(
1852	PRFileMap *fmap,
1853	PROffset64 offset, /* must be aligned and sized according to the
1854	* return value of PR_GetMemMapAlignment() */
1855	PRUint32 len);
1856
1857	NSPR_API(PRStatus) PR_MemUnmap(void *addr, PRUint32 len);
1858
1859	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	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	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	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	NSPR_API(PRFileDesc *) PR_NewPollableEvent(void);
2013
2014	NSPR_API(PRStatus) PR_DestroyPollableEvent(PRFileDesc *event);
2015
2016	NSPR_API(PRStatus) PR_SetPollableEvent(PRFileDesc *event);
2017
2018	NSPR_API(PRStatus) PR_WaitForPollableEvent(PRFileDesc *event);
2019
2020	PR_END_EXTERN_C
2021
2022	#endif /* prio_h___ */
2023

---

Generated while processing kdesupport/qca/plugins/qca-nss/qca-nss.cpp
Generated on 2014-Aug-04 from project include
Powered by Code Browser 1.7