share/man/man5/procfs.5

   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
  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 .Ar major , Ns Ar minor
 159 of the controlling terminal, or
 160 .Dv -1,-1
 161 if there is no controlling terminal.
 162 .It
 163 a list of process flags:
 164 .Dv ctty
 165 if there is a controlling terminal,
 166 .Dv sldr
 167 if the process is a session leader,
 168 .Dv noflags
 169 if neither of the other two flags are set.
 170 .It
 171 the process start time in seconds and microseconds,
 172 comma separated.
 173 .It
 174 the user time in seconds and microseconds,
 175 comma separated.
 176 .It
 177 the system time in seconds and microseconds,
 178 comma separated.
 179 .It
 180 the wait channel message
 181 .It
 182 the process credentials consisting of
 183 the effective user id
 184 and the list of groups (whose first member
 185 is the effective group id)
 186 all comma separated.
 187 .It
 188 the hostname of the jail in which the process runs, or
 189 .Ql -
 190 to indicate that the process is not running within a jail.
 191 .El
 192 .El
 193 .Pp
 194 In a normal debugging environment,
 195 where the target is fork/exec'd by the debugger,
 196 the debugger should fork and the child should stop
 197 itself (with a self-inflicted
 198 .Dv SIGSTOP
 199 for example).
 200 The parent should issue a
 201 .Dv wait
 202 and then an
 203 .Dv attach
 204 command via the appropriate
 205 .Pa ctl
 206 file.
 207 The child process will receive a
 208 .Dv SIGTRAP
 209 immediately after the call to exec (see
 210 .Xr execve 2 ) .
 211 .Pp
 212 Each node is owned by the process's user, and belongs to that user's
 213 primary group, except for the
 214 .Pa mem
 215 node, which belongs to the
 216 .Li kmem
 217 group.
 218 .Sh FILES
 219 .Bl -tag -width /proc/curproc/XXXXXXX -compact
 220 .It Pa /proc
 221 normal mount point for the
 222 .Nm .
 223 .It Pa /proc/pid
 224 directory containing process information for process
 225 .Pa pid .
 226 .It Pa /proc/curproc
 227 directory containing process information for the current process
 228 .It Pa /proc/curproc/cmdline
 229 the process executable name
 230 .It Pa /proc/curproc/ctl
 231 used to send control messages to the process
 232 .It Pa /proc/curproc/etype
 233 executable type
 234 .It Pa /proc/curproc/file
 235 executable image
 236 .It Pa /proc/curproc/fpregs
 237 the process floating point register set
 238 .It Pa /proc/curproc/map
 239 virtual memory map of the process
 240 .It Pa /proc/curproc/mem
 241 the complete virtual address space of the process
 242 .It Pa /proc/curproc/note
 243 used for signaling the process
 244 .It Pa /proc/curproc/notepg
 245 used for signaling the process group
 246 .It Pa /proc/curproc/osrel
 247 the process osrel value
 248 .It Pa /proc/curproc/regs
 249 the process register set
 250 .It Pa /proc/curproc/rlimit
 251 the process current and maximum rlimit
 252 .It Pa /proc/curproc/status
 253 the process' current status
 254 .El
 255 .Sh EXAMPLES
 256 To mount a
 257 .Nm
 258 file 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
 271 This manual page written by
 272 .An Garrett Wollman ,
 273 based on the description
 274 provided by
 275 .An Jan-Simon Pendry ,
 276 and revamped later by
 277 .An Mike Pritchard .