share/man/man5/procfs.5

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