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 August 10, 1994
   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 .Pa <machine/reg.h> .
  82 .Pa dbregs
  83 is currently only implemented on the i386 architecture.
  84 .It Pa etype
  85 The type of the executable referenced by the
  86 .Pa file
  87 entry.
  88 .It Pa file
  89 A reference to the vnode from which the process text was read.
  90 This can be used to gain access to the process' symbol table,
  91 or to start another copy of the process.
  92 .It Pa fpregs
  93 The floating point registers as defined by
  94 .Dv "struct fpregs"
  95 in
  96 .Pa <machine/reg.h> .
  97 .Pa fpregs
  98 is only implemented on machines which have distinct general
  99 purpose and floating point register sets.
 100 .It Pa map
 101 A map of the process' virtual memory.
 102 .It Pa mem
 103 The complete virtual memory image of the process.
 104 Only those address which exist in the process can be accessed.
 105 Reads and writes to this file modify the process.
 106 Writes to the text segment remain private to the process.
 107 .It Pa note
 108 Used for sending signals to the process.  Not implemented.
 109 .It Pa notepg
 110 Used for sending signal to the process group.  Not implemented.
 111 .It Pa regs
 112 Allows read and write access to the process' register set.
 113 This file contains a binary data structure
 114 .Dv "struct regs"
 115 defined in
 116 .Pa <machine/reg.h> .
 117 .Pa regs
 118 can only be written when the process is stopped.
 119 .It Pa rlimit
 120 This is a read-only file containing the process current and maximum
 121 limits.
 122 Each line is of the format
 123 .Ar rlimit current max ,
 124 with -1
 125 indicating infinity.
 126 .It Pa status
 127 The process status.
 128 This file is read-only and returns a single line containing
 129 multiple space-separated fields as follows:
 130 .Pp
 131 .Bl -bullet -compact
 132 .It
 133 command name
 134 .It
 135 process id
 136 .It
 137 parent process id
 138 .It
 139 process group id
 140 .It
 141 session id
 142 .It
 143 .Ar major , Ns Ar minor
 144 of the controlling terminal, or
 145 .Dv -1,-1
 146 if there is no controlling terminal.
 147 .It
 148 a list of process flags:
 149 .Dv ctty
 150 if there is a controlling terminal,
 151 .Dv sldr
 152 if the process is a session leader,
 153 .Dv noflags
 154 if neither of the other two flags are set.
 155 .It
 156 the process start time in seconds and microseconds,
 157 comma separated.
 158 .It
 159 the user time in seconds and microseconds,
 160 comma separated.
 161 .It
 162 the system time in seconds and microseconds,
 163 comma separated.
 164 .It
 165 the wait channel message
 166 .It
 167 the process credentials consisting of
 168 the effective user id
 169 and the list of groups (whose first member
 170 is the effective group id)
 171 all comma separated.
 172 .El
 173 .El
 174 .Pp
 175 In a normal debugging environment,
 176 where the target is fork/exec'd by the debugger,
 177 the debugger should fork and the child should stop
 178 itself (with a self-inflicted
 179 .Dv SIGSTOP
 180 for example).
 181 The parent should issue a
 182 .Dv wait
 183 and then an
 184 .Dv attach
 185 command via the appropriate
 186 .Pa ctl
 187 file.
 188 The child process will receive a
 189 .Dv SIGTRAP
 190 immediately after the call to exec (see
 191 .Xr execve 2 ) .
 192 .Pp
 193 Each node is owned by the process's user, and belongs to that user's
 194 primary group, except for the
 195 .Pa mem
 196 node, which belongs to the
 197 .Li kmem
 198 group.
 199 .Sh FILES
 200 .Bl -tag -width /proc/curproc/XXXXXXX -compact
 201 .It Pa /proc
 202 normal mount point for the
 203 .Nm .
 204 .It Pa /proc/pid
 205 directory containing process information for process
 206 .Pa pid .
 207 .It Pa /proc/curproc
 208 directory containing process information for the current process
 209 .It Pa /proc/curproc/cmdline
 210 the process executable name
 211 .It Pa /proc/curproc/ctl
 212 used to send control messages to the process
 213 .It Pa /proc/curproc/etype
 214 executable type
 215 .It Pa /proc/curproc/file
 216 executable image
 217 .It Pa /proc/curproc/fpregs
 218 the process floating point register set
 219 .It Pa /proc/curproc/map
 220 virtual memory map of the process
 221 .It Pa /proc/curproc/mem
 222 the complete virtual address space of the process
 223 .It Pa /proc/curproc/note
 224 used for signaling the process
 225 .It Pa /proc/curproc/notepg
 226 used for signaling the process group
 227 .It Pa /proc/curproc/regs
 228 the process register set
 229 .It Pa /proc/curproc/rlimit
 230 the process current and maximum rlimit
 231 .It Pa /proc/curproc/status
 232 the process' current status
 233 .El
 234 .Sh SEE ALSO
 235 .Xr mount 2 ,
 236 .Xr sigaction 2 ,
 237 .Xr unmount 2 ,
 238 .Xr mount_procfs 8
 239 .Sh AUTHORS
 240 .An -nosplit
 241 This manual page written by
 242 .An Garrett Wollman ,
 243 based on the description
 244 provided by
 245 .An Jan-Simon Pendry ,
 246 and revamped later by
 247 .An Mike Pritchard .