Index: head/bin/freebsd-version/freebsd-version.1 =================================================================== --- head/bin/freebsd-version/freebsd-version.1 (revision 297354) +++ head/bin/freebsd-version/freebsd-version.1 (revision 297355) @@ -1,124 +1,123 @@ .\"- .\" Copyright (c) 2013 Dag-Erling Smørgrav .\" 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 5, 2013 .Dt FREEBSD-VERSION 1 .Os .Sh NAME .Nm freebsd-version .Nd print the version and patch level of the installed system .Sh SYNOPSIS .Nm .Op Fl ku .Sh DESCRIPTION The .Nm utility makes a best effort to determine the version and patch level of the installed kernel and / or userland. .Pp The following options are available: .Bl -tag -width Fl .It Fl k Print the version and patch level of the installed kernel. Unlike .Xr uname 1 , if a new kernel has been installed but the system has not yet rebooted, .Nm will print the version and patch level of the new kernel. .It Fl u Print the version and patch level of the installed userland. These are hardcoded into .Nm during the build. .El .Pp If both .Fl k and .Fl u are specified, .Nm will print the kernel version first, then the userland version, on separate lines. If neither is specified, it will print the userland version only. .Sh IMPLEMENTATION NOTES The .Nm utility should provide the correct answer in the vast majority of cases, including on systems kept up-to-date using .Xr freebsd-update 8 , which does not update the kernel version unless the kernel itself was affected by the latest patch. .Pp To determine the name (and hence the location) of a custom kernel, the .Nm utility will attempt to parse .Pa /boot/defaults/loader.conf and .Pa /boot/loader.conf , looking for definitions of the .Va kernel and .Va bootfile variables, both with a default value of .Dq kernel . It may however fail to locate the correct kernel if either or both of these variables are defined in a non-standard location, such as in .Pa /boot/loader.rc . .Sh ENVIRONMENT .Bl -tag -width ROOT .It Ev ROOT Path to the root of the filesystem in which to look for .Pa loader.conf and the kernel. .El .Sh EXAMPLES To determine the version of the currently running userland: .Bd -literal -offset indent /bin/freebsd-version -u .Ed .Pp To inspect a system being repaired using a live CD: .Bd -literal -offset indent mount -rt ufs /dev/ada0p2 /mnt env ROOT=/mnt /mnt/bin/freebsd-version -ku .Ed .Sh SEE ALSO .Xr uname 1 , -.Xr loader.conf 5 , -.Xr freebsd-version 8 +.Xr loader.conf 5 .Sh HISTORY The .Nm command appeared in .Fx 10.0 . .Sh AUTHORS The .Nm utility and this manual page were written by .An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . Index: head/lib/libc/stdio/open_memstream.3 =================================================================== --- head/lib/libc/stdio/open_memstream.3 (revision 297354) +++ head/lib/libc/stdio/open_memstream.3 (revision 297355) @@ -1,155 +1,155 @@ .\" Copyright (c) 2013 Hudson River Trading LLC .\" Written by: John H. Baldwin .\" 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 1, 2015 .Dt OPEN_MEMSTREAM 3 .Os .Sh NAME .Nm open_memstream , .Nm open_wmemstream .Nd dynamic memory buffer stream open functions .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In stdio.h .Ft FILE * .Fn open_memstream "char **bufp" "size_t *sizep" .In wchar.h .Ft FILE * .Fn open_wmemstream "wchar_t **bufp" "size_t *sizep" .Sh DESCRIPTION The .Fn open_memstream and .Fn open_wmemstream functions create a write-only, seekable stream backed by a dynamically allocated memory buffer. The .Fn open_memstream function creates a byte-oriented stream, while the .Fn open_wmemstream function creates a wide-oriented stream. .Pp Each stream maintains a current position and size. Initially, the position and size are set to zero. Each write begins at the current position and advances it the number of successfully written bytes for .Fn open_memstream or wide characters for .Fn open_wmemstream . If a write moves the current position beyond the length of the buffer, the length of the buffer is extended and a null character is appended to the buffer. .Pp A stream's buffer always contains a null character at the end of the buffer that is not included in the current length. .Pp If a stream's current position is moved beyond the current length via a seek operation and a write is performed, the characters between the current length and the current position are filled with null characters before the write is performed. .Pp After a successful call to .Xr fclose 3 or .Xr fflush 3 , the pointer referenced by .Fa bufp will contain the start of the memory buffer and the variable referenced by .Fa sizep will contain the smaller of the current position and the current buffer length. .Pp After a successful call to .Xr fflush 3 , the pointer referenced by .Fa bufp and the variable referenced by .Fa sizep are only valid until the next write operation or a call to .Xr fclose 3 . .Pp Once a stream is closed, the allocated buffer referenced by .Fa bufp should be released via a call to .Xr free 3 when it is no longer needed. .Sh IMPLEMENTATION NOTES Internally all I/O streams are effectively byte-oriented, so using wide-oriented operations to write to a stream opened via .Fn open_wmemstream results in wide characters being expanded to a stream of multibyte characters in stdio's internal buffers. These multibyte characters are then converted back to wide characters when written into the stream. As a result, the wide-oriented streams maintain an internal multibyte character conversion state that is cleared on any seek opertion that changes the current position. This should have no effect as long as wide-oriented output operations are used on a wide-oriented stream. .Sh RETURN VALUES Upon successful completion, .Fn open_memstream and .Fn open_wmemstream return a .Tn FILE pointer. Otherwise, .Dv NULL is returned and the global variable .Va errno is set to indicate the error. .Sh ERRORS .Bl -tag -width Er .It Bq Er EINVAL The .Fa bufp or .Fa sizep argument was .Dv NULL . .It Bq Er ENOMEM Memory for the stream or buffer could not be allocated. .El .Sh SEE ALSO .Xr fclose 3 , .Xr fflush 3 , .Xr fopen 3 , .Xr free 3 , .Xr fseek 3 , -.Xr sbuf 3 , -.Xr stdio 3 +.Xr stdio 3 , +.Xr sbuf 9 .Sh STANDARDS The .Fn open_memstream and .Fn open_wmemstream functions conform to .St -p1003.1-2008 . Index: head/lib/libc/sys/ptrace.2 =================================================================== --- head/lib/libc/sys/ptrace.2 (revision 297354) +++ head/lib/libc/sys/ptrace.2 (revision 297355) @@ -1,871 +1,871 @@ .\" $FreeBSD$ .\" $NetBSD: ptrace.2,v 1.2 1995/02/27 12:35:37 cgd Exp $ .\" .\" This file is in the public domain. .Dd December 29, 2015 .Dt PTRACE 2 .Os .Sh NAME .Nm ptrace .Nd process tracing and debugging .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/ptrace.h .Ft int .Fn ptrace "int request" "pid_t pid" "caddr_t addr" "int data" .Sh DESCRIPTION The .Fn ptrace system call provides tracing and debugging facilities. It allows one process (the .Em tracing process) to control another (the .Em traced process). The tracing process must first attach to the traced process, and then issue a series of .Fn ptrace system calls to control the execution of the process, as well as access process memory and register state. For the duration of the tracing session, the traced process will be .Dq re-parented , with its parent process ID (and resulting behavior) changed to the tracing process. It is permissible for a tracing process to attach to more than one other process at a time. When the tracing process has completed its work, it must detach the traced process; if a tracing process exits without first detaching all processes it has attached, those processes will be killed. .Pp Most of the time, the traced process runs normally, but when it receives a signal (see .Xr sigaction 2 ) , it stops. The tracing process is expected to notice this via .Xr wait 2 or the delivery of a .Dv SIGCHLD signal, examine the state of the stopped process, and cause it to terminate or continue as appropriate. The signal may be a normal process signal, generated as a result of traced process behavior, or use of the .Xr kill 2 system call; alternatively, it may be generated by the tracing facility as a result of attaching, system calls, or stepping by the tracing process. The tracing process may choose to intercept the signal, using it to observe process behavior (such as .Dv SIGTRAP ) , or forward the signal to the process if appropriate. The .Fn ptrace system call is the mechanism by which all this happens. .Pp The .Fa request argument specifies what operation is being performed; the meaning of the rest of the arguments depends on the operation, but except for one special case noted below, all .Fn ptrace calls are made by the tracing process, and the .Fa pid argument specifies the process ID of the traced process or a corresponding thread ID. The .Fa request argument can be: .Bl -tag -width 12n .It Dv PT_TRACE_ME This request is the only one used by the traced process; it declares that the process expects to be traced by its parent. All the other arguments are ignored. (If the parent process does not expect to trace the child, it will probably be rather confused by the results; once the traced process stops, it cannot be made to continue except via .Fn ptrace . ) When a process has used this request and calls .Xr execve 2 or any of the routines built on it (such as .Xr execv 3 ) , it will stop before executing the first instruction of the new image. Also, any setuid or setgid bits on the executable being executed will be ignored. If the child was created by .Xr vfork 2 system call or -.Xr rfork(2) +.Xr rfork 2 call with the .Dv RFMEM flag specified, the debugging events are reported to the parent only after the .Xr execve 2 is executed. .It Dv PT_READ_I , Dv PT_READ_D These requests read a single .Vt int of data from the traced process's address space. Traditionally, .Fn ptrace has allowed for machines with distinct address spaces for instruction and data, which is why there are two requests: conceptually, .Dv PT_READ_I reads from the instruction space and .Dv PT_READ_D reads from the data space. In the current .Fx implementation, these two requests are completely identical. The .Fa addr argument specifies the address (in the traced process's virtual address space) at which the read is to be done. This address does not have to meet any alignment constraints. The value read is returned as the return value from .Fn ptrace . .It Dv PT_WRITE_I , Dv PT_WRITE_D These requests parallel .Dv PT_READ_I and .Dv PT_READ_D , except that they write rather than read. The .Fa data argument supplies the value to be written. .It Dv PT_IO This request allows reading and writing arbitrary amounts of data in the traced process's address space. The .Fa addr argument specifies a pointer to a .Vt "struct ptrace_io_desc" , which is defined as follows: .Bd -literal struct ptrace_io_desc { int piod_op; /* I/O operation */ void *piod_offs; /* child offset */ void *piod_addr; /* parent offset */ size_t piod_len; /* request length */ }; /* * Operations in piod_op. */ #define PIOD_READ_D 1 /* Read from D space */ #define PIOD_WRITE_D 2 /* Write to D space */ #define PIOD_READ_I 3 /* Read from I space */ #define PIOD_WRITE_I 4 /* Write to I space */ .Ed .Pp The .Fa data argument is ignored. The actual number of bytes read or written is stored in .Va piod_len upon return. .It Dv PT_CONTINUE The traced process continues execution. The .Fa addr argument is an address specifying the place where execution is to be resumed (a new value for the program counter), or .Po Vt caddr_t Pc Ns 1 to indicate that execution is to pick up where it left off. The .Fa data argument provides a signal number to be delivered to the traced process as it resumes execution, or 0 if no signal is to be sent. .It Dv PT_STEP The traced process is single stepped one instruction. The .Fa addr argument should be passed .Po Vt caddr_t Pc Ns 1 . The .Fa data argument provides a signal number to be delivered to the traced process as it resumes execution, or 0 if no signal is to be sent. .It Dv PT_KILL The traced process terminates, as if .Dv PT_CONTINUE had been used with .Dv SIGKILL given as the signal to be delivered. .It Dv PT_ATTACH This request allows a process to gain control of an otherwise unrelated process and begin tracing it. It does not need any cooperation from the to-be-traced process. In this case, .Fa pid specifies the process ID of the to-be-traced process, and the other two arguments are ignored. This request requires that the target process must have the same real UID as the tracing process, and that it must not be executing a setuid or setgid executable. (If the tracing process is running as root, these restrictions do not apply.) The tracing process will see the newly-traced process stop and may then control it as if it had been traced all along. .It Dv PT_DETACH This request is like PT_CONTINUE, except that it does not allow specifying an alternate place to continue execution, and after it succeeds, the traced process is no longer traced and continues execution normally. .It Dv PT_GETREGS This request reads the traced process's machine registers into the .Do .Vt "struct reg" .Dc (defined in .In machine/reg.h ) pointed to by .Fa addr . .It Dv PT_SETREGS This request is the converse of .Dv PT_GETREGS ; it loads the traced process's machine registers from the .Do .Vt "struct reg" .Dc (defined in .In machine/reg.h ) pointed to by .Fa addr . .It Dv PT_GETFPREGS This request reads the traced process's floating-point registers into the .Do .Vt "struct fpreg" .Dc (defined in .In machine/reg.h ) pointed to by .Fa addr . .It Dv PT_SETFPREGS This request is the converse of .Dv PT_GETFPREGS ; it loads the traced process's floating-point registers from the .Do .Vt "struct fpreg" .Dc (defined in .In machine/reg.h ) pointed to by .Fa addr . .It Dv PT_GETDBREGS This request reads the traced process's debug registers into the .Do .Vt "struct dbreg" .Dc (defined in .In machine/reg.h ) pointed to by .Fa addr . .It Dv PT_SETDBREGS This request is the converse of .Dv PT_GETDBREGS ; it loads the traced process's debug registers from the .Do .Vt "struct dbreg" .Dc (defined in .In machine/reg.h ) pointed to by .Fa addr . .It Dv PT_LWPINFO This request can be used to obtain information about the kernel thread, also known as light-weight process, that caused the traced process to stop. The .Fa addr argument specifies a pointer to a .Vt "struct ptrace_lwpinfo" , which is defined as follows: .Bd -literal struct ptrace_lwpinfo { lwpid_t pl_lwpid; int pl_event; int pl_flags; sigset_t pl_sigmask; sigset_t pl_siglist; siginfo_t pl_siginfo; char pl_tdname[MAXCOMLEN + 1]; pid_t pl_child_pid; u_int pl_syscall_code; u_int pl_syscall_narg; }; .Ed .Pp The .Fa data argument is to be set to the size of the structure known to the caller. This allows the structure to grow without affecting older programs. .Pp The fields in the .Vt "struct ptrace_lwpinfo" have the following meaning: .Bl -tag -width indent -compact .It pl_lwpid LWP id of the thread .It pl_event Event that caused the stop. Currently defined events are .Bl -tag -width indent -compact .It PL_EVENT_NONE No reason given .It PL_EVENT_SIGNAL Thread stopped due to the pending signal .El .It pl_flags Flags that specify additional details about observed stop. Currently defined flags are: .Bl -tag -width indent -compact .It PL_FLAG_SCE The thread stopped due to system call entry, right after the kernel is entered. The debugger may examine syscall arguments that are stored in memory and registers according to the ABI of the current process, and modify them, if needed. .It PL_FLAG_SCX The thread is stopped immediately before syscall is returning to the usermode. The debugger may examine system call return values in the ABI-defined registers and/or memory. .It PL_FLAG_EXEC When .Dv PL_FLAG_SCX is set, this flag may be additionally specified to inform that the program being executed by debuggee process has been changed by successful execution of a system call from the .Fn execve 2 family. .It PL_FLAG_SI Indicates that .Va pl_siginfo member of .Vt "struct ptrace_lwpinfo" contains valid information. .It PL_FLAG_FORKED Indicates that the process is returning from a call to .Fn fork 2 that created a new child process. The process identifier of the new process is available in the .Va pl_child_pid member of .Vt "struct ptrace_lwpinfo" . .It PL_FLAG_CHILD The flag is set for first event reported from a new child, which is automatically attached due to .Dv PT_FOLLOW_FORK enabled. .It PL_FLAG_BORN This flag is set for the first event reported from a new LWP when LWP events are enabled via .Dv PT_LWP_EVENTS . It is reported along with .Dv PL_FLAG_SCX and is always reported if LWP events are enabled. .It PL_FLAG_EXITED This flag is set for the last event reported by an exiting LWP when LWP events are enabled via .Dv PT_LWP_EVENTS . Note that this event is not reported when the last LWP in a process exits. The termination of the last thread is reported via a normal process exit event. .El .It pl_sigmask The current signal mask of the LWP .It pl_siglist The current pending set of signals for the LWP. Note that signals that are delivered to the process would not appear on an LWP siglist until the thread is selected for delivery. .It pl_siginfo The siginfo that accompanies the signal pending. Only valid for .Dv PL_EVENT_SIGNAL stop when .Dv PL_FLAG_SI is set in .Va pl_flags . .It pl_tdname The name of the thread. .It pl_child_pid The process identifier of the new child process. Only valid for a .Dv PL_EVENT_SIGNAL stop when .Dv PL_FLAG_FORKED is set in .Va pl_flags . .It pl_syscall_code The ABI-specific identifier of the current system call. Note that for indirect system calls this field reports the indirected system call. Only valid when .Dv PL_FLAG_SCE or .Dv PL_FLAG_SCX is set in .Va pl_flags. .It pl_syscall_narg The number of arguments passed to the current system call not counting the system call identifier. Note that for indirect system calls this field reports the arguments passed to the indirected system call. Only valid when .Dv PL_FLAG_SCE or .Dv PL_FLAG_SCX is set in .Va pl_flags. .El .It PT_GETNUMLWPS This request returns the number of kernel threads associated with the traced process. .It PT_GETLWPLIST This request can be used to get the current thread list. A pointer to an array of type .Vt lwpid_t should be passed in .Fa addr , with the array size specified by .Fa data . The return value from .Fn ptrace is the count of array entries filled in. .It PT_SETSTEP This request will turn on single stepping of the specified process. .It PT_CLEARSTEP This request will turn off single stepping of the specified process. .It PT_SUSPEND This request will suspend the specified thread. .It PT_RESUME This request will resume the specified thread. .It PT_TO_SCE This request will trace the specified process on each system call entry. .It PT_TO_SCX This request will trace the specified process on each system call exit. .It PT_SYSCALL This request will trace the specified process on each system call entry and exit. .It PT_FOLLOW_FORK This request controls tracing for new child processes of a traced process. If .Fa data is non-zero, then new child processes will enable tracing and stop before executing their first instruction. If .Fa data is zero, then new child processes will execute without tracing enabled. By default, tracing is not enabled for new child processes. Child processes do not inherit this property. The traced process will set the .Dv PL_FLAG_FORKED flag upon exit from a system call that creates a new process. .It PT_LWP_EVENTS This request controls tracing of LWP creation and destruction. If .Fa data is non-zero, then LWPs will stop to report creation and destruction events. If .Fa data is zero, then LWP creation and destruction events will not be reported. By default, tracing is not enabled for LWP events. Child processes do not inherit this property. New LWPs will stop to report an event with .Dv PL_FLAG_BORN set before executing their first instruction. Exiting LWPs will stop to report an event with .Dv PL_FLAG_EXITED set before completing their termination. .Pp Note that new processes do not report an event for the creation of their initial thread, and exiting processes do not report an event for the termination of the last thread. .It PT_VM_TIMESTAMP This request returns the generation number or timestamp of the memory map of the traced process as the return value from .Fn ptrace . This provides a low-cost way for the tracing process to determine if the VM map changed since the last time this request was made. .It PT_VM_ENTRY This request is used to iterate over the entries of the VM map of the traced process. The .Fa addr argument specifies a pointer to a .Vt "struct ptrace_vm_entry" , which is defined as follows: .Bd -literal struct ptrace_vm_entry { int pve_entry; int pve_timestamp; u_long pve_start; u_long pve_end; u_long pve_offset; u_int pve_prot; u_int pve_pathlen; long pve_fileid; uint32_t pve_fsid; char *pve_path; }; .Ed .Pp The first entry is returned by setting .Va pve_entry to zero. Subsequent entries are returned by leaving .Va pve_entry unmodified from the value returned by previous requests. The .Va pve_timestamp field can be used to detect changes to the VM map while iterating over the entries. The tracing process can then take appropriate action, such as restarting. By setting .Va pve_pathlen to a non-zero value on entry, the pathname of the backing object is returned in the buffer pointed to by .Va pve_path , provided the entry is backed by a vnode. The .Va pve_pathlen field is updated with the actual length of the pathname (including the terminating null character). The .Va pve_offset field is the offset within the backing object at which the range starts. The range is located in the VM space at .Va pve_start and extends up to .Va pve_end (inclusive). .Pp The .Fa data argument is ignored. .El .Sh x86 MACHINE-SPECIFIC REQUESTS .Bl -tag -width "Dv PT_GETXSTATE_INFO" .It Dv PT_GETXMMREGS Copy the XMM FPU state into the buffer pointed to by the argument .Fa addr . The buffer has the same layout as the 32-bit save buffer for the machine instruction .Dv FXSAVE . .Pp This request is only valid for i386 programs, both on native 32-bit systems and on amd64 kernels. For 64-bit amd64 programs, the XMM state is reported as part of the FPU state returned by the .Dv PT_GETFPREGS request. .Pp The .Fa data argument is ignored. .It Dv PT_SETXMMREGS Load the XMM FPU state for the thread from the buffer pointed to by the argument .Fa addr . The buffer has the same layout as the 32-bit load buffer for the machine instruction .Dv FXRSTOR . .Pp As with .Dv PT_GETXMMREGS, this request is only valid for i386 programs. .Pp The .Fa data argument is ignored. .It Dv PT_GETXSTATE_INFO Report which XSAVE FPU extensions are supported by the CPU and allowed in userspace programs. The .Fa addr argument must point to a variable of type .Vt struct ptrace_xstate_info , which contains the information on the request return. .Vt struct ptrace_xstate_info is defined as follows: .Bd -literal struct ptrace_xstate_info { uint64_t xsave_mask; uint32_t xsave_len; }; .Ed The .Dv xsave_mask field is a bitmask of the currently enabled extensions. The meaning of the bits is defined in the Intel and AMD processor documentation. The .Dv xsave_len field reports the length of the XSAVE area for storing the hardware state for currently enabled extensions in the format defined by the x86 .Dv XSAVE machine instruction. .Pp The .Fa data argument value must be equal to the size of the .Vt struct ptrace_xstate_info . .It Dv PT_GETXSTATE Return the content of the XSAVE area for the thread. The .Fa addr argument points to the buffer where the content is copied, and the .Fa data argument specifies the size of the buffer. The kernel copies out as much content as allowed by the buffer size. The buffer layout is specified by the layout of the save area for the .Dv XSAVE machine instruction. .It Dv PT_SETXSTATE Load the XSAVE state for the thread from the buffer specified by the .Fa addr pointer. The buffer size is passed in the .Fa data argument. The buffer must be at least as large as the .Vt struct savefpu (defined in .Pa x86/fpu.h ) to allow the complete x87 FPU and XMM state load. It must not be larger than the XSAVE state length, as reported by the .Dv xsave_len field from the .Vt struct ptrace_xstate_info of the .Dv PT_GETXSTATE_INFO request. Layout of the buffer is identical to the layout of the load area for the .Dv XRSTOR machine instruction. .It Dv PT_GETFSBASE Return the value of the base used when doing segmented memory addressing using the %fs segment register. The .Fa addr argument points to an .Vt unsigned long variable where the base value is stored. .Pp The .Fa data argument is ignored. .It Dv PT_GETGSBASE Like the .Dv PT_GETFSBASE request, but returns the base for the %gs segment register. .It Dv PT_SETFSBASE Set the base for the %fs segment register to the value pointed to by the .Fa addr argument. .Fa addr must point to the .Vt unsigned long variable containing the new base. .Pp The .Fa data argument is ignored. .It Dv PT_SETGSBASE Like the .Dv PT_SETFSBASE request, but sets the base for the %gs segment register. .El .Sh PowerPC MACHINE-SPECIFIC REQUESTS .Bl -tag -width "Dv PT_SETVRREGS" .It Dv PT_GETVRREGS Return the thread's .Dv ALTIVEC machine state in the buffer pointed to by .Fa addr . .Pp The .Fa data argument is ignored. .It Dv PT_SETVRREGS Set the thread's .Dv ALTIVEC machine state from the buffer pointed to by .Fa addr . .Pp The .Fa data argument is ignored. .El .Pp Additionally, other machine-specific requests can exist. .Sh RETURN VALUES Some requests can cause .Fn ptrace to return \-1 as a non-error value; to disambiguate, .Va errno can be set to 0 before the call and checked afterwards. .Sh ERRORS The .Fn ptrace system call may fail if: .Bl -tag -width Er .It Bq Er ESRCH .Bl -bullet -compact .It No process having the specified process ID exists. .El .It Bq Er EINVAL .Bl -bullet -compact .It A process attempted to use .Dv PT_ATTACH on itself. .It The .Fa request argument was not one of the legal requests. .It The signal number (in .Fa data ) to .Dv PT_CONTINUE was neither 0 nor a legal signal number. .It .Dv PT_GETREGS , .Dv PT_SETREGS , .Dv PT_GETFPREGS , .Dv PT_SETFPREGS , .Dv PT_GETDBREGS , or .Dv PT_SETDBREGS was attempted on a process with no valid register set. (This is normally true only of system processes.) .It .Dv PT_VM_ENTRY was given an invalid value for .Fa pve_entry . This can also be caused by changes to the VM map of the process. .It The size (in .Fa data ) provided to .Dv PT_LWPINFO was less than or equal to zero, or larger than the .Vt ptrace_lwpinfo structure known to the kernel. .It The size (in .Fa data ) provided to the x86-specific .Dv PT_GETXSTATE_INFO request was not equal to the size of the .Vt struct ptrace_xstate_info . .It The size (in .Fa data ) provided to the x86-specific .Dv PT_SETXSTATE request was less than the size of the x87 plus the XMM save area. .It The size (in .Fa data ) provided to the x86-specific .Dv PT_SETXSTATE request was larger than returned in the .Dv xsave_len member of the .Vt struct ptrace_xstate_info from the .Dv PT_GETXSTATE_INFO request. .It The base value, provided to the amd64-specific requests .Dv PT_SETFSBASE or .Dv PT_SETGSBASE , pointed outside of the valid user address space. This error will not occur in 32-bit programs. .El .It Bq Er EBUSY .Bl -bullet -compact .It .Dv PT_ATTACH was attempted on a process that was already being traced. .It A request attempted to manipulate a process that was being traced by some process other than the one making the request. .It A request (other than .Dv PT_ATTACH ) specified a process that was not stopped. .El .It Bq Er EPERM .Bl -bullet -compact .It A request (other than .Dv PT_ATTACH ) attempted to manipulate a process that was not being traced at all. .It An attempt was made to use .Dv PT_ATTACH on a process in violation of the requirements listed under .Dv PT_ATTACH above. .El .It Bq Er ENOENT .Bl -bullet -compact .It .Dv PT_VM_ENTRY previously returned the last entry of the memory map. No more entries exist. .El .It Bq Er ENAMETOOLONG .Bl -bullet -compact .It .Dv PT_VM_ENTRY cannot return the pathname of the backing object because the buffer is not big enough. .Fa pve_pathlen holds the minimum buffer size required on return. .El .El .Sh SEE ALSO .Xr execve 2 , .Xr sigaction 2 , .Xr wait 2 , .Xr execv 3 , .Xr i386_clr_watch 3 , .Xr i386_set_watch 3 .Sh HISTORY The .Fn ptrace function appeared in .At v7 . Index: head/lib/libfetch/fetch.3 =================================================================== --- head/lib/libfetch/fetch.3 (revision 297354) +++ head/lib/libfetch/fetch.3 (revision 297355) @@ -1,844 +1,843 @@ .\"- .\" Copyright (c) 1998-2013 Dag-Erling Smørgrav .\" Copyright (c) 2013-2016 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 March 18, 2016 .Dt FETCH 3 .Os .Sh NAME .Nm fetchMakeURL , .Nm fetchParseURL , .Nm fetchFreeURL , .Nm fetchXGetURL , .Nm fetchGetURL , .Nm fetchPutURL , .Nm fetchStatURL , .Nm fetchListURL , .Nm fetchXGet , .Nm fetchGet , .Nm fetchPut , .Nm fetchStat , .Nm fetchList , .Nm fetchXGetFile , .Nm fetchGetFile , .Nm fetchPutFile , .Nm fetchStatFile , .Nm fetchListFile , .Nm fetchXGetHTTP , .Nm fetchGetHTTP , .Nm fetchPutHTTP , .Nm fetchStatHTTP , .Nm fetchListHTTP , .Nm fetchXGetFTP , .Nm fetchGetFTP , .Nm fetchPutFTP , .Nm fetchStatFTP , .Nm fetchListFTP .Nd file transfer functions .Sh LIBRARY .Lb libfetch .Sh SYNOPSIS .In sys/param.h .In stdio.h .In fetch.h .Ft struct url * .Fn fetchMakeURL "const char *scheme" "const char *host" "int port" "const char *doc" "const char *user" "const char *pwd" .Ft struct url * .Fn fetchParseURL "const char *URL" .Ft void .Fn fetchFreeURL "struct url *u" .Ft FILE * .Fn fetchXGetURL "const char *URL" "struct url_stat *us" "const char *flags" .Ft FILE * .Fn fetchGetURL "const char *URL" "const char *flags" .Ft FILE * .Fn fetchPutURL "const char *URL" "const char *flags" .Ft int .Fn fetchStatURL "const char *URL" "struct url_stat *us" "const char *flags" .Ft struct url_ent * .Fn fetchListURL "const char *URL" "const char *flags" .Ft FILE * .Fn fetchXGet "struct url *u" "struct url_stat *us" "const char *flags" .Ft FILE * .Fn fetchGet "struct url *u" "const char *flags" .Ft FILE * .Fn fetchPut "struct url *u" "const char *flags" .Ft int .Fn fetchStat "struct url *u" "struct url_stat *us" "const char *flags" .Ft struct url_ent * .Fn fetchList "struct url *u" "const char *flags" .Ft FILE * .Fn fetchXGetFile "struct url *u" "struct url_stat *us" "const char *flags" .Ft FILE * .Fn fetchGetFile "struct url *u" "const char *flags" .Ft FILE * .Fn fetchPutFile "struct url *u" "const char *flags" .Ft int .Fn fetchStatFile "struct url *u" "struct url_stat *us" "const char *flags" .Ft struct url_ent * .Fn fetchListFile "struct url *u" "const char *flags" .Ft FILE * .Fn fetchXGetHTTP "struct url *u" "struct url_stat *us" "const char *flags" .Ft FILE * .Fn fetchGetHTTP "struct url *u" "const char *flags" .Ft FILE * .Fn fetchPutHTTP "struct url *u" "const char *flags" .Ft int .Fn fetchStatHTTP "struct url *u" "struct url_stat *us" "const char *flags" .Ft struct url_ent * .Fn fetchListHTTP "struct url *u" "const char *flags" .Ft FILE * .Fn fetchXGetFTP "struct url *u" "struct url_stat *us" "const char *flags" .Ft FILE * .Fn fetchGetFTP "struct url *u" "const char *flags" .Ft FILE * .Fn fetchPutFTP "struct url *u" "const char *flags" .Ft int .Fn fetchStatFTP "struct url *u" "struct url_stat *us" "const char *flags" .Ft struct url_ent * .Fn fetchListFTP "struct url *u" "const char *flags" .Sh DESCRIPTION These functions implement a high-level library for retrieving and uploading files using Uniform Resource Locators (URLs). .Pp .Fn fetchParseURL takes a URL in the form of a null-terminated string and splits it into its components function according to the Common Internet Scheme Syntax detailed in RFC1738. A regular expression which produces this syntax is: .Bd -literal :(//((:)?@)?(:)?)?/()? .Ed .Pp If the URL does not seem to begin with a scheme name, the following syntax is assumed: .Bd -literal (((:)?@)?(:)?)?/()? .Ed .Pp Note that some components of the URL are not necessarily relevant to all URL schemes. For instance, the file scheme only needs the and components. .Pp .Fn fetchMakeURL and .Fn fetchParseURL return a pointer to a .Vt url structure, which is defined as follows in .In fetch.h : .Bd -literal #define URL_SCHEMELEN 16 #define URL_USERLEN 256 #define URL_PWDLEN 256 struct url { char scheme[URL_SCHEMELEN+1]; char user[URL_USERLEN+1]; char pwd[URL_PWDLEN+1]; char host[MAXHOSTNAMELEN+1]; int port; char *doc; off_t offset; size_t length; time_t ims_time; }; .Ed .Pp The .Va ims_time field stores the time value for .Li If-Modified-Since HTTP requests. .Pp The pointer returned by .Fn fetchMakeURL or .Fn fetchParseURL should be freed using .Fn fetchFreeURL . .Pp .Fn fetchXGetURL , .Fn fetchGetURL , and .Fn fetchPutURL constitute the recommended interface to the .Nm fetch library. They examine the URL passed to them to determine the transfer method, and call the appropriate lower-level functions to perform the actual transfer. .Fn fetchXGetURL also returns the remote document's metadata in the .Vt url_stat structure pointed to by the .Fa us argument. .Pp The .Fa flags argument is a string of characters which specify transfer options. The meaning of the individual flags is scheme-dependent, and is detailed in the appropriate section below. .Pp .Fn fetchStatURL attempts to obtain the requested document's metadata and fill in the structure pointed to by its second argument. The .Vt url_stat structure is defined as follows in .In fetch.h : .Bd -literal struct url_stat { off_t size; time_t atime; time_t mtime; }; .Ed .Pp If the size could not be obtained from the server, the .Fa size field is set to -1. If the modification time could not be obtained from the server, the .Fa mtime field is set to the epoch. If the access time could not be obtained from the server, the .Fa atime field is set to the modification time. .Pp .Fn fetchListURL attempts to list the contents of the directory pointed to by the URL provided. If successful, it returns a malloced array of .Vt url_ent structures. The .Vt url_ent structure is defined as follows in .In fetch.h : .Bd -literal struct url_ent { char name[PATH_MAX]; struct url_stat stat; }; .Ed .Pp The list is terminated by an entry with an empty name. .Pp The pointer returned by .Fn fetchListURL should be freed using .Fn free . .Pp .Fn fetchXGet , .Fn fetchGet , .Fn fetchPut and .Fn fetchStat are similar to .Fn fetchXGetURL , .Fn fetchGetURL , .Fn fetchPutURL and .Fn fetchStatURL , except that they expect a pre-parsed URL in the form of a pointer to a .Vt struct url rather than a string. .Pp All of the .Fn fetchXGetXXX , .Fn fetchGetXXX and .Fn fetchPutXXX functions return a pointer to a stream which can be used to read or write data from or to the requested document, respectively. Note that although the implementation details of the individual access methods vary, it can generally be assumed that a stream returned by one of the .Fn fetchXGetXXX or .Fn fetchGetXXX functions is read-only, and that a stream returned by one of the .Fn fetchPutXXX functions is write-only. .Sh FILE SCHEME .Fn fetchXGetFile , .Fn fetchGetFile and .Fn fetchPutFile provide access to documents which are files in a locally mounted file system. Only the component of the URL is used. .Pp .Fn fetchXGetFile and .Fn fetchGetFile do not accept any flags. .Pp .Fn fetchPutFile accepts the .Ql a (append to file) flag. If that flag is specified, the data written to the stream returned by .Fn fetchPutFile will be appended to the previous contents of the file, instead of replacing them. .Sh FTP SCHEME .Fn fetchXGetFTP , .Fn fetchGetFTP and .Fn fetchPutFTP implement the FTP protocol as described in RFC959. .Pp If the .Ql P (not passive) flag is specified, an active (rather than passive) connection will be attempted. .Pp The .Ql p flag is supported for compatibility with earlier versions where active connections were the default. It has precedence over the .Ql P flag, so if both are specified, .Nm will use a passive connection. .Pp If the .Ql l (low) flag is specified, data sockets will be allocated in the low (or default) port range instead of the high port range (see .Xr ip 4 ) . .Pp If the .Ql d (direct) flag is specified, .Fn fetchXGetFTP , .Fn fetchGetFTP and .Fn fetchPutFTP will use a direct connection even if a proxy server is defined. .Pp If no user name or password is given, the .Nm fetch library will attempt an anonymous login, with user name "anonymous" and password "anonymous@". .Sh HTTP SCHEME The .Fn fetchXGetHTTP , .Fn fetchGetHTTP and .Fn fetchPutHTTP functions implement the HTTP/1.1 protocol. With a little luck, there is even a chance that they comply with RFC2616 and RFC2617. .Pp If the .Ql d (direct) flag is specified, .Fn fetchXGetHTTP , .Fn fetchGetHTTP and .Fn fetchPutHTTP will use a direct connection even if a proxy server is defined. .Pp If the .Ql i (if-modified-since) flag is specified, and the .Va ims_time field is set in .Vt "struct url" , then .Fn fetchXGetHTTP and .Fn fetchGetHTTP will send a conditional .Li If-Modified-Since HTTP header to only fetch the content if it is newer than .Va ims_time . .Pp Since there seems to be no good way of implementing the HTTP PUT method in a manner consistent with the rest of the .Nm fetch library, .Fn fetchPutHTTP is currently unimplemented. .Sh HTTPS SCHEME Based on HTTP SCHEME. By default the peer is verified using the CA bundle located in .Pa /usr/local/etc/ssl/cert.pem . If this file does not exist, .Pa /etc/ssl/cert.pem is used instead. If neither file exists, and .Ev SSL_CA_CERT_PATH has not been set, OpenSSL's default CA cert and path settings apply. The certificate bundle can contain multiple CA certificates. A common source of a current CA bundle is .Pa \%security/ca_root_nss . .Pp The CA bundle used for peer verification can be changed by setting the environment variables .Ev SSL_CA_CERT_FILE to point to a concatenated bundle of trusted certificates and .Ev SSL_CA_CERT_PATH to point to a directory containing hashes of trusted CAs (see .Xr verify 1 ) . .Pp A certificate revocation list (CRL) can be used by setting the environment variable .Ev SSL_CRL_FILE (see .Xr crl 1 ) . .Pp Peer verification can be disabled by setting the environment variable .Ev SSL_NO_VERIFY_PEER . Note that this also disables CRL checking. .Pp By default the service identity is verified according to the rules detailed in RFC6125 (also known as hostname verification). This feature can be disabled by setting the environment variable .Ev SSL_NO_VERIFY_HOSTNAME . .Pp Client certificate based authentication is supported. The environment variable .Ev SSL_CLIENT_CERT_FILE should be set to point to a file containing key and client certificate to be used in PEM format. When a PEM-format key is in a separate file from the client certificate, the environment variable .Ev SSL_CLIENT_KEY_FILE can be set to point to the key file. In case the key uses a password, the user will be prompted on standard input (see .Xr PEM 3 ) . .Pp By default .Nm libfetch allows TLSv1 and newer when negotiating the connecting with the remote peer. You can change this behavior by setting the .Ev SSL_ALLOW_SSL3 environment variable to allow SSLv3 and .Ev SSL_NO_TLS1 , .Ev SSL_NO_TLS1_1 and .Ev SSL_NO_TLS1_2 to disable TLS 1.0, 1.1 and 1.2 respectively. .Sh AUTHENTICATION Apart from setting the appropriate environment variables and specifying the user name and password in the URL or the .Vt struct url , the calling program has the option of defining an authentication function with the following prototype: .Pp .Ft int .Fn myAuthMethod "struct url *u" .Pp The callback function should fill in the .Fa user and .Fa pwd fields in the provided .Vt struct url and return 0 on success, or any other value to indicate failure. .Pp To register the authentication callback, simply set .Va fetchAuthMethod to point at it. The callback will be used whenever a site requires authentication and the appropriate environment variables are not set. .Pp This interface is experimental and may be subject to change. .Sh RETURN VALUES .Fn fetchParseURL returns a pointer to a .Vt struct url containing the individual components of the URL. If it is unable to allocate memory, or the URL is syntactically incorrect, .Fn fetchParseURL returns a NULL pointer. .Pp The .Fn fetchStat functions return 0 on success and -1 on failure. .Pp All other functions return a stream pointer which may be used to access the requested document, or NULL if an error occurred. .Pp The following error codes are defined in .In fetch.h : .Bl -tag -width 18n .It Bq Er FETCH_ABORT Operation aborted .It Bq Er FETCH_AUTH Authentication failed .It Bq Er FETCH_DOWN Service unavailable .It Bq Er FETCH_EXISTS File exists .It Bq Er FETCH_FULL File system full .It Bq Er FETCH_INFO Informational response .It Bq Er FETCH_MEMORY Insufficient memory .It Bq Er FETCH_MOVED File has moved .It Bq Er FETCH_NETWORK Network error .It Bq Er FETCH_OK No error .It Bq Er FETCH_PROTO Protocol error .It Bq Er FETCH_RESOLV Resolver error .It Bq Er FETCH_SERVER Server error .It Bq Er FETCH_TEMP Temporary error .It Bq Er FETCH_TIMEOUT Operation timed out .It Bq Er FETCH_UNAVAIL File is not available .It Bq Er FETCH_UNKNOWN Unknown error .It Bq Er FETCH_URL Invalid URL .El .Pp The accompanying error message includes a protocol-specific error code and message, like "File is not available (404 Not Found)" .Sh ENVIRONMENT .Bl -tag -width ".Ev FETCH_BIND_ADDRESS" .It Ev FETCH_BIND_ADDRESS Specifies a hostname or IP address to which sockets used for outgoing connections will be bound. .It Ev FTP_LOGIN Default FTP login if none was provided in the URL. .It Ev FTP_PASSIVE_MODE If set to .Ql no , forces the FTP code to use active mode. If set to any other value, forces passive mode even if the application requested active mode. .It Ev FTP_PASSWORD Default FTP password if the remote server requests one and none was provided in the URL. .It Ev FTP_PROXY URL of the proxy to use for FTP requests. The document part is ignored. FTP and HTTP proxies are supported; if no scheme is specified, FTP is assumed. If the proxy is an FTP proxy, .Nm libfetch will send .Ql user@host as user name to the proxy, where .Ql user is the real user name, and .Ql host is the name of the FTP server. .Pp If this variable is set to an empty string, no proxy will be used for FTP requests, even if the .Ev HTTP_PROXY variable is set. .It Ev ftp_proxy Same as .Ev FTP_PROXY , for compatibility. .It Ev HTTP_ACCEPT Specifies the value of the .Va Accept header for HTTP requests. If empty, no .Va Accept header is sent. The default is .Dq */* . .It Ev HTTP_AUTH Specifies HTTP authorization parameters as a colon-separated list of items. The first and second item are the authorization scheme and realm respectively; further items are scheme-dependent. Currently, the .Dq basic and .Dq digest authorization methods are supported. .Pp Both methods require two parameters: the user name and password, in that order. .Pp This variable is only used if the server requires authorization and no user name or password was specified in the URL. .It Ev HTTP_PROXY URL of the proxy to use for HTTP requests. The document part is ignored. Only HTTP proxies are supported for HTTP requests. If no port number is specified, the default is 3128. .Pp Note that this proxy will also be used for FTP documents, unless the .Ev FTP_PROXY variable is set. .It Ev http_proxy Same as .Ev HTTP_PROXY , for compatibility. .It Ev HTTP_PROXY_AUTH Specifies authorization parameters for the HTTP proxy in the same format as the .Ev HTTP_AUTH variable. .Pp This variable is used if and only if connected to an HTTP proxy, and is ignored if a user and/or a password were specified in the proxy URL. .It Ev HTTP_REFERER Specifies the referrer URL to use for HTTP requests. If set to .Dq auto , the document URL will be used as referrer URL. .It Ev HTTP_USER_AGENT Specifies the User-Agent string to use for HTTP requests. This can be useful when working with HTTP origin or proxy servers that differentiate between user agents. If defined but empty, no User-Agent header is sent. .It Ev NETRC Specifies a file to use instead of .Pa ~/.netrc to look up login names and passwords for FTP and HTTP sites as well as HTTP proxies. See .Xr ftp 1 for a description of the file format. .It Ev NO_PROXY Either a single asterisk, which disables the use of proxies altogether, or a comma- or whitespace-separated list of hosts for which proxies should not be used. .It Ev no_proxy Same as .Ev NO_PROXY , for compatibility. .It Ev SSL_ALLOW_SSL3 Allow SSL version 3 when negotiating the connection (not recommended). .It Ev SSL_CA_CERT_FILE CA certificate bundle containing trusted CA certificates. Default value: See HTTPS SCHEME above. .It Ev SSL_CA_CERT_PATH Path containing trusted CA hashes. .It Ev SSL_CLIENT_CERT_FILE PEM encoded client certificate/key which will be used in client certificate authentication. .It Ev SSL_CLIENT_KEY_FILE PEM encoded client key in case key and client certificate are stored separately. .It Ev SSL_CRL_FILE File containing certificate revocation list. .It Ev SSL_NO_TLS1 Do not allow TLS version 1.0 when negotiating the connection. .It Ev SSL_NO_TLS1_1 Do not allow TLS version 1.1 when negotiating the connection. .It Ev SSL_NO_TLS1_2 Do not allow TLS version 1.2 when negotiating the connection. .It Ev SSL_NO_VERIFY_HOSTNAME If set, do not verify that the hostname matches the subject of the certificate presented by the server. .It Ev SSL_NO_VERIFY_PEER If set, do not verify the peer certificate against trusted CAs. .El .Sh EXAMPLES To access a proxy server on .Pa proxy.example.com port 8080, set the .Ev HTTP_PROXY environment variable in a manner similar to this: .Pp .Dl HTTP_PROXY=http://proxy.example.com:8080 .Pp If the proxy server requires authentication, there are two options available for passing the authentication data. The first method is by using the proxy URL: .Pp .Dl HTTP_PROXY=http://:@proxy.example.com:8080 .Pp The second method is by using the .Ev HTTP_PROXY_AUTH environment variable: .Bd -literal -offset indent HTTP_PROXY=http://proxy.example.com:8080 HTTP_PROXY_AUTH=basic:*:: .Ed .Pp To disable the use of a proxy for an HTTP server running on the local host, define .Ev NO_PROXY as follows: .Bd -literal -offset indent NO_PROXY=localhost,127.0.0.1 .Ed .Pp Access HTTPS website without any certificate verification whatsoever: .Bd -literal -offset indent SSL_NO_VERIFY_PEER=1 SSL_NO_VERIFY_HOSTNAME=1 .Ed .Pp Access HTTPS website using client certificate based authentication and a private CA: .Bd -literal -offset indent SSL_CLIENT_CERT_FILE=/path/to/client.pem SSL_CA_CERT_FILE=/path/to/myca.pem .Ed .Sh SEE ALSO .Xr fetch 1 , -.Xr ftpio 3 , .Xr ip 4 .Rs .%A J. Postel .%A J. K. Reynolds .%D October 1985 .%B File Transfer Protocol .%O RFC959 .Re .Rs .%A P. Deutsch .%A A. Emtage .%A A. Marine. .%D May 1994 .%T How to Use Anonymous FTP .%O RFC1635 .Re .Rs .%A T. Berners-Lee .%A L. Masinter .%A M. McCahill .%D December 1994 .%T Uniform Resource Locators (URL) .%O RFC1738 .Re .Rs .%A R. Fielding .%A J. Gettys .%A J. Mogul .%A H. Frystyk .%A L. Masinter .%A P. Leach .%A T. Berners-Lee .%D January 1999 .%B Hypertext Transfer Protocol -- HTTP/1.1 .%O RFC2616 .Re .Rs .%A J. Franks .%A P. Hallam-Baker .%A J. Hostetler .%A S. Lawrence .%A P. Leach .%A A. Luotonen .%A L. Stewart .%D June 1999 .%B HTTP Authentication: Basic and Digest Access Authentication .%O RFC2617 .Re .Sh HISTORY The .Nm fetch library first appeared in .Fx 3.0 . .Sh AUTHORS .An -nosplit The .Nm fetch library was mostly written by .An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org with numerous suggestions and contributions from .An Jordan K. Hubbard Aq Mt jkh@FreeBSD.org , .An Eugene Skepner Aq Mt eu@qub.com , .An Hajimu Umemoto Aq Mt ume@FreeBSD.org , .An Henry Whincup Aq Mt henry@techiebod.com , .An Jukka A. Ukkonen Aq Mt jau@iki.fi , .An Jean-Fran\(,cois Dockes Aq Mt jf@dockes.org , .An Michael Gmelin Aq Mt freebsd@grem.de and others. It replaces the older .Nm ftpio library written by .An Poul-Henning Kamp Aq Mt phk@FreeBSD.org and .An Jordan K. Hubbard Aq Mt jkh@FreeBSD.org . .Pp This manual page was written by .An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org and .An Michael Gmelin Aq Mt freebsd@grem.de . .Sh BUGS Some parts of the library are not yet implemented. The most notable examples of this are .Fn fetchPutHTTP , .Fn fetchListHTTP , .Fn fetchListFTP and FTP proxy support. .Pp There is no way to select a proxy at run-time other than setting the .Ev HTTP_PROXY or .Ev FTP_PROXY environment variables as appropriate. .Pp .Nm libfetch does not understand or obey 305 (Use Proxy) replies. .Pp Error numbers are unique only within a certain context; the error codes used for FTP and HTTP overlap, as do those used for resolver and system errors. For instance, error code 202 means "Command not implemented, superfluous at this site" in an FTP context and "Accepted" in an HTTP context. .Pp .Fn fetchStatFTP does not check that the result of an MDTM command is a valid date. .Pp In case password protected keys are used for client certificate based authentication the user is prompted for the password on each and every fetch operation. .Pp The man page is incomplete, poorly written and produces badly formatted text. .Pp The error reporting mechanism is unsatisfactory. .Pp Some parts of the code are not fully reentrant. Index: head/sbin/atm/atmconfig/atmconfig.8 =================================================================== --- head/sbin/atm/atmconfig/atmconfig.8 (revision 297354) +++ head/sbin/atm/atmconfig/atmconfig.8 (revision 297355) @@ -1,319 +1,318 @@ .\" .\" Copyright (c) 2001-2003 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). .\" 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. .\" .\" Author: Hartmut Brandt .\" .\" $FreeBSD$ .\" .Dd August 11, 2003 .Dt ATMCONFIG 8 .Os .Sh NAME .Nm atmconfig .Nd "ATM configuration tool" .Sh SYNOPSIS .Nm .Op Fl htv .Op Ar command Op Ar sub-command Op ... .Op Ar options .Op Ar arg ... .Sh DESCRIPTION The .Nm tool is used to configure the Netgraph ATM network sub-system. .Pp The command line of .Nm generally consists of common options followed by a command string, optionally followed by sub-command strings, optional command specific options and command specific arguments. Commands and sub-commands as well as command specific options may be abbreviated as long as there is only one match possible. .Ss Common Options The following common options change the overall behaviour of .Nm : .Bl -tag -width indent .It Fl h Print a very short usage info and exit. .It Fl t Several show-type commands output a header and then several lines of information. If this option is given, the header is omitted, simplifying the parsing of the output. .It Fl v Be more verbose. .El .Ss Obtaining Help The .Ic help command has a number of useful sub-commands. .Pp To get general help use: .D1 Nm Ic help .Pp To get a list of available commands use: .D1 Nm Ic help Cm commands .Pp To get a list of available sub-commands use: .D1 Nm Ic help Ar command .Pp or (if there are deeper levels of sub-commands): .D1 Nm Ic help Ar command sub-command ... .Pp To get a list of options and arguments for a command use: .D1 Nm Ic help Ar command sub-command ... (given that there are no further sub-command levels). .Pp To get a list of common options use: .D1 Nm Ic help Cm options .Ss The Ic diag Command The .Ic diag command allows the inspection of the ATM interfaces on the local host and the modification of device parameters. Sub-commands are: .Cm list (print a list of interfaces), .Cm config (print hardware configuration), .Cm phy (access PHY chip), .Cm stats (print statistics) and .Cm vcc (print list of VCCs). .Bl -tag -width indent .\"---------------------------------------- .It Nm Ic diag Cm list This sub-command lists all ATM interfaces in the system. It takes no options or arguments. .\"---------------------------------------- .It Xo .Nm Ic diag Cm config .Op Fl atm .Op Fl hardware .Op Ar device ... .Xc This command prints the configuration of ATM interfaces. If no .Ar device is given, all devices are listed, otherwise only the specified devices. The option .Fl atm instructs the command to print ATM layer configuration parameters like the number of VCI and VPI bits, whereas the .Fl hardware option requests card specific information like the vendor or the serial number. If none of the options is given, the defaults is to assume .Fl atm . .\"---------------------------------------- .It Xo .Nm Ic diag Cm phy print .Op Fl numeric .Ar device .Xc This command prints the PHY registers in a (potential) human comprehensible format. If .Fl numeric is given, the format is hex bytes. Otherwise, textual representation will be printed. .\"---------------------------------------- .It Nm Ic diag Cm phy show Op Ar device ... This sub-command prints static information about the PHY device used in the ATM card like the type of the PHY and the media. .\"---------------------------------------- .It Xo .Nm Ic diag Cm phy set .Ar device .Ar reg .Ar mask .Ar val .Xc This sub-command allows one to change bits in PHY registers. This should be used with great care. The bits of the given PHY chip register for which the corresponding bit in .Ar mask is one are set to the values of the corresponding bits in .Ar val . All register bits that have a zero in .Ar mask are written back with their original value. .\"---------------------------------------- .It Xo .Nm Ic diag Cm phy stats .Op Fl clear .Ar device .Xc Print the PHY statistics for the given .Ar device . When the optional .Fl clear is given, the statistics are cleared atomically. .\"---------------------------------------- .It Xo .Nm Ic diag Cm vcc .Op Fl abr .Op Fl channel .Op Fl traffic .Op Ar device .Xc Retrieve the list of currently active channels on either all or the specified interfaces. For each channel, the following information is printed depending on the options (default is .Fl channel ) . .Bl -tag -width ".Fl traffic" .It Fl abr Print ABR specific traffic parameters: ICR, TBE, NRM, TRM, ADTF, RIF, RDF, CDF. .It Fl channel Print basic information: VPI, VCI, AAL, traffic type, MTU and flags. .It Fl traffic Print traffic parameters: PCR, SCR, MBS, MCR. .El .\"---------------------------------------- .It Nm Ic diag Cm stats Ar device Print driver specific statistics. .El .Ss The Ic natm Command The .Ic natm command is used to change .Xr natmip 4 routes on the local host. The sub-commands for the routing table are: .Cm add (to add a new route), .Cm delete (to delete an existing route) and .Cm show (to print the currently installed NATM routes). .Pp .Bl -tag -width indent -compact .\"---------------------------------------- .It Xo .Nm Ic natm Cm add .Ar dest .Ar device .Ar vpi .Ar vci .Ar encaps .Xc .It Xo .Nm Ic natm Cm add .Ar dest .Ar device .Ar vpi .Ar vci .Ar encaps .Cm ubr Op Ar pcr .Xc .It Xo .Nm Ic natm Cm add .Ar dest .Ar device .Ar vpi .Ar vci .Ar encaps .Cm cbr Ar pcr .Xc .It Xo .Nm Ic natm Cm add .Ar dest .Ar device .Ar vpi .Ar vci .Ar encaps .Cm vbr Ar pcr scr mbs .Xc .It Xo .Nm Ic natm Cm add .Ar dest .Ar device .Ar vpi .Ar vci .Ar encaps .Cm abr Ar pcr mcr icr tbe nrm trm adtf rif rdf cdf .Xc Add a new route to the routing table. The destination address (the address on the other end of the link) is given in .Ar dest . The .Ar device , .Ar vpi and .Ar vci arguments are the name of the ATM device and the VPI and VCI values for the link. The .Ar encaps argument may be either .Cm AAL5 or .Cm LLC/SNAP both of which specify AAL5 encapsulation, the first one without additional encapsulation, the second one with LLC/SNAP headers. The first two forms of the command add an UBR (unspecified bit rate) channel, where the second form allows the optional specification of a peak cell rate (PCR). The third form adds a CBR (constant bit rate) channel where a PCR must be given. The fourth form adds a VBR (variable bit rate) channel. The arguments are the peak cell rate, the sustainable cell rate and the maximum bursts size. The last form of the command adds an ABR (available bit rate) channel. .\"---------------------------------------- .Pp .It Nm Ic natm Cm delete Ar dest .It Xo .Nm Ic natm Cm delete .Ar device .Ar vpi .Ar vci .Xc This commands deletes an NATM route. The route may be specified either by the destination address or by the .Ar device , vpi and .Ar vci triple. .\"---------------------------------------- .Pp .It Nm Ic natm Cm show List all NATM routes. .El .Sh SEE ALSO .Xr natm 4 , -.Xr natmip 4 , -.Xr atm 8 +.Xr natmip 4 .Sh AUTHORS .An Hartmut Brandt Aq Mt harti@FreeBSD.org Index: head/share/man/man4/cyapa.4 =================================================================== --- head/share/man/man4/cyapa.4 (revision 297354) +++ head/share/man/man4/cyapa.4 (revision 297355) @@ -1,200 +1,200 @@ .\" 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 July 25, 2015 .Dt CYAPA 4 .Os .Sh NAME .Nm cyapa .Nd Cypress APA trackpad with I2C interface driver .Sh SYNOPSIS To compile this driver into the kernel, place the following lines into the kernel configuration file: .Bd -ragged -offset indent .Cd "device cyapa" .Cd "device ig4" .Cd "device smbus" .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 cyapa_load="YES" ig4_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for the Cypress APA trackpad. It emulates the IntelliMouse PS/2 protocol. It supports basic mouse ioctls, so that .Xr moused 8 is supported properly. .Ss Trackpad layout .Bd -literal 2/3 1/3 +--------------------+------------+ | | Middle | | | Button | | Left | | | Button +------------+ | | Right | | | Button | +--------------------+............| | Thumb/Button Area | 15% +---------------------------------+ .Ed .Ss Trackpad features .Bl -tag -width 8n .It Va Two finger scrolling Use two fingers for Z axis scrolling. .It Va Button down/second finger While one finger clicks and holds down the touchpad, the second finger can be used to move the mouse cursor. This can be useful for drawing or selecting text. .It Va Thumb/Button area The lower 15% of the trackpad will not affect the mouse cursor position. This allows for high precision clicking, by controlling the cursor with the index finger and pushing/holding the pad down with the thumb. .It Va Trackpad button Push physical button. The left two thirds of the pad issues a LEFT button event. The upper right corner issues a MIDDLE button event. The lower right corner issues a RIGHT button. Optionally, tap to click can be enabled (see below). .El .Sh SYSCTL VARIABLES These .Xr sysctl 8 variables are available: .Bl -tag -width 8n .It Va debug.cyapa_idle_freq Scan frequency in idle mode, the default is 1. .It Va debug.cyapa_slow_freq Scan frequency in slow mode, the default is 20. .It Va debug.cyapa_norm_freq Scan frequency in normal mode, the default is 100. .It Va debug.cyapa_minpressure Minimum pressure to detect a finger, the default is 12. .It Va debug.cyapa_enable_tapclick Controls tap to click. Possible values: .Bl -tag -width 8n .It 0 Tap to click is disabled. This is the default value. .It 1 Tap to click always generates a left mouse button event. .It 2 Tap to click generates left mouse button event if the left 2/3rds of the pad are tapped and a right mouse button event otherwise. .It 3 Tap to click generates mouse button events as if the physical button was pressed (see .Sx DESCRIPTION above). .El .It Va debug.cyapa_tapclick_min_ticks Minimum tap duration in ticks to create a click, the default is 1. .It Va debug.cyapa_tapclick_max_ticks Maximum tap duration in ticks to create a click, the default is 8. .It Va debug.cyapa_move_min_ticks Minimum ticks before cursor movement occurs, the default is 4. .It Va debug.cyapa_scroll_wait_ticks Ticks to wait before starting to scroll, the default is 0. .It Va debug.cyapa_scroll_stick_ticks Ticks while preventing cursor movement on single finger after scroll, the default is 15. .It Va debug.cyapa_thumbarea_percent Size of bottom thumb area in percent, the default is 15. .It Va debug.cyapa_debug Setting this to a non-zero value enables debug output to console and syslog, the default is 0. .It Va debug.cyapa_reset Setting this to a non-zero value reinitializes the device. The sysctl resets to zero immediately. .El .Sh FILES .Nm creates .Pa /dev/cyapa0 , which presents the mouse as an .Ar IntelliMouse PS/2 device. It supports .Xr moused 8 levels 0 through 2, level 1 is used by default. .Sh EXAMPLES To use .Nm with .Xr moused 8 , add the following lines to the .Xr rc.conf 5 file: .Pp .Dl moused_enable="YES" .Dl moused_port="/dev/cyapa0" .Pp If vertical scrolling is not desired, add .Pp .Dl moused_flags="-l0" .Pp to .Xr rc.conf 5 . .Pp Enable tap to click for the left and the right mouse button and disable the thumb area by adding these lines to the .Xr sysctl.conf 5 file: .Pp .Dl debug.cyapa_thumbarea_percent=0 .Dl debug.cyapa_enable_tapclick=2 .Sh SEE ALSO .Xr ig4 4 , -.Xr moused 4 , .Xr smbus 4 , -.Xr sysmouse 4 +.Xr sysmouse 4 , +.Xr moused 8 .Sh AUTHORS .An -nosplit The original .Nm driver was written for DragonFly BSD by .An Matthew Dillon . .Pp It has been ported, modified, and enhanced for .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 . .Sh BUGS The .Nm driver detects the device based on its I2C address (0x67). This might have unforeseen consequences if the initialization sequence is sent to an unknown device at that address. Index: head/share/man/man4/ddb.4 =================================================================== --- head/share/man/man4/ddb.4 (revision 297354) +++ head/share/man/man4/ddb.4 (revision 297355) @@ -1,1530 +1,1530 @@ .\" .\" Mach Operating System .\" Copyright (c) 1991,1990 Carnegie Mellon University .\" Copyright (c) 2007 Robert N. M. Watson .\" All Rights Reserved. .\" .\" Permission to use, copy, modify and distribute this software and its .\" documentation is hereby granted, provided that both the copyright .\" notice and this permission notice appear in all copies of the .\" software, derivative works or modified versions, and any portions .\" thereof, and that both notices appear in supporting documentation. .\" .\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" .\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR .\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. .\" .\" Carnegie Mellon requests users of this software to return to .\" .\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU .\" School of Computer Science .\" Carnegie Mellon University .\" Pittsburgh PA 15213-3890 .\" .\" any improvements or extensions that they make and grant Carnegie Mellon .\" the rights to redistribute these changes. .\" .\" changed a \# to #, since groff choked on it. .\" .\" HISTORY .\" ddb.4,v .\" Revision 1.1 1993/07/15 18:41:02 brezak .\" Man page for DDB .\" .\" Revision 2.6 92/04/08 08:52:57 rpd .\" Changes from OSF. .\" [92/01/17 14:19:22 jsb] .\" Changes for OSF debugger modifications. .\" [91/12/12 tak] .\" .\" Revision 2.5 91/06/25 13:50:22 rpd .\" Added some watchpoint explanation. .\" [91/06/25 rpd] .\" .\" Revision 2.4 91/06/17 15:47:31 jsb .\" Added documentation for continue/c, match, search, and watchpoints. .\" I've not actually explained what a watchpoint is; maybe Rich can .\" do that (hint, hint). .\" [91/06/17 10:58:08 jsb] .\" .\" Revision 2.3 91/05/14 17:04:23 mrt .\" Correcting copyright .\" .\" Revision 2.2 91/02/14 14:10:06 mrt .\" Changed to new Mach copyright .\" [91/02/12 18:10:12 mrt] .\" .\" Revision 2.2 90/08/30 14:23:15 dbg .\" Created. .\" [90/08/30 dbg] .\" .\" $FreeBSD$ .\" .Dd January 15, 2016 .Dt DDB 4 .Os .Sh NAME .Nm ddb .Nd interactive kernel debugger .Sh SYNOPSIS In order to enable kernel debugging facilities include: .Bd -ragged -offset indent .Cd options KDB .Cd options DDB .Ed .Pp To prevent activation of the debugger on kernel .Xr panic 9 : .Bd -ragged -offset indent .Cd options KDB_UNATTENDED .Ed .Pp In order to print a stack trace of the current thread on the console for a panic: .Bd -ragged -offset indent .Cd options KDB_TRACE .Ed .Pp To print the numerical value of symbols in addition to the symbolic representation, define: .Bd -ragged -offset indent .Cd options DDB_NUMSYM .Ed .Pp To enable the .Xr gdb 1 backend, so that remote debugging with .Xr kgdb 1 is possible, include: .Bd -ragged -offset indent .Cd options GDB .Ed .Sh DESCRIPTION The .Nm kernel debugger is an interactive debugger with a syntax inspired by .Xr gdb 1 . If linked into the running kernel, it can be invoked locally with the .Ql debug .Xr keymap 5 action. The debugger is also invoked on kernel .Xr panic 9 if the .Va debug.debugger_on_panic .Xr sysctl 8 MIB variable is set non-zero, which is the default unless the .Dv KDB_UNATTENDED option is specified. .Pp The current location is called .Va dot . The .Va dot is displayed with a hexadecimal format at a prompt. The commands .Ic examine and .Ic write update .Va dot to the address of the last line examined or the last location modified, and set .Va next to the address of the next location to be examined or changed. Other commands do not change .Va dot , and set .Va next to be the same as .Va dot . .Pp The general command syntax is: .Ar command Ns Op Li / Ns Ar modifier .Ar address Ns Op Li , Ns Ar count .Pp A blank line repeats the previous command from the address .Va next with count 1 and no modifiers. Specifying .Ar address sets .Va dot to the address. Omitting .Ar address uses .Va dot . A missing .Ar count is taken to be 1 for printing commands or infinity for stack traces. .Pp The .Nm debugger has a pager feature (like the .Xr more 1 command) for the output. If an output line exceeds the number set in the .Va lines variable, it displays .Dq Li --More-- and waits for a response. The valid responses for it are: .Pp .Bl -tag -compact -width ".Li SPC" .It Li SPC one more page .It Li RET one more line .It Li q abort the current command, and return to the command input mode .El .Pp Finally, .Nm provides a small (currently 10 items) command history, and offers simple .Nm emacs Ns -style command line editing capabilities. In addition to the .Nm emacs control keys, the usual .Tn ANSI arrow keys may be used to browse through the history buffer, and move the cursor within the current line. .Sh COMMANDS .Bl -tag -width indent -compact .It Ic examine .It Ic x Display the addressed locations according to the formats in the modifier. Multiple modifier formats display multiple locations. If no format is specified, the last format specified for this command is used. .Pp The format characters are: .Bl -tag -compact -width indent .It Cm b look at by bytes (8 bits) .It Cm h look at by half words (16 bits) .It Cm l look at by long words (32 bits) .It Cm g look at by quad words (64 bits) .It Cm a print the location being displayed .It Cm A print the location with a line number if possible .It Cm x display in unsigned hex .It Cm z display in signed hex .It Cm o display in unsigned octal .It Cm d display in signed decimal .It Cm u display in unsigned decimal .It Cm r display in current radix, signed .It Cm c display low 8 bits as a character. Non-printing characters are displayed as an octal escape code (e.g., .Ql \e000 ) . .It Cm s display the null-terminated string at the location. Non-printing characters are displayed as octal escapes. .It Cm m display in unsigned hex with character dump at the end of each line. The location is also displayed in hex at the beginning of each line. .It Cm i display as an instruction .It Cm I display as an instruction with possible alternate formats depending on the machine, but none of the supported architectures have an alternate format. .It Cm S display a symbol name for the pointer stored at the address .El .Pp .It Ic xf Examine forward: execute an .Ic examine command with the last specified parameters to it except that the next address displayed by it is used as the start address. .Pp .It Ic xb Examine backward: execute an .Ic examine command with the last specified parameters to it except that the last start address subtracted by the size displayed by it is used as the start address. .Pp .It Ic print Ns Op Li / Ns Cm acdoruxz .It Ic p Ns Op Li / Ns Cm acdoruxz Print .Ar addr Ns s according to the modifier character (as described above for .Cm examine ) . Valid formats are: .Cm a , x , z , o , d , u , r , and .Cm c . If no modifier is specified, the last one specified to it is used. The argument .Ar addr can be a string, in which case it is printed as it is. For example: .Bd -literal -offset indent print/x "eax = " $eax "\enecx = " $ecx "\en" .Ed .Pp will print like: .Bd -literal -offset indent eax = xxxxxx ecx = yyyyyy .Ed .Pp .It Xo .Ic write Ns Op Li / Ns Cm bhl .Ar addr expr1 Op Ar expr2 ... .Xc .It Xo .Ic w Ns Op Li / Ns Cm bhl .Ar addr expr1 Op Ar expr2 ... .Xc Write the expressions specified after .Ar addr on the command line at succeeding locations starting with .Ar addr . The write unit size can be specified in the modifier with a letter .Cm b (byte), .Cm h (half word) or .Cm l (long word) respectively. If omitted, long word is assumed. .Pp .Sy Warning : since there is no delimiter between expressions, strange things may happen. It is best to enclose each expression in parentheses. .Pp .It Ic set Li $ Ns Ar variable Oo Li = Oc Ar expr Set the named variable or register with the value of .Ar expr . Valid variable names are described below. .Pp .It Ic break Ns Op Li / Ns Cm u .It Ic b Ns Op Li / Ns Cm u Set a break point at .Ar addr . If .Ar count is supplied, continues .Ar count \- 1 times before stopping at the break point. If the break point is set, a break point number is printed with .Ql # . This number can be used in deleting the break point or adding conditions to it. .Pp If the .Cm u modifier is specified, this command sets a break point in user address space. Without the .Cm u option, the address is considered to be in the kernel space, and a wrong space address is rejected with an error message. This modifier can be used only if it is supported by machine dependent routines. .Pp .Sy Warning : If a user text is shadowed by a normal user space debugger, user space break points may not work correctly. Setting a break point at the low-level code paths may also cause strange behavior. .Pp .It Ic delete Ar addr .It Ic d Ar addr .It Ic delete Li # Ns Ar number .It Ic d Li # Ns Ar number Delete the break point. The target break point can be specified by a break point number with .Ql # , or by using the same .Ar addr specified in the original .Ic break command. .Pp .It Ic watch Ar addr Ns Li , Ns Ar size Set a watchpoint for a region. Execution stops when an attempt to modify the region occurs. The .Ar size argument defaults to 4. If you specify a wrong space address, the request is rejected with an error message. .Pp .Sy Warning : Attempts to watch wired kernel memory may cause unrecoverable error in some systems such as i386. Watchpoints on user addresses work best. .Pp .It Ic hwatch Ar addr Ns Li , Ns Ar size Set a hardware watchpoint for a region if supported by the architecture. Execution stops when an attempt to modify the region occurs. The .Ar size argument defaults to 4. .Pp .Sy Warning : The hardware debug facilities do not have a concept of separate address spaces like the watch command does. Use .Ic hwatch for setting watchpoints on kernel address locations only, and avoid its use on user mode address spaces. .Pp .It Ic dhwatch Ar addr Ns Li , Ns Ar size Delete specified hardware watchpoint. .Pp .It Ic step Ns Op Li / Ns Cm p .It Ic s Ns Op Li / Ns Cm p Single step .Ar count times (the comma is a mandatory part of the syntax). If the .Cm p modifier is specified, print each instruction at each step. Otherwise, only print the last instruction. .Pp .Sy Warning : depending on machine type, it may not be possible to single-step through some low-level code paths or user space code. On machines with software-emulated single-stepping (e.g., pmax), stepping through code executed by interrupt handlers will probably do the wrong thing. .Pp .It Ic continue Ns Op Li / Ns Cm c .It Ic c Ns Op Li / Ns Cm c Continue execution until a breakpoint or watchpoint. If the .Cm c modifier is specified, count instructions while executing. Some machines (e.g., pmax) also count loads and stores. .Pp .Sy Warning : when counting, the debugger is really silently single-stepping. This means that single-stepping on low-level code may cause strange behavior. .Pp .It Ic until Ns Op Li / Ns Cm p Stop at the next call or return instruction. If the .Cm p modifier is specified, print the call nesting depth and the cumulative instruction count at each call or return. Otherwise, only print when the matching return is hit. .Pp .It Ic next Ns Op Li / Ns Cm p .It Ic match Ns Op Li / Ns Cm p Stop at the matching return instruction. If the .Cm p modifier is specified, print the call nesting depth and the cumulative instruction count at each call or return. Otherwise, only print when the matching return is hit. .Pp .It Xo .Ic trace Ns Op Li / Ns Cm u .Op Ar pid | tid .Op Li , Ns Ar count .Xc .It Xo .Ic t Ns Op Li / Ns Cm u .Op Ar pid | tid .Op Li , Ns Ar count .Xc .It Xo .Ic where Ns Op Li / Ns Cm u .Op Ar pid | tid .Op Li , Ns Ar count .Xc .It Xo .Ic bt Ns Op Li / Ns Cm u .Op Ar pid | tid .Op Li , Ns Ar count .Xc Stack trace. The .Cm u option traces user space; if omitted, .Ic trace only traces kernel space. The optional argument .Ar count is the number of frames to be traced. If .Ar count is omitted, all frames are printed. .Pp .Sy Warning : User space stack trace is valid only if the machine dependent code supports it. .Pp .It Xo .Ic search Ns Op Li / Ns Cm bhl .Ar addr .Ar value .Op Ar mask .Op Li , Ns Ar count .Xc Search memory for .Ar value . This command might fail in interesting ways if it does not find the searched-for value. This is because .Nm does not always recover from touching bad memory. The optional .Ar count argument limits the search. .\" .Pp .It Xo .Ic findstack .Ar addr .Xc Prints the thread address for a thread kernel-mode stack of which contains the specified address. If the thread is not found, search the thread stack cache and prints the cached stack address. Otherwise, prints nothing. .Pp .It Ic show Cm all procs Ns Op Li / Ns Cm m .It Ic ps Ns Op Li / Ns Cm m Display all process information. The process information may not be shown if it is not supported in the machine, or the bottom of the stack of the target process is not in the main memory at that time. The .Cm m modifier will alter the display to show VM map addresses for the process and not show other information. .\" .Pp .It Ic show Cm all ttys Show all TTY's within the system. Output is similar to .Xr pstat 8 , but also includes the address of the TTY structure. .\" .Pp .It Ic show Cm allchains Show the same information like "show lockchain" does, but for every thread in the system. .\" .Pp .It Ic show Cm alllocks Show all locks that are currently held. This command is only available if .Xr witness 4 is included in the kernel. .\" .Pp .It Ic show Cm allpcpu The same as "show pcpu", but for every CPU present in the system. .\" .Pp .It Ic show Cm allrman Show information related with resource management, including interrupt request lines, DMA request lines, I/O ports, I/O memory addresses, and Resource IDs. .\" .Pp .It Ic show Cm apic Dump data about APIC IDT vector mappings. .\" .Pp .It Ic show Cm breaks Show breakpoints set with the "break" command. .\" .Pp .It Ic show Cm bio Ar addr Show information about the bio structure .Vt struct bio present at .Ar addr . See the .Pa sys/bio.h header file and .Xr g_bio 9 for more details on the exact meaning of the structure fields. .\" .Pp .It Ic show Cm buffer Ar addr Show information about the buf structure .Vt struct buf present at .Ar addr . See the .Pa sys/buf.h header file for more details on the exact meaning of the structure fields. .\" .Pp .It Ic show Cm cbstat Show brief information about the TTY subsystem. .\" .Pp .It Ic show Cm cdev Without argument, show the list of all created cdev's, consisting of devfs node name and struct cdev address. When address of cdev is supplied, show some internal devfs state of the cdev. .\" .Pp .It Ic show Cm conifhk Lists hooks currently waiting for completion in run_interrupt_driven_config_hooks(). .\" .Pp .It Ic show Cm cpusets Print numbered root and assigned CPU affinity sets. See .Xr cpuset 2 for more details. .\" .Pp .It Ic show Cm cyrixreg Show registers specific to the Cyrix processor. .\" .Pp .It Ic show Cm devmap Prints the contents of the static device mapping table. Currently only available on the ARM architecture. .\" .Pp .It Ic show Cm domain Ar addr Print protocol domain structure .Vt struct domain at address .Ar addr . See the .Pa sys/domain.h header file for more details on the exact meaning of the structure fields. .\" .Pp .It Ic show Cm ffs Op Ar addr Show brief information about ffs mount at the address .Ar addr , if argument is given. Otherwise, provides the summary about each ffs mount. .\" .Pp .It Ic show Cm file Ar addr Show information about the file structure .Vt struct file present at address .Ar addr . .\" .Pp .It Ic show Cm files Show information about every file structure in the system. .\" .Pp .It Ic show Cm freepages Show the number of physical pages in each of the free lists. .\" .Pp .It Ic show Cm geom Op Ar addr If the .Ar addr argument is not given, displays the entire GEOM topology. If .Ar addr is given, displays details about the given GEOM object (class, geom, provider or consumer). .\" .Pp .It Ic show Cm idt Show IDT layout. The first column specifies the IDT vector. The second one is the name of the interrupt/trap handler. Those functions are machine dependent. .\" .Pp .It Ic show Cm inodedeps Op Ar addr Show brief information about each inodedep structure. If .Ar addr is given, only inodedeps belonging to the fs located at the supplied address are shown. .\" .Pp .It Ic show Cm inpcb Ar addr Show information on IP Control Block .Vt struct in_pcb present at .Ar addr . .\" .Pp .It Ic show Cm intr Dump information about interrupt handlers. .\" .Pp .It Ic show Cm intrcnt Dump the interrupt statistics. .\" .Pp .It Ic show Cm irqs Show interrupt lines and their respective kernel threads. .\" .Pp .It Ic show Cm jails Show the list of .Xr jail 8 instances. In addition to what .Xr jls 8 shows, also list kernel internal details. .\" .Pp .It Ic show Cm lapic Show information from the local APIC registers for this CPU. .\" .Pp .It Ic show Cm lock Ar addr Show lock structure. The output format is as follows: .Bl -tag -width "flags" .It Ic class: Class of the lock. Possible types include .Xr mutex 9 , .Xr rmlock 9 , .Xr rwlock 9 , .Xr sx 9 . .It Ic name: Name of the lock. .It Ic flags: Flags passed to the lock initialization function. For exact possibilities see manual pages of possible lock types. .It Ic state: Current state of a lock. As well as .Ic flags it's lock-specific. .It Ic owner: Lock owner. .El .\" .Pp .It Ic show Cm lockchain Ar addr Show all threads a particular thread at address .Ar addr is waiting on based on non-sleepable and non-spin locks. .\" .Pp .It Ic show Cm lockedbufs Show the same information as "show buf", but for every locked .Vt struct buf object. .\" .Pp .It Ic show Cm lockedvnods List all locked vnodes in the system. .\" .Pp .It Ic show Cm locks Prints all locks that are currently acquired. This command is only available if .Xr witness 4 is included in the kernel. .\" .Pp .It Ic show Cm locktree .\" .Pp .It Ic show Cm malloc Prints .Xr malloc 9 memory allocator statistics. The output format is as follows: .Pp .Bl -tag -compact -offset indent -width "Requests" .It Ic Type Specifies a type of memory. It is the same as a description string used while defining the given memory type with .Xr MALLOC_DECLARE 9 . .It Ic InUse Number of memory allocations of the given type, for which .Xr free 9 has not been called yet. .It Ic MemUse Total memory consumed by the given allocation type. .It Ic Requests Number of memory allocation requests for the given memory type. .El .Pp The same information can be gathered in userspace with .Dq Nm vmstat Fl m . .\" .Pp .It Ic show Cm map Ns Oo Li / Ns Cm f Oc Ar addr Prints the VM map at .Ar addr . If the .Cm f modifier is specified the complete map is printed. .\" .Pp .It Ic show Cm msgbuf Print the system's message buffer. It is the same output as in the .Dq Nm dmesg case. It is useful if you got a kernel panic, attached a serial cable to the machine and want to get the boot messages from before the system hang. .\" .It Ic show Cm mount Displays short info about all currently mounted file systems. .Pp .It Ic show Cm mount Ar addr Displays details about the given mount point. .\" .Pp .It Ic show Cm object Ns Oo Li / Ns Cm f Oc Ar addr Prints the VM object at .Ar addr . If the .Cm f option is specified the complete object is printed. .\" .Pp .It Ic show Cm page Show statistics on VM pages. .\" .Pp .It Ic show Cm pageq Show statistics on VM page queues. .\" .Pp .It Ic show Cm pciregs Print PCI bus registers. The same information can be gathered in userspace by running .Dq Nm pciconf Fl lv . .\" .Pp .It Ic show Cm pcpu Print current processor state. The output format is as follows: .Pp .Bl -tag -compact -offset indent -width "spin locks held:" .It Ic cpuid Processor identifier. .It Ic curthread Thread pointer, process identifier and the name of the process. .It Ic curpcb Control block pointer. .It Ic fpcurthread FPU thread pointer. .It Ic idlethread Idle thread pointer. .It Ic APIC ID CPU identifier coming from APIC. .It Ic currentldt LDT pointer. .It Ic spin locks held Names of spin locks held. .El .\" .Pp .It Ic show Cm pgrpdump Dump process groups present within the system. .\" .Pp .It Ic show Cm proc Op Ar addr If no .Op Ar addr is specified, print information about the current process. Otherwise, show information about the process at address .Ar addr . .\" .Pp .It Ic show Cm procvm Show process virtual memory layout. .\" .Pp .It Ic show Cm protosw Ar addr Print protocol switch structure .Vt struct protosw at address .Ar addr . .\" .Pp .It Ic show Cm registers Ns Op Li / Ns Cm u Display the register set. If the .Cm u modifier is specified, it displays user registers instead of kernel registers or the currently saved one. .Pp .Sy Warning : The support of the .Cm u modifier depends on the machine. If not supported, incorrect information will be displayed. .\" .Pp .It Ic show Cm rman Ar addr Show resource manager object .Vt struct rman at address .Ar addr . Addresses of particular pointers can be gathered with "show allrman" command. .\" .Pp .It Ic show Cm rtc Show real time clock value. Useful for long debugging sessions. .\" .Pp .It Ic show Cm sleepchain Show all the threads a particular thread is waiting on based on sleepable locks. .\" .Pp .It Ic show Cm sleepq .It Ic show Cm sleepqueue Both commands provide the same functionality. They show sleepqueue .Vt struct sleepqueue structure. Sleepqueues are used within the .Fx kernel to implement sleepable synchronization primitives (thread holding a lock might sleep or be context switched), which at the time of writing are: .Xr condvar 9 , .Xr sx 9 and standard .Xr msleep 9 interface. .\" .Pp .It Ic show Cm sockbuf Ar addr .It Ic show Cm socket Ar addr Those commands print .Vt struct sockbuf and .Vt struct socket objects placed at .Ar addr . Output consists of all values present in structures mentioned. For exact interpretation and more details, visit .Pa sys/socket.h header file. .\" .Pp .It Ic show Cm sysregs Show system registers (e.g., .Li cr0-4 on i386.) Not present on some platforms. .\" .Pp .It Ic show Cm tcpcb Ar addr Print TCP control block .Vt struct tcpcb lying at address .Ar addr . For exact interpretation of output, visit .Pa netinet/tcp.h header file. .\" .Pp .It Ic show Cm thread Op Ar addr If no .Ar addr is specified, show detailed information about current thread. Otherwise, information about thread at .Ar addr is printed. .\" .Pp .It Ic show Cm threads Show all threads within the system. Output format is as follows: .Pp .Bl -tag -compact -offset indent -width "Second column" .It Ic First column Thread identifier (TID) .It Ic Second column Thread structure address .It Ic Third column Backtrace. .El .\" .Pp .It Ic show Cm tty Ar addr Display the contents of a TTY structure in a readable form. .\" .Pp .It Ic show Cm turnstile Ar addr Show turnstile .Vt struct turnstile structure at address .Ar addr . Turnstiles are structures used within the .Fx kernel to implement synchronization primitives which, while holding a specific type of lock, cannot sleep or context switch to another thread. Currently, those are: .Xr mutex 9 , .Xr rwlock 9 , .Xr rmlock 9 . .\" .Pp .It Ic show Cm uma Show UMA allocator statistics. Output consists five columns: .Pp .Bl -tag -compact -offset indent -width "Requests" .It Cm "Zone" Name of the UMA zone. The same string that was passed to .Xr uma_zcreate 9 as a first argument. .It Cm "Size" Size of a given memory object (slab). .It Cm "Used" Number of slabs being currently used. .It Cm "Free" Number of free slabs within the UMA zone. .It Cm "Requests" Number of allocations requests to the given zone. .El .Pp The very same information might be gathered in the userspace with the help of .Dq Nm vmstat Fl z . .\" .Pp .It Ic show Cm unpcb Ar addr Shows UNIX domain socket private control block .Vt struct unpcb present at the address .Ar addr . .\" .Pp .It Ic show Cm vmochk Prints, whether the internal VM objects are in a map somewhere and none have zero ref counts. .\" .Pp .It Ic show Cm vmopag This is supposed to show physical addresses consumed by a VM object. Currently, it is not possible to use this command when .Xr witness 4 is compiled in the kernel. .\" .Pp .It Ic show Cm vnode Op Ar addr Prints vnode .Vt struct vnode structure lying at .Op Ar addr . For the exact interpretation of the output, look at the .Pa sys/vnode.h header file. .\" .Pp .It Ic show Cm vnodebufs Ar addr Shows clean/dirty buffer lists of the vnode located at .Ar addr . .\" .Pp .It Ic show Cm watches Displays all watchpoints. Shows watchpoints set with "watch" command. .\" .Pp .It Ic show Cm witness Shows information about lock acquisition coming from the .Xr witness 4 subsystem. .\" .Pp .It Ic gdb Toggles between remote GDB and DDB mode. In remote GDB mode, another machine is required that runs .Xr gdb 1 using the remote debug feature, with a connection to the serial console port on the target machine. Currently only available on the i386 architecture. .Pp .It Ic halt Halt the system. .Pp .It Ic kill Ar sig pid Send signal .Ar sig to process .Ar pid . The signal is acted on upon returning from the debugger. This command can be used to kill a process causing resource contention in the case of a hung system. See .Xr signal 3 for a list of signals. Note that the arguments are reversed relative to .Xr kill 2 . .Pp .It Ic reboot Op Ar seconds .It Ic reset Op Ar seconds Hard reset the system. If the optional argument .Ar seconds is given, the debugger will wait for this long, at most a week, before rebooting. .Pp .It Ic help Print a short summary of the available commands and command abbreviations. .Pp .It Ic capture on .It Ic capture off .It Ic capture reset .It Ic capture status .Nm supports a basic output capture facility, which can be used to retrieve the results of debugging commands from userspace using -.Xr sysctl 2 . +.Xr sysctl 3 . .Ic capture on enables output capture; .Ic capture off disables capture. .Ic capture reset will clear the capture buffer and disable capture. .Ic capture status will report current buffer use, buffer size, and disposition of output capture. .Pp Userspace processes may inspect and manage .Nm capture state using .Xr sysctl 8 : .Pp .Dv debug.ddb.capture.bufsize may be used to query or set the current capture buffer size. .Pp .Dv debug.ddb.capture.maxbufsize may be used to query the compile-time limit on the capture buffer size. .Pp .Dv debug.ddb.capture.bytes may be used to query the number of bytes of output currently in the capture buffer. .Pp .Dv debug.ddb.capture.data returns the contents of the buffer as a string to an appropriately privileged process. .Pp This facility is particularly useful in concert with the scripting and .Xr textdump 4 facilities, allowing scripted debugging output to be captured and committed to disk as part of a textdump for later analysis. The contents of the capture buffer may also be inspected in a kernel core dump using .Xr kgdb 1 . .Pp .It Ic run .It Ic script .It Ic scripts .It Ic unscript Run, define, list, and delete scripts. See the .Sx SCRIPTING section for more information on the scripting facility. .Pp .It Ic textdump dump .It Ic textdump set .It Ic textdump status .It Ic textdump unset Use the .Ic textdump dump command to immediately perform a textdump. More information may be found in .Xr textdump 4 . The .Ic textdump set command may be used to force the next kernel core dump to be a textdump rather than a traditional memory dump or minidump. .Ic textdump status reports whether a textdump has been scheduled. .Ic textdump unset cancels a request to perform a textdump as the next kernel core dump. .El .Sh VARIABLES The debugger accesses registers and variables as .Li $ Ns Ar name . Register names are as in the .Dq Ic show Cm registers command. Some variables are suffixed with numbers, and may have some modifier following a colon immediately after the variable name. For example, register variables can have a .Cm u modifier to indicate user register (e.g., .Dq Li $eax:u ) . .Pp Built-in variables currently supported are: .Pp .Bl -tag -width ".Va tabstops" -compact .It Va radix Input and output radix. .It Va maxoff Addresses are printed as .Dq Ar symbol Ns Li + Ns Ar offset unless .Ar offset is greater than .Va maxoff . .It Va maxwidth The width of the displayed line. .It Va lines The number of lines. It is used by the built-in pager. .It Va tabstops Tab stop width. .It Va work Ns Ar xx Work variable; .Ar xx can take values from 0 to 31. .El .Sh EXPRESSIONS Most expression operators in C are supported except .Ql ~ , .Ql ^ , and unary .Ql & . Special rules in .Nm are: .Bl -tag -width ".No Identifiers" .It Identifiers The name of a symbol is translated to the value of the symbol, which is the address of the corresponding object. .Ql \&. and .Ql \&: can be used in the identifier. If supported by an object format dependent routine, .Sm off .Oo Ar filename : Oc Ar func : lineno , .Sm on .Oo Ar filename : Oc Ns Ar variable , and .Oo Ar filename : Oc Ns Ar lineno can be accepted as a symbol. .It Numbers Radix is determined by the first two letters: .Ql 0x : hex, .Ql 0o : octal, .Ql 0t : decimal; otherwise, follow current radix. .It Li \&. .Va dot .It Li + .Va next .It Li .. address of the start of the last line examined. Unlike .Va dot or .Va next , this is only changed by .Ic examine or .Ic write command. .It Li ' last address explicitly specified. .It Li $ Ns Ar variable Translated to the value of the specified variable. It may be followed by a .Ql \&: and modifiers as described above. .It Ar a Ns Li # Ns Ar b A binary operator which rounds up the left hand side to the next multiple of right hand side. .It Li * Ns Ar expr Indirection. It may be followed by a .Ql \&: and modifiers as described above. .El .Sh SCRIPTING .Nm supports a basic scripting facility to allow automating tasks or responses to specific events. Each script consists of a list of DDB commands to be executed sequentially, and is assigned a unique name. Certain script names have special meaning, and will be automatically run on various .Nm events if scripts by those names have been defined. .Pp The .Ic script command may be used to define a script by name. Scripts consist of a series of .Nm commands separated with the .Ql \&; character. For example: .Bd -literal -offset indent script kdb.enter.panic=bt; show pcpu script lockinfo=show alllocks; show lockedvnods .Ed .Pp The .Ic scripts command lists currently defined scripts. .Pp The .Ic run command execute a script by name. For example: .Bd -literal -offset indent run lockinfo .Ed .Pp The .Ic unscript command may be used to delete a script by name. For example: .Bd -literal -offset indent unscript kdb.enter.panic .Ed .Pp These functions may also be performed from userspace using the .Xr ddb 8 command. .Pp Certain scripts are run automatically, if defined, for specific .Nm events. The follow scripts are run when various events occur: .Bl -tag -width kdb.enter.powerfail .It Dv kdb.enter.acpi The kernel debugger was entered as a result of an .Xr acpi 4 event. .It Dv kdb.enter.bootflags The kernel debugger was entered at boot as a result of the debugger boot flag being set. .It Dv kdb.enter.break The kernel debugger was entered as a result of a serial or console break. .It Dv kdb.enter.cam The kernel debugger was entered as a result of a .Xr CAM 4 event. .It Dv kdb.enter.mac The kernel debugger was entered as a result of an assertion failure in the .Xr mac_test 4 module of the TrustedBSD MAC Framework. .It Dv kdb.enter.ndis The kernel debugger was entered as a result of an .Xr ndis 4 breakpoint event. .It Dv kdb.enter.netgraph The kernel debugger was entered as a result of a .Xr netgraph 4 event. .It Dv kdb.enter.panic .Xr panic 9 was called. .It Dv kdb.enter.powerfail The kernel debugger was entered as a result of a powerfail NMI on the sparc64 platform. .It Dv kdb.enter.powerpc The kernel debugger was entered as a result of an unimplemented interrupt type on the powerpc platform. .It Dv kdb.enter.sysctl The kernel debugger was entered as a result of the .Dv debug.kdb.enter sysctl being set. .It Dv kdb.enter.trapsig The kernel debugger was entered as a result of a trapsig event on the sparc64 platform. .It Dv kdb.enter.unionfs The kernel debugger was entered as a result of an assertion failure in the union file system. .It Dv kdb.enter.unknown The kernel debugger was entered, but no reason has been set. .It Dv kdb.enter.vfslock The kernel debugger was entered as a result of a VFS lock violation. .It Dv kdb.enter.watchdog The kernel debugger was entered as a result of a watchdog firing. .It Dv kdb.enter.witness The kernel debugger was entered as a result of a .Xr witness 4 violation. .El .Pp In the event that none of these scripts is found, .Nm will attempt to execute a default script: .Bl -tag -width kdb.enter.powerfail .It Dv kdb.enter.default The kernel debugger was entered, but a script exactly matching the reason for entering was not defined. This can be used as a catch-all to handle cases not specifically of interest; for example, .Dv kdb.enter.witness might be defined to have special handling, and .Dv kdb.enter.default might be defined to simply panic and reboot. .El .Sh HINTS On machines with an ISA expansion bus, a simple NMI generation card can be constructed by connecting a push button between the A01 and B01 (CHCHK# and GND) card fingers. Momentarily shorting these two fingers together may cause the bridge chipset to generate an NMI, which causes the kernel to pass control to .Nm . Some bridge chipsets do not generate a NMI on CHCHK#, so your mileage may vary. The NMI allows one to break into the debugger on a wedged machine to diagnose problems. Other bus' bridge chipsets may be able to generate NMI using bus specific methods. There are many PCI and PCIe add-in cards which can generate NMI for debugging. Modern server systems typically use IPMI to generate signals to enter the debugger. The .Dv devel/ipmitool port can be used to send the .Cd chassis power diag command which delivers an NMI to the processor. Embedded systems often use JTAG for debugging, but rarely use it in combination with .Nm . .Pp For serial consoles, you can enter the debugger by sending a BREAK condition on the serial line if .Cd options BREAK_TO_DEBUGGER is specified in the kernel. Most terminal emulation programs can send a break sequence with a special key sequence or via a menu item. However, in some setups, sending the break can be difficult to arrange or happens spuriously, so if the kernel contains .Cd options ALT_BREAK_TO_DEBUGGER then the sequence of CR TILDE CTRL-B enters the debugger; CR TILDE CTRL-P causes a panic instead of entering the debugger; and CR TILDE CTRL-R causes an immediate reboot. In all the above sequences, CR is a Carriage Return and is usually sent by hitting the Enter or Return key. TILDE is the ASCII tilde character (~). CTRL-x is Control x created by hitting the control key and then x and then releasing both. .Pp The break to enter the debugger behavior may be enabled at run-time by setting the .Xr sysctl 8 .Dv debug.kdb.break_to_debugger to 1. The alternate sequence to enter the debugger behavior may be enabled at run-time by setting the .Xr sysctl 8 .Dv debug.kdb.alt_break_to_debugger to 1. The debugger may be entered by setting the .Xr sysctl 8 .Dv debug.kdb.enter to 1. .Sh FILES Header files mentioned in this manual page can be found below .Pa /usr/include directory. .Pp .Bl -dash -compact .It .Pa sys/buf.h .It .Pa sys/domain.h .It .Pa netinet/in_pcb.h .It .Pa sys/socket.h .It .Pa sys/vnode.h .El .Sh SEE ALSO .Xr gdb 1 , .Xr kgdb 1 , .Xr acpi 4 , .Xr CAM 4 , .Xr mac_test 4 , .Xr ndis 4 , .Xr netgraph 4 , .Xr textdump 4 , .Xr witness 4 , .Xr ddb 8 , .Xr sysctl 8 , .Xr panic 9 .Sh HISTORY The .Nm debugger was developed for Mach, and ported to .Bx 386 0.1 . This manual page translated from .Xr man 7 macros by .An Garrett Wollman . .Pp .An Robert N. M. Watson added support for .Nm output capture, .Xr textdump 4 and scripting in .Fx 7.1 . Index: head/share/man/man4/pcm.4 =================================================================== --- head/share/man/man4/pcm.4 (revision 297354) +++ head/share/man/man4/pcm.4 (revision 297355) @@ -1,796 +1,796 @@ .\" .\" Copyright (c) 2009-2011 Joel Dahl .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd March 22, 2012 .Dt SOUND 4 .Os .Sh NAME .Nm sound , .Nm pcm , .Nm snd .Nd .Fx PCM audio device infrastructure .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device sound" .Ed .Sh DESCRIPTION The .Nm driver is the main component of the .Fx sound system. It works in conjunction with a bridge device driver on supported devices and provides PCM audio record and playback once it attaches. Each bridge device driver supports a specific set of audio chipsets and needs to be enabled together with the .Nm driver. PCI and ISA PnP audio devices identify themselves so users are usually not required to add anything to .Pa /boot/device.hints . .Pp Some of the main features of the .Nm driver are: multichannel audio, per-application volume control, dynamic mixing through virtual sound channels, true full duplex operation, bit perfect audio, rate conversion and low latency modes. .Pp The .Nm driver is enabled by default, along with several bridge device drivers. Those not enabled by default can be loaded during runtime with .Xr kldload 8 or during boot via .Xr loader.conf 5 . The following bridge device drivers are available: .Pp .Bl -bullet -compact .It .Xr snd_ad1816 4 .It .Xr snd_ai2s 4 (enabled by default on powerpc) .It .Xr snd_als4000 4 .It .Xr snd_atiixp 4 .It .Xr snd_audiocs 4 (enabled by default on sparc64) .It .Xr snd_cmi 4 (enabled by default on amd64, i386) .It .Xr snd_cs4281 4 .It .Xr snd_csa 4 (enabled by default on amd64, i386) .It .Xr snd_davbus 4 (enabled by default on powerpc) .It .Xr snd_ds1 4 .It .Xr snd_emu10k1 4 .It .Xr snd_emu10kx 4 (enabled by default on amd64, i386) .It .Xr snd_envy24 4 .It .Xr snd_envy24ht 4 .It .Xr snd_es137x 4 (enabled by default on amd64, i386, sparc64) .It .Xr snd_ess 4 .It .Xr snd_fm801 4 .It .Xr snd_gusc 4 .It .Xr snd_hda 4 (enabled by default on amd64, i386) .It .Xr snd_hdspe 4 .It .Xr snd_ich 4 (enabled by default on amd64, i386) .It .Xr snd_maestro 4 .It .Xr snd_maestro3 4 .It .Xr snd_mss 4 .It .Xr snd_neomagic 4 .It snd_sb16 .It snd_sb8 .It .Xr snd_sbc 4 .It .Xr snd_solo 4 .It .Xr snd_spicds 4 .It .Xr snd_t4dwave 4 (enabled by default on sparc64) .It .Xr snd_uaudio 4 (enabled by default on amd64, i386, powerpc, sparc64) .It .Xr snd_via8233 4 (enabled by default on amd64, i386) .It .Xr snd_via82c686 4 .It .Xr snd_vibes 4 .El .Pp Refer to the manual page for each bridge device driver for driver specific settings and information. .Ss Legacy Hardware For old legacy .Tn ISA cards, the driver looks for .Tn MSS cards at addresses .Dv 0x530 and .Dv 0x604 . These values can be overridden in .Pa /boot/device.hints . Non-PnP sound cards require the following lines in .Xr device.hints 5 : .Bd -literal -offset indent hint.pcm.0.at="isa" hint.pcm.0.irq="5" hint.pcm.0.drq="1" hint.pcm.0.flags="0x0" .Ed .Pp Apart from the usual parameters, the flags field is used to specify the secondary .Tn DMA channel (generally used for capture in full duplex cards). Flags are set to 0 for cards not using a secondary .Tn DMA channel, or to 0x10 + C to specify channel C. .Ss Boot Variables In general, the module .Pa snd_foo corresponds to .Cd "device snd_foo" and can be loaded by the boot .Xr loader 8 via .Xr loader.conf 5 or from the command line using the .Xr kldload 8 utility. Options which can be specified in .Pa /boot/loader.conf include: .Bl -tag -width ".Va snd_driver_load" -offset indent .It Va snd_driver_load .Pq Dq Li NO If set to .Dq Li YES , this option loads all available drivers. .It Va snd_hda_load .Pq Dq Li NO If set to .Dq Li YES , only the Intel High Definition Audio bridge device driver and dependent modules will be loaded. .It Va snd_foo_load .Pq Dq Li NO If set to .Dq Li YES , load driver for card/chipset foo. .El .Pp To define default values for the different mixer channels, set the channel to the preferred value using hints, e.g.: .Va hint.pcm.0.line Ns = Ns Qq Li 0 . This will mute the input channel per default. .Ss Multichannel Audio Multichannel audio, popularly referred to as .Dq surround sound is supported and enabled by default. The FreeBSD multichannel matrix processor supports up to 18 interleaved channels, but the limit is currently set to 8 channels (as commonly used for 7.1 surround sound). The internal matrix mapping can handle reduction, expansion or re-routing of channels. This provides a base interface for related multichannel .Fn ioctl support. Multichannel audio works both with and without .Tn VCHANs . .Pp Most bridge device drivers are still missing multichannel matrixing support, but in most cases this should be trivial to implement. Use the .Va dev.pcm.%d.[play|rec].vchanformat -.Xr sysctl(8) +.Xr sysctl 8 to adjust the number of channels used. The current multichannel interleaved structure and arrangement was implemented by inspecting various popular UNIX applications. There were no single standard, so much care has been taken to try to satisfy each possible scenario, despite the fact that each application has its own conflicting standard. .Ss EQ The Parametric Software Equalizer (EQ) enables the use of .Dq tone controls (bass and treble). Commonly used for ear-candy or frequency compensation due to the vast difference in hardware quality. EQ is disabled by default, but can be enabled with the .Va hint.pcm.%d.eq tunable. .Ss VCHANs Each device can optionally support more playback and recording channels than physical hardware provides by using .Dq virtual channels or .Tn VCHANs . .Tn VCHAN options can be configured via the .Xr sysctl 8 interface but can only be manipulated while the device is inactive. .Ss VPC FreeBSD supports independent and individual volume controls for each active application, without touching the master .Nm volume. This is sometimes referred to as Volume Per Channel (VPC). The .Tn VPC feature is enabled by default. .Ss Loader Tunables The following loader tunables are used to set driver configuration at the .Xr loader 8 prompt before booting the kernel, or they can be stored in .Pa /boot/loader.conf in order to automatically set them before booting the kernel. It is also possible to use .Xr kenv 1 to change these tunables before loading the .Nm driver. The following tunables can not be changed during runtime using .Xr sysctl 8 . .Bl -tag -width indent .It Va hint.pcm.%d.eq Set to 1 or 0 to explicitly enable (1) or disable (0) the equalizer. Requires a driver reload if changed. Enabling this will make bass and treble controls appear in mixer applications. This tunable is undefined by default. Equalizing is disabled by default. .It Va hint.pcm.%d.vpc Set to 1 or 0 to explicitly enable (1) or disable (0) the .Tn VPC feature. This tunable is undefined by default. .Tn VPC is however enabled by default. .El .Ss Runtime Configuration There are a number of .Xr sysctl 8 variables available which can be modified during runtime. These values can also be stored in .Pa /etc/sysctl.conf in order to automatically set them during the boot process. .Va hw.snd.* are global settings and .Va dev.pcm.* are device specific. .Bl -tag -width indent .It Va hw.snd.compat_linux_mmap Linux .Xr mmap 2 compatibility. The following values are supported (default is 0): .Bl -tag -width 2n .It -1 Force disabling/denying PROT_EXEC .Xr mmap 2 requests. .It 0 Auto detect proc/ABI type, allow .Xr mmap 2 for Linux applications, and deny for everything else. .It 1 Always allow PROT_EXEC page mappings. .El .It Va hw.snd.default_auto Automatically assign the default sound unit. The following values are supported (default is 1): .Bl -tag -width 2n .It 0 Do not assign the default sound unit automatically. .It 1 Use the best available sound device based on playing and recording capabilities of the device. .It 2 Use the most recently attached device. .El .It Va hw.snd.default_unit Default sound card for systems with multiple sound cards. When using .Xr devfs 5 , the default device for .Pa /dev/dsp . Equivalent to a symlink from .Pa /dev/dsp to .Pa /dev/dsp Ns Va ${hw.snd.default_unit} . .It Va hw.snd.feeder_eq_exact_rate Only certain rates are allowed for precise processing. The default behavior is however to allow sloppy processing for all rates, even the unsupported ones. Enable to toggle this requirement and only allow processing for supported rates. .It Va hw.snd.feeder_rate_max Maximum allowable sample rate. .It Va hw.snd.feeder_rate_min Minimum allowable sample rate. .It Va hw.snd.feeder_rate_polyphase_max Adjust to set the maximum number of allowed polyphase entries during the process of building resampling filters. Disabling polyphase resampling has the benefit of reducing memory usage, at the expense of slower and lower quality conversion. Only applicable when the SINC interpolator is used. Default value is 183040. Set to 0 to disable polyphase resampling. .It Va hw.snd.feeder_rate_quality Sample rate converter quality. Default value is 1, linear interpolation. Available options include: .Bl -tag -width 2n .It 0 Zero Order Hold, ZOH. Very fast, but with poor quality. .It 1 Linear interpolation. Fast, quality is subject to personal preference. Technically the quality is poor however, due to the lack of anti-aliasing filtering. .It 2 Bandlimited SINC interpolator. Implements polyphase banking to boost the conversion speed, at the cost of memory usage, with multiple high quality polynomial interpolators to improve the conversion accuracy. 100% fixed point, 64bit accumulator with 32bit coefficients and high precision sample buffering. Quality values are 100dB stopband, 8 taps and 85% bandwidth. .It 3 Continuation of the bandlimited SINC interpolator, with 100dB stopband, 36 taps and 90% bandwidth as quality values. .It 4 Continuation of the bandlimited SINC interprolator, with 100dB stopband, 164 taps and 97% bandwidth as quality values. .El .It Va hw.snd.feeder_rate_round Sample rate rounding threshold, to avoid large prime division at the cost of accuracy. All requested sample rates will be rounded to the nearest threshold value. Possible values range between 0 (disabled) and 500. Default is 25. .It Va hw.snd.latency Configure the buffering latency. Only affects applications that do not explicitly request blocksize / fragments. This tunable provides finer granularity than the .Va hw.snd.latency_profile tunable. Possible values range between 0 (lowest latency) and 10 (highest latency). .It Va hw.snd.latency_profile Define sets of buffering latency conversion tables for the .Va hw.snd.latency tunable. A value of 0 will use a low and aggressive latency profile which can result in possible underruns if the application cannot keep up with a rapid irq rate, especially during high workload. The default value is 1, which is considered a moderate/safe latency profile. .It Va hw.snd.maxautovchans Global .Tn VCHAN setting that only affects devices with at least one playback or recording channel available. The sound system will dynamically create up to this many .Tn VCHANs . Set to .Dq 0 if no .Tn VCHANs are desired. Maximum value is 256. .It Va hw.snd.report_soft_formats Controls the internal format conversion if it is available transparently to the application software. When disabled or not available, the application will only be able to select formats the device natively supports. .It Va hw.snd.report_soft_matrix Enable seamless channel matrixing even if the hardware does not support it. Makes it possible to play multichannel streams even with a simple stereo sound card. .It Va hw.snd.verbose Level of verbosity for the .Pa /dev/sndstat device. Higher values include more output and the highest level, four, should be used when reporting problems. Other options include: .Bl -tag -width 2n .It 0 Installed devices and their allocated bus resources. .It 1 The number of playback, record, virtual channels, and flags per device. .It 2 Channel information per device including the channel's current format, speed, and pseudo device statistics such as buffer overruns and buffer underruns. .It 3 File names and versions of the currently loaded sound modules. .It 4 Various messages intended for debugging. .El .It Va hw.snd.vpc_0db Default value for .Nm volume. Increase to give more room for attenuation control. Decrease for more amplification, with the possible cost of sound clipping. .It Va hw.snd.vpc_autoreset When a channel is closed the channel volume will be reset to 0db. This means that any changes to the volume will be lost. Enabling this will preserve the volume, at the cost of possible confusion when applications tries to re-open the same device. .It Va hw.snd.vpc_mixer_bypass The recommended way to use the .Tn VPC feature is to teach applications to use the correct .Fn ioctl : .Dv SNDCTL_DSP_GETPLAYVOL, SNDCTL_DSP_SETPLAYVOL, .Dv SNDCTL_DSP_SETRECVOL, SNDCTL_DSP_SETRECVOL. This is however not always possible. Enable this to allow applications to use their own existing mixer logic to control their own channel volume. .It Va hw.snd.vpc_reset Enable to restore all channel volumes back to the default value of 0db. .It Va dev.pcm.%d.bitperfect Enable or disable bitperfect mode. When enabled, channels will skip all dsp processing, such as channel matrixing, rate converting and equalizing. The pure .Nm stream will be fed directly to the hardware. If .Tn VCHANs are enabled, the bitperfect mode will use the .Tn VCHAN format/rate as the definitive format/rate target. The recommended way to use bitperfect mode is to disable .Tn VCHANs and enable this sysctl. Default is disabled. .It Va dev.pcm.%d.[play|rec].vchans The current number of .Tn VCHANs allocated per device. This can be set to preallocate a certain number of .Tn VCHANs . Setting this value to .Dq 0 will disable .Tn VCHANs for this device. .It Va dev.pcm.%d.[play|rec].vchanformat Format for .Tn VCHAN mixing. All playback paths will be converted to this format before the mixing process begins. By default only 2 channels are enabled. Available options include: .Bl -tag -width 2n .It s16le:1.0 Mono. .It s16le:2.0 Stereo, 2 channels (left, right). .It s16le:2.1 3 channels (left, right, LFE). .It s16le:3.0 3 channels (left, right, rear center). .It s16le:4.0 Quadraphonic, 4 channels (front/rear left and right). .It s16le:4.1 5 channels (4.0 + LFE). .It s16le:5.0 5 channels (4.0 + center). .It s16le:5.1 6 channels (4.0 + center + LFE). .It s16le:6.0 6 channels (4.0 + front/rear center). .It s16le:6.1 7 channels (6.0 + LFE). .It s16le:7.1 8 channels (4.0 + center + LFE + left and right side). .El .It Va dev.pcm.%d.[play|rec].vchanmode .Tn VCHAN format/rate selection. Available options include: .Bl -tag -width 2n .It fixed Channel mixing is done using fixed format/rate. Advanced operations such as digital passthrough will not work. Can be considered as a .Dq legacy mode. This is the default mode for hardware channels which lack support for digital formats. .It passthrough Channel mixing is done using fixed format/rate, but advanced operations such as digital passthrough also work. All channels will produce sound as usual until a digital format playback is requested. When this happens all other channels will be muted and the latest incoming digital format will be allowed to pass through undisturbed. Multiple concurrent digital streams are supported, but the latest stream will take precedence and mute all other streams. .It adaptive Works like the .Dq passthrough mode, but is a bit smarter, especially for multiple .Nm channels with different format/rate. When a new channel is about to start, the entire list of virtual channels will be scanned, and the channel with the best format/rate (usually the highest/biggest) will be selected. This ensures that mixing quality depends on the best channel. The downside is that the hardware DMA mode needs to be restarted, which may cause annoying pops or clicks. .El .It Va dev.pcm.%d.[play|rec].vchanrate Sample rate speed for .Tn VCHAN mixing. All playback paths will be converted to this sample rate before the mixing process begins. .It Va dev.pcm.%d.polling Experimental polling mode support where the driver operates by querying the device state on each tick using a .Xr callout 9 mechanism. Disabled by default and currently only available for a few device drivers. .El .Ss Recording Channels On devices that have more than one recording source (ie: mic and line), there is a corresponding .Pa /dev/dsp%d.r%d device. The .Xr mixer 8 utility can be used to start and stop recording from an specific device. .Ss Statistics Channel statistics are only kept while the device is open. So with situations involving overruns and underruns, consider the output while the errant application is open and running. .Ss IOCTL Support The driver supports most of the .Tn OSS .Fn ioctl functions, and most applications work unmodified. A few differences exist, while memory mapped playback is supported natively and in .Tn Linux emulation, memory mapped recording is not due to .Tn VM system design. As a consequence, some applications may need to be recompiled with a slightly modified audio module. See .In sys/soundcard.h for a complete list of the supported .Fn ioctl functions. .Sh FILES The .Nm drivers may create the following device nodes: .Pp .Bl -tag -width ".Pa /dev/audio%d.%d" -compact .It Pa /dev/audio%d.%d Sparc-compatible audio device. .It Pa /dev/dsp%d.%d Digitized voice device. .It Pa /dev/dspW%d.%d Like .Pa /dev/dsp , but 16 bits per sample. .It Pa /dev/dsp%d.p%d Playback channel. .It Pa /dev/dsp%d.r%d Record channel. .It Pa /dev/dsp%d.vp%d Virtual playback channel. .It Pa /dev/dsp%d.vr%d Virtual recording channel. .It Pa /dev/sndstat Current .Nm status, including all channels and drivers. .El .Pp The first number in the device node represents the unit number of the .Nm device. All .Nm devices are listed in .Pa /dev/sndstat . Additional messages are sometimes recorded when the device is probed and attached, these messages can be viewed with the .Xr dmesg 8 utility. .Pp The above device nodes are only created on demand through the dynamic .Xr devfs 5 clone handler. Users are strongly discouraged to access them directly. For specific sound card access, please instead use .Pa /dev/dsp or .Pa /dev/dsp%d . .Sh EXAMPLES Use the sound metadriver to load all .Nm bridge device drivers at once (for example if it is unclear which the correct driver to use is): .Pp .Dl kldload snd_driver .Pp Load a specific bridge device driver, in this case the Intel High Definition Audio driver: .Pp .Dl kldload snd_hda .Pp Check the status of all detected .Nm devices: .Pp .Dl cat /dev/sndstat .Pp Change the default sound device, in this case to the second device. This is handy if there are multiple .Nm devices available: .Pp .Dl sysctl hw.snd.default_unit=1 .Sh DIAGNOSTICS .Bl -diag .It pcm%d:play:%d:dsp%d.p%d: play interrupt timeout, channel dead The hardware does not generate interrupts to serve incoming (play) or outgoing (record) data. .It unsupported subdevice XX A device node is not created properly. .El .Sh SEE ALSO .Xr snd_ad1816 4 , .Xr snd_ai2s 4 , .Xr snd_als4000 4 , .Xr snd_atiixp 4 , .Xr snd_audiocs 4 , .Xr snd_cmi 4 , .Xr snd_cs4281 4 , .Xr snd_csa 4 , .Xr snd_davbus 4 , .Xr snd_ds1 4 , .Xr snd_emu10k1 4 , .Xr snd_emu10kx 4 , .Xr snd_envy24 4 , .Xr snd_envy24ht 4 , .Xr snd_es137x 4 , .Xr snd_ess 4 , .Xr snd_fm801 4 , .Xr snd_gusc 4 , .Xr snd_hda 4 , .Xr snd_hdspe 4 , .Xr snd_ich 4 , .Xr snd_maestro 4 , .Xr snd_maestro3 4 , .Xr snd_mss 4 , .Xr snd_neomagic 4 , .Xr snd_sbc 4 , .Xr snd_solo 4 , .Xr snd_spicds 4 , .Xr snd_t4dwave 4 , .Xr snd_uaudio 4 , .Xr snd_via8233 4 , .Xr snd_via82c686 4 , .Xr snd_vibes 4 , .Xr devfs 5 , .Xr device.hints 5 , .Xr loader.conf 5 , .Xr dmesg 8 , .Xr kldload 8 , .Xr mixer 8 , .Xr sysctl 8 .Rs .%T "Cookbook formulae for audio EQ biquad filter coefficients, by Robert Bristow-Johnson" .%U "http://www.musicdsp.org/files/Audio-EQ-Cookbook.txt" .Re .Rs .%T "Julius O'Smith's Digital Audio Resampling" .%U "http://ccrma.stanford.edu/~jos/resample/" .Re .Rs .%T "Polynomial Interpolators for High-Quality Resampling of Oversampled Audio, by Olli Niemitalo" .%U "http://www.student.oulu.fi/~oniemita/dsp/deip.pdf" .Re .Rs .%T "The OSS API" .%U "http://www.opensound.com/pguide/oss.pdf" .Re .Sh HISTORY The .Nm device driver first appeared in .Fx 2.2.6 as .Nm pcm , written by .An Luigi Rizzo . It was later rewritten in .Fx 4.0 by .An Cameron Grant . The API evolved from the VOXWARE standard which later became OSS standard. .Sh AUTHORS .An -nosplit .An Luigi Rizzo Aq Mt luigi@iet.unipi.it initially wrote the .Nm pcm device driver and this manual page. .An Cameron Grant Aq Mt gandalf@vilnya.demon.co.uk later revised the device driver for .Fx 4.0 . .An Seigo Tanimura Aq Mt tanimura@r.dl.itc.u-tokyo.ac.jp revised this manual page. It was then rewritten for .Fx 5.2 . .Sh BUGS Some features of your sound card (e.g., global volume control) might not be supported on all devices. Index: head/share/man/man4/sppp.4 =================================================================== --- head/share/man/man4/sppp.4 (revision 297354) +++ head/share/man/man4/sppp.4 (revision 297355) @@ -1,239 +1,238 @@ .\" .\" Copyright (c) 1997, 2001 Joerg Wunsch .\" .\" 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 May 25, 2008 .Dt SPPP 4 .Os .Sh NAME .Nm sppp .Nd point to point protocol network layer for synchronous lines .Sh SYNOPSIS .Cd "device sppp" .Sh DESCRIPTION The .Nm network layer implements the state machine and the Link Control Protocol (LCP) of the .Em point to point protocol (PPP) as described in RFC 1661. Note that this layer does not provide network interfaces of its own, it is rather intended to be layered on top of drivers providing a synchronous point-to-point connection that wish to run a PPP stack over it. The corresponding network interfaces have to be provided by these hardware drivers. .Pp The .Nm layer provides three basic modes of operation. The default mode, with no special flags to be set, is to create the PPP connection (administrative .Em Open event to the LCP layer) as soon as the interface is taken up with the .Xr ifconfig 8 command. Taking the interface down again will terminate the LCP layer and thus all other layers on top. The link will also terminate itself as soon as no Network Control Protocol (NCP) is open anymore, indicating that the lower layers are no longer needed. .Pp Setting the link-level flag .Em link0 with .Xr ifconfig 8 will cause the respective network interface to go into .Em passive mode. This means, the administrative .Em Open event to the LCP layer will be delayed until after the lower layers signals an .Em Up event (rise of .Dq carrier ) . This can be used by lower layers to support a dialin connection where the physical layer is not available immediately at startup, but only after some external event arrives. Receipt of a .Em Down event from the lower layer will not take the interface completely down in this case. .Pp Finally, setting the flag .Em link1 will cause the interface to operate in .Em dial-on-demand mode. This is also only useful if the lower layer supports the notion of a carrier. Upon configuring the respective interface, it will delay the administrative .Em Open event to the LCP layer until either an outbound network packet arrives, or until the lower layer signals an .Em Up event, indicating an inbound connection. As with passive mode, receipt of a .Em Down event (loss of carrier) will not automatically take the interface down, thus it remains available for further connections. .Pp The .Nm layer supports the .Em debug interface flag that can be set with .Xr ifconfig 8 . If this flag is set, the various control protocol packets being exchanged as well as the option negotiation between both ends of the link will be logged at level .Dv LOG_DEBUG . This can be helpful to examine configuration problems during the first attempts to set up a new configuration. Without this flag being set, only the major phase transitions will be logged at level .Dv LOG_INFO . .Pp It is possible to leave the local interface IP address open for negotiation by setting it to 0.0.0.0. This requires that the remote peer can correctly supply a value for it based on the identity of the caller, or on the remote address supplied by this side. Due to the way the IPCP option negotiation works, this address is being supplied late during the negotiation, which might cause the remote peer to make wrong assumptions. .Pp In a similar spirit the remote address can be set to the magical value .Li 0.0.0. Ns Em * which means that we do not care what address the remote side will use, as long as it is not 0.0.0.0. This is useful if your ISP has several dial-in servers. You can of course .Nm route Cm add Ar something_or_other 0.0.0. Ns Em * and it will do exactly what you would want it to. .Pp The PAP and CHAP authentication protocols as described in RFC 1334, and RFC 1994 resp., are also implemented. Their parameters are being controlled by the .Xr spppcontrol 8 utility. .Pp VJ header compression is implemented, and enabled by default. It can be disabled using .Xr spppcontrol 8 . .Sh DIAGNOSTICS .Bl -diag .It : illegal in state An event happened that should not happen for the current state the respective control protocol is in. See RFC 1661 for a description of the state automaton. .It : loopback The state automaton detected a line loopback (that is, it was talking with itself). The interface will be temporarily disabled. .It : up The LCP layer is running again, after a line loopback had previously been detected. .It : down The keepalive facility detected the line being unresponsive. Keepalive must be explicitly requested by the lower layers in order to take place. .El .Sh SEE ALSO .Xr inet 4 , .Xr intro 4 , -.Xr ppp 4 , .Xr ifconfig 8 , .Xr spppcontrol 8 .Rs .%A W. Simpson, Editor .%T "The Point-to-Point Protocol (PPP)" .%O RFC 1661 .Re .Rs .%A G. McGregor .%T "The PPP Internet Protocol Control Protocol (IPCP)" .%O RFC 1332 .Re .Rs .%A B. Lloyd .%A W. Simpson .%T "PPP Authentication Protocols" .%O RFC 1334 .Re .Rs .%A W. Simpson .%T "PPP Challenge Handshake Authentication Protocol (CHAP)" .%O RFC 1994 .Re .Sh AUTHORS .An -nosplit The original implementation of .Nm was written in 1994 at Cronyx Ltd., Moscow by .An Serge Vakulenko Aq Mt vak@cronyx.ru . .An J\(:org Wunsch Aq Mt joerg_wunsch@uriah.heep.sax.de rewrote a large part in 1997 in order to fully implement the state machine as described in RFC 1661, so it could also be used for dialup lines. He also wrote this man page. Serge later on wrote a basic implementation for PAP and CHAP, which served as the base for the current implementation, done again by .An J\(:org Wunsch . .Sh BUGS Many. .Pp Currently, only the .Em IPCP control protocol and .Xr ip 4 network protocol is supported. More NCPs should be implemented, as well as other control protocols for authentication and link quality reporting. .Pp Negotiation loop avoidance is not fully implemented. If the negotiation does not converge, this can cause an endless loop. .Pp The various parameters that should be adjustable per RFC 1661 are currently hard-coded into the kernel, and should be made accessible through .Xr spppcontrol 8 . .Pp .Em Passive mode has not been tested extensively. .Pp Link-level compression protocols should be supported. Index: head/share/man/man4/vxlan.4 =================================================================== --- head/share/man/man4/vxlan.4 (revision 297354) +++ head/share/man/man4/vxlan.4 (revision 297355) @@ -1,235 +1,235 @@ .\" Copyright (c) 2014 Bryan Venteicher .\" 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 16, 2014 .Dt VXLAN 4 .Os .Sh NAME .Nm vxlan .Nd "Virtual eXtensible LAN interface" .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device vxlan" .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_vxlan_load="YES" .Ed .Sh DESCRIPTION The .Nm driver creates a virtual tunnel endpoint in a .Nm segment. A .Nm segment is a virtual Layer 2 (Ethernet) network that is overlaid in a Layer 3 (IP/UDP) network. .Nm is analogous to .Xr vlan 4 but is designed to be better suited for large, multiple tenant data center environments. .Pp Each .Nm interface is created at runtime using interface cloning. This is most easily done with the .Xr ifconfig 8 .Cm create command or using the .Va cloned_interfaces variable in .Xr rc.conf 5 . The interface may be removed with the .Xr ifconfig 8 .Cm destroy command. .Pp The .Nm driver creates a pseudo Ethernet network interface that supports the usual network .Xr ioctl 2 Ns s and is thus can be used with .Xr ifconfig 8 like any other Ethernet interface. The .Nm interface encapsulates the Ethernet frame by prepending IP/UDP and .Nm headers. Thus, the encapsulated (inner) frame is able to transmitted over a routed, Layer 3 network to the remote host. .Pp The .Nm interface may be configured in either unicast or multicast mode. When in unicast mode, the interface creates a tunnel to a single remote host, and all traffic is transmitted to that host. When in multicast mode, the interface joins an IP multicast group, and receives packets sent to the group address, and transmits packets to either the multicast group address, or directly the remote host if there is an appropriate forwarding table entry. .Pp When the .Nm interface is brought up, a .Xr UDP 4 .Xr socket 9 is created based on the configuration, such as the local address for unicast mode or the group address for multicast mode, and the listening (local) port number. Since multiple .Nm interfaces may be created that either use the same local address or join the same group address, and use the same port, the driver may share a socket among multiple interfaces. However, each interface within a socket must belong to a unique .Nm segment. The analogous .Xr vlan 4 configuration would be a physical interface configured as the parent device for multiple VLAN interfaces, each with a unique VLAN tag. Each .Nm segment is identified by a 24-bit value in the .Nm header called the .Dq VXLAN Network Identifier , or VNI. .Pp When configured with the .Xr ifconfig 8 .Cm vxlanlearn parameter, the interface dynamically creates forwarding table entries from received packets. An entry in the forwarding table maps the inner source MAC address to the outer remote IP address. During transmit, the interface attempts to lookup an entry for the encapsulated destination MAC address. If an entry is found, the IP address in the entry is used to directly transmit the encapsulated frame to the destination. Otherwise, when configured in multicast mode, the interface must flood the frame to all hosts in the group. The maximum number of entries in the table is configurable with the .Xr ifconfig 8 .Cm vxlanmaxaddr command. Stale entries in the table periodically pruned. The timeout is configurable with the .Xr ifconfig 8 .Cm vxlantimeout command. The table may be viewed with the .Xr sysctl 8 .Cm net.link.vxlan.N.ftable.dump command. .Sh MTU Since the .Nm interface encapsulates the Ethernet frame with an IP, UDP, and .Nm header, the resulting frame may be larger than the MTU of the physical network. The .Nm specification recommends the physical network MTU be configured to use jumbo frames to accommodate the encapsulated frame size. Alternatively, the .Xr ifconfig 8 .Cm mtu command may be used to reduce the MTU size on the .Nm interface to allow the encapsulated frame to fit in the current MTU of the physical network. .Sh EXAMPLES Create a .Nm interface in unicast mode with the .Cm vxlanlocal tunnel address of 192.168.100.1, and the .Cm vxlanremote tunnel address of 192.168.100.2. .Bd -literal -offset indent ifconfig vxlan create vxlanid 108 vxlanlocal 192.168.100.1 vxlanremote 192.168.100.2 .Ed .Pp Create a .Nm interface in multicast mode, with the .Cm local address of 192.168.10.95, and the .Cm group address of 224.0.2.6. The em0 interface will be used to transmit multicast packets. .Bd -literal -offset indent ifconfig vxlan create vxlanid 42 vxlanlocal 192.168.10.95 vxlangroup 224.0.2.6 vxlandev em0 .Ed .Pp Once created, the .Nm interface can be configured with .Xr ifconfig 8 . .Sh SEE ALSO .Xr inet 4 , .Xr inet6 4 , +.Xr vlan 4 , .Xr ifconfig 8 , -.Xr sysctl 8 , -.Xr vlan 8 +.Xr sysctl 8 .Rs .%A "M. Mahalingam" .%A "et al" .%T "Virtual eXtensible Local Area Network (VXLAN): A Framework for Overlaying Virtualized Layer 2 Networks over Layer 3 Networks" .%D August 2014 .%O "RFC 7348" .Re .Sh AUTHOR .An -nosplit The .Nm driver was written by .An Bryan Venteicher Aq bryanv@freebsd.org . Index: head/share/man/man5/periodic.conf.5 =================================================================== --- head/share/man/man5/periodic.conf.5 (revision 297354) +++ head/share/man/man5/periodic.conf.5 (revision 297355) @@ -1,993 +1,993 @@ .\"- .\" Copyright (c) 2000 Brian Somers .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd March 26, 2015 .Dt PERIODIC.CONF 5 .Os .Sh NAME .Nm periodic.conf .Nd periodic job configuration information .Sh DESCRIPTION The file .Nm contains a description of how daily, weekly and monthly system maintenance jobs should run. It resides in the .Pa /etc/defaults directory and parts may be overridden by a file of the same name in .Pa /etc , which itself may be overridden by the .Pa /etc/periodic.conf.local file. .Pp The .Nm file is actually sourced as a shell script from each of the periodic scripts and is intended to simply provide default configuration variables. .Pp The following variables are used by .Xr periodic 8 itself: .Bl -tag -offset 4n -width 2n .It Va local_periodic .Pq Vt str List of directories to search for periodic scripts. This list is always prefixed with .Pa /etc/periodic , and is only used when an argument to .Xr periodic 8 is not an absolute directory name. .It Ao Ar dir Ac Ns Va _output .Pq Vt path No or Vt list What to do with the output of the scripts executed from the directory .Ar dir . If this variable is set to an absolute path name, output is logged to that file, otherwise it is taken as one or more space separated email addresses and mailed to those users. If this variable is not set or is empty, output is sent to standard output. .Pp For an unattended machine, suitable values for .Va daily_output , .Va weekly_output , and .Va monthly_output might be .Dq Li /var/log/daily.log , .Dq Li /var/log/weekly.log , and .Dq Li /var/log/monthly.log respectively, as .Xr newsyslog 8 will rotate these files (if they exists) at the appropriate times. .It Ao Ar dir Ac Ns Va _show_success .It Ao Ar dir Ac Ns Va _show_info .It Ao Ar dir Ac Ns Va _show_badconfig .Pq Vt bool These variables control whether .Xr periodic 8 will mask the output of the executed scripts based on their return code (where .Ar dir is the base directory name in which each script resides). If the return code of a script is .Sq 0 and .Ao Ar dir Ac Ns Va _show_success is set to .Dq Li NO , .Xr periodic 8 will mask the script's output. If the return code of a script is .Sq 1 and .Ao Ar dir Ac Ns Va _show_info is set to .Dq Li NO , .Xr periodic 8 will mask the script's output. If the return code of a script is .Sq 2 and .Ao Ar dir Ac Ns Va _show_badconfig is set to .Dq Li NO , .Xr periodic 8 will mask the script's output. If these variables are set to neither .Dq Li YES nor .Dq Li NO , they default to .Dq Li YES , .Dq Li YES and .Dq Li NO respectively. .Pp Refer to the .Xr periodic 8 manual page for how script return codes are interpreted. .El .Pp The following variables are used by the standard scripts that reside in .Pa /etc/periodic/daily : .Bl -tag -offset 4n -width 2n .It Va daily_clean_disks_enable .Pq Vt bool Set to .Dq Li YES if you want to remove all files matching .Va daily_clean_disks_files daily. .It Va daily_clean_disks_files .Pq Vt str Set to a list of file names to match. Wild cards are permitted. .It Va daily_clean_disks_days .Pq Vt num When .Va daily_clean_disks_enable is set to .Dq Li YES , this must also be set to the number of days old that a file's access and modification times must be before it is deleted. .It Va daily_clean_disks_verbose .Pq Vt bool Set to .Dq Li YES if you want the removed files to be reported in your daily output. .It Va daily_clean_tmps_enable .Pq Vt bool Set to .Dq Li YES if you want to clear temporary directories daily. .It Va daily_clean_tmps_dirs .Pq Vt str Set to the list of directories to clear if .Va daily_clean_tmps_enable is set to .Dq Li YES . .It Va daily_clean_tmps_days .Pq Vt num When .Va daily_clean_tmps_enable is set, this must also be set to the number of days old that a file's access and modification times must be before it is deleted. .It Va daily_clean_tmps_ignore .Pq Vt str Set to the list of files that should not be deleted when .Va daily_clean_tmps_enable is set to .Dq Li YES . Wild card characters are permitted. .It Va daily_clean_tmps_verbose .Pq Vt bool Set to .Dq Li YES if you want the removed files to be reported in your daily output. .It Va daily_clean_preserve_enable .Pq Vt bool Set to .Dq Li YES if you wish to remove old files from .Pa /var/preserve . .It Va daily_clean_preserve_days .Pq Vt num Set to the number of days that files must not have been modified before they are deleted. .It Va daily_clean_preserve_verbose .Pq Vt bool Set to .Dq Li YES if you want the removed files to be reported in your daily output. .It Va daily_clean_msgs_enable .Pq Vt bool Set to .Dq Li YES if you wish old system messages to be purged. .It Va daily_clean_msgs_days .Pq Vt num Set to the number of days that files must not have been modified before they are deleted. If this variable is left blank, the .Xr msgs 1 default is used. .It Va daily_clean_rwho_enable .Pq Vt bool Set to .Dq Li YES if you wish old files in .Pa /var/who to be purged. .It Va daily_clean_rwho_days .Pq Vt num Set to the number of days that files must not have been modified before they are deleted. .It Va daily_clean_rwho_verbose .Pq Vt bool Set to .Dq Li YES if you want the removed files to be reported in your daily output. .It Va daily_clean_hoststat_enable .Pq Vt bool Set to .Dq Li YES to run .Nm sendmail Fl bH to automatically purge stale entries from .Xr sendmail 8 Ns 's host status cache. Files will be deleted using the same criteria as .Xr sendmail 8 would normally use when determining whether to believe the cached information, as configured in .Pa /etc/mail/sendmail.cf . .It Va daily_backup_passwd_enable .Pq Vt bool Set to .Dq Li YES if you want the .Pa /etc/master.passwd and .Pa /etc/group files backed up and reported on. Reporting consists of checking both files for modifications and running .Xr chkgrp 8 on the .Pa group file. .It Va daily_backup_aliases_enable .Pq Vt bool Set to .Dq Li YES if you want the .Pa /etc/mail/aliases file backed up and modifications to be displayed in your daily output. .It Va daily_calendar_enable .Pq Vt bool Set to .Dq Li YES if you want to run .Nm calendar Fl a daily. .It Va daily_accounting_enable .Pq Vt bool Set to .Dq Li YES if you want to rotate your daily accounting files. No rotations are necessary unless .Va accounting_enable is enabled in .Xr rc.conf 5 . .It Va daily_accounting_compress .Pq Vt bool Set to .Dq Li YES if you want your daily accounting files to be compressed using .Xr gzip 1 . .It Va daily_accounting_save .Pq Vt num When .Va daily_accounting_enable is set, this may also be set to the number of daily accounting files that are to be saved. The default is .Dq Li 3 . .It Va daily_accounting_flags .Pq Vt str Set to the arguments to pass to the .Xr sa 8 utility (in addition to .Fl s ) when .Va daily_accounting_enable is set to .Dq Li YES . The default is .Fl q . .It Va daily_news_expire_enable .Pq Vt bool Set to .Dq Li YES if you want to run .Pa /etc/news.expire . .It Va daily_status_disks_enable .Pq Vt bool Set to .Dq Li YES if you want to run .Xr df 1 (with the arguments supplied in .Va daily_status_disks_df_flags ) and .Nm dump Fl W . .It Va daily_status_disks_df_flags .Pq Vt str Set to the arguments for the .Xr df 1 utility when .Va daily_status_disks_enable is set to .Dq Li YES . The default is .Fl l Fl h . .It Va daily_status_zfs_enable .Pq Vt bool Set to .Dq Li YES if you want to run .Nm zpool Cm status on your .Xr zfs 8 pools. .It Va daily_status_zfs_zpool_list_enable .Pq Vt bool Set to .Dq Li YES if you want to run .Nm zpool Cm list on your .Xr zfs 8 pools. Requires .Va daily_status_zfs_enable to be set to .Li YES . .It Va daily_status_gmirror_enable .Pq Vt bool Set to .Dq Li YES if you want to run .Nm gmirror Cm status on your .Xr gmirror 8 devices. .It Va daily_status_graid3_enable .Pq Vt bool Set to .Dq Li YES if you want to run .Nm graid3 Cm status on your .Xr graid3 8 devices. .It Va daily_status_gstripe_enable .Pq Vt bool Set to .Dq Li YES if you want to run .Nm gstripe Cm status on your .Xr gstripe 8 devices. .It Va daily_status_gconcat_enable .Pq Vt bool Set to .Dq Li YES if you want to run .Nm gconcat Cm status on your .Xr gconcat 8 devices. .It Va daily_status_network_enable .Pq Vt bool Set to .Dq Li YES if you want to run .Nm netstat Fl i . .It Va daily_status_network_netstat_flags .Pq Vt str Set to additional arguments for the .Xr netstat 1 utility when .Va daily_status_network_enable is set to .Dq Li YES . The default is .Fl d . .It Va daily_status_network_usedns .Pq Vt bool Set to .Dq Li YES if you want to run .Xr netstat 1 without the .Fl n option (to do DNS lookups). .It Va daily_status_rwho_enable .Pq Vt bool Set to .Dq Li YES if you want to run .Xr uptime 1 (or .Xr ruptime 1 if .Va rwhod_enable is set to .Dq Li YES in .Pa /etc/rc.conf ) . .It Va daily_status_mailq_enable .Pq Vt bool Set to .Dq Li YES if you want to run .Xr mailq 1 . .It Va daily_status_mailq_shorten .Pq Vt bool Set to .Dq Li YES if you want to shorten the .Xr mailq 1 output when .Va daily_status_mailq_enable is set to .Dq Li YES . .It Va daily_status_include_submit_mailq .Pq Vt bool Set to .Dq Li YES if you also want to run .Xr mailq 1 on the submit mail queue when .Va daily_status_mailq_enable is set to .Dq Li YES . This may not work with MTAs other than .Xr sendmail 8 . .It Va daily_status_security_enable .Pq Vt bool Set to .Dq Li YES if you want to run the security check. The security check is another set of .Xr periodic 8 scripts. The system defaults are in .Pa /etc/periodic/security . Local scripts should be placed in .Pa /usr/local/etc/periodic/security . See the .Xr periodic 8 manual page for more information. .It Va daily_status_security_inline .Pq Vt bool Set to .Dq Li YES if you want the security check output inline. The default is to either mail or log the output according to the value of .Va daily_status_security_output . .It Va daily_status_security_output .Pq Vt str Where to send the output of the security check if .Va daily_status_security_inline is set to .Dq Li NO . This variable behaves in the same way as the .Va *_output variables above, namely it can be set either to one or more email addresses or to an absolute file name. .It Va daily_status_mail_rejects_enable .Pq Vt bool Set to .Dq Li YES if you want to summarise mail rejections logged to .Pa /var/log/maillog for the previous day. .It Va daily_status_mail_rejects_logs .Pq Vt num Set to the number of maillog files that should be checked for yesterday's mail rejects. .It Va daily_status_ntpd .Pq Vt bool Set to .Dq Li YES if you want to enable NTP status check. .It Va daily_status_world_kernel .Pq Vt bool Set to .Dq Li YES to check the running userland and kernel are in sync. .It Va daily_queuerun_enable .Pq Vt bool Set to .Dq Li YES if you want to manually run the mail queue at least once a day. .It Va daily_submit_queuerun .Pq Vt bool Set to .Dq Li YES if you also want to manually run the submit mail queue at least once a day when .Va daily_queuerun_enable is set to .Dq Li YES . .It Va daily_scrub_zfs_enable .Pq Vt bool Set to .Dq Li YES if you want to run a zfs scrub periodically. .It Va daily_scrub_zfs_pools .Pq Vt str A space separated list of names of zfs pools to scrub. If the list is empty or not set, all zfs pools are scrubbed. .It Va daily_scrub_zfs_default_threshold .Pq Vt int Number of days between a scrub if no pool-specific threshold is set. If not set, the default value is 35, corresponding to 5 weeks. .It Va daily_scrub_zfs_ Ns Ao Ar poolname Ac Ns Va _threshold .Pq Vt int The same as .Va daily_scrub_zfs_default_threshold but specific to the pool .Ao Ar poolname Ac Ns . .It Va daily_local .Pq Vt str Set to a list of extra scripts that should be run after all other daily scripts. All scripts must be absolute path names. .El .Pp The following variables are used by the standard scripts that reside in .Pa /etc/periodic/weekly : .Bl -tag -offset 4n -width 2n .It Va weekly_locate_enable .Pq Vt bool Set to .Dq Li YES if you want to run .Pa /usr/libexec/locate.updatedb . This script is run using .Nm nice Fl 5 as user .Dq Li nobody , and generates the table used by the .Xr locate 1 command. .It Va weekly_whatis_enable .Pq Vt bool Set to .Dq Li YES if you want to run .Pa /usr/libexec/makewhatis.local . This script regenerates the database used by the .Xr apropos 1 command. .It Va weekly_catman_enable .Pq Vt bool Set to .Dq Li YES if you want to run .Pa /usr/libexec/catman.local . This script processes all out of date manual pages, speeding up the .Xr man 1 command at the expense of disk space. .It Va weekly_noid_enable .Pq Vt bool Set to .Dq Li YES if you want to locate orphaned files on the system. An orphaned file is one with an invalid owner or group. .It Va weekly_noid_dirs .Pq Vt str A list of directories under which orphaned files are searched for. This would usually be set to .Pa / . .It Va weekly_status_security_enable .Pq Vt bool Weekly counterpart of .Va daily_status_security_enable . .It Va weekly_status_security_inline .Pq Vt bool Weekly counterpart of .Va daily_status_security_inline . .It Va weekly_status_security_output .Pq Vt str Weekly counterpart of .Va daily_status_security_output . .It Va weekly_status_pkg_enable .Pq Vt bool Set to .Dq Li YES if you want to use -.Xr pkg_version 1 +.Xr pkg-version 8 to list installed packages which are out of date. .It Va pkg_version .Pq Vt str When .Va weekly_status_pkg_enable is set to .Dq Li YES , this variable specifies the program that is used to determine the out of date packages. If unset, the -.Xr pkg_version 1 +.Xr pkg-version 8 program is used. As an example, this variable might be set to .Dq Li portversion if the .Pa ports/sysutils/portupgrade port has been installed. .It Va pkg_version_index .Pq Vt str This variable specifies the .Pa INDEX file from .Pa /usr/ports that should be used by -.Xr pkg_version 1 . +.Xr pkg-version 8 . Because the dependency tree may be substantially different between versions of .Fx , there may be more than one .Pa INDEX file in .Pa /usr/ports . .Pp Note, if the .Va pkg_version variable is set to .Dq Li portversion , it will also be necessary to arrange that the correct .Pa INDEX file is specified using environment variables and that .Va pkg_version_index is cleared in .Pa /etc/periodic.conf .Pq Dq Li pkg_version_index= . .It Va weekly_local .Pq Vt str Set to a list of extra scripts that should be run after all other weekly scripts. All scripts must be absolute path names. .El .Pp The following variables are used by the standard scripts that reside in .Pa /etc/periodic/monthly : .Bl -tag -offset 4n -width 2n .It Va monthly_accounting_enable .Pq Vt bool Set to .Dq Li YES if you want to do login accounting using the .Xr ac 8 command. .It Va monthly_status_security_enable .Pq Vt bool Monthly counterpart of .Va daily_status_security_enable . .It Va monthly_status_security_inline .Pq Vt bool Monthly counterpart of .Va daily_status_security_inline . .It Va monthly_status_security_output .Pq Vt str Monthly counterpart of .Va daily_status_security_output . .It Va monthly_local .Pq Vt str Set to a list of extra scripts that should be run after all other monthly scripts. All scripts must be absolute path names. .El .Pp The following variables are used by the standard scripts that reside in .Pa /etc/periodic/security . Those scripts are usually run from daily .Pq Va daily_status_security_enable , weekly .Pq Va weekly_status_security_enable , and monthly .Pq Va monthly_status_security_enable periodic hooks. The .Va ..._period of each script can be configured as .Dq daily , .Dq weekly , .Dq monthly or .Dq NO . Note that when periodic security scripts are run from .Xr crontab 5 , they will be always run unless their .Va ..._enable or .Va ..._period variable is set to .Dq NO . .Bl -tag -offset 4n -width 2n .It Va security_status_diff_flags .Pq Vt str Set to the arguments to pass to the .Xr diff 1 utility when generating differences. The default is .Fl b u . .It Va security_status_chksetuid_enable .Pq Vt bool Set to .Dq Li YES to compare the modes and modification times of setuid executables with the previous day's values. .It Va security_status_chksetuid_period .Pq Vt str Set to either .Dq Li daily , .Dq Li weekly , .Dq Li monthly or .Dq Li NO . .It Va security_status_chkportsum_enable .Pq Vt bool Set to .Dq Li YES to verify checksums of all installed packages against the known checksums in .Pa /var/db/pkg . .It Va security_status_chkportsum_period .Pq Vt str Set to either .Dq Li daily , .Dq Li weekly , .Dq Li monthly or .Dq Li NO . .It Va security_status_neggrpperm_enable .Pq Vt bool Set to .Dq Li YES to check for files where the group of a file has less permissions than the world at large. When users are in more than 14 supplemental groups these negative permissions may not be enforced via NFS shares. .It Va security_status_neggrpperm_period .Pq Vt str Set to either .Dq Li daily , .Dq Li weekly , .Dq Li monthly or .Dq Li NO . .It Va security_status_chkmounts_enable .Pq Vt bool Set to .Dq Li YES to check for changes mounted file systems to the previous day's values. .It Va security_status_chkmounts_period .Pq Vt str Set to either .Dq Li daily , .Dq Li weekly , .Dq Li monthly or .Dq Li NO . .It Va security_status_noamd .Pq Vt bool Set to .Dq Li YES if you want to ignore .Xr amd 8 mounts when comparing against yesterday's file system mounts in the .Va security_status_chkmounts_enable check. .It Va security_status_chkuid0_enable .Pq Vt bool Set to .Dq Li YES to check .Pa /etc/master.passwd for accounts with UID 0. .It Va security_status_chkuid0_period .Pq Vt str Set to either .Dq Li daily , .Dq Li weekly , .Dq Li monthly or .Dq Li NO . .It Va security_status_passwdless_enable .Pq Vt bool Set to .Dq Li YES to check .Pa /etc/master.passwd for accounts with empty passwords. .It Va security_status_passwdless_period .Pq Vt str Set to either .Dq Li daily , .Dq Li weekly , .Dq Li monthly or .Dq Li NO . .It Va security_status_logincheck_enable .Pq Vt bool Set to .Dq Li YES to check .Pa /etc/login.conf ownership, see .Xr login.conf 5 for more information. .It Va security_status_logincheck_period .Pq Vt str Set to either .Dq Li daily , .Dq Li weekly , .Dq Li monthly or .Dq Li NO . .It Va security_status_ipfwdenied_enable .Pq Vt bool Set to .Dq Li YES to show log entries for packets denied by .Xr ipfw 8 since yesterday's check. .It Va security_status_ipfwdenied_period .Pq Vt str Set to either .Dq Li daily , .Dq Li weekly , .Dq Li monthly or .Dq Li NO . .It Va security_status_ipfdenied_enable .Pq Vt bool Set to .Dq Li YES to show log entries for packets denied by .Xr ipf 8 since yesterday's check. .It Va security_status_ipfdenied_period .Pq Vt str Set to either .Dq Li daily , .Dq Li weekly , .Dq Li monthly or .Dq Li NO . .It Va security_status_pfdenied_enable .Pq Vt bool Set to .Dq Li YES to show log entries for packets denied by .Xr pf 4 since yesterday's check. .It Va security_status_pfdenied_period .Pq Vt str Set to either .Dq Li daily , .Dq Li weekly , .Dq Li monthly or .Dq Li NO . .It Va security_status_ipfwlimit_enable .Pq Vt bool Set to .Dq Li YES to display .Xr ipfw 8 rules that have reached their verbosity limit. .It Va security_status_ipfwlimit_period .Pq Vt str Set to either .Dq Li daily , .Dq Li weekly , .Dq Li monthly or .Dq Li NO . .It Va security_status_kernelmsg_enable .Pq Vt bool Set to .Dq Li YES to show new .Xr dmesg 8 entries since yesterday's check. .It Va security_status_kernelmsg_period .Pq Vt str Set to either .Dq Li daily , .Dq Li weekly , .Dq Li monthly or .Dq Li NO . .It Va security_status_loginfail_enable .Pq Vt bool Set to .Dq Li YES to display failed logins from .Pa /var/log/messages in the previous day. .It Va security_status_loginfail_period .Pq Vt str Set to either .Dq Li daily , .Dq Li weekly , .Dq Li monthly or .Dq Li NO . .It Va security_status_tcpwrap_enable .Pq Vt bool Set to .Dq Li YES to display connections denied by tcpwrappers (see .Xr hosts_access 5 ) from .Pa /var/log/messages during the previous day. .It Va security_status_tcpwrap_period .Pq Vt str Set to either .Dq Li daily , .Dq Li weekly , .Dq Li monthly or .Dq Li NO . .El .Sh FILES .Bl -tag -width ".Pa /etc/defaults/periodic.conf" .It Pa /etc/defaults/periodic.conf The default configuration file. This file contains all default variables and values. .It Pa /etc/periodic.conf The usual system specific variable override file. .It Pa /etc/periodic.conf.local An additional override file, useful when .Pa /etc/periodic.conf is shared or distributed. .El .Sh SEE ALSO .Xr apropos 1 , .Xr calendar 1 , .Xr df 1 , .Xr diff 1 , .Xr gzip 1 , .Xr locate 1 , .Xr man 1 , .Xr msgs 1 , .Xr netstat 1 , .Xr nice 1 , -.Xr pkg_version 1 , .Xr login.conf 5 , .Xr rc.conf 5 , .Xr ac 8 , .Xr chkgrp 8 , .Xr dump 8 , .Xr newsyslog 8 , .Xr periodic 8 , +.Xr pkg-version 8 , .Xr sendmail 8 .Sh HISTORY The .Nm file appeared in .Fx 4.1 . .Sh AUTHORS .An Brian Somers Aq Mt brian@Awfulhak.org Index: head/share/man/man7/ports.7 =================================================================== --- head/share/man/man7/ports.7 (revision 297354) +++ head/share/man/man7/ports.7 (revision 297355) @@ -1,571 +1,571 @@ .\" .\" Copyright (c) 1997 David E. O'Brien .\" .\" 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 June 6, 2014 .Dt PORTS 7 .Os .Sh NAME .Nm ports .Nd contributed applications .Sh DESCRIPTION The .Fx Ports Collection offers a simple way for users and administrators to install applications. Each .Em port contains any patches necessary to make the original application source code compile and run on .Fx . Compiling an application is as simple as typing .Nm make Cm build in the port directory! The .Pa Makefile automatically fetches the application source code, either from a local disk or via FTP, unpacks it on your system, applies the patches, and compiles it. If all goes well, simply type .Nm make Cm install to install the application. .Pp For more information about using ports, see .Dq "Packages and Ports" in .%B "The FreeBSD Handbook" , .Pa ( file:/usr/share/doc/en_US.ISO8859-1/books/handbook/ports.html or .Pa http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/ports.html ) . For information about creating new ports, see .%B "The Porter's Handbook" .Pa ( file:/usr/share/doc/en_US.ISO8859-1/books/porters-handbook/index.html or .Pa http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/porters-handbook/ ) . .Sh TARGETS Some of the targets work recursively through subdirectories. This lets you, for example, install all of the .Dq Li biology ports. The targets that do this are .Cm build , checksum , clean , configure , .Cm depends , extract , fetch , install , and .Cm package . .Pp The following targets will be run automatically by each proceeding target in order. That is, .Cm build will be run (if necessary) by .Cm install , and so on all the way to .Cm fetch . Usually, you will only use the .Cm install target. .Bl -tag -width ".Cm configure" .It Cm config Configure .Va OPTIONS for this port using .Xr dialog4ports 1 . .It Cm fetch Fetch all of the files needed to build this port from the sites listed in .Va MASTER_SITES and .Va PATCH_SITES . See .Va FETCH_CMD , MASTER_SITE_OVERRIDE and .Va MASTER_SITE_BACKUP . .It Cm checksum Verify that the fetched distfile's checksum matches the one the port was tested against. If the distfile's checksum does not match, it also fetches the distfiles which are missing or failed the checksum calculation. Defining .Va NO_CHECKSUM will skip this step. .It Cm depends Install (or compile if only compilation is necessary) any dependencies of the current port. When called by the .Cm extract or .Cm fetch targets, this is run in piecemeal as .Cm fetch-depends , build-depends , etc. Defining .Va NO_DEPENDS will skip this step. .It Cm extract Expand the distfile into a work directory. .It Cm patch Apply any patches that are necessary for the port. .It Cm configure Configure the port. Some ports will ask you questions during this stage. See .Va INTERACTIVE and .Va BATCH . .It Cm build Build the port. This is the same as calling the .Cm all target. .It Cm install Install the port and register it with the package system. This is all you really need to do. .El .Pp The following targets are not run during the normal install process. .Bl -tag -width ".Cm fetch-recursive" .It Cm showconfig Display .Va OPTIONS config for this port. .It Cm showconfig-recursive Display .Va OPTIONS config for this port and all its dependencies. .It Cm rmconfig Remove .Va OPTIONS config for this port. .It Cm rmconfig-recursive Remove .Va OPTIONS config for this port and all its dependencies. .It Cm config-conditional Skip the ports which have already had their .Va OPTIONS configured. .It Cm config-recursive Configure .Va OPTIONS for this port and all its dependencies using .Xr dialog4ports 1 . .It Cm fetch-list Show list of files to be fetched in order to build the port. .It Cm fetch-recursive Fetch the distfiles of the port and all its dependencies. .It Cm fetch-recursive-list Show list of files that would be retrieved by .Cm fetch-recursive . .It Cm run-depends-list , build-depends-list Print a list of all the compile and run dependencies, and dependencies of those dependencies, by port directory. .It Cm all-depends-list Print a list of all dependencies for the port. .It Cm pretty-print-run-depends-list , pretty-print-build-depends-list Print a list of all the compile and run dependencies, and dependencies of those dependencies, by port name and version. .It Cm missing Print a list of missing dependencies to be installed for the port. .It Cm clean Remove the expanded source code. This recurses to dependencies unless .Va NOCLEANDEPENDS is defined. .It Cm distclean Remove the port's distfiles and perform the .Cm clean target. The .Cm clean portion recurses to dependencies unless .Va NOCLEANDEPENDS is defined, but the .Cm distclean portion never recurses (this is perhaps a bug). .It Cm reinstall Use this to restore a port after using -.Xr pkg_delete 1 +.Xr pkg-delete 8 when you should have used .Cm deinstall . .It Cm deinstall Remove an installed port from the system, similar to -.Xr pkg_delete 1 . +.Xr pkg-delete 8 . .It Cm deinstall-all Remove all installed ports with the same .Va PKGORIGIN from the system. .It Cm package Make a binary package for the port. The port will be installed if it has not already been. The package is a .Pa .tbz file that you can use to install the port on other machines with -.Xr pkg_add 1 . +.Xr pkg-add 8 . If the directory specified by .Va PACKAGES does not exist, the package will be put into the current directory. See .Va PKGREPOSITORY and .Va PKGFILE . .It Cm package-recursive Like .Cm package , but makes a package for each depending port as well. .It Cm package-name Prints the name with version of the port. .It Cm readmes Create a port's .Pa README.html . This can be used from .Pa /usr/ports to create a browsable web of all ports on your system! .It Cm search Search the .Pa INDEX file for the pattern specified by the .Va key (searches the port name, comment, and dependencies), .Va name (searches the port name only), .Va path (searches the port path), .Va info (searches the port info), .Va maint (searches the port maintainer), .Va cat (searches the port category), .Va bdeps (searches the port build-time dependency), .Va rdeps (searches the port run-time dependency), .Va www (searches the port web site) .Xr make 1 variables, and their exclusion counterparts: .Va xname , xkey etc. For example, one would type: .Pp .Dl "cd /usr/ports && make search name=query" .Pp to find all ports whose name matches .Dq Li query . Results include the matching ports' path, comment, maintainer, build dependencies, and run dependencies. .Bd -literal -offset indent cd /usr/ports && make search name=pear- \e xbdeps=apache .Ed .Pp To find all ports whose names contain .Dq Li pear- and which do not have apache listed in build-time dependencies. .Bd -literal -offset indent cd /usr/ports && make search name=pear- \e xname='ht(tp|ml)' .Ed .Pp To find all ports whose names contain .Dq Li pear- , but not .Dq Li html or .Dq Li http . .Bd -literal -offset indent make search key=apache display=name,path,info keylim=1 .Ed .Pp To find ports that contain .Dq Li apache in either of the name, path, info fields, ignore the rest of the record. .Pp By default the search is not case-sensitive. In order to make it case-sensitive you can use the .Va icase variable: .Bd -literal -offset indent make search name=p5-R icase=0 .Ed .It Cm quicksearch Reduced .Cm search output. Only display name, path and info. .It Cm describe Generate a one-line description of each port for use in the .Pa INDEX file. .It Cm maintainer Display the port maintainer's email address. .It Cm index Create .Pa /usr/ports/INDEX , which is used by the .Cm pretty-print-* and .Cm search targets. Running the .Cm index target will ensure your .Pa INDEX file is up to date with your ports tree. .It Cm fetchindex Fetch the .Pa INDEX file from the .Fx cluster. .El .Sh ENVIRONMENT You can change all of these. .Bl -tag -width ".Va MASTER_SITES" .It Va PORTSDIR Location of the ports tree. This is .Pa /usr/ports on .Fx and .Ox , and .Pa /usr/pkgsrc on .Nx . .It Va WRKDIRPREFIX Where to create any temporary files. Useful if .Va PORTSDIR is read-only (perhaps mounted from a CD-ROM). .It Va DISTDIR Where to find/put distfiles, normally .Pa distfiles/ in .Va PORTSDIR . .It Va PACKAGES Used only for the .Cm package target; the base directory for the packages tree, normally .Pa packages/ in .Va PORTSDIR . If this directory exists, the package tree will be (partially) constructed. This directory does not have to exist; if it does not, packages will be placed into the current directory, or you can define one of .Bl -tag -width ".Va PKGREPOSITORY" .It Va PKGREPOSITORY Directory to put the package in. .It Va PKGFILE The full path to the package. .El .It Va LOCALBASE Where existing things are installed and where to search for files when resolving dependencies (usually .Pa /usr/local ) . .It Va PREFIX Where to install this port (usually set to the same as .Va LOCALBASE ) . .It Va MASTER_SITES Primary sites for distribution files if not found locally. .It Va PATCH_SITES Primary locations for distribution patch files if not found locally. .It Va MASTER_SITE_FREEBSD If set, go to the master .Fx site for all files. .It Va MASTER_SITE_OVERRIDE Try going to these sites for all files and patches, first. .It Va MASTER_SITE_BACKUP Try going to these sites for all files and patches, last. .It Va RANDOMIZE_MASTER_SITES Try the download locations in a random order. .It Va MASTER_SORT Sort the download locations according to user supplied pattern. Example: .Dl .dk .sunet.se .se dk.php.net .no .de heanet.dl.sourceforge.net .It Va MASTER_SITE_INDEX Where to get .Pa INDEX source built on .Fx cluster (for .Cm fetchindex target). Defaults to .Pa http://www.FreeBSD.org/ports/ . .It Va FETCHINDEX Command to get .Pa INDEX (for .Cm fetchindex target). Defaults to .Dq Nm fetch Fl am . .It Va NOCLEANDEPENDS If defined, do not let .Cm clean recurse to dependencies. .It Va FETCH_CMD Command to use to fetch files. Normally .Xr fetch 1 . .It Va FORCE_PKG_REGISTER If set, overwrite any existing package registration on the system. .It Va MOTIFLIB Location of .Pa libXm. Ns Brq Pa a , Ns Pa so . .It Va INTERACTIVE If defined, only operate on a port if it requires interaction. .It Va BATCH If defined, only operate on a port if it can be installed 100% automatically. .It Va DISABLE_VULNERABILITIES If defined, disable check for security vulnerabilities using .Xr pkg-audit 8 when installing new ports. .It Va NO_IGNORE If defined, allow installation of ports marked as .Aq Va FORBIDDEN . The default behavior of the Ports framework is to abort when the installation of a forbidden port is attempted. Of course, these ports may not work as expected, but if you really know what you are doing and are sure about installing a forbidden port, then .Va NO_IGNORE lets you do it. .It Va NO_CHECKSUM If defined, skip verifying the port's checksum. .It Va TRYBROKEN If defined, attempt to build a port even if it is marked as .Aq Va BROKEN . .It Va PORT_DBDIR Directory where the results of configuring .Va OPTIONS are stored. Defaults to .Pa /var/db/ports . Each port where .Va OPTIONS have been configured will have a uniquely named sub-directory, containing a single file .Pa options . .El .Sh MAKE VARIABLES The following list provides a name and short description for many of the variables that are used when building ports. More information on these and other related variables may be found in .Pa ${PORTSDIR}/Mk/* and the .Fx Porter's Handbook. .Bl -tag -width ".Va OVERRIDE_LINUX_BASE_PORT" .It Va WITH_OPENSSL_PORT .Pq Vt bool If set, causes ports that make use of OpenSSL to use the OpenSSL from ports .Pq if available instead of the OpenSSL from the base system. .It Va WITH_DEBUG .Pq Vt bool If set, debugging symbols are installed for ports binaries. .It Va WITH_DEBUG_PORTS A list of origins for which to set .Va WITH_DEBUG_PORTS . .It Va WITH_SSP_PORTS .Pq Vt bool If set, enables .Fl fstack-protector for most ports. .It Va WITH_GHOSTSCRIPT_VER If set, the version of ghostscript to be used by ports. .It Va OVERRIDE_LINUX_BASE_PORT The default linux base to use. .It Va WITH_CCACHE_BUILD .Pq Vt bool If set, enables the use of .Xr ccache 1 for building ports. .It Va CCACHE_DIR Which directory to use for the ccache data. .El .Sh FILES .Bl -tag -width ".Pa /usr/ports/Mk/bsd.port.mk" -compact .It Pa /usr/ports The default ports directory .It Pa /usr/ports/Mk/bsd.port.mk The big Kahuna. .El .Sh SEE ALSO .Xr make 1 , .Xr make.conf 5 , .Xr pkg 8 , .Xr portsnap 8 .Pp The following are part of the ports collection: .Pp .Xr pkg 7 , .Xr portlint 1 .Rs .%B "The FreeBSD Handbook" .Re .Pp .Pa http://www.FreeBSD.org/ports (searchable index of all ports) .Sh HISTORY The Ports Collection appeared in .Fx 1.0 . It has since spread to .Nx and .Ox . .Sh AUTHORS .An -nosplit This manual page was originated by .An David O'Brien . .Sh BUGS Ports documentation is split over four places \(em .Pa /usr/ports/Mk/bsd.port.mk , .%B "The Porter's Handbook" , the .Dq "Packages and Ports" chapter of .%B "The FreeBSD Handbook" , and this manual page. Index: head/share/man/man9/netisr.9 =================================================================== --- head/share/man/man9/netisr.9 (revision 297354) +++ head/share/man/man9/netisr.9 (revision 297355) @@ -1,213 +1,213 @@ .\" .\" Copyright (c) 2009 Robert N. M. Watson .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice(s), this list of conditions and the following disclaimer as .\" the first lines of this file unmodified other than the possible .\" addition of one or more copyright notices. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice(s), this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH .\" DAMAGE. .\" .\" $FreeBSD$ .\" .Dd January 11, 2015 .Dt NETISR 9 .Os .Sh NAME .Nm netisr .Nd Kernel network dispatch service .Sh SYNOPSIS .In net/netisr.h .Ft void .Fn netisr_register "const struct netisr_handler *nhp" .Ft void .Fn netisr_unregister "const struct netisr_handler *nhp" .Ft int .Fn netisr_dispatch "u_int proto" "struct mbuf *m" .Ft int .Fn netisr_dispatch_src "u_int proto" "uintptr_t source" "struct mbuf *m" .Ft int .Fn netisr_queue "u_int proto" "struct mbuf *m" .Ft int .Fn netisr_queue_src "u_int proto" "uintptr_t source" "struct mbuf *m" .Ft void .Fn netisr_clearqdrops "const struct netisr_handler *nhp" .Ft void .Fn netisr_getqdrops "const struct netisr_handler *nhp" "uint64_t *qdropsp" .Ft void .Fn netisr_getqlimit "const struct netisr_handler *nhp" "u_int *qlimitp" .Ft int .Fn netisr_setqlimit "const struct netisr_handler *nhp" "u_int qlimit" .Ft u_int .Fn netisr_default_flow2cpu "u_int flowid" .Ft u_int .Fn netisr_get_cpucount "void" .Ft u_int .Fn netisr_get_cpuid "u_int cpunumber" .Sh DESCRIPTION The .Nm kernel interface suite allows device drivers (and other packet sources) to direct packets to protocols for directly dispatched or deferred processing. Protocol registration and work stream statistics may be monitored using .Xr netstat 1 . .Ss Protocol registration Protocols register and unregister handlers using .Fn netisr_register and .Fn netisr_unregister , and may also manage queue limits and statistics using the .Fn netisr_clearqdrops , .Fn netisr_getqdrops , .Fn netisr_getqlimit , and .Fn netisr_setqlimit . .Pp .Nm supports multi-processor execution of handlers, and relies on a combination of source ordering and protocol-specific ordering and work-placement policies to decide how to distribute work across one or more worker threads. Registering protocols will declare one of three policies: .Bl -tag -width NETISR_POLICY_SOURCE .It Dv NETISR_POLICY_SOURCE .Nm should maintain source ordering without advice from the protocol. .Nm will ignore any flow IDs present on .Vt mbuf headers for the purposes of work placement. .It Dv NETISR_POLICY_FLOW .Nm should maintain flow ordering as defined by the .Vt mbuf header flow ID field. If the protocol implements .Va nh_m2flow , then .Nm will query the protocol in the event that the .Vt mbuf doesn't have a flow ID, falling back on source ordering. .It NETISR_POLICY_CPU .Nm will entirely delegate all work placement decisions to the protocol, querying .Va nh_m2cpuid for each packet. .El .Pp Registration is declared using .Vt "struct netisr_handler" , whose fields are defined as follows: .Bl -tag -width "netisr_handler_t nh_handler" .It Vt "const char *" Va nh_name Unique character string name of the protocol, which may be included in -.Xr sysctl 2 +.Xr sysctl 3 MIB names, so should not contain whitespace. .It Vt netisr_handler_t Va nh_handler Protocol handler function that will be invoked on each packet received for the protocol. .It Vt netisr_m2flow_t Va nh_m2flow Optional protocol function to generate a flow ID and set a valid hashtype for packets that enter the .Nm with .Dv M_HASHTYPE_GET(m) equal to .Dv M_HASHTYPE_NONE . Will be used only with .Dv NETISR_POLICY_FLOW . .It Vt netisr_m2cpuid_t Va nh_m2cpuid Protocol function to determine what CPU a packet should be processed on. Will be used only with .Dv NETISR_POLICY_CPU . .It Vt netisr_drainedcpu_t Va nh_drainedcpu Optional callback function that will be invoked when a per-CPU queue was drained. It will never fire for directly dispatched packets. Unless fully understood, this special-purpose function should not be used. .\" In case you intend to use this please send 50 chocolate bars to each .\" of rwatson and bz and wait for an answer. .It Vt u_int Va nh_proto Protocol number used by both protocols to identify themselves to .Nm , and by packet sources to select what handler will be used to process packets. A table of supported protocol numbers appears below. For implementation reasons, protocol numbers great than 15 are currently unsupported. .It Vt u_int Va nh_qlimit The maximum per-CPU queue depth for the protocol; due to internal implementation details, the effective queue depth may be as much as twice this number. .It Vt u_int Va nh_policy The ordering and work placement policy for the protocol, as described earlier. .El .Ss Packet source interface Packet sources, such as network interfaces, may request protocol processing using the .Fn netisr_dispatch and .Fn netisr_queue interfaces. Both accept a protocol number and .Vt mbuf argument, but while .Fn netisr_queue will always execute the protocol handler asynchronously in a deferred context, .Fn netisr_dispatch will optionally direct dispatch if permitted by global and per-protocol policy. .Pp In order to provide additional load balancing and flow information, packet sources may also specify an opaque source identifier, which in practice might be a network interface number or socket pointer, using the .Fn netisr_dispatch_src and .Fn netisr_queue_src variants. .Ss Protocol number constants The follow protocol numbers are currently defined: .Bl -tag -width NETISR_ROUTE .It Dv NETISR_IP IPv4 .It Dv NETISR_IGMP IGMPv3 loopback .It Dv NETISR_ROUTE Routing socket loopback .It Dv NETISR_ARP ARP .It Dv NETISR_IPV6 IPv6 .It Dv NETISR_NATM ATM .It Dv NETISR_EPAIR .Xr netstat 1 , .Xr epair 4 .El .Sh AUTHORS This manual page and the .Nm implementation were written by .An Robert N. M. Watson .