diff options
Diffstat (limited to 'share/man/man4/procfs.4')
-rw-r--r-- | share/man/man4/procfs.4 | 308 |
1 files changed, 308 insertions, 0 deletions
diff --git a/share/man/man4/procfs.4 b/share/man/man4/procfs.4 new file mode 100644 index 000000000000..64dd3100e6bc --- /dev/null +++ b/share/man/man4/procfs.4 @@ -0,0 +1,308 @@ +.\" Written by Garrett Wollman +.\" This file is in the public domain. +.\" +.Dd April 10, 2023 +.Dt PROCFS 4 +.Os +.Sh NAME +.Nm procfs +.Nd process file system +.Sh SYNOPSIS +.Bd -literal +proc /proc procfs rw 0 0 +.Ed +.Sh DESCRIPTION +.Bf -symbolic +This functionality is deprecated. +Users are advised to use +.Xr libprocstat 3 +and +.Xr kvm 3 +instead. +.Ef +.Pp +The process file system, or +.Nm , +implements a view of the system process table inside the file system. +It is normally mounted on +.Pa /proc . +.Pp +The +.Nm +provides a two-level view of process space, unlike the previous +.Fx 1.1 +.Nm +implementation. +At the highest level, processes themselves are named, according to +their process ids in decimal, with no leading zeros. +There is also a +special node called +.Pa curproc +which always refers to the process making the lookup request. +.Pp +Each node is a directory which contains the following entries: +.Bl -tag -width status +.It Pa dbregs +The debug registers as defined by +.Dv "struct dbregs" +in +.In machine/reg.h . +.Pa dbregs +is currently only implemented on the i386 architecture. +.It Pa etype +The type of the executable referenced by the +.Pa file +entry. +.It Pa file +A symbolic link to the file from which the process text was read. +This can be used to gain access to the process' symbol table, +or to start another copy of the process. +If the file cannot be found, the link target is +.Ql unknown . +.It Pa fpregs +The floating point registers as defined by +.Dv "struct fpregs" +in +.In machine/reg.h . +.Pa fpregs +is only implemented on machines which have distinct general +purpose and floating point register sets. +.It Pa map +A collection of lines describing the memory regions of the process, +where each line contains the following fields: +.Bl -tag -compact -width private-resident +.It start-address +The starting address for the region (inclusive). +.It end-address +The ending address for the region (exclusive). +.It resident +The number of resident pages. +.It private-resident +The number of resident pages that were private to the process. +.It obj +The virtual address of the +.Vt struct vm_object +kernel data structure describing the memory region. +.It access +A three character string comprising the characters +.Sq r , +.Sq w +and +.Sq x , +denoting read, write, and execute permissions respectively. +The lack of a permission is represented by +.Sq - . +.It ref_count +The number of references to the region. +.It shadow_count +The number of VM objects that this region is a shadow for. +.It flags +The flags for the object, see the flags named +.Sy OBJ_* +in +.In vm/vm_object.h . +.It copy-on-write +Whether the region is copy-on-write. +One of: +.Bl -tag -compact -width NCOW +.It COW +A copy-on-write region. +.It NCOW +A non-copy-on-write region. +.El +.It needs-copy +Whether the region needs a copy. +One of: +.Bl -tag -compact -width NNC +.It NC +The region needs a copy. +.It NNC +The region does not need a copy. +.El +.It type +The type of the region. +One of: +.Bl -tag -compact -width unknown +.It dead +A region associated with a dead VM object. +.It device +A region backed by device memory. +.It none +A region not backed by anything. +.It phys +A region backed by physical memory. +.It swap +A region backed by swap. +.It unknown +A region of unknown type. +.It vnode +A region backed by a file. +.El +.It fullpath +The path to the file backing the memory region, or +.Sq - +if there is no such file. +.It cred +One of: +.Bl -tag -compact -width NCH +.It CH +The region is being charged to the user specified in the +.Sq charged-uid +field. +.It NCH +The region is not being charged to any user. +.El +.It charged-uid +The UID of the user being charged, or -1 if no user is being charged. +.El +.It Pa mem +The complete virtual memory image of the process. +Only those address which exist in the process can be accessed. +Reads and writes to this file modify the process. +Writes to the text segment remain private to the process. +.It Pa note +Used for sending signals to the process. +Not implemented. +.It Pa notepg +Used for sending signal to the process group. +Not implemented. +.It Pa osrel +Allows read and write of the kernel osrel value assigned to the process. +It affects the compatibility shims that are turned on and off +depending on the value. +Initial process value is read from the ABI note tag in the executed ELF image, +and is zero if the tag not supported by binary format or was not found. +.It Pa regs +Allows read and write access to the process' register set. +This file contains a binary data structure +.Dv "struct regs" +defined in +.In machine/reg.h . +.Pa regs +can only be written when the process is stopped. +.It Pa rlimit +This is a read-only file containing the process current and maximum +limits. +Each line is of the format +.Ar rlimit current max , +with -1 +indicating infinity. +.It Pa status +The process status. +This file is read-only and returns a single line containing +multiple space-separated fields as follows: +.Pp +.Bl -bullet -compact +.It +command name +.It +process id +.It +parent process id +.It +process group id +.It +session id +.It +device name +of the controlling terminal, or +a minus sign +.Pq Dq - +if there is no controlling terminal. +.It +a list of process flags: +.Dv ctty +if there is a controlling terminal, +.Dv sldr +if the process is a session leader, +.Dv noflags +if neither of the other two flags are set. +.It +the process start time in seconds and microseconds, +comma separated. +.It +the user time in seconds and microseconds, +comma separated. +.It +the system time in seconds and microseconds, +comma separated. +.It +the wait channel message +.It +the process credentials consisting of +the effective user id +and the list of groups (whose first member +is the effective group id) +all comma separated. +.It +the hostname of the jail in which the process runs, or +.Ql - +to indicate that the process is not running within a jail. +.El +.El +.Pp +Each node is owned by the process's user, and belongs to that user's +primary group. +.Sh FILES +.Bl -tag -width /proc/curproc/XXXXXXX -compact +.It Pa /proc +normal mount point for the +.Nm . +.It Pa /proc/pid +directory containing process information for process +.Pa pid . +.It Pa /proc/curproc +directory containing process information for the current process +.It Pa /proc/self +directory containing process information for the current process +.It Pa /proc/curproc/cmdline +the process executable name +.It Pa /proc/curproc/etype +executable type +.It Pa /proc/curproc/exe +executable image +.It Pa /proc/curproc/file +executable image +.It Pa /proc/curproc/fpregs +the process floating point register set +.It Pa /proc/curproc/map +virtual memory map of the process +.It Pa /proc/curproc/mem +the complete virtual address space of the process +.It Pa /proc/curproc/note +used for signaling the process +.It Pa /proc/curproc/notepg +used for signaling the process group +.It Pa /proc/curproc/osrel +the process osrel value +.It Pa /proc/curproc/regs +the process register set +.It Pa /proc/curproc/rlimit +the process current and maximum rlimit +.It Pa /proc/curproc/status +the process' current status +.El +.Sh EXAMPLES +To mount a +.Nm +file system on +.Pa /proc : +.Pp +.Dl "mount -t procfs proc /proc" +.Sh SEE ALSO +.Xr procstat 1 , +.Xr mount 2 , +.Xr sigaction 2 , +.Xr unmount 2 , +.Xr kvm 3 , +.Xr libprocstat 3 , +.Xr pseudofs 9 +.Sh AUTHORS +.An -nosplit +This manual page written by +.An Garrett Wollman , +based on the description +provided by +.An Jan-Simon Pendry , +and revamped later by +.An Mike Pritchard . |