1GETSOCKOPT(2)                 System Calls Manual                GETSOCKOPT(2)
2
3
4

NAME

6       getsockopt, setsockopt - get and set options on sockets
7

SYNOPSIS

9       #include <sys/types.h>
10       #include <sys/socket.h>
11
12       getsockopt(s, level, optname, optval, optlen)
13       int s, level, optname;
14       char *optval;
15       int *optlen;
16
17       setsockopt(s, level, optname, optval, optlen)
18       int s, level, optname;
19       char *optval;
20       int optlen;
21

DESCRIPTION

23       Getsockopt  and setsockopt manipulate options associated with a socket.
24       Options may exist at multiple protocol levels; they are always  present
25       at the uppermost ``socket'' level.
26
27       When  manipulating socket options the level at which the option resides
28       and the name of the option must be specified.  To manipulate options at
29       the  ``socket'' level, level is specified as SOL_SOCKET.  To manipulate
30       options at any other level the protocol number of the appropriate  pro‐
31       tocol  controlling  the  option  is supplied.  For example, to indicate
32       that an option is to be interpreted by the TCP protocol,  level  should
33       be set to the protocol number of TCP; see getprotoent(3N).
34
35       The  parameters  optval and optlen are used to access option values for
36       setsockopt.  For getsockopt they identify a buffer in which  the  value
37       for the requested option(s) are to be returned.  For getsockopt, optlen
38       is a value-result parameter, initially containing the size of the  buf‐
39       fer pointed to by optval, and modified on return to indicate the actual
40       size of the value returned.  If no option value is to  be  supplied  or
41       returned, optval may be supplied as 0.
42
43       Optname  and  any  specified  options  are  passed uninterpreted to the
44       appropriate protocol  module  for  interpretation.   The  include  file
45       <sys/socket.h>  contains  definitions  for  ``socket''  level  options,
46       described below.  Options at other protocol levels vary in  format  and
47       name; consult the appropriate entries in section (4P).
48
49       Most  socket-level  options take an int parameter for optval.  For set‐
50       sockopt, the parameter should non-zero to enable a boolean  option,  or
51       zero  if  the option is to be disabled.  SO_LINGER uses a struct linger
52       parameter, defined in <sys/socket.h>, which specifies the desired state
53       of the option and the linger interval (see below).
54
55       The  following  options  are recognized at the socket level.  Except as
56       noted, each may be examined with getsockopt and set with setsockopt.
57
58              SO_DEBUG        toggle recording of debugging information
59              SO_REUSEADDR    toggle local address reuse
60              SO_KEEPALIVE    toggle keep connections alive
61              SO_DONTROUTE    toggle routing bypass for outgoing messages
62              SO_LINGER       linger on close if data present
63              SO_BROADCAST    toggle permission to transmit broadcast messages
64              SO_OOBINLINE    toggle reception of out-of-band data in band
65              SO_SNDBUF       set buffer size for output
66              SO_RCVBUF       set buffer size for input
67              SO_TYPE         get the type of the socket (get only)
68              SO_ERROR        get and clear error on the socket (get only)
69
70       SO_DEBUG  enables  debugging  in  the  underlying   protocol   modules.
71       SO_REUSEADDR indicates that the rules used in validating addresses sup‐
72       plied in  a  bind(2)  call  should  allow  reuse  of  local  addresses.
73       SO_KEEPALIVE  enables  the  periodic transmission of messages on a con‐
74       nected socket.  Should the connected party fail  to  respond  to  these
75       messages,  the  connection is considered broken and processes using the
76       socket are notified via a SIGPIPE signal.  SO_DONTROUTE indicates  that
77       outgoing  messages  should  bypass  the  standard  routing  facilities.
78       Instead, messages are directed to  the  appropriate  network  interface
79       according to the network portion of the destination address.
80
81       SO_LINGER  controls  the action taken when unsent messags are queued on
82       socket and a close(2) is performed.  If the  socket  promises  reliable
83       delivery  of  data  and  SO_LINGER  is  set,  the system will block the
84       process on the close attempt until it is able to transmit the  data  or
85       until  it  decides  it  is unable to deliver the information (a timeout
86       period, termed the linger interval, is specified in the setsockopt call
87       when  SO_LINGER is requested).  If SO_LINGER is disabled and a close is
88       issued, the system will process the close in a manner that  allows  the
89       process to continue as quickly as possible.
90
91       The option SO_BROADCAST requests permission to send broadcast datagrams
92       on the socket.  Broadcast was a privileged operation  in  earlier  ver‐
93       sions of the system.  With protocols that support out-of-band data, the
94       SO_OOBINLINE option requests that out-of-band data  be  placed  in  the
95       normal  data  input  queue as received; it will then be accessible with
96       recv or read calls without the MSG_OOB flag.  SO_SNDBUF  and  SO_RCVBUF
97       are  options to adjust the normal buffer sizes allocated for output and
98       input buffers, respectively.  The buffer  size  may  be  increased  for
99       high-volume  connections,  or  may  be  decreased to limit the possible
100       backlog of incoming data.  The system places an absolute limit on these
101       values.   Finally, SO_TYPE and SO_ERROR are options used only with set‐
102       sockopt.  SO_TYPE returns the type of the socket, such as  SOCK_STREAM;
103       it  is  useful  for  servers that inherit sockets on startup.  SO_ERROR
104       returns any pending error on the socket and clears  the  error  status.
105       It  may  be used to check for asynchronous errors on connected datagram
106       sockets or for other asynchronous errors.
107

RETURN VALUE

109       A 0 is returned if the call succeeds, -1 if it fails.
110

ERRORS

112       The call succeeds unless:
113
114       [EBADF]             The argument s is not a valid descriptor.
115
116       [ENOTSOCK]          The argument s is a file, not a socket.
117
118       [ENOPROTOOPT]       The option is unknown at the level indicated.
119
120       [EFAULT]            The address pointed to by optval is not in a  valid
121                           part of the process address space.  For getsockopt,
122                           this error may also be returned if optlen is not in
123                           a valid part of the process address space.
124

SEE ALSO

126       ioctl(2), socket(2), getprotoent(3N)
127

BUGS

129       Several  of the socket options should be handled at lower levels of the
130       system.
131
132
133
1344.2 Berkeley Distribution        May 23, 1986                    GETSOCKOPT(2)
Impressum