share/man/man5/procfs.5

   1 .\" Written by Garrett Wollman
   2 .\" This file is in the public domain.
   3 .\"
   4 .Dd April 10, 2023
   5 .Dt PROCFS 5
   6 .Os
   7 .Sh NAME
   8 .Nm procfs
   9 .Nd process file system
  10 .Sh SYNOPSIS
  11 .Bd -literal
  12 proc            /proc   procfs  rw 0 0
  13 .Ed
  14 .Sh DESCRIPTION
  15 .Bf -symbolic
  16 This functionality is deprecated.
  17 Users are advised to use
  18 .Xr libprocstat 3
  19 and
  20 .Xr kvm 3
  21 instead.
  22 .Ef
  23 .Pp
  24 The process file system, or
  25 .Nm ,
  26 implements a view of the system process table inside the file system.
  27 It is normally mounted on
  28 .Pa /proc .
  29 .Pp
  30 The
  31 .Nm
  32 provides a two-level view of process space, unlike the previous
  33 .Fx 1.1
  34 .Nm
  35 implementation.
  36 At the highest level, processes themselves are named, according to
  37 their process ids in decimal, with no leading zeros.
  38 There is also a
  39 special node called
  40 .Pa curproc
  41 which always refers to the process making the lookup request.
  42 .Pp
  43 Each node is a directory which contains the following entries:
  44 .Bl -tag -width status
  45 .It Pa dbregs
  46 The debug registers as defined by
  47 .Dv "struct dbregs"
  48 in
  49 .In machine/reg.h .
  50 .Pa dbregs
  51 is currently only implemented on the i386 architecture.
  52 .It Pa etype
  53 The type of the executable referenced by the
  54 .Pa file
  55 entry.
  56 .It Pa file
  57 A symbolic link to the file from which the process text was read.
  58 This can be used to gain access to the process' symbol table,
  59 or to start another copy of the process.
  60 If the file cannot be found, the link target is
  61 .Ql unknown .
  62 .It Pa fpregs
  63 The floating point registers as defined by
  64 .Dv "struct fpregs"
  65 in
  66 .In machine/reg.h .
  67 .Pa fpregs
  68 is only implemented on machines which have distinct general
  69 purpose and floating point register sets.
  70 .It Pa map
  71 A collection of lines describing the memory regions of the process,
  72 where each line contains the following fields:
  73 .Bl -tag -compact -width private-resident
  74 .It start-address
  75 The starting address for the region (inclusive).
  76 .It end-address
  77 The ending address for the region (exclusive).
  78 .It resident
  79 The number of resident pages.
  80 .It private-resident
  81 The number of resident pages that were private to the process.
  82 .It obj
  83 The virtual address of the
  84 .Vt struct vm_object
  85 kernel data structure describing the memory region.
  86 .It access
  87 A three character string comprising the characters
  88 .Sq r ,
  89 .Sq w
  90 and
  91 .Sq x ,
  92 denoting read, write, and execute permissions respectively.
  93 The lack of a permission is represented by
  94 .Sq - .
  95 .It ref_count
  96 The number of references to the region.
  97 .It shadow_count
  98 The number of VM objects that this region is a shadow for.
  99 .It flags
 100 The flags for the object, see the flags named
 101 .Sy OBJ_*
 102 in
 103 .In vm/vm_object.h .
 104 .It copy-on-write
 105 Whether the region is copy-on-write.
 106 One of:
 107 .Bl -tag -compact -width NCOW
 108 .It COW
 109 A copy-on-write region.
 110 .It NCOW
 111 A non-copy-on-write region.
 112 .El
 113 .It needs-copy
 114 Whether the region needs a copy.
 115 One of:
 116 .Bl -tag -compact -width NNC
 117 .It NC
 118 The region needs a copy.
 119 .It NNC
 120 The region does not need a copy.
 121 .El
 122 .It type
 123 The type of the region.
 124 One of:
 125 .Bl -tag -compact -width unknown
 126 .It dead
 127 A region associated with a dead VM object.
 128 .It device
 129 A region backed by device memory.
 130 .It none
 131 A region not backed by anything.
 132 .It phys
 133 A region backed by physical memory.
 134 .It swap
 135 A region backed by swap.
 136 .It unknown
 137 A region of unknown type.
 138 .It vnode
 139 A region backed by a file.
 140 .El
 141 .It fullpath
 142 The path to the file backing the memory region, or
 143 .Sq -
 144 if there is no such file.
 145 .It cred
 146 One of:
 147 .Bl -tag -compact -width NCH
 148 .It CH
 149 The region is being charged to the user specified in the
 150 .Sq charged-uid
 151 field.
 152 .It NCH
 153 The region is not being charged to any user.
 154 .El
 155 .It charged-uid
 156 The UID of the user being charged, or -1 if no user is being charged.
 157 .El
 158 .It Pa mem
 159 The complete virtual memory image of the process.
 160 Only those address which exist in the process can be accessed.
 161 Reads and writes to this file modify the process.
 162 Writes to the text segment remain private to the process.
 163 .It Pa note
 164 Used for sending signals to the process.
 165 Not implemented.
 166 .It Pa notepg
 167 Used for sending signal to the process group.
 168 Not implemented.
 169 .It Pa osrel
 170 Allows read and write of the kernel osrel value assigned to the process.
 171 It affects the compatibility shims that are turned on and off
 172 depending on the value.
 173 Initial process value is read from the ABI note tag in the executed ELF image,
 174 and is zero if the tag not supported by binary format or was not found.
 175 .It Pa regs
 176 Allows read and write access to the process' register set.
 177 This file contains a binary data structure
 178 .Dv "struct regs"
 179 defined in
 180 .In machine/reg.h .
 181 .Pa regs
 182 can only be written when the process is stopped.
 183 .It Pa rlimit
 184 This is a read-only file containing the process current and maximum
 185 limits.
 186 Each line is of the format
 187 .Ar rlimit current max ,
 188 with -1
 189 indicating infinity.
 190 .It Pa status
 191 The process status.
 192 This file is read-only and returns a single line containing
 193 multiple space-separated fields as follows:
 194 .Pp
 195 .Bl -bullet -compact
 196 .It
 197 command name
 198 .It
 199 process id
 200 .It
 201 parent process id
 202 .It
 203 process group id
 204 .It
 205 session id
 206 .It
 207 device name
 208 of the controlling terminal, or
 209 a minus sign
 210 .Pq Dq -
 211 if there is no controlling terminal.
 212 .It
 213 a list of process flags:
 214 .Dv ctty
 215 if there is a controlling terminal,
 216 .Dv sldr
 217 if the process is a session leader,
 218 .Dv noflags
 219 if neither of the other two flags are set.
 220 .It
 221 the process start time in seconds and microseconds,
 222 comma separated.
 223 .It
 224 the user time in seconds and microseconds,
 225 comma separated.
 226 .It
 227 the system time in seconds and microseconds,
 228 comma separated.
 229 .It
 230 the wait channel message
 231 .It
 232 the process credentials consisting of
 233 the effective user id
 234 and the list of groups (whose first member
 235 is the effective group id)
 236 all comma separated.
 237 .It
 238 the hostname of the jail in which the process runs, or
 239 .Ql -
 240 to indicate that the process is not running within a jail.
 241 .El
 242 .El
 243 .Pp
 244 Each node is owned by the process's user, and belongs to that user's
 245 primary group.
 246 .Sh FILES
 247 .Bl -tag -width /proc/curproc/XXXXXXX -compact
 248 .It Pa /proc
 249 normal mount point for the
 250 .Nm .
 251 .It Pa /proc/pid
 252 directory containing process information for process
 253 .Pa pid .
 254 .It Pa /proc/curproc
 255 directory containing process information for the current process
 256 .It Pa /proc/curproc/cmdline
 257 the process executable name
 258 .It Pa /proc/curproc/etype
 259 executable type
 260 .It Pa /proc/curproc/file
 261 executable image
 262 .It Pa /proc/curproc/fpregs
 263 the process floating point register set
 264 .It Pa /proc/curproc/map
 265 virtual memory map of the process
 266 .It Pa /proc/curproc/mem
 267 the complete virtual address space of the process
 268 .It Pa /proc/curproc/note
 269 used for signaling the process
 270 .It Pa /proc/curproc/notepg
 271 used for signaling the process group
 272 .It Pa /proc/curproc/osrel
 273 the process osrel value
 274 .It Pa /proc/curproc/regs
 275 the process register set
 276 .It Pa /proc/curproc/rlimit
 277 the process current and maximum rlimit
 278 .It Pa /proc/curproc/status
 279 the process' current status
 280 .El
 281 .Sh EXAMPLES
 282 To mount a
 283 .Nm
 284 file system on
 285 .Pa /proc :
 286 .Pp
 287 .Dl "mount -t procfs proc /proc"
 288 .Sh SEE ALSO
 289 .Xr procstat 1 ,
 290 .Xr mount 2 ,
 291 .Xr sigaction 2 ,
 292 .Xr unmount 2 ,
 293 .Xr kvm 3 ,
 294 .Xr libprocstat 3 ,
 295 .Xr pseudofs 9
 296 .Sh AUTHORS
 297 .An -nosplit
 298 This manual page written by
 299 .An Garrett Wollman ,
 300 based on the description
 301 provided by
 302 .An Jan-Simon Pendry ,
 303 and revamped later by
 304 .An Mike Pritchard .