| blob | a892d5f39d389abaa4db8bb2ad44aa877e21f1f1 |
1 /****** bsdsocket.library/accept ********************************************
2 *
3 * NAME
4 * accept - accept a connection on a socket
5 *
6 * SYNOPSIS
7 * #include <sys/types.h>
8 * #include <sys/socket.h>
9 *
10 * ns = accept(s, addr, addrlen)
11 * D0 D0 A0 A1
12 *
13 * long accept(long, struct sockaddr *, long *);
14 *
15 * FUNCTION
16 * The argument s is a socket that has been created with
17 * socket(), bound to an address with bind(), and is listen-
18 * ing for connections after a listen(). accept() extracts the
19 * first connection on the queue of pending connections,
20 * creates a new socket with the same properties of s and allo-
21 * cates a new socket descriptor for the socket. If no pending
22 * connections are present on the queue, and the socket is not
23 * marked as non-blocking, accept() blocks the caller until a
24 * connection is present. If the socket is marked non-blocking
25 * and no pending connections are present on the queue,
26 * accept() returns an error as described below. The accepted
27 * socket is used to read and write data to and from the socket
28 * which connected to this one; it is not used to accept more
29 * connections. The original socket s remains open for accept-
30 * ing further connections.
31 *
32 * The argument addr is a result parameter that is filled in
33 * with the address of the connecting entity, as known to the
34 * communications layer. The exact format of the addr parame-
35 * ter is determined by the domain in which the communication
36 * is occurring. The addrlen is a value-result parameter; it
37 * should initially contain the amount of space pointed to by
38 * addr; on return it will contain the actual length (in bytes)
39 * of the address returned. This call is used with
40 * connection-based socket types, currently with SOCK_STREAM.
41 *
42 * It is possible to select() a socket for the purposes of
43 * doing an accept() by selecting it for read.
44 *
45 * RETURN VALUES
46 * accept() returns a non-negative descriptor for the accepted
47 * socket on success. On failure, it returns -1 and sets errno
48 * to indicate the error.
49 *
50 * ERRORS
51 * EBADF - The descriptor is invalid.
52 *
53 * EINTR - The operation was interrupted by a break
54 * signal.
55 *
56 * EOPNOTSUPP - The referenced socket is not of type
57 * SOCK_STREAM.
58 *
59 * EWOULDBLOCK - The socket is marked non-blocking and no con-
60 * nections are present to be accepted.
61 *
62 * SEE ALSO
63 * bind(), connect(), listen(), select(), SetSocketSignals(),
64 * socket()
65 *****************************************************************************
66 *
67 */
68 \f
69 /****** bsdsocket.library/bind **********************************************
70 *
71 * NAME
72 * bind - bind a name to a socket
73 *
74 * SYNOPSIS
75 * #include <sys/types.h>
76 * #include <sys/socket.h>
77 *
78 * success = bind(s, name, namelen)
79 * D0 D0 A0 D1
80 *
81 * long bind(long, struct sockaddr *, long);
82 *
83 * FUNCTION
84 * bind() assigns a name to an unnamed socket. When a socket
85 * is created with socket(2) it exists in a name space (address
86 * family) but has no name assigned. bind() requests that the
87 * name pointed to by name be assigned to the socket.
88 *
89 * RETURN VALUES
90 * 0 - on success.
91 *
92 * -1 - on failure and sets errno to indicate the error.
93 *
94 * ERRORS
95 * EACCES - The requested address is protected, and
96 * the current user has inadequate permis-
97 * sion to access it.
98 *
99 * EADDRINUSE - The specified address is already in use.
100 *
101 * EADDRNOTAVAIL - The specified address is not available
102 * from the local machine.
103 *
104 * EBADF - s is not a valid descriptor.
105 *
106 * EINVAL - namelen is not the size of a valid
107 * address for the specified address fam-
108 * ily.
109 *
110 * The socket is already bound to an
111 * address.
112 *
113 * SEE ALSO
114 * connect(), getsockname(), listen(), socket()
115 *
116 * NOTES
117 * The rules used in name binding vary between communication
118 * domains.
119 *****************************************************************************
120 *
121 */
124 /****** bsdsocket.library/CloseSocket ***************************************
125 *
126 * NAME
127 * CloseSocket - delete a socket descriptor
128 *
129 * SYNOPSIS
130 * success = CloseSocket(s)
131 * D0 D0
132 *
133 * long CloseSocket(long);
134 *
135 * FUNCTION
136 * CloseSocket() deletes a descriptor from the library base
137 * socket reference table. If s is the last reference to the
138 * underlying object, then the object will be deactivated and
139 * socket (see socket()), associated naming information and
140 * queued data are discarded.
141 *
142 * All sockets are automatically closed when the socket library
143 * is closed, but closing sockets as soon as possible is
144 * recommended to save system resources.
145 *
146 * RETURN VALUES
147 * 0 on success.
148 *
149 * -1 on failure and sets errno to indicate the error.
150 *
151 * ERRORS
152 * EBADF - s is not an active socket descriptor.
153 *
154 * EINTR - linger on close was interrupted.
155 * The socket is closed, however.
156 *
157 * SEE ALSO
158 * accept(), SocketBaseTagList(), shutdown(), socket(),
159 * exec.library/CloseLibrary()
160 *****************************************************************************
161 *
162 */
166 /****** bsdsocket.library/connect *******************************************
167 *
168 * NAME
169 * connect - initiate a connection on a socket
170 *
171 * SYNOPSIS
172 * #include <sys/types.h>
173 * #include <sys/socket.h>
174 *
175 * success = connect(s, name, namelen)
176 * D0 D0 A0 D1
177 *
178 * long connect(long, struct sockaddr *, long);
179 *
180 * FUNCTION
181 * The parameter s is a socket. If it is of type SOCK_DGRAM,
182 * then this call specifies the peer with which the socket is
183 * to be associated; this address is that to which datagrams
184 * are to be sent, and the only address from which datagrams
185 * are to be received. If it is of type SOCK_STREAM, then this
186 * call attempts to make a connection to another socket. The
187 * other socket is specified by name which is an address in the
188 * communications space of the socket. Each communications
189 * space interprets the name parameter in its own way. Gen-
190 * erally, stream sockets may successfully connect() only once;
191 * datagram sockets may use connect() multiple times to change
192 * their association. Datagram sockets may dissolve the asso-
193 * ciation by connecting to an invalid address, such as a null
194 * address.
195 *
196 * RETURN VALUES
197 * 0 on success.
198 *
199 * -1 on failure and sets errno to indicate the error.
200 *
201 * ERRORS
202 * EADDRINUSE - The address is already in use.
203 *
204 * EADDRNOTAVAIL - The specified address is not available
205 * on the remote machine.
206 *
207 * EAFNOSUPPORT - Addresses in the specified address fam-
208 * ily cannot be used with this socket.
209 *
210 * EALREADY - The socket is non-blocking and a previ-
211 * ous connection attempt has not yet been
212 * completed.
213 *
214 * EBADF - s is not a valid descriptor.
215 *
216 * ECONNREFUSED - The attempt to connect was forcefully
217 * rejected. The calling program should
218 * CloseSocket() the socket descriptor, and
219 * issue another socket() call to obtain a
220 * new descriptor before attempting another
221 * connect() call.
222 *
223 * EINPROGRESS - The socket is non-blocking and the con-
224 * nection cannot be completed immediately.
225 * It is possible to select() for comple-
226 * tion by selecting the socket for writ-
227 * ing.
228 *
229 * EINTR - The operation was interrupted by a break
230 * signal.
231 *
232 * EINVAL - namelen is not the size of a valid
233 * address for the specified address fam-
234 * ily.
235 *
236 * EISCONN The socket is already connected.
237 *
238 * ENETUNREACH - The network is not reachable from this
239 * host.
240 *
241 * ETIMEDOUT - Connection establishment timed out
242 * without establishing a connection.
243 *
244 * SEE ALSO
245 * accept(), CloseSocket(), connect(), getsockname(), select(),
246 * socket()
247 *****************************************************************************
248 *
249 */
252 /****** bsdsocket.library/Dup2Socket *****************************************
253 *
254 * NAME
255 * Dup2Socket - duplicate a socket descriptor
256 *
257 * SYNOPSIS
258 *
259 * newfd = Dup2Socket(fd1, fd2)
260 * D0 D0 D1
261 *
262 * long Dup2Socket(long, long);
263 *
264 * DESCRIPTION
265 * Dup2Socket() duplicates an existing socket descriptor.
266 * the argument fd1 is small non-negative value that indexes
267 * the socket on SocketBase descriptor table. The value must
268 * be less than the size of the table, which is returned by
269 * getdtablesize(). fd2 specifies the desired value of the new
270 * descriptor. If descriptor fd2 is already in use, it is
271 * first deallocated as if it were closed by CloseSocket(). If
272 * the value if fd2 is -1, the new descriptor used and returned
273 * is the lowest numbered descriptor that is not currently in
274 * use by the SocketBase.
275 *
276 * Dup2Socket() has also an feature to mark a file descriptor as
277 * being used. If fd1 is given as -1, fd2 is marked as being used
278 * socket descriptor table and it won't be allocated for any
279 * socket. This mark can be removed using CloseSocket() call.
280 *
281 * RETURN VALUES
282 * Dup2Socket() returns a new descriptor on success. On failure
283 * -1 is returned and errno is set to indicate the error.
284 *
285 * ERRORS
286 * EBADF fd1 or fd2 is not a valid active descriptor.
287 *
288 * EMFILE Too many descriptors are active.
289 *
290 * SEE ALSO
291 * accept(), CloseSocket(), getdtablesize(), SocketBaseTagList(),
292 * socket()
293 *
294 *****************************************************************************
295 *
296 */
299 /****** bsdsocket.library/getpeername ***************************************
300 *
301 * NAME
302 * getpeername - get name of connected peer
303 *
304 * SYNOPSIS
305 * success = getpeername(s, name, namelen)
306 * D0 D0 A0 A1
307 *
308 * long getpeername(long, struct sockaddr *, long *);
309 *
310 * FUNCTION
311 * getpeername() returns the name of the peer connected to
312 * socket s. The long pointed to by the namelen parameter
313 * should be initialized to indicate the amount of space
314 * pointed to by name. On return it contains the actual size
315 * of the name returned (in bytes). The name is truncated if
316 * the buffer provided is too small.
317 *
318 * RETURN VALUE
319 * A 0 is returned if the call succeeds, -1 if it fails.
320 *
321 * ERRORS
322 * EBADF - The argument s is not a valid descriptor.
323 *
324 * ENOBUFS - Insufficient resources were available in the
325 * system to perform the operation.
326 *
327 * ENOTCONN - The socket is not connected.
328 *
329 * SEE ALSO
330 * accept(), bind(), getsockname(), socket()
331 *****************************************************************************
332 *
333 */
336 /****** bsdsocket.library/getsockname ***************************************
337 *
338 * NAME
339 * getsockname - get socket name
340 *
341 * SYNOPSIS
342 *
343 * success = getsockname(s, name, namelen)
344 * D0 D0 A0 A1
345 *
346 * long getsockname(long, struct sockaddr *, long *);
347 *
348 * FUNCTION
349 * getsockname() returns the current name for the specified
350 * socket. The namelen parameter should be initialized to
351 * indicate the amount of space pointed to by name. On return
352 * it contains the actual size of the name returned (in bytes).
353 *
354 * DIAGNOSTICS
355 * A 0 is returned if the call succeeds, -1 if it fails.
356 *
357 * ERRORS
358 * The call succeeds unless:
359 *
360 * EBADF s is not a valid descriptor.
361 *
362 * ENOBUFS Insufficient resources were available in the
363 * system to perform the operation.
364 *
365 * SEE ALSO
366 * bind(), getpeername(), socket()
367 *****************************************************************************
368 *
369 */
372 /****** bsdsocket.library/getsockopt ****************************************
373 *
374 * NAME
375 * getsockopt, setsockopt - get and set options on sockets
376 *
377 * SYNOPSIS
378 * #include <sys/types.h>
379 * #include <sys/socket.h>
380 *
381 * success = getsockopt(s, level, optname, optval, optlen)
382 * D0 D0 D1 D2 A0 A1
383 *
384 * long getsockopt(long, long, long, caddr_t, long *);
385 *
386 * success = setsockopt(s, level, optname, optval, optlen)
387 * D0 D0 D1 D2 A0 D3
388 *
389 * long setsockopt(long, long, long, caddr_t, long);
390 *
391 * FUNCTION
392 * getsockopt() and setsockopt() manipulate options associated
393 * with a socket. Options may exist at multiple protocol lev-
394 * els; they are always present at the uppermost ``socket''
395 * level.
396 *
397 * When manipulating socket options the level at which the
398 * option resides and the name of the option must be specified.
399 * To manipulate options at the ``socket'' level, level is
400 * specified as SOL_SOCKET. To manipulate options at any other
401 * level the protocol number of the appropriate protocol con-
402 * trolling the option is supplied. For example, to indicate
403 * that an option is to be interpreted by the TCP protocol,
404 * level should be set to the protocol number of TCP.
405 *
406 * The parameters optval and optlen are used to access option
407 * values for setsockopt(). For getsockopt() they identify a
408 * buffer in which the value for the requested option(s) are to
409 * be returned. For getsockopt(), optlen is a value-result
410 * parameter, initially containing the size of the buffer
411 * pointed to by optval, and modified on return to indicate the
412 * actual size of the value returned. If no option value is to
413 * be supplied or returned, optval may be supplied as 0.
414 *
415 * optname and any specified options are passed uninterpreted
416 * to the appropriate protocol module for interpretation. The
417 * include file <sys/socket.h> contains definitions for
418 * ``socket'' level options, described below. Options at other
419 * protocol levels vary in format and name.
420 *
421 * Most socket-level options take an int parameter for optval.
422 * For setsockopt(), the parameter should be non-zero to enable
423 * a boolean option, or zero if the option is to be disabled.
424 *
425 * SO_LINGER uses a struct linger parameter, defined in
426 * <sys/socket.h>, which specifies the desired state of the
427 * option and the linger interval (see below).
428 *
429 * The following options are recognized at the socket level.
430 * Except as noted, each may be examined with getsockopt() and
431 * set with setsockopt().
432 *
433 * SO_DEBUG - toggle recording of debugging
434 * information
435 * SO_REUSEADDR - toggle local address reuse
436 * SO_KEEPALIVE - toggle keep connections alive
437 * SO_DONTROUTE - toggle routing bypass for outgoing
438 * messages
439 * SO_LINGER - linger on close if data present
440 * SO_BROADCAST - toggle permission to transmit
441 * broadcast messages
442 * SO_OOBINLINE - toggle reception of out-of-band
443 * data in band
444 * SO_SNDBUF - set buffer size for output
445 * SO_RCVBUF - set buffer size for input
446 * SO_TYPE - get the type of the socket (get
447 * only)
448 * SO_ERROR - get and clear error on the socket
449 * (get only)
450 *
451 * SO_DEBUG enables debugging in the underlying protocol
452 * modules. SO_REUSEADDR indicates that the rules used in
453 * validating addresses supplied in a bind() call should allow
454 * reuse of local addresses. SO_KEEPALIVE enables the periodic
455 * transmission of messages on a connected socket. Should the
456 * connected party fail to respond to these messages, the con-
457 * nection is considered broken. If the process is
458 * waiting in select() when the connection is broken, select()
459 * returns true for any read or write events selected for the
460 * socket. SO_DONTROUTE indicates that outgoing messages
461 * should bypass the standard routing facilities. Instead,
462 * messages are directed to the appropriate network interface
463 * according to the network portion of the destination address.
464 *
465 * SO_LINGER controls the action taken when unsent messags are
466 * queued on socket and a CloseSocket() is performed. If the
467 * socket promises reliable delivery of data and SO_LINGER is
468 * set, the system will block the process on the close
469 * attempt until it is able to transmit the data or until it
470 * decides it is unable to deliver the information (a timeout
471 * period, in seconds, termed the linger interval, is specified
472 * in the set- sockopt() call when SO_LINGER is requested). If
473 * SO_LINGER is disabled and a CloseSocket() is issued, the
474 * system will process the close in a manner that allows the
475 * process to continue as quickly as possible.
476 *
477 * The option SO_BROADCAST requests permission to send broad-
478 * cast datagrams on the socket. Broadcast was a privileged
479 * operation in earlier versions of the system. With protocols
480 * that support out-of-band data, the SO_OOBINLINE option
481 * requests that out-of-band data be placed in the normal data
482 * input queue as received; it will then be accessible with
483 * recv() or read() calls without the MSG_OOB flag. SO_SNDBUF
484 * and SO_RCVBUF are options to adjust the normal buffer sizes
485 * allocated for output and input buffers, respectively. The
486 * buffer size may be increased for high-volume connections, or
487 * may be decreased to limit the possible backlog of incoming
488 * data. The system places an absolute limit on these values.
489 * Finally, SO_TYPE and SO_ERROR are options used only with
490 * getsockopt(). SO_TYPE returns the type of the socket, such
491 * as SOCK_STREAM; it is useful for servers that inherit sock-
492 * ets on startup. SO_ERROR returns any pending error on the
493 * socket and clears the error status. It may be used to check
494 * for asynchronous errors on connected datagram sockets or for
495 * other asynchronous errors.
496 *
497 * RETURN VALUES
498 * 0 - on success.
499 *
500 * -1 - on failure and set errno to indicate the error.
501 *
502 * ERRORS
503 * EBADF - s is not a valid descriptor.
504 *
505 * ENOPROTOOPT - The option is unknown at the level indi-
506 * cated.
507 *
508 * SEE ALSO
509 * IoctlSocket(), socket()
510 *
511 * BUGS
512 * Several of the socket options should be handled at lower
513 * levels of the system.
514 *****************************************************************************
515 *
516 */
519 /****** bsdsocket.library/IoctlSocket ***************************************
520 *
521 * NAME
522 * IoctlSocket - control sockets
523 *
524 * SYNOPSIS
525 *
526 * #include <sys/types.h>
527 * #include <sys/ioctl.h>
528 *
529 * value = IoctlSocket(fd, request, arg)
530 * D0 D0 D1 A0
531 *
532 * long IoctlSocket(long, long, caddr_t);
533 *
534 * FUNCTION
535 * IoctlSocket() performs a special function on the object referred
536 * to by the open socket descriptor fd. Note: the setsockopt()
537 * call (see getsockopt()) is the primary method for operating
538 * on sockets as such, rather than on the underlying protocol
539 * or network interface.
540 *
541 * For most IoctlSocket() functions, arg is a pointer to data to
542 * be used by the function or to be filled in by the function.
543 * Other functions may ignore arg or may treat it directly as a
544 * data item; they may, for example, be passed an int value.
545 *
546 * The following requests are supported:
547 *
548 *
549 * FIOASYNC The argument is a pointer to a long.
550 * Set or clear asynchronous I/O. If the
551 * value of that long is a 1 (one) the
552 * descriptor is set for asynchronous I/O.
553 * If the value of that long is a 0 (zero)
554 * the descriptor is cleared for asynchro-
555 * nous I/O.
556 *
557 * FIOCLEX
558 * FIONCLEX Ignored, no use for close-on-exec flag
559 * in Amiga.
560 *
561 * FIOGETOWN
562 * SIOCGPGRP The argument is pointer to struct Task*.
563 * Set the value of that pointer to the
564 * Task that is receiving SIGIO or SIGURG
565 * signals for the socket referred to by
566 * the descriptor passed to IoctlSocket().
567 *
568 * FIONBIO The argument is a pointer to a long.
569 * Set or clear non-blocking I/O. If the
570 * value of that long is a 1 (one) the
571 * descriptor is set for non-blocking I/O.
572 * If the value of that long is a 0 (zero)
573 * the descriptor is cleared for non-
574 * blocking I/O.
575 *
576 * FIONREAD The argument is a pointer to a long.
577 * Set the value of that long to the number
578 * of immediately readable characters from
579 * the socket fd.
580 *
581 * FIOSETOWN
582 * SIOCSPGRP The argument is pointer to struct Task*,
583 * pointer to the task that will subseq-
584 * uently receive SIGIO or SIGURG signals
585 * for the socket referred to by the
586 * descriptor passed.
587 *
588 * SIOCCATMARK The argument is a pointer to a long.
589 * Set the value of that long to 1 if the
590 * read pointer for the socket referred to
591 * by the descriptor passed to
592 * IoctlSocket() points to a mark in the
593 * data stream for an out-of-band message,
594 * and to 0 if it does not point to a mark.
595 *
596 *
597 * RETURN VALUES
598 * IoctlSocket() returns 0 on success for most requests. Some
599 * specialized requests may return non-zero values on success; On
600 * failure, IoctlSocket() returns -1 and sets errno to indicate
601 * the error.
602 *
603 * ERRORS
604 * EBADF fd is not a valid descriptor.
605 *
606 * EINVAL request or arg is not valid.
607 *
608 * IoctlSocket() will also fail if the object on which the function
609 * is being performed detects an error. In this case, an error
610 * code specific to the object and the function will be
611 * returned.
612 *
613 * SEE ALSO
614 * getsockopt(), SocketBaseTagList(), setsockopt()
615 *****************************************************************************
616 *
617 */
620 /****** bsdsocket.library/listen ********************************************
621 * NAME
622 * listen - listen for connections on a socket
623 *
624 * SYNOPSIS
625 * success = listen(s, backlog)
626 * D0 D0 D1
627 *
628 * long listen(long, long);
629 *
630 * FUNCTION
631 * To accept connections, a socket is first created with
632 * socket(), a backlog for incoming connections is specified
633 * with listen() and then the connections are accepted with
634 * accept(). The listen() call applies only to socket of
635 * type SOCK_STREAM.
636 *
637 * The backlog parameter defines the maximum length the queue
638 * of pending connections may grow to. If a connection request
639 * arrives with the queue full the client will receive an error
640 * with an indication of ECONNREFUSED.
641 *
642 * RETURN VALUES
643 * 0 on success.
644 *
645 * -1 on failure and sets errno to indicate the error.
646 *
647 * ERRORS
648 * EBADF - s is not a valid descriptor.
649 *
650 * EOPNOTSUPP - The socket is not of a type that sup-
651 * ports listen().
652 *
653 * SEE ALSO
654 * accept(), connect(), socket()
655 *
656 * BUGS
657 * The backlog is currently limited (silently) to 5.
658 *****************************************************************************
659 *
660 */
663 /****** bsdsocket.library/recv **********************************************
664 * NAME
665 * recv, recvfrom, - receive a message from a socket
666 *
667 * SYNOPSIS
668 * #include <sys/types.h>
669 * #include <sys/socket.h>
670 *
671 * nbytes = recv(s, buf, len, flags)
672 * D0 D0 A0 D1 D2
673 *
674 * long recv(long, char *, long, long);
675 *
676 * nbytes = recvfrom(s, buf, len, flags, from, fromlen)
677 * D0 D0 A0 D1 D2 A1 A2
678 *
679 * long recvfrom(long, char *, long, long,
680 * struct sockaddr *, long *);
681 *
682 * FUNCTION
683 * s is a socket created with socket(). recv() and recvfrom(),
684 * are used to receive messages from another socket. recv()
685 * may be used only on a connected socket (see connect()),
686 * while recvfrom() may be used to receive data on a socket
687 * whether it is in a connected state or not.
688 *
689 * If from is not a NULL pointer, the source address of the
690 * message is filled in. fromlen is a value-result parameter,
691 * initialized to the size of the buffer associated with from,
692 * and modified on return to indicate the actual size of the
693 * address stored there. The length of the message is
694 * returned. If a message is too long to fit in the supplied
695 * buffer, excess bytes may be discarded depending on the type
696 * of socket the message is received from (see socket()).
697 *
698 * If no messages are available at the socket, the receive call
699 * waits for a message to arrive, unless the socket is non-
700 * blocking (see IoctlSocket()) in which case -1 is returned
701 * with the external variable errno set to EWOULDBLOCK.
702 *
703 * The select() call may be used to determine when more data
704 * arrive.
705 *
706 * The flags parameter is formed by ORing one or more of the
707 * following:
708 *
709 * MSG_OOB - Read any "out-of-band" data present on the
710 * socket, rather than the regular "in-band"
711 * data.
712 *
713 * MSG_PEEK - "Peek" at the data present on the socket; the
714 * data are returned, but not consumed, so that
715 * a subsequent receive operation will see the
716 * same data.
717 *
718 * RETURN VALUES
719 * These calls return the number of bytes received, or -1 if an
720 * error occurred.
721 *
722 * ERRORS
723 * EBADF - s is an invalid descriptor.
724 *
725 * EINTR - The operation was interrupted by a break
726 * signal.
727 *
728 * EWOULDBLOCK - The socket is marked non-blocking and
729 * the requested operation would block.
730 *
731 * SEE ALSO
732 * connect(), getsockopt(), IoctlSocket(), select(), send(),
733 * SocketBaseTagList(), socket()
734 *****************************************************************************
735 *
736 */
738 #define NOTEX
739 /****** bsdsocket.library/recvfrom ******************************************
740 *
741 * SEE ALSO
742 * recv()
743 *****************************************************************************
744 *
745 */
748 /****** bsdsocket.library/select ********************************************
749 *
750 * NAME
751 * select -- synchronous I/O multiplexing (stub/inline function)
752 * WaitSelect -- select() with Amiga Wait() function.
753 *
754 * SYNOPSIS
755 * #include <sys/types.h>
756 * #include <sys/time.h>
757 *
758 * n = select (nfds, readfds, writefds, exceptfds, timeout)
759 *
760 * long select(long, fd_set *, fd_set *, fd_set *,
761 * struct timeval *);
762 *
763 * n = WaitSelect (nfds, readfds, writefds, exceptfds, timeout,
764 * D0 D0 A0 A1 A2 A3
765 * sigmp)
766 * D1
767 *
768 * long WaitSelect(long, fd_set *, fd_set *, fd_set *,
769 * struct timeval *, long *);
770 *
771 * FD_SET (fd, &fdset)
772 * FD_CLR (fd, &fdset)
773 * FD_ISSET (fd, &fdset)
774 * FD_ZERO (&fdset)
775 * long fd;
776 * fd_set fdset;
777 *
778 * DESCRIPTION
779 * select() examines the socket descriptor sets whose addresses
780 * are passed in readfds, writefds, and exceptfds to see if
781 * some of their descriptors are ready for reading, ready for
782 * writing, or have an exceptional condition pending. nfds is
783 * the number of bits to be checked in each bit mask that
784 * represent a file descriptor; the descriptors from 0 through
785 * (nfds - 1) in the descriptor sets are examined. On return,
786 * select() replaces the given descriptor sets with subsets
787 * consisting of those descriptors that are ready for the
788 * requested operation. The total number of ready descriptors
789 * in all the sets is returned.
790 *
791 * WaitSelect() also takes a signal mask which is waited during
792 * normal select() operation. If one of these singals is recei-
793 * ved, WaitSelect() returns and has re-set the signal mask
794 * to return those signals that have arrived. Normal select()
795 * return values are returned.
796 *
797 * The descriptor sets are stored as bit fields in arrays of
798 * integers. The following macros are provided for manipulat-
799 * ing such descriptor sets: FD_ZERO (&fdset) initializes a
800 * descriptor set fdset to the null set. FD_SET(fd, &fdset )
801 * includes a particular descriptor fd in fdset. FD_CLR(fd,
802 * &fdset) removes fd from fdset. FD_ISSET(fd, &fdset) is
803 * nonzero if fd is a member of fdset, zero otherwise. The
804 * behavior of these macros is undefined if a descriptor value
805 * is less than zero or greater than or equal to FD_SETSIZE,
806 * which is normally at least equal to the maximum number of
807 * descriptors supported by the system.
808 *
809 * If timeout is not a NULL pointer, it specifies a maximum
810 * interval to wait for the selection to complete. If timeout
811 * is a NULL pointer, the select blocks indefinitely. To
812 * effect a poll, the timeout argument should be a non-NULL
813 * pointer, pointing to a zero-valued timeval structure.
814 *
815 * Any of readfds, writefds, and exceptfds may be given as NULL
816 * pointers if no descriptors are of interest.
817 *
818 * Selecting true for reading on a socket descriptor upon which
819 * a listen() call has been performed indicates that a subse-
820 * quent accept() call on that descriptor will not block.
821 *
822 * RETURN VALUES
823 * select() returns a non-negative value on success. A positive
824 * value indicates the number of ready descriptors in the
825 * descriptor sets. 0 indicates that the time limit referred to
826 * by timeout expired or that the operation was interrupted
827 * either by a break signal or by arrival of a signal specified
828 * in *sigmp. On failure, select() returns -1, sets errno to
829 * indicate the error, and the descriptor sets are not changed.
830 *
831 * ERRORS
832 * EBADF - One of the descriptor sets specified an
833 * invalid descriptor.
834 *
835 * EINTR - one of the signals in SIGINTR mask (see Set-
836 * SocketSignals()) is set and it was not
837 * requested in WaitSelect() call.
838 *
839 * EINVAL - A component of the pointed-to time limit is
840 * outside the acceptable range: t_sec must be
841 * between 0 and 10^8, inclusive. t_usec must be
842 * greater than or equal to 0, and less than
843 * 10^6.
844 *
845 * SEE ALSO
846 * accept(), connect(), getdtablesize(), listen(), recv(),
847 * send(), SetDTableSize(), SetSocketSignals()
848 *
849 * NOTES
850 * Under rare circumstances, select() may indicate that a
851 * descriptor is ready for writing when in fact an attempt to
852 * write would block. This can happen if system resources
853 * necessary for a write are exhausted or otherwise unavail-
854 * able. If an application deems it critical that writes to a
855 * file descriptor not block, it should set the descriptor for
856 * non-blocking I/O using the FIOASYNC request to IoctlSocket().
857 *
858 * Default system limit for open socket descriptors is
859 * currently 64. However, in order to accommodate programs
860 * which might potentially use a larger number of open files
861 * with select, it is possible to increase this size within a
862 * program by providing a larger definition of FD_SETSIZE
863 * before the inclusion of <sys/types.h> and use
864 * SocketBaseTags(SBTM_SETVAL(SBTC_DTABLESIZE), FD_SETSIZE);
865 * call directly after OpenLibrary().
866 *
867 * BUGS
868 * select() should probably return the time remaining from the
869 * original timeout, if any, by modifying the time value in
870 * place. This may be implemented in future versions of the
871 * system. Thus, it is unwise to assume that the timeout
872 * pointer will be unmodified by the select() call.
873 *****************************************************************************
874 *
875 */
878 /****** bsdsocket.library/send **********************************************
879 *
880 * NAME
881 * send, sendto - send a message from a socket
882 *
883 * SYNOPSIS
884 * #include <sys/types.h>
885 * #include <sys/socket.h>
886 *
887 * nbytes = send(s, msg, len, flags)
888 * D0 D0 A0 D1 D2
889 *
890 * int send(int, char *, int, int);
891 *
892 * nbytes = sendto(s, msg, len, flags, to, tolen)
893 * D0 D0 A0 D1 D2 A1 D3
894 *
895 * int send(int, char *, int, int, struct sockaddr *, int);
896 *
897 * FUNCTION
898 * s is a socket created with socket(). send() and sendto() are
899 * used to transmit a message to another socket. send() may be
900 * used only when the socket is in a connected state, while
901 * sendto() may be used at any time.
902 *
903 * The address of the target is given by to with tolen specify-
904 * ing its size. The length of the message is given by len. If
905 * the message is too long to pass atomically through the
906 * underlying protocol, then the error EMSGSIZE is returned, and
907 * the message is not transmitted.
908 *
909 * No indication of failure to deliver is implicit in a send().
910 * Return values of -1 indicate some locally detected errors.
911 *
912 * If no buffer space is available at the socket to hold the
913 * message to be transmitted, then send() normally blocks,
914 * unless the socket has been placed in non-blocking I/O mode.
915 * The select() call may be used to determine when it is pos-
916 * sible to send more data.
917 *
918 * The flags parameter is formed by ORing one or more of the
919 * following:
920 *
921 * MSG_OOB - Send ``out-of-band'' data on sockets
922 * that support this notion. The underly-
923 * ing protocol must also support ``out-
924 * of-band'' data. Currently, only
925 * SOCK_STREAM sockets created in the
926 * AF_INET address family support out-of-
927 * band data.
928 *
929 * MSG_DONTROUTE - The SO_DONTROUTE option is turned on for
930 * the duration of the operation. This is
931 * usually used only by diagnostic or rout-
932 * ing programs.
933 *
934 * RETURN VALUES
935 * On success, these functions return the number of bytes sent.
936 * On failure, they return -1 and set errno to indicate the
937 * error.
938 *
939 * ERRORS
940 * EBADF - s is an invalid descriptor.
941 *
942 * EINTR - The operation was interrupted by a break
943 * signal.
944 *
945 * EINVAL - len is not the size of a valid address
946 * for the specified address family.
947 *
948 * EMSGSIZE - The socket requires that message be sent
949 * atomically, and the size of the message
950 * to be sent made this impossible.
951 *
952 * ENOBUFS - The system was unable to allocate an
953 * internal buffer. The operation may
954 * succeed when buffers become available.
955 *
956 * ENOBUFS - The output queue for a network interface
957 * was full. This generally indicates that
958 * the interface has stopped sending, but
959 * may be caused by transient congestion.
960 *
961 * EWOULDBLOCK - The socket is marked non-blocking and
962 * the requested operation would block.
963 *
964 * SEE ALSO
965 * connect(), getsockopt(), recv(), select(), socket()
966 *****************************************************************************
967 *
968 */
970 #define NOTEX
971 /****** bsdsocket.library/sendto ********************************************
972 *
973 * SEE ALSO
974 * send()
975 *****************************************************************************
976 *
977 */
979 #define NOTEX
980 /****** bsdsocket.library/setsockopt ****************************************
981 *
982 * SEE ALSO
983 * getsockopt()
984 *****************************************************************************
985 *
986 */
989 /****** bsdsocket.library/shutdown ******************************************
990 *
991 * NAME
992 * shutdown - shut down part of a full-duplex connection
993 *
994 * SYNOPSIS
995 * success = shutdown(s, how)
996 * D0 D0 D1
997 *
998 * long shutdown(long, long);
999 *
1000 * DESCRIPTION
1001 * The shutdown() call causes all or part of a full-duplex con-
1002 * nection on the socket associated with s to be shut down. If
1003 * how is 0, then further receives will be disallowed. If how
1004 * is 1, then further sends will be disallowed. If how is 2,
1005 * then further sends and receives will be disallowed.
1006 *
1007 * RETURN VALUES
1008 * 0 - on success.
1009 *
1010 * -1 - on failure and sets errno to indicate the error.
1011 *
1012 * ERRORS
1013 * EBADF - s is not a valid descriptor.
1014 *
1015 * ENOTCONN - The specified socket is not connected.
1016 *
1017 * SEE ALSO
1018 * connect(), socket()
1019 *
1020 * BUGS
1021 * The how values should be defined constants.
1022 *****************************************************************************
1023 *
1024 */
1027 /****** bsdsocket.library/socket ********************************************
1028 *
1029 * NAME
1030 * socket - create an endpoint for communication
1031 *
1032 * SYNOPSIS
1033 * #include <sys/types.h>
1034 * #include <sys/socket.h>
1035 *
1036 * s = socket(domain, type, protocol)
1037 * D0 D0 D1 D2
1038 *
1039 * long socket(long, long, long);
1040 *
1041 * FUNCTION
1042 * socket() creates an endpoint for communication and returns a
1043 * descriptor.
1044 *
1045 * The domain parameter specifies a communications domain
1046 * within which communication will take place; this selects the
1047 * protocol family which should be used. The protocol family
1048 * generally is the same as the address family for the
1049 * addresses supplied in later operations on the socket. These
1050 * families are defined in the include file <sys/socket.h>.
1051 * The currently understood formats are
1052 *
1053 * PF_INET - (ARPA Internet protocols)
1054 *
1055 * The socket has the indicated type, which specifies the
1056 * semantics of communication. Currently defined types are:
1057 *
1058 * SOCK_STREAM
1059 * SOCK_DGRAM
1060 * SOCK_RAW
1061 *
1062 * A SOCK_STREAM type provides sequenced, reliable, two-way
1063 * connection based byte streams. An out-of-band data
1064 * transmission mechanism may be supported. A SOCK_DGRAM
1065 * socket supports datagrams (connectionless, unreliable mes-
1066 * sages of a fixed (typically small) maximum length).
1067 * SOCK_RAW sockets provide access to internal network
1068 * interfaces.
1069 *
1070 * The protocol specifies a particular protocol to be used with
1071 * the socket. Normally only a single protocol exists to sup-
1072 * port a particular socket type within a given protocol fam-
1073 * ily. However, it is possible that many protocols may exist,
1074 * in which case a particular protocol must be specified in
1075 * this manner. The protocol number to use is particular to
1076 * the "communication domain" in which communication is to take
1077 * place.
1078 *
1079 * Sockets of type SOCK_STREAM are full-duplex byte streams,
1080 * similar to pipes. A stream socket must be in a connected
1081 * state before any data may be sent or received on it. A con-
1082 * nection to another socket is created with a connect() call.
1083 * Once connected, data may be transferred using send() and
1084 * recv() or their variant calls. When a session has been
1085 * completed a CloseSocket() may be performed. Out-of-band
1086 * data may also be transmitted as described in send() and
1087 * received as described in recv().
1088 *
1089 * The communications protocols used to implement a SOCK_STREAM
1090 * insure that data is not lost or duplicated. If a piece of
1091 * data for which the peer protocol has buffer space cannot be
1092 * successfully transmitted within a reasonable length of time,
1093 * then the connection is considered broken and calls will
1094 * indicate an error with -1 returns and with ETIMEDOUT as the
1095 * specific error code (see Errno()). The protocols optionally
1096 * keep sockets "warm" by forcing transmissions roughly every
1097 * minute in the absence of other activity.
1098 *
1099 * SOCK_DGRAM and SOCK_RAW sockets allow sending of datagrams
1100 * to correspondents named in send() calls. Datagrams are
1101 * generally received with recv(), which returns the next
1102 * datagram with its return address.
1103 *
1104 * The operation of sockets is controlled by socket level
1105 * options. These options are defined in the file socket.h.
1106 * getsockopt() and setsockopt() are used to get and set
1107 * options, respectively.
1108 *
1109 * RETURN VALUES
1110 * socket() returns a non-negative descriptor on success. On
1111 * failure, it returns -1 and sets errno to indicate the error.
1112 *
1113 * ERRORS
1114 * EACCES - Permission to create a socket of the
1115 * specified type and/or protocol is
1116 * denied.
1117 *
1118 * EMFILE - The per-process descriptor table is
1119 * full.
1120 *
1121 * ENOBUFS - Insufficient buffer space is available.
1122 * The socket cannot be created until suf-
1123 * ficient resources are freed.
1124 *
1125 * EPROTONOSUPPORT - The protocol type or the specified pro-
1126 * tocol is not supported within this
1127 * domain.
1128 *
1129 * EPROTOTYPE - The protocol is the wrong type for the
1130 * socket.
1131 *
1132 * SEE ALSO
1133 * accept(), bind(), CloseSocket(), connect(), getsockname(),
1134 * getsockopt(), IoctlSocket(), listen(), recv(), select(),
1135 * send(), shutdown(), WaitSelect()
1136 *****************************************************************************
1137 *
1138 */