share/man/man5/procfs.5

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