Index: head/lib/libc/capability/cap_rights_init.3 =================================================================== --- head/lib/libc/capability/cap_rights_init.3 (revision 366582) +++ head/lib/libc/capability/cap_rights_init.3 (revision 366583) @@ -1,253 +1,253 @@ .\" .\" Copyright (c) 2013 The FreeBSD Foundation .\" All rights reserved. .\" .\" This documentation was written by Pawel Jakub Dawidek 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. .\" .\" $FreeBSD$ .\" .Dd May 5, 2020 .Dt CAP_RIGHTS_INIT 3 .Os .Sh NAME .Nm cap_rights_init , .Nm cap_rights_set , .Nm cap_rights_clear , .Nm cap_rights_is_set , .Nm cap_rights_is_valid , .Nm cap_rights_merge , .Nm cap_rights_remove , .Nm cap_rights_contains .Nd manage cap_rights_t structure .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/capsicum.h .Ft cap_rights_t * .Fn cap_rights_init "cap_rights_t *rights" "..." .Ft cap_rights_t * .Fn cap_rights_set "cap_rights_t *rights" "..." .Ft cap_rights_t * .Fn cap_rights_clear "cap_rights_t *rights" "..." .Ft bool .Fn cap_rights_is_set "const cap_rights_t *rights" "..." .Ft bool .Fn cap_rights_is_valid "const cap_rights_t *rights" .Ft cap_rights_t * .Fn cap_rights_merge "cap_rights_t *dst" "const cap_rights_t *src" .Ft cap_rights_t * .Fn cap_rights_remove "cap_rights_t *dst" "const cap_rights_t *src" .Ft bool .Fn cap_rights_contains "const cap_rights_t *big" "const cap_rights_t *little" .Sh DESCRIPTION The functions documented here allow to manage the .Vt cap_rights_t structure. .Pp Capability rights should be separated with comma when passed to the .Fn cap_rights_init , .Fn cap_rights_set , .Fn cap_rights_clear and .Fn cap_rights_is_set functions. For example: .Bd -literal cap_rights_set(&rights, CAP_READ, CAP_WRITE, CAP_FSTAT, CAP_SEEK); .Ed .Pp The complete list of the capability rights can be found in the .Xr rights 4 manual page. .Pp The .Fn cap_rights_init function initialize provided .Vt cap_rights_t structure. Only properly initialized structure can be passed to the remaining functions. For convenience the structure can be filled with capability rights instead of calling the .Fn cap_rights_set function later. For even more convenience pointer to the given structure is returned, so it can be directly passed to .Xr cap_rights_limit 2 : .Bd -literal cap_rights_t rights; if (cap_rights_limit(fd, cap_rights_init(&rights, CAP_READ, CAP_WRITE)) < 0) err(1, "Unable to limit capability rights"); .Ed .Pp The .Fn cap_rights_set function adds the given capability rights to the given .Vt cap_rights_t structure. .Pp The .Fn cap_rights_clear function removes the given capability rights from the given .Vt cap_rights_t structure. .Pp The .Fn cap_rights_is_set function checks if all the given capability rights are set for the given .Vt cap_rights_t structure. .Pp The .Fn cap_rights_is_valid function verifies if the given .Vt cap_rights_t structure is valid. .Pp The .Fn cap_rights_merge function merges all capability rights present in the .Fa src structure into the .Fa dst structure. .Pp The .Fn cap_rights_remove function removes all capability rights present in the .Fa src structure from the .Fa dst structure. .Pp The .Fn cap_rights_contains function checks if the .Fa big structure contains all capability rights present in the .Fa little structure. .Sh RETURN VALUES The functions never fail. In case an invalid capability right or an invalid .Vt cap_rights_t structure is given as an argument, the program will be aborted. .Pp The .Fn cap_rights_init , .Fn cap_rights_set and .Fn cap_rights_clear functions return pointer to the .Vt cap_rights_t structure given in the .Fa rights argument. .Pp The .Fn cap_rights_merge and .Fn cap_rights_remove functions return pointer to the .Vt cap_rights_t structure given in the .Fa dst argument. .Pp The .Fn cap_rights_is_set returns .Va true if all the given capability rights are set in the .Fa rights argument. .Pp The .Fn cap_rights_is_valid function performs various checks to see if the given .Vt cap_rights_t structure is valid and returns .Va true if it is. .Pp The .Fn cap_rights_contains function returns .Va true if all capability rights set in the .Fa little structure are also present in the .Fa big structure. .Sh EXAMPLES The following example demonstrates how to prepare a .Vt cap_rights_t structure to be passed to the .Xr cap_rights_limit 2 system call. .Bd -literal cap_rights_t rights; int fd; fd = open("/tmp/foo", O_RDWR); if (fd < 0) err(1, "open() failed"); cap_rights_init(&rights, CAP_FSTAT, CAP_READ); if (allow_write_and_seek) cap_rights_set(&rights, CAP_WRITE, CAP_SEEK); if (dont_allow_seek) cap_rights_clear(&rights, CAP_SEEK); if (cap_rights_limit(fd, &rights) < 0 && errno != ENOSYS) err(1, "cap_rights_limit() failed"); .Ed .Sh SEE ALSO .Xr cap_rights_limit 2 , .Xr open 2 , .Xr capsicum 4 , .Xr rights 4 .Sh HISTORY The functions .Fn cap_rights_init , .Fn cap_rights_set , .Fn cap_rights_clear , .Fn cap_rights_is_set , .Fn cap_rights_is_valid , .Fn cap_rights_merge , -.Fn cap_rights_remove +.Fn cap_rights_remove and .Fn cap_rights_contains first appeared in .Fx 8.3 . Support for capabilities and capabilities mode was developed as part of the .Tn TrustedBSD Project. .Sh AUTHORS This family of functions was created by .An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net under sponsorship from the FreeBSD Foundation. Index: head/lib/libc/sys/cpuset_getaffinity.2 =================================================================== --- head/lib/libc/sys/cpuset_getaffinity.2 (revision 366582) +++ head/lib/libc/sys/cpuset_getaffinity.2 (revision 366583) @@ -1,174 +1,174 @@ .\" Copyright (c) 2008 Christian Brueffer .\" Copyright (c) 2008 Jeffrey Roberson .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd May 23, 2017 .Dt CPUSET_GETAFFINITY 2 .Os .Sh NAME .Nm cpuset_getaffinity , .Nm cpuset_setaffinity .Nd manage CPU affinity .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/param.h .In sys/cpuset.h .Ft int .Fn cpuset_getaffinity "cpulevel_t level" "cpuwhich_t which" "id_t id" "size_t setsize" "cpuset_t *mask" .Ft int .Fn cpuset_setaffinity "cpulevel_t level" "cpuwhich_t which" "id_t id" "size_t setsize" "const cpuset_t *mask" .Sh DESCRIPTION .Fn cpuset_getaffinity and .Fn cpuset_setaffinity allow the manipulation of sets of CPUs available to processes, threads, interrupts, jails and other resources. These functions may manipulate sets of CPUs that contain many processes or per-object anonymous masks that effect only a single object. .Pp The valid values for the .Fa level and .Fa which arguments are documented in .Xr cpuset 2 . These arguments specify which object and which set of the object we are referring to. Not all possible combinations are valid. For example, only processes may belong to a numbered set accessed by a .Fa level argument of .Dv CPU_LEVEL_CPUSET . All resources, however, have a mask which may be manipulated with .Dv CPU_LEVEL_WHICH . .Pp Masks of type .Ft cpuset_t are composed using the .Dv CPU_SET macros. The kernel tolerates large sets as long as all CPUs specified in the set exist. Sets smaller than the kernel uses generate an error on calls to .Fn cpuset_getaffinity even if the result set would fit within the user supplied set. Calls to .Fn cpuset_setaffinity tolerate small sets with no restrictions. .Pp The supplied mask should have a size of .Fa setsize bytes. This size is usually provided by calling .Li sizeof(mask) which is ultimately determined by the value of .Dv CPU_SETSIZE as defined in .In sys/cpuset.h . .Pp .Fn cpuset_getaffinity retrieves the mask from the object specified by .Fa level , .Fa which and .Fa id and stores it in the space provided by .Fa mask . .Pp .Fn cpuset_setaffinity attempts to set the mask for the object specified by .Fa level , .Fa which and .Fa id to the value in .Fa mask . .Sh RETURN VALUES .Rv -std .Sh ERRORS The following error codes may be set in .Va errno : .Bl -tag -width Er .\" When changing this list, consider updating share/man/man3/pthread_create.3, .\" since that function can return any of these errors. .It Bq Er EINVAL The .Fa level or .Fa which argument was not a valid value. .It Bq Er EINVAL The .Fa mask argument specified when calling .Fn cpuset_setaffinity was not a valid value. .It Bq Er EDEADLK The .Fn cpuset_setaffinity call would leave a thread without a valid CPU to run on because the set does not overlap with the thread's anonymous mask. .It Bq Er EFAULT The mask pointer passed was invalid. .It Bq Er ESRCH The object specified by the .Fa id and .Fa which arguments could not be found. .It Bq Er ERANGE The .Fa cpusetsize was either preposterously large or smaller than the kernel set size. .It Bq Er EPERM The calling process did not have the credentials required to complete the operation. .It Bq Er ECAPMODE -The calling process attempted to act on a process other than itself, while +The calling process attempted to act on a process other than itself, while in capability mode. See .Xr capsicum 4 . .El .Sh SEE ALSO .Xr capsicum 4 , .Xr cpuset 1 , .Xr cpuset 2 , .Xr cpuset_getid 2 , .Xr cpuset_setid 2 , .Xr cpuset_getdomain 2 , .Xr cpuset_setdomain 2 , .Xr pthread_affinity_np 3 , .Xr pthread_attr_affinity_np 3 , .Xr cpuset 9 .Sh HISTORY The .Nm family of system calls first appeared in .Fx 7.1 . .Sh AUTHORS .An Jeffrey Roberson Aq Mt jeff@FreeBSD.org Index: head/lib/libc/sys/cpuset_getdomain.2 =================================================================== --- head/lib/libc/sys/cpuset_getdomain.2 (revision 366582) +++ head/lib/libc/sys/cpuset_getdomain.2 (revision 366583) @@ -1,190 +1,191 @@ .\" Copyright (c) 2018 Jeffrey Roberson .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd June 18, 2020 .Dt CPUSET_GETDOMAIN 2 .Os .Sh NAME .Nm cpuset_getdomain , .Nm cpuset_setdomain .Nd manage memory domain policy .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/param.h .In sys/domainset.h .Ft int .Fn cpuset_getdomain "cpulevel_t level" "cpuwhich_t which" "id_t id" "size_t setsize" "domainset_t *mask" "int *policy" .Ft int .Fn cpuset_setdomain "cpulevel_t level" "cpuwhich_t which" "id_t id" "size_t setsize" "const domainset_t *mask" "int policy" .Sh DESCRIPTION .Fn cpuset_getdomain and .Fn cpuset_setdomain allow the manipulation of sets of memory domains and allocation policy available to processes, threads, jails and other resources. These functions may manipulate sets of memory domains that contain many processes or per-object anonymous masks that affect only a single object. .Pp The valid values for the .Fa level and .Fa which arguments are documented in .Xr cpuset 2 . These arguments specify which object and which set of the object we are referring to. Not all possible combinations are valid. For example, only processes may belong to a numbered set accessed by a .Fa level argument of .Dv CPU_LEVEL_CPUSET . All resources, however, have a mask which may be manipulated with .Dv CPU_LEVEL_WHICH . .Pp Masks of type .Ft domainset_t are composed using the .Dv DOMAINSET macros. The kernel tolerates large sets as long as all domains specified in the set exist. Sets smaller than the kernel uses generate an error on calls to .Fn cpuset_getdomain even if the result set would fit within the user supplied set. Calls to .Fn cpuset_setdomain tolerate small sets with no restrictions. .Pp The supplied mask should have a size of .Fa setsize bytes. This size is usually provided by calling .Li sizeof(mask) which is ultimately determined by the value of .Dv DOMAINSET_SETSIZE as defined in .In sys/domainset.h . .Pp .Fn cpuset_getdomain retrieves the mask and policy from the object specified by .Fa level , .Fa which and .Fa id and stores it in the space provided by .Fa mask and .Fa policy . .Pp .Fn cpuset_setdomain attempts to set the mask and policy for the object specified by .Fa level , .Fa which and .Fa id to the values in .Fa mask and .Fa policy . .Sh ALLOCATION POLICIES Valid policy values are as follows: .Bl -tag -width "foo" .It Dv DOMAINSET_POLICY_ROUNDROBIN Memory is allocated on a round-robin basis by cycling through each domain in .Fa mask . .It Dv DOMAINSET_POLICY_FIRSTTOUCH Memory is allocated on the domain local to the CPU the requesting thread is -running on. Failure to allocate from this domain will fallback to round-robin. +running on. +Failure to allocate from this domain will fallback to round-robin. .It Dv DOMAINSET_POLICY_PREFER Memory is allocated preferentially from the single domain specified in the mask. If memory is unavailable the domains listed in the parent cpuset will be visited in a round-robin order. .El .Sh RETURN VALUES .Rv -std .Sh ERRORS The following error codes may be set in .Va errno : .Bl -tag -width Er .\" When changing this list, consider updating share/man/man3/pthread_create.3, .\" since that function can return any of these errors. .It Bq Er EINVAL The .Fa level or .Fa which argument was not a valid value. .It Bq Er EINVAL The .Fa mask or .Fa policy argument specified when calling .Fn cpuset_setdomain was not a valid value. .It Bq Er EDEADLK The .Fn cpuset_setdomain call would leave a thread without a valid CPU to run on because the set does not overlap with the thread's anonymous mask. .It Bq Er EFAULT The mask pointer passed was invalid. .It Bq Er ESRCH The object specified by the .Fa id and .Fa which arguments could not be found. .It Bq Er ERANGE The .Fa domainsetsize was either preposterously large or smaller than the kernel set size. .It Bq Er EPERM The calling process did not have the credentials required to complete the operation. .It Bq Er ECAPMODE -The calling process attempted to act on a process other than itself, while +The calling process attempted to act on a process other than itself, while in capability mode. See .Xr capsicum 4 . .El .Sh SEE ALSO .Xr capsicum 4 , .Xr cpuset 1 , .Xr cpuset 2 , .Xr cpuset_getid 2 , .Xr cpuset_setid 2 , .Xr cpuset_getaffinity 2 , .Xr cpuset_setaffinity 2 , .Xr cpuset 9 .Sh HISTORY The .Nm family of system calls first appeared in .Fx 12.0 . .Sh AUTHORS .An Jeffrey Roberson Aq Mt jeff@FreeBSD.org Index: head/lib/libc/sys/fhlink.2 =================================================================== --- head/lib/libc/sys/fhlink.2 (revision 366582) +++ head/lib/libc/sys/fhlink.2 (revision 366583) @@ -1,277 +1,277 @@ .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2018 Gandi .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd September 23, 2020 .Dt FHLINK 2 .Os .Sh NAME .Nm fhlink , .Nm fhlinkat .Nd make a hard file link .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In unistd.h .Ft int .Fn fhlink "fhandle_t *fhp" "const char *to" .Ft int .Fn fhlinkat "fhandle_t *fhp" "int tofd" "const char *to" .Fc .Sh DESCRIPTION The .Fn fhlink system call atomically creates the specified directory entry (hard link) .Fa to with the attributes of the underlying object pointed at by .Fa fhp . If the link is successful: the link count of the underlying object is incremented; .Fa fhp and .Fa to share equal access and rights to the underlying object. .Pp If .Fa fhp is removed, the file .Fa to is not deleted and the link count of the underlying object is decremented. .Pp The object pointed at by the .Fa fhp argument must exist for the hard link to succeed and both .Fa fhp and .Fa to must be in the same file system. The .Fa fhp argument may not be a directory. .Pp The .Fn fhlinkat system call is equivalent to .Fa fhlink except in the case where .Fa to is a relative paths. In this case a relative path .Fa to is interpreted relative to the directory associated with the file descriptor .Fa tofd instead of the current working directory. .Pp Values for .Fa flag are constructed by a bitwise-inclusive OR of flags from the following list, defined in .In fcntl.h : .Bl -tag -width indent .It Dv AT_SYMLINK_FOLLOW If .Fa fhp names a symbolic link, a new link for the target of the symbolic link is created. .It Dv AT_BENEATH Only allow to link to a file which is beneath of the topping directory. See the description of the .Dv O_BENEATH flag in the .Xr open 2 manual page. .It Dv AT_RESOLVE_BENEATH Only walks paths below the topping directory. See the description of the .Dv O_RESOLVE_BENEATH flag in the .Xr open 2 manual page. .El .Pp If .Fn fhlinkat is passed the special value .Dv AT_FDCWD in the .Fa tofd parameter, the current working directory is used for the .Fa to argument. If .Fa tofd has value .Dv AT_FDCWD , the behavior is identical to a call to .Fn link . Unless .Fa flag contains the .Dv AT_SYMLINK_FOLLOW flag, if .Fa fhp names a symbolic link, a new link is created for the symbolic link .Fa fhp and not its target. .Sh RETURN VALUES .Rv -std link .Sh ERRORS The .Fn fhlink system call will fail and no link will be created if: .Bl -tag -width Er .It Bq Er ENOTDIR A component of .Fa to prefix is not a directory. .It Bq Er ENAMETOOLONG A component of .Fa to exceeded 255 characters, or entire length of .Fa to name exceeded 1023 characters. .It Bq Er ENOENT A component of .Fa to prefix does not exist. .It Bq Er EOPNOTSUPP The file system containing the file pointed at by .Fa fhp does not support links. .It Bq Er EMLINK The link count of the file pointed at by .Fa fhp would exceed 32767. .It Bq Er EACCES -A component of +A component of .Fa to prefix denies search permission. .It Bq Er EACCES The requested link requires writing in a directory with a mode that denies write permission. .It Bq Er ELOOP Too many symbolic links were encountered in translating one of the pathnames. .It Bq Er ENOENT The file pointed at by .Fa fhp does not exist. .It Bq Er EEXIST The link named by .Fa to does exist. .It Bq Er EPERM The file pointed at by .Fa fhp is a directory. .It Bq Er EPERM The file pointed at by .Fa fhp has its immutable or append-only flag set, see the .Xr chflags 2 manual page for more information. .It Bq Er EPERM The parent directory of the file named by .Fa to has its immutable flag set. .It Bq Er EXDEV The link named by .Fa to and the file pointed at by .Fa fhp are on different file systems. .It Bq Er ENOSPC The directory in which the entry for the new link is being placed cannot be extended because there is no space left on the file system containing the directory. .It Bq Er EDQUOT The directory in which the entry for the new link is being placed cannot be extended because the user's quota of disk blocks on the file system containing the directory has been exhausted. .It Bq Er EIO An I/O error occurred while reading from or writing to the file system to make the directory entry. .It Bq Er EINTEGRITY Corrupted data was detected while reading from the file system. .It Bq Er EROFS The requested link requires writing in a directory on a read-only file system. .It Bq Er EFAULT One of the pathnames specified is outside the process's allocated address space. .It Bq Er ESTALE The file handle .Fa fhp is no longer valid .El .Pp In addition to the errors returned by the .Fn fhlink , the .Fn fhlinkat system call may fail if: .Bl -tag -width Er .It Bq Er EBADF The .Fa fhp or .Fa to argument does not specify an absolute path and the .Fa tofd argument, is not .Dv AT_FDCWD nor a valid file descriptor open for searching. .It Bq Er EINVAL The value of the .Fa flag argument is not valid. .It Bq Er ENOTDIR The .Fa fhp or .Fa to argument is not an absolute path and .Fa tofd is not .Dv AT_FDCWD nor a file descriptor associated with a directory. .El .Sh SEE ALSO .Xr fhstat 2 , .Xr fhreadlink 2 , .Xr fhopen 2 , Index: head/lib/libc/sys/getitimer.2 =================================================================== --- head/lib/libc/sys/getitimer.2 (revision 366582) +++ head/lib/libc/sys/getitimer.2 (revision 366583) @@ -1,195 +1,195 @@ .\" Copyright (c) 1983, 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. .\" .\" @(#)getitimer.2 8.3 (Berkeley) 5/16/95 .\" $FreeBSD$ .\" -.Dd May 1, 2020 +.Dd May 1, 2020 .Dt GETITIMER 2 .Os .Sh NAME .Nm getitimer , .Nm setitimer .Nd get/set value of interval timer .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/time.h .Fd "#define ITIMER_REAL 0" .Fd "#define ITIMER_VIRTUAL 1" .Fd "#define ITIMER_PROF 2" .Ft int .Fn getitimer "int which" "struct itimerval *value" .Ft int .Fn setitimer "int which" "const struct itimerval *value" "struct itimerval *ovalue" .Sh DESCRIPTION The system provides each process with three interval timers, defined in .In sys/time.h . The .Fn getitimer system call returns the current value for the timer specified in .Fa which in the structure at .Fa value . The .Fn setitimer system call sets a timer to the specified .Fa value (returning the previous value of the timer if .Fa ovalue is not a null pointer). .Pp A timer value is defined by the .Fa itimerval structure: .Bd -literal -offset indent struct itimerval { struct timeval it_interval; /* timer interval */ struct timeval it_value; /* current value */ }; .Ed .Pp If .Fa it_value is non-zero, it indicates the time to the next timer expiration. If .Fa it_interval is non-zero, it specifies a value to be used in reloading .Fa it_value when the timer expires. Setting .Fa it_value to 0 disables a timer, regardless of the value of .Fa it_interval . Setting .Fa it_interval to 0 causes a timer to be disabled after its next expiration (assuming .Fa it_value is non-zero). .Pp Time values smaller than the resolution of the system clock are rounded up to this resolution (typically 10 milliseconds). .Pp The .Dv ITIMER_REAL timer decrements in real time. A .Dv SIGALRM signal is delivered when this timer expires. .Pp The .Dv ITIMER_VIRTUAL timer decrements in process virtual time. It runs only when the process is executing. A .Dv SIGVTALRM signal is delivered when it expires. .Pp The .Dv ITIMER_PROF timer decrements both in process virtual time and when the system is running on behalf of the process. It is designed to be used by interpreters in statistically profiling the execution of interpreted programs. Each time the .Dv ITIMER_PROF timer expires, the .Dv SIGPROF signal is delivered. Because this signal may interrupt in-progress system calls, programs using this timer must be prepared to restart interrupted system calls. .Pp The maximum number of seconds allowed for .Fa it_interval and .Fa it_value in .Fn setitimer is 100000000. .Sh NOTES Three macros for manipulating time values are defined in .In sys/time.h . The .Fn timerclear macro sets a time value to zero, .Fn timerisset tests if a time value is non-zero, and .Fn timercmp compares two time values. .Sh RETURN VALUES .Rv -std .Sh ERRORS The .Fn getitimer and .Fn setitimer system calls will fail if: .Bl -tag -width Er .It Bq Er EFAULT The .Fa value argument specified a bad address. .It Bq Er EINVAL The .Fa value argument specified a time that was too large to be handled. .El .Sh SEE ALSO .Xr gettimeofday 2 , .Xr select 2 , .Xr sigaction 2 , .Xr clocks 7 .Sh STANDARDS The .Fn getitimer and .Fn setitimer functions conform to .St -p1003.1-2001 . The later .St -p1003.1-2008 revision however marked both functions as obsolescent, recommending the use of .Xr timer_gettime 2 and .Xr timer_settime 2 instead. .Sh HISTORY The .Fn getitimer system call appeared in .Bx 4.2 . Index: head/lib/libc/sys/getsockopt.2 =================================================================== --- head/lib/libc/sys/getsockopt.2 (revision 366582) +++ head/lib/libc/sys/getsockopt.2 (revision 366583) @@ -1,616 +1,617 @@ .\" Copyright (c) 1983, 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. .\" .\" @(#)getsockopt.2 8.4 (Berkeley) 5/2/95 .\" $FreeBSD$ .\" -.Dd June 03, 2020 +.Dd June 3, 2020 .Dt GETSOCKOPT 2 .Os .Sh NAME .Nm getsockopt , .Nm setsockopt .Nd get and set options on sockets .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .Ft int .Fn getsockopt "int s" "int level" "int optname" "void * restrict optval" "socklen_t * restrict optlen" .Ft int .Fn setsockopt "int s" "int level" "int optname" "const void *optval" "socklen_t optlen" .Sh DESCRIPTION The .Fn getsockopt and .Fn setsockopt system calls manipulate the .Em options associated with a socket. Options may exist at multiple protocol levels; they are always present at the uppermost .Dq socket level. .Pp When manipulating socket options the level at which the option resides and the name of the option must be specified. To manipulate options at the socket level, .Fa level is specified as .Dv SOL_SOCKET . To manipulate options at any other level the protocol number of the appropriate protocol controlling the option is supplied. For example, to indicate that an option is to be interpreted by the .Tn TCP protocol, .Fa level should be set to the protocol number of .Tn TCP ; see .Xr getprotoent 3 . .Pp The .Fa optval and .Fa optlen arguments are used to access option values for .Fn setsockopt . For .Fn getsockopt they identify a buffer in which the value for the requested option(s) are to be returned. For .Fn getsockopt , .Fa optlen is a value-result argument, initially containing the size of the buffer pointed to by .Fa optval , and modified on return to indicate the actual size of the value returned. If no option value is to be supplied or returned, .Fa optval may be NULL. .Pp The .Fa optname argument and any specified options are passed uninterpreted to the appropriate protocol module for interpretation. The include file .In sys/socket.h contains definitions for socket level options, described below. Options at other protocol levels vary in format and name; consult the appropriate entries in section 4 of the manual. .Pp Most socket-level options utilize an .Vt int argument for .Fa optval . For .Fn setsockopt , the argument should be non-zero to enable a boolean option, or zero if the option is to be disabled. .Dv SO_LINGER uses a .Vt "struct linger" argument, defined in .In sys/socket.h , which specifies the desired state of the option and the linger interval (see below). .Dv SO_SNDTIMEO and .Dv SO_RCVTIMEO use a .Vt "struct timeval" argument, defined in .In sys/time.h . .Pp The following options are recognized at the socket level. For protocol-specific options, see protocol manual pages, e.g. .Xr ip 4 or .Xr tcp 4 . Except as noted, each may be examined with .Fn getsockopt and set with .Fn setsockopt . .Bl -column SO_ACCEPTFILTER -offset indent .It Dv SO_DEBUG Ta "enables recording of debugging information" .It Dv SO_REUSEADDR Ta "enables local address reuse" .It Dv SO_REUSEPORT Ta "enables duplicate address and port bindings" .It Dv SO_REUSEPORT_LB Ta "enables duplicate address and port bindings with load balancing" .It Dv SO_KEEPALIVE Ta "enables keep connections alive" .It Dv SO_DONTROUTE Ta "enables routing bypass for outgoing messages" .It Dv SO_LINGER Ta "linger on close if data present" .It Dv SO_BROADCAST Ta "enables permission to transmit broadcast messages" .It Dv SO_OOBINLINE Ta "enables reception of out-of-band data in band" .It Dv SO_SNDBUF Ta "set buffer size for output" .It Dv SO_RCVBUF Ta "set buffer size for input" .It Dv SO_SNDLOWAT Ta "set minimum count for output" .It Dv SO_RCVLOWAT Ta "set minimum count for input" .It Dv SO_SNDTIMEO Ta "set timeout value for output" .It Dv SO_RCVTIMEO Ta "set timeout value for input" .It Dv SO_ACCEPTFILTER Ta "set accept filter on listening socket" .It Dv SO_NOSIGPIPE Ta controls generation of .Dv SIGPIPE for the socket .It Dv SO_TIMESTAMP Ta "enables reception of a timestamp with datagrams" .It Dv SO_BINTIME Ta "enables reception of a timestamp with datagrams" .It Dv SO_ACCEPTCONN Ta "get listening status of the socket (get only)" .It Dv SO_DOMAIN Ta "get the domain of the socket (get only)" .It Dv SO_TYPE Ta "get the type of the socket (get only)" .It Dv SO_PROTOCOL Ta "get the protocol number for the socket (get only)" .It Dv SO_PROTOTYPE Ta "SunOS alias for the Linux SO_PROTOCOL (get only)" .It Dv SO_ERROR Ta "get and clear error on the socket (get only)" .It Dv SO_SETFIB Ta "set the associated FIB (routing table) for the socket (set only)" .El .Pp The following options are recognized in .Fx : .Bl -column SO_LISTENINCQLEN -offset indent .It Dv SO_LABEL Ta "get MAC label of the socket (get only)" .It Dv SO_PEERLABEL Ta "get socket's peer's MAC label (get only)" .It Dv SO_LISTENQLIMIT Ta "get backlog limit of the socket (get only)" .It Dv SO_LISTENQLEN Ta "get complete queue length of the socket (get only)" .It Dv SO_LISTENINCQLEN Ta "get incomplete queue length of the socket (get only)" .It Dv SO_USER_COOKIE Ta "set the 'so_user_cookie' value for the socket (uint32_t, set only)" .It Dv SO_TS_CLOCK Ta "set specific format of timestamp returned by SO_TIMESTAMP" .It Dv SO_MAX_PACING_RATE Ta "set the maximum transmit rate in bytes per second for the socket" .It Dv SO_NO_OFFLOAD Ta "disables protocol offloads" .It Dv SO_NO_DDP Ta "disables direct data placement offload" .El .Pp .Dv SO_DEBUG enables debugging in the underlying protocol modules. .Pp .Dv SO_REUSEADDR indicates that the rules used in validating addresses supplied in a .Xr bind 2 system call should allow reuse of local addresses. .Pp .Dv SO_REUSEPORT allows completely duplicate bindings by multiple processes if they all set .Dv SO_REUSEPORT before binding the port. This option permits multiple instances of a program to each receive UDP/IP multicast or broadcast datagrams destined for the bound port. .Pp .Dv SO_REUSEPORT_LB allows completely duplicate bindings by multiple processes if they all set .Dv SO_REUSEPORT_LB before binding the port. Incoming TCP and UDP connections are distributed among the sharing processes based on a hash function of local port number, foreign IP -address and port number. A maximum of 256 processes can share one socket. +address and port number. +A maximum of 256 processes can share one socket. .Pp .Dv SO_KEEPALIVE enables the periodic transmission of messages on a connected socket. Should the connected party fail to respond to these messages, the connection is considered broken and processes using the socket are notified via a .Dv SIGPIPE signal when attempting to send data. .Pp .Dv SO_DONTROUTE indicates that outgoing messages should bypass the standard routing facilities. Instead, messages are directed to the appropriate network interface according to the network portion of the destination address. .Pp .Dv SO_LINGER controls the action taken when unsent messages are queued on socket and a .Xr close 2 is performed. If the socket promises reliable delivery of data and .Dv SO_LINGER is set, the system will block the process on the .Xr close 2 attempt until it is able to transmit the data or until it decides it is unable to deliver the information (a timeout period, termed the linger interval, is specified in seconds in the .Fn setsockopt system call when .Dv SO_LINGER is requested). If .Dv SO_LINGER is disabled and a .Xr close 2 is issued, the system will process the close in a manner that allows the process to continue as quickly as possible. .Pp The option .Dv SO_BROADCAST requests permission to send broadcast datagrams on the socket. Broadcast was a privileged operation in earlier versions of the system. .Pp With protocols that support out-of-band data, the .Dv SO_OOBINLINE option requests that out-of-band data be placed in the normal data input queue as received; it will then be accessible with .Xr recv 2 or .Xr read 2 calls without the .Dv MSG_OOB flag. Some protocols always behave as if this option is set. .Pp .Dv SO_SNDBUF and .Dv SO_RCVBUF are options to adjust the normal buffer sizes allocated for output and input buffers, respectively. The buffer size may be increased for high-volume connections, or may be decreased to limit the possible backlog of incoming data. The system places an absolute maximum on these values, which is accessible through the .Xr sysctl 3 MIB variable .Dq Li kern.ipc.maxsockbuf . .Pp .Dv SO_SNDLOWAT is an option to set the minimum count for output operations. Most output operations process all of the data supplied by the call, delivering data to the protocol for transmission and blocking as necessary for flow control. Nonblocking output operations will process as much data as permitted subject to flow control without blocking, but will process no data if flow control does not allow the smaller of the low water mark value or the entire request to be processed. A .Xr select 2 operation testing the ability to write to a socket will return true only if the low water mark amount could be processed. The default value for .Dv SO_SNDLOWAT is set to a convenient size for network efficiency, often 1024. .Pp .Dv SO_RCVLOWAT is an option to set the minimum count for input operations. In general, receive calls will block until any (non-zero) amount of data is received, then return with the smaller of the amount available or the amount requested. The default value for .Dv SO_RCVLOWAT is 1. If .Dv SO_RCVLOWAT is set to a larger value, blocking receive calls normally wait until they have received the smaller of the low water mark value or the requested amount. Receive calls may still return less than the low water mark if an error occurs, a signal is caught, or the type of data next in the receive queue is different from that which was returned. .Pp .Dv SO_SNDTIMEO is an option to set a timeout value for output operations. It accepts a .Vt "struct timeval" argument with the number of seconds and microseconds used to limit waits for output operations to complete. If a send operation has blocked for this much time, it returns with a partial count or with the error .Er EWOULDBLOCK if no data were sent. In the current implementation, this timer is restarted each time additional data are delivered to the protocol, implying that the limit applies to output portions ranging in size from the low water mark to the high water mark for output. .Pp .Dv SO_RCVTIMEO is an option to set a timeout value for input operations. It accepts a .Vt "struct timeval" argument with the number of seconds and microseconds used to limit waits for input operations to complete. In the current implementation, this timer is restarted each time additional data are received by the protocol, and thus the limit is in effect an inactivity timer. If a receive operation has been blocked for this much time without receiving additional data, it returns with a short count or with the error .Er EWOULDBLOCK if no data were received. .Pp .Dv SO_SETFIB can be used to over-ride the default FIB (routing table) for the given socket. The value must be from 0 to one less than the number returned from the sysctl .Em net.fibs . .Pp .Dv SO_USER_COOKIE can be used to set the uint32_t so_user_cookie field in the socket. The value is an uint32_t, and can be used in the kernel code that manipulates traffic related to the socket. The default value for the field is 0. As an example, the value can be used as the skipto target or pipe number in .Nm ipfw/dummynet . .Pp .Dv SO_ACCEPTFILTER places an .Xr accept_filter 9 on the socket, which will filter incoming connections on a listening stream socket before being presented for .Xr accept 2 . Once more, .Xr listen 2 must be called on the socket before trying to install the filter on it, or else the .Fn setsockopt system call will fail. .Bd -literal struct accept_filter_arg { char af_name[16]; char af_arg[256-16]; }; .Ed .Pp The .Fa optval argument should point to a .Fa struct accept_filter_arg that will select and configure the .Xr accept_filter 9 . The .Fa af_name argument should be filled with the name of the accept filter that the application wishes to place on the listening socket. The optional argument .Fa af_arg can be passed to the accept filter specified by .Fa af_name to provide additional configuration options at attach time. Passing in an .Fa optval of NULL will remove the filter. .Pp The .Dv SO_NOSIGPIPE option controls generation of the .Dv SIGPIPE signal normally sent when writing to a connected socket where the other end has been closed returns with the error .Er EPIPE . .Pp If the .Dv SO_TIMESTAMP or .Dv SO_BINTIME option is enabled on a .Dv SOCK_DGRAM socket, the .Xr recvmsg 2 call may return a timestamp corresponding to when the datagram was received. However, it may not, for example due to a resource shortage. The .Va msg_control field in the .Vt msghdr structure points to a buffer that contains a .Vt cmsghdr structure followed by a .Vt "struct timeval" for .Dv SO_TIMESTAMP and .Vt "struct bintime" for .Dv SO_BINTIME . The .Vt cmsghdr fields have the following values for TIMESTAMP by default: .Bd -literal cmsg_len = CMSG_LEN(sizeof(struct timeval)); cmsg_level = SOL_SOCKET; cmsg_type = SCM_TIMESTAMP; .Ed .Pp and for .Dv SO_BINTIME : .Bd -literal cmsg_len = CMSG_LEN(sizeof(struct bintime)); cmsg_level = SOL_SOCKET; cmsg_type = SCM_BINTIME; .Ed .Pp Additional timestamp types are available by following .Dv SO_TIMESTAMP with .Dv SO_TS_CLOCK , which requests a specific timestamp format to be returned instead of .Dv SCM_TIMESTAMP when .Dv SO_TIMESTAMP is enabled. These .Dv SO_TS_CLOCK values are recognized in .Fx : .Bl -column SO_TS_CLOCK -offset indent .It Dv SO_TS_REALTIME_MICRO Ta "realtime (SCM_TIMESTAMP, struct timeval), default" .It Dv SO_TS_BINTIME Ta "realtime (SCM_BINTIME, struct bintime)" .It Dv SO_TS_REALTIME Ta "realtime (SCM_REALTIME, struct timespec)" .It Dv SO_TS_MONOTONIC Ta "monotonic time (SCM_MONOTONIC, struct timespec)" .El .Pp .Dv SO_ACCEPTCONN , .Dv SO_TYPE , .Dv SO_PROTOCOL (and its alias .Dv SO_PROTOTYPE ) and .Dv SO_ERROR are options used only with .Fn getsockopt . .Dv SO_ACCEPTCONN returns whether the socket is currently accepting connections, that is, whether or not the .Xr listen 2 system call was invoked on the socket. .Dv SO_TYPE returns the type of the socket, such as .Dv SOCK_STREAM ; it is useful for servers that inherit sockets on startup. .Dv SO_PROTOCOL returns the protocol number for the socket, for .Dv AF_INET and .Dv AF_INET6 address families. .Dv SO_ERROR returns any pending error on the socket and clears the error status. It may be used to check for asynchronous errors on connected datagram sockets or for other asynchronous errors. .Pp .Dv SO_LABEL returns the MAC label of the socket. .Dv SO_PEERLABEL returns the MAC label of the socket's peer. Note that your kernel must be compiled with MAC support. See .Xr mac 3 for more information. .Pp .Dv SO_LISTENQLIMIT returns the maximal number of queued connections, as set by .Xr listen 2 . .Dv SO_LISTENQLEN returns the number of unaccepted complete connections. .Dv SO_LISTENINCQLEN returns the number of unaccepted incomplete connections. .Pp .Dv SO_MAX_PACING_RATE instruct the socket and underlying network adapter layers to limit the transfer rate to the given unsigned 32-bit value in bytes per second. .Pp .Dv SO_NO_OFFLOAD disables support for protocol offloads. At present, this prevents TCP sockets from using TCP offload engines. .Dv SO_NO_DDP disables support for a specific TCP offload known as direct data placement (DDP). DDP is an offload supported by Chelsio network adapters that permits reassembled TCP data streams to be received via zero-copy in user-supplied buffers using .Xr aio_read 2 . .Sh RETURN VALUES .Rv -std .Sh ERRORS The .Fn getsockopt and .Fn setsockopt system calls succeed unless: .Bl -tag -width Er .It Bq Er EBADF The argument .Fa s is not a valid descriptor. .It Bq Er ENOTSOCK The argument .Fa s is a file, not a socket. .It Bq Er ENOPROTOOPT The option is unknown at the level indicated. .It Bq Er EFAULT The address pointed to by .Fa optval is not in a valid part of the process address space. For .Fn getsockopt , this error may also be returned if .Fa optlen is not in a valid part of the process address space. .It Bq Er EINVAL Installing an .Xr accept_filter 9 on a non-listening socket was attempted. .It Bq Er ENOMEM A memory allocation failed that was required to service the request. .El .Pp The .Fn setsockopt system call may also return the following error: .Bl -tag -width Er .It Bq Er ENOBUFS Insufficient resources were available in the system to perform the operation. .El .Sh SEE ALSO .Xr ioctl 2 , .Xr listen 2 , .Xr recvmsg 2 , .Xr socket 2 , .Xr getprotoent 3 , .Xr mac 3 , .Xr sysctl 3 , .Xr ip 4 , .Xr ip6 4 , .Xr sctp 4 , .Xr tcp 4 , .Xr protocols 5 , .Xr sysctl 8 , .Xr accept_filter 9 , .Xr bintime 9 .Sh HISTORY The .Fn getsockopt and .Fn setsockopt system calls appeared in .Bx 4.2 . .Sh BUGS Several of the socket options should be handled at lower levels of the system. Index: head/lib/libgssapi/gss_accept_sec_context.3 =================================================================== --- head/lib/libgssapi/gss_accept_sec_context.3 (revision 366582) +++ head/lib/libgssapi/gss_accept_sec_context.3 (revision 366583) @@ -1,483 +1,485 @@ .\" -*- nroff -*- .\" .\" Copyright (c) 2005 Doug Rabson .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .\" The following commands are required for all man pages. .Dd January 26, 2010 .Dt GSS_ACCEPT_SEC_CONTEXT 3 PRM .Os .Sh NAME .Nm gss_accept_sec_context .Nd Accept a security context initiated by a peer application .\" This next command is for sections 2 and 3 only. .\" .Sh LIBRARY .Sh SYNOPSIS .In "gssapi/gssapi.h" .Ft OM_uint32 .Fo gss_accept_sec_context .Fa "OM_uint32 *minor_status" .Fa "gss_ctx_id_t *context_handle" .Fa "const gss_cred_id_t acceptor_cred_handle" .Fa "const gss_buffer_t input_token_buffer" .Fa "const gss_channel_bindings_t input_chan_bindings" .Fa "const gss_name_t *src_name" .Fa "gss_OID *mech_type" .Fa "gss_buffer_t output_token" .Fa "OM_uint32 *ret_flags" .Fa "OM_uint32 *time_rec" .Fa "gss_cred_id_t *delegated_cred_handle" .Fc .Sh DESCRIPTION -Allows a remotely initiated security context between the application -and a remote peer to be established. The routine may return a +Allows a remotely initiated security context between the application and a remote +peer to be established. +The routine may return a .Fa output_token which should be transferred to the peer application, where the peer application will present it to .Xr gss_init_sec_context 3 . If no token need be sent, .Fn gss_accept_sec_context will indicate this by setting the length field of the .Fa output_token argument to zero. To complete the context establishment, one or more reply tokens may be required from the peer application; if so, .Fn gss_accept_sec_context will return a status flag of .Dv GSS_S_CONTINUE_NEEDED , in which case it should be called again when the reply token is received from the peer application, passing the token to .Fn gss_accept_sec_context via the .Fa input_token parameters. .Pp Portable applications should be constructed to use the token length and return status to determine whether a token needs to be sent or -waited for. Thus a typical portable caller should always invoke +waited for. +Thus a typical portable caller should always invoke .Fn gss_accept_sec_context within a loop: .Bd -literal gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT; do { receive_token_from_peer(input_token); maj_stat = gss_accept_sec_context(&min_stat, &context_hdl, cred_hdl, input_token, input_bindings, &client_name, &mech_type, output_token, &ret_flags, &time_rec, &deleg_cred); if (GSS_ERROR(maj_stat)) { report_error(maj_stat, min_stat); }; if (output_token->length != 0) { send_token_to_peer(output_token); gss_release_buffer(&min_stat, output_token); }; if (GSS_ERROR(maj_stat)) { if (context_hdl != GSS_C_NO_CONTEXT) gss_delete_sec_context(&min_stat, &context_hdl, GSS_C_NO_BUFFER); break; }; } while (maj_stat & GSS_S_CONTINUE_NEEDED); .Ed .Pp Whenever the routine returns a major status that includes the value .Dv GSS_S_CONTINUE_NEEDED , the context is not fully established and the following restrictions apply to the output parameters: .Pp The value returned via the .Fa time_rec parameter is undefined unless the accompanying .Fa ret_flags parameter contains the bit .Dv GSS_C_PROT_READY_FLAG , indicating that per-message services may be applied in advance of a successful completion status, the value returned via the .Fa mech_type parameter may be undefined until the routine returns a major status value of .Dv GSS_S_COMPLETE . .Pp The values of the .Dv GSS_C_DELEG_FLAG , .Dv GSS_C_MUTUAL_FLAG , .Dv GSS_C_REPLAY_FLAG , .Dv GSS_C_SEQUENCE_FLAG , .Dv GSS_C_CONF_FLAG , .Dv GSS_C_INTEG_FLAG and .Dv GSS_C_ANON_FLAG bits returned via the .Fa ret_flags parameter should contain the values that the implementation expects would be valid if context establishment were to succeed. .Pp The values of the .Dv GSS_C_PROT_READY_FLAG and .Dv GSS_C_TRANS_FLAG bits within .Fa ret_flags should indicate the actual state at the time .Fn gss_accept_sec_context returns, whether or not the context is fully established. .Pp Although this requires that GSS-API implementations set the .Dv GSS_C_PROT_READY_FLAG in the final .Fa ret_flags returned to a caller (i.e. when accompanied by a .Dv GSS_S_COMPLETE status code), applications -should not rely on this behavior as the flag was not defined in -Version 1 of the GSS-API. Instead, applications should be prepared to -use per-message services after a successful context establishment, -according to the +should not rely on this behavior as the flag was not defined in Version 1 of the GSS-API. +Instead, applications should be prepared to use per-message services after a +successful context establishment, according to the .Dv GSS_C_INTEG_FLAG and .Dv GSS_C_CONF_FLAG values. .Pp All other bits within the .Fa ret_flags argument should be set to zero. While the routine returns .Dv GSS_S_CONTINUE_NEEDED , the values returned via the .Fa ret_flags argument indicate the services that the implementation expects to be available from the established context. .Pp If the initial call of .Fn gss_accept_sec_context fails, the implementation should not create a context object, and should leave the value of the context_handle parameter set to .Dv GSS_C_NO_CONTEXT to -indicate this. In the event of a failure on a subsequent call, the -implementation is permitted to delete the "half-built" security -context (in which case it should set the +indicate this. +In the event of a failure on a subsequent call, the implementation is +permitted to delete the "half-built" security context (in which case it +should set the .Fa context_handle parameter to .Dv GSS_C_NO_CONTEXT ), but the preferred behavior is to leave the security context (and the context_handle parameter) untouched for the application to delete (using .Xr gss_delete_sec_context 3 ). .Pp During context establishment, the informational status bits .Dv GSS_S_OLD_TOKEN and .Dv GSS_S_DUPLICATE_TOKEN indicate fatal errors, and GSS-API mechanisms should always return them in association with a routine error of .Dv GSS_S_FAILURE . This requirement for pairing did not exist in version 1 of the GSS-API specification, so applications that wish to run over version 1 implementations must special-case these codes. .Sh PARAMETERS .Bl -tag -width ".It input_chan_bindings" .It context_handle Context handle for new context. Supply .Dv GSS_C_NO_CONTEXT for first call; use value returned in subsequent calls. Once .Fn gss_accept_sec_context has returned a value via this parameter, resources have been assigned to the corresponding context, and must be freed by the application after use with a call to .Xr gss_delete_sec_context 3 . .It acceptor_cred_handle Credential handle claimed by context acceptor. Specify .Dv GSS_C_NO_CREDENTIAL to accept the context as a default principal. If .Dv GSS_C_NO_CREDENTIAL is specified, but no default acceptor principal is defined, .Dv GSS_S_NO_CRED will be returned. .It input_token_buffer Token obtained from remote application. .It input_chan_bindings Application-specified bindings. Allows application to securely bind channel identification information to the security context. If channel bindings are not used, specify .Dv GSS_C_NO_CHANNEL_BINDINGS . .It src_name Authenticated name of context initiator. After use, this name should be deallocated by passing it to .Xr gss_release_name 3 . If not required, specify .Dv NULL . .It mech_type Security mechanism used. The returned OID value will be a pointer into static storage, and should be treated as read-only by the caller (in particular, it does not need to be freed). If not required, specify .Dv NULL . .It output_token Token to be passed to peer application. If the length field of the returned token buffer is 0, then no token need be passed to the peer application. If a non-zero length field is returned, the associated storage must be freed after use by the application with a call to .Xr gss_release_buffer 3 . .It ret_flags Contains various independent flags, each of which indicates that the context supports a specific service option. If not needed, specify .Dv NULL . Symbolic names are provided for each flag, and the symbolic names corresponding to the required flags should be logically-ANDed with the .Fa ret_flags value to test whether a given option is supported by the context. The flags are: .Bl -tag -width "WW" .It GSS_C_DELEG_FLAG .Bl -tag -width "False" .It True Delegated credentials are available via the delegated_cred_handle parameter .It False No credentials were delegated .El .It GSS_C_MUTUAL_FLAG .Bl -tag -width "False" .It True Remote peer asked for mutual authentication .It False Remote peer did not ask for mutual authentication .El .It GSS_C_REPLAY_FLAG .Bl -tag -width "False" .It True Replay of protected messages will be detected .It False Replayed messages will not be detected .El .It GSS_C_SEQUENCE_FLAG .Bl -tag -width "False" .It True Out-of-sequence protected messages will be detected .It False Out-of-sequence messages will not be detected .El .It GSS_C_CONF_FLAG .Bl -tag -width "False" .It True Confidentiality service may be invoked by calling the .Xr gss_wrap 3 routine .It False No confidentiality service (via .Xr gss_wrap 3 ) available. .Xr gss_wrap 3 will provide message encapsulation, data-origin authentication and integrity services only. .El .It GSS_C_INTEG_FLAG .Bl -tag -width "False" .It True Integrity service may be invoked by calling either .Xr gss_get_mic 3 or .Xr gss_wrap 3 routines. .It False Per-message integrity service unavailable. .El .It GSS_C_ANON_FLAG .Bl -tag -width "False" .It True The initiator does not wish to be authenticated; the .Fa src_name parameter (if requested) contains an anonymous internal name. .It False The initiator has been authenticated normally. .El .It GSS_C_PROT_READY_FLAG .Bl -tag -width "False" .It True Protection services (as specified by the states of the .Dv GSS_C_CONF_FLAG and .Dv GSS_C_INTEG_FLAG ) are available if the accompanying major status return value is either .Dv GSS_S_COMPLETE or .Dv GSS_S_CONTINUE_NEEDED. .It False Protection services (as specified by the states of the .Dv GSS_C_CONF_FLAG and .Dv GSS_C_INTEG_FLAG ) are available only if the accompanying major status return value is .Dv GSS_S_COMPLETE . .El .It GSS_C_TRANS_FLAG .Bl -tag -width "False" .It True The resultant security context may be transferred to other processes via a call to .Xr gss_export_sec_context 3 . .It False The security context is not transferable. .El .El .Pp All other bits should be set to zero. .It time_rec Number of seconds for which the context will remain valid. Specify .Dv NULL if not required. .It delegated_cred_handle Credential handle for credentials received from context initiator. Only valid if .Dv GSS_C_DELEG_FLAG in .Fa ret_flags is true, in which case an explicit credential handle (i.e. not .Dv GSS_C_NO_CREDENTIAL ) will be returned; if false, .Fn gss_accept_context will set this parameter to .Dv GSS_C_NO_CREDENTIAL . If a credential handle is returned, the associated resources must be released by the application after use with a call to .Xr gss_release_cred 3 . Specify .Dv NULL if not required. .It minor_status Mechanism specific status code. .El .Sh RETURN VALUES .Bl -tag -width ".It GSS_S_DEFECTIVE_CREDENTIAL" .It GSS_S_CONTINUE_NEEDED Indicates that a token from the peer application is required to complete the context, and that gss_accept_sec_context must be called again with that token. .It GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed on the input_token failed. .It GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks performed on the credential failed. .It GSS_S_NO_CRED The supplied credentials were not valid for context acceptance, or the credential handle did not reference any credentials. .It GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. .It GSS_S_BAD_BINDINGS The input_token contains different channel bindings to those specified via the input_chan_bindings parameter. .It GSS_S_NO_CONTEXT Indicates that the supplied context handle did not refer to a valid context. .It GSS_S_BAD_SIG The input_token contains an invalid MIC. .It GSS_S_OLD_TOKEN The input_token was too old. This is a fatal error during context establishment. .It GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a duplicate of a token already processed. This is a fatal error during context establishment. .It GSS_S_BAD_MECH The received token specified a mechanism that is not supported by the implementation or the provided credential. .El .Sh SEE ALSO .Xr gss_delete_sec_context 3 , .Xr gss_export_sec_context 3 , .Xr gss_get_mic 3 , .Xr gss_init_sec_context 3 , .Xr gss_release_buffer 3 , .Xr gss_release_cred 3 , .Xr gss_release_name 3 , .Xr gss_wrap 3 .Sh STANDARDS .Bl -tag -width ".It RFC 2743" .It RFC 2743 Generic Security Service Application Program Interface Version 2, Update 1 .It RFC 2744 Generic Security Service API Version 2 : C-bindings .El .Sh HISTORY The .Nm function first appeared in .Fx 7.0 . .Sh AUTHORS John Wray, Iris Associates .Sh COPYRIGHT Copyright (C) The Internet Society (2000). All Rights Reserved. .Pp This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. .Pp The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. .Pp This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Index: head/lib/libmd/mdX.3 =================================================================== --- head/lib/libmd/mdX.3 (revision 366582) +++ head/lib/libmd/mdX.3 (revision 366583) @@ -1,215 +1,215 @@ .\" .\" ---------------------------------------------------------------------------- .\" "THE BEER-WARE LICENSE" (Revision 42): .\" wrote this file. As long as you retain this notice you .\" can do whatever you want with this stuff. If we meet some day, and you think .\" this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp .\" ---------------------------------------------------------------------------- .\" .\" $FreeBSD$ .\" .Dd May 21, 2019 .Dt MDX 3 .Os .Sh NAME .Nm MDXInit , .Nm MDXUpdate , .Nm MDXPad , .Nm MDXFinal , .Nm MDXEnd , .Nm MDXFile , .Nm MDXFileChunk , .Nm MDXData .Nd calculate the RSA Data Security, Inc., ``MDX'' message digest .Sh LIBRARY .Lb libmd .Sh SYNOPSIS .In sys/types.h .In mdX.h .Ft void .Fn MDXInit "MDX_CTX *context" .Ft void .Fn MDXUpdate "MDX_CTX *context" "const void *data" "unsigned int len" .Ft void .Fn MDXPad "MDX_CTX *context" .Ft void .Fn MDXFinal "unsigned char digest[16]" "MDX_CTX *context" .Ft "char *" .Fn MDXEnd "MDX_CTX *context" "char *buf" .Ft "char *" .Fn MDXFile "const char *filename" "char *buf" .Ft "char *" .Fn MDXFileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" .Ft "char *" .Fn MDXData "const void *data" "unsigned int len" "char *buf" .Sh DESCRIPTION The MDX functions calculate a 128-bit cryptographic checksum (digest) for any number of input bytes. A cryptographic checksum is a one-way hash-function, that is, you cannot find (except by exhaustive search) the input corresponding to a particular output. This net result is a .Dq fingerprint of the input-data, which does not disclose the actual input. .Pp MD4 is the fastest and MD5 is somewhat slower. MD4 has now been broken; it should only be used where necessary for backward compatibility. MD5 has not yet (1999-02-11) been broken, but sufficient attacks have been made that its security is in some doubt. The attacks on both MD4 and MD5 are both in the nature of finding .Dq collisions \[en] that is, multiple inputs which hash to the same value; it is still unlikely for an attacker to be able to determine the exact original input given a hash value. .Pp The .Fn MDXInit , .Fn MDXUpdate , and .Fn MDXFinal functions are the core functions. Allocate an .Vt MDX_CTX , initialize it with .Fn MDXInit , run over the data with .Fn MDXUpdate , and finally extract the result using .Fn MDXFinal , which will also erase the .Vt MDX_CTX . .Pp The .Fn MDXPad function can be used to pad message data in same way as done by .Fn MDXFinal without terminating calculation. .Pp The .Fn MDXEnd function is a wrapper for .Fn MDXFinal which converts the return value to a 33-character (including the terminating '\e0') .Tn ASCII string which represents the 128 bits in hexadecimal. .Pp The .Fn MDXFile function calculates the digest of a file, and uses .Fn MDXEnd to return the result. If the file cannot be opened, a null pointer is returned. The .Fn MDXFileChunk function is similar to .Fn MDXFile , but it only calculates the digest over a byte-range of the file specified, starting at .Fa offset and spanning .Fa length bytes. If the .Fa length parameter is specified as 0, or more than the length of the remaining part of the file, .Fn MDXFileChunk calculates the digest from .Fa offset to the end of file. The .Fn MDXData function calculates the digest of a chunk of data in memory, and uses .Fn MDXEnd to return the result. .Pp When using .Fn MDXEnd , .Fn MDXFile , or .Fn MDXData , the .Fa buf argument can be a null pointer, in which case the returned string is allocated with .Xr malloc 3 and subsequently must be explicitly deallocated using .Xr free 3 after use. If the .Fa buf argument is non-null it must point to at least 33 characters of buffer space. .Sh ERRORS The .Fn MDXEnd function called with a null buf argument may fail and return NULL if: .Bl -tag -width Er .It Bq Er ENOMEM Insufficient storage space is available. .El .Pp The .Fn MDXFile and .Fn MDXFileChunk -may return NULL when underlying +may return NULL when underlying .Xr open 2 , .Xr fstat 2 , .Xr lseek 2 , or .Xr MDXEnd 2 fail. .Sh SEE ALSO .Xr md4 3 , .Xr md5 3 , .Xr ripemd 3 , .Xr sha 3 , .Xr sha256 3 , .Xr sha512 3 , .Xr skein 3 .Rs .%A R. Rivest .%T The MD4 Message-Digest Algorithm .%O RFC 1186 .Re .Rs .%A R. Rivest .%T The MD5 Message-Digest Algorithm .%O RFC 1321 .Re .Rs .%A H. Dobbertin .%T Alf Swindles Ann .%J CryptoBytes .%N 1(3):5 .%D 1995 .Re .Rs .%A MJ. B. Robshaw .%T On Recent Results for MD2, MD4 and MD5 .%J RSA Laboratories Bulletin .%N 4 .%D November 12, 1996 .Re .Sh HISTORY These functions appeared in .Fx 2.0 . .Sh AUTHORS The original MDX routines were developed by .Tn RSA Data Security, Inc., and published in the above references. This code is derived directly from these implementations by .An Poul-Henning Kamp Aq Mt phk@FreeBSD.org . .Pp Phk ristede runen. .Sh BUGS The .Tn MD5 algorithm has been proven to be vulnerable to practical collision attacks and should not be relied upon to produce unique outputs, .Em nor should they be used as part of a cryptographic signature scheme. Index: head/lib/libmd/ripemd.3 =================================================================== --- head/lib/libmd/ripemd.3 (revision 366582) +++ head/lib/libmd/ripemd.3 (revision 366583) @@ -1,165 +1,165 @@ .\" .\" ---------------------------------------------------------------------------- .\" "THE BEER-WARE LICENSE" (Revision 42): .\" wrote this file. As long as you retain this notice you .\" can do whatever you want with this stuff. If we meet some day, and you think .\" this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp .\" ---------------------------------------------------------------------------- .\" .\" From: Id: mdX.3,v 1.14 1999/02/11 20:31:49 wollman Exp .\" $FreeBSD$ .\" .Dd July 20, 2018 .Dt RIPEMD 3 .Os .Sh NAME .Nm RIPEMD160_Init , .Nm RIPEMD160_Update , .Nm RIPEMD160_Final , .Nm RIPEMD160_End , .Nm RIPEMD160_File , .Nm RIPEMD160_FileChunk , .Nm RIPEMD160_Data .Nd calculate the RIPEMD160 message digest .Sh LIBRARY .Lb libmd .Sh SYNOPSIS .In sys/types.h .In ripemd.h .Ft void .Fn RIPEMD160_Init "RIPEMD160_CTX *context" .Ft void .Fn RIPEMD160_Update "RIPEMD160_CTX *context" "const unsigned char *data" "unsigned int len" .Ft void .Fn RIPEMD160_Final "unsigned char digest[20]" "RIPEMD160_CTX *context" .Ft "char *" .Fn RIPEMD160_End "RIPEMD160_CTX *context" "char *buf" .Ft "char *" .Fn RIPEMD160_File "const char *filename" "char *buf" .Ft "char *" .Fn RIPEMD160_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" .Ft "char *" .Fn RIPEMD160_Data "const unsigned char *data" "unsigned int len" "char *buf" .Sh DESCRIPTION The .Li RIPEMD160_ functions calculate a 160-bit cryptographic checksum (digest) for any number of input bytes. A cryptographic checksum is a one-way hash function; that is, it is computationally impractical to find the input corresponding to a particular output. This net result is a .Dq fingerprint of the input-data, which does not disclose the actual input. .Pp The .Fn RIPEMD160_Init , .Fn RIPEMD160_Update , and .Fn RIPEMD160_Final functions are the core functions. Allocate an .Vt RIPEMD160_CTX , initialize it with .Fn RIPEMD160_Init , run over the data with .Fn RIPEMD160_Update , and finally extract the result using .Fn RIPEMD160_Final , which will also erase the .Vt RIPEMD160_CTX . .Pp The .Fn RIPEMD160_End function is a wrapper for .Fn RIPEMD160_Final which converts the return value to a 41-character (including the terminating '\e0') .Tn ASCII string which represents the 160 bits in hexadecimal. .Pp The .Fn RIPEMD160_File function calculates the digest of a file, and uses .Fn RIPEMD160_End to return the result. If the file cannot be opened, a null pointer is returned. The .Fn RIPEMD160_FileChunk function is similar to .Fn RIPEMD160_File , but it only calculates the digest over a byte-range of the file specified, starting at .Fa offset and spanning .Fa length bytes. If the .Fa length parameter is specified as 0, or more than the length of the remaining part of the file, .Fn RIPEMD160_FileChunk calculates the digest from .Fa offset to the end of file. The .Fn RIPEMD160_Data function calculates the digest of a chunk of data in memory, and uses .Fn RIPEMD160_End to return the result. .Pp When using .Fn RIPEMD160_End , .Fn RIPEMD160_File , or .Fn RIPEMD160_Data , the .Fa buf argument can be a null pointer, in which case the returned string is allocated with .Xr malloc 3 and subsequently must be explicitly deallocated using .Xr free 3 after use. If the .Fa buf argument is non-null it must point to at least 41 characters of buffer space. .Sh ERRORS The .Fn RIPEMD160_End function called with a null buf argument may fail and return NULL if: .Bl -tag -width Er .It Bq Er ENOMEM Insufficient storage space is available. .El .Pp The .Fn RIPEMD160_File and .Fn RIPEMD160_FileChunk -may return NULL when underlying +may return NULL when underlying .Xr open 2 , .Xr fstat 2 , .Xr lseek 2 , or .Xr RIPEMD160_End 2 fail. .Sh SEE ALSO .Xr md4 3 , .Xr md5 3 , .Xr sha 3 , .Xr sha256 3 , .Xr sha512 3 , .Xr skein 3 .Sh HISTORY These functions appeared in .Fx 4.0 . .Sh AUTHORS The core hash routines were implemented by Eric Young based on the published .Tn RIPEMD160 specification. .Sh BUGS No method is known to exist which finds two files having the same hash value, nor to find a file with a specific hash value. There is on the other hand no guarantee that such a method does not exist. Index: head/lib/libmd/sha.3 =================================================================== --- head/lib/libmd/sha.3 (revision 366582) +++ head/lib/libmd/sha.3 (revision 366583) @@ -1,210 +1,210 @@ .\" .\" ---------------------------------------------------------------------------- .\" "THE BEER-WARE LICENSE" (Revision 42): .\" wrote this file. As long as you retain this notice you .\" can do whatever you want with this stuff. If we meet some day, and you think .\" this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp .\" ---------------------------------------------------------------------------- .\" .\" From: Id: mdX.3,v 1.14 1999/02/11 20:31:49 wollman Exp .\" $FreeBSD$ .\" .Dd May 21, 2019 .Dt SHA 3 .Os .Sh NAME .Nm SHA_Init , .Nm SHA_Update , .Nm SHA_Final , .Nm SHA_End , .Nm SHA_File , .Nm SHA_FileChunk , .Nm SHA_Data , .Nm SHA1_Init , .Nm SHA1_Update , .Nm SHA1_Final , .Nm SHA1_End , .Nm SHA1_File , .Nm SHA1_FileChunk , .Nm SHA1_Data .Nd calculate the FIPS 160 and 160-1 ``SHA'' message digests .Sh LIBRARY .Lb libmd .Sh SYNOPSIS .In sys/types.h .In sha.h .Ft void .Fn SHA_Init "SHA_CTX *context" .Ft void .Fn SHA_Update "SHA_CTX *context" "const unsigned char *data" "size_t len" .Ft void .Fn SHA_Final "unsigned char digest[20]" "SHA_CTX *context" .Ft "char *" .Fn SHA_End "SHA_CTX *context" "char *buf" .Ft "char *" .Fn SHA_File "const char *filename" "char *buf" .Ft "char *" .Fn SHA_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" .Ft "char *" .Fn SHA_Data "const unsigned char *data" "unsigned int len" "char *buf" .Ft void .Fn SHA1_Init "SHA_CTX *context" .Ft void .Fn SHA1_Update "SHA_CTX *context" "const unsigned char *data" "size_t len" .Ft void .Fn SHA1_Final "unsigned char digest[20]" "SHA_CTX *context" .Ft "char *" .Fn SHA1_End "SHA_CTX *context" "char *buf" .Ft "char *" .Fn SHA1_File "const char *filename" "char *buf" .Ft "char *" .Fn SHA1_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" .Ft "char *" .Fn SHA1_Data "const unsigned char *data" "unsigned int len" "char *buf" .Sh DESCRIPTION The .Li SHA_ and .Li SHA1_ functions calculate a 160-bit cryptographic checksum (digest) for any number of input bytes. A cryptographic checksum is a one-way hash function; that is, it is computationally impractical to find the input corresponding to a particular output. This net result is a .Dq fingerprint of the input-data, which does not disclose the actual input. .Pp .Tn SHA (or .Tn SHA-0 ) is the original Secure Hash Algorithm specified in .Tn FIPS 160. It was quickly proven insecure, and has been superseded by .Tn SHA-1 . .Tn SHA-0 is included for compatibility purposes only. .Pp The .Fn SHA1_Init , .Fn SHA1_Update , and .Fn SHA1_Final functions are the core functions. Allocate an .Vt SHA_CTX , initialize it with .Fn SHA1_Init , run over the data with .Fn SHA1_Update , and finally extract the result using .Fn SHA1_Final , which will also erase the .Vt SHA_CTX . .Pp .Fn SHA1_End is a wrapper for .Fn SHA1_Final which converts the return value to a 41-character (including the terminating '\e0') .Tn ASCII string which represents the 160 bits in hexadecimal. .Pp .Fn SHA1_File calculates the digest of a file, and uses .Fn SHA1_End to return the result. If the file cannot be opened, a null pointer is returned. .Fn SHA1_FileChunk is similar to .Fn SHA1_File , but it only calculates the digest over a byte-range of the file specified, starting at .Fa offset and spanning .Fa length bytes. If the .Fa length parameter is specified as 0, or more than the length of the remaining part of the file, .Fn SHA1_FileChunk calculates the digest from .Fa offset to the end of file. .Fn SHA1_Data calculates the digest of a chunk of data in memory, and uses .Fn SHA1_End to return the result. .Pp When using .Fn SHA1_End , .Fn SHA1_File , or .Fn SHA1_Data , the .Fa buf argument can be a null pointer, in which case the returned string is allocated with .Xr malloc 3 and subsequently must be explicitly deallocated using .Xr free 3 after use. If the .Fa buf argument is non-null it must point to at least 41 characters of buffer space. .Sh ERRORS The .Fn SHA1_End function called with a null buf argument may fail and return NULL if: .Bl -tag -width Er .It Bq Er ENOMEM Insufficient storage space is available. .El .Pp The .Fn SHA1_File and .Fn SHA1_FileChunk -may return NULL when underlying +may return NULL when underlying .Xr open 2 , .Xr fstat 2 , .Xr lseek 2 , or .Xr SHA1_End 2 fail. .Sh SEE ALSO .Xr md4 3 , .Xr md5 3 , .Xr ripemd 3 , .Xr sha256 3 , .Xr sha512 3 , .Xr skein 3 .Sh HISTORY These functions appeared in .Fx 4.0 . .Sh AUTHORS The core hash routines were implemented by Eric Young based on the published .Tn FIPS standards. .Sh BUGS The .Tn SHA1 algorithm has been proven to be vulnerable to practical collision attacks and should not be relied upon to produce unique outputs, .Em nor should it be used as part of a new cryptographic signature scheme. .Pp The .Tn IA32 (Intel) implementation of .Tn SHA-1 makes heavy use of the .Ql bswapl instruction, which is not present on the original 80386. Attempts to use .Tn SHA-1 on those processors will cause an illegal instruction trap. (Arguably, the kernel should simply emulate this instruction.) Index: head/lib/libmd/sha256.3 =================================================================== --- head/lib/libmd/sha256.3 (revision 366582) +++ head/lib/libmd/sha256.3 (revision 366583) @@ -1,187 +1,187 @@ .\" .\" ---------------------------------------------------------------------------- .\" "THE BEER-WARE LICENSE" (Revision 42): .\" wrote this file. As long as you retain this notice you .\" can do whatever you want with this stuff. If we meet some day, and you think .\" this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp .\" ---------------------------------------------------------------------------- .\" .\" From: Id: mdX.3,v 1.14 1999/02/11 20:31:49 wollman Exp .\" $FreeBSD$ .\" .Dd July 20, 2018 .Dt SHA256 3 .Os .Sh NAME .Nm SHA224_Init , .Nm SHA224_Update , .Nm SHA224_Final , .Nm SHA224_End , .Nm SHA224_File , .Nm SHA224_FileChunk , .Nm SHA224_Data , .Nm SHA256_Init , .Nm SHA256_Update , .Nm SHA256_Final , .Nm SHA256_End , .Nm SHA256_File , .Nm SHA256_FileChunk , .Nm SHA256_Data .Nd calculate the FIPS 180-2 ``SHA-256'' (or SHA-224) message digest .Sh LIBRARY .Lb libmd .Sh SYNOPSIS .In sys/types.h .In sha224.h .Ft void .Fn SHA224_Init "SHA224_CTX *context" .Ft void .Fn SHA224_Update "SHA224_CTX *context" "const unsigned char *data" "size_t len" .Ft void .Fn SHA224_Final "unsigned char digest[32]" "SHA224_CTX *context" .Ft "char *" .Fn SHA224_End "SHA224_CTX *context" "char *buf" .Ft "char *" .Fn SHA224_File "const char *filename" "char *buf" .Ft "char *" .Fn SHA224_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" .Ft "char *" .Fn SHA224_Data "const unsigned char *data" "unsigned int len" "char *buf" .In sha256.h .Ft void .Fn SHA256_Init "SHA256_CTX *context" .Ft void .Fn SHA256_Update "SHA256_CTX *context" "const unsigned char *data" "size_t len" .Ft void .Fn SHA256_Final "unsigned char digest[32]" "SHA256_CTX *context" .Ft "char *" .Fn SHA256_End "SHA256_CTX *context" "char *buf" .Ft "char *" .Fn SHA256_File "const char *filename" "char *buf" .Ft "char *" .Fn SHA256_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" .Ft "char *" .Fn SHA256_Data "const unsigned char *data" "unsigned int len" "char *buf" .Sh DESCRIPTION The .Li SHA256_ functions calculate a 256-bit cryptographic checksum (digest) for any number of input bytes. A cryptographic checksum is a one-way hash function; that is, it is computationally impractical to find the input corresponding to a particular output. This net result is a .Dq fingerprint of the input-data, which does not disclose the actual input. .Pp The .Fn SHA256_Init , .Fn SHA256_Update , and .Fn SHA256_Final functions are the core functions. Allocate an .Vt SHA256_CTX , initialize it with .Fn SHA256_Init , run over the data with .Fn SHA256_Update , and finally extract the result using .Fn SHA256_Final , which will also erase the .Vt SHA256_CTX . .Pp .Fn SHA256_End is a wrapper for .Fn SHA256_Final which converts the return value to a 65-character (including the terminating '\e0') .Tn ASCII string which represents the 256 bits in hexadecimal. .Pp .Fn SHA256_File calculates the digest of a file, and uses .Fn SHA256_End to return the result. If the file cannot be opened, a null pointer is returned. .Fn SHA256_FileChunk is similar to .Fn SHA256_File , but it only calculates the digest over a byte-range of the file specified, starting at .Fa offset and spanning .Fa length bytes. If the .Fa length parameter is specified as 0, or more than the length of the remaining part of the file, .Fn SHA256_FileChunk calculates the digest from .Fa offset to the end of file. .Fn SHA256_Data calculates the digest of a chunk of data in memory, and uses .Fn SHA256_End to return the result. .Pp When using .Fn SHA256_End , .Fn SHA256_File , or .Fn SHA256_Data , the .Fa buf argument can be a null pointer, in which case the returned string is allocated with .Xr malloc 3 and subsequently must be explicitly deallocated using .Xr free 3 after use. If the .Fa buf argument is non-null it must point to at least 65 characters of buffer space. .Pp SHA224 is identical SHA256, except it has slightly different initialization vectors, and is truncated to a shorter digest. .Sh ERRORS The .Fn SHA256_End function called with a null buf argument may fail and return NULL if: .Bl -tag -width Er .It Bq Er ENOMEM Insufficient storage space is available. .El .Pp The .Fn SHA256_File and .Fn SHA256_FileChunk -may return NULL when underlying +may return NULL when underlying .Xr open 2 , .Xr fstat 2 , .Xr lseek 2 , or .Xr SHA256_End 2 fail. .Sh SEE ALSO .Xr md4 3 , .Xr md5 3 , .Xr ripemd 3 , .Xr sha 3 , .Xr sha512 3 , .Xr skein 3 .Sh HISTORY These functions appeared in .Fx 6.0 . .Sh AUTHORS The core hash routines were implemented by Colin Percival based on the published .Tn FIPS 180-2 standard. .Sh BUGS No method is known to exist which finds two files having the same hash value, nor to find a file with a specific hash value. There is on the other hand no guarantee that such a method does not exist. Index: head/lib/libmd/sha512.3 =================================================================== --- head/lib/libmd/sha512.3 (revision 366582) +++ head/lib/libmd/sha512.3 (revision 366583) @@ -1,232 +1,232 @@ .\" .\" ---------------------------------------------------------------------------- .\" "THE BEER-WARE LICENSE" (Revision 42): .\" wrote this file. As long as you retain this notice you .\" can do whatever you want with this stuff. If we meet some day, and you think .\" this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp .\" ---------------------------------------------------------------------------- .\" .\" From: Id: mdX.3,v 1.14 1999/02/11 20:31:49 wollman Exp .\" $FreeBSD$ .\" .Dd May 21, 2019 .Dt SHA512 3 .Os .Sh NAME .Nm SHA512_Init , .Nm SHA512_Update , .Nm SHA512_Final , .Nm SHA512_End , .Nm SHA512_File , .Nm SHA512_FileChunk , .Nm SHA512_Data , .Nm SHA384_Init , .Nm SHA384_Update , .Nm SHA384_Final , .Nm SHA384_End , .Nm SHA384_File , .Nm SHA384_FileChunk , .Nm SHA384_Data , .Nm SHA512_256_Init , .Nm SHA512_256_Update , .Nm SHA512_256_Final , .Nm SHA512_256_End , .Nm SHA512_256_File , .Nm SHA512_256_FileChunk , .Nm SHA512_256_Data .Nd calculate the FIPS 180-4 ``SHA-512'' family of message digests .Sh LIBRARY .Lb libmd .Sh SYNOPSIS .In sys/types.h .In sha512.h .Ft void .Fn SHA512_Init "SHA512_CTX *context" .Ft void .Fn SHA512_Update "SHA512_CTX *context" "const unsigned char *data" "size_t len" .Ft void .Fn SHA512_Final "unsigned char digest[64]" "SHA512_CTX *context" .Ft "char *" .Fn SHA512_End "SHA512_CTX *context" "char *buf" .Ft "char *" .Fn SHA512_File "const char *filename" "char *buf" .Ft "char *" .Fn SHA512_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" .Ft "char *" .Fn SHA512_Data "const unsigned char *data" "unsigned int len" "char *buf" .In sha384.h .Ft void .Fn SHA384_Init "SHA384_CTX *context" .Ft void .Fn SHA384_Update "SHA384_CTX *context" "const unsigned char *data" "size_t len" .Ft void .Fn SHA384_Final "unsigned char digest[48]" "SHA384_CTX *context" .Ft "char *" .Fn SHA384_End "SHA384_CTX *context" "char *buf" .Ft "char *" .Fn SHA384_File "const char *filename" "char *buf" .Ft "char *" .Fn SHA384_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" .Ft "char *" .Fn SHA384_Data "const unsigned char *data" "unsigned int len" "char *buf" .In sha512t.h .Ft void .Fn SHA512_256_Init "SHA512_CTX *context" .Ft void .Fn SHA512_256_Update "SHA512_CTX *context" "const unsigned char *data" "size_t len" .Ft void .Fn SHA512_256_Final "unsigned char digest[32]" "SHA512_CTX *context" .Ft "char *" .Fn SHA512_256_End "SHA512_CTX *context" "char *buf" .Ft "char *" .Fn SHA512_256_File "const char *filename" "char *buf" .Ft "char *" .Fn SHA512_256_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" .Ft "char *" .Fn SHA512_256_Data "const unsigned char *data" "unsigned int len" "char *buf" .Sh DESCRIPTION The .Li SHA512_ functions calculate a 512-bit cryptographic checksum (digest) for any number of input bytes. A cryptographic checksum is a one-way hash function; that is, it is computationally impractical to find the input corresponding to a particular output. This net result is a .Dq fingerprint of the input-data, which does not disclose the actual input. .Pp The .Fn SHA512_Init , .Fn SHA512_Update , and .Fn SHA512_Final functions are the core functions. Allocate an .Vt SHA512_CTX , initialize it with .Fn SHA512_Init , run over the data with .Fn SHA512_Update , and finally extract the result using .Fn SHA512_Final , which will also erase the .Vt SHA512_CTX . .Pp .Fn SHA512_End is a wrapper for .Fn SHA512_Final which converts the return value to a 129-character (including the terminating '\e0') .Tn ASCII string which represents the 512 bits in hexadecimal. .Pp .Fn SHA512_File calculates the digest of a file, and uses .Fn SHA512_End to return the result. If the file cannot be opened, a null pointer is returned. .Fn SHA512_FileChunk is similar to .Fn SHA512_File , but it only calculates the digest over a byte-range of the file specified, starting at .Fa offset and spanning .Fa length bytes. If the .Fa length parameter is specified as 0, or more than the length of the remaining part of the file, .Fn SHA512_FileChunk calculates the digest from .Fa offset to the end of file. .Fn SHA512_Data calculates the digest of a chunk of data in memory, and uses .Fn SHA512_End to return the result. .Pp When using .Fn SHA512_End , .Fn SHA512_File , or .Fn SHA512_Data , the .Fa buf argument can be a null pointer, in which case the returned string is allocated with .Xr malloc 3 and subsequently must be explicitly deallocated using .Xr free 3 after use. If the .Fa buf argument is non-null it must point to at least 129 characters of buffer space. .Pp The .Li SHA384_ and .Li SHA512_256_ functions are identical to the .Li SHA512_ functions except they use a different initial hash value and the output is truncated to 384 bits and 256 bits respectively. .Pp .Fn SHA384_End is a wrapper for .Fn SHA384_Final which converts the return value to a 97-character (including the terminating '\e0') .Tn ASCII string which represents the 384 bits in hexadecimal. .Pp .Fn SHA512_256_End is a wrapper for .Fn SHA512_Final which converts the return value to a 65-character (including the terminating '\e0') .Tn ASCII string which represents the 256 bits in hexadecimal. .Sh ERRORS The .Fn SHA512_End function called with a null buf argument may fail and return NULL if: .Bl -tag -width Er .It Bq Er ENOMEM Insufficient storage space is available. .El .Pp The .Fn SHA512_File and .Fn SHA512_FileChunk -may return NULL when underlying +may return NULL when underlying .Xr open 2 , .Xr fstat 2 , .Xr lseek 2 , or .Xr SHA512_End 2 fail. .Sh SEE ALSO .Xr md4 3 , .Xr md5 3 , .Xr ripemd 3 , .Xr sha 3 , .Xr sha256 3 , .Xr sha512 3 , .Xr skein 3 .Sh HISTORY These functions appeared in .Fx 9.0 . .Sh AUTHORS The core hash routines were implemented by Colin Percival based on the published .Tn FIPS 180-2 standard. .Sh BUGS No method is known to exist which finds two files having the same hash value, nor to find a file with a specific hash value. There is on the other hand no guarantee that such a method does not exist. Index: head/lib/libmd/skein.3 =================================================================== --- head/lib/libmd/skein.3 (revision 366582) +++ head/lib/libmd/skein.3 (revision 366583) @@ -1,236 +1,236 @@ .\"- .\" Copyright (c) 2016 Allan Jude .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd May 21, 2019 .Dt SKEIN 3 .Os .Sh NAME .Nm SKEIN256_Init , .Nm SKEIN256_Update , .Nm SKEIN256_Final , .Nm SKEIN256_End , .Nm SKEIN256_File , .Nm SKEIN256_FileChunk , .Nm SKEIN256_Data , .Nm SKEIN512_Init , .Nm SKEIN512_Update , .Nm SKEIN512_Final , .Nm SKEIN512_End , .Nm SKEIN512_File , .Nm SKEIN512_FileChunk , .Nm SKEIN512_Data , .Nm SKEIN1024_Init , .Nm SKEIN1024_Update , .Nm SKEIN1024_Final , .Nm SKEIN1024_End , .Nm SKEIN1024_File , .Nm SKEIN1024_FileChunk , .Nm SKEIN1024_Data .Nd calculate the ``SKEIN'' family of message digests .Sh LIBRARY .Lb libmd .Sh SYNOPSIS .In sys/types.h .In skein.h .Ft void .Fn SKEIN256_Init "SKEIN256_CTX *context" .Ft void .Fn SKEIN256_Update "SKEIN256_CTX *context" "const unsigned char *data" "size_t len" .Ft void .Fn SKEIN256_Final "unsigned char digest[32]" "SKEIN256_CTX *context" .Ft "char *" .Fn SKEIN256_End "SKEIN256_CTX *context" "char *buf" .Ft "char *" .Fn SKEIN256_File "const char *filename" "char *buf" .Ft "char *" .Fn SKEIN256_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" .Ft "char *" .Fn SKEIN256_Data "const unsigned char *data" "unsigned int len" "char *buf" .Ft void .Fn SKEIN512_Init "SKEIN512_CTX *context" .Ft void .Fn SKEIN512_Update "SKEIN512_CTX *context" "const unsigned char *data" "size_t len" .Ft void .Fn SKEIN512_Final "unsigned char digest[64]" "SKEIN512_CTX *context" .Ft "char *" .Fn SKEIN512_End "SKEIN512_CTX *context" "char *buf" .Ft "char *" .Fn SKEIN512_File "const char *filename" "char *buf" .Ft "char *" .Fn SKEIN512_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" .Ft "char *" .Fn SKEIN512_Data "const unsigned char *data" "unsigned int len" "char *buf" .Ft void .Fn SKEIN1024_Init "SKEIN1024_CTX *context" .Ft void .Fn SKEIN1024_Update "SKEIN1024_CTX *context" "const unsigned char *data" "size_t len" .Ft void .Fn SKEIN1024_Final "unsigned char digest[128]" "SKEIN1024_CTX *context" .Ft "char *" .Fn SKEIN1024_End "SKEIN1024_CTX *context" "char *buf" .Ft "char *" .Fn SKEIN1024_File "const char *filename" "char *buf" .Ft "char *" .Fn SKEIN1024_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" .Ft "char *" .Fn SKEIN1024_Data "const unsigned char *data" "unsigned int len" "char *buf" .Sh DESCRIPTION .Li Skein is a new family of cryptographic hash functions based on the .Li Threefish large-block cipher. Its design combines speed, security, simplicity, and a great deal of flexibility in a modular package that is easy to analyze. .Li Skein is defined for three different internal state sizes\(em256 bits, 512 bits, and 1024 bits\(emand any output size. This allows Skein to be a drop-in replacement for the entire SHA family of hash functions. .Pp The .Fn SKEIN256_Init , .Fn SKEIN256_Update , and .Fn SKEIN256_Final functions are the core functions. Allocate an .Vt SKEIN256_CTX , initialize it with .Fn SKEIN256_Init , run over the data with .Fn SKEIN256_Update , and finally extract the result using .Fn SKEIN256_Final , which will also erase the .Vt SKEIN256_CTX . .Pp .Fn SKEIN256_End is a wrapper for .Fn SKEIN256_Final which converts the return value to a 33-character (including the terminating '\e0') .Tn ASCII string which represents the 256 bits in hexadecimal. .Pp .Fn SKEIN256_File calculates the digest of a file, and uses .Fn SKEIN256_End to return the result. If the file cannot be opened, a null pointer is returned. .Fn SKEIN256_FileChunk is similar to .Fn SKEIN256_File , but it only calculates the digest over a byte-range of the file specified, starting at .Fa offset and spanning .Fa length bytes. If the .Fa length parameter is specified as 0, or more than the length of the remaining part of the file, .Fn SKEIN256_FileChunk calculates the digest from .Fa offset to the end of file. .Fn SKEIN256_Data calculates the digest of a chunk of data in memory, and uses .Fn SKEIN256_End to return the result. .Pp When using .Fn SKEIN256_End , .Fn SKEIN256_File , or .Fn SKEIN256_Data , the .Fa buf argument can be a null pointer, in which case the returned string is allocated with .Xr malloc 3 and subsequently must be explicitly deallocated using .Xr free 3 after use. If the .Fa buf argument is non-null it must point to at least 33 characters of buffer space. .Pp The .Li SKEIN512_ and .Li SKEIN1024_ functions are similar to the .Li SKEIN256_ functions except they produce a 512-bit, 65 character, or 1024-bit, 129 character, output. .Sh ERRORS The .Fn SKEIN256_End function called with a null buf argument may fail and return NULL if: .Bl -tag -width Er .It Bq Er ENOMEM Insufficient storage space is available. .El .Pp The .Fn SKEIN256_File and .Fn SKEIN256_FileChunk -may return NULL when underlying +may return NULL when underlying .Xr open 2 , .Xr fstat 2 , .Xr lseek 2 , or .Xr SKEIN256_End 2 fail. .Sh SEE ALSO .Xr md4 3 , .Xr md5 3 , .Xr ripemd 3 , .Xr sha 3 , .Xr sha256 3 , .Xr sha512 3 .Sh HISTORY These functions appeared in .Fx 11.0 . .Sh AUTHORS .An -nosplit -The core hash routines were imported from version 1.3 of the optimized +The core hash routines were imported from version 1.3 of the optimized Skein reference implementation written by .An Doug Whiting as submitted to the NSA SHA-3 contest. The algorithms were developed by -.An Niels Ferguson , +.An Niels Ferguson , .An Stefan Lucks , -.An Bruce Schneier , -.An Doug Whiting , +.An Bruce Schneier , +.An Doug Whiting , .An Mihir Bellare , .An Tadayoshi Kohno , .An Jon Callas, and .An Jesse Walker . Index: head/lib/libmt/mt.3 =================================================================== --- head/lib/libmt/mt.3 (revision 366582) +++ head/lib/libmt/mt.3 (revision 366583) @@ -1,454 +1,454 @@ -.\" +.\" .\" Copyright (c) 2013, 2015 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. -.\" +.\" .\" Authors: Ken Merry (Spectra Logic Corporation) -.\" +.\" .\" $FreeBSD$ .\" .Dd February 13, 2015 .Dt MT 3 .Os .Sh NAME .Nm mt_start_element , .Nm mt_end_element , .Nm mt_char_handler , .Nm mt_status_tree_sbuf , .Nm mt_status_tree_print , .Nm mt_status_entry_free , .Nm mt_status_free , .Nm mt_entry_sbuf , .Nm mt_param_parent_print , .Nm mt_param_entry_print , .Nm mt_protect_print , .Nm mt_param_list , .Nm mt_density_name , .Nm mt_density_bp , .Nm mt_density_num , .Nm mt_get_xml_str , .Nm mt_get_status .Nd Magnetic Tape library .Sh LIBRARY .Lb libmt .Sh SYNOPSIS .In sys/sbuf.h .In bsdxml.h .In mtlib.h .Ft void .Fo mt_start_element .Fa "void *user_data" .Fa "const char *name" .Fa "const char **attr" .Fc .Ft void .Fo mt_end_element .Fa "void *user_data" .Fa "const char *name" .Fc .Ft void .Fo mt_char_handler .Fa "void *user_data" .Fa "const XML_Char *str" .Fa "int len" .Fc .Ft void .Fo mt_status_tree_sbuf .Fa "struct sbuf *sb" .Fa "struct mt_status_entry *entry" .Fa "int indent" .Fa "void (*sbuf_func)(struct sbuf *sb, struct mt_status_entry *entry, void *arg)" .Fa "void *arg" .Fc .Ft void .Fo mt_status_tree_print .Fa "struct mt_status_entry *entry" .Fa "int indent" .Fa "void (*print_func)(struct mt_status_entry *entry, void *arg)" .Fa "void *arg" .Fc .Ft "struct mt_status_entry *" .Fo mt_entry_find .Fa "struct mt_status_entry *entry" .Fa "char *name" .Fc .Ft "struct mt_status_entry *" .Fo mt_status_entry_find .Fa "struct mt_status_data *status_data" .Fa "char *name" .Fc .Ft void .Fo mt_status_entry_free .Fa "struct mt_status_entry *entry)" .Fc .Ft void .Fo mt_status_free .Fa "struct mt_status_data *status_data" .Fc .Ft void .Fo mt_entry_sbuf .Fa "struct sbuf *sb" .Fa "struct mt_status_entry *entry" .Fa "char *fmt" .Fc .Ft void .Fo mt_param_parent_sbuf .Fa "struct sbuf *sb" .Fa "struct mt_status_entry *entry" .Fa "struct mt_print_params *print_params" .Fc .Ft void .Fo mt_param_parent_print .Fa "struct mt_status_entry *entry" .Fa "struct mt_print_params *print_params" .Fc .Ft void .Fo mt_param_entry_sbuf .Fa "struct sbuf *sb" .Fa "struct mt_status_entry *entry" .Fa "void *arg" .Fc .Ft void .Fo mt_param_entry_print .Fa "struct mt_status_entry *entry" .Fa "void *arg" .Fc .Ft int .Fo mt_protect_print .Fa "struct mt_status_data *status_data" .Fa "int verbose" .Fc .Ft int .Fo mt_param_list .Fa "struct mt_status_data *status_data" .Fa "char *param_name" .Fa "int quiet" .Fc .Ft "const char *" .Fo mt_density_name .Fa "int density_num" .Fc .Ft int .Fo mt_density_bp .Fa "int density_num" .Fa "int bpi" .Fc .Ft int .Fo mt_density_num .Fa "const char *density_name" .Fc .Ft int .Fo mt_get_status .Fa "char *xml_str" .Fa "struct mt_status_data *status_data" .Fc .Sh DESCRIPTION The MT library consists of a number of functions designed to aid in interacting with the .Xr sa 4 driver. The .Xr sa 4 driver returns some status data as XML-formatted strings, and the primary purpose of this library is to make it easier for the software developer to parse those strings and extract the status values. .Pp -The +The .Fn mt_start_element , .Fn mt_end_element , and .Fn mt_char_handler functions are designed to work with the .Xr libbsdxml 3 library, which is an XML parsing library. The user data for the XML parser should be set with .Fn XML_SetUserData to a zeroed struct mt_status_data with the entries list initialized. The element handlers for the XML parser should be set to .Fn mt_start_element and .Fn mt_end_element with .Fn XML_SetElementHandler . The character data handler should be set to .Fn mt_char_handler with the .Fn XML_SetCharacterDataHandler function. The error member of the status_data structure will be set to 0 if parsing is successful, and non-zero if parsing failed. In the event of a failure, the error_str member will contain an error message describing the failure. These functions will build a tree of tape driver status data that can be searched and printed using the other functions in this library. .Pp .Fn mt_status_tree_sbuf takes the root node of a tree of .Xr sa 4 driver status information, and displays it in an .Xr sbuf 9 . The .Ar sb argument is the destination sbuf. The .Ar entry argument is the root of the tree. The .Ar indent argument is the number of characters to indent the output. Each recursive call to .Fn mt_status_tree_sbuf will have the indent level incremented by 2. The .Ar sbuf_func argument is for a user-supplied alternate printing function. If it is non-NULL, it will be called instead of the default output printing code. The .Ar arg argument is an argument for the .Ar sbuf_func function. .Pp The .Fn mt_status_tree_print function is the same as the .Fn mt_status_tree_sbuf function, except that the tree is printed to standard out instead of to a sbuf. .Pp The .Fn mt_entry_find function returns the first entry in the tree starting at .Ar entry that matches .Ar name . The supplied node name can be a single level name like "foo", or it can specify mulitple node names that must be matched, for instance "foo.bar.baz". In the case of a single level name, it will match any node beneath .Ar entry that matches .Ar name . In the case of a multi-level name like "foo.bar.baz", it will return the first entry named "baz" whose immediate parent is "bar" and where the parent of "bar" is named "foo". .Pp The .Fn mt_status_entry_find is the same as .Fn mt_entry_find , except that it operates on the top level mt_status_data and all mt_status_entry nodes below it instead of just an mt_status_entry structure. .Pp The .Fn mt_status_entry_free function frees the tree of status data underneath .Ar entry . .Pp The .Fn mt_status_free function frees the tree of status data underneath .Ar status_data . .Pp The .Fn mt_entry_sbuf function prints .Ar entry to the supplied sbuf .Ar sb , optionally using the .Xr printf 3 format .Ar fmt . If .Ar fmt is NULL, then .Fn mt_entry_sbuf will render integer types in base 10 without special formatting and all other types as they were rendered in the XML. .Pp .Fn mt_param_parent_sbuf prints the parents of the given .Ar entry to the supplied sbuf .Ar sb subject to the print parameters .Ar print_params . The result will be formatted with a period between each level, like "foo.bar.baz". .Pp .Fn mt_param_parent_print is like .Fn mt_param_parent_sbuf except that it prints the results to standard output instead of an sbuf. .Pp .Fn mt_param_entry_sbuf prints the -.Ar entry +.Ar entry to the given sbuf .Ar sb . The argument .Ar arg is a pointer to struct mt_print_params, which allows the caller to control the printing output. This function is intended to be supplied as an argument to .Fn mt_status_tree_sbuf . .Pp .Fn mt_param_entry_print is like .Fn mt_param_entry_sbuf except that it prints to standard output instead of an sbuf. It is intended to be used as an argument to .Fn mt_status_tree_print . .Pp .Fn mt_protect_print prints tape drive protection information from the supplied .Ar status_data beginning at the node name defined as the root node for protection data. If the .Ar verbose argument is non-zero, protection entry descriptions will be printed. If it is zero, protection entry descriptions will not be printed. .Pp .Fn mt_param_list prints tape driver parameters information from the supplied .Ar status_data . If the .Ar param_name is non-NULL, only the named parameter will be printed. If .Ar quiet is non-zero, parameter descriptions will be omitted in the output. .Pp .Fn mt_density_name Returns a text identifier for the supplied numeric .Ar density_num . The .Ar density_num should currently be a value between 0 and 255 inclusive, since that is the valid range for .Tn SCSI density code values. See below for notes on the return values. .Pp .Fn mt_density_bp Returns the bits per inch or bits per mm values for a given density entry specified by the .Ar density_num . -If the +If the .Ar bpi argument is non-zero, the bits per inch value is returned. Otherwise, the bits per mm value is returned. .Pp .Fn mt_density_num returns a numeric value for a text density description. It does a case-insensitive comparison of density names in the density table to the supplied density name. .Pp .Fn mt_get_xml_str gets the current XML status / parameter string from the sa(4) driver instance referenced by the open file descriptor .Ar mtfd . -The -.Xr mtio 4 +The +.Xr mtio 4 .Xr ioctl 2 to be used is supplied as the .Ar cmd argument. Currently the .Fn mt_get_xml_str function will work with the .Dv MTIOCEXTGET and .Dv MTIOCPARAMGET ioctls. The supplied .Ar xml_str will be filled in with a pointer to the complete XML status string. Multiple calls to the given .Xr ioctl 2 are made and more space is malloced until all of the XML string is fetched. The string returned in the .Ar xml_str argument should be freed when it is no longer in use. .Sh RETURN VALUES .Fn mt_entry_find returns the first matching entry, or NULL if it fails to find a match. .Pp .Fn mt_status_entry_find returns the first matching entry, or NULL if it fails to find a match. .Pp .Fn mt_protect_print Returns 0 for success, and non-zero for failure. .Fn mt_protect_print can only fail if it cannot find protection information in the supplied status data. .Pp .Fn mt_param_list Returns 0 for success and non-zero for failure. .Fn mt_param_list can only fail if it cannot find parameter information in the supplied status data. .Pp .Fn mt_density_name returns a text description of a numeric density. The special density value 0 is decoded as "default". The special density value 0x7f is decoded as "same". If the density is not known, .Fn mt_density_name will return "UNKNOWN". .Pp .Fn mt_density_bp -returns the bits per inch value for the given density (if the +returns the bits per inch value for the given density (if the .Ar bpi field is non-zero), the bits per mm value otherwise, or 0 if the supplied .Ar density_num is not in the density table or the table entry does not include bpi / bpmm values. .Pp .Fn mt_density_num returns a numeric density value between 0 and 255 for the supplied density name. It returns 0 if the density name is not recognized. .Pp .Fn mt_get_xml_str returns 0 for success, and -1 for failure. .Sh SEE ALSO .Xr mt 1 , .Xr mtio 4 , .Xr sa 4 .Sh HISTORY The MT library first appeared in .Fx 10.1 . .Sh AUTHORS .An Ken Merry Aq ken@FreeBSD.org .Sh BUGS The library interface is not complete, and may change in the future. Application authors should not rely on the library interface to be consistent in the immediate future. Index: head/lib/libpathconv/abs2rel.3 =================================================================== --- head/lib/libpathconv/abs2rel.3 (revision 366582) +++ head/lib/libpathconv/abs2rel.3 (revision 366583) @@ -1,136 +1,136 @@ .\" .\" Copyright (c) 1997 Shigio Yamaguchi. All rights reserved. .\" Copyright (c) 1999 Tama Communications 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. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd Dec 15, 1997" .Dt ABS2REL 3 .Os .Sh NAME .Nm abs2rel .Nd make a relative path name from an absolute path name .Sh SYNOPSIS .Ft "char *" .Fn abs2rel "const char *path" "const char *base" "char *result" "size_t size" .Sh DESCRIPTION The .Fn abs2rel function makes a relative path name from an absolute path name .Fa path based on a directory .Fa base and copies the resulting path name into the memory referenced by .Fa result . The .Fa result argument must refer to a buffer capable of storing at least .Fa size characters. The resulting path name may include symbolic links. The .Fn abs2rel function doesn't check whether or not any path exists. .Sh "RETURN VALUES" The .Fn abs2rel function returns relative path name on success. If an error occurs, it returns .Dv NULL . .Sh ERRORS The .Fn abs2rel function may fail and set the external variable .Va errno to indicate the error. .Bl -tag -width Er .It Bq Er EINVAL The .Fa base directory isn't an absolute path name or the .Fa size argument is zero. .It Bq Er ERANGE The .Fa size argument is greater than zero but smaller than the length of the pathname plus 1. .Sh EXAMPLE char result[MAXPATHLEN]; char *path = abs2rel("/usr/src/sys", "/usr/local/lib", result, MAXPATHLEN); yields: path == "../../src/sys" Similarly, path1 = abs2rel("/usr/src/sys", "/usr", result, MAXPATHLEN); path2 = abs2rel("/usr/src/sys", "/usr/src/sys", result, MAXPATHLEN); yields: path1 == "src/sys" path2 == "." .Sh BUGS If the .Fa base directory includes symbolic links, the .Fn abs2rel function produces the wrong path. For example, if '/sys' is a symbolic link to '/usr/src/sys', char *path = abs2rel("/usr/local/lib", "/sys", result, MAXPATHLEN); yields: path == "../usr/local/lib" /* It's wrong!! */ You should convert the base directory into a real path in advance. .Pp path = abs2rel("/sys/kern", realpath("/sys", resolvedname), result, MAXPATHLEN); yields: path == "../../../sys/kern" /* It's correct but ... */ -That is correct, but a little redundant. If you wish get the simple -answer 'kern', do the following. +That is correct, but a little redundant. +If you wish get the simple answer 'kern', do the following. path = abs2rel(realpath("/sys/kern", r1), realpath("/sys", r2), result, MAXPATHLEN); The .Fn realpath function assures correct result, but don't forget that .Fn realpath requires that all but the last component of the path exist. .Sh "SEE ALSO" .Xr rel2abs 3 .Sh AUTHORS Shigio Yamaguchi (shigio@tamacom.com) Index: head/lib/libpmc/pmc.sandybridge.3 =================================================================== --- head/lib/libpmc/pmc.sandybridge.3 (revision 366582) +++ head/lib/libpmc/pmc.sandybridge.3 (revision 366583) @@ -1,939 +1,939 @@ -.\" Copyright (c) 2012 Davide Italiano +.\" Copyright (c) 2012 Davide Italiano .\" 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 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. .\" .\" $FreeBSD$ .\" .Dd October 19, 2012 .Dt PMC.SANDYBRIDGE 3 .Os .Sh NAME .Nm pmc.sandybridge .Nd measurement events for .Tn Intel .Tn Sandy Bridge family CPUs .Sh LIBRARY .Lb libpmc .Sh SYNOPSIS .In pmc.h .Sh DESCRIPTION .Tn Intel .Tn "Sandy Bridge" CPUs contain PMCs conforming to the version 3 of the .Tn Intel performance measurement architecture. These CPUs may contain up to three classes of PMCs: .Bl -tag -width "Li PMC_CLASS_IAP" .It Li PMC_CLASS_IAF Fixed-function counters that count only one hardware event per counter. .It Li PMC_CLASS_IAP Programmable counters that may be configured to count one of a defined set of hardware events. .It Li PMC_CLASS_TSC These PMCs are documented in .Xr pmc.tsc 3 . .El .Pp The number of PMCs available in each class and their widths need to be determined at run time by calling .Xr pmc_cpuinfo 3 . .Pp Intel Sandy Bridge PMCs are documented in .Rs .%B "Intel(R) 64 and IA-32 Architectures Software Developers Manual" .%T "Volume 3B: System Programming Guide, Part 2" .%N "Order Number: 253669-039US" .%D May 2011 .%Q "Intel Corporation" .Re .Ss SANDY BRIDGE FIXED FUNCTION PMCS These PMCs and their supported events are documented in .Xr pmc.iaf 3 . .Ss SANDY BRIDGE PROGRAMMABLE PMCS The programmable PMCs support the following capabilities: .Bl -column "PMC_CAP_INTERRUPT" "Support" .It Em Capability Ta Em Support .It PMC_CAP_CASCADE Ta \&No .It PMC_CAP_EDGE Ta Yes .It PMC_CAP_INTERRUPT Ta Yes .It PMC_CAP_INVERT Ta Yes .It PMC_CAP_READ Ta Yes .It PMC_CAP_PRECISE Ta \&No .It PMC_CAP_SYSTEM Ta Yes .It PMC_CAP_TAGGING Ta \&No .It PMC_CAP_THRESHOLD Ta Yes .It PMC_CAP_USER Ta Yes .It PMC_CAP_WRITE Ta Yes .El .Ss Event Qualifiers Event specifiers for these PMCs support the following common qualifiers: .Bl -tag -width indent .It Li rsp= Ns Ar value Configure the Off-core Response bits. .Bl -tag -width indent .It Li REQ_DMND_DATA_RD Counts the number of demand and DCU prefetch data reads of full and partial cachelines as well as demand data page table entry cacheline reads. Does not count L2 data read prefetches or instruction fetches. .It Li REQ_DMND_RFO Counts the number of demand and DCU prefetch reads for ownership (RFO) requests generated by a write to data cacheline. Does not count L2 RFO prefetches. .It Li REQ_DMND_IFETCH Counts the number of demand and DCU prefetch instruction cacheline reads. Does not count L2 code read prefetches. .It Li REQ_WB Counts the number of writeback (modified to exclusive) transactions. .It Li REQ_PF_DATA_RD Counts the number of data cacheline reads generated by L2 prefetchers. .It Li REQ_PF_RFO Counts the number of RFO requests generated by L2 prefetchers. .It Li REQ_PF_IFETCH Counts the number of code reads generated by L2 prefetchers. .It Li REQ_PF_LLC_DATA_RD L2 prefetcher to L3 for loads. .It Li REQ_PF_LLC_RFO RFO requests generated by L2 prefetcher .It Li REQ_PF_LLC_IFETCH L2 prefetcher to L3 for instruction fetches. .It Li REQ_BUS_LOCKS Bus lock and split lock requests. .It Li REQ_STRM_ST Streaming store requests. .It Li REQ_OTHER Any other request that crosses IDI, including I/O. .It Li RES_ANY Catch all value for any response types. .It Li RES_SUPPLIER_NO_SUPP No Supplier Information available. .It Li RES_SUPPLIER_LLC_HITM M-state initial lookup stat in L3. .It Li RES_SUPPLIER_LLC_HITE E-state. .It Li RES_SUPPLIER_LLC_HITS S-state. .It Li RES_SUPPLIER_LLC_HITF F-state. .It Li RES_SUPPLIER_LOCAL Local DRAM Controller. .It Li RES_SNOOP_SNP_NONE No details on snoop-related information. .It Li RES_SNOOP_SNP_NO_NEEDED No snoop was needed to satisfy the request. .It Li RES_SNOOP_SNP_MISS A snoop was needed and it missed all snooped caches: -For LLC Hit, ReslHitl was returned by all cores -For LLC Miss, Rspl was returned by all sockets and data was returned from DRAM. .It Li RES_SNOOP_HIT_NO_FWD A snoop was needed and it hits in at least one snooped cache. Hit denotes a cache-line was valid before snoop effect. This includes: -Snoop Hit w/ Invalidation (LLC Hit, RFO) -Snoop Hit, Left Shared (LLC Hit/Miss, IFetch/Data_RD) -Snoop Hit w/ Invalidation and No Forward (LLC Miss, RFO Hit S) In the LLC Miss case, data is returned from DRAM. .It Li RES_SNOOP_HIT_FWD A snoop was needed and data was forwarded from a remote socket. This includes: -Snoop Forward Clean, Left Shared (LLC Hit/Miss, IFetch/Data_RD/RFT). .It Li RES_SNOOP_HITM A snoop was needed and it HitM-ed in local or remote cache. HitM denotes a cache-line was in modified state before effect as a results of snoop. This includes: -Snoop HitM w/ WB (LLC miss, IFetch/Data_RD) -Snoop Forward Modified w/ Invalidation (LLC Hit/Miss, RFO) -Snoop MtoS (LLC Hit, IFetch/Data_RD). .It Li RES_NON_DRAM Target was non-DRAM system address. This includes MMIO transactions. .El .It Li cmask= Ns Ar value Configure the PMC to increment only if the number of configured events measured in a cycle is greater than or equal to .Ar value . .It Li edge Configure the PMC to count the number of de-asserted to asserted transitions of the conditions expressed by the other qualifiers. If specified, the counter will increment only once whenever a condition becomes true, irrespective of the number of clocks during which the condition remains true. .It Li inv Invert the sense of comparison when the .Dq Li cmask qualifier is present, making the counter increment when the number of events per cycle is less than the value specified by the .Dq Li cmask qualifier. .It Li os Configure the PMC to count events happening at processor privilege level 0. .It Li usr Configure the PMC to count events occurring at privilege levels 1, 2 or 3. .El .Pp If neither of the .Dq Li os or .Dq Li usr qualifiers are specified, the default is to enable both. .Ss Event Specifiers (Programmable PMCs) Sandy Bridge programmable PMCs support the following events: .Bl -tag -width indent .It Li LD_BLOCKS.DATA_UNKNOWN .Pq EVENT_03H, Umask 01H Blocked loads due to store buffer blocks with unknown data. .It Li LD_BLOCKS.STORE_FORWARD .Pq Event 03H, Umask 02H Loads blocked by overlapping with store buffer that cannot be forwarded. .It Li LD_BLOCKS.NO_SR .Pq Event 03H, Umask 08H # of Split loads blocked due to resource not available. .It Li LD_BLOCKS.ALL_BLOCK .Pq EVENT_03H, Umask 10H Number of cases where any load is blocked but has no DCU miss. .It Li MISALIGN_MEM_REF.LOADS .Pq Event 05H, Umask 01H Speculative cache-line split load uops dispatched to L1D. .It Li MISALIGN_MEM_REF.STORES .Pq Event 05H, Umask 02H Speculative cache-line split Store-address uops dispatched to L1D. .It Li LD_BLOCKS_PARTIAL.ADDRESS_ALIAS .Pq Event 07H, Umask 01H False dependencies in MOB due to partial compare on address. .It Li LD_BLOCKS_PARTIAL.ALL_STA_BLOCK .Pq Event 07H, Umask 08H The number of times that load operations are temporarily blocked because of older stores, with addresses that are not yet known. A load operation may incur more than one block of this type. .It LI DTLB_LOAD_MISSES.MISS_CAUSES_A_WALK .Pq Event 08H, Umask 01H Misses in all TLB levels that cause a page walk of any page size. .It Li DTLB_LOAD_MISSES.WALK_COMPLETED .Pq Event 08H, Umask 02H Misses in all TLB levels that caused page walk completed of any size. .It Li DTLB_LOAD_MISSES.WALK_DURATION .Pq Event 08H, Umask 04H Cycle PMH is busy with a walk. .It Li DTLB_LOAD_MISSES.STLB_HIT .Pq Event 08H, Umask 10H Number of cache load STLB hits. No page walk. .It Li INT_MISC.RECOVERY_CYCLES .Pq Event 0DH, Umask 03H Cycles waiting to recover after Machine Clears or JEClear. Set Cmask = 1. Set Edge to count occurrences .It Li INT_MISC.RAT_STALL_CYCLES .Pq Event 0DH, Umask 40H Cycles RAT external stall is sent to IDQ for this thread. .It Li UOPS_ISSUED.ANY .Pq Event 0EH, Umask 01H Increments each cycle the # of Uops issued by the RAT to RS. Set Cmask = 1, Inv = 1, Any= 1 to count stalled cycles of this core. Set Cmask = 1, Inv = 1 to count stalled cycles .It Li FP_COMP_OPS_EXE.X87 .Pq Event 10H, Umask 01H Counts number of X87 uops executed. .It Li FP_COMP_OPS_EXE.SSE_FP_PACKED_DOUBLE .Pq Event 10H, Umask 10H Counts number of SSE* double precision FP packed uops executed. .It Li FP_COMP_OPS_EXE.SSE_FP_SCALAR_SINGLE .Pq Event 10H, Umask 20H Counts number of SSE* single precision FP scalar uops executed. .It Li FP_COMP_OPS_EXE.SSE_PACKED_SINGLE .Pq Event 10H, Umask 40H Counts number of SSE* single precision FP packed uops executed. .It LiFP_COMP_OPS_EXE.SSE_SCALAR_DOUBLE .Pq Event 10H, Umask 80H Counts number of SSE* double precision FP scalar uops executed. .It Li SIMD_FP_256.PACKED_SINGLE .Pq Event 11H, Umask 01H Counts 256-bit packed single-precision floating-point instructions. .It Li SIMD_FP_256.PACKED_DOUBLE .Pq Event 11H, Umask 02H Counts 256-bit packed double-precision floating-point instructions. .It Li ARITH.FPU_DIV_ACTIVE .Pq Event 14H, Umask 01H Cycles that the divider is active, includes INT and FP. Set 'edge =1, cmask=1' to count the number of divides. .It Li INSTS_WRITTEN_TO_IQ.INSTS .Pq Event 17H, Umask 01H Counts the number of instructions written into the IQ every cycle. .It Li L2_RQSTS.DEMAND_DATA_RD_HIT .Pq Event 24H, Umask 01H Demand Data Read requests that hit L2 cache. .It Li L2_RQSTS.ALL_DEMAND_DATA_RD .Pq Event 24H, Umask 03H Counts any demand and L1 HW prefetch data load requests to L2. .It Li L2_RQSTS.RFO_HITS .Pq Event 24H, Umask 04H Counts the number of store RFO requests that hit the L2 cache. .It Li L2_RQSTS.RFO_MISS .Pq Event 24H, Umask 08H Counts the number of store RFO requests that miss the L2 cache. .It Li L2_RQSTS.ALL_RFO .Pq Event 24H, Umask 0CH Counts all L2 store RFO requests. .It Li L2_RQSTS.CODE_RD_HIT .Pq Event 24H, Umask 10H Number of instruction fetches that hit the L2 cache. .It Li L2_RQSTS.CODE_RD_MISS .Pq Event 24H, Umask 20H Number of instruction fetches that missed the L2 cache. .It Li L2_RQSTS.ALL_CODE_RD .Pq Event 24H, Umask 30H Counts all L2 code requests. .It Li L2_RQSTS.PF_HIT .Pq Event 24H, Umask 40H Requests from L2 Hardware prefetcher that hit L2. .It Li L2_RQSTS.PF_MISS .Pq Event 24H, Umask 80H Requests from L2 Hardware prefetcher that missed L2. .It Li L2_RQSTS.ALL_PF .Pq Event 24H, Umask C0H Any requests from L2 Hardware prefetchers. .It Li L2_STORE_LOCK_RQSTS.MISS .Pq Event 27H, Umask 01H RFOs that miss cache lines. .It Li L2_STORE_LOCK_RQSTS.HIT_E .Pq Event 27H, Umask 04H RFOs that hit cache lines in E state. .It Li L2_STORE_LOCK_RQSTS.HIT_M .Pq EVENT_27H, Umask 08H RFOs that hit cache lines in M state. .It Li L2_STORE_LOCK_RQSTS.ALL .Pq EVENT_27H, Umask 0FH RFOs that access cache lines in any state. .It Li L2_L1D_WB_RQSTS.HIT_E .Pq Event 28H, Umask 04H Not rejected writebacks from L1D to L2 cache lines in E state. .It Li L2_L1D_WB_RQSTS.HIT_M .Pq Event 28H, Umask 08H Not rejected writebacks from L1D to L2 cache lines in M state. .It Li LONGEST_LAT_CACHE.REFERENCE .Pq Event 2EH, Umask 4FH This event counts requests originating from the core that reference a cache line in the last level cache. .It Li LONGEST_LAT_CACHE.MISS .Pq Event 2EH, Umask 41H This event counts each cache miss condition for references to the last level cache. .It Li CPU_CLK_UNHALTED.THREAD_P .Pq Event 3CH, Umask 00H Counts the number of thread cycles while the thread is not in a halt state. The thread enters the halt state when it is running the HLT instruction. The core frequency may change from time to time due to power or thermal throttling. .It Li CPU_CLK_THREAD_UNHALTED.REF_XCLK .Pq Event 3CH, Umask 01H Increments at the frequency of XCLK (100 MHz) when not halted. .It Li L1D_PEND_MISS.PENDING .Pq Event 48H, Umask 01H Increments the number of outstanding L1D misses every cycle. Set Cmask = 1 and Edge =1 to count occurrences. Counter 2 only; Set Cmask = 1 to count cycles. .It Li DTLB_STORE_MISSES.MISS_CAUSES_A_WALK .Pq Event 49H, Umask 01H Miss in all TLB levels causes an page walk of any page size (4K/2M/4M/1G). .It Li DTLB_STORE_MISSES.WALK_COMPLETED .Pq Event 49H, Umask 02H Miss in all TLB levels causes a page walk that completes of any page size (4K/2M/4M/1G). .It Li DTLB_STORE_MISSES.WALK_DURATION .Pq Event 49H, Umask 04H Cycles PMH is busy with this walk. .It Li DTLB_STORE_MISSES.STLB_HIT .Pq Event 49H, Umask 10H Store operations that miss the first TLB level but hit the second and do not cause page walks. .It Li LOAD_HIT_PRE.SW_PF .Pq Event 4CH, Umask 01H Not SW-prefetch load dispatches that hit fill buffer allocated for S/W prefetch. .It Li LOAD_HIT_PER.HW_PF .Pq Event 4CH, Umask 02H Not SW-prefetch load dispatches that hit fill buffer allocated for H/W prefetch. .It Li HW_PRE_REQ.DL1_MISS .Pq Event 4EH, Umask 02H Hardware Prefetch requests that miss the L1D cache. A request is being counted each time it access the cache & miss it, including if a block is applicable or if hit the Fill Buffer for example. This accounts for both L1 streamer and IP-based (IPP) HW prefetchers. .It Li L1D.REPLACEMENT .Pq Event 51H, Umask 01H Counts the number of lines brought into the L1 data cache. .It Li L1D.ALLOCATED_IN_M .Pq Event 51H, Umask 02H Counts the number of allocations of modified L1D cache lines. .It Li L1D.EVICTION .Pq Event 51H, Umask 04H Counts the number of modified lines evicted from the L1 data cache due to replacement. .It Li L1D.ALL_M_REPLACEMENT .Pq Event 51H, Umask 08H Cache lines in M state evicted out of L1D due to Snoop HitM or dirty line replacement. .It Li PARTIAL_RAT_STALLS.FLAGS_MERGE_UOP .Pq Event 59H, Umask 20H Increments the number of flags-merge uops in flight each cycle. Set Cmask = 1 to count cycles. .It Li PARTIAL_RAT_STALLS.SLOW_LEA_WINDOW .Pq Event 59H, Umask 40H Cycles with at least one slow LEA uop allocated. .It Li PARTIAL_RAT_STALLS.MUL_SINGLE_UOP .Pq Event 59H, Umask 80H Number of Multiply packed/scalar single precision uops allocated. .It Li RESOURCE_STALLS2.ALL_FL_EMPTY .Pq Event 5BH, Umask 0CH Cycles stalled due to free list empty. .It Li RESOURCE_STALLS2.ALL_PRF_CONTROL .Pq Event 5BH, Umask 0FH Cycles stalled due to control structures full for physical registers. .It Li RESOURCE_STALLS2.BOB_FULL .Pq Event 5BH, Umask 40H Cycles Allocator is stalled due to Branch Order Buffer. .It Li RESOURCE_STALLS2.OOO_RSRC .Pq Event 5BH, Umask 4FH Cycles stalled due to out of order resources full. .It Li CPL_CYCLES.RING0 .Pq Event 5CH, Umask 01H Unhalted core cycles when the thread is in ring 0. Use Edge to count transition .It Li CPL_CYCLES.RING123 .Pq Event 5CH, Umask 02H Unhalted core cycles when the thread is not in ring 0. .It Li RS_EVENTS.EMPTY_CYCLES .Pq Event 5EH, Umask 01H Cycles the RS is empty for the thread. .It Li OFFCORE_REQUESTS_OUTSTANDING.DEMAND_DATA_RD .Pq Event 60H, Umask 01H Offcore outstanding Demand Data Read transactions in SQ to uncore. Set Cmask=1 to count cycles. .It Li OFFCORE_REQUESTS_OUTSTANDING.DEMAND_RFO .Pq Event 60H, Umask 04H Offcore outstanding RFO store transactions in SQ to uncore. Set Cmask=1 to count cycles. .It Li OFFCORE_REQUESTS_OUTSTANDING.ALL_DATA_RD .Pq Event 60H, Umask 08H Offcore outstanding cacheable data read transactions in SQ to uncore. Set Cmask=1 to count cycles. .It Li LOCK_CYCLES.SPLIT_LOCK_UC_LOCK_DURATION .Pq Event 63H, Umask 01H Cycles in which the L1D and L2 are locked, due to a UC lock or split lock. .It Li LOCK_CYCLES.CACHE_LOCK_DURATION .Pq Event 63H, Umask 02H Cycles in which the L1D is locked. .It Li IDQ.EMPTY .Pq Event 79H, Umask 02H Counts cycles the IDQ is empty. .It Li IQD.MITE_UOPS .Pq Event 79H, Umask 04H Increment each cycle # of uops delivered to IDQ from MITE path. Set Cmask = 1 to count cycles. Can combine Umask 04H and 20H .It Li IDQ.DSB_UOPS .Pq Event 79H, Umask 08H Increment each cycle. # of uops delivered to IDQ from DSB path. Set Cmask = 1 to count cycles. Can combine Umask 08H and 10H .It Li IDQ.MS_DSB_UOPS .Pq Event 79H, Umask 10H Increment each cycle # of uops delivered to IDQ when MS busy by DSB. Set Cmask = 1 to count cycles MS is busy. Set Cmask=1 and Edge=1 to count MS activations. Can combine Umask 08H and 10H .It Li IDQ.MS_MITE_UOPS .Pq Event 79H, Umask 20H Increment each cycle # of uops delivered to IDQ when MS is busy by MITE. Set Cmask = 1 to count cycles. Can combine Umask 04H and 20H .It Li IDQ.MS_UOPS .Pq Event 79H, Umask 30H Increment each cycle # of uops delivered to IDQ from MS by either DSB or MITE. Set Cmask = 1 to count cycles. Can combine Umask 04H, 08H and 30H .It Li ICACHE.MISSES .Pq Event 80H, Umask 02H Number of Instruction Cache, Streaming Buffer and Victim Cache Misses. Includes UC accesses. .It Li ITLB_MISSES.MISS_CAUSES_A_WALK .Pq Event 85H, Umask 01H Misses in all ITLB levels that cause page walks. .It Li ITLB_MISSES.WALK_COMPLETED .Pq Event 85H, Umask 02H Misses in all ITLB levels that cause completed page walks. .It Li ITLB_MISSES.WALK_DURATION .Pq Event 85H, Umask 04H Cycle PMH is busy with a walk. .It Li ITLB_MISSES.STLB_HIT .Pq Event 85H, Umask 10H Number of cache load STLB hits. No page walk. .It Li ILD_STALL.LCP .Pq Event 87H, Umask 01H Stalls caused by changing prefix length of the instruction. .It Li ILD_STALL.IQ_FULL .Pq Event 87H, Umask 04H Stall cycles due to IQ is full. .It Li BR_INST_EXEC.NONTAKEN_COND .Pq Event 88H , Umask 41H Count conditional near branch instructions that were executed (but not necessarily retired) and not taken. .It Li BR_INST_EXEC.TAKEN_COND .Pq Event 88H , Umask 81H Count conditional near branch instructions that were executed (but not necessarily retired) and taken. .It Li BR_INST_EXEC.DIRECT_JMP .Pq Event 88H , Umask 82H Count all unconditional near branch instructions excluding calls and indirect branches. .It Li BR_INST_EXEC.INDIRECT_JMP_NON_CALL_RET .Pq Event 88H , Umask 84H Count executed indirect near branch instructions that are not calls nor returns. .It Li BR_INST_EXEC.RETURN_NEAR .Pq Event 88H , Umask 88H Count indirect near branches that have a return mnemonic. .It Li BR_INST_EXEC.DIRECT_NEAR_CALL .Pq Event 88H , Umask 90H Count unconditional near call branch instructions, excluding non call branch, executed. .It Li BR_INST_EXEC.INDIRECT_NEAR_CALL .Pq Event 88H , Umask A0H Count indirect near calls, including both register and memory indirect, executed. .It Li BR_INST_EXEC.ALL_BRANCHES .Pq Event 88H , Umask FFH Counts all near executed branches (not necessarily retired). .It Li BR_MISP_EXEC.NONTAKEN_COND .Pq Event 89H , Umask 41H Count conditional near branch instructions mispredicted as nontaken. .It Li BR_MISP_EXEC.TAKEN_COND .Pq Event 89H , Umask 81H Count conditional near branch instructions mispredicted as taken. .It Li BR_MISP_EXEC.INDIRECT_JMP_NON_CALL_RET .Pq Event 89H , Umask 84H Count mispredicted indirect near branch instructions that are not calls nor returns. .It Li BR_MISP_EXEC.RETURN_NEAR .Pq Event 89H , Umask 88H Count mispredicted indirect near branches that have a return mnemonic. .It Li BR_MISP_EXEC.DIRECT_NEAR_CALL .Pq Event 89H , Umask 90H Count mispredicted unconditional near call branch instructions, excluding non call branch, executed. .It Li BR_MISP_EXEC.INDIRECT_NEAR_CALL .Pq Event 89H , Umask A0H Count mispredicted indirect near calls, including both register and memory indirect, executed. .It Li BR_MISP_EXEC.ALL_BRANCHES .Pq Event 89H , Umask FFH Counts all mispredicted near executed branches (not necessarily retired). .It Li IDQ_UOPS_NOT_DELIVERED.CORE .Pq Event 9CH, Umask 01H Count number of non-delivered uops to RAT per thread. Use Cmask to qualify uop b/w .It Li UOPS_DISPATCHED_PORT.PORT_0 .Pq Event A1H, Umask 01H Cycles which a Uop is dispatched on port 0. .It Li UOPS_DISPATCHED_PORT.PORT_1 .Pq Event A1H, Umask 02H Cycles which a Uop is dispatched on port 1. .It Li UOPS_DISPATCHED_PORT.PORT_2_LD .Pq Event A1H, Umask 04H Cycles which a load uop is dispatched on port 2. .It Li UOPS_DISPATCHED_PORT.PORT_2_STA .Pq Event A1H, Umask 08H Cycles which a store address uop is dispatched on port 2. .It Li UOPS_DISPATCHED_PORT.PORT_2 .Pq Event A1H, Umask 0CH Cycles which a Uop is dispatched on port 2. .It Li UOPS_DISPATCHED_PORT.PORT_3_LD .Pq Event A1H, Umask 10H Cycles which a load uop is dispatched on port 3. .It Li UOPS_DISPATCHED_PORT.PORT_3_STA .Pq Event A1H, Umask 20H Cycles which a store address uop is dispatched on port 3. .It Li UOPS_DISPATCHED_PORT.PORT_3 .Pq Event A1H, Umask 30H .Pq Cycles which a Uop is dispatched on port 3. .It Li UOPS_DISPATCHED_PORT.PORT_4 .Pq Event A1H, Umask 40H Cycles which a Uop is dispatched on port 4. .It Li UOPS_DISPATCHED_PORT.PORT_5 .Pq Event A1H, Umask 80H Cycles which a Uop is dispatched on port 5. .It Li RESOURCE_STALLS.ANY .Pq Event A2H, Umask 01H Cycles Allocation is stalled due to Resource Related reason. .It Li RESOURCE_STALLS.LB .Pq Event A2H, Umask 02H Counts the cycles of stall due to lack of load buffers. .It Li RESOURCE_STALLS.LB .Pq Event A2H, Umask 04H Cycles stalled due to no eligible RS entry available. .It Li RESOURCE_STALLS.SB .Pq Event A2H, Umask 08H Cycles stalled due to no store buffers available. (not including draining form sync) .It Li RESOURCE_STALLS.ROB .Pq Event A2H, Umask 10H Cycles stalled due to re-order buffer full. .It Li RESOURCE_STALLS.FCSW .Pq Event A2H, Umask 20H Cycles stalled due to writing the FPU control word. .It Li RESOURCE_STALLS.MXCSR .Pq Event A2H, Umask 40H Cycles stalled due to the MXCSR register rename occurring to close to a previous MXCSR rename. .It Li RESOURCE_STALLS.OTHER .Pq Event A2H, Umask 80H Cycles stalled while execution was stalled due to other resource issues. .It Li DSB2MITE_SWITCHES.COUNT .Pq Event ABH, Umask 01H Number of DSB to MITE switches. .It Li DSB2MITE_SWITCHES.PENALTY_CYCLES .Pq Event ABH, Umask 02H Cycles DSB to MITE switches caused delay. .It Li DSB_FILL.OTHER_CANCEL .Pq Event ACH, Umask 02H Cases of cancelling valid DSB fill not because of exceeding way limit. .It Li DSB_FILL.EXCEED_DSB_LINES .Pq Event ACH, Umask 08H DSB Fill encountered > 3 DSB lines. .It Li DSB_FILL.ALL_CANCEL .Pq Event ACH, Umask 0AH Cases of cancelling valid Decode Stream Buffer (DSB) fill not because of exceeding way limit. .It Li ITLB.ITLB_FLUSH .Pq Event AEH, Umask 01H Counts the number of ITLB flushes, includes 4k/2M/4M pages. .It Li OFFCORE_REQUESTS.DEMAND_DATA_RD .Pq Event B0H, Umask 01H Demand data read requests sent to uncore. .It Li OFFCORE_REQUESTS.DEMAND_RFO .Pq Event B0H, Umask 04H Demand RFO read requests sent to uncore, including regular RFOs, locks, ItoM. .It Li OFFCORE_REQUESTS.ALL_DATA_RD .Pq Event B0H, Umask 08H Data read requests sent to uncore (demand and prefetch). .It Li UOPS_DISPATCHED.THREAD .Pq Event B1H, Umask 01H Counts total number of uops to be dispatched per-thread each cycle. Set Cmask = 1, INV =1 to count stall cycles. .It Li UOPS_DISPATCHED.CORE .Pq Event B1H, Umask 02H Counts total number of uops to be dispatched per-core each cycle. Do not need to set ANY .It Li OFFCORE_REQUESTS_BUFFER.SQ_FULL .Pq Event B2H, Umask 01H Offcore requests buffer cannot take more entries for this thread core. .It Li AGU_BYPASS_CANCEL.COUNT .Pq Event B6H, Umask 01H Counts executed load operations with all the following traits: 1. addressing of the format [base + offset], 2. the offset is between 1 and 2047, 3. the address specified in the base register is in one page and the address [base+offset] is in another page. .It Li OFF_CORE_RESPONSE_0 .Pq Event B7H, Umask 01H Off-core Response Performance Monitoring; PMC0 only. Requires programming MSR 01A6H .It Li OFF_CORE_RESPONSE_1 .Pq Event BBH, Umask 01H Off-core Response Performance Monitoring. PMC3 only. Requires programming MSR 01A7H .It Li TLB_FLUSH.DTLB_THREAD .Pq Event BDH, Umask 01H DTLB flush attempts of the thread-specific entries. .It Li TLB_FLUSH.STLB_ANY .Pq Event BDH, Umask 20H Count number of STLB flush attempts. .It Li L1D_BLOCKS.BANK_CONFLICT_CYCLES .Pq Event BFH, Umask 05H Cycles when dispatched loads are cancelled due to L1D bank conflicts with other load ports. cmask=1 .It Li INST_RETIRED.ANY_P .Pq Event C0H, Umask 00H Number of instructions at retirement. .It Li INST_RETIRED.PREC_DIST .Pq Event C0H, Umask 01H Precise instruction retired event with HW to reduce effect of PEBS shadow in IP distribution PMC1 only; Must quiesce other PMCs. .It Li INST_RETIRED.X87 .Pq Event C0H, Umask 02H X87 instruction retired event. .It Li OTHER_ASSISTS.ITLB_MISS_RETIRED .Pq Event C1H, Umask 02H Instructions that experienced an ITLB miss. .It Li OTHER_ASSISTS.AVX_STORE .Pq Event C1H, Umask 08H Number of assists associated with 256-bit AVX store operations. .It Li OTHER_ASSISTS.AVX_TO_SSE .Pq Event C1H, Umask 10H Number of transitions from AVX256 to legacy SSE when penalty applicable. .It Li OTHER_ASSISTS.SSE_TO_AVX .Pq Event C1H, Umask 20H Number of transitions from SSE to AVX-256 when penalty applicable. .It Li UOPS_RETIRED.ALL .Pq Event C2H, Umask 01H Counts the number of micro-ops retired. Use cmask=1 and invert to count active cycles or stalled cycles. .It Li UOPS_RETIRED.RETIRE_SLOTS .Pq Event C2H, Umask 02H Counts the number of retirement slots used each cycle. .It Li MACHINE_CLEARS.MEMORY_ORDERING .Pq Event C3H, Umask 02H Counts the number of machine clears due to memory order conflicts. .It Li MACHINE_CLEARS.SMC .Pq Event C3H, Umask 04H Counts the number of times that a program writes to a code section. .It Li MACHINE_CLEARS.MASKMOV .Pq Event C3H, Umask 20H Counts the number of executed AVX masked load operations that refer to an illegal address range with the mask bits set to 0. .It Li BR_INST_RETIRED.ALL_BRANCH .Pq Event C4H, Umask 00H Branch instructions at retirement. .It Li BR_INST_RETIRED.CONDITIONAL .Pq Event C4H, Umask 01H Counts the number of conditional branch instructions retired. .It Li BR_INST_RETIRED.NEAR_CALL .Pq Event C4H, Umask 02H Direct and indirect near call instructions retired. .It Li BR_INST_RETIRED.ALL_BRANCHES .Pq Event C4H, Umask 04H Counts the number of branch instructions retired. .It Li BR_INST_RETIRED.NEAR_RETURN .Pq Event C4H, Umask 08H Counts the number of near return instructions retired. .It Li BR_INST_RETIRED.NOT_TAKEN .Pq Event C4H, Umask 10H Counts the number of not taken branch instructions retired. .It Li BR_INST_RETIRED.NEAR_TAKEN .Pq Event C4H, Umask 20H Number of near taken branches retired. .It Li BR_INST_RETIRED.FAR_BRANCH .Pq Event C4H, Umask 40H Number of far branches retired. .It Li BR_MISP_RETIRED.ALL_BRANCHES .Pq Event C5H, Umask 00H Mispredicted branch instructions at retirement. .It Li BR_MISP_RETIRED.CONDITIONAL .Pq Event C5H, Umask 01H Mispredicted conditional branch instructions retired. .It Li BR_MISP_RETIRED.NEAR_CALL .Pq Event C5H, Umask 02H Direct and indirect mispredicted near call instructions retired. .It Li BR_MISP_RETIRED.ALL_BRANCH .Pq Event C5H, Umask 04H Mispredicted macro branch instructions retired. .It Li BR_MISP_RETIRED.NOT_TAKEN .Pq Event C5H, Umask 10H Mispredicted not taken branch instructions retired. .It Li BR_MISP_RETIRED.TAKEN .Pq Event C5H, Umask 20H Mispredicted taken branch instructions retired. .It Li FP_ASSIST.X87_OUTPUT .Pq Event CAH, Umask 02H Number of X87 assists due to output value. .It Li FP_ASSIST.X87_INPUT .Pq Event CAH, Umask 04H Number of X87 assists due to input value. .It Li FP_ASSIST.SIMD_OUTPUT .Pq Event CAH, Umask 08H Number of SIMD FP assists due to Output values. .It Li FP_ASSIST.SIMD_INPUT .Pq Event CAH, Umask 10H Number of SIMD FP assists due to input values. .It Li FP_ASSIST.ANY .Pq Event CAH, Umask 1EH Cycles with any input/output SSE* or FP assists. .It Li ROB_MISC_EVENTS.LBR_INSERTS .Pq Event CCH, Umask 20H Count cases of saving new LBR records by hardware. .It Li MEM_TRANS_RETIRED.LOAD_LATENCY .Pq Event CDH, Umask 01H Sample loads with specified latency threshold. PMC3 only. Specify threshold in MSR 0x3F6. .It Li MEM_TRANS_RETIRED.PRECISE_STORE .Pq Event CDH, Umask 02H Sample stores and collect precise store operation via PEBS record. PMC3 only. .It Li MEM_UOP_RETIRED.LOADS .Pq Event D0H, Umask 01H Qualify retired memory uops that are loads. Combine with umask 10H, 20H, 40H, 80H. .It Li MEM_UOP_RETIRED.STORES .Pq Event D0H, Umask 02H Qualify retired memory uops that are stores. Combine with umask 10H, 20H, 40H, 80H. .It Li MEM_UOP_RETIRED.STLB_MISS .Pq Event D0H, Umask 10H Qualify retired memory uops with STLB miss. Must combine with umask 01H, 02H, to produce counts. .It Li MEM_UOP_RETIRED.LOCK .Pq Event D0H, Umask 20H Qualify retired memory uops with lock. Must combine with umask 01H, 02H, to produce counts. .It Li MEM_UOP_RETIRED.SPLIT .Pq Event D0H, Umask 40H Qualify retired memory uops with line split. Must combine with umask 01H, 02H, to produce counts. .It Li MEM_UOP_RETIRED_ALL .Pq Event D0H, Umask 80H Qualify any retired memory uops. Must combine with umask 01H, 02H, to produce counts. .It Li MEM_LOAD_UOPS_RETIRED.L1_HIT .Pq Event D1H, Umask 01H Retired load uops with L1 cache hits as data sources. Must combine with umask 01H, 02H, to produce counts. .It Li MEM_LOAD_UOPS_RETIRED.L2_HIT .Pq Event D1H, Umask 02H Retired load uops with L2 cache hits as data sources. .It Li MEM_LOAD_UOPS_RETIRED.LLC_HIT .Pq Event D1H, Umask 04H Retired load uops which data sources were data hits in LLC without snoops required. .It Li MEM_LOAD_UOPS_RETIRED.HIT_LFB .Pq Event D1H, Umask 40H Retired load uops which data sources were load uops missed L1 but hit FB due to preceding miss to the same cache line with data not ready. .It Li MEM_LOAD_UOPS_LLC_HIT_RETIRED.XSNP_MISS .Pq Event D2H, Umask 01H Retired load uops which data sources were LLC hit and cross-core snoop missed in on-pkg core cache. .It Li MEM_LOAD_UOPS_LLC_HIT_RETIRED.XSNP_HIT .Pq Event D2H, Umask 02H Retired load uops which data sources were LLC and cross-core snoop hits in on-pkg core cache. .It Li MEM_LOAD_UOPS_LLC_HIT_RETIRED.XSNP_HITM .Pq Event D2H, Umask 04H Retired load uops which data sources were HitM responses from shared LLC. .It Li MEM_LOAD_UOPS_LLC_HIT_RETIRED.XSNP_NONE .Pq Event D2H, Umask 08H Retired load uops which data sources were hits in LLC without snoops required. .It Li MEM_LOAD_UOPS_LLC_HIT_RETIRED.LLC_MISS .Pq Event D4H, Umask 02H Retired load uops with unknown information as data source in cache serviced the load. .It Li L2_TRANS.DEMAND_DATA_RD .Pq Event F0H, Umask 01H Demand Data Read requests that access L2 cache. .It Li L2_TRANS.RF0 .Pq Event F0H, Umask 02H RFO requests that access L2 cache. .It Li L2_TRANS.CODE_RD .Pq Event F0H, Umask 04H L2 cache accesses when fetching instructions. .It Li L2_TRANS.ALL_PF .Pq Event F0H, Umask 08H L2 or LLC HW prefetches that access L2 cache. .It Li L2_TRANS.L1D_WB .Pq Event F0H, Umask 10H L1D writebacks that access L2 cache. .It Li L2_TRANS.L2_FILL .Pq Event F0H, Umask 20H L2 fill requests that access L2 cache. .It Li L2_TRANS.L2_WB .Pq Event F0H, Umask 40H L2 writebacks that access L2 cache. .It Li L2_TRANS.ALL_REQUESTS .Pq Event F0H, Umask 80H Transactions accessing L2 pipe. .It Li L2_LINES_IN.I .Pq Event F1H, Umask 01H L2 cache lines in I state filling L2. Counting does not cover rejects. .It Li L2_LINES_IN.S .Pq Event F1H, Umask 02H L2 cache lines in S state filling L2. Counting does not cover rejects. .It Li L2_LINES_IN.E .Pq Event F1H, Umask 04H L2 cache lines in E state filling L2. Counting does not cover rejects. .It Li L2_LINES-IN.ALL .Pq Event F1H, Umask 07H L2 cache lines filling L2. Counting does not cover rejects. .It Li L2_LINES_OUT.DEMAND_CLEAN .Pq Event F2H, Umask 01H Clean L2 cache lines evicted by demand. .It Li L2_LINES_OUT.DEMAND_DIRTY .Pq Event F2H, Umask 02H Dirty L2 cache lines evicted by demand. .It Li L2_LINES_OUT.PF_CLEAN .Pq Event F2H, Umask 04H Clean L2 cache lines evicted by L2 prefetch. .It Li L2_LINES_OUT.PF_DIRTY .Pq Event F2H, Umask 08H Dirty L2 cache lines evicted by L2 prefetch. .It Li L2_LINES_OUT.DIRTY_ALL .Pq Event F2H, Umask 0AH Dirty L2 cache lines filling the L2. Counting does not cover rejects. .It Li SQ_MISC.SPLIT_LOCK .Pq Event F4H, Umask 10H Split locks in SQ. .El .Sh SEE ALSO .Xr pmc 3 , .Xr pmc.atom 3 , .Xr pmc.core 3 , .Xr pmc.corei7 3 , .Xr pmc.corei7uc 3 , .Xr pmc.iaf 3 , .Xr pmc.ivybridge 3 , .Xr pmc.ivybridgexeon 3 , .Xr pmc.k7 3 , .Xr pmc.k8 3 , .Xr pmc.p4 3 , .Xr pmc.p5 3 , .Xr pmc.p6 3 , .Xr pmc.sandybridgeuc 3 , .Xr pmc.sandybridgexeon 3 , .Xr pmc.soft 3 , .Xr pmc.tsc 3 , .Xr pmc.ucf 3 , .Xr pmc.westmere 3 , .Xr pmc.westmereuc 3 , .Xr pmc_cpuinfo 3 , .Xr pmclog 3 , .Xr hwpmc 4 .Sh HISTORY The .Nm pmc library first appeared in .Fx 6.0 . .Sh AUTHORS .An -nosplit The .Lb libpmc library was written by .An Joseph Koshy Aq Mt jkoshy@FreeBSD.org . The support for the Sandy Bridge microarchitecture was written by .An Davide Italiano Aq Mt davide@FreeBSD.org . Index: head/lib/libpmc/pmc.sandybridgeuc.3 =================================================================== --- head/lib/libpmc/pmc.sandybridgeuc.3 (revision 366582) +++ head/lib/libpmc/pmc.sandybridgeuc.3 (revision 366583) @@ -1,233 +1,233 @@ -.\" Copyright (c) 2012 Davide Italiano +.\" Copyright (c) 2012 Davide Italiano .\" 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 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. .\" .\" $FreeBSD$ .\" .Dd October 19, 2012 .Dt PMC.SANDYBRIDGEUC 3 .Os .Sh NAME .Nm pmc.sandybridgeuc .Nd uncore measurement events for .Tn Intel .Tn Sandy Bridge family CPUs .Sh LIBRARY .Lb libpmc .Sh SYNOPSIS .In pmc.h .Sh DESCRIPTION .Tn Intel .Tn "Sandy Bridge" CPUs contain PMCs conforming to version 3 of the .Tn Intel performance measurement architecture. These CPUs contain two classes of PMCs: .Bl -tag -width "Li PMC_CLASS_UCP" .It Li PMC_CLASS_UCF Fixed-function counters that count only one hardware event per counter. .It Li PMC_CLASS_UCP Programmable counters that may be configured to count one of a defined set of hardware events. .El .Pp The number of PMCs available in each class and their widths need to be determined at run time by calling .Xr pmc_cpuinfo 3 . .Pp Intel Sandy Bridge PMCs are documented in .Rs .%B "Intel(R) 64 and IA-32 Architectures Software Developers Manual" .%T "Volume 3B: System Programming Guide, Part 2" .%N "Order Number: 253669-039US" .%D May 2011 .%Q "Intel Corporation" .Re .Ss SANDYBRIDGE UNCORE FIXED FUNCTION PMCS These PMCs and their supported events are documented in .Xr pmc.ucf 3 . Not all CPUs in this family implement fixed-function counters. .Ss SANDYBRIDGE UNCORE PROGRAMMABLE PMCS The programmable PMCs support the following capabilities: .Bl -column "PMC_CAP_INTERRUPT" "Support" .It Em Capability Ta Em Support .It PMC_CAP_CASCADE Ta \&No .It PMC_CAP_EDGE Ta Yes .It PMC_CAP_INTERRUPT Ta \&No .It PMC_CAP_INVERT Ta Yes .It PMC_CAP_READ Ta Yes .It PMC_CAP_PRECISE Ta \&No .It PMC_CAP_SYSTEM Ta \&No .It PMC_CAP_TAGGING Ta \&No .It PMC_CAP_THRESHOLD Ta Yes .It PMC_CAP_USER Ta \&No .It PMC_CAP_WRITE Ta Yes .El .Ss Event Qualifiers Event specifiers for these PMCs support the following common qualifiers: .Bl -tag -width indent .It Li cmask= Ns Ar value Configure the PMC to increment only if the number of configured events measured in a cycle is greater than or equal to .Ar value . .It Li edge Configure the PMC to count the number of de-asserted to asserted transitions of the conditions expressed by the other qualifiers. If specified, the counter will increment only once whenever a condition becomes true, irrespective of the number of clocks during which the condition remains true. .It Li inv Invert the sense of comparison when the .Dq Li cmask qualifier is present, making the counter increment when the number of events per cycle is less than the value specified by the .Dq Li cmask qualifier. .El .Ss Event Specifiers (Programmable PMCs) Sandy Bridge programmable PMCs support the following events: .Bl -tag -width indent .It Li CBO_XSNP_RESPONSE.RSPIHITI .Pq Event 22H, Umask 01H Snoop responses received from processor cores to requests initiated by this Cbox. Must combine with one of the umask values of 20H, 40H, 80H .It Li CBO_XSNP_RESPONSE.RSPIHITFSE .Pq Event 22H, Umask 02H Must combine with one of the umask values of 20H, 40H, 80H .It Li CBO_XSNP_RESPONSE.RSPSHITFSE .Pq Event 22H, Umask 04H Must combine with one of the umask values of 20H, 40H, 80H .It Li CBO_XSNP_RESPONSE.RSPSFWDM .Pq Event 22H, Umask 08H .It Li CBO_XSNP_RESPONSE.RSPIFWDM .Pq Event 22H, Umask 01H .It Li CBO_XSNP_RESPONSE.AND_EXTERNAL .Pq Event 22H, Umask 20H Filter on cross-core snoops resulted in external snoop request. Must combine with at least one of 01H, 02H, 04H, 08H, 10H .It Li CBO_XSNP_RESPONSE.AND_XCORE .Pq Event 22H, Umask 40H Filter on cross-core snoops resulted in core request. Must combine with at least one of 01H, 02H, 04H, 08H, 10H .It Li CBO_XSNP_RESPONSE.AND_XCORE .Pq Event 22H, Umask 80H Filter on cross-core snoops resulted in LLC evictions. Must combine with at least one of 01H, 02H, 04H, 08H, 10H .It Li CBO_CACHE_LOOKUP.M .Pq Event 34H, Umask 01H LLC lookup request that access cache and found line in M-state. Must combine with one of the umask values of 10H, 20H, 40H, 80H .It Li CBO_CACHE_LOOKUP.E .Pq Event 34H, Umask 02H LLC lookup request that access cache and found line in E-state. Must combine with one of the umask values of 10H, 20H, 40H, 80H .It Li CBO_CACHE_LOOKUP.S .Pq Event 34H, Umask 04H LLC lookup request that access cache and found line in S-state. Must combine with one of the umask values of 10H, 20H, 40H, 80H .It Li CBO_CACHE_LOOKUP.I .Pq Event 34H, Umask 08H LLC lookup request that access cache and found line in I-state. Must combine with one of the umask values of 10H, 20H, 40H, 80H .It Li CBO_CACHE_LOOKUP.AND_READ .Pq Event 34H, Umask 10H Filter on processor core initiated cacheable read requests. Must combine with at least one of 01H, 02H, 04H, 08H .It Li CBO_CACHE_LOOKUP_AND_READ2 .Pq Event 34H, Umask 20H Filter on processor core initiated cacheable write requests. Must combine with at least one of 01H, 02H, 04H, 08H .It Li CBO_CACHE_LOOKUP.AND_EXTSNP .Pq Event 34H, Umask 40H Filter on external snoop requests. Must combine with at least one of 01H, 02H, 04H, 08H .It Li CBO_CACHE_LOOKUP.AND_ANY .Pq Event 34H, Umask 80H Filter on any IRQ or IPQ initiated requests including uncacheable, noncoherent requests. Must combine with at least one of 01H, 02H, 04H, 08H .It Li IMPH_CBO_TRK_OCCUPANCY.ALL .Pq Event 80H, Umask 01H Counts cycles weighted by the number of core-outgoing valid entries. Valid entries are between allocation to the first of IDIO or DRSO messages. Accounts for coherent and incoherent traffic. Counter 0 only .It Li IMPH_CBO_TRK_REQUEST.ALL .Pq Event 81H, Umask 01H Counts the number of core-outgoing entries. Accounts for coherent and incoherent traffic. .It Li IMPH_CBO_TRK_REQUEST.WRITES .Pq Event 81H, Umask 20H Counts the number of allocated write entries, include full, partial, and evictions. .It Li IMPH_CBO_TRK_REQUEST.EVICTIONS .Pq Event 81H, Umask 80H Counts the number of evictions allocated. .It Li IMPH_COH_TRK_OCCUPANCY.ALL .Pq Event 83H, Umask 01H Counts cycles weighted by the number of core-outgoing valid entries in the coherent tracker queue. Counter 0 only .It Li IMPH_COH_TRK_REQUEST.ALL .Pq Event 84H, Umask 01H Counts the number of core-outgoing entries in the coherent tracker queue. .El .Sh SEE ALSO .Xr pmc 3 , .Xr pmc.atom 3 , .Xr pmc.core 3 , .Xr pmc.corei7 3 , .Xr pmc.corei7uc 3 , .Xr pmc.iaf 3 , .Xr pmc.k7 3 , .Xr pmc.k8 3 , .Xr pmc.p4 3 , .Xr pmc.p5 3 , .Xr pmc.p6 3 , .Xr pmc.sandybridge 3 , .Xr pmc.sandybridgexeon 3 , .Xr pmc.soft 3 , .Xr pmc.tsc 3 , .Xr pmc.ucf 3 , .Xr pmc.westmere 3 , .Xr pmc.westmereuc 3 , .Xr pmc_cpuinfo 3 , .Xr pmclog 3 , .Xr hwpmc 4 .Sh HISTORY The .Nm pmc library first appeared in .Fx 6.0 . .Sh AUTHORS .An -nosplit The .Lb libpmc library was written by .An Joseph Koshy Aq Mt jkoshy@FreeBSD.org . The support for the Sandy Bridge microarchitecture was added by .An Davide Italiano Aq Mt davide@FreeBSD.org . Index: head/lib/libradius/libradius.3 =================================================================== --- head/lib/libradius/libradius.3 (revision 366582) +++ head/lib/libradius/libradius.3 (revision 366583) @@ -1,614 +1,615 @@ .\" Copyright 1998 Juniper Networks, Inc. .\" Copyright 2009 Alexander Motin . .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd August 5, 2009 .Dt LIBRADIUS 3 .Os .Sh NAME .Nm libradius .Nd RADIUS client/server library .Sh SYNOPSIS .In radlib.h .Ft "struct rad_handle *" .Fn rad_acct_open "void" .Ft int .Fn rad_add_server "struct rad_handle *h" "const char *host" "int port" "const char *secret" "int timeout" "int max_tries" .Ft int .Fn rad_add_server_ex "struct rad_handle *h" "const char *host" "int port" "const char *secret" "int timeout" "int max_tries" "int dead_time" "struct in_addr *bindto" .Ft "struct rad_handle *" .Fn rad_auth_open "void" .Ft void .Fn rad_close "struct rad_handle *h" .Ft int .Fn rad_config "struct rad_handle *h" "const char *file" .Ft int .Fn rad_continue_send_request "struct rad_handle *h" "int selected" "int *fd" "struct timeval *tv" .Ft int .Fn rad_create_request "struct rad_handle *h" "int code" .Ft int .Fn rad_create_response "struct rad_handle *h" "int code" .Ft "struct in_addr" .Fn rad_cvt_addr "const void *data" .Ft uint32_t .Fn rad_cvt_int "const void *data" .Ft char * .Fn rad_cvt_string "const void *data" "size_t len" .Ft int .Fn rad_get_attr "struct rad_handle *h" "const void **data" "size_t *len" .Ft int .Fn rad_get_vendor_attr "uint32_t *vendor" "const void **data" "size_t *len" .Ft int .Fn rad_init_send_request "struct rad_handle *h" "int *fd" "struct timeval *tv" .Ft int .Fn rad_put_addr "struct rad_handle *h" "int type" "struct in_addr addr" .Ft int .Fn rad_put_attr "struct rad_handle *h" "int type" "const void *data" "size_t len" .Ft int .Fn rad_put_int "struct rad_handle *h" "int type" "uint32_t value" .Ft int .Fn rad_put_string "struct rad_handle *h" "int type" "const char *str" .Ft int .Fn rad_put_message_authentic "struct rad_handle *h" .Ft int .Fn rad_put_vendor_addr "struct rad_handle *h" "int vendor" "int type" "struct in_addr addr" .Ft int .Fn rad_put_vendor_attr "struct rad_handle *h" "int vendor" "int type" "const void *data" "size_t len" .Ft int .Fn rad_put_vendor_int "struct rad_handle *h" "int vendor" "int type" "uint32_t value" .Ft int .Fn rad_put_vendor_string "struct rad_handle *h" "int vendor" "int type" "const char *str" .Ft ssize_t .Fn rad_request_authenticator "struct rad_handle *h" "char *buf" "size_t len" .Ft int .Fn rad_receive_request "struct rad_handle *h" .Ft int .Fn rad_send_request "struct rad_handle *h" .Ft int .Fn rad_send_response "struct rad_handle *h" .Ft "struct rad_handle *" .Fn rad_server_open "int fd" .Ft "const char *" .Fn rad_server_secret "struct rad_handle *h" .Ft "void" .Fn rad_bind_to "struct rad_handle *h" "in_addr_t addr" .Ft u_char * .Fn rad_demangle "struct rad_handle *h" "const void *mangled" "size_t mlen" .Ft u_char * .Fn rad_demangle_mppe_key "struct rad_handle *h" "const void *mangled" "size_t mlen" "size_t *len" .Ft "const char *" .Fn rad_strerror "struct rad_handle *h" .Sh DESCRIPTION The .Nm library implements the Remote Authentication Dial In User Service (RADIUS). RADIUS, defined in RFCs 2865 and 2866, allows clients to perform authentication and accounting by means of network requests to remote servers. .Ss Initialization To use the library, an application must first call .Fn rad_auth_open , .Fn rad_acct_open or .Fn rad_server_open to obtain a .Vt "struct rad_handle *" , which provides the context for subsequent operations. The former function is used for RADIUS authentication and the latter is used for RADIUS accounting. Calls to .Fn rad_auth_open , .Fn rad_acct_open and .Fn rad_server_open always succeed unless insufficient virtual memory is available. If the necessary memory cannot be allocated, the functions return .Dv NULL . For compatibility with earlier versions of this library, .Fn rad_open is provided as a synonym for .Fn rad_auth_open . .Pp Before issuing any RADIUS requests, the library must be made aware of the servers it can contact. The easiest way to configure the library is to call .Fn rad_config . .Fn rad_config causes the library to read a configuration file whose format is described in .Xr radius.conf 5 . The pathname of the configuration file is passed as the .Fa file argument to .Fn rad_config . This argument may also be given as .Dv NULL , in which case the standard configuration file .Pa /etc/radius.conf is used. .Fn rad_config returns 0 on success, or \-1 if an error occurs. .Pp The library can also be configured programmatically by calls to .Fn rad_add_server or .Fn rad_add_server_ex . .Fn rad_add_server is a backward compatible function, implemented via .Fn rad_add_server_ex . The .Fa host parameter specifies the server host, either as a fully qualified domain name or as a dotted-quad IP address in text form. The .Fa port parameter specifies the UDP port to contact on the server. If .Fa port is given as 0, the library looks up the .Ql radius/udp or .Ql radacct/udp service in the network .Xr services 5 database, and uses the port found there. If no entry is found, the library uses the standard RADIUS ports, 1812 for authentication and 1813 for accounting. The shared secret for the server host is passed to the .Fa secret parameter. It may be any .Dv NUL Ns -terminated string of bytes. The RADIUS protocol ignores all but the leading 128 bytes of the shared secret. The timeout for receiving replies from the server is passed to the .Fa timeout parameter, in units of seconds. The maximum number of repeated requests to make before giving up is passed into the .Fa max_tries parameter. Time interval in seconds when the server will not be requested if it is marked as dead (did not answer on the last try) set with .Fa dead_time parameter. .Fa bindto parameter is an IP address on the multihomed host that is used as a source address for all requests. .Fn rad_add_server returns 0 on success, or \-1 if an error occurs. .Pp .Fn rad_add_server or .Fn rad_add_server_ex may be called multiple times, and they may be used together with .Fn rad_config . At most 10 servers may be specified. When multiple servers are given, they are tried in round-robin fashion until a valid response is received, or until each server's .Fa max_tries limit has been reached. .Ss Creating a RADIUS Request A RADIUS request consists of a code specifying the kind of request, and zero or more attributes which provide additional information. To begin constructing a new request, call .Fn rad_create_request . In addition to the usual .Vt "struct rad_handle *" , this function takes a .Fa code parameter which specifies the type of the request. Most often this will be .Dv RAD_ACCESS_REQUEST . .Fn rad_create_request returns 0 on success, or \-1 on if an error occurs. .Pp After the request has been created with .Fn rad_create_request , attributes can be attached to it. This is done through calls to .Fn rad_put_addr , .Fn rad_put_int , and .Fn rad_put_string . Each accepts a .Fa type parameter identifying the attribute, and a value which may be an Internet address, an integer, or a .Dv NUL Ns -terminated string, respectively. Alternatively, .Fn rad_put_vendor_addr , .Fn rad_put_vendor_int or .Fn rad_put_vendor_string may be used to specify vendor specific attributes. Vendor specific definitions may be found in .In radlib_vs.h .Pp The library also provides a function .Fn rad_put_attr which can be used to supply a raw, uninterpreted attribute. The .Fa data argument points to an array of bytes, and the .Fa len argument specifies its length. .Pp It is possible adding the Message-Authenticator to the request. This is an HMAC-MD5 hash of the entire Access-Request packet (see RFC 3579). This attribute must be present in any packet that includes an EAP-Message attribute. It can be added by using the .Fn rad_put_message_authentic function. The .Nm library calculates the HMAC-MD5 hash implicitly before sending the request. If the Message-Authenticator was found inside the response packet, then the packet is silently dropped, if the validation failed. In order to get this feature, the library should be compiled with OpenSSL support. .Pp The .Fn rad_put_X functions return 0 on success, or \-1 if an error occurs. .Ss Sending the Request and Receiving the Response After the RADIUS request has been constructed, it is sent either by means of .Fn rad_send_request or by a combination of calls to .Fn rad_init_send_request and .Fn rad_continue_send_request . .Pp The .Fn rad_send_request function sends the request and waits for a valid reply, retrying the defined servers in round-robin fashion as necessary. If a valid response is received, .Fn rad_send_request returns the RADIUS code which specifies the type of the response. This will typically be .Dv RAD_ACCESS_ACCEPT , .Dv RAD_ACCESS_REJECT , or .Dv RAD_ACCESS_CHALLENGE . If no valid response is received, .Fn rad_send_request returns \-1. .Pp As an alternative, if you do not wish to block waiting for a response, .Fn rad_init_send_request and .Fn rad_continue_send_request may be used instead. If a reply is received from the RADIUS server or a timeout occurs, these functions return a value as described for .Fn rad_send_request . Otherwise, a value of zero is returned and the values pointed to by .Fa fd and .Fa tv are set to the descriptor and timeout that should be passed to .Xr select 2 . .Pp .Fn rad_init_send_request must be called first, followed by repeated calls to .Fn rad_continue_send_request as long as a return value of zero is given. Between each call, the application should call .Xr select 2 , passing .Fa *fd as a read descriptor and timing out after the interval specified by .Fa tv . When .Xr select 2 returns, .Fn rad_continue_send_request should be called with .Fa selected set to a non-zero value if .Xr select 2 indicated that the descriptor is readable. .Pp Like RADIUS requests, each response may contain zero or more attributes. After a response has been received successfully by .Fn rad_send_request or .Fn rad_continue_send_request , its attributes can be extracted one by one using .Fn rad_get_attr . Each time .Fn rad_get_attr is called, it gets the next attribute from the current response, and stores a pointer to the data and the length of the data via the reference parameters .Fa data and .Fa len , respectively. Note that the data resides in the response itself, and must not be modified. A successful call to .Fn rad_get_attr returns the RADIUS attribute type. If no more attributes remain in the current response, .Fn rad_get_attr returns 0. If an error such as a malformed attribute is detected, \-1 is returned. .Pp If .Fn rad_get_attr returns .Dv RAD_VENDOR_SPECIFIC , .Fn rad_get_vendor_attr may be called to determine the vendor. The vendor specific RADIUS attribute type is returned. The reference parameters .Fa data and .Fa len (as returned from .Fn rad_get_attr ) are passed to .Fn rad_get_vendor_attr , and are adjusted to point to the vendor specific attribute data. .Pp The common types of attributes can be decoded using .Fn rad_cvt_addr , .Fn rad_cvt_int , and .Fn rad_cvt_string . These functions accept a pointer to the attribute data, which should have been obtained using .Fn rad_get_attr and optionally .Fn rad_get_vendor_attr . In the case of .Fn rad_cvt_string , the length .Fa len must also be given. These functions interpret the attribute as an Internet address, an integer, or a string, respectively, and return its value. .Fn rad_cvt_string returns its value as a .Dv NUL Ns -terminated string in dynamically allocated memory. The application should free the string using .Xr free 3 when it is no longer needed. .Pp If insufficient virtual memory is available, .Fn rad_cvt_string returns .Dv NULL . .Fn rad_cvt_addr and .Fn rad_cvt_int cannot fail. .Pp The .Fn rad_request_authenticator function may be used to obtain the Request-Authenticator attribute value associated with the current RADIUS server according to the supplied rad_handle. The target buffer .Fa buf of length .Fa len must be supplied and should be at least 16 bytes. The return value is the number of bytes written to .Fa buf or \-1 to indicate that .Fa len was not large enough. .Pp The .Fn rad_server_secret returns the secret shared with the current RADIUS server according to the supplied rad_handle. .Pp The .Fn rad_bind_to assigns a source address for all requests to the current RADIUS server. .Pp The .Fn rad_demangle function demangles attributes containing passwords and MS-CHAPv1 MPPE-Keys. The return value is .Dv NULL on failure, or the plaintext attribute. This value should be freed using .Xr free 3 when it is no longer needed. .Pp The .Fn rad_demangle_mppe_key function demangles the send- and recv-keys when using MPPE (see RFC 2548). The return value is .Dv NULL on failure, or the plaintext attribute. This value should be freed using .Xr free 3 when it is no longer needed. .Ss Obtaining Error Messages Those functions which accept a .Vt "struct rad_handle *" argument record an error message if they fail. The error message can be retrieved by calling .Fn rad_strerror . The message text is overwritten on each new error for the given .Vt "struct rad_handle *" . Thus the message must be copied if it is to be preserved through subsequent library calls using the same handle. .Ss Cleanup To free the resources used by the RADIUS library, call .Fn rad_close . .Ss Server operation Server mode operates much alike to client mode, except packet send and receive -steps are swapped. To operate as server you should obtain server context with +steps are swapped. +To operate as server you should obtain server context with .Fn rad_server_open function, passing opened and bound UDP socket file descriptor as argument. You should define allowed clients and their secrets using .Fn rad_add_server function. port, timeout and max_tries arguments are ignored in server mode. You should call .Fn rad_receive_request -function to receive request from client. If you do not want to block on socket -read, you are free to use any poll(), select() or non-blocking sockets for -the socket. +function to receive request from client. +If you do not want to block on socket read, you are free to use any +poll(), select() or non-blocking sockets for the socket. Received request can be parsed with same parsing functions as for client. To respond to the request you should call .Fn rad_create_response and fill response content with same packet writing functions as for client. When packet is ready, it should be sent with .Fn rad_send_response . .Sh RETURN VALUES The following functions return a non-negative value on success. If they detect an error, they return \-1 and record an error message which can be retrieved using .Fn rad_strerror . .Pp .Bl -item -offset indent -compact .It .Fn rad_add_server .It .Fn rad_config .It .Fn rad_create_request .It .Fn rad_create_response .It .Fn rad_get_attr .It .Fn rad_put_addr .It .Fn rad_put_attr .It .Fn rad_put_int .It .Fn rad_put_string .It .Fn rad_put_message_authentic .It .Fn rad_init_send_request .It .Fn rad_continue_send_request .It .Fn rad_send_request .It .Fn rad_send_response .El .Pp The following functions return a .No non- Ns Dv NULL pointer on success. If they are unable to allocate sufficient virtual memory, they return .Dv NULL , without recording an error message. .Pp .Bl -item -offset indent -compact .It .Fn rad_acct_open .It .Fn rad_auth_open .It .Fn rad_server_open .It .Fn rad_cvt_string .El .Pp The following functions return a .No non- Ns Dv NULL pointer on success. If they fail, they return .Dv NULL , with recording an error message. .Pp .Bl -item -offset indent -compact .It .Fn rad_demangle .It .Fn rad_demangle_mppe_key .El .Sh FILES .Bl -tag -width indent .It Pa /etc/radius.conf .El .Sh SEE ALSO .Xr radius.conf 5 .Rs .%A "C. Rigney, et al" .%T "Remote Authentication Dial In User Service (RADIUS)" .%O "RFC 2865" .Re .Rs .%A "C. Rigney" .%T "RADIUS Accounting" .%O "RFC 2866" .Re .Rs .%A G. Zorn .%T "Microsoft Vendor-specific RADIUS attributes" .%O RFC 2548 .Re .Rs .%A C. Rigney, et al .%T "RADIUS extensions" .%O RFC 2869 .Re .Sh AUTHORS .An -nosplit This software was originally written by .An John Polstra , and donated to the .Fx project by Juniper Networks, Inc. .An Oleg Semyonov subsequently added the ability to perform RADIUS accounting. Later additions and changes by .An Michael Bretterklieber . Server mode support was added by .An Alexander Motin . Index: head/lib/librpcsec_gss/rpc_gss_set_callback.3 =================================================================== --- head/lib/librpcsec_gss/rpc_gss_set_callback.3 (revision 366582) +++ head/lib/librpcsec_gss/rpc_gss_set_callback.3 (revision 366583) @@ -1,115 +1,116 @@ .\" Copyright (c) 2008 Isilon Inc http://www.isilon.com/ .\" Authors: Doug Rabson .\" Developed with Red Inc: Alfred Perlstein .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .Dd January 26, 2010 .Dt RPC_GSS_SET_CALLBACK 3 .Os .Sh NAME .Nm rpc_gss_set_callback .Nd "Register a security context creation callback" .Sh LIBRARY .Lb librpcsec_gss .Sh SYNOPSIS .In rpc/rpcsec_gss.h .Ft bool_t .Fo (*callback) .Fa "struct svc_req *req" .Fa "gss_cred_id_t deleg" .Fa "gss_ctx_id_t gss_context" .Fa "rpc_gss_lock_t *lock" .Fa "void **cookie" .Fc .Ft bool_t .Fn rpc_gss_set_callback "rpc_gss_callback_t *cb" .Sh DESCRIPTION Register a function which will be called when new security contexts are created on a server. This function will be called on the first RPC request which uses that context and has the opportunity of rejecting the request (for instance after matching the request credentials to an access control list). To accept the new security context, the callback should return .Dv TRUE , otherwise .Dv FALSE . If the callback accepts a context, it becomes responsible for the lifetime of the delegated client credentials (if any). .Pp It is also possible to 'lock' the values of service and quality of protection used by the context. If a context is locked, any subsequent requests which use different values for service and quality of protection will be rejected. .Sh PARAMETERS .Bl -tag -width ".It gss_context" .It cb A structure containing the RPC program and version for this callback and a function which will be called when new contexts are created for the given RPC program and version .It req The RPC request using the new context .It deleg GSS-API delegated credentials (if any) .It gss_context The GSS-API context .It lock -A structure used to enforce a particular QOP and service. Set +A structure used to enforce a particular QOP and service. +Set .Fa lock->locked to .Dv TRUE to lock the service and QOP values .It cookie The callback function may set .Fa *cookie to any pointer sized value. This value can be accessed during the lifetime of the context via .Fn rpc_gss_getcred . .El .Sh RETURN VALUES Returns .Dv TRUE if the callback was registered successfully or .Dv FALSE otherwise .Sh SEE ALSO .Xr gssapi 3 , .Xr rpc 3 , .Xr rpc_gss_getcred 3 , .Xr rpcset_gss 3 .Sh HISTORY The .Nm function first appeared in .Fx 8.0 . .Sh AUTHORS This manual page was written by .An Doug Rabson Aq Mt dfr@FreeBSD.org . .Sh BUGS There is no mechanism for informing a server when a security context has been deleted. This makes it difficult to allocate resources (e.g. to return via the callback's .Fa cookie argument). Index: head/lib/libsysdecode/sysdecode_mask.3 =================================================================== --- head/lib/libsysdecode/sysdecode_mask.3 (revision 366582) +++ head/lib/libsysdecode/sysdecode_mask.3 (revision 366583) @@ -1,242 +1,242 @@ .\" .\" Copyright (c) 2016 John Baldwin .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd January 16, 2018 .Dt sysdecode_mask 3 .Os .Sh NAME .Nm sysdecode_mask , .Nm sysdecode_accessmode , .Nm sysdecode_atflags , .Nm sysdecode_capfcntlrights , .Nm sysdecode_fcntl_fileflags , .Nm sysdecode_fileflags , .Nm sysdecode_filemode , .Nm sysdecode_flock_operation , .Nm sysdecode_mlockall_flags , .Nm sysdecode_mmap_flags , .Nm sysdecode_mmap_prot , .Nm sysdecode_mount_flags , .Nm sysdecode_msg_flags , .Nm sysdecode_msync_flags , .Nm sysdecode_open_flags , .Nm sysdecode_pipe2_flags , .Nm sysdecode_reboot_howto , .Nm sysdecode_rfork_flags , .Nm sysdecode_semget_flags , .Nm sysdecode_sendfile_flags , .Nm sysdecode_shmat_flags , .Nm sysdecode_sctp_nxt_flags , .Nm sysdecode_sctp_rcv_flags , .Nm sysdecode_sctp_snd_flags , .Nm sysdecode_socket_type , .Nm sysdecode_thr_create_flags , .Nm sysdecode_umtx_cvwait_flags , .Nm sysdecode_umtx_rwlock_flags , .Nm sysdecode_vmprot , .Nm sysdecode_wait4_options , .Nm sysdecode_wait6_options .Nd print name of various bitmask values .Sh LIBRARY .Lb libsysdecode .Sh SYNOPSIS .In sys/types.h .In stdbool.h .In stdio.h .In sysdecode.h .Ft bool .Fn sysdecode_access_mode "FILE *fp" "int mode" "int *rem" .Ft bool .Fn sysdecode_atflags "FILE *fp" "int flags" "int *rem" .Ft bool .Fn sysdecode_cap_fcntlrights "FILE *fp" "uint32_t rights" "uint32_t *rem" .Ft bool .Fn sysdecode_fcntl_fileflags "FILE *fp" "int flags" "int *rem" .Ft bool .Fn sysdecode_fileflags "FILE *fp" "fflags_t flags" "fflags_t *rem" .Ft bool .Fn sysdecode_filemode "FILE *fp" "int mode" "int *rem" .Ft bool .Fn sysdecode_flock_operation "FILE *fp" "int operation" "int *rem" .Ft bool .Fn sysdecode_mlockall_flags "FILE *fp" "int flags" "int *rem" .Ft bool .Fn sysdecode_mmap_flags "FILE *fp" "int flags" "int *rem" .Ft bool .Fn sysdecode_mmap_prot "FILE *fp" "int prot" "int *rem" .Ft bool .Fn sysdecode_mount_flags "FILE *fp" "int flags" "int *rem" .Ft bool .Fn sysdecode_msg_flags "FILE *fp" "int flags" "int *rem" .Ft bool .Fn sysdecode_msync_flags "FILE *fp" "int flags" "int *rem" .Ft bool .Fn sysdecode_open_flags "FILE *fp" "int flags" "int *rem" .Ft bool .Fn sysdecode_pipe2_flags "FILE *fp" "int flags" "int *rem" .Ft bool .Fn sysdecode_reboot_howto "FILE *fp" "int howto" "int *rem" .Ft bool .Fn sysdecode_rfork_flags "FILE *fp" "int flags" "int *rem" .Ft bool .Fn sysdecode_sctp_nxt_flags "FILE *fp" "int flags" "int *rem" .Ft bool .Fn sysdecode_sctp_rcv_flags "FILE *fp" "int flags" "int *rem" .Ft bool .Fn sysdecode_sctp_snd_flags "FILE *fp" "int flags" "int *rem" .Ft bool .Fn sysdecode_semget_flags "FILE *fp" "int flags" "int *rem" .Ft bool .Fn sysdecode_sendfile_flags "FILE *fp" "int flags" "int *rem" .Ft bool .Fn sysdecode_shmat_flags "FILE *fp" "int flags" "int *rem" .Ft bool .Fn sysdecode_socket_type "FILE *fp" "int type" "int *rem" .Ft bool .Fn sysdecode_thr_create_flags "FILE *fp" "int flags" "int *rem" .Ft bool .Fn sysdecode_umtx_cvwait_flags "FILE *fp" "u_long flags" "u_long *rem" .Ft bool .Fn sysdecode_umtx_rwlock_flags "FILE *fp" "u_long flags" "u_long *rem" .Ft bool .Fn sysdecode_vmprot "FILE *fp" "int type" "int *rem" .Ft bool .Fn sysdecode_wait4_options "FILE *fp" "int options" "int *rem" .Ft bool .Fn sysdecode_wait6_options "FILE *fp" "int options" "int *rem" .Sh DESCRIPTION The .Nm functions are used to generate a text description of an integer value built from a mask of bitfields. The text description lists the C macros for field values joined by pipe .Sq | characters matching the format used in C source code. Most of the values decoded by these functions are passed as arguments to system calls, though some of these values are used internally in the kernel. .Pp Each function writes the text description to .Fa fp . The second argument should contain the integer value to be decoded. The .Fa rem argument is set to the value of any bits that were not decoded .Pq bit fields that do not have a corresponding C macro . .Fa rem may be set to .Dv NULL if the caller does not need this value. Each function returns .Dv true if any bit fields in the value were decoded and .Dv false if no bit fields were decoded. .Pp Most of these functions decode an argument passed to a system call: .Bl -column "Fn sysdecode_flock_operation" "Xr cap_fcntls_limit 2" .It Sy Function Ta Sy System Call Ta Sy Argument .It Fn sysdecode_access_mode Ta Xr access 2 Ta Fa mode .It Fn sysdecode_atflags Ta Xr chflagsat 2 , Xr fstatat 2 Ta Fa atflag , Fa flag .It Fn sysdecode_cap_fcntlrights Ta Xr cap_fcntls_limit 2 Ta Fa fcntlrights .It Fn sysdecode_fileflags Ta Xr chflags 2 Ta Fa flags .It Fn sysdecode_filemode Ta Xr chmod 2 , Xr open 2 Ta mode .It Fn sysdecode_flock_operation Ta Xr flock 2 Ta Fa operation .It Fn sysdecode_mlockall_flags Ta Xr mlockall 2 Ta Fa flags .It Fn sysdecode_mmap_flags Ta Xr mmap 2 Ta Fa flags .It Fn sysdecode_mmap_prot Ta Xr mmap 2 Ta Fa prot .It Fn sysdecode_mount_flags Ta Xr mount 2 Ta Fa flags .It Fn sysdecode_msg_flags Ta Xr recv 2 , Xr send 2 Ta Fa flags .It Fn sysdecode_msync_flags Ta Xr msync 2 Ta Fa flags .It Fn sysdecode_open_flags Ta Xr open 2 Ta Fa flags .It Fn sysdecode_pipe2_flags Ta Xr pipe2 Ta Fa flags .It Fn sysdecode_reboot_howto Ta Xr reboot 2 Ta Fa howto .It Fn sysdecode_rfork_flags Ta Xr rfork 2 Ta Fa flags .It Fn sysdecode_semget_flags Ta Xr semget 2 Ta Fa flags .It Fn sysdecode_sendfile_flags Ta Xr sendfile 2 Ta Fa flags .It Fn sysdecode_shmat_flags Ta Xr shmat 2 Ta Fa flags .It Fn sysdecode_socket_type Ta Xr socket 2 Ta Fa type .It Fn sysdecode_thr_create_flags Ta Xr thr_create 2 Ta Fa flags .It Fn sysdecode_wait4_options Ta Xr wait4 2 Ta Fa options .It Fn sysdecode_wait6_options Ta Xr wait6 2 Ta Fa options .El .Pp Other functions decode the values described below: .Bl -tag -width ".Fn sysdecode_umtx_cvwait_flags" .It Fn sysdecode_fcntl_fileflags The file flags used with the .Dv F_GETFL and .Dv F_SETFL .Xr fcntl 2 commands. .It Fn sysdecode_sctp_nxt_flags -The +The .Fa nxt_flags member of a .Vt struct sctp_nxtinfo . .It Fn sysdecode_sctp_rcv_flags -The +The .Fa rcv_flags member of a .Vt struct sctp_rcvinfo . .It Fn sysdecode_sctp_snd_flags -The +The .Fa snd_flags member of a .Vt struct sctp_sndinfo . .It Fn sysdecode_umtx_cvwait_flags The .Fa val argument to .Xr _umtx_op 2 for .Dv UMTX_OP_CV_WAIT operations. .It Fn sysdecode_umtx_rwlock_flags The .Fa val argument to .Xr _umtx_op 2 for .Dv UMTX_OP_RW_RDLOCK operations. .It Fn sysdecode_vmprot The memory protection flags stored in .Vt vm_prot_t variables. .El .Sh RETURN VALUES The .Nm functions return .Dv true if any bit fields in the value were decoded and .Dv false if no bit fields were decoded. .Sh SEE ALSO .Xr sysdecode 3 , .Xr sysdecode_enum 3 Index: head/lib/libusb/libusb20.3 =================================================================== --- head/lib/libusb/libusb20.3 (revision 366582) +++ head/lib/libusb/libusb20.3 (revision 366583) @@ -1,1077 +1,1080 @@ .\" .\" Copyright (c) 2008-2019 Hans Petter Selasky .\" .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd December 27, 2019 .Dt LIBUSB20 3 .Os .Sh NAME .Nm libusb20 . .Nd "USB access library" . . .Sh LIBRARY . . USB access library (libusb -lusb) . . . .Sh SYNOPSIS .In libusb20.h .Ft int .Fn libusb20_tr_close "struct libusb20_transfer *xfer" .Ft int .Fn libusb20_tr_open "struct libusb20_transfer *xfer" "uint32_t max_buf_size" "uint32_t max_frame_count" "uint8_t ep_no" .Fn libusb20_tr_open_stream "struct libusb20_transfer *xfer" "uint32_t max_buf_size" "uint32_t max_frame_count" "uint8_t ep_no" "uint16_t stream_id" .Ft struct libusb20_transfer* .Fn libusb20_tr_get_pointer "struct libusb20_device *pdev" "uint16_t tr_index" .Ft uint16_t .Fn libusb20_tr_get_time_complete "struct libusb20_transfer *xfer" .Ft uint32_t .Fn libusb20_tr_get_actual_frames "struct libusb20_transfer *xfer" .Ft uint32_t .Fn libusb20_tr_get_actual_length "struct libusb20_transfer *xfer" .Ft uint32_t .Fn libusb20_tr_get_max_frames "struct libusb20_transfer *xfer" .Ft uint32_t .Fn libusb20_tr_get_max_packet_length "struct libusb20_transfer *xfer" .Ft uint32_t .Fn libusb20_tr_get_max_total_length "struct libusb20_transfer *xfer" .Ft uint8_t .Fn libusb20_tr_get_status "struct libusb20_transfer *xfer" .Ft uint8_t .Fn libusb20_tr_pending "struct libusb20_transfer *xfer" .Ft void .Fn libusb20_tr_callback_wrapper "struct libusb20_transfer *xfer" .Ft void .Fn libusb20_tr_clear_stall_sync "struct libusb20_transfer *xfer" .Ft void .Fn libusb20_tr_drain "struct libusb20_transfer *xfer" .Ft void .Fn libusb20_tr_set_buffer "struct libusb20_transfer *xfer" "void *buffer" "uint16_t fr_index" .Ft void .Fn libusb20_tr_set_callback "struct libusb20_transfer *xfer" "libusb20_tr_callback_t *cb" .Ft void .Fn libusb20_tr_set_flags "struct libusb20_transfer *xfer" "uint8_t flags" .Ft uint32_t .Fn libusb20_tr_get_length "struct libusb20_transfer *xfer" "uint16_t fr_index" .Ft void .Fn libusb20_tr_set_length "struct libusb20_transfer *xfer" "uint32_t length" "uint16_t fr_index" .Ft void .Fn libusb20_tr_set_priv_sc0 "struct libusb20_transfer *xfer" "void *sc0" .Ft void .Fn libusb20_tr_set_priv_sc1 "struct libusb20_transfer *xfer" "void *sc1" .Ft void .Fn libusb20_tr_set_timeout "struct libusb20_transfer *xfer" "uint32_t timeout" .Ft void .Fn libusb20_tr_set_total_frames "struct libusb20_transfer *xfer" "uint32_t nframes" .Ft void .Fn libusb20_tr_setup_bulk "struct libusb20_transfer *xfer" "void *pbuf" "uint32_t length" "uint32_t timeout" .Ft void .Fn libusb20_tr_setup_control "struct libusb20_transfer *xfer" "void *psetup" "void *pbuf" "uint32_t timeout" .Ft void .Fn libusb20_tr_setup_intr "struct libusb20_transfer *xfer" "void *pbuf" "uint32_t length" "uint32_t timeout" .Ft void .Fn libusb20_tr_setup_isoc "struct libusb20_transfer *xfer" "void *pbuf" "uint32_t length" "uint61_t fr_index" .Ft uint8_t .Fn libusb20_tr_bulk_intr_sync "struct libusb20_transfer *xfer" "void *pbuf" "uint32_t length" "uint32_t *pactlen" "uint32_t timeout" .Ft void .Fn libusb20_tr_start "struct libusb20_transfer *xfer" .Ft void .Fn libusb20_tr_stop "struct libusb20_transfer *xfer" .Ft void .Fn libusb20_tr_submit "struct libusb20_transfer *xfer" .Ft void * .Fn libusb20_tr_get_priv_sc0 "struct libusb20_transfer *xfer" .Ft void * .Fn libusb20_tr_get_priv_sc1 "struct libusb20_transfer *xfer" .Ft const char * .Fn libusb20_dev_get_backend_name "struct libusb20_device *" .Ft int .Fn libusb20_dev_get_port_path "struct libusb20_device *pdev" "uint8_t *buf" "uint8_t bufsize" .Ft int .Fn libusb20_dev_get_info "struct libusb20_device *pdev" "struct usb_device_info *pinfo" .Ft int .Fn libusb20_dev_get_iface_desc "struct libusb20_device *pdev" "uint8_t iface_index" "char *buf" "uint8_t len" .Ft const char * .Fn libusb20_dev_get_desc "struct libusb20_device *pdev" .Ft int .Fn libusb20_dev_get_stats "struct libusb20_device *pdev" "struct libusb20_device_stats *pstats" .Ft int .Fn libusb20_dev_close "struct libusb20_device *pdev" .Ft int .Fn libusb20_dev_detach_kernel_driver "struct libusb20_device *pdev" "uint8_t iface_index" .Ft int .Fn libusb20_dev_set_config_index "struct libusb20_device *pdev" "uint8_t configIndex" .Ft int .Fn libusb20_dev_get_debug "struct libusb20_device *pdev" .Ft int .Fn libusb20_dev_get_fd "struct libusb20_device *pdev" .Ft int .Fn libusb20_dev_kernel_driver_active "struct libusb20_device *pdev" "uint8_t iface_index" .Ft int .Fn libusb20_dev_open "struct libusb20_device *pdev" "uint16_t transfer_max" .Ft int .Fn libusb20_dev_process "struct libusb20_device *pdev" .Ft int .Fn libusb20_dev_request_sync "struct libusb20_device *pdev" "struct LIBUSB20_CONTROL_SETUP_DECODED *setup" "void *data" "uint16_t *pactlen" "uint32_t timeout" "uint8_t flags" .Ft int .Fn libusb20_dev_req_string_sync "struct libusb20_device *pdev" "uint8_t index" "uint16_t langid" "void *ptr" "uint16_t len" .Ft int .Fn libusb20_dev_req_string_simple_sync "struct libusb20_device *pdev" "uint8_t index" "void *ptr" "uint16_t len" .Ft int .Fn libusb20_dev_reset "struct libusb20_device *pdev" .Ft int .Fn libusb20_dev_check_connected "struct libusb20_device *pdev" .Ft int .Fn libusb20_dev_set_power_mode "struct libusb20_device *pdev" "uint8_t power_mode" .Ft uint8_t .Fn libusb20_dev_get_power_mode "struct libusb20_device *pdev" .Ft uint16_t .Fn libusb20_dev_get_power_usage "struct libusb20_device *pdev" .Ft int .Fn libusb20_dev_set_alt_index "struct libusb20_device *pdev" "uint8_t iface_index" "uint8_t alt_index" .Ft struct LIBUSB20_DEVICE_DESC_DECODED * .Fn libusb20_dev_get_device_desc "struct libusb20_device *pdev" .Ft struct libusb20_config * .Fn libusb20_dev_alloc_config "struct libusb20_device *pdev" "uint8_t config_index" .Ft struct libusb20_device * .Fn libusb20_dev_alloc "void" .Ft uint8_t .Fn libusb20_dev_get_address "struct libusb20_device *pdev" .Ft uint8_t .Fn libusb20_dev_get_parent_address "struct libusb20_device *pdev" .Ft uint8_t .Fn libusb20_dev_get_parent_port "struct libusb20_device *pdev" .Ft uint8_t .Fn libusb20_dev_get_bus_number "struct libusb20_device *pdev" .Ft uint8_t .Fn libusb20_dev_get_mode "struct libusb20_device *pdev" .Ft uint8_t .Fn libusb20_dev_get_speed "struct libusb20_device *pdev" .Ft uint8_t .Fn libusb20_dev_get_config_index "struct libusb20_device *pdev" .Ft void .Fn libusb20_dev_free "struct libusb20_device *pdev" .Ft void .Fn libusb20_dev_set_debug "struct libusb20_device *pdev" "int debug" .Ft void .Fn libusb20_dev_wait_process "struct libusb20_device *pdev" "int timeout" .Ft int .Fn libusb20_be_get_template "struct libusb20_backend *pbe" "int *ptemp" .Ft int .Fn libusb20_be_set_template "struct libusb20_backend *pbe" "int temp" .Ft int .Fn libusb20_be_get_dev_quirk "struct libusb20_backend *pber" "uint16_t index" "struct libusb20_quirk *pq" .Ft int .Fn libusb20_be_get_quirk_name "struct libusb20_backend *pbe" "uint16_t index" "struct libusb20_quirk *pq" .Ft int .Fn libusb20_be_add_dev_quirk "struct libusb20_backend *pbe" "struct libusb20_quirk *pq" .Ft int .Fn libusb20_be_remove_dev_quirk "struct libusb20_backend *pbe" "struct libusb20_quirk *pq" .Ft struct libusb20_backend * .Fn libusb20_be_alloc_default "void" .Ft struct libusb20_backend * .Fn libusb20_be_alloc_freebsd "void" .Ft struct libusb20_backend * .Fn libusb20_be_alloc_linux "void" .Ft struct libusb20_device * .Fn libusb20_be_device_foreach "struct libusb20_backend *pbe" "struct libusb20_device *pdev" .Ft void .Fn libusb20_be_dequeue_device "struct libusb20_backend *pbe" "struct libusb20_device *pdev" .Ft void .Fn libusb20_be_enqueue_device "struct libusb20_backend *pbe" "struct libusb20_device *pdev" .Ft void .Fn libusb20_be_free "struct libusb20_backend *pbe" .Ft uint8_t .Fn libusb20_me_get_1 "const struct libusb20_me_struct *me" "uint16_t off" .Ft uint16_t .Fn libusb20_me_get_2 "const struct libusb20_me_struct *me" "uint16_t off" .Ft uint16_t .Fn libusb20_me_encode "void *pdata" "uint16_t len" "const void *pdecoded" .Ft uint16_t .Fn libusb20_me_decode "const void *pdata" "uint16_t len" "void *pdecoded" .Ft "const uint8_t *" .Fn libusb20_desc_foreach "const struct libusb20_me_struct *me" "const uint8_t *pdesc" .Ft "const char *" .Fn libusb20_strerror "int code" .Ft "const char *" .Fn libusb20_error_name "int code" . . .Sh DESCRIPTION . The .Nm library implements functions to be able to easily access and control USB through the USB file system interface. The .Nm interfaces are specific to the .Fx usb stack and are not available on other operating systems, portable applications should consider using .Xr libusb 3 . . . .Sh USB TRANSFER OPERATIONS . . .Fn libusb20_tr_close will release all kernel resources associated with an USB .Fa xfer . . This function returns zero upon success. . Non-zero return values indicate a LIBUSB20_ERROR value. . .Pp . .Fn libusb20_tr_open will allocate kernel buffer resources according to .Fa max_buf_size and .Fa max_frame_count associated with an USB .Fa pxfer and bind the transfer to the specified .Fa ep_no . .Fa max_buf_size is the minimum buffer size which the data transport layer has to support. If .Fa max_buf_size is zero, the .Nm library will use wMaxPacketSize to compute the buffer size. This can be useful for isochronous transfers. The actual buffer size can be greater than .Fa max_buf_size and is returned by .Fn libusb20_tr_get_max_total_length . . If .Fa max_frame_count is OR'ed with LIBUSB20_MAX_FRAME_PRE_SCALE the remaining part of the argument is converted from milliseconds into the actual number of frames rounded up, when this function returns. This flag is only valid for ISOCHRONOUS transfers and has no effect for other transfer types. The actual number of frames setup is found by calling .Fn libusb20_tr_get_max_frames . . This function returns zero upon success. . Non-zero return values indicate a LIBUSB20_ERROR value. . .Pp . .Fn libusb20_tr_open_stream is identical to .Fn libusb20_tr_open except that a stream ID can be specified for BULK endpoints having such a feature. .Fn libusb20_tr_open can be used to open stream ID zero. . .Pp . .Fn libusb20_tr_get_pointer will return a pointer to the allocated USB transfer according to the .Fa pdev and .Fa tr_index arguments. . This function returns NULL in case of failure. . .Pp . .Fn libusb20_tr_get_time_complete will return the completion time of an USB transfer in -millisecond units. This function is most useful for isochronous USB -transfers when doing echo cancelling. +millisecond units. +This function is most useful for isochronous USB transfers when doing echo +cancelling. . .Pp . .Fn libusb20_tr_get_actual_frames will return the actual number of USB frames after an USB -transfer completed. A value of zero means that no data was transferred. -. +transfer completed. +A value of zero means that no data was transferred. .Pp . .Fn libusb20_tr_get_actual_length will return the sum of the actual length for all transferred USB frames for the given USB transfer. . .Pp . .Fn libusb20_tr_get_max_frames will return the maximum number of USB frames that were allocated when an USB transfer was setup for the given USB transfer. . .Pp . .Fn libusb20_tr_get_max_packet_length will return the maximum packet length in bytes associated with the given USB transfer. . The packet length can be used round up buffer sizes so that short USB packets are avoided for proxy buffers. . . .Pp . .Fn libusb20_tr_get_max_total_length will return the maximum value for the data length sum of all USB frames associated with an USB transfer. In case of control transfers the value returned does not include the length of the SETUP packet, 8 bytes, which is part of frame zero. The returned value of this function is always aligned to the maximum packet size, wMaxPacketSize, of the endpoint which the USB transfer is bound to. . .Pp . .Fn libusb20_tr_get_status will return the status of an USB transfer. . Status values are defined by a set of LIBUSB20_TRANSFER_XXX enums. . .Pp . .Fn libusb20_tr_pending will return non-zero if the given USB transfer is pending for completion. . Else this function returns zero. . .Pp . .Fn libusb20_tr_callback_wrapper This is an internal function used to wrap asynchronous USB callbacks. . .Pp . .Fn libusb20_tr_clear_stall_sync This is an internal function used to synchronously clear the stall on the given USB transfer. . Please see the USB specification for more information on stall clearing. . If the given USB transfer is pending when this function is called, the USB transfer will complete with an error after that this function has been called. . .Pp . .Fn libusb20_tr_drain will stop the given USB transfer and will not return until the USB transfer has been stopped in hardware. . .Pp . .Fn libusb20_tr_set_buffer is used to set the .Fa buffer pointer for the given USB transfer and .Fa fr_index . . Typically the frame index is zero. . . .Pp . .Fn libusb20_tr_set_callback is used to set the USB callback for asynchronous USB transfers. . The callback type is defined by libusb20_tr_callback_t. . .Pp . .Fn libusb20_tr_set_flags is used to set various USB flags for the given USB transfer. .Bl -tag -width "LIBUSB20_TRANSFER_SINGLE_SHORT_NOT_OK" .It LIBUSB20_TRANSFER_SINGLE_SHORT_NOT_OK Report a short frame as error. .It LIBUSB20_TRANSFER_MULTI_SHORT_NOT_OK Multiple short frames are not allowed. .It LIBUSB20_TRANSFER_FORCE_SHORT All transmitted frames are short terminated. .It LIBUSB20_TRANSFER_DO_CLEAR_STALL Will do a clear-stall before starting the transfer. .El . .Pp . .Fn libusb20_tr_get_length returns the length of the given USB frame by index. After an USB transfer is complete the USB frame length will get updated to the actual transferred length. . .Pp . .Fn libusb20_tr_set_length sets the length of the given USB frame by index. . .Pp . .Fn libusb20_tr_set_priv_sc0 sets private driver pointer number zero. . .Pp . .Fn libusb20_tr_set_priv_sc1 sets private driver pointer number one. . .Pp . .Fn libusb20_tr_set_timeout sets the timeout for the given USB transfer. . A timeout value of zero means no timeout. . The timeout is given in milliseconds. . .Pp . .Fn libusb20_tr_set_total_frames sets the total number of frames that should be executed when the USB transfer is submitted. . The total number of USB frames must be less than the maximum number of USB frames associated with the given USB transfer. . .Pp . .Fn libusb20_tr_setup_bulk is a helper function for setting up a single frame USB BULK transfer. . .Pp . .Fn libusb20_tr_setup_control is a helper function for setting up a single or dual frame USB CONTROL transfer depending on the control transfer length. . .Pp . .Fn libusb20_tr_setup_intr is a helper function for setting up a single frame USB INTERRUPT transfer. . .Pp . .Fn libusb20_tr_setup_isoc is a helper function for setting up a multi frame USB ISOCHRONOUS transfer. . .Pp . .Fn libusb20_tr_bulk_intr_sync will perform a synchronous BULK or INTERRUPT transfer having length given by the .Fa length argument and buffer pointer given by the .Fa pbuf argument on the USB transfer given by the .Fa xfer argument. . If the .Fa pactlen argument is non-NULL the actual transfer length will be stored at the given pointer destination. . If the .Fa timeout argument is non-zero the transfer will timeout after the given value in milliseconds. . This function does not change the transfer flags, like short packet not ok. . This function returns zero on success else a LIBUSB20_TRANSFER_XXX value is returned. . .Pp . .Fn libusb20_tr_start will get the USB transfer started, if not already started. . This function will not get the transfer queued in hardware. . This function is non-blocking. . .Pp . .Fn libusb20_tr_stop will get the USB transfer stopped, if not already stopped. . This function is non-blocking, which means that the actual stop can happen after the return of this function. . .Pp . .Fn libusb20_tr_submit will get the USB transfer queued in hardware. . . .Pp . .Fn libusb20_tr_get_priv_sc0 returns private driver pointer number zero associated with an USB transfer. . . .Pp . .Fn libusb20_tr_get_priv_sc1 returns private driver pointer number one associated with an USB transfer. . . .Sh USB DEVICE OPERATIONS . . .Fn libusb20_dev_get_backend_name returns a zero terminated string describing the backend used. . .Pp . .Fn libusb20_dev_get_port_path retrieves the list of USB port numbers which the datastream for a given USB device follows. The first port number is the Root HUB port number. Then children port numbers follow. The Root HUB device itself has a port path length of zero. Valid port numbers start at one and range until and including 255. Typically there should not be more than 16 levels, due to electrical and protocol limitations. This functions returns the number of actual port levels upon success else a LIBUSB20_ERROR value is returned which are always negative. If the actual number of port levels is greater than the maximum specified, a LIBUSB20_ERROR value is returned. . .Pp . .Fn libusb20_dev_get_info retrieves the BSD specific usb_device_info structure into the memory location given by .Fa pinfo . The USB device given by .Fa pdev must be opened before this function will succeed. This function returns zero on success else a LIBUSB20_ERROR value is returned. . .Pp . .Fn libusb20_dev_get_iface_desc retrieves the kernel interface description for the given USB .Fa iface_index . The format of the USB interface description is: "drivername: " The description string is always zero terminated. A zero length string is written in case no driver is attached to the given interface. The USB device given by .Fa pdev must be opened before this function will succeed. This function returns zero on success else a LIBUSB20_ERROR value is returned. . .Pp . .Fn libusb20_dev_get_desc returns a zero terminated string describing the given USB device. The format of the string is: "drivername: " . .Pp . .Fn libusb20_dev_get_stats retrieves the device statistics into the structure pointed to by the .Fa pstats argument. This function returns zero on success else a LIBUSB20_ERROR value is returned. . .Pp . .Fn libusb20_dev_close will close the given USB device. . This function returns zero on success else a LIBUSB20_ERROR value is returned. . .Pp . .Fn libusb20_dev_detach_kernel_driver will try to detach the kernel driver for the USB interface given by .Fa iface_index . . This function returns zero on success else a LIBUSB20_ERROR value is returned. . .Pp . .Fn libusb20_dev_set_config_index will try to set the configuration index on an USB device. . The first configuration index is zero. . The un-configure index is 255. . This function returns zero on success else a LIBUSB20_ERROR value is returned. . .Pp . .Fn libusb20_dev_get_debug returns the debug level of an USB device. . .Pp . .Fn libusb20_dev_get_fd returns the file descriptor of the given USB device. . A negative value is returned when no file descriptor is present. . The file descriptor can be used for polling purposes. . .Pp . .Fn libusb20_dev_kernel_driver_active returns zero if a kernel driver is active on the given USB interface. . Else a LIBUSB20_ERROR value is returned. . .Pp . .Fn libusb20_dev_open opens an USB device so that setting up USB transfers becomes possible. . The number of USB transfers can be zero which means only control transfers are allowed. . This function returns zero on success else a LIBUSB20_ERROR value is returned. . A return value of LIBUSB20_ERROR_BUSY means that the device is already opened. . .Pp . .Fn libusb20_dev_process is called to sync kernel USB transfers with userland USB transfers. . This function returns zero on success else a LIBUSB20_ERROR value is returned typically indicating that the given USB device has been detached. . .Pp . .Fn libusb20_dev_request_sync will perform a synchronous control request on the given USB device. . Before this call will succeed the USB device must be opened. . .Fa setup is a pointer to a decoded and host endian SETUP packet. .Fa data -is a pointer to a data transfer buffer associated with the control transaction. This argument can be NULL. +is a pointer to a data transfer buffer associated with the control transaction. +This argument can be NULL. .Fa pactlen -is a pointer to a variable that will hold the actual transfer length after the control transaction is complete. +is a pointer to a variable that will hold the actual transfer length after the +control transaction is complete. .Fa timeout is the transaction timeout given in milliseconds. A timeout of zero means no timeout. .Fa flags is used to specify transaction flags, for example LIBUSB20_TRANSFER_SINGLE_SHORT_NOT_OK. . This function returns zero on success else a LIBUSB20_ERROR value is returned. . .Pp . .Fn libusb20_dev_req_string_sync will synchronously request an USB string by language ID and string index into the given buffer limited by a maximum length. . This function returns zero on success else a LIBUSB20_ERROR value is returned. . .Pp . .Fn libusb20_dev_req_string_simple_sync will synchronously request an USB string using the default language ID and convert the string into ASCII before storing the string into the given buffer limited by a maximum length which includes the terminating zero. . This function returns zero on success else a LIBUSB20_ERROR value is returned. . . .Pp . .Fn libusb20_dev_reset will try to BUS reset the given USB device and restore the last set USB configuration. . This function returns zero on success else a LIBUSB20_ERROR value is returned. . . .Pp . .Fn libusb20_dev_check_connected will check if an opened USB device is still connected. . This function returns zero if the device is still connected else a LIBUSB20_ERROR value is returned. . . .Pp . .Fn libusb20_dev_set_power_mode sets the power mode of the USB device. . Valid power modes: .Bl -tag -width "LIBUSB20_POWER_OFF" .It LIBUSB20_POWER_OFF .It LIBUSB20_POWER_ON .It LIBUSB20_POWER_SAVE .It LIBUSB20_POWER_SUSPEND .It LIBUSB20_POWER_RESUME .El .Pp . This function returns zero on success else a LIBUSB20_ERROR value is returned. . .Pp . .Fn libusb20_dev_get_power_mode returns the currently selected power mode for the given USB device. . .Pp . .Fn libusb20_dev_get_power_usage returns the reported power usage in milliamps for the given USB device. A power usage of zero typically means that the device is self powered. . .Pp . .Fn libusb20_dev_set_alt_index will try to set the given alternate index for the given USB interface index. . This function returns zero on success else a LIBUSB20_ERROR value is returned. . .Pp . .Fn libusb20_dev_get_device_desc returns a pointer to the decoded and host endian version of the device descriptor. . The USB device need not be opened when calling this function. . .Pp . .Fn libusb20_dev_alloc_config -will read out and decode the USB config descriptor for -the given USB device and config index. This function returns a pointer -to the decoded configuration which must eventually be passed to -free(). NULL is returned in case of failure. +will read out and decode the USB config descriptor for the given USB device +and config index. +This function returns a pointer to the decoded configuration which must eventually +be passed to free(). +NULL is returned in case of failure. . .Pp . .Fn libusb20_dev_alloc is an internal function to allocate a new USB device. . .Pp . .Fn libusb20_dev_get_address returns the internal and not necessarily the real hardware address of the given USB device. Valid addresses start at one. . .Pp . .Fn libusb20_dev_get_parent_address returns the internal and not necessarily the real hardware address of the given parent USB HUB device. This value is zero for the root HUB which usually has a device address equal to one. Valid addresses start at one. . .Pp . .Fn libusb20_dev_get_parent_port returns the port number on the parent USB HUB device. This value is zero for the root HUB which usually has a device address equal to one. Valid port numbers start at one. . .Pp . .Fn libusb20_dev_get_bus_number returns the internal bus number which the given USB device belongs to. Valid bus numbers start at zero. . .Pp . .Fn libusb20_dev_get_mode returns the current operation mode of the USB entity. . Valid return values are: .Bl -tag -width "LIBUSB20_MODE_DEVICE" .It LIBUSB20_MODE_HOST .It LIBUSB20_MODE_DEVICE .El . .Pp . .Fn libusb20_dev_get_speed returns the current speed of the given USB device. . .Bl -tag -width "LIBUSB20_SPEED_VARIABLE" .It LIBUSB20_SPEED_UNKNOWN .It LIBUSB20_SPEED_LOW .It LIBUSB20_SPEED_FULL .It LIBUSB20_SPEED_HIGH .It LIBUSB20_SPEED_VARIABLE .It LIBUSB20_SPEED_SUPER .El . .Pp . .Fn libusb20_dev_get_config_index returns the currently selected config index for the given USB device. . .Pp . .Fn libusb20_dev_free will free the given USB device and all associated USB transfers. . .Pp . .Fn libusb20_dev_set_debug will set the debug level for the given USB device. . .Pp . .Fn libusb20_dev_wait_process will wait until a pending USB transfer has completed on the given USB device. . A timeout value can be specified which is passed on to the .Xr poll 2 function. . .Sh USB BACKEND OPERATIONS . .Fn libusb20_be_get_template will return the currently selected global USB device side mode template into the integer pointer .Fa ptemp . This function returns zero on success else a LIBUSB20_ERROR value is returned. . .Pp . .Fn libusb20_be_set_template will set the global USB device side mode template to .Fa temp . The new template is not activated until after the next USB enumeration. The template number decides how the USB device will present itself to -the USB Host, like Mass Storage Device, USB Ethernet Device. Also see -the +the USB Host, like Mass Storage Device, USB Ethernet Device. +Also see the .Xr usb2_template 4 module. This function returns zero on success else a LIBUSB20_ERROR value is returned. . .Pp . .Fn libusb20_be_get_dev_quirk will return the device quirk according to .Fa index into the libusb20_quirk structure pointed to by .Fa pq . This function returns zero on success else a LIBUSB20_ERROR value is returned. . If the given quirk does not exist LIBUSB20_ERROR_NOT_FOUND is returned. . .Pp . .Fn libusb20_be_get_quirk_name will return the quirk name according to .Fa index into the libusb20_quirk structure pointed to by .Fa pq . This function returns zero on success else a LIBUSB20_ERROR value is returned. . If the given quirk does not exist LIBUSB20_ERROR_NOT_FOUND is returned. . .Pp . .Fn libusb20_be_add_dev_quirk will add the libusb20_quirk structure pointed to by the .Fa pq argument into the device quirk list. . This function returns zero on success else a LIBUSB20_ERROR value is returned. . If the given quirk cannot be added LIBUSB20_ERROR_NO_MEM is returned. . .Pp . .Fn libusb20_be_remove_dev_quirk will remove the quirk matching the libusb20_quirk structure pointed to by the .Fa pq argument from the device quirk list. . This function returns zero on success else a LIBUSB20_ERROR value is returned. . If the given quirk does not exist LIBUSB20_ERROR_NOT_FOUND is returned. . .Pp . .Fn libusb20_be_alloc_default .Fn libusb20_be_alloc_freebsd .Fn libusb20_be_alloc_linux -These functions are used to allocate a specific USB backend or the -operating system default USB backend. Allocating a backend is a way to -scan for currently present USB devices. -. +These functions are used to allocate a specific USB backend or the operating system +default USB backend. +Allocating a backend is a way to scan for currently present USB devices. .Pp . .Fn libusb20_be_device_foreach is used to iterate USB devices present in a USB backend. . The starting value of .Fa pdev is NULL. . This function returns the next USB device in the list. . If NULL is returned the end of the USB device list has been reached. . .Pp . .Fn libusb20_be_dequeue_device will dequeue the given USB device pointer from the backend USB device list. . Dequeued USB devices will not be freed when the backend is freed. . .Pp . .Fn libusb20_be_enqueue_device will enqueue the given USB device pointer in the backend USB device list. . Enqueued USB devices will get freed when the backend is freed. . .Pp . .Fn libusb20_be_free will free the given backend and all USB devices in its device list. . . .Sh USB DESCRIPTOR PARSING . .Fn libusb20_me_get_1 pie offset This function will return a byte at the given byte offset of a message entity. . This function is safe against invalid offsets. . .Pp . .Fn libusb20_me_get_2 pie offset This function will return a little endian 16-bit value at the given byte offset of a message entity. . This function is safe against invalid offsets. . .Pp . .Fn libusb20_me_encode pbuf len pdecoded This function will encode a so-called *DECODED structure into binary format. . The total encoded length that will fit in the given buffer is returned. . If the buffer pointer is NULL no data will be written to the buffer location. . .Pp . .Fn libusb20_me_decode pbuf len pdecoded This function will decode a binary structure into a so-called *DECODED structure. . The total decoded length is returned. . The buffer pointer cannot be NULL. . . .Sh USB DEBUGGING .Ft const char * .Fn libusb20_strerror "int code" Get the ASCII representation of the error given by the .Fa code argument. This function does not return NULL. .Pp .Ft const char * .Fn libusb20_error_name "int code" Get the ASCII representation of the error enum given by the .Fa code argument. This function does not return NULL. . .Sh FILES .Bl -tag -width Pa .It Pa /dev/usb .El .Sh SEE ALSO .Xr libusb 3 , .Xr usb 4 , .Xr usbconfig 8 , .Xr usbdump 8 . . .Sh HISTORY . . Some parts of the .Nm API derives from the libusb project at sourceforge. Index: head/lib/libutil/login_ok.3 =================================================================== --- head/lib/libutil/login_ok.3 (revision 366582) +++ head/lib/libutil/login_ok.3 (revision 366583) @@ -1,150 +1,150 @@ .\" Copyright (c) 1995 David Nugent .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, is permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice immediately at the beginning of the file, without modification, .\" 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. This work was done expressly for inclusion into FreeBSD. Other use .\" is permitted provided this notation is included. .\" 4. Absolutely no warranty of function or purpose is made by the author .\" David Nugent. .\" 5. Modifications may be freely made to this file providing the above .\" conditions are met. .\" .\" $FreeBSD$ .\" -.Dd May 10, 2020 +.Dd May 10, 2020 .Dt LOGIN_OK 3 .Os .Sh NAME .Nm auth_ttyok , .Nm auth_hostok , .Nm auth_timeok .Nd functions for checking login class based login restrictions .Sh LIBRARY .Lb libutil .Sh SYNOPSIS .In sys/types.h .In time.h .In login_cap.h .Ft int .Fn auth_ttyok "login_cap_t *lc" "const char *tty" .Ft int .Fn auth_hostok "login_cap_t *lc" "const char *host" "char const *ip" .Ft int .Fn auth_timeok "login_cap_t *lc" "time_t t" .Sh DESCRIPTION This set of functions checks to see if login is allowed based on login class capability entries in the login database, .Xr login.conf 5 . .Pp The .Fn auth_ttyok function checks to see if the named tty is available to users of a specific class, and is either in the .Em ttys.allow access list, and not in the .Em ttys.deny access list. An empty .Em ttys.allow list (or if no such capability exists for the given login class) logins via any tty device are allowed unless the .Em ttys.deny list exists and is non-empty, and the device or its tty group (see .Xr ttys 5 ) is not in the list. Access to ttys may be allowed or restricted specifically by tty device name, a device name which includes a wildcard (e.g.\& ttyD* or cuaD*), or may name a ttygroup, when group= tags have been assigned in .Pa /etc/ttys . Matching of ttys and ttygroups is case sensitive. Passing a .Dv NULL or empty string as the .Ar tty parameter causes the function to return a non-zero value. .Pp The .Fn auth_hostok function checks for any host restrictions for remote logins. The function checks on both a host name and IP address (given in its text form, typically n.n.n.n) against the .Em host.allow and .Em host.deny login class capabilities. As with ttys and their groups, wildcards and character classes may be used in the host allow and deny capability records. The .Xr fnmatch 3 function is used for matching, and the matching on hostnames is case insensitive. Note that this function expects that the hostname is fully expanded (i.e., the local domain name added if necessary) and the IP address is in its canonical form. No hostname or address lookups are attempted. .Pp It is possible to call this function with either the hostname or the IP address missing (i.e.\& .Dv NULL ) and matching will be performed only on the basis of the parameter given. Passing .Dv NULL or empty strings in both parameters will result in a non-zero return value. .Pp The .Fn auth_timeok function checks to see that a given time value is within the .Em times.allow login class capability and not within the .Em times.deny access lists. An empty or non-existent .Em times.allow list allows access at any time, except if a given time is falls within a period in the .Em times.deny list. The format of time period records contained in both .Em times.allow and .Em times.deny capability fields is explained in detail in the .Xr login_times 3 manual page. .Sh RETURN VALUES A non-zero return value from any of these functions indicates that login access is granted. A zero return value means either that the item being tested is not in the .Em allow access list, or is within the .Em deny access list. .Sh SEE ALSO .Xr getcap 3 , .Xr login_cap 3 , .Xr login_class 3 , .Xr login_times 3 , .Xr login.conf 5 , .Xr termcap 5 .Sh HISTORY The functions .Fn auth_ttyok , .Fn auth_hostok and .Fn auth_timeok functions first appeared in .Fx 2.1.5 . Index: head/lib/msun/man/sincos.3 =================================================================== --- head/lib/msun/man/sincos.3 (revision 366582) +++ head/lib/msun/man/sincos.3 (revision 366583) @@ -1,82 +1,82 @@ .\" Copyright (c) 2011 Steven G. Kargl. .\" .\" 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 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. .\" .\" $FreeBSD$ .\" .Dd March 12, 2011 .Dt SINCOS 3 .Os .Sh NAME .Nm sincos , .Nm sincosf , .Nm sincosl .Nd sine and cosine functions .Sh LIBRARY .Lb libm .Sh SYNOPSIS .In math.h .Ft void .Fn sincos "double x" "double *s" "double *c" .Ft void .Fn sincosf "float x" "float *s" "float *c" .Ft void .Fn sincosl "long double x" "long double *s" "long double *c" .Sh DESCRIPTION The .Fn sincos , .Fn sincosf , and .Fn sincosl functions compute the sine and cosine of .Fa x . Using these functions allows argument reduction to occur only -once instead of twice with individual invocations of +once instead of twice with individual invocations of .Fn sin -and +and .Fn cos . -Like +Like .Fn sin -and +and .Fn cos , a large magnitude argument may yield a result with little or no significance. .Sh RETURN VALUES -Upon returning from +Upon returning from .Fn sincos , .Fn sincosf , and .Fn sincosl , -the memory pointed to by -.Ar "*s" +the memory pointed to by +.Ar "*s" and -.Ar "*c" +.Ar "*c" are assigned the values of sine and cosine, respectively. .Sh SEE ALSO .Xr cos 3 , .Xr sin 3 , .Sh HISTORY -These functions were added to +These functions were added to .Fx 9.0 -to aid in writing various complex function contained in +to aid in writing various complex function contained in .St -isoC-99 . Index: head/share/man/man4/fdt_pinctrl.4 =================================================================== --- head/share/man/man4/fdt_pinctrl.4 (revision 366582) +++ head/share/man/man4/fdt_pinctrl.4 (revision 366583) @@ -1,127 +1,126 @@ .\" Copyright (c) 2018 Oleksandr Tymoshenko .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE 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. .\" .\" $FreeBSD$ .\" .Dd March 3, 2018 .Dt "FDT_PINCTRL" 4 .Os .Sh NAME .Nm fdt_pinctrl .Nd FDT I/O pin multiplexing support .Sh SYNOPSIS .Cd "device fdt_pinctrl" .Sh DESCRIPTION -.Pp Pin multiplexing is a technology used to re-purpose a single physical connection (depending on chip packaging it may be -pin, ball, or pad) by routing its signal to any one of several +pin, ball, or pad) by routing its signal to any one of several different SoC internal devices. For example, based on the actual device design, a single SoC chip pin might perform any of these roles: SPI clock, I2C data, GPIO pin, or PWM signal. Function selection is performed by the pinmux controller, a SoC hardware block which is usually controlled by a set of registers. Pinmux controller capabilities and register format depend on the actual hardware implementation. .Pp On .Xr fdt 4 based systems, the pinmux controller is represented by a node in the device tree. It may have any number of child nodes representing pin configuration groups. Properties of such nodes are hardware-specific and handled by individual pinctrl drivers. .Ss Example 1 Pinmux controller device tree node .Bd -literal pinctrl@7e220000 { compatible = "vndr,soc1715-pinctrl"; reg = <0x7e220000 0x100> spi0_pins: spi0 { vndr,pins = <11 12> vndr,functions = } i2c0_pins: i2c0 { ... } } .Ed .Pp Client devices are hardware devices that require certain pin configurations to function properly. Depending on the state the device is in (active, idle) it might require different pin configurations. Each configuration is described by setting the pinctrl-N property to the list of phandles pointing to specific child nodes of the pinmux controller node. N is an integer value starting with 0 and incremented by 1 for every new set of pin configurations. pinctrl-0 is a default configuration that is applied in the .Xr fdt_pinctrl_configure_tree 9 call. In addition to referring to pin configurations by index, they can be referred to by name if the pinctrl-names property is set. The value of pinctrl-names is a list of strings with names for each pinctrl-N property. Client devices can request specific configuration using .Xr fdt_pinctrl_configure 9 and .Xr fdt_pinctrl_configure_by_name 9 . .Ss Example 2 .Bd -literal backlight@7f000000 { compatible = "vndr,vndr-bl" reg = <0x7f000000 0x20> ... pinctrl-name = "active", "idle" pinctrl-0 = <&backlight_active_pins> pinctrl-1 = <&backlight_idle_pins> } .Ed .Pp The pinctrl driver should implement the FDT_PINCTRL_CONFIGURE method, register itself as a pin configuration handler by calling fdt_pinctrl_register function, and call .Xr fdt_pinctrl_configure_tree 9 to configure pins for all enabled devices (devices where the "status" property is not set to "disabled"). .Sh SEE ALSO .Xr fdt_pinctrl 9 .Sh HISTORY The .Nm driver first appeared in .Fx 10.2 . .Sh AUTHORS .An -nosplit The .Nm device driver was developed by .An \&Ian Lepore Aq Mt ian@FreeBSD.org . This manual page was written by .An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org . Index: head/share/man/man4/ig4.4 =================================================================== --- head/share/man/man4/ig4.4 (revision 366582) +++ head/share/man/man4/ig4.4 (revision 366583) @@ -1,84 +1,84 @@ .\" Copyright (c) 2015 Michael Gmelin .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd September 13, 2018 .Dt IG4 4 .Os .Sh NAME .Nm ig4 .Nd Synopsys DesignWare I2C Controller .Sh SYNOPSIS To compile this driver into the kernel, place the following lines into the kernel configuration file: .Bd -ragged -offset indent .Cd "device ig4" .Cd "device iicbus" .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 ig4_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides access to peripherals attached to an I2C controller. .Sh HARDWARE .Nm supports the I2C controllers based on Synopsys DesignWare IP that can be found in Intel(R) Core(TM) processors starting from the fourth generation, Intel(R) Bay Trail, Apollo Lake SoC families, and some AMD systems. .Sh SYSCTL VARIABLES These .Xr sysctl 8 variables are available: .Bl -tag -width "debug.ig4_dump" .It Va debug.ig4_dump This sysctl is a zero-based bit mask. When any of the bits are set, a register dump is printed for every I2C transfer on an .Nm device with the same unit number. .El .Sh SEE ALSO .Xr iic 4 , .Xr iicbus 4 .Sh AUTHORS .An -nosplit The .Nm -driver was written for +driver was written for .Dx by .An Matthew Dillon and subsequently ported to .Fx by .An Michael Gmelin Aq Mt freebsd@grem.de . .Pp This manual page was written by .An Michael Gmelin Aq Mt freebsd@grem.de . Index: head/share/man/man4/man4.i386/ce.4 =================================================================== --- head/share/man/man4/man4.i386/ce.4 (revision 366582) +++ head/share/man/man4/man4.i386/ce.4 (revision 366583) @@ -1,111 +1,111 @@ .\" Copyright (c) 2006 Roman Kurakin .\" 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 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. .\" .\" $FreeBSD$ .\" .Dd January 30, 2006 .Dt CE 4 i386 .Os .Sh NAME .Nm ce .Nd "driver for synchronous Cronyx Tau-PCI/32 WAN adapters" .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device ce" .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 if_ce_load="YES" .Ed .Pp Additional options: .Cd "device sppp" .Cd "options NETGRAPH" .Cd "options NETGRAPH_CRONYX" .Sh DESCRIPTION The .Nm driver needs either .Xr sppp 4 or .Xr netgraph 4 . Which one to use is determined by the .Dv NETGRAPH_CRONYX option. If this option is present in your kernel configuration file, the .Nm driver will be compiled with .Xr netgraph 4 support. Otherwise, it will be compiled with .Xr sppp 4 support. .Pp Refer to .Xr sconfig 8 for information about the .Nm adapter configuration. .Sh HARDWARE The .Nm driver supports the following models of Tau-PCI/32 WAN adapters: .Pp .Bl -tag -width 20n -compact .It Cronyx Tau-PCI/32 two fractional/unframed E1 interfaces, with 32 HDLC channels shared between them with total adapter throughput 2048 kbps. .It Cronyx Tau-PCI/32-Lite single fractional/unframed E1 interface, with 32 HDLC channels. .El .Sh SEE ALSO .Xr cp 4 , .Xr ctau 4 , .Xr cx 4 , .Xr sppp 4 , .Xr ifconfig 8 , .Xr sconfig 8 , .Xr spppcontrol 8 .Sh HISTORY The .Nm driver was added in .Fx 6.2 , .Fx 5.5 and .Fx 4.11 . The .Nm driver for previous versions of .Fx is available from .Pa http://www.cronyx.ru/ . Index: head/share/man/man4/mlx5io.4 =================================================================== --- head/share/man/man4/mlx5io.4 (revision 366582) +++ head/share/man/man4/mlx5io.4 (revision 366583) @@ -1,191 +1,191 @@ .\" .\" Copyright (c) 2018, 2019 Mellanox Technologies .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. -.\" +.\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd October 2, 2019 .Dt mlx5io 4 .Os .Sh NAME .Nm mlx5io .Nd IOCTL interface to manage Connect-X 4/5/6 Mellanox network adapters .Sh SYNOPSIS .In dev/mlx5/mlx5io.h .Sh DESCRIPTION The .Nm interface is provided for management of the Connect-X4, 5 and 6 network adapters in the aspects not covered by the generic network configuration, mostly related to the PCIe attachment and internal card working. Interface consists of the commands, which are passed by means of .Xr ioctl 2 on the file descriptor, opened from the .Pa /dev/mlx5ctl device node. .Pp The following commands are implemented: .Bl -tag -width indent .It Dv MLX5_FWDUMP_FORCE Take the snapshot of the firmware registers state and store it in the kernel buffer. The buffer must be empty, in other words, no dumps should be written so far, or existing dump cleared with the .Dv MLX5_FWDUMP_RESET command for the specified device. The argument for the command should point to the .Vt struct mlx5_tool_addr structure, containing the PCIe bus address of the device. .Bd -literal struct mlx5_tool_addr { uint32_t domain; uint8_t bus; uint8_t slot; uint8_t func; }; .Ed .It Dv MLX5_FWDUMP_RESET Clear the stored firmware dump, preparing the kernel buffer for the next dump. The argument for the command should point to the .Vt struct mlx5_tool_addr structure, containing the PCIe bus address of the device. .It Dv MLX5_FWDUMP_GET Fetch the stored firmware dump into the user memory. The argument to the command should point to the input/output .Vt struct mlx5_fwdump_get structure. Its .Dv devaddr field specifies the address of the device, the .Dv buf fields points to the array of .Vt struct mlx5_fwdump_reg of records of the registers values, the size of the array is specified in the .Dv reg_cnt field. .Bd -literal struct mlx5_fwdump_get { struct mlx5_tool_addr devaddr; struct mlx5_fwdump_reg *buf; size_t reg_cnt; size_t reg_filled; /* out */ }; .Ed .Pp On successfull return, the .Dv reg_filled field reports the number of the .Dv buf array elements actually filled with the registers values. If .Dv buf contains the .Dv NULL pointer, no registers are filled, but .Dv reg_filled still contains the number of registers that should be passed for the complete dump. .Pp The .Vt struct mlx5_fwdump_reg element contains the address of the register in the field .Dv addr , and its value in the field .Dv val . .Bd -literal struct mlx5_fwdump_reg { uint32_t addr; uint32_t val; }; .Ed .It Dv MLX5_FW_UPDATE Requests firmware update (flash) on the adapter specified by the .Dv devaddr using the firmware image in .Dv MFA2 format. The argument for the ioctl command is the .Vt struct mlx5_fw_update with the following definition. .Bd -literal struct mlx5_fw_update { struct mlx5_tool_addr devaddr; void *img_fw_data; size_t img_fw_data_len; }; .Ed Image address in memory is passed in .Dv img_fw_data , the length of the image is specified in .Dv img_fw_data_len field. .It Dv MLX5_FW_RESET Requests PCIe link-level reset on the device. The address of the device is specified by the .Vt struct mlx5_tool_addr structure, which should be passed as an argument. .It Dv MLX5_EEPROM_GET Fetch EEPROM information. The argument to the command should point to the input/output .Vt struct mlx5_eeprom_get structure where, the .Dv devaddr field specifies the address of the device. .Bd -literal struct mlx5_eeprom_get { struct mlx5_tool_addr devaddr; size_t eeprom_info_page_valid; uint32_t *eeprom_info_buf; size_t eeprom_info_out_len; }; .Ed .Pp On successfull return, the .Dv eeprom_info_out_len field reports the length of the EEPROM information. .Dv eeprom_info_buf field contains the actual EEPROM information. .Dv eeprom_info_page_valid field reports the third page validity. .El .Sh FILES The .Pa /dev/mlx5ctl .Xr devfs 5 node is used to pass commands to the driver. .Sh RETURN VALUES If successful, the IOCTL returns zero. Otherwise, -1 is returned and the global variable .Va errno is set to indicate the error. .Sh SEE ALSO .Xr errno 2 , .Xr ioctl 2 , .Xr mlx5en 4 , .Xr mlx5ib 4 , .Xr mlx5tool 8 and .Xr pci 9 . Index: head/share/man/man4/mrsas.4 =================================================================== --- head/share/man/man4/mrsas.4 (revision 366582) +++ head/share/man/man4/mrsas.4 (revision 366583) @@ -1,409 +1,409 @@ .\" Copyright (c) 2014 LSI Corp .\" All rights reserved. .\" Author: Kashyap Desai .\" Support: freebsdraid@lsi.com .\" .\" 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 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 COPYRIGHT HOLDERS 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 .\" COPYRIGHT HOLDER 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. .\" .\" The views and conclusions contained in the software and documentation .\" are those of the authors and should not be interpreted as representing .\" official policies, either expressed or implied, of the FreeBSD Project. .\" .\" $FreeBSD$ .\" -.Dd Mar 13, 2019 +.Dd March 13, 2019 .Dt MRSAS 4 .Os .Sh NAME .Nm mrsas .Nd "LSI MegaRAID 6Gb/s and 12Gb/s SAS+SATA RAID controller driver" .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device pci" .Cd "device mrsas" .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 mrsas_load="YES" .Ed .Sh DESCRIPTION The .Nm driver will detect LSI's next generation (6Gb/s and 12Gb/s) PCI Express SAS/SATA RAID controllers. See the .Nm HARDWARE section for the supported devices list. A disk (virtual disk/physical disk) attached to the .Nm driver will be visible to the user through .Xr camcontrol 8 as .Pa /dev/da? device nodes. A simple management interface is also provided on a per-controller basis via the .Pa /dev/mrsas? device node. .Pp The .Nm name is derived from the phrase "MegaRAID SAS HBA", which is substantially different than the old "MegaRAID" Driver .Xr mfi 4 which does not connect targets to the .Xr cam 4 layer and thus requires a new driver which attaches targets to the .Xr cam 4 layer. Older MegaRAID controllers are supported by .Xr mfi 4 and will not work with .Nm , but both the .Xr mfi 4 and .Nm drivers can detect and manage the LSI MegaRAID SAS 2208/2308/3008/3108 series of controllers. .Pp The .Xr device.hints 5 option is provided to tune the .Nm driver's behavior for LSI MegaRAID SAS 2208/2308/3008/3108 controllers. By default, the .Xr mfi 4 driver will detect these controllers. See the .Nm PRIORITY section to know more about driver priority for MR-Fusion devices. .Pp .Nm will provide a priority of (-30) (between .Dv BUS_PROBE_DEFAULT and .Dv BUS_PROBE_LOW_PRIORITY ) at probe call for device id's 0x005B, 0x005D, and 0x005F so that .Nm does not take control of these devices without user intervention. .Pp Solid-state drives (SSD) get ATA TRIM support with .Nm if underlying adapter allows it. This may require configuring SSD as Non-RAID drive rather then JBOD virtual mode. .Sh HARDWARE The .Nm driver supports the following hardware: .Pp [ Thunderbolt 6Gb/s MR controller ] .Bl -bullet -compact .It LSI MegaRAID SAS 9265 .It LSI MegaRAID SAS 9266 .It LSI MegaRAID SAS 9267 .It LSI MegaRAID SAS 9270 .It LSI MegaRAID SAS 9271 .It LSI MegaRAID SAS 9272 .It LSI MegaRAID SAS 9285 .It LSI MegaRAID SAS 9286 .It DELL PERC H810 .It DELL PERC H710/P .El .Pp [ Invader/Fury 12Gb/s MR controller ] .Bl -bullet -compact .It LSI MegaRAID SAS 9380 .It LSI MegaRAID SAS 9361 .It LSI MegaRAID SAS 9341 .It DELL PERC H830 .It DELL PERC H730/P .It DELL PERC H330 .El .Sh CONFIGURATION To disable Online Controller Reset(OCR) for a specific .Nm driver instance, set the following tunable value in .Xr loader.conf 5 : .Bd -literal -offset indent dev.mrsas.X.disable_ocr=1 .Ed .Pp where X is the adapter number. .Pp To change the I/O timeout value for a specific .Nm driver instance, set the following tunable value in .Xr loader.conf 5 : .Bd -literal -offset indent dev.mrsas.X.mrsas_io_timeout=NNNNNN .Ed .Pp where NNNNNN is the timeout value in milli-seconds. .Pp To change the firmware fault check timer value for a specific .Nm driver instance, set the following tunable value in .Xr loader.conf 5 : .Bd -literal -offset indent dev.mrsas.X.mrsas_fw_fault_check_delay=NN .Ed .Pp where NN is the fault check delay value in seconds. .Pp The current number of active I/O commands is shown in the .Va dev.mrsas.X.fw_outstanding .Xr sysctl 8 variable. .Sh DEBUGGING To enable debugging prints from the .Nm driver, set the .Va hw.mrsas.X.debug_level variable, where X is the adapter number, either in .Xr loader.conf 5 or via .Xr sysctl 8 . The following bits have the described effects: .Bl -tag -width indent -offset indent .It 0x01 Enable informational prints. .It 0x02 Enable tracing prints. .It 0x04 Enable prints for driver faults. .It 0x08 Enable prints for OCR and I/O timeout. .It 0x10 Enable prints for AEN events. .El .Sh PRIORITY The .Nm driver will always set a default (-30) priority in the PCI subsystem for selection of MR-Fusion cards. (It is between .Dv BUS_PROBE_DEFAULT and .Dv BUS_PROBE_LOW_PRIORITY ) . MR-Fusion Controllers include all cards with the Device IDs - 0x005B, 0x005D, 0x005F. .Pp The .Xr mfi 4 driver will set a priority of either .Dv BUS_PROBE_DEFAULT or .Dv BUS_PROBE_LOW_PRIORITY (depending on the device.hints setting) in the PCI subsystem for selection of MR-Fusion cards. With the above design in place, the .Xr mfi 4 driver will attach to a MR-Fusion card given that it has a higher priority than .Nm . .Pp Using .Pa /boot/device.hints (as mentioned below), the user can provide a preference for the .Nm driver to detect a MR-Fusion card instead of the .Xr mfi 4 driver. .Bd -ragged -offset indent .Cd hw.mfi.mrsas_enable="1" .Ed .Pp At boot time, the .Xr mfi 4 driver will get priority to detect MR-Fusion controllers by default. Before changing this default driver selection policy, LSI advises users to understand how the driver selection policy works. LSI's policy is to provide priority to the .Xr mfi 4 driver to detect MR-Fusion cards, but allow for the ability to choose the .Nm driver to detect MR-Fusion cards. .Pp LSI recommends setting hw.mfi.mrsas_enable="0" for customers who are using the older .Xr mfi 4 driver and do not want to switch to .Nm . For those customers who are using a MR-Fusion controller for the first time, LSI recommends using the .Nm driver and setting hw.mfi.mrsas_enable="1". .Pp Changing the default behavior is well tested under most conditions, but unexpected behavior may pop up if more complex and unrealistic operations are executed by switching between the .Xr mfi 4 and .Nm drivers for MR-Fusion. Switching drivers is designed to happen only one time. Although multiple switching is possible, it is not recommended. The user should decide from .Nm Start of Day which driver they want to use for the MR-Fusion card. .Pp The user may see different device names when switching from .Xr mfi 4 to .Nm . This behavior is .Nm Functions As Designed and the user needs to change the .Xr fstab 5 entry manually if they are doing any experiments with .Xr mfi 4 and .Nm interoperability. .Sh FILES .Bl -tag -width ".Pa /dev/mrsas?" -compact .It Pa /dev/da? array/logical disk interface .It Pa /dev/mrsas? management interface .El .Sh SEE ALSO .Xr cam 4 , .Xr mfi 4 , .Xr pci 4 , .Xr device.hints 5 , .Xr camcontrol 8 .Sh HISTORY The .Nm driver first appeared in .Fx 10.1 . .Bd -ragged .Cd "mfi Driver:" .Xr mfi 4 is the old .Fx driver which started with support for Gen-1 Controllers and was extended to support up to MR-Fusion (Device ID = 0x005B, 0x005D, 0x005F). .Ed .Bd -ragged .Cd "mrsas Driver:" .Nm is the new driver reworked by LSI which supports Thunderbolt and onward products. The SAS+SATA RAID controller with device id 0x005b is referred to as the Thunderbolt controller throughout this man page. .Ed .Bd -ragged .Nm cam aware HBA drivers: .Fx has a .Xr cam 4 layer which attaches storage devices and provides a common access mechanism to storage controllers and attached devices. The .Nm driver is .Xr cam 4 aware and devices associated with .Nm can be seen using .Xr camcontrol 8 . The .Xr mfi 4 driver does not understand the .Xr cam 4 layer and it directly associates storage disks to the block layer. .Pp .Nm Thunderbolt Controller: This is the 6Gb/s MegaRAID HBA card which has device id 0x005B. .Pp .Nm Invader Controller: This is 12Gb/s MegaRAID HBA card which has device id 0x005D. .Pp .Nm Fury Controller: This is the 12Gb/s MegaRAID HBA card which has device id 0x005F. .Ed .Sh AUTHORS The .Nm driver and this manual page were written by .An Kashyap Desai Aq Mt Kashyap.Desai@lsi.com . .Sh TODO The driver does not support big-endian architectures at this time. .Pp The driver does not support alias for device name (it is required when the user switches between two drivers and does not want to edit .Pa /etc/fstab manually). .Pp The .Nm driver exposes devices as .Pa /dev/da? , whereas .Xr mfi 4 exposes devices as .Pa /dev/mfid? . .Pp .Nm does not support the Linux Emulator interface. .Pp .Nm will not work with .Xr mfiutil 8 . Index: head/share/man/man4/ng_pppoe.4 =================================================================== --- head/share/man/man4/ng_pppoe.4 (revision 366582) +++ head/share/man/man4/ng_pppoe.4 (revision 366583) @@ -1,576 +1,576 @@ .\" Copyright (c) 1996-1999 Whistle Communications, Inc. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, use and .\" redistribution of this software, in source or object code forms, with or .\" without modifications are expressly permitted by Whistle Communications; .\" provided, however, that: .\" 1. Any and all reproductions of the source or object code must include the .\" copyright notice above and the following disclaimer of warranties; and .\" 2. No rights are granted, in any manner or form, to use Whistle .\" Communications, Inc. trademarks, including the mark "WHISTLE .\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as .\" such appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY .\" OF SUCH DAMAGE. .\" .\" Author: Archie Cobbs .\" .\" $FreeBSD$ .\" $Whistle: ng_pppoe.8,v 1.1 1999/01/25 23:46:27 archie Exp $ .\" .Dd February 14, 2018 .Dt NG_PPPOE 4 .Os .Sh NAME .Nm ng_pppoe .Nd RFC 2516 PPPoE protocol netgraph node type .Sh SYNOPSIS .In sys/types.h .In net/ethernet.h .In netgraph.h .In netgraph/ng_pppoe.h .Sh DESCRIPTION The .Nm pppoe node type performs the PPPoE protocol. It is used in conjunction with the .Xr netgraph 4 extensions to the Ethernet framework to divert and inject Ethernet packets to and from a PPP agent (which is not specified). .Pp The .Dv NGM_PPPOE_GET_STATUS control message can be used at any time to query the current status of the PPPoE module. The only statistics presently available are the total packet counts for input and output. This node does not yet support the .Dv NGM_TEXT_STATUS control message. .Sh HOOKS This node type supports the following hooks: .Bl -tag -width ".Va [unspecified]" .It Va ethernet The hook that should normally be connected to an .Xr ng_ether 4 node. Once connected, .Nm will send a message down this hook to determine Ethernet address of the underlying node. Obtained address will be stored and then used for outgoing datagrams. .It Va debug Presently no use. .It Va [unspecified] Any other name is assumed to be a session hook that will be connected to a PPP client agent, or a PPP server agent. .El .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width 3n .It Dv NGM_PPPOE_GET_STATUS This command returns status information in a .Dv "struct ngpppoestat" : .Bd -literal -offset 4n struct ngpppoestat { u_int packets_in; /* packets in from Ethernet */ u_int packets_out; /* packets out towards Ethernet */ }; .Ed .It Dv NGM_TEXT_STATUS This generic message returns a human-readable version of the node status. (not yet) .It Dv NGM_PPPOE_CONNECT Pq Ic pppoe_connect Tell a nominated newly created hook that its session should enter the state machine as a client. It must be newly created and a service name can be given as an argument. It is legal to specify a zero-length service name, this is common on some DSL setups. It is possible to request a connection to a specific access concentrator, and/or set a specific Host-Uniq tag, required by some Internet providers, using the .Qq Li [AC-Name\\][Host-Uniq|]Service-Name syntax. To set a binary Host-Uniq, it must be encoded as a hexadecimal lowercase -string and prefixed with +string and prefixed with .Qq Li 0x , -for example +for example .Qq Li 0x6d792d746167 is equivalent to .Qq Li my-tag . A session request packet will be broadcast on the Ethernet. This command uses the .Dv ngpppoe_init_data structure shown below. For example, this init data argument can be used to connect to .Qq Li my-isp service with .Qq Li my-host uniq tag, accepting only .Qq Li remote-ac as access concentrator: .Bd -literal -offset indent "remote-ac\\my-host|my-isp" .Ed .It Dv NGM_PPPOE_LISTEN Pq Ic pppoe_listen Tell a nominated newly created hook that its session should enter the state machine as a server listener. The argument given is the name of the service to listen for. A zero-length service name will match all requests for service. A matching service request packet will be passed unmodified back to the process responsible for starting the service. It can then examine it and pass it on to the session that is started to answer the request. This command uses the .Dv ngpppoe_init_data structure shown below. .It Dv NGM_PPPOE_OFFER Pq Ic pppoe_offer Tell a nominated newly created hook that its session should enter the state machine as a server. The argument given is the name of the service to offer. A zero-length service is legal. The State machine will progress to a state where it will await a request packet to be forwarded to it from the startup server, which in turn probably received it from a LISTEN mode hook (see above). This is so that information that is required for the session that is embedded in the original session request packet, is made available to the state machine that eventually answers the request. When the Session request packet is received, the session negotiation will proceed. This command uses the .Dv ngpppoe_init_data structure shown below. .El .Pp The three commands above use a common data structure: .Bd -literal -offset 4n struct ngpppoe_init_data { char hook[NG_HOOKSIZ]; /* hook to monitor on */ uint16_t data_len; /* length of the service name */ char data[0]; /* init data goes here */ }; .Ed .Bl -tag -width 3n .It Dv NGM_PPPOE_SUCCESS Pq Ic pppoe_success This command is sent to the node that started this session with one of the above messages, and reports a state change. This message reports successful Session negotiation. It uses the structure shown below, and reports back the hook name corresponding to the successful session. .It Dv NGM_PPPOE_FAIL Pq Ic pppoe_fail This command is sent to the node that started this session with one of the above messages, and reports a state change. This message reports failed Session negotiation. It uses the structure shown below, and reports back the hook name corresponding to the failed session. The hook will probably have been removed immediately after sending this message. .It Dv NGM_PPPOE_CLOSE Pq Ic pppoe_close This command is sent to the node that started this session with one of the above messages, and reports a state change. This message reports a request to close a session. It uses the structure shown below, and reports back the hook name corresponding to the closed session. The hook will probably have been removed immediately after sending this message. At present this message is not yet used and a .Dv NGM_PPPOE_FAIL message will be received at closure instead. .It Dv NGM_PPPOE_ACNAME This command is sent to the node that started this session with one of the above messages, and reports the Access Concentrator Name. .El .Pp The four commands above use a common data structure: .Bd -literal -offset 4n struct ngpppoe_sts { char hook[NG_HOOKSIZ]; }; .Ed .Bl -tag -width 3n .It Dv NGM_PPPOE_GETMODE Pq Ic pppoe_getmode This command returns the current compatibility mode of the node as a string. .Tn ASCII form of this message is .Qq Li pppoe_getmode . The following keywords can be returned: .Bl -tag -width 3n .It Qq standard The node operates according to RFC 2516. .It Qq 3Com When .Nm is a PPPoE client, it initiates a session encapsulating packets into incorrect 3Com ethertypes. This compatibility option does not affect server mode. In server mode .Nm supports both modes simultaneously, depending on the ethertype, the client used when connecting. .It Qq D-Link When .Nm is a PPPoE server serving only specific Service-Name(s), it will respond to a PADI requests with empty Service-Name tag, returning all available Service-Name(s) on node. This option is necessary for compatibility with D-Link DI-614+ and DI-624+ SOHO routers as clients, when serving only specific Service-Name. This compatibility option does not affect client mode. .El .It Dv NGM_PPPOE_SETMODE Pq Ic pppoe_setmode Configure node to the specified mode. The string argument is required. This command understands the same keywords that are returned by the .Dv NGM_PPPOE_GETMODE command. .Tn ASCII form of this message is .Qq Li pppoe_setmode . For example, the following command will configure the node to initiate the next session in the proprietary 3Com mode: .Bd -literal -offset indent ngctl msg fxp0:orphans pppoe_setmode '"3Com"' .Ed .It Dv NGM_PPPOE_SETENADDR Pq Ic setenaddr Set the node Ethernet address for outgoing datagrams. This message is important when a node has failed to obtain an Ethernet address from its peer on the .Dv ethernet hook, or when user wants to override this address with another one. .Tn ASCII form of this message is .Qq Li setenaddr . .It Dv NGM_PPPOE_SETMAXP Pq Ic setmaxp Set the node PPP-Max-Payload value as described in RFC 4638. This message applies only to a client configuration. .Tn ASCII form of this message is .Qq Li setmaxp . .Pp Data structure returned to client is: .Bd -literal -offset 4n struct ngpppoe_maxp { char hook[NG_HOOKSIZ]; uint16_t data; }; .Ed .It Dv NGM_PPPOE_SEND_HURL Pq Ic send_hurl Tell a nominated hook with an active session to send a PADM message with a HURL tag. The argument is the URL to be delivered to the client: .Bd -literal -offset indent ngctl msg fxp0:orphans send_hurl '{ hook="myHook" data="http://example.net/cpe" }' .Ed .It Dv NGM_PPPOE_SEND_MOTM Pq Ic send_motm Tell a nominated hook with an active session to send a PADM message with a MOTM tag. The argument is the message to be delivered to the client: .Bd -literal -offset indent ngctl msg fxp0:orphans send_motm '{ hook="myHook" data="Welcome aboard" }' .Ed .El .Pp The two commands above use the same ngpppoe_init_data structure described above. .Bl -tag -width 3n .It Dv NGM_PPPOE_HURL This command is sent to the node that started this session when a PADM message with a HURL tag is received, and contains a URL that the host can pass to a web browser for presentation to the user. .It Dv NGM_PPPOE_MOTM This command is sent to the node that started this session when a PADM message with a MOTM tag is received, and contains a Message Of The Minute that the host can display to the user. .El .Pp The two commands above use a common data structure: .Bd -literal -offset 4n struct ngpppoe_padm { char msg[PPPOE_PADM_VALUE_SIZE]; }; .Ed .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, when all session have been disconnected or when the .Dv ethernet hook is disconnected. .Sh EXAMPLES The following code uses .Dv libnetgraph to set up a .Nm node and connect it to both a socket node and an Ethernet node. It can handle the case of when a .Nm node is already attached to the Ethernet. It then starts a client session. .Bd -literal #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include static int setup(char *ethername, char *service, char *sessname, int *dfd, int *cfd); int main() { int fd1, fd2; setup("xl0", NULL, "fred", &fd1, &fd2); sleep (30); } static int setup(char *ethername, char *service, char *sessname, int *dfd, int *cfd) { struct ngm_connect ngc; /* connect */ struct ngm_mkpeer mkp; /* mkpeer */ /******** nodeinfo stuff **********/ u_char rbuf[2 * 1024]; struct ng_mesg *const resp = (struct ng_mesg *) rbuf; struct hooklist *const hlist = (struct hooklist *) resp->data; struct nodeinfo *const ninfo = &hlist->nodeinfo; int ch, no_hooks = 0; struct linkinfo *link; struct nodeinfo *peer; /****message to connect PPPoE session*****/ struct { struct ngpppoe_init_data idata; char service[100]; } message; /********tracking our little graph ********/ char path[100]; char source_ID[NG_NODESIZ]; char pppoe_node_name[100]; int k; /* * Create the data and control sockets */ if (NgMkSockNode(NULL, cfd, dfd) < 0) { return (errno); } /* * find the ether node of the name requested by asking it for * it's inquiry information. */ if (strlen(ethername) > 16) return (EINVAL); sprintf(path, "%s:", ethername); if (NgSendMsg(*cfd, path, NGM_GENERIC_COOKIE, NGM_LISTHOOKS, NULL, 0) < 0) { return (errno); } /* * the command was accepted so it exists. Await the reply (It's * almost certainly already waiting). */ if (NgRecvMsg(*cfd, resp, sizeof(rbuf), NULL) < 0) { return (errno); } /** * The following is available about the node: * ninfo->name (string) * ninfo->type (string) * ninfo->id (uint32_t) * ninfo->hooks (uint32_t) (count of hooks) * check it is the correct type. and get it's ID for use * with mkpeer later. */ if (strncmp(ninfo->type, NG_ETHER_NODE_TYPE, strlen(NG_ETHER_NODE_TYPE)) != 0) { return (EPROTOTYPE); } sprintf(source_ID, "[%08x]:", ninfo->id); /* * look for a hook already attached. */ for (k = 0; k < ninfo->hooks; k++) { /** * The following are available about each hook. * link->ourhook (string) * link->peerhook (string) * peer->name (string) * peer->type (string) * peer->id (uint32_t) * peer->hooks (uint32_t) */ link = &hlist->link[k]; peer = &hlist->link[k].nodeinfo; /* Ignore debug hooks */ if (strcmp("debug", link->ourhook) == 0) continue; /* If the orphans hook is attached, use that */ if (strcmp(NG_ETHER_HOOK_ORPHAN, link->ourhook) == 0) { break; } /* the other option is the 'divert' hook */ if (strcmp("NG_ETHER_HOOK_DIVERT", link->ourhook) == 0) { break; } } /* * See if we found a hook there. */ if (k < ninfo->hooks) { if (strcmp(peer->type, NG_PPPOE_NODE_TYPE) == 0) { /* * If it's a type PPPoE, we skip making one * ourself, but we continue, using * the existing one. */ sprintf(pppoe_node_name, "[%08x]:", peer->id); } else { /* * There is already someone hogging the data, * return an error. Some day we'll try * daisy-chaining.. */ return (EBUSY); } } else { /* * Try make a node of type PPPoE against node "ID" * On hook NG_ETHER_HOOK_ORPHAN. */ snprintf(mkp.type, sizeof(mkp.type), "%s", NG_PPPOE_NODE_TYPE); snprintf(mkp.ourhook, sizeof(mkp.ourhook), "%s", NG_ETHER_HOOK_ORPHAN); snprintf(mkp.peerhook, sizeof(mkp.peerhook), "%s", NG_PPPOE_HOOK_ETHERNET); /* Send message */ if (NgSendMsg(*cfd, source_ID, NGM_GENERIC_COOKIE, NGM_MKPEER, &mkp, sizeof(mkp)) < 0) { return (errno); } /* * Work out a name for the new node. */ sprintf(pppoe_node_name, "%s:%s", source_ID, NG_ETHER_HOOK_ORPHAN); } /* * We now have a PPPoE node attached to the Ethernet * card. The Ethernet is addressed as ethername: The PPPoE * node is addressed as pppoe_node_name: attach to it. * Connect socket node to specified node Use the same hook * name on both ends of the link. */ snprintf(ngc.path, sizeof(ngc.path), "%s", pppoe_node_name); snprintf(ngc.ourhook, sizeof(ngc.ourhook), "%s", sessname); snprintf(ngc.peerhook, sizeof(ngc.peerhook), "%s", sessname); if (NgSendMsg(*cfd, ".:", NGM_GENERIC_COOKIE, NGM_CONNECT, &ngc, sizeof(ngc)) < 0) { return (errno); } #ifdef NONSTANDARD /* * In some cases we are speaking to 3Com hardware, so * configure node to non-standard mode. */ if (NgSendMsg(*cfd, ngc.path, NGM_PPPOE_COOKIE, NGM_PPPOE_SETMODE, NG_PPPOE_NONSTANDARD, strlen(NG_PPPOE_NONSTANDARD) + 1) == -1) { return (errno); } #endif /* * Send it a message telling it to start up. */ bzero(&message, sizeof(message)); snprintf(message.idata.hook, sizeof(message.idata.hook), "%s", sessname); if (service == NULL) { message.idata.data_len = 0; } else { snprintf(message.idata.data, sizeof(message.idata.data), "%s", service); message.idata.data_len = strlen(service); } /* Tell session/hook to start up as a client */ if (NgSendMsg(*cfd, ngc.path, NGM_PPPOE_COOKIE, NGM_PPPOE_CONNECT, &message.idata, sizeof(message.idata) + message.idata.data_len) < 0) { return (errno); } return (0); } .Ed .Sh SEE ALSO .Xr netgraph 3 , .Xr netgraph 4 , .Xr ng_ether 4 , .Xr ng_ppp 4 , .Xr ng_socket 4 , .Xr ngctl 8 , .Xr ppp 8 .Rs .%A L. Mamakos .%A K. Lidl .%A J. Evarts .%A D. Carrel .%A D. Simone .%A R. Wheeler .%T "A Method for transmitting PPP over Ethernet (PPPoE)" .%O RFC 2516 .Re .Sh HISTORY The .Nm node type was implemented in .Fx 4.0 . .Sh AUTHORS .An Julian Elischer Aq Mt julian@FreeBSD.org Index: head/share/man/man4/qlxgbe.4 =================================================================== --- head/share/man/man4/qlxgbe.4 (revision 366582) +++ head/share/man/man4/qlxgbe.4 (revision 366583) @@ -1,92 +1,92 @@ .\"- .\" Copyright (c) 2013 Qlogic Corportaion .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd April 1, 2013 .Dt QLXGBE 4 .Os .Sh NAME .Nm qlxgbe .Nd "QLogic 10 Gigabit Ethernet & CNA Adapter Driver" .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device qlxgbe" .Ed .Pp To load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent if_qlxgbe_load="YES" .Ed .Sh DESCRIPTION The .Nm driver supports IPv4 checksum offload, TCP and UDP checksum offload for both IPv4 and IPv6, Large Segment Offload for both IPv4 and IPv6, Jumbo frames, VLAN Tag, and Receive Side scaling, ability to select either HW or Software LRO, -when LRO is enabled (default HW LRO). +when LRO is enabled (default HW LRO). For further hardware information, see .Pa http://www.qlogic.com/ . .Sh HARDWARE The .Nm driver supports 10 Gigabit Ethernet & CNA Adapter based on the following chipsets: .Pp .Bl -bullet -compact .It QLogic 8300 series .El .Sh SUPPORT For support questions please contact your QLogic approved reseller or QLogic Technical Support at .Pa http://support.qlogic.com , or by E-mail at .Aq Mt support@qlogic.com . .Sh SEE ALSO .Xr altq 4 , .Xr arp 4 , .Xr netintro 4 , .Xr ng_ether 4 , .Xr ifconfig 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 10.0 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An David C Somayajulu at QLogic Corporation. Index: head/share/man/man4/rtwn.4 =================================================================== --- head/share/man/man4/rtwn.4 (revision 366582) +++ head/share/man/man4/rtwn.4 (revision 366583) @@ -1,246 +1,246 @@ .\" $OpenBSD: rtwn.4,v 1.2 2015/07/09 11:28:53 stsp Exp $ .\" .\" Copyright (c) 2010 Damien Bergamini .\" Copyright (c) 2015 Stefan Sperling .\" Copyright (c) 2016 Andriy Voskoboinyk .\" .\" 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. .\" .\" $FreeBSD$ .\" .Dd January 2, 2019 .Dt RTWN 4 .Os .Sh NAME .Nm rtwn .Nd Realtek IEEE 802.11 wireless network driver .Sh SYNOPSIS .Cd "options RTWN_DEBUG" .Cd "options RTWN_WITHOUT_UCODE" .Pp To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device rtwn" .Cd "device rtwnfw" .Cd "device rtwn_usb" .Cd "device rtwn_pci" .Cd "device wlan" .Cd "device firmware" .Ed .Pp Alternatively, to load the driver as a module at boot time, place following lines in .Xr loader.conf 5 : .Bd -literal -offset indent if_rtwn_pci_load="YES" if_rtwn_usb_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for wireless network devices based on the Realtek RTL8192C, RTL8188E, RTL8192E, RTL8812A and RTL8821A programming APIs. These APIs are used by a wide variety of chips; most chips with USB and some with PCI interface are supported. .Pp To enable use for PCI/PCIe systems, see the rtwn_pci(4) driver; for USB devices, use the rtwn_usb(4) driver. .Pp The driver supports .Cm station , .Cm adhoc , .Cm hostap and .Cm monitor mode operation. There are no limitations for number of .Cm monitor mode virtual interfaces; in addition to any other virtual interface one .Cm station interface can be added (Note: RTL8821AU supports two non-monitor mode interfaces at the same time). .Pp All chips have hardware support for WEP, AES-CCM and TKIP encryption. .Pp The .Nm driver can be configured at runtime with .Xr ifconfig 8 . .Sh FILES .Bl -tag -width ".Pa /usr/share/doc/legal/realtek.LICENSE" -compact .It Pa /usr/share/doc/legal/realtek.LICENSE .Nm firmware license .El .Pp The driver (if not compiled with .Cd options RTWN_WITHOUT_UCODE ) may use following firmware files, which are loaded when an interface is brought up: .Bl -tag -width Ds -offset indent -compact .It Pa /boot/kernel/rtwn-rtl8188eefw.ko .It Pa /boot/kernel/rtwn-rtl8188eufw.ko .It Pa /boot/kernel/rtwn-rtl8192cfwE_B.ko .It Pa /boot/kernel/rtwn-rtl8192cfwE.ko .It Pa /boot/kernel/rtwn-rtl8192cfwT.ko .It Pa /boot/kernel/rtwn-rtl8192cfwU.ko .It Pa /boot/kernel/rtwn-rtl8192eufw.ko .It Pa /boot/kernel/rtwn-rtl8812aufw.ko .It Pa /boot/kernel/rtwn-rtl8821aufw.ko .El .Sh EXAMPLES Join an existing BSS network (i.e., connect to an access point): .Bd -literal -offset indent ifconfig wlan create wlandev rtwn0 inet 192.168.0.20 \e netmask 0xffffff00 .Ed .Pp Join a specific BSS network with network name .Dq Li my_net : .Pp .Dl "ifconfig wlan create wlandev rtwn0 ssid my_net up" .Pp Join a specific BSS network with 64-bit WEP encryption: .Bd -literal -offset indent ifconfig wlan create wlandev rtwn0 ssid my_net \e wepmode on wepkey 0x1234567890 weptxkey 1 up .Ed .Pp Create an IBSS network with 128-bit WEP encryption on the channel 4: .Bd -literal -offset indent ifconfig wlan create wlandev rtwn0 wlanmode adhoc ssid my_net \e wepmode on wepkey 0x01020304050607080910111213 weptxkey 1 \e channel 4 .Ed .Pp Join/create an 802.11b IBSS network with network name .Dq Li my_net : .Bd -literal -offset indent ifconfig wlan0 create wlandev rtwn0 wlanmode adhoc ifconfig wlan0 inet 192.168.0.22 netmask 0xffffff00 ssid my_net \e mode 11b .Ed .Pp Create a host-based access point: .Bd -literal -offset indent ifconfig wlan0 create wlandev rtwn0 wlanmode hostap ifconfig wlan0 inet 192.168.0.10 netmask 0xffffff00 ssid my_ap .Ed .Sh LOADER TUNABLES Tunables can be set at the .Xr loader 8 prompt before booting the kernel or stored in .Xr loader.conf 5 . .Bl -tag -width indent .It Va dev.rtwn.%d.hwcrypto This tunable controls how key slots are assigned: .br -0 - disable h/w crypto support. Features that require access -to frame contents (e.g., TCP/UDP/IP Rx checksum validation) -will not work; +0 - disable h/w crypto support. +Features that require access to frame contents (e.g., TCP/UDP/IP Rx +checksum validation) will not work; .br 1 - use h/w crypto support for pairwise keys only; .br 2 - use h/w crypto support for all keys; may not work for multi-vap configurations. .br By default it is set to 1. .It Va dev.rtwn.%d.ratectl This tunable switches between rate control implementations: .br 0 - no rate control; .br 1 - driver sends 'tx complete' reports to net80211; algorithm is controlled via net80211; .br 2 - firmware-based rate control. .br By default it is set to 1; however driver may choose another algorithm in case if it is not implemented .br Currently selected algorithm is reported via .Em Va dev.rtwn.%d.ratectl_selected read-only OID. .It Va dev.rtwn.%d.rx_buf_size (USB only) Controls size of temporary Rx buffer; smaller buffer size may increase number of interrupts. .El .Sh DIAGNOSTICS .Bl -diag .It "rtwn%d: could not read efuse byte at address 0x%x" .It "rtwn%d: %s: cannot read rom, error %d" There was an error while reading ROM; device attach will be aborted. This should not happen. .It "rtwn%d: failed loadfirmware of file %s" For some reason, the driver was unable to read the microcode file from the filesystem. The file might be missing or corrupted. The driver will disable firmware-dependent features. .It "rtwn%d: wrong firmware size (%zu)" .It "rtwn%d: %s: failed to upload firmware %s (error %d)" .It "rtwn%d: timeout waiting for firmware readiness" Firmware upload failed; the file might be corrupted. The driver will disable firmware-dependent features. This should not happen. .It "rtwn%d: device timeout" A frame dispatched to the hardware for transmission did not complete in time. The driver will reset the hardware. This should not happen. .El .Sh SEE ALSO .Xr intro 4 , .Xr netintro 4 , .Xr rtwn_pci 4 , .Xr rtwn_usb 4 , .Xr rtwnfw 4 , .Xr wlan 4 , .Xr wlan_amrr 4 , .Xr wlan_ccmp 4 , .Xr wlan_tkip 4 , .Xr wlan_wep 4 , .Xr wlan_xauth 4 , .Xr hostapd 8 , .Xr ifconfig 8 , .Xr wpa_supplicant 8 .Sh HISTORY The .Cm urtwn driver first appeared in .Ox 4.9 and .Fx 10.0 ; the .Nm driver first appeared in .Ox 5.8 . .Sh AUTHORS The .Nm driver was initially written by .An -nosplit .An Stefan Sperling Aq Mt stsp@openbsd.org and ported by .An Kevin Lo Aq Mt kevlo@freebsd.org . It was based on the .Cm urtwn driver written by .An Damien Bergamini Aq Mt damien.bergamini@free.fr . .Sh BUGS The .Nm driver currently does not implement firmware-based rate control. Index: head/share/man/man4/sa.4 =================================================================== --- head/share/man/man4/sa.4 (revision 366582) +++ head/share/man/man4/sa.4 (revision 366583) @@ -1,409 +1,409 @@ .\" Copyright (c) 1996 .\" Julian Elischer . All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd May 5, 2017 .Dt SA 4 .Os .Sh NAME .Nm sa .Nd SCSI Sequential Access device driver .Sh SYNOPSIS .Cd device sa .Sh DESCRIPTION The .Nm driver provides support for all .Tn SCSI devices of the sequential access class that are attached to the system through a supported .Tn SCSI Host Adapter. The sequential access class includes tape and other linear access devices. .Pp A .Tn SCSI Host adapter must also be separately configured into the system before a .Tn SCSI sequential access device can be configured. .Sh MOUNT SESSIONS The .Nm driver is based around the concept of a .Dq Em mount session , which is defined as the period between the time that a tape is mounted, and the time when it is unmounted. Any parameters set during a mount session remain in effect for the remainder of the session or until replaced. The tape can be unmounted, bringing the session to a close in several ways. These include: .Bl -enum .It Closing a `rewind device', referred to as sub-mode 00 below. An example is .Pa /dev/sa0 . .It Using the MTOFFL .Xr ioctl 2 command, reachable through the .Sq Cm offline command of .Xr mt 1 . .El .Pp It should be noted that tape devices are exclusive open devices, except in the case where a control mode device is opened. In the latter case, exclusive access is only sought when needed (e.g., to set parameters). .Sh SUB-MODES Bits 0 and 1 of the minor number are interpreted as .Sq sub-modes . The sub-modes differ in the action taken when the device is closed: .Bl -tag -width XXXX .It 00 A close will rewind the device; if the tape has been written, then a file mark will be written before the rewind is requested. The device is unmounted. .It 01 A close will leave the tape mounted. If the tape was written to, a file mark will be written. No other head positioning takes place. Any further reads or writes will occur directly after the last read, or the written file mark. .It 10 A close will rewind the device. If the tape has been written, then a file mark will be written before the rewind is requested. On completion of the rewind an unload command will be issued. The device is unmounted. .El .Sh BLOCKING MODES .Tn SCSI tapes may run in either .Sq Em variable or .Sq Em fixed block-size modes. Most .Tn QIC Ns -type devices run in fixed block-size mode, where most nine-track tapes and many new cartridge formats allow variable block-size. The difference between the two is as follows: .Bl -inset .It Variable block-size: Each write made to the device results in a single logical record written to the tape. One can never read or write .Em part of a record from tape (though you may request a larger block and read a smaller record); nor can one read multiple blocks. Data from a single write is therefore read by a single read. The block size used may be any value supported by the device, the .Tn SCSI adapter and the system (usually between 1 byte and 64 Kbytes, sometimes more). .Pp When reading a variable record/block from the tape, the head is logically considered to be immediately after the last item read, and before the next item after that. If the next item is a file mark, but it was never read, then the next process to read will immediately hit the file mark and receive an end-of-file notification. .It Fixed block-size: Data written by the user is passed to the tape as a succession of fixed size blocks. It may be contiguous in memory, but it is considered to be a series of independent blocks. One may never write an amount of data that is not an exact multiple of the blocksize. One may read and write the same data as a different set of records. In other words, blocks that were written together may be read separately, and vice-versa. .Pp If one requests more blocks than remain in the file, the drive will encounter the file mark. As there is some data to return (unless there were no records before the file mark), the read will succeed, returning that data. The next read will return immediately with a value of 0. (As above, if the file mark is never read, it remains for the next process to read if in no-rewind mode.) .El .Sh BLOCK SIZES By default, the driver will NOT accept reads or writes to a tape device that are larger than may be written to or read from the mounted tape using a single write or read request. Because of this, the application author may have confidence that his wishes are respected in terms of the block size written to tape. For example, if the user tries to write a 256KB block to the tape, but the controller can handle no more than 128KB, the write will fail. The previous .Fx behavior, prior to .Fx 10.0, was to break up large reads or writes into smaller blocks when going to the tape. The problem with that behavior, though, is that it hides the actual on-tape block size from the application writer, at least in variable block mode. .Pp If the user would like his large reads and writes broken up into separate pieces, he may set the following loader tunables. Note that these tunables WILL GO AWAY in .Fx 11.0 . They are provided for transition purposes only. .Bl -tag -width 12 .It kern.cam.sa.allow_io_split .Pp This variable, when set to 1, will configure all .Nm devices to split large buffers into smaller pieces when needed. .It kern.cam.sa.%d.allow_io_split .Pp This variable, when set to 1, will configure the given .Nm unit to split large buffers into multiple pieces. This will override the global setting, if it exists. .El .Pp There are several .Xr sysctl 8 variables available to view block handling parameters: .Bl -tag -width 12 .It kern.cam.sa.%d.allow_io_split .Pp This variable allows the user to see, but not modify, the current I/O split setting. The user is not permitted to modify this setting so that there is no chance of behavior changing for the application while a tape is mounted. .It kern.cam.sa.%d.maxio .Pp This variable shows the maximum I/O size in bytes that is allowed by the combination of kernel tuning parameters (MAXPHYS, DFLTPHYS) and the capabilities of the controller that is attached to the tape drive. Applications may look at this value for a guide on how large an I/O may be permitted, but should keep in mind that the actual maximum may be restricted further by the tape drive via the .Tn SCSI READ BLOCK LIMITS command. .It kern.cam.sa.%d.cpi_maxio .Pp This variable shows the maximum I/O size supported by the controller, in bytes, that is reported via the CAM Path Inquiry CCB (XPT_PATH_INQ). If this is 0, that means that the controller has not reported a maximum I/O size. .El .Sh FILE MARK HANDLING The handling of file marks on write is automatic. If the user has written to the tape, and has not done a read since the last write, then a file mark will be written to the tape when the device is closed. If a rewind is requested after a write, then the driver assumes that the last file on the tape has been written, and ensures that there are two file marks written to the tape. The exception to this is that there seems to be a standard (which we follow, but do not understand why) that certain types of tape do not actually write two file marks to tape, but when read, report a `phantom' file mark when the last file is read. These devices include the QIC family of devices. (It might be that this set of devices is the same set as that of fixed block devices. This has not been determined yet, and they are treated as separate behaviors by the driver at this time.) .Sh PARAMETERS The .Nm driver supports a number of parameters. The user can query parameters using .Dq mt param -l (which uses the .Dv MTIOCPARAMGET ioctl) and the user can set parameters using -.Dq mt param -s +.Dq mt param -s (which uses the .Dv MTIOCPARAMSET ioctl). See .Xr mt 1 and .Xr mtio 4 for more details on the interface. .Pp Supported parameters: .Bl -tag -width 5n .It sili The default is 0. When set to 1, it sets the Suppress Incorrect Length Indicator (SILI) bit on tape reads. Tape drives normally return sense data (which contains the residual) when the application reads a block that is not the same length as the amount of data requested. The SILI bit suppresses that notification in most cases. See the SSC-5 spec (available at t10.org), specifically the section on the READ(6) command, for more information. .It eot_warn The default is 0. By default, the .Nm driver reports entering Programmable Early Warning, Early Warning and End of Media conditions by returning a write with 0 bytes written, and .Dv errno set to 0. -If +If .Va eot_warn is set to 1, the .Nm driver will set .Dv errno -to +to .Dv ENOSPC when it enters any of the out of space conditions. .It protection.protection_supported This is a read-only parameter, and is set to 1 if the tape drive supports protection information. .It protection.prot_method If protection is supported, set this to the desired protection method supported by the tape drive. As of SSC-5r03 (available at t10.org), the protection method values are: .Bl -tag -width 3n .It 0 No protection. .It 1 Reed-Solomon CRC, 4 bytes in length. .It 2 CRC32C, 4 bytes in length. .El .It protection.pi_length Length of the protection information, see above for lengths. .It protection.lbp_w If set to 1, enable logical block protection on writes. The CRC must be appended to the end of the block written to the tape driver. The tape drive will verify the CRC when it receives the block. .It protection.lbp_r If set to 1, enable logical block protection on reads. The CRC will be appended to the end of the block read from the tape driver. The application should verify the CRC when it receives the block. .It protection.rdbp If set to 1, enable logical block protection on the RECOVER BUFFERED DATA command. The .Nm driver does not currently use the RECOVER BUFFERED DATA command. .El .Sh IOCTLS The .Nm driver supports all of the ioctls of .Xr mtio 4 . .Sh FILES .Bl -tag -width /dev/[n][e]sa[0-9] -compact .It Pa /dev/[n][e]sa[0-9] general form: .It Pa /dev/sa0 Rewind on close .It Pa /dev/nsa0 No rewind on close .It Pa /dev/esa0 Eject on close (if capable) .It Pa /dev/sa0.ctl Control mode device (to examine state while another program is accessing the device, e.g.). .El .Sh DIAGNOSTICS The .Nm driver supports injecting End Of Media (EOM) notification to aid application development and testing. EOM is indicated to the application by returning the read or write with 0 bytes written. In addition, when EOM is injected, the tape position status will be updated to temporarily show Beyond of the Programmable Early Warning (BPEW) status. To see BPEW status, use the .Dv MTIOCEXTGET -ioctl, which is used by the -.Dq mt status +ioctl, which is used by the +.Dq mt status command. -To inject an EOM notification, set the +To inject an EOM notification, set the .Pp .Va kern.cam.sa.%d.inject_eom .Pp sysctl variable to 1. One EOM notification will be sent, BPEW status will be set for one position query, and then the driver state will be reset to normal. .Sh SEE ALSO .Xr mt 1 , .Xr cam 4 .Sh AUTHORS .An -nosplit The .Nm driver was written for the .Tn CAM .Tn SCSI subsystem by .An Justin T. Gibbs and .An Kenneth Merry . Many ideas were gleaned from the .Nm st device driver written and ported from .Tn Mach 2.5 by .An Julian Elischer . .Pp The owner of record for many years was .An Matthew Jacob . The current maintainer is .An Kenneth Merry .Sh BUGS This driver lacks many of the hacks required to deal with older devices. Many older .Tn SCSI-1 devices may not work properly with this driver yet. .Pp Additionally, certain tapes (QIC tapes mostly) that were written under .Fx 2.X are not automatically read correctly with this driver: you may need to explicitly set variable block mode or set to the blocksize that works best for your device in order to read tapes written under .Fx 2.X. .Pp Partitions are only supported for status information and location. It would be nice to add support for creating and editing tape partitions. Index: head/share/man/man4/smartpqi.4 =================================================================== --- head/share/man/man4/smartpqi.4 (revision 366582) +++ head/share/man/man4/smartpqi.4 (revision 366583) @@ -1,103 +1,103 @@ .\" Copyright (c) 2018 Murthy Bhat .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ stable/10/share/man/man4/smartpqi.4 195614 2017-01-11 08:10:18Z jkim $ .Dd April 6, 2018 .Dt SMARTPQI 4 .Os .Sh NAME .Nm smartpqi .Nd Microsemi smartpqi SCSI driver for PQI controllers .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd device pci .Cd device scbus .Cd device smartpqi .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 smartpqi_load="YES" .Ed .Sh DESCRIPTION The .Nm SCSI driver provides support for the new generation of PQI controllers from Microsemi. The .Nm driver is the first SCSI driver to implement the PQI queuing model. .Pp The .Nm driver will replace the aacraid driver for Adaptec Series 9 controllers. .Pp The .Pa /dev/smartpqi? device nodes provide access to the management interface of the controller. One node exists per installed card. .Sh HARDWARE Controllers supported by the .Nm driver include: .Pp .Bl -bullet -compact .It HPE Gen10 Smart Array Controller Family .It -OEM Controllers based on the Microsemi Chipset +OEM Controllers based on the Microsemi Chipset .El .Sh FILES .Bl -tag -width /boot/kernel/aac.ko -compact .It Pa /dev/smartpqi? smartpqi management interface .El .Sh SEE ALSO .Xr kld 4 , .Xr linux 4 , .Xr scsi 4 , .Xr kldload 8 , .Xr pass 4 , .Xr xpt 4 , .Xr loader.conf 5 , .Xr camcontrol 8 .Rs .%T "Microsemi Website" .%U http://www.microsemi.com/ .Re .Sh HISTORY The .Nm driver first appeared in .Fx 11.1 . .Sh AUTHORS .An Murthy Bhat .Aq murthy.bhat@microsemi.com .Sh BUGS The controller is not actually paused on suspend/resume. Index: head/share/man/man4/spigen.4 =================================================================== --- head/share/man/man4/spigen.4 (revision 366582) +++ head/share/man/man4/spigen.4 (revision 366583) @@ -1,207 +1,207 @@ .\" .\" Copyright (c) 2018 Ian Lepore .\" 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 ``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 BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd August 21, 2020 .Dt SPIGEN 4 .Os .Sh NAME .Nm spigen .Nd SPI generic I/O device driver .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device spi" .Cd "device spibus" .Cd "device spigen" .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 spigen_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides direct access to a slave device on the SPI bus. Each instance of a .Nm device is associated with a single chip-select line on the bus, and all I/O performed through that instance is done with that chip-select line asserted. .Pp SPI data transfers are inherently bi-directional; there are not separate -read and write operations. +read and write operations. When commands and data are sent to a device, data also comes back from the device, although in some cases the data may not be useful (or even documented or predictable for some devices). Likewise on a read operation, whatever data is in the buffer at the start of the operation is sent to (and typically ignored by) the device, with each outgoing byte then replaced in the buffer by the corresponding incoming byte. Thus, all buffers passed to the transfer functions are both input and output buffers. .Pp The .Nm driver provides access to the SPI slave device with the following .Xr ioctl 2 calls, defined in .In sys/spigenio.h : .Bl -tag -width indent .It Dv SPIGENIOC_TRANSFER Pq Vt "struct spigen_transfer" Transfer a command and optional associated data to/from the device, using the buffers described by the st_command and st_data fields in the .Vt spigen_transfer . Set .Vt st_data.iov_len to zero if there is no data associated with the command. .Bd -literal struct spigen_transfer { struct iovec st_command; struct iovec st_data; }; .Ed .It Dv SPIGENIOC_TRANSFER_MMAPPED Pq Vt "spigen_transfer_mmapped" Transfer a command and optional associated data to/from the device. The buffers for the transfer are a previously-mmap'd region. The length of the command and data within that region are described by the .Vt stm_command_length and .Vt stm_data_length fields of .Vt spigen_transfer_mmapped . If .Vt stm_data_length is non-zero, the data appears in the memory region immediately following the command (that is, at offset .Vt stm_command_length from the start of the mapped region). .Bd -literal struct spigen_transfer_mmapped { size_t stm_command_length; size_t stm_data_length; }; .Ed .It Dv SPIGENIOC_GET_CLOCK_SPEED Pq Vt uint32_t Get the maximum clock speed (bus frequency in Hertz) to be used when communicating with this slave device. .It Dv SPIGENIOC_SET_CLOCK_SPEED Pq Vt uint32_t Set the maximum clock speed (bus frequency in Hertz) to be used when communicating with this slave device. The setting remains in effect for subsequent transfers; it is not necessary to reset this before each transfer. The actual bus frequency may be lower due to hardware limitiations of the SPI bus controller device. .It Dv SPIGENIOC_GET_SPI_MODE Pq Vt uint32_t Get the SPI mode (clock polarity and phase) to be used when communicating with this device. .It Dv SPIGENIOC_SET_SPI_MODE Pq Vt uint32_t Set the SPI mode (clock polarity and phase) to be used when communicating with this device. The setting remains in effect for subsequent transfers; it is not necessary to reset this before each transfer. .El .Sh HINTS CONFIGURATION -On a +On a .Xr device.hints 5 based system, such as .Li MIPS , these values are configurable for .Nm : .Bl -tag -width indent .It Va hint.spigen.%d.at The spibus the .Nm instance is attached to. .It Va hint.spigen.%d.clock The maximum bus frequency to use when communicating with this device. Actual bus speed may be lower, depending on the capabilities of the SPI bus controller hardware. .It Va hint.spigen.%d.cs The chip-select number to assert when performing I/O for this device. Set the high bit (1 << 31) to invert the logic level of the chip select line. .It Va hint.spigen.%d.mode The SPI mode (0-3) to use when communicating with this device. .El .Sh FDT CONFIGURATION On an .Xr fdt 4 based system, the spigen device is defined as a slave device subnode of the SPI bus controller node. All properties documented in the .Va spibus.txt bindings document can be used with the .Nm device. The most commonly-used ones are documented below. .Pp The following properties are required in the .Nm device subnode: .Bl -tag -width indent .It Va compatible Must be the string "freebsd,spigen". .It Va reg Chip select address of device. .It Va spi-max-frequency The maximum bus frequency to use when communicating with this slave device. Actual bus speed may be lower, depending on the capabilities of the SPI bus controller hardware. .El .Pp The following properties are optional for the .Nm device subnode: .Bl -tag -width indent .It Va spi-cpha Empty property indicating the slave device requires shifted clock phase (CPHA) mode. .It Va spi-cpol Empty property indicating the slave device requires inverse clock polarity (CPOL) mode. .It Va spi-cs-high Empty property indicating the slave device requires chip select active high. .El .Sh FILES .Bl -tag -width -compact .It Pa /dev/spigen* .El .Sh SEE ALSO .Xr fdt 4 , .Xr device.hints 5 , .Xr spi 8 .Sh HISTORY The .Nm driver appeared in .Fx 11.0 . FDT support appeared in .Fx 11.2 . Index: head/share/man/man4/syscons.4 =================================================================== --- head/share/man/man4/syscons.4 (revision 366582) +++ head/share/man/man4/syscons.4 (revision 366583) @@ -1,633 +1,633 @@ .\" .\" Copyright (c) 1999 .\" Kazutaka YOKOTA .\" 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 as .\" the first lines of this file unmodified. .\" 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 ``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 BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd June 2, 2018 .Dt SYSCONS 4 .Os .Sh NAME .Nm syscons , .Nm sc .Nd the console driver .Sh SYNOPSIS .Cd "options MAXCONS=N" .Cd "options SC_ALT_MOUSE_IMAGE" .Cd "options SC_CUT_SEPCHARS=_characters_" .Cd "options SC_CUT_SPACES2TABS" .Cd "options SC_DFLT_TERM" .Cd "options SC_DISABLE_KDBKEY" .Cd "options SC_DISABLE_REBOOT" .Cd "options SC_HISTORY_SIZE=N" .Cd "options SC_MOUSE_CHAR=C" .Cd "options SC_NO_CUTPASTE" .Cd "options SC_NO_FONT_LOADING" .Cd "options SC_NO_HISTORY" .Cd "options SC_NO_PALETTE_LOADING" .Cd "options SC_NO_SUSPEND_VTYSWITCH" .Cd "options SC_NO_SYSMOUSE" .Cd "options SC_NO_TERM_DUMB" .Cd "options SC_NO_TERM_SC" .Cd "options SC_NO_TERM_SCTEKEN" .Cd "options SC_PIXEL_MODE" .Cd "options SC_TWOBUTTON_MOUSE" .Cd "options SC_NORM_ATTR=_attribute_" .Cd "options SC_NORM_REV_ATTR=_attribute_" .Cd "options SC_KERNEL_CONS_ATTR=_attribute_" .Cd "options SC_KERNEL_CONS_ATTRS=_attributes_" .Cd "options SC_KERNEL_CONS_REV_ATTR=_attribute_" .Cd "options SC_DFLT_FONT" .Cd "makeoptions SC_DFLT_FONT=_font_name_" .Cd "device sc" .Pp In .Pa /boot/device.hints : .Cd hint.sc.0.at="isa" .Cd hint.sc.0.vesa_mode=0x103 .Pp In .Pa /boot/loader.conf : .Cd kern.vty=sc .Sh DESCRIPTION The .Nm driver provides multiple virtual terminals. It resembles the SCO color console driver. .Pp The .Nm driver is implemented on top of the keyboard driver .Pq Xr atkbd 4 and the video card driver .Pq Xr vga 4 and so requires both of them to be configured in the system. .Pp There can be only one .Nm device defined in the system. .Ss Virtual Terminals The .Nm driver provides multiple virtual terminals which appear as if they were separate terminals. One virtual terminal is considered current and exclusively occupies the screen and the keyboard; the other virtual terminals are placed in the background. .Pp In order to use virtual terminals, they must be individually marked ``on'' in .Pa /etc/ttys so that .Xr getty 8 will recognize them to be active and run .Xr login 1 to let the user log in to the system. By default, only the first eight virtual terminals are activated in .Pa /etc/ttys . .Pp You press the .Dv Alt key and a switch key to switch between virtual terminals. The following table summarizes the correspondence between the switch key and the virtual terminal. .Bd -literal -offset indent Alt-F1 ttyv0 Alt-F7 ttyv6 Shift-Alt-F1 ttyva Alt-F2 ttyv1 Alt-F8 ttyv7 Shift-Alt-F2 ttyvb Alt-F3 ttyv2 Alt-F9 ttyv8 Shift-Alt-F3 ttyvc Alt-F4 ttyv3 Alt-F10 ttyv9 Shift-Alt-F4 ttyvd Alt-F5 ttyv4 Alt-F11 ttyva Shift-Alt-F5 ttyve Alt-F6 ttyv5 Alt-F12 ttyvb Shift-Alt-F6 ttyvf .Ed .Pp You can also use the ``nscr'' key (usually the .Dv PrintScreen key on the AT Enhanced keyboard) to cycle available virtual terminals. .Pp The default number of available virtual terminals is 16. This can be changed with the kernel configuration option .Dv MAXCONS (see below). .Pp Note that the X server usually requires a virtual terminal for display purposes, so at least one terminal must be left unused by .Xr getty 8 so that it can be used by the X server. .Ss Key Definitions and Function Key Strings The .Nm driver, in conjunction with the keyboard driver, allows the user to change key definitions and function key strings. The .Xr kbdcontrol 1 command will load a key definition file (known as ``keymap'' file), dump the current keymap, and assign a string to a function key. See .Xr keyboard 4 and .Xr kbdmap 5 for the keymap file. .Pp You may want to set the .Ar keymap variable in .Pa /etc/rc.conf.local to the desired keymap file so that it will be automatically loaded when the system starts up. .Ss Software Font For most modern video cards, e.g., VGA, the .Nm driver and the video card driver allow the user to change the font used on the screen. The .Xr vidcontrol 1 command can be used to load a font file from .Pa /usr/share/syscons/fonts . .Pp The font comes in various sizes: 8x8, 8x14 and 8x16. The 8x16 font is typically used for the VGA card in the 80-column-by-25-line mode. Other video modes may require different font sizes. It is better to always load all three sizes of the same font. .Pp You may set .Ar font8x8 , .Ar font8x14 and .Ar font8x16 variables in .Pa /etc/rc.conf to the desired font files so that they will be automatically loaded when the system starts up. .Pp Optionally you can specify a particular font file as the default. See the .Dv SC_DFLT_FONT option below. .Ss Screen Map If your video card does not support software fonts, you may still be able to achieve a similar effect by re-mapping the font built into your video card. Use .Xr vidcontrol 1 to load a screen map file which defines the mapping between character codes. .Ss Mouse Support and Copy-and-Paste You can use your mouse to copy text on the screen and paste it as if it was typed by hand. You must be running the mouse daemon .Xr moused 8 and enable the mouse cursor in the virtual terminal via .Xr vidcontrol 1 . .Pp Pressing mouse button 1 (usually the left button) will start selection. Releasing button 1 will end the selection process. The selected text will be marked by inverting foreground and background colors. You can press button 3 (usually the right button) to extend the selected region. The selected text is placed in the copy buffer and can be pasted at the cursor position by pressing button 2 (usually the middle button) as many times as you like. .Pp If your mouse has only two buttons, you may want to use the .Dv SC_TWOBUTTON_MOUSE option below to make the right button to paste the text. Alternatively you can make the mouse daemon emulate the middle button. See the man page for .Xr moused 8 for more details. .Ss Back Scrolling The .Nm driver allows the user to browse the output which has ``scrolled off'' the top of the screen. .Pp Press the ``slock'' key (usually .Dv ScrllLock / .Dv Scroll Lock or .Dv Pause on many keyboards) and the terminal is in the ``scrollback'' mode. It is indicated by the .Dv Scroll Lock LED. Use the arrow keys, the .Dv Page Up/Down keys and the .Dv Home/End keys to scroll buffered terminal output. Press the ``slock'' key again to get back to the normal terminal mode. .Pp The size of the scrollback buffer can be set by the .Dv SC_HISTORY_SIZE option described below. .Ss Screen Saver The .Nm driver can be made to put up the screen saver if the current virtual terminal is idle, that is, the user is not typing on the keyboard nor moving the mouse. See .Xr splash 4 and .Xr vidcontrol 1 for more details. .Sh DRIVER CONFIGURATION .Ss Kernel Configuration Options The following kernel configuration options control the .Nm driver. .Bl -tag -width MOUSE .It Dv MAXCONS=N This option sets the number of virtual terminals to .Fa N . The default value is 16. .It Dv SC_ALT_MOUSE_IMAGE This option selects the alternative way of displaying the mouse cursor in the virtual terminal. It may be expensive for some video cards to draw the arrow-shaped cursor, and you may want to try this option. However, the appearance of the alternative mouse cursor may not be very appealing. Note that if you use the .Dv SC_NO_FONT_LOADING option then you must also use this option if you wish to be able to use the mouse. .It Dv SC_CUT_SEPCHARS=_characters_ This options specifies characters that will be looked for when the driver searches for words boundaries when doing cut operation. By default, its value is .Qq Li \ex20 \(em a space character. .It Dv SC_CUT_SPACES2TABS This options instructs the driver to convert leading spaces into tabs when copying data into cut buffer. This might be useful to preserve indentation when copying tab-indented text. .It Dv SC_DFLT_TERM=_name_ This option specifies the name of the preferred terminal emulator. .It Dv SC_DISABLE_KDBKEY This option disables the ``debug'' key combination (by default, it is .Dv Alt-Esc , or .Dv Ctl-PrintScreen ) . It will prevent users from entering the kernel debugger (KDB) by pressing the key combination. KDB will still be invoked when the kernel panics or hits a break point if it is included in the kernel. If this option is not defined, this behavior may be controlled at runtime by the .Xr sysctl 8 variable .Va hw.syscons.kbd_debug . .It Dv SC_DISABLE_REBOOT This option disables the ``reboot'' key (by default, it is .Dv Ctl-Alt-Del ) , so that the casual user may not accidentally reboot the system. If this option is not defined, this behavior may be controlled at runtime by the .Xr sysctl 8 variable .Va hw.syscons.kbd_reboot . .It Dv SC_HISTORY_SIZE=N Sets the size of back scroll buffer to .Fa N lines. The default value is 100. .It Dv SC_MOUSE_CHAR=C Unless the .Dv SC_ALT_MOUSE_IMAGE option above is specified, the .Nm driver reserves four consecutive character codes in order to display the mouse cursor in the virtual terminals in some systems. This option specifies the first character code to .Fa C to be used for this purpose. The default value is 0xd0. A good candidate is 0x03. .It Dv SC_PIXEL_MODE Adds support for pixel (raster) mode console. This mode is useful on some laptop computers, but less so on most other systems, and it adds substantial amount of code to syscons. If this option is NOT defined, you can reduce the kernel size a lot. See the .Dv VESAMODE flag below. .It Dv SC_TWOBUTTON_MOUSE If you have a two button mouse, you may want to add this option to use the right button of the mouse to paste text. See .Sx Mouse Support and Copy-and-Paste above. .It Dv SC_NORM_ATTR=_attribute_ .It Dv SC_NORM_REV_ATTR=_attribute_ .It Dv SC_KERNEL_CONS_ATTR=_attribute_ .It Dv SC_KERNEL_CONS_ATTRS=_attributes_ .It Dv SC_KERNEL_CONS_REV_ATTR=_attribute_ These options will set the default colors. Available colors are defined in .In machine/pc/display.h . See .Sx EXAMPLES below. .Dv SC_KERNEL_CONS_ATTRS is a character string giving a sequence of attributes in binary format. The sequence will be repeated up to the number of CPUs. Beware that the string must not be null, since the kernel divides by its length. .It Dv SC_DFLT_FONT This option will specify the default font. Available fonts are: iso, iso2, koi8-r, koi8-u, cp437, cp850, cp865, cp866 and cp866u. 16-line, 14-line and 8-line font data will be compiled in. Without this option, the .Nm driver will use whatever font is already loaded in the video card, unless you explicitly load a software font at startup. See .Sx EXAMPLES below. .It Dv SC_NO_SUSPEND_VTYSWITCH This option, which is also available as .Xr loader 8 tunable and .Xr sysctl 8 variable .Va hw.syscons.sc_no_suspend_vtswitch , disables switching between virtual terminals (graphics <-> text) during suspend/resume (ACPI and APM). Use this option if your system is freezing when you are running X and trying to suspend. .El .Pp The following options will remove some features from the .Nm driver and save kernel memory. .Bl -tag -width MOUSE .It Dv SC_NO_CUTPASTE This option disables ``copy and paste'' operation in virtual terminals. .It Dv SC_NO_FONT_LOADING The .Nm driver can load software fonts on some video cards. This option removes this feature. Note that if you still wish to use the mouse with this option then you must also use the .Dv SC_ALT_MOUSE_IMAGE option. .It Dv SC_NO_HISTORY This option disables back-scrolling in virtual terminals. .\".It Dv SC_NO_PALETTE_LOADING .It Dv SC_NO_SYSMOUSE This option removes mouse support in the .Nm driver. The mouse daemon .Xr moused 8 will fail if this option is defined. This option implies the .Dv SC_NO_CUTPASTE option too. .It Dv SC_NO_TERM_DUMB .It Dv SC_NO_TERM_SC .It Dv SC_NO_TERM_SCTEKEN These options remove the .Qq dumb , .Qq sc , and -.Qq scteken +.Qq scteken terminal emulators, respectively. .El .Ss Driver Flags The following driver flags can be used to control the .Nm driver. Driver flags can be set with the .Cd hint.sc.0.flags tunable, either in .Pa /boot/device.hints , or else at the loader prompt (see .Xr loader 8 ) . .Bl -tag -width bit_0 .\".It bit 0 (VISUAL_BELL) .\"Uses the ``visual'' bell. .\"The screen will blink instead of generating audible sound. .\".It bit 1,2 (CURSOR_TYPE) .\"This option specifies the cursor appearance. .\"Possible values are: .\".Bl -tag -width TYPE -compact .\".It Dv 0 .\"normal block cursor .\".It Dv 2 .\"blinking block cursor .\".It Dv 4 .\"underline cursor .\".It Dv 6 .\"blinking underline (aka destructive) cursor .\".El .\".It bit 6 (QUIET_BELL) .\"This option suppresses the bell, whether audible or visual, .\"if it is rung in a background virtual terminal. .It 0x0080 (VESAMODE) This option puts the video card in the VESA mode specified by .Pa /boot/device.hints variable .Va vesa_mode during kernel initialization. Note that in order for this flag to work, the kernel must be compiled with the .Dv SC_PIXEL_MODE option explained above. A list of the available mode can be obtained via .Xr vidcontrol 1 . .\"Note also that the ``copy-and-paste'' function is not currently supported .\"in this mode and the mouse pointer will not be displayed. .It 0x0100 (AUTODETECT_KBD) This option instructs the syscons driver to periodically scan for a keyboard device if it is not currently attached to one. Otherwise, the driver only probes for a keyboard once during bootup. .El .Ss Loader Tunables These settings can be entered at the .Xr loader 8 prompt or in .Xr loader.conf 5 . .Bl -tag -width indent .It Va kern.vty When both .Nm and .Xr vt 4 have been compiled into the kernel, the one to use for the system console can be selected by setting this variable to .Ql sc or .Ql vt . The .Pa GENERIC kernel uses .Xr vt 4 when this value is not set. .El .Sh FILES .Bl -tag -width /usr/share/syscons/xxxxyyyyzzz -compact .It Pa /dev/console .It Pa /dev/consolectl .It Pa /dev/ttyv? virtual terminals .It Pa /etc/ttys terminal initialization information .It Pa /usr/share/syscons/fonts/* font files .It Pa /usr/share/syscons/keymaps/* key map files .It Pa /usr/share/syscons/scrmaps/* screen map files .El .Sh EXAMPLES As the .Nm driver requires the keyboard driver and the video card driver, the kernel configuration file should contain the following lines. .Bd -literal -offset indent device atkbdc device atkbd device vga device sc device splash .Ed .Pp You also need the following lines in .Pa /boot/device.hints for these drivers. .Bd -literal -offset indent hint.atkbdc.0.at="isa" hint.atkbdc.0.port="0x060" hint.atkbd.0.at="atkbdc" hint.atkbd.0.irq="1" hint.vga.0.at="isa" hint.sc.0.at="isa" .Ed .Pp If you do not intend to load the splash image or use the screen saver, the last line is not necessary, and can be omitted. .Pp Note that the keyboard controller driver .Nm atkbdc is required by the keyboard driver .Nm atkbd . .Pp The following lines will set the default colors. The normal text will be green on black background. The reversed text will be yellow on green background. Note that you cannot put any white space inside the quoted string, because of the current implementation of .Xr config 8 . .Pp .Dl "options SC_NORM_ATTR=(FG_GREEN|BG_BLACK)" .Dl "options SC_NORM_REV_ATTR=(FG_YELLOW|BG_GREEN)" .Pp The following lines will set the default colors of the kernel message. The kernel message will be printed bright red on black background. The reversed message will be black on red background. .Pp .Dl "options SC_KERNEL_CONS_ATTR=(FG_LIGHTRED|BG_BLACK)" .Dl "options SC_KERNEL_CONS_REV_ATTR=(FG_BLACK|BG_RED)" .Pp Provided .Dv SC_KERNEL_CONS_ATTR is not set, or is set to its default of bright white on black, the following line will set 4 red-ish colors for printing kernel messages in colors depending on the CPU. .Pp .Dl options SC_KERNEL_CONS_ATTRS=\e"\ex0c\ex04\ex40\ex0e\e" .Pp The default scheme is probably better for up to 8 CPUs. Use a long string to get unique colors for more than 8 CPUs. .Pp To turn off all per-CPU coloring of kernel messages, set SC_KERNEL_CONS_ATTR to a non-default value, or use the default in a pattern of length 1. .Pp .Dl options SC_KERNEL_CONS_ATTRS=\e"\ex0f\e" .Pp The following example adds the font files .Pa cp850-8x16.fnt , .Pa cp850-8x14.font and .Pa cp850-8x8.font to the kernel. .Pp .Dl "options SC_DFLT_FONT" .Dl "makeoptions SC_DFLT_FONT=cp850" .Dl "device sc" .\".Sh DIAGNOSTICS .Sh SEE ALSO .Xr kbdcontrol 1 , .Xr login 1 , .Xr vidcontrol 1 , .Xr atkbd 4 , .Xr atkbdc 4 , .Xr keyboard 4 , .Xr screen 4 , .Xr splash 4 , .Xr ukbd 4 , .Xr vga 4 , .Xr vt 4 , .Xr kbdmap 5 , .Xr rc.conf 5 , .Xr ttys 5 , .Xr config 8 , .Xr getty 8 , .Xr kldload 8 , .Xr moused 8 .Sh HISTORY The .Nm driver first appeared in .Fx 1.0 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An S\(/oren Schmidt Aq Mt sos@FreeBSD.org . This manual page was written by .An Kazutaka Yokota Aq Mt yokota@FreeBSD.org . .Sh CAVEATS The amount of data that is possible to insert from the cut buffer is limited by the .Brq Dv MAX_INPUT , a system limit on the number of bytes that may be stored in the terminal input queue - usually 1024 bytes (see .Xr termios 4 ) . .Sh BUGS This manual page is incomplete and urgently needs revision. Index: head/share/man/man4/udbp.4 =================================================================== --- head/share/man/man4/udbp.4 (revision 366582) +++ head/share/man/man4/udbp.4 (revision 366583) @@ -1,165 +1,165 @@ .\" Copyright (c) 1999 .\" Nick Hibma . All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd October 20, 2017 .Dt UDBP 4 .Os .Sh NAME .Nm udbp .Nd USB Double Bulk Pipe driver .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device udbp" .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 udbp_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for host-to-host cables that contain at least two bulk pipes (one for each direction). This typically includes cables branded for use with .Sy Windows USB Easy Transfer , and many cables based on the Prolific PL2xx1 series of USB bridge chips. A useful (but non-comprehensive) list of compatible USB host cables is listed in the .Sx SEE ALSO section below. .Pp .\" XXX The description of how to add netgraph to the kernel .\" is out of place here. It should be limited to the .\" netgraph(4) manpage only. However, that page does .\" not yet give instructions for kldload(8) for the .\" clueless. Working on it -- sheldonh It requires .Xr netgraph 4 to be available. This can be done either by adding .Cd "options NETGRAPH" to your kernel configuration file, or alternatively loading .Xr netgraph 4 as a module, either from .Pa /boot/loader.conf or from the command line, before the .Nm module. .Sh EXAMPLES .Dl options NETGRAPH .Dl device udbp .Pp Add the .Nm driver to the kernel. .Pp .Dl kldload netgraph .Dl kldload udbp .Pp Load the .Xr netgraph 4 module and then the .Nm driver. .Pp .Dl ngctl mkpeer udbp0: eiface data ether .Dl ifconfig ngeth0 ether aa:dd:xx:xx:xx .Dl ifconfig ngeth0 inet 169.254.x.x/16 .Pp Create a new Ethernet network interface node and connect its ether hook to the data hook of the .Nm driver. .Pp This enables FreeBSD to communicate with a Linux peer (e.g. using the .Sy plusb driver). The Linux node should be configured to prefer link-local IPv4 addresses (e.g. using Network Manager in Debian and Red Hat derived distributions). .Pp Whilst both FreeBSD and Linux are able to interoperate by loosely following CDC EEM 1.0 in their behaviour, neither implementation has been expressly designed to follow its specification. .Sh SEE ALSO .Xr netgraph 4 , .Xr ng_eiface 4 , .Xr ohci 4 , .Xr uhci 4 , .Xr usb 4 , .Xr ngctl 8 .\" .Rs -.%B Universal Serial Bus: Communications Class Subclass Specification for Ethernet Emulation Model Devices +.%B Universal Serial Bus: Communications Class Subclass Specification for Ethernet Emulation Model Devices .%N Revision 1.0 .%D February 2, 2005 .%I USB Implementers Forum, Inc. .%U http://www.usb.org/developers/docs/devclass_docs/CDC_EEM10.pdf .Re .\" .Rs .%B Total Commander: Supported cables for USB cable connection .%I Ghisler Software GmbH. .%U https://www.ghisler.com/cables/index.htm .Re .Sh CAVEATS The point-to-point nature and additional latency of USB host-host links makes them unsuitable as a "drop-in" replacement for an Ethernet LAN; for a USB 3.0 SuperSpeed cable, latency is comparable to 100BaseTX Ethernet (but often worse), with throughput comparable to 2.5GBASE-T. .Pp -However, their energy efficiency makes them attractive for embedded -applications. A Plugable PL27A1 cable claims 24mA of USB3 bus power, +However, their energy efficiency makes them attractive for embedded applications. +A Plugable PL27A1 cable claims 24mA of USB3 bus power, as compared to 150mA for a typical USB 3.0 to Gigabit Ethernet interface. .Sh HISTORY The .Nm driver first appeared in .Fx 5.0 . .Sh BUGS The .Nm driver does not support the special packets described in section 5.1 of the CDC EEM specification. .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Doug Ambrisko Aq Mt ambrisko@whistle.com , .An Julian Elischer Aq Mt julian@FreeBSD.org and .An Nick Hibma Aq Mt n_hibma@FreeBSD.org . .Pp This manual page was written by -.An Nick Hibma Aq Mt n_hibma@FreeBSD.org +.An Nick Hibma Aq Mt n_hibma@FreeBSD.org and updated by .An Bruce Simpson Aq Mt bms@FreeBSD.org . Index: head/share/man/man9/OF_finddevice.9 =================================================================== --- head/share/man/man9/OF_finddevice.9 (revision 366582) +++ head/share/man/man9/OF_finddevice.9 (revision 366583) @@ -1,74 +1,73 @@ .\" .\" Copyright (c) 2018 Oleksandr Tymoshenko .\" .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd April 9, 2018 .Dt OF_FINDDEVICE 9 .Os .Sh NAME .Nm OF_finddevice .Nd find node in device tree .Sh SYNOPSIS .In dev/ofw/ofw_bus.h .In dev/ofw/ofw_bus_subr.h .Ft phandle_t .Fn OF_finddevice "const char *path" .Sh DESCRIPTION -.Pp .Fn OF_finddevice returns the phandle for the node specified by the .Fa path . Returns -1 if the path cannot be found in the tree. -.Sh CAVEATS -The return value should only be checked with equality -operators (equal to, not equal to) and not relational comparison -(less than, greater than ). -There is a discrepancy between IEEE 1275 standard and -.Fx Ns 's -internal representation of a phandle: IEEE 1275 -requires the return value of this function to be -1 if the path -is not found. -But phandle_t is an unsigned type, so it cannot -be relationally compared with -1 or 0, this comparison -is always true or always false. .Sh EXAMPLES .Bd -literal phandle_t root, i2c; root = OF_finddevice("/"); i2c = OF_finddevice("/soc/axi/i2c@a0e0000"); if (i2c != -1) { ... } .Ed .Sh SEE ALSO .Xr OF_child 9 .Xr OF_parent 9 .Xr OF_peer 9 .Sh AUTHORS .An -nosplit This manual page was written by .An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org . +.Sh CAVEATS +The return value should only be checked with equality +operators (equal to, not equal to) and not relational comparison +(less than, greater than ). +There is a discrepancy between IEEE 1275 standard and +.Fx Ns 's +internal representation of a phandle: IEEE 1275 +requires the return value of this function to be -1 if the path +is not found. +But phandle_t is an unsigned type, so it cannot +be relationally compared with -1 or 0, this comparison +is always true or always false. Index: head/share/man/man9/backlight.9 =================================================================== --- head/share/man/man9/backlight.9 (revision 366582) +++ head/share/man/man9/backlight.9 (revision 366583) @@ -1,77 +1,77 @@ .\" Copyright (c) 2020 Emmanuel Vadot .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" -.Dd October 02, 2020 +.Dd October 2, 2020 .Dt BACKLIGHT 9 .Os .Sh NAME .Nm backlight , .Nm backlight_register , .Nm backlight_destroy , .Nm BACKLIGHT_GET_STATUS , .Nm BACKLIGHT_SET_STATUS , .Nd BACKLIGHT methods .Sh SYNOPSIS .Cd "device backlight" .In "backlight_if.h" .In "sys/sys/backlight.h" .Ft int .Fn BACKLIGHT_GET_STATUS "device_t bus" "struct backlight_props *props" .Ft int .Fn BACKLIGHT_SET_STATUS "device_t bus" "struct backlight_props *props" .Ft struct cdev * .Fn backlight_register "const char *name" "device_t dev" .Ft int .Fn backlight_destroy "struct cdev *cdev" .Sh DESCRIPTION The backlight driver provides a generic way for handling a panel backlight. .Pp Drivers for backlight system register themselves globally using the .Fn backlight_register function. They must define two methods, .Fn BACKLIGHT_GET_STATUS which is used to query the current brightness level and .Fn BACKLIGHT_SET_STATUS which is used to update it. .Sh INTERFACE .Bl -tag -width indent .It Fn BACKLIGHT_GET_STATUS "device_t bus" "struct backlight_props *props" Driver fills the current brightless level and the optional supported levels. .It Fn BACKLIGHT_SET_STATUS "device_t bus" "struct backlight_props *props" Driver update the backlight level based on the brightness member of the props struct. .El .Sh FILES .Bl -tag -width "/dev/backlight/*" .It Pa /dev/backlight/* .Sh HISTORY The .Nm backlight interface first appear in .Fx 13.0 . The .Nm backlight driver and manual page was written by .An Emmanuel Vadot Aq Mt manu@FreeBSD.org . Index: head/share/man/man9/vnet.9 =================================================================== --- head/share/man/man9/vnet.9 (revision 366582) +++ head/share/man/man9/vnet.9 (revision 366583) @@ -1,519 +1,518 @@ .\"- .\" Copyright (c) 2010 The FreeBSD Foundation .\" All rights reserved. .\" .\" This documentation was written by CK Software GmbH 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. .\" .\" $FreeBSD$ .\" .Dd July 24, 2018 .Dt VNET 9 .Os .Sh NAME .Nm VNET .Nd "network subsystem virtualization infrastructure" .Sh SYNOPSIS .Cd "options VIMAGE" .Cd "options VNET_DEBUG" .Pp .In sys/vnet.h -.Pp .\"------------------------------------------------------------ .Ss "Constants and Global Variables" .\" .Dv VNET_SETNAME .\" "set_vnet" .Dv VNET_SYMPREFIX .\" "vnet_entry_" .Vt extern struct vnet *vnet0; .\"------------------------------------------------------------ .Ss "Variable Declaration" .Fo VNET .Fa "name" .Fc .\" .Fo VNET_NAME .Fa "name" .Fc .\" .Fo VNET_DECLARE .Fa "type" "name" .Fc .\" .Fo VNET_DEFINE .Fa "type" "name" .Fc .\" .Fo VNET_DEFINE_STATIC .Fa "type" "name" .Fc .\" .Bd -literal #define V_name VNET(name) .Ed .\" ------------------------------------------------------------ .Ss "Virtual Instance Selection" .\" .Fo CRED_TO_VNET .Fa "struct ucred *" .Fc .\" .Fo TD_TO_VNET .Fa "struct thread *" .Fc .\" .Fo P_TO_VNET .Fa "struct proc *" .Fc .\" .Fo IS_DEFAULT_VNET .Fa "struct vnet *" .Fc .\" .Fo VNET_ASSERT .Fa exp msg .Fc .\" .Fo CURVNET_SET .Fa "struct vnet *" .Fc .\" .Fo CURVNET_SET_QUIET .Fa "struct vnet *" .Fc .\" .Fn CURVNET_RESTORE .\" .Fo VNET_ITERATOR_DECL .Fa "struct vnet *" .Fc .\" .Fo VNET_FOREACH .Fa "struct vnet *" .Fc .\" ------------------------------------------------------------ .Ss "Locking" .\" .Fn VNET_LIST_RLOCK .Fn VNET_LIST_RUNLOCK .Fn VNET_LIST_RLOCK_NOSLEEP .Fn VNET_LIST_RUNLOCK_NOSLEEP .\" ------------------------------------------------------------ .Ss "Startup and Teardown Functions" .\" .Ft "struct vnet *" .Fo vnet_alloc .Fa void .Fc .\" .Ft void .Fo vnet_destroy .Fa "struct vnet *" .Fc .\" .Fo VNET_SYSINIT .Fa ident .Fa "enum sysinit_sub_id subsystem" .Fa "enum sysinit_elem_order order" .Fa "sysinit_cfunc_t func" .Fa "const void *arg" .Fc .\" .Fo VNET_SYSUNINIT .Fa ident .Fa "enum sysinit_sub_id subsystem" .Fa "enum sysinit_elem_order order" .Fa "sysinit_cfunc_t func" .Fa "const void *arg" .Fc .\" ------------------------------------------------------------ .Ss "Eventhandlers" .\" .Fo VNET_GLOBAL_EVENTHANDLER_REGISTER .Fa "const char *name" .Fa "void *func" .Fa "void *arg" .Fa "int priority" .Fc .\" .Fo VNET_GLOBAL_EVENTHANDLER_REGISTER_TAG .Fa "eventhandler_tag tag" .Fa "const char *name" .Fa "void *func" .Fa "void *arg" .Fa "int priority" .Fc .\" ------------------------------------------------------------ .Ss "Sysctl Handling" .Fo SYSCTL_VNET_INT .Fa parent nbr name access ptr val descr .Fc .Fo SYSCTL_VNET_PROC .Fa parent nbr name access ptr arg handler fmt descr .Fc .Fo SYSCTL_VNET_STRING .Fa parent nbr name access arg len descr .Fc .Fo SYSCTL_VNET_STRUCT .Fa parent nbr name access ptr type descr .Fc .Fo SYSCTL_VNET_UINT .Fa parent nbr name access ptr val descr .Fc .Fo VNET_SYSCTL_ARG .Fa req arg1 .Fc .\" ------------------------------------------------------------ .Sh DESCRIPTION .Nm is the name of a technique to virtualize the network stack. The basic idea is to change global resources most notably variables into per network stack resources and have functions, sysctls, eventhandlers, etc. access and handle them in the context of the correct instance. Each (virtual) network stack is attached to a .Em prison , with .Vt vnet0 being the unrestricted default network stack of the base system. .Pp The global defines for .Dv VNET_SETNAME and .Dv VNET_SYMPREFIX are shared with .Xr kvm 3 to access internals for debugging reasons. .\" ------------------------------------------------------------ .Ss "Variable Declaration" .\" Variables are virtualized by using the .Fn VNET_DEFINE macro rather than writing them out as .Em type name . One can still use static initialization, e.g., .Pp .Dl Li VNET_DEFINE(int, foo) = 1; .Pp Variables declared with the static keyword can use the .Fn VNET_DEFINE_STATIC macro, e.g., .Pp .Dl Li VNET_DEFINE_STATIC(SLIST_HEAD(, bar), bars); .Pp Static initialization is not possible when the virtualized variable would need to be referenced, e.g., with .Dq TAILQ_HEAD_INITIALIZER() . In that case a .Fn VNET_SYSINIT based initialization function must be used. .Pp External variables have to be declared using the .Fn VNET_DECLARE macro. In either case the convention is to define another macro, that is then used throughout the implementation to access that variable. The variable name is usually prefixed by .Em V_ to express that it is virtualized. The .Fn VNET macro will then translate accesses to that variable to the copy of the currently selected instance (see the .Sx "Virtual instance selection" section): .Pp .Dl Li #define V_name VNET(name) .Pp .Em NOTE: Do not confuse this with the convention used by .Xr VFS 9 . .Pp The .Fn VNET_NAME macro returns the offset within the memory region of the virtual network stack instance. It is usually only used with .Fn SYSCTL_VNET_* macros. .\" ------------------------------------------------------------ .Ss "Virtual Instance Selection" .\" There are three different places where the current virtual network stack pointer is stored and can be taken from: .Bl -enum -offset indent .It a .Em prison : .Dl "(struct prison *)->pr_vnet" .Pp For convenience the following macros are provided: .Bd -literal -compact -offset indent .Fn CRED_TO_VNET "struct ucred *" .Fn TD_TO_VNET "struct thread *" .Fn P_TO_VNET "struct proc *" .Ed .It a .Em socket : .Dl "(struct socket *)->so_vnet" .It an .Em interface : .Dl "(struct ifnet *)->if_vnet" .El .Pp .\" In addition the currently active instance is cached in .Dq "curthread->td_vnet" which is usually only accessed through the .Dv curvnet macro. .Pp .\" To set the correct context of the current virtual network instance, use the .Fn CURVNET_SET or .Fn CURVNET_SET_QUIET macros. The .Fn CURVNET_SET_QUIET version will not record vnet recursions in case the kernel was compiled with .Cd "options VNET_DEBUG" and should thus only be used in well known cases, where recursion is unavoidable. Both macros will save the previous state on the stack and it must be restored with the .Fn CURVNET_RESTORE macro. .Pp .Em NOTE: As the previous state is saved on the stack, you cannot have multiple .Fn CURVNET_SET calls in the same block. .Pp .Em NOTE: As the previous state is saved on the stack, a .Fn CURVNET_RESTORE call has to be in the same block as the .Fn CURVNET_SET call or in a subblock with the same idea of the saved instances as the outer block. .Pp .Em NOTE: As each macro is a set of operations and, as previously explained, cannot be put into its own block when defined, one cannot conditionally set the current vnet context. The following will .Em not work: .Bd -literal -offset indent if (condition) CURVNET_SET(vnet); .Ed .Pp nor would this work: .Bd -literal -offset indent if (condition) { CURVNET_SET(vnet); } CURVNET_RESTORE(); .Ed .Pp .\" Sometimes one needs to loop over all virtual instances, for example to update virtual from global state, to run a function from a .Xr callout 9 for each instance, etc. For those cases the .Fn VNET_ITERATOR_DECL and .Fn VNET_FOREACH macros are provided. The former macro defines the variable that iterates over the loop, and the latter loops over all of the virtual network stack instances. See .Sx "Locking" for how to savely traverse the list of all virtual instances. .Pp .\" The .Fn IS_DEFAULT_VNET macro provides a safe way to check whether the currently active instance is the unrestricted default network stack of the base system .Pq Vt vnet0 . .Pp .\" The .Fn VNET_ASSERT macro provides a way to conditionally add assertions that are only active with .Cd "options VIMAGE" compiled in and either .Cd "options VNET_DEBUG" or .Cd "options INVARIANTS" enabled as well. It uses the same semantics as .Xr KASSERT 9 . .\" ------------------------------------------------------------ .Ss "Locking" .\" For public access to the list of virtual network stack instances e.g., by the .Fn VNET_FOREACH macro, read locks are provided. Macros are used to abstract from the actual type of the locks. If a caller may sleep while traversing the list, it must use the .Fn VNET_LIST_RLOCK and .Fn VNET_LIST_RUNLOCK macros. Otherwise, the caller can use .Fn VNET_LIST_RLOCK_NOSLEEP and .Fn VNET_LIST_RUNLOCK_NOSLEEP . .\" ------------------------------------------------------------ .Ss "Startup and Teardown Functions" .\" To start or tear down a virtual network stack instance the internal functions .Fn vnet_alloc and .Fn vnet_destroy are provided and called from the jail framework. They run the publicly provided methods to handle network stack startup and teardown. .Pp For public control, the system startup interface has been enhanced to not only handle a system boot but to also handle a virtual network stack startup and teardown. To the base system the .Fn VNET_SYSINIT and .Fn VNET_SYSUNINIT macros look exactly as if there were no virtual network stack. In fact, if .Cd "options VIMAGE" is not compiled in they are compiled to the standard .Fn SYSINIT macros. In addition to that they are run for each virtual network stack when starting or, in reverse order, when shutting down. .\" ------------------------------------------------------------ .Ss "Eventhandlers" .\" Eventhandlers can be handled in two ways: .Pp .Bl -enum -offset indent -compact .It save the .Em tags returned in each virtual instance and properly free the eventhandlers on teardown using those, or .It use one eventhandler that will iterate over all virtual network stack instances. .El .Pp For the first case one can just use the normal .Xr EVENTHANDLER 9 functions, while for the second case the .Fn VNET_GLOBAL_EVENTHANDLER_REGISTER and .Fn VNET_GLOBAL_EVENTHANDLER_REGISTER_TAG macros are provided. These differ in that .Fn VNET_GLOBAL_EVENTHANDLER_REGISTER_TAG takes an extra first argument that will carry the .Fa "tag" upon return. Eventhandlers registered with either of these will not run .Fa func directly but .Fa func will be called from an internal iterator function for each vnet. Both macros can only be used for eventhandlers that do not take additional arguments, as the variadic arguments from an .Xr EVENTHANDLER_INVOKE 9 call will be ignored. .\" ------------------------------------------------------------ .Ss "Sysctl Handling" .\" A .Xr sysctl 9 can be virtualized by using one of the .Fn SYSCTL_VNET_* macros. .Pp They take the same arguments as the standard .Xr sysctl 9 functions, with the only difference, that the .Fa ptr argument has to be passed as .Ql &VNET_NAME(foo) instead of .Ql &foo so that the variable can be selected from the correct memory region of the virtual network stack instance of the caller. .Pp For the very rare case a sysctl handler function would want to handle .Fa arg1 itself the .Fn VNET_SYSCTL_ARG req arg1 is provided that will translate the .Fa arg1 argument to the correct memory address in the virtual network stack context of the caller. .\" ------------------------------------------------------------ .Sh SEE ALSO .Xr jail 2 , .Xr kvm 3 , .Xr EVENTHANDLER 9 , .\" .Xr pcpu 9 , .Xr KASSERT 9 , .Xr sysctl 9 .\" .Xr SYSINIT 9 .Pp Marko Zec, Implementing a Clonable Network Stack in the FreeBSD Kernel, USENIX ATC'03, June 2003, Boston .Sh HISTORY The virtual network stack implementation first appeared in .Fx 8.0 . .Sh AUTHORS .An -nosplit The .Nm framework was designed and implemented at the University of Zagreb by .An Marko Zec under sponsorship of the FreeBSD Foundation and NLnet Foundation, and later extended and refined by .An Bjoern A. Zeeb (also under FreeBSD Foundation sponsorship), and .An Robert Watson . .Pp This manual page was written by .An Bjoern A. Zeeb, CK Software GmbH, under sponsorship from the FreeBSD Foundation. Index: head/usr.bin/dpv/dpv.1 =================================================================== --- head/usr.bin/dpv/dpv.1 (revision 366582) +++ head/usr.bin/dpv/dpv.1 (revision 366583) @@ -1,433 +1,434 @@ .\" Copyright (c) 2013-2016 Devin Teske .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd January 26, 2016 .Dt DPV 1 .Os .Sh NAME .Nm dpv .Nd stream data from stdin or multiple paths with dialog progress view .Sh SYNOPSIS .Nm .Op options .Ar [bytes:]label .Nm .Op options .Fl m .Ar [bytes1:]label1 .Ar path1 .Op Ar [bytes2:]label2 path2 ... .Sh DESCRIPTION .Nm provides a dialog progress view, allowing a user to see current throughput rate and total data transferred for one or more streams. .Pp The .Nm utility has two main modes for processing input. .Pp The default input mode, without .Ql Fl m , .Nm reads bytes from standard input. A label for the data must be provided. .Pp The secondary input mode, with .Ql Fl m , .Nm reads multiple paths .Pq up to 2047 or Dq ARG_MAX/2-1 , sequentially. .Pp Data read in either mode is either thrown away .Pq default , sent to a spawned instance of the program specified via .Ql Fl x Ar cmd , or sent to a unique file specified by .Ql Fl o Ar file . .Pp With or without .Ql Fl m , progress is displayed using one of .Xr dialog 3 .Pq default , .Xr dialog 1 .Pq see Ql Fl D , or instead .Xr Xdialog 1 .Pq see Ql Fl X . .Pp The following options are available: .Bl -tag -width ".Fl b Ar backtitle" .It Fl a Ar text Display .Ar text below the file progress indicator(s). .It Fl b Ar backtitle Display .Ar backtitle on the backdrop, at top-left, behind the dialog widget. When using .Xr Xdialog 1 , this is displayed inside the window .Pq at the top followed by a separator line. .It Fl d Debug mode. Print dialog prompt data to standard out and provide additional debugging on standard error. .It Fl D Do not use the default interface of .Xr dialog 3 , but instead spawn an instance of .Xr dialog 1 . The path to .Xr dialog 1 is taken from the .Ev DIALOG environment variable or simply .Dq Li dialog if unset or NULL. .It Fl h Produce a short syntax usage with brief option descriptions and exit. Output is produced on standard error. .It Fl i Ar format Customize the single-file format string used to update the status line. Ignored when using either .Ql Fl D or .Ql Fl X which lack the ability to display the status line .Pq containing bytes/rate/thread information . Default value is .Dq Li %'10lli bytes read @ %'9.1f bytes/sec. . This format is used when handling one file. .It Fl I Ar format Customize the multi-file format string used to update the status line. Ignored when using either .Ql Fl D or .Ql Fl X which lack the ability to display the status line .Pq containing bytes/rate/thread information . Default value is .Dq Li %'10lli bytes read @ %'9.1f bytes/sec. [%i/%i busy/wait] . This format is used when handling more than one file. .It Fl k Keep tite. Prevent visually distracting initialization/exit routines for scripts running .Xr dialog 1 several times. .It Fl l -Line mode. Read lines from input instead of bytes. +Line mode. +Read lines from input instead of bytes. .It Fl L Ar size Label size. If negative, shrink to longest label width. .It Fl m Multi-input mode. Instead of reading bytes from standard input, read from a set of paths .Pq one for each label . By default, each path is processed sequentially in the order given. .It Fl n Ar num Display at-most .Ar num progress indicators per screen. If zero, display as many as possible. If negative, only display the main progress indicator. Default is 0. Maximum value is 10. .It Fl N No overrun. If enabled, stop reading known-length inputs when input reaches stated length. .It Fl o Ar file Output data to .Ar file . The first occurrence of .Ql %s .Pq if any in .Ql Ar file will be replaced with the .Ar label text. .It Fl p Ar text Display .Ar text above the file progress indicator(s). .It Fl P Ar size Mini-progressbar size. If negative, don't display mini-progressbars .Pq only the large overall progress indicator is shown . If zero, auto-adjust based on number of files to read. When zero and only one file to read, defaults to -1. When zero and more than one file to read, defaults to 17. .It Fl t Ar title Display .Ar title atop the dialog box. Note that if you use this option at the same time as .Ql Fl X and .Ql Fl b Ar backtitle , the .Ar backtitle and .Ar title are effectively switched .Pq see BUGS section below . .It Fl T Test mode. Simulate reading a number of bytes, divided evenly across the number of files, while stepping through each percent value of each file to process. Appends .Dq Li [TEST MODE] to the status line .Pq to override, use Ql Fl u Ar format . No data is actually read. .It Fl U Ar num Update status line .Ar num times per-second. Default value is .Ql Li 2 . A value of .Ql Li 0 disables status line updates. If negative, update the status line as fast as possible. Ignored when using either .Ql Fl D or .Ql Fl X which lack the ability to display the status line .Pq containing bytes/rate/thread information . .It Fl w Wide mode. Allows long .Ar text arguments used with .Ql Fl p and .Ql Fl a to bump the dialog width. Prompts wider than the maximum width will wrap .Pq unless using Xr Xdialog 1 ; see BUGS section below . .It Fl x Ar cmd Execute .Ar cmd .Pq via Xr sh 1 and send it data that has been read. Data is available to .Ar cmd on standard input. With .Ql Fl m , .Ar cmd is executed once for each .Ar path argument. The first occurrence of .Ql %s .Pq if any in .Ql Ar cmd will be replaced with the .Ar label text. .It Fl X Enable X11 mode by using .Xr Xdialog 1 instead of .Xr dialog 1 or .Xr dialog 3 . .El .Sh ENVIRONMENT The following environment variables are referenced by .Nm : .Bl -tag -width ".Ev USE_COLOR" .It Ev DIALOG Override command string used to launch .Xr dialog 1 .Pq requires Ql Fl D or .Xr Xdialog 1 .Pq requires Ql Fl X ; default is either .Ql dialog .Pq for Ql Fl D or .Ql Xdialog .Pq for Ql Fl X . .It Ev DIALOGRC If set and non-NULL, path to .Ql .dialogrc file. .It Ev HOME If .Ql Ev $DIALOGRC is either not set or NULL, used as a prefix to .Ql .dialogrc .Pq i.e., Ql $HOME/.dialogrc . .It Ev USE_COLOR If set and NULL, disables the use of color when using .Xr dialog 1 .Pq does not apply to Xr Xdialog 1 . .El .Sh DEPENDENCIES If using .Ql Fl D , .Xr dialog 1 is required. .Pp If using .Ql Fl X , .Xr Xdialog 1 is required. .Sh FILES .Bl -tag -width ".Pa $HOME/.dialogrc" -compact .It Pa $HOME/.dialogrc .El .Sh EXAMPLES Simple example to show how fast .Xr yes 1 produces lines .Pq usually about ten-million per-second; your results may vary : .Bd -literal -offset indent yes | dpv -l yes .Ed .Pp Display progress while timing how long it takes .Xr yes 1 to produce a half-billion lines .Pq usually under one minute; your results may vary : .Bd -literal -offset indent time yes | dpv -Nl 500000000:yes .Ed .Pp An example to watch how quickly a file is transferred using .Xr nc 1 : .Bd -literal -offset indent dpv -x "nc -w 1 somewhere.com 3000" -m label file .Ed .Pp A similar example, transferring a file from another process and passing the expected size to .Nm : .Bd -literal -offset indent cat file | dpv -x "nc -w 1 somewhere.com 3000" 12345:label .Ed .Pp A more complicated example: .Bd -literal -offset indent tar cf - . | dpv -x "gzip -9 > out.tgz" \\ $( du -s . | awk '{print $1 * 1024}' ):label .Ed .Pp Taking an image of a disk: .Bd -literal -offset indent dpv -o disk-image.img -m label /dev/ada0 .Ed .Pp Writing an image back to a disk: .Bd -literal -offset indent dpv -o /dev/ada0 -m label disk-image.img .Ed .Pp Zeroing a disk: .Bd -literal -offset indent dpv -o /dev/md42 < /dev/zero .Ed .Sh SEE ALSO .Xr dialog 1 , .Xr sh 1 , .Xr Xdialog 1 , .Xr dialog 3 .Sh HISTORY A .Nm utility first appeared in .Fx 10.2 . .Sh AUTHORS .An Devin Teske Aq dteske@FreeBSD.org .Sh BUGS .Xr Xdialog 1 , when given both .Ql Fl -title Ar title .Pq see above Ql Fl t Ar title and .Ql Fl -backtitle Ar backtitle .Pq see above Ql Fl b Ar backtitle , displays the backtitle in place of the title and vice-versa. .Pp .Xr Xdialog 1 does not wrap long prompt texts received after initial launch. This is a known issue with the .Ql --gauge widget in .Xr Xdialog 1 . .Pp .Xr dialog 1 does not display the first character after a series of escaped escape-sequences (e.g., ``\\\\n'' produces ``\\'' instead of ``\\n''). This is a known issue with .Xr dialog 1 and does not affect .Xr dialog 3 or .Xr Xdialog 1 . .Pp If your application ignores .Ev USE_COLOR when set and NULL before calling .Xr dpv 1 with color escape sequences anyway, .Xr dialog 3 and .Xr dialog 1 may not render properly. Workaround is to detect when .Ev USE_COLOR is set and NULL and either not use color escape sequences at that time or use .Xr unset 1 .Xr [ sh 1 ] or .Xr unsetenv 1 .Xr [ csh 1 ] to unset .Ev USE_COLOR , forcing interpretation of color sequences. This does not effect .Xr Xdialog 1 , which renders the color escape sequences as plain text. See .Do embedded "\\Z" sequences .Dc in .Xr dialog 1 for additional information. Index: head/usr.bin/indent/indent.1 =================================================================== --- head/usr.bin/indent/indent.1 (revision 366582) +++ head/usr.bin/indent/indent.1 (revision 366583) @@ -1,607 +1,608 @@ .\" Copyright (c) 1980, 1990, 1993 .\" The Regents of the University of California. All rights reserved. .\" Copyright (c) 1976 Board of Trustees of the University of Illinois. .\" 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. .\" .\" @(#)indent.1 8.1 (Berkeley) 7/1/93 .\" $FreeBSD$ .\" .Dd June 11, 2018 .Dt INDENT 1 .Os .Sh NAME .Nm indent .Nd indent and format C program source .Sh SYNOPSIS .Nm .Op Ar input-file Op Ar output-file .Op Fl bacc | Fl nbacc .Op Fl bad | Fl nbad .Op Fl badp | Fl nbadp .Op Fl bap | Fl nbap .Op Fl bbb | Fl nbbb .Op Fl \&bc | Fl nbc .Op Fl \&bl | Fl \&br .Op Fl bs | Fl nbs .Op Fl c Ns Ar n .Op Fl \&cd Ns Ar n .Bk -words .Op Fl cdb | Fl ncdb .Ek .Op Fl \&ce | Fl nce .Op Fl \&ci Ns Ar n .Op Fl cli Ns Ar n .Op Fl cs | Fl ncs .Op Fl d Ns Ar n .Op Fl \&di Ns Ar n .Op Fl dj | Fl ndj .Bk -words .Op Fl ei | Fl nei .Op Fl eei | Fl neei .Ek .Bk -words .Op Fl fbs | Fl nfbs .Op Fl fc1 | Fl nfc1 .Op Fl fcb | Fl nfcb .Ek .Op Fl i Ns Ar n .Op Fl \&ip | Fl nip .Op Fl l Ns Ar n .Op Fl \&lc Ns Ar n .Op Fl \&ldi Ns Ar n .Op Fl \&lp | Fl nlp .Op Fl \&lpl | Fl nlpl .Op Fl npro .Op Fl P Ns Ar file .Op Fl pcs | Fl npcs .Op Fl psl | Fl npsl .Op Fl \&sc | Fl nsc .Bk -words .Op Fl sob | Fl nsob .Ek .Op Fl \&st .Op Fl \&ta .Op Fl T Ns Ar typename .Op Fl ts Ns Ar n .Op Fl U Ns Ar file .Op Fl ut | Fl nut .Op Fl v | Fl \&nv .Op Fl -version .Sh DESCRIPTION The .Nm utility is a .Em C program formatter. It reformats the .Em C program in the .Ar input-file according to the switches. The switches which can be specified are described below. They may appear before or after the file names. .Pp .Sy NOTE : If you only specify an .Ar input-file , the formatting is done `in-place', that is, the formatted file is written back into .Ar input-file and a backup copy of .Ar input-file is written in the current directory. If .Ar input-file is named .Sq Pa /blah/blah/file , the backup file is named .Sq Pa file.BAK -by default. The extension used for the backup file may be overridden using the +by default. +The extension used for the backup file may be overridden using the .Ev SIMPLE_BACKUP_SUFFIX environment variable. .Pp If .Ar output-file is specified, .Nm checks to make sure that it is different from .Ar input-file . .Pp The options listed below control the formatting style imposed by .Nm . .Bl -tag -width Op .It Fl bacc , nbacc If .Fl bacc is specified, a blank line is forced around every conditional compilation block. For example, in front of every #ifdef and after every #endif. Other blank lines surrounding such blocks will be swallowed. Default: .Fl nbacc . .It Fl bad , nbad If .Fl bad is specified, a blank line is forced after every block of declarations. Default: .Fl nbad . .It Fl badp , nbadp This is vaguely similar to .Fl bad except that it only applies to the first set of declarations in a procedure (just after the first `{') and it causes a blank line to be generated even if there are no declarations. The default is .Fl nbadp . .It Fl bap , nbap If .Fl bap is specified, a blank line is forced after every procedure body. Default: .Fl nbap . .It Fl bbb , nbbb If .Fl bbb is specified, a blank line is forced before every block comment. Default: .Fl nbbb . .It Fl \&bc , nbc If .Fl \&bc is specified, then a newline is forced after each comma in a declaration. .Fl nbc turns off this option. Default: .Fl \&nbc . .It Fl \&bl , \&br Specifying .Fl \&bl lines up compound statements like this: .Bd -literal -offset indent if (...) { code } .Ed .Pp Specifying .Fl \&br (the default) makes them look like this: .Bd -literal -offset indent if (...) { code } .Ed .It Fl bs , nbs Whether a blank should always be inserted after sizeof. The default is .Fl nbs . .It Fl c Ns Ar n The column in which comments on code start. The default is 33. .It Fl cd Ns Ar n The column in which comments on declarations start. The default is for these comments to start in the same column as those on code. .It Fl cdb , ncdb Enables (disables) the placement of comment delimiters on blank lines. With this option enabled, comments look like this: .Bd -literal -offset indent /* * this is a comment */ .Ed .Pp Rather than like this: .Bd -literal -offset indent /* this is a comment */ .Ed .Pp This only affects block comments, not comments to the right of code. The default is .Fl cdb . .It Fl ce , nce Enables (disables) forcing of `else's to cuddle up to the immediately preceding `}'. The default is .Fl \&ce . .It Fl \&ci Ns Ar n Sets the continuation indent to be .Ar n . Continuation lines will be indented that far from the beginning of the first line of the statement. Parenthesized expressions have extra indentation added to indicate the nesting, unless .Fl \&lp is in effect or the continuation indent is exactly half of the main indent. .Fl \&ci defaults to the same value as .Fl i . .It Fl cli Ns Ar n Causes case labels to be indented .Ar n tab stops to the right of the containing .Ic switch statement. .Fl cli0.5 causes case labels to be indented half a tab stop. The default is .Fl cli0 . .It Fl cs , ncs Control whether parenthesized type names in casts are followed by a space or not. The default is .Fl ncs . .It Fl d Ns Ar n Controls the placement of comments which are not to the right of code. For example, .Fl \&d\&1 means that such comments are placed one indentation level to the left of code. Specifying the default .Fl \&d\&0 lines up these comments with the code. See the section on comment indentation below. .It Fl \&di Ns Ar n Specifies the indentation, in character positions, of global variable names and all struct/union member names relative to the beginning of their type declaration. The default is .Fl di16 . .It Fl dj , ndj .Fl \&dj left justifies declarations. .Fl ndj indents declarations the same as code. The default is .Fl ndj . .It Fl \&ei , nei Enables (disables) special .Ic else-if processing. If it is enabled, an .Ic if following an .Ic else will have the same indentation as the preceding .Ic \&if statement. The default is .Fl ei . .It Fl eei , neei Enables (disables) extra indentation on continuation lines of the expression part of .Ic if and .Ic while statements. These continuation lines will be indented one extra level. The default is .Fl neei . .It Fl fbs , nfbs Enables (disables) splitting the function declaration and opening brace across two lines. The default is .Fl fbs . .It Fl fc1 , nfc1 Enables (disables) the formatting of comments that start in column 1. Often, comments whose leading `/' is in column 1 have been carefully hand formatted by the programmer. In such cases, .Fl nfc1 should be used. The default is .Fl fc1 . .It Fl fcb , nfcb Enables (disables) the formatting of block comments (ones that begin with `/*\\n'). Often, block comments have been not so carefully hand formatted by the programmer, but reformatting that would just change the line breaks is not wanted. In such cases, .Fl nfcb should be used. Block comments are then handled like box comments. The default is .Fl fcb . .It Fl i Ns Ar n The number of columns for one indentation level. The default is 8. .It Fl \&ip , nip Enables (disables) the indentation of parameter declarations from the left margin. The default is .Fl \&ip . .It Fl l Ns Ar n Maximum length of an output line. The default is 78. .It Fl lc Ns Ar n Maximum length of an output line in a block comment. The default is 0, which means to limit block comment lines in accordance with .Fl l . .It Fl \&ldi Ns Ar n Specifies the indentation, in character positions, of local variable names relative to the beginning of their type declaration. The default is for local variable names to be indented by the same amount as global ones. .It Fl \&lp , nlp Lines up code surrounded by parentheses in continuation lines. With .Fl \&lp , if a line has a left paren which is not closed on that line, then continuation lines will be lined up to start at the character position just after the left paren. For example, here is how a piece of continued code looks with .Fl nlp in effect: .Bd -literal -offset indent p1 = first_procedure(second_procedure(p2, p3), \ \ third_procedure(p4, p5)); .Ed .Pp With .Fl lp in effect (the default) the code looks somewhat clearer: .Bd -literal -offset indent p1\ =\ first_procedure(second_procedure(p2,\ p3), \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ third_procedure(p4,\ p5)); .Ed .Pp Inserting two more newlines we get: .Bd -literal -offset indent p1\ =\ first_procedure(second_procedure(p2, \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ p3), \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ third_procedure(p4, \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ p5)); .Ed .It Fl \&lpl , nlpl With .Fl \&lpl , code surrounded by parentheses in continuation lines is lined up even if it would extend past the right margin. With .Fl \&nlpl (the default), such a line that would extend past the right margin is moved left to keep it within the margin, if that does not require placing it to the left of the prevailing indentation level. These switches have no effect if .Fl nlp is selected. .It Fl npro Causes the profile files, .Sq Pa ./.indent.pro and .Sq Pa ~/.indent.pro , to be ignored. .It Fl P Ns Ar file Read profile from .Ar file . .It Fl pcs , npcs If true .Pq Fl pcs all procedure calls will have a space inserted between the name and the `('. The default is .Fl npcs . .It Fl psl , npsl If true .Pq Fl psl the names of procedures being defined are placed in column 1 \- their types, if any, will be left on the previous lines. The default is .Fl psl . .It Fl \&sc , nsc Enables (disables) the placement of asterisks (`*'s) at the left edge of all comments. The default is .Fl sc . .It Fl sob , nsob If .Fl sob is specified, indent will swallow optional blank lines. You can use this to get rid of blank lines after declarations. Default: .Fl nsob . .It Fl \&st Causes .Nm to take its input from stdin and put its output to stdout. .It Fl ta Automatically add all identifiers ending in "_t" to the list of type keywords. .It Fl T Ns Ar typename Adds .Ar typename to the list of type keywords. Names accumulate: .Fl T can be specified more than once. You need to specify all the typenames that appear in your program that are defined by .Ic typedef \- nothing will be harmed if you miss a few, but the program will not be formatted as nicely as it should. This sounds like a painful thing to have to do, but it is really a symptom of a problem in C: .Ic typedef causes a syntactic change in the language and .Nm cannot find all instances of .Ic typedef . .It Fl ts Ns Ar n Assumed distance between tab stops. The default is 8. .It Fl U Ns Ar file Adds type names from .Ar file to the list of type keywords. .It Fl ut , nut Enables (disables) the use of tab characters in the output. The default is .Fl ut . .It Fl v , \&nv .Fl v turns on `verbose' mode; .Fl \&nv turns it off. When in verbose mode, .Nm reports when it splits one line of input into two or more lines of output, and gives some size statistics at completion. The default is .Fl \&nv . .It Fl -version Causes .Nm to print its version number and exit. .El .Pp You may set up your own `profile' of defaults to .Nm by creating a file called .Pa .indent.pro in your login directory and/or the current directory and including whatever switches you like. A `.indent.pro' in the current directory takes precedence over the one in your login directory. If .Nm is run and a profile file exists, then it is read to set up the program's defaults. Switches on the command line, though, always override profile switches. The switches should be separated by spaces, tabs or newlines. .Pp .Ss Comments .Sq Em Box .Em comments . The .Nm utility assumes that any comment with a dash or star immediately after the start of comment (that is, `/*\-' or `/**') is a comment surrounded by a box of stars. Each line of such a comment is left unchanged, except that its indentation may be adjusted to account for the change in indentation of the first line of the comment. .Pp .Em Straight text . All other comments are treated as straight text. The .Nm utility fits as many words (separated by blanks, tabs, or newlines) on a line as possible. Blank lines break paragraphs. .Ss Comment indentation If a comment is on a line with code it is started in the `comment column', which is set by the .Fl c Ns Ns Ar n command line parameter. Otherwise, the comment is started at .Ar n indentation levels less than where code is currently being placed, where .Ar n is specified by the .Fl d Ns Ns Ar n command line parameter. If the code on a line extends past the comment column, the comment starts further to the right, and the right margin may be automatically extended in extreme cases. .Ss Preprocessor lines In general, .Nm leaves preprocessor lines alone. The only reformatting that it will do is to straighten up trailing comments. It leaves embedded comments alone. Conditional compilation .Pq Ic #ifdef...#endif is recognized and .Nm attempts to correctly compensate for the syntactic peculiarities introduced. .Ss C syntax The .Nm utility understands a substantial amount about the syntax of C, but it has a `forgiving' parser. It attempts to cope with the usual sorts of incomplete and malformed syntax. In particular, the use of macros like: .Pp .Dl #define forever for(;;) .Pp is handled properly. .Sh ENVIRONMENT The .Nm utility uses the .Ev HOME environment variable. .Sh FILES .Bl -tag -width "./.indent.pro" -compact .It Pa ./.indent.pro profile file .It Pa ~/.indent.pro profile file .El .Sh HISTORY The .Nm command appeared in .Bx 4.2 . .Sh BUGS The .Nm utility has even more switches than .Xr ls 1 . .Pp A common mistake is to try to indent all the .Em C programs in a directory by typing: .Pp .Dl indent *.c .Pp This is probably a bug, not a feature. Index: head/usr.bin/localedef/localedef.1 =================================================================== --- head/usr.bin/localedef/localedef.1 (revision 366582) +++ head/usr.bin/localedef/localedef.1 (revision 366583) @@ -1,271 +1,271 @@ .\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved .\" Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved .\" Portions Copyright 2013 DEY Storage Systems, Inc. .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for .\" permission to reproduce portions of its copyrighted documentation. .\" Original documentation from The Open Group can be obtained online at .\" http://www.opengroup.org/bookstore/. .\" The Institute of Electrical and Electronics Engineers and The Open Group, .\" have given us permission to reprint portions of their documentation. In .\" the following statement, the phrase "this text" refers to portions of the .\" system documentation. Portions of this text are reprinted and reproduced .\" in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, .\" 2004 Edition, Standard for Information Technology -- Portable Operating .\" System Interface (POSIX), The Open Group Base Specifications Issue 6, .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics .\" Engineers, Inc and The Open Group. In the event of any discrepancy between .\" these versions and the original IEEE and The Open Group Standard, the .\" original IEEE and The Open Group Standard is the referee document. The .\" original Standard can be obtained online at .\" http://www.opengroup.org/unix/online.html. .\" This notice shall appear on any product containing this material. .\" The contents of this file are subject to the terms of the Common .\" Development and Distribution License (the "License"). You may not use .\" this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or .\" http://www.opensolaris.org/os/licensing. See the License for the specific .\" language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and .\" include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, .\" add the following below this CDDL HEADER, with the fields enclosed by .\" brackets "[]" replaced with your own identifying information: .\" Portions Copyright [yyyy] [name of copyright owner] .\" .\" $FreeBSD$ .\" .Dd October 18, 2018 .Dt LOCALEDEF 1 .Os .Sh NAME .Nm localedef .Nd define locale environment .Sh SYNOPSIS .Nm .Op Fl bcDlUv .Op Fl f Ar charmap .Op Fl i Ar sourcefile .Op Fl u Ar codeset .Op Fl w Ar widthfile .Ar localename .Sh DESCRIPTION The .Nm utility converts source definitions for locale categories into a format usable by the functions and utilities whose operational behavior is determined by the setting of the locale environment variables; see .Xr environ 7 . .Pp The utility reads source definitions for one or more locale categories belonging to the same locale from the file named in the .Fl i option (if specified) or from standard input. .Pp Each category source definition is identified by the corresponding environment variable name and terminated by an .Sy END .Em category-name statement. The following categories are supported: .Bl -tag -width ".Ev LC_MONETARY" .It Ev LC_CTYPE Defines character classification and case conversion. .It Ev LC_COLLATE Defines collation rules. .It Ev LC_MONETARY Defines the format and symbols used in formatting of monetary information. .It Ev LC_NUMERIC Defines the decimal delimiter, grouping and grouping symbol for non-monetary numeric editing. .It Ev LC_TIME Defines the format and content of date and time information. .It Ev LC_MESSAGES Defines the format and values of affirmative and negative responses. .El .Pp The following options are supported: .Bl -tag -width indent .It Fl b Use big-endian byte order for output. .It Fl c Creates permanent output even if warning messages have been issued. .It Fl D BSD-style output. Rather than the default of creating the .Ar localename directory and creating files like .Pa LC_CTYPE , .Pa LC_COLLATE , etc.\& in that directory, the output file names have the format .Dq . and are dumped to the current directory. .It Fl f Ar charmap Specifies the pathname of a file containing a mapping of character symbols and collating element symbols to actual character encodings. This option must be specified if symbolic names (other than collating symbols defined in a .Sy collating-symbol keyword) are used. If the .Fl f option is not present, the default character mapping will be used. .It Fl i Ar sourcefile The path name of a file containing the source definitions. If this option is not present, source definitions will be read from standard input. .It Fl l Use little-endian byte order for output. .It Fl u Ar codeset Specifies the name of a codeset used as the target mapping of character symbols and collating element symbols whose encoding values are defined in terms of the ISO/IEC 10646-1:2000 standard position constant values. See .Sx NOTES . .It Fl U Ignore the presence of character symbols that have no matching character -definition. This facilitates the use of a common locale definition file -to be used across multiple encodings, even when some symbols are not -present in a given encoding. +definition. +This facilitates the use of a common locale definition file to be used across multiple +encodings, even when some symbols are not present in a given encoding. .It Fl v Emit verbose debugging output on standard output. .It Fl w Ar widthfile The path name of the file containing character screen width definitions. If not supplied, then default screen widths will be assumed, which will generally not account for East Asian encodings requiring more than a single character cell to display, nor for combining or accent marks that occupy no additional screen width. .El .Pp The following operands are required: .Bl -tag -width ".Ar localename" .It Ar localename Identifies the locale. If the name contains one or more slash characters, .Ar localename will be interpreted as a path name where the created locale definitions will be stored. This capability may be restricted to users with appropriate privileges. (As a consequence of specifying one .Ar localename , although several categories can be processed in one execution, only categories belonging to the same locale can be processed.) .El .Sh OUTPUT .Nm creates a directory of files that represents the locale's data, unless instructed otherwise by the .Fl D ( BSD output) option. The contants of this directory should generally be copied into the appropriate subdirectory of .Pa /usr/share/locale in order the definitions to be visible to programs linked with libc. .Sh ENVIRONMENT See .Xr environ 7 for definitions of the following environment variables that affect the execution of .Nm : .Ev LANG , .Ev LC_ALL , .Ev LC_COLLATE , .Ev LC_CTYPE , .Ev LC_MESSAGES , .Ev LC_MONETARY , .Ev LC_MUMERIC , .Ev LC_TIME , and .Ev NLSPATH . .Sh EXIT STATUS The following exit values are returned: .Bl -tag -width XX .It 0 No errors occurred and the locales were successfully created. .It 1 Warnings occurred and the locales were successfully created. .It 2 The locale specification exceeded implementation limits or the coded character set or sets used were not supported by the implementation, and no locale was created. .It >3 Warnings or errors occurred and no output was created. .El .Pp If an error is detected, no permanent output will be created. .Sh SEE ALSO .Xr locale 1 , .Xr iconv_open 3 , .Xr nl_langinfo 3 , .Xr strftime 3 , .Xr environ 7 .Sh WARNINGS If warnings occur, permanent output will be created if the .Fl c option was specified. The following conditions will cause warning messages to be issued: .Bl -bullet .It If a symbolic name not found in the .Pa charmap file is used for the descriptions of the .Sy LC_CTYPE or .Sy LC_COLLATE categories (for other categories, this will be an error condition). .It If optional keywords not supported by the implementation are present in the source. .El .Sh NOTES When the .Fl u option is used, the .Ar codeset option-argument is interpreted as a name of a codeset to which the ISO/IEC 10646-1:2000 standard position constant values are converted. Both the ISO/IEC 10646-1:2000 standard position constant values and other formats (decimal, hexadecimal, or octal) are valid as encoding values within the charmap file. The .Ar codeset can be any codeset that is supported by the .Fn iconv_open 3 function. .Pp When conflicts occur between the charmap specification of .Ar codeset , .Em mb_cur_max , or .Em mb_cur_min and the corresponding value for the codeset represented by the .Fl u option-argument .Ar codeset , the .Nm utility fails with an error. .Pp When conflicts occur between the charmap encoding values specified for symbolic names of characters of the portable character set and the character encoding values defined by the US-ASCII, the result is unspecified. .Sh HISTORY .Nm first appeared in .Fx 11 . .Pp It was written by .An Garrett D'Amore .Aq Mt garrett@nexenta.com for Illumos. .An John Marino .Aq Mt draco@marino.st provided the alternations necessary to compile cleanly on .Dx . .An Baptiste Daroussin .Aq Mt bapt@FreeBSD.org ported it to .Fx and converted it to .Xr tree 3 . Index: head/usr.bin/mkimg/mkimg.1 =================================================================== --- head/usr.bin/mkimg/mkimg.1 (revision 366582) +++ head/usr.bin/mkimg/mkimg.1 (revision 366583) @@ -1,376 +1,376 @@ .\" Copyright (c) 2013, 2014 Juniper Networks, Inc. .\" 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 ``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 BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd June 8, 2020 .Dt MKIMG 1 .Os .Sh NAME .Nm mkimg .Nd "utility to make disk images" .Sh SYNOPSIS .Nm .Op Fl H Ar heads .Op Fl P Ar blksz .Op Fl S Ar secsz .Op Fl T Ar tracksz .Op Fl b Ar bootcode .Op Fl c Ar min_capacity .Op Fl C Ar max_capacity .Op Fl -capacity Ar capacity .Op Fl f Ar format .Op Fl o Ar outfile .Op Fl a Ar active .Op Fl v .Op Fl y .Op Fl s Ar scheme Op Fl p Ar partition ... .Nm .Fl -formats | Fl -schemes | Fl -version .Sh DESCRIPTION The .Nm utility creates a disk image from the raw partition contents specified with the .Ar partition argument(s) and using the partitioning scheme specified with the .Ar scheme argument. The disk image is written to .Ar stdout by default or the file specified with the .Ar outfile argument. The image file is a raw disk image by default, but the format of the image file can be specified with the .Ar format argument. .Pp The disk image can be made bootable by specifying the scheme-specific boot block contents with the .Ar bootcode argument and, depending on the scheme, with a boot partition. The contents of such a boot partition is provided like any other partition and the .Nm utility does not treat it any differently from other partitions. .Pp Some partitioning schemes need a disk geometry and for those the .Nm utility accepts the .Ar tracksz and .Ar heads arguments, specifying the number of sectors per track and the number of heads per cylinder (resp.) .Pp Both the logical and physical sector size can be specified and for that the .Nm utility accepts the .Ar secsz and .Ar blksz arguments. The .Ar secsz argument is used to specify the logical sector size. This is the sector size reported by a disk when queried for its capacity. Modern disks use a larger sector size internally, referred to as block size by the .Nm utility and this can be specified by the .Ar blksz argument. The .Nm utility will use the (physical) block size to determine the start of partitions and to round the size of the disk image. .Pp The .Fl c option can be used to specify a minimal capacity for the disk image. Use this option without the .Fl s and .Fl p options to create an empty disk image with the given (virtual) size. An empty partition table can be written to the disk when specifying a partitioning scheme with the .Fl s option, but without specifying any partitions. When the size required for all the partitions is larger than the given capacity, then the disk image will be larger than the capacity given. .Pp The .Fl C option specifies a maximum capacity for the disk image. If the combined sizes of the given partitions exceed the size given with .Fl C , image creation fails. .Pp The .Fl -capacity option is a shorthand to specify the minimum and maximum capacity at the same time. .Pp The .Fl v option increases the level of output that the .Nm utility prints. .Pp The .Fl y option is used for testing purposes only and is not to be used in production. When present, the .Nm utility will generate predictable values for Universally Unique Identifiers (UUIDs) and time stamps so that consecutive runs of the .Nm utility will create images that are identical. .Pp The .Ar active option marks a partition as active, if the partitioning scheme supports it. Currently, only the .Ar mbr scheme supports this concept. By default, .Nm will only mark the first partition as active when boot code is specified. Use the .Ar active option to override the active partition. The number specified corresponds to the number after the 's' in the partition's .Xr geom 8 name. No partitions are marked active when the value is 0. .Pp A set of long options exist to query about the .Nm utility itself. Options in this set should be given by themselves because the .Nm utility exits immediately after providing the requested information. The version of the .Nm utility is printed when the .Fl -version option is given. The list of supported output formats is printed when the .Fl -formats option is given and the list of supported partitioning schemes is printed when the .Fl -schemes option is given. Both the format and scheme lists a space-separated lists for easy handling in scripts. .Pp For a more descriptive list of supported partitioning schemes or supported output format, or for a detailed description of how to specify partitions, run the .Nm utility without any arguments. This will print a usage message with all the necessary details. .Sh DISK FORMATS The .Nm utility supports a number of output file formats. A short description of these is given below. .Ss QCOW and QCOW2 QCOW stands for "QEMU Copy On Write". It's a sparse file format akin to VHD and VMDK and QCOW represents the first version. QCOW2 represents version 2 of the file format. Version 2 is not backward compatible with version 1 and adds support for snapshots among other things. The QCOW file formats are natively supported by QEMU and Xen. To write QCOW, specify .Fl f Ar qcow on the command line. To write version 2 QCOW, specify .Fl f Ar qcow2 on the command line. The preferred file extension is ".qcow" and ".qcow2" for QCOW and QCOW2 (resp.), but ".qcow" is sometimes used for version 2 files as well. .Ss RAW file format This file format is a sector by sector representation of an actual disk. -There is no extra information that describes or relates to the format -itself. The size of the file is the size of the (virtual) disk. +There is no extra information that describes or relates to the format itself. +The size of the file is the size of the (virtual) disk. This file format is suitable for being copyied onto a disk with utilities like .Nm dd . To write a raw disk file, either omit the .Fl f option, or specify .Fl f Ar raw on the command line. The preferred file extension is one of ".img" or ".raw", but there's no real convention for it. .Ss Dynamic VHD and Fixed VHD Microsoft's "Virtual Hard Disk" file formats. The dynamic format is a sparse format akin to QCOW and VMDK. The fixed format is effectively a raw format with a footer appended to the file and as such it's often indistinguishable from the raw format. The fixed file format has been added to support Microsoft's Azure platform and due to inconsistencies in interpretation of the footer is not compatible with utilities like .Nm qemu when it is specifically instructed to interpreted the file as a VHD file. By default .Nm qemu will treat the file as a raw disk file, which mostly works fine. To have .Nm create a dynamic VHD file, specify .Fl f Ar vhd on the command line. To create a fixed VHD file for use by Azure, specify .Fl f Ar vhdf on the command line. The preferred file extension is ".vhd". .Ss Dynamic VHDX Microsoft's "Virtual Hard Disk v2" file formats, the successor to VHD. VHDX is the required format for the 2nd generation Hyper-V VMs. To have .Nm create a dynamic VHDX file, specify .Fl f Ar vhdx on the command line. The preferred file extension is ".vhdx". .Ss VMDK VMware's "Virtual Machine Disk" file format. It's a sparse file format akin to QCOW and VHD and supported by many virtualization solutions. To create a VMDK file, specify .Fl f Ar vmdk on the command line. The preferred file extension is ".vmdk". .Pp Not all virtualization solutions support all file formats, but often those virtualization environments have utilities to convert from one format to another. Note however that conversion may require that the virtual disk size is changed to match the constraints of the output format and this may invalidate the contents of the disk image. For example, the GUID Partition Table (GPT) scheme has a header in the last sector on the disk. When changing the disk size, the GPT must be changed so that the last header is moved accordingly. This is typically not part of the conversion process. If possible, use an output format specifically for the environment in which the file is intended to be used. .Sh ENVIRONMENT .Bl -tag -width "TMPDIR" -compact .It Ev TMPDIR Directory to put temporary files in; default is .Pa /tmp . .El .Sh EXAMPLES To create a bootable disk image that is partitioned using the GPT scheme and containing a root file system that was previously created using .Xr makefs 8 and also containing a swap partition, run the .Nm utility as follows: .Dl % mkimg -s gpt -b /boot/pmbr -p freebsd-boot:=/boot/gptboot \ -p freebsd-ufs:=root-file-system.ufs -p freebsd-swap::1G \ -o gpt.img .Pp The command line given above results in a raw image file. This is because no output format was given. To create a VMDK image for example, add the .Fl f Ar vmdk argument to the .Nm utility and name the output file accordingly. .Pp A nested partitioning scheme is created by running the .Nm utility twice. The output of the first will be fed as the contents of a partition to the second. This can be done using a temporary file, like so: .Dl % mkimg -s bsd -b /boot/boot -p freebsd-ufs:=root-file-system.ufs \ -p freebsd-swap::1G -o /tmp/bsd.img .Dl % mkimg -s mbr -b /boot/mbr -p freebsd:=/tmp/bsd.img -o mbr-bsd.img .Pp Alternatively, the .Nm utility can be run in a cascaded fashion, whereby the output of the first is fed directly into the second. To do this, run the .Nm utility as follows: .Dl % mkimg -s mbr -b /boot/mbr -p freebsd:-'mkimg -s bsd -b /boot/boot \ -p freebsd-ufs:=root-file-system.ufs -p freebsd-swap::1G' -o mbr-bsd.img .Pp To accommodate the need to have partitions named or numbered in a certain way, the .Nm utility allows for the specification of empty partitions. For example, to create an image that is compatible with partition layouts found in .Pa /etc/disktab , the 'd' partition often needs to be skipped. This is accomplished by inserting an unused partition after the first 2 partition specifications. It is worth noting at this time that the BSD scheme will automatically skip the 'c' partition by virtue of it referring to the entire disk. To create an image that is compatible with the qp120at disk, use the .Nm utility as follows: .Dl % mkimg -s bsd -b /boot/boot -p freebsd-ufs:=root-file-system.ufs \ -p freebsd-swap::20M -p- -p- -p- -p- -p freebsd-ufs:=usr-file-system.ufs \ -o bsd.img .Pp For partitioning schemes that feature partition labels, the .Nm utility supports assigning labels to the partitions specified. In the following example the file system partition is labeled as 'backup': .Dl % mkimg -s gpt -p freebsd-ufs/backup:=file-system.ufs -o gpt.img .Sh SEE ALSO .Xr dd 1 , .Xr gpart 8 , .Xr makefs 8 , .Xr mdconfig 8 , .Xr newfs 8 .Sh HISTORY The .Nm utility first appeared in .Fx 10.1 . .Sh AUTHORS The .Nm utility and manpage were written by .An Marcel Moolenaar Aq Mt marcel@FreeBSD.org . Index: head/usr.sbin/bsnmpd/tools/bsnmptools/bsnmpget.1 =================================================================== --- head/usr.sbin/bsnmpd/tools/bsnmptools/bsnmpget.1 (revision 366582) +++ head/usr.sbin/bsnmpd/tools/bsnmptools/bsnmpget.1 (revision 366583) @@ -1,433 +1,434 @@ .\" .\" Copyright (c) 2010 The FreeBSD Foundation .\" All rights reserved. .\" .\" Portions of this documentation were written by Shteryana Sotirova Shopova .\" under sponsorship from the FreeBSD Foundation. .\" .\" Copyright (c) 2005-2007 The FreeBSD Project. .\" All rights reserved. .\" .\" Author: Shteryana Shopova .\" .\" 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 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. .\" .\" $FreeBSD$ .\" .Dd January 10, 2012 .Dt BSNMPGET 1 .Os .Sh NAME .Nm bsnmpget , .Nm bsnmpwalk , .Nm bsnmpset .Nd "simple tools for querying SNMP agents" .Sh SYNOPSIS .Nm .Op Fl aDdehnK .Op Fl A Ar options .Op Fl b Ar buffersize .Op Fl C Ar options .Op Fl I Ar options .Op Fl i Ar filelist .Op Fl l Ar filename .Op Fl M Ar max-repetitions .Op Fl N Ar non-repeaters .Op Fl o Ar output .Op Fl P Ar options .Op Fl p Ar pdu .Op Fl r Ar retries .Op Fl s Ar [trans::][community@][server][:port] .Op Fl t Ar timeout .Op Fl U Ar options .Op Fl v Ar version .Op Ar OID ... .Pp .Nm bsnmpwalk .Op Fl dhnK .Op Fl A Ar options .Op Fl b Ar buffersize .Op Fl C Ar options .Op Fl I Ar options .Op Fl i Ar filelist .Op Fl l Ar filename .Op Fl o Ar output .Op Fl P Ar options .Op Fl r Ar retries .Op Fl s Ar [trans::][community@][server][:port] .Op Fl t Ar timeout .Op Fl U Ar options .Op Fl v Ar version .Op Ar OID ... .Pp .Nm bsnmpset .Op Fl adehnK .Op Fl A Ar options .Op Fl b Ar buffersize .Op Fl C Ar options .Op Fl I Ar options .Op Fl i Ar filelist .Op Fl l Ar filename .Op Fl o Ar output .Op Fl P Ar options .Op Fl r Ar retries .Op Fl s Ar [trans::][community@][server][:port] .Op Fl t Ar timeout .Op Fl U Ar options .Op Fl v Ar version .Ar OID Ns = Ar syntax Ns : Ns Ar value .Op Ar OID Ns = Ar syntax Ns : Ns Ar value ... .Sh DESCRIPTION .Nm , .Nm bsnmpwalk and .Nm bsnmpset are simple tools for retrieving management information from and setting management information to a Simple Network Management Protocol (SNMP) agent. .Pp Depending on the options .Nm bsnmpget constructs either a SNMP GetRequest, GetNextRequest or a GetBulkRequest packet, fills in the object identifiers (OIDs) of the objects whose values will be retrieved, waits for a response and prints it if received successfully. .Pp .Nm Bsnmpwalk queries an agent with ether SNMP GetNextRequest or GetBulkRequest packets, asking for values of OID instances that are a part of the object subtree rooted at the provided OIDs. .Pp .Nm Bsnmpset constructs a SNMP SetRequest packet, fills in the OIDs (object identifiers), syntaxes and values of the objects whose values are to be set and waits for a response from server. .Sh OPTIONS The options are as follows (not all apply to all three programs): .Bl -tag -width ".It Fl D Ar options" .It Fl A Ar options Authentication options to use with SNMPv3 PDUs .Bl -tag -width \& .It Cm proto=[md5|sha] The protocol to use when calculating the PDU message digest. .It Cm key=authkey A binary localized authentication key to use when calculating the PDU message digest. .El .Pp By default SNMPv3 PDUs are sent unauthenticated. .It Fl a Skip any sanity checks when adding OIDs to a Protocol Data Unit (PDU): ingore syntax/access type, allow adding of non-leaf objects for GetPdu and read-only objects to a SetPDU. .It Fl b Ar buffersize Tune the size of buffers used to send and receive packets. The default size is 10000 bytes which should be enough unless an agent sends a really large octetstring. The maximum allowed length is 65535 according to the Structure of Management Information (SMIv2). .It Fl C Ar options The context to query with SNMPv3 PDUs. .Bl -tag -width \& .It Cm context=name -The context name. Default is "" (empty). +The context name. +Default is "" (empty). .It Cm context-engine=engine-id The SNMP Engine ID of the context to query with SNMPv3 PDUs, represented as binary octet string. By default, this is set to the Engine ID of the SNMP agent. .El .It Fl D Perform SNMP USM Engine Discovery, rather than sending a request for the value of a specific object. .It Fl d Turn on debugging. This option will cause the packets sent and received to be dumped to the terminal. .It Fl e Retry on error. If an error is returned in the response PDU, resend the request removing the variable that caused the error until a valid response is received. This is only useful for a GetRequest- and a GetNextRequest-PDU. .It Fl h Print a short help text with default values for various options. .It Fl I Ar options Load each MIB description file from the given list to translate symbolic object names to their numerical representation and vice versa. Use the other options to obtain a non-default behaviour: .Bl -tag -width \& .It Cm cut=OID Specifies the initial OID that was cut by .Xr gensnmpdef 1 when producing the MIB description file. The default value is .iso(1).org(3).dod(6) which is what should have been used for all the files installed under .Pa /usr/share/snmp/defs . Use this only if you generated your own files, providing a .Fl c option to .Xr gensnmpdef 1 . .It Cm path=filedir The directory where files in the list will be searched. The default is .Pa /usr/share/snmp/defs Ns . .It Cm file=filelist A comma separated list of files to which the two options above will apply. .El .Pp The file suboption has to come after the other suboptions so that their non-default values will be applied to the list of files. The order of the other suboptions before each file suboption can be random. Suboptions may be separated either by commas or by spaces. If using spaces make sure the entire option string is one argument, for example using quotes. .It Fl i Ar filelist List of MIB description files produced by .Xr gensnmpdef 1 which .Nm bsnmpget , .Nm bsnmpwalk or .Nm bsnmpset will search to translate numerical OIDs to their symbolic object names. Multiple files can be provided either giving this option multiple times or a comma separated list of file names. If a filename begins with a letter the default directory, .Pa /usr/share/snmp/defs , will be searched. .It Fl K Calculate and display the localized authentication and privacy keys corresponding to a plain text password. The password is obtained via the environment. Additionally, if one or more OIDs are specified, the calculated keys are used when processing the SNMPv3 requests. .It Fl l Ar filename The path of the posix local (unix domain) socket if local transport is used. .It Fl M Ar max-repetitions The value for the max-repetitions field in a GetBulk PDU. Default is 10. .It Fl N Ar non-repeaters The value for the non-repeaters field in a GetBulk PDU. Default is 0. .It Fl n Only use numerical representations for input and output OIDs and do not try to resolve symbolic object names. Note that .Nm bsnmpget , .Nm bsnmpwalk and .Nm bsnmpset will print numerical OIDs anyway if the corresponding string representation is not found in the MIB description files. .It Fl o Ar [quiet|short|verbose] The format used to print the received response. Quiet only prints values, short (default) prints an abbreviated OID representation and the value. In addition to the short output verbose prints the type before the value. .It Fl P Ar options Privacy options to use with SNMPv3 PDUs .Bl -tag -width \& .It Cm proto=[aes|des] The protocol to use when encrypting/decrypting SNMPv3 PDU data. .It Cm key=privkey A binary localized privacy key to use when encrypting/decrypting SNMPv3 PDU data. .El .Pp By default plain text SNMPv3 PDUs are sent. .It Fl p Ar [get|getnext|getbulk] The PDU type to send by .Nm bsmpget and .Nm bsnmpwalk . Default is get for .Nm bsmpget and getnext for .Nm bsnmpwalk . Getbulk allows executing the so called SNMP "bulkwalks" allowing the values of multiple columns to be retrieved in a single PDU by .Nm bsnmpwalk . .It Fl r Ar retries Number of resends of request packets before giving up if the agent does not respond after the first try. Default is 3. .It Fl s Ar [trans::] Ns Ar [community@] Ns Ar [server] Ns Ar [:port] Each of the server specification components is optional but at least one has to be provided if the .Ar s option is used. The server specification is constructed in the following manner: .Bl -tag -width \& .It Cm trans:: Transport type may be one of udp, stream or dgram. If this option is not provided an UDP inet/inet6 socket will be used, which is the most common. Stream stands for a posix local stream socket and a posix local datagram socket will be used if dgram is specified. .It Cm community@ Specify an SNMP community string to be used when sending packets. If the option is skipped the default "public" will be used for .Nm and .Nm bsnmpwalk and the default "private" community string will be used for .Nm bsnmpset . .It Cm server This might be either the IP address or the hostname where the agent is listening. The default is .Qq localhost . .It Cm port The destination port to send the requests to. This is useful if the SNMP agent listens on a non-default port. Default is given by the .Qq snmp entry in .Pa /etc/services , port 161. .El .It Fl t Ar timeout Number of seconds before resending a request packet if the agent does not respond. The default value is 3 seconds. .It Fl U Ar options User credentials when sending SNMPv3 PDUs. .Bl -tag -width \& .It Cm engine=id The Engine ID of the SNMP agent represented as a binary octet string. .It Cm engine-boots=value The value of the snmpEngineBoots of the SNMP agent. .It Cm engine-time=value The value of the snmpEngineTime of the SNMP agent. .Pp If any of the above is not specified, SNMP USM Engine Discovery is attempted. This is also the default behavior. .It Cm name=username The USM user name to include in the SNMPv3 PDUs. By default, the user name is obtained via the environment. .El .It Fl v Ar version The SNMP protocol version to use when sending requests. SNMP versions 1, 2 and 3 are supported. If no version option is provided .Nm bsnmpget , .Nm bsnmpwalk and .Nm bsnmpset will use version 2. Note that GetBulkRequest-PDUs were introduced in SNMPv2 thus setting the version to 1 is incompatible with sending a GetBulk PDU. .It OID The object identifier whose value to retrieve. At least one OID should be provided for .Nm bsnmpget to be able to send a request. .Pp For .Nm bsnmpwalk this is the root object identifier of the subtree whose values are to be retrieved. If no OID is provided .Nm bsnmpwalk will walk the mib2 subtree rooted at .iso(1).org(3).dod(6).internet(1).mgmt(2).mib2(1) . .Pp Any of the formats used to print a single variable is valid as input OID: .Bl -tag -width \& .It 1.3.6.1.2.1.25.1.1.0 .It sysDescr .It ifPhysAddress.1 .It ifRcvAddressStatus.2.6.255.255.255.255.255.255 .It ifRcvAddressType[2,ff:ff:ff:ff:ff:ff] .It ifRcvAddressStatus[Integer:1,OctetString:ff:ff:ff:ff:ff:ff] (requires the .Fl o Ar verbose option) .El .Pp Square brackets are used to denote an entry's indexes. When used in an input OID, the square brackets may have to be escaped or the OID has to be quoted to protect it from the shell. Note there is no difference between ifName.1 and "ifName[1]". .It OID Ns = Ns Ar [syntax Ns :] Ns Ar value The object identifier with its syntax type and value that is to be set. At least one such string OID=[syntax:]value should be provided to .Nm bsnmpset to be able to send a request. .Bl -tag -width \& .It Cm OID OID may be input as a string, a string followed by a random number of integers (suboids) separated by dots, a sequence of integers separated by dots - that is if the .Ar n option is used - and in such case a syntax is required for every value, or a string followed by square brackets (used to denote an entry's indexes) and corresponding indexes. Any of the formats used to print a single variable by .Nm bsnmpset is valid as input OID as well: .Bl -tag -width \& .It 1.3.6.1.2.1.25.1.1.0=TimeTicks:537615486 .It sysLocation=OctetString:"@ Home" (with Fl o Ar verbose No option) .It sysLocation.0="@ Home" .It 1.3.6.1.2.1.2.2.1.6.1=OctetString:ffffffffffff .It ifPhysAddress.1="00:02:b3:1d:1c:a3" .It ifRcvAddressStatus.1.6.255.255.255.255.255.255=1 .It "ifRcvAddressStatus[Integer:1,OctetString:ff:ff:ff:ff:ff:ff]=Integer:1" (with the .Fl o Ar verbose option) .El .It Cm syntax where the syntax string is one of: Integer, OctetString, OID, IpAddress, Counter32, Gauge, TimeTicks, Counter64. .It Cm value The value to be set - IP address in form of u.u.u.u - for example 1.3.1.6.1.2.0=IpAddress:192.168.0.1, strings require inverted-commas if they contain any special characters or spaces, all other numeric types do not. .El .El .Sh ENVIRONMENT .Nm , .Nm bsnmpwalk and .Nm bsnmpset use the following environment variables: .Bl -tag -width SNMPAUTH .It Ev SNMPAUTH Specifies a default SNMP USM authentication protocol. .It Ev SNMPPRIV Specifies a default SNMP USM privacy protocol. .It Ev SNMPUSER Specifies a default SNMP USM user name. .It Ev SNMPPASSWD Specifies the SNMP USM plain text password to use when calculating localized authentication and privacy keys. If this variable exists in the environment, SNMPv3 is the default version to use for outgoing requests. .El .Sh SEE ALSO .Xr gensnmpdef 1 .Sh AUTHORS .An Shteryana Shopova Aq Mt syrinx@FreeBSD.org Index: head/usr.sbin/camdd/camdd.8 =================================================================== --- head/usr.sbin/camdd/camdd.8 (revision 366582) +++ head/usr.sbin/camdd/camdd.8 (revision 366583) @@ -1,283 +1,283 @@ -.\" +.\" .\" Copyright (c) 2015 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. -.\" +.\" .\" Authors: Ken Merry (Spectra Logic Corporation) -.\" -.\" $FreeBSD$ .\" +.\" $FreeBSD$ +.\ .Dd November 11, 2015 .Dt CAMDD 8 .Os .Sh NAME .Nm camdd .Nd CAM data transfer utility .Sh SYNOPSIS .Nm .Aq Fl i|o Ar pass=pass_dev|file=filename,bs=blocksize,[...] .Op Fl C Ar retry_count .Op Fl E .Op Fl m Ar max_io .Op Fl t Ar timeout .Op Fl v .Op Fl h .Sh DESCRIPTION The .Nm utility is a sequential data transfer utility that offers standard .Xr read 2 and .Xr write 2 operation in addition to a mode that uses the asynchronous .Xr pass 4 API. The asynchronous .Xr pass 4 API allows multiple requests to be queued to a device simultaneously. .Pp .Nm collects performance information and will display it when the transfer completes, when .Nm is terminated or when it receives a SIGINFO signal. .Pp The following options are available: .Bl -tag -width 12n .It Fl i | o Ar args Specify the input and output device or file. -Both +Both .Fl i and .Fl o must be specified. There are a number of parameters that can be specified. One of the first two (file or pass) MUST be specified to indicate which I/O method to use on the device in question. .Bl -tag -width 9n .It pass=dev Specify a .Xr pass 4 device to operate on. This requests that .Nm access the device in question be accessed via the asynchronous .Xr pass 4 interface. .Pp The device name can be a .Xr pass 4 name and unit number, for instance .Dq pass0 , or a regular peripheral driver name and unit number, for instance .Dq da5 . It can also be the path of a -.Xr pass 4 +.Xr pass 4 or other disk device, like .Dq /dev/da5 . It may also be a bus:target:lun, for example: .Dq 0:5:0 . .Pp Only .Xr pass 4 devices for .Tn SCSI disk-like devices are supported. .Tn ATA devices are not currently supported, but support could be added later. Specifically, .Tn SCSI Direct Access (type 0), WORM (type 4), CDROM (type 5), and RBC (Reduced Block Command, type 14) devices are supported. Tape drives, medium changers, enclosures etc. are not supported. .It file=path Specify a file or device to operate on. This requests that the file or device in question be accessed using the standard .Xr read 2 and .Xr write 2 system calls. The file interface does not support queueing multiple commands at a time. It does support probing disk sector size and capacity information, and tape blocksize and maximum transfer size information. The file interface supports standard files, disks, tape drives, special devices, pipes and standard input and output. -If the file is specified as a +If the file is specified as a .Dq - , standard input or standard output are used. For tape devices, the specified blocksize will be the size that .Nm attempts to use to write to or read from the tape. When writing to a tape device, the blocksize is treated like a disk sector size. So, that means .Nm will not write anything smaller than the sector size. -At the end of a transfer, if there isn't sufficient data from the reader +At the end of a transfer, if there isn't sufficient data from the reader to yield a full block, .Nm will add zeros on the end of the data from the reader to make up a full block. .It bs=N Specify the blocksize to use for transfers. .Nm will attempt to read or write using the requested blocksize. .Pp Note that the blocksize given only applies to either the input or the output path. To use the same blocksize for the input and output transfers, you must specify that blocksize with both the .Fl i and .Fl o arguments. .Pp The blocksize may be specified in bytes, or using any suffix (e.g. k, M, G) supported by .Xr expand_number 3 . .It offset=N Specify the starting offset for the input or output device or file. The offset may be specified in bytes, or by using any suffix (e.g. k, M, G) supported by .Xr expand_number 3 . .It depth=N Specify a desired queue depth for the input or output path. .Nm will attempt to keep the requested number of requests of the specified blocksize queued to the input or output device. Queue depths greater than 1 are only supported for the asynchronous -.Xr pass 4 +.Xr pass 4 output method. The queue depth is maintained on a best effort basis, and may not be possible to maintain for especially fast devices. For writes, maintaining the queue depth also depends on a sufficiently fast reading device. .It mcs=N Specify the minimum command size to use for .Xr pass 4 devices. Some devices do not support 6 byte .Tn SCSI commands. The .Xr da 4 device handles this restriction automatically, but the .Xr pass 4 device allows the user to specify the .Tn SCSI command used. If a device does not accept 6 byte .Tn SCSI READ/WRITE commands (which is the default at lower LBAs), it will generally accept 10 byte .Tn SCSI commands instead. .It debug=N Specify the debug level for this device. There is currently only one debug level setting, so setting this to any non-zero value will turn on debugging. The debug facility may be expanded in the future. .El .It Fl C Ar count Specify the retry count for commands sent via the asynchronous .Xr pass 4 interface. This does not apply to commands sent via the file interface. .It Fl E Enable kernel error recovery for the .Xr pass 4 driver. If error recovery is not enabled, unit attention conditions and other transient failures may cause the transfer to fail. .It Fl m Ar size Specify the maximum amount of data to be transferred. This may be specified in bytes, or by using any suffix (e.g. K, M, G) supported by .Xr expand_number 3 . .It Fl t Ar timeout Specify the command timeout in seconds to use for commands sent via the .Xr pass 4 driver. .It Fl v Enable verbose reporting of errors. This is recommended to aid in debugging any .Tn SCSI issues that come up. .It Fl h Display the .Nm usage message. .El .Pp If .Nm receives a SIGINFO signal, it will print the current input and output byte counts, elapsed runtime and average throughput. If .Nm receives a SIGINT signal, it will print the current input and output byte counts, elapsed runtime and average throughput and then exit. .Sh EXAMPLES .Dl camdd -i pass=da8,bs=512k,depth=4 -o pass=da3,bs=512k,depth=4 .Pp Copy all data from da8 to da3 using a blocksize of 512k for both drives, and attempt to maintain a queue depth of 4 on both the input and output devices. The transfer will stop when the end of either device is reached. .Pp .Dl camdd -i file=/dev/zero,bs=1M -o pass=da5,bs=1M,depth=4 -m 100M .Pp Read 1MB blocks of zeros from /dev/zero, and write them to da5 with a desired queue depth of 4. Stop the transfer after 100MB has been written. .Pp .Dl camdd -i pass=da8,bs=1M,depth=3 -o file=disk.img .Pp Copy disk da8 using a 1MB blocksize and desired queue depth of 3 to the file disk.img. .Pp -.Dl camdd -i file=/etc/rc -o file=- +.Dl camdd -i file=/etc/rc -o file=- .Pp Read the file /etc/rc and write it to standard output. .Pp .Dl camdd -i pass=da10,bs=64k,depth=16 -o file=/dev/nsa0,bs=128k .Pp Copy 64K blocks from the disk da10 with a queue depth of 16, and write to the tape drive sa0 with a 128k blocksize. The copy will stop when either the end of the disk or tape is reached. .Sh SEE ALSO .Xr cam 3 , .Xr cam 4 , .Xr pass 4 , .Xr camcontrol 8 .Sh HISTORY .Nm first appeared in .Fx 10.2 .Sh AUTHORS .An Kenneth Merry Aq Mt ken@FreeBSD.org Index: head/usr.sbin/mlx5tool/mlx5tool.8 =================================================================== --- head/usr.sbin/mlx5tool/mlx5tool.8 (revision 366582) +++ head/usr.sbin/mlx5tool/mlx5tool.8 (revision 366583) @@ -1,122 +1,122 @@ .\" .\" Copyright (c) 2018, 2019 Mellanox Technologies .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. -.\" +.\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd May 7, 2019 .Dt mlx5tool 8 .Os .Sh NAME .Nm mlx5tool .Nd Utility for managing Connect-X 4/5/6 Mellanox network adapters .Sh SYNOPSIS .Nm .Fl d Ar domain:bus:slot:func .Fl E .Nm .Fl d Ar domain:bus:slot:func .Fl e .Nm .Fl d Ar domain:bus:slot:func .Fl f Ar file.mfa2 .Nm .Fl d Ar domain:bus:slot:func .Fl o Ar file .Fl w .Nm .Fl d Ar domain:bus:slot:func .Fl r .Nm .Fl d Ar domain:bus:slot:func .Fl z .Sh DESCRIPTION The .Nm utility is provided for management of the Connect-X4, 5 and 6 network adapters in the aspects not covered by the generic .Xr ifconfig 8 command, mostly related to the PCIe attachment and internal card working. The utility executes commands on specific adapter, which is addressed using .Em device:bus:slot:function conventions of the PCIe buses. You can match adapters ethernet name and addresses using the .X pciconf 8 utility. The address is passed as an argument of the .Fl d option, which must be specified for each invocation. .Pp When the driver detects the malfunctioning of the hardware, or by user request, it is possible to create .Em firmware dump , which contains debugging information about internal device state, for analysis of the failure by the Mellanox support team. .Pp The following commands are currently implemented: .Bl -tag -width indent .It Fl E Print EEPROM information .It Fl e Take the snapshot of the firmware registers state and store it in the kernel buffer. The buffer must be empty, in other words, no dumps should be written so far, or existing dump cleared with the .It Fl f Flashes the firmware image .Fa file.mfa2 to the specified adapter. Image must be in MFA2 pack format and contain a component suitable for the adapter hardware. .Pp Typically, PCIe link-level reset is required to activate the newly flashed image, which can be performed by the system reboot or using the .Fl z option. .Fl r command for the specified device. .It Fl r Clear the stored firmware dump, preparing the kernel buffer for the next dump. .It Fl w Fetches the stored firmware dump and writes it into the file specified by the .Fl o option argument. .It Fl z Performs PCIe link-level reset on the specified device. .El .Sh FILES The .Pa /dev/mlx5ctl .Xr devfs 5 node is used to pass commands to the driver. .Sh SEE ALSO .Xr mlx5en 4 , .Xr mlx5ib 4 , .Xr mlx5io 4 , .Xr ifconfig 8 and .Xr pciconf 8 . Index: head/usr.sbin/nfsd/pnfsserver.4 =================================================================== --- head/usr.sbin/nfsd/pnfsserver.4 (revision 366582) +++ head/usr.sbin/nfsd/pnfsserver.4 (revision 366583) @@ -1,425 +1,425 @@ .\" Copyright (c) 2018 Rick Macklem .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd December 20, 2019 .Dt PNFSSERVER 4 .Os .Sh NAME .Nm pNFSserver .Nd NFS Version 4.1 and 4.2 Parallel NFS Protocol Server .Sh DESCRIPTION A set of FreeBSD servers may be configured to provide a .Xr pnfs 4 service. One FreeBSD system needs to be configured as a MetaData Server (MDS) and at least one additional FreeBSD system needs to be configured as one or more Data Servers (DS)s. .Pp These FreeBSD systems are configured to be NFSv4.1 and NFSv4.2 servers, see .Xr nfsd 8 and .Xr exports 5 if you are not familiar with configuring a NFSv4.n server. All DS(s) and the MDS should support NFSv4.2 as well as NFSv4.1. Mixing an MDS that supports NFSv4.2 with any DS(s) that do not support NFSv4.2 will not work correctly. As such, all DS(s) must be upgraded from .Fx 12 to .Fx 13 before upgrading the MDS. .Sh DS server configuration The DS(s) need to be configured as NFSv4.1 and NFSv4.2 server(s), with a top level exported directory used for storage of data files. This directory must be owned by .Dq root and would normally have a mode of .Dq 700 . Within this directory there needs to be additional directories named ds0,...,dsN (where N is 19 by default) also owned by .Dq root with mode .Dq 700 . These are the directories where the data files are stored. The following command can be run by root when in the top level exported directory to create these subdirectories. .Bd -literal -offset indent jot -w ds 20 0 | xargs mkdir -m 700 .Ed .sp Note that .Dq 20 is the default and can be set to a larger value on the MDS as shown below. .sp The top level exported directory used for storage of data files must be exported to the MDS with the .Dq maproot=root sec=sys export options so that the MDS can create entries in these subdirectories. It must also be exported to all pNFS aware clients, but these clients do not require the .Dq maproot=root export option and this directory should be exported to them with the same options as used by the MDS to export file system(s) to the clients. .Pp It is possible to have multiple DSs on the same FreeBSD system, but each of these DSs must have a separate top level exported directory used for storage of data files and each of these DSs must be mountable via a separate IP address. Alias addresses can be set on the DS server system for a network interface via .Xr ifconfig 8 to create these different IP addresses. Multiple DSs on the same server may be useful when data for different file systems on the MDS are being stored on different file system volumes on the FreeBSD DS system. .Sh MDS server configuration The MDS must be a separate FreeBSD system from the FreeBSD DS system(s) and NFS clients. It is configured as a NFSv4.1 and NFSv4.2 server with file system(s) exported to clients. However, the .Dq -p command line argument for .Xr nfsd is used to indicate that it is running as the MDS for a pNFS server. .Pp The DS(s) must all be mounted on the MDS using the following mount options: .Bd -literal -offset indent nfsv4,minorversion=2,soft,retrans=2 .Ed .sp so that they can be defined as DSs in the .Dq -p option. Normally these mounts would be entered in the .Xr fstab 5 on the MDS. For example, if there are four DSs named nfsv4-data[0-3], the .Xr fstab 5 lines might look like: .Bd -literal -offset nfsv4-data0:/ /data0 nfs rw,nfsv4,minorversion=2,soft,retrans=2 0 0 nfsv4-data1:/ /data1 nfs rw,nfsv4,minorversion=2,soft,retrans=2 0 0 nfsv4-data2:/ /data2 nfs rw,nfsv4,minorversion=2,soft,retrans=2 0 0 nfsv4-data3:/ /data3 nfs rw,nfsv4,minorversion=2,soft,retrans=2 0 0 .Ed .sp The .Xr nfsd 8 command line option .Dq -p indicates that the NFS server is a pNFS MDS and specifies what DSs are to be used. .br For the above .Xr fstab 5 example, the .Xr nfsd 8 nfs_server_flags line in your .Xr rc.conf 5 might look like: .Bd -literal -offset nfs_server_flags="-u -t -n 128 -p nfsv4-data0:/data0,nfsv4-data1:/data1,nfsv4-data2:/data2,nfsv4-data3:/data3" .Ed .sp This example specifies that the data files should be distributed over the four DSs and File layouts will be issued to pNFS enabled clients. If issuing Flexible File layouts is desired for this case, setting the sysctl .Dq vfs.nfsd.default_flexfile non-zero in your .Xr sysctl.conf 5 file will make the .Nm do that. .br Alternately, this variant of .Dq nfs_server_flags will specify that two way mirroring is to be done, via the .Dq -m command line option. .Bd -literal -offset nfs_server_flags="-u -t -n 128 -p nfsv4-data0:/data0,nfsv4-data1:/data1,nfsv4-data2:/data2,nfsv4-data3:/data3 -m 2" .Ed .sp With two way mirroring, the data file for each exported file on the MDS will be stored on two of the DSs. When mirroring is enabled, the server will always issue Flexible File layouts. .Pp It is also possible to specify which DSs are to be used to store data files for specific exported file systems on the MDS. For example, if the MDS has exported two file systems .Dq /export1 and .Dq /export2 to clients, the following variant of .Dq nfs_server_flags will specify that data files for .Dq /export1 will be stored on nfsv4-data0 and nfsv4-data1, whereas the data files for .Dq /export2 will be store on nfsv4-data2 and nfsv4-data3. .Bd -literal -offset nfs_server_flags="-u -t -n 128 -p nfsv4-data0:/data0#/export1,nfsv4-data1:/data1#/export1,nfsv4-data2:/data2#/export2,nfsv4-data3:/data3#/export2" .Ed .sp This can be used by system administrators to control where data files are stored and might be useful for control of storage use. For this case, it may be convenient to co-locate more than one of the DSs on the same FreeBSD server, using separate file systems on the DS system for storage of the respective DS's data files. If mirroring is desired for this case, the .Dq -m option also needs to be specified. There must be enough DSs assigned to each exported file system on the MDS to support the level of mirroring. The above example would be fine for two way mirroring, but four way mirroring would not work, since there are only two DSs assigned to each exported file system on the MDS. .Pp The number of subdirectories in each DS is defined by the .Dq vfs.nfs.dsdirsize sysctl on the MDS. This value can be increased from the default of 20, but only when the .Xr nfsd 8 is not running and after the additional ds20,... subdirectories have been created on all the DSs. For a service that will store a large number of files this sysctl should be set much larger, to avoid the number of entries in a subdirectory from getting too large. .Sh Client mounts Once operational, NFSv4.1 or NFSv4.2 FreeBSD client mounts done with the .Dq pnfs option should do I/O directly on the DSs. The clients mounting the MDS must be running the .Xr nfscbd daemon for pNFS to work. Set .Bd -literal -offset indent nfscbd_enable="YES" .Ed .sp in the .Xr rc.conf 5 on these clients. Non-pNFS aware clients or NFSv3 mounts will do all I/O RPCs on the MDS, which acts as a proxy for the appropriate DS(s). .Sh Backing up a pNFS service Since the data is separated from the metadata, the simple way to back up a pNFS service is to do so from an NFS client that has the service mounted on it. If you back up the MDS exported file system(s) on the MDS, you must do it in such a way that the .Dq system namespace extended attributes get backed up. .Sh Handling of failed mirrored DSs When a mirrored DS fails, it can be disabled one of three ways: .sp 1 - The MDS detects a problem when trying to do proxy operations on the DS. This can take a couple of minutes after the DS failure or network partitioning occurs. .sp 2 - A pNFS client can report an I/O error that occurred for a DS to the MDS in the arguments for a LayoutReturn operation. .sp 3 - The system administrator can perform the pnfsdskill(8) command on the MDS to disable it. If the system administrator does a pnfsdskill(8) and it fails with ENXIO (Device not configured) that normally means the DS was already disabled via #1 or #2. Since doing this is harmless, once a system administrator knows that there is a problem with a mirrored DS, doing the command is recommended. .sp Once a system administrator knows that a mirrored DS has malfunctioned or has been network partitioned, they should do the following as root/su on the MDS: .Bd -literal -offset indent # pnfsdskill # umount -N .Ed .sp Note that the must be the exact mounted-on path string used when the DS was mounted on the MDS. .Pp Once the mirrored DS has been disabled, the pNFS service should continue to -function, but file updates will only happen on the DS(s) +function, but file updates will only happen on the DS(s) that have not been disabled. Assuming two way mirroring, that implies the one DS of the pair stored in the .Dq pnfsd.dsfile extended attribute for the file on the MDS, for files stored on the disabled DS. .Pp The next step is to clear the IP address in the .Dq pnfsd.dsfile extended attribute on all files on the MDS for the failed DS. This is done so that, when the disabled DS is repaired and brought back online, the data files on this DS will not be used, since they may be out of date. The command that clears the IP address is .Xr pnfsdsfile 8 with the .Dq -r option. .Bd -literal -offset For example: # pnfsdsfile -r nfsv4-data3 yyy.c yyy.c: nfsv4-data2.home.rick ds0/207508569ff983350c000000ec7c0200e4c57b2e0000000000000000 0.0.0.0 ds0/207508569ff983350c000000ec7c0200e4c57b2e0000000000000000 .Ed .sp replaces nfsv4-data3 with an IPv4 address of 0.0.0.0, so that nfsv4-data3 will not get used. .Pp Normally this will be called within a .Xr find 1 command for all regular files in the exported directory tree and must be done on the MDS. When used with .Xr find 1 , you will probably also want the .Dq -q option so that it won't spit out the results for every file. If the disabled/repaired DS is nfsv4-data3, the commands done on the MDS would be: .Bd -literal -offset # cd # find . -type f -exec pnfsdsfile -q -r nfsv4-data3 {} \; .Ed .sp There is a problem with the above command if the file found by .Xr find 1 is renamed or unlinked before the .Xr pnfsdsfile 8 command is done on it. This should normally generate an error message. A simple unlink is harmless but a link/unlink or rename might result in the file not having been processed under its new name. To check that all files have their IP addresses set to 0.0.0.0 these commands can be used (assuming the .Xr sh 1 shell): .Bd -literal -offset # cd # find . -type f -exec pnfsdsfile {} \; | sed "/nfsv4-data3/!d" .Ed .sp Any line(s) printed require the .Xr pnfsdsfile 8 with .Dq -r to be done again. Once this is done, the replaced/repaired DS can be brought back online. It should have empty ds0,...,dsN directories under the top level exported directory for storage of data files just like it did when first set up. Mount it on the MDS exactly as you did before disabling it. For the nfsv4-data3 example, the command would be: .Bd -literal -offset # mount -t nfs -o nfsv4,minorversion=2,soft,retrans=2 nfsv4-data3:/ /data3 .Ed .sp Then restart the nfsd to re-enable the DS. .Bd -literal -offset # /etc/rc.d/nfsd restart .Ed .sp Now, new files can be stored on nfsv4-data3, but files with the IP address zeroed out on the MDS will not yet use the repaired DS (nfsv4-data3). The next step is to go through the exported file tree on the MDS and, for each of the files with an IPv4 address of 0.0.0.0 in its extended attribute, copy the file data to the repaired DS and re-enable use of this mirror for it. This command for copying the file data for one MDS file is .Xr pnfsdscopymr 8 and it will also normally be used in a .Xr find 1 . For the example case, the commands on the MDS would be: .Bd -literal -offset # cd # find . -type f -exec pnfsdscopymr -r /data3 {} \; .Ed .sp When this completes, the recovery should be complete or at least nearly so. As noted above, if a link/unlink or rename occurs on a file name while the above .Xr find 1 is in progress, it may not get copied. To check for any file(s) not yet copied, the commands are: .Bd -literal -offset # cd # find . -type f -exec pnfsdsfile {} \; | sed "/0\.0\.0\.0/!d" .Ed .sp If this command prints out any file name(s), these files must have the .Xr pnfsdscopymr 8 command done on them to complete the recovery. .Bd -literal -offset # pnfsdscopymr -r /data3 .Ed .sp If this commmand fails with the error .br .Dq pnfsdscopymr: Copymr failed for file : Device not configured .br repeatedly, this may be caused by a Read/Write layout that has not been returned. The only way to get rid of such a layout is to restart the .Xr nfsd 8 . .sp All of these commands are designed to be done while the pNFS service is running and can be re-run safely. .Pp For a more detailed discussion of the setup and management of a pNFS service see: .Bd -literal -offset indent http://people.freebsd.org/~rmacklem/pnfs-planb-setup.txt .Ed .sp .Sh SEE ALSO .Xr nfsv4 4 , .Xr pnfs 4 , .Xr exports 5 , .Xr fstab 5 , .Xr rc.conf 5 , .Xr sysctl.conf 5 , .Xr nfscbd 8 , .Xr nfsd 8 , .Xr nfsuserd 8 , .Xr pnfsdscopymr 8 , .Xr pnfsdsfile 8 , .Xr pnfsdskill 8 .Sh HISTORY The .Nm service first appeared in .Fx 12.0 . .Sh BUGS Since the MDS cannot be mirrored, it is a single point of failure just as a non .Tn pNFS server is. For non-mirrored configurations, all FreeBSD systems used in the service are single points of failure. Index: head/usr.sbin/zonectl/zonectl.8 =================================================================== --- head/usr.sbin/zonectl/zonectl.8 (revision 366582) +++ head/usr.sbin/zonectl/zonectl.8 (revision 366583) @@ -1,236 +1,236 @@ -.\" +.\" .\" Copyright (c) 2015 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. -.\" +.\" .\" Authors: Ken Merry (Spectra Logic Corporation) -.\" -.\" $FreeBSD$ .\" +.\" $FreeBSD$ +.\ .Dd May 18, 2016 .Dt ZONECTL 8 .Os .Sh NAME .Nm zonectl .Nd Shingled Magnetic Recording Zone Control utility .Sh SYNOPSIS .Nm .Aq Fl d Ar dev .Aq Fl c Ar cmd .Op Fl a .Op Fl l Ar LBA .Op Fl o Ar rep_opts .Op Fl P Ar print_opts .Sh DESCRIPTION Manage .Tn SCSI and .Tn ATA Zoned Block devices. This allows managing devices that conform to the .Tn SCSI Zoned Block Commands (ZBC) and .Tn ATA Zoned ATA Command Set (ZAC) specifications. Devices using these command sets are usually hard drives using Shingled Magnetic Recording (SMR). There are three types of SMR drives: .Bl -tag -width 13n .It Drive Managed Drive Managed drives look and act just like a standard random access block device, but underneath, the drive reads and writes the bulk of its capacity using SMR zones. Sequential writes will yield better performance, but writing sequentially is not required. .It Host Aware Host Aware drives expose the underlying zone layout via .Tn SCSI or .Tn ATA commands and allow the host to manage the zone conditions. The host is not required to manage the zones on the drive, though. Sequential writes will yield better performance in Sequential Write Preferred zones, but the host can write randomly in those zones. .It Host Managed Host Managed drives expose the underlying zone layout via .Tn SCSI or .Tn ATA commands. The host is required to access the zones according to the rules described by the zone layout. Any commands that violate the rules will be returned with an error. .El .Pp SMR drives are divided into zones (typically in the range of 256MB each) that fall into three general categories: .Bl -tag -width 20n .It Conventional These are also known as Non Write Pointer zones. These zones can be randomly written without an unexpected performance penalty. .It Sequential Preferred These zones should be written sequentially starting at the write pointer for the zone. They may be written randomly. Writes that do not conform to the zone layout may be significantly slower than expected. .It Sequential Required These zones must be written sequentially. If they are not written sequentially, starting at the write pointer, the command will fail. .El .Pp .Bl -tag -width 12n .It Fl c Ar cmd Specify the zone subcommand: .Bl -tag -width 6n .It params Display device parameters, including the type of device (Drive Managed, Host Aware, Host Managed, Not Zoned), the zone commands supported, and how many open zones it supports. .It rz Issue the Report Zones command. All zones are returned by default. Specify report options with .Fl o and printing options with .Fl P . Specify the starting LBA with .Fl l . Note that .Dq reportzones is also accepted as a command argument. .It open Explicitly open the zone specified by the starting LBA. .It close Close the zone specified by starting LBA. .It finish Finish the zone specified by the starting LBA. .It rwp Reset the write pointer for the zone specified by the starting LBA. .El .It Fl a For the Open, Close, Finish, and Reset Write Pointer operations, apply the operation to all zones on the drive. .It Fl l Ar lba Specify the starting LBA. For the Report Zones command, this tells the drive to report starting with the zone that starts at the given LBA. For the other commands, this allows the user to identify the zone requested by its starting LBA. The LBA may be specified in decimal, hexadecimal or octal notation. .It Fl o Ar rep_opt For the Report Zones command, specify a subset of zones to report. .Bl -tag -width 8n .It all Report all zones. This is the default. .It emtpy Report only empty zones. .It imp_open Report zones that are implicitly open. This means that the host has sent a write to the zone without explicitly opening the zone. .It exp_open Report zones that are explicitly open. .It closed Report zones that have been closed by the host. .It full Report zones that are full. .It ro Report zones that are in the read only state. Note that .Dq readonly is also accepted as an argument. .It offline Report zones that are in the offline state. .It reset Report zones that the device recommends should have their write pointers reset. .It nonseq Report zones that have the Non Sequential Resources Active flag set. These are zones that are Sequential Write Preferred, but have been written non-sequentially. .It nonwp Report Non Write Pointer zones, also known as Conventional zones. .El .It Fl P Ar print_opt Specify a printing option for Report Zones: .Bl -tag -width 7n .It normal Normal Report Zones output. This is the default. The summary and column headings are printed, fields are separated by spaces and the fields themselves may contain spaces. .It summary Just print the summary: the number of zones, the maximum LBA (LBA of the -last logical block on the drive), and the value of the -.Dq same +last logical block on the drive), and the value of the +.Dq same field. The .Dq same field describes whether the zones on the drive are all identical, all different, or whether they are the same except for the last zone, etc. .It script Print the zones in a script friendly format. The summary and column headings are omitted, the fields are separated by commas, and the fields do not contain spaces. The fields contain underscores where spaces would normally be used. .El .El .Sh EXAMPLES .Bd -literal -offset indent zonectl -d /dev/da5 -c params .Ed .Pp Display basic zoning information for disk da5. .Pp .Bd -literal -offset indent zonectl -d /dev/da5 -c rz .Ed .Pp Issue the Report Zones command to disk da5, and print out all zones on the drive in the default format. .Pp .Bd -literal -offset indent zonectl -d /dev/da5 -c rz -o reset -P script .Ed .Pp Issue the Report Zones command to disk da5, and print out all of the zones that have the Reset Write Pointer Recommended bit set to true. Print the zones in a script friendly form. .Pp .Bd -literal -offset indent zonectl -d /dev/da5 -c rwp -l 0x2c80000 .Ed .Pp Issue the Reset Write Pointer command to disk da5 for the zone that starts at LBA 0x2c80000. .Pp .Bd -literal -offset indent .Sh AUTHORS .An Kenneth Merry Aq ken@FreeBSD.org