SOCKOPT(9)

SOCKOPT(9) | Kernel Developer's Manual | SOCKOPT(9)

# 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.

January 3, 2018 | NetBSD 9.5