rainlance
/
AmiTCP-SDK
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
AmiTCP-SDK/help/bsdsocket.guide

2866 lines
113 KiB
Plaintext
Raw Permalink Blame History

@database bsdsocket.guide
@Master bsdsocket.texi
@Width 72
This is the AmigaGuide® file bsdsocket.guide, produced by Makeinfo-1.55 from
the input file bsdsocket.texi.
This file is:
Copyright © 1994 AmiTCP/IP Group,
Network Solutions Development Inc.
All rights reserved.
@Node Main "bsdsocket.guide"
AMITCP/IP API Function Reference
********************************
@{" Disclaimer & Copyright " Link "Disclaimer & Copyright"}
@{" Function Reference " Link "Function Reference"}
@EndNode
@Node "Disclaimer & Copyright" "bsdsocket.guide/Disclaimer & Copyright"
@Next "Function Reference"
@Prev "Main"
@Toc "Main"
Disclaimer & Copyright
**********************
This manual is based on original documents from BSD net/2 release,
which is hereby acknowledged:
Copyright © 1982, 1986, 1988, 1990 Regents of the University of
California.
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials
provided with the distribution.
3. All advertising materials mentioning features or use of this
software must display the following acknowledgment:
This product includes software developed by the
University of California, Berkeley and its contributors.
4. Neither the name of the University nor the names of its
contributors may be used to endorse or promote products
derived from this software without specific prior written
permission.
THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS
OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
This manual is:
Copyright © 1994 AmiTCP/IP Group,
Network Solutions Development Inc.
All rights reserved.
@EndNode
@Node "accept()" "bsdsocket.guide/accept()"
@Next "bind()"
@Toc "Function Reference"
@{b}accept()@{ub}
========
@{i}NAME@{ui}
@{b}accept@{ub} -- accept a connection on a socket
@{i}SYNOPSIS@{ui}
@{i}#include <sys/types.h>@{ui}
@{i}#include <sys/socket.h>@{ui}
@{i}int accept(int s, struct sockaddr * addr, int * addrlen)@{ui}
@{i}D0 D0 A0 A1@{ui}
@{i}DESCRIPTION@{ui}
The argument @{b}s@{ub} is a socket that has been created with @{"socket()" Link "socket()"},
bound to an address with @{"bind()" Link "bind()"}, and is listening for connections
after a @{"listen()" Link "listen()"}. The @{b}accept()@{ub} argument extracts the first
connection request on the queue of pending connections, creates a
new socket with the same properties of @{b}s@{ub} and allocates a new file
descriptor for the socket. If no pending connections are present
on the queue, and the socket is not marked as non-blocking,
@{b}accept()@{ub} blocks the caller until a connection is present. If
the socket is marked non-blocking and no pending connections are
present on the queue, @{b}accept()@{ub} returns an error as described
below. The accepted socket is used to read and write data to and
from the socket which connected to this one; it is not used to
accept more connections. The original socket @{b}s@{ub} remains open.
The argument @{b}addr@{ub} is a result parameter that is filled in with the
address of the connecting entity, as known to the communications
layer. The exact format of the @{b}addr@{ub} parameter is determined by
the domain in which the communication is occurring. The @{b}addrlen@{ub}
is a value-result parameter; it should initially contain the
amount of space pointed to by @{b}addr@{ub}; on return it will contain the
actual length (in bytes) of the address returned. This call is
used with connection-based socket types, currently with
@{b}SOCK_STREAM@{ub}.
It is possible to @{"select()" Link "select()"} a socket for the purposes of doing an
@{b}accept()@{ub} by selecting it for read.
One can obtain user connection request data without confirming the
connection by issuing a @{"recv()" Link "recv()"} call with an @{b}msg_iovlen@{ub} of 0 and a
non-zero @{b}msg_controllen@{ub}, or by issuing a @{"getsockopt()" Link "getsockopt()"} request.
Similarly, one can provide user connection rejection information
by issuing a @{"send()" Link "send()"} call with providing only the control
information, or by calling @{"setsockopt()" Link "getsockopt()"}.
@{i}RETURN VALUES@{ui}
The call returns -1 on error. If it succeeds, it returns a
non-negative integer that is a descriptor for the accepted socket.
@{i}ERRORS@{ui}
The @{b}accept()@{ub} will fail if:
@{b}[EBADF]@{ub}
The descriptor is invalid.
@{b}[EINTR]@{ub}
The operation was interrupted by a break signal.
@{b}[EOPNOTSUPP]@{ub}
The referenced socket is not of type @{b}SOCK_STREAM@{ub}.
@{b}[EWOULDBLOCK]@{ub}
The socket is marked non-blocking and no connections are
present to be accepted.
@{i}SEE ALSO@{ui}
@{"bind()" Link "bind()"}, @{"connect()" Link "connect()"}, @{"listen()" Link "listen()"}, @{"select()" Link "select()"}, @{"SetSocketSignals()" Link "SetSocketSignals()"}, @{"socket()" Link "socket()"},
@{"SocketBaseTagList()" Link "SocketBaseTagList()"}
@{i}NOTES@{ui}
@{b}accept()@{ub} calls the @{b}fdCallback()@{ub} with action codes @{b}FDCB_CHECK@{ub} and
@{b}FDCB_ALLOC@{ub} to check and mark the new descriptor as allocated
if the callback is defined. See @{"SocketBaseTagList()" Link "SocketBaseTagList()"} for more
information on @{b}fdCallback()@{ub}.
@{i}HISTORY@{ui}
The @{b}accept()@{ub} function appeared in 4.2BSD.
@EndNode
@Node "bind()" "bsdsocket.guide/bind()"
@Next "CloseSocket()"
@Prev "accept()"
@Toc "Function Reference"
@{b}bind()@{ub}
======
@{i}NAME@{ui}
@{b}bind@{ub} -- bind a name to a socket
@{i}SYNOPSIS@{ui}
@{i}#include <sys/types.h>@{ui}
@{i}#include <sys/socket.h>@{ui}
@{i}int bind(int s, struct sockaddr * name, int namelen)@{ui}
@{i}D0 D0 A0 D1@{ui}
@{i}DESCRIPTION@{ui}
@{b}Bind()@{ub} assigns a name to an unnamed socket. When a socket is
created with @{"socket()" Link "socket()"} it exists in a name space (address family)
but has no name assigned. @{b}Bind()@{ub} requests that @{b}name@{ub} be assigned
to the socket.
@{i}RETURN VALUES@{ui}
If the bind is successful, a 0 value is returned. A return value
of -1 indicates an error, which is further specified in the
library variable errno (see @{"Errno()" Link "Errno()"}.)
@{i}ERRORS@{ui}
The @{b}bind()@{ub} call will fail if:
@{b}[EBADF]@{ub}
@{b}S@{ub} is not a valid descriptor.
@{b}[EADDRNOTAVAIL]@{ub}
The specified address is not available from the local machine.
@{b}[EADDRINUSE]@{ub}
The specified address is already in use.
@{b}[EINVAL]@{ub}
The socket is already bound to an address.
@{b}[EACCES]@{ub}
The requested address is protected, and the current user has
inadequate permission to access it.
@{i}SEE ALSO@{ui}
@{"connect()" Link "connect()"}, @{"listen()" Link "listen()"}, @{"socket()" Link "socket()"}, @{"getsockname()" Link "getsockname()"}
@{i}HISTORY@{ui}
The @{b}bind()@{ub} function call appeared in 4.2BSD.
@EndNode
@Node "CloseSocket()" "bsdsocket.guide/CloseSocket()"
@Next "connect()"
@Prev "bind()"
@Toc "Function Reference"
@{b}CloseSocket()@{ub}
=============
@{i}NAME@{ui}
@{b}CloseSocket@{ub} -- delete a socket descriptor
@{i}SYNOPSIS@{ui}
@{i}int CloseSocket(int s)@{ui}
@{i}D0 D0@{ui}
@{i}DESCRIPTION@{ui}
The @{b}CloseSocket()@{ub} call deletes a descriptor from the library base
socket reference table. If this is the last reference to the
underlying object, the object will be deactivated and @{"socket()" Link "socket()"}
associated naming information and queued data are discarded.
All sockets are automatically closed when the socket library is
closed, but closing sockets as soon as possible is recommended to
save system resources.
@{i}RETURN VALUES@{ui}
Upon successful completion, a value of 0 is returned. Otherwise,
a value of -1 is returned and the library variable @{b}errno@{ub} (see
@{"Errno()" Link "Errno()"}) is set to indicate the error.
@{i}ERRORS@{ui}
@{b}CloseSocket()@{ub} will fail if:
@{b}[EBADF]@{ub}
@{b}S@{ub} is not an active socket descriptor.
@{b}[EINTR]@{ub}
An interupt was received.
@{i}SEE ALSO@{ui}
@{"accept()" Link "accept()"},
@{"shutdown()" Link "shutdown()"},
@{"socket()" Link "socket()"},
@{"SocketBaseTagList()" Link "SocketBaseTagList()"},
@{b}exec.library/CloseLibrary()@{ub}
@{i}NOTES@{ui}
@{b}CloseSocket()@{ub} calls the @{b}fdCallback()@{ub} with action code @{b}FDCB_FREE@{ub} if
the callback is defined. See @{"SocketBaseTagList()" Link "SocketBaseTagList()"} for more
information on @{b}fdCallback()@{ub}.
@EndNode
@Node "connect()" "bsdsocket.guide/connect()"
@Next "Dup2Socket()"
@Prev "CloseSocket()"
@Toc "Function Reference"
@{b}connect()@{ub}
=========
@{i}NAME@{ui}
@{b}connect@{ub} -- initiate a connection on a socket
@{i}SYNOPSIS@{ui}
@{i}#include <sys/types.h>@{ui}
@{i}#include <sys/socket.h>@{ui}
@{i}int connect(int s, struct sockaddr * name, int namelen)@{ui}
@{i}D0 D0 A0 D1@{ui}
@{i}DESCRIPTION@{ui}
The parameter @{b}s@{ub} is a socket. If it is of type @{b}SOCK_DGRAM@{ub}, this
call specifies the peer with which the socket is to be associated;
this address is that to which datagrams are to be sent, and the
only address from which datagrams are to be received. If the
socket is of type @{b}SOCK_STREAM@{ub}, this call attempts to make a
connection to another socket. The other socket is specified by
@{b}name@{ub}, which is an address in the communications space of the
socket. Each communications space interprets the @{b}name@{ub} parameter
in its own way. Generally, stream sockets may successfully
@{b}connect()@{ub} only once; datagram sockets may use @{b}connect()@{ub}
multiple times to change their association. Datagram sockets may
dissolve the association by connecting to an invalid address, such
as a null address.
@{i}RETURN VALUES@{ui}
If the connection or binding succeeds, 0 is returned. Otherwise a
-1 is returned, and a more specific error code is stored in @{b}errno@{ub}.
@{i}ERRORS@{ui}
The @{b}connect()@{ub} call fails if:
@{b}[EBADF]@{ub}
@{b}S@{ub} is not a valid descriptor.
@{b}[EADDRNOTAVAIL]@{ub}
The specified address is not available on this machine.
@{b}[EAFNOSUPPORT]@{ub}
Addresses in the specified address family cannot be used with
this socket.
@{b}[EISCONN]@{ub}
The socket is already connected.
@{b}[ETIMEDOUT]@{ub}
Connection establishment timed out without establishing a
connection.
@{b}[ECONNREFUSED]@{ub}
The attempt to connect was forcefully rejected.
@{b}[ENETUNREACH]@{ub}
The network isn't reachable from this host.
@{b}[EADDRINUSE]@{ub}
The address is already in use.
@{b}[EINPROGRESS]@{ub}
The socket is non-blocking and the connection cannot be
completed immediately. It is possible to @{"select()" Link "select()"} for
completion by selecting the socket for writing.
@{b}[EALREADY]@{ub}
The socket is non-blocking and a previous connection attempt
has not yet been completed.
@{i}SEE ALSO@{ui}
@{"accept()" Link "accept()"}, @{"select()" Link "select()"}, @{"socket()" Link "socket()"}, @{"getsockname()" Link "getsockname()"}
@{i}HISTORY@{ui}
The @{b}connect()@{ub} function call appeared in 4.2BSD.
@EndNode
@Node "Dup2Socket()" "bsdsocket.guide/Dup2Socket()"
@Next "Errno()"
@Prev "connect()"
@Toc "Function Reference"
@{b}Dup2Socket()@{ub}
============
@{i}NAME@{ui}
@{b}Dup2Socket@{ub} -- duplicate a socket descriptor
@{i}SYNOPSIS@{ui}
@{i}int Dup2Socket(int fd1, int fd2)@{ui}
@{i}D0 D0 D1@{ui}
@{i}DESCRIPTION@{ui}
@{b}Dup2Socket()@{ub} duplicates an existing socket descriptor. The
argument @{b}fd1@{ub} is small non-negative value that indexes the socket
on library base socket descriptor table. The value must be less
than the size of the table, which is returned by @{b}getdtablesize()@{ub}.
@{b}fd2@{ub} specifies the desired value of the new descriptor. If
socket pointed by @{b}fd2@{ub} is already in use, it is first deallocated
as if it were closed by @{b}CloseSocket()@{ub}. If the value of @{b}fd2@{ub} is -1,
the new descriptor used and returned is the lowest numbered
descriptor that is not currently in use by the task's socket
library base.
Since AMITCP/IP 3.0 @{b}Dup2Socket()@{ub} has also an feature to mark a
file descriptor as being used. If @{b}fd1@{ub} is given as -1, @{b}fd2@{ub} is
marked as being used socket descriptor table and it won't be
allocated for any socket. This mark can be removed using
@{b}CloseSocket()@{ub} call.
@{i}RETURN VALUES@{ui}
The value -1 is returned if an error occurs in either call. The
library variable @{b}errno@{ub} (see @{"Errno()" Link "Errno()"}) indicates the cause of the
error.
@{i}ERRORS@{ui}
@{b}Dup2Socket()@{ub} fail if:
@{b}[EBADF]@{ub}
@{b}sd1@{ub} or @{b}sd2@{ub} is not a valid active descriptor
@{b}[EMFILE]@{ub}
Too many descriptors are active.
@{i}SEE ALSO@{ui}
@{"accept()" Link "accept()"}, @{"CloseSocket()" Link "CloseSocket()"}, @{"socket()" Link "socket()"}, @{"getdtablesize()" Link "getdtablesize()"}, @{"SocketBaseTagList()" Link "SocketBaseTagList()"}
@{i}NOTES@{ui}
@{b}Dup2Socket()@{ub} calls the @{b}fdCallback()@{ub} with action codes @{b}FDCB_CHECK@{ub}
and @{b}FDCB_ALLOC@{ub} to check and mark the new descriptor as allocated
if the callback is defined. See @{"SocketBaseTagList()" Link "SocketBaseTagList()"} for more
information on @{b}fdCallback()@{ub}.
@EndNode
@Node "Errno()" "bsdsocket.guide/Errno()"
@Next "getdtablesize()"
@Prev "Dup2Socket()"
@Toc "Function Reference"
@{b}Errno()@{ub}
=======
@{i}NAME@{ui}
@{b}Errno@{ub} -- get error value after unsuccessful function call
@{i}SYNOPSIS@{ui}
@{i}long Errno(void)@{ui}
@{i}D0@{ui}
@{i}FUNCTION@{ui}
When some function in socket library return an error condition
value, they also set a specific error value. This error value can
be (among other things) extracted by this function.
@{i}RESULT@{ui}
Error value indicating the error on last failure of some bsdsocket
library function call.
@{i}NOTES@{ui}
Return value of @{b}Errno()@{ub} is not changed after successful function
so so it cannot be used to determine success of any function call
of this library. Also, another function call to this library may
change the return value of @{b}Errno()@{ub} so use it right after error
occurred.
@{i}SEE ALSO@{ui}
@{"SetErrnoPtr()" Link "SetErrnoPtr()"}, @{"SocketBaseTagList()" Link "SocketBaseTagList()"}
@EndNode
@Node "getdtablesize()" "bsdsocket.guide/getdtablesize()"
@Next "gethostbyname()"
@Prev "Errno()"
@Toc "Function Reference"
@{b}getdtablesize()@{ub}
===============
@{i}NAME@{ui}
@{b}getdtablesize@{ub} -- get descriptor table size
@{i}SYNOPSIS@{ui}
@{i}int getdtablesize(void)@{ui}
@{i}D0@{ui}
@{i}DESCRIPTION@{ui}
Each socket library base has a socket descriptor table which
initially has 64 slots. The entries in the descriptor table are
numbered with small integers starting at 0. The call
@{b}getdtablesize()@{ub} returns the size of this table.
@{i}SEE ALSO@{ui}
@{"CloseSocket()" Link "CloseSocket()"}, @{"Dup2Socket()" Link "Dup2Socket()"}, @{"select()" Link "select()"} @{"SocketBaseTagList()" Link "SocketBaseTagList()"}
@{i}NOTES@{ui}
AMITCP/IP versions below 3.0 used to have function @{b}SetDtableSize()@{ub}
in place of this function. From now on, use @{"SocketBaseTagList()" Link "SocketBaseTagList()"} to
set new size for socket descriptor table.
@{i}HISTORY@{ui}
The @{b}getdtablesize()@{ub} function call appeared in 4.2BSD.
@EndNode
@Node "gethostbyname()" "bsdsocket.guide/gethostbyname()"
@Next "gethostid()"
@Prev "getdtablesize()"
@Toc "Function Reference"
@{b}gethostbyname()@{ub}, @{b}gethostbyaddr()@{ub}
================================
@{i}NAME@{ui}
@{b}gethostbyname@{ub}, @{b}gethostbyaddr@{ub} -- get network host entry
@{i}SYNOPSIS@{ui}
@{i}#include <netdb.h>@{ui}
@{i}extern struct h_errno;@{ui}
@{i}struct hostent * gethostbyname(char * name)@{ui}
@{i}D0 A0@{ui}
@{i}struct hostent * gethostbyaddr(char * addr, int len, int type)@{ui}
@{i}D0 A0 D0 D1@{ui}
@{i}DESCRIPTION@{ui}
The @{b}gethostbyname()@{ub} and @{b}gethostbyaddr()@{ub} functions each return a
pointer to an object with the following structure describing an
internet host referenced by name or by address, respectively.
This structure contains either the information obtained from the
name server, @{b}named@{ub} or broken-out fields from a line in @{b}/etc/hosts@{ub}.
If the local name server is not running these routines do a lookup
in @{b}/etc/hosts@{ub}.
@{i}struct hostent {
char *h_name; /*@{i} official name of host @{ui}*/
char **h_aliases; /*@{i} alias list @{ui}*/
int h_addrtype; /*@{i} host address type @{ui}*/
int h_length; /*@{i} length of address @{ui}*/
char **h_addr_list; /*@{i} list of addresses from name server @{ui}*/
};
#define h_addr h_addr_list[0] /*@{i} address, for backward compatibility @{ui}*/@{ui}
The members of this structure are:
@{b}h_name@{ub}
Official name of the host.
@{b}h_aliases@{ub}
A zero terminated array of alternate names for the host.
@{b}h_addrtype@{ub}
The type of address being returned; currently always @{b}AF_INET@{ub}.
@{b}h_length@{ub}
The length, in bytes, of the address.
@{b}h_addr_list@{ub}
A zero terminated array of network addresses for the host.
Host addresses are returned in network byte order.
@{b}h_addr@{ub}
The first address in @{b}h_addr_list@{ub}; this is for backward
(source) compatiblity.
@{i}DIAGNOSTICS@{ui}
Error return status from @{b}gethostbyname()@{ub} and @{b}gethostbyaddr()@{ub} is
indicated by return of a null pointer. The library integer
@{b}h_errno@{ub} (see @{"SocketBaseTagList()" Link "SocketBaseTagList()"}) may then be checked to
see whether this is a temporary failure or an invalid or unknown
host. If its argument @{b}string@{ub} is non@{b}-NULL@{ub}, it is printed, followed
by a colon and a space. The error message is printed with a
trailing newline.
The library variable @{b}h_errno@{ub} can have the following values:
@{b}HOST_NOT_FOUND@{ub}
No such host is known.
@{b}TRY_AGAIN@{ub}
This is usually a temporary error and means that the local
server did not receive a response from an authoritative
server. A retry at some later time may succeed.
@{b}NO_RECOVERY@{ub}
Some unexpected server failure was encountered. This is a
non-recoverable error.
@{b}NO_DATA@{ub}
The requested name is valid but does not have an IP address;
this is not a temporary error. This means that the name is
known to the name server but there is no address associated
with this name. Another type of request to the name server
using this domain name will result in an answer; for example,
a mail-forwarder may be registered for this domain.
@{i}SEE ALSO@{ui}
AMITCP/IP configuration
@{i}HISTORY@{ui}
The @{b}herror()@{ub} function appeared in 4.3BSD. @{b}gethostbyaddr()@{ub} and
@{b}gethostbyname()@{ub} functions appeared in 4.2BSD.
@{i}BUGS@{ui}
These functions use static data storage; if the data is needed for
future use, it should be copied before any subsequent calls
overwrite it. Only the Internet address format is currently
understood.
@EndNode
@Node "gethostid()" "bsdsocket.guide/gethostid()"
@Next "gethostname()"
@Prev "gethostbyname()"
@Toc "Function Reference"
@{b}gethostid()@{ub}
===========
@{i}NAME@{ui}
@{b}gethostid@{ub} -- get unique identifier of current host
@{i}SYNOPSIS@{ui}
@{i}long gethostid(void)@{ui}
@{i}D0@{ui}
@{i}DESCRIPTION@{ui}
@{b}gethostid()@{ub} returns the 32-bit identifier for the current processor
that is intended to be unique among all UNIX systems in existence.
This is normally a DARPA Internet address for the local machine.
@{i}SEE ALSO@{ui}
@{"gethostname()" Link "gethostname()"}
@{i}BUGS@{ui}
32 bits for the identifier is too small.
@{i}HISTORY@{ui}
The @{b}gethostid()@{ub} function call appeared in 4.2BSD.
@EndNode
@Node "gethostname()" "bsdsocket.guide/gethostname()"
@Next "getnetbyname()"
@Prev "gethostid()"
@Toc "Function Reference"
@{b}gethostname()@{ub}
=============
@{i}NAME@{ui}
@{b}gethostname@{ub} -- get name of current host
@{i}SYNOPSIS@{ui}
@{i}int gethostname(char * name, int namelen)@{ui}
@{i}D0 A0 D0@{ui}
@{i}DESCRIPTION@{ui}
@{b}Gethostname()@{ub} returns the standard host name for the current
processor. The parameter @{b}namelen@{ub} specifies the size of the @{b}name@{ub}
array. The returned name is null-terminated unless insufficient
space is provided.
@{i}SEE ALSO@{ui}
@{"gethostid()" Link "gethostid()"}
@{i}HISTORY@{ui}
The @{b}gethostname()@{ub} function call appeared in 4.2BSD.
@EndNode
@Node "getnetbyname()" "bsdsocket.guide/getnetbyname()"
@Next "getpeername()"
@Prev "gethostname()"
@Toc "Function Reference"
@{b}getnetbyname()@{ub}, @{b}getnetbyaddr()@{ub}
==============================
@{i}NAME@{ui}
@{b}getnetbyaddr@{ub}, @{b}getnetbyname@{ub} -- get network entry
@{i}SYNOPSIS@{ui}
@{i}#include <netdb.h>@{ui}
@{i}struct netent * getnetbyname(char * name)@{ui}
@{i}D0 A0@{ui}
@{i}struct netent * getnetbyaddr(long net, int type)@{ui}
@{i}D0 D0 D1@{ui}
@{i}DESCRIPTION@{ui}
The @{b}getnetbyname()@{ub} and @{b}getnetbyaddr()@{ub} functions each return a
pointer to an object with the following structure containing the
broken-out fields of a line in the network data base.
@{i}struct netent {
char *n_name; /*@{i} official name of net @{ui}*/
char **n_aliases; /*@{i} alias list @{ui}*/
int n_addrtype; /*@{i} net number type @{ui}*/
unsigned long n_net; /*@{i} net number @{ui}*/
};@{ui}
The members of this structure are:
@{b}n_name@{ub}
The official name of the network.
@{b}n_aliases@{ub}
A zero terminated list of alternate names for the network.
@{b}n_addrtype@{ub}
The type of the network number returned; currently only
AF_INET.
@{b}n_net@{ub}
The network number. Network numbers are returned in machine
byte order.
@{i}DIAGNOSTICS@{ui}
Null pointer (0) returned on @{b}EOF@{ub} or error.
@{i}SEE ALSO@{ui}
AMITCP/IP configuration
@{i}HISTORY@{ui}
The @{b}getnetbyaddr()@{ub} and @{b}getnetbyname()@{ub} functions appeared in 4.2BSD.
@{i}BUGS@{ui}
The data space used by these functions is static; if future use
requires the data, it should be copied before any subsequent calls
to these functions overwrite it. Only Internet network numbers
are currently understood. Expecting network numbers to fit in no
more than 32 bits is probably naive.
@EndNode
@Node "getpeername()" "bsdsocket.guide/getpeername()"
@Next "getprotobyname()"
@Prev "getnetbyname()"
@Toc "Function Reference"
@{b}getpeername()@{ub}
=============
@{i}NAME@{ui}
@{b}getpeername@{ub} -- get name of connected peer
@{i}SYNOPSIS@{ui}
@{i}int getpeername(int s, struct sockaddr * name, int * namelen)@{ui}
@{i}D0 D0 A0 A1@{ui}
@{i}DESCRIPTION@{ui}
@{b}Getpeername()@{ub} returns the name of the peer connected to socket @{b}s@{ub}.
The @{b}namelen@{ub} parameter should be initialized to indicate the amount
of space pointed to by @{b}name@{ub}. On return it contains the actual
size of the name returned (in bytes). The name is truncated if the
buffer provided is too small.
@{i}DIAGNOSTICS@{ui}
A 0 is returned if the call succeeds, -1 if it fails.
@{i}ERRORS@{ui}
The call succeeds unless:
@{b}[EBADF]@{ub}
The argument @{b}s@{ub} is not a valid descriptor.
@{b}[ENOTCONN]@{ub}
The socket is not connected.
@{b}[ENOBUFS]@{ub}
Insufficient resources were available in the system to
perform the operation.
@{i}SEE ALSO@{ui}
@{"accept()" Link "accept()"}, @{"bind()" Link "bind()"}, @{"socket()" Link "socket()"}, @{"getsockname()" Link "getsockname()"}
@{i}HISTORY@{ui}
The @{b}getpeername()@{ub} function call appeared in 4.2BSD.
@EndNode
@Node "getprotobyname()" "bsdsocket.guide/getprotobyname()"
@Next "getservbyname()"
@Prev "getpeername()"
@Toc "Function Reference"
@{b}getprotobyname()@{ub}, @{b}getprotobynumber()@{ub}
====================================
@{i}NAME@{ui}
@{b}getprotobynumber@{ub}, @{b}getprotobyname@{ub} -- get protocol entry
@{i}SYNOPSIS@{ui}
@{i}#include <netdb.h>@{ui}
@{i}struct protoent * getprotobyname(char * name)@{ui}
@{i}D0 A0@{ui}
@{i}struct protoent * getprotobynumber(int proto)@{ui}
@{i}D0 D0@{ui}
@{i}DESCRIPTION@{ui}
The @{b}getprotobyname()@{ub} and @{b}getprotobynumber()@{ub} functions each return
a pointer to an object with the following structure containing the
broken-out fields of a line in the network protocol data base.
@{i}
struct protoent {
char *p_name; /*@{i} official name of protocol @{ui}*/
char **p_aliases; /*@{i} alias list @{ui}*/
int p_proto; /*@{i} protocol number @{ui}*/
};@{ui}
The members of this structure are:
@{b}p_name@{ub}
The official name of the protocol.
@{b}p_aliases@{ub}
A zero terminated list of alternate names for the protocol.
@{b}p_proto@{ub}
The protocol number.
@{i}RETURN VALUES@{ui}
Null pointer (0) returned on @{b}EOF@{ub} or error.
@{i}SEE ALSO@{ui}
AMITCP/IP configuration
@{i}HISTORY@{ui}
The @{b}getprotobynumber()@{ub} and @{b}getprotobyname()@{ub} 4.2BSD.
@{i}BUGS@{ui}
These functions use a static data space; if the data is needed for
future use, it should be copied before any subsequent calls
overwrite it. Only the Internet protocols are currently
understood.
@EndNode
@Node "getservbyname()" "bsdsocket.guide/getservbyname()"
@Next "GetSocketEvents()"
@Prev "getprotobyname()"
@Toc "Function Reference"
@{b}getservbyname()@{ub}, @{b}getservbyport()@{ub}
================================
@{i}NAME@{ui}
@{b}getservbyport@{ub}, @{b}getservbyname@{ub} -- get service entry
@{i}SYNOPSIS@{ui}
@{i}#include <netdb.h>@{ui}
@{i}struct servent * getservbyname(char * name, char * proto)@{ui}
@{i}D0 A0 A1@{ui}
@{i}struct servent * getservbyport(int port, char * proto)@{ui}
@{i}D0 D0 A0@{ui}
@{i}DESCRIPTION@{ui}
The @{b}getservbyname()@{ub} and @{b}getservbyport()@{ub} functions each return a
pointer to an object with the following structure containing the
broken-out fields of a line in the network services data base.
@{i}struct servent {
char *s_name; /*@{i} official name of service @{ui}*/
char **s_aliases; /*@{i} alias list @{ui}*/
int s_port; /*@{i} port service resides at @{ui}*/
char *s_proto; /*@{i} protocol to use @{ui}*/
};@{ui}
The members of this structure are:
@{b}s_name@{ub}
The official name of the service.
@{b}s_aliases@{ub}
A zero terminated list of alternate names for the service.
@{b}s_port@{ub}
The port number at which the service resides. Port numbers
are returned in network byte order.
@{b}s_proto@{ub}
The name of the protocol to use when contacting the service.
@{i}DIAGNOSTICS@{ui}
Null pointer (0) returned on @{b}EOF@{ub} or error.
@{i}SEE ALSO@{ui}
@{"getprotobyname()" Link "getprotobyname()"} and AMITCP/IP configuration
@{i}HISTORY@{ui}
The @{b}getservbyport()@{ub}and @{b}getservbyname()@{ub} functions appeared in
4.2BSD.
@{i}BUGS@{ui}
These functions use static data storage; if the data is needed for
future use, it should be copied before any subsequent calls
overwrite it. Expecting port numbers to fit in a 32 bit quantity
is probably naive.
@EndNode
@Node "GetSocketEvents()" "bsdsocket.guide/GetSocketEvents()"
@Next "getsockname()"
@Prev "getservbyname()"
@Toc "Function Reference"
@{b}GetSocketEvents()@{ub}
=================
@{i}NAME@{ui}
@{b}GetSocketEvents@{ub} -- get asynchronic socket events if any
@{i}SYNOPSIS@{ui}
@{i}#include <sys/socket.h>@{ui}
@{i}LONG GetSocketEvents(ULONG *eventsp)@{ui}
@{i} A0@{ui}
@{i}FUNCTION@{ui}
@{b}GetSocketEvents()@{ub} is used to retrieve asynchronous events of
sockets. The socket descriptor for which events happened is
returned as a return value. If the return value is @{b}-1@{ub}, then there
are no sockets with asynchronous events. Note that the @{b}errno@{ub}
variable is @{i}not@{ui} set in this case.
The asynchronous socket events are notified with the event signal.
The application must set this signal with the @{"SocketBaseTagList()" Link "SocketBaseTagList()"}
tag code @{b}SBTC_SIGEVENTMASK@{ub}. In addiotion to that, the application
must set the event filter masks for each socket with the
@{"getsockopt()" Link "getsockopt()"} @{b}SO_EVENTMASK@{ub} option. The socket must also be in
async mode (@{"IoctlSocket()" Link "IoctlSocket()"} @{b}FIOASYNC@{ub}), but this mode will be set on
by the @{"getsockopt()" Link "getsockopt()"} for @{b}SO_EVENTMASK@{ub} automaticly. The socket must
also have an owner task which to notify. The owner task is set to
the creating task of the socket by default. A socket got from
@{"ObtainSocket()" Link "ObtainSocket()"} retains the old owner, however. So, after
@{"ObtainSocket()" Link "ObtainSocket()"}, the owner must be set explicitly with the
@{"IoctlSocket()" Link "IoctlSocket()"} code @{b}FIOSETOWN@{ub}.
The events are returned via @{b}eventsp@{ub} as a bit mask of event codes
defined in @{b}<sys/socket.h>@{ub}. The event codes should be tested in
the order they are defined in the header file and described below,
since it is possible to get @{b}FD_CONNECT@{ub}, @{b}FD_READ@{ub} and @{b}FD_CLOSE@{ub} at
the same time, for example. (That would mean that the connection
was established, data was received and the connection was closed).
@{b}FD_ACCEPT@{ub}
Indicates that there is a new connection waiting for
acception. This event is @{i}level triggered@{ui}, meaning that the
event is set again if there is yet another connection after
the @{"accept()" Link "accept()"} call. Because of this it is enough to respond
with one @{"accept()" Link "accept()"} call for each @{b}FD_ACCEPT@{ub} received.
@{b}FD_CONNECT@{ub}
Indicates that the pending connection has been established.
This event should be waited for after a non-blocking
@{"connect()" Link "connect()"}. Note that this event is generated even if the
socket is not in non-blocking mode.
@{b}FD_OOB@{ub}
Indicates that the socket has received a notifiction of urgent
(out-of-band) data. The urgent data might not yet be
received, and it might be impossible to receive, if the
socket receive buffer is full. This means that the
application should read the normal data from the buffer so
that the urgent data could be received and read by the
application.
@{b}FD_READ@{ub}
This event is set whenever new data arrives on the socket
receive buffer. Note that the application should read all
the data it can from the socket, since there is no quarantee
that @{i}new@{ui} data would arrive, and thus cause a new event to be
generated.
@{b}FD_WRITE@{ub}
This indicates that the application can write to the
@{i}non-blocking@{ui} socket again. This event is set only if the
socket is in non-blocking mode. This event is generated @{i}only@{ui}
after the application could not write all the data to the
socket (i.e., the operation would have blocked if the socket
was not in non-blocking mode).
@{b}FD_ERROR@{ub}
This indicates an asynchronous error that happened on the
socket. When this event is returned the @{b}errno@{ub} is set to the
socket error code.
Note that the socket error code is not cleared, so that the
forthcoming socket functions might notice the error, too. If
the socket error code must be cleared, the @{"getsockopt()" Link "getsockopt()"} for
@{b}SO_ERROR@{ub} should be called, since the internal socket
error is cleared as a side effect of that function (and code).
@{b}FD_CLOSE@{ub}
This indicates that the connection was closed. Note that the
socket receive buffer might still have some data which should
be received before the socket is closed.
If the connection was closed due to an error, the @{b}FD_ERROR@{ub}
event is sent before this event. The @{b}FD_ERROR@{ub} could be
either returned by an earlier @{b}GetSocketEvents()@{ub} for this
socket or included in the same event mask with the @{b}FD_CLOSE@{ub}.
The exact semantics for the @{b}FD_CLOSE@{ub} depend on the application
protocol. If the other end uses @{"shutdown()" Link "shutdown()"} to close only the
sending side of the connection, the receiver of the @{b}FD_CLOSE@{ub}
might still be able to send data.
@{i}EXAMPLE@{ui}
@{i}NOTES@{ui}
@{i}SEE ALSO@{ui}
@{"IoctlSocket()" Link "IoctlSocket()"}, @{"recv()" Link "recv()"}, @{"send()" Link "send()"}, @{"setsockopt()" Link "getsockopt()"},
@{"SocketBaseTagList()" Link "SocketBaseTagList()"}
!!
@EndNode
@Node "getsockname()" "bsdsocket.guide/getsockname()"
@Next "getsockopt()"
@Prev "GetSocketEvents()"
@Toc "Function Reference"
@{b}getsockname()@{ub}
=============
@{i}NAME@{ui}
@{b}getsockname@{ub} -- get socket name
@{i}SYNOPSIS@{ui}
@{i}int getsockname(int s, struct sockaddr * name, int * namelen)@{ui}
@{i}D0 D0 A0 A1@{ui}
@{i}DESCRIPTION@{ui}
@{b}Getsockname()@{ub} returns the current @{b}name@{ub} for the specified socket.
The @{b}namelen@{ub} parameter should be initialized to indicate the amount
of space pointed to by @{b}name@{ub}. On return it contains the actual
size of the name returned (in bytes).
@{i}DIAGNOSTICS@{ui}
A 0 is returned if the call succeeds, -1 if it fails.
@{i}ERRORS@{ui}
The call succeeds unless:
@{b}[EBADF]@{ub}
The argument @{b}s@{ub} is not a valid descriptor.
@{b}[ENOBUFS]@{ub}
Insufficient resources were available in the system to
perform the operation.
@{i}SEE ALSO@{ui}
@{"bind()" Link "bind()"}, @{"socket()" Link "socket()"}, @{"getpeername()" Link "getpeername()"}
@{i}HISTORY@{ui}
The @{b}getsockname()@{ub} function call appeared in 4.2BSD.
@EndNode
@Node "getsockopt()" "bsdsocket.guide/getsockopt()"
@Next "htonl()"
@Prev "getsockname()"
@Toc "Function Reference"
@{b}getsockopt()@{ub}, @{b}setsockopt()@{ub}
==========================
@{i}NAME@{ui}
@{b}getsockopt@{ub}, @{b}setsockopt@{ub} -- get and set options on sockets
@{i}SYNOPSIS@{ui}
@{i}#include <sys/types.h>@{ui}
@{i}#include <sys/socket.h>@{ui}
@{i}int getsockopt(int s, int level,
D0 D0 D1
int optname, void * optval, int * optlen)
D2 A0 A1
int setsockopt(int s, int level,
D0 D0 D1
int optname, const void * optval, int optlen)
D2 A0 D3@{ui}
@{i}DESCRIPTION@{ui}
@{b}getsockopt()@{ub} and @{b}setsockopt()@{ub} manipulate the @{i}options@{ui} associated
with a socket. Options may exist at multiple protocol levels;
they are always present at the uppermost "socket" level.
When manipulating socket options the level at which the option
resides and the name of the option must be specified. To
manipulate options at the socket level, @{b}level@{ub} is specified as
@{b}SOL_SOCKET@{ub}. To manipulate options at any other level the
protocol number of the appropriate protocol controlling the option
is supplied. For example, to indicate that an option is to be
interpreted by the TCP protocol, @{b}level@{ub} should be set to the
protocol number of TCP; see @{"getprotobyname()" Link "getprotobyname()"}.
The parameters @{b}optval@{ub} and @{b}optlen@{ub} are used to access option values
for @{b}setsockopt()@{ub} For @{b}getsockopt()@{ub} they identify a buffer in which
the value for the requested option(s) are to be returned. For
@{b}getsockopt()@{ub} @{b}optlen@{ub} is a value-result parameter, initially
containing the size of the buffer pointed to by @{b}optval@{ub}, and
modified on return to indicate the actual size of the value
returned. If no option value is to be supplied or returned,
@{b}optval@{ub} may be @{b}NULL@{ub}.
@{b}optname@{ub} and any specified options are passed uninterpreted to the
appropriate protocol module for interpretation. The include file
@{b}<sys/socket.h>@{ub} contains definitions for socket level options,
described below. Options at other protocol levels vary in format
and name.
Most socket-level options utilize an @{b}int@{ub} parameter for @{b}optval@{ub}.
For @{b}setsockopt()@{ub} the parameter should be non-zero to enable a
boolean option, or zero if the option is to be disabled.
@{b}SO_LINGER@{ub} uses a @{b}struct@{ub} linger parameter, defined in
@{b}<sys/socket.h>@{ub}, which specifies the desired state of the
option and the linger interval (see below). @{b}SO_SNDTIMEO@{ub} and
@{b}SO_RCVTIMEO@{ub} use a @{b}struct@{ub} timeval parameter, defined in
@{b}<sys/time.h>@{ub}.
The following options are recognized at the socket level. Except
as noted, each may be examined with @{b}getsockopt()@{ub} and set with
@{b}setsockopt()@{ub}
@{b}SO_DEBUG@{ub}
enables recording of debugging information
@{b}SO_REUSEADDR@{ub}
enables local address reuse
@{b}SO_KEEPALIVE@{ub}
enables keep connections alive
@{b}SO_DONTROUTE@{ub}
enables routing bypass for outgoing messages
@{b}SO_LINGER@{ub}
linger on close if data present
@{b}SO_BROADCAST@{ub}
enables permission to transmit broadcast messages
@{b}SO_OOBINLINE@{ub}
enables reception of out-of-band data in band
@{b}SO_SNDBUF@{ub}
set buffer size for output
@{b}SO_RCVBUF@{ub}
set buffer size for input
@{b}SO_SNDLOWAT@{ub}
set minimum count for output
@{b}SO_RCVLOWAT@{ub}
set minimum count for input
@{b}SO_SNDTIMEO@{ub}
set timeout value for output
@{b}SO_RCVTIMEO@{ub}
set timeout value for input
@{b}SO_TYPE@{ub}
get the type of the socket (get only)
@{b}SO_ERROR@{ub}
get and clear error on the socket (get only)
@{b}SO_EVENTMASK@{ub}
set event mask to specify which events should be
notified to the application
@{b}SO_DEBUG@{ub} enables debugging in the underlying protocol modules.
@{b}SO_REUSEADDR@{ub} indicates that the rules used in validating
addresses supplied in a @{"bind()" Link "bind()"} call should allow reuse of local
addresses. @{b}SO_KEEPALIVE@{ub} enables the periodic transmission of
messages on a connected socket. Should the connected party fail
to respond to these messages, the connection is considered broken
and processes using the socket are notified via a @{b}SIGPIPE@{ub} signal
when attempting to send data. @{b}SO_DONTROUTE@{ub} indicates that
outgoing messages should bypass the standard routing facilities.
Instead, messages are directed to the appropriate network
interface according to the network portion of the destination
address.
@{b}SO_LINGER@{ub} controls the action taken when unsent messags are queued
on socket and a @{"CloseSocket()" Link "CloseSocket()"} is performed. If the socket
promises reliable delivery of data and @{b}SO_LINGER@{ub} isset, the system
will block the process on the @{"CloseSocket()" Link "CloseSocket()"} attempt until it is
able to transmit the data or until it decides it is unable to
deliver the information (a timeout period, termed the linger
interval, is specified in the @{b}setsockopt()@{ub} call when @{b}SO_LINGER@{ub} is
requested). If @{b}SO_LINGER@{ub} is disabled and a @{"CloseSocket()" Link "CloseSocket()"} is
issued, the system will process the close in a manner that allows
the process to continue as quickly as possible.
The option @{b}SO_BROADCAST@{ub} requests permission to send broadcast
datagrams on the socket. Broadcast was a privileged operation in
earlier versions of the system. With protocols that support
out-of-band data, the @{b}SO_OOBINLINE@{ub} option requests that
out-of-band data be placed in the normal data input queue as
received; it will then be accessible with @{"recv()" Link "recv()"} calls without the
@{b}MSG_OOB@{ub} flag. Some protocols always behave as if this option
is set. @{b}SO_SNDBUF@{ub} and @{b}SO_RCVBUF@{ub} are options to adjust the normal
buffer sizes allocated for output and input buffers, respectively.
The buffer size may be increased for high-volume connections, or
may be decreased to limit the possible backlog of incoming data.
The system places an absolute limit on these values.
@{b}SO_SNDLOWAT@{ub} is an option to set the minimum count for output
operations. Most output operations process all of the data
supplied by the call, delivering data to the protocol for
transmission and blocking as necessary for flow control.
Nonblocking output operations will process as much data as
permitted subject to flow control without blocking, but will
process no data if flow control does not allow the smaller of the
low water mark value or the entire request to be processed. A
@{"select()" Link "select()"} operation testing the ability to write to a socket will
return true only if the low water mark amount could be processed.
The default value for @{b}SO_SNDLOWAT@{ub} is set to a convenient size for
network efficiency, often 1024. @{b}SO_RCVLOWAT@{ub} is an option to set
the minimum count for input operations. In general, receive calls
will block until any (non-zero) amount of data is received, then
return with smaller of the amount available or the amount
requested. The default value for @{b}SO_SNDLOWAT@{ub} is 1. If
@{b}SO_SNDLOWAT@{ub} is set to a larger value, blocking receive
calls normally wait until they have received the smaller of the
low water mark value or the requested amount. Receive calls may
still return less than the low water mark if an error occurs, a
signal is caught, or the type of data next in the receive queue is
different than that returned.
@{b}SO_SNDTIMEO@{ub} is an option to set a timeout value for output
operations. It accepts a @{b}struct@{ub} timeval parameter with the number
of seconds and microseconds used to limit waits for output
operations to complete. If a send operation has blocked for this
much time, it returns with a partial count or with the error
@{b}EWOULDBLOCK@{ub} if no data were sent. In the current
implementation, this timer is restarted each time additional data
are delivered to the protocol, implying that the limit applies to
output portions ranging in size from the low water mark to the
high water mark for output. @{b}SO_RCVTIMEO@{ub} is an option to set a
timeout value for input operations. It accepts a @{b}struct@{ub}timeval
parameter with the number of seconds and microseconds used to
limit waits for input operations to complete. In the current
implementation, this timer is restarted each time additional data
are received by the protocol, and thus the limit is in effect an
inactivity timer. If a receive operation has been blocked for
this much time without receiving additional data, it returns with
a short count or with the error @{b}EWOULDBLOCK@{ub} if no data were
received.
Finally, @{b}SO_TYPE@{ub} and @{b}SO_ERROR@{ub} are options used only with
@{b}setsockopt()@{ub} @{b}SO_TYPE@{ub} returns the type of the socket, such as
@{b}SOCK_STREAM@{ub}; it is useful for servers that inherit sockets on
startup. @{b}SO_ERROR@{ub} returns any pending error on the socket and
clears the error status. It may be used to check for asynchronous
errors on connected datagram sockets or for other asynchronous
errors.
Additionally, @{b}SO_EVENTMASK@{ub} is used to specify which @{i}asynchronous
events@{ui} are to be notified to the socket owner. See
@{"GetSocketEvents()" Link "GetSocketEvents()"} for more info on this. @{b}SO_EVENTMASK@{ub} is AMITCP/IP
addition.
@{i}RETURN VALUES@{ui}
A 0 is returned if the call succeeds, -1 if it fails.
@{i}ERRORS@{ui}
The call succeeds unless:
@{b}[EBADF]@{ub}
The argument @{b}s@{ub} is not a valid descriptor.
@{b}[ENOPROTOOPT]@{ub}
The option is unknown at the level indicated.
@{i}SEE ALSO@{ui}
@{"IoctlSocket()" Link "IoctlSocket()"}, @{"socket()" Link "socket()"}, @{"getprotobyname()" Link "getprotobyname()"}, @{"GetSocketEvents()" Link "GetSocketEvents()"}
@{i}BUGS@{ui}
Several of the socket options should be handled at lower levels of
the system.
@{i}HISTORY@{ui}
The @{b}getsockopt()@{ub} system call appeared in 4.2BSD.
@EndNode
@Node "htonl()" "bsdsocket.guide/htonl()"
@Next "inet_addr()"
@Prev "getsockopt()"
@Toc "Function Reference"
@{b}htonl()@{ub}, @{b}htons()@{ub}, @{b}ntohl()@{ub}, @{b}ntohs()@{ub}
==================================
@{i}NAME@{ui}
@{b}htonl@{ub}, @{b}htons@{ub}, @{b}ntohl@{ub}, @{b}ntohs@{ub} -- convert values between host and
network byte order
@{i}SYNOPSIS@{ui}
@{i}#include <sys/param.h>@{ui}
@{i}u_long htonl(u_long hostlong)@{ui}
@{i}u_short htons(u_short hostshort)@{ui}
@{i}u_long ntohl(u_long netlong)@{ui}
@{i}u_short ntohs(u_short netshort)@{ui}
@{i}DESCRIPTION@{ui}
These routines convert 16 and 32 bit quantities between network
byte order and host byte order. On machines which have a byte
order which is the same as the network order, routines are defined
as null macros. Commodore Amiga is such a machine.
These routines are most often used in conjunction with Internet
addresses and ports as returned by @{"gethostbyname()" Link "gethostbyname()"} and
@{"getservbyname()" Link "getservbyname()"}.
@{i}SEE ALSO@{ui}
@{"gethostbyname()" Link "gethostbyname()"}, @{"getservbyname()" Link "getservbyname()"}
@{i}HISTORY@{ui}
The @{b}byteorder@{ub} -- functions appeared in 4.2BSD.
@{i}BUGS@{ui}
On the VAX bytes are handled backwards from most everyone else in
the world. This is not expected to be fixed in the near future.
@EndNode
@Node "inet_addr()" "bsdsocket.guide/inet_addr()"
@Next "IoctlSocket()"
@Prev "htonl()"
@Toc "Function Reference"
@{b}inet_addr()@{ub}, @{b}inet_network()@{ub}, @{b}inet_ntoa()@{ub}, @{b}inet_makeaddr()@{ub}, @{b}inet_lnaof()@{ub}, @{b}inet_netof()@{ub}
=====================================================================================
@{i}NAME@{ui}
@{b}inet_addr@{ub}, @{b}inet_network@{ub}, @{b}Inet_NtoA@{ub}, @{b}Inet_MakeAddr@{ub}, @{b}Inet_LnaOf@{ub},
@{b}Inet_NetOf@{ub} -- Internet address manipulation routines
@{b}inet_ntoa@{ub}, @{b}inet_makeaddr@{ub}, @{b}inet_lnaof@{ub}, @{b}inet_netof@{ub} -- inline/stub
functios of above to handle structure args
@{i}SYNOPSIS@{ui}
@{i}#include <sys/socket.h>@{ui}
@{i}#include <netinet/in.h>@{ui}
@{i}#include <arpa/inet.h>@{ui}
@{i}unsigned long inet_addr(const char * cp)@{ui}
@{i}D0 A0@{ui}
@{i}unsigned long inet_network(const char * cp)@{ui}
@{i}D0 A0@{ui}
@{i}char * Inet_NtoA(unsigned long in)@{ui}
@{i}D0 D0@{ui}
@{i}unsigned long Inet_MakeAddr(int net, int lna)@{ui}
@{i}D0 D0 D1@{ui}
@{i}unsigned long Inet_LnaOf(unsigned long in)@{ui}
@{i}D0 D0@{ui}
@{i}unsigned long Inet_NetOf(unsigned long in)@{ui}
@{i}D0 D0@{ui}
@{i}char * inet_ntoa(struct in_addr in)@{ui}
@{i}struct in_addr inet_makeaddr(int net, int lna)@{ui}
@{i}unsigned long inet_lnaof(struct in_addr in)@{ui}
@{i}unsigned long inet_netof(struct in_addr in)@{ui}
@{i}IMPLEMENTATION NOTE@{ui}
Return value of @{b}Inet_MakeAddr()@{ub} and argument types of
@{b}Inet_LnaOf()@{ub}, @{b}Inet_NetOf()@{ub} and @{b}Inet_NtoA()@{ub} are longs
instead of struct in_addr. The original behaviour is achieved by
using included stub functions (lower case function names) which
handle structure arguments.
@{i}DESCRIPTION@{ui}
The routines @{b}inet_addr()@{ub} and @{b}inet_network()@{ub} interpret character
strings representing numbers expressed in the Internet standard
`.' notation, returning numbers suitable for use as Internet
addresses and Internet network numbers, respectively. The routine
@{b}inet_ntoa()@{ub} takes an Internet address and returns an ASCII
string representing the address in base 256 notation "d.d.d.d"
described below .The routine @{b}inet_makeaddr()@{ub} takes an Internet
network number and a local network address and constructs an
Internet address from it. The routines @{b}inet_netof()@{ub} and
@{b}inet_lnaof()@{ub} break apart Internet host addresses, returning
the network number and local network address part, respectively.
All Internet addresses are returned in network order (bytes
ordered from left to right). All network numbers and local
address parts are returned as machine format integer values.
@{i}INTERNET ADDRESSES@{ui}
Values specified using the `.' notation take one of the following
forms:
@{i}a.b.c.d
a.b.c
a.b
a@{ui}
When four parts are specified, each is interpreted as a byte of
data and assigned, from left to right, to the four bytes of an
Internet address. Note that when an Internet address is viewed as
a 32-bit integer quantity on the VAX the bytes referred to above
appear as "d.c.b.a ." That is, VAX bytes are ordered from right
to left.
When a three part address is specified, the last part is
interpreted as a 16-bit quantity and placed in the right-most two
bytes of the network address. This makes the three part address
format convenient for specifying Class B network addresses as
"128.net.host ."
When a two part address is supplied, the last part is interpreted
as a 24-bit quantity and placed in the right most three bytes of
the network address. This makes the two part address format
convenient for specifying Class A network addresses as "net.host ."
When only one part is given, the value is stored directly in the
network address without any byte rearrangement.
All numbers supplied as "parts" in a `.' notation may be decimal,
octal, or hexadecimal, as specified in the C language (i.e., a
leading 0x or 0X implies hexadecimal; otherwise, a leading 0
implies octal; otherwise, the number is interpreted as decimal).
@{i}DIAGNOSTICS@{ui}
The constant @{b}INADDR_NONE@{ub} is returned by @{b}inet_addr()@{ub} and
@{b}inet_network()@{ub} for malformed requests.
@{i}SEE ALSO@{ui}
@{"gethostbyname()" Link "gethostbyname()"}
@{i}HISTORY@{ui}
These functions appeared in 4.2BSD.
@{i}BUGS@{ui}
The value @{b}INADDR_NONE@{ub} (0xffffffff) is a valid broadcast address,
but @{b}inet_addr()@{ub} cannot return that value without indicating
failure. The problem of host byte ordering versus network byte
ordering is confusing. A simple way to specify Class C network
addresses in a manner similar to that for Class B and Class A is
needed. The string returned by @{b}inet_ntoa()@{ub} resides in a static
memory area.
Inet_addr should return a @{b}struct@{ub} in_addr.
@EndNode
@Node "IoctlSocket()" "bsdsocket.guide/IoctlSocket()"
@Next "listen()"
@Prev "inet_addr()"
@Toc "Function Reference"
@{b}IoctlSocket()@{ub}
=============
@{i}NAME@{ui}
@{b}IoctlSocket@{ub} -- control sockets
@{i}SYNOPSIS@{ui}
@{i}#include <sys/ioctl.h>@{ui}
@{i}int IoctlSocket(int s, unsigned long request, char * argp)@{ui}
@{i}D0 D0 D1 A0@{ui}
@{i}DESCRIPTION@{ui}
@{b}IoctlSocket()@{ub} performs a special function on the object referred to
by the open socket descriptor s. Note: the @{"getsockopt()" Link "getsockopt()"} call is
the primary method for operating on sockets as such, rather than
on the underlying protocol or network interface.
For most @{b}IoctlSocket()@{ub} functions, argp is a pointer to data to be
used by the function or to be filled in by the function. Other
functions may ignore arg or may treat it directly as a data item;
they may, for example, be passed an int value.
An ioctl @{b}request@{ub} has encoded in it whether the argument is an "in"
parameter or "out" parameter, and the size of the argument @{b}argp@{ub} in
bytes. Macros and defines used in specifying an ioctl @{b}request@{ub} are
located in the file @{b}<sys/ioctl.h>@{ub}.
The following requests are supported:
@{b}FIOASYNC@{ub}
The argument is a pointer to a long. Set or clear
asynchronous I/O. If the value of that long is a 1 (one) the
descriptor is set for asynchronous I/O. If the value of that
long is a 0 (zero) the descriptor is cleared for asynchro-
nous I/O.
@{b}FIOCLEX@{ub}
@{b}FIONCLEX@{ub}
Ignored, no use for close-on-exec flag in Amiga.
@{b}FIOGETOWN@{ub}
@{b}SIOCGPGRP@{ub}
The argument is pointer to struct Task*. Set the value of
that pointer to the Task that is receiving SIGIO or SIGURG
signals for the socket referred to by the descriptor passed
to IoctlSocket().
@{b}FIONBIO@{ub}
The argument is a pointer to a long. Set or clear
non-blocking I/O. If the value of that long is a 1 (one) the
descriptor is set for non-blocking I/O. If the value of that
long is a 0 (zero) the descriptor is cleared for non-
blocking I/O.
@{b}FIONREAD@{ub}
The argument is a pointer to a long. Set the value of that
long to the number of immediately readable characters from
the socket fd.
@{b}FIOSETOWN@{ub}
@{b}SIOCSPGRP@{ub}
The argument is pointer to struct Task*, pointer to the task
that will subseq- uently receive SIGIO or SIGURG signals for
the socket referred to by the descriptor passed.
@{b}SIOCCATMARK@{ub}
The argument is a pointer to a long. Set the value of that
long to 1 if the read pointer for the socket referred to by
the descriptor passed to IoctlSocket() points to a mark in
the data stream for an out-of-band message, and to 0 if it
does not point to a mark.
@{i}RETURN VALUES@{ui}
@{b}IoctlSocket()@{ub} returns 0 on success for most requests. Some
specialized requests may return non-zero values on success; On
failure, @{b}IoctlSocket()@{ub} returns -1 and sets @{b}errno@{ub} to indicate the
error.
@{i}ERRORS@{ui}
@{b}Ioctl()@{ub} will fail:
@{b}[EBADF]@{ub}
@{b}s@{ub} is not a valid descriptor.
@{b}[EINVAL]@{ub}
@{b}Request@{ub} or @{b}argp@{ub} is not valid.
@{b}IoctlSocket()@{ub} will also fail if the object on which the function is
being performed detects an error. In this case, an error code
specific to the object and the function will be returned.
@{i}SEE ALSO@{ui}
@{"setsockopt()" Link "getsockopt()"}, @{"SocketBaseTagList()" Link "SocketBaseTagList()"}
@{i}HISTORY@{ui}
An @{b}ioctl()@{ub} function call appeared in Version 7 AT&T UNIX.
@EndNode
@Node "listen()" "bsdsocket.guide/listen()"
@Next "ObtainSocket()"
@Prev "IoctlSocket()"
@Toc "Function Reference"
@{b}listen()@{ub}
========
@{i}NAME@{ui}
@{b}listen@{ub} -- listen for connections on a socket
@{i}SYNOPSIS@{ui}
@{i}#include <sys/socket.h>@{ui}
@{i}int listen(int s, int backlog)@{ui}
@{i}D0 D0 D1@{ui}
@{i}DESCRIPTION@{ui}
To accept connections, a socket is first created with @{"socket()" Link "socket()"}, a
willingness to accept incoming connections and a queue limit for
incoming connections are specified with @{b}listen()@{ub} and then the
connections are accepted with @{"accept()" Link "accept()"}. The @{b}listen()@{ub} call applies
only to sockets of type @{b}SOCK_STREAM@{ub} or @{b}SOCK_SEQPACKET@{ub}.
The @{b}backlog@{ub} parameter defines the maximum length the queue of
pending connections may grow to. If a connection request arrives
with the queue full the client may receive an error with an
indication of @{b}ECONNREFUSED@{ub}, or, if the underlying protocol supports
retransmission, the request may be ignored so that retries may
succeed.
@{i}RETURN VALUES@{ui}
A 0 return value indicates success; -1 indicates an error.
@{i}ERRORS@{ui}
@{b}Listen()@{ub} will fail if:
@{b}[EBADF]@{ub}
The argument @{b}s@{ub} is not a valid descriptor.
@{b}[EOPNOTSUPP]@{ub}
The socket is not of a type that supports the operation
@{b}listen()@{ub}
@{i}SEE ALSO@{ui}
@{"accept()" Link "accept()"}, @{"connect()" Link "connect()"}, @{"socket()" Link "socket()"}
@{i}BUGS@{ui}
The @{b}backlog@{ub} is currently limited (silently) to 5.
@{i}HISTORY@{ui}
The @{b}listen()@{ub} function call appeared in 4.2BSD.
@EndNode
@Node "ObtainSocket()" "bsdsocket.guide/ObtainSocket()"
@Next "recv()"
@Prev "listen()"
@Toc "Function Reference"
@{b}ObtainSocket()@{ub}
==============
@{i}NAME@{ui}
@{b}ObtainSocket@{ub} -- get a previously released socket
@{i}SYNOPSIS@{ui}
@{i}LONG ObtainSocket(LONG id, LONG domain, LONG type, LONG protocol)@{ui}
@{i}D0 D0 D1 D2 D3@{ui}
@{i}FUNCTION@{ui}
When one task wants to give a socket to an another one, it
releases it (with a key value) to a special socket list held by
AmiTCP/IP. This function requests that socket and receives it if
id and other parameters match.
After release 3.0 of AMITCP/IP @{b}ObtainSocket()@{ub} can be called with an
unique id and @{b}domain@{ub} as ZERO to request any kind of socket that is
available with that @{b}id@{ub}.
@{i}INPUTS@{ui}
@{b}id@{ub}
a key value for finding the correct available socket.
@{b}domain@{ub}
see documentation of @{"socket()" Link "socket()"}.
@{b}type@{ub}
see documentation of @{"socket()" Link "socket()"}.
@{b}protocol@{ub}
see documentation of @{"socket()" Link "socket()"}.
@{i}RESULT@{ui}
Non negative socket descriptor on success. On failure, -1 is
returned and the errno is set to indicate the error.
@{i}ERRORS@{ui}
@{b}EMFILE@{ub}
The per-process descriptor table is full.
@{b}EPROTONOSUPPORT@{ub}
The protocol type or the specified protocol is not supported
within this domain.
@{b}EPROTOTYPE@{ub}
The protocol is the wrong type for the socket.
@{b}EWOULDBLOCK@{ub}
Matching socket is not found.
@{i}SEE ALSO@{ui}
@{"ReleaseSocket()" Link "ReleaseSocket()"}, @{"socket()" Link "socket()"}, @{"SocketBaseTagList()" Link "SocketBaseTagList()"}
@{i}NOTES@{ui}
@{b}ObtainSocket()@{ub} calls the @{b}fdCallback()@{ub} with action codes @{b}FDCB_CHECK@{ub}
and @{b}FDCB_ALLOC@{ub} to check and mark the new descriptor as allocated
if the callback is defined. It may also call the callback again
with @{b}FDCB_FREE@{ub}, if an error condition occurs. See
@{"SocketBaseTagList()" Link "SocketBaseTagList()"} for more information on @{b}fdCallback()@{ub}.
@EndNode
@Node "recv()" "bsdsocket.guide/recv()"
@Next "ReleaseSocket()"
@Prev "ObtainSocket()"
@Toc "Function Reference"
@{b}recv()@{ub}, @{b}recvfrom()@{ub}, @{b}recvmsg()@{ub}
=============================
@{i}NAME@{ui}
@{b}recv@{ub}, @{b}recvfrom@{ub}, @{b}recvmsg@{ub} -- receive a message from a socket
@{i}SYNOPSIS@{ui}
@{i}#include <sys/types.h>@{ui}
@{i}#include <sys/socket.h>@{ui}
@{i}int recv(int s, void * buf, int len, int flags)@{ui}
@{i}D0 D0 A0 D1 D2@{ui}
@{i}int recvfrom(int s, void * buf, int len, int flags,@{ui}
@{i}D0 D0 A0 D1 D2 @{ui}
@{i} struct sockaddr * from, int * fromlen)@{ui}
@{i} A1 A2@{ui}
@{i}int recvmsg(int s, struct msghdr * msg, int flags)@{ui}
@{i}D0 D0 A0 D1@{ui}
@{i}DESCRIPTION@{ui}
@{b}Recv()@{ub}, @{b}recvfrom()@{ub} and @{b}recvmsg()@{ub} are used to receive messages from
a socket. @{b}Recv()@{ub} may be used only on a connected socket (see
@{"connect()" Link "connect()"}), while @{b}recvfrom()@{ub} and @{b}recvmsg()@{ub} and may be used to
receive data on a socket whether or not it is connection-oriented.
If @{b}from@{ub} is non-nil, and the socket is not connection-oriented, the
source address of the message is filled in. @{b}Fromlen@{ub} is a
value-result parameter, initialized to the size of the buffer
associated with @{b}from@{ub}, and modified on return to indicate the
actual size of the address stored there.
All three routines return the length of the message on successful
completion. If a message is too long to fit in the supplied
buffer, excess bytes may be discarded depending on the type of
socket the message is received from (see @{"socket()" Link "socket()"}).
If no messages are available at the socket, the receive call waits
for a message to arrive, unless the socket is nonblocking (see
@{"IoctlSocket()" Link "IoctlSocket()"}) in which case the value -1 is returned and the
library variable @{b}errno@{ub} (see @{"Errno()" Link "Errno()"}) set to @{b}EWOULDBLOCK@{ub}. The
receive calls normally return any data available, up to the
requested amount, rather than waiting for receipt of the full
amount requested; this behavior is affected by the socket-level
options @{b}SO_RCVLOWAT@{ub} and @{b}SO_RCVTIMEO@{ub} described in @{"getsockopt()" Link "getsockopt()"}.
The @{"select()" Link "select()"} call may be used to determine when more data arrive.
The @{b}flags@{ub} argument to a recv call is formed by @{i}or@{ui}'ing one or more
of the values:
@{b}MSG_OOB@{ub}
process out-of-band data
@{b}MSG_PEEK@{ub}
peek at incoming message
@{b}MSG_WAITALL@{ub}
wait for full request or error
The @{b}MSG_OOB@{ub} flag requests receipt of out-of-band data that would
not be received in the normal data stream. Some protocols place
expedited data at the head of the normal data queue, and thus this
flag cannot be used with such protocols. The @{b}MSG_PEEK@{ub} flag causes
the receive operation to return data from the beginning of the
receive queue without removing that data from the queue. Thus, a
subsequent receive call will return the same data. The
@{b}MSG_WAITALL@{ub} flag requests that the operation block until
the full request is satisfied. However, the call may still return
less data than requested if a signal is caught, an error or
disconnect occurs, or the next data to be received is of a
different type than that returned.
The @{b}recvmsg()@{ub} call uses a @{b}msghdr@{ub} structure to minimize the number
of directly supplied parameters. This structure has the following
form, as defined in @{b}<sys/socket.h>@{ub}:
@{i}struct msghdr {
caddr_t msg_name; /*@{i} optional address @{ui}*/
u_int msg_namelen; /*@{i} size of address @{ui}*/
struct iovec *msg_iov; /*@{i} scatter/gather array @{ui}*/
u_int msg_iovlen; /*@{i} # elements in msg_iov @{ui}*/
caddr_t msg_control; /*@{i} ancillary data, see below @{ui}*/
u_int msg_controllen; /*@{i} ancillary data buffer len @{ui}*/
int msg_flags; /*@{i} flags on received message @{ui}*/
};@{ui}
Here @{b}msg_name@{ub} and @{b}msg_namelen@{ub} specify the destination address if
the socket is unconnected; @{b}msg_name@{ub} may be given as a null pointer
if no names are desired or required. @{b}Msg_iov@{ub} and @{b}msg_iovlen@{ub}
describe scatter gather locations, the input data is scattered
into @{b}msg_iovlen@{ub} buffers spesified by the members of the @{b}msg_iov@{ub}
array: @{b}msg_iov[0]@{ub}, @{b}msg_iov[0]@{ub}, ..., @{b}msg_iov[@{b}msg_iovlen@{ub} - 1]@{ub}.
The @{b}iovec@{ub} structure is defined as
@{i}struct iovec {
caddr_t iov_base;
int iov_len;
};
@{ui}
Each @{b}iovec@{ub} entry specifies the base address and length of an area
in memory where data should be placed. @{b}Recvmsg()@{ub} will always fill
an area completely before proceeding to the next.
The fields @{b}msg_control@{ub} and @{b}msg_controllen@{ub} are not currently used
in this implementation, set them as 0 before use.
The @{b}msg_flags@{ub} field is set on return according to the message
received. @{b}MSG_EOR@{ub} indicates end-of-record; the data returned
completed a record (generally used with sockets of type
@{b}SOCK_SEQPACKET@{ub}). @{b}MSG_TRUNC@{ub} indicates that the trailing
portion of a datagram was discarded because the datagram was
larger than the buffer supplied. @{b}MSG_CTRUNC@{ub} indicates that some
control data were discarded due to lack of space in the buffer for
ancillary data. @{b}MSG_OOB@{ub} is returned to indicate that expedited or
out-of-band data were received.
@{i}RETURN VALUES@{ui}
These calls return the number of bytes received, or -1 if an error
occurred.
@{i}ERRORS@{ui}
The calls fail if:
@{b}[EBADF]@{ub}
The argument @{b}s@{ub} is an invalid descriptor.
@{b}[ENOTCONN]@{ub}
The socket is assoicated with a connection-oriented protocol
and has not been connected (see @{"connect()" Link "connect()"} and @{"accept()" Link "accept()"}).
@{b}[EWOULDBLOCK]@{ub}
The socket is marked non-blocking, and the receive operation
would block, or a receive timeout had been set, and the
timeout expired before data were received.
@{b}[EINTR]@{ub}
The receive was interrupted by delivery of a signal before
any data were available.
@{i}SEE ALSO@{ui}
@{"getsockopt()" Link "getsockopt()"}, @{"IoctlSocket()" Link "IoctlSocket()"}, @{"select()" Link "select()"}, @{"send()" Link "send()"}, @{"socket()" Link "socket()"}
@{i}HISTORY@{ui}
The @{b}recv()@{ub} function call appeared in 4.2BSD.
@EndNode
@Node "ReleaseSocket()" "bsdsocket.guide/ReleaseSocket()"
@Next "select()"
@Prev "recv()"
@Toc "Function Reference"
@{b}ReleaseSocket()@{ub}, @{b}ReleaseCopyOfSocket()@{ub}
======================================
@{i}NAME@{ui}
@{b}ReleaseSocket@{ub}, @{b}ReleaseCopyOfSocket@{ub} -- make a socket be available
with ObtainSocket() call.
@{i}SYNOPSIS@{ui}
@{i}LONG ReleaseSocket(LONG sd, LONG id)@{ui}
@{i}D0 D0 D1@{ui}
@{i}LONG ReleaseCopyOfSocket(LONG sd, LONG id)@{ui}
@{i}D0 D0 D1@{ui}
@{i}FUNCTION@{ui}
The @{b}ReleaseSocket()@{ub} removes the socket pointed by descriptor @{b}sd@{ub}
from it's descriptor table and puts it available via next
@{"ObtainSocket()" Link "ObtainSocket()"} call.
The @{b}ReleaseCopyOfSocket()@{ub} makes a new reference to given socket
and that is made available to another caller.
@{i}INPUTS@{ui}
@{b}sd@{ub}
descriptor of the socket to be released.
@{b}id@{ub}
the key value to identify use of this socket. It can be
unique or not, depending on its value. If @{b}id@{ub} value is
between 0 and 65535, inclusively, it is considered
nonunique and it can be used as a port number, for
example. If @{b}id@{ub} is greater than 65535 and less than
2^31) it must be unique in currently held sockets in
AMITCP/IP socket list, Otherwise an error will be
returned and socket is not released. If @{b}id@{ub} == UNIQUE_ID
(defined in @{b}<sys/socket.h>@{ub}) an unique id will be
generated.
@{i}RESULT@{ui}
-1 in case of error, otherwise the key value of the socket put in
the list. Most useful when an unique id is generated by this
routine.
@{i}ERRORS@{ui}
@{b}EINVAL@{ub}
Requested unique id is already used.
@{b}ENOMEM@{ub}
The memory needed could not be allocated.
@{i}NOTE@{ui}
In case of @{b}ReleaseCopyOfSocket()@{ub}. The socket descriptor is not
deallocated from the descriptor table of the calling task.
@{i}SEE ALSO@{ui}
@{"ObtainSocket()" Link "ObtainSocket()"}. @{"SocketBaseTagList()" Link "SocketBaseTagList()"}
@{i}NOTES@{ui}
@{b}ReleaseSocket()@{ub} (but not @{b}ReleaseCopyOfSocket()@{ub}) calls the
@{b}fdCallback()@{ub} with action code @{b}FDCB_FREE@{ub} if the callback is
defined. See @{"SocketBaseTagList()" Link "SocketBaseTagList()"} for more information on
@{b}fdCallback()@{ub}.
@EndNode
@Node "select()" "bsdsocket.guide/select()"
@Next "send()"
@Prev "ReleaseSocket()"
@Toc "Function Reference"
@{b}select()@{ub}, @{b}WaitSelect()@{ub}
======================
@{i}NAME@{ui}
@{b}select@{ub} -- synchronous I/O multiplexing (stub/inline function)
@{b}WaitSelect@{ub} -- select() with Exec @{b}Wait()@{ub} function.
@{i}SYNOPSIS@{ui}
@{i}#include <sys/types.h>@{ui}
@{i}#include <sys/time.h>@{ui}
@{i}
int select(int nfds, fd_set * readfds, fd_set * writefds,
fd_set * exceptfds, struct timeval * timeout)
int WaitSelect(int nfds, fd_set * readfds, fd_set * writefds,
D0 D0 A0 A1
fd_set * exceptfds, struct timeval * timeout,
A2 A3
ULONG * sigmask)
D1
FD_SET(fd, &fdset)
FD_CLR(fd, &fdset)
FD_ISSET(fd, &fdset)
FD_ZERO(&fdset)@{ui}
@{i}DESCRIPTION@{ui}
@{b}Select()@{ub} examines the I/O descriptor sets whose addresses are
passed in @{b}readfds@{ub}, @{b}writefds@{ub}, and @{b}exceptfds@{ub} to see if some of their
descriptors are ready for reading, are ready for writing, or have
an exceptional condition pending, respectively. The first @{b}nfds@{ub}
descriptors are checked in each set; i.e., the descriptors from 0
through @{b}nfds@{ub}-1 in the descriptor sets are examined. On return,
@{b}select()@{ub} replaces the given descriptor sets with subsets
consisting of those descriptors that are ready for the requested
operation. @{b}Select()@{ub} returns the total number of ready descriptors
in all the sets.
@{b}WaitSelect()@{ub} also takes a signal mask which is waited during normal
@{b}select()@{ub} operation. If one of these singals is received,
@{b}WaitSelect()@{ub} returns and has re-set the signal mask to return
those signals that have arrived and value 0 is returned (total
number of ready descriptors in all the sets, which is currently
zero for efficiency reasons).
The descriptor sets are stored as bit fields in arrays of
integers. The following macros are provided for manipulating such
descriptor sets: @{b}FD_ZERO(&fdset)@{ub} initializes a descriptor set
@{b}fdset@{ub} to the null set. @{b}FD_SET(fd, &fdset)@{ub} includes a
particular descriptor @{b}fd@{ub} in @{b}fdset@{ub}. @{b}FD_CLR(fd, &fdset)@{ub} removes @{b}fd@{ub}
from @{b}fdset@{ub}. @{b}FD_ISSET(fd, &fdset)@{ub} is non-zero if @{b}fd@{ub} is a member of
@{b}fdset@{ub}, zero otherwise. The behavior of these macros is
undefined if a descriptor value is less than zero or greater than
or equal to @{b}FD_SETSIZE@{ub}, which is normally at least equal to the
maximum number of descriptors supported by the system.
If @{b}timeout@{ub} is a non-nil pointer, it specifies a maximum interval to
wait for the selection to complete. If @{b}timeout@{ub} is a nil pointer,
the select blocks indefinitely. To affect a poll, the @{b}timeout@{ub}
argument should be non-nil, pointing to a zero-valued timeval
structure.
Any of @{b}readfds@{ub}, @{b}writefds@{ub}, and @{b}exceptfds@{ub} may be given as NULL
pointers if no descriptors are of interest.
Selecting true for reading on a socket descriptor upon which a
@{b}listen()@{ub} call has been performed indicates that a subsequent
@{b}accept()@{ub} call on that descriptor will not block.
@{i}RETURN VALUES@{ui}
@{b}Select()@{ub} returns the number of ready descriptors that are contained
in the descriptor sets, or -1 if an error occurred. If the time
limit expires (or signal in mask arrives), the functions returns
0. If error is returned, including one due to an interrupted
call, the descriptor sets will be unmodified.
@{i}ERRORS@{ui}
An error return from @{b}select()@{ub} indicates:
@{b}[EBADF]@{ub}
One of the descriptor sets specified an invalid descriptor.
@{b}[EINTR]@{ub}
A signal was delivered before the time limit expired and
before any of the selected events occurred.
@{b}[EINVAL]@{ub}
The specified time limit is invalid. One of its components
is negative or too large.
@{i}SEE ALSO@{ui}
@{"accept()" Link "accept()"}, @{"connect()" Link "connect()"}, @{"recv()" Link "recv()"}, @{"send()" Link "send()"}, @{"getdtablesize()" Link "getdtablesize()"},
@{"SocketBaseTagList()" Link "SocketBaseTagList()"}
@{i}NOTES@{ui}
@{b}Select()@{ub} is actually a stub/inline function that calls
@{b}WaitSelect()@{ub} with a signal mask set as NULL pointer.
@{i}BUGS@{ui}
@{b}WaitSelect()@{ub} should probably return the time remaining from the
original timeout, if any, by modifying the time value in place.
This may be implemented in future versions of the system. Thus,
it is unwise to assume that the timeout value will be unmodified
by the @{b}WaitSelect()@{ub} call.
@{i}HISTORY@{ui}
The @{b}select()@{ub} function call appeared in 4.2BSD.
@EndNode
@Node "send()" "bsdsocket.guide/send()"
@Next "SetErrnoPtr()"
@Prev "select()"
@Toc "Function Reference"
@{b}send()@{ub}, @{b}sendto()@{ub}, @{b}sendmsg()@{ub}
===========================
@{i}NAME@{ui}
@{b}send@{ub}, @{b}sendto@{ub}, @{b}sendmsg@{ub} -- send a message from a socket
@{i}SYNOPSIS@{ui}
@{i}#include <sys/types.h>@{ui}
@{i}#include <sys/socket.h>@{ui}
@{i}int send(int s, const void * msg, int len, int flags)@{ui}
@{i}D0 D0 A0 D1 D2@{ui}
@{i}int sendto(int s, const void * msg, int len, int flags,@{ui}
@{i}D0 D0 A0 D1 D2@{ui}
@{i} const struct sockaddr * to, int tolen)@{ui}
@{i} A1 D3@{ui}
@{i}int sendmsg(int s, const struct msghdr * msg, int flags)@{ui}
@{i}D0 D0 A0 D1@{ui}
@{i}DESCRIPTION@{ui}
@{b}Send()@{ub} @{b}sendto()@{ub} and @{b}sendmsg()@{ub} are used to transmit a message to
another socket. @{b}Send()@{ub} may be used only when the socket is in a
@{i}connected@{ui} state, while @{b}sendto()@{ub} and @{b}sendmsg()@{ub} may be used at
any time.
The address of the target is given by @{b}to@{ub} with @{b}tolen@{ub} specifying its
size. The length of the message is given by @{b}len@{ub}. If the message
is too long to pass atomically through the underlying protocol,
the error @{b}EMSGSIZE@{ub} is returned, and the message is not transmitted.
No indication of failure to deliver is implicit in a @{b}send()@{ub} Locally
detected errors are indicated by a return value of -1.
If no messages space is available at the socket to hold the
message to be transmitted, then @{b}send()@{ub} normally blocks, unless the
socket has been placed in non-blocking I/O mode. The @{"select()" Link "select()"}
call may be used to determine when it is possible to send more
data.
The @{b}flags@{ub} parameter may include one or more of the following:
@{i}#define MSG_OOB 0x1 /*@{i} process out-of-band data @{ui}*/
#define MSG_DONTROUTE 0x4 /*@{i} bypass routing, use direct interface @{ui}*/
@{ui}
The flag @{b}MSG_OOB@{ub} is used to send "out-of-band" data on sockets
that support this notion (e.g. @{b}SOCK_STREAM@{ub}); the underlying
protocol must also support "out-of-band" data. @{b}MSG_DONTROUTE@{ub} is
usually used only by diagnostic or routing programs.
See @{"recv()" Link "recv()"} for a description of the @{b}msghdr@{ub} structure.
@{i}RETURN VALUES@{ui}
The call returns the number of characters sent, or -1 if an error
occurred.
@{i}ERRORS@{ui}
@{b}Send()@{ub} @{b}sendto()@{ub} and @{b}sendmsg()@{ub} fail if:
@{b}[EBADF]@{ub}
An invalid descriptor was specified.
@{b}[EMSGSIZE]@{ub}
The socket requires that message be sent atomically, and the
size of the message to be sent made this impossible.
@{b}[EWOULDBLOCK]@{ub}
The socket is marked non-blocking and the requested operation
would block.
@{b}[ENOBUFS]@{ub}
The system was unable to allocate an internal buffer. The
operation may succeed when buffers become available.
@{b}[ENOBUFS]@{ub}
The output queue for a network interface was full. This
generally indicates that the interface has stopped sending,
but may be caused by transient congestion.
@{i}SEE ALSO@{ui}
@{"IoctlSocket()" Link "IoctlSocket()"}, @{"recv()" Link "recv()"}, @{"select()" Link "select()"}, @{"getsockopt()" Link "getsockopt()"}, @{"socket()" Link "socket()"}
@{i}HISTORY@{ui}
The @{b}send()@{ub} function call appeared in 4.2BSD.
@EndNode
@Node "SetErrnoPtr()" "bsdsocket.guide/SetErrnoPtr()"
@Next "SetSocketSignals()"
@Prev "send()"
@Toc "Function Reference"
@{b}SetErrnoPtr()@{ub}
=============
@{i}NAME@{ui}
@{b}SetErrnoPtr@{ub} -- set the "global" errno pointer (OBSOLETE)
@{i}SYNOPSIS@{ui}
@{i}void SetErrnoPtr(void * ptr, int size)@{ui}
@{i} A0 D0@{ui}
@{i}FUNCTION@{ui}
This functions allows caller to redirect error variable inside
scope of caller task. Usually this is used to make task's global
variable errno as error variable.
Since AMITCP/IP version 3.0 you can use function
@{"SocketBaseTagList()" Link "SocketBaseTagList()"} to set error value pointer.
@{i}INPUTS@{ui}
@{b}ptr@{ub}
pointer to error variable that is to be modified on every
error condition on this library function.
@{b}size@{ub}
size of the error variable. It can be 1, 2 or 4 bytes long.
@{i}EXAMPLE@{ui}
@{i} #include <errno.h>
struct Library;
struct Library * SocketBase = NULL;
int main(void)
{
...
if ((SocketBase = OpenLibrary("bsdsocket.library", 2))
!= NULL) {
SetErrnoPtr(&errno, sizeof errno);
...
}
}@{ui}
@{i}NOTES@{ui}
Be sure that this new error variable exists until library base is
finally closed or @{b}SetErrnoPtr()@{ub} is called again for another
variable.
@{i}SEE ALSO@{ui}
@{"Errno()" Link "Errno()"}, @{"SocketBaseTagList()" Link "SocketBaseTagList()"}
@EndNode
@Node "SetSocketSignals()" "bsdsocket.guide/SetSocketSignals()"
@Next "shutdown()"
@Prev "SetErrnoPtr()"
@Toc "Function Reference"
@{b}SetSocketSignals()@{ub}
==================
@{i}NAME@{ui}
@{b}SetSocketSignals@{ub} -- set SIGINTR, SIGIO and SIGURG signals
(OBSOLETE).
@{i}SYNOPSIS@{ui}
@{i}void SetSocketSignals(ULONG intrmask, ULONG iomask, ULONG urgmask)@{ui}
@{i} D0 D1 D2@{ui}
@{i}FUNCTION@{ui}
@{b}SetSocketSignals()@{ub} tells the AMITCP/IP which signal masks
corresponds unix SIGINT, SIGIO and SIGURG signals to be used in
current amiga software. The @{b}intrmask@{ub} mask is used to determine
which Amiga signals interrupt blocking library calls.
The @{b}iomask@{ub} is sent when asynchronous notification of socket events
is done and the urgmask is sent when out-of-band data arrives.
The signals are sent only to the owning task of particular socket.
The task that creates the socket is set to the owner of the
socket by default. If the socket is inherited with the
@{"ObtainSocket()" Link "ObtainSocket()"} function, the owner must be set explicitly with the
@{b}FIOSETOWN@{ub} (@{b}SIOCSPGRP@{ub}) @{"IoctlSocket()" Link "IoctlSocket()"} call.
Note that the supplied values write over old ones. If this
function is used and CTRL-C is still wanted to interrupt the calls
(the default behaviour), the value SIGBREAKF_CTRL_C must be
explicitly @{i}or@{ui}'ed to the @{b}intrmask@{ub}.
@{i}NOTES@{ui}
The function @{b}SetSocketSignals()@{ub} is obsoleted by the function
@{"SocketBaseTagList()" Link "SocketBaseTagList()"}.
@{i}SEE ALSO@{ui}
@{"IoctlSocket()" Link "IoctlSocket()"}, @{"recv()" Link "recv()"}, @{"send()" Link "send()"}, @{"select()" Link "select()"}, @{"SetSocketSignals()" Link "SetSocketSignals()"}
@EndNode
@Node "shutdown()" "bsdsocket.guide/shutdown()"
@Next "socket()"
@Prev "SetSocketSignals()"
@Toc "Function Reference"
@{b}shutdown()@{ub}
==========
@{i}NAME@{ui}
@{b}shutdown@{ub} -- shut down part of a full-duplex connection
@{i}SYNOPSIS@{ui}
@{i}#include <sys/socket.h>@{ui}
@{i}int shutdown(int s, int how)@{ui}
@{i}D0 D0 D1@{ui}
@{i}DESCRIPTION@{ui}
The @{b}shutdown()@{ub} call causes all or part of a full-duplex connection
on the socket associated with @{b}s@{ub} to be shut down. If @{b}how@{ub} is 0,
further receives will be disallowed. If @{b}how@{ub} is 1, further sends
will be disallowed. If @{b}how@{ub} is 2, further sends and receives will
be disallowed.
@{i}DIAGNOSTICS@{ui}
A 0 is returned if the call succeeds, -1 if it fails.
@{i}ERRORS@{ui}
The call succeeds unless:
@{b}[EBADF]@{ub}
@{b}S@{ub} is not a valid descriptor.
@{b}[ENOTCONN]@{ub}
The specified socket is not connected.
@{i}SEE ALSO@{ui}
@{"connect()" Link "connect()"}, @{"socket()" Link "socket()"}
@{i}HISTORY@{ui}
The @{b}shutdown()@{ub} function call appeared in 4.2BSD.
@EndNode
@Node "socket()" "bsdsocket.guide/socket()"
@Next "SocketBaseTagList()"
@Prev "shutdown()"
@Toc "Function Reference"
@{b}socket()@{ub}
========
@{i}NAME@{ui}
@{b}socket@{ub} -- create an endpoint for communication
@{i}SYNOPSIS@{ui}
@{i}#include <sys/types.h>@{ui}
@{i}#include <sys/socket.h>@{ui}
@{i}int socket(int domain, int type, int protocol)@{ui}
@{i}D0 D0 D1 D2@{ui}
@{i}DESCRIPTION@{ui}
@{b}Socket()@{ub} creates an endpoint for communication and returns a
descriptor.
The @{b}domain@{ub} parameter specifies a communications domain within which
communication will take place; this selects the protocol family
which should be used. These families are defined in the include
file @{b}<sys/socket.h>@{ub}. The currently understood formats are
@{i}AF_UNIX (UNIX internal protocols),
AF_INET (ARPA Internet protocols),
AF_ISO (ISO protocols),
AF_NS (Xerox Network Systems protocols), and
AF_IMPLINK (IMP ``host at IMP'' link layer).@{ui}
AMITCP/IP currently supports only @{i}AF_INET@{ui} protocol family.
The socket has the indicated @{b}type@{ub}, which specifies the semantics of
communication. Currently defined types are:
@{i}SOCK_STREAM
SOCK_DGRAM
SOCK_RAW
SOCK_SEQPACKET
SOCK_RDM@{ui}
A @{b}SOCK_STREAM@{ub} type provides sequenced, reliable, two-way connection
based byte streams. An out-of-band data transmission mechanism
may be supported. A @{b}SOCK_DGRAM@{ub} socket supports datagrams
(connectionless, unreliable messages of a fixed (typically small)
maximum length). A @{b}SOCK_SEQPACKET@{ub} socket may provide a sequenced,
reliable, two-way connection-based data transmission path for
datagrams of fixed maximum length; a consumer may be required to
read an entire packet with each read system call. This facility
is protocol specific, and presently implemented only for @{b}PF_NS@{ub}.
@{b}SOCK_RAW@{ub} sockets provide access to internal network protocols
and interfaces. The types @{b}SOCK_RAW@{ub}, which is available only to
the super-user, and @{b}SOCK_RDM@{ub}, which is planned, but not yet
implemented, are not described here.
The @{b}protocol@{ub} specifies a particular protocol to be used with the
socket. Normally only a single protocol exists to support a
particular socket type within a given protocol family. However,
it is possible that many protocols may exist, in which case a
particular protocol must be specified in this manner. The
protocol number to use is particular to the "communication domain"
in which communication is to take place.
Sockets of type @{b}SOCK_STREAM@{ub} are full-duplex byte streams, similar
to pipes. A stream socket must be in a @{i}connected@{ui} state before any
data may be sent or received on it. A connection to another
socket is created with a @{"connect()" Link "connect()"} call. Once connected, data may
be transferred using @{"recv()" Link "recv()"} and @{"send()" Link "send()"} or their variant calls.
When a session has been completed a @{"CloseSocket()" Link "CloseSocket()"} may be
performed. Out-of-band data may also be transmitted as described
in @{"send()" Link "send()"} and received as described in @{"recv()" Link "recv()"}.
The communications protocols used to implement a @{b}SOCK_STREAM@{ub} insure
that data is not lost or duplicated. If a piece of data for which
the peer protocol has buffer space cannot be successfully
transmitted within a reasonable length of time, then the
connection is considered broken and calls will indicate an error
with -1 returns and with @{b}ETIMEDOUT@{ub} as the specific error code (see
@{"Errno()" Link "Errno()"}). The protocols optionally keep sockets "warm" by forcing
transmissions roughly every minute in the absence of other
activity. An error is then indicated if no response can be
elicited on an otherwise idle connection for a extended period
(e.g. 5 minutes).
@{b}SOCK_SEQPACKET@{ub} sockets employ the same system calls as @{b}SOCK_STREAM@{ub}
sockets. The only difference is that @{"recv()" Link "recv()"} calls will return
only the amount of data requested, and any remaining in the
arriving packet will be discarded.
@{b}SOCK_DGRAM@{ub} and @{b}SOCK_RAW@{ub} sockets allow sending of datagrams to
correspondents named in @{"send()" Link "send()"} calls. Datagrams are generally
received with @{"recvfrom()" Link "recv()"}, which returns the next datagram with its
return address.
An @{"IoctlSocket()" Link "IoctlSocket()"} call can be used to specify a task to receive a
@{b}SIGURG@{ub} signal when the out-of-band data arrives. It may also
enable non-blocking I/O and asynchronous notification of I/O events
via @{b}SIGIO@{ub}.
The operation of sockets is controlled by socket level @{i}options@{ui}.
These options are defined in the file @{b}<sys/socket.h>@{ub}.
@{b}setsockopt()@{ub} and @{"getsockopt()" Link "getsockopt()"} are used to set and get
options, respectively.
@{i}RETURN VALUES@{ui}
A -1 is returned if an error occurs, otherwise the return value is
a descriptor referencing the socket.
@{i}ERRORS@{ui}
The @{b}socket()@{ub} call fails if:
@{b}[EPROTONOSUPPORT]@{ub}
The protocol type or the specified protocol is not supported
within this domain.
@{b}[EMFILE]@{ub}
The per-process descriptor table is full.
@{b}[EACCESS]@{ub}
Permission to create a socket of the specified type and/or
protocol is denied.
@{b}[ENOBUFS]@{ub}
Insufficient buffer space is available. The socket cannot be
created until sufficient resources are freed.
@{i}SEE ALSO@{ui}
@{"accept()" Link "accept()"}, @{"bind()" Link "bind()"}, @{"connect()" Link "connect()"}, @{"CloseSocket()" Link "CloseSocket()"}, @{"getprotobyname()" Link "getprotobyname()"},
@{"getsockname()" Link "getsockname()"}, @{"getsockopt()" Link "getsockopt()"}, @{"IoctlSocket()" Link "IoctlSocket()"}, @{"listen()" Link "listen()"}, @{"recv()" Link "recv()"},
@{"select()" Link "select()"}, @{"send()" Link "send()"}, @{"shutdown()" Link "shutdown()"}, @{"SocketBaseTagList()" Link "SocketBaseTagList()"}
`An Introductory 4.3 BSD Interprocess Communication Tutorial',
reprinted in UNIX Programmer's Supplementary Documents Volume 1.
`BSD Interprocess Communication Tutorial', reprinted in UNIX
Programmer's Supplementary Documents Volume 1.
@{i}NOTES@{ui}
@{b}socket()@{ub} calls the @{b}fdCallback()@{ub} with action codes @{b}FDCB_CHECK@{ub} and
@{b}FDCB_ALLOC@{ub} to check and mark the new descriptor as allocated
if the callback is defined. See @{"SocketBaseTagList()" Link "SocketBaseTagList()"} for more
information on @{b}fdCallback()@{ub}.
@{i}HISTORY@{ui}
The @{b}socket()@{ub} function call appeared in 4.2BSD.
@EndNode
@Node "SocketBaseTagList()" "bsdsocket.guide/SocketBaseTagList()"
@Next "syslog()"
@Prev "socket()"
@Toc "Function Reference"
@{b}SocketBaseTagList()@{ub}
===================
@{i}NAME@{ui}
@{b}SocketBaseTagList@{ub} -- Set/Get SocketBase attributes.
@{i}SYNOPSIS@{ui}
@{i}#include <amitcp/socketbasetags.h>@{ui}
@{i}ULONG SocketBaseTagList(struct TagItem * taglist);@{ui}
@{i}D0 A0@{ui}
@{i}ULONG SocketBaseTags(ULONG tag, ...);@{ui}
@{i}FUNCTION@{ui}
Set or get a list of (mostly) SocketBase instance dependent
attributes from the AMITCP/IP.
@{i}INPUTS@{ui}
These functions expect as their argument a standard tag list, one
or several array of struct TagItem as defined in the header file
@{b}<utility/tagitem.h>@{ub}. The structure contains two fields: @{b}ti_Tag@{ub}
and @{b}ti_Data@{ub}. The @{b}ti_Tag@{ub} field contains tag code, which determines
what the @{b}SocketBaseTagList()@{ub} should do with its argument, the
@{b}ti_Data@{ub} field.
The include file @{b}<amitcp/socketbasetags.h>@{ub} defines macros for base
tag code values. Base tag code macros begin with `SBTC_' (as
Socket Base Tag Code). The base tag value defines what data item
the tag item refers.
The tag code contains other information besides the referred data
item. It controls, whether the @{b}SocketBaseTagList()@{ub} should set or
get the appropriate parameter, and whether the argument of the tag
in question is passed by value or by reference.
The include file @{b}<amitcp/socketbasetags.h>@{ub} defines the following
macros, which are used to construct the @{b}ti_Tag@{ub} values from the base
tag codes:
SBTM_GETREF(code) - get by reference
SBTM_GETVAL(code) - get by value
SBTM_SETREF(code) - set by reference
SBTM_SETVAL(code) - set by value
If the actual data is stored directly into the @{b}ti_Data@{ub} field, you
should use the 'by value' macros, @{b}SBTM_GETVAL()@{ub} or @{b}SBTM_SETVAL()@{ub}.
However, if the @{b}ti_Data@{ub} field contains a pointer to actual data,
you should use the 'by reference' macros, @{b}SBTM_GETREF()@{ub} or
@{b}SBTM_SETREF()@{ub}. In either case the actual data should always
be a LONG aligned to even address.
According the used tag naming scheme a tag which has "PTR" suffix
takes an pointer as its argument. Don't mix the pointer arguments
with 'by reference' argument passing. It is possible to pass a
pointer by reference (in which case the @{b}ti_Data@{ub} is a pointer to
the actual pointer).
The list of all defined base tag codes is as follows:
@{b}SBTC_BREAKMASK@{ub}
Tag data contains the INTR signal mask. If the calling task
receives a signal in the INTR mask, the AMITCP/IP interrupts
current function calls and returns with the error code EINTR.
The INTR mask defaults to the CTRL-C signal (SIGBREAKF_C,
bit 12).
@{b}SBTC_DTABLESIZE@{ub}
Socket Descriptor Table size. This defaults to 64.
@{b}SBTC_ERRNO@{ub}
The errno value. The values are defined in @{"<sys-errno.h>" Link "<sys-errno.h>"}.
@{b}SBTC_ERRNOBYTEPTR@{ub}
@{b}SBTC_ERRNOWORDPTR@{ub}
@{b}SBTC_ERRNOLONGPTR@{ub}
@{b}SBTC_ERRNOPTR(size)@{ub}
Set (only) the pointer to the errno variable defined by the
program. AMITCP/IP defines a value for this by default, but
the application must set the pointer (and the size of the
@{b}errno@{ub}) with one of these tags, if it wishes to access the
errno variable directly.
The SBTC_ERRNOPTR(size) is a macro, which expands to one of
the other (@{b}BYTE@{ub}, @{b}WORD@{ub} or @{b}LONG@{ub}) tag codes, meaning that only
1, 2 and 4 are legal size values.
The @{b}NetLib:autoinit.c@{ub} sets the errno pointer for the
application, if the application is linked with it.
@{b}SBTC_ERRNOSTRPTR@{ub}
Returns an error string pointer describing the errno value
given on input. You can not set the error message, only get
is allowed.
On call the @{b}ti_Data@{ub} must contain the error code number. On
return the @{b}ti_Data@{ub} is assigned to the string pointer.
(@{b}*ti_Data@{ub}, if passed by reference). See the file
@{"<sys-errno.h>" Link "<sys-errno.h>"} for symbolic definitions for the errno codes.
@{b}SBTC_FDCALLBACK@{ub}
A callback function pointer for coordination of file
descriptor usage between AMITCP/IP and link-library. By
default no callback is called and the value of this pointer
is NULL. The prototype for the callback function is:
@{i}int error = fdCallback(int fd, int action);@{ui}
@{i}D0 D0 D1@{ui}
where
@{b}error@{ub}
- 0 for success or one of the error codes in
@{"<sys-errno.h>" Link "<sys-errno.h>"} in case of error. The AMITCP/IP API
function that calls the callback usually returns the
@{b}error@{ub} back to the caller without any further
modification.
@{b}fd@{ub}
- file descriptor number to take @{b}action@{ub} on.
@{b}action@{ub}
- one of the action codes, which are defined in the
header file @{"<amitcp-socketbasetags.h>" Link "<amitcp-socketbasetags.h>"}) as follows:
@{b}FDCB_FREE@{ub}
- mark the @{b}fd@{ub} as unused on the link library
structure. If @{b}fd@{ub} represents a file handled by the
link library, the error @{b}ENOTSOCK@{ub} should be returned.
@{b}FDCB_ALLOC@{ub}
- mark the @{b}fd@{ub} allocated as a socket.
@{b}FDCB_CHECK@{ub}
-check if the @{b}fd@{ub} is free. If an error is returned,
the @{b}fd@{ub} is marked as used in the AMITCP/IP
structures.
The AMITCP/IP calls the callback every time a socket
descriptor is allocated or freed. AMITCP/IP uses the
@{b}FDCB_CHECK@{ub} before actual allocation to check that it
agrees with the link library on the next free descriptor
number. Thus the link library doesn't need to tell the
AMITCP/IP if it creates a new file handle in @{b}open()@{ub}, for
example.
See file @{b}_chkufb.c@{ub} on the @{i}net.lib@{ui} sources for an example
implementation of the callback function for the SAS/C.
@{b}SBTC_HERRNO@{ub}
The name resolver error code value. Get this to find out why
the @{b}gethostbyname()@{ub} or @{b}gethostbyaddr()@{ub} failed. The values are
defined in @{"<netdb.h>" Link "<netdb.h>"}.
@{b}SBTC_HERRNOSTRPTR@{ub}
Returns host error string for error number in tag data. Host
error is set on unsuccesful @{"gethostbyname()" Link "gethostbyname()"} and
@{"gethostbyaddr()" Link "gethostbyaddr()"} calls. See the file @{"<netdb.h>" Link "<netdb.h>"} for the
symbolic definitions for the @{b}herrno@{ub} valus.
Notes for the @{b}SBTC_ERRNOSTRPTR@{ub} apply also to this tag code.
@{b}SBTC_IOERRNOSTRPTR@{ub}
Returns an error string for standard AmigaOS I/O error number
as defined in the header file @{"<exec-errors.h>" Link "<exec-errors.h>"}. Note that the
error number taken by this tag code is positive, so the error
codes must be negated (to be positive). The positive error
codes depend on the particular IO device, the standard
Sana-II error codes can be retrieved by the tag code
@{b}SBTC_S2ERRNOSTRPTR@{ub}.
Notes for the @{b}SBTC_ERRNOSTRPTR@{ub} apply also to this tag code.
@{b}SBTC_LOGFACILITY@{ub}
Facility code for the syslog messages as defined in
@{b}<sys/syslog.h>@{ub}. Defaults to @{b}LOG_USER@{ub}.
@{b}SBTC_LOGMASK@{ub}
Sets the filter mask of the syslog messages. By default the
mask is @{b}0xff@{ub}, meaning that all messages are passed to the log
system.
@{b}SBTC_LOGSTAT@{ub}
Syslog options defined in @{b}<sys/syslog.h>@{ub}.
@{b}SBTC_LOGTAGPTR@{ub}
A pointer to a string which is used by @{b}Syslog()@{ub} to mark
individual syslog messages. This defaults to @{b}NULL@{ub}, but is set
to the name of the calling program by the autoinit code in
@{b}netlib:autoinit.c@{ub}. This is for compatibility with pre-3.0
programs.
@{b}SBTC_S2ERRNOSTRPTR@{ub}
Returns an error string for a Sana-II specific I/O error code
as defined in the header file @{"<devices-sana2.h>" Link "<devices-sana2.h>"}.
Notes for the @{b}SBTC_ERRNOSTRPTR@{ub} apply also to this tag code.
@{b}SBTC_S2WERRNOSTRPTR@{ub}
Returns an error string for a Sana-II Wire Error code as
defined in the header file @{"<devices-sana2.h>" Link "<devices-sana2.h>"}.
Notes for the SBTC_ERRNOSTRPTR apply also to this tag code.
@{b}SBTC_SIGEVENTMASK@{ub}
Tag data contains the signal mask to be sent to the
application whenever notification about socket events is in
order. The default value for this is zero, inhibiting any
event notifications. The application must set this mask if
it desires to be notified about asynchronous socket events.
When the application receives the signal specified in the
mask, it can use the function @{"GetSocketEvents()" Link "GetSocketEvents()"} to find out
what happened.
@{b}SBTC_SIGIOMASK@{ub}
The signals specified in the mask in the tag data are sent to
the calling task when asynhronous I/O is to be notified. The
default value is zero, i.e., no signals are sent. The signals
in the mask are sent whenever something happens on the
socket. This mechanism is compatible with the Unix SIGIO
signal.
Since AmigaOS signals may get combined, one signal may include
notification for originally distinct events on the socket.
One example of this is the reception of data and connection
closure.
Usage of the socket events (see @{"GetSocketEvents()" Link "GetSocketEvents()"}) is
recommended over this because of the problem described above.
@{b}SBTC_SIGURGMASK@{ub}
The signals specified in the mask in the tag data are sent to
the calling task when notification about urgent data arrives.
The default value is zero, ie. no signals are sent. This
mechanism is compatible with the Unix SIGURG signal.
Note that this signal does not indicate the arrival of the
actual out-of-band data. If the receive buffer of the socket
is full, the urgent data can't even be received. Because of
this the application may need to read some normal data off
the socket before it can read the urgent data.
@{i}RESULT@{ui}
Returns 0 on success, and a (positive) index of the failing tag on
error. Note that the value 1 means @{i}first@{ui} TagItem, 2 the second
one, and so on. The return value is NOT a C-language index, which
are 0 based.
@{i}EXAMPLES@{ui}
To be written, see @{b}net.lib@{ub} sources for various examples.
@{i}SEE ALSO@{ui}
@{"<netinclude:amitcp-socketbasetags.h>" Link "<netinclude:amitcp-socketbasetags.h>"}, @{"<include:utility-tagitem.h>" Link "<include:utility-tagitem.h>"}
@EndNode
@Node "syslog()" "bsdsocket.guide/syslog()"
@Prev "SocketBaseTagList()"
@Toc "Function Reference"
@{b}syslog()@{ub}, @{b}vsyslog()@{ub}
===================
@{i}NAME@{ui}
@{b}syslog@{ub}, @{b}vsyslog@{ub} -- write message to AMITCP/IP log
@{i}SYNOPSIS@{ui}
@{i}#include <syslog.h>@{ui}
@{i}void syslog(int priority, const char * message, ...)@{ui}
@{i}void vsyslog(int level, const char * format, LONG * args)@{ui}
@{i} D0 A0 A1@{ui}
@{i}DESCRIPTION@{ui}
Writes the message given as format string and arguments
(printf-style) both to the log file and to the console. The
message is prepended with the name of the calling application, if
the name is known by AMITCP/IP (the standard autoinitiazer module
in the net.lib passes the name of the application to AMITCP/IP).
The message is identical to a @{b}printf()@{ub} format string, except that
@{b}%m@{ub} is replaced by the current error message. (As denoted by
the library variable @{b}errno@{ub} (see @{"Errno()" Link "Errno()"}).) A trailing newline is
added if none is present.
The level is selected from an ordered list:
@{b}LOG_EMERG@{ub}
A panic condition.
@{b}LOG_ALERT@{ub}
A condition that should be corrected immediately, such as a
corrupted system database.
@{b}LOG_CRIT@{ub}
Critical conditions, e.g., hard device errors.
@{b}LOG_ERR@{ub}
Errors.
@{b}LOG_WARNING@{ub}
Warning messages.
@{b}LOG_NOTICE@{ub}
Conditions that are not error conditions, but should possibly
be handled specially.
@{b}LOG_INFO@{ub}
Informational messages.
@{b}LOG_DEBUG@{ub}
Messages that contain information normally of use only when
debugging a program.
@{i}INPUTS@{ui}
@{b}Level@{ub}
indicates the type of the message. The levels are defined in
sys/syslog.h and listed above.
@{b}format@{ub}
This is a printf-style format string. In addition @{b}%m@{ub} is
expanded to current error message.
@{b}...@{ub}
arguments as in printf().
@{b}args@{ub}
pointer to an array of arguments.
@{i}RESULT@{ui}
Returns no value.
@{i}EXAMPLES@{ui}
To log a message at priority LOG_INFO, it would make the following
call to syslog:
@{i}syslog(LOG_ALERT, "who: internal error 23");
syslog(LOG_INFO, "Connection from host %s", CallingHost);@{ui}
@{i}NOTES@{ui}
In contrast to the previous releases of the AMITCP/IP, the integer
arguments are expected to be 32 bits wide, thus eliminating the
need to specify the 'l' size modifier for the number formatters.
This function is callable from interrupts.
@{i}BUGS@{ui}
Because there is a limited number of internal messages used by the
logging system, some log messages may get lost if a high priority
task or interrupt handler sends many messages in succession. If
this happens, the next log message tells the fact.
@{i}SEE ALSO@{ui}
@{b}src/netlib/syslog.c@{ub} for syslog utility functions (@{b}openlog()@{ub},
@{b}closelog()@{ub} and @{b}setlogmask()@{ub}), C-library @{b}printf()@{ub} documentation
@{i}HISTORY@{ui}
These functions appeared in 4.2BSD.
@EndNode
@Node "Function Reference" "bsdsocket.guide/Function Reference"
@Prev "Disclaimer & Copyright"
@Toc "Main"
Function Index
**************
@{" accept " Link "accept()"} accept()
@{" bind " Link "bind()"} bind()
@{" CloseSocket " Link "CloseSocket()"} CloseSocket()
@{" connect " Link "connect()"} connect()
@{" Dup2Socket " Link "Dup2Socket()"} Dup2Socket()
@{" Errno " Link "Errno()"} Errno()
@{" getdtablesize " Link "getdtablesize()"} getdtablesize()
@{" gethostbyaddr " Link "gethostbyname()"} gethostbyname()
@{" gethostbyname " Link "gethostbyname()"} gethostbyname()
@{" gethostid " Link "gethostid()"} gethostid()
@{" gethostname " Link "gethostname()"} gethostname()
@{" getnetbyaddr " Link "getnetbyname()"} getnetbyname()
@{" getnetbyname " Link "getnetbyname()"} getnetbyname()
@{" getpeername " Link "getpeername()"} getpeername()
@{" getprotobyname " Link "getprotobyname()"} getprotobyname()
@{" getprotobynumber " Link "getprotobyname()"} getprotobyname()
@{" getservbyname " Link "getservbyname()"} getservbyname()
@{" getservbyport " Link "getservbyname()"} getservbyname()
@{" GetSocketEvents " Link "GetSocketEvents()"} GetSocketEvents()
@{" getsockname " Link "getsockname()"} getsockname()
@{" getsockopt " Link "getsockopt()"} getsockopt()
@{" htonl " Link "htonl()"} htonl()
@{" htons " Link "htonl()"} htonl()
@{" inet_addr " Link "inet_addr()"} inet_addr()
@{" inet_lnaof " Link "inet_addr()"} inet_addr()
@{" Inet_LnaOf " Link "inet_addr()"} inet_addr()
@{" inet_makeaddr " Link "inet_addr()"} inet_addr()
@{" Inet_MakeAddr " Link "inet_addr()"} inet_addr()
@{" inet_netof " Link "inet_addr()"} inet_addr()
@{" Inet_NetOf " Link "inet_addr()"} inet_addr()
@{" inet_network " Link "inet_addr()"} inet_addr()
@{" inet_ntoa " Link "inet_addr()"} inet_addr()
@{" Inet_NtoA " Link "inet_addr()"} inet_addr()
@{" IoctlSocket " Link "IoctlSocket()"} IoctlSocket()
@{" listen " Link "listen()"} listen()
@{" ntohl " Link "htonl()"} htonl()
@{" ntohs " Link "htonl()"} htonl()
@{" ObtainSocket " Link "ObtainSocket()"} ObtainSocket()
@{" recv " Link "recv()"} recv()
@{" recvfrom " Link "recv()"} recv()
@{" recvmsg " Link "recv()"} recv()
@{" ReleaseCopyOfSocket " Link "ReleaseSocket()"} ReleaseSocket()
@{" ReleaseSocket " Link "ReleaseSocket()"} ReleaseSocket()
@{" select " Link "select()"} select()
@{" send " Link "send()"} send()
@{" sendmsg " Link "send()"} send()
@{" sendto " Link "send()"} send()
@{" SetErrnoPtr " Link "SetErrnoPtr()"} SetErrnoPtr()
@{" SetSocketSignals " Link "SetSocketSignals()"} SetSocketSignals()
@{" setsockopt " Link "getsockopt()"} getsockopt()
@{" shutdown " Link "shutdown()"} shutdown()
@{" socket " Link "socket()"} socket()
@{" SocketBaseTagList " Link "SocketBaseTagList()"} SocketBaseTagList()
@{" syslog " Link "syslog()"} syslog()
@{" vsyslog " Link "syslog()"} syslog()
@{" WaitSelect " Link "select()"} select()
@EndNode
Reference in New Issue View Git Blame Copy Permalink