man2/getsockopt.2

   1 .\" Copyright (c) 1983, 1991 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" SPDX-License-Identifier: BSD-4-Clause-UC
   5 .\"
   6 .\"     $Id: getsockopt.2,v 1.1 1999/05/24 14:57:04 freitag Exp $
   7 .\"
   8 .\" Modified Sat Jul 24 16:19:32 1993 by Rik Faith (faith@cs.unc.edu)
   9 .\" Modified Mon Apr 22 02:29:06 1996 by Martin Schulze (joey@infodrom.north.de)
  10 .\" Modified Tue Aug 27 10:52:51 1996 by Andries Brouwer (aeb@cwi.nl)
  11 .\" Modified Thu Jan 23 13:29:34 1997 by Andries Brouwer (aeb@cwi.nl)
  12 .\" Modified Sun Mar 28 21:26:46 1999 by Andries Brouwer (aeb@cwi.nl)
  13 .\" Modified 1999 by Andi Kleen <ak@muc.de>.
  14 .\"     Removed most stuff because it is in socket.7 now.
  15 .\"
  16 .TH GETSOCKOPT 2 2021-03-22 "Linux" "Linux Programmer's Manual"
  17 .SH NAME
  18 getsockopt, setsockopt \- get and set options on sockets
  19 .SH LIBRARY
  20 Standard C library
  21 .RI ( libc ", " \-lc )
  22 .SH SYNOPSIS
  23 .nf
  24 .B #include <sys/socket.h>
  25 .PP
  26 .BI "int getsockopt(int " sockfd ", int " level ", int " optname ,
  27 .BI "               void *restrict " optval ", socklen_t *restrict " optlen );
  28 .BI "int setsockopt(int " sockfd ", int " level ", int " optname ,
  29 .BI "               const void *" optval ", socklen_t " optlen );
  30 .fi
  31 .SH DESCRIPTION
  32 .BR getsockopt ()
  33 and
  34 .BR setsockopt ()
  35 manipulate options for the socket referred to by the file descriptor
  36 .IR sockfd .
  37 Options may exist at multiple
  38 protocol levels; they are always present at the uppermost
  39 socket level.
  40 .PP
  41 When manipulating socket options, the level at which the
  42 option resides and the name of the option must be specified.
  43 To manipulate options at the sockets API level,
  44 .I level
  45 is specified as
  46 .BR SOL_SOCKET .
  47 To manipulate options at any
  48 other level the protocol number of the appropriate protocol
  49 controlling the option is supplied.
  50 For example,
  51 to indicate that an option is to be interpreted by the
  52 .B TCP
  53 protocol,
  54 .I level
  55 should be set to the protocol number of
  56 .BR TCP ;
  57 see
  58 .BR getprotoent (3).
  59 .PP
  60 The arguments
  61 .I optval
  62 and
  63 .I optlen
  64 are used to access option values for
  65 .BR setsockopt ().
  66 For
  67 .BR getsockopt ()
  68 they identify a buffer in which the value for the
  69 requested option(s) are to be returned.
  70 For
  71 .BR getsockopt (),
  72 .I optlen
  73 is a value-result argument, initially containing the
  74 size of the buffer pointed to by
  75 .IR optval ,
  76 and modified on return to indicate the actual size of
  77 the value returned.
  78 If no option value is to be supplied or returned,
  79 .I optval
  80 may be NULL.
  81 .PP
  82 .I Optname
  83 and any specified options are passed uninterpreted to the appropriate
  84 protocol module for interpretation.
  85 The include file
  86 .I <sys/socket.h>
  87 contains definitions for socket level options, described below.
  88 Options at
  89 other protocol levels vary in format and name; consult the appropriate
  90 entries in section 4 of the manual.
  91 .PP
  92 Most socket-level options utilize an
  93 .I int
  94 argument for
  95 .IR optval .
  96 For
  97 .BR setsockopt (),
  98 the argument should be nonzero to enable a boolean option, or zero if the
  99 option is to be disabled.
 100 .PP
 101 For a description of the available socket options see
 102 .BR socket (7)
 103 and the appropriate protocol man pages.
 104 .SH RETURN VALUE
 105 On success, zero is returned for the standard options.
 106 On error, \-1 is returned, and
 107 .I errno
 108 is set to indicate the error.
 109 .PP
 110 Netfilter allows the programmer
 111 to define custom socket options with associated handlers; for such
 112 options, the return value on success is the value returned by the handler.
 113 .SH ERRORS
 114 .TP
 115 .B EBADF
 116 The argument
 117 .I sockfd
 118 is not a valid file descriptor.
 119 .TP
 120 .B EFAULT
 121 The address pointed to by
 122 .I optval
 123 is not in a valid part of the process address space.
 124 For
 125 .BR getsockopt (),
 126 this error may also be returned if
 127 .I optlen
 128 is not in a valid part of the process address space.
 129 .TP
 130 .B EINVAL
 131 .I optlen
 132 invalid in
 133 .BR setsockopt ().
 134 In some cases this error can also occur for an invalid value in
 135 .I optval
 136 (e.g., for the
 137 .B IP_ADD_MEMBERSHIP
 138 option described in
 139 .BR ip (7)).
 140 .TP
 141 .B ENOPROTOOPT
 142 The option is unknown at the level indicated.
 143 .TP
 144 .B ENOTSOCK
 145 The file descriptor
 146 .I sockfd
 147 does not refer to a socket.
 148 .SH STANDARDS
 149 POSIX.1-2001, POSIX.1-2008,
 150 SVr4, 4.4BSD (these system calls first appeared in 4.2BSD).
 151 .\" SVr4 documents additional ENOMEM and ENOSR error codes, but does
 152 .\" not document the
 153 .\" .BR SO_SNDLOWAT ", " SO_RCVLOWAT ", " SO_SNDTIMEO ", " SO_RCVTIMEO
 154 .\" options
 155 .SH NOTES
 156 For background on the
 157 .I socklen_t
 158 type, see
 159 .BR accept (2).
 160 .SH BUGS
 161 Several of the socket options should be handled at lower levels of the
 162 system.
 163 .SH SEE ALSO
 164 .BR ioctl (2),
 165 .BR socket (2),
 166 .BR getprotoent (3),
 167 .BR protocols (5),
 168 .BR ip (7),
 169 .BR packet (7),
 170 .BR socket (7),
 171 .BR tcp (7),
 172 .BR udp (7),
 173 .BR unix (7)