mirror of https://github.com/mkerrisk/man-pages
228 lines
8.2 KiB
Plaintext
228 lines
8.2 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "GETSOCKOPT" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" getsockopt
|
|
.SH NAME
|
|
getsockopt \- get the socket options
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <sys/socket.h>
|
|
.br
|
|
.sp
|
|
int getsockopt(int\fP \fIsocket\fP\fB, int\fP \fIlevel\fP\fB, int\fP
|
|
\fIoption_name,\fP\fB
|
|
.br
|
|
\ \ \ \ \ \ void *restrict\fP \fIoption_value\fP\fB, socklen_t *restrict\fP
|
|
\fIoption_len\fP\fB);
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIgetsockopt\fP() function manipulates options associated with
|
|
a socket.
|
|
.LP
|
|
The \fIgetsockopt\fP() function shall retrieve the value for the option
|
|
specified by the \fIoption_name\fP argument for the
|
|
socket specified by the \fIsocket\fP argument. If the size of the
|
|
option value is greater than \fIoption_len\fP, the value stored
|
|
in the object pointed to by the \fIoption_value\fP argument shall
|
|
be silently truncated. Otherwise, the object pointed to by the
|
|
\fIoption_len\fP argument shall be modified to indicate the actual
|
|
length of the value.
|
|
.LP
|
|
The \fIlevel\fP argument specifies the protocol level at which the
|
|
option resides. To retrieve options at the socket level,
|
|
specify the \fIlevel\fP argument as SOL_SOCKET. To retrieve options
|
|
at other levels, supply the appropriate level identifier for
|
|
the protocol controlling the option. For example, to indicate that
|
|
an option is interpreted by the TCP (Transmission Control
|
|
Protocol), set \fIlevel\fP to IPPROTO_TCP as defined in the \fI<netinet/in.h>\fP
|
|
header.
|
|
.LP
|
|
The socket in use may require the process to have appropriate privileges
|
|
to use the \fIgetsockopt\fP() function.
|
|
.LP
|
|
The \fIoption_name\fP argument specifies a single option to be retrieved.
|
|
It can be one of the following values defined in \fI<sys/socket.h>\fP:
|
|
.TP 7
|
|
SO_DEBUG
|
|
Reports whether debugging information is being recorded. This option
|
|
shall store an \fBint\fP value. This is a Boolean
|
|
option.
|
|
.TP 7
|
|
SO_ACCEPTCONN
|
|
Reports whether socket listening is enabled. This option shall store
|
|
an \fBint\fP value. This is a Boolean option.
|
|
.TP 7
|
|
SO_BROADCAST
|
|
Reports whether transmission of broadcast messages is supported, if
|
|
this is supported by the protocol. This option shall store
|
|
an \fBint\fP value. This is a Boolean option.
|
|
.TP 7
|
|
SO_REUSEADDR
|
|
Reports whether the rules used in validating addresses supplied to
|
|
\fIbind\fP() should
|
|
allow reuse of local addresses, if this is supported by the protocol.
|
|
This option shall store an \fBint\fP value. This is a
|
|
Boolean option.
|
|
.TP 7
|
|
SO_KEEPALIVE
|
|
Reports whether connections are kept active with periodic transmission
|
|
of messages, if this is supported by the protocol.
|
|
.LP
|
|
If the connected socket fails to respond to these messages, the connection
|
|
shall be broken and threads writing to that socket
|
|
shall be notified with a SIGPIPE signal. This option shall store an
|
|
\fBint\fP value. This is a Boolean option.
|
|
.TP 7
|
|
SO_LINGER
|
|
Reports whether the socket lingers on \fIclose\fP() if data is present.
|
|
If SO_LINGER is
|
|
set, the system blocks the process during \fIclose\fP() until it can
|
|
transmit the data or
|
|
until the end of the interval indicated by the \fIl_linger\fP member,
|
|
whichever comes first. If SO_LINGER is not specified, and \fIclose\fP()
|
|
is issued, the system handles the call in a way that allows the process
|
|
to
|
|
continue as quickly as possible. This option shall store a \fBlinger\fP
|
|
structure.
|
|
.TP 7
|
|
SO_OOBINLINE
|
|
Reports whether the socket leaves received out-of-band data (data
|
|
marked urgent) inline. This option shall store an \fBint\fP
|
|
value. This is a Boolean option.
|
|
.TP 7
|
|
SO_SNDBUF
|
|
Reports send buffer size information. This option shall store an \fBint\fP
|
|
value.
|
|
.TP 7
|
|
SO_RCVBUF
|
|
Reports receive buffer size information. This option shall store an
|
|
\fBint\fP value.
|
|
.TP 7
|
|
SO_ERROR
|
|
Reports information about error status and clears it. This option
|
|
shall store an \fBint\fP value.
|
|
.TP 7
|
|
SO_TYPE
|
|
Reports the socket type. This option shall store an \fBint\fP value.
|
|
Socket types are described in \fISocket Types\fP .
|
|
.TP 7
|
|
SO_DONTROUTE
|
|
Reports whether outgoing messages bypass the standard routing facilities.
|
|
The destination shall be on a directly-connected
|
|
network, and messages are directed to the appropriate network interface
|
|
according to the destination address. The effect, if any,
|
|
of this option depends on what protocol is in use. This option shall
|
|
store an \fBint\fP value. This is a Boolean option.
|
|
.TP 7
|
|
SO_RCVLOWAT
|
|
Reports the minimum number of bytes to process for socket input operations.
|
|
The default value for SO_RCVLOWAT is 1. If
|
|
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. (They may 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 from that returned;
|
|
for example, out-of-band data.) This option shall store an
|
|
\fBint\fP value. Note that not all implementations allow this option
|
|
to be retrieved.
|
|
.TP 7
|
|
SO_RCVTIMEO
|
|
Reports the timeout value for input operations. This option shall
|
|
store a \fBtimeval\fP structure with the number of seconds
|
|
and microseconds specifying the limit on how long to wait for an input
|
|
operation to complete. If a receive operation has blocked
|
|
for this much time without receiving additional data, it shall return
|
|
with a partial count or \fIerrno\fP set to [EAGAIN] or
|
|
[EWOULDBLOCK] if no data was received. The default for this option
|
|
is zero, which indicates that a receive operation shall not time
|
|
out. Note that not all implementations allow this option to be retrieved.
|
|
.TP 7
|
|
SO_SNDLOWAT
|
|
Reports the minimum number of bytes to process for socket output operations.
|
|
Non-blocking output operations shall process no
|
|
data if flow control does not allow the smaller of the send low water
|
|
mark value or the entire request to be processed. This option
|
|
shall store an \fBint\fP value. Note that not all implementations
|
|
allow this option to be retrieved.
|
|
.TP 7
|
|
SO_SNDTIMEO
|
|
Reports the timeout value specifying the amount of time that an output
|
|
function blocks because flow control prevents data from
|
|
being sent. If a send operation has blocked for this time, it shall
|
|
return with a partial count or with \fIerrno\fP set to
|
|
[EAGAIN] or [EWOULDBLOCK] if no data was sent. The default for this
|
|
option is zero, which indicates that a send operation shall not
|
|
time out. The option shall store a \fBtimeval\fP structure. Note that
|
|
not all implementations allow this option to be
|
|
retrieved.
|
|
.sp
|
|
.LP
|
|
For Boolean options, a zero value indicates that the option is disabled
|
|
and a non-zero value indicates that the option is
|
|
enabled.
|
|
.SH RETURN VALUE
|
|
.LP
|
|
Upon successful completion, \fIgetsockopt\fP() shall return 0; otherwise,
|
|
-1 shall be returned and \fIerrno\fP set to indicate
|
|
the error.
|
|
.SH ERRORS
|
|
.LP
|
|
The \fIgetsockopt\fP() function shall fail if:
|
|
.TP 7
|
|
.B EBADF
|
|
The \fIsocket\fP argument is not a valid file descriptor.
|
|
.TP 7
|
|
.B EINVAL
|
|
The specified option is invalid at the specified socket level.
|
|
.TP 7
|
|
.B ENOPROTOOPT
|
|
.sp
|
|
The option is not supported by the protocol.
|
|
.TP 7
|
|
.B ENOTSOCK
|
|
The \fIsocket\fP argument does not refer to a socket.
|
|
.sp
|
|
.LP
|
|
The \fIgetsockopt\fP() function may fail if:
|
|
.TP 7
|
|
.B EACCES
|
|
The calling process does not have the appropriate privileges.
|
|
.TP 7
|
|
.B EINVAL
|
|
The socket has been shut down.
|
|
.TP 7
|
|
.B ENOBUFS
|
|
Insufficient resources are available in the system to complete the
|
|
function.
|
|
.sp
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.LP
|
|
None.
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
None.
|
|
.SH RATIONALE
|
|
.LP
|
|
None.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIbind\fP() , \fIclose\fP() , \fIendprotoent\fP() , \fIsetsockopt\fP()
|
|
, \fIsocket\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
|
\fI<sys/socket.h>\fP, \fI<netinet/in.h>\fP
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
event of any discrepancy between this version and the original IEEE and
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
is the referee document. The original Standard can be obtained online at
|
|
http://www.opengroup.org/unix/online.html .
|