Index: stable/12/share/man/man9/EVENTHANDLER.9 =================================================================== --- stable/12/share/man/man9/EVENTHANDLER.9 (revision 366091) +++ stable/12/share/man/man9/EVENTHANDLER.9 (revision 366092) @@ -1,424 +1,424 @@ .\" Copyright (c) 2004 Joseph Koshy .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" $FreeBSD$ .\" .Dd October 21, 2018 .Dt EVENTHANDLER 9 .Os .Sh NAME .Nm EVENTHANDLER .Nd kernel event handling functions .Sh SYNOPSIS .In sys/eventhandler.h .Fn EVENTHANDLER_DECLARE name type .Fn EVENTHANDLER_DEFINE name func arg priority .Fn EVENTHANDLER_INVOKE name ... .Ft eventhandler_tag .Fn EVENTHANDLER_REGISTER name func arg priority .Fn EVENTHANDLER_DEREGISTER name tag .Fn EVENTHANDLER_DEREGISTER_NOWAIT name tag .Fn EVENTHANDLER_LIST_DECLARE name .Fn EVENTHANDLER_LIST_DEFINE name .Fn EVENTHANDLER_DIRECT_INVOKE name .Ft eventhandler_tag .Fo eventhandler_register .Fa "struct eventhandler_list *list" .Fa "const char *name" .Fa "void *func" .Fa "void *arg" .Fa "int priority" .Fc .Ft void .Fo eventhandler_deregister .Fa "struct eventhandler_list *list" .Fa "eventhandler_tag tag" .Fc .Ft void .Fo eventhandler_deregister_nowait .Fa "struct eventhandler_list *list" .Fa "eventhandler_tag tag" .Fc .Ft "struct eventhandler_list *" .Fn eventhandler_find_list "const char *name" .Ft void .Fn eventhandler_prune_list "struct eventhandler_list *list" .Sh DESCRIPTION The .Nm mechanism provides a way for kernel subsystems to register interest in kernel events and have their callback functions invoked when these events occur. .Pp Callback functions are invoked in order of priority. The relative priority of each callback among other callbacks associated with an event is given by argument .Fa priority , which is an integer ranging from .Dv EVENTHANDLER_PRI_FIRST (highest priority), to .Dv EVENTHANDLER_PRI_LAST (lowest priority). The symbol .Dv EVENTHANDLER_PRI_ANY may be used if the handler does not have a specific priority associated with it. .Pp The normal way to use this subsystem is via the macro interface. For events that are high frequency it is suggested that you additionally use .Fn EVENTHANDLER_LIST_DEFINE so that the event handlers can be invoked directly using .Fn EVENTHANDLER_DIRECT_INVOKE (see below). This saves the invoker from having to do a locked traversal of a global list of event handler lists. .Bl -tag -width indent .It Fn EVENTHANDLER_DECLARE This macro declares an event handler named by argument .Fa name with callback functions of type .Fa type . .It Fn EVENTHANDLER_DEFINE This macro uses .Xr SYSINIT 9 to register a callback function .Fa func with event handler .Fa name . When invoked, function .Fa func will be invoked with argument .Fa arg as its first parameter along with any additional parameters passed in via macro .Fn EVENTHANDLER_INVOKE (see below). .It Fn EVENTHANDLER_REGISTER This macro registers a callback function .Fa func with event handler .Fa name . When invoked, function .Fa func will be invoked with argument .Fa arg as its first parameter along with any additional parameters passed in via macro .Fn EVENTHANDLER_INVOKE (see below). If registration is successful, .Fn EVENTHANDLER_REGISTER returns a cookie of type .Vt eventhandler_tag . .It Fn EVENTHANDLER_DEREGISTER This macro removes a previously registered callback associated with tag .Fa tag from the event handler named by argument .Fa name . It waits until no threads are running handlers for this event before returning, making it safe to unload a module immediately upon return from this function. .It Fn EVENTHANDLER_DEREGISTER_NOWAIT This macro removes a previously registered callback associated with tag .Fa tag from the event handler named by argument .Fa name . Upon return, one or more threads could still be running the removed function(s), but no new calls will be made. To remove a handler function from within that function, use this version of deregister, to avoid a deadlock. .It Fn EVENTHANDLER_INVOKE This macro is used to invoke all the callbacks associated with event handler .Fa name . This macro is a variadic one. Additional arguments to the macro after the .Fa name parameter are passed as the second and subsequent arguments to each registered callback function. .It Fn EVENTHANDLER_LIST_DEFINE This macro defines a reference to an event handler list named by argument .Fa name . It uses .Xr SYSINIT 9 to initialize the reference and the eventhandler list. .It Fn EVENTHANDLER_LIST_DECLARE This macro declares an event handler list named by argument .Fa name . This is only needed for users of .Fn EVENTHANDLER_DIRECT_INVOKE which are not in the same compilation unit of that list's definition. .It Fn EVENTHANDLER_DIRECT_INVOKE This macro invokes the event handlers registered for the list named by argument .Fa name . This macro can only be used if the list was defined with .Fn EVENTHANDLER_LIST_DEFINE . The macro is variadic with the same semantics as .Fn EVENTHANDLER_INVOKE . .El .Pp The macros are implemented using the following functions: .Bl -tag -width indent .It Fn eventhandler_register The .Fn eventhandler_register function is used to register a callback with a given event. The arguments expected by this function are: .Bl -tag -width ".Fa priority" .It Fa list A pointer to an existing event handler list, or .Dv NULL . If .Fa list is .Dv NULL , the event handler list corresponding to argument .Fa name is used. .It Fa name The name of the event handler list. .It Fa func A pointer to a callback function. Argument .Fa arg is passed to the callback function .Fa func as its first argument when it is invoked. .It Fa priority The relative priority of this callback among all the callbacks registered for this event. Valid values are those in the range .Dv EVENTHANDLER_PRI_FIRST to .Dv EVENTHANDLER_PRI_LAST . .El .Pp The .Fn eventhandler_register function returns a .Fa tag that can later be used with .Fn eventhandler_deregister to remove the particular callback function. .It Fn eventhandler_deregister The .Fn eventhandler_deregister function removes the callback associated with tag .Fa tag from the event handler list pointed to by .Fa list . If .Fa tag is .Va NULL , all callback functions for the event are removed. This function will not return until all threads have exited from the removed handler callback function(s). This function is not safe to call from inside an event handler callback. .It Fn eventhandler_deregister_nowait The .Fn eventhandler_deregister function removes the callback associated with tag .Fa tag from the event handler list pointed to by .Fa list . This function is safe to call from inside an event handler callback. .It Fn eventhandler_find_list The .Fn eventhandler_find_list function returns a pointer to event handler list structure corresponding to event .Fa name . .It Fn eventhandler_prune_list The .Fn eventhandler_prune_list function removes all deregistered callbacks from the event list .Fa list . .El .Ss Kernel Event Handlers The following event handlers are present in the kernel: .Bl -tag -width indent .It Vt acpi_sleep_event Callbacks invoked when the system is being sent to sleep. .It Vt acpi_wakeup_event Callbacks invoked when the system is being woken up. .It Vt app_coredump_start Callbacks invoked at start of application core dump. .It Vt app_coredump_progress Callbacks invoked during progress of application core dump. .It Vt app_coredump_finish Callbacks invoked at finish of application core dump. .It Vt app_coredump_error Callbacks invoked on error of application core dump. .It Vt bpf_track Callbacks invoked when a BPF listener attaches to/detaches from network interface. .It Vt cpufreq_levels_changed Callback invoked when cpu frequency levels have changed. .It Vt cpufreq_post_change Callback invoked after cpu frequency has changed. .It Vt cpufreq_pre_change Callback invoked before cpu frequency has changed. .It Vt dcons_poll Callback invoked to poll for dcons changes. .It Vt device_attach Callback invoked after a device has attached. .It Vt device_detach Callbacks invoked before and after a device has detached. .It Vt dev_clone Callbacks invoked when a new entry is created under .Pa /dev . .It Vt group_attach_event Callback invoked when an interfance has been added to an interface group. .It Vt group_change_event Callback invoked when an change has been made to an interface group. .It Vt group_detach_event Callback invoked when an interfance has been removed from an interface group. .It Vt ifaddr_event Callbacks invoked when an address is set up on a network interface. .It Vt ifaddr_event_ext -Callback invoked when an address has been added or removed from an interface. +Callback invoked when an address has been added or removed from an interface. .It Vt if_clone_event Callbacks invoked when an interface is cloned. .It Vt iflladdr_event Callback invoked when an if link layer address event has happened. .It Vt ifnet_arrival_event Callbacks invoked when a new network interface appears. .It Vt ifnet_departure_event Callbacks invoked when a network interface is taken down. .It Vt ifnet_link_event Callback invoked when an interfance link event has happened. .It Vt kld_load Callbacks invoked after a linker file has been loaded. .It Vt kld_unload Callbacks invoked after a linker file has been successfully unloaded. .It Vt kld_unload_try Callbacks invoked before a linker file is about to be unloaded. These callbacks may be used to return an error and prevent the unload from proceeding. .It Vt lle_event Callback invoked when an link layer event has happened. .It Vt nmbclusters_change Callback invoked when the number of mbuf clusters has changed. .It Vt nmbufs_change Callback invoked when the number of mbufs has changed. .It Vt maxsockets_change Callback invoked when the maximum number of sockets has changed. .It Vt mountroot Callback invoked when root has been mounted. .It Vt power_profile_change Callbacks invoked when the power profile of the system changes. .It Vt power_resume Callback invoked when the system has resumed. .It Vt power_suspend Callback invoked just before the system is suspended. .It Vt process_ctor Callback invoked when a process is created. .It Vt process_dtor Callback invoked when a process is destroyed. .It Vt process_exec Callbacks invoked when a process performs an .Fn exec operation. .It Vt process_exit Callbacks invoked when a process exits. .It Vt process_fini Callback invoked when a process memory is destroyed. This is never called. .It Vt process_fork Callbacks invoked when a process forks a child. .It Vt process_init Callback invoked when a process is initialized. .It Vt random_adaptor_attach Callback invoked when a new random module has been loaded. .It Vt register_framebuffer Callback invoked when a new frame buffer is registered. .It Vt route_redirect_event Callback invoked when a route gets redirected to a new location. .It Vt shutdown_pre_sync Callbacks invoked at shutdown time, before file systems are synchronized. .It Vt shutdown_post_sync Callbacks invoked at shutdown time, after all file systems are synchronized. .It Vt shutdown_final Callbacks invoked just before halting the system. .It Vt tcp_offload_listen_start Callback invoked for TCP Offload to start listening for new connections. .It Vt tcp_offload_listen_stop Callback invoked ror TCP Offload to stop listening for new connections. .It Vt thread_ctor Callback invoked when a thread object is created. .It Vt thread_dtor Callback invoked when a thread object is destroyed. .It Vt thread_init Callback invoked when a thread object is initialized. .It Vt thread_fini Callback invoked when a thread object is deinitalized. .It Vt usb_dev_configured Callback invoked when a USB device is configured .It Vt unregister_framebuffer Callback invoked when a frame buffer is deregistered. .It Vt vfs_mounted Callback invoked when a file system is mounted. .It Vt vfs_unmounted Callback invoked when a file system is unmounted. .It Vt vlan_config Callback invoked when the vlan configuration has changed. .It Vt vlan_unconfig Callback invoked when a vlan is destroyed. .It Vt vm_lowmem Callbacks invoked when virtual memory is low. .It Vt watchdog_list Callbacks invoked when the system watchdog timer is reinitialized. .El .Sh RETURN VALUES The macro .Fn EVENTHANDLER_REGISTER and function .Fn eventhandler_register return a cookie of type .Vt eventhandler_tag , which may be used in a subsequent call to .Fn EVENTHANDLER_DEREGISTER or .Fn eventhandler_deregister . .Pp The .Fn eventhandler_find_list function returns a pointer to an event handler list corresponding to parameter .Fa name , or .Dv NULL if no such list was found. .Sh HISTORY The .Nm facility first appeared in .Fx 4.0 . .Sh AUTHORS This manual page was written by .An Joseph Koshy Aq Mt jkoshy@FreeBSD.org and .An Matt Joras Aq Mt mjoras@FreeBSD.org . Index: stable/12/share/man/man9/OF_node_from_xref.9 =================================================================== --- stable/12/share/man/man9/OF_node_from_xref.9 (revision 366091) +++ stable/12/share/man/man9/OF_node_from_xref.9 (revision 366092) @@ -1,100 +1,100 @@ .\" .\" Copyright (c) 2018 Oleksandr Tymoshenko .\" .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd April 9, 2018 .Dt OF_NODE_FROM_XREF 9 .Os .Sh NAME .Nm OF_node_from_xref , .Nm OF_xref_from_node .Nd convert between kernel phandle and effective phandle .Sh SYNOPSIS .In dev/ofw/ofw_bus.h .In dev/ofw/ofw_bus_subr.h .Ft phandle_t .Fn OF_node_from_xref "phandle_t xref" .Ft phandle_t .Fn OF_xref_from_node "phandle_t node" .Sh DESCRIPTION .Pp Some OpenFirmware implementations (FDT, IBM) have a concept of effective phandle or xrefs. They are used to cross-reference device tree nodes. For instance, a framebuffer controller may refer to a GPIO controller and pin that controls the backlight. In this example, the GPIO node would have a cell (32-bit integer) property with a reserved name like "phandle" or "linux,phandle" whose value uniquely identifies the node. The actual name depends on the implementation. The framebuffer node would have a property with the name described by device bindings (device-specific set of properties). It can be a cell property or a combined property with one part of it being a cell. The value of the framebuffer node's property would be the same as the value of the GPIO "phandle" property so it can be said that the framebuffer node refers to the GPIO node. The kernel uses internal logic to assign unique identifiers to the device tree nodes, and these values do not match the values of "phandle" properties. .Fn OF_node_from_xref and .Fn OF_xref_from_node are used to perform conversion between these two kinds of node -identifiers. +identifiers. .Pp .Fn OF_node_from_xref returns the kernel phandle for the effective phandle .Fa xref . If one cannot be found or the OpenFirmware implementation does not support effective phandles, the function returns the input value. .Pp .Fn OF_xref_from_xref returns the effective phandle for the kernel phandle .Fa xref . If one cannot be found or the OpenFirmware implementation does not support effective phandles, the function returns the input value. .Sh EXAMPLES .Bd -literal phandle_t panelnode, panelxref; char *model; if (OF_getencprop(node, "lcd-panel", &panelxref) <= 0) return; panelnode = OF_node_from_xref(panelxref); if (OF_getprop_alloc(hdminode, "model", (void **)&model) <= 0) return; .Ed .Sh SEE ALSO .Xr OF_device_from_xref 9 .Xr OF_device_register_xref 9 .Sh AUTHORS .An -nosplit This manual page was written by .An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org . Index: stable/12/share/man/man9/ieee80211.9 =================================================================== --- stable/12/share/man/man9/ieee80211.9 (revision 366091) +++ stable/12/share/man/man9/ieee80211.9 (revision 366092) @@ -1,718 +1,718 @@ .\" .\" Copyright (c) 2004 Bruce M. Simpson .\" Copyright (c) 2004 Darron Broad .\" Copyright (c) 2009 Sam Leffler, Errno Consulting .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd December 31, 2017 .Dt IEEE80211 9 .Os .Sh NAME .Nm IEEE80211 .Nd 802.11 network layer .Sh SYNOPSIS .In net80211/ieee80211_var.h .Ft void .Fn ieee80211_ifattach "struct ieee80211com *ic" .Ft void .Fn ieee80211_ifdetach "struct ieee80211com *ic" .Ft int .Fn ieee80211_mhz2ieee "u_int freq" "u_int flags" .Ft int .Fn ieee80211_chan2ieee "struct ieee80211com *ic" "const struct ieee80211_channel *c" .Ft u_int .Fn ieee80211_ieee2mhz "u_int chan" "u_int flags" .Ft int .Fn ieee80211_media_change "struct ifnet *ifp" .Ft void .Fn ieee80211_media_status "struct ifnet *ifp" "struct ifmediareq *imr" .Ft int .Fn ieee80211_setmode "struct ieee80211com *ic" "enum ieee80211_phymode mode" .Ft enum ieee80211_phymode .Fo ieee80211_chan2mode .Fa "const struct ieee80211_channel *chan" .Fc .Ft int .Fo ieee80211_rate2media .Fa "struct ieee80211com *ic" "int rate" "enum ieee80211_phymode mode" .Fc .Ft int .Fn ieee80211_media2rate "int mword" .Sh DESCRIPTION IEEE 802.11 device drivers are written to use the infrastructure provided by the .Nm software layer. This software provides a support framework for drivers that includes ifnet cloning, state management, and a user management API by which applications interact with 802.11 devices. Most drivers depend on the .Nm layer for protocol services but devices that off-load functionality may bypass the layer to connect directly to the device (e.g. the .Xr ndis 4 emulation support does this). .Pp A .Nm device driver implements a virtual radio API that is exported to users through network interfaces (aka vaps) that are cloned from the underlying device. These interfaces have an operating mode (station, adhoc, hostap, wds, monitor, etc.\&) that is fixed for the lifetime of the interface. Devices that can support multiple concurrent interfaces allow multiple vaps to be cloned. This enables construction of interesting applications such as an AP vap and one or more WDS vaps or multiple AP vaps, each with a different security model. The .Nm layer virtualizes most 802.11 state and coordinates vap state changes including scheduling multiple vaps. State that is not virtualized includes the current channel and WME/WMM parameters. Protocol processing is typically handled entirely in the .Nm layer with drivers responsible purely for moving data between the host and device. Similarly, .Nm handles most .Xr ioctl 2 requests without entering the driver; instead drivers are notified of state changes that require their involvement. .Pp The virtual radio interface defined by the .Nm layer means that drivers must be structured to follow specific rules. Drivers that support only a single interface at any time must still follow these rules. .Pp Most of these functions require that attachment to the stack is performed before calling. .Pp .\" The .Fn ieee80211_ifattach function attaches the wireless network interface .Fa ic to the 802.11 network stack layer. This function must be called before using any of the .Nm functions which need to store driver state across invocations. .Pp .\" The .Fn ieee80211_ifdetach function frees any .Nm structures associated with the driver, and performs Ethernet and BPF detachment on behalf of the caller. .Pp .\" The .Fn ieee80211_mhz2ieee utility function converts the frequency .Fa freq (specified in MHz) to an IEEE 802.11 channel number. The .Fa flags argument is a hint which specifies whether the frequency is in the 2GHz ISM band .Pq Vt IEEE80211_CHAN_2GHZ or the 5GHz band .Pq Vt IEEE80211_CHAN_5GHZ ; appropriate clipping of the result is then performed. .Pp .\" The .Fn ieee80211_chan2ieee function converts the channel specified in .Fa *c to an IEEE channel number for the driver .Fa ic . If the conversion would be invalid, an error message is printed to the system console. This function REQUIRES that the driver is hooked up to the .Nm subsystem. .Pp .\" The .Fn ieee80211_ieee2mhz utility function converts the IEEE channel number .Ft chan to a frequency (in MHz). The .Fa flags argument is a hint which specifies whether the frequency is in the 2GHz ISM band .Pq Vt IEEE80211_CHAN_2GHZ or the 5GHz band .Pq Vt IEEE80211_CHAN_5GHZ ; appropriate clipping of the result is then performed. .Pp .\" The .Fn ieee80211_media_status and .Fn ieee80211_media_change functions are device-independent handlers for .Vt ifmedia commands and are not intended to be called directly. .Pp .\" The .Fn ieee80211_setmode function is called from within the 802.11 stack to change the mode of the driver's PHY; it is not intended to be called directly. .Pp .\" The .Fn ieee80211_chan2mode function returns the PHY mode required for use with the channel .Fa chan . This is typically used when selecting a rate set, to be advertised in beacons, for example. .Pp .\" The .Fn ieee80211_rate2media function converts the bit rate .Fa rate (measured in units of 0.5Mbps) to an .Vt ifmedia sub-type, for the device .Fa ic running in PHY mode .Fa mode . The .Fn ieee80211_media2rate performs the reverse of this conversion, returning the bit rate (in 0.5Mbps units) corresponding to an .Vt ifmedia sub-type. . .Sh DATA STRUCTURES The virtual radio architecture splits state between a single per-device .Vt ieee80211com structure and one or more .Vt ieee80211vap structures. Drivers are expected to setup various shared state in these structures at device attach and during vap creation but otherwise should treat them as read-only. The .Vt ieee80211com structure is allocated by the .Nm layer as adjunct data to a device's .Vt ifnet ; it is accessed through the .Vt if_l2com structure member. The .Vt ieee80211vap structure is allocated by the driver in the .Dq vap create method and should be extended with any driver-private state. This technique of giving the driver control to allocate data structures is used for other .Nm data structures and should be exploited to maintain driver-private state together with public .Nm state. .Pp The other main data structures are the station, or node, table that tracks peers in the local BSS, and the channel table that defines the current set of available radio channels. Both tables are bound to the .Vt ieee80211com structure and shared by all vaps. Long-lasting references to a node are counted to guard against premature reclamation. In particular every packet sent/received holds a node reference (either explicitly for transmit or implicitly on receive). .Pp The .Vt ieee80211com and .Vt ieee80211vap structures also hold a collection of method pointers that drivers fill-in and/or override to take control of certain operations. These methods are the primary way drivers are bound to the .Nm layer and are described below. .Sh DRIVER ATTACH/DETACH Drivers attach to the .Nm layer with the .Fn ieee80211_ifattach function. The driver is expected to allocate and setup any device-private data structures before passing control. The .Vt ieee80211com structure must be pre-initialized with state required to setup the .Nm layer: .Bl -tag -width ic_channels .It Dv ic_ifp Backpointer to the physical device's ifnet. .It Dv ic_caps Device/driver capabilities; see below for a complete description. .It Dv ic_channels Table of channels the device is capable of operating on. This is initially provided by the driver but may be changed through calls that change the regulatory state. .It Dv ic_nchan Number of entries in .Dv ic_channels . .El .Pp On return from .Fn ieee80211_ifattach the driver is expected to override default callback functions in the .Vt ieee80211com structure to register it's private routines. Methods marked with a .Dq * must be provided by the driver. .Bl -tag -width ic_channels .It Dv ic_vap_create* Create a vap instance of the specified type (operating mode). Any fixed BSSID and/or MAC address is provided. Drivers that support multi-bssid operation may honor the requested BSSID or assign their own. .It Dv ic_vap_delete* Destroy a vap instance created with .Dv ic_vap_create . .It Dv ic_getradiocaps Return the list of calibrated channels for the radio. The default method returns the current list of channels (space permitting). .It Dv ic_setregdomain Process a request to change regulatory state. The routine may reject a request or constrain changes (e.g. reduce transmit power caps). The default method accepts all proposed changes. .It Dv ic_send_mgmt Send an 802.11 management frame. The default method fabricates the frame using .Nm state and passes it to the driver through the .Dv ic_raw_xmit method. .It Dv ic_raw_xmit Transmit a raw 802.11 frame. The default method drops the frame and generates a message on the console. .It Dv ic_updateslot Update hardware state after an 802.11 IFS slot time change. There is no default method; the pointer may be NULL in which case it will not be used. .It Dv ic_update_mcast Update hardware for a change in the multicast packet filter. The default method prints a console message. .It Dv ic_update_promisc Update hardware for a change in the promiscuous mode setting. The default method prints a console message. .It Dv ic_newassoc Update driver/device state for association to a new AP (in station mode) or when a new station associates (e.g. in AP mode). There is no default method; the pointer may be NULL in which case it will not be used. .It Dv ic_node_alloc Allocate and initialize a .Vt ieee80211_node structure. This method cannot sleep. The default method allocates zero'd memory using .Xr malloc 9 . Drivers should override this method to allocate extended storage for their own needs. Memory allocated by the driver must be tagged with .Dv M_80211_NODE to balance the memory allocation statistics. .It Dv ic_node_free Reclaim storage of a node allocated by .Dv ic_node_alloc . Drivers are expected to .Em interpose their own method to cleanup private state but must call through this method to allow .Nm to reclaim it's private state. .It Dv ic_node_cleanup Cleanup state in a .Vt ieee80211_node created by .Dv ic_node_alloc . This operation is distinguished from .Dv ic_node_free in that it may be called long before the node is actually reclaimed to cleanup adjunct state. This can happen, for example, when a node must not be reclaimed due to references held by packets in the transmit queue. Drivers typically interpose .Dv ic_node_cleanup instead of .Dv ic_node_free . .It Dv ic_node_age Age, and potentially reclaim, resources associated with a node. The default method ages frames on the power-save queue (in AP mode) and pending frames in the receive reorder queues (for stations using A-MPDU). .It Dv ic_node_drain Reclaim all optional resources associated with a node. This call is used to free up resources when they are in short supply. .It Dv ic_node_getrssi Return the Receive Signal Strength Indication (RSSI) in .5 dBm units for the specified node. This interface returns a subset of the information returned by .Dv ic_node_getsignal . The default method calculates a filtered average over the last ten samples passed in to .Xr ieee80211_input 9 or .Xr ieee80211_input_all 9 . .It Dv ic_node_getsignal Return the RSSI and noise floor (in .5 dBm units) for a station. The default method calculates RSSI as described above; the noise floor returned is the last value supplied to .Xr ieee80211_input 9 or .Xr ieee80211_input_all 9 . .It Dv ic_node_getmimoinfo Return MIMO radio state for a station in support of the .Dv IEEE80211_IOC_STA_INFO ioctl request. The default method returns nothing. .It Dv ic_scan_start* Prepare driver/hardware state for scanning. This callback is done in a sleepable context. .It Dv ic_scan_end* Restore driver/hardware state after scanning completes. This callback is done in a sleepable context. .It Dv ic_set_channel* Set the current radio channel using .Vt ic_curchan . This callback is done in a sleepable context. .It Dv ic_scan_curchan Start scanning on a channel. This method is called immediately after each channel change and must initiate the work to scan a channel and schedule a timer to advance to the next channel in the scan list. This callback is done in a sleepable context. The default method handles active scan work (e.g. sending ProbeRequest frames), and schedules a call to .Xr ieee80211_scan_next 9 according to the maximum dwell time for the channel. Drivers that off-load scan work to firmware typically use this method to trigger per-channel scan activity. .It Dv ic_scan_mindwell Handle reaching the minimum dwell time on a channel when scanning. This event is triggered when one or more stations have been found on a channel and the minimum dwell time has been reached. This callback is done in a sleepable context. The default method signals the scan machinery to advance to the next channel as soon as possible. Drivers can use this method to preempt further work (e.g. if scanning is handled by firmware) or ignore the request to force maximum dwell time on a channel. .It Dv ic_recv_action Process a received Action frame. The default method points to .Xr ieee80211_recv_action 9 which provides a mechanism for setting up handlers for each Action frame class. .It Dv ic_send_action Transmit an Action frame. The default method points to .Xr ieee80211_send_action 9 which provides a mechanism for setting up handlers for each Action frame class. .It Dv ic_ampdu_enable Check if transmit A-MPDU should be enabled for the specified station and AC. The default method checks a per-AC traffic rate against a per-vap threshold to decide if A-MPDU should be enabled. This method also rate-limits ADDBA requests so that requests are not made too frequently when a receiver has limited resources. .It Dv ic_addba_request Request A-MPDU transmit aggregation. The default method sets up local state and issues an ADDBA Request Action frame. Drivers may interpose this method if they need to setup private state for handling transmit A-MPDU. .It Dv ic_addb_response Process a received ADDBA Response Action frame and setup resources as needed for doing transmit A-MPDU. .It Dv ic_addb_stop Shutdown an A-MPDU transmit stream for the specified station and AC. The default method reclaims local state after sending a DelBA Action frame. .It Dv ic_bar_response Process a response to a transmitted BAR control frame. .It Dv ic_ampdu_rx_start Prepare to receive A-MPDU data from the specified station for the TID. .It Dv ic_ampdu_rx_stop Terminate receipt of A-MPDU data from the specified station for the TID. .El .Pp Once the .Nm layer is attached to a driver there are two more steps typically done to complete the work: .Bl -enum .It Setup .Dq radiotap support for capturing raw 802.11 packets that pass through the device. This is done with a call to .Xr ieee80211_radiotap_attach 9 . .It Do any final device setup like enabling interrupts. .El .Pp State is torn down and reclaimed with a call to .Fn ieee80211_ifdetach . Note this call may result in multiple callbacks into the driver so it should be done before any critical driver state is reclaimed. On return from .Fn ieee80211_ifdetach all associated vaps and ifnet structures are reclaimed or inaccessible to user applications so it is safe to teardown driver state without worry about being re-entered. The driver is responsible for calling .Xr if_free 9 on the ifnet it allocated for the physical device. .Sh DRIVER CAPABILITIES Driver/device capabilities are specified using several sets of flags in the .Vt ieee80211com structure. General capabilities are specified by .Vt ic_caps . Hardware cryptographic capabilities are specified by .Vt ic_cryptocaps . 802.11n capabilities, if any, are specified by .Vt ic_htcaps . The .Nm layer propagates a subset of these capabilities to each vap through the equivalent fields: .Vt iv_caps , .Vt iv_cryptocaps , and .Vt iv_htcaps . The following general capabilities are defined: .Bl -tag -width IEEE80211_C_8023ENCAP .It Dv IEEE80211_C_STA Device is capable of operating in station (aka Infrastructure) mode. .It Dv IEEE80211_C_8023ENCAP Device requires 802.3-encapsulated frames be passed for transmit. By default .Nm will encapsulate all outbound frames as 802.11 frames (without a PLCP header). .It Dv IEEE80211_C_FF Device supports Atheros Fast-Frames. .It Dv IEEE80211_C_TURBOP Device supports Atheros Dynamic Turbo mode. .It Dv IEEE80211_C_IBSS Device is capable of operating in adhoc/IBSS mode. .It Dv IEEE80211_C_PMGT Device supports dynamic power-management (aka power save) in station mode. .It Dv IEEE80211_C_HOSTAP Device is capable of operating as an Access Point in Infrastructure mode. .It Dv IEEE80211_C_AHDEMO Device is capable of operating in Adhoc Demo mode. In this mode the device is used purely to send/receive raw 802.11 frames. .It Dv IEEE80211_C_SWRETRY Device supports software retry of transmitted frames. .It Dv IEEE80211_C_TXPMGT Device support dynamic transmit power changes on transmitted frames; also known as Transmit Power Control (TPC). .It Dv IEEE80211_C_SHSLOT Device supports short slot time operation (for 802.11g). .It Dv IEEE80211_C_SHPREAMBLE Device supports short preamble operation (for 802.11g). .It Dv IEEE80211_C_MONITOR Device is capable of operating in monitor mode. .It Dv IEEE80211_C_DFS Device supports radar detection and/or DFS. DFS protocol support can be handled by .Nm but the device must be capable of detecting radar events. .It Dv IEEE80211_C_MBSS Device is capable of operating in MeshBSS (MBSS) mode (as defined by 802.11s Draft 3.0). .It Dv IEEE80211_C_WPA1 Device supports WPA1 operation. .It Dv IEEE80211_C_WPA2 Device supports WPA2/802.11i operation. .It Dv IEEE80211_C_BURST Device supports frame bursting. .It Dv IEEE80211_C_WME Device supports WME/WMM operation (at the moment this is mostly support for sending and receiving QoS frames with EDCF). .It Dv IEEE80211_C_WDS Device supports transmit/receive of 4-address frames. .It Dv IEEE80211_C_BGSCAN Device supports background scanning. .It Dv IEEE80211_C_TXFRAG Device supports transmit of fragmented 802.11 frames. .It Dv IEEE80211_C_TDMA Device is capable of operating in TDMA mode. .El .Pp The follow general crypto capabilities are defined. In general .Nm will fall-back to software support when a device is not capable of hardware acceleration of a cipher. This can be done on a per-key basis. .Nm can also handle software .Dv Michael calculation combined with hardware .Dv AES acceleration. .Bl -tag -width IEEE80211_C_8023ENCAP .It Dv IEEE80211_CRYPTO_WEP Device supports hardware WEP cipher. .It Dv IEEE80211_CRYPTO_TKIP Device supports hardware TKIP cipher. .It Dv IEEE80211_CRYPTO_AES_OCB Device supports hardware AES-OCB cipher. .It Dv IEEE80211_CRYPTO_AES_CCM Device supports hardware AES-CCM cipher. .It Dv IEEE80211_CRYPTO_TKIPMIC Device supports hardware Michael for use with TKIP. .It Dv IEEE80211_CRYPTO_CKIP Devices supports hardware CKIP cipher. .El .Pp The follow general 802.11n capabilities are defined. The first capabilities are defined exactly as they appear in the 802.11n specification. Capabilities beginning with IEEE80211_HTC_AMPDU are used solely by the .Nm layer. .Bl -tag -width IEEE80211_C_8023ENCAP .It Dv IEEE80211_HTCAP_CHWIDTH40 Device supports 20/40 channel width operation. .It Dv IEEE80211_HTCAP_SMPS_DYNAMIC Device supports dynamic SM power save operation. .It Dv IEEE80211_HTCAP_SMPS_ENA Device supports static SM power save operation. .It Dv IEEE80211_HTCAP_GREENFIELD Device supports Greenfield preamble. .It Dv IEEE80211_HTCAP_SHORTGI20 Device supports Short Guard Interval on 20MHz channels. .It Dv IEEE80211_HTCAP_SHORTGI40 Device supports Short Guard Interval on 40MHz channels. .It Dv IEEE80211_HTCAP_TXSTBC Device supports Space Time Block Convolution (STBC) for transmit. .It Dv IEEE80211_HTCAP_RXSTBC_1STREAM Device supports 1 spatial stream for STBC receive. .It Dv IEEE80211_HTCAP_RXSTBC_2STREAM Device supports 1-2 spatial streams for STBC receive. .It Dv IEEE80211_HTCAP_RXSTBC_3STREAM Device supports 1-3 spatial streams for STBC receive. .It Dv IEEE80211_HTCAP_MAXAMSDU_7935 Device supports A-MSDU frames up to 7935 octets. .It Dv IEEE80211_HTCAP_MAXAMSDU_3839 Device supports A-MSDU frames up to 3839 octets. .It Dv IEEE80211_HTCAP_DSSSCCK40 Device supports use of DSSS/CCK on 40MHz channels. .It Dv IEEE80211_HTCAP_PSMP Device supports PSMP. .It Dv IEEE80211_HTCAP_40INTOLERANT Device is intolerant of 40MHz wide channel use. .It Dv IEEE80211_HTCAP_LSIGTXOPPROT Device supports L-SIG TXOP protection. .It Dv IEEE80211_HTC_AMPDU Device supports A-MPDU aggregation. Note that any 802.11n compliant device must support A-MPDU receive so this implicitly means support for .Em transmit of A-MPDU frames. .It Dv IEEE80211_HTC_AMSDU Device supports A-MSDU aggregation. Note that any 802.11n compliant device must support A-MSDU receive so this implicitly means support for .Em transmit of A-MSDU frames. .It Dv IEEE80211_HTC_HT Device supports High Throughput (HT) operation. This capability must be set to enable 802.11n functionality in .Nm . .It Dv IEEE80211_HTC_SMPS Device supports MIMO Power Save operation. .It Dv IEEE80211_HTC_RIFS Device supports Reduced Inter Frame Spacing (RIFS). .El .Sh SEE ALSO .Xr ioctl 2 , .Xr ndis 4 , .Xr ieee80211_amrr 9 , .Xr ieee80211_beacon 9 , .Xr ieee80211_bmiss 9 , .Xr ieee80211_crypto 9 , .Xr ieee80211_ddb 9 , .Xr ieee80211_input 9 , .Xr ieee80211_node 9 , .Xr ieee80211_output 9 , .Xr ieee80211_proto 9 , .Xr ieee80211_radiotap 9 , .Xr ieee80211_regdomain 9 , .Xr ieee80211_scan 9 , .Xr ieee80211_vap 9 , .Xr ifnet 9 , .Xr malloc 9 .Sh HISTORY The .Nm series of functions first appeared in .Nx 1.5 , and were later ported to .Fx 4.6 . This man page was updated with the information from .Nx .Nm -man page. +man page. .Sh AUTHORS .An -nosplit The original .Nx .Nm man page was written by .An Bruce M. Simpson Aq Mt bms@FreeBSD.org and .An Darron Broad Aq Mt darron@kewl.org . Index: stable/12/share/man/man9/socket.9 =================================================================== --- stable/12/share/man/man9/socket.9 (revision 366091) +++ stable/12/share/man/man9/socket.9 (revision 366092) @@ -1,648 +1,648 @@ .\"- .\" Copyright (c) 2006 Robert N. M. Watson .\" Copyright (c) 2014 Benjamin J. Kaduk .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd October 18, 2018 .Dt SOCKET 9 .Os .Sh NAME .Nm socket .Nd "kernel socket interface" .Sh SYNOPSIS .In sys/socket.h .In sys/socketvar.h .Ft void .Fn soabort "struct socket *so" .Ft int .Fn soaccept "struct socket *so" "struct sockaddr **nam" .Ft int .Fn socheckuid "struct socket *so" "uid_t uid" .Ft int .Fn sobind "struct socket *so" "struct sockaddr *nam" "struct thread *td" .Ft void .Fn soclose "struct socket *so" .Ft int .Fn soconnect "struct socket *so" "struct sockaddr *nam" "struct thread *td" .Ft int .Fo socreate .Fa "int dom" "struct socket **aso" "int type" "int proto" .Fa "struct ucred *cred" "struct thread *td" .Fc .Ft int .Fn sodisconnect "struct socket *so" .Ft void .Fo sodtor_set -.Fa "struct socket *so" +.Fa "struct socket *so" .Fa "void (*func)(struct socket *)" .Fc .Ft struct sockaddr * .Fn sodupsockaddr "const struct sockaddr *sa" "int mflags" .Ft void .Fn sofree "struct socket *so" .Ft void .Fn sohasoutofband "struct socket *so" .Ft int .Fn solisten "struct socket *so" "int backlog" "struct thread *td" .Ft void .Fn solisten_proto "struct socket *so" "int backlog" .Ft int .Fn solisten_proto_check "struct socket *so" .Ft struct socket * .Fn sonewconn "struct socket *head" "int connstatus" .Ft int .Fo sopoll .Fa "struct socket *so" "int events" "struct ucred *active_cred" .Fa "struct thread *td" .Fc .Ft int .Fo sopoll_generic .Fa "struct socket *so" "int events" "struct ucred *active_cred" .Fa "struct thread *td" .Fc .Ft int .Fo soreceive .Fa "struct socket *so" "struct sockaddr **psa" "struct uio *uio" .Fa "struct mbuf **mp0" "struct mbuf **controlp" "int *flagsp" .Fc .Ft int .Fo soreceive_stream .Fa "struct socket *so" "struct sockaddr **paddr" .Fa "struct uio *uio" "struct mbuf **mp0" "struct mbuf **controlp" .Fa "int *flagsp" .Fc .Ft int .Fo soreceive_dgram .Fa "struct socket *so" "struct sockaddr **paddr" .Fa "struct uio *uio" "struct mbuf **mp0" "struct mbuf **controlp" .Fa "int *flagsp" .Fc .Ft int .Fo soreceive_generic .Fa "struct socket *so" "struct sockaddr **paddr" .Fa "struct uio *uio" "struct mbuf **mp0" "struct mbuf **controlp" .Fa "int *flagsp" .Fc .Ft int .Fn soreserve "struct socket *so" "u_long sndcc" "u_long rcvcc" .Ft void .Fn sorflush "struct socket *so" .Ft int .Fo sosend .Fa "struct socket *so" "struct sockaddr *addr" "struct uio *uio" .Fa "struct mbuf *top" "struct mbuf *control" "int flags" "struct thread *td" .Fc .Ft int .Fo sosend_dgram .Fa "struct socket *so" "struct sockaddr *addr" .Fa "struct uio *uio" "struct mbuf *top" "struct mbuf *control" .Fa "int flags" "struct thread *td" .Fc .Ft int .Fo sosend_generic .Fa "struct socket *so" "struct sockaddr *addr" .Fa "struct uio *uio" "struct mbuf *top" "struct mbuf *control" .Fa "int flags" "struct thread *td" .Fc .Ft int .Fn soshutdown "struct socket *so" "int how" .Ft void .Fn sotoxsocket "struct socket *so" "struct xsocket *xso" .Ft void .Fn soupcall_clear "struct socket *so" "int which" .Ft void .Fo soupcall_set .Fa "struct socket *so" "int which" .Fa "int (*func)(struct socket *, void *, int)" "void *arg" .Fc .Ft void .Fn sowakeup "struct socket *so" "struct sockbuf *sb" .In sys/sockopt.h .Ft int .Fn sosetopt "struct socket *so" "struct sockopt *sopt" .Ft int .Fn sogetopt "struct socket *so" "struct sockopt *sopt" .Ft int .Fn sooptcopyin "struct sockopt *sopt" "void *buf" "size_t len" "size_t minlen" .Ft int .Fn sooptcopyout "struct sockopt *sopt" "const void *buf" "size_t len" .Sh DESCRIPTION The kernel .Nm programming interface permits in-kernel consumers to interact with local and network socket objects in a manner similar to that permitted using the .Xr 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 .Vt "struct socket" pointers. Some portions of the kernel API exist only to implement the user API, and are not expected to be used by kernel code. The portions of the socket API used by socket consumers and implementations of network protocols will differ; some routines are only useful for protocol implementors. .Pp Except where otherwise indicated, .Nm functions may sleep, and are not appropriate for use in an .Xr ithread 9 context or while holding non-sleepable kernel locks. .Ss Creating and Destroying Sockets A new socket may be created using .Fn socreate . As with .Xr socket 2 , arguments specify the requested domain, type, and protocol via .Fa dom , type , and .Fa proto . The socket is returned via .Fa aso on success. In addition, the credential used to authorize operations associated with the socket will be passed via .Fa cred (and will be cached for the lifetime of the socket), and the thread performing the operation via .Fa td . .Em Warning : authorization of the socket creation operation will be performed using the thread credential for some protocols (such as raw sockets). .Pp Sockets may be closed and freed using .Fn soclose , which has similar semantics to .Xr close 2 . .Pp In certain circumstances, it is appropriate to destroy a socket without waiting for it to disconnect, for which .Fn soabort is used. This is only appropriate for incoming connections which are in a partially connected state. It must be called on an unreferenced socket, by the thread which removed the socket from its listen queue, to prevent races. It will call into protocol code, so no socket locks may be held over the call. The caller of .Fn soabort is responsible for setting the VNET context. The normal path to freeing a socket is .Fn sofree , which handles reference counting on the socket. It should be called whenever a reference is released, and also whenever reference flags are cleared in socket or protocol code. Calls to .Fn sofree should not be made from outside the socket layer; outside callers should use .Fn soclose instead. .Ss Connections and Addresses The .Fn sobind function is equivalent to the .Xr bind 2 system call, and binds the socket .Fa so to the address .Fa nam . The operation would be authorized using the credential on thread .Fa td . .Pp The .Fn soconnect function is equivalent to the .Xr connect 2 system call, and initiates a connection on the socket .Fa so to the address .Fa nam . The operation will be authorized using the credential on thread .Fa td . Unlike the user system call, .Fn soconnect returns immediately; the caller may .Xr msleep 9 on .Fa so->so_timeo while holding the socket mutex and waiting for the .Dv SS_ISCONNECTING flag to clear or .Fa so->so_error to become non-zero. If .Fn soconnect fails, the caller must manually clear the .Dv SS_ISCONNECTING flag. .Pp A call to .Fn sodisconnect disconnects the socket without closing it. .Pp The .Fn soshutdown function is equivalent to the .Xr shutdown 2 system call, and causes part or all of a connection on a socket to be closed down. .Pp Sockets are transitioned from non-listening status to listening with .Fn solisten . .Ss Socket Options The .Fn sogetopt function is equivalent to the .Xr getsockopt 2 system call, and retrieves a socket option on socket .Fa so . The .Fn sosetopt function is equivalent to the .Xr setsockopt 2 system call, and sets a socket option on socket .Fa so . .Pp The second argument in both .Fn sogetopt and .Fn sosetopt is the .Fa sopt pointer to a .Vt "struct sopt" describing the socket option operation. The caller-allocated structure must be zeroed, and then have its fields initialized to specify socket option operation arguments: .Bl -tag -width ".Va sopt_valsize" .It Va sopt_dir Set to .Dv SOPT_SET or .Dv SOPT_GET depending on whether this is a get or set operation. .It Va sopt_level Specify the level in the network stack the operation is targeted at; for example, .Dv SOL_SOCKET . .It Va sopt_name Specify the name of the socket option to set. .It Va sopt_val Kernel space pointer to the argument value for the socket option. .It Va sopt_valsize Size of the argument value in bytes. .El .Ss Socket Upcalls In order for the owner of a socket to be notified when the socket is ready to send or receive data, an upcall may be registered on the socket. The upcall is a function that will be called by the socket framework when a socket buffer associated with the given socket is ready for reading or writing. .Fn soupcall_set is used to register a socket upcall. The function .Va func is registered, and the pointer .Va arg will be passed as its second argument when it is called by the framework. The possible values for .Va which are .Dv SO_RCV and .Dv SO_SND , which register upcalls for receive and send events, respectively. The upcall function .Fn func must return either .Dv SU_OK or .Dv SU_ISCONNECTED , depending on whether or not a call to .Xr soisconnected should be made by the socket framework after the upcall returns. The upcall .Va func cannot call .Xr soisconnected itself due to lock ordering with the socket buffer lock. Only .Dv SO_RCV upcalls should return .Dv SU_ISCONNECTED . When a .Dv SO_RCV upcall returns .Dv SU_ISCONNECTED , the upcall will be removed from the socket. .Pp Upcalls are removed from their socket by .Fn soupcall_clear . The .Va which argument again specifies whether the sending or receiving upcall is to be cleared, with .Dv SO_RCV or .Dv SO_SND . .Ss Socket Destructor Callback A kernel system can use the .Fn sodtor_set function to set a destructor for a socket. The destructor is called when the socket is is about to be freed. The destructor is called before the protocol detach routine. The destructor can serve as a callback to initiate additional cleanup actions. .Ss Socket I/O The .Fn soreceive function is equivalent to the .Xr recvmsg 2 system call, and attempts to receive bytes of data from the socket .Fa so , optionally blocking awaiting for data if none is ready to read. Data may be retrieved directly to kernel or user memory via the .Fa uio argument, or as an mbuf chain returned to the caller via .Fa mp0 , avoiding a data copy. The .Fa uio must always be .Pf non- Dv NULL . If .Fa mp0 is .Pf non- Dv NULL , only the .Fa uio_resid of .Fa uio is used. The caller may optionally retrieve a socket address on a protocol with the .Dv PR_ADDR capability by providing storage via .Pf non- Dv NULL .Fa psa argument. The caller may optionally retrieve control data mbufs via a .Pf non- Dv NULL .Fa controlp argument. Optional flags may be passed to .Fn soreceive via a .Pf non- Dv NULL .Fa flagsp argument, and use the same flag name space as the .Xr recvmsg 2 system call. .Pp The .Fn sosend function is equivalent to the .Xr sendmsg 2 system call, and attempts to send bytes of data via the socket .Fa so , optionally blocking if data cannot be immediately sent. Data may be sent directly from kernel or user memory via the .Fa uio argument, or as an mbuf chain via .Fa top , avoiding a data copy. Only one of the .Fa uio or .Fa top pointers may be .Pf non- Dv NULL . An optional destination address may be specified via a .Pf non- Dv NULL .Fa addr argument, which may result in an implicit connect if supported by the protocol. The caller may optionally send control data mbufs via a .Pf non- Dv NULL .Fa control argument. Flags may be passed to .Fn sosend using the .Fa flags argument, and use the same flag name space as the .Xr sendmsg 2 system call. .Pp Kernel callers running in .Xr ithread 9 context, or with a mutex held, will wish to use non-blocking sockets and pass the .Dv MSG_DONTWAIT flag in order to prevent these functions from sleeping. .Pp A socket can be queried for readability, writability, out-of-band data, or end-of-file using .Fn sopoll . The possible values for .Va events are as for .Xr poll 2 , with symbolic values .Dv POLLIN , .Dv POLLPRI , .Dv POLLOUT , .Dv POLLRDNORM , .Dv POLLWRNORM , .Dv POLLRDBAND , and .Dv POLLINGEOF taken from .In sys/poll.h . .Pp Calls to .Fn soaccept pass through to the protocol's accept routine to accept an incoming connection. .Ss Socket Utility Functions The uid of a socket's credential may be compared against a .Va uid with .Fn socheckuid . .Pp A copy of an existing .Vt struct sockaddr may be made using .Fn sodupsockaddr . .Pp Protocol implementations notify the socket layer of the arrival of out-of-band data using .Fn sohasoutofband , so that the socket layer can notify socket consumers of the available data. .Pp An .Dq external-format version of a .Vt struct socket can be created using .Fn sotoxsocket , suitable for isolating user code from changes in the kernel structure. .Ss Protocol Implementations Protocols must supply an implementation for .Fn solisten ; such protocol implementations can call back into the socket layer using .Fn solisten_proto_check and .Fn solisten_proto to check and set the socket-layer listen state. These callbacks are provided so that the protocol implementation can order the socket layer and protocol locks as necessary. Protocols must supply an implementation of .Fn soreceive ; the functions .Fn soreceive_stream , .Fn soreceive_dgram , and .Fn soreceive_generic are supplied for use by such implementations. .Pp Protocol implementations can use .Fn sonewconn to create a socket and attach protocol state to that socket. This can be used to create new sockets available for .Fn soaccept on a listen socket. The returned socket has a reference count of zero. .Pp Protocols must supply an implementation for .Fn sopoll ; .Fn sopoll_generic is provided for the use by protocol implementations. .Pp The functions .Fn sosend_dgram and .Fn sosend_generic are supplied to assist in protocol implementations of .Fn sosend . .Pp When a protocol creates a new socket structure, it is necessary to reserve socket buffer space for that socket, by calling .Fn soreserve . The rough inverse of this reservation is performed by .Fn sorflush , which is called automatically by the socket framework. .Pp When a protocol needs to wake up threads waiting for the socket to become ready to read or write, variants of .Fn sowakeup are used. The .Fn sowakeup function should not be called directly by protocol code, instead use the wrappers .Fn sorwakeup , .Fn sorwakeup_locked , .Fn sowwakeup , and .Fn sowwakeup_locked for readers and writers, with the corresponding socket buffer lock not already locked, or already held, respectively. .Pp The functions .Fn sooptcopyin and .Fn sooptcopyout are useful for transferring .Vt struct sockopt data between user and kernel code. .Sh SEE ALSO .Xr bind 2 , .Xr close 2 , .Xr connect 2 , .Xr getsockopt 2 , .Xr recv 2 , .Xr send 2 , .Xr setsockopt 2 , .Xr shutdown 2 , .Xr socket 2 , .Xr ng_ksocket 4 , .Xr ithread 9 , .Xr msleep 9 , .Xr ucred 9 .Sh HISTORY The .Xr socket 2 system call appeared in .Bx 4.2 . This manual page was introduced in .Fx 7.0 . .Sh AUTHORS This manual page was written by .An Robert Watson and .An Benjamin Kaduk . .Sh BUGS The use of explicitly passed credentials, credentials hung from explicitly passed threads, the credential on .Dv curthread , and the cached credential from socket creation time is inconsistent, and may lead to unexpected behaviour. It is possible that several of the .Fa td arguments should be .Fa cred arguments, or simply not be present at all. .Pp The caller may need to manually clear .Dv SS_ISCONNECTING if .Fn soconnect returns an error. .Pp The .Dv MSG_DONTWAIT flag is not implemented for .Fn sosend , and may not always work with .Fn soreceive when zero copy sockets are enabled. .Pp This manual page does not describe how to register socket upcalls or monitor a socket for readability/writability without using blocking I/O. .Pp The .Fn soref and .Fn sorele functions are not described, and in most cases should not be used, due to confusing and potentially incorrect interactions when .Fn sorele is last called after .Fn soclose . Index: stable/12/share/man/man9/tcp_functions.9 =================================================================== --- stable/12/share/man/man9/tcp_functions.9 (revision 366091) +++ stable/12/share/man/man9/tcp_functions.9 (revision 366092) @@ -1,391 +1,392 @@ .\" .\" Copyright (c) 2016 Jonathan Looney .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR .\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd March 10, 2017 .Dt TCP_FUNCTIONS 9 .Os .Sh NAME .Nm tcp_functions .Nd Alternate TCP Stack Framework .Sh SYNOPSIS .In netinet/tcp.h .In netinet/tcp_var.h .Ft int .Fn register_tcp_functions "struct tcp_function_block *blk" "int wait" .Ft int .Fn register_tcp_functions_as_name "struct tcp_function_block *blk" \ "const char *name" "int wait" .Fn register_tcp_functions_as_names "struct tcp_function_block *blk" \ "int wait" "const char *names[]" "int *num_names" .Ft int .Fn deregister_tcp_functions "struct tcp_function_block *blk" .Sh DESCRIPTION The .Nm framework allows a kernel developer to implement alternate TCP stacks. The alternate stacks can be compiled in the kernel or can be implemented in loadable kernel modules. This functionality is intended to encourage experimentation with the TCP stack and to allow alternate behaviors to be deployed for different TCP connections on a single system. .Pp A system administrator can set a system default stack. By default, all TCP connections will use the system default stack. Additionally, users can specify a particular stack to use on a per-connection basis. (See .Xr tcp 4 for details on setting the system default stack, or selecting a specific stack for a given connection.) .Pp This man page treats "TCP stacks" as synonymous with "function blocks". This is intentional. A "TCP stack" is a collection of functions that implement a set of behavior. Therefore, an alternate "function block" defines an alternate "TCP stack". .Pp The .Fn register_tcp_functions , .Fn register_tcp_functions_as_name , and .Fn register_tcp_functions_as_names functions request that the system add a specified function block and register it for use with a given name. Modules may register the same function block multiple times with different names. However, names must be globally unique among all registered function blocks. Also, modules may not ever modify the contents of the function block (including the name) after it has been registered, unless the module first successfully de-registers the function block. .Pp The .Fn register_tcp_functions function requests that the system register the function block with the name defined in the function block's .Va tfb_tcp_block_name field. Note that this is the only one of the three registration functions that automatically registers the function block using the name defined in the function block's .Va tfb_tcp_block_name field. If a module uses one of the other registration functions, it may request that the system register the function block using the name defined in the function block's .Va tfb_tcp_block_name field by explicitly providing that name. .Pp The .Fn register_tcp_functions_as_name function requests that the system register the function block with the name provided in the .Fa name argument. .Pp The .Fn register_tcp_functions_as_names function requests that the system register the function block with all the names provided in the .Fa names argument. The .Fa num_names argument provides a pointer to the number of names. This function will either succeed in registering all of the names in the array, or none of the names in the array. On failure, the .Fa num_names argument is updated with the index number of the entry in the .Fa names array which the system was processing when it encountered the error. .Pp The .Fn deregister_tcp_functions function requests that the system remove a specified function block from the system. If this call succeeds, it will completely deregister the function block, regardless of the number of names used to register the function block. If the call fails because sockets are still using the specified function block, the system will mark the function block as being in the process of being removed. This will prevent additional sockets from using the specified function block. However, it will not impact sockets that are already using the function block. .Pp .Nm modules must call one or more of the registration functions during initialization and successfully call the .Fn deregister_tcp_functions function prior to allowing the module to be unloaded. .Pp The .Fa blk argument is a pointer to a .Vt "struct tcp_function_block" , which is explained below (see .Sx Function Block Structure ) . The .Fa wait argument is used as the .Fa flags argument to .Xr malloc 9 , and must be set to one of the valid values defined in that man page. .Ss Function Block Structure The .Fa blk argument is a pointer to a .Vt "struct tcp_function_block" , which has the following members: .Bd -literal -offset indent struct tcp_function_block { char tfb_tcp_block_name[TCP_FUNCTION_NAME_LEN_MAX]; int (*tfb_tcp_output)(struct tcpcb *); void (*tfb_tcp_do_segment)(struct mbuf *, struct tcphdr *, struct socket *, struct tcpcb *, int, int, uint8_t, int); int (*tfb_tcp_ctloutput)(struct socket *so, struct sockopt *sopt, struct inpcb *inp, struct tcpcb *tp); /* Optional memory allocation/free routine */ void (*tfb_tcp_fb_init)(struct tcpcb *); void (*tfb_tcp_fb_fini)(struct tcpcb *, int); /* Optional timers, must define all if you define one */ int (*tfb_tcp_timer_stop_all)(struct tcpcb *); void (*tfb_tcp_timer_activate)(struct tcpcb *, uint32_t, u_int); int (*tfb_tcp_timer_active)(struct tcpcb *, uint32_t); void (*tfb_tcp_timer_stop)(struct tcpcb *, uint32_t); /* Optional functions */ void (*tfb_tcp_rexmit_tmr)(struct tcpcb *); void (*tfb_tcp_handoff_ok)(struct tcpcb *); /* System use */ volatile uint32_t tfb_refcnt; uint32_t tfb_flags; }; .Ed .Pp The .Va tfb_tcp_block_name field identifies the unique name of the TCP stack, and should be no longer than TCP_FUNCTION_NAME_LEN_MAX-1 characters in length. .Pp The .Va tfb_tcp_output , .Va tfb_tcp_do_segment , and .Va tfb_tcp_ctloutput fields are pointers to functions that perform the equivalent actions as the default .Fn tcp_output , .Fn tcp_do_segment , and .Fn tcp_default_ctloutput functions, respectively. Each of these function pointers must be non-NULL. .Pp If a TCP stack needs to initialize data when a socket first selects the TCP stack (or, when the socket is first opened), it should set a non-NULL pointer in the .Va tfb_tcp_fb_init field. Likewise, if a TCP stack needs to cleanup data when a socket stops using the TCP stack (or, when the socket is closed), it should set a non-NULL pointer in the .Va tfb_tcp_fb_fini field. .Pp If the .Va tfb_tcp_fb_fini argument is non-NULL, the function to which it points is called when the kernel is destroying the TCP control block or when the socket is transitioning to use a different TCP stack. The function is called with arguments of the TCP control block and an integer flag. The flag will be zero if the socket is transitioning to use another TCP stack or one if the TCP control block is being destroyed. .Pp If the TCP stack implements additional timers, the TCP stack should set a non-NULL pointer in the .Va tfb_tcp_timer_stop_all , .Va tfb_tcp_timer_activate , .Va tfb_tcp_timer_active , and .Va tfb_tcp_timer_stop fields. These fields should all be .Dv NULL or should all contain pointers to functions. The .Va tfb_tcp_timer_activate , .Va tfb_tcp_timer_active , and .Va tfb_tcp_timer_stop functions will be called when the .Fn tcp_timer_activate , .Fn tcp_timer_active , and .Fn tcp_timer_stop functions, respectively, are called with a timer type other than the standard types. The functions defined by the TCP stack have the same semantics (both for arguments and return values) as the normal timer functions they supplement. .Pp Additionally, a stack may define its own actions to take when the retransmit timer fires by setting a non-NULL function pointer in the .Va tfb_tcp_rexmit_tmr field. This function is called very early in the process of handling a retransmit timer. However, care must be taken to ensure the retransmit timer leaves the TCP control block in a valid state for the remainder of the retransmit timer logic. .Pp A user may select a new TCP stack before calling .Xr connect 2 or .Xr listen 2 . Optionally, a TCP stack may also allow a user to begin using the TCP stack for a connection that is in a later state by setting a non-NULL function pointer in the .Va tfb_tcp_handoff_ok field. If this field is non-NULL and a user attempts to select that TCP stack after calling .Xr connect 2 or .Xr listen 2 for that socket, the kernel will call the function pointed to by the .Va tfb_tcp_handoff_ok field. The function should return 0 if the user is allowed to switch the socket to use -the TCP stack. Otherwise, the function should return an error code, which will -be returned to the user. +the TCP stack. +Otherwise, the function should return an error code, which will be returned to +the user. If the .Va tfb_tcp_handoff_ok field is .Dv NULL and a user attempts to select the TCP stack after calling .Xr connect 2 or .Xr listen 2 for that socket, the operation will fail and the kernel will return .Er EINVAL . .Pp The .Va tfb_refcnt and .Va tfb_flags fields are used by the kernel's TCP code and will be initialized when the TCP stack is registered. .Ss Requirements for Alternate TCP Stacks If the TCP stack needs to store data beyond what is stored in the default TCP control block, the TCP stack can initialize its own per-connection storage. The .Va t_fb_ptr field in the .Vt "struct tcpcb" control block structure has been reserved to hold a pointer to this per-connection storage. If the TCP stack uses this alternate storage, it should understand that the value of the .Va t_fb_ptr pointer may not be initialized to .Dv NULL . Therefore, it should use a .Va tfb_tcp_fb_init function to initialize this field. Additionally, it should use a .Va tfb_tcp_fb_fini function to deallocate storage when the socket is closed. .Pp It is understood that alternate TCP stacks may keep different sets of data. However, in order to ensure that data is available to both the user and the rest of the system in a standardized format, alternate TCP stacks must update all fields in the TCP control block to the greatest extent practical. .Sh RETURN VALUES The .Fn register_tcp_functions , .Fn register_tcp_functions_as_name , .Fn register_tcp_functions_as_names , and .Fn deregister_tcp_functions functions return zero on success and non-zero on failure. In particular, the .Fn deregister_tcp_functions will return .Er EBUSY until no more connections are using the specified TCP stack. A module calling .Fn deregister_tcp_functions must be prepared to wait until all connections have stopped using the specified TCP stack. .Sh ERRORS The .Fn register_tcp_functions function will fail if: .Bl -tag -width Er .It Bq Er EINVAL Any of the members of the .Fa blk argument are set incorrectly. .It Bq Er ENOMEM The function could not allocate memory for its internal data. .It Bq Er EALREADY A function block is already registered with the same name. .El The .Fn deregister_tcp_functions function will fail if: .Bl -tag -width Er .It Bq Er EPERM The .Fa blk argument references the kernel's compiled-in default function block. .It Bq Er EBUSY The function block is still in use by one or more sockets, or is defined as the current default function block. .It Bq Er ENOENT The .Fa blk argument references a function block that is not currently registered. .El .Sh SEE ALSO .Xr connect 2 , .Xr listen 2 , .Xr tcp 4 , .Xr malloc 9 .Sh HISTORY This framework first appeared in .Fx 11.0 . .Sh AUTHORS .An -nosplit The .Nm framework was written by .An Randall Stewart Aq Mt rrs@FreeBSD.org . .Pp This manual page was written by .An Jonathan Looney Aq Mt jtl@FreeBSD.org . Index: stable/12/share/man/man9/ucred.9 =================================================================== --- stable/12/share/man/man9/ucred.9 (revision 366091) +++ stable/12/share/man/man9/ucred.9 (revision 366092) @@ -1,215 +1,214 @@ .\" .\" Copyright (C) 2001 Chad David . All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice(s), this list of conditions and the following disclaimer as .\" the first lines of this file unmodified other than the possible .\" addition of one or more copyright notices. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice(s), this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH .\" DAMAGE. .\" .\" $FreeBSD$ .\" .Dd January 23, 2019 .Dt UCRED 9 .Os .Sh NAME .Nm ucred , .Nm crget , .Nm crhold , .Nm crfree , .Nm crcopy , .Nm crdup , .Nm cru2x .Nd "functions related to user credentials" .Sh SYNOPSIS .In sys/param.h .In sys/ucred.h .Ft "struct ucred *" .Fn crget void .Ft "struct ucred *" .Fn crhold "struct ucred *cr" .Ft void .Fn crfree "struct ucred *cr" .Ft void .Fn crcopy "struct ucred *dest" "struct ucred *src" .Ft "struct ucred *" .Fn crcopysafe "struct proc *p" "struct ucred *cr" .Ft "struct ucred *" .Fn crdup "struct ucred *cr" .Ft void .Fn crsetgroups "struct ucred *cr" "int ngrp" "gid_t *groups" .Ft void .Fn cru2x "struct ucred *cr" "struct xucred *xcr" .Sh DESCRIPTION The .Nm family of functions is used to manage user credential structures .Pq Vt "struct ucred" within the kernel. .Pp The .Fn crget function allocates memory for a new structure, sets its reference count to 1, and initializes its lock. .Pp The .Fn crhold function increases the reference count on the credential. .Pp The .Fn crfree function decreases the reference count on the credential. If the count drops to 0, the storage for the structure is freed. .Pp The .Fn crcopy function copies the contents of the source (template) credential into the destination template. The .Vt uidinfo structure within the destination is referenced by calling .Xr uihold 9 . .Pp The .Fn crcopysafe function copies the current credential associated with the process .Fa p into the newly allocated credential .Fa cr . The process lock on .Fa p must be held and will be dropped and reacquired as needed to allocate group storage space in .Fa cr . .Pp The .Fn crdup function allocates memory for a new structure and copies the contents of .Fa cr into it. The actual copying is performed by .Fn crcopy . .Pp The .Fn crsetgroups function sets the .Va cr_groups and .Va cr_ngroups variables and allocates space as needed. It also truncates the group list to the current maximum number of groups. No other mechanism should be used to modify the .Va cr_groups array except for updating the primary group via assignment to .Va cr_groups[0] . .Pp The .Fn cru2x function converts a .Vt ucred structure to an .Vt xucred structure. That is, it copies data from .Fa cr to .Fa xcr ; it ignores fields in the former that are not present in the latter (e.g., .Va cr_uidinfo ) , and appropriately sets fields in the latter that are not present in the former (e.g., .Va cr_version ) . -.Pp .Sh RETURN VALUES .Fn crget , .Fn crhold , .Fn crdup , and .Fn crcopysafe all return a pointer to a .Vt ucred structure. .Sh USAGE NOTES As of .Fx 5.0 , the .Vt ucred structure contains extensible fields. This means that the correct protocol must always be followed to create a fresh and writable credential structure: new credentials must always be derived from existing credentials using .Fn crget , .Fn crcopy , and .Fn crcopysafe . .Pp In the common case, credentials required for access control decisions are used in a read-only manner. In these circumstances, the thread credential .Va td_ucred should be used, as it requires no locking to access safely, and remains stable for the duration of the call even in the face of a multi-threaded application changing the process credentials from another thread. .Pp During a process credential update, the process lock must be held across check and update, to prevent race conditions. The process credential, .Va td->td_proc->p_ucred , must be used both for check and update. If a process credential is updated during a system call and checks against the thread credential are to be made later during the same system call, the thread credential must also be refreshed from the process credential so as to prevent use of a stale value. To avoid this scenario, it is recommended that system calls updating the process credential be designed to avoid other authorization functions. .Pp If temporarily elevated privileges are required for a thread, the thread credential can by replaced for the duration of an activity, or for the remainder of the system call. However, as a thread credential is often shared, appropriate care should be taken to make sure modifications are made to a writable credential through the use of .Fn crget and .Fn crcopy . .Pp Caution should be exercised when checking authorization for a thread or process perform an operation on another thread or process. As a result of temporary elevation, the target thread credential should .Em never be used as the target credential in an access control decision: the process credential associated with the thread, .Va td->td_proc->p_ucred , should be used instead. For example, .Xr p_candebug 9 accepts a target process, not a target thread, for access control purposes. .Sh SEE ALSO .Xr uihold 9 .Sh AUTHORS This manual page was written by .An Chad David Aq Mt davidc@acns.ab.ca . Index: stable/12 =================================================================== --- stable/12 (revision 366091) +++ stable/12 (revision 366092) Property changes on: stable/12 ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head:r365858