OpenCores
URL https://opencores.org/ocsvn/openrisc_me/openrisc_me/trunk

Subversion Repositories openrisc_me

Compare Revisions

  • This comparison shows the changes necessary to convert path 
    /openrisc/trunk/rtos/ecos-2.0/packages/net/common/v2_0/doc/manpages/sys
    from Rev 27 to Rev 174
    ↔ Reverse comparison
  •

Rev 27 → Rev 174

/select.2
0,0 → 1,260
.\" $OpenBSD: select.2,v 1.20 2001/09/04 08:04:08 deraadt Exp $
.\" $NetBSD: select.2,v 1.5 1995/06/27 22:32:28 cgd Exp $
.\"
.\" Copyright (c) 1983, 1991, 1993
.\" The 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 acknowledgement:
.\" 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.
.\"
.\" @(#)select.2 8.2 (Berkeley) 3/25/94
.\"
.Dd March 25, 1994
.Dt SELECT 2
.Os
.Sh NAME
.Nm select
.Nd synchronous I/O multiplexing
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/time.h>
.Fd #include <unistd.h>
.Ft int
.Fn select "int nfds" "fd_set *readfds" "fd_set *writefds" "fd_set *exceptfds" "struct timeval *timeout"
.Fn FD_SET fd &fdset
.Fn FD_CLR fd &fdset
.Fn FD_ISSET fd &fdset
.Fn FD_ZERO &fdset
.Sh DESCRIPTION
.Fn select
examines the I/O descriptor sets whose addresses are passed in
.Fa readfds ,
.Fa writefds ,
and
.Fa exceptfds
to see if some of their descriptors
are ready for reading, are ready for writing, or have an exceptional
condition pending, respectively.
The first
.Fa nfds
descriptors are checked in each set;
i.e., the descriptors from 0 through
.Fa nfds Ns No -1
in the descriptor sets are examined.
On return,
.Fn select
replaces the given descriptor sets
with subsets consisting of those descriptors that are ready
for the requested operation.
.Fn select
returns the total number of ready descriptors in all the sets.
.Pp
The descriptor sets are stored as bit fields in arrays of integers.
The following macros are provided for manipulating such descriptor sets:
.Fn FD_ZERO &fdset
initializes a descriptor set
.Fa fdset
to the null set.
.Fn FD_SET fd &fdset
includes a particular descriptor
.Fa fd
in
.Fa fdset .
.Fn FD_CLR fd &fdset
removes
.Fa fd
from
.Fa fdset .
.Fn FD_ISSET fd &fdset
is non-zero if
.Fa fd
is a member of
.Fa fdset ,
zero otherwise.
The behavior of these macros is undefined if
a descriptor value is less than zero or greater than or equal to
.Dv FD_SETSIZE ,
which is normally at least equal
to the maximum number of descriptors supported by the system.
.Pp
If
.Fa timeout
is a non-null pointer, it specifies a maximum interval to wait for the
selection to complete.
If
.Fa timeout
is a null pointer, the select blocks indefinitely.
To effect a poll, the
.Fa timeout
argument should be non-null, pointing to a zero-valued timeval structure.
.Fa timeout
is not changed by
.Fn select ,
and may be reused on subsequent calls; however, it is good style to
re-initialize it before each invocation of
.Fn select .
.Pp
Any of
.Fa readfds ,
.Fa writefds ,
and
.Fa exceptfds
may be given as null pointers if no descriptors are of interest.
.Sh RETURN VALUES
.Fn select
returns the number of ready descriptors that are contained in
the descriptor sets, or \-1 is an error occurred.
If the time limit expires,
.Fn select
returns 0.
If
.Fn select
returns with an error, including one due to an interrupted call,
the descriptor sets will be unmodified.
.Sh ERRORS
An error return from
.Fn select
indicates:
.Bl -tag -width Er
.It Bq Er EFAULT
One or more of
.Fa readfds ,
.Fa writefds ,
or
.Fa exceptfds
points outside the process's allocated address space.
.It Bq Er EBADF
One of the descriptor sets specified an invalid descriptor.
.It Bq Er EINTR
A signal was delivered before the time limit expired and
before any of the selected events occurred.
.It Bq Er EINVAL
The specified time limit is invalid.
One of its components is negative or too large.
.El
.Sh SEE ALSO
.Xr accept 2 ,
.Xr connect 2 ,
.Xr gettimeofday 2 ,
.Xr poll 2 ,
.Xr read 2 ,
.Xr recv 2 ,
.Xr send 2 ,
.Xr write 2 ,
.Xr getdtablesize 3
.Sh BUGS
Although the provision of
.Xr getdtablesize 3
was intended to allow user programs to be written independent
of the kernel limit on the number of open files, the dimension
of a sufficiently large bit field for select remains a problem.
The default bit size of
.Ft fd_set
is based on the symbol
.Dv FD_SETSIZE
(currently 256),
but that is somewhat smaller than the current kernel limit
to the number of open files.
However, in order to accommodate programs which might potentially
use a larger number of open files with select, it is possible
to increase this size within a program by providing
a larger definition of
.Dv FD_SETSIZE
before the inclusion of
.Aq Pa sys/types.h .
The kernel will cope, and the userland libraries provided with the
system are also ready for large numbers of file descriptors.
.Pp
Alternatively, to be really safe, it is possible to allocate
.Ft fd_set
bit-arrays dynamically.
The idea is to permit a program to work properly even if it is
.Xr execve 2 Ns 'd
with 4000 file descriptors pre-allocated.
The following illustrates the technique which is used by
userland libraries:
.Pp
.Bd -literal -offset indent -compact
fd_set *fdsr;
int max = fd;
 
fdsr = (fd_set *)calloc(howmany(max+1, NFDBITS),
sizeof(fd_mask));
if (fdsr == NULL) {
...
return (-1);
}
FD_SET(fd, fdsr);
n = select(max+1, fdsr, NULL, NULL, &tv);
...
free(fdsr);
.Ed
.Pp
Alternatively, it is possible to use the
.Xr poll 2
interface.
.Xr poll 2
is more efficient when the size of
.Fn select Ns 's
.Ft fd_set
bit-arrays are very large, and for fixed numbers of
file descriptors one need not size and dynamically allocate a
memory object.
.Pp
.Fn select
should probably have been designed to return the time remaining from the
original timeout, if any, by modifying the time value in place.
Even though some systems stupidly act in this different way, it is
unlikely this semantic will ever be commonly implemented, as the
change causes massive source code compatibility problems.
Furthermore, recent new standards have dictated the current behaviour.
In general, due to the existence of those brain-damaged
non-conforming systems, it is unwise to assume that the timeout
value will be unmodified by the
.Fn select
call, and the caller should reinitialize it on each invocation.
Calculating the delta is easily done by calling
.Xr gettimeofday 2
before and after the call to
.Fn select Ns ,
and using
.Fn timersub
(as described in
.Xr getitimer 2 ) .
.Pp
Internally to the kernel,
.Fn select
works poorly if multiple processes wait on the same file descriptor.
Given that, it is rather surprising to see that many daemons are
written that way (i.e.,
.Xr httpd 8 ) .
.Sh HISTORY
The
.Fn select
function call appeared in
.Bx 4.2 .
/accept.2
0,0 → 1,173
.\" $OpenBSD: accept.2,v 1.12 2001/03/11 05:02:29 aaron Exp $
.\" $NetBSD: accept.2,v 1.7 1996/01/31 20:14:42 mycroft Exp $
.\"
.\" Copyright (c) 1983, 1990, 1991, 1993
.\" The 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 acknowledgement:
.\" 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.
.\"
.\" @(#)accept.2 8.2 (Berkeley) 12/11/93
.\"
.Dd February 15, 1999
.Dt ACCEPT 2
.Os
.Sh NAME
.Nm accept
.Nd accept a connection on a socket
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Ft int
.Fn accept "int s" "struct sockaddr *addr" "socklen_t *addrlen"
.Sh DESCRIPTION
The argument
.Fa s
is a socket that has been created with
.Xr socket 2 ,
bound to an address with
.Xr bind 2 ,
and is listening for connections after a
.Xr listen 2 .
The
.Fn accept
argument extracts the first connection request on the queue of pending
connections, creates a new socket with the same properties of
.Fa s ,
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,
.Fn accept
blocks the caller until a connection is present.
If the socket is marked non-blocking and no pending
connections are present on the queue,
.Fn accept
returns an error as described below.
The accepted socket may not be used to accept more connections.
The original socket
.Fa s
remains open.
.Pp
The argument
.Fa addr
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
.Fa addr
parameter is determined by the domain in which the communication
is occurring.
The
.Fa addrlen
is a value-result parameter; it should initially contain the
amount of space pointed to by
.Fa addr ;
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
.Dv SOCK_STREAM .
.Pp
It is possible to
.Xr select 2
or
.Xr poll 2
a socket for the purposes of doing an
.Fn accept
by selecting it for read.
.Pp
For certain protocols which require an explicit confirmation, such as
.Tn ISO
or
.Tn DATAKIT ,
.Fn accept
can be thought of as merely dequeuing the next connection
request and not implying confirmation.
Confirmation can be implied by a normal read or write on the new file
descriptor, and rejection can be implied by closing the new socket.
.Pp
One can obtain user connection request data without confirming
the connection by issuing a
.Xr recvmsg 2
call with an
.Fa msg_iovlen
of 0 and a non-zero
.Fa msg_controllen ,
or by issuing a
.Xr getsockopt 2
request.
Similarly, one can provide user connection rejection information
by issuing a
.Xr sendmsg 2
call with providing only the control information, or by calling
.Xr setsockopt 2 .
.Sh RETURN VALUES
The call returns \-1 on error.
If it succeeds, it returns a non-negative integer that is a descriptor
for the accepted socket.
.Sh ERRORS
The
.Fn accept
will fail if:
.Bl -tag -width Er
.It Bq Er EBADF
The descriptor is invalid.
.It Bq Er ENOTSOCK
The descriptor references a file, not a socket.
.It Bq Er EOPNOTSUPP
The referenced socket is not of type
.Dv SOCK_STREAM .
.It Bq Er EINVAL
The referenced socket is not listening for connections (that is,
.Xr listen 2
has not yet been called).
.It Bq Er EFAULT
The
.Fa addr
parameter is not in a writable part of the user address space.
.It Bq Er EWOULDBLOCK
The socket is marked non-blocking and no connections
are present to be accepted.
.It Bq Er EMFILE
The per-process descriptor table is full.
.It Bq Er ENFILE
The system file table is full.
.It Bq Er ECONNABORTED
A connection has been aborted.
.El
.Sh SEE ALSO
.Xr bind 2 ,
.Xr connect 2 ,
.Xr listen 2 ,
.Xr poll 2 ,
.Xr select 2 ,
.Xr poll 2 ,
.Xr socket 2
.Sh HISTORY
The
.Fn accept
function appeared in
.Bx 4.2 .
/getsockname.2
0,0 → 1,164
.\" $OpenBSD: getsockname.2,v 1.16 2001/08/06 10:42:26 mpech Exp $
.\" $NetBSD: getsockname.2,v 1.6 1995/10/12 15:41:00 jtc Exp $
.\"
.\" Copyright (c) 1983, 1991, 1993
.\" The 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 acknowledgement:
.\" 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.
.\"
.\" @(#)getsockname.2 8.1 (Berkeley) 6/4/93
.\"
.Dd July 17, 1999
.Dt GETSOCKNAME 2
.Os
.Sh NAME
.Nm getsockname
.Nd get socket name
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Ft int
.Fn getsockname "int s" "struct sockaddr *name" "socklen_t *namelen"
.Sh DESCRIPTION
.Fn getsockname
returns the locally bound address information for a specified socket.
.Pp
Common uses of this function are as follows:
.Bl -bullet
.It
When
.Xr bind 2
is called with a port number of 0 (indicating the kernel should pick
an ephemeral port)
.Fn getsockname
is used to retrieve the kernel-assigned port number.
.It
When a process calls
.Xr bind 2
on a wildcard IP address,
.Fn getsockname
is used to retrieve the local IP address for the connection.
.It
When a function wishes to know the address family of a socket,
.Fn getsockname
can be used.
.El
.Pp
.Fn getsockname
takes three parameters:
.Pp
.Fa s ,
Contains the file desriptor for the socket to be looked up.
.Pp
.Fa name
points to a
.Li sockaddr
structure which will hold the resulting address information.
Normal use requires one to use a structure
specific to the protocol family in use, such as
.Li sockaddr_in
(IPv4) or
.Li sockaddr_in6
(IPv6), cast to a (struct sockaddr *).
.Pp
For greater portability (such as newer protocol families) the new
structure sockaddr_storage exists.
.Li sockaddr_storage
is large enough to hold any of the other sockaddr_* variants.
On return, it should be cast to the correct sockaddr type,
according to the current protocol family.
.Pp
.Fa namelen
Indicates the amount of space pointed to by
.Fa name ,
in bytes.
Upon return,
.Fa namelen
is set to the actual size of the returned address information.
.Pp
If the address of the destination socket for a given socket connection is
needed, the
.Xr getpeername 2
function should be used instead.
.Pp
If
.Fa name
does not point to enough space to hold the entire socket address, the
result will be truncated to
.Fa namelen
bytes.
.Sh RETURN VALUES
On success,
.Fn getsockname
returns a 0, and
.Fa namelen
is set to the actual size of the socket address returned in
.Fa name .
Otherwise,
.Va errno
is set, and a value of \-1 is returned.
.Sh ERRORS
If
.Fn getsockname
fails,
.Va errno
is set to one of the following:
.Bl -tag -width Er
.It Bq Er EBADF
The argument
.Fa s
is not a valid descriptor.
.It Bq Er ENOTSOCK
The argument
.Fa s
is a file, not a socket.
.It Bq Er ENOBUFS
Insufficient resources were available in the system
to perform the operation.
.It Bq Er EFAULT
The
.Fa name
parameter points to memory not in a valid part of the
process address space.
.El
.Sh SEE ALSO
.Xr accept 2 ,
.Xr bind 2 ,
.Xr getpeername 2 ,
.Xr getpeereid 2 ,
.Xr socket 2
.Sh BUGS
Names bound to sockets in the UNIX domain are inaccessible;
.Nm getsockname
returns a zero length name.
.Sh HISTORY
The
.Fn getsockname
function call appeared in
.Bx 4.2 .
/getsockopt.2
0,0 → 1,348
.\" $OpenBSD: getsockopt.2,v 1.16 2000/10/18 05:12:10 aaron Exp $
.\" $NetBSD: getsockopt.2,v 1.7 1995/02/27 12:33:29 cgd Exp $
.\"
.\" Copyright (c) 1983, 1991, 1993
.\" The 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 acknowledgement:
.\" 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.
.\"
.\" @(#)getsockopt.2 8.3 (Berkeley) 4/19/94
.\"
.Dd February 15, 1999
.Dt GETSOCKOPT 2
.Os
.Sh NAME
.Nm getsockopt ,
.Nm setsockopt
.Nd get and set options on sockets
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Ft int
.Fn getsockopt "int s" "int level" "int optname" "void *optval" "socklen_t *optlen"
.Ft int
.Fn setsockopt "int s" "int level" "int optname" "const void *optval" "socklen_t optlen"
.Sh DESCRIPTION
.Fn getsockopt
and
.Fn setsockopt
manipulate the
.Em options
associated with a socket.
Options may exist at multiple protocol levels;
they are always present at the uppermost
.Dq socket
level.
.Pp
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,
.Fa level
is specified as
.Dv SOL_SOCKET .
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
.Tn TCP
protocol,
.Fa level
should be set to the protocol number of
.Tn TCP ;
see
.Xr getprotoent 3 .
.Pp
The parameters
.Fa optval
and
.Fa optlen
are used to access option values for
.Fn setsockopt .
For
.Fn getsockopt
they identify a buffer in which the value for the
requested option(s) are to be returned.
For
.Fn getsockopt ,
.Fa optlen
is a value-result parameter, initially containing the
size of the buffer pointed to by
.Fa optval ,
and modified on return to indicate the actual size of the value returned.
If no option value is to be supplied or returned,
.Fa optval
may be
.Dv NULL .
.Pp
.Fa optname
and any specified options are passed uninterpreted to the appropriate
protocol module for interpretation.
The include file
.Ao Pa sys/socket.h Ac
contains definitions for socket level options, described below.
Options at other protocol levels vary in format and name;
consult the appropriate entries in section 4 of the manual.
.Pp
Most socket-level options utilize an
.Li int
parameter for
.Fa optval .
For
.Fn setsockopt ,
the parameter should be non-zero to enable a boolean option,
or zero if the option is to be disabled.
.Dv SO_LINGER
uses a
.Li struct linger
parameter, defined in
.Aq Pa sys/socket.h ,
which specifies the desired state of the option and the
linger interval (see below).
.Dv SO_SNDTIMEO
and
.Dv SO_RCVTIMEO
use a
.Li struct timeval
parameter, defined in
.Aq Pa sys/time.h .
.Pp
The following options are recognized at the socket level.
Except as noted, each may be examined with
.Fn getsockopt
and set with
.Fn setsockopt .
.Bl -column SO_OOBINLINE -offset indent
.It Dv SO_DEBUG Ta "enables recording of debugging information"
.It Dv SO_REUSEADDR Ta "enables local address reuse"
.It Dv SO_REUSEPORT Ta "enables duplicate address and port bindings"
.It Dv SO_KEEPALIVE Ta "enables keep connections alive"
.It Dv SO_DONTROUTE Ta "enables routing bypass for outgoing messages"
.It Dv SO_LINGER Ta "linger on close if data present"
.It Dv SO_BROADCAST Ta "enables permission to transmit broadcast messages"
.It Dv SO_OOBINLINE Ta "enables reception of out-of-band data in band"
.It Dv SO_SNDBUF Ta "set buffer size for output"
.It Dv SO_RCVBUF Ta "set buffer size for input"
.It Dv SO_SNDLOWAT Ta "set minimum count for output"
.It Dv SO_RCVLOWAT Ta "set minimum count for input"
.It Dv SO_SNDTIMEO Ta "set timeout value for output"
.It Dv SO_RCVTIMEO Ta "set timeout value for input"
.It Dv SO_TYPE Ta "get the type of the socket (get only)"
.It Dv SO_ERROR Ta "get and clear error on the socket (get only)"
.El
.Pp
.Dv SO_DEBUG
enables debugging in the underlying protocol modules.
.Dv SO_REUSEADDR
indicates that the rules used in validating addresses supplied in a
.Xr bind 2
call should allow reuse of local addresses.
.Dv SO_REUSEPORT
allows completely duplicate bindings by multiple processes if they all set
.Dv SO_REUSEPORT
before binding the port.
This option permits multiple instances of a program to each
receive UDP/IP multicast or broadcast datagrams destined for the bound port.
.Dv SO_KEEPALIVE
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
.Dv SIGPIPE
signal when attempting to send data.
.Dv SO_DONTROUTE
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.
.Pp
.Dv SO_LINGER
controls the action taken when unsent messages
are queued on socket and a
.Xr close 2
is performed.
If the socket promises reliable delivery of data and
.Dv SO_LINGER
is set, the system will block the process on the
.Xr close 2
attempt until it is able to transmit the data or until it decides it
is unable to deliver the information (a timeout period measured in seconds,
termed the linger interval, is specified in the
.Fn setsockopt
call when
.Dv SO_LINGER
is requested).
If
.Dv SO_LINGER
is disabled and a
.Xr close 2
is issued, the system will process the close in a manner that allows
the process to continue as quickly as possible.
.Pp
The option
.Dv SO_BROADCAST
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
.Dv SO_OOBINLINE
option requests that out-of-band data be placed in the normal data input
queue as received; it will then be accessible with
.Xr recv 2
or
.Xr read 2
calls without the
.Dv MSG_OOB
flag.
Some protocols always behave as if this option is set.
.Dv SO_SNDBUF
and
.Dv SO_RCVBUF
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.
.Pp
.Dv SO_SNDLOWAT
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
.Xr select 2
or
.Xr poll 2
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
.Dv SO_SNDLOWAT
is set to a convenient size for network efficiency, often 1024.
.Dv SO_RCVLOWAT
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 the smaller of the amount available or the amount
requested.
The default value for
.Dv SO_RCVLOWAT
is 1.
If
.Dv SO_RCVLOWAT
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.
.Pp
.Dv SO_SNDTIMEO
is an option to set a timeout value for output operations.
It accepts a
.Li struct 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
.Er EWOULDBLOCK
if no data was 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.
.Dv SO_RCVTIMEO
is an option to set a timeout value for input operations.
It accepts a
.Li struct 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
.Er EWOULDBLOCK
if no data were received.
.Pp
Finally,
.Dv SO_TYPE
and
.Dv SO_ERROR
are options used only with
.Fn getsockopt .
.Dv SO_TYPE
returns the type of the socket, such as
.Dv SOCK_STREAM ;
it is useful for servers that inherit sockets on startup.
.Dv SO_ERROR
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.
.Sh RETURN VALUES
A 0 is returned if the call succeeds, \-1 if it fails.
.Sh ERRORS
The call succeeds unless:
.Bl -tag -width Er
.It Bq Er EBADF
The argument
.Fa s
is not a valid descriptor.
.It Bq Er ENOTSOCK
The argument
.Fa s
is a file, not a socket.
.It Bq Er ENOPROTOOPT
The option is unknown at the level indicated.
.It Bq Er EFAULT
The address pointed to by
.Fa optval
is not in a valid part of the process address space.
For
.Fn getsockopt ,
this error may also be returned if
.Fa optlen
is not in a valid part of the process address space.
.El
.Sh SEE ALSO
.Xr connect 2 ,
.Xr ioctl 2 ,
.Xr poll 2 ,
.Xr select 2 ,
.Xr poll 2 ,
.Xr socket 2 ,
.Xr getprotoent 3 ,
.Xr protocols 5
.Sh BUGS
Several of the socket options should be handled at lower levels of the system.
.Sh HISTORY
The
.Fn getsockopt
system call appeared in
.Bx 4.2 .
/socketpair.2
0,0 → 1,109
.\" $OpenBSD: socketpair.2,v 1.10 1999/07/06 18:21:04 deraadt Exp $
.\" $NetBSD: socketpair.2,v 1.5 1995/02/27 12:38:00 cgd Exp $
.\"
.\" Copyright (c) 1983, 1991, 1993
.\" The 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 acknowledgement:
.\" 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.
.\"
.\" @(#)socketpair.2 8.1 (Berkeley) 6/4/93
.\"
.Dd June 4, 1993
.Dt SOCKETPAIR 2
.Os
.Sh NAME
.Nm socketpair
.Nd create a pair of connected sockets
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Ft int
.Fn socketpair "int d" "int type" "int protocol" "int *sv"
.Sh DESCRIPTION
The
.Fn socketpair
call creates an unnamed pair of connected sockets in
the specified domain
.Fa d ,
of the specified
.Fa type ,
and using the optionally specified
.Fa protocol .
The descriptors used in referencing the new sockets
are returned in
.Fa sv Ns [0]
and
.Fa sv Ns [1] .
The two sockets are indistinguishable.
.Sh RETURN VALUES
A 0 is returned if the call succeeds, \-1 if it fails.
.Sh ERRORS
The call succeeds unless:
.Bl -tag -width Er
.It Bq Er EMFILE
Too many descriptors are in use by this process.
.It Bq Er EAFNOSUPPORT
The specified address family is not supported on this machine.
.It Bq Er EPROTONOSUPPORT
The specified protocol is not supported on this machine.
.It Bq Er EOPNOTSUPP
The specified protocol does not support creation of socket pairs.
.It Bq Er EFAULT
The address
.Fa sv
does not specify a valid part of the
process address space.
.It Bq Er ENFILE
The system file table is full.
.El
.Sh SEE ALSO
.Xr pipe 2 ,
.Xr read 2 ,
.Xr write 2
.Sh BUGS
This call is currently implemented only for the
.Tn LOCAL
domain.
Many operating systems only accept a
.Ar protocol
of
.Ev PF_UNSPEC ,
so that should be used instead of
.Ev PF_LOCAL
for maximal portability.
.Sh STANDARDS
The
.Fn socketpair
function conforms to
.St -xpg4.2 .
.Sh HISTORY
The
.Fn socketpair
function call appeared in
.Bx 4.2 .
/poll.2
0,0 → 1,203
.\" $OpenBSD: poll.2,v 1.11 2001/08/11 08:13:18 fgsch Exp $
.\"
.\" Copyright (c) 1994 Jason R. Thorpe
.\" 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 acknowledgement:
.\" This product includes software developed by Jason R. Thorpe.
.\" 4. The name of the author may not be used to endorse or promote products
.\" derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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
.\"
.Dd December 13, 1994
.Dt POLL 2
.Os
.Sh NAME
.Nm poll
.Nd synchronous I/O multiplexing
.Sh SYNOPSIS
.Fd #include <poll.h>
.Ft int
.Fn poll "struct pollfd *fds" "int nfds" "int timeout"
.Sh DESCRIPTION
.Fn poll
provides a mechanism for reporting I/O conditions across a set of file
descriptors.
.Pp
The arguments are as follows:
.Bl -tag -width timeout
.It Pa fds
Points to an array of
.Nm pollfd
structures, which are defined as:
.Bd -literal -offset indent
struct pollfd {
int fd;
short events;
short revents;
};
.Ed
.Pp
The
.Pa fd
member is an open file descriptor.
The
.Pa events
and
.Pa revents
members are bitmasks of conditions to monitor and conditions found,
respectively.
.It Pa nfds
The number of
.Nm pollfd
structures in the array.
.It Pa timeout
Maximum interval to wait for the poll to complete, in milliseconds.
If this value is 0, then
.Fn poll
will return immediately.
If this value is INFTIM (-1),
.Fn poll
will block indefinitely until a condition is found.
.El
.Pp
The calling process sets the
.Pa events
bitmask and
.Fn poll
sets the
.Pa revents
bitmask.
Each call to
.Fn poll
resets the
.Pa revents
bitmask for accuracy.
The condition flags in the bitmasks are defined as:
.Bl -tag -width POLLRDNORM
.It Nm POLLIN
Data is available on the file descriptor for reading.
.It Nm POLLNORM
Same as
.Nm POLLIN .
.It Nm POLLPRI
Same as
.Nm POLLIN .
.It Nm POLLOUT
Data can be written to the file descriptor without blocking.
.It Nm POLLERR
This flag is not used in this implementation and is provided only for source
code compatibility.
.It Nm POLLHUP
The file descriptor was valid before the polling process and invalid after.
Presumably, this means that the file descriptor was closed sometime during
the poll.
.It Nm POLLNVAL
The corresponding file descriptor is invalid.
.It Nm POLLRDNORM
Same as
.Nm POLLIN .
.It Nm POLLRDBAND
Same as
.Nm POLLIN .
.It Nm POLLWRNORM
Same as
.Nm POLLOUT .
.It Nm POLLWRBAND
Same as
.Nm POLLOUT .
.It Nm POLLMSG
This flag is not used in this implementation and is provided only for source
code compatibility.
.El
.Pp
All flags except
.Nm POLLIN ,
.Nm POLLOUT ,
and their synonyms are for use only in the
.Pa revents
member of the
.Nm pollfd
structure.
An attempt to set any of these flags in the
.Pa events
member will generate an error condition.
.Pp
In addition to I/O multiplexing,
.Fn poll
can be used to generate simple timeouts.
This functionality may be achieved by passing a null pointer for
.Pa fds .
.Sh WARNINGS
The
.Nm POLLHUP
flag is only a close approximation and may not always be accurate.
.Sh RETURN VALUES
Upon error,
.Fn poll
returns a \-1 and sets the global variable
.Va errno
to indicate the error.
If the timeout interval was reached before any events occurred,
a 0 is returned.
Otherwise,
.Fn poll
returns the number of file descriptors for which
.Pa revents
is non-zero.
.Sh ERRORS
.Fn poll
will fail if:
.Bl -tag -width "EINVAL "
.It Bq Er EINVAL
.Pa nfds
was either a negative number or greater than the number of available
file descriptors.
.It Bq Er EINVAL
An invalid flags was set in the
.Pa events
member of the
.Nm pollfd
structure.
.It Bq Er EINVAL
The timeout passed to
.Fn poll
was too large.
.It Bq Er EAGAIN
Resource allocation failed inside of
.Fn poll .
Subsequent calls to
.Fn poll
may succeed.
.It Bq Er EINTR
.Fn poll
caught a signal during the polling process.
.El
.Sh SEE ALSO
.Xr poll 2 ,
.Xr select 2 ,
.Xr sysconf 3
.Sh HISTORY
A
.Fn poll
system call appeared in
.At V .
/socket.2
0,0 → 1,264
.\" $OpenBSD: socket.2,v 1.18 2000/10/18 05:12:12 aaron Exp $
.\" $NetBSD: socket.2,v 1.5 1995/02/27 12:37:53 cgd Exp $
.\"
.\" Copyright (c) 1983, 1991, 1993
.\" The 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 acknowledgement:
.\" 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.
.\"
.\" @(#)socket.2 8.1 (Berkeley) 6/4/93
.\"
.Dd June 4, 1993
.Dt SOCKET 2
.Os
.Sh NAME
.Nm socket
.Nd create an endpoint for communication
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Ft int
.Fn socket "int domain" "int type" "int protocol"
.Sh DESCRIPTION
.Fn socket
creates an endpoint for communication and returns a descriptor.
.Pp
The
.Fa domain
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
.Ao Pa sys/socket.h Ac .
The currently understood formats are
.Pp
.Bd -literal -offset indent -compact
AF_UNIX (UNIX internal protocols),
AF_INET (ARPA Internet protocols),
AF_INET6 (ARPA IPv6 protocols),
AF_ISO (ISO protocols),
AF_NS (Xerox Network Systems protocols),
AF_IPX (Internetwork Packet Exchange), and
AF_IMPLINK (IMP \*(lqhost at IMP\*(rq link layer).
.Ed
.Pp
The socket has the indicated
.Fa type ,
which specifies the semantics of communication.
Currently defined types are:
.Pp
.Bd -literal -offset indent -compact
SOCK_STREAM
SOCK_DGRAM
SOCK_RAW
SOCK_SEQPACKET
SOCK_RDM
.Ed
.Pp
A
.Dv SOCK_STREAM
type provides sequenced, reliable,
two-way connection based byte streams.
An out-of-band data transmission mechanism may be supported.
A
.Dv SOCK_DGRAM
socket supports
datagrams (connectionless, unreliable messages of
a fixed (typically small) maximum length).
A
.Dv SOCK_SEQPACKET
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
.Dv PF_NS .
.Dv SOCK_RAW
sockets provide access to internal network protocols and interfaces.
The types
.Dv SOCK_RAW ,
which is available only to the superuser, and
.Dv SOCK_RDM ,
which is planned,
but not yet implemented, are not described here.
.Pp
The
.Fa protocol
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 \*(lqcommunication domain\*(rq
in which communication is to take place; see
.Xr protocols 5 .
A value of 0 for
.Fa protocol
will let the system select an appropriate protocol for the requested
socket type.
.Pp
Sockets of type
.Dv SOCK_STREAM
are full-duplex byte streams, similar to pipes.
A stream socket must be in a
.Em connected
state before any data may be sent or received on it.
A connection to another socket is created with a
.Xr connect 2
call.
Once connected, data may be transferred using
.Xr read 2
and
.Xr write 2
calls or some variant of the
.Xr send 2
and
.Xr recv 2
calls.
When a session has been completed a
.Xr close 2
may be performed.
Out-of-band data may also be transmitted as described in
.Xr send 2
and received as described in
.Xr recv 2 .
.Pp
The communications protocols used to implement a
.Dv SOCK_STREAM
ensure 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
.Er ETIMEDOUT
as the specific code in the global variable
.Va errno .
The protocols optionally keep sockets
.Dq 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).
A
.Dv SIGPIPE
signal is raised if a process sends on a broken stream; this causes
naive processes, which do not handle the signal, to exit.
.Pp
.Dv SOCK_SEQPACKET
sockets employ the same system calls
as
.Dv SOCK_STREAM
sockets.
The only difference is that
.Xr read 2
calls will return only the amount of data requested,
and any remaining in the arriving packet will be discarded.
.Pp
.Dv SOCK_DGRAM
and
.Dv SOCK_RAW
sockets allow sending of datagrams to correspondents named in
.Xr send 2
calls.
Datagrams are generally received with
.Xr recvfrom 2 ,
which returns the next datagram with its return address.
.Pp
An
.Xr fcntl 2
call can be used to specify a process group to receive
a
.Dv SIGURG
signal when the out-of-band data arrives.
It may also enable non-blocking I/O and asynchronous notification
of I/O events via
.Dv SIGIO .
.Pp
The operation of sockets is controlled by socket level
.Em options .
These options are defined in the file
.Ao Pa sys/socket.h Ac .
.Xr setsockopt 2
and
.Xr getsockopt 2
are used to set and get options, respectively.
.Sh RETURN VALUES
A \-1 is returned if an error occurs, otherwise the return
value is a descriptor referencing the socket.
.Sh ERRORS
The
.Fn socket
call fails if:
.Bl -tag -width Er
.It Bq Er EPROTONOSUPPORT
The protocol type or the specified protocol is not supported
within this domain.
.It Bq Er EMFILE
The per-process descriptor table is full.
.It Bq Er ENFILE
The system file table is full.
.It Bq Er EACCES
Permission to create a socket of the specified type and/or protocol
is denied.
.It Bq Er ENOBUFS
Insufficient buffer space is available.
The socket cannot be created until sufficient resources are freed.
.El
.Sh SEE ALSO
.Xr accept 2 ,
.Xr bind 2 ,
.Xr connect 2 ,
.Xr getsockname 2 ,
.Xr getsockopt 2 ,
.Xr ioctl 2 ,
.Xr listen 2 ,
.Xr poll 2 ,
.Xr read 2 ,
.Xr recv 2 ,
.Xr select 2 ,
.Xr send 2 ,
.Xr setsockopt 2 ,
.Xr shutdown 2 ,
.Xr socketpair 2 ,
.Xr write 2 ,
.Xr getprotoent 3 ,
.Xr netintro 4
.Rs
.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
.%O "reprinted in UNIX Programmer's Supplementary Documents Volume 1"
.Re
.Rs
.%T "BSD Interprocess Communication Tutorial"
.%O "reprinted in UNIX Programmer's Supplementary Documents Volume 1"
.Re
.Sh HISTORY
The
.Fn socket
function call appeared in
.Bx 4.2 .
/send.2
0,0 → 1,227
.\" $OpenBSD: send.2,v 1.19 2000/10/18 05:12:11 aaron Exp $
.\" $NetBSD: send.2,v 1.6 1996/01/15 01:17:18 thorpej Exp $
.\"
.\" Copyright (c) 1983, 1991, 1993
.\" The 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 acknowledgement:
.\" 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.
.\"
.\" @(#)send.2 8.2 (Berkeley) 2/21/94
.\"
.Dd July 28, 1998
.Dt SEND 2
.Os
.Sh NAME
.Nm send ,
.Nm sendto ,
.Nm sendmsg
.Nd send a message from a socket
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Ft ssize_t
.Fn send "int s" "const void *msg" "size_t len" "int flags"
.Ft ssize_t
.Fn sendto "int s" "const void *msg" "size_t len" "int flags" "const struct sockaddr *to" "socklen_t tolen"
.Ft ssize_t
.Fn sendmsg "int s" "const struct msghdr *msg" "int flags"
.Sh DESCRIPTION
.Fn send ,
.Fn sendto ,
and
.Fn sendmsg
are used to transmit a message to another socket.
.Fn send
may be used only when the socket is in a
.Em connected
state, while
.Fn sendto
and
.Fn sendmsg
may be used at any time.
.Pp
The address of the target is given by
.Fa to
with
.Fa tolen
specifying its size.
The length of the message is given by
.Fa len .
If the message is too long to pass atomically through the
underlying protocol, the error
.Er EMSGSIZE
is returned, and
the message is not transmitted.
.Pp
No indication of failure to deliver is implicit in a
.Fn send .
Locally detected errors are indicated by a return value of \-1.
.Pp
If no messages space is available at the socket to hold
the message to be transmitted, then
.Fn send
normally blocks, unless the socket has been placed in
non-blocking I/O mode.
The
.Xr select 2
or
.Xr poll 2
system calls may be used to determine when it is possible to
send more data.
.Pp
The
.Fa flags
parameter may include one or more of the following:
.Bd -literal
#define MSG_OOB 0x1 /* process out-of-band data */
#define MSG_DONTROUTE 0x4 /* bypass routing, use direct interface */
.Ed
.Pp
The flag
.Dv MSG_OOB
is used to send
.Dq out-of-band
data on sockets that support this notion (e.g.,
.Dv SOCK_STREAM ) ;
the underlying protocol must also support
.Dq out-of-band
data.
.Dv MSG_DONTROUTE
is usually used only by diagnostic or routing programs.
.Pp
See
.Xr recv 2
for a description of the
.Fa msghdr
structure.
.Sh RETURN VALUES
The call returns the number of characters sent, or \-1
if an error occurred.
.Sh ERRORS
.Fn send ,
.Fn sendto ,
and
.Fn sendmsg
fail if:
.Bl -tag -width Er
.It Bq Er EBADF
An invalid descriptor was specified.
.It Bq Er ENOTSOCK
The argument
.Fa s
is not a socket.
.It Bq Er EFAULT
An invalid user space address was specified for a parameter.
.It Bq Er EMSGSIZE
The socket requires that message be sent atomically,
and the size of the message to be sent made this impossible.
.It Bq Er EAGAIN
The socket is marked non-blocking and the requested operation
would block.
.It Bq Er ENOBUFS
The system was unable to allocate an internal buffer.
The operation may succeed when buffers become available.
.It Bq Er ENOBUFS
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.
.It Bq Er EACCES
The
.Dv SO_BROADCAST
option is not set on the socket, and a broadcast address
was given as the destination.
.It Bq Er EHOSTUNREACH
The destination address specified an unreachable host.
.It Bq Er EINVAL
The
.Fa flags
parameter is invalid.
.It Bq Er EHOSTDOWN
The destination address specified a host that is down.
.It Bq Er ENETDOWN
The destination address specified a network that is down.
.It Bq Er ECONNREFUSED
The destination host rejected the message (or a previous one).
This error can only be returned by connected sockets.
.It Bq Er ENOPROTOOPT
There was a problem sending the message.
This error can only be returned by connected sockets.
.It Bq Er EDESTADDRREQ
The socket is not connected, and no destination address was specified.
.It Bq Er EISCONN
The socket is already connected, and a destination address was specified.
.El
.Pp
In addition,
.Fn send
and
.Fn sendto
may return the following error:
.Bl -tag -width Er
.It Bq Er EINVAL
.Fa len
was larger than
.Dv SSIZE_MAX .
.El
.Pp
Also,
.Fn sendmsg
may return the following errors:
.Bl -tag -width Er
.It Bq Er EINVAL
The sum of the
.Fa iov_len
values in the
.Fa msg_iov
array overflowed an
.Em ssize_t .
.It Bq Er EMSGSIZE
The
.Fa msg_iovlen
member of
.Fa msg
was less than 0 or larger than
.Dv IOV_MAX .
.It Bq Er EAFNOSUPPORT
Addresses in the specified address family cannot be used with this socket.
.El
.Sh SEE ALSO
.Xr fcntl 2 ,
.Xr getsockopt 2 ,
.Xr poll 2 ,
.Xr recv 2 ,
.Xr select 2 ,
.Xr poll 2 ,
.Xr socket 2 ,
.Xr write 2
.Sh HISTORY
The
.Fn send
function call appeared in
.Bx 4.2 .
/connect.2
0,0 → 1,165
.\" $OpenBSD: connect.2,v 1.14 1999/08/15 13:14:11 deraadt Exp $
.\" $NetBSD: connect.2,v 1.8 1995/10/12 15:40:48 jtc Exp $
.\"
.\" Copyright (c) 1983, 1993
.\" The 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 acknowledgement:
.\" 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.
.\"
.\" @(#)connect.2 8.1 (Berkeley) 6/4/93
.\"
.Dd February 15, 1999
.Dt CONNECT 2
.Os
.Sh NAME
.Nm connect
.Nd initiate a connection on a socket
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Ft int
.Fn connect "int s" "const struct sockaddr *name" "socklen_t namelen"
.Sh DESCRIPTION
The parameter
.Fa s
is a socket.
If it is of type
.Dv SOCK_DGRAM ,
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
.Dv SOCK_STREAM ,
this call attempts to make a connection to
another socket.
The other socket is specified by
.Fa name ,
which is an address in the communications space of the socket.
Each communications space interprets the
.Fa name
parameter in its own way.
Generally, stream sockets may successfully
.Fn connect
only once; datagram sockets may use
.Fn connect
multiple times to change their association.
Datagram sockets may dissolve the association
by connecting to an invalid address, such as a null address.
.Sh RETURN VALUES
If the connection or binding succeeds, 0 is returned.
Otherwise a \-1 is returned, and a more specific error
code is stored in
.Va errno .
.Sh ERRORS
The
.Fn connect
call fails if:
.Bl -tag -width Er
.It Bq Er EBADF
.Fa S
is not a valid descriptor.
.It Bq Er ENOTSOCK
.Fa S
is a descriptor for a file, not a socket.
.It Bq Er EADDRNOTAVAIL
The specified address is not available on this machine.
.It Bq Er EAFNOSUPPORT
Addresses in the specified address family cannot be used with this socket.
.It Bq Er EISCONN
The socket is already connected.
.It Bq Er ETIMEDOUT
Connection establishment timed out without establishing a connection.
.It Bq Er EINVAL
A TCP connection with a local broadcast, the all-ones or a
multicast address as the peer was attempted.
.It Bq Er ECONNREFUSED
The attempt to connect was forcefully rejected.
.It Bq Er EINTR
A connect was interrupted before it succeeded
by the delivery of a signal.
.It Bq Er ENETUNREACH
The network isn't reachable from this host.
.It Bq Er EADDRINUSE
The address is already in use.
.It Bq Er EFAULT
The
.Fa name
parameter specifies an area outside
the process address space.
.It Bq Er EINPROGRESS
The socket is non-blocking
and the connection cannot
be completed immediately.
It is possible to
.Xr select 2
or
.Xr poll 2
for completion by selecting the socket for writing, and also use
.Xr getsockopt 2
with
.Dv SO_ERROR
to check for error conditions.
.It Bq Er EALREADY
The socket is non-blocking
and a previous connection attempt
has not yet been completed.
.El
.Pp
The following errors are specific to connecting names in the UNIX domain.
These errors may not apply in future versions of the UNIX IPC domain.
.Bl -tag -width Er
.It Bq Er ENOTDIR
A component of the path prefix is not a directory.
.It Bq Er ENAMETOOLONG
A component of a pathname exceeded
.Dv {NAME_MAX}
characters, or an entire path name exceeded
.Dv {PATH_MAX}
characters.
.It Bq Er ENOENT
The named socket does not exist.
.It Bq Er EACCES
Search permission is denied for a component of the path prefix.
.It Bq Er EACCES
Write access to the named socket is denied.
.It Bq Er ELOOP
Too many symbolic links were encountered in translating the pathname.
.El
.Sh SEE ALSO
.Xr accept 2 ,
.Xr getsockname 2 ,
.Xr getsockopt 2 ,
.Xr poll 2 ,
.Xr select 2 ,
.Xr socket 2
.Sh HISTORY
The
.Fn connect
function call appeared in
.Bx 4.2 .
/ioctl.2
0,0 → 1,126
.\" $OpenBSD: ioctl.2,v 1.11 2001/07/30 01:12:43 deraadt Exp $
.\" $NetBSD: ioctl.2,v 1.5 1995/02/27 12:33:47 cgd Exp $
.\"
.\" Copyright (c) 1980, 1991, 1993
.\" The 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 acknowledgement:
.\" 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.
.\"
.\" @(#)ioctl.2 8.2 (Berkeley) 12/11/93
.\"
.Dd December 11, 1993
.Dt IOCTL 2
.Os
.Sh NAME
.Nm ioctl
.Nd control device
.Sh SYNOPSIS
.Fd #include <sys/ioctl.h>
.Ft int
.Fn ioctl "int d" "unsigned long request" "..."
.Sh DESCRIPTION
The
.Fn ioctl
function manipulates the underlying device parameters of special files.
In particular, many operating
characteristics of character special files (e.g., terminals)
may be controlled with
.Fn ioctl
requests.
.Pp
The argument
.Fa d
must be an open file descriptor. The third argument is called
.Fa arg
and contains additional information needed by this device
to perform the requested function.
.Fa arg
is either an
.Li int
or a pointer to a device-specific data structure, depending upon
the given
.Fa request .
.Pp
An
.Nm
.Fa request
has encoded in it whether the argument is an
.Dq in
parameter
or
.Dq out
parameter, and the size of the third argument
.Pq Fa arg
in bytes.
Macros and defines used in specifying an ioctl
.Fa request
are located in the file
.Ao Pa sys/ioctl.h Ac .
.Sh RETURN VALUES
If an error has occurred, a value of \-1 is returned and
.Va errno
is set to indicate the error.
.Sh ERRORS
.Fn ioctl
will fail if:
.Bl -tag -width Er
.It Bq Er EBADF
.Fa d
is not a valid descriptor.
.It Bq Er ENOTTY
.Fa d
is not associated with a character
special device.
.It Bq Er ENOTTY
The specified request does not apply to the kind
of object that the descriptor
.Fa d
references.
.It Bq Er EINVAL
.Fa request
or
.Fa arg
is not valid.
.It Bq Er EFAULT
.Fa arg
points outside the process's allocated address space.
.El
.Sh SEE ALSO
.Xr cdio 1 ,
.Xr chio 1 ,
.Xr mt 1 ,
.Xr execve 2 ,
.Xr fcntl 2 ,
.Xr intro 4 ,
.Xr tty 4
.Sh HISTORY
An
.Fn ioctl
function call appeared in
.At v7 .
/shutdown.2
0,0 → 1,103
.\" $OpenBSD: shutdown.2,v 1.9 2000/08/09 12:57:54 aaron Exp $
.\" $NetBSD: shutdown.2,v 1.5 1995/02/27 12:37:11 cgd Exp $
.\"
.\" Copyright (c) 1983, 1991, 1993
.\" The 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 acknowledgement:
.\" 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.
.\"
.\" @(#)shutdown.2 8.1 (Berkeley) 6/4/93
.\"
.Dd June 4, 1993
.Dt SHUTDOWN 2
.Os
.Sh NAME
.Nm shutdown
.Nd shut down part of a full-duplex connection
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Ft int
.Fn shutdown "int s" "int how"
.Sh DESCRIPTION
The
.Fn shutdown
call causes all or part of a full-duplex connection on
the socket associated with
.Fa s
to be shut down.
If
.Fa how
is
.Ar SHUT_RD ,
further receives will be disallowed.
If
.Fa how
is
.Ar SHUT_WR ,
further sends will be disallowed.
If
.Fa how
is
.Ar SHUT_RDWR ,
further sends and receives will be disallowed.
.Sh RETURN VALUES
A 0 is returned if the call succeeds, \-1 if it fails.
.Sh ERRORS
The call succeeds unless:
.Bl -tag -width Er
.It Bq Er EINVAL
.Fa how
is not
.Ar SHUT_RD ,
.Ar SHUT_WR ,
or
.Ar SHUT_RDWR .
.It Bq Er EBADF
.Fa s
is not a valid descriptor.
.It Bq Er ENOTSOCK
.Fa s
is a file, not a socket.
.It Bq Er ENOTCONN
The specified socket is not connected.
.El
.Sh SEE ALSO
.Xr connect 2 ,
.Xr socket 2
.Sh HISTORY
The
.Fn shutdown
function call appeared in
.Bx 4.2 .
The
.Fa how
arguments used to be simply 0, 1, and 2, but now have named values
as specified by
.St -xpg4 .
/bind.2
0,0 → 1,131
.\" $OpenBSD: bind.2,v 1.10 2000/10/18 05:12:08 aaron Exp $
.\" $NetBSD: bind.2,v 1.8 1995/10/12 15:40:46 jtc Exp $
.\"
.\" Copyright (c) 1983, 1993
.\" The 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 acknowledgement:
.\" 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.
.\"
.\" @(#)bind.2 8.1 (Berkeley) 6/4/93
.\"
.Dd February 15, 1999
.Dt BIND 2
.Os
.Sh NAME
.Nm bind
.Nd bind a name to a socket
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Ft int
.Fn bind "int s" "const struct sockaddr *name" "socklen_t namelen"
.Sh DESCRIPTION
.Fn bind
assigns a name to an unnamed socket.
When a socket is created with
.Xr socket 2
it exists in a name space (address family) but has no name assigned.
.Fn bind
requests that
.Fa name
be assigned to the socket.
.Sh NOTES
Binding a name in the UNIX domain creates a socket in the file
system that must be deleted by the caller when it is no longer
needed (using
.Xr unlink 2 ) .
.Pp
The rules used in name binding vary between communication domains.
Consult the manual entries in section 4 for detailed information.
.Sh RETURN VALUES
If the bind is successful, a 0 value is returned.
A return value of \-1 indicates an error, which is
further specified in the global
.Va errno .
.Sh ERRORS
The
.Fn bind
call will fail if:
.Bl -tag -width Er
.It Bq Er EBADF
.Fa S
is not a valid descriptor.
.It Bq Er ENOTSOCK
.Fa S
is not a socket.
.It Bq Er EADDRNOTAVAIL
The specified address is not available from the local machine.
.It Bq Er EADDRINUSE
The specified address is already in use.
.It Bq Er EINVAL
The socket is already bound to an address.
.It Bq Er EINVAL
The family of the socket and that requested in
.Va name->sa_family
are not equivalent.
.It Bq Er EACCES
The requested address is protected, and the current user
has inadequate permission to access it.
.It Bq Er EFAULT
The
.Fa name
parameter is not in a valid part of the user address space.
.El
.Pp
The following errors are specific to binding names in the UNIX domain.
.Bl -tag -width Er
.It Bq Er ENOTDIR
A component of the path prefix is not a directory.
.It Bq Er ENAMETOOLONG
A component of a pathname exceeded
.Dv {NAME_MAX}
characters, or an entire path name exceeded
.Dv {PATH_MAX}
characters.
.It Bq Er ENOENT
A prefix component of the path name does not exist.
.It Bq Er ELOOP
Too many symbolic links were encountered in translating the pathname.
.It Bq Er EIO
An I/O error occurred while making the directory entry or allocating the inode.
.It Bq Er EROFS
The name would reside on a read-only file system.
.It Bq Er EISDIR
An empty pathname was specified.
.El
.Sh SEE ALSO
.Xr connect 2 ,
.Xr getsockname 2 ,
.Xr listen 2 ,
.Xr socket 2
.Sh HISTORY
The
.Fn bind
function call appeared in
.Bx 4.2 .
/getpeername.2
0,0 → 1,141
.\" $OpenBSD: getpeername.2,v 1.16 2001/06/26 19:56:52 dugsong Exp $
.\" $NetBSD: getpeername.2,v 1.6 1995/10/12 15:40:56 jtc Exp $
.\"
.\" Copyright (c) 1983, 1991, 1993
.\" The 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 acknowledgement:
.\" 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.
.\"
.\" @(#)getpeername.2 8.1 (Berkeley) 6/4/93
.\"
.Dd July 17, 1999
.Dt GETPEERNAME 2
.Os
.Sh NAME
.Nm getpeername
.Nd get name of connected peer
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Ft int
.Fn getpeername "int s" "struct sockaddr *name" "socklen_t *namelen"
.Sh DESCRIPTION
.Fn getpeername
returns the address information of the peer connected to socket
.Fa s .
One common use occurs when a process inherits an open socket, such as
TCP servers forked from
.Xr inetd 8 .
In this scenario,
.Fn getpeername
is used to determine the connecting client's IP address.
.Pp
.Fn getpeername
takes three parameters:
.Pp
.Fa s
Contains the file descriptor of the socket whose peer should be looked up.
.Pp
.Fa name
Points to a
.Li sockaddr
structure that will hold the address information for the connected peer.
Normal use requires one to use a structure
specific to the protocol family in use, such as
.Li sockaddr_in
(IPv4) or
.Li sockaddr_in6
(IPv6), cast to a (struct sockaddr *).
.Pp
For greater portability, especially with the newer protocol families, the new
.Li struct sockaddr_storage
should be used.
.Li sockaddr_storage
is large enough to hold any of the other sockaddr_* variants.
On return, it can be cast to the correct sockaddr type,
based the protocol family contained in its ss_family field.
.Pp
.Fa namelen
Indicates the amount of space pointed to by
.Fa name ,
in bytes.
.Pp
If address information for the local end of the socket is required, the
.Xr getsockname 2
function should be used instead.
.Pp
If
.Fa name
does not point to enough space to hold the entire socket address, the
result will be truncated to
.Fa namelen
bytes.
.Sh RETURN VALUES
If the call succeeds, a 0 is returned and
.Fa namelen
is set to the actual size of the socket address returned in
.Fa name .
Otherwise,
.Va errno
is set and a value of \-1 is returned.
.Sh ERRORS
On failure,
.Va errno
is set to one of the following:
.Bl -tag -width Er
.It Bq Er EBADF
The argument
.Fa s
is not a valid descriptor.
.It Bq Er ENOTSOCK
The argument
.Fa s
is a file, not a socket.
.It Bq Er ENOTCONN
The socket is not connected.
.It Bq Er ENOBUFS
Insufficient resources were available in the system
to perform the operation.
.It Bq Er EFAULT
The
.Fa name
parameter points to memory not in a valid part of the
process address space.
.El
.Sh SEE ALSO
.Xr accept 2 ,
.Xr bind 2 ,
.Xr getsockname 2 ,
.Xr getpeereid 2 ,
.Xr socket 2
.Sh HISTORY
The
.Fn getpeername
function call appeared in
.Bx 4.2 .

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.