1getsockopt(3SOCKET)        Sockets Library Functions       getsockopt(3SOCKET)
2
3
4

NAME

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

SYNOPSIS

9       cc [ flag ... ] file ... -lsocket  -lnsl  [ library ... ]
10       #include <sys/types.h>
11       #include <sys/socket.h>
12
13       int getsockopt(int s, int level, int optname, void *optval,
14            int *optlen);
15
16
17       int setsockopt(int s, int level, int optname, const void *optval,
18            int optlen);
19
20

DESCRIPTION

22       The  getsockopt() and setsockopt() functions manipulate options associ‐
23       ated with a socket. Options may exist at multiple protocol levels; they
24       are always present at the uppermost "socket" level.
25
26
27       The  level  argument  specifies  the protocol level at which the option
28       resides. To manipulate options at the socket level, specify  the  level
29       argument  as  SOL_SOCKET.  To manipulate options at the protocol level,
30       supply the appropriate protocol number for the protocol controlling the
31       option.  For example, to indicate that an option will be interpreted by
32       the TCP, set level to the protocol number of TCP,  as  defined  in  the
33       <netinet/in.h>   header,   or   as   determined  by  using  getprotoby‐
34       name(3SOCKET). Some socket protocol families may also define additional
35       levels,  such  as  SOL_ROUTE.  Only  socket-level options are described
36       here.
37
38
39       The parameters optval and optlen are used to access option  values  for
40       setsockopt().  For  getsockopt(),  they  identify a buffer in which the
41       value(s) for the requested option(s) are to be returned.  For  getsock‐
42       opt(),  optlen  is  a  value-result parameter, initially containing the
43       size of the buffer pointed to by optval,  and  modified  on  return  to
44       indicate  the  actual  size of the value returned. Use a 0 optval if no
45       option value is to be supplied or returned.
46
47
48       The optname and any specified options are passed uninterpreted  to  the
49       appropriate  protocol  module  for  interpretation.  The  include  file
50       <sys/socket.h>  contains  definitions  for  the  socket-level   options
51       described  below.  Options  at other protocol levels vary in format and
52       name.
53
54
55       Most socket-level options take an int for optval. For setsockopt(), the
56       optval parameter should be non-zero to enable a boolean option, or zero
57       if the option is to be disabled. SO_LINGER uses a struct linger parame‐
58       ter  that  specifies  the  desired  state  of the option and the linger
59       interval. struct linger is defined  in  <sys/socket.h>.  struct  linger
60       contains the following members:
61
62       l_onoff     on = 1/off = 0
63
64
65       l_linger    linger time, in seconds
66
67
68
69       The  following  options  are  recognized at the socket level. Except as
70       noted, each may be examined with getsockopt()  and  set  with  setsock‐
71       opt().
72
73       SO_DEBUG           enable/disable recording of debugging information
74
75
76       SO_REUSEADDR       enable/disable local address reuse
77
78
79       SO_KEEPALIVE       enable/disable keep connections alive
80
81
82       SO_DONTROUTE       enable/disable routing bypass for outgoing messages
83
84
85       SO_LINGER          linger on close if data is present
86
87
88       SO_BROADCAST       enable/disable permission to transmit broadcast mes‐
89                          sages
90
91
92       SO_OOBINLINE       enable/disable reception of out-of-band data in band
93
94
95       SO_SNDBUF          set buffer size for output
96
97
98       SO_RCVBUF          set buffer size for input
99
100
101       SO_DGRAM_ERRIND    application wants delayed error
102
103
104       SO_TIMESTAMP       enable/disable reception of timestamp with datagrams
105
106
107       SO_EXCLBIND        enable/disable exclusive binding of the socket
108
109
110       SO_TYPE            get the type of the socket (get only)
111
112
113       SO_ERROR           get and clear error on the socket (get only)
114
115
116       SO_MAC_EXEMPT      get or set mandatory access control on  the  socket.
117                          This  option  is  available  only when the system is
118                          configured with Trusted Extensions.
119
120
121       SO_ALLZONES        bypass zone boundaries (privileged).
122
123
124       SO_DOMAIN          get the domain used in the socket (get only)
125
126
127       SO_PROTOTYPE       for socket in domains PF_INET and PF_INET6, get  the
128                          underlying  protocol  number used in the socket. For
129                          socket in domain PF_ROUTE, get  the  address  family
130                          used in the socket.
131
132
133
134       The  SO_DEBUG  option enables debugging in the underlying protocol mod‐
135       ules. The SO_REUSEADDR option indicates that the rules used in validat‐
136       ing  addresses  supplied  in a bind(3SOCKET) call should allow reuse of
137       local addresses. The SO_KEEPALIVE option enables the periodic transmis‐
138       sion of messages on a connected socket. If the connected party fails to
139       respond to these messages, the  connection  is  considered  broken  and
140       threads  using  the  socket  are  notified  using a SIGPIPE signal. The
141       SO_DONTROUTE option indicates that outgoing messages should bypass  the
142       standard  routing  facilities.  Instead,  messages  are directed to the
143       appropriate network interface according to the network portion  of  the
144       destination address.
145
146
147       The SO_LINGER option controls the action taken when unsent messages are
148       queued on a socket and a close(2) is performed. If the socket  promises
149       reliable  delivery  of data and SO_LINGER is set, the system will block
150       the thread on the close() attempt until it is able to transmit the data
151       or  until it decides it is unable to deliver the information (a timeout
152       period, termed the linger interval, is specified  in  the  setsockopt()
153       call  when  SO_LINGER  is  requested).  If  SO_LINGER is disabled and a
154       close() is issued, the system will process the close() in a manner that
155       allows the thread to continue as quickly as possible.
156
157
158       The option SO_BROADCAST requests permission to send broadcast datagrams
159       on the socket.  With  protocols  that  support  out-of-band  data,  the
160       SO_OOBINLINE  option  requests  that  out-of-band data be placed in the
161       normal data input queue as received; it will then  be  accessible  with
162       recv() or read() calls without the MSG_OOB flag.
163
164
165       The  SO_SNDBUF  and  SO_RCVBUF  options  adjust the normal buffer sizes
166       allocated for output and input buffers, respectively. The  buffer  size
167       may  be  increased  for  high-volume connections or may be decreased to
168       limit the possible backlog of incoming data. The  maximum  buffer  size
169       for UDP is determined by the value of the ndd variable udp_max_buf. The
170       maximum buffer size for TCP is determined the value of the ndd variable
171       tcp_max_buf.  Use  the ndd(1M) utility to determine the current default
172       values. See the Solaris Tunable Parameters Reference Manual for  infor‐
173       mation  on  setting  the  values  of  udp_max_buf  and  tcp_max_buf. At
174       present, lowering SO_RCVBUF on a  TCP  connection  after  it  has  been
175       established has no effect.
176
177
178       By  default, delayed errors (such as ICMP port unreachable packets) are
179       returned only  for  connected  datagram  sockets.  The  SO_DGRAM_ERRIND
180       option  makes  it  possible to receive errors for datagram sockets that
181       are not connected. When this option  is  set,  certain  delayed  errors
182       received  after  completion  of  a sendto() or sendmsg() operation will
183       cause a subsequent sendto() or sendmsg() operation using the same  des‐
184       tination address (to parameter) to fail with the appropriate error. See
185       send(3SOCKET).
186
187
188       If the SO_TIMESTAMP option is enabled on a SO_DGRAM or a SO_RAW socket,
189       the recvmsg(3XNET) call will return a timestamp in the native data for‐
190       mat, corresponding to when the datagram was received.
191
192
193       The SO_EXCLBIND option is used to enable or disable the exclusive bind‐
194       ing of a socket. It overrides the use of the SO_REUSEADDR option to re‐
195       use  an  address  on  bind(3SOCKET).  The  actual  semantics   of   the
196       SO_EXCLBIND  option  depend  on the underlying protocol. See tcp(7P) or
197       udp(7P) for more information.
198
199
200       The SO_TYPE and SO_ERROR options are used only with  getsockopt().  The
201       SO_TYPE   option   returns   the  type  of  the  socket,  for  example,
202       SOCK_STREAM. It is useful for servers that inherit sockets on  startup.
203       The  SO_ERROR option returns any pending error on the socket and clears
204       the error status. It may be used to check for  asynchronous  errors  on
205       connected datagram sockets or for other asynchronous errors.
206
207
208       The  SO_MAC_EXEMPT  option is used to toggle socket behavior with unla‐
209       beled peers. A socket that has this option enabled can communicate with
210       an unlabeled peer if it is in the global zone or has a label that domi‐
211       nates the default label of the peer. Otherwise, the socket must have  a
212       label that is equal to the default label of the unlabeled peer. Calling
213       setsockopt() with this option returns an EACCES error  if  the  process
214       lacks  the  NET_MAC_AWARE  privilege  or  if  the  socket is bound. The
215       SO_MAC_EXEMPT option is available only when the  system  is  configured
216       with Trusted Extensions.
217
218
219       The  SO_ALLZONES  option  can be used to bypass zone boundaries between
220       shared-IP zones. Normally, the system  prevents  a  socket  from  being
221       bound  to  an address that is not assigned to the current zone. It also
222       prevents a socket that is bound to a wildcard  address  from  receiving
223       traffic  for other zones. However, some daemons which run in the global
224       zone might need to send and receive traffic using addresses that belong
225       to  other shared-IP zones. If set before a socket is bound, SO_ALLZONES
226       causes the socket to ignore zone boundaries between shared-IP zones and
227       permits the socket to be bound to any address assigned to the shared-IP
228       zones. If the socket is bound to a wildcard address, it receives  traf‐
229       fic  intended  for  all shared-IP zones and behaves as if an equivalent
230       socket were bound in each active shared-IP zone. Applications that  use
231       the SO_ALLZONES option to initiate connections or send datagram traffic
232       should specify the source address for outbound traffic by binding to  a
233       specific  address.  There  is  no effect from setting this option in an
234       exclusive-IP zone. Setting  this  option  requires  the  sys_net_config
235       privilege. See zones(5).
236

RETURN VALUES

238       If  successful,  getsockopt() and setsockopt() return 0. Otherwise, the
239       functions return −1 and set errno to indicate the error.
240

ERRORS

242       The getsockopt() and setsockopt() calls succeed unless:
243
244       EBADF            The argument s is not a valid file descriptor.
245
246
247       ENOMEM           There was insufficient memory available for the opera‐
248                        tion to complete.
249
250
251       ENOPROTOOPT      The option is unknown at the level indicated.
252
253
254       ENOSR            There  were  insufficient  STREAMS resources available
255                        for the operation to complete.
256
257
258       ENOTSOCK         The argument s is not a socket.
259
260
261       ENOBUFS          SO_SNDBUF or SO_RCVBUF exceeds a system limit.
262
263
264       EINVAL           Invalid length for IP_OPTIONS.
265
266
267       EHOSTUNREACH     Invalid address for IP_MULTICAST_IF.
268
269
270       EINVAL           Not a  multicast  address  for  IP_ADD_MEMBERSHIP  and
271                        IP_DROP_MEMBERSHIP.
272
273
274       EADDRNOTAVAIL    Bad   interface   address  for  IP_ADD_MEMBERSHIP  and
275                        IP_DROP_MEMBERSHIP.
276
277
278       EADDRINUSE       Address already joined for IP_ADD_MEMBERSHIP.
279
280
281       ENOENT           Address not joined for IP_DROP_MEMBERSHIP.
282
283
284       EPERM            No permissions.
285
286
287       EACCES           Permission denied.
288
289
290       EINVAL           The specified  option  is  invalid  at  the  specified
291                        socket level, or the socket has been shut down.
292
293

ATTRIBUTES

295       See attributes(5) for descriptions of the following attributes:
296
297
298
299
300       ┌─────────────────────────────┬─────────────────────────────┐
301       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
302       ├─────────────────────────────┼─────────────────────────────┤
303       │MT-Level                     │Safe                         │
304       └─────────────────────────────┴─────────────────────────────┘
305

SEE ALSO

307       ndd(1M),   close(2),   ioctl(2),  read(2),  bind(3SOCKET),  getprotoby‐
308       name(3SOCKET),    recv(3SOCKET),     recvmsg(3XNET),     send(3SOCKET),
309       socket(3SOCKET),  socket.h(3HEAD),  attributes(5),  zones(5),  tcp(7P),
310       udp(7P)
311
312
313       Solaris Tunable Parameters Reference Manual
314
315
316
317SunOS 5.11                        27 Jan 2009              getsockopt(3SOCKET)
Impressum