prio.h@ 101948

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

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

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

Download in other formats: