diff --git a/lib/libbe/libbe.3 b/lib/libbe/libbe.3 index eb0e9a34bb5e..4d9439206b7b 100644 --- a/lib/libbe/libbe.3 +++ b/lib/libbe/libbe.3 @@ -1,589 +1,589 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2017 Kyle Kneitinger .\" Copyright (c) 2018 Kyle Evans .\" .\" 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. .\" .Dd April 9, 2024 .Dt LIBBE 3 .Os .Sh NAME .Nm libbe .Nd library for creating, destroying and modifying ZFS boot environments .Sh LIBRARY .Lb libbe .Sh SYNOPSIS .In be.h .Ft "libbe_handle_t *hdl" Ns .Fn libbe_init "const char *be_root" .Pp .Ft void .Fn libbe_close "libbe_handle_t *hdl" .Pp .Ft const char * Ns .Fn be_active_name "libbe_handle_t *hdl" .Pp .Ft const char * Ns .Fn be_active_path "libbe_handle_t *hdl" .Pp .Ft const char * Ns .Fn be_nextboot_name "libbe_handle_t *hdl" .Pp .Ft const char * Ns .Fn be_nextboot_path "libbe_handle_t *hdl" .Pp .Ft const char * Ns .Fn be_root_path "libbe_handle_t *hdl" .Pp .Ft int Ns .Fn be_snapshot "libbe_handle_t *hdl" "const char *be_name" "const char *snap_name" "bool recursive" "char *result" .Pp .Ft bool Ns .Fn be_is_auto_snapshot_name "libbe_handle_t *hdl" "const char *snap" .Pp .Ft int .Fn be_create "libbe_handle_t *hdl" "const char *be_name" .Pp .Ft int .Fn be_create_depth "libbe_handle_t *hdl" "const char *be_name" "const char *snap" "int depth" .Pp .Ft int .Fn be_create_from_existing "libbe_handle_t *hdl" "const char *be_name" "const char *be_origin" .Pp .Ft int .Fn be_create_from_existing_snap "libbe_handle_t *hdl" "const char *be_name" "const char *snap" .Pp .Ft int .Fn be_rename "libbe_handle_t *hdl" "const char *be_old" "const char *be_new" .Pp .Ft int .Fn be_activate "libbe_handle_t *hdl" "const char *be_name" "bool temporary" .Pp .Ft int .Fn be_deactivate "libbe_handle_t *hdl" "const char *be_name" "bool temporary" .Pp .Ft int .Fn be_destroy "libbe_handle_t *hdl" "const char *be_name" "int options" .Pp .Ft void .Fn be_nicenum "uint64_t num" "char *buf" "size_t bufsz" .Pp .\" TODO: Write up of mount options .\" typedef enum { .\" BE_MNT_FORCE = 1 << 0, .\" BE_MNT_DEEP = 1 << 1, .\" } be_mount_opt_t .Ft int .Fn be_mount "libbe_handle_t *hdl" "const char *be_name" "const char *mntpoint" "int flags" "char *result" .Pp .Ft int .Fn be_mounted_at "libbe_handle_t *hdl" "const char *path" "nvlist_t *details" .Pp .Ft int .Fn be_unmount "libbe_handle_t *hdl" "const char *be_name" "int flags" .Pp .Ft int .Fn libbe_errno "libbe_handle_t *hdl" .Pp .Ft const char * Ns .Fn libbe_error_description "libbe_handle_t *hdl" .Pp .Ft void .Fn libbe_print_on_error "libbe_handle_t *hdl" "bool doprint" .Pp .Ft int .Fn be_root_concat "libbe_handle_t *hdl" "const char *be_name" "char *result" .Pp .Ft int .Fn be_validate_name "libbe_handle_t *hdl" "const char *be_name" .Pp .Ft int .Fn be_validate_snap "libbe_handle_t *hdl" "const char *snap" .Pp .Ft int .Fn be_exists "libbe_handle_t *hdl" "const char *be_name" .Pp .Ft int .Fn be_export "libbe_handle_t *hdl" "const char *be_name" "int fd" .Pp .Ft int .Fn be_import "libbe_handle_t *hdl" "const char *be_name" "int fd" .Pp .Ft int .Fn be_prop_list_alloc "nvlist_t **prop_list" .Pp .Ft int .Fn be_get_bootenv_props "libbe_handle_t *hdl" "nvlist_t *be_list" .Pp .Ft int .Fn be_get_dataset_props "libbe_handle_t *hdl" "const char *ds_name" "nvlist_t *props" .Pp .Ft int .Fn be_get_dataset_snapshots "libbe_handle_t *hdl" "const char *ds_name" "nvlist_t *snap_list" .Pp .Ft void .Fn be_prop_list_free "nvlist_t *prop_list" .Sh DESCRIPTION .Nm interfaces with libzfs to provide a set of functions for various operations regarding ZFS boot environments, including "deep" boot environments in which a boot environment has child datasets. .Pp A context structure is passed to each function, allowing for a small amount of state to be retained, such as errors from previous operations. .Nm may be configured to print the corresponding error message to .Dv stderr when an error is encountered with .Fn libbe_print_on_error . .Pp All functions returning an .Vt int return 0 on success, or a .Nm errno otherwise as described in .Sx DIAGNOSTICS . .Pp The .Fn libbe_init function takes an optional BE root and initializes .Nm , returning a .Vt "libbe_handle_t *" on success, or .Dv NULL on error. If a BE root is supplied, .Nm will only operate out of that pool and BE root. An error may occur if: .Bl -bullet .It .Pa /boot and .Pa / are not on the same filesystem and device, .It libzfs fails to initialize, .It The system has not been properly booted with a ZFS boot environment, .It .Nm fails to open the zpool the active boot environment resides on, or .It .Nm fails to locate the boot environment that is currently mounted. .El .Pp The .Fn libbe_close function frees all resources previously acquired in .Fn libbe_init , invalidating the handle in the process. .Pp The .Fn be_active_name function returns the name of the currently booted boot environment. This boot environment may not belong to the same BE root as the root libbe is operating on! .Pp The .Fn be_active_path function returns the full path of the currently booted boot environment. This boot environment may not belong to the same BE root as the root libbe is operating on! .Pp The .Fn be_nextboot_name function returns the name of the boot environment that will be active on reboot. .Pp The .Fn be_nextboot_path function returns the full path of the boot environment that will be active on reboot. .Pp The .Fn be_root_path function returns the boot environment root path. .Pp The .Fn be_snapshot function creates a snapshot of .Fa be_name named .Fa snap_name . A value of .Dv NULL may be used, indicating that .Fn be_snaphot should derive the snapshot name from the current date and time. If .Fa recursive is set, then .Fn be_snapshot will recursively snapshot the dataset. If .Fa result is not .Dv NULL , then it will be populated with the final .Dq Fa be_name Ns @ Ns Fa snap_name . .Pp The .Fn be_is_auto_snapshot_name function is used to determine if the given snapshot name matches the format that the .Fn be_snapshot function will use by default if it is not given a snapshot name to use. It returns .Dv true if the name matches the format, and .Dv false if it does not. .Pp The .Fn be_create function creates a boot environment with the given name. The new boot environment will be created from a recursive snapshot of the currently booted boot environment. .Pp The .Fn be_create_depth function creates a boot environment with the given name from an existing snapshot. The depth parameter specifies the depth of recursion that will be cloned from the existing snapshot. A depth of '0' is no recursion and '-1' is unlimited (i.e., a recursive boot environment). .Pp The .Fn be_create_from_existing function creates a boot environment with the given name from the name of an existing boot environment. A recursive snapshot will be made of the origin boot environment, and the new boot environment will be created from that. .Pp The .Fn be_create_from_existing_snap function creates a recursive boot environment with the given name from an existing snapshot. .Pp The .Fn be_rename function renames a boot environment without unmounting it, as if renamed with the .Fl u argument were passed to .Nm zfs .Cm rename .Pp The .Fn be_activate function makes a boot environment active on the next boot. If the .Fa temporary flag is set, then it will be active for the next boot only, as done by .Xr zfsbootcfg 8 . .Pp The .Fn be_deactivate function deactivates a boot environment. If the .Fa temporary flag is set, then it will cause removal of boot once configuration, set by .Fn be_activate function or by .Xr zfsbootcfg 8 . If the .Fa temporary flag is not set, .Fn be_deactivate function will set zfs .Dv canmount property to .Dv noauto . .Pp The .Fn be_destroy function will recursively destroy the given boot environment. It will not destroy a mounted boot environment unless the .Dv BE_DESTROY_FORCE option is set in .Fa options . If the .Dv BE_DESTROY_ORIGIN option is set in .Fa options , the .Fn be_destroy function will destroy the origin snapshot to this boot environment as well. .Pp The .Fn be_nicenum function will format .Fa name in a traditional ZFS humanized format, similar to .Xr humanize_number 3 . This function effectively proxies .Fn zfs_nicenum from libzfs. .Pp The .Fn be_mount function will mount the given boot environment. If .Fa mountpoint is .Dv NULL , a mount point will be generated in .Pa /tmp using .Xr mkdtemp 3 . If .Fa result is not .Dv NULL , it should be large enough to accommodate .Dv BE_MAXPATHLEN including the null terminator. the final mount point will be copied into it. Setting the .Dv BE_MNT_FORCE flag will pass .Dv MNT_FORCE to the underlying .Xr mount 2 call. .Pp The .Fn be_mounted_at function will check if there is a boot environment mounted at the given .Fa path . If .Fa details is not .Dv NULL , it will be populated with a list of the mounted dataset's properties. This list of properties matches the properties collected by .Fn be_get_bootenv_props . .Pp The .Fn be_unmount function will unmount the given boot environment. Setting the .Dv BE_MNT_FORCE flag will pass .Dv MNT_FORCE to the underlying .Xr mount 2 call. .Pp The .Fn libbe_errno function returns the .Nm errno. .Pp The .Fn libbe_error_description function returns a string description of the currently set .Nm errno. .Pp The .Fn libbe_print_on_error function will change whether or not .Nm prints the description of any encountered error to .Dv stderr , based on .Fa doprint . .Pp The .Fn be_root_concat function will concatenate the boot environment root and the given boot environment name into .Fa result . .Pp The .Fn be_validate_name function will validate the given boot environment name for both length restrictions as well as valid character restrictions. This function does not set the internal library error state. .Pp The .Fn be_validate_snap function will validate the given snapshot name. The snapshot must have a valid name, exist, and have a mountpoint of .Pa / . This function does not set the internal library error state. .Pp The .Fn be_exists function will check whether the given boot environment exists and has a mountpoint of .Pa / . This function does not set the internal library error state, but will return the appropriate error. .Pp The .Fn be_export function will export the given boot environment to the file specified by .Fa fd . A snapshot will be created of the boot environment prior to export. .Pp The .Fn be_import function will import the boot environment in the file specified by .Fa fd , and give it the name .Fa be_name . .Pp The .Fn be_prop_list_alloc function allocates a property list suitable for passing to .Fn be_get_bootenv_props , .Fn be_get_dataset_props , or .Fn be_get_dataset_snapshots . It should be freed later by .Fa be_prop_list_free . .Pp The .Fn be_get_bootenv_props function will populate .Fa be_list with .Vt nvpair_t of boot environment names paired with an .Vt nvlist_t of their properties. The following properties are currently collected as appropriate: .Bl -column "Returned name" .It Sy Returned name Ta Sy Description .It dataset Ta - .It name Ta Boot environment name .It mounted Ta Current mount point .It mountpoint Ta Do mountpoint Dc property .It origin Ta Do origin Dc property .It creation Ta Do creation Dc property .It active Ta Currently booted environment .It used Ta Literal Do used Dc property .It usedds Ta Literal Do usedds Dc property .It usedsnap Ta Literal Do usedrefreserv Dc property .It referenced Ta Literal Do referenced Dc property .It nextboot Ta Active on next boot .El .Pp Only the .Dq dataset , .Dq name , .Dq active , and .Dq nextboot returned values will always be present. All other properties may be omitted if not available. .Pp The .Fn be_get_dataset_props function will get properties of the specified dataset. .Fa props is populated directly with a list of the properties as returned by .Fn be_get_bootenv_props . .Pp The .Fn be_get_dataset_snapshots function will retrieve all snapshots of the given dataset. .Fa snap_list will be populated with a list of .Vt nvpair_t exactly as specified by .Fn be_get_bootenv_props . .Pp The .Fn be_prop_list_free function will free the property list. .Sh DIAGNOSTICS Upon error, one of the following values will be returned: .Bl -bullet -offset indent -compact .It BE_ERR_SUCCESS .It BE_ERR_INVALIDNAME .It BE_ERR_EXISTS .It BE_ERR_NOENT .It BE_ERR_PERMS .It BE_ERR_DESTROYACT .It BE_ERR_DESTROYMNT .It BE_ERR_BADPATH .It BE_ERR_PATHBUSY .It BE_ERR_PATHLEN .It BE_ERR_BADMOUNT .It BE_ERR_NOORIGIN .It BE_ERR_MOUNTED .It BE_ERR_NOMOUNT .It BE_ERR_ZFSOPEN .It BE_ERR_ZFSCLONE .It BE_ERR_IO .It BE_ERR_NOPOOL .It BE_ERR_NOMEM .It BE_ERR_UNKNOWN .It BE_ERR_INVORIGIN .El .Sh SEE ALSO .Xr bectl 8 .Sh HISTORY .Xr bectl 8 and .Nm were written by .An Kyle Kneitinger (kneitinger) Aq Mt kyle@kneit.in as a 2017 Google Summer of Code project, with .An Allan Jude (allanjude) Aq Mt allanjude@freebsd.org as mentor. .Sh AUTHORS Kyle Kneitinger, mentored as above. .Pp -Post-GSoC changes were written by +Post-GSoC changes were written by .An Kyle Evans (kevans) Aq Mt kevans@freebsd.org . diff --git a/lib/libc/net/inet.3 b/lib/libc/net/inet.3 index 7b1a5fcc8ede..9b822fd6805a 100644 --- a/lib/libc/net/inet.3 +++ b/lib/libc/net/inet.3 @@ -1,293 +1,293 @@ .\" Copyright (c) 1983, 1990, 1991, 1993 .\" The Regents of the University of California. 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. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. .\" .Dd November 9, 2021 .Dt INET 3 .Os .Sh NAME .Nm inet_aton , .Nm inet_addr , .Nm inet_network , .Nm inet_ntoa , .Nm inet_ntoa_r , .Nm inet_ntop , .Nm inet_pton , .Nm inet_makeaddr , .Nm inet_lnaof , .Nm inet_netof .Nd Internet address manipulation routines .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In netinet/in.h .In arpa/inet.h .Ft int .Fn inet_aton "const char *cp" "struct in_addr *pin" .Ft in_addr_t .Fn inet_addr "const char *cp" .Ft in_addr_t .Fn inet_network "const char *cp" .Ft char * .Fn inet_ntoa "struct in_addr in" .Ft char * .Fo inet_ntoa_r .Fa "struct in_addr in" .Fa "char *buf" .Fa "socklen_t size" .Fc .Ft const char * .Fo inet_ntop .Fa "int af" .Fa "const void * restrict src" .Fa "char * restrict dst" .Fa "socklen_t size" .Fc .Ft int .Fn inet_pton "int af" "const char * restrict src" "void * restrict dst" .Ft struct in_addr .Fn inet_makeaddr "in_addr_t net" "in_addr_t lna" .Ft in_addr_t .Fn inet_lnaof "struct in_addr in" .Ft in_addr_t .Fn inet_netof "struct in_addr in" .Sh DESCRIPTION The routines .Fn inet_aton , .Fn inet_addr and .Fn inet_network interpret character strings representing numbers expressed in the Internet standard .Ql .\& notation. .Pp The .Fn inet_pton function converts a presentation format address (that is, printable form as held in a character string) to network format (usually a .Ft struct in_addr or some other internal binary representation, in network byte order). It returns 1 if the address was valid for the specified address family, or 0 if the address was not parseable in the specified address family, or -1 if some system error occurred (in which case .Va errno will have been set). This function is presently valid for .Dv AF_INET and .Dv AF_INET6 . .Pp The .Fn inet_aton routine interprets the specified character string as an Internet address, placing the address into the structure provided. It returns 1 if the string was successfully interpreted, or 0 if the string is invalid. The .Fn inet_addr and .Fn inet_network functions return numbers suitable for use as Internet addresses and Internet network numbers, respectively. .Pp The function .Fn inet_ntop converts an address .Fa *src from network format (usually a .Ft struct in_addr or some other binary form, in network byte order) to presentation format (suitable for external display purposes). The .Fa size argument specifies the size, in bytes, of the buffer .Fa *dst . .Dv INET_ADDRSTRLEN and .Dv INET6_ADDRSTRLEN define the maximum size required to convert an address of the respective type. It returns NULL if a system error occurs (in which case, .Va errno will have been set), or it returns a pointer to the destination string. This function is presently valid for .Dv AF_INET and .Dv AF_INET6 . .Pp The routine .Fn inet_ntoa takes an Internet address and returns an .Tn ASCII string representing the address in .Ql .\& notation. The routine .Fn inet_ntoa_r is the reentrant version of .Fn inet_ntoa . The deprecated routine .Fn inet_makeaddr takes an Internet network number and a local host address on that network, and constructs an Internet address from it. It should only be assumed to work for historical class A/B/C networks. The deprecated routines .Fn inet_netof and .Fn inet_lnaof break apart Internet host addresses, returning the network number and local host address part, respectively, assuming the historical class A/B/C network masks. .Pp All Internet addresses are returned in network order (bytes ordered from left to right). All network numbers and local address parts are returned as machine byte order integer values. .Sh INTERNET ADDRESSES (IP VERSION 4) The -.Fn inet_aton +.Fn inet_aton and .Fn inet_addr functions accept IPv4 values specified using the .Ql .\& notation in one of the following forms: .Bd -literal -offset indent a.b.c.d a.b.c a.b a .Ed .Pp When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, to the four bytes of an Internet address. .Pp When a three part address is specified, the last part is interpreted as a 16-bit quantity and placed in the least significant two bytes of the network address. .Pp When a two part address is supplied, the last part is interpreted as a 24-bit quantity and placed in the least significant three bytes of the network address. .Pp When only one part is given, the value is stored directly in the network address without any byte rearrangement. .Pp All numbers supplied as .Dq parts in a .Ql .\& notation may be decimal, octal, or hexadecimal, as specified in the C language (i.e., a leading 0x or 0X implies hexadecimal; otherwise, a leading 0 implies octal; otherwise, the number is interpreted as decimal). .Pp Note that .Fn inet_pton does not accept 1-, 2-, or 3-part dotted addresses; all four parts must be specified and are interpreted only as decimal values. This is a narrower input set than that accepted by .Fn inet_aton . .Sh DIAGNOSTICS The constant .Dv INADDR_NONE is returned by .Fn inet_addr and .Fn inet_network for malformed requests. .Sh ERRORS The .Fn inet_ntop call fails if: .Bl -tag -width Er .It Bq Er ENOSPC .Fa size was not large enough to store the presentation form of the address. .It Bq Er EAFNOSUPPORT .Fa *src was not an .Dv AF_INET or .Dv AF_INET6 family address. .El .Sh SEE ALSO .Xr byteorder 3 , .Xr getaddrinfo 3 , .Xr gethostbyname 3 , .Xr getnameinfo 3 , .Xr getnetent 3 , .Xr inet_net 3 , .Xr hosts 5 , .Xr networks 5 .Rs .%R RFC .%N 2373 .%D July 1998 .%T "IP Version 6 Addressing Architecture" .Re .Sh STANDARDS The .Fn inet_ntop and .Fn inet_pton functions conform to .St -xns5.2 . .Sh HISTORY These functions appeared in .Bx 4.2 . .Sh BUGS The value .Dv INADDR_NONE (0xffffffff) is a valid broadcast address, but .Fn inet_addr cannot return that value without indicating failure. The newer .Fn inet_aton function does not share this problem. The problem of host byte ordering versus network byte ordering is confusing. The string returned by .Fn inet_ntoa resides in a static memory area. .Pp The .Fn inet_addr function should return a .Fa struct in_addr . diff --git a/sbin/mount/mntopts.3 b/sbin/mount/mntopts.3 index 2480be2bdc9e..74fca612479f 100644 --- a/sbin/mount/mntopts.3 +++ b/sbin/mount/mntopts.3 @@ -1,379 +1,379 @@ .\" Copyright (c) 2023 Marshall Kirk McKusick .\" Copyright (c) 1994 The Regents of the University of California. .\" .\" 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 AUTHORS 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 AUTHORS 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. .\" .Dd January 19, 2023 .Dt MNTOPTS 3 .Os .Sh NAME .Nm getmntopts , .Nm getmntpoint , .Nm chkdoreload , .Nm build_iovec , .Nm build_iovec_argf , .Nm free_iovec , .Nm checkpath , .Nm rmslashes .Nd "mount point operations" .Sh SYNOPSIS .In mntopts.h .Ft void .Fo getmntopts .Fa "const char *options" "const struct mntopt *mopts" .Fa "int *flagp" "int *altflagp" .Fc .Ft struct statfs * .Fn getmntpoint "const char *name" .Ft int .Fo chkdoreload .Fa "struct statfs *mntp" .Fa "void (*prtmsg)(const char *fmt, ...)" .Fc .Ft void .Fo build_iovec .Fa "struct iovec **iov" "int *iovlen" "const char *name" "void *val" .Fa "size_t len" .Fc .Ft void .Fo build_iovec_argf .Fa "struct iovec **iov" "int *iovlen" "const char *name" .Fa "const char *fmt" "..." .Fc .Ft void .Fn free_iovec "struct iovec **iov" "int *iovlen" .Ft int .Fn checkpath "const char *path" "char *resolved" .Ft void .Fn rmslashes "char *rrpin" "char *rrpout" .Sh DESCRIPTION The .Nm mntopts functions support operations associated with a mount point. For historic reasons are in a file in the sources for the .Xr mount 8 program. Thus, to access them the following lines need to be added to the .Nm Makefile of the program wanting to use them: .Bd -literal SRCS+= getmntopts.c MOUNT= ${SRCTOP}/sbin/mount CFLAGS+= -I${MOUNT} \&.PATH: ${MOUNT} .Ed .Pp The .Fn getmntopts function takes a comma separated option list and a list of valid option names, and computes the bitmask corresponding to the requested set of options. .Pp The string .Fa options is broken down into a sequence of comma separated tokens. Each token is looked up in the table described by .Fa mopts and the bits in the word referenced by either .Fa flagp or .Fa altflagp (depending on the .Va m_altloc field of the option's table entry) are updated. The flag words are not initialized by .Fn getmntopts . The table, .Fa mopts , has the following format: .Bd -literal struct mntopt { char *m_option; /* option name */ int m_inverse; /* is this a negative option, e.g., "dev" */ int m_flag; /* bit to set, e.g., MNT_RDONLY */ int m_altloc; /* non-zero to use altflagp rather than flagp */ }; .Ed .Pp The members of this structure are: .Bl -tag -width m_inverse .It Va m_option the option name, for example .Dq Li suid . .It Va m_inverse tells .Fn getmntopts that the name has the inverse meaning of the bit. For example, .Dq Li suid is the string, whereas the mount flag is .Dv MNT_NOSUID . In this case, the sense of the string and the flag are inverted, so the .Va m_inverse flag should be set. .It Va m_flag the value of the bit to be set or cleared in the flag word when the option is recognized. The bit is set when the option is discovered, but cleared if the option name was preceded by the letters .Dq Li no . The .Va m_inverse flag causes these two operations to be reversed. .It Va m_altloc the bit should be set or cleared in .Fa altflagp rather than .Fa flagp . .El .Pp Each of the user visible .Dv MNT_ flags has a corresponding .Dv MOPT_ macro which defines an appropriate .Vt "struct mntopt" entry. To simplify the program interface and ensure consistency across all programs, a general purpose macro, .Dv MOPT_STDOPTS , is defined which contains an entry for all the generic VFS options. In addition, the macros .Dv MOPT_FORCE and .Dv MOPT_UPDATE exist to enable the .Dv MNT_FORCE and .Dv MNT_UPDATE flags to be set. Finally, the table must be terminated by an entry with a .Dv NULL first element. .Pp The .Fn getmntpoint function takes the pathname of a possible mount point or of a device (with or without .Pa /dev/ prepended to it). If the pathname is a directory or a file, .Fn getmntpoint checks to see if the mount point currently has a filesystem mounted on it. If the pathname is a device, .Fn getmntpoint checks to see if it is currently mounted. If there is an associated mount, a pointer to a .Vt "struct statfs" is returned. The returned result is stored in a static buffer that is over-written each time the .Fn getmntpoint function or the .Xr getmntinfo 3 library routine is called. If no mount is found, NULL is returned. .Pp The .Fn chkdoreload -function takes a pointer to a +function takes a pointer to a .Vt "struct statfs" . If the filesystem associated with the mount point is mounted read-only, .Fn chkdoreload requests the filesystem to reload all of its metadata from its backing store. The second parameter is the function to call to print an error message if the reload fails. If no error message is desired, a .Dv NULL can be passed as the second argument. The .Fn chkdoreload function returns zero on success or non-zero on failure. .Pp The .Fn build_iovec function adds a parameter to a list of parameters to be passed to the .Xr nmount 2 system call. The parameter list is built up in .Va iov and its length is kept in .Va iovlen . Before the first call to .Fn build_iovec , .Va iov should be set to .Dv NULL and .Va iovlen should be set to 0. The parameter name is passed in .Va name . The value of the parameter name is pointed to by .Va val . The size of the value is passed in .Va len . If the value is a string, a .Va len of -1 is passed to indicate that the length should be determined using .Xr strlen 3 . If the parameter has no value, .Va name should be .Dv NULL and .Va len should be 0. .Pp The .Fn build_iovec_argf function adds a formatted parameter to a list of parameters to be passed to the .Xr nmount 2 system call. The parameter list is built up in .Va iov and its length is kept in .Va iovlen . Before the first call to .Fn build_iovec_argf , .Va iov should be set to .Dv NULL and .Va iovlen should be set to 0. The parameter name is passed in .Va name . The value of the parameter name is described by a format string pointed to by .Va fmt . If the parameter has no value, .Va name should be .Dv NULL . .Pp The .Fn free_iovec function frees the memory in the .Va iov vector of the length specified in .Va iovlen that was previously allocated by the .Fn build_iovec and / or .Fn build_iovec_argf functions. The .Va iov is set to .Dv NULL and the .Va iovlen is set to 0 to indicate that the space has been freed. .Pp The .Fn checkpath function uses .Xr realpath 3 to verify that its .Va path argument is valid and references a directory. The .Fn checkpath function returns zero on success or non-zero on failure. .Pp The .Fn rmslashes function removes all double slashes and trailing slashes from its .Va rrpin pathname parameter and returns the resulting pathname in its .Va rrpout parameter. .Sh EXAMPLES Most commands will use the standard option set. Local file systems which support the .Dv MNT_UPDATE flag, would also have an .Dv MOPT_UPDATE entry. This can be declared and used as follows: .Bd -literal #include "mntopts.h" struct mntopt mopts[] = { MOPT_STDOPTS, MOPT_UPDATE, { NULL } }; ... mntflags = mntaltflags = 0; ... getmntopts(options, mopts, &mntflags, &mntaltflags); ... .Ed .Sh DIAGNOSTICS If the external integer variable .Va getmnt_silent is zero, then the .Fn getmntopts function displays an error message and exits if an unrecognized option is encountered. Otherwise unrecognized options are silently ignored. By default .Va getmnt_silent is zero. .Sh SEE ALSO .Xr err 3 , .Xr mount 8 , .Xr nmount 8 .Sh HISTORY The .Fn getmntopts function appeared in .Bx 4.4 . The .Fn build_iovec , .Fn build_iovec_argf , .Fn free_iovec , .Fn checkpath , and .Fn rmslashes functions were added with .Xr nmount 8 in .Fx 5.0 . The .Fn getmntpoint and .Fn chkdoreload functions were added in .Fx 13.2 . diff --git a/sbin/nvmecontrol/nvmecontrol.8 b/sbin/nvmecontrol/nvmecontrol.8 index 76c79778021d..e21079b17ed6 100644 --- a/sbin/nvmecontrol/nvmecontrol.8 +++ b/sbin/nvmecontrol/nvmecontrol.8 @@ -1,1043 +1,1043 @@ .\" .\" Copyright (c) 2020 Warner Losh .\" Copyright (c) 2018-2019 Alexander Motin .\" Copyright (c) 2012 Intel Corporation .\" 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, .\" without modification. .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer .\" substantially similar to the "NO WARRANTY" disclaimer below .\" ("Disclaimer") and any redistribution must be conditioned upon .\" including a substantially similar Disclaimer requirement for further .\" binary redistribution. .\" .\" NO WARRANTY .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT .\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR 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 DAMAGES. .\" .\" nvmecontrol man page. .\" .\" Author: Jim Harris .\" .Dd May 10, 2024 .Dt NVMECONTROL 8 .Os .Sh NAME .Nm nvmecontrol .Nd NVM Express control utility .Sh SYNOPSIS .Nm .Ic devlist .Op Fl h .Nm .Ic identify .Op Fl v .Op Fl x .Op Fl n Ar nsid .Aq Ar device-id | Ar namespace-id .Nm .Ic perftest .Aq Fl n Ar num_threads .Aq Fl o Ar read|write .Op Fl p .Aq Fl s Ar size_in_bytes .Aq Fl t Ar time_in_sec .Aq Ar namespace-id .Nm .Ic reset .Aq Ar device-id .Nm .Ic logpage .Aq Fl p Ar page_id .Op Fl x .Op Fl v Ar vendor-string .Op Fl b .Op Fl f Ar LSP .Op Fl i Ar LSI .Op Fl r .Aq Ar device-id | Ar namespace-id .Nm .Ic ns active .Aq Ar device-id .Nm .Ic ns allocated .Aq Ar device-id .Nm .Ic ns attach .Aq Fl n Ar nsid .Aq Fl c Ar cntid .Aq Ar device-id .Nm .Ic ns attached .Aq Fl n Ar nsid .Aq Ar device-id .Nm .Ic ns controllers .Aq Ar device-id .Nm .Ic ns create .Aq Fl s Ar nsze .Op Fl c Ar ncap .Op Fl f Ar lbaf .Op Fl m Ar mset .Op Fl n Ar nmic .Op Fl p Ar pi .Op Fl l Ar pil .Op Fl L Ar flbas .Op Fl d Ar dps .Aq Ar device-id .Nm .Ic ns delete .Aq Fl n Ar nsid .Aq Ar device-id .Nm .Ic ns detach .Aq Fl n Ar nsid .Aq Fl c Ar cntid .Aq Ar device-id .Nm .Ic ns identify .Op Fl v .Op Fl x .Aq Fl n Ar nsid .Aq Ar device-id .Nm .Ic nsid .Aq Ar device-id | Ar namespace-id .Nm .Ic resv acquire .Aq Fl c Ar crkey .Op Fl p Ar prkey .Aq Fl t Ar rtype .Aq Fl a Ar racqa .Aq Ar namespace-id .Nm .Ic resv register .Op Fl i .Op Fl c Ar crkey .Aq Fl k Ar nrkey .Aq Fl r Ar rrega .Op Fl p Ar cptpl .Aq Ar namespace-id .Nm .Ic resv release .Aq Fl c Ar crkey .Aq Fl t Ar rtype .Aq Fl a Ar rrela .Aq Ar namespace-id .Nm .Ic resv report .Op Fl e .Op Fl v .Op Fl x .Aq Ar namespace-id .Nm .Ic firmware .Op Fl s Ar slot .Op Fl f Ar path_to_firmware .Op Fl a .Aq Ar device-id .Nm .Ic format .Op Fl f Ar fmt .Op Fl m Ar mset .Op Fl p Ar pi .Op Fl l Ar pil .Op Fl E .Op Fl C .Aq Ar device-id | Ar namespace-id .Nm .Ic sanitize .Aq Fl a Ar sanact .Op Fl c Ar owpass .Op Fl d .Op Fl p Ar ovrpat .Op Fl r .Op Fl I .Op Fl U .Aq Ar device-id .Nm .Ic power .Op Fl l .Op Fl p power_state .Op Fl w workload_hint .Nm .Ic selftest .Aq Fl c Ar code .Aq Ar device-id | Ar namespace-id .Nm .Ic wdc cap-diag .Op Fl o path_template .Aq Ar device-id .Nm .Ic wdc drive-log .Op Fl o path_template .Aq Ar device-id .Nm .Ic wdc get-crash-dump .Op Fl o path_template .Aq Ar device-id .\" .Nm .\" .Ic wdc purge .\" .Aq device-id .\" .Nm .\" .Ic wdc purge-monitor .\" .Aq device-id .Nm .Ic admin-passthru .Op args .Aq Ar device-id .Nm .Ic io-passthru .Op args .Aq Ar namespace-id .Nm .Ic discover .Op Fl v .Op Fl t Ar transport .Op Fl q Ar HostNQN .Nm .Ic connect .Op Fl FGg .Op Fl c Ar cntl-id .Op Fl i Ar queues .Op Fl k Ar seconds .Op Fl t Ar transport .Op Fl q Ar HostNQN .Op Fl Q Ar entries .Aq Ar address .Aq Ar SubNQN .Nm .Ic connect-all .Op Fl FGg .Op Fl i Ar queues .Op Fl k Ar seconds .Op Fl t Ar transport .Op Fl q Ar HostNQN .Op Fl Q Ar entries .Aq Ar address .Nm .Ic disconnect .Aq Ar device-id | Ar namespace-id | Ar SubNQN .Nm .Ic reconnect .Op Fl FGg .Op Fl i Ar queues .Op Fl k Ar seconds .Op Fl t Ar transport .Op Fl q Ar HostNQN .Op Fl Q Ar entries .Aq Ar device-id .Aq Ar address .Nm .Ic telemetry-log .Fl O Ar output-file .Op Fl d Ar data-area .Aq Ar device-id .Sh DESCRIPTION NVM Express (NVMe) is a storage protocol standard for SSDs and other high-speed storage devices over PCI Express as well as remote storage devices accessed via a network fabric. .Ss devlist List all NVMe controllers and namespaces along with their device nodes. With the .Fl h argument, use unit suffixes: Byte, Kibibyte, Mebibyte, Gibibyte, Tebibyte and Pebibyte (based on powers of 1024) when showing the disk space. By default, uses Mebibyte. .Ss identify The identify commands reports information from the drive's .Dv IDENTIFY_CONTROLLER if a .Ar device-id is specified. It reports .Dv IDENTIFY_NAMESPACE data if a .Ar namespace-id is specified. When used with disk names, the .Dv IDENTIFY_NAMESPACE data is reported, unless the namespace .Ar nsid is overridden with the .Fl n flag. Then that namespace's data is reported, if it exists. The command accepts the following parameters: .Bl -tag -width 6n .It Fl n The namespace .Aq nsid to use instead of the namespace associated with the device. A .Ar nsid of .Dq 0 is used to retrieve the .Dv IDENTIFY_CONTROLLER data associated with that drive. .El .Ss logpage The logpage command knows how to print log pages of various types. It also knows about vendor specific log pages from hgst/wdc, samsung and intel. Note that some vendors use the same log page numbers for different data. .Pp .Bl -tag -compact -width "Page 0x00" .It Dv Page 0x01 Drive Error Log .It Dv Page 0x02 Health/SMART Data .It Dv Page 0x03 Firmware Information .It Dv Page 0x04 Changed Namespace List .It Dv Page 0x05 Commands Supported and Effects .It Dv Page 0x06 Device Self-test .It Dv Page 0x80 Reservation Notification .It Dv Page 0x81 Sanitize Status .It Dv Page 0xc1 Advanced SMART information (WDC/HGST) .It Dv Page 0xc1 Read latency stats (Intel) .It Dv Page 0xc2 Wite latency stats (Intel) .It Dv Page 0xc5 Temperature stats (Intel) .It Dv Page 0xca Advanced SMART information (Intel) .It Dv Page 0xca Extended SMART information (Samsung) .El .Pp Specifying .Fl v .Ic help will list all valid vendors and pages. .Fl x will print the page as hex. .Fl b will print the binary data for the page. .Fl s will set Log Specific Field. .Fl i will set Log Specific Identifier. .Fl r will set Retain Asynchronous Event. .Ss ns Various namespace management commands. If namespace management is supported by device, allow list, create and delete namespaces, list, attach and detach controllers to namespaces. Each NVM device consists of one or more NVM subsystems. Each NVM subsystem has one or more NVM ports. Each NVM port is attached to one or more NVM controllers (though typically 1). Each NVM controller is attached to one or more namespaces. .Pp After a namespace is created, it is considered .Dq allocated . All namespaces that have not been created are unallocated. An allocated namespace may be active or inactive. An active namespace is attached to the controller and may be interacted with. A namespace can move from active to inactive when detached. An allocated namespace may be deleted to become unallocated. For more details on the nuances of NVM namespaces, please see section 2 .Em Theory of Operation and section 3 .Em NVM Express Architecture of the latest NVM standard. .Ss ns active Provide a list of active namespace identifiers for the givne NVM controller. .Ss ns allocated Provide a list of allocated namespace identifiers for the givne NVM controller. .Ss ns attach Attach an nsid to a controller. The primary controller is used if one is not specified. .Ss ns attached Provide a list of controllers attached to a nsid. If only a nvme controller argument is provided, a nsid must also be specified. .Ss ns controllers Provide a list of all controllers in the NVM subsystem. .Ss ns create Creates a new namespace. .Ss ns delete Delete a namespace. It must be currently inactive. .Ss ns detach Detach a namespace from a controller. The namespace will become inaccessible, but its contents will remain if it is .Em activated again. .Ss ns identify Print detailed information about the namespace. .Ss nsid Reports the namespace id and controller device associated with the .Aq Ar namespace-id or .Aq Ar device-id argument. .Ss resv acquire Acquire or preempt namespace reservation, using specified parameters: .Bl -tag -width 6n .It Fl a Acquire action: .Bl -tag -compact -width 6n .It Dv 0 Acquire .It Dv 1 Preempt .It Dv 2 Preempt and abort .El .It Fl c Current reservation key. .It Fl p Preempt reservation key. .It Fl t Reservation type: .Bl -tag -compact -width 6n .It Dv 1 Write Exclusive .It Dv 2 Exclusive Access .It Dv 3 Write Exclusive - Registrants Only .It Dv 4 Exclusive Access - Registrants Only .It Dv 5 Write Exclusive - All Registrants .It Dv 6 Exclusive Access - All Registrants .El .El .Ss resv register Register, unregister or replace reservation key, using specified parameters: .Bl -tag -width 6n .It Fl c Current reservation key. .It Fl k New reservation key. .It Fl r Register action: .Bl -tag -compact -width 6n .It Dv 0 Register .It Dv 1 Unregister .It Dv 2 Replace .El .It Fl i Ignore Existing Key .It Fl p Change Persist Through Power Loss State: .Bl -tag -compact -width 6n .It Dv 0 No change to PTPL state .It Dv 2 Set PTPL state to ‘0’. Reservations are released and registrants are cleared on a power on. .It Dv 3 Set PTPL state to ‘1’. Reservations and registrants persist across a power loss. .El .El .Ss resv release Release or clear reservation, using specified parameters: .Bl -tag -width 6n .It Fl c Current reservation key. .It Fl t Reservation type. .It Fl a Release action: .Bl -tag -compact -width 6n .It Dv 0 Release .It Dv 1 Clean .El .El .Ss resv report Print reservation status, using specified parameters: .Bl -tag -width 6n .It Fl x Print reservation status in hex. .It Fl e Use Extended Data Structure. .El .Ss format Format either specified namespace, or all namespaces of specified controller, using specified parameters: .Bl -tag -width 8n .It Fl f Ar fmt The index .Ar fmt of the parameters to use. LBA Format #, as specified in the identification of the namespace using .Dq nvmecontrol identify command with a namespace specified maps this index into these parameters. .It Fl m Ar mset Metadata Setting. .Ar mset .Bl -tag -compact -width 6n .It Dv 0 do not transfer metadata with LBA information .It Dv 1 Transfer the metadata as part of the extended LBA information. .El .It Fl p Ar pi Protection Information. .Bl -tag -compact -width 6n .It Dv 0 Protection Information not enabled. .It Dv 1 Type 1 information protection enabled. .It Dv 2 Type 2 information protection enabled. .It Dv 3 Type 3 information protection enabled. .El .It Fl l Ar pil Protection Information Location. .Bl -tag -compact -width 6n .It Dv 0 Transfer the protection metadata as the last N bytes of the transfer. .It Dv 1 Transfer the protection metadata as the first N bytes of the transfer. .El .It Fl E Enables User Data Erase during format. All users data is erased and subsequent reads are indeterminate. The drive may implement this as a cryptographic erase or it may physically erase the underlying media. .It Fl C Enables Cryptographic Erase during format. All user data is erased cryptographically by deleting the encryption key, rendering it unintelligible. .El .Pp When formatting specific namespace, existing values are used as defaults. When formatting all namespaces, all parameters should be specified. Some controllers may not support formatting or erasing specific or all namespaces. The .Xr nvme 4 driver does not currently support metadata and protection information transfers. .Ss sanitize Sanitize NVM subsystem of specified controller, using specified parameters: .Bl -tag -width 6n .It Fl a Ar operation Specify the sanitize operation to perform. .Bl -tag -width 16n .It overwrite Perform an overwrite operation by writing a user supplied data pattern to the device one or more times. The pattern is given by the .Fl p argument. The number of times is given by the .Fl c argument. .It block Perform a block erase operation. All the device's blocks are set to a vendor defined value, typically zero. .It crypto Perform a cryptographic erase operation. The encryption keys are changed to prevent the decryption of the data. .It exitfailure Exits a previously failed sanitize operation. A failed sanitize operation can only be exited if it was run in the unrestricted completion mode, as provided by the .Fl U argument. .It 1, 2, 3, 4 nvme-cli compatible .Fl a values for .Dq exitfailure , .Dq block , .Dq overwrite , and .Dq crypto respectively. .El .It Fl c Ar passes The number of passes when performing an .Sq overwrite operation. Valid values are between 1 and 16. The default is 1. .It Fl d No Deallocate After Sanitize. .It Fl I When performing an .Sq overwrite operation, the pattern is inverted between consecutive passes. .It Fl p Ar pattern 32 bits of pattern to use when performing an .Sq overwrite operation. The pattern is repeated as needed to fill each block. .It Fl U Perform the sanitize in the unrestricted completion mode. If the operation fails, it can later be exited with the .Sq exitfailure operation. .It Fl r Run in .Dq report only mode. This will report status on a sanitize that is already running on the drive. .El .Ss power Manage the power modes of the NVMe controller. .Bl -tag -width 6n .It Fl l List all supported power modes. .It Fl p Ar mode Set the power mode to .Ar mode . This must be a mode listed with the .Dl nvmecontrol power -l command. .It Fl w Ar hint Set the workload hint for automatic power mode control. .Bl -tag -compact -width 6n .It 0 No workload hint is provided. .It 1 Extended idle period workload. The device is often idle for minutes at a time. A burst of write commands comes in over a period of seconds. Then the device returns to being idle. .It 2 Heavy sequential writes. A huge number of sequential writes will be submitted, filling the submission queues. .It Other All other values are reserved and have no standard meaning. .El Please see the .Dq NVM Subsystem Workloads section of the relevant NVM Express Base Standard for details. .El .Ss selftest Start the specified device self-test: .Bl -tag -width 6n .It Fl c Ar code Specify the device self-test command code. Common codes are: .Bl -tag -compact -width 6n .It Dv 0x1 Start a short device self-test operation .It Dv 0x2 Start an extended device self-test operation .It Dv 0xe Start a vendor specific device self-test operation .It Dv 0xf Abort the device self-test operation .El .El .Ss wdc The various wdc command retrieve log data from the wdc/hgst drives. The .Fl o flag specifies a path template to use to output the files. Each file takes the path template (which defaults to nothing), appends the drive's serial number and the type of dump it is followed by .bin. These logs must be sent to the vendor for analysis. This tool only provides a way to extract them. .Ss passthru The .Dq admin-passthru and .Dq io-passthru commands send NVMe commands to either the administrative or the data part of the device. These commands are expected to be compatible with nvme-cli. Please see the NVM Express Base Standard for details. .Bl -tag -width 16n .It Fl o -opcode Ar opcode Opcode to send. .It Fl 2 -cdw2 Ar value 32-bit value for CDW2. .It Fl 3 -cdw3 Ar value 32-bit value for CDW3. .It Fl 4 -cdw10 Ar value 32-bit value for CDW10. .It Fl 5 -cdw11 Ar value 32-bit value for CDW11. .It Fl 6 -cdw12 Ar value 32-bit value for CDW12. .It Fl 7 -cdw13 Ar value 32-bit value for CDW13. .It Fl 8 -cdw14 Ar value 32-bit value for CDW14. .It Fl 9 -cdw15 Ar value 32-bit value for CDW15. .It Fl l -data-len Length of the data for I/O (bytes). .It Fl m -metadata-len Length of the metadata segment for command (bytes). This is ignored and not implemented in .Xr nvme 4 . .It Fl f -flags Nvme command flags. .It Fl n -namespace-id Namespace ID for command (Ignored). .It Fl p -prefill Value to prefill payload with. .It Fl b -raw-binary Output in binary format (otherwise a hex dump is produced). .It Fl d -dry-run Do not actually execute the command, but perform sanity checks on it. .It Fl r -read Command reads data from the device. .It Fl s -show-command Show all the command values on stdout. .It Fl w -write Command writes data to the device. .El .Pp Send arbitrary commands to the device. Can be used to extract vendor specific logs. Transfers to/from the device possible, but limited to .Dv MAXPHYS bytes. Commands either read data or write it, but not both. Commands needing metadata are not supported by the .Xr nvme 4 drive. .Ss discover List the remote controllers advertised by a remote Discovery Controller: .Bl -tag -width 6n .It Fl t Ar transport Transport to use. The default is .It Fl q Ar HostNQN NVMe Qualified Name to use for this host. By default an NQN is auto-generated from the current host's UUID. .Ar tcp . .It Fl v Display the .Dv IDENTIFY_CONTROLLER data for the Discovery Controller. .El .Ss connect Establish an association with the I/O controller named .Ar SubNQN at .Ar address . The address must include a port. .Pp An admin queue pair and one or more I/O queue pairs are created and handed off to the kernel to create a new controller device. .Bl -tag -width 6n .It Fl c Ar cntl-id Remote controller ID to request: .Bl -tag .It dynamic Request a dynamic controller ID for controllers using the dynamic controller model. This is the default. .It static Request a dynamic controller ID for controllers using the static controller model. .It Ar number Request a specific controller ID for controllers using the static controller model. .El .It Fl F Request submission queue flow control. By default submission queue flow control is disabled unless the remote controller requires it. .It Fl g Enable TCP PDU header digests. .It Fl G Enable TCP PDU data digests. .It Fl i Ar queues Number of I/O queue pairs to create. The default is 1. .It Fl k Ar seconds Keep Alive timer duration in seconds. The default is 120. .It Fl t Ar transport Transport to use. The default is .Ar tcp . .It Fl q Ar HostNQN NVMe Qualified Name to use for this host. By default an NQN is auto-generated from the current host's UUID. .It Fl Q Ar entries Number of entries in each I/O queue. By default the maximum queue size reported by the MQES field of the remote host's CAP property is used. .El .Ss connect-all Query the Discovery Controller at .Ar address and establish an association for each advertised I/O controller. The .Fl t flag determines the transport used for the initial association with the Discovery Controller and defaults to .Ar tcp . All other flags are used to control properties of each I/O assocation as described above for the .Cm connect command. .Ss disconnect Delete the controller device associated with a remote I/O controller including any active association and open queues. .Ss reconnect Reestablish an association for the remote I/O controller associated with .Ar device-id at .Ar address . The address must include a port. The flags have the same meaning for the new association as described above for the .Cm connect command. .Ss telemetry-log -Extract the telemetry log associated with +Extract the telemetry log associated with .Ar device-id , using the specified parameters: .Bl -tag -width 6n .It Fl O Ar output-file Output file for the data. This parameter is mandatory. .It Fl d Ar data-area The data area is either 1, 2 or 3. .El .Sh DEVICE NAMES Where .Aq Ar namespace-id is required, you can use either the .Pa nvmeXnsY device, or the disk device such as .Pa ndaZ or .Pa nvdZ . The leading .Pa /dev/ may be omitted. Where .Aq Ar device-id is required, you can use either the .Pa nvmeX device, or the disk device such as .Pa ndaZ or .Pa nvdZ . For commands that take an optional .Aq nsid you can use it to get information on other namespaces, or to query the drive itself. A .Aq nsid of .Dq 0 means query the drive itself. .Sh FABRICS TRANSPORTS The following NVM Express over Fabrics transports are supported for accessing remote controllers: .Bl -tag .It tcp TCP transport .El .Sh NETWORK ADDRESSES Network addresses for remote controllers can use one of the following formats: .Bl -bullet .It .Bq Ar IPv6 address .Ns : Ns Ar port .It .Ar IPv4 address .Ns : Ns Ar port .It .Ar hostname Ns : Ns Ar port .It .Bq Ar IPv6 address .It .Ar IPv6 address .It .Ar IPv4 address .It .Ar hostname .El .Pp If a .Ar port is not provided, a default value is used if possible. .Sh EXAMPLES .Dl nvmecontrol devlist .Pp Display a list of NVMe controllers and namespaces along with their device nodes. .Pp .Dl nvmecontrol identify nvme0 .Dl nvmecontrol identify -n 0 nvd0 .Pp Display a human-readable summary of the nvme0 .Dv IDENTIFY_CONTROLLER data. In this example, nvd0 is connected to nvme0. .Pp .Dl nvmecontrol identify -x -v nvme0ns1 .Dl nvmecontrol identify -x -v -n 1 nvme0 .Pp Display an hexadecimal dump of the nvme0 .Dv IDENTIFY_NAMESPACE data for namespace 1. .Pp .Dl nvmecontrol perftest -n 32 -o read -s 512 -t 30 nvme0ns1 .Pp Run a performance test on nvme0ns1 using 32 kernel threads for 30 seconds. Each thread will issue a single 512 byte read command. Results are printed to stdout when 30 seconds expires. .Pp .Dl nvmecontrol reset nvme0 .Dl nvmecontrol reset nda4 .Pp Perform a controller-level reset of the nvme0 controller. In this example, nda4 is wired to nvme0. .Pp .Dl nvmecontrol logpage -p 1 nvme0 .Pp Display a human-readable summary of the nvme0 controller's Error Information Log. Log pages defined by the NVMe specification include Error Information Log (ID=1), SMART/Health Information Log (ID=2), and Firmware Slot Log (ID=3). .Pp .Dl nvmecontrol logpage -p 0xc1 -v wdc nvme0 .Pp Display a human-readable summary of the nvme0's wdc-specific advanced SMART data. .Pp .Dl nvmecontrol logpage -p 1 -x nvme0 .Pp Display a hexadecimal dump of the nvme0 controller's Error Information Log. .Pp .Dl nvmecontrol logpage -p 0xcb -b nvme0 > /tmp/page-cb.bin .Pp Print the contents of vendor specific page 0xcb as binary data on standard out. Redirect it to a temporary file. .Pp .Dl nvmecontrol firmware -s 2 -f /tmp/nvme_firmware nvme0 .Pp Download the firmware image contained in "/tmp/nvme_firmware" to slot 2 of the nvme0 controller, but do not activate the image. .Pp .Dl nvmecontrol firmware -s 4 -a nvme0 .Pp Activate the firmware in slot 4 of the nvme0 controller on the next reset. .Pp .Dl nvmecontrol firmware -s 7 -f /tmp/nvme_firmware -a nvme0 .Pp Download the firmware image contained in "/tmp/nvme_firmware" to slot 7 of the nvme0 controller and activate it on the next reset. .Pp .Dl nvmecontrol power -l nvme0 .Pp List all the current power modes. .Pp .Dl nvmecontrol power -p 3 nvme0 .Pp Set the current power mode. .Pp .Dl nvmecontrol power nvme0 .Pp Get the current power mode. .Pp .Dl nvmecontrol identify -n 0 nda0 .Pp Identify the drive data associated with the .Pa nda0 device. The corresponding .Pa nvmeX devices is used automatically. .Pp .Dl nvmecontrol identify nda0 .Pp Get the namespace parameters associated with the .Pa nda0 device. The corresponding .Pa nvmeXnsY device is used automatically. .Pp .Dl nvmecontrol format -f 2 -m 0 -p 0 -l 0 -C nvme2 .Pp Format all the name spaces on nvme2 using parameters from .Dq LBA Format #2 with no metadata or protection data using cryptographic erase. If the .Dq nvmecontrol identify -n 1 nvme2 command ended with .Pp .Bd -literal LBA Format #00: Data Size: 512 Metadata Size: 0 Performance: Good LBA Format #01: Data Size: 512 Metadata Size: 8 Performance: Good LBA Format #02: Data Size: 4096 Metadata Size: 0 Performance: Good LBA Format #03: Data Size: 4096 Metadata Size: 8 Performance: Good LBA Format #04: Data Size: 4096 Metadata Size: 64 Performance: Good .Ed .Pp then this would give a 4k data format for at least namespace 1, with no metadata. .Pp .Sh DYNAMIC LOADING The directories .Pa /lib/nvmecontrol and .Pa /usr/local/lib/nvmecontrol are scanned for any .so files. These files are loaded. The members of the .Va top linker set are added to the top-level commands. The members of the .Va logpage linker set are added to the logpage parsers. .Sh SEE ALSO .Rs .%T The NVM Express Base Specification .%D June 10, 2019 .%U https://nvmexpress.org/wp-content/uploads/NVM-Express-1_4-2019.06.10-Ratified.pdf .Re .Sh HISTORY The .Nm utility appeared in .Fx 9.2 . .Sh AUTHORS .An -nosplit .Nm was developed by Intel and originally written by .An Jim Harris Aq Mt jimharris@FreeBSD.org . .Pp This man page was written by .An Jim Harris Aq Mt jimharris@FreeBSD.org . diff --git a/secure/lib/libcrypto/man/man3/OSSL_DECODER_CTX.3 b/secure/lib/libcrypto/man/man3/OSSL_DECODER_CTX.3 index ba3a05e6902c..f5b730f40096 100644 --- a/secure/lib/libcrypto/man/man3/OSSL_DECODER_CTX.3 +++ b/secure/lib/libcrypto/man/man3/OSSL_DECODER_CTX.3 @@ -1,379 +1,379 @@ .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "OSSL_DECODER_CTX 3ossl" .TH OSSL_DECODER_CTX 3ossl "2023-09-19" "3.0.11" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" OSSL_DECODER_CTX, OSSL_DECODER_CTX_new, OSSL_DECODER_settable_ctx_params, OSSL_DECODER_CTX_set_params, OSSL_DECODER_CTX_free, OSSL_DECODER_CTX_set_selection, OSSL_DECODER_CTX_set_input_type, OSSL_DECODER_CTX_set_input_structure, OSSL_DECODER_CTX_add_decoder, OSSL_DECODER_CTX_add_extra, OSSL_DECODER_CTX_get_num_decoders, OSSL_DECODER_INSTANCE, OSSL_DECODER_CONSTRUCT, OSSL_DECODER_CLEANUP, OSSL_DECODER_CTX_set_construct, OSSL_DECODER_CTX_set_construct_data, OSSL_DECODER_CTX_set_cleanup, OSSL_DECODER_CTX_get_construct, OSSL_DECODER_CTX_get_construct_data, OSSL_DECODER_CTX_get_cleanup, OSSL_DECODER_export, OSSL_DECODER_INSTANCE_get_decoder, OSSL_DECODER_INSTANCE_get_decoder_ctx, OSSL_DECODER_INSTANCE_get_input_type, OSSL_DECODER_INSTANCE_get_input_structure \&\- Decoder context routines .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include \& \& typedef struct ossl_decoder_ctx_st OSSL_DECODER_CTX; \& \& OSSL_DECODER_CTX *OSSL_DECODER_CTX_new(void); \& const OSSL_PARAM *OSSL_DECODER_settable_ctx_params(OSSL_DECODER *decoder); \& int OSSL_DECODER_CTX_set_params(OSSL_DECODER_CTX *ctx, \& const OSSL_PARAM params[]); \& void OSSL_DECODER_CTX_free(OSSL_DECODER_CTX *ctx); \& \& int OSSL_DECODER_CTX_set_selection(OSSL_DECODER_CTX *ctx, int selection); \& int OSSL_DECODER_CTX_set_input_type(OSSL_DECODER_CTX *ctx, \& const char *input_type); \& int OSSL_DECODER_CTX_set_input_structure(OSSL_DECODER_CTX *ctx, \& const char *input_structure); \& int OSSL_DECODER_CTX_add_decoder(OSSL_DECODER_CTX *ctx, OSSL_DECODER *decoder); -\& int OSSL_DECODER_CTX_add_extra(OSSL_DECODER_CTX *ctx, -\& OSSL_LIB_CTX *libctx, +\& int OSSL_DECODER_CTX_add_extra(OSSL_DECODER_CTX *ctx, +\& OSSL_LIB_CTX *libctx, \& const char *propq); \& int OSSL_DECODER_CTX_get_num_decoders(OSSL_DECODER_CTX *ctx); \& \& typedef struct ossl_decoder_instance_st OSSL_DECODER_INSTANCE; \& OSSL_DECODER * \& OSSL_DECODER_INSTANCE_get_decoder(OSSL_DECODER_INSTANCE *decoder_inst); \& void * \& OSSL_DECODER_INSTANCE_get_decoder_ctx(OSSL_DECODER_INSTANCE *decoder_inst); \& const char * \& OSSL_DECODER_INSTANCE_get_input_type(OSSL_DECODER_INSTANCE *decoder_inst); \& OSSL_DECODER_INSTANCE_get_input_structure(OSSL_DECODER_INSTANCE *decoder_inst, \& int *was_set); \& \& typedef int OSSL_DECODER_CONSTRUCT(OSSL_DECODER_INSTANCE *decoder_inst, \& const OSSL_PARAM *object, \& void *construct_data); \& typedef void OSSL_DECODER_CLEANUP(void *construct_data); \& \& int OSSL_DECODER_CTX_set_construct(OSSL_DECODER_CTX *ctx, \& OSSL_DECODER_CONSTRUCT *construct); \& int OSSL_DECODER_CTX_set_construct_data(OSSL_DECODER_CTX *ctx, \& void *construct_data); \& int OSSL_DECODER_CTX_set_cleanup(OSSL_DECODER_CTX *ctx, \& OSSL_DECODER_CLEANUP *cleanup); \& OSSL_DECODER_CONSTRUCT *OSSL_DECODER_CTX_get_construct(OSSL_DECODER_CTX *ctx); \& void *OSSL_DECODER_CTX_get_construct_data(OSSL_DECODER_CTX *ctx); \& OSSL_DECODER_CLEANUP *OSSL_DECODER_CTX_get_cleanup(OSSL_DECODER_CTX *ctx); \& \& int OSSL_DECODER_export(OSSL_DECODER_INSTANCE *decoder_inst, \& void *reference, size_t reference_sz, \& OSSL_CALLBACK *export_cb, void *export_cbarg); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \fB\s-1OSSL_DECODER_CTX\s0\fR holds data about multiple decoders, as needed to figure out what the input data is and to attempt to unpack it into one of several possible related results. This also includes chaining decoders, so the output from one can become the input for another. This allows having generic format decoders such as \s-1PEM\s0 to \s-1DER,\s0 as well as more specialized decoders like \s-1DER\s0 to \s-1RSA.\s0 .PP The chains may be limited by specifying an input type, which is considered a starting point. This is both considered by \fBOSSL_DECODER_CTX_add_extra()\fR, which will stop adding one more decoder implementations when it has already added those that take the specified input type, and functions like \&\fBOSSL_DECODER_from_bio\fR\|(3), which will only start the decoding process with the decoder implementations that take that input type. For example, if the input type is set to \f(CW\*(C`DER\*(C'\fR, a \s-1PEM\s0 to \s-1DER\s0 decoder will be ignored. .PP The input type can also be \s-1NULL,\s0 which means that the caller doesn't know what type of input they have. In this case, \fBOSSL_DECODER_from_bio()\fR will simply try with one decoder implementation after the other, and thereby discover what kind of input the caller gave it. .PP For every decoding done, even an intermediary one, a constructor provided by the caller is called to attempt to construct an appropriate type / structure that the caller knows how to handle from the current decoding result. The constructor is set with \fBOSSL_DECODER_CTX_set_construct()\fR. .PP \&\fB\s-1OSSL_DECODER_INSTANCE\s0\fR is an opaque structure that contains data about the decoder that was just used, and that may be useful for the constructor. There are some functions to extract data from this type, described further down. .SS "Functions" .IX Subsection "Functions" \&\fBOSSL_DECODER_CTX_new()\fR creates a new empty \fB\s-1OSSL_DECODER_CTX\s0\fR. .PP \&\fBOSSL_DECODER_settable_ctx_params()\fR returns an \s-1\fBOSSL_PARAM\s0\fR\|(3) array of parameter descriptors. .PP \&\fBOSSL_DECODER_CTX_set_params()\fR attempts to set parameters specified with an \&\s-1\fBOSSL_PARAM\s0\fR\|(3) array \fIparams\fR. These parameters are passed to all decoders that have been added to the \fIctx\fR so far. Parameters that an implementation doesn't recognise should be ignored by it. .PP \&\fBOSSL_DECODER_CTX_free()\fR frees the given context \fIctx\fR. .PP \&\fBOSSL_DECODER_CTX_add_decoder()\fR populates the \fB\s-1OSSL_DECODER_CTX\s0\fR \fIctx\fR with a decoder, to be used to attempt to decode some encoded input. .PP \&\fBOSSL_DECODER_CTX_add_extra()\fR finds decoders that generate input for already added decoders, and adds them as well. This is used to build decoder chains. .PP \&\fBOSSL_DECODER_CTX_set_input_type()\fR sets the starting input type. This limits the decoder chains to be considered, as explained in the general description above. .PP \&\fBOSSL_DECODER_CTX_set_input_structure()\fR sets the name of the structure that the input is expected to have. This may be used to determines what decoder implementations may be used. \s-1NULL\s0 is a valid input structure, when it's not relevant, or when the decoder implementations are expected to figure it out. .PP \&\fBOSSL_DECODER_CTX_get_num_decoders()\fR gets the number of decoders currently added to the context \fIctx\fR. .PP \&\fBOSSL_DECODER_CTX_set_construct()\fR sets the constructor \fIconstruct\fR. .PP \&\fBOSSL_DECODER_CTX_set_construct_data()\fR sets the constructor data that is passed to the constructor every time it's called. .PP \&\fBOSSL_DECODER_CTX_set_cleanup()\fR sets the constructor data \fIcleanup\fR function. This is called by \fBOSSL_DECODER_CTX_free\fR\|(3). .PP \&\fBOSSL_DECODER_CTX_get_construct()\fR, \fBOSSL_DECODER_CTX_get_construct_data()\fR and \&\fBOSSL_DECODER_CTX_get_cleanup()\fR return the values that have been set by \&\fBOSSL_DECODER_CTX_set_construct()\fR, \fBOSSL_DECODER_CTX_set_construct_data()\fR and \&\fBOSSL_DECODER_CTX_set_cleanup()\fR respectively. .PP \&\fBOSSL_DECODER_export()\fR is a fallback function for constructors that cannot use the data they get directly for diverse reasons. It takes the same decode instance \fIdecoder_inst\fR that the constructor got and an object \&\fIreference\fR, unpacks the object which it refers to, and exports it by creating an \s-1\fBOSSL_PARAM\s0\fR\|(3) array that it then passes to \fIexport_cb\fR, along with \fIexport_arg\fR. .SS "Constructor" .IX Subsection "Constructor" A \fB\s-1OSSL_DECODER_CONSTRUCT\s0\fR gets the following arguments: .IP "\fIdecoder_inst\fR" 4 .IX Item "decoder_inst" The \fB\s-1OSSL_DECODER_INSTANCE\s0\fR for the decoder from which the constructor gets its data. .IP "\fIobject\fR" 4 .IX Item "object" A provider-native object abstraction produced by the decoder. Further information on the provider-native object abstraction can be found in \&\fBprovider\-object\fR\|(7). .IP "\fIconstruct_data\fR" 4 .IX Item "construct_data" The pointer that was set with \fBOSSL_DECODE_CTX_set_construct_data()\fR. .PP The constructor is expected to return 1 when the data it receives can be constructed, otherwise 0. .PP These utility functions may be used by a constructor: .PP \&\fBOSSL_DECODER_INSTANCE_get_decoder()\fR can be used to get the decoder implementation from a decoder instance \fIdecoder_inst\fR. .PP \&\fBOSSL_DECODER_INSTANCE_get_decoder_ctx()\fR can be used to get the decoder implementation's provider context from a decoder instance \fIdecoder_inst\fR. .PP \&\fBOSSL_DECODER_INSTANCE_get_input_type()\fR can be used to get the decoder implementation's input type from a decoder instance \fIdecoder_inst\fR. .PP \&\fBOSSL_DECODER_INSTANCE_get_input_structure()\fR can be used to get the input structure for the decoder implementation from a decoder instance \&\fIdecoder_inst\fR. This may be \s-1NULL.\s0 .SH "RETURN VALUES" .IX Header "RETURN VALUES" \&\fBOSSL_DECODER_CTX_new()\fR returns a pointer to a \fB\s-1OSSL_DECODER_CTX\s0\fR, or \s-1NULL\s0 if the context structure couldn't be allocated. .PP \&\fBOSSL_DECODER_settable_ctx_params()\fR returns an \s-1\fBOSSL_PARAM\s0\fR\|(3) array, or \&\s-1NULL\s0 if none is available. .PP \&\fBOSSL_DECODER_CTX_set_params()\fR returns 1 if all recognised parameters were valid, or 0 if one of them was invalid or caused some other failure in the implementation. .PP \&\fBOSSL_DECODER_CTX_add_decoder()\fR, \fBOSSL_DECODER_CTX_add_extra()\fR, \&\fBOSSL_DECODER_CTX_set_construct()\fR, \fBOSSL_DECODER_CTX_set_construct_data()\fR and \&\fBOSSL_DECODER_CTX_set_cleanup()\fR return 1 on success, or 0 on failure. .PP \&\fBOSSL_DECODER_CTX_get_construct()\fR, \fBOSSL_DECODER_CTX_get_construct_data()\fR and \&\fBOSSL_DECODER_CTX_get_cleanup()\fR return the current pointers to the constructor, the constructor data and the cleanup functions, respectively. .PP \&\fBOSSL_DECODER_CTX_num_decoders()\fR returns the current number of decoders. It returns 0 if \fIctx\fR is \s-1NULL.\s0 .PP \&\fBOSSL_DECODER_export()\fR returns 1 on success, or 0 on failure. .PP \&\fBOSSL_DECODER_INSTANCE_decoder()\fR returns an \fB\s-1OSSL_DECODER\s0\fR pointer on success, or \s-1NULL\s0 on failure. .PP \&\fBOSSL_DECODER_INSTANCE_decoder_ctx()\fR returns a provider context pointer on success, or \s-1NULL\s0 on failure. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBprovider\fR\|(7), \s-1\fBOSSL_DECODER\s0\fR\|(3), \fBOSSL_DECODER_from_bio\fR\|(3) .SH "HISTORY" .IX Header "HISTORY" The functions described here were added in OpenSSL 3.0. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved. .PP Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy in the file \s-1LICENSE\s0 in the source distribution or at . diff --git a/secure/lib/libcrypto/man/man3/SSL_set_retry_verify.3 b/secure/lib/libcrypto/man/man3/SSL_set_retry_verify.3 index fcc1c53cb096..489a4ff5423e 100644 --- a/secure/lib/libcrypto/man/man3/SSL_set_retry_verify.3 +++ b/secure/lib/libcrypto/man/man3/SSL_set_retry_verify.3 @@ -1,199 +1,199 @@ .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "SSL_SET_RETRY_VERIFY 3ossl" .TH SSL_SET_RETRY_VERIFY 3ossl "2023-09-19" "3.0.11" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" SSL_set_retry_verify \- indicate that certificate verification should be retried .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include \& \& int SSL_set_retry_verify(SSL *ssl); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBSSL_set_retry_verify()\fR should be called from the certificate verification callback on a client when the application wants to indicate that the handshake should be suspended and the control should be returned to the application. \&\fBSSL_want_retry_verify\fR\|(3) will return 1 as a consequence until the handshake is resumed again by the application, retrying the verification step. .PP Please refer to \fBSSL_CTX_set_cert_verify_callback\fR\|(3) for further details. .SH "NOTES" .IX Header "NOTES" The effect of calling \fBSSL_set_retry_verify()\fR outside of the certificate verification callback on the client side is undefined. .SH "RETURN VALUES" .IX Header "RETURN VALUES" SSL_set_retry \fBverify()\fR returns 1 on success, 0 otherwise. .SH "EXAMPLES" .IX Header "EXAMPLES" The following code snippet shows how to obtain the \fB\s-1SSL\s0\fR object associated with the \fBX509_STORE_CTX\fR to call the \fBSSL_set_retry_verify()\fR function: .PP .Vb 2 \& int idx = SSL_get_ex_data_X509_STORE_CTX_idx(); \& SSL *ssl; \& \& /* this should not happen but check anyway */ \& if (idx < 0 -\& || (ssl = X509_STORE_CTX_get_ex_data(ctx, idx)) == NULL) +\& || (ssl = X509_STORE_CTX_get_ex_data(ctx, idx)) == NULL) \& return 0; \& \& if (/* we need to retry verification callback */) \& return SSL_set_retry_verify(ssl); \& \& /* do normal processing of the verification callback */ .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBssl\fR\|(7), \fBSSL_connect\fR\|(3), \fBSSL_CTX_set_cert_verify_callback\fR\|(3), \&\fBSSL_want_retry_verify\fR\|(3) .SH "HISTORY" .IX Header "HISTORY" \&\fBSSL_set_retry_verify()\fR was added in OpenSSL 3.0.2 to replace backwards incompatible handling of a negative return value from the verification callback. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2022 The OpenSSL Project Authors. All Rights Reserved. .PP Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy in the file \s-1LICENSE\s0 in the source distribution or at . diff --git a/secure/lib/libcrypto/man/man3/X509_LOOKUP.3 b/secure/lib/libcrypto/man/man3/X509_LOOKUP.3 index 0cde28cae042..ce29dfe232c4 100644 --- a/secure/lib/libcrypto/man/man3/X509_LOOKUP.3 +++ b/secure/lib/libcrypto/man/man3/X509_LOOKUP.3 @@ -1,359 +1,359 @@ .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "X509_LOOKUP 3ossl" .TH X509_LOOKUP 3ossl "2023-09-19" "3.0.11" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" X509_LOOKUP, X509_LOOKUP_TYPE, X509_LOOKUP_new, X509_LOOKUP_free, X509_LOOKUP_init, X509_LOOKUP_shutdown, X509_LOOKUP_set_method_data, X509_LOOKUP_get_method_data, X509_LOOKUP_ctrl_ex, X509_LOOKUP_ctrl, X509_LOOKUP_load_file_ex, X509_LOOKUP_load_file, X509_LOOKUP_add_dir, X509_LOOKUP_add_store_ex, X509_LOOKUP_add_store, X509_LOOKUP_load_store_ex, X509_LOOKUP_load_store, X509_LOOKUP_get_store, X509_LOOKUP_by_subject_ex, X509_LOOKUP_by_subject, X509_LOOKUP_by_issuer_serial, X509_LOOKUP_by_fingerprint, X509_LOOKUP_by_alias \&\- OpenSSL certificate lookup mechanisms .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include \& \& typedef x509_lookup_st X509_LOOKUP; \& \& typedef enum X509_LOOKUP_TYPE; \& \& X509_LOOKUP *X509_LOOKUP_new(X509_LOOKUP_METHOD *method); \& int X509_LOOKUP_init(X509_LOOKUP *ctx); \& int X509_LOOKUP_shutdown(X509_LOOKUP *ctx); \& void X509_LOOKUP_free(X509_LOOKUP *ctx); \& \& int X509_LOOKUP_set_method_data(X509_LOOKUP *ctx, void *data); \& void *X509_LOOKUP_get_method_data(const X509_LOOKUP *ctx); \& \& int X509_LOOKUP_ctrl_ex(X509_LOOKUP *ctx, int cmd, const char *argc, long argl, \& char **ret, OSSL_LIB_CTX *libctx, const char *propq); \& int X509_LOOKUP_ctrl(X509_LOOKUP *ctx, int cmd, const char *argc, \& long argl, char **ret); \& int X509_LOOKUP_load_file_ex(X509_LOOKUP *ctx, char *name, long type, \& OSSL_LIB_CTX *libctx, const char *propq); \& int X509_LOOKUP_load_file(X509_LOOKUP *ctx, char *name, long type); \& int X509_LOOKUP_load_file_ex(X509_LOOKUP *ctx, char *name, long type, \& OSSL_LIB_CTX *libctx, const char *propq); \& int X509_LOOKUP_add_dir(X509_LOOKUP *ctx, char *name, long type); \& int X509_LOOKUP_add_store_ex(X509_LOOKUP *ctx, char *uri, OSSL_LIB_CTX *libctx, \& const char *propq); \& int X509_LOOKUP_add_store(X509_LOOKUP *ctx, char *uri); \& int X509_LOOKUP_load_store_ex(X509_LOOKUP *ctx, char *uri, OSSL_LIB_CTX *libctx, \& const char *propq); \& int X509_LOOKUP_load_store(X509_LOOKUP *ctx, char *uri); \& \& X509_STORE *X509_LOOKUP_get_store(const X509_LOOKUP *ctx); \& \& int X509_LOOKUP_by_subject_ex(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type, \& const X509_NAME *name, X509_OBJECT *ret, \& OSSL_LIB_CTX *libctx, const char *propq); \& int X509_LOOKUP_by_subject(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type, \& const X509_NAME *name, X509_OBJECT *ret); \& int X509_LOOKUP_by_issuer_serial(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type, \& const X509_NAME *name, \& const ASN1_INTEGER *serial, X509_OBJECT *ret); \& int X509_LOOKUP_by_fingerprint(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type, \& const unsigned char *bytes, int len, \& X509_OBJECT *ret); \& int X509_LOOKUP_by_alias(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type, \& const char *str, int len, X509_OBJECT *ret); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \fBX509_LOOKUP\fR structure holds the information needed to look up certificates and CRLs according to an associated \fBX509_LOOKUP_METHOD\fR\|(3). Multiple \fBX509_LOOKUP\fR instances can be added to an \fBX509_STORE\fR\|(3) to enable lookup in that store. .PP \&\fBX509_LOOKUP_new()\fR creates a new \fBX509_LOOKUP\fR using the given lookup \&\fImethod\fR. It can also be created by calling \fBX509_STORE_add_lookup\fR\|(3), which will associate a \fBX509_STORE\fR with the lookup mechanism. .PP \&\fBX509_LOOKUP_init()\fR initializes the internal state and resources as needed by the given \fBX509_LOOKUP\fR to do its work. .PP \&\fBX509_LOOKUP_shutdown()\fR tears down the internal state and resources of the given \fBX509_LOOKUP\fR. .PP \&\fBX509_LOOKUP_free()\fR destructs the given \fBX509_LOOKUP\fR. .PP \&\fBX509_LOOKUP_set_method_data()\fR and \fBX509_LOOKUP_get_method_data()\fR associates and retrieves a pointer to application data to and from the given \fBX509_LOOKUP\fR, respectively. .PP \&\fBX509_LOOKUP_ctrl_ex()\fR is used to set or get additional data to or from a \fBX509_LOOKUP\fR structure or its associated \fBX509_LOOKUP_METHOD\fR\|(3). The arguments of the control command are passed via \fIargc\fR and \fIargl\fR, its return value via \fI*ret\fR. The library context \fIlibctx\fR and property query \fIpropq\fR are used when fetching algorithms from providers. The meaning of the arguments depends on the \fIcmd\fR number of the control command. In general, this function is not called directly, but wrapped by a macro call, see below. The control \fIcmd\fRs known to OpenSSL are discussed in more depth in \*(L"Control Commands\*(R". .PP \&\fBX509_LOOKUP_ctrl()\fR is similar to \fBX509_LOOKUP_ctrl_ex()\fR but uses \s-1NULL\s0 for the library context \fIlibctx\fR and property query \fIpropq\fR. .PP \&\fBX509_LOOKUP_load_file_ex()\fR passes a filename to be loaded immediately into the associated \fBX509_STORE\fR. The library context \fIlibctx\fR and property query \fIpropq\fR are used when fetching algorithms from providers. \&\fItype\fR indicates what type of object is expected. This can only be used with a lookup using the implementation \&\fBX509_LOOKUP_file\fR\|(3). .PP \&\fBX509_LOOKUP_load_file()\fR is similar to \fBX509_LOOKUP_load_file_ex()\fR but uses \s-1NULL\s0 for the library context \fIlibctx\fR and property query \fIpropq\fR. .PP \&\fBX509_LOOKUP_add_dir()\fR passes a directory specification from which certificates and CRLs are loaded on demand into the associated \&\fBX509_STORE\fR. \&\fItype\fR indicates what type of object is expected. This can only be used with a lookup using the implementation \&\fBX509_LOOKUP_hash_dir\fR\|(3). .PP \&\fBX509_LOOKUP_add_store_ex()\fR passes a \s-1URI\s0 for a directory-like structure from which containers with certificates and CRLs are loaded on demand into the associated \fBX509_STORE\fR. The library context \fIlibctx\fR and property query \fIpropq\fR are used when fetching algorithms from providers. .PP \&\fBX509_LOOKUP_add_store()\fR is similar to \fBX509_LOOKUP_add_store_ex()\fR but uses \s-1NULL\s0 for the library context \fIlibctx\fR and property query \fIpropq\fR. .PP \&\fBX509_LOOKUP_load_store_ex()\fR passes a \s-1URI\s0 for a single container from which certificates and CRLs are immediately loaded into the associated \&\fBX509_STORE\fR. The library context \fIlibctx\fR and property query \fIpropq\fR are used when fetching algorithms from providers. These functions can only be used with a lookup using the implementation \fBX509_LOOKUP_store\fR\|(3). .PP \&\fBX509_LOOKUP_load_store()\fR is similar to \fBX509_LOOKUP_load_store_ex()\fR but uses \s-1NULL\s0 for the library context \fIlibctx\fR and property query \fIpropq\fR. .PP \&\fBX509_LOOKUP_load_file_ex()\fR, \fBX509_LOOKUP_load_file()\fR, \&\fBX509_LOOKUP_add_dir()\fR, \&\fBX509_LOOKUP_add_store_ex()\fR \fBX509_LOOKUP_add_store()\fR, \&\fBX509_LOOKUP_load_store_ex()\fR and \fBX509_LOOKUP_load_store()\fR are implemented as macros that use \fBX509_LOOKUP_ctrl()\fR. .PP \&\fBX509_LOOKUP_by_subject_ex()\fR, \fBX509_LOOKUP_by_subject()\fR, \&\fBX509_LOOKUP_by_issuer_serial()\fR, \fBX509_LOOKUP_by_fingerprint()\fR, and \&\fBX509_LOOKUP_by_alias()\fR look up certificates and CRLs in the \fBX509_STORE\fR\|(3) associated with the \fBX509_LOOKUP\fR using different criteria, where the looked up object is stored in \fIret\fR. Some of the underlying \fBX509_LOOKUP_METHOD\fRs will also cache objects matching the criteria in the associated \fBX509_STORE\fR, which makes it possible to handle cases where the criteria have more than one hit. .SS "Control Commands" .IX Subsection "Control Commands" The \fBX509_LOOKUP_METHOD\fRs built into OpenSSL recognize the following \&\fBX509_LOOKUP_ctrl()\fR \fIcmd\fRs: .IP "\fBX509_L_FILE_LOAD\fR" 4 .IX Item "X509_L_FILE_LOAD" This is the command that \fBX509_LOOKUP_load_file_ex()\fR and \&\fBX509_LOOKUP_load_file()\fR use. The filename is passed in \fIargc\fR, and the type in \fIargl\fR. .IP "\fBX509_L_ADD_DIR\fR" 4 .IX Item "X509_L_ADD_DIR" This is the command that \fBX509_LOOKUP_add_dir()\fR uses. The directory specification is passed in \fIargc\fR, and the type in \&\fIargl\fR. .IP "\fBX509_L_ADD_STORE\fR" 4 .IX Item "X509_L_ADD_STORE" This is the command that \fBX509_LOOKUP_add_store_ex()\fR and \&\fBX509_LOOKUP_add_store()\fR use. The \s-1URI\s0 is passed in \fIargc\fR. .IP "\fBX509_L_LOAD_STORE\fR" 4 .IX Item "X509_L_LOAD_STORE" This is the command that \fBX509_LOOKUP_load_store_ex()\fR and \&\fBX509_LOOKUP_load_store()\fR use. The \s-1URI\s0 is passed in \fIargc\fR. .SH "RETURN VALUES" .IX Header "RETURN VALUES" \&\fBX509_LOOKUP_new()\fR returns a \fBX509_LOOKUP\fR pointer when successful, or \s-1NULL\s0 on error. .PP \&\fBX509_LOOKUP_init()\fR and \fBX509_LOOKUP_shutdown()\fR return 1 on success, or 0 on error. .PP \&\fBX509_LOOKUP_ctrl()\fR returns \-1 if the \fBX509_LOOKUP\fR doesn't have an -associated \fBX509_LOOKUP_METHOD\fR, or 1 if the +associated \fBX509_LOOKUP_METHOD\fR, or 1 if the doesn't have a control function. Otherwise, it returns what the control function in the \&\fBX509_LOOKUP_METHOD\fR returns, which is usually 1 on success and 0 in error. .IX Xref "509_LOOKUP_METHOD" .PP \&\fBX509_LOOKUP_get_store()\fR returns a \fBX509_STORE\fR pointer if there is one, otherwise \s-1NULL.\s0 .PP \&\fBX509_LOOKUP_by_subject_ex()\fR, \fBX509_LOOKUP_by_subject()\fR, \&\fBX509_LOOKUP_by_issuer_serial()\fR, \fBX509_LOOKUP_by_fingerprint()\fR, and \&\fBX509_LOOKUP_by_alias()\fR all return 0 if there is no \fBX509_LOOKUP_METHOD\fR or that method doesn't implement the corresponding function. Otherwise, it returns what the corresponding function in the \&\fBX509_LOOKUP_METHOD\fR returns, which is usually 1 on success and 0 in error. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBX509_LOOKUP_METHOD\fR\|(3), \fBX509_STORE\fR\|(3) .SH "HISTORY" .IX Header "HISTORY" The functions \fBX509_LOOKUP_by_subject_ex()\fR and \&\fBX509_LOOKUP_ctrl_ex()\fR were added in OpenSSL 3.0. .PP The macros \fBX509_LOOKUP_load_file_ex()\fR, \&\fBX509_LOOKUP_load_store_ex()\fR and 509_LOOKUP_add_store_ex() were added in OpenSSL 3.0. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved. .PP Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy in the file \s-1LICENSE\s0 in the source distribution or at . diff --git a/secure/usr.bin/openssl/man/openssl-speed.1 b/secure/usr.bin/openssl/man/openssl-speed.1 index c6b04dd01ccd..371ef75579b5 100644 --- a/secure/usr.bin/openssl/man/openssl-speed.1 +++ b/secure/usr.bin/openssl/man/openssl-speed.1 @@ -1,267 +1,267 @@ .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "OPENSSL-SPEED 1ossl" .TH OPENSSL-SPEED 1ossl "2023-09-22" "3.0.11" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" openssl\-speed \- test library performance .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fBopenssl speed\fR [\fB\-help\fR] [\fB\-elapsed\fR] [\fB\-evp\fR \fIalgo\fR] [\fB\-hmac\fR \fIalgo\fR] [\fB\-cmac\fR \fIalgo\fR] [\fB\-mb\fR] [\fB\-aead\fR] [\fB\-multi\fR \fInum\fR] [\fB\-async_jobs\fR \fInum\fR] [\fB\-misalign\fR \fInum\fR] [\fB\-decrypt\fR] [\fB\-primes\fR \fInum\fR] [\fB\-seconds\fR \fInum\fR] [\fB\-bytes\fR \fInum\fR] [\fB\-mr\fR] [\fB\-rand\fR \fIfiles\fR] [\fB\-writerand\fR \fIfile\fR] [\fB\-engine\fR \fIid\fR] [\fB\-provider\fR \fIname\fR] [\fB\-provider\-path\fR \fIpath\fR] [\fB\-propquery\fR \fIpropq\fR] [\fIalgorithm\fR ...] .SH "DESCRIPTION" .IX Header "DESCRIPTION" This command is used to test the performance of cryptographic algorithms. .SH "OPTIONS" .IX Header "OPTIONS" .IP "\fB\-help\fR" 4 .IX Item "-help" Print out a usage message. .IP "\fB\-elapsed\fR" 4 .IX Item "-elapsed" When calculating operations\- or bytes-per-second, use wall-clock time instead of \s-1CPU\s0 user time as divisor. It can be useful when testing speed of hardware engines. .IP "\fB\-evp\fR \fIalgo\fR" 4 .IX Item "-evp algo" Use the specified cipher or message digest algorithm via the \s-1EVP\s0 interface. If \fIalgo\fR is an \s-1AEAD\s0 cipher, then you can pass \fB\-aead\fR to benchmark a TLS-like sequence. And if \fIalgo\fR is a multi-buffer capable cipher, e.g. aes\-128\-cbc\-hmac\-sha1, then \fB\-mb\fR will time multi-buffer operation. .Sp To see the algorithms supported with this option, use \&\f(CW\*(C`openssl list \-digest\-algorithms\*(C'\fR or \f(CW\*(C`openssl list \-cipher\-algorithms\*(C'\fR command. .IP "\fB\-multi\fR \fInum\fR" 4 .IX Item "-multi num" Run multiple operations in parallel. .IP "\fB\-async_jobs\fR \fInum\fR" 4 .IX Item "-async_jobs num" Enable async mode and start specified number of jobs. .IP "\fB\-misalign\fR \fInum\fR" 4 .IX Item "-misalign num" Misalign the buffers by the specified number of bytes. .IP "\fB\-hmac\fR \fIdigest\fR" 4 .IX Item "-hmac digest" Time the \s-1HMAC\s0 algorithm using the specified message digest. .IP "\fB\-cmac\fR \fIcipher\fR" 4 .IX Item "-cmac cipher" Time the \s-1CMAC\s0 algorithm using the specified cipher e.g. \&\f(CW\*(C`openssl speed \-cmac aes128\*(C'\fR. .IP "\fB\-decrypt\fR" 4 .IX Item "-decrypt" Time the decryption instead of encryption. Affects only the \s-1EVP\s0 testing. .IP "\fB\-mb\fR" 4 .IX Item "-mb" Enable multi-block mode on EVP-named cipher. .IP "\fB\-aead\fR" 4 .IX Item "-aead" Benchmark EVP-named \s-1AEAD\s0 cipher in TLS-like sequence. .IP "\fB\-primes\fR \fInum\fR" 4 .IX Item "-primes num" Generate a \fInum\fR\-prime \s-1RSA\s0 key and use it to run the benchmarks. This option is only effective if \s-1RSA\s0 algorithm is specified to test. .IP "\fB\-seconds\fR \fInum\fR" 4 .IX Item "-seconds num" Run benchmarks for \fInum\fR seconds. .IP "\fB\-bytes\fR \fInum\fR" 4 .IX Item "-bytes num" Run benchmarks on \fInum\fR\-byte buffers. Affects ciphers, digests and the \s-1CSPRNG.\s0 -The limit on the size of the buffer is \s-1INT_MAX\s0 \- 64 bytes, which for a 32\-bit +The limit on the size of the buffer is \s-1INT_MAX\s0 \- 64 bytes, which for a 32\-bit int would be 2147483583 bytes. .IP "\fB\-mr\fR" 4 .IX Item "-mr" Produce the summary in a mechanical, machine-readable, format. .IP "\fB\-rand\fR \fIfiles\fR, \fB\-writerand\fR \fIfile\fR" 4 .IX Item "-rand files, -writerand file" See \*(L"Random State Options\*(R" in \fBopenssl\fR\|(1) for details. .IP "\fB\-engine\fR \fIid\fR" 4 .IX Item "-engine id" See \*(L"Engine Options\*(R" in \fBopenssl\fR\|(1). This option is deprecated. .IP "\fB\-provider\fR \fIname\fR" 4 .IX Item "-provider name" .PD 0 .IP "\fB\-provider\-path\fR \fIpath\fR" 4 .IX Item "-provider-path path" .IP "\fB\-propquery\fR \fIpropq\fR" 4 .IX Item "-propquery propq" .PD See \*(L"Provider Options\*(R" in \fBopenssl\fR\|(1), \fBprovider\fR\|(7), and \fBproperty\fR\|(7). .IP "\fIalgorithm\fR ..." 4 .IX Item "algorithm ..." If any \fIalgorithm\fR is given, then those algorithms are tested, otherwise a pre-compiled grand selection is tested. .SH "BUGS" .IX Header "BUGS" The \fIalgorithm\fR can be selected only from a pre-compiled subset of things that the \f(CW\*(C`openssl speed\*(C'\fR command knows about. To test any additional digest or cipher algorithm supported by OpenSSL use the \f(CW\*(C`\-evp\*(C'\fR option. .PP There is no way to test the speed of any additional public key algorithms supported by third party providers with the \f(CW\*(C`openssl speed\*(C'\fR command. .SH "HISTORY" .IX Header "HISTORY" The \fB\-engine\fR option was deprecated in OpenSSL 3.0. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2000\-2022 The OpenSSL Project Authors. All Rights Reserved. .PP Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy in the file \s-1LICENSE\s0 in the source distribution or at . diff --git a/share/man/man3/bitstring.3 b/share/man/man3/bitstring.3 index bfc0eb5ca139..07558bd41ec3 100644 --- a/share/man/man3/bitstring.3 +++ b/share/man/man3/bitstring.3 @@ -1,469 +1,469 @@ .\" Copyright (c) 1989, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" Paul Vixie. .\" 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. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. .\" .\" Copyright (c) 2014,2016 Spectra Logic Corporation .\" 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, .\" without modification. .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer .\" substantially similar to the "NO WARRANTY" disclaimer below .\" ("Disclaimer") and any redistribution must be conditioned upon .\" including a substantially similar Disclaimer requirement for further .\" binary redistribution. .\" .\" NO WARRANTY .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT .\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR 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 DAMAGES. .\" .Dd November 21, 2023 .Dt BITSTRING 3 .Os .Sh NAME .Nm bit_alloc , .Nm bit_clear , .Nm bit_count , .Nm bit_decl , .Nm bit_ffc , .Nm bit_ffs , .Nm bit_ff_at , .Nm bit_ffc_at , .Nm bit_ffs_at , .Nm bit_ffc_area , .Nm bit_ffs_area , .Nm bit_ff_area_at , .Nm bit_ffc_area_at , .Nm bit_ffs_area_at , .Nm bit_nclear , .Nm bit_nset , .Nm bit_ntest , .Nm bit_set , .Nm bit_test , .Nm bitstr_size .Nd bit-string manipulation functions and macros .Sh SYNOPSIS .In bitstring.h .Ft bitstr_t * .Fn bit_alloc "size_t nbits" .Ft void .Fn bit_decl "bitstr_t *name" "size_t nbits" .Ft void .Fn bit_clear "bitstr_t *name" "size_t bit" .Ft void .Fn bit_count "bitstr_t *name" "size_t count" "size_t nbits" "ssize_t *value" .Ft void .Fn bit_ffc "bitstr_t *name" "size_t nbits" "ssize_t *value" .Ft void .Fn bit_ffs "bitstr_t *name" "size_t nbits" "ssize_t *value" .Ft void .Fn bit_ffc_at "bitstr_t *name" "size_t start" "size_t nbits" "ssize_t *value" .Ft void .Fn bit_ffs_at "bitstr_t *name" "size_t start" "size_t nbits" "ssize_t *value" .Ft void .Fn bit_ff_at "bitstr_t *name" "size_t start" "size_t nbits" "int match" "ssize_t *value" .Ft void .Fn bit_ffc_area "bitstr_t *name" "size_t nbits" "size_t size" "ssize_t *value" .Ft void .Fn bit_ffs_area "bitstr_t *name" "size_t nbits" "size_t size" "ssize_t *value" .Ft void .Fn bit_ffc_area_at "bitstr_t *name" "size_t start" "size_t nbits" "size_t size" "ssize_t *value" .Ft void .Fn bit_ffs_area_at "bitstr_t *name" "size_t start" "size_t nbits" "size_t size" "ssize_t *value" .Ft void .Fn bit_ff_area_at "bitstr_t *name" "size_t start" "size_t nbits" "size_t size" "int match" "ssize_t *value" .Fn bit_foreach "bitstr_t *name" "size_t nbits" "size_t var" .Fn bit_foreach_at "bitstr_t *name" "size_t start" "size_t nbits" "size_t var" .Fn bit_foreach_unset "bitstr_t *name" "size_t nbits" "size_t var" .Fn bit_foreach_unset_at "bitstr_t *name" "size_t start" "size_t nbits" "size_t var" .Ft void .Fn bit_nclear "bitstr_t *name" "size_t start" "size_t stop" .Ft void .Fn bit_nset "bitstr_t *name" "size_t start" "size_t stop" .Ft int .Fn bit_ntest "bitstr_t *name" "size_t start" "size_t stop" "int match" .Ft void .Fn bit_set "bitstr_t *name" "size_t bit" .Ft int .Fn bitstr_size "size_t nbits" .Ft int .Fn bit_test "bitstr_t *name" "size_t bit" .Sh DESCRIPTION These macros operate on strings of bits. .Pp The function .Fn bit_alloc returns a pointer of type .Dq Fa "bitstr_t *" to sufficient space to store .Fa nbits bits, or .Dv NULL if no space is available. If successful, the returned bit string is initialized with all bits cleared. .Pp The macro .Fn bit_decl declares a bit string with sufficient space to store .Fa nbits bits. .Fn bit_decl may be used to include statically sized bit strings in structure definitions or to create bit strings on the stack. Users of this macro are responsible for initialization of the bit string, typically via a global initialization of the containing struct or use of the .Fn bit_nset or .Fn bin_nclear functions. .Pp The macro .Fn bitstr_size returns the number of bytes necessary to store .Fa nbits bits. This is useful for copying bit strings. .Pp The functions .Fn bit_clear and .Fn bit_set clear or set the zero-based numbered bit .Fa bit , in the bit string .Ar name . .Pp The .Fn bit_nset and .Fn bit_nclear functions set or clear the zero-based numbered bits from .Fa start through .Fa stop in the bit string .Ar name . .Pp The .Fn bit_test function evaluates to non-zero if the zero-based numbered bit .Fa bit of bit string .Fa name is set, and zero otherwise. .Pp The .Fn bit_ntest function evaluates to non-zero if the zero-based numbered bits from .Fa start through .Fa stop in the bit string .Ar name all have the value .Ar match . .Pp The function .Fn bit_ffc stores in the location referenced by .Fa value the zero-based number of the first bit not set in the array of .Fa nbits bits referenced by .Fa name . If all bits are set, the location referenced by .Fa value is set to \-1. .Pp The .Fn bit_ffs function stores in the location referenced by .Fa value the zero-based number of the first bit set in the array of .Fa nbits bits referenced by .Fa name . If no bits are set, the location referenced by .Fa value is set to \-1. .Pp The function .Fn bit_ffc_at stores in the location referenced by .Fa value the zero-based number of the first bit not set in the array of .Fa nbits bits referenced by .Fa name , at or after the zero-based bit index .Fa start . If all bits at or after .Fa start are set, the location referenced by .Fa value is set to \-1. .Pp The .Fn bit_ffs_at function stores in the location referenced by .Fa value the zero-based number of the first bit set in the array of .Fa nbits bits referenced by .Fa name , at or after the zero-based bit index .Fa start . If no bits are set after .Fa start , the location referenced by .Fa value is set to \-1. .Pp The .Fn bit_ff_at function stores in the location referenced by .Fa value the zero-based number of the first bit in the array of .Fa nbits bits referenced by .Fa name , at or after the zero-based bit index .Fa start that has value .Fa match . If no bits after .Fa start match that value, the location referenced by .Fa value is set to \-1. .Pp The .Fn bit_ffc_area function stores in the location referenced by .Fa value the zero-based number of the first bit beginning a sequence of unset bits of at least .Fa size unset bits in the array of .Fa nbits bits referenced by .Fa name . If no sequence of contiguous unset bits of the specified .Fa size can be found, the location referenced by .Fa value is set to \-1. .Pp The .Fn bit_ffs_area function stores in the location referenced by .Fa value the zero-based number of the first bit beginning a sequence of set bits of at least .Fa size set bits in the array of .Fa nbits bits referenced by .Fa name . If no sequence of contiguous set bits of the specified .Fa size can be found, the location referenced by .Fa value is set to \-1. .Pp The .Fn bit_ffc_area_at function stores in the location referenced by .Fa value the zero-based number of the first bit beginning a sequence of unset bits of at least .Fa size unset bits in the array of .Fa nbits bits referenced by .Fa name , at or after the zero-based bit index .Fa start . If no sequence of contiguous unset bits of the specified .Fa size can be found at or after .Fa start , the location referenced by .Fa value is set to \-1. .Pp The .Fn bit_ffs_area_at function stores in the location referenced by .Fa value the zero-based number of the first bit beginning a sequence of set bits of at least .Fa size set bits in the array of .Fa nbits bits referenced by .Fa name , at or after the zero-based bit index .Fa start . If no sequence of contiguous set bits of the specified .Fa size can be found at or after .Fa start , the location referenced by .Fa value is set to \-1. .Pp The .Fn bit_ff_area_at function stores in the location referenced by .Fa value the zero-based number of the first bit beginning a sequence of bits of at least .Fa size bits in the array of .Fa nbits bits referenced by .Fa name , at or after the zero-based bit index -.Fa start +.Fa start in which all bits have the value .Fa match . If no sequence of contiguous such bits of the specified .Fa size can be found at or after .Fa start , the location referenced by .Fa value is set to \-1. .Pp The .Fn bit_count function stores in the location referenced by .Fa value the number of bits set in the array of .Fa nbits bits referenced by .Fa name , at or after the zero-based bit index .Fa start . .Pp The macro .Fn bit_foreach traverses all set bits in the array of .Fa nbits referenced by .Fa name in the forward direction, assigning each location in turn to .Fa var . .Pp The macro .Fn bit_foreach_at traverses all set bits in the array of .Fa nbits referenced by .Fa name in the forward direction at or after the zero-based bit index .Fa start , assigning each location in turn to .Fa var . .Pp The macro .Fn bit_foreach_unset traverses all unset bits in the array of .Fa nbits referenced by .Fa name in the forward direction, assigning each location in turn to .Fa var . .Pp The macro .Fn bit_foreach_unset_at traverses all unset bits in the array of .Fa nbits referenced by .Fa name in the forward direction at or after the zero-based bit index .Fa start , assigning each location in turn to .Fa var . .Pp The arguments in bit string macros are evaluated only once and may safely have side effects. .Sh EXAMPLES .Bd -literal -offset indent #include #include \&... #define LPR_BUSY_BIT 0 #define LPR_FORMAT_BIT 1 #define LPR_DOWNLOAD_BIT 2 \&... #define LPR_AVAILABLE_BIT 9 #define LPR_MAX_BITS 10 make_lpr_available() { bitstr_t bit_decl(bitlist, LPR_MAX_BITS); ... bit_nclear(bitlist, 0, LPR_MAX_BITS - 1); ... if (!bit_test(bitlist, LPR_BUSY_BIT)) { bit_clear(bitlist, LPR_FORMAT_BIT); bit_clear(bitlist, LPR_DOWNLOAD_BIT); bit_set(bitlist, LPR_AVAILABLE_BIT); } } .Ed .Sh SEE ALSO .Xr malloc 3 , .Xr bitset 9 .Sh HISTORY The .Nm bitstring functions first appeared in .Bx 4.4 . diff --git a/share/man/man3/pthread_condattr.3 b/share/man/man3/pthread_condattr.3 index f3b1d3639827..96d30263d7f2 100644 --- a/share/man/man3/pthread_condattr.3 +++ b/share/man/man3/pthread_condattr.3 @@ -1,169 +1,169 @@ .\" Copyright (C) 2000 Jason Evans . .\" 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. .Dd October 27, 2023 .Dt PTHREAD_CONDATTR 3 .Os .Sh NAME .Nm pthread_condattr_init , .Nm pthread_condattr_destroy , .Nm pthread_condattr_getclock , .Nm pthread_condattr_setclock , .Nm pthread_condattr_getpshared , .Nm pthread_condattr_setpshared .Nd condition attribute operations .Sh LIBRARY .Lb libpthread .Sh SYNOPSIS .In pthread.h .Ft int .Fn pthread_condattr_init "pthread_condattr_t *attr" .Ft int .Fn pthread_condattr_destroy "pthread_condattr_t *attr" .Ft int .Fo pthread_condattr_getclock .Fa "pthread_condattr_t * restrict attr" "clockid_t * restrict clock_id" .Fc .Ft int .Fn pthread_condattr_setclock "pthread_condattr_t *attr" "clockid_t clock_id" .Ft int .Fo pthread_condattr_getpshared .Fa "pthread_condattr_t * restrict attr" "int * restrict pshared" -.Fc +.Fc .Ft int .Fn pthread_condattr_setpshared "pthread_condattr_t *attr" "int pshared" .Sh DESCRIPTION Condition attribute objects are used to specify parameters to .Fn pthread_cond_init . .Pp The .Fn pthread_condattr_init function initializes a condition attribute object with the default attributes. .Pp The .Fn pthread_condattr_destroy function destroys a condition attribute object. .Pp The .Fn pthread_condattr_getclock function will put the value of the clock attribute from .Fa attr into the memory area pointed to by .Fa clock_id . The .Fn pthread_condattr_setclock function will set the clock attribute of .Fa attr to the value specified in .Fa clock_id . The clock attribute affects the interpretation of .Fa abstime in .Xr pthread_cond_timedwait 3 and may be set to .Dv CLOCK_REALTIME (default) or .Dv CLOCK_MONOTONIC . .Pp The .Fn pthread_condattr_getpshared function will put the value of the process-shared attribute from .Fa attr into the memory area pointed to by .Fa pshared . The .Fn pthread_condattr_setpshared function will set the process-shared attribute of .Fa attr to the value specified in .Fa pshared . The argument .Fa pshared may have one of the following values: .Bl -tag -width ".Dv PTHREAD_PROCESS_PRIVATE" .It Dv PTHREAD_PROCESS_PRIVATE The condition variable it is attached to may only be accessed by threads in the same process as the one that created the object. .It Dv PTHREAD_PROCESS_SHARED The condition variable it is attached to may be accessed by threads in processes other than the one that created the object. .El See .Xr libthr 3 for details of the implementation of shared condition variables, and their limitations. .Sh RETURN VALUES If successful, these functions return 0. Otherwise, an error number is returned to indicate the error. .Sh ERRORS The .Fn pthread_condattr_init function will fail if: .Bl -tag -width Er .It Bq Er ENOMEM Out of memory. .El .Pp The .Fn pthread_condattr_destroy function will fail if: .Bl -tag -width Er .It Bq Er EINVAL Invalid value for .Fa attr . .El .Pp The .Fn pthread_condattr_setclock function will fail if: .Bl -tag -width Er .It Bq Er EINVAL The value specified in .Fa clock_id is not one of the allowed values. .El .Pp The .Fn pthread_condattr_setpshared function will fail if: .Bl -tag -width Er .It Bq Er EINVAL The value specified in .Fa pshared is not one of the allowed values. .El .Sh SEE ALSO .Xr libthr 3 , .Xr pthread_cond_init 3 , .Xr pthread_cond_timedwait 3 .Sh STANDARDS The .Fn pthread_condattr_init and .Fn pthread_condattr_destroy functions conform to .St -p1003.1-96 diff --git a/share/man/man4/u3g.4 b/share/man/man4/u3g.4 index 234b5a4b3277..4035c8d3a8df 100644 --- a/share/man/man4/u3g.4 +++ b/share/man/man4/u3g.4 @@ -1,167 +1,167 @@ .\" .\" Copyright (c) 2008 AnyWi Technologies .\" All rights reserved. .\" .\" This code is derived from uark.c .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd February 4, 2023 +.Dd February 4, 2023 .Dt U3G 4 .Os .Sh NAME .Nm u3g .Nd USB support for 3G and 4G datacards .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device usb" .Cd "device ucom" .Cd "device u3g" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent u3g_load="YES" .Ed .Pp If neither of the above is done, the driver will automatically be loaded by devd(8) when the device is connected. .Sh DESCRIPTION The .Nm driver provides support for the multiple USB-to-serial interfaces exposed by many 3G USB/PCCard modems. .Pp The device is accessed through the .Xr ucom 4 driver which makes it behave like a .Xr tty 4 . .Sh HARDWARE The .Nm driver supports the following adapters: .Pp .Bl -bullet -compact .It Option GT 3G Fusion, GT Fusion Quad, etc. (only 3G part, not WLAN) .It Option GT 3G, GT 3G Quad, etc. .It Vodafone Mobile Connect Card 3G .It Vodafone Mobile Broadband K3772-Z .It Qualcomm Inc. CDMA MSM .It Qualcomm Inc. GOBI 1000, 2000 and 3000 devices with MDM1000 or MDM2000 chipsets .It QUECTEL BGX, ECX, EGX, EMX, EPX, RGX series. .It Quectel EM160R (see CAVEATS) .It Huawei B190, E180v, E220, E3372, E3372v153, E5573Cs322, ('') .It Novatel U740, MC950D, X950D, etc. .It Sierra MC875U, MC8775U, etc. .It Panasonic CF-F9 GOBI .El .Pp (See .Pa /sys/dev/usb/serial/u3g.c for the complete list of supported cards for each vendor mentioned above.) .Pp The supported 3G cards provide the necessary modem port for ppp, or mpd connections as well as extra ports (depending on the specific device) to provide other functions (additional command port, diagnostic port, SIM toolkit port). .Pp In some of these devices a mass storage device supported by the .Xr umass 4 driver is present which contains Windows and Mac OS X drivers. The device starts up in disk mode (TruInstall, ZeroCD, etc.) and requires additional commands to switch it to modem mode. If your device is not switching automatically, please try to add quirks. See .Xr usbconfig 8 and .Xr usb_quirk 4 . .Sh FILES .Bl -tag -width "/dev/ttyU*.*.init" -compact .It Pa /dev/ttyU*.* for callin ports .It Pa /dev/ttyU*.*.init .It Pa /dev/ttyU*.*.lock corresponding callin initial-state and lock-state devices .Pp .It Pa /dev/cuaU*.* for callout ports .It Pa /dev/cuaU*.*.init .It Pa /dev/cuaU*.*.lock corresponding callout initial-state and lock-state devices .El .Sh EXAMPLES Connect to the Internet using the default configuration: .Bd -literal -offset indent ppp -background u3g .Ed .Sh SEE ALSO .Xr tty 4 , .Xr ucom 4 , .Xr usb 4 , .Xr usb_quirk 4 , .Xr devd 8 , .Xr ppp 8 , .Xr usbconfig 8 .Sh HISTORY The .Nm driver appeared in .Fx 7.2 , is based on the .Xr uark 4 driver, and written by .An Andrea Guzzo Aq Mt aguzzo@anywi.com in September 2008. .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Andrea Guzzo Aq Mt aguzzo@anywi.com and .An Nick Hibma Aq Mt n_hibma@FreeBSD.org . Hardware for testing was provided by AnyWi Technologies, Leiden, NL. .Sh CAVEATS The Quectel EM160R is not officially supported in PPP mode. In order to use it in PPP mode, the ctsrts option needs to be turned off, for example, by adding: .Dl set ctsrts off to .Pa /etc/ppp/ppp.conf in the correct section. .Sh BUGS The automatic mode switch from disk mode to modem mode does not work unless the driver is either built into the kernel or loaded before the device is connected. .Pp The GOBI-based devices require the gobi loader available from the .Pa sysutils/gobi_loader port. diff --git a/share/man/man8/debug.sh.8 b/share/man/man8/debug.sh.8 index 77a1e06cc56a..bf0fdbd6bcf5 100644 --- a/share/man/man8/debug.sh.8 +++ b/share/man/man8/debug.sh.8 @@ -1,191 +1,191 @@ .\" Copyright (c) 1994-2021 Simon J. Gerraty .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" This file is provided in the hope that it will .\" be of use. There is absolutely NO WARRANTY. .\" Permission to copy, redistribute or otherwise .\" use this file is hereby granted provided that .\" the above copyright notice and this notice are .\" left intact. .\" .\" Please send copies of changes and bug-fixes to: .\" sjg@crufty.net .\" .Dd October 22, 2024 .Dt DEBUG.SH 8 .Os .Sh NAME .Nm debug.sh .Nd selectively debug scripts .Sh SYNOPSIS .Bl -item -compact .It .Ic $_DEBUG_SH .\& Pa debug.sh .Pp .It .Ic DebugOn Oo Fl eo Oc Ar tag ... .It .Ic DebugOff Oo Fl eo Oc Oo Cm rc= Ns Ar rc Oc Ar tag ... .It .Ic Debugging .It .Ic DebugAdd Ar tag .It .Ic DebugEcho Op Ar message .It .Ic DebugLog Op Ar message .It .Ic DebugShell Ar tag ... .It .Ic DebugTrace Ar message .It .Ic Debug Ar tag ... .El .Sh DESCRIPTION .Nm provides the following functions to facilitate flexible run-time tracing of complicated shell scripts. .Bl -tag -width 4n .It Ic DebugOn Oo Fl eo Oc Ar tag ... turns tracing on if any .Ar tag is found in .Va DEBUG_SH (a comma separated list of tags). .Pp It turns tracing off if .Ar !tag is found in .Va DEBUG_SH . .Pp It sets .Va DEBUG_ON to the .Ar tag that caused tracing to be enabled, or .Va DEBUG_OFF if we matched .Ar !tag . .Pp If .Fl e option is present, returns 1 if no .Ar tag matched. .Pp If .Fl o option is present, tracing is turned off unless there was a matched .Ar tag , useful for functions too noisy to tace. .It Ic DebugOff Oo Fl eo Oc Oo Cm rc= Ns Ar rc Oc Ar tag ... turns tracing on if any .Ar tag matches .Va DEBUG_OFF or off if any .Ar tag matches .Va DEBUG_ON . This allows nested functions to not interfere with each other. .Pp The flags .Fl e and .Fl o are ignored, they just allow for symmetry with calls to .Fn DebugOn . .Pp The optional .Ar rc value will be returned rather than the default of 0. -Thus if +Thus if .Fn DebugOff is the last operation in a function, .Ar rc will be the return code of the function. .It Ic Debugging returns true if tracing is enabled. It is useful for bounding complex debug actions, rather than using lots of .Ic $DEBUG_DO lines. .It Ic DebugAdd Ar tag Add .Ar tag to .Va DEBUG_SH to influence later output, possibly in a child process. .It Ic DebugEcho is just shorthand for: .Bd -literal -offset indent $DEBUG_DO echo "$@" .Ed .It Ic DebugLog Op Ar message If debugging is enabled, output .Ar message prefixed with a time-stamp. .It Ic DebugShell Ar tag ... runs an interactive shell if any .Ar tag is found in .Va DEBUG_INTERACTIVE , and there is a tty available. The shell used is defined by .Va DEBUG_SHELL or .Va SHELL and defaults to .Pa /bin/sh . .It Ic DebugTrace Ar message Debug output can be very noisy, and it can be tricky to align with the script. This function outputs a very noticable banner indicating the value of .Va DEBUG_ON , and .Ar message is passed to .Fn DebugLog , finally the banner is repeated. .It Ic Debug Ar tag ... For backwards compatibility, calls .Fn DebugOn and if that does not turn tracing on, it calls .Fn DebugOff to turn it off. .El .Pp The variables .Va DEBUG_SKIP and .Va DEBUG_DO are set so as to enable/disable code that should be skipped/run when debugging is turned on. .Va DEBUGGING is the same as .Va DEBUG_SKIP for backwards compatability and is only set by .Fn Debug . .Pp The use of .Ic $_DEBUG_SH is to prevent multiple inclusion, though it does no harm in this case. .Sh BUGS Does not work with some versions of .Xr ksh 1 . If a function turns tracing on, ksh turns it off when the function returns - useless. .Pp PD ksh works ok ;-) .Sh AUTHOR .An -nosplit .Nm was written by .An Simon J Gerraty Aq Mt sjg@crufty.net . diff --git a/share/man/man9/bitset.9 b/share/man/man9/bitset.9 index a4e360a678d7..b77cfec63e26 100644 --- a/share/man/man9/bitset.9 +++ b/share/man/man9/bitset.9 @@ -1,658 +1,658 @@ .\" Copyright (c) 2015 Conrad Meyer .\" 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. .\" .Dd September 20, 2021 .Dt BITSET 9 .Os .Sh NAME .Nm bitset(9) \(em .Nm BITSET_DEFINE , .Nm BITSET_T_INITIALIZER , .Nm BITSET_FSET , .Nm BIT_CLR , .Nm BIT_COPY , .Nm BIT_ISSET , .Nm BIT_SET , .Nm BIT_ZERO , .Nm BIT_FILL , .Nm BIT_SETOF , .Nm BIT_EMPTY , .Nm BIT_ISFULLSET , .Nm BIT_FFS , .Nm BIT_FFS_AT , .Nm BIT_FLS , .Nm BIT_FOREACH_ISSET , .Nm BIT_FOREACH_ISCLR , .Nm BIT_COUNT , .Nm BIT_SUBSET , .Nm BIT_OVERLAP , .Nm BIT_CMP , .Nm BIT_OR , .Nm BIT_OR2 , .Nm BIT_ORNOT , .Nm BIT_ORNOT2 , .Nm BIT_AND , .Nm BIT_AND2 , .Nm BIT_ANDNOT , .Nm BIT_ANDNOT2 , .Nm BIT_XOR , .Nm BIT_XOR2 , .Nm BIT_CLR_ATOMIC , .Nm BIT_SET_ATOMIC , .Nm BIT_SET_ATOMIC_ACQ , .Nm BIT_TEST_SET_ATOMIC , .Nm BIT_TEST_CLR_ATOMIC , .Nm BIT_AND_ATOMIC , .Nm BIT_OR_ATOMIC , .Nm BIT_COPY_STORE_REL .Nd bitset manipulation macros .Sh SYNOPSIS .In sys/_bitset.h .In sys/bitset.h .\" .Fn BITSET_DEFINE "STRUCTNAME" "const SETSIZE" .Fn BITSET_T_INITIALIZER "ARRAY_CONTENTS" .Fn BITSET_FSET "N_WORDS" .\" .Fn BIT_CLR "const SETSIZE" "size_t bit" "struct STRUCTNAME *bitset" .Fn BIT_COPY "const SETSIZE" "struct STRUCTNAME *from" "struct STRUCTNAME *to" .Ft bool .Fn BIT_ISSET "const SETSIZE" "size_t bit" "struct STRUCTNAME *bitset" .Fn BIT_SET "const SETSIZE" "size_t bit" "struct STRUCTNAME *bitset" .Fn BIT_ZERO "const SETSIZE" "struct STRUCTNAME *bitset" .Fn BIT_FILL "const SETSIZE" "struct STRUCTNAME *bitset" .Fn BIT_SETOF "const SETSIZE" "size_t bit" "struct STRUCTNAME *bitset" .Ft bool .Fn BIT_EMPTY "const SETSIZE" "struct STRUCTNAME *bitset" .Ft bool .Fn BIT_ISFULLSET "const SETSIZE" "struct STRUCTNAME *bitset" .Ft long .Fn BIT_FFS "const SETSIZE" "struct STRUCTNAME *bitset" .Ft long .Fn BIT_FFS_AT "const SETSIZE" "struct STRUCTNAME *bitset" "long start" .Ft long .Fn BIT_FLS "const SETSIZE" "struct STRUCTNAME *bitset" .Fo BIT_FOREACH_ISSET .Fa "const SETSIZE" .Fa "size_t bit" .Fa "const struct STRUCTNAME *bitset" .Fc .Fo BIT_FOREACH_ISCLR .Fa "const SETSIZE" .Fa "size_t bit" .Fa "const struct STRUCTNAME *bitset" .Fc .Ft long .Fn BIT_COUNT "const SETSIZE" "struct STRUCTNAME *bitset" .Ft bool .Fo BIT_SUBSET .Fa "const SETSIZE" "struct STRUCTNAME *haystack" "struct STRUCTNAME *needle" .Fc .Ft bool .Fo BIT_OVERLAP .Fa "const SETSIZE" "struct STRUCTNAME *bitset1" "struct STRUCTNAME *bitset2" .Fc .Ft bool .Fo BIT_CMP .Fa "const SETSIZE" "struct STRUCTNAME *bitset1" "struct STRUCTNAME *bitset2" .Fc .Fn BIT_OR "const SETSIZE" "struct STRUCTNAME *dst" "struct STRUCTNAME *src" .Fo BIT_OR2 .Fa "const SETSIZE" .Fa "struct STRUCTNAME *dst" .Fa "struct STRUCTNAME *src1" .Fa "struct STRUCTNAME *src2" .Fc .Fn BIT_ORNOT "const SETSIZE" "struct STRUCTNAME *dst" "struct STRUCTNAME *src" .Fo BIT_ORNOT2 .Fa "const SETSIZE" .Fa "struct STRUCTNAME *dst" .Fa "struct STRUCTNAME *src1" .Fa "struct STRUCTNAME *src2" .Fc .Fn BIT_AND "const SETSIZE" "struct STRUCTNAME *dst" "struct STRUCTNAME *src" .Fo BIT_AND2 .Fa "const SETSIZE" .Fa "struct STRUCTNAME *dst" .Fa "struct STRUCTNAME *src1" .Fa "struct STRUCTNAME *src2" .Fc .Fn BIT_ANDNOT "const SETSIZE" "struct STRUCTNAME *dst" "struct STRUCTNAME *src" .Fo BIT_ANDNOT2 .Fa "const SETSIZE" .Fa "struct STRUCTNAME *dst" .Fa "struct STRUCTNAME *src1" .Fa "struct STRUCTNAME *src2" .Fc .Fn BIT_XOR "const SETSIZE" "struct STRUCTNAME *dst" "struct STRUCTNAME *src" .Fo BIT_XOR2 .Fa "const SETSIZE" .Fa "struct STRUCTNAME *dst" .Fa "struct STRUCTNAME *src1" .Fa "struct STRUCTNAME *src2" .Fc .\" .Fn BIT_CLR_ATOMIC "const SETSIZE" "size_t bit" "struct STRUCTNAME *bitset" .Fn BIT_SET_ATOMIC "const SETSIZE" "size_t bit" "struct STRUCTNAME *bitset" .Fn BIT_SET_ATOMIC_ACQ "const SETSIZE" "size_t bit" "struct STRUCTNAME *bitset" .Ft bool .Fn BIT_TEST_SET_ATOMIC "const SETSIZE" "size_t bit" "struct STRUCTNAME *bitset" .Ft bool .Fn BIT_TEST_CLR_ATOMIC "const SETSIZE" "size_t bit" "struct STRUCTNAME *bitset" .\" .Fo BIT_AND_ATOMIC .Fa "const SETSIZE" "struct STRUCTNAME *dst" "struct STRUCTNAME *src" .Fc .Fo BIT_OR_ATOMIC .Fa "const SETSIZE" "struct STRUCTNAME *dst" "struct STRUCTNAME *src" .Fc .Fo BIT_COPY_STORE_REL .Fa "const SETSIZE" "struct STRUCTNAME *from" "struct STRUCTNAME *to" .Fc .Fd #define _WANT_FREEBSD_BITSET .Sh DESCRIPTION The .Nm family of macros provide a flexible and efficient bitset implementation if the maximum size of the set is known at compilation. Throughout this manual page, the name .Fa SETSIZE refers to the size of the bitset in bits. Individual bits in bitsets are referenced with indices zero through .Fa SETSIZE - 1 . One example use of .In sys/bitset.h is .In sys/cpuset.h . .Pp These macros are meant to be used in the kernel and are visible if .Dv _KERNEL is defined when .In sys/_bitset.h or .In sys/bitset.h are included in a program. -Userland programs must define +Userland programs must define .Dv _WANT_FREEBSD_BITSET before including these files to make the macros visible. .Pp The .Fn BITSET_DEFINE macro defines a bitset struct .Fa STRUCTNAME with room to represent .Fa SETSIZE bits. .Pp The .Fn BITSET_T_INITIALIZER macro allows one to initialize a bitset struct with a compile time literal value. .Pp The .Fn BITSET_FSET macro generates a compile time literal, usable by .Fn BITSET_T_INITIALIZER , representing a full bitset (all bits set). For examples of .Fn BITSET_T_INITIALIZER and .Fn BITSET_FSET usage, see the .Sx BITSET_T_INITIALIZER EXAMPLE section. The .Fa N_WORDS parameter to .Fn BITSET_FSET should be: .Bd -literal -offset indent __bitset_words(SETSIZE) .Ed .Pp The .Fn BIT_CLR macro clears bit .Fa bit in the bitset pointed to by .Fa bitset . The .Fn BIT_CLR_ATOMIC macro is identical, but the bit is cleared atomically. The .Fn BIT_TEST_CLR_ATOMIC macro atomically clears the bit and returns whether it was set. .Pp The .Fn BIT_COPY macro copies the contents of the bitset .Fa from to the bitset .Fa to . .Fn BIT_COPY_STORE_REL is similar, but copies component machine words from .Fa from and writes them to .Fa to with atomic store with release semantics. (That is, if .Fa to is composed of multiple machine words, .Fn BIT_COPY_STORE_REL performs multiple individually atomic operations.) .Pp The .Fn BIT_ISSET macro returns .Dv true if the bit .Fa bit in the bitset pointed to by .Fa bitset is set. .Pp The .Fn BIT_SET macro sets bit .Fa bit in the bitset pointed to by .Fa bitset . The .Fn BIT_SET_ATOMIC macro is identical, but the bit is set atomically. The .Fn BIT_SET_ATOMIC_ACQ macro sets the bit with acquire semantics. The .Fn BIT_TEST_SET_ATOMIC macro atomically sets the bit and returns whether it was set. .Pp The .Fn BIT_ZERO macro clears all bits in .Fa bitset . .Pp The .Fn BIT_FILL macro sets all bits in .Fa bitset . .Pp The .Fn BIT_SETOF macro clears all bits in .Fa bitset before setting only bit .Fa bit . .Pp The .Fn BIT_EMPTY macro returns .Dv true if .Fa bitset is empty. .Pp The .Fn BIT_ISFULLSET macro returns .Dv true if .Fa bitset is full (all bits set). .Pp The .Fn BIT_FFS macro returns the 1-index of the first (lowest) set bit in .Fa bitset , or zero if .Fa bitset is empty. Like with .Xr ffs 3 , to use the non-zero result of .Fn BIT_FFS as a .Fa bit index parameter to any other .Nm macro, you must subtract one from the result. .Pp The .Fn BIT_FFS_AT macro returns the 1-index of the first (lowest) set bit in .Fa bitset , which is greater than the given 1-indexed .Fa start , or zero if no bits in .Fa bitset greater than .Fa start are set. .Pp The .Fn BIT_FLS macro returns the 1-index of the last (highest) set bit in .Fa bitset , or zero if .Fa bitset is empty. Like with .Xr fls 3 , to use the non-zero result of .Fn BIT_FLS as a .Fa bit index parameter to any other .Nm macro, you must subtract one from the result. .Pp The .Fn BIT_FOREACH_ISSET macro can be used to iterate over all set bits in .Fa bitset . The index variable .Fa bit must have been declared with type .Ft int , and upon each iteration .Fa bit is set to the index of successive set bits. The value of .Fa bit after the loop terminates is undefined. Similarly, .Fn BIT_FOREACH_ISCLR iterates over all clear bits in .Fa bitset . In the loop body, the currently indexed bit may be set or cleared. However, setting or clearing bits other than the currently indexed bit does not guarantee that they will or will not be returned in subsequent iterations of the same loop. .Pp The .Fn BIT_COUNT macro returns the total number of set bits in .Fa bitset . .Pp The .Fn BIT_SUBSET macro returns .Dv true if .Fa needle is a subset of .Fa haystack . .Pp The .Fn BIT_OVERLAP macro returns .Dv true if .Fa bitset1 and .Fa bitset2 have any common bits. (That is, if .Fa bitset1 AND .Fa bitset2 is not the empty set.) .Pp The .Fn BIT_CMP macro returns .Dv true if .Fa bitset1 is NOT equal to .Fa bitset2 . .Pp The .Fn BIT_OR macro sets bits present in .Fa src in .Fa dst . (It is the .Nm equivalent of the scalar: .Fa dst |= .Fa src . ) .Fn BIT_OR_ATOMIC is similar, but sets bits in the component machine words in .Fa dst atomically. (That is, if .Fa dst is composed of multiple machine words, .Fn BIT_OR_ATOMIC performs multiple individually atomic operations.) .Pp The .Fn BIT_OR2 macro computes .Fa src1 bitwise or .Fa src2 and assigns the result to .Fa dst . (It is the .Nm equivalent of the scalar: .Fa dst = .Fa src1 | .Fa src2 . ) .Pp The .Fn BIT_ORNOT macro sets bits not in .Fa src in .Fa dst . (It is the .Nm equivalent of the scalar: .Fa dst |= .Fa ~ src . ) .Pp The .Fn BIT_ORNOT2 macro computes .Fa src1 bitwise or not .Fa src2 and assigns the result to .Fa dst . (It is the .Nm equivalent of the scalar: .Fa dst = .Fa src1 | ~ .Fa src2 . ) .Pp The .Fn BIT_AND macro clears bits absent from .Fa src from .Fa dst . (It is the .Nm equivalent of the scalar: .Fa dst &= .Fa src . ) .Fn BIT_AND_ATOMIC is similar, with the same atomic semantics as .Fn BIT_OR_ATOMIC . .Pp The .Fn BIT_AND2 macro computes .Fa src1 bitwise and .Fa src2 and assigns the result to .Fa dst . (It is the .Nm equivalent of the scalar: .Fa dst = .Fa src1 & .Fa src2 . ) .Pp The .Fn BIT_ANDNOT macro clears bits set in .Fa src from .Fa dst . (It is the .Nm equivalent of the scalar: .Fa dst &= .Fa ~ src . ) .Pp The .Fn BIT_ANDNOT2 macro computes .Fa src1 bitwise and not .Fa src2 and assigns the result to .Fa dst . (It is the .Nm equivalent of the scalar: .Fa dst = .Fa src1 & ~ .Fa src2 . ) .Pp The .Fn BIT_XOR macro toggles bits set in .Fa src in .Fa dst . (It is the .Nm equivalent of the scalar: .Fa dst ^= .Fa src . ) .Pp The .Fn BIT_XOR2 macro computes .Fa src1 bitwise exclusive or .Fa src2 and assigns the result to .Fa dst . (It is the .Nm equivalent of the scalar: .Fa dst = .Fa src1 ^ .Fa src2 . ) .Sh BITSET_T_INITIALIZER EXAMPLE .Bd -literal BITSET_DEFINE(_myset, MYSETSIZE); struct _myset myset; /* Initialize myset to filled (all bits set) */ myset = BITSET_T_INITIALIZER(BITSET_FSET(__bitset_words(MYSETSIZE))); /* Initialize myset to only the lowest bit set */ myset = BITSET_T_INITIALIZER(0x1); .Ed .Sh SEE ALSO .Xr bitstring 3 , .Xr cpuset 9 .Sh HISTORY The .Nm macros first appeared in .Fx 10.0 in January 2014. They were MFCed to .Fx 9.3 , released in July 2014. .Pp This manual page first appeared in .Fx 11.0 . .Sh AUTHORS .An -nosplit The .Nm macros were generalized and pulled out of .In sys/cpuset.h as .In sys/_bitset.h and .In sys/bitset.h by .An Attilio Rao Aq Mt attilio@FreeBSD.org . This manual page was written by .An Conrad Meyer Aq Mt cem@FreeBSD.org . .Sh CAVEATS The .Fa SETSIZE argument to all of these macros must match the value given to .Fn BITSET_DEFINE . .Pp Unlike every other reference to individual set members, which are zero-indexed, .Fn BIT_FFS , .Fn BIT_FFS_AT and .Fn BIT_FLS return a one-indexed result (or zero if the set is empty). .Pp In order to use the macros defined in .In sys/bitset.h and .In sys/_bitset.h in userland programs, .Dv _WANT_FREEBSD_BITSET has to be defined before including the header files. This requirements exists to prevent a name space pollution due to macros defined in .Nm in programs that include .In sys/cpuset.h or .In sched.h . diff --git a/share/man/man9/mod_cc.9 b/share/man/man9/mod_cc.9 index 86d9c7b5312c..09580aa943a9 100644 --- a/share/man/man9/mod_cc.9 +++ b/share/man/man9/mod_cc.9 @@ -1,421 +1,421 @@ .\" .\" Copyright (c) 2008-2009 Lawrence Stewart .\" Copyright (c) 2010-2011 The FreeBSD Foundation .\" All rights reserved. .\" .\" Portions of this documentation were written at the Centre for Advanced .\" Internet Architectures, Swinburne University of Technology, Melbourne, .\" Australia by David Hayes and Lawrence Stewart under sponsorship from the .\" FreeBSD Foundation. .\" .\" 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. .\" .Dd May 13, 2021 .Dt MOD_CC 9 .Os .Sh NAME .Nm mod_cc , .Nm DECLARE_CC_MODULE , .Nm CCV .Nd Modular Congestion Control .Sh SYNOPSIS .In netinet/tcp.h .In netinet/cc/cc.h .In netinet/cc/cc_module.h .Fn DECLARE_CC_MODULE "ccname" "ccalgo" .Fn CCV "ccv" "what" .Sh DESCRIPTION The .Nm framework allows congestion control algorithms to be implemented as dynamically loadable kernel modules via the .Xr kld 4 facility. Transport protocols can select from the list of available algorithms on a connection-by-connection basis, or use the system default (see .Xr mod_cc 4 for more details). .Pp .Nm modules are identified by an .Xr ascii 7 name and set of hook functions encapsulated in a .Vt "struct cc_algo" , which has the following members: .Bd -literal -offset indent struct cc_algo { char name[TCP_CA_NAME_MAX]; int (*mod_init) (void); int (*mod_destroy) (void); size_t (*cc_data_sz)(void); int (*cb_init) (struct cc_var *ccv, void *ptr); void (*cb_destroy) (struct cc_var *ccv); void (*conn_init) (struct cc_var *ccv); void (*ack_received) (struct cc_var *ccv, uint16_t type); void (*cong_signal) (struct cc_var *ccv, uint32_t type); void (*post_recovery) (struct cc_var *ccv); void (*after_idle) (struct cc_var *ccv); int (*ctl_output)(struct cc_var *, struct sockopt *, void *); void (*rttsample)(struct cc_var *, uint32_t, uint32_t, uint32_t); void (*newround)(struct cc_var *, uint32_t); }; .Ed .Pp The .Va name field identifies the unique name of the algorithm, and should be no longer than TCP_CA_NAME_MAX-1 characters in length (the TCP_CA_NAME_MAX define lives in .In netinet/tcp.h for compatibility reasons). .Pp The .Va mod_init function is called when a new module is loaded into the system but before the registration process is complete. It should be implemented if a module needs to set up some global state prior to being available for use by new connections. Returning a non-zero value from .Va mod_init will cause the loading of the module to fail. .Pp The .Va mod_destroy function is called prior to unloading an existing module from the kernel. It should be implemented if a module needs to clean up any global state before being removed from the kernel. The return value is currently ignored. .Pp The .Va cc_data_sz function is called by the socket option code to get the size of data that the .Va cb_init function needs. The socket option code then preallocates the modules memory so that the .Va cb_init function will not fail (the socket option code uses M_WAITOK with no locks held to do this). .Pp The .Va cb_init function is called when a TCP control block .Vt struct tcpcb is created. It should be implemented if a module needs to allocate memory for storing private per-connection state. Returning a non-zero value from .Va cb_init will cause the connection set up to be aborted, terminating the connection as a result. Note that the ptr argument passed to the function should be checked to see if it is non-NULL, if so it is preallocated memory that the cb_init function must use instead of calling malloc itself. .Pp The .Va cb_destroy function is called when a TCP control block .Vt struct tcpcb is destroyed. It should be implemented if a module needs to free memory allocated in .Va cb_init . .Pp The .Va conn_init function is called when a new connection has been established and variables are being initialised. It should be implemented to initialise congestion control algorithm variables for the newly established connection. .Pp The .Va ack_received function is called when a TCP acknowledgement (ACK) packet is received. Modules use the .Fa type argument as an input to their congestion management algorithms. The ACK types currently reported by the stack are CC_ACK and CC_DUPACK. CC_ACK indicates the received ACK acknowledges previously unacknowledged data. CC_DUPACK indicates the received ACK acknowledges data we have already received an ACK for. .Pp The .Va cong_signal function is called when a congestion event is detected by the TCP stack. Modules use the .Fa type argument as an input to their congestion management algorithms. The congestion event types currently reported by the stack are CC_ECN, CC_RTO, CC_RTO_ERR and CC_NDUPACK. CC_ECN is reported when the TCP stack receives an explicit congestion notification (RFC3168). CC_RTO is reported when the retransmission time out timer fires. CC_RTO_ERR is reported if the retransmission time out timer fired in error. CC_NDUPACK is reported if N duplicate ACKs have been received back-to-back, where N is the fast retransmit duplicate ack threshold (N=3 currently as per RFC5681). .Pp The .Va post_recovery function is called after the TCP connection has recovered from a congestion event. It should be implemented to adjust state as required. .Pp The .Va after_idle function is called when data transfer resumes after an idle period. It should be implemented to adjust state as required. .Pp The .Va ctl_output function is called when .Xr getsockopt 2 or .Xr setsockopt 2 is called on a .Xr tcp 4 socket with the .Va struct sockopt pointer forwarded unmodified from the TCP control, and a .Va void * pointer to algorithm specific argument. .Pp The .Va rttsample function is called to pass round trip time information to the congestion controller. The additional arguments to the function include the microsecond RTT that is being noted, the number of times that the data being acknowledged was retransmitted as well as the flightsize at send. For transports that do not track flightsize at send, this variable will be the current cwnd at the time of the call. .Pp The .Va newround function is called each time a new round trip time begins. The montonically increasing round number is also passed to the congestion controller as well. This can be used for various purposes by the congestion controller (e.g Hystart++). .Pp Note that currently not all TCP stacks call the .Va rttsample and .Va newround function so dependency on these functions is also dependent upon which TCP stack is in use. .Pp The .Fn DECLARE_CC_MODULE macro provides a convenient wrapper around the .Xr DECLARE_MODULE 9 macro, and is used to register a .Nm module with the .Nm framework. The .Fa ccname argument specifies the module's name. The .Fa ccalgo argument points to the module's .Vt struct cc_algo . .Pp .Nm modules must instantiate a .Vt struct cc_algo , but are only required to set the name field, and optionally any of the function pointers. Note that if a module defines the .Va cb_init function it also must define a .Va cc_data_sz function. This is because when switching from one congestion control module to another the socket option code will preallocate memory for the .Va cb_init function. If no memory is allocated by the modules .Va cb_init then the .Va cc_data_sz function should return 0. .Pp The stack will skip calling any function pointer which is NULL, so there is no requirement to implement any of the function pointers (with the exception of the cb_init <-> cc_data_sz dependency noted above). Using the C99 designated initialiser feature to set fields is encouraged. .Pp Each function pointer which deals with congestion control state is passed a pointer to a .Vt struct cc_var , which has the following members: .Bd -literal -offset indent struct cc_var { void *cc_data; int bytes_this_ack; tcp_seq curack; uint32_t flags; int type; union ccv_container { struct tcpcb *tcp; struct sctp_nets *sctp; } ccvc; uint16_t nsegs; uint8_t labc; }; .Ed .Pp .Vt struct cc_var groups congestion control related variables into a single, embeddable structure and adds a layer of indirection to accessing transport protocol control blocks. The eventual goal is to allow a single set of .Nm modules to be shared between all congestion aware transport protocols, though currently only .Xr tcp 4 is supported. .Pp To aid the eventual transition towards this goal, direct use of variables from the transport protocol's data structures is strongly discouraged. However, it is inevitable at the current time to require access to some of these variables, and so the .Fn CCV macro exists as a convenience accessor. The .Fa ccv argument points to the .Vt struct cc_var passed into the function by the .Nm framework. The .Fa what argument specifies the name of the variable to access. .Pp Apart from the .Va type and .Va ccv_container fields, the remaining fields in .Vt struct cc_var are for use by .Nm modules. .Pp The .Va cc_data field is available for algorithms requiring additional per-connection state to attach a dynamic memory pointer to. The memory should be allocated and attached in the module's .Va cb_init hook function. .Pp The .Va bytes_this_ack field specifies the number of new bytes acknowledged by the most recently received ACK packet. It is only valid in the .Va ack_received hook function. .Pp The .Va curack field specifies the sequence number of the most recently received ACK packet. It is only valid in the .Va ack_received , .Va cong_signal and .Va post_recovery hook functions. .Pp The .Va flags field is used to pass useful information from the stack to a .Nm module. The CCF_ABC_SENTAWND flag is relevant in .Va ack_received and is set when appropriate byte counting (RFC3465) has counted a window's worth of bytes has been sent. It is the module's responsibility to clear the flag after it has processed the signal. The CCF_CWND_LIMITED flag is relevant in .Va ack_received and is set when the connection's ability to send data is currently constrained by the value of the congestion window. Algorithms should use the absence of this flag being set to avoid accumulating a large difference between the congestion window and send window. .Pp The .Va nsegs variable is used to pass in how much compression was done by the local LRO system. So for example if LRO pushed three in-order acknowledgements into one acknowledgement the variable would be set to three. .Pp -The +The .Va labc variable is used in conjunction with the CCF_USE_LOCAL_ABC flag to override what labc variable the congestion controller will use for this particular acknowledgement. .Sh SEE ALSO .Xr cc_cdg 4 , .Xr cc_chd 4 , .Xr cc_cubic 4 , .Xr cc_dctcp 4 , .Xr cc_hd 4 , .Xr cc_htcp 4 , .Xr cc_newreno 4 , .Xr cc_vegas 4 , .Xr mod_cc 4 , .Xr tcp 4 .Sh ACKNOWLEDGEMENTS Development and testing of this software were made possible in part by grants from the FreeBSD Foundation and Cisco University Research Program Fund at Community Foundation Silicon Valley. .Sh FUTURE WORK Integrate with .Xr sctp 4 . .Sh HISTORY The modular Congestion Control (CC) framework first appeared in .Fx 9.0 . .Pp The framework was first released in 2007 by James Healy and Lawrence Stewart whilst working on the NewTCP research project at Swinburne University of Technology's Centre for Advanced Internet Architectures, Melbourne, Australia, which was made possible in part by a grant from the Cisco University Research Program Fund at Community Foundation Silicon Valley. More details are available at: .Pp http://caia.swin.edu.au/urp/newtcp/ .Sh AUTHORS .An -nosplit The .Nm framework was written by .An Lawrence Stewart Aq Mt lstewart@FreeBSD.org , .An James Healy Aq Mt jimmy@deefa.com and .An David Hayes Aq Mt david.hayes@ieee.org . .Pp This manual page was written by .An David Hayes Aq Mt david.hayes@ieee.org and .An Lawrence Stewart Aq Mt lstewart@FreeBSD.org . diff --git a/stand/man/loader.efi.8 b/stand/man/loader.efi.8 index 736b07d2922d..1417d994478c 100644 --- a/stand/man/loader.efi.8 +++ b/stand/man/loader.efi.8 @@ -1,492 +1,492 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2019-2022 Netflix, Inc .\" Copyright (c) 2022 Mateusz Piotrowski <0mp@FreeBSD.org> .\" Copyright 2022 The FreeBSD Foundation .\" .\" Part of this documentation was written by .\" Konstantin Belousov under sponsorship .\" from the FreeBSD Foundation. .\" .\" 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. .\" .Dd September 3, 2024 .Dt LOADER.EFI 8 .Os .Sh NAME .Nm loader.efi .Nd UEFI kernel loader .Sh DESCRIPTION On UEFI systems, .Nm loads the kernel. .Pp .Xr boot1.efi 8 is used to load .Nm when it is placed within a UFS or ZFS file system. Alternatively, .Nm is used directly when configured with .Xr efibootmgr 8 , or when placed directly as the default boot program as described in .Xr uefi 8 . When a system is built using .Xr bsdinstall 8 , .Nm will be used directly. .Ss Console Considerations The EFI BIOS provides a generic console. In .Nm this is selected by specifying .Dq efi using the .Dv console variable. .Nm examines the .Dv 8be4df61-93ca-11d2-aa0d-00e098032b8c-ConOut UEFI environment variable to guess what the .Dq efi console points to. .Nm will output its prompts and menus to all the places specified by ConOut. However, the .Fx kernel has a limitation when more than one console is present. The kernel outputs to all configured consoles. Only the primary console will get the log messages from the .Xr rc 8 system, and prompts for things like .Xr geli 8 passwords. If .Nm finds a video device first, then .Nm tells the kernel to use the video console as primary. Likewise, if a serial device is first in the .Dv ConOut list, the serial port will be the primary console. .Pp If there is no .Dv ConOut variable, both serial and video are attempted. .Nm uses the .Dq efi console for the video (which may or may not work) and .Dq comconsole for the serial on .Dv COM1 at the default baud rate. The kernel will use a dual console, with the video console primary if a UEFI graphics device is detected, or the serial console as primary if not. .Pp On x86 platforms, if you wish to redirect the loader's output to a serial port when the EFI BIOS doesn't support it, or to a serial port that isn't the one the EFI BIOS redirects its output to, set .Dv console to .Dq comconsole . The default port is .Dv COM1 with an I/O address of 0x3f8. .Dv comconsole_port is used to set this to a different port address. .Dv comconsole_speed is used to set the of the serial port (the default is 9600). If you have .Dv console set to .Dq efi,comconsole you will get output on both the EFI console and the serial port. If this causes a doubling of characters, set .Dv console to .Dq efi , since your EFI BIOS is redirecting to the serial port already. .Pp If your EFI BIOS redirects the serial port, you may need to tell the kernel which address to use. EFI uses ACPI's UID to identify the serial port, but .Nm does not have an ACPI parser, so it cannot convert that to an I/O port. The .Fx kernel initializes its consoles before it can decode ACPI resources. The .Fx kernel will look at the .Dv hw.uart.console variable to set its serial console. Its format should be described in .Xr uart 4 but is not. Set it to .Dq io:0x3f8,br:115200 with the proper port address. PCI or memory mapped ports are beyond the scope of this man page. .Pp The serial ports are assigned as follows on IBM PC compatible systems: .Bl -column -offset indent ".Sy Windows Name" ".Sy I/O Port Address" ".Sy Typical FreeBSD device" .It Sy Windows Name Ta Sy I/O Port Address Ta Sy Typical FreeBSD device .It COM1 Ta 0x3f8 Ta Pa /dev/uart0 .It COM2 Ta 0x2f8 Ta Pa /dev/uart1 .It COM3 Ta 0x3e8 Ta Pa /dev/uart2 .It COM4 Ta 0x2e8 Ta Pa /dev/uart3 .El Though .Dv COM3 and .Dv COM4 can vary. .Pp .Ss Primary Console The primary console is set using the boot flags. These command line arguments set corresponding flags for the kernel. These flags can be controlled by setting loader environment variables to .Dq yes or .Dq no . Boot flags may be set on the command line to the boot command. Inside the kernel, the RB_ flags are used to control behavior, sometimes in architecturally specific ways and are included to aid in discovery of any behavior not covered in this document. .Bl -column -offset indent ".Sy boot flag" ".Sy loader variable" ".Sy Kernel RB_ flag" .It Sy boot flag Ta Sy loader variable Ta Sy Kernel RB_ flag .It Fl a Ta Dv boot_askme Ta Va RB_ASKNAME .It Fl c Ta Dv boot_cdrom Ta Va RB_CDROM .It Fl d Ta Dv boot_ddb Ta Va RB_KDB .It Fl r Ta Dv boot_dfltroot Ta Va RB_DFLTROOT .It Fl D Ta Dv boot_multiple Ta Va RB_MULTIPLE .It Fl m Ta Dv boot_mute Ta Va RB_MUTE .It Fl g Ta Dv boot_gdb Ta Va RB_GDB .It Fl h Ta Dv boot_serial Ta Va RB_SERIAL .It Fl p Ta Dv boot_pause Ta Va RB_PAUSE .It Fl P Ta Dv boot_probe Ta Va RB_PROBE .It Fl s Ta Dv boot_single Ta Va RB_SINGLE .It Fl v Ta Dv boot_verbose Ta Va RB_VERBOSE .El And the following flags determine the primary console: .Bl -column -offset indent ".Sy Flags" ".Sy Kernel Flags" ".Sy Kernel Consoles" ".Sy Primary Console" .It Sy Flags Ta Sy Kernel Flags Ta Sy Kernel Consoles Ta Sy Primary Console .It none Ta 0 Ta Video Ta Video .It Fl h Ta RB_SERIAL Ta Serial Ta Serial .It Fl D Ta RB_MULTIPLE Ta Serial, Video Ta Video .It Fl Dh Ta RB_SERIAL | RB_MULTIPLE Ta Serial, Video Ta Serial .El .Pp .Nm does not implement the probe .Fl P functionality where we use the video console if a keyboard is connected and a serial console otherwise. .Ss Additional Environment Variables .Nm loads some extra variables early in startup from .Pa /efi/freebsd/loader.env from the EFI partition. Only simple variables can be set here. It can be useful to specify the root filesystem: .Bd -literal -offset indent rootdev=disk0s1a .Ed .Ss Staging Slop The kernel must parse the firmware memory map tables to know what memory it can use. Since it must allocate memory to do this, .Nm ensures there's extra memory available, called .Dq slop , after everything it loads .Po the kernel, modules and metadata .Pc for the kernel to bootstrap the memory allocator. .Pp By default, amd64 reserves 8MB. The .Ic staging_slop command allows for tuning the slop size. It takes a single argument, the size of the slop in bytes. .Ss amd64 Nocopy .Nm will load the kernel into memory that is 2MB aligned below 4GB. It cannot load to a fixed address because the UEFI firmware may reserve arbitrary memory for its use at runtime. Prior to .Fx 13.1 , kernels retained the old BIOS-boot protocol of loading at exactly 2MB. Such kernels must be copied from their loaded location to 2MB prior starting them up. The .Ic copy_staging command is used to enable this copying for older kernels. It takes a single argument which can be one of .Bl -tag -width disable .It Ar disable Force-disable copying staging area to .Ad 2M . .It Ar enable Force-enable copying staging area to .Ad 2M . .It Ar auto Selects the behaviour based on the kernel's capability of boostraping from non-2M physical base. The kernel reports this capability by exporting the symbol .Va kernphys . .El .Pp Arm64 loaders have operated in the .Sq nocopy mode from their inception, so there is no .Ic copy_staging command on that platform. Riscv, 32-bit arm and arm64 have always loaded at any .Ad 2MB aligned location, so do not provide .Ic copy_staging . .Pp .Bd -ragged -offset indent .Sy Note. BIOS loaders on i386 and amd64 put the staging area starting at the physical address .Ad 2M , then enable paging with identical mapping for the low .Ad 1G . The initial port of .Nm followed the same scheme for handing control to the kernel, since it avoided modifications for the loader/kernel hand-off protocol, and for the kernel page table bootstrap. .Pp This approach is incompatible with the UEFI specification, and as a practical matter, caused troubles on many boards, because UEFI firmware is free to use any memory for its own needs. Applications like .Nm must only use memory explicitly allocated using boot interfaces. The original way also potentially destroyed UEFI runtime interfaces data. .Pp Eventually, .Nm and the kernel were improved to avoid this problem. .Ed .Ss amd64 Faults Because it executes in x86 protected mode, the amd64 version of .Nm is susceptible to CPU faults due to programmer mistakes and memory corruption. To make debugging such faults easier, amd64 .Nm can provide detailed reporting of the CPU state at the time of the fault. .Pp The .Ic grab_faults command installs a handler for faults directly in the IDT, avoiding the use of the UEFI debugging interface .Fn EFI_DEBUG_SUPPORT_PROTOCOL.RegisterExceptionCallback . That interface is left available for advanced debuggers in the UEFI environment. The .Ic ungrab_faults command tries to deinstall the fault handler, returning TSS and IDT CPU tables to their pre-installation state. The .Ic fault command produces a fault in the .Nm environment for testing purposes, by executing the .Ic ud2 processor instruction. .Sh FILES .Bl -tag -width "/boot/loader.efi" .It Pa /boot/loader.efi The location of the UEFI kernel loader within the system. .El .Ss EFI System Partition .Nm is installed on the ESP (EFI System Partition) in one of the following locations: .Bl -tag -width "efi/freebsd/loader.efi" .It Pa efi/boot/bootXXX.efi The default location for any EFI loader .Po see .Xr uefi 8 for values to replace .Ql XXX with .Pc . .It Pa efi/freebsd/loader.efi The location reserved specifically for the .Fx EFI loader. .El .Pp The default location for the ESP mount point is documented in .Xr hier 7 . .Sh EXAMPLES .Ss Updating loader.efi on the ESP The following example shows how to install a new .Nm on the ESP. The exact placement is complicated due to the diversity of installations, setups and situations. In this section, paths that are all lower case are Unix paths. Paths that are all upper case are relative to the ESP mount point, though they may appear as lower case on your system because the -FAT filesystem of the ESP is case insensitive. +FAT filesystem of the ESP is case insensitive. .Pp Locate the ESP, which has its own partition type of .Dq efi : .Bd -literal -offset indent # gpart show nda0 => 40 7501476448 nda0 GPT (3.5T) 40 614400 1 efi (300M) 614440 7500862048 2 freebsd-zfs (3.5T) .Ed .Pp The name of the ESP on this system is .Pa nda0p1 . By default, this will be mounted on .Pa /boot/efi . To check: .Bd -literal -offset indent # mount | grep nda0p1 /dev/nda0p1 on /boot/efi (msdosfs, local) .Ed If it's not mounted, you will need to mount it: .Bd -literal -offset indent # mount -t msdosfs /dev/nda0p1 /boot/efi .Ed .Pp .Xr efibootmgr 8 reports what we booted from. .Bd -literal -offset indent # efibootmgr -v Boot to FW : false BootCurrent: 0001 Timeout : 2 seconds BootOrder : 0000, 0001, 0003, 0004, 0005, 0006, 0001, 0008, 000A, 000B, 000C, 000E, 0007 \&... +Boot0001* FreeBSD ZPOOL HD(1,GPT,b5d0f86b-265d-1e1b-18aa-0ed55e1e73bd,0x28,0x96000)/File(\EFI\FREEBSD\LOADER.EFI) nda0p1:/EFI/FREEBSD/LOADER.EFI /boot/efi//EFI/FREEBSD/LOADER.EFI \&... .Ed Often there are several options, depending on the BIOS. The entry that we booted with is marked with a .Sq + at the start of the line, as shown above. So in this case, this firmware is using .Pa /EFI/FREEBSD/LOADER.EFI from the ESP. Often times it will be the UEFI .Dq default loader, which varies by architecture. .Bl -column -offset indent "Architecture" "Default Path" .It Sy Architecture Ta Sy Default Path .It amd64 Ta Pa /EFI/BOOT/BOOTX64.EFI .It arm Ta Pa /EFI/BOOT/BOOTARM.EFI .It arm64 Ta Pa /EFI/BOOT/BOOTAA64.EFI .It i386 Ta Pa /EFI/BOOT/BOOTIA32.EFI .It riscv Ta Pa /EFI/BOOT/BOOTRISCV64.EFI .El However, care must be taken: some multiple-boot environments rely on a special .Pa bootXXX.efi to function. Before updating a .Pa bootXXX.efi file, make sure it is the FreeBSD boot loader before updating it: .Bd -literal -offset indent # strings /boot/efi/EFI/BOOT/BOOTX64.EFI | grep FreeBSD | grep EFI FreeBSD/amd64 EFI loader, Revision 3.0 .Ed .Pp .Xr bsdinstall 8 copies .Pa loader.efi to the default name if there wasn't one there before. Check to see if they are copies before updating (with X64 substituted using the above table): .Bd -literal -offset indent # cmp /boot/efi/EFI/FREEBSD/LOADER.EFI /boot/efi/EFI/BOOT/BOOTX64.EFI .Ed Copy the loader: .Bd -literal -offset indent # cp /boot/loader.efi /boot/efi/EFI/FREEBSD/LOADER.EFI .Ed replacing the all caps part of the example with the proper path. .Pp If ESP path was .Pa /FREEBSD/LOADER.EFI and LOADER.EFI and BOOTX64.EFI were identical in the cmp step, copy the loader to the default location: .Bd -literal -offset indent # cp /boot/loader.efi /boot/efi/EFI/BOOT/BOOTX64.EFI .Ed .Pp Finally, if you mounted the ESP, you may wish to unmount it. .Bd -literal -offset indent # umount /boot/efi .Ed .Sh SEE ALSO .Xr loader 8 , .Xr uefi 8 .Sh BUGS Non-x86 serial console handling is even more confusing and less well documented. .Pp Sometimes when the serial port speed isn't set, 9600 is used. Other times the result is typically 115200 since the speed remains unchanged from the default. .Pp U-Boot implements a subset of the UEFI standard. Some versions do not support fetching loader variables, so .Pa efibootmgr may not work. In addition, .Pa efibootmgr is not supported on armv7 or riscv. In these instances, the user has to understand what was booted to update it properly (and in most cases, it will be the FreeBSD path and the UEFI default so just copy loader.efi there if there are loaders there). Typically in these embedded situations, there is only one .efi file (loader.efi or a copy of loader.efi). The path to this file is typically the default removable path above. .Pp Managing booting multiple OSes on UEFI varies greatly, so extra caution when updating the UEFI default loader. .Pp The old, now obsolete, boot1.efi was installed as bootx64.efi in .Fx 10 and earlier. Since it was quite limited in functionality, we created very small ESPs by default. A modern loader.efi will not fit. However, if the old boot1.efi still works, there's no need to update it since it will chain boot /boot/loader.efi from a copy that make installworld updates. diff --git a/usr.sbin/i2c/i2c.8 b/usr.sbin/i2c/i2c.8 index 3415b614f87d..b5ce8aaea1a4 100644 --- a/usr.sbin/i2c/i2c.8 +++ b/usr.sbin/i2c/i2c.8 @@ -1,224 +1,224 @@ .\" .\" Copyright (C) 2008-2009 Semihalf, Michal Hajduk and Bartlomiej Sieka .\" 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 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. .\" .Dd May 22, 2019 .Dt I2C 8 .Os .Sh NAME .Nm i2c .Nd test I2C bus and slave devices .Sh SYNOPSIS .Nm .Cm -a Ar address .Op Fl f Ar device .Op Fl d Ar r|w .Op Fl w Ar 0|8|16|16LE|16BE .Op Fl o Ar offset .Op Fl c Ar count .Op Fl m Ar tr|ss|rs|no .Op Fl b .Op Fl v .Nm .Cm -h .Nm .Cm -i .Op Fl v .Op Ar cmd ... .Op Ar - .Nm .Cm -r .Op Fl f Ar device .Op Fl v .Nm .Cm -s .Op Fl f Ar device .Op Fl n Ar skip_addr .Op Fl v .Sh DESCRIPTION The .Nm utility can be used to perform raw data transfers (read or write) to devices on an I2C bus. It can also scan the bus for available devices and reset the I2C controller. .Pp The options are as follows: .Bl -tag -width ".Fl d Ar direction" .It Fl a Ar address 7-bit address on the I2C device to operate on (hex). .It Fl b binary mode - when performing a read operation, the data read from the device is output in binary format on stdout. .It Fl c Ar count number of bytes to transfer (decimal). .It Fl d Ar r|w transfer direction: r - read, w - write. Data to be written is read from stdin as binary bytes. .It Fl f Ar device I2C bus to use (default is /dev/iic0). .It Fl i Interpreted mode .It Fl h Help .It Fl m Ar tr|ss|rs|no addressing mode, i.e., I2C bus operations performed after the offset for the transfer has been written to the device and before the actual read/write operation. .Bl -tag -compact -offset indent .It Va tr complete-transfer .It Va ss stop then start .It Va rs repeated start .It Va no none .El Some I2C bus hardware does not provide control over the individual start, repeat-start, and stop operations. Such hardware can only perform a complete transfer of the offset and the data as a single operation. The .Va tr mode creates control structures describing the transfer and submits them to the driver as a single complete transaction. This mode works on all types of I2C hardware. .It Fl n Ar skip_addr address(es) to be skipped during bus scan. One or more addresses ([0x]xx) or ranges of addresses ([0x]xx-[0x]xx or [0x]xx..[0x]xx) separated by commas or colons. .It Fl o Ar offset offset within the device for data transfer (hex). The default is zero. Use .Dq -w 0 to disable writing of the offset to the slave. .It Fl r reset the controller. .It Fl s scan the bus for devices. .It Fl v be verbose. .It Fl w Ar 0|8|16|16LE|16BE device offset width (in bits). This is used to determine how to pass .Ar offset specified with .Fl o to the slave. Zero means that the offset is ignored and not passed to the slave at all. The endianness defaults to little-endian. .El .Sh INTERPRETED MODE When started with .Fl i any remaining arguments are interpreted as commands, and if the last argument is '-', or there are no arguments, commands will (also) be read from stdin. .Pp Available commands: .Bl -tag -compact .It 'r' bus address [0|8|16|16LE|16BE] offset count Read command, count bytes are read and hexdumped to stdout. .It 'w' bus address [0|8|16|16LE|16BE] offset hexstring Write command, hexstring (white-space is allowed) is written to device. .It 'p' anything Print command, the entire line is printed to stdout. (This can be used for synchronization.) .El .Pp All numeric fields accept canonical decimal/octal/hex notation. .Pp Without the .Fl v option, all errors are fatal with non-zero exit status. .Pp With the .Fl v option, no errors are fatal, and all commands will return either "OK\en" or "ERROR\en" on stdout. In case of error, detailed diagnostics will precede that on stderr. .Pp Blank lines and lines starting with '#' are ignored. .Sh EXAMPLES .Bl -bullet .It Scan the default bus (/dev/iic0) for devices: .Pp i2c -s .It -Scan the default bus (/dev/iic0) for devices and skip addresses +Scan the default bus (/dev/iic0) for devices and skip addresses 0x45 to 0x47 (inclusive) and 0x56. .Pp i2c -s -n 0x56,45-47 .It Read 8 bytes of data from device at address 0x56 (e.g., an EEPROM): .Pp i2c -a 0x56 -d r -c 8 .It Write 16 bytes of data from file data.bin to device 0x56 at offset 0x10: .Pp i2c -a 0x56 -d w -c 16 -o 0x10 -b < data.bin .It Copy 4 bytes between two EEPROMs (0x56 on /dev/iic1 to 0x57 on /dev/iic0): .Pp i2c -a 0x56 -f /dev/iic1 -d r -c 0x4 -b | i2c -a 0x57 -f /dev/iic0 -d w -c 4 -b .It Reset the controller: .Pp i2c -f /dev/iic1 -r .It Read 8 bytes at address 24 in an EEPROM: .Pp i2c -i 'r 0 0x50 16BE 24 8' .It Read 2x8 bytes at address 24 and 48 in an EEPROM: .Pp echo 'r 0 0x50 16BE 48 8' | i2c -i 'r 0 0x50 16BE 24 8' - .El .Sh WARNING Many systems store critical low-level information in I2C memories, and may contain other I2C devices, such as temperature or voltage sensors. Reading these can disturb the firmware's operation and writing to them can "brick" the hardware. .Sh SEE ALSO .Xr iic 4 , .Xr iicbus 4 , .Xr smbus 4 .Sh HISTORY The .Nm utility appeared in .Fx 8.0 . .Sh AUTHORS .An -nosplit The .Nm utility and this manual page were written by .An Bartlomiej Sieka Aq Mt tur@semihalf.com and .An Michal Hajduk Aq Mt mih@semihalf.com . .Pp .An Poul-Henning Kamp Aq Mt phk@FreeBSD.org added interpreted mode. diff --git a/usr.sbin/jail/jail.8 b/usr.sbin/jail/jail.8 index 0dcab757ef24..67f325d15a93 100644 --- a/usr.sbin/jail/jail.8 +++ b/usr.sbin/jail/jail.8 @@ -1,1533 +1,1533 @@ .\" Copyright (c) 2000, 2003 Robert N. M. Watson .\" Copyright (c) 2008-2012 James Gritton .\" 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. .\" .Dd September 19, 2024 .Dt JAIL 8 .Os .Sh NAME .Nm jail .Nd "manage system jails" .Sh SYNOPSIS .Ss From Configuration File .Nm .Op Fl cm .Op Fl Cdqv .Op Fl f Ar conf_file .Op Fl p Ar limit .Op Ar jail .Nm .Op Fl r .Op Fl Cqv .Op Fl f Ar conf_file .Op Fl p Ar limit .Op Cm * | Ar jail ... .Ss Without Configuration File .Nm .Op Fl cm .Op Fl dhilqv .Op Fl J Ar jid_file .Op Fl u Ar username .Op Fl U Ar username .Ar param Ns = Ns Ar value ... .Op Cm command Ns = Ns Ar command ... .Nm .Op Fl rR .Op Fl qv .Op Cm * | Ar jail ... .Ss Show Parameters .Nm .Op Fl f Ar conf_file .Fl e .Ar separator .Ss Backward Compatibility .Nm .Op Fl dhilqv .Op Fl J Ar jid_file .Op Fl u Ar username .Op Fl U Ar username .Op Fl n Ar jailname .Op Fl s Ar securelevel .Ar path hostname ip Ns Op Cm \&, Ns Ar ... .Ar command ... .Sh DESCRIPTION The .Nm utility creates new jails, or modifies or removes existing jails. It can also print a list of configured jails and their parameters. A jail .Pq or Dq prison is specified via parameters on the command line, or in the .Xr jail.conf 5 file. .Pp At least one of the options .Fl c , .Fl e , .Fl m or .Fl r must be specified. These options are used alone or in combination to describe the operation to perform: .Bl -tag -width indent .It Fl c Create a new jail. The jail .Va jid and .Va name parameters (if specified on the command line) must not refer to an existing jail. .It Fl e Ar separator Exhibit a list of all configured non-wildcard jails and their parameters. No jail creation, modification or removal performed if this option is used. The .Ar separator string is used to separate parameters. Use .Xr jls 8 utility to list running jails. .It Fl m Modify an existing jail. One of the .Va jid or .Va name parameters must exist and refer to an existing jail. Some parameters may not be changed on a running jail. .It Fl r Remove the .Ar jail specified by jid or name. All jailed processes are killed, and all jails that are children of this jail are also removed. .It Fl rc Restart an existing jail. The jail is first removed and then re-created, as if .Dq Nm Fl r and .Dq Nm Fl c were run in succession. .It Fl cm Create a jail if it does not exist, or modify the jail if it does exist. .It Fl mr Modify an existing jail. The jail may be restarted if necessary to modify parameters than could not otherwise be changed. .It Fl cmr Create a jail if it doesn't exist, or modify (and possibly restart) the jail if it does exist. .El .Pp Other available options are: .Bl -tag -width indent .It Fl C Clean up after an already-removed jail, running commands and operations that are typically run following jail removal. .It Fl f Ar conf_file Use configuration file .Ar conf_file instead of the default .Pa /etc/jail.conf . .It Fl h Resolve the .Va host.hostname parameter (or .Va hostname ) and add all IP addresses returned by the resolver to the list of addresses for this jail. This is equivalent to the .Va ip_hostname parameter. .It Fl i Output (only) the jail identifier of the newly created jail(s). This implies the .Fl q option. .It Fl J Ar jid_file Write a .Ar jid_file file, containing the parameters used to start the jail. .It Fl l Run commands in a clean environment. This is deprecated and is equivalent to the exec.clean parameter. .It Fl n Ar jailname Set the jail's name. This is deprecated and is equivalent to the .Va name parameter. .It Fl p Ar limit Limit the number of commands from .Va exec.* that can run simultaneously. .It Fl q Suppress the message printed whenever a jail is created, modified or removed. Only error messages will be printed. .It Fl R A variation of the .Fl r option that removes an existing jail without using the configuration file. No removal-related parameters for this jail will be used \(em the jail will simply be removed. .It Fl s Ar securelevel Set the .Va kern.securelevel MIB entry to the specified value inside the newly created jail. This is deprecated and is equivalent to the .Va securelevel parameter. .It Fl u Ar username The user name from host environment as whom jailed commands should run. This is deprecated and is equivalent to the .Va exec.jail_user and .Va exec.system_jail_user parameters. .It Fl U Ar username The user name from the jailed environment as whom jailed commands should run. This is deprecated and is equivalent to the .Va exec.jail_user parameter. .It Fl v Print a message on every operation, such as running commands and mounting filesystems. .It Fl d This is deprecated and is equivalent to the .Va allow.dying parameter, which is also deprecated. It used to allow making changes to a .Va dying jail. Now such jails are always replaced when a new jail is created with the same .Va jid or .Va name . .El .Pp If no arguments are given after the options, the operation (except remove) will be performed on all jails specified in the .Xr jail.conf 5 file. A single argument of a jail name will operate only on the specified jail. The .Fl r and .Fl R options can also remove running jails that aren't in the .Xr jail.conf 5 file, specified by name or jid. .Pp An argument of .Dq * is a wildcard that will operate on all jails, regardless of whether they appear in .Xr jail.conf 5 ; this is the surest way for .Fl r to remove all jails. If hierarchical jails exist, a partial-matching wildcard definition may be specified. For example, an argument of .Dq foo.* would apply to jails with names like .Dq foo.bar and .Dq foo.bar.baz . .Pp A jail may also be specified via parameters directly on the command line in .Dq name=value form, ignoring the contents of .Xr jail.conf 5 . For backward compatibility, the command line may also have four fixed parameters, without names: .Ar path , .Ar hostname , .Ar ip , and .Ar command . .Ss Jail Parameters Parameters in the .Xr jail.conf 5 file, or on the command line, are generally of the form .Dq name=value . Some parameters are boolean, and do not have a value but are set by the name alone with or without a .Dq no prefix, e.g. .Va persist or .Va nopersist . They can also be given the values .Dq true and .Dq false . Other parameters may have more than one value, specified as a comma-separated list or with .Dq += in the configuration file (see .Xr jail.conf 5 for details). .Pp The .Nm utility recognizes two classes of parameters. There are the true jail parameters that are passed to the kernel when the jail is created, which can be seen with .Xr jls 8 , and can (usually) be changed with .Dq Nm Fl m . Then there are pseudo-parameters that are only used by .Nm itself. .Pp Jails have a set of core parameters, and kernel modules can add their own jail parameters. The current set of available parameters can be retrieved via .Dq Nm sysctl Fl d Va security.jail.param . Any parameters not set will be given default values, often based on the current environment. The core parameters are: .Bl -tag -width indent .It Va jid The jail identifier. This will be assigned automatically to a new jail (or can be explicitly set), and can be used to identify the jail for later modification, or for such commands as .Xr jls 8 or .Xr jexec 8 . .It Va name The jail name. This is an arbitrary string that identifies a jail (except it may not contain a .Sq \&. ) . Like the .Va jid , it can be passed to later .Nm commands, or to .Xr jls 8 or .Xr jexec 8 . If no .Va name is supplied, a default is assumed that is the same as the .Va jid . The .Va name parameter is implied by the .Xr jail.conf 5 file format, and need not be explicitly set when using the configuration file. .It Va path The directory which is to be the root of the jail. Any commands run inside the jail, either by .Nm or from .Xr jexec 8 , are run from this directory. .It Va ip4.addr A list of IPv4 addresses assigned to the jail. If this is set, the jail is restricted to using only these addresses. Any attempts to use other addresses fail, and attempts to use wildcard addresses silently use the jailed address instead. For IPv4 the first address given will be used as the source address when source address selection on unbound sockets cannot find a better match. It is only possible to start multiple jails with the same IP address if none of the jails has more than this single overlapping IP address assigned to itself. .It Va ip4.saddrsel A boolean option to change the formerly mentioned behaviour and disable IPv4 source address selection for the jail in favour of the primary IPv4 address of the jail. Source address selection is enabled by default for all jails and the .Va ip4.nosaddrsel setting of a parent jail is not inherited for any child jails. .It Va ip4 Control the availability of IPv4 addresses. Possible values are .Dq inherit to allow unrestricted access to all system addresses, .Dq new to restrict addresses via .Va ip4.addr , and .Dq disable to stop the jail from using IPv4 entirely. Setting the .Va ip4.addr parameter implies a value of .Dq new . .It Va ip6.addr , Va ip6.saddrsel , Va ip6 A set of IPv6 options for the jail, the counterparts to .Va ip4.addr , .Va ip4.saddrsel and .Va ip4 above. .It Va vnet Create the jail with its own virtual network stack, with its own network interfaces, addresses, routing table, etc. The kernel must have been compiled with the .Sy VIMAGE option for this to be available. Possible values are .Dq inherit to use the system network stack, possibly with restricted IP addresses, and .Dq new to create a new network stack. .It Va host.hostname The hostname of the jail. Other similar parameters are .Va host.domainname , .Va host.hostuuid and .Va host.hostid . .It Va host Set the origin of hostname and related information. Possible values are .Dq inherit to use the system information and .Dq new for the jail to use the information from the above fields. Setting any of the above fields implies a value of .Dq new . .It Va securelevel The value of the jail's .Va kern.securelevel sysctl. A jail never has a lower securelevel than its parent system, but by setting this parameter it may have a higher one. If the system securelevel is changed, any jail securelevels will be at least as secure. .It Va devfs_ruleset The number of the devfs ruleset that is enforced for mounting devfs in this jail. A value of zero (default) means no ruleset is enforced. Descendant jails inherit the parent jail's devfs ruleset enforcement. Mounting devfs inside a jail is possible only if the .Va allow.mount and .Va allow.mount.devfs permissions are effective and .Va enforce_statfs is set to a value lower than 2. Devfs rules and rulesets cannot be viewed or modified from inside a jail. .Pp NOTE: It is important that only appropriate device nodes in devfs be exposed to a jail; access to disk devices in the jail may permit processes in the jail to bypass the jail sandboxing by modifying files outside of the jail. See .Xr devfs 8 for information on how to use devfs rules to limit access to entries in the per-jail devfs. A simple devfs ruleset for jails is available as ruleset #4 in .Pa /etc/defaults/devfs.rules . .It Va children.max The number of child jails allowed to be created by this jail (or by other jails under this jail). This limit is zero by default, indicating the jail is not allowed to create child jails. See the .Sx "Hierarchical Jails" section for more information. .It Va children.cur The number of descendants of this jail, including its own child jails and any jails created under them. .It Va enforce_statfs This determines what information processes in a jail are able to get about mount points. It affects the behaviour of the following syscalls: .Xr statfs 2 , .Xr fstatfs 2 , .Xr getfsstat 2 , and .Xr fhstatfs 2 (as well as similar compatibility syscalls). When set to 0, all mount points are available without any restrictions. When set to 1, only mount points below the jail's chroot directory are visible. In addition to that, the path to the jail's chroot directory is removed from the front of their pathnames. When set to 2 (default), above syscalls can operate only on a mount-point where the jail's chroot directory is located. .It Va persist Setting this boolean parameter allows a jail to exist without any processes. Normally, a command is run as part of jail creation, and then the jail is destroyed as its last process exits. A new jail must have either the .Va persist parameter or .Va exec.start or .Va command pseudo-parameter set. .It Va cpuset.id The ID of the cpuset associated with this jail (read-only). .It Va dying This is true if the jail is in the process of shutting down (read-only). .It Va parent The .Va jid of the parent of this jail, or zero if this is a top-level jail (read-only). .It Va osrelease The string for the jail's .Va kern.osrelease sysctl and uname -r. .It Va osreldate The number for the jail's .Va kern.osreldate and uname -K. .It Va allow.* Some restrictions of the jail environment may be set on a per-jail basis. With the exception of .Va allow.set_hostname and .Va allow.reserved_ports , these boolean parameters are off by default. .Bl -tag -width indent .It Va allow.set_hostname The jail's hostname may be changed via .Xr hostname 1 or .Xr sethostname 3 . .It Va allow.sysvipc A process within the jail has access to System V IPC primitives. This is deprecated in favor of the per-module parameters (see below). When this parameter is set, it is equivalent to setting .Va sysvmsg , .Va sysvsem , and .Va sysvshm all to .Dq inherit . .It Va allow.raw_sockets The jail root is allowed to create raw sockets. Setting this parameter allows utilities like .Xr ping 8 and .Xr traceroute 8 to operate inside the jail. If this is set, the source IP addresses are enforced to comply with the IP address bound to the jail, regardless of whether or not the .Dv IP_HDRINCL flag has been set on the socket. Since raw sockets can be used to configure and interact with various network subsystems, extra caution should be used where privileged access to jails is given out to untrusted parties. .It Va allow.chflags Normally, privileged users inside a jail are treated as unprivileged by .Xr chflags 2 . When this parameter is set, such users are treated as privileged, and may manipulate system file flags subject to the usual constraints on .Va kern.securelevel . .It Va allow.mount privileged users inside the jail will be able to mount and unmount file system types marked as jail-friendly. The .Xr lsvfs 1 command can be used to find file system types available for mount from within a jail. This permission is effective only if .Va enforce_statfs is set to a value lower than 2. .It Va allow.mount.devfs privileged users inside the jail will be able to mount and unmount the devfs file system. This permission is effective only together with .Va allow.mount and only when .Va enforce_statfs is set to a value lower than 2. The devfs ruleset should be restricted from the default by using the .Va devfs_ruleset option. .It Va allow.quotas The jail root may administer quotas on the jail's filesystem(s). This includes filesystems that the jail may share with other jails or with non-jailed parts of the system. .It Va allow.read_msgbuf Jailed users may read the kernel message buffer. If the .Va security.bsd.unprivileged_read_msgbuf MIB entry is zero, this will be restricted to the root user. .It Va allow.socket_af Sockets within a jail are normally restricted to IPv4, IPv6, local (UNIX), and route. This allows access to other protocol stacks that have not had jail functionality added to them. .It Va allow.mlock Locking or unlocking physical pages in memory are normally not available within a jail. When this parameter is set, users may .Xr mlock 2 or .Xr munlock 2 memory subject to .Va security.bsd.unprivileged_mlock and resource limits. .It Va allow.nfsd The .Xr mountd 8 , .Xr nfsd 8 , .Xr nfsuserd 8 , .Xr gssd 8 and .Xr rpc.tlsservd 8 daemons are permitted to run inside a properly configured vnet-enabled jail. The jail's root must be a file system mount point and .Va enforce_statfs must not be set to 0, so that .Xr mountd 8 can export file systems visible within the jail. .Va enforce_statfs must be set to 1 if file systems mounted under the jail's file system need to be exported by .Xr mount 8 . For exporting only the jail's file system, a setting of 2 is sufficient. If the kernel configuration does not include the .Sy NFSD option, .Pa nfsd.ko must be loaded outside of the jails. This is normally done by adding .Dq nfsd to .Va kld_list in the .Xr rc.conf 5 file outside of the jails. Similarily, if the .Xr gssd 8 is to be run in a jail, either the kernel .Sy KGSSAPI option needs to be specified or .Dq kgssapi and .Dq kgssapi_krb5 need to be in .Va kld_list in the .Xr rc.conf 5 file outside of the jails. .It Va allow.reserved_ports The jail root may bind to ports lower than 1024. .It Va allow.unprivileged_proc_debug Unprivileged processes in the jail may use debugging facilities. .It Va allow.suser The value of the jail's .Va security.bsd.suser_enabled sysctl. The super-user will be disabled automatically if its parent system has it disabled. The super-user is enabled by default. .It Va allow.extattr Allow privileged process in the jail to manipulate filesystem extended attributes in the system namespace. .It Va allow.adjtime Allow privileged process in the jail to slowly adjusting global operating system time. For example through utilities like .Xr ntpd 8 . .It Va allow.settime Allow privileged process in the jail to set global operating system data and time. For example through utilities like .Xr date 1 . This permission includes also .Va allow.adjtime . .El .El .Pp Kernel modules may add their own parameters, which only exist when the module is loaded. These are typically headed under a parameter named after the module, with values of .Dq inherit to give the jail full use of the module, .Dq new to encapsulate the jail in some module-specific way, and .Dq disable to make the module unavailable to the jail. There also may be other parameters to define jail behavior within the module. Module-specific parameters include: .Bl -tag -width indent .It Va allow.mount.fdescfs privileged users inside the jail will be able to mount and unmount the fdescfs file system. This permission is effective only together with .Va allow.mount and only when .Va enforce_statfs is set to a value lower than 2. .It Va allow.mount.fusefs privileged users inside the jail will be able to mount and unmount fuse-based file systems. This permission is effective only together with .Va allow.mount and only when .Va enforce_statfs is set to a value lower than 2. .It Va allow.mount.nullfs privileged users inside the jail will be able to mount and unmount the nullfs file system. This permission is effective only together with .Va allow.mount and only when .Va enforce_statfs is set to a value lower than 2. .It Va allow.mount.procfs privileged users inside the jail will be able to mount and unmount the procfs file system. This permission is effective only together with .Va allow.mount and only when .Va enforce_statfs is set to a value lower than 2. .It Va allow.mount.linprocfs privileged users inside the jail will be able to mount and unmount the linprocfs file system. This permission is effective only together with .Va allow.mount and only when .Va enforce_statfs is set to a value lower than 2. .It Va allow.mount.linsysfs privileged users inside the jail will be able to mount and unmount the linsysfs file system. This permission is effective only together with .Va allow.mount and only when .Va enforce_statfs is set to a value lower than 2. .It Va allow.mount.tmpfs privileged users inside the jail will be able to mount and unmount the tmpfs file system. This permission is effective only together with .Va allow.mount and only when .Va enforce_statfs is set to a value lower than 2. .It Va allow.mount.zfs privileged users inside the jail will be able to mount and unmount the ZFS file system. This permission is effective only together with .Va allow.mount and only when .Va enforce_statfs is set to a value lower than 2. See .Xr zfs-jail 8 for information on how to configure the ZFS filesystem to operate from within a jail. .It Va allow.vmm The jail may access .Xr vmm 4 . This flag is only available when the .Xr vmm 4 kernel module is loaded. .It Va linux Determine how a jail's Linux emulation environment appears. A value of .Dq inherit will keep the same environment, and .Dq new will give the jail its own environment (still originally inherited when the jail is created). .It Va linux.osname , linux.osrelease , linux.oss_version The Linux OS name, OS release, and OSS version associated with this jail. .It Va sysvmsg Allow access to SYSV IPC message primitives. If set to .Dq inherit , all IPC objects on the system are visible to this jail, whether they were created by the jail itself, the base system, or other jails. If set to .Dq new , the jail will have its own key namespace, and can only see the objects that it has created; the system (or parent jail) has access to the jail's objects, but not to its keys. If set to .Dq disable , the jail cannot perform any sysvmsg-related system calls. .It Va sysvsem, sysvshm Allow access to SYSV IPC semaphore and shared memory primitives, in the same manner as .Va sysvmsg . .It Va zfs.mount_snapshot When set to 1, jailed users may access the contents of ZFS snapshots under the filesystem's .Pa .zfs directory. If .Va allow.mount.zfs is set, the snapshots may also be mounted. .El .Pp There are pseudo-parameters that are not passed to the kernel, but are used by .Nm to set up the jail environment, often by running specified commands when jails are created or removed. The .Va exec.* command parameters are .Xr sh 1 command lines that are run in either the system or jail environment. They may be given multiple values, which would run the specified commands in sequence. All commands must succeed (return a zero exit status), or the jail will not be created or removed, as appropriate. .Pp The pseudo-parameters are: .Bl -tag -width indent .It Va exec.prepare Command(s) to run in the system environment to prepare a jail for creation. These commands are executed before assigning IP addresses and mounting filesystems, so they may be used to create a new jail filesystem if it does not already exist. .It Va exec.prestart Command(s) to run in the system environment before a jail is created. .It Va exec.created Command(s) to run in the system environment right after a jail has been created, but before commands (or services) get executed in the jail. .It Va exec.start Command(s) to run in the jail environment when a jail is created. A typical command to run is .Dq sh /etc/rc . .It Va command A synonym for .Va exec.start for use when specifying a jail directly on the command line. Unlike other parameters whose value is a single string, .Va command uses the remainder of the .Nm command line as its own arguments. .It Va exec.poststart Command(s) to run in the system environment after a jail is created, and after any .Va exec.start commands have completed. .It Va exec.prestop Command(s) to run in the system environment before a jail is removed. .It Va exec.stop Command(s) to run in the jail environment before a jail is removed, and after any .Va exec.prestop commands have completed. A typical command to run is .Dq sh /etc/rc.shutdown jail . .It Va exec.poststop Command(s) to run in the system environment after a jail is removed. .It Va exec.release Command(s) to run in the system environment after all other actions are done. These commands are executed after unmounting filesystems and removing IP addresses, so they may be used to remove a jail filesystem if it is no longer needed. .It Va exec.clean Run commands in a clean environment. The environment is discarded except for .Ev HOME , SHELL , TERM and .Ev USER . .Ev HOME and .Ev SHELL are set to the target login's default values. .Ev USER is set to the target login. .Ev TERM is imported from the current environment. .Ev PATH is set to "/bin:/usr/bin". The environment variables from the login class capability database for the target login are also set. If a user is specified (as with .Va exec.jail_user ) , commands are run from that (possibly jailed) user's directory. .It Va exec.jail_user The user to run commands as, when running in the jail environment. The default is to run the commands as the current user. .It Va exec.system_jail_user This boolean option looks for the .Va exec.jail_user in the system .Xr passwd 5 file, instead of in the jail's file. .It Va exec.system_user The user to run commands as, when running in the system environment. The default is to run the commands as the current user. .It Va exec.timeout The maximum amount of time to wait for a command to complete, in seconds. If a command is still running after this timeout has passed, the jail will not be created or removed, as appropriate. .It Va exec.consolelog A file to direct command output (stdout and stderr) to. .It Va exec.fib The FIB (routing table) to set when running commands inside the jail. .It Va stop.timeout The maximum amount of time to wait for a jail's processes to exit after sending them a .Dv SIGTERM signal (which happens after the .Va exec.stop commands have completed). After this many seconds have passed, the jail will be removed, which will kill any remaining processes. If this is set to zero, no .Dv SIGTERM is sent and the jail is immediately removed. The default is 10 seconds. .It Va interface A network interface to add the jail's IP addresses .Va ( ip4.addr and .Va ip6.addr ) to. An alias for each address will be added to the interface before the jail is created, and will be removed from the interface after the jail is removed. .It Va ip4.addr In addition to the IP addresses that are passed to the kernel, an interface, netmask and additional parameters (as supported by .Xr ifconfig 8 Ns ) may also be specified, in the form .Dq Ar interface Ns | Ns Ar ip-address Ns / Ns Ar netmask param ... . If an interface is given before the IP address, an alias for the address will be added to that interface, as it is with the .Va interface parameter. If a netmask in either dotted-quad or CIDR form is given after an IP address, it will be used when adding the IP alias. If additional parameters are specified then they will also be used when adding the IP alias. .It Va ip6.addr In addition to the IP addresses that are passed to the kernel, an interface, prefix and additional parameters (as supported by .Xr ifconfig 8 Ns ) may also be specified, in the form .Dq Ar interface Ns | Ns Ar ip-address Ns / Ns Ar prefix param ... . .It Va vnet.interface A network interface to give to a vnet-enabled jail after is it created. The interface will automatically be released when the jail is removed. .It Va zfs.dataset A list of ZFS datasets to be attached to the jail. This requires .Va allow.mount.zfs to be set. -See +See .Xr zfs-jail 8 for information on how to configure a ZFS dataset to be operated from within a jail. .It Va ip_hostname Resolve the .Va host.hostname parameter and add all IP addresses returned by the resolver to the list of addresses .Po Va ip4.addr or .Va ip6.addr Pc for this jail. This may affect default address selection for outgoing IPv4 connections from jails. The address first returned by the resolver for each address family will be used as the primary address. .It Va mount A filesystem to mount before creating the jail (and to unmount after removing it), given as a single .Xr fstab 5 line. .It Va mount.fstab An .Xr fstab 5 format file containing filesystems to mount before creating a jail. .It Va mount.devfs Mount a .Xr devfs 4 filesystem on the chrooted .Pa /dev directory, and apply the ruleset in the .Va devfs_ruleset parameter (or a default of ruleset 4: devfsrules_jail) to restrict the devices visible inside the jail. .It Va mount.fdescfs Mount a .Xr fdescfs 4 filesystem on the chrooted .Pa /dev/fd directory. .It Va mount.procfs Mount a .Xr procfs 4 filesystem on the chrooted .Pa /proc directory. .It Va allow.dying This is deprecated and has no effect. It used to allow making changes to a .Va dying jail. Now such jails are always replaced when a new jail is created with the same .Va jid or .Va name . .It Va depend Specify a jail (or jails) that this jail depends on. When this jail is to be created, any jail(s) it depends on must already exist. If not, they will be created automatically, up to the completion of the last .Va exec.poststart command, before any action will taken to create this jail. When jails are removed the opposite is true: this jail will be removed, up to the last .Va exec.poststop command, before any jail(s) it depends on are stopped. .El .Sh EXAMPLES Jails are typically set up using one of two philosophies: either to constrain a specific application (possibly running with privilege), or to create a .Dq "virtual system image" running a variety of daemons and services. In both cases, a fairly complete file system install of .Fx is required, so as to provide the necessary command line tools, daemons, libraries, application configuration files, etc. However, for a virtual server configuration, a fair amount of additional work is required so as to replace the .Dq boot process. This manual page documents the configuration steps necessary to support either of these steps, although the configuration steps may need to be refined based on local requirements. .Ss "Setting up a Jail Directory Tree" To set up a jail directory tree containing an entire .Fx distribution, the following .Xr sh 1 command script can be used: .Bd -literal -offset indent D=/here/is/the/jail cd /usr/src mkdir -p $D make world DESTDIR=$D make distribution DESTDIR=$D .Ed .Pp In many cases this example would put far more in the jail than needed. In the other extreme case a jail might contain only one file: the executable to be run in the jail. .Pp We recommend experimentation, and caution that it is a lot easier to start with a .Dq fat jail and remove things until it stops working, than it is to start with a .Dq thin jail and add things until it works. .Ss "Setting Up a Jail" Do what was described in .Sx "Setting Up a Jail Directory Tree" to build the jail directory tree. For the sake of this example, we will assume you built it in .Pa /data/jail/testjail , for a jail named .Dq testjail . Substitute below as needed with your own directory, IP address, and hostname. .Ss "Setting up the Host Environment" First, set up the real system's environment to be .Dq jail-friendly . For consistency, we will refer to the parent box as the .Dq "host environment" , and to the jailed virtual machine as the .Dq "jail environment" . Since jails are implemented using IP aliases, one of the first things to do is to disable IP services on the host system that listen on all local IP addresses for a service. If a network service is present in the host environment that binds all available IP addresses rather than specific IP addresses, it may service requests sent to jail IP addresses if the jail did not bind the port. This means changing .Xr inetd 8 to only listen on the appropriate IP address, and so forth. Add the following to .Pa /etc/rc.conf in the host environment: .Bd -literal -offset indent sendmail_enable="NO" inetd_flags="-wW -a 192.0.2.23" rpcbind_enable="NO" .Ed .Pp .Li 192.0.2.23 is the native IP address for the host system, in this example. Daemons that run out of .Xr inetd 8 can be easily configured to use only the specified host IP address. Other daemons will need to be manually configured \(em for some this is possible through .Xr rc.conf 5 flags entries; for others it is necessary to modify per-application configuration files, or to recompile the application. The following frequently deployed services must have their individual configuration files modified to limit the application to listening to a specific IP address: .Pp To configure .Xr sshd 8 , it is necessary to modify .Pa /etc/ssh/sshd_config . .Pp To configure .Xr sendmail 8 , it is necessary to modify .Pa /etc/mail/sendmail.cf . .Pp In addition, a number of services must be recompiled in order to run them in the host environment. This includes most applications providing services using .Xr rpc 3 , such as .Xr rpcbind 8 , .Xr nfsd 8 , and .Xr mountd 8 . In general, applications for which it is not possible to specify which IP address to bind should not be run in the host environment unless they should also service requests sent to jail IP addresses. Attempting to serve NFS from the host environment may also cause confusion, and cannot be easily reconfigured to use only specific IPs, as some NFS services are hosted directly from the kernel. Any third-party network software running in the host environment should also be checked and configured so that it does not bind all IP addresses, which would result in those services also appearing to be offered by the jail environments. .Pp Once these daemons have been disabled or fixed in the host environment, it is best to reboot so that all daemons are in a known state, to reduce the potential for confusion later (such as finding that when you send mail to a jail, and its sendmail is down, the mail is delivered to the host, etc.). .Ss "Configuring the Jail" Start any jail for the first time without configuring the network interface so that you can clean it up a little and set up accounts. As with any machine (virtual or not), you will need to set a root password, time zone, etc. Some of these steps apply only if you intend to run a full virtual server inside the jail; others apply both for constraining a particular application or for running a virtual server. .Pp Start a shell in the jail: .Bd -literal -offset indent jail -c path=/data/jail/testjail mount.devfs \\ host.hostname=testhostname ip4.addr=192.0.2.100 \\ command=/bin/sh .Ed .Pp Assuming no errors, you will end up with a shell prompt within the jail. You can now run .Xr bsdconfig 8 and do the post-install configuration to set various configuration options, or perform these actions manually by editing .Pa /etc/rc.conf , etc. .Pp .Bl -bullet -offset indent -compact .It Configure .Pa /etc/resolv.conf so that name resolution within the jail will work correctly. .It Run .Xr newaliases 1 to quell .Xr sendmail 8 warnings. .It Set a root password, probably different from the real host system. .It Set the timezone. .It Add accounts for users in the jail environment. .It Install any packages the environment requires. .El .Pp You may also want to perform any package-specific configuration (web servers, SSH servers, etc), patch up .Pa /etc/syslog.conf so it logs as you would like, etc. If you are not using a virtual server, you may wish to modify .Xr syslogd 8 in the host environment to listen on the syslog socket in the jail environment; in this example, the syslog socket would be stored in .Pa /data/jail/testjail/var/run/log . .Pp Exit from the shell, and the jail will be shut down. .Ss "Starting the Jail" You are now ready to restart the jail and bring up the environment with all of its daemons and other programs. Create an entry for the jail in .Pa /etc/jail.conf : .Bd -literal -offset indent testjail { path = /tmp/jail/testjail; mount.devfs; host.hostname = testhostname; ip4.addr = 192.0.2.100; interface = em0; exec.start = "/bin/sh /etc/rc"; exec.stop = "/bin/sh /etc/rc.shutdown jail"; } .Ed .Pp To start a virtual server environment, .Pa /etc/rc is run to launch various daemons and services, and .Pa /etc/rc.shutdown is run to shut them down when the jail is removed. If you are running a single application in the jail, substitute the command used to start the application for .Dq /bin/sh /etc/rc ; there may be some script available to cleanly shut down the application, or it may be sufficient to go without a stop command, and have .Nm send .Dv SIGTERM to the application. .Pp Start the jail by running: .Bd -literal -offset indent jail -c testjail .Ed .Pp A few warnings may be produced; however, it should all work properly. You should be able to see .Xr inetd 8 , .Xr syslogd 8 , and other processes running within the jail using .Xr ps 1 , with the .Ql J flag appearing beside jailed processes. To see an active list of jails, use .Xr jls 8 . If .Xr sshd 8 is enabled in the jail environment, you should be able to .Xr ssh 1 to the hostname or IP address of the jailed environment, and log in using the accounts you created previously. .Pp It is possible to have jails started at boot time. Please refer to the .Dq jail_* variables in .Xr rc.conf 5 for more information. .Ss "Managing the Jail" Normal machine shutdown commands, such as .Xr halt 8 , .Xr reboot 8 , and .Xr shutdown 8 , cannot be used successfully within the jail. To kill all processes from within a jail, you may use one of the following commands, depending on what you want to accomplish: .Bd -literal -offset indent kill -TERM -1 kill -KILL -1 .Ed .Pp This will send the .Dv SIGTERM or .Dv SIGKILL signals to all processes in the jail \(em be careful not to run this from the host environment! Once all of the jail's processes have died, unless the jail was created with the .Va persist parameter, the jail will be removed. Depending on the intended use of the jail, you may also want to run .Pa /etc/rc.shutdown from within the jail. .Pp To shut down the jail from the outside, simply remove it with: .Bd -literal -offset indent jail -r .Ed .Pp which will run any commands specified by .Va exec.stop , and then send .Dv SIGTERM and eventually .Dv SIGKILL to any remaining jailed processes. .Pp The .Pa /proc/ Ns Ar pid Ns Pa /status file contains, as its last field, the name of the jail in which the process runs, or .Dq Li - to indicate that the process is not running within a jail. The .Xr ps 1 command also shows a .Ql J flag for processes in a jail. .Pp You can also list/kill processes based on their jail ID. To show processes and their jail ID, use the following command: .Pp .Dl "ps ax -o pid,jid,args" .Pp To show and then kill processes in jail number 3 use the following commands: .Bd -literal -offset indent pgrep -lfj 3 pkill -j 3 .Ed or: .Pp .Dl "killall -j 3" .Ss "Jails and File Systems" It is not possible to .Xr mount 8 or .Xr umount 8 any file system inside a jail unless the file system is marked jail-friendly, the jail's .Va allow.mount parameter is set, and the jail's .Va enforce_statfs parameter is lower than 2. .Pp Multiple jails sharing the same file system can influence each other. For example, a user in one jail can fill the file system, leaving no space for processes in the other jail. Trying to use .Xr quota 1 to prevent this will not work either, as the file system quotas are not aware of jails but only look at the user and group IDs. This means the same user ID in two jails share a single file system quota. One would need to use one file system per jail to make this work. .Ss "Sysctl MIB Entries" The read-only entry .Va security.jail.jailed can be used to determine if a process is running inside a jail (value is one) or not (value is zero). .Pp The variable .Va security.jail.jail_max_af_ips determines how may address per address family a jail may have. The default is 255. .Pp Some MIB variables have per-jail settings. Changes to these variables by a jailed process do not affect the host environment, only the jail environment. These variables are .Va kern.securelevel , .Va security.bsd.suser_enabled , .Va kern.hostname , .Va kern.domainname , .Va kern.hostid , and .Va kern.hostuuid . .Ss "Hierarchical Jails" By setting a jail's .Va children.max parameter, processes within a jail may be able to create jails of their own. These child jails are kept in a hierarchy, with jails only able to see and/or modify the jails they created (or those jails' children). Each jail has a read-only .Va parent parameter, containing the .Va jid of the jail that created it; a .Va jid of 0 indicates the jail is a child of the current jail (or is a top-level jail if the current process isn't jailed). .Pp Jailed processes are not allowed to confer greater permissions than they themselves are given, e.g., if a jail is created with .Va allow.nomount , it is not able to create a jail with .Va allow.mount set. Similarly, such restrictions as .Va ip4.addr and .Va securelevel may not be bypassed in child jails. .Pp A child jail may in turn create its own child jails if its own .Va children.max parameter is set (remember it is zero by default). These jails are visible to and can be modified by their parent and all ancestors. .Pp Jail names reflect this hierarchy, with a full name being an MIB-type string separated by dots. For example, if a base system process creates a jail .Dq foo , and a process under that jail creates another jail .Dq bar , then the second jail will be seen as .Dq foo.bar in the base system (though it is only seen as .Dq bar to any processes inside jail .Dq foo ) . Jids on the other hand exist in a single space, and each jail must have a unique jid. .Pp Like the names, a child jail's .Va path appears relative to its creator's own .Va path . This is by virtue of the child jail being created in the chrooted environment of the first jail. .Sh SEE ALSO .Xr date 1 , .Xr killall 1 , .Xr lsvfs 1 , .Xr newaliases 1 , .Xr pgrep 1 , .Xr pkill 1 , .Xr ps 1 , .Xr quota 1 , .Xr adjtime 2 , .Xr clock_settime 2 , .Xr jail_set 2 , .Xr ntp_adjtime 2 , .Xr devfs 4 , .Xr fdescfs 4 , .Xr linprocfs 4 , .Xr linsysfs 4 , .Xr procfs 4 , .Xr vmm 4 , .Xr jail.conf 5 , .Xr rc.conf 5 , .Xr sysctl.conf 5 , .Xr bsdconfig 8 , .Xr chroot 8 , .Xr devfs 8 , .Xr halt 8 , .Xr ifconfig 8 , .Xr inetd 8 , .Xr jexec 8 , .Xr jls 8 , .Xr mount 8 , .Xr mountd 8 , .Xr nfsd 8 , .Xr ntpd 8 , .Xr reboot 8 , .Xr rpcbind 8 , .Xr sendmail 8 , .Xr shutdown 8 , .Xr sysctl 8 , .Xr syslogd 8 , .Xr umount 8 , .Xr zfs-jail 8 , .Xr extattr 9 .Sh HISTORY The .Nm utility appeared in .Fx 4.0 . Hierarchical/extensible jails were introduced in .Fx 8.0 . The configuration file was introduced in .Fx 9.1 . .Sh AUTHORS .An -nosplit The jail feature was written by .An Poul-Henning Kamp for R&D Associates who contributed it to .Fx . .Pp .An Robert Watson wrote the extended documentation, found a few bugs, added a few new features, and cleaned up the userland jail environment. .Pp .An Bjoern A. Zeeb added multi-IP jail support for IPv4 and IPv6 based on a patch originally done by .An Pawel Jakub Dawidek for IPv4. .Pp .An James Gritton added the extensible jail parameters, hierarchical jails, and the configuration file. .Sh BUGS It might be a good idea to add an address alias flag such that daemons listening on all IPs .Pq Dv INADDR_ANY will not bind on that address, which would facilitate building a safe host environment such that host daemons do not impose on services offered from within jails. Currently, the simplest answer is to minimize services offered on the host, possibly limiting it to services offered from .Xr inetd 8 which is easily configurable. .Sh NOTES Great care should be taken when managing directories visible within the jail. For example, if a jailed process has its current working directory set to a directory that is moved out of the jail's chroot, then the process may gain access to the file space outside of the jail. It is recommended that directories always be copied, rather than moved, out of a jail. .Pp In addition, there are several ways in which an unprivileged user outside the jail can cooperate with a privileged user inside the jail and thereby obtain elevated privileges in the host environment. Most of these attacks can be mitigated by ensuring that the jail root is not accessible to unprivileged users in the host environment. Regardless, as a general rule, untrusted users with privileged access to a jail should not be given access to the host environment. diff --git a/usr.sbin/newsyslog/newsyslog.conf.5 b/usr.sbin/newsyslog/newsyslog.conf.5 index 9f229bc04402..a8ab132edaa8 100644 --- a/usr.sbin/newsyslog/newsyslog.conf.5 +++ b/usr.sbin/newsyslog/newsyslog.conf.5 @@ -1,458 +1,458 @@ .\" This file was split from the newsyslog(8) manual page by Tom Rhodes .\" and includes modifications as appropriate. .\" The original header is included below: .\" .\" This file contains changes from the Open Software Foundation. .\" .\" Copyright 1988, 1989 by the Massachusetts Institute of Technology .\" .\" Permission to use, copy, modify, and distribute this software .\" and its documentation for any purpose and without fee is .\" hereby granted, provided that the above copyright notice .\" appear in all copies and that both that copyright notice and .\" this permission notice appear in supporting documentation, .\" and that the names of M.I.T. and the M.I.T. S.I.P.B. not be .\" used in advertising or publicity pertaining to distribution .\" of the software without specific, written prior permission. .\" M.I.T. and the M.I.T. S.I.P.B. make no representations about .\" the suitability of this software for any purpose. It is .\" provided "as is" without express or implied warranty. .\" .Dd December 25, 2023 .Dt NEWSYSLOG.CONF 5 .Os .Sh NAME .Nm newsyslog.conf .Nd .Xr newsyslog 8 configuration file .Sh DESCRIPTION The .Nm file is used to set log file rotation configuration for the .Xr newsyslog 8 utility. Configuration may designate that logs are rotated based on size, last rotation time, or time of day. The .Nm file can also be used to designate secure permissions to log files at rotation time. During initialization, .Xr newsyslog 8 reads a configuration file, normally .Pa /etc/newsyslog.conf , to determine which logs may potentially be rotated and archived. Each line has five mandatory fields and four optional fields, separated with whitespace. Blank lines or lines beginning with .Ql # are ignored. If .Ql # is placed in the middle of the line, the .Ql # character and the rest of the line after it is ignored. To prevent special meaning, the .Ql # character may be escaped with .Ql \e ; in this case preceding .Ql \e is removed and .Ql # is treated as an ordinary character. The fields of the configuration file are as follows: .Bl -tag -width indent .It Ar logfile_name Name of the system log file to be archived, or one of the special strings .Dq Li , .Dq Li , or .Dq Li . The entry, which should be placed at the beginning of the .Nm configuration file, sets the global compress method. This method is applied when a log file is flagged as compressible, which has the same effect of passing a compress method to the .Fl c option on the .Xr newsyslog 8 command line. The special entry will only be used if a log file name is given as a command line argument to .Xr newsyslog 8 , and if that log file name is not matched by any other line in the configuration file. The include entry is used to include other configuration files and supports globbing. .It Ar owner : Ns Ar group This optional field specifies the owner and group for the archive file. The .Ql \&: is essential regardless if the .Ar owner or .Ar group field is left blank or contains a value. The field may be numeric, or a name which is present in .Pa /etc/passwd or .Pa /etc/group . .It Ar mode Specify the file mode of the log file and archives. Valid mode bits are .Dv 0666 . (That is, read and write permissions for the rotated log may be specified for the owner, group, and others.) All other mode bits are ignored. .It Ar count Specify the maximum number of archive files which may exist. This does not consider the current log file. .It Ar size When the size of the log file reaches .Ar size in kilobytes, the log file will be trimmed as described above. If this field contains an asterisk .Pq Ql * , the log file will not be trimmed based on size. .It Ar when The .Ar when field may consist of an interval, a specific time, or both. If the .Ar when field contains an asterisk .Pq Ql * , log rotation will solely depend on the contents of the .Ar size field. Otherwise, the .Ar when field consists of an optional interval in hours, usually followed by an .So Li \&@ Sc Ns No -sign and a time in restricted .Tn ISO 8601 format. Additionally, the format may also be constructed with a .Ql $ sign along with a rotation time specification of once a day, once a week, or once a month. .Pp Time based trimming happens only if .Xr newsyslog 8 is run within one hour of the specified time. If an interval is specified, the log file will be trimmed if that many hours have passed since the last rotation. When both a time and an interval are specified then both conditions must be satisfied for the rotation to take place. .Pp There is no provision for the specification of a timezone. There is little point in specifying an explicit minutes or seconds component in the current implementation, since the only comparison is .Dq within the hour . .Pp .Sy ISO 8601 restricted time format : .Pp The lead-in character for a restricted .Tn ISO 8601 time is an .Ql @ sign. The particular format of the time in restricted .Tn ISO 8601 is: .Sm off .Oo Oo Oo Oo Oo .Va cc Oc .Va yy Oc .Va mm Oc .Va dd Oc .Oo .Li T Oo .Va hh Oo .Va mm Oo .Va ss .Oc Oc Oc Oc Oc . .Sm on Optional date fields default to the appropriate component of the current date; optional time fields default to midnight; hence if today is January 22, 1999, the following date specifications are all equivalent: .Pp .Bl -item -compact -offset indent .It .Sq Li 19990122T000000 .It .Sq Li 990122T000000 .It .Sq Li 0122T000000 .It .Sq Li 22T000000 .It .Sq Li T000000 .It .Sq Li T0000 .It .Sq Li T00 .It .Sq Li 22T .It .Sq Li T .It .Sq Li \& .El .Pp .Sy Day, week, and month time format: .Pp The lead-in character for day, week, and month specification is a .Ql $ sign. The particular format of day, week, and month specification is: .Op Li D Ns Va hh , .Op Li W Ns Va w Ns Op Li D Ns Va hh , and .Op Li M Ns Va dd Ns Op Li D Ns Va hh , respectively. Optional time fields default to midnight. The ranges for day and hour specifications are: .Pp .Bl -tag -width indent -offset indent -compact .It Ar hh hours, range 0..23 .It Ar w day of week, range 0..6, 0 = Sunday .It Ar dd day of month, range 1..31, or one of the letters .Ql L or .Ql l to specify the last day of the month. .El .Pp Some examples: .Pp .Bl -tag -width indent -offset indent -compact .It Li $D0 rotate every night at midnight (same as .Li @T00 ) .It Li $D23 rotate every day at 23:00 (same as .Li @T23 ) .It Li $W0D23 rotate every week on Sunday at 23:00 .It Li $W5D16 rotate every week on Friday at 16:00 .It Li $M1D0 rotate at the first day of every month at midnight (i.e., the start of the day; same as .Li @01T00 ) .It Li $M5D6 rotate on every fifth day of month at 6:00 (same as .Li @05T06 ) .El .It Ar flags This optional field is made up of one or more characters that specify any special processing to be done for the log files matched by this line. The following are valid flags: .Bl -tag -width indent .It Cm B indicates that the log file is a binary file, or has some special format. Usually .Xr newsyslog 8 inserts an .Tn ASCII message into a log file during rotation. This message is used to indicate when, and sometimes why the log file was rotated. If .Cm B is specified, then that informational message will not be inserted into the log file. .It Cm C indicates that the log file should be created if it does not already exist, and if the .Fl C option was also specified on the command line. .It Cm D indicates that .Xr newsyslog 8 should set the .Dv UF_NODUMP flag when creating a new version of this log file. This option would affect how the .Xr dump 8 command treats the log file when making a file system backup. .It Cm E indicates that the log file should not be rotated when its size is zero. The .Cm E flag is mostly useful in conjunction with .Cm B flag to prevent .Xr newsyslog 8 -from inserting an informational +from inserting an informational .Tn ASCII message into the new file. .It Cm G indicates that the specified .Ar logfile_name is a shell pattern, and that .Xr newsyslog 8 should archive all filenames matching that pattern using the other options on this line. See .Xr glob 3 for details on syntax and matching rules. .It Cm J indicates that .Xr newsyslog 8 should consider the rotated log file as compressible. In legacy mode, this also tells .Xr newsyslog 8 to use .Xr bzip2 1 . .It Cm N indicates that there is no process which needs to be signaled when this log file is rotated. .It Cm P indicates that the zero-th rotated file should not be compressed. .It Cm R if this flag is set the .Xr newsyslog 8 will run shell command defined in .Ar path_to_pid_cmd_file after rotation instead of trying to send signal to a process id stored in the file. .It Cm T if this flag is set the informational rotation message written to the log file will be in the format specified by RFC5424. Normally, the rotation message is written in the traditional (RFC3164) syslog format. .It Cm U indicates that the file specified by .Ar path_to_pid_cmd_file will contain the ID for a process group instead of a process. This option also requires that the first line in that file be a negative value to distinguish it from a process ID. .It Cm X indicates that .Xr newsyslog 8 should consider the rotated log file as compressible. In legacy mode, this also tells .Xr newsyslog 8 to use .Xr xz 1 . .It Cm Y indicates that .Xr newsyslog 8 should consider the rotated log file as compressible. In legacy mode, this also tells .Xr newsyslog 8 to use .Xr zstd 1 . .It Cm Z indicates that .Xr newsyslog 8 should consider the rotated log file as compressible. In legacy mode, this also tells .Xr newsyslog 8 to use .Xr gzip 1 . .It Fl a minus sign will not cause any special processing, but it can be used as a placeholder to create a .Ar flags field when you need to specify any of the following fields. .El .It Ar path_to_pid_cmd_file This optional field specifies the file name containing a daemon's process ID or to find a group process ID if the .Cm U flag was specified. If this field is present, a .Ar signal is sent to the process ID contained in this file. If this field is not present and the .Cm N flag has not been specified, then a .Dv SIGHUP signal will be sent to .Xr syslogd 8 or to the process id found in the file specified by .Xr newsyslog 8 Ns 's .Fl S switch. This field must start with .Ql / in order to be recognized properly. When used with the .Cm R flag, the file is treated as a path to a binary to be executed by the .Xr newsyslog 8 after rotation instead of sending the signal out. .It Ar signal This optional field specifies the signal that will be sent to the daemon process (or to all processes in a process group, if the .Cm U flag was specified). If this field is not present, then a .Dv SIGHUP signal will be sent. Signal names must start with .Dq SIG and be the signal name, e.g., .Dv SIGUSR1 . Alternatively, .Ar signal can be the signal number, e.g., 30 for .Dv SIGUSR1 . .El .Sh EXAMPLES The following is an example of the .Dq Aq Li include entry: .Dl " /etc/newsyslog-local.conf" .Sh SEE ALSO .Xr bzip2 1 , .Xr gzip 1 , .Xr xz 1 , .Xr zstd 1 , .Xr syslog 3 , .Xr chown 8 , .Xr newsyslog 8 , .Xr syslogd 8 .Pp .Rs .%A C. Lonvick .%T The BSD syslog Protocol .%O RFC3164 .Re .Rs .%A R. Gerhards .%T The Syslog Protocol .%O RFC5424 .Re .Sh HISTORY This manual page first appeared in .Fx 4.10 .