share/man/man5/procfs.5

   1 .\" $FreeBSD$
   2 .\" Written by Garrett Wollman
   3 .\" This file is in the public domain.
   4 .\"
   5 .Dd September 3, 2004
   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 regs
 121 Allows read and write access to the process' register set.
 122 This file contains a binary data structure
 123 .Dv "struct regs"
 124 defined in
 125 .In machine/reg.h .
 126 .Pa regs
 127 can only be written when the process is stopped.
 128 .It Pa rlimit
 129 This is a read-only file containing the process current and maximum
 130 limits.
 131 Each line is of the format
 132 .Ar rlimit current max ,
 133 with -1
 134 indicating infinity.
 135 .It Pa status
 136 The process status.
 137 This file is read-only and returns a single line containing
 138 multiple space-separated fields as follows:
 139 .Pp
 140 .Bl -bullet -compact
 141 .It
 142 command name
 143 .It
 144 process id
 145 .It
 146 parent process id
 147 .It
 148 process group id
 149 .It
 150 session id
 151 .It
 152 .Ar major , Ns Ar minor
 153 of the controlling terminal, or
 154 .Dv -1,-1
 155 if there is no controlling terminal.
 156 .It
 157 a list of process flags:
 158 .Dv ctty
 159 if there is a controlling terminal,
 160 .Dv sldr
 161 if the process is a session leader,
 162 .Dv noflags
 163 if neither of the other two flags are set.
 164 .It
 165 the process start time in seconds and microseconds,
 166 comma separated.
 167 .It
 168 the user time in seconds and microseconds,
 169 comma separated.
 170 .It
 171 the system time in seconds and microseconds,
 172 comma separated.
 173 .It
 174 the wait channel message
 175 .It
 176 the process credentials consisting of
 177 the effective user id
 178 and the list of groups (whose first member
 179 is the effective group id)
 180 all comma separated.
 181 .It
 182 the hostname of the jail in which the process runs, or
 183 .Ql -
 184 to indicate that the process is not running within a jail.
 185 .El
 186 .El
 187 .Pp
 188 In a normal debugging environment,
 189 where the target is fork/exec'd by the debugger,
 190 the debugger should fork and the child should stop
 191 itself (with a self-inflicted
 192 .Dv SIGSTOP
 193 for example).
 194 The parent should issue a
 195 .Dv wait
 196 and then an
 197 .Dv attach
 198 command via the appropriate
 199 .Pa ctl
 200 file.
 201 The child process will receive a
 202 .Dv SIGTRAP
 203 immediately after the call to exec (see
 204 .Xr execve 2 ) .
 205 .Pp
 206 Each node is owned by the process's user, and belongs to that user's
 207 primary group, except for the
 208 .Pa mem
 209 node, which belongs to the
 210 .Li kmem
 211 group.
 212 .Sh FILES
 213 .Bl -tag -width /proc/curproc/XXXXXXX -compact
 214 .It Pa /proc
 215 normal mount point for the
 216 .Nm .
 217 .It Pa /proc/pid
 218 directory containing process information for process
 219 .Pa pid .
 220 .It Pa /proc/curproc
 221 directory containing process information for the current process
 222 .It Pa /proc/curproc/cmdline
 223 the process executable name
 224 .It Pa /proc/curproc/ctl
 225 used to send control messages to the process
 226 .It Pa /proc/curproc/etype
 227 executable type
 228 .It Pa /proc/curproc/file
 229 executable image
 230 .It Pa /proc/curproc/fpregs
 231 the process floating point register set
 232 .It Pa /proc/curproc/map
 233 virtual memory map of the process
 234 .It Pa /proc/curproc/mem
 235 the complete virtual address space of the process
 236 .It Pa /proc/curproc/note
 237 used for signaling the process
 238 .It Pa /proc/curproc/notepg
 239 used for signaling the process group
 240 .It Pa /proc/curproc/regs
 241 the process register set
 242 .It Pa /proc/curproc/rlimit
 243 the process current and maximum rlimit
 244 .It Pa /proc/curproc/status
 245 the process' current status
 246 .El
 247 .Sh EXAMPLES
 248 To mount a
 249 .Nm
 250 file system on
 251 .Pa /proc :
 252 .Pp
 253 .Dl "mount -t procfs proc /proc"
 254 .Sh SEE ALSO
 255 .Xr mount 2 ,
 256 .Xr sigaction 2 ,
 257 .Xr unmount 2 ,
 258 .Xr procctl 8 ,
 259 .Xr pseudofs 9
 260 .Sh AUTHORS
 261 .An -nosplit
 262 This manual page written by
 263 .An Garrett Wollman ,
 264 based on the description
 265 provided by
 266 .An Jan-Simon Pendry ,
 267 and revamped later by
 268 .An Mike Pritchard .