prio.h@ 11551

Last change on this file since 11551 was 11551, checked in by vboxsync, 16 years ago
API/xpcom: prefix any C symbols in VBoxXPCOM.so, to avoid namespace pollution. Enabled only on Linux at the moment.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 79.5 KB

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

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/libs/xpcom18a4/nsprpub/pr/include/prio.h@ 11551

Download in other formats: