prio.h@ 101893

Last change on this file since 101893 was 101891, checked in by vboxsync, 18 months ago
libs/xpcom: Remove more unused code in nsprpub, bugref:10545
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 61.8 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_OpenDir VBoxNsprPR_OpenDir
76	#define PR_ReadDir VBoxNsprPR_ReadDir
77	#define PR_CloseDir VBoxNsprPR_CloseDir
78	#define PR_CreatePipe VBoxNsprPR_CreatePipe
79	#define PR_GetDescType VBoxNsprPR_GetDescType
80	#define PR_GetSpecialFD VBoxNsprPR_GetSpecialFD
81	#define PR_GetUniqueIdentity VBoxNsprPR_GetUniqueIdentity
82	#define PR_GetNameForIdentity VBoxNsprPR_GetNameForIdentity
83	#define PR_GetLayersIdentity VBoxNsprPR_GetLayersIdentity
84	#define PR_GetIdentitiesLayer VBoxNsprPR_GetIdentitiesLayer
85	#define PR_GetDefaultIOMethods VBoxNsprPR_GetDefaultIOMethods
86	#define PR_CreateIOLayerStub VBoxNsprPR_CreateIOLayerStub
87	#define PR_CreateIOLayer VBoxNsprPR_CreateIOLayer
88	#define PR_PushIOLayer VBoxNsprPR_PushIOLayer
89	#define PR_PopIOLayer VBoxNsprPR_PopIOLayer
90	#define PR_OpenFile VBoxNsprPR_OpenFile
91	#define PR_Writev VBoxNsprPR_Writev
92	#define PR_Delete VBoxNsprPR_Delete
93	#define PR_Rename VBoxNsprPR_Rename
94	#define PR_GetFileInfo VBoxNsprPR_GetFileInfo
95	#define PR_GetFileInfo64 VBoxNsprPR_GetFileInfo64
96	#define PR_GetOpenFileInfo VBoxNsprPR_GetOpenFileInfo
97	#define PR_GetOpenFileInfo64 VBoxNsprPR_GetOpenFileInfo64
98	#define PR_Available VBoxNsprPR_Available
99	#define PR_Sync VBoxNsprPR_Sync
100	#define PR_MkDir VBoxNsprPR_MkDir
101	#define PR_MakeDir VBoxNsprPR_MakeDir
102	#define PR_RmDir VBoxNsprPR_RmDir
103	#define PR_OpenTCPSocket VBoxNsprPR_OpenTCPSocket
104	#define PR_ConnectContinue VBoxNsprPR_ConnectContinue
105	#define PR_GetConnectStatus VBoxNsprPR_GetConnectStatus
106	#define PR_Shutdown VBoxNsprPR_Shutdown
107	#define PR_Recv VBoxNsprPR_Recv
108	#define PR_Send VBoxNsprPR_Send
109	#define PR_TransmitFile VBoxNsprPR_TransmitFile
110	#define PR_GetSockName VBoxNsprPR_GetSockName
111	#define PR_GetPeerName VBoxNsprPR_GetPeerName
112	#define PR_GetSocketOption VBoxNsprPR_GetSocketOption
113	#define PR_CreatePipe VBoxNsprPR_CreatePipe
114	#endif /* VBOX_WITH_XPCOM_NAMESPACE_CLEANUP */
115
116	PR_BEGIN_EXTERN_C
117
118	/* Typedefs */
119	typedef struct PRDir PRDir;
120	typedef struct PRDirEntry PRDirEntry;
121	typedef struct PRFileDesc PRFileDesc;
122	typedef struct PRFileInfo PRFileInfo;
123	typedef struct PRFileInfo64 PRFileInfo64;
124	typedef union PRNetAddr PRNetAddr;
125	typedef struct PRIOMethods PRIOMethods;
126	typedef struct PRPollDesc PRPollDesc;
127	typedef struct PRFilePrivate PRFilePrivate;
128
129	/*
130	***************************************************************************
131	** The file descriptor.
132	** This is the primary structure to represent any active open socket,
133	** whether it be a normal file or a network connection. Such objects
134	** are stackable (or layerable). Each layer may have its own set of
135	** method pointers and context private to that layer. All each layer
136	** knows about its neighbors is how to get to their method table.
137	***************************************************************************
138	*/
139
140	typedef PRIntn PRDescIdentity; /* see: Layering file descriptors */
141
142	struct PRFileDesc {
143	const PRIOMethods methods; / the I/O methods table */
144	PRFilePrivate secret; / layer dependent data */
145	PRFileDesc lower, higher; /* pointers to adjacent layers */
146	void (PR_CALLBACK dtor)(PRFileDesc fd);
147	/* A destructor function for layer */
148	PRDescIdentity identity; /* Identity of this particular layer */
149	};
150
151	/*
152	***************************************************************************
153	** PRTransmitFileFlags
154	**
155	** Flags for PR_TransmitFile. Pass PR_TRANSMITFILE_CLOSE_SOCKET to
156	** PR_TransmitFile if the connection should be closed after the file
157	** is transmitted.
158	***************************************************************************
159	*/
160	typedef enum PRTransmitFileFlags {
161	PR_TRANSMITFILE_KEEP_OPEN = 0, /* socket is left open after file
162	* is transmitted. */
163	PR_TRANSMITFILE_CLOSE_SOCKET = 1 /* socket is closed after file
164	* is transmitted. */
165	} PRTransmitFileFlags;
166
167	/*
168	**************************************************************************
169	** Macros for PRNetAddr
170	**
171	** Address families: PR_AF_INET, PR_AF_INET6, PR_AF_LOCAL
172	** IP addresses: PR_INADDR_ANY, PR_INADDR_LOOPBACK, PR_INADDR_BROADCAST
173	**************************************************************************
174	*/
175
176	#ifdef WIN32
177
178	#define PR_AF_INET 2
179	#define PR_AF_LOCAL 1
180	#define PR_INADDR_ANY (unsigned long)0x00000000
181	#define PR_INADDR_LOOPBACK 0x7f000001
182	#define PR_INADDR_BROADCAST (unsigned long)0xffffffff
183
184	#else /* WIN32 */
185
186	#define PR_AF_INET AF_INET
187	#define PR_AF_LOCAL AF_UNIX
188	#define PR_INADDR_ANY INADDR_ANY
189	#define PR_INADDR_LOOPBACK INADDR_LOOPBACK
190	#define PR_INADDR_BROADCAST INADDR_BROADCAST
191
192	#endif /* WIN32 */
193
194	/*
195	** Define PR_AF_INET6 in prcpucfg.h with the same
196	** value as AF_INET6 on platforms with IPv6 support.
197	** Otherwise define it here.
198	*/
199	#ifndef PR_AF_INET6
200	#define PR_AF_INET6 100
201	#endif
202
203	#ifndef PR_AF_UNSPEC
204	#define PR_AF_UNSPEC 0
205	#endif
206
207	/*
208	**************************************************************************
209	** A network address
210	**
211	** Only Internet Protocol (IPv4 and IPv6) addresses are supported.
212	** The address family must always represent IPv4 (AF_INET, probably == 2)
213	** or IPv6 (AF_INET6).
214	**************************************************************************
215	*************************************************************************/
216
217	struct PRIPv6Addr {
218	union {
219	PRUint8 _S6_u8[16];
220	PRUint16 _S6_u16[8];
221	PRUint32 _S6_u32[4];
222	PRUint64 _S6_u64[2];
223	} _S6_un;
224	};
225	#define pr_s6_addr _S6_un._S6_u8
226	#define pr_s6_addr16 _S6_un._S6_u16
227	#define pr_s6_addr32 _S6_un._S6_u32
228	#define pr_s6_addr64 _S6_un._S6_u64
229
230	typedef struct PRIPv6Addr PRIPv6Addr;
231
232	union PRNetAddr {
233	struct {
234	PRUint16 family; /* address family (0x00ff maskable) */
235	char data[14]; /* raw address data */
236	} raw;
237	struct {
238	PRUint16 family; /* address family (AF_INET) */
239	PRUint16 port; /* port number */
240	PRUint32 ip; /* The actual 32 bits of address */
241	char pad[8];
242	} inet;
243	struct {
244	PRUint16 family; /* address family (AF_INET6) */
245	PRUint16 port; /* port number */
246	PRUint32 flowinfo; /* routing information */
247	PRIPv6Addr ip; /* the actual 128 bits of address */
248	PRUint32 scope_id; /* set of interfaces for a scope */
249	} ipv6;
250	#if defined(XP_UNIX)
251	struct { /* Unix domain socket address */
252	PRUint16 family; /* address family (AF_UNIX) */
253	char path[104]; /* null-terminated pathname */
254	} local;
255	#endif
256	};
257
258	/*
259	***************************************************************************
260	** PRSockOption
261	**
262	** The file descriptors can have predefined options set after they file
263	** descriptor is created to change their behavior. Only the options in
264	** the following enumeration are supported.
265	***************************************************************************
266	*/
267	typedef enum PRSockOption
268	{
269	PR_SockOpt_Nonblocking, /* nonblocking io */
270	PR_SockOpt_Linger, /* linger on close if data present */
271	PR_SockOpt_Reuseaddr, /* allow local address reuse */
272	PR_SockOpt_Keepalive, /* keep connections alive */
273	PR_SockOpt_RecvBufferSize, /* send buffer size */
274	PR_SockOpt_SendBufferSize, /* receive buffer size */
275
276	PR_SockOpt_IpTimeToLive, /* time to live */
277	PR_SockOpt_IpTypeOfService, /* type of service and precedence */
278
279	PR_SockOpt_AddMember, /* add an IP group membership */
280	PR_SockOpt_DropMember, /* drop an IP group membership */
281	PR_SockOpt_McastInterface, /* multicast interface address */
282	PR_SockOpt_McastTimeToLive, /* multicast timetolive */
283	PR_SockOpt_McastLoopback, /* multicast loopback */
284
285	PR_SockOpt_NoDelay, /* don't delay send to coalesce packets */
286	PR_SockOpt_MaxSegment, /* maximum segment size */
287	PR_SockOpt_Broadcast, /* enable broadcast */
288	PR_SockOpt_Last
289	} PRSockOption;
290
291	typedef struct PRLinger {
292	PRBool polarity; /* Polarity of the option's setting */
293	PRIntervalTime linger; /* Time to linger before closing */
294	} PRLinger;
295
296	typedef struct PRMcastRequest {
297	PRNetAddr mcaddr; /* IP multicast address of group */
298	PRNetAddr ifaddr; /* local IP address of interface */
299	} PRMcastRequest;
300
301	typedef struct PRSocketOptionData
302	{
303	PRSockOption option;
304	union
305	{
306	PRUintn ip_ttl; /* IP time to live */
307	PRUintn mcast_ttl; /* IP multicast time to live */
308	PRUintn tos; /* IP type of service and precedence */
309	PRBool non_blocking; /* Non-blocking (network) I/O */
310	PRBool reuse_addr; /* Allow local address reuse */
311	PRBool keep_alive; /* Keep connections alive */
312	PRBool mcast_loopback; /* IP multicast loopback */
313	PRBool no_delay; /* Don't delay send to coalesce packets */
314	PRBool broadcast; /* Enable broadcast */
315	PRSize max_segment; /* Maximum segment size */
316	PRSize recv_buffer_size; /* Receive buffer size */
317	PRSize send_buffer_size; /* Send buffer size */
318	PRLinger linger; /* Time to linger on close if data present */
319	PRMcastRequest add_member; /* add an IP group membership */
320	PRMcastRequest drop_member; /* Drop an IP group membership */
321	PRNetAddr mcast_if; /* multicast interface address */
322	} value;
323	} PRSocketOptionData;
324
325	/*
326	***************************************************************************
327	** PRIOVec
328	**
329	** The I/O vector is used by the write vector method to describe the areas
330	** that are affected by the ouput operation.
331	***************************************************************************
332	*/
333	typedef struct PRIOVec {
334	char *iov_base;
335	int iov_len;
336	} PRIOVec;
337
338	/*
339	***************************************************************************
340	** Discover what type of socket is being described by the file descriptor.
341	***************************************************************************
342	*/
343	typedef enum PRDescType
344	{
345	PR_DESC_FILE = 1,
346	PR_DESC_SOCKET_TCP = 2,
347	PR_DESC_SOCKET_UDP = 3,
348	PR_DESC_LAYERED = 4,
349	PR_DESC_PIPE = 5
350	} PRDescType;
351
352	typedef enum PRSeekWhence {
353	PR_SEEK_SET = 0,
354	PR_SEEK_CUR = 1,
355	PR_SEEK_END = 2
356	} PRSeekWhence;
357
358	NSPR_API(PRDescType) PR_GetDescType(PRFileDesc *file);
359
360	/*
361	***************************************************************************
362	** PRIOMethods
363	**
364	** The I/O methods table provides procedural access to the functions of
365	** the file descriptor. It is the responsibility of a layer implementor
366	** to provide suitable functions at every entry point. If a layer provides
367	** no functionality, it should call the next lower(higher) function of the
368	** same name (e.g., return fd->lower->method->close(fd->lower));
369	**
370	** Not all functions are implemented for all types of files. In cases where
371	** that is true, the function will return a error indication with an error
372	** code of PR_INVALID_METHOD_ERROR.
373	***************************************************************************
374	*/
375
376	typedef PRStatus (PR_CALLBACK PRCloseFN)(PRFileDesc fd);
377	typedef PRInt32 (PR_CALLBACK PRReadFN)(PRFileDesc fd, void *buf, PRInt32 amount);
378	typedef PRInt32 (PR_CALLBACK PRWriteFN)(PRFileDesc fd, const void *buf, PRInt32 amount);
379	typedef PRInt32 (PR_CALLBACK PRAvailableFN)(PRFileDesc fd);
380	typedef PRStatus (PR_CALLBACK PRFsyncFN)(PRFileDesc fd);
381	typedef PROffset32 (PR_CALLBACK PRSeekFN)(PRFileDesc fd, PROffset32 offset, PRSeekWhence how);
382	typedef PROffset64 (PR_CALLBACK PRSeek64FN)(PRFileDesc fd, PROffset64 offset, PRSeekWhence how);
383	typedef PRStatus (PR_CALLBACK PRFileInfoFN)(PRFileDesc fd, PRFileInfo *info);
384	typedef PRStatus (PR_CALLBACK PRFileInfo64FN)(PRFileDesc fd, PRFileInfo64 *info);
385	typedef PRInt32 (PR_CALLBACK *PRWritevFN)(
386	PRFileDesc fd, const PRIOVec iov, PRInt32 iov_size,
387	PRIntervalTime timeout);
388	typedef PRStatus (PR_CALLBACK *PRConnectFN)(
389	PRFileDesc fd, const PRNetAddr addr, PRIntervalTime timeout);
390	typedef PRFileDesc* (PR_CALLBACK *PRAcceptFN) (
391	PRFileDesc fd, PRNetAddr addr, PRIntervalTime timeout);
392	typedef PRStatus (PR_CALLBACK PRBindFN)(PRFileDesc fd, const PRNetAddr *addr);
393	typedef PRStatus (PR_CALLBACK PRListenFN)(PRFileDesc fd, PRIntn backlog);
394	typedef PRStatus (PR_CALLBACK PRShutdownFN)(PRFileDesc fd, PRIntn how);
395	typedef PRInt32 (PR_CALLBACK *PRRecvFN)(
396	PRFileDesc fd, void buf, PRInt32 amount,
397	PRIntn flags, PRIntervalTime timeout);
398	typedef PRInt32 (PR_CALLBACK *PRSendFN) (
399	PRFileDesc fd, const void buf, PRInt32 amount,
400	PRIntn flags, PRIntervalTime timeout);
401	typedef PRInt16 (PR_CALLBACK *PRPollFN)(
402	PRFileDesc fd, PRInt16 in_flags, PRInt16 out_flags);
403	typedef PRStatus (PR_CALLBACK PRGetsocknameFN)(PRFileDesc fd, PRNetAddr *addr);
404	typedef PRStatus (PR_CALLBACK PRGetpeernameFN)(PRFileDesc fd, PRNetAddr *addr);
405	typedef PRStatus (PR_CALLBACK *PRGetsocketoptionFN)(
406	PRFileDesc fd, PRSocketOptionData data);
407	typedef PRStatus (PR_CALLBACK *PRSetsocketoptionFN)(
408	PRFileDesc fd, const PRSocketOptionData data);
409	typedef PRStatus (PR_CALLBACK *PRConnectcontinueFN)(
410	PRFileDesc *fd, PRInt16 out_flags);
411	typedef PRIntn (PR_CALLBACK PRReservedFN)(PRFileDesc fd);
412
413	struct PRIOMethods {
414	PRDescType file_type; /* Type of file represented (tos) */
415	PRCloseFN close; /* close file and destroy descriptor */
416	PRReadFN read; /* read up to specified bytes into buffer */
417	PRWriteFN write; /* write specified bytes from buffer */
418	PRAvailableFN available; /* determine number of bytes available */
419	PRFsyncFN fsync; /* flush all buffers to permanent store */
420	PRSeekFN seek; /* position the file to the desired place */
421	PRSeek64FN seek64; /* ditto, 64 bit */
422	PRFileInfoFN fileInfo; /* Get information about an open file */
423	PRFileInfo64FN fileInfo64; /* ditto, 64 bit */
424	PRWritevFN writev; /* Write segments as described by iovector */
425	PRConnectFN connect; /* Connect to the specified (net) address */
426	PRAcceptFN accept; /* Accept a connection for a (net) peer */
427	PRBindFN bind; /* Associate a (net) address with the fd */
428	PRListenFN listen; /* Prepare to listen for (net) connections */
429	PRShutdownFN shutdown; /* Shutdown a (net) connection */
430	PRRecvFN recv; /* Solicit up the the specified bytes */
431	PRSendFN send; /* Send all the bytes specified */
432	PRPollFN poll; /* Test the fd to see if it is ready */
433	PRGetsocknameFN getsockname; /* Get (net) address associated with fd */
434	PRGetpeernameFN getpeername; /* Get peer's (net) address */
435	PRReservedFN reserved_fn_6; /* reserved for future use */
436	PRReservedFN reserved_fn_5; /* reserved for future use */
437	PRGetsocketoptionFN getsocketoption;
438	/* Get current setting of specified option */
439	PRSetsocketoptionFN setsocketoption;
440	/* Set value of specified option */
441	PRConnectcontinueFN connectcontinue;
442	/* Continue a nonblocking connect */
443	PRReservedFN reserved_fn_3; /* reserved for future use */
444	PRReservedFN reserved_fn_2; /* reserved for future use */
445	PRReservedFN reserved_fn_1; /* reserved for future use */
446	PRReservedFN reserved_fn_0; /* reserved for future use */
447	};
448
449	/*
450	**************************************************************************
451	* FUNCTION: PR_GetSpecialFD
452	* DESCRIPTION: Get the file descriptor that represents the standard input,
453	* output, or error stream.
454	* INPUTS:
455	* PRSpecialFD id
456	* A value indicating the type of stream desired:
457	* PR_StandardInput: standard input
458	* PR_StandardOuput: standard output
459	* PR_StandardError: standard error
460	* OUTPUTS: none
461	* RETURNS: PRFileDesc *
462	* If the argument is valid, PR_GetSpecialFD returns a file descriptor
463	* that represents the corresponding standard I/O stream. Otherwise,
464	* PR_GetSpecialFD returns NULL and sets error PR_INVALID_ARGUMENT_ERROR.
465	**************************************************************************
466	*/
467
468	typedef enum PRSpecialFD
469	{
470	PR_StandardInput, /* standard input */
471	PR_StandardOutput, /* standard output */
472	PR_StandardError /* standard error */
473	} PRSpecialFD;
474
475	NSPR_API(PRFileDesc*) PR_GetSpecialFD(PRSpecialFD id);
476
477	#define PR_STDIN PR_GetSpecialFD(PR_StandardInput)
478	#define PR_STDOUT PR_GetSpecialFD(PR_StandardOutput)
479	#define PR_STDERR PR_GetSpecialFD(PR_StandardError)
480
481	/*
482	**************************************************************************
483	* Layering file descriptors
484	*
485	* File descriptors may be layered. Each layer has it's own identity.
486	* Identities are allocated by the runtime and are to be associated
487	* (by the layer implementor) with all layers that are of that type.
488	* It is then possible to scan the chain of layers and find a layer
489	* that one recongizes and therefore predict that it will implement
490	* a desired protocol.
491	*
492	* There are three well-known identities:
493	* PR_INVALID_IO_LAYER => an invalid layer identity, for error return
494	* PR_TOP_IO_LAYER => the identity of the top of the stack
495	* PR_NSPR_IO_LAYER => the identity used by NSPR proper
496	* PR_TOP_IO_LAYER may be used as a shorthand for identifying the topmost
497	* layer of an existing stack. Ie., the following two constructs are
498	* equivalent.
499	*
500	* rv = PR_PushIOLayer(stack, PR_TOP_IO_LAYER, my_layer);
501	* rv = PR_PushIOLayer(stack, PR_GetLayersIdentity(stack), my_layer)
502	*
503	* A string may be associated with the creation of the identity. It
504	* will be copied by the runtime. If queried the runtime will return
505	* a reference to that copied string (not yet another copy). There
506	* is no facility for deleting an identity.
507	**************************************************************************
508	*/
509
510	#define PR_IO_LAYER_HEAD (PRDescIdentity)-3
511	#define PR_INVALID_IO_LAYER (PRDescIdentity)-1
512	#define PR_TOP_IO_LAYER (PRDescIdentity)-2
513	#define PR_NSPR_IO_LAYER (PRDescIdentity)0
514
515	NSPR_API(PRDescIdentity) PR_GetUniqueIdentity(const char *layer_name);
516	NSPR_API(const char*) PR_GetNameForIdentity(PRDescIdentity ident);
517	NSPR_API(PRDescIdentity) PR_GetLayersIdentity(PRFileDesc* fd);
518	NSPR_API(PRFileDesc) PR_GetIdentitiesLayer(PRFileDesc fd_stack, PRDescIdentity id);
519
520	/*
521	**************************************************************************
522	* PR_GetDefaultIOMethods: Accessing the default methods table.
523	* You may get a pointer to the default methods table by calling this function.
524	* You may then select any elements from that table with which to build your
525	* layer's methods table. You may NOT modify the table directly.
526	**************************************************************************
527	*/
528	NSPR_API(const PRIOMethods *) PR_GetDefaultIOMethods(void);
529
530	/*
531	**************************************************************************
532	* Creating a layer
533	*
534	* A new layer may be allocated by calling PR_CreateIOLayerStub(). The
535	* file descriptor returned will contain the pointer to the methods table
536	* provided. The runtime will not modify the table nor test its correctness.
537	**************************************************************************
538	*/
539	NSPR_API(PRFileDesc*) PR_CreateIOLayerStub(
540	PRDescIdentity ident, const PRIOMethods *methods);
541
542	/*
543	**************************************************************************
544	* Creating a layer
545	*
546	* A new stack may be created by calling PR_CreateIOLayer(). The
547	* file descriptor returned will point to the top of the stack, which has
548	* the layer 'fd' as the topmost layer.
549	*
550	* NOTE: This function creates a new style stack, which has a fixed, dummy
551	* header. The old style stack, created by a call to PR_PushIOLayer,
552	* results in modifying contents of the top layer of the stack, when
553	* pushing and popping layers of the stack.
554	**************************************************************************
555	*/
556	NSPR_API(PRFileDesc) PR_CreateIOLayer(PRFileDesc fd);
557
558	/*
559	**************************************************************************
560	* Pushing a layer
561	*
562	* A file descriptor (perhaps allocated using PR_CreateIOLayerStub()) may
563	* be pushed into an existing stack of file descriptors at any point the
564	* caller deems appropriate. The new layer will be inserted into the stack
565	* just above the layer with the indicated identity.
566	*
567	* Note: Even if the identity parameter indicates the top-most layer of
568	* the stack, the value of the file descriptor describing the original
569	* stack will not change.
570	**************************************************************************
571	*/
572	NSPR_API(PRStatus) PR_PushIOLayer(
573	PRFileDesc fd_stack, PRDescIdentity id, PRFileDesc layer);
574
575	/*
576	**************************************************************************
577	* Popping a layer
578	*
579	* A layer may be popped from a stack by indicating the identity of the
580	* layer to be removed. If found, a pointer to the removed object will
581	* be returned to the caller. The object then becomes the responsibility
582	* of the caller.
583	*
584	* Note: Even if the identity indicates the top layer of the stack, the
585	* reference returned will not be the file descriptor for the stack and
586	* that file descriptor will remain valid.
587	**************************************************************************
588	*/
589	NSPR_API(PRFileDesc) PR_PopIOLayer(PRFileDesc fd_stack, PRDescIdentity id);
590
591	/*
592	**************************************************************************
593	* FUNCTION: PR_Open
594	* DESCRIPTION: Open a file for reading, writing, or both.
595	* INPUTS:
596	* const char *name
597	* The path name of the file to be opened
598	* PRIntn flags
599	* The file status flags.
600	* It is a bitwise OR of the following bit flags (only one of
601	* the first three flags below may be used):
602	* PR_RDONLY Open for reading only.
603	* PR_WRONLY Open for writing only.
604	* PR_RDWR Open for reading and writing.
605	* PR_CREATE_FILE If the file does not exist, the file is created
606	* If the file exists, this flag has no effect.
607	* PR_SYNC If set, each write will wait for both the file data
608	* and file status to be physically updated.
609	* PR_APPEND The file pointer is set to the end of
610	* the file prior to each write.
611	* PR_TRUNCATE If the file exists, its length is truncated to 0.
612	* PR_EXCL With PR_CREATE_FILE, if the file does not exist,
613	* the file is created. If the file already
614	* exists, no action and NULL is returned
615	*
616	* PRIntn mode
617	* The access permission bits of the file mode, if the file is
618	* created when PR_CREATE_FILE is on.
619	* OUTPUTS: None
620	* RETURNS: PRFileDesc *
621	* If the file is successfully opened,
622	* returns a pointer to the PRFileDesc
623	* created for the newly opened file.
624	* Returns a NULL pointer if the open
625	* failed.
626	* SIDE EFFECTS:
627	* RESTRICTIONS:
628	* MEMORY:
629	* The return value, if not NULL, points to a dynamically allocated
630	* PRFileDesc object.
631	* ALGORITHM:
632	**************************************************************************
633	*/
634
635	/* Open flags */
636	#define PR_RDONLY 0x01
637	#define PR_WRONLY 0x02
638	#define PR_RDWR 0x04
639	#define PR_CREATE_FILE 0x08
640	#define PR_APPEND 0x10
641	#define PR_TRUNCATE 0x20
642	#define PR_SYNC 0x40
643	#define PR_EXCL 0x80
644
645	/*
646	** File modes ....
647	**
648	** CAVEAT: 'mode' is currently only applicable on UNIX platforms.
649	** The 'mode' argument may be ignored by PR_Open on other platforms.
650	**
651	** 00400 Read by owner.
652	** 00200 Write by owner.
653	** 00100 Execute (search if a directory) by owner.
654	** 00040 Read by group.
655	** 00020 Write by group.
656	** 00010 Execute by group.
657	** 00004 Read by others.
658	** 00002 Write by others
659	** 00001 Execute by others.
660	**
661	*/
662
663	NSPR_API(PRFileDesc) PR_Open(const char name, PRIntn flags, PRIntn mode);
664
665	/*
666	**************************************************************************
667	* FUNCTION: PR_OpenFile
668	* DESCRIPTION:
669	* Open a file for reading, writing, or both.
670	* PR_OpenFile has the same prototype as PR_Open but implements
671	* the specified file mode where possible.
672	**************************************************************************
673	*/
674
675	/* File mode bits */
676	#define PR_IRWXU 00700 /* read, write, execute/search by owner */
677	#define PR_IRUSR 00400 /* read permission, owner */
678	#define PR_IWUSR 00200 /* write permission, owner */
679	#define PR_IXUSR 00100 /* execute/search permission, owner */
680	#define PR_IRWXG 00070 /* read, write, execute/search by group */
681	#define PR_IRGRP 00040 /* read permission, group */
682	#define PR_IWGRP 00020 /* write permission, group */
683	#define PR_IXGRP 00010 /* execute/search permission, group */
684	#define PR_IRWXO 00007 /* read, write, execute/search by others */
685	#define PR_IROTH 00004 /* read permission, others */
686	#define PR_IWOTH 00002 /* write permission, others */
687	#define PR_IXOTH 00001 /* execute/search permission, others */
688
689	NSPR_API(PRFileDesc*) PR_OpenFile(
690	const char *name, PRIntn flags, PRIntn mode);
691
692	/*
693	**************************************************************************
694	* FUNCTION: PR_Close
695	* DESCRIPTION:
696	* Close a file or socket.
697	* INPUTS:
698	* PRFileDesc *fd
699	* a pointer to a PRFileDesc.
700	* OUTPUTS:
701	* None.
702	* RETURN:
703	* PRStatus
704	* SIDE EFFECTS:
705	* RESTRICTIONS:
706	* None.
707	* MEMORY:
708	* The dynamic memory pointed to by the argument fd is freed.
709	**************************************************************************
710	*/
711
712	NSPR_API(PRStatus) PR_Close(PRFileDesc *fd);
713
714	/*
715	**************************************************************************
716	* FUNCTION: PR_Read
717	* DESCRIPTION:
718	* Read bytes from a file or socket.
719	* The operation will block until either an end of stream indication is
720	* encountered, some positive number of bytes are transferred, or there
721	* is an error. No more than 'amount' bytes will be transferred.
722	* INPUTS:
723	* PRFileDesc *fd
724	* pointer to the PRFileDesc object for the file or socket
725	* void *buf
726	* pointer to a buffer to hold the data read in.
727	* PRInt32 amount
728	* the size of 'buf' (in bytes)
729	* OUTPUTS:
730	* RETURN:
731	* PRInt32
732	* a positive number indicates the number of bytes actually read in.
733	* 0 means end of file is reached or the network connection is closed.
734	* -1 indicates a failure. The reason for the failure is obtained
735	* by calling PR_GetError().
736	* SIDE EFFECTS:
737	* data is written into the buffer pointed to by 'buf'.
738	* RESTRICTIONS:
739	* None.
740	* MEMORY:
741	* N/A
742	* ALGORITHM:
743	* N/A
744	**************************************************************************
745	*/
746
747	NSPR_API(PRInt32) PR_Read(PRFileDesc fd, void buf, PRInt32 amount);
748
749	/*
750	***************************************************************************
751	* FUNCTION: PR_Write
752	* DESCRIPTION:
753	* Write a specified number of bytes to a file or socket. The thread
754	* invoking this function blocks until all the data is written.
755	* INPUTS:
756	* PRFileDesc *fd
757	* pointer to a PRFileDesc object that refers to a file or socket
758	* const void *buf
759	* pointer to the buffer holding the data
760	* PRInt32 amount
761	* amount of data in bytes to be written from the buffer
762	* OUTPUTS:
763	* None.
764	* RETURN: PRInt32
765	* A positive number indicates the number of bytes successfully written.
766	* A -1 is an indication that the operation failed. The reason
767	* for the failure is obtained by calling PR_GetError().
768	***************************************************************************
769	*/
770
771	NSPR_API(PRInt32) PR_Write(PRFileDesc fd,const void buf,PRInt32 amount);
772
773	/*
774	***************************************************************************
775	* FUNCTION: PR_Writev
776	* DESCRIPTION:
777	* Write data to a socket. The data is organized in a PRIOVec array. The
778	* operation will block until all the data is written or the operation
779	* fails.
780	* INPUTS:
781	* PRFileDesc *fd
782	* Pointer that points to a PRFileDesc object for a socket.
783	* const PRIOVec *iov
784	* An array of PRIOVec. PRIOVec is a struct with the following
785	* two fields:
786	* char *iov_base;
787	* int iov_len;
788	* PRInt32 iov_size
789	* Number of elements in the iov array. The value of this
790	* argument must not be greater than PR_MAX_IOVECTOR_SIZE.
791	* If it is, the method will fail (PR_BUFFER_OVERFLOW_ERROR).
792	* PRIntervalTime timeout
793	* Time limit for completion of the entire write operation.
794	* OUTPUTS:
795	* None
796	* RETURN:
797	* A positive number indicates the number of bytes successfully written.
798	* A -1 is an indication that the operation failed. The reason
799	* for the failure is obtained by calling PR_GetError().
800	***************************************************************************
801	*/
802
803	#define PR_MAX_IOVECTOR_SIZE 16 /* 'iov_size' must be <= */
804
805	NSPR_API(PRInt32) PR_Writev(
806	PRFileDesc fd, const PRIOVec iov, PRInt32 iov_size,
807	PRIntervalTime timeout);
808
809	/*
810	***************************************************************************
811	* FUNCTION: PR_Delete
812	* DESCRIPTION:
813	* Delete a file from the filesystem. The operation may fail if the
814	* file is open.
815	* INPUTS:
816	* const char *name
817	* Path name of the file to be deleted.
818	* OUTPUTS:
819	* None.
820	* RETURN: PRStatus
821	* The function returns PR_SUCCESS if the file is successfully
822	* deleted, otherwise it returns PR_FAILURE.
823	***************************************************************************
824	*/
825
826	NSPR_API(PRStatus) PR_Delete(const char *name);
827
828	/**************************************************************************/
829
830	typedef enum PRFileType
831	{
832	PR_FILE_FILE = 1,
833	PR_FILE_DIRECTORY = 2,
834	PR_FILE_OTHER = 3
835	} PRFileType;
836
837	struct PRFileInfo {
838	PRFileType type; /* Type of file */
839	PROffset32 size; /* Size, in bytes, of file's contents */
840	PRTime creationTime; /* Creation time per definition of PRTime */
841	PRTime modifyTime; /* Last modification time per definition of PRTime */
842	};
843
844	struct PRFileInfo64 {
845	PRFileType type; /* Type of file */
846	PROffset64 size; /* Size, in bytes, of file's contents */
847	PRTime creationTime; /* Creation time per definition of PRTime */
848	PRTime modifyTime; /* Last modification time per definition of PRTime */
849	};
850
851	/****************************************************************************
852	* FUNCTION: PR_GetFileInfo, PR_GetFileInfo64
853	* DESCRIPTION:
854	* Get the information about the file with the given path name. This is
855	* applicable only to NSFileDesc describing 'file' types (see
856	* INPUTS:
857	* const char *fn
858	* path name of the file
859	* OUTPUTS:
860	* PRFileInfo *info
861	* Information about the given file is written into the file
862	* information object pointer to by 'info'.
863	* RETURN: PRStatus
864	* PR_GetFileInfo returns PR_SUCCESS if file information is successfully
865	* obtained, otherwise it returns PR_FAILURE.
866	***************************************************************************
867	*/
868
869	NSPR_API(PRStatus) PR_GetFileInfo(const char fn, PRFileInfo info);
870	NSPR_API(PRStatus) PR_GetFileInfo64(const char fn, PRFileInfo64 info);
871
872	/*
873	**************************************************************************
874	* FUNCTION: PR_GetOpenFileInfo, PR_GetOpenFileInfo64
875	* DESCRIPTION:
876	* Get information about an open file referred to by the
877	* given PRFileDesc object.
878	* INPUTS:
879	* const PRFileDesc *fd
880	* A reference to a valid, open file.
881	* OUTPUTS:
882	* Same as PR_GetFileInfo, PR_GetFileInfo64
883	* RETURN: PRStatus
884	* PR_GetFileInfo returns PR_SUCCESS if file information is successfully
885	* obtained, otherwise it returns PR_FAILURE.
886	***************************************************************************
887	*/
888
889	NSPR_API(PRStatus) PR_GetOpenFileInfo(PRFileDesc fd, PRFileInfo info);
890	NSPR_API(PRStatus) PR_GetOpenFileInfo64(PRFileDesc fd, PRFileInfo64 info);
891
892	/*
893	**************************************************************************
894	* FUNCTION: PR_Rename
895	* DESCRIPTION:
896	* Rename a file from the old name 'from' to the new name 'to'.
897	* INPUTS:
898	* const char *from
899	* The old name of the file to be renamed.
900	* const char *to
901	* The new name of the file.
902	* OUTPUTS:
903	* None.
904	* RETURN: PRStatus
905	**************************************************************************
906	*/
907
908	NSPR_API(PRStatus) PR_Rename(const char from, const char to);
909
910	/*
911	*************************************************************************
912	* FUNCTION: PR_Access
913	* DESCRIPTION:
914	* Determine accessibility of a file.
915	* INPUTS:
916	* const char *name
917	* path name of the file
918	* PRAccessHow how
919	* specifies which access permission to check for.
920	* It can be one of the following values:
921	* PR_ACCESS_READ_OK Test for read permission
922	* PR_ACCESS_WRITE_OK Test for write permission
923	* PR_ACCESS_EXISTS Check existence of file
924	* OUTPUTS:
925	* None.
926	* RETURN: PRStatus
927	* PR_SUCCESS is returned if the requested access is permitted.
928	* Otherwise, PR_FAILURE is returned. Additional information
929	* regarding the reason for the failure may be retrieved from
930	* PR_GetError().
931	*************************************************************************
932	*/
933
934	typedef enum PRAccessHow {
935	PR_ACCESS_EXISTS = 1,
936	PR_ACCESS_WRITE_OK = 2,
937	PR_ACCESS_READ_OK = 3
938	} PRAccessHow;
939
940	NSPR_API(PRStatus) PR_Access(const char *name, PRAccessHow how);
941
942	/*
943	*************************************************************************
944	* FUNCTION: PR_Seek, PR_Seek64
945	* DESCRIPTION:
946	* Moves read-write file offset
947	* INPUTS:
948	* PRFileDesc *fd
949	* Pointer to a PRFileDesc object.
950	* PROffset32, PROffset64 offset
951	* Specifies a value, in bytes, that is used in conjunction
952	* with the 'whence' parameter to set the file pointer. A
953	* negative value causes seeking in the reverse direction.
954	* PRSeekWhence whence
955	* Specifies how to interpret the 'offset' parameter in setting
956	* the file pointer associated with the 'fd' parameter.
957	* Values for the 'whence' parameter are:
958	* PR_SEEK_SET Sets the file pointer to the value of the
959	* 'offset' parameter
960	* PR_SEEK_CUR Sets the file pointer to its current location
961	* plus the value of the offset parameter.
962	* PR_SEEK_END Sets the file pointer to the size of the
963	* file plus the value of the offset parameter.
964	* OUTPUTS:
965	* None.
966	* RETURN: PROffset32, PROffset64
967	* Upon successful completion, the resulting pointer location,
968	* measured in bytes from the beginning of the file, is returned.
969	* If the PR_Seek() function fails, the file offset remains
970	* unchanged, and the returned value is -1. The error code can
971	* then be retrieved via PR_GetError().
972	*************************************************************************
973	*/
974
975	NSPR_API(PROffset32) PR_Seek(PRFileDesc *fd, PROffset32 offset, PRSeekWhence whence);
976	NSPR_API(PROffset64) PR_Seek64(PRFileDesc *fd, PROffset64 offset, PRSeekWhence whence);
977
978	/*
979	************************************************************************
980	* FUNCTION: PR_Available
981	* DESCRIPTION:
982	* Determine the amount of data in bytes available for reading
983	* in the given file or socket.
984	* INPUTS:
985	* PRFileDesc *fd
986	* Pointer to a PRFileDesc object that refers to a file or
987	* socket.
988	* OUTPUTS:
989	* None
990	* RETURN: PRInt32, PRInt64
991	* Upon successful completion, PR_Available returns the number of
992	* bytes beyond the current read pointer that is available for
993	* reading. Otherwise, it returns a -1 and the reason for the
994	* failure can be retrieved via PR_GetError().
995	************************************************************************
996	*/
997
998	NSPR_API(PRInt32) PR_Available(PRFileDesc *fd);
999
1000	/*
1001	************************************************************************
1002	* FUNCTION: PR_Sync
1003	* DESCRIPTION:
1004	* Sync any buffered data for a fd to its backing device (disk).
1005	* INPUTS:
1006	* PRFileDesc *fd
1007	* Pointer to a PRFileDesc object that refers to a file or
1008	* socket
1009	* OUTPUTS:
1010	* None
1011	* RETURN: PRStatus
1012	* PR_SUCCESS is returned if the requested access is permitted.
1013	* Otherwise, PR_FAILURE is returned.
1014	************************************************************************
1015	*/
1016
1017	NSPR_API(PRStatus) PR_Sync(PRFileDesc *fd);
1018
1019	/************************************************************************/
1020
1021	struct PRDirEntry {
1022	const char name; / name of entry, relative to directory name */
1023	};
1024
1025	#if !defined(NO_NSPR_10_SUPPORT)
1026	#define PR_DirName(dirEntry) (dirEntry->name)
1027	#endif
1028
1029	/*
1030	*************************************************************************
1031	* FUNCTION: PR_OpenDir
1032	* DESCRIPTION:
1033	* Open the directory by the given name
1034	* INPUTS:
1035	* const char *name
1036	* path name of the directory to be opened
1037	* OUTPUTS:
1038	* None
1039	* RETURN: PRDir *
1040	* If the directory is sucessfully opened, a PRDir object is
1041	* dynamically allocated and a pointer to it is returned.
1042	* If the directory cannot be opened, a NULL pointer is returned.
1043	* MEMORY:
1044	* Upon successful completion, the return value points to
1045	* dynamically allocated memory.
1046	*************************************************************************
1047	*/
1048
1049	NSPR_API(PRDir) PR_OpenDir(const char name);
1050
1051	/*
1052	*************************************************************************
1053	* FUNCTION: PR_ReadDir
1054	* DESCRIPTION:
1055	* INPUTS:
1056	* PRDir *dir
1057	* pointer to a PRDir object that designates an open directory
1058	* PRDirFlags flags
1059	* PR_SKIP_NONE Do not skip any files
1060	* PR_SKIP_DOT Skip the directory entry "." that
1061	* represents the current directory
1062	* PR_SKIP_DOT_DOT Skip the directory entry ".." that
1063	* represents the parent directory.
1064	* PR_SKIP_BOTH Skip both '.' and '..'
1065	* PR_SKIP_HIDDEN Skip hidden files
1066	* OUTPUTS:
1067	* RETURN: PRDirEntry*
1068	* Returns a pointer to the next entry in the directory. Returns
1069	* a NULL pointer upon reaching the end of the directory or when an
1070	* error occurs. The actual reason can be retrieved via PR_GetError().
1071	*************************************************************************
1072	*/
1073
1074	typedef enum PRDirFlags {
1075	PR_SKIP_NONE = 0x0,
1076	PR_SKIP_DOT = 0x1,
1077	PR_SKIP_DOT_DOT = 0x2,
1078	PR_SKIP_BOTH = 0x3,
1079	PR_SKIP_HIDDEN = 0x4
1080	} PRDirFlags;
1081
1082	NSPR_API(PRDirEntry) PR_ReadDir(PRDir dir, PRDirFlags flags);
1083
1084	/*
1085	*************************************************************************
1086	* FUNCTION: PR_CloseDir
1087	* DESCRIPTION:
1088	* Close the specified directory.
1089	* INPUTS:
1090	* PRDir *dir
1091	* The directory to be closed.
1092	* OUTPUTS:
1093	* None
1094	* RETURN: PRStatus
1095	* If successful, will return a status of PR_SUCCESS. Otherwise
1096	* a value of PR_FAILURE. The reason for the failure may be re-
1097	* trieved using PR_GetError().
1098	*************************************************************************
1099	*/
1100
1101	NSPR_API(PRStatus) PR_CloseDir(PRDir *dir);
1102
1103	/*
1104	*************************************************************************
1105	* FUNCTION: PR_MkDir
1106	* DESCRIPTION:
1107	* Create a new directory with the given name and access mode.
1108	* INPUTS:
1109	* const char *name
1110	* The name of the directory to be created. All the path components
1111	* up to but not including the leaf component must already exist.
1112	* PRIntn mode
1113	* See 'mode' definiton in PR_Open().
1114	* OUTPUTS:
1115	* None
1116	* RETURN: PRStatus
1117	* If successful, will return a status of PR_SUCCESS. Otherwise
1118	* a value of PR_FAILURE. The reason for the failure may be re-
1119	* trieved using PR_GetError().
1120	*************************************************************************
1121	*/
1122
1123	NSPR_API(PRStatus) PR_MkDir(const char *name, PRIntn mode);
1124
1125	/*
1126	*************************************************************************
1127	* FUNCTION: PR_MakeDir
1128	* DESCRIPTION:
1129	* Create a new directory with the given name and access mode.
1130	* PR_MakeDir has the same prototype as PR_MkDir but implements
1131	* the specified access mode where possible.
1132	*************************************************************************
1133	*/
1134
1135	NSPR_API(PRStatus) PR_MakeDir(const char *name, PRIntn mode);
1136
1137	/*
1138	*************************************************************************
1139	* FUNCTION: PR_RmDir
1140	* DESCRIPTION:
1141	* Remove a directory by the given name.
1142	* INPUTS:
1143	* const char *name
1144	* The name of the directory to be removed. All the path components
1145	* must already exist. Only the leaf component will be removed.
1146	* OUTPUTS:
1147	* None
1148	* RETURN: PRStatus
1149	* If successful, will return a status of PR_SUCCESS. Otherwise
1150	* a value of PR_FAILURE. The reason for the failure may be re-
1151	* trieved using PR_GetError().
1152	**************************************************************************
1153	*/
1154
1155	NSPR_API(PRStatus) PR_RmDir(const char *name);
1156
1157	/*
1158	*************************************************************************
1159	* FUNCTION: PR_OpenTCPSocket
1160	* DESCRIPTION:
1161	* Create a new TCP socket of the specified address family.
1162	* INPUTS:
1163	* PRIntn af
1164	* Address family
1165	* OUTPUTS:
1166	* None
1167	* RETURN: PRFileDesc*
1168	* Upon successful completion, PR_NewTCPSocket returns a pointer
1169	* to the PRFileDesc created for the newly opened TCP socket.
1170	* Returns a NULL pointer if the creation of a new TCP socket failed.
1171	*
1172	**************************************************************************
1173	*/
1174
1175	NSPR_API(PRFileDesc*) PR_OpenTCPSocket(PRIntn af);
1176
1177	/*
1178	*************************************************************************
1179	* FUNCTION: PR_Connect
1180	* DESCRIPTION:
1181	* Initiate a connection on a socket.
1182	* INPUTS:
1183	* PRFileDesc *fd
1184	* Points to a PRFileDesc object representing a socket
1185	* PRNetAddr *addr
1186	* Specifies the address of the socket in its own communication
1187	* space.
1188	* PRIntervalTime timeout
1189	* Time limit for completion of the connect operation.
1190	* OUTPUTS:
1191	* None
1192	* RETURN: PRStatus
1193	* Upon successful completion of connection initiation, PR_Connect
1194	* returns PR_SUCCESS. Otherwise, it returns PR_FAILURE. Further
1195	* failure information can be obtained by calling PR_GetError().
1196	**************************************************************************
1197	*/
1198
1199	NSPR_API(PRStatus) PR_Connect(
1200	PRFileDesc fd, const PRNetAddr addr, PRIntervalTime timeout);
1201
1202	/*
1203	*************************************************************************
1204	* FUNCTION: PR_ConnectContinue
1205	* DESCRIPTION:
1206	* Continue a nonblocking connect. After a nonblocking connect
1207	* is initiated with PR_Connect() (which fails with
1208	* PR_IN_PROGRESS_ERROR), one should call PR_Poll() on the socket,
1209	* with the in_flags PR_POLL_WRITE \| PR_POLL_EXCEPT. When
1210	* PR_Poll() returns, one calls PR_ConnectContinue() on the
1211	* socket to determine whether the nonblocking connect has
1212	* completed or is still in progress. Repeat the PR_Poll(),
1213	* PR_ConnectContinue() sequence until the nonblocking connect
1214	* has completed.
1215	* INPUTS:
1216	* PRFileDesc *fd
1217	* the file descriptor representing a socket
1218	* PRInt16 out_flags
1219	* the out_flags field of the poll descriptor returned by
1220	* PR_Poll()
1221	* RETURN: PRStatus
1222	* If the nonblocking connect has successfully completed,
1223	* PR_ConnectContinue returns PR_SUCCESS. If PR_ConnectContinue()
1224	* returns PR_FAILURE, call PR_GetError():
1225	* - PR_IN_PROGRESS_ERROR: the nonblocking connect is still in
1226	* progress and has not completed yet. The caller should poll
1227	* on the file descriptor for the in_flags
1228	* PR_POLL_WRITE\|PR_POLL_EXCEPT and retry PR_ConnectContinue
1229	* later when PR_Poll() returns.
1230	* - Other errors: the nonblocking connect has failed with this
1231	* error code.
1232	*/
1233
1234	NSPR_API(PRStatus) PR_ConnectContinue(PRFileDesc *fd, PRInt16 out_flags);
1235
1236	/*
1237	*************************************************************************
1238	* THIS FUNCTION IS DEPRECATED. USE PR_ConnectContinue INSTEAD.
1239	*
1240	* FUNCTION: PR_GetConnectStatus
1241	* DESCRIPTION:
1242	* Get the completion status of a nonblocking connect. After
1243	* a nonblocking connect is initiated with PR_Connect() (which
1244	* fails with PR_IN_PROGRESS_ERROR), one should call PR_Poll()
1245	* on the socket, with the in_flags PR_POLL_WRITE \| PR_POLL_EXCEPT.
1246	* When PR_Poll() returns, one calls PR_GetConnectStatus on the
1247	* PRPollDesc structure to determine whether the nonblocking
1248	* connect has succeeded or failed.
1249	* INPUTS:
1250	* const PRPollDesc *pd
1251	* Pointer to a PRPollDesc whose fd member is the socket,
1252	* and in_flags must contain PR_POLL_WRITE and PR_POLL_EXCEPT.
1253	* PR_Poll() should have been called and set the out_flags.
1254	* RETURN: PRStatus
1255	* If the nonblocking connect has successfully completed,
1256	* PR_GetConnectStatus returns PR_SUCCESS. If PR_GetConnectStatus()
1257	* returns PR_FAILURE, call PR_GetError():
1258	* - PR_IN_PROGRESS_ERROR: the nonblocking connect is still in
1259	* progress and has not completed yet.
1260	* - Other errors: the nonblocking connect has failed with this
1261	* error code.
1262	*/
1263
1264	NSPR_API(PRStatus) PR_GetConnectStatus(const PRPollDesc *pd);
1265
1266	/*
1267	*************************************************************************
1268	* FUNCTION: PR_Accept
1269	* DESCRIPTION:
1270	* Accept a connection on a socket.
1271	* INPUTS:
1272	* PRFileDesc *fd
1273	* Points to a PRFileDesc object representing the rendezvous socket
1274	* on which the caller is willing to accept new connections.
1275	* PRIntervalTime timeout
1276	* Time limit for completion of the accept operation.
1277	* OUTPUTS:
1278	* PRNetAddr *addr
1279	* Returns the address of the connecting entity in its own
1280	* communication space. It may be NULL.
1281	* RETURN: PRFileDesc*
1282	* Upon successful acceptance of a connection, PR_Accept
1283	* returns a valid file descriptor. Otherwise, it returns NULL.
1284	* Further failure information can be obtained by calling PR_GetError().
1285	**************************************************************************
1286	*/
1287
1288	NSPR_API(PRFileDesc*) PR_Accept(
1289	PRFileDesc fd, PRNetAddr addr, PRIntervalTime timeout);
1290
1291	/*
1292	*************************************************************************
1293	* FUNCTION: PR_Bind
1294	* DESCRIPTION:
1295	* Bind an address to a socket.
1296	* INPUTS:
1297	* PRFileDesc *fd
1298	* Points to a PRFileDesc object representing a socket.
1299	* PRNetAddr *addr
1300	* Specifies the address to which the socket will be bound.
1301	* OUTPUTS:
1302	* None
1303	* RETURN: PRStatus
1304	* Upon successful binding of an address to a socket, PR_Bind
1305	* returns PR_SUCCESS. Otherwise, it returns PR_FAILURE. Further
1306	* failure information can be obtained by calling PR_GetError().
1307	**************************************************************************
1308	*/
1309
1310	NSPR_API(PRStatus) PR_Bind(PRFileDesc fd, const PRNetAddr addr);
1311
1312	/*
1313	*************************************************************************
1314	* FUNCTION: PR_Listen
1315	* DESCRIPTION:
1316	* Listen for connections on a socket.
1317	* INPUTS:
1318	* PRFileDesc *fd
1319	* Points to a PRFileDesc object representing a socket that will be
1320	* used to listen for new connections.
1321	* PRIntn backlog
1322	* Specifies the maximum length of the queue of pending connections.
1323	* OUTPUTS:
1324	* None
1325	* RETURN: PRStatus
1326	* Upon successful completion of listen request, PR_Listen
1327	* returns PR_SUCCESS. Otherwise, it returns PR_FAILURE. Further
1328	* failure information can be obtained by calling PR_GetError().
1329	**************************************************************************
1330	*/
1331
1332	NSPR_API(PRStatus) PR_Listen(PRFileDesc *fd, PRIntn backlog);
1333
1334	/*
1335	*************************************************************************
1336	* FUNCTION: PR_Shutdown
1337	* DESCRIPTION:
1338	* Shut down part of a full-duplex connection on a socket.
1339	* INPUTS:
1340	* PRFileDesc *fd
1341	* Points to a PRFileDesc object representing a connected socket.
1342	* PRIntn how
1343	* Specifies the kind of disallowed operations on the socket.
1344	* PR_SHUTDOWN_RCV - Further receives will be disallowed
1345	* PR_SHUTDOWN_SEND - Further sends will be disallowed
1346	* PR_SHUTDOWN_BOTH - Further sends and receives will be disallowed
1347	* OUTPUTS:
1348	* None
1349	* RETURN: PRStatus
1350	* Upon successful completion of shutdown request, PR_Shutdown
1351	* returns PR_SUCCESS. Otherwise, it returns PR_FAILURE. Further
1352	* failure information can be obtained by calling PR_GetError().
1353	**************************************************************************
1354	*/
1355
1356	typedef enum PRShutdownHow
1357	{
1358	PR_SHUTDOWN_RCV = 0, /* disallow further receives */
1359	PR_SHUTDOWN_SEND = 1, /* disallow further sends */
1360	PR_SHUTDOWN_BOTH = 2 /* disallow further receives and sends */
1361	} PRShutdownHow;
1362
1363	NSPR_API(PRStatus) PR_Shutdown(PRFileDesc *fd, PRShutdownHow how);
1364
1365	/*
1366	*************************************************************************
1367	* FUNCTION: PR_Recv
1368	* DESCRIPTION:
1369	* Receive a specified number of bytes from a connected socket.
1370	* The operation will block until some positive number of bytes are
1371	* transferred, a time out has occurred, or there is an error.
1372	* No more than 'amount' bytes will be transferred.
1373	* INPUTS:
1374	* PRFileDesc *fd
1375	* points to a PRFileDesc object representing a socket.
1376	* void *buf
1377	* pointer to a buffer to hold the data received.
1378	* PRInt32 amount
1379	* the size of 'buf' (in bytes)
1380	* PRIntn flags
1381	* must be zero or PR_MSG_PEEK.
1382	* PRIntervalTime timeout
1383	* Time limit for completion of the receive operation.
1384	* OUTPUTS:
1385	* None
1386	* RETURN: PRInt32
1387	* a positive number indicates the number of bytes actually received.
1388	* 0 means the network connection is closed.
1389	* -1 indicates a failure. The reason for the failure is obtained
1390	* by calling PR_GetError().
1391	**************************************************************************
1392	*/
1393
1394	#define PR_MSG_PEEK 0x2
1395
1396	NSPR_API(PRInt32) PR_Recv(PRFileDesc fd, void buf, PRInt32 amount,
1397	PRIntn flags, PRIntervalTime timeout);
1398
1399	/*
1400	*************************************************************************
1401	* FUNCTION: PR_Send
1402	* DESCRIPTION:
1403	* Send a specified number of bytes from a connected socket.
1404	* The operation will block until all bytes are
1405	* processed, a time out has occurred, or there is an error.
1406	* INPUTS:
1407	* PRFileDesc *fd
1408	* points to a PRFileDesc object representing a socket.
1409	* void *buf
1410	* pointer to a buffer from where the data is sent.
1411	* PRInt32 amount
1412	* the size of 'buf' (in bytes)
1413	* PRIntn flags
1414	* (OBSOLETE - must always be zero)
1415	* PRIntervalTime timeout
1416	* Time limit for completion of the send operation.
1417	* OUTPUTS:
1418	* None
1419	* RETURN: PRInt32
1420	* A positive number indicates the number of bytes successfully processed.
1421	* This number must always equal 'amount'. A -1 is an indication that the
1422	* operation failed. The reason for the failure is obtained by calling
1423	* PR_GetError().
1424	**************************************************************************
1425	*/
1426
1427	NSPR_API(PRInt32) PR_Send(PRFileDesc fd, const void buf, PRInt32 amount,
1428	PRIntn flags, PRIntervalTime timeout);
1429
1430	/*
1431	*************************************************************************
1432	** FUNCTION: PR_GetSockName
1433	** DESCRIPTION:
1434	** Get socket name. Return the network address for this socket.
1435	**
1436	** INPUTS:
1437	** PRFileDesc *fd
1438	** Points to a PRFileDesc object representing the socket.
1439	** OUTPUTS:
1440	** PRNetAddr *addr
1441	** Returns the address of the socket in its own communication space.
1442	** RETURN: PRStatus
1443	** Upon successful completion, PR_GetSockName returns PR_SUCCESS.
1444	** Otherwise, it returns PR_FAILURE. Further failure information can
1445	** be obtained by calling PR_GetError().
1446	**************************************************************************
1447	**/
1448	NSPR_API(PRStatus) PR_GetSockName(PRFileDesc fd, PRNetAddr addr);
1449
1450	/*
1451	*************************************************************************
1452	** FUNCTION: PR_GetPeerName
1453	** DESCRIPTION:
1454	** Get name of the connected peer. Return the network address for the
1455	** connected peer socket.
1456	**
1457	** INPUTS:
1458	** PRFileDesc *fd
1459	** Points to a PRFileDesc object representing the connected peer.
1460	** OUTPUTS:
1461	** PRNetAddr *addr
1462	** Returns the address of the connected peer in its own communication
1463	** space.
1464	** RETURN: PRStatus
1465	** Upon successful completion, PR_GetPeerName returns PR_SUCCESS.
1466	** Otherwise, it returns PR_FAILURE. Further failure information can
1467	** be obtained by calling PR_GetError().
1468	**************************************************************************
1469	**/
1470	NSPR_API(PRStatus) PR_GetPeerName(PRFileDesc fd, PRNetAddr addr);
1471
1472	NSPR_API(PRStatus) PR_GetSocketOption(
1473	PRFileDesc fd, PRSocketOptionData data);
1474
1475	NSPR_API(PRStatus) PR_SetSocketOption(
1476	PRFileDesc fd, const PRSocketOptionData data);
1477
1478	/*
1479	*********************************************************************
1480	*
1481	* File descriptor inheritance
1482	*
1483	*********************************************************************
1484	*/
1485
1486	/*
1487	************************************************************************
1488	* FUNCTION: PR_SetFDInheritable
1489	* DESCRIPTION:
1490	* Set the inheritance attribute of a file descriptor.
1491	*
1492	* INPUTS:
1493	* PRFileDesc *fd
1494	* Points to a PRFileDesc object.
1495	* PRBool inheritable
1496	* If PR_TRUE, the file descriptor fd is set to be inheritable
1497	* by a child process. If PR_FALSE, the file descriptor is set
1498	* to be not inheritable by a child process.
1499	* RETURN: PRStatus
1500	* Upon successful completion, PR_SetFDInheritable returns PR_SUCCESS.
1501	* Otherwise, it returns PR_FAILURE. Further failure information can
1502	* be obtained by calling PR_GetError().
1503	*************************************************************************
1504	*/
1505	NSPR_API(PRStatus) PR_SetFDInheritable(
1506	PRFileDesc *fd,
1507	PRBool inheritable);
1508
1509	/*
1510	************************************************************************
1511	* FUNCTION: PR_GetInheritedFD
1512	* DESCRIPTION:
1513	* Get an inherited file descriptor with the specified name.
1514	*
1515	* INPUTS:
1516	* const char *name
1517	* The name of the inherited file descriptor.
1518	* RETURN: PRFileDesc *
1519	* Upon successful completion, PR_GetInheritedFD returns the
1520	* inherited file descriptor with the specified name. Otherwise,
1521	* it returns NULL. Further failure information can be obtained
1522	* by calling PR_GetError().
1523	*************************************************************************
1524	*/
1525	NSPR_API(PRFileDesc ) PR_GetInheritedFD(const char name);
1526
1527	/*
1528	******************************************************************
1529	*
1530	* Interprocess communication
1531	*
1532	******************************************************************
1533	*/
1534
1535	/*
1536	* Creates an anonymous pipe and returns file descriptors for the
1537	* read and write ends of the pipe.
1538	*/
1539
1540	NSPR_API(PRStatus) PR_CreatePipe(
1541	PRFileDesc **readPipe,
1542	PRFileDesc **writePipe
1543	);
1544
1545	/************************************************************************/
1546	/************ The following definitions are for poll ****************/
1547	/************************************************************************/
1548
1549	struct PRPollDesc {
1550	PRFileDesc* fd;
1551	PRInt16 in_flags;
1552	PRInt16 out_flags;
1553	};
1554
1555	/*
1556	** Bit values for PRPollDesc.in_flags or PRPollDesc.out_flags. Binary-or
1557	** these together to produce the desired poll request.
1558	*/
1559
1560	#if defined(_PR_POLL_BACKCOMPAT)
1561
1562	#include <poll.h>
1563	#define PR_POLL_READ POLLIN
1564	#define PR_POLL_WRITE POLLOUT
1565	#define PR_POLL_EXCEPT POLLPRI
1566	#define PR_POLL_ERR POLLERR /* only in out_flags */
1567	#define PR_POLL_NVAL POLLNVAL /* only in out_flags when fd is bad */
1568	#define PR_POLL_HUP POLLHUP /* only in out_flags */
1569
1570	#else /* _PR_POLL_BACKCOMPAT */
1571
1572	#define PR_POLL_READ 0x1
1573	#define PR_POLL_WRITE 0x2
1574	#define PR_POLL_EXCEPT 0x4
1575	#define PR_POLL_ERR 0x8 /* only in out_flags */
1576	#define PR_POLL_NVAL 0x10 /* only in out_flags when fd is bad */
1577	#define PR_POLL_HUP 0x20 /* only in out_flags */
1578
1579	#endif /* _PR_POLL_BACKCOMPAT */
1580
1581	/*
1582	*************************************************************************
1583	** FUNCTION: PR_Poll
1584	** DESCRIPTION:
1585	**
1586	** The call returns as soon as I/O is ready on one or more of the underlying
1587	** socket objects. A count of the number of ready descriptors is
1588	** returned unless a timeout occurs in which case zero is returned.
1589	**
1590	** PRPollDesc.fd should be set to a pointer to a PRFileDesc object
1591	** representing a socket. This field can be set to NULL to indicate to
1592	** PR_Poll that this PRFileDesc object should be ignored.
1593	** PRPollDesc.in_flags should be set to the desired request
1594	** (read/write/except or some combination). Upon successful return from
1595	** this call PRPollDesc.out_flags will be set to indicate what kind of
1596	** i/o can be performed on the respective descriptor. PR_Poll() uses the
1597	** out_flags fields as scratch variables during the call. If PR_Poll()
1598	** returns 0 or -1, the out_flags fields do not contain meaningful values
1599	** and must not be used.
1600	**
1601	** INPUTS:
1602	** PRPollDesc *pds A pointer to an array of PRPollDesc
1603	**
1604	** PRIntn npds The number of elements in the array
1605	** If this argument is zero PR_Poll is
1606	** equivalent to a PR_Sleep(timeout).
1607	**
1608	** PRIntervalTime timeout Amount of time the call will block waiting
1609	** for I/O to become ready. If this time expires
1610	** w/o any I/O becoming ready, the result will
1611	** be zero.
1612	**
1613	** OUTPUTS: None
1614	** RETURN:
1615	** PRInt32 Number of PRPollDesc's with events or zero
1616	** if the function timed out or -1 on failure.
1617	** The reason for the failure is obtained by
1618	** calling PR_GetError().
1619	**************************************************************************
1620	*/
1621	NSPR_API(PRInt32) PR_Poll(
1622	PRPollDesc *pds, PRIntn npds, PRIntervalTime timeout);
1623
1624	PR_END_EXTERN_C
1625
1626	#endif /* prio_h___ */

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

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

Download in other formats: