sockopt(9) [netbsd man page]
SOCKOPT(9) BSD 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 */ 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 buf- fer 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 sockpt 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. BSD
September 4, 2009 BSD
Check Out this Related Man Page
SOCKET(9) BSD Kernel Developer's Manual SOCKET(9) NAME
socket -- kernel socket interface SYNOPSIS
#include <sys/socket.h> #include <sys/socketvar.h> int sobind(struct socket *so, struct sockaddr *nam, struct thread *td); void soclose(struct socket *so); int soconnect(struct socket *so, struct sockaddr *nam, struct thread *td); int socreate(int dom, struct socket **aso, int type, int proto, struct ucred *cred, struct thread *td); int sogetopt(struct socket *so, struct sockopt *sopt); int soreceive(struct socket *so, struct sockaddr **psa, struct uio *uio, struct mbuf **mp0, struct mbuf **controlp, int *flagsp); int sosetopt(struct socket *so, struct sockopt *sopt); int sosend(struct socket *so, struct sockaddr *addr, struct uio *uio, struct mbuf *top, struct mbuf *control, int flags, struct thread *td); int soshutdown(struct socket *so, int how); DESCRIPTION
The kernel socket programming interface permits in-kernel consumers to interact with local and network socket objects in a manner similar to that permitted using the socket(2) user API. These interfaces are appropriate for use by distributed file systems and other network-aware kernel services. While the user API operates on file descriptors, the kernel interfaces operate directly on struct socket pointers. Except where otherwise indicated, socket functions may sleep, and are not appropriate for use in an ithread(9) context or while holding non- sleepable kernel locks. Creating and Destroying Sockets A new socket may be created using socreate(). As with socket(2), arguments specify the requested domain, type, and protocol via dom, type, and proto. The socket is returned via aso on success. In addition, the credential used to authorize operations associated with the socket will be passed via cred (and will be cached for the lifetime of the socket), and the thread performing the operation via td. Warning: autho- rization of the socket creation operation will be performed using the thread credential for some protocols (such as raw sockets). Sockets may be closed and freed using soclose(), which has similar semantics to close(2). Connections and Addresses The sobind() function is equivalent to the bind(2) system call, and binds the socket so to the address nam. The operation would be autho- rized using the credential on thread td. The soconnect() function is equivalent to the connect(2) system call, and initiates a connection on the socket so to the address nam. The operation will be authorized using the credential on thread td. Unlike the user system call, soconnect() returns immediately; the caller may msleep(9) on so->so_timeo while holding the socket mutex and waiting for the SS_ISCONNECTING flag to clear or so->so_error to become non- zero. If soconnect() fails, the caller must manually clear the SS_ISCONNECTING flag. The soshutdown() function is equivalent to the shutdown(2) system call, and causes part or all of a connection on a socket to be closed down. Socket Options The sogetopt() function is equivalent to the getsockopt(2) system call, and retrieves a socket option on socket so. The sosetopt() function is equivalent to the setsockopt(2) system call, and sets a socket option on socket so. The second argument in both sogetopt() and sosetopt() is the sopt pointer to a struct sopt describing the socket option operation. The call- er-allocated structure must be zeroed, and then have its fields initialized to specify socket option operation arguments: sopt_dir Set to SOPT_SET or SOPT_GET depending on whether this is a get or set operation. sopt_level Specify the level in the network stack the operation is targeted at; for example, SOL_SOCKET. sopt_name Specify the name of the socket option to set. sopt_val Kernel space pointer to the argument value for the socket option. sopt_valsize Size of the argument value in bytes. Socket I/O The soreceive() function is equivalent to the recvmsg(2) system call, and attempts to receive bytes of data from the socket so, optionally blocking awaiting for data if none is ready to read. Data may be retrieved directly to kernel or user memory via the uio argument, or as an mbuf chain returned to the caller via mp0, avoiding a data copy. Only one of the uio or mp0 pointers may be non-NULL. The caller may optionally retrieve a socket address on a protocol with the PR_ADDR capability by providing storage via non-NULL psa argument. The caller may optionally retrieve control data mbufs via a non-NULL controlp argument. Optional flags may be passed to soreceive() via a non-NULL flagsp argument, and use the same flag name space as the recvmsg(2) system call. The sosend() function is equivalent to the sendmsg(2) system call, and attempts to send bytes of data via the socket so, optionally blocking if data cannot be immediately sent. Data may be sent directly from kernel or user memory via the uio argument, or as an mbuf chain via top, avoiding a data copy. Only one of the uio or top pointers may be non-NULL. An optional destination address may be specified via a non-NULL addr argument, which may result in an implicit connect if supported by the protocol. The caller may optionally send control data mbufs via a non-NULL control argument. Flags may be passed to sosend() using the flags argument, and use the same flag name space as the sendmsg(2) sys- tem call. Kernel callers running in ithread(9) context, or with a mutex held, will wish to use non-blocking sockets and pass the MSG_DONTWAIT flag in order to prevent these functions from sleeping. SEE ALSO
bind(2), close(2), connect(2), getsockopt(2), recv(2), send(2), setsockopt(2), shutdown(2), socket(2), ng_ksocket(4), ithread(9), msleep(9), ucred(9) HISTORY
The socket(2) system call appeared in 4.2BSD. This manual page was introduced in FreeBSD 7.0. AUTHORS
This manual page was written by Robert Watson. BUGS
The use of explicitly passed credentials, credentials hung from explicitly passed threads, the credential on curthread, and the cached cre- dential from socket creation time is inconsistent, and may lead to unexpected behaviour. It is possible that several of the td arguments should be cred arguments, or simply not be present at all. The caller may need to manually clear SS_ISCONNECTING if soconnect() returns an error. The MSG_DONTWAIT flag is not implemented for sosend(), and may not always work with soreceive() when zero copy sockets are enabled. This manual page does not describe how to register socket upcalls or monitor a socket for readability/writability without using blocking I/O. The soref() and sorele() functions are not described, and in most cases should not be used, due to confusing and potentially incorrect inter- actions when sorele() is last called after soclose(). BSD
December 14, 2006 BSD