share/man/man5/procfs.5

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