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 (date) "Linux man-pages (unreleased)"
  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 .P
  26 .BI "int getsockopt(int " sockfd ", int " level ", int " optname ,
  27 .BI "               void " optval "[restrict *." optlen ],
  28 .BI "               socklen_t *restrict " optlen );
  29 .BI "int setsockopt(int " sockfd ", int " level ", int " optname ,
  30 .BI "               const void " optval [. optlen ],
  31 .BI "               socklen_t " optlen );
  32 .fi
  33 .SH DESCRIPTION
  34 .BR getsockopt ()
  35 and
  36 .BR setsockopt ()
  37 manipulate options for the socket referred to by the file descriptor
  38 .IR sockfd .
  39 Options may exist at multiple
  40 protocol levels; they are always present at the uppermost
  41 socket level.
  42 .P
  43 When manipulating socket options, the level at which the
  44 option resides and the name of the option must be specified.
  45 To manipulate options at the sockets API level,
  46 .I level
  47 is specified as
  48 .BR SOL_SOCKET .
  49 To manipulate options at any
  50 other level the protocol number of the appropriate protocol
  51 controlling the option is supplied.
  52 For example,
  53 to indicate that an option is to be interpreted by the
  54 .B TCP
  55 protocol,
  56 .I level
  57 should be set to the protocol number of
  58 .BR TCP ;
  59 see
  60 .BR getprotoent (3).
  61 .P
  62 The arguments
  63 .I optval
  64 and
  65 .I optlen
  66 are used to access option values for
  67 .BR setsockopt ().
  68 For
  69 .BR getsockopt ()
  70 they identify a buffer in which the value for the
  71 requested option(s) are to be returned.
  72 For
  73 .BR getsockopt (),
  74 .I optlen
  75 is a value-result argument, initially containing the
  76 size of the buffer pointed to by
  77 .IR optval ,
  78 and modified on return to indicate the actual size of
  79 the value returned.
  80 If no option value is to be supplied or returned,
  81 .I optval
  82 may be NULL.
  83 .P
  84 .I Optname
  85 and any specified options are passed uninterpreted to the appropriate
  86 protocol module for interpretation.
  87 The include file
  88 .I <sys/socket.h>
  89 contains definitions for socket level options, described below.
  90 Options at
  91 other protocol levels vary in format and name; consult the appropriate
  92 entries in section 4 of the manual.
  93 .P
  94 Most socket-level options utilize an
  95 .I int
  96 argument for
  97 .IR optval .
  98 For
  99 .BR setsockopt (),
 100 the argument should be nonzero to enable a boolean option, or zero if the
 101 option is to be disabled.
 102 .P
 103 For a description of the available socket options see
 104 .BR socket (7)
 105 and the appropriate protocol man pages.
 106 .SH RETURN VALUE
 107 On success, zero is returned for the standard options.
 108 On error, \-1 is returned, and
 109 .I errno
 110 is set to indicate the error.
 111 .P
 112 Netfilter allows the programmer
 113 to define custom socket options with associated handlers; for such
 114 options, the return value on success is the value returned by the handler.
 115 .SH ERRORS
 116 .TP
 117 .B EBADF
 118 The argument
 119 .I sockfd
 120 is not a valid file descriptor.
 121 .TP
 122 .B EFAULT
 123 The address pointed to by
 124 .I optval
 125 is not in a valid part of the process address space.
 126 For
 127 .BR getsockopt (),
 128 this error may also be returned if
 129 .I optlen
 130 is not in a valid part of the process address space.
 131 .TP
 132 .B EINVAL
 133 .I optlen
 134 invalid in
 135 .BR setsockopt ().
 136 In some cases this error can also occur for an invalid value in
 137 .I optval
 138 (e.g., for the
 139 .B IP_ADD_MEMBERSHIP
 140 option described in
 141 .BR ip (7)).
 142 .TP
 143 .B ENOPROTOOPT
 144 The option is unknown at the level indicated.
 145 .TP
 146 .B ENOTSOCK
 147 The file descriptor
 148 .I sockfd
 149 does not refer to a socket.
 150 .SH STANDARDS
 151 POSIX.1-2008.
 152 .SH HISTORY
 153 POSIX.1-2001,
 154 SVr4, 4.4BSD (first appeared in 4.2BSD).
 155 .\" SVr4 documents additional ENOMEM and ENOSR error codes, but does
 156 .\" not document the
 157 .\" .BR SO_SNDLOWAT ", " SO_RCVLOWAT ", " SO_SNDTIMEO ", " SO_RCVTIMEO
 158 .\" options
 159 .SH BUGS
 160 Several of the socket options should be handled at lower levels of the
 161 system.
 162 .SH SEE ALSO
 163 .BR ioctl (2),
 164 .BR socket (2),
 165 .BR getprotoent (3),
 166 .BR protocols (5),
 167 .BR ip (7),
 168 .BR packet (7),
 169 .BR socket (7),
 170 .BR tcp (7),
 171 .BR udp (7),
 172 .BR unix (7)