share/man/man9/sockopt.9

   1 .\"     $NetBSD: sockopt.9,v 1.6 2009/08/03 19:57:40 rmind Exp $
   2 .\"
   3 .\" Copyright (c) 2008 Iain Hibbert
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  18 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  20 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  21 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  22 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  23 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  24 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25 .\"
  26 .Dd September 4, 2009
  27 .Dt SOCKOPT 9
  28 .Os
  29 .Sh NAME
  30 .Nm sockopt_init ,
  31 .Nm sockopt_destroy ,
  32 .Nm sockopt_get ,
  33 .Nm sockopt_getint
  34 .Nm sockopt_set ,
  35 .Nm sockopt_setint ,
  36 .Nd socket options handling
  37 .Sh SYNOPSIS
  38 .In sys/socketvar.h
  39 .Ft void
  40 .Fn sockopt_init "struct sockopt *sopt" "int level" "int name" "size_t size"
  41 .Ft void
  42 .Fn sockopt_destroy "struct sockopt *sopt"
  43 .Ft int
  44 .Fn sockopt_get "struct sockopt *sopt" "void *value" "size_t size"
  45 .Ft int
  46 .Fn sockopt_getint "struct sockopt *sopt" "int *value"
  47 .Ft int
  48 .Fn sockopt_set "struct sockopt *sopt" "const void *value" "size_t size"
  49 .Ft int
  50 .Fn sockopt_setint "struct sockopt *sopt" "int value"
  51 .Sh DESCRIPTION
  52 The
  53 .Ft sockopt
  54 structure is used to pass a socket option and associated value:
  55 .Bd -literal -offset indent
  56 struct sockopt {
  57         int             sopt_level;             /* option level */
  58         int             sopt_name;              /* option name */
  59         size_t          sopt_size;              /* data length */
  60         void *          sopt_data;              /* data pointer */
  61         uint8_t         sopt_buf[sizeof(int)];  /* internal storage */
  62 };
  63 .Ed
  64 .Pp
  65 The internal storage is used for the common case of values up to integer
  66 size so that memory allocation is not required and sopt_data will point
  67 to this in that case.
  68 .Pp
  69 Rather than provide accessor functions, the
  70 .Ft sockopt
  71 structure is public and the contents are expected to be internally
  72 consistent, but the normal practice would be to use the appropriate methods
  73 for storage and retrieval of values where a known datatype is expected,
  74 as the size will be verified.
  75 .Pp
  76 Note: a sockopt structure may only be used for a single level/name/size
  77 combination.
  78 If the structure is to be re-used, it must be destroyed and re-initialized
  79 with the new values.
  80 .Sh OPTIONS
  81 .Bl -tag -width xxxx
  82 .It Cd "options DIAGNOSTIC"
  83 Kernels compiled with the
  84 .Dv DIAGNOSTIC
  85 option will perform basic sanity checks on socket options operations.
  86 .El
  87 .Sh FUNCTIONS
  88 .Bl -tag -width xxxx
  89 .It Fn sockopt_init "sopt" "level" "name" "size"
  90 Initialise sockopt storage.
  91 If
  92 .Ar size
  93 is given,
  94 .Fn sockopt_init
  95 will arrange for sopt_data to point to a buffer of
  96 .Ar size
  97 bytes for the sockopt value.
  98 Where memory needs to be allocated to satisfy this,
  99 .Fn sockopt_init
 100 may sleep.
 101 .It Fn sockopt_destroy "sopt"
 102 Destroy sockopt storage, releasing any allocated memory.
 103 .It Fn sockopt_get "sopt" "value" "size"
 104 Copy out sockopt value.
 105 Will return
 106 .Er EINVAL
 107 if an incorrect data size is given.
 108 .It Fn sockopt_getint "sopt" "value"
 109 Common case of get sockopt integer value.
 110 Will return
 111 .Er EINVAL
 112 if sockopt does not contain an integer sized value.
 113 .It Fn sockopt_set "sopt" "value" "size"
 114 Copy in sockopt value.
 115 The sockopt structure must contain a data field of
 116 .Ar size
 117 bytes or be previously unset, in which case a data buffer may be
 118 allocated using
 119 .Xr kmem_alloc 9
 120 with the
 121 .Dv KM_NOSLEEP
 122 flag which may cause
 123 .Fn sockopt_set
 124 to return
 125 .Er ENOMEM .
 126 .Pp
 127 Note: If you need to use
 128 .Fn sockopt_set
 129 in a context where memory allocation may be required and you do not wish to
 130 contemplate failure, the sockopt structure can be initialised in a more suitable
 131 context using
 132 .Fn sockopt_init
 133 which will not fail.
 134 .It Fn sockopt_setint "sopt" "value"
 135 Common case of set sockopt integer value.
 136 The sockpt structure must contain an int sized data field or be previously
 137 unset, in which case the data pointer will be set to the internal storage.
 138 .El
 139 .Sh CODE REFERENCES
 140 This section describes places within the
 141 .Nx
 142 source tree where code implementing socket options can be found.
 143 All pathnames are relative to
 144 .Pa /usr/src .
 145 .Pp
 146 The function prototypes and sockopt structure are defined in the
 147 .Pa sys/sys/socketvar.h
 148 header file, and the socket options implementation is in
 149 .Pa sys/kern/uipc_socket.c .
 150 .Sh SEE ALSO
 151 .Xr errno 2 ,
 152 .Xr kmem 9
 153 .Sh HISTORY
 154 The socket options KPI was inspired by a similar KPI in
 155 .Fx
 156 and
 157 first appeared in
 158 .Nx 5.0 .