1.\" $FreeBSD$ 2.\" Written by Garrett Wollman 3.\" This file is in the public domain. 4.\" 5.Dd September 22, 2009 6.Dt PROCFS 5 7.Os 8.Sh NAME 9.Nm procfs 10.Nd process file system 11.Sh SYNOPSIS 12.Bd -literal 13proc /proc procfs rw 0 0 14.Ed 15.Sh DESCRIPTION 16The process file system, or 17.Nm , 18implements a view of the system process table inside the file system. 19It is normally mounted on 20.Pa /proc , 21and is required for the complete operation of programs such as 22.Xr ps 1 23and 24.Xr w 1 . 25.Pp 26The 27.Nm 28provides a two-level view of process space, unlike the previous 29.Fx 1.1 30.Nm 31implementation. 32At the highest level, processes themselves are named, according to 33their process ids in decimal, with no leading zeros. 34There is also a 35special node called 36.Pa curproc 37which always refers to the process making the lookup request. 38.Pp 39Each node is a directory which contains the following entries: 40.Pp 41Each directory contains several files: 42.Bl -tag -width status 43.It Pa ctl 44a write-only file which supports a variety 45of control operations. 46Control commands are written as strings to the 47.Pa ctl 48file. 49The control commands are: 50.Bl -tag -width detach -compact 51.It attach 52stops the target process and arranges for the sending 53process to become the debug control process. 54.It detach 55continue execution of the target process and 56remove it from control by the debug process (which 57need not be the sending process). 58.It run 59continue running the target process until 60a signal is delivered, a breakpoint is hit, or the 61target process exits. 62.It step 63single step the target process, with no signal delivery. 64.It wait 65wait for the target process to come to a steady 66state ready for debugging. 67The target process must be in this state before 68any of the other commands are allowed. 69.El 70.Pp 71The string can also be the name of a signal, lower case 72and without the 73.Dv SIG 74prefix, 75in which case that signal is delivered to the process 76(see 77.Xr sigaction 2 ) . 78.Pp 79The 80.Xr procctl 8 81utility can be used to clear tracepoints in a stuck process. 82.It Pa dbregs 83The debug registers as defined by 84.Dv "struct dbregs" 85in 86.In machine/reg.h . 87.Pa dbregs 88is currently only implemented on the i386 architecture. 89.It Pa etype 90The type of the executable referenced by the 91.Pa file 92entry. 93.It Pa file 94A symbolic link to the file from which the process text was read. 95This can be used to gain access to the process' symbol table, 96or to start another copy of the process. 97If the file cannot be found, the link target is 98.Ql unknown . 99.It Pa fpregs 100The floating point registers as defined by 101.Dv "struct fpregs" 102in 103.In machine/reg.h . 104.Pa fpregs 105is only implemented on machines which have distinct general 106purpose and floating point register sets. 107.It Pa map 108A map of the process' virtual memory. 109.It Pa mem 110The complete virtual memory image of the process. 111Only those address which exist in the process can be accessed. 112Reads and writes to this file modify the process. 113Writes to the text segment remain private to the process. 114.It Pa note 115Used for sending signals to the process. 116Not implemented. 117.It Pa notepg 118Used for sending signal to the process group. 119Not implemented. 120.It Pa osrel 121Allows read and write of the kernel osrel value assigned to the process. 122It affects the compatibility shims that are turned on and off 123depending on the value. 124Initial process value is read from the ABI note tag in the executed ELF image, 125and is zero if the tag not supported by binary format or was not found. 126.It Pa regs 127Allows read and write access to the process' register set. 128This file contains a binary data structure 129.Dv "struct regs" 130defined in 131.In machine/reg.h . 132.Pa regs 133can only be written when the process is stopped. 134.It Pa rlimit 135This is a read-only file containing the process current and maximum 136limits. 137Each line is of the format 138.Ar rlimit current max , 139with -1 140indicating infinity. 141.It Pa status 142The process status. 143This file is read-only and returns a single line containing 144multiple space-separated fields as follows: 145.Pp 146.Bl -bullet -compact 147.It 148command name 149.It 150process id 151.It 152parent process id 153.It 154process group id 155.It 156session id 157.It 158.Ar major , Ns Ar minor 159of the controlling terminal, or 160.Dv -1,-1 161if there is no controlling terminal. 162.It 163a list of process flags: 164.Dv ctty 165if there is a controlling terminal, 166.Dv sldr 167if the process is a session leader, 168.Dv noflags 169if neither of the other two flags are set. 170.It 171the process start time in seconds and microseconds, 172comma separated. 173.It 174the user time in seconds and microseconds, 175comma separated. 176.It 177the system time in seconds and microseconds, 178comma separated. 179.It 180the wait channel message 181.It 182the process credentials consisting of 183the effective user id 184and the list of groups (whose first member 185is the effective group id) 186all comma separated. 187.It 188the hostname of the jail in which the process runs, or 189.Ql - 190to indicate that the process is not running within a jail. 191.El 192.El 193.Pp 194In a normal debugging environment, 195where the target is fork/exec'd by the debugger, 196the debugger should fork and the child should stop 197itself (with a self-inflicted 198.Dv SIGSTOP 199for example). 200The parent should issue a 201.Dv wait 202and then an 203.Dv attach 204command via the appropriate 205.Pa ctl 206file. 207The child process will receive a 208.Dv SIGTRAP 209immediately after the call to exec (see 210.Xr execve 2 ) . 211.Pp 212Each node is owned by the process's user, and belongs to that user's 213primary group, except for the 214.Pa mem 215node, which belongs to the 216.Li kmem 217group. 218.Sh FILES 219.Bl -tag -width /proc/curproc/XXXXXXX -compact 220.It Pa /proc 221normal mount point for the 222.Nm . 223.It Pa /proc/pid 224directory containing process information for process 225.Pa pid . 226.It Pa /proc/curproc 227directory containing process information for the current process 228.It Pa /proc/curproc/cmdline 229the process executable name 230.It Pa /proc/curproc/ctl 231used to send control messages to the process 232.It Pa /proc/curproc/etype 233executable type 234.It Pa /proc/curproc/file 235executable image 236.It Pa /proc/curproc/fpregs 237the process floating point register set 238.It Pa /proc/curproc/map 239virtual memory map of the process 240.It Pa /proc/curproc/mem 241the complete virtual address space of the process 242.It Pa /proc/curproc/note 243used for signaling the process 244.It Pa /proc/curproc/notepg 245used for signaling the process group 246.It Pa /proc/curproc/osrel 247the process osrel value 248.It Pa /proc/curproc/regs 249the process register set 250.It Pa /proc/curproc/rlimit 251the process current and maximum rlimit 252.It Pa /proc/curproc/status 253the process' current status 254.El 255.Sh EXAMPLES 256To mount a 257.Nm 258file system on 259.Pa /proc : 260.Pp 261.Dl "mount -t procfs proc /proc" 262.Sh SEE ALSO 263.Xr procstat 1 , 264.Xr mount 2 , 265.Xr sigaction 2 , 266.Xr unmount 2 , 267.Xr procctl 8 , 268.Xr pseudofs 9 269.Sh AUTHORS 270.An -nosplit 271This manual page written by 272.An Garrett Wollman , 273based on the description 274provided by 275.An Jan-Simon Pendry , 276and revamped later by 277.An Mike Pritchard . 278