NAME
sockopt_init,
sockopt_destroy,
sockopt_get,
sockopt_getint,
sockopt_set,
sockopt_setint —
socket options handling
SYNOPSIS
#include <sys/socketvar.h>
void
sockopt_init(
struct
sockopt *sopt,
int
level,
int name,
size_t size);
void
sockopt_destroy(
struct
sockopt *sopt);
int
sockopt_get(
struct
sockopt *sopt,
void
*value,
size_t size);
int
sockopt_getint(
struct
sockopt *sopt,
int
*value);
int
sockopt_set(
struct
sockopt *sopt,
const void
*value,
size_t size);
int
sockopt_setint(
struct
sockopt *sopt,
int
value);
DESCRIPTION
The
sockopt structure is used to pass a socket option and
associated value:
struct sockopt {
int sopt_level; /* option level */
int sopt_name; /* option name */
size_t sopt_size; /* data length */
size_t sopt_retsize; /* returned data length */
void * sopt_data; /* data pointer */
uint8_t sopt_buf[sizeof(int)]; /* internal storage */
};
The internal storage is used for the common case of values up to integer size so
that memory allocation is not required and sopt_data will point to this in
that case.
Rather than provide accessor functions, the
sockopt
structure is public and the contents are expected to be internally consistent,
but the normal practice would be to use the appropriate methods for storage
and retrieval of values where a known datatype is expected, as the size will
be verified.
Note: a sockopt structure may only be used for a single level/name/size
combination. If the structure is to be re-used, it must be destroyed and
re-initialized with the new values.
OPTIONS
-
-
- options
DIAGNOSTIC
- Kernels compiled with the
DIAGNOSTIC
option will perform basic sanity checks
on socket options operations.
FUNCTIONS
-
-
- sockopt_init(sopt,
level, name,
size)
- Initialise sockopt storage. If size
is given, sockopt_init() will arrange for sopt_data to
point to a buffer of size bytes for the sockopt
value. Where memory needs to be allocated to satisfy this,
sockopt_init() may sleep.
-
-
- sockopt_destroy(sopt)
- Destroy sockopt storage, releasing any allocated
memory.
-
-
- sockopt_get(sopt,
value, size)
- Copy out sockopt value. Will return
EINVAL
if an incorrect data size is given.
-
-
- sockopt_getint(sopt,
value)
- Common case of get sockopt integer value. Will return
EINVAL
if sockopt does not contain an integer
sized value.
-
-
- sockopt_set(sopt,
value, size)
- Copy in sockopt value. The sockopt structure must contain a
data field of size bytes or be previously unset, in
which case a data buffer may be allocated using
kmem_alloc(9) with the
KM_NOSLEEP
flag which may cause
sockopt_set() to return ENOMEM
.
Note: If you need to use sockopt_set() in a context where
memory allocation may be required and you do not wish to contemplate
failure, the sockopt structure can be initialised in a more suitable
context using sockopt_init() which will not fail.
-
-
- sockopt_setint(sopt,
value)
- Common case of set sockopt integer value. The sockopt
structure must contain an int sized data field or be previously unset, in
which case the data pointer will be set to the internal storage.
CODE REFERENCES
The function prototypes and sockopt structure are defined in the
sys/sys/socketvar.h header file, and the socket options
implementation is in
sys/kern/uipc_socket.c.
SEE ALSO
errno(2),
kmem(9)
HISTORY
The socket options KPI was inspired by a similar KPI in
FreeBSD and first appeared in
NetBSD
5.0.