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