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