diff --git a/lib/libc/sys/fhlink.2 b/lib/libc/sys/fhlink.2 index 332856630879..b7f7d02dd136 100644 --- a/lib/libc/sys/fhlink.2 +++ b/lib/libc/sys/fhlink.2 @@ -1,255 +1,254 @@ .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2018 Gandi .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd November 30, 2022 .Dt FHLINK 2 .Os .Sh NAME .Nm fhlink , .Nm fhlinkat .Nd make a hard file link .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In unistd.h .Ft int .Fn fhlink "fhandle_t *fhp" "const char *to" .Ft int .Fn fhlinkat "fhandle_t *fhp" "int tofd" "const char *to" -.Fc .Sh DESCRIPTION The .Fn fhlink system call atomically creates the specified directory entry (hard link) .Fa to with the attributes of the underlying object pointed at by .Fa fhp . If the link is successful: the link count of the underlying object is incremented; .Fa fhp and .Fa to share equal access and rights to the underlying object. .Pp If .Fa fhp is removed, the file .Fa to is not deleted and the link count of the underlying object is decremented. .Pp The object pointed at by the .Fa fhp argument must exist for the hard link to succeed and both .Fa fhp and .Fa to must be in the same file system. The .Fa fhp argument may not be a directory. .Pp The .Fn fhlinkat system call is equivalent to .Fa fhlink except in the case where .Fa to is a relative paths. In this case a relative path .Fa to is interpreted relative to the directory associated with the file descriptor .Fa tofd instead of the current working directory. .Pp If .Fn fhlinkat is passed the special value .Dv AT_FDCWD in the .Fa tofd parameter, the current working directory is used for the .Fa to argument. If .Fa tofd has value .Dv AT_FDCWD , the behavior is identical to a call to .Fn link . Unless .Fa flag contains the .Dv AT_SYMLINK_FOLLOW flag, if .Fa fhp names a symbolic link, a new link is created for the symbolic link .Fa fhp and not its target. .Sh RETURN VALUES .Rv -std link .Sh ERRORS The .Fn fhlink system call will fail and no link will be created if: .Bl -tag -width Er .It Bq Er ENOTDIR A component of .Fa to prefix is not a directory. .It Bq Er ENAMETOOLONG A component of .Fa to exceeded 255 characters, or entire length of .Fa to name exceeded 1023 characters. .It Bq Er ENOENT A component of .Fa to prefix does not exist. .It Bq Er EOPNOTSUPP The file system containing the file pointed at by .Fa fhp does not support links. .It Bq Er EMLINK The link count of the file pointed at by .Fa fhp would exceed 32767. .It Bq Er EACCES A component of .Fa to prefix denies search permission. .It Bq Er EACCES The requested link requires writing in a directory with a mode that denies write permission. .It Bq Er ELOOP Too many symbolic links were encountered in translating one of the pathnames. .It Bq Er ENOENT The file pointed at by .Fa fhp does not exist. .It Bq Er EEXIST The link named by .Fa to does exist. .It Bq Er EPERM The file pointed at by .Fa fhp is a directory. .It Bq Er EPERM The file pointed at by .Fa fhp has its immutable or append-only flag set, see the .Xr chflags 2 manual page for more information. .It Bq Er EPERM The parent directory of the file named by .Fa to has its immutable flag set. .It Bq Er EXDEV The link named by .Fa to and the file pointed at by .Fa fhp are on different file systems. .It Bq Er ENOSPC The directory in which the entry for the new link is being placed cannot be extended because there is no space left on the file system containing the directory. .It Bq Er EDQUOT The directory in which the entry for the new link is being placed cannot be extended because the user's quota of disk blocks on the file system containing the directory has been exhausted. .It Bq Er EIO An I/O error occurred while reading from or writing to the file system to make the directory entry. .It Bq Er EINTEGRITY Corrupted data was detected while reading from the file system. .It Bq Er EROFS The requested link requires writing in a directory on a read-only file system. .It Bq Er EFAULT One of the pathnames specified is outside the process's allocated address space. .It Bq Er ESTALE The file handle .Fa fhp is no longer valid .El .Pp In addition to the errors returned by the .Fn fhlink , the .Fn fhlinkat system call may fail if: .Bl -tag -width Er .It Bq Er EBADF The .Fa fhp or .Fa to argument does not specify an absolute path and the .Fa tofd argument, is not .Dv AT_FDCWD nor a valid file descriptor open for searching. .It Bq Er EINVAL The value of the .Fa flag argument is not valid. .It Bq Er ENOTDIR The .Fa fhp or .Fa to argument is not an absolute path and .Fa tofd is not .Dv AT_FDCWD nor a file descriptor associated with a directory. .El .Sh SEE ALSO .Xr fhopen 2 , .Xr fhreadlink 2 , .Xr fhstat 2 .Sh HISTORY The .Fn fhlink and .Fn fhlinkat system calls first appeared in .Fx 12.1 . diff --git a/lib/libc/sys/fhreadlink.2 b/lib/libc/sys/fhreadlink.2 index 23850c6a2117..222142de223e 100644 --- a/lib/libc/sys/fhreadlink.2 +++ b/lib/libc/sys/fhreadlink.2 @@ -1,97 +1,95 @@ .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2018 Gandi .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd November 30, 2022 .Dt FHREADLINK 2 .Os .Sh NAME .Nm fhreadlink .Nd read value of a symbolic link .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/param.h .In sys/mount.h .Ft int .Fn fhreadlink "fhandle_t *fhp" "char *buf" "size_t bufsize" -.Fc .Sh DESCRIPTION The .Fn fhreadlink system call places the contents of the symbolic link .Fa fhp in the buffer .Fa buf , which has size .Fa bufsiz . The .Fn fhreadlink system call does not append a .Dv NUL character to .Fa buf . .Pp .Sh RETURN VALUES The call returns the count of characters placed in the buffer if it succeeds, or a \-1 if an error occurs, placing the error code in the global variable .Va errno . .Sh ERRORS The .Fn readlink system call will fail if: .Bl -tag -width Er .It Bq Er ENOENT The named file does not exist. .It Bq Er ELOOP Too many symbolic links were encountered in translating the file handle .Fa fhp . .It Bq Er EINVAL The named file is not a symbolic link. .It Bq Er EIO An I/O error occurred while reading from the file system. .It Bq Er EINTEGRITY Corrupted data was detected while reading from the file system. .It Bq Er EFAULT The .Fa buf argument extends outside the process's allocated address space. .It Bq Er ESTALE The file handle .Fa fhp is no longer valid .El -.El .Sh SEE ALSO .Xr fhstat 2 , .Xr fhlink 2 , .Sh HISTORY The .Fn fhreadlink system call first appeared in .Fx 12.1 . diff --git a/lib/libc/sys/getfh.2 b/lib/libc/sys/getfh.2 index f5eaf4be7874..ae3b67edf1e8 100644 --- a/lib/libc/sys/getfh.2 +++ b/lib/libc/sys/getfh.2 @@ -1,233 +1,234 @@ .\" Copyright (c) 1989, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" Copyright (c) 2018 Gandi .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)getfh.2 8.1 (Berkeley) 6/9/93 .\" .Dd November 30, 2022 .Dt GETFH 2 .Os .Sh NAME .Nm getfh , .Nm lgetfh , .Nm getfhat .Nd get file handle .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/param.h .In sys/mount.h .Ft int .Fn getfh "const char *path" "fhandle_t *fhp" .Ft int .Fn lgetfh "const char *path" "fhandle_t *fhp" .Ft int .Fn getfhat "int fd" "const char *path" "fhandle_t *fhp" "int flag" .Sh DESCRIPTION The .Fn getfh system call returns a file handle for the specified file or directory in the file handle pointed to by .Fa fhp . .Pp The .Fn lgetfh system call is like .Fn getfh except in the case where the named file is a symbolic link, in which case .Fn lgetfh returns information about the link, while .Fn getfh returns information about the file the link references. .Pp The .Fn getfhat system call is equivalent to .Fn getfh and .Fn lgetfh except when the .Fa path specifies a relative path. For .Fn getfhat and relative .Fa path , the status is retrieved from a file relative to the directory associated with the file descriptor .Fa fd instead of the current working directory. .Pp The values for the .Fa flag are constructed by a bitwise-inclusive OR of flags from this list, defined in .In fcntl.h : .Bl -tag -width indent .It Dv AT_SYMLINK_NOFOLLOW If .Fa path names a symbolic link, the status of the symbolic link is returned. .It Dv AT_RESOLVE_BENEATH Only walk paths below the directory specified by the .Ar fd descriptor. See the description of the .Dv O_RESOLVE_BENEATH flag in the .Xr open 2 manual page. .El .Pp If .Fn getfhat is passed the special value .Dv AT_FDCWD in the .Fa fd parameter, the current working directory is used and the behavior is identical to a call to .Fn getfth or .Fn lgetfh respectively, depending on whether or not the .Dv AT_SYMLINK_NOFOLLOW bit is set in .Fa flag . .Pp When .Fn getfhat is called with an absolute .Fa path , it ignores the .Fa fd argument. .Pp These system calls are restricted to the superuser. .Sh RETURN VALUES .Rv -std .Sh ERRORS The .Fn getfh and .Fn lgetfh system calls fail if one or more of the following are true: .Bl -tag -width Er .It Bq Er EPERM The caller does not have appropriate privilege to perform the operation. .It Bq Er ENOTDIR A component of the path prefix of .Fa path is not a directory. .It Bq Er ENAMETOOLONG The length of a component of .Fa path exceeds 255 characters, or the length of .Fa path exceeds 1023 characters. .It Bq Er ENOENT The file referred to by .Fa path does not exist. .It Bq Er EACCES Search permission is denied for a component of the path prefix of .Fa path . .It Bq Er ELOOP Too many symbolic links were encountered in translating .Fa path . .It Bq Er EFAULT The .Fa fhp argument points to an invalid address. .It Bq Er EFAULT The .Fa path argument points to an invalid address. .It Bq Er EIO An .Tn I/O error occurred while reading from or writing to the file system. .It Bq Er EINTEGRITY Corrupted data was detected while reading from the file system. .It Bq Er ESTALE The file handle .Fa fhp is no longer valid. .El .Pp In addition to the errors returned by .Fn getfh , and .Fn lgetfh , the .Fn getfhat system call may fail if: .Bl -tag -width Er .It Bq Er EBADF The .Fa path argument does not specify an absolute path and the .Fa fd argument, is neither .Dv AT_FDCWD nor a valid file descriptor open for searching. .It Bq Er EINVAL The value of the .Fa flag argument is not valid. .It Bq Er ENOTDIR The .Fa path argument is not an absolute path and .Fa fd is neither .Dv AT_FDCWD nor a file descriptor associated with a directory. +.El .Sh SEE ALSO .Xr fhopen 2 , .Xr open 2 , .Xr stat 2 .Sh HISTORY The .Fn getfh system call first appeared in .Bx 4.4 . The .Fn lgetfh system call first appeared in .Fx 5.3 . The .Fn getfhat system call first appeared in .Fx 12.1 . diff --git a/lib/libc/sys/procctl.2 b/lib/libc/sys/procctl.2 index cb5234b6e40c..b040116a8e60 100644 --- a/lib/libc/sys/procctl.2 +++ b/lib/libc/sys/procctl.2 @@ -1,857 +1,858 @@ .\" Copyright (c) 2013 Hudson River Trading LLC .\" Written by: John H. Baldwin .\" All rights reserved. .\" .\" Copyright (c) 2014 The FreeBSD Foundation .\" Portions of this documentation were written by Konstantin Belousov .\" under sponsorship from the FreeBSD Foundation. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd October 26, 2023 .Dt PROCCTL 2 .Os .Sh NAME .Nm procctl .Nd control processes .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/procctl.h .Ft int .Fn procctl "idtype_t idtype" "id_t id" "int cmd" "void *data" .Sh DESCRIPTION The .Fn procctl system call provides for control over processes. The .Fa idtype and .Fa id arguments specify the set of processes to control. If multiple processes match the identifier, .Nm will make a .Dq best effort to control as many of the selected processes as possible. An error is only returned if no selected processes successfully complete the request. The following identifier types are supported: .Bl -tag -width P_PGID .It Dv P_PID Control the process with the process ID .Fa id . .Fa id zero is a shortcut for the calling process ID. .It Dv P_PGID Control processes belonging to the process group with the ID .Fa id . .El .Pp The control request to perform is specified by the .Fa cmd argument. .Pp All status changing requests .Dv *_CTL require the caller to have the right to debug the target. All status query requests .DV *_STATUS require the caller to have the right to observe the target. .Pp The following commands are supported: .Bl -tag -width PROC_TRAPCAP_STATUS .It Dv PROC_ASLR_CTL Controls the Address Space Layout Randomization (ASLR) in the program images created by .Xr execve 2 in the specified process or its descendants that do not either change the control or modify it by other means. The .Fa data parameter must point to the integer variable holding one of the following values: .Bl -tag -width PROC_ASLR_FORCE_DISABLE .It Dv PROC_ASLR_FORCE_ENABLE Request that ASLR is enabled after execution, even if it is disabled system-wide. The image flag and set-uid might prevent ASLR enablement still. .It Dv PROC_ASLR_FORCE_DISABLE Request that ASLR is disabled after execution. Same notes as for .Dv PROC_ASLR_FORCE_ENABLE apply. .It Dv PROC_ASLR_NOFORCE Use the system-wide configured policy for ASLR. .El .It Dv PROC_ASLR_STATUS Returns the current status of ASLR enablement for the target process. The .Fa data parameter must point to the integer variable, where one of the following values is written: .Bl -tag -width PROC_ASLR_FORCE_DISABLE .It Dv PROC_ASLR_FORCE_ENABLE .It Dv PROC_ASLR_FORCE_DISABLE .It Dv PROC_ASLR_NOFORCE .El .Pp If the currently executed image in the process itself has ASLR enabled, the .Dv PROC_ASLR_ACTIVE flag is or-ed with the value listed above. .It Dv PROC_PROTMAX_CTL Controls implicit application of PROT_MAX protection equal to the .Fa prot argument of the .Xr mmap 2 syscall, in the target process. The .Fa data parameter must point to the integer variable holding one of the following values: .Bl -tag -width PROC_PROTMAX_FORCE_DISABLE .It Dv PROC_PROTMAX_FORCE_ENABLE Enables implicit PROT_MAX application, even if it is disabled system-wide by the sysctl .Va vm.imply_prot_max . The image flag might still prevent the enablement. .It Dv PROC_PROTMAX_FORCE_DISABLE Request that implicit application of PROT_MAX be disabled. Same notes as for .Dv PROC_PROTMAX_FORCE_ENABLE apply. .It Dv PROC_PROTMAX_NOFORCE Use the system-wide configured policy for PROT_MAX. .El .It Dv PROC_PROTMAX_STATUS Returns the current status of implicit PROT_MAX enablement for the target process. The .Fa data parameter must point to the integer variable, where one of the following values is written: .Bl -tag -width PROC_PROTMAX_FORCE_DISABLE .It Dv PROC_PROTMAX_FORCE_ENABLE .It Dv PROC_PROTMAX_FORCE_DISABLE .It Dv PROC_PROTMAX_NOFORCE .El .Pp If the currently executed image in the process itself has implicit PROT_MAX application enabled, the .Dv PROC_PROTMAX_ACTIVE flag is or-ed with the value listed above. .It Dv PROC_SPROTECT Set process protection state. This is used to mark a process as protected from being killed if the system exhausts the available memory and swap. The .Fa data parameter must point to an integer containing an operation and zero or more optional flags. The following operations are supported: .Bl -tag -width PPROT_CLEAR .It Dv PPROT_SET Mark the selected processes as protected. .It Dv PPROT_CLEAR Clear the protected state of selected processes. .El .Pp The following optional flags are supported: .Bl -tag -width PPROT_DESCEND .It Dv PPROT_DESCEND Apply the requested operation to all child processes of each selected process in addition to each selected process. .It Dv PPROT_INHERIT When used with .Dv PPROT_SET , mark all future child processes of each selected process as protected. Future child processes will also mark all of their future child processes. .El .It Dv PROC_REAP_ACQUIRE Acquires the reaper status for the current process. Reaper status means that children orphaned by the reaper's descendants that were forked after the acquisition of reaper status are reparented to the reaper process. After system initialization, .Xr init 8 is the default reaper. .It Dv PROC_REAP_RELEASE Release the reaper state for the current process. The reaper of the current process becomes the new reaper of the current process's descendants. .It Dv PROC_REAP_STATUS Provides information about the reaper of the specified process, or the process itself when it is a reaper. The .Fa data argument must point to a .Vt procctl_reaper_status structure which is filled in by the syscall on successful return. .Bd -literal struct procctl_reaper_status { u_int rs_flags; u_int rs_children; u_int rs_descendants; pid_t rs_reaper; pid_t rs_pid; }; .Ed The .Fa rs_flags may have the following flags returned: .Bl -tag -width REAPER_STATUS_REALINIT .It Dv REAPER_STATUS_OWNED The specified process has acquired reaper status and has not released it. When the flag is returned, the specified process .Fa id , pid, identifies the reaper, otherwise the .Fa rs_reaper field of the structure is set to the pid of the reaper for the specified process id. .It Dv REAPER_STATUS_REALINIT The specified process is the root of the reaper tree, i.e., .Xr init 8 . .El .Pp The .Fa rs_children field returns the number of children of the reaper among the descendants. It is possible to have a child whose reaper is not the specified process, since the reaper for any existing children is not reset on the .Dv PROC_REAP_ACQUIRE operation. The .Fa rs_descendants field returns the total number of descendants of the reaper(s), not counting descendants of the reaper in the subtree. The .Fa rs_reaper field returns the reaper pid. The .Fa rs_pid returns the pid of one reaper child if there are any descendants. .It Dv PROC_REAP_GETPIDS Queries the list of descendants of the reaper of the specified process. The request takes a pointer to a .Vt procctl_reaper_pids structure in the .Fa data parameter. .Bd -literal struct procctl_reaper_pids { u_int rp_count; struct procctl_reaper_pidinfo *rp_pids; }; .Ed When called, the .Fa rp_pids field must point to an array of .Vt procctl_reaper_pidinfo structures, to be filled in on return, and the .Fa rp_count field must specify the size of the array, into which no more than .Fa rp_count elements will be filled in by the kernel. .Pp The .Vt "struct procctl_reaper_pidinfo" structure provides some information about one of the reaper's descendants. Note that for a descendant that is not a child, it may be incorrectly identified because of a race in which the original child process exited and the exited process's pid was reused for an unrelated process. .Bd -literal struct procctl_reaper_pidinfo { pid_t pi_pid; pid_t pi_subtree; u_int pi_flags; }; .Ed The .Fa pi_pid field is the process id of the descendant. The .Fa pi_subtree field provides the pid of the child of the reaper, which is the (grand-)parent of the process. The .Fa pi_flags field returns the following flags, further describing the descendant: .Bl -tag -width REAPER_PIDINFO_EXITING .It Dv REAPER_PIDINFO_VALID Set to indicate that the .Vt procctl_reaper_pidinfo structure was filled in by the kernel. Zero-filling the .Fa rp_pids array and testing the .Dv REAPER_PIDINFO_VALID flag allows the caller to detect the end of the returned array. .It Dv REAPER_PIDINFO_CHILD The .Fa pi_pid field identifies the direct child of the reaper. .It Dv REAPER_PIDINFO_REAPER The reported process is itself a reaper. The descendants of the subordinate reaper are not reported. .It Dv REAPER_PIDINFO_ZOMBIE The reported process is in the zombie state, ready to be reaped. .It Dv REAPER_PIDINFO_STOPPED The reported process is stopped by a SIGSTOP/SIGTSTP signal. .It Dv REAPER_PIDINFO_EXITING The reported process is in the process of exiting (but not yet a zombie). .El .It Dv PROC_REAP_KILL Request to deliver a signal to some subset of the descendants of the reaper. The .Fa data parameter must point to a .Vt procctl_reaper_kill structure, which is used both for parameters and status return. .Bd -literal struct procctl_reaper_kill { int rk_sig; u_int rk_flags; pid_t rk_subtree; u_int rk_killed; pid_t rk_fpid; }; .Ed The .Fa rk_sig field specifies the signal to be delivered. Zero is not a valid signal number, unlike for .Xr kill 2 . The .Fa rk_flags field further directs the operation. It is or-ed from the following flags: .Bl -tag -width REAPER_KILL_CHILDREN .It Dv REAPER_KILL_CHILDREN Deliver the specified signal only to direct children of the reaper. .It Dv REAPER_KILL_SUBTREE Deliver the specified signal only to descendants that were forked by the direct child with pid specified in the .Fa rk_subtree field. .El If neither the .Dv REAPER_KILL_CHILDREN nor the .Dv REAPER_KILL_SUBTREE flags are specified, all current descendants of the reaper are signalled. .Pp If a signal was delivered to any process, the return value from the request is zero. In this case, the .Fa rk_killed field identifies the number of processes signalled. The .Fa rk_fpid field is set to the pid of the first process for which signal delivery failed, e.g., due to permission problems. If no such process exists, the .Fa rk_fpid field is set to -1. .It Dv PROC_TRACE_CTL Enable or disable tracing of the specified process(es), according to the value of the integer argument. Tracing includes attachment to the process using the .Xr ptrace 2 and .Xr ktrace 2 , debugging sysctls, .Xr hwpmc 4 , .Xr dtrace 1 , and core dumping. Possible values for the .Fa data argument are: .Bl -tag -width PROC_TRACE_CTL_DISABLE_EXEC .It Dv PROC_TRACE_CTL_ENABLE Enable tracing, after it was disabled by .Dv PROC_TRACE_CTL_DISABLE . Only allowed for self. .It Dv PROC_TRACE_CTL_DISABLE Disable tracing for the specified process. Tracing is re-enabled when the process changes the executing program with the .Xr execve 2 syscall. A child inherits the trace settings from the parent on .Xr fork 2 . .It Dv PROC_TRACE_CTL_DISABLE_EXEC Same as .Dv PROC_TRACE_CTL_DISABLE , but the setting persists for the process even after .Xr execve 2 . .El .It Dv PROC_TRACE_STATUS Returns the current tracing status for the specified process in the integer variable pointed to by .Fa data . If tracing is disabled, .Fa data is set to -1. If tracing is enabled, but no debugger is attached by the .Xr ptrace 2 syscall, .Fa data is set to 0. If a debugger is attached, .Fa data is set to the pid of the debugger process. .It Dv PROC_TRAPCAP_CTL Controls the capability mode sandbox actions for the specified sandboxed processes, on a return from any syscall which gives either a .Er ENOTCAPABLE or .Er ECAPMODE error. If the control is enabled, such errors from the syscalls cause delivery of the synchronous .Dv SIGTRAP signal to the thread immediately before returning from the syscalls. .Pp Possible values for the .Fa data argument are: .Bl -tag -width PROC_TRAPCAP_CTL_DISABLE .It Dv PROC_TRAPCAP_CTL_ENABLE Enable the .Dv SIGTRAP signal delivery on capability mode access violations. The enabled mode is inherited by the children of the process, and is kept after .Xr fexecve 2 calls. .It Dv PROC_TRAPCAP_CTL_DISABLE Disable the signal delivery on capability mode access violations. Note that the global sysctl .Dv kern.trap_enotcap might still cause the signal to be delivered. See .Xr capsicum 4 . .El .Pp On signal delivery, the .Va si_errno member of the .Fa siginfo signal handler parameter is set to the syscall error value, and the .Va si_code member is set to .Dv TRAP_CAP . The system call number is stored in the .Va si_syscall field of the .Fa siginfo signal handler parameter. The other system call parameters can be read from the .Fa ucontext_t but the system call number is typically stored in the register that also contains the return value and so is unavailable in the signal handler. .Pp See .Xr capsicum 4 for more information about the capability mode. .It Dv PROC_TRAPCAP_STATUS Return the current status of signalling capability mode access violations for the specified process. The integer value pointed to by the .Fa data argument is set to the .Dv PROC_TRAPCAP_CTL_ENABLE value if the process control enables signal delivery, and to .Dv PROC_TRAPCAP_CTL_DISABLE otherwise. .Pp See the note about sysctl .Dv kern.trap_enotcap above, which gives independent global control of signal delivery. .It Dv PROC_PDEATHSIG_CTL Request the delivery of a signal when the parent of the calling process exits. .Fa idtype must be .Dv P_PID and .Fa id must be the either caller's pid or zero, with no difference in effect. The value is cleared for child processes and when executing set-user-ID or set-group-ID binaries. .Fa data must point to a value of type .Vt int indicating the signal that should be delivered to the caller. Use zero to cancel a previously requested signal delivery. .It Dv PROC_PDEATHSIG_STATUS Query the current signal number that will be delivered when the parent of the calling process exits. .Fa idtype must be .Dv P_PID and .Fa id must be the either caller's pid or zero, with no difference in effect. .Fa data must point to a memory location that can hold a value of type .Vt int . If signal delivery has not been requested, it will contain zero on return. .It Dv PROC_STACKGAP_CTL Controls the stack gaps in the specified process. A stack gap is the part of the growth area for a .Dv MAP_STACK mapped region that is reserved and never filled by memory. Instead, the process is guaranteed to receive a .Dv SIGSEGV signal on accessing pages in the gap. Gaps protect against stack overflow corrupting memory adjacent to the stack. .Pp The .Fa data argument must point to an integer variable containing flags. The following flags are allowed: .Bl -tag -width PROC_STACKGAP_DISABLE_EXEC .It Dv PROC_STACKGAP_ENABLE This flag is only accepted for consistency with .Dv PROC_STACKGAP_STATUS . If stack gaps are enabled, the flag is ignored. If disabled, the flag causes an .Ev EINVAL error to be returned. After gaps are disabled in a process, they can only be re-enabled when an .Xr execve 2 is performed. .It Dv PROC_STACKGAP_DISABLE Disable stack gaps for the process. For existing stacks, the gap is no longer a reserved part of the growth area and can be filled by memory on access. .It Dv PROC_STACKGAP_ENABLE_EXEC Enable stack gaps for programs started after an .Xr execve 2 by the specified process. .It Dv PROC_STACKGAP_DISABLE_EXEC Inherit disabled stack gaps state after .Xr execve 2 . In other words, if the currently executing program has stack gaps disabled, they are kept disabled on exec. If gaps were enabled, they are kept enabled after exec. .El .Pp The stack gap state is inherited from the parent on .Xr fork 2 . .It Dv PROC_STACKGAP_STATUS Returns the current stack gap state for the specified process. .Fa data must point to an integer variable, which is used to return a bitmask consisting of the following flags: .Bl -tag -width PROC_STACKGAP_DISABLE_EXEC .It Dv PROC_STACKGAP_ENABLE Stack gaps are enabled. .It Dv PROC_STACKGAP_DISABLE Stack gaps are disabled. .It Dv PROC_STACKGAP_ENABLE_EXEC Stack gaps are enabled in the process after .Xr execve 2 . .It Dv PROC_STACKGAP_DISABLE_EXEC Stack gaps are disabled in the process after .Xr execve 2 . .El .It Dv PROC_NO_NEW_PRIVS_CTL Allows one to ignore the SUID and SGID bits on the program images activated by .Xr execve 2 in the specified process and its future descendants. The .Fa data parameter must point to the integer variable holding the following value: .Bl -tag -width PROC_NO_NEW_PRIVS_ENABLE .It Dv PROC_NO_NEW_PRIVS_ENABLE Request SUID and SGID bits to be ignored. .El .Pp It is not possible to disable it once it has been enabled. .It Dv PROC_NO_NEW_PRIVS_STATUS Returns the current status of SUID/SGID enablement for the target process. The .Fa data parameter must point to the integer variable, where one of the following values is written: .Bl -tag -width PROC_NO_NEW_PRIVS_DISABLE .It Dv PROC_NO_NEW_PRIVS_ENABLE .It Dv PROC_NO_NEW_PRIVS_DISABLE .El .It Dv PROC_WXMAP_CTL Controls the 'write exclusive against execution' permissions for the mappings in the process address space. It overrides the global settings established by the .Dv kern.elf{32/64}.allow_wx sysctl, and the corresponding bit in the ELF control note, see .Xr elfctl 1 . .Pp The .Fa data parameter must point to the integer variable holding one of the following values: .Bl -tag -width PROC_WX_MAPPINGS_DISALLOW_EXEC .It Dv PROC_WX_MAPPINGS_PERMIT Enable creation of mappings that have both write and execute protection attributes, in the specified process' address space. .It Dv PROC_WX_MAPPINGS_DISALLOW_EXEC In the new address space created by .Xr execve 2 , disallow creation of mappings that have both write and execute permissions. .El .Pp Once creation of writeable and executable mappings is allowed, it is impossible (and pointless) to disallow it. The only way to ensure the absence of such mappings after they were enabled in a given process, is to set the .Dv PROC_WX_MAPPINGS_DISALLOW_EXEC flag and .Xr execve 2 an image. .It Dv PROC_WXMAP_STATUS Returns the current status of the 'write exclusive against execution' enforcement for the specified process. The .Dv data parameter must point to the integer variable, where one of the following values is written: .Bl -tag -width PROC_WX_MAPPINGS_DISALLOW_EXEC .It Dv PROC_WX_MAPPINGS_PERMIT Creation of simultaneously writable and executable mapping is permitted, otherwise the process cannot create such mappings. .It Dv PROC_WX_MAPPINGS_DISALLOW_EXEC After .Xr execve 2 , the new address space should disallow creation of simultaneously writable and executable mappings. .El .Pp Additionally, if the address space of the process disallows creation of simultaneously writable and executable mappings and it is guaranteed that no such mapping was created since address space creation, the .Dv PROC_WXORX_ENFORCE flag is set in the returned value. .El .Sh x86 MACHINE-SPECIFIC REQUESTS .Bl -tag -width PROC_KPTI_STATUS .It Dv PROC_KPTI_CTL AMD64 only. Controls the Kernel Page Table Isolation (KPTI) option for the children of the specified process. For the command to work, the .Va vm.pmap.kpti tunable must be enabled on boot. It is not possible to change the KPTI setting for a running process, except at the .Xr execve 2 , where the address space is reinitialized. .Pp The .Fa data parameter must point to an integer variable containing one of the following commands: .Bl -tag -width PROC_KPTI_CTL_DISABLE_ON_EXEC .It Dv PROC_KPTI_CTL_ENABLE_ON_EXEC Enable KPTI after .Xr execve 2 . .It Dv PROC_KPTI_CTL_DISABLE_ON_EXEC Disable KPTI after .Xr execve 2 . Only root or a process having the .Va PRIV_IO privilege might use this option. .El .It Dv PROC_KPTI_STATUS Returns the current KPTI status for the specified process. .Fa data must point to the integer variable, which returns the following statuses: .Bl -tag -width PROC_KPTI_CTL_DISABLE_ON_EXEC .It Dv PROC_KPTI_CTL_ENABLE_ON_EXEC .It Dv PROC_KPTI_CTL_DISABLE_ON_EXEC .El .Pp The status is or-ed with the .Va PROC_KPTI_STATUS_ACTIVE in case KPTI is active for the current address space of the process. +.El .Sh NOTES Disabling tracing on a process should not be considered a security feature, as it is bypassable both by the kernel and privileged processes, and via other system mechanisms. As such, it should not be utilized to reliably protect cryptographic keying material or other confidential data. .Pp Note that processes can trivially bypass the 'no simultaneously writable and executable mappings' policy by first marking some mapping as writeable and write code to it, then removing write and adding execute permission. This may be legitimately required by some programs, such as JIT compilers. .Sh RETURN VALUES If an error occurs, a value of -1 is returned and .Va errno is set to indicate the error. .Sh ERRORS The .Fn procctl system call will fail if: .Bl -tag -width Er .It Bq Er EFAULT The .Fa data parameter points outside the process's allocated address space. .It Bq Er EINVAL The .Fa cmd argument specifies an unsupported command. .Pp The .Fa idtype argument specifies an unsupported identifier type. .It Bq Er EPERM The calling process does not have permission to perform the requested operation on any of the selected processes. .It Bq Er ESRCH No processes matched the requested .Fa idtype and .Fa id . .It Bq Er EINVAL An invalid operation or flag was passed in .Fa data for a .Dv PROC_SPROTECT command. .It Bq Er EPERM The .Fa idtype argument is not equal to .Dv P_PID , or .Fa id is not equal to the pid of the calling process, for .Dv PROC_REAP_ACQUIRE or .Dv PROC_REAP_RELEASE requests. .It Bq Er EINVAL Invalid or undefined flags were passed to a .Dv PROC_REAP_KILL request. .It Bq Er EINVAL An invalid or zero signal number was requested for a .Dv PROC_REAP_KILL request. .It Bq Er EINVAL The .Dv PROC_REAP_RELEASE request was issued by the .Xr init 8 process. .It Bq Er EBUSY The .Dv PROC_REAP_ACQUIRE request was issued by a process that had already acquired reaper status and has not yet released it. .It Bq Er EBUSY The .Dv PROC_TRACE_CTL request was issued for a process already being traced. .It Bq Er EPERM The .Dv PROC_TRACE_CTL request to re-enable tracing of the process .Po Dv PROC_TRACE_CTL_ENABLE Pc , or to disable persistence of .Dv PROC_TRACE_CTL_DISABLE on .Xr execve 2 was issued for a non-current process. .It Bq Er EINVAL The value of the integer .Fa data parameter for the .Dv PROC_TRACE_CTL or .Dv PROC_TRAPCAP_CTL request is invalid. .It Bq Er EINVAL The .Dv PROC_PDEATHSIG_CTL or .Dv PROC_PDEATHSIG_STATUS request referenced an unsupported .Fa id , .Fa idtype or invalid signal number. .El .Sh SEE ALSO .Xr dtrace 1 , .Xr proccontrol 1 , .Xr protect 1 , .Xr cap_enter 2 , .Xr kill 2 , .Xr ktrace 2 , .Xr mmap 2 , .Xr mprotect 2 , .Xr ptrace 2 , .Xr wait 2 , .Xr capsicum 4 , .Xr hwpmc 4 , .Xr init 8 .Sh HISTORY The .Fn procctl function appeared in .Fx 10.0 . .Pp The reaper facility is based on a similar feature of Linux and DragonflyBSD, and first appeared in .Fx 10.2 . .Pp The .Dv PROC_PDEATHSIG_CTL facility is based on the prctl(PR_SET_PDEATHSIG, ...) feature of Linux, and first appeared in .Fx 11.2 . .Pp The ASLR support was added to system for the checklists compliance in .Fx 13.0 . diff --git a/lib/libc/sys/ptrace.2 b/lib/libc/sys/ptrace.2 index ae1770315aa5..9b789a0e45b3 100644 --- a/lib/libc/sys/ptrace.2 +++ b/lib/libc/sys/ptrace.2 @@ -1,1441 +1,1441 @@ .\" $NetBSD: ptrace.2,v 1.2 1995/02/27 12:35:37 cgd Exp $ .\" .\" This file is in the public domain. .Dd August 18, 2023 .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, stepping by the tracing process, or an event in the traced 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 A traced process may report additional signal stops corresponding to events in the traced process. These additional signal stops are reported as .Dv SIGTRAP or .Dv SIGSTOP signals. The tracing process can use the .Dv PT_LWPINFO request to determine which events are associated with a .Dv SIGTRAP or .Dv SIGSTOP signal. Note that multiple events may be associated with a single signal. For example, events indicated by the .Dv PL_FLAG_BORN , .Dv PL_FLAG_FORKED , and .Dv PL_FLAG_EXEC flags are also reported as a system call exit event .Pq Dv PL_FLAG_SCX . The signal stop for a new child process enabled via .Dv PTRACE_FORK will report a .Dv SIGSTOP signal. All other additional signal stops use .Dv SIGTRAP . .Sh DETACH AND TERMINATION .Pp Normally, exiting tracing process should wait for all pending debugging events and then detach from all alive traced processes before exiting using .Dv PT_DETACH request. If tracing process exits without detaching, for instance due to abnormal termination, the destiny of the traced children processes is determined by the .Dv kern.kill_on_debugger_exit sysctl control. .Pp If the control is set to the default value 1, such traced processes are terminated. If set to zero, kernel implicitly detaches traced processes. Traced processes are un-stopped if needed, and then continue the execution without tracing. Kernel drops any .Dv SIGTRAP signals queued to the traced children, which could be either generated by not yet consumed debug events, or sent by other means, the later should not be done anyway. .Sh SELECTING THE TARGET The .Fa pid argument of the call specifies the target on which to perform the requested operation. For operations affecting the global process state, the process ID is typically passed there. Similarly, for operations affecting only a thread, the thread ID needs to be passed. .Pp Still, for global operations, the ID of any thread can be used as the target, and system will perform the request on the process owning that thread. If a thread operation got the process ID as .Fa pid , the system randomly selects a thread from among the threads owned by the process. For single-threaded processes there is no difference between specifying process or thread ID as the target. .Sh DISABLING PTRACE The .Nm subsystem provides rich facilities to manipulate other processes state. Sometimes it may be desirable to disallow it either completely, or limit its scope. The following controls are provided for this: .Bl -tag -width security.bsd.unprivileged_proc_debug .It Dv security.bsd.allow_ptrace Setting this sysctl to zero makes .Nm return .Er ENOSYS always as if the syscall is not implemented by the kernel. .It Dv security.bsd.unprivileged_proc_debug Setting this sysctl to zero disallows the use of .Fn ptrace by unprivileged processes. .It Dv security.bsd.see_other_uids Setting this sysctl to zero prevents .Fn ptrace requests from targeting processes with a real user identifier different from the caller's. These requests will fail with error .Er ESRCH . .It Dv security.bsd.see_other_gids Setting this sysctl to zero disallows .Fn ptrace requests from processes that have no groups in common with the target process, considering their sets of real and supplementary groups. These requests will fail with error .Er ESRCH . .It Dv security.bsd.see_jail_proc Setting this sysctl to zero disallows .Fn ptrace requests from processes belonging to a different jail than that of the target process, even if the requesting process' jail is an ancestor of the target process'. These requests will fail with error .Er ESRCH . .It Dv securelevel and init The .Xr init 1 process can only be traced with .Nm if securelevel is zero. .It Dv procctl(2) PROC_TRACE_CTL Process can deny attempts to trace itself with .Xr procctl 2 .Dv PROC_TRACE_CTL request. In this case requests return .Xr EPERM error. .El .Sh TRACING EVENTS .Pp Each traced process has a tracing event mask. An event in the traced process only reports a signal stop if the corresponding flag is set in the tracing event mask. The current set of tracing event flags include: .Bl -tag -width "Dv PTRACE_SYSCALL" .It Dv PTRACE_EXEC Report a stop for a successful invocation of .Xr execve 2 . This event is indicated by the .Dv PL_FLAG_EXEC flag in the .Va pl_flags member of .Vt "struct ptrace_lwpinfo" . .It Dv PTRACE_SCE Report a stop on each system call entry. This event is indicated by the .Dv PL_FLAG_SCE flag in the .Va pl_flags member of .Vt "struct ptrace_lwpinfo" . .It Dv PTRACE_SCX Report a stop on each system call exit. This event is indicated by the .Dv PL_FLAG_SCX flag in the .Va pl_flags member of .Vt "struct ptrace_lwpinfo" . .It Dv PTRACE_SYSCALL Report stops for both system call entry and exit. .It Dv PTRACE_FORK This event flag controls tracing for new child processes of a traced process. .Pp When this event flag is enabled, new child processes will enable tracing and stop before executing their first instruction. The new child process will include the .Dv PL_FLAG_CHILD flag in the .Va pl_flags member of .Vt "struct ptrace_lwpinfo" . The traced process will report a stop that includes the .Dv PL_FLAG_FORKED flag. The process ID of the new child process will also be present in the .Va pl_child_pid member of .Vt "struct ptrace_lwpinfo" . If the new child process was created via .Xr vfork 2 , the traced process's stop will also include the .Dv PL_FLAG_VFORKED flag. Note that new child processes will be attached with the default tracing event mask; they do not inherit the event mask of the traced process. .Pp When this event flag is not enabled, new child processes will execute without tracing enabled. .It Dv PTRACE_LWP This event flag controls tracing of LWP .Pq kernel thread creation and destruction. When this event is enabled, new LWPs will stop and report an event with .Dv PL_FLAG_BORN set before executing their first instruction, and exiting LWPs will stop and 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 Dv PTRACE_VFORK Report a stop event when a parent process resumes after a .Xr vfork 2 . .Pp When a thread in the traced process creates a new child process via .Xr vfork 2 , the stop that reports .Dv PL_FLAG_FORKED and .Dv PL_FLAG_SCX occurs just after the child process is created, but before the thread waits for the child process to stop sharing process memory. If a debugger is not tracing the new child process, it must ensure that no breakpoints are enabled in the shared process memory before detaching from the new child process. This means that no breakpoints are enabled in the parent process either. .Pp The .Dv PTRACE_VFORK flag enables a new stop that indicates when the new child process stops sharing the process memory of the parent process. A debugger can reinsert breakpoints in the parent process and resume it in response to this event. This event is indicated by setting the .Dv PL_FLAG_VFORK_DONE flag. .El .Pp The default tracing event mask when attaching to a process via .Dv PT_ATTACH , .Dv PT_TRACE_ME , or .Dv PTRACE_FORK includes only .Dv PTRACE_EXEC events. All other event flags are disabled. .Sh PTRACE REQUESTS .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 "Dv PT_GET_EVENT_MASK" .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 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 process to trace. In this case, .Fa pid specifies the process ID of the process to trace, 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_GETREGSET This request reads the registers from the traced process. The .Fa data argument specifies the register set to read, with the .Fa addr argument pointing at a .Vt "struct iovec" where the .Va iov_base field points to a register set specific structure to hold the registers, and the .Va iov_len field holds the length of the structure. .It Dv PT_SETREGSET This request writes to the registers of the traced process. The .Fa data argument specifies the register set to write to, with the .Fa addr argument pointing at a .Vt "struct iovec" where the .Va iov_base field points to a register set specific structure to hold the registers, and the .Va iov_len field holds the length of the structure. If .Va iov_base is NULL the kernel will return the expected length of the register set specific structure in the .Va iov_len field and not change the target register set. .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 Va pl_lwpid LWP id of the thread .It Va pl_event Event that caused the stop. Currently defined events are: .Bl -tag -width "Dv PL_EVENT_SIGNAL" -compact .It Dv PL_EVENT_NONE No reason given .It Dv PL_EVENT_SIGNAL Thread stopped due to the pending signal .El .It Va pl_flags Flags that specify additional details about observed stop. Currently defined flags are: .Bl -tag -width indent -compact .It Dv 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 Dv 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 Dv 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 Dv PL_FLAG_SI Indicates that .Va pl_siginfo member of .Vt "struct ptrace_lwpinfo" contains valid information. .It Dv 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 Dv PL_FLAG_CHILD The flag is set for first event reported from a new child which is automatically attached when .Dv PTRACE_FORK is enabled. .It Dv PL_FLAG_BORN This flag is set for the first event reported from a new LWP when .Dv PTRACE_LWP is enabled. It is reported along with .Dv PL_FLAG_SCX . .It Dv PL_FLAG_EXITED This flag is set for the last event reported by an exiting LWP when .Dv PTRACE_LWP is enabled. 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. .It Dv PL_FLAG_VFORKED Indicates that the thread is returning from a call to .Xr vfork 2 that created a new child process. This flag is set in addition to .Dv PL_FLAG_FORKED . .It Dv PL_FLAG_VFORK_DONE Indicates that the thread has resumed after a child process created via .Xr vfork 2 has stopped sharing its address space with the traced process. .El .It Va pl_sigmask The current signal mask of the LWP .It Va 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 Va 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 Va pl_tdname The name of the thread. .It Va 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 Va 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 Va 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 Dv PT_GETNUMLWPS This request returns the number of kernel threads associated with the traced process. .It Dv 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 Dv PT_SETSTEP This request will turn on single stepping of the specified process. Stepping is automatically disabled when a single step trap is caught. .It Dv PT_CLEARSTEP This request will turn off single stepping of the specified process. .It Dv PT_SUSPEND This request will suspend the specified thread. .It Dv PT_RESUME This request will resume the specified thread. .It Dv PT_TO_SCE This request will set the .Dv PTRACE_SCE event flag to trace all future system call entries and continue the process. The .Fa addr and .Fa data arguments are used the same as for .Dv PT_CONTINUE . .It Dv PT_TO_SCX This request will set the .Dv PTRACE_SCX event flag to trace all future system call exits and continue the process. The .Fa addr and .Fa data arguments are used the same as for .Dv PT_CONTINUE . .It Dv PT_SYSCALL This request will set the .Dv PTRACE_SYSCALL event flag to trace all future system call entries and exits and continue the process. The .Fa addr and .Fa data arguments are used the same as for .Dv PT_CONTINUE . .It Dv PT_GET_SC_ARGS For the thread which is stopped in either .Dv PL_FLAG_SCE or .Dv PL_FLAG_SCX state, that is, on entry or exit to a syscall, this request fetches the syscall arguments. .Pp The arguments are copied out into the buffer pointed to by the .Fa addr pointer, sequentially. Each syscall argument is stored as the machine word. Kernel copies out as many arguments as the syscall accepts, see the .Va pl_syscall_narg member of the .Vt struct ptrace_lwpinfo , but not more than the .Fa data bytes in total are copied. .It Dv PT_GET_SC_RET Fetch the system call return values on exit from a syscall. This request is only valid for threads stopped in a syscall exit (the .Dv PL_FLAG_SCX state). The .Fa addr argument specifies a pointer to a .Vt "struct ptrace_sc_ret" , which is defined as follows: .Bd -literal struct ptrace_sc_ret { register_t sr_retval[2]; int sr_error; }; .Ed .Pp The .Fa data argument is set to the size of the structure. .Pp If the system call completed successfully, .Va sr_error is set to zero and the return values of the system call are saved in .Va sr_retval . If the system call failed to execute, .Va sr_error field is set to a positive .Xr errno 2 value. If the system call completed in an unusual fashion, .Va sr_error is set to a negative value: -.Bl -tag -width Dv EJUSTRETURN -compact +.Bl -tag -width EJUSTRETURN -compact .It Dv ERESTART System call will be restarted. .It Dv EJUSTRETURN System call completed sucessfully but did not set a return value .Po for example, .Xr setcontext 2 and .Xr sigreturn 2 .Pc . .El .It Dv PT_FOLLOW_FORK This request controls tracing for new child processes of a traced process. If .Fa data is non-zero, .Dv PTRACE_FORK is set in the traced process's event tracing mask. If .Fa data is zero, .Dv PTRACE_FORK is cleared from the traced process's event tracing mask. .It Dv PT_LWP_EVENTS This request controls tracing of LWP creation and destruction. If .Fa data is non-zero, .Dv PTRACE_LWP is set in the traced process's event tracing mask. If .Fa data is zero, .Dv PTRACE_LWP is cleared from the traced process's event tracing mask. .It Dv PT_GET_EVENT_MASK This request reads the traced process's event tracing mask into the integer pointed to by .Fa addr . The size of the integer must be passed in .Fa data . .It Dv PT_SET_EVENT_MASK This request sets the traced process's event tracing mask from the integer pointed to by .Fa addr . The size of the integer must be passed in .Fa data . .It Dv 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 Dv 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. .It Dv PT_COREDUMP This request creates a coredump for the stopped program. The .Fa addr argument specifies a pointer to a .Vt "struct ptrace_coredump" , which is defined as follows: .Bd -literal struct ptrace_coredump { int pc_fd; uint32_t pc_flags; off_t pc_limit; }; .Ed The fields of the structure are: .Bl -tag -width pc_flags .It Dv pc_fd File descriptor to write the dump to. It must refer to a regular file, opened for writing. .It Dv pc_flags Flags. The following flags are defined: .Bl -tag -width PC_COMPRESS .It Dv PC_COMPRESS Request compression of the dump. .It Dv PC_ALL Include non-dumpable entries into the dump. The dumper ignores .Dv MAP_NOCORE flag of the process map entry, but device mappings are not dumped even with .Dv PC_ALL set. .El .It Dv pc_limit Maximum size of the coredump. Specify zero for no limit. .El .Pp The size of .Vt "struct ptrace_coredump" must be passed in .Fa data . .It Dv PT_SC_REMOTE Request to execute a syscall in the context of the traced process, in the specified thread. The .Fa addr argument must point to the .Vt "struct ptrace_sc_remote" , which describes the requested syscall and its arguments, and receives the result. The size of .Vt "struct ptrace_sc_remote" must be passed in .Fa data. .Bd -literal struct ptrace_sc_remote { struct ptrace_sc_ret pscr_ret; u_int pscr_syscall; u_int pscr_nargs; u_long *pscr_args; }; .Ed The .Dv pscr_syscall contains the syscall number to execute, the .Dv pscr_nargs is the number of supplied arguments, which are supplied in the .Dv pscr_args array. Result of the execution is returned in the .Dv pscr_ret member. Note that the request and its result do not affect the returned value from the currently executed syscall, if any. .El .Sh PT_COREDUMP and PT_SC_REMOTE usage The process must be stopped before dumping or initiating a remote system call. A single thread in the target process is temporarily unsuspended in the kernel to perform the action. If the .Nm call fails before a thread is unsuspended, there is no event to .Xr waitpid 2 for. If a thread was unsuspended, it will stop again before the .Nm call returns, and the process must be waited upon using .Xr waitpid 2 to consume the new stop event. Since it is hard to deduce whether a thread was unsuspended before an error occurred, it is recommended to unconditionally perform .Xr waitpid 2 with .Dv WNOHANG flag after .Dv PT_COREDUMP and .Dv PT_SC_REMOTE , and silently accept zero result from it. .Pp For .Dv PT_SC_REMOTE , the selected thread must be stopped in the safe place, which is currently defined as a syscall exit, or a return from kernel to user mode (basically, a signal handler call place). Kernel returns .Er EBUSY status if attempt is made to execute remote syscall at unsafe stop. .Pp Note that neither .Dv kern.trap_enotcap sysctl setting, nor the corresponding .Xr procctl 2 flag .Dv PROC_TRAPCAP_CTL_ENABLE are obeyed during the execution of the syscall by .Dv PT_SC_REMOTE . In other words, .Dv SIGTRAP signal is not sent to a process executing in capability mode, which violated a mode access restriction. .Pp Note that due to the mode of execution for the remote syscall, in particular, the setting where only one thread is allowed to run, the syscall might block on resources owned by suspended threads. This might result in the target process deadlock. In this situation, the only way out is to kill the target. .Sh ARM MACHINE-SPECIFIC REQUESTS .Bl -tag -width "Dv PT_SETVFPREGS" .It Dv PT_GETVFPREGS Return the thread's .Dv VFP machine state in the buffer pointed to by .Fa addr . .Pp The .Fa data argument is ignored. .It Dv PT_SETVFPREGS Set the thread's .Dv VFP machine state from the buffer pointed to by .Fa addr . .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. .It Dv PT_GETVSRREGS Return doubleword 1 of the thread's .Dv VSX registers VSR0-VSR31 in the buffer pointed to by .Fa addr . .Pp The .Fa data argument is ignored. .It Dv PT_SETVSRREGS Set doubleword 1 of the thread's .Dv VSX registers VSR0-VSR31 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 Most requests return 0 on success and \-1 on error. Some requests can cause .Fn ptrace to return \-1 as a non-error value, among them are .Dv PT_READ_I and .Dv PT_READ_D , which return the value read from the process memory on success. To disambiguate, .Va errno can be set to 0 before the call and checked afterwards. .Pp The current .Fn ptrace implementation always sets .Va errno to 0 before calling into the kernel, both for historic reasons and for consistency with other operating systems. It is recommended to assign zero to .Va errno explicitly for forward compatibility. .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 ENOMEM .Bl -bullet -compact .It A .Dv PT_READ_I, .Dv PT_READ_D, .Dv PT_WRITE_I, or .Dv PT_WRITE_D request attempted to access an invalid address, or a memory allocation failure occurred when accessing process memory. .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 v6 . diff --git a/lib/libc/sys/swapon.2 b/lib/libc/sys/swapon.2 index c0c12d9dde68..8cfac8ce1f64 100644 --- a/lib/libc/sys/swapon.2 +++ b/lib/libc/sys/swapon.2 @@ -1,161 +1,162 @@ .\" Copyright (c) 1980, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)swapon.2 8.1 (Berkeley) 6/4/93 .\" .Dd December 8, 2021 .Dt SWAPON 2 .Os .Sh NAME .Nm swapon , swapoff .Nd control devices for interleaved paging/swapping .Sh LIBRARY .Lb libc .Sh SYNOPSIS -.It vm/vm_param.h -.It vm/swap_pager.h +.In vm/vm_param.h +.In vm/swap_pager.h +.Pp .In unistd.h .Ft int .Fn swapon "const char *special" .Ft int .Fn swapoff "const char *special" "u_int flags" .Sh DESCRIPTION The .Fn swapon system call makes the block device .Fa special available to the system for allocation for paging and swapping. The names of potentially available devices are known to the system and defined at system configuration time. The size of the swap area on .Fa special is calculated at the time the device is first made available for swapping. .Pp The .Fn swapoff system call disables paging and swapping on the given device. All associated swap metadata are deallocated, and the device is made available for other purposes. .Pp The .Fa special argument points to the name of the device or file used for swapping. .The .Va flags argument takes the following flags: .Bl -tag -width SWAPOFF_FORCE .It Dv SWAPOFF_FORCE Overrides a very conservative check that prevents swapoff if the total amount of free memory and remaining swap devices space might be unsufficient for the system to continue operating. .El .Sh RETURN VALUES If an error has occurred, a value of -1 is returned and .Va errno is set to indicate the error. .Sh ERRORS Both .Fn swapon and .Fn swapoff can fail if: .Bl -tag -width Er .It Bq Er ENOTDIR A component of the path prefix is not a directory. .It Bq Er ENAMETOOLONG A component of a pathname exceeded 255 characters, or an entire path name exceeded 1023 characters. .It Bq Er ENOENT The named device does not exist. .It Bq Er EACCES Search permission is denied for a component of the path prefix. .It Bq Er ELOOP Too many symbolic links were encountered in translating the pathname. .It Bq Er EPERM The caller is not the super-user. .It Bq Er EFAULT The .Fa special argument points outside the process's allocated address space. .El .Pp Additionally, .Fn swapon can fail for the following reasons: .Bl -tag -width Er .It Bq Er ENOTBLK The .Fa special argument is not a block device. .It Bq Er EBUSY The device specified by .Fa special has already been made available for swapping .It Bq Er ENXIO The major device number of .Fa special is out of range (this indicates no device driver exists for the associated hardware). .It Bq Er EIO An I/O error occurred while opening the swap device. .It Bq Er EINTEGRITY Corrupted data was detected while reading from the file system to open the swap device. .El .Pp Lastly, .Fn swapoff can fail if: .Bl -tag -width Er .It Bq Er EINVAL The system is not currently swapping to .Fa special . .It Bq Er ENOMEM Not enough virtual memory is available to safely disable paging and swapping to the given device. .El .Sh SEE ALSO .Xr config 8 , .Xr swapon 8 , .Xr sysctl 8 .Sh HISTORY The .Fn swapon system call appeared in .Bx 4.0 . The .Fn swapoff system call appeared in .Fx 5.1 .