/share/man/man5/procfs.5

  1.\" $FreeBSD$
  2.\" Written by Garrett Wollman
  3.\" This file is in the public domain.
  4.\"
  5.Dd September 22, 2009
  6.Dt PROCFS 5
  7.Os
  8.Sh NAME
  9.Nm procfs
 10.Nd process file system
 11.Sh SYNOPSIS
 12.Bd -literal
 13proc		/proc	procfs	rw 0 0
 14.Ed
 15.Sh DESCRIPTION
 16The process file system, or
 17.Nm ,
 18implements a view of the system process table inside the file system.
 19It is normally mounted on
 20.Pa /proc ,
 21and is required for the complete operation of programs such as
 22.Xr ps 1
 23and
 24.Xr w 1 .
 25.Pp
 26The
 27.Nm
 28provides a two-level view of process space, unlike the previous
 29.Fx 1.1
 30.Nm
 31implementation.
 32At the highest level, processes themselves are named, according to
 33their process ids in decimal, with no leading zeros.
 34There is also a
 35special node called
 36.Pa curproc
 37which always refers to the process making the lookup request.
 38.Pp
 39Each node is a directory which contains the following entries:
 40.Pp
 41Each directory contains several files:
 42.Bl -tag -width status
 43.It Pa ctl
 44a write-only file which supports a variety
 45of control operations.
 46Control commands are written as strings to the
 47.Pa ctl
 48file.
 49The control commands are:
 50.Bl -tag -width detach -compact
 51.It attach
 52stops the target process and arranges for the sending
 53process to become the debug control process.
 54.It detach
 55continue execution of the target process and
 56remove it from control by the debug process (which
 57need not be the sending process).
 58.It run
 59continue running the target process until
 60a signal is delivered, a breakpoint is hit, or the
 61target process exits.
 62.It step
 63single step the target process, with no signal delivery.
 64.It wait
 65wait for the target process to come to a steady
 66state ready for debugging.
 67The target process must be in this state before
 68any of the other commands are allowed.
 69.El
 70.Pp
 71The string can also be the name of a signal, lower case
 72and without the
 73.Dv SIG
 74prefix,
 75in which case that signal is delivered to the process
 76(see
 77.Xr sigaction 2 ) .
 78.Pp
 79The
 80.Xr procctl 8
 81utility can be used to clear tracepoints in a stuck process.
 82.It Pa dbregs
 83The debug registers as defined by
 84.Dv "struct dbregs"
 85in
 86.In machine/reg.h .
 87.Pa dbregs
 88is currently only implemented on the i386 architecture.
 89.It Pa etype
 90The type of the executable referenced by the
 91.Pa file
 92entry.
 93.It Pa file
 94A symbolic link to the file from which the process text was read.
 95This can be used to gain access to the process' symbol table,
 96or to start another copy of the process.
 97If the file cannot be found, the link target is
 98.Ql unknown .
 99.It Pa fpregs
100The floating point registers as defined by
101.Dv "struct fpregs"
102in
103.In machine/reg.h .
104.Pa fpregs
105is only implemented on machines which have distinct general
106purpose and floating point register sets.
107.It Pa map
108A map of the process' virtual memory.
109.It Pa mem
110The complete virtual memory image of the process.
111Only those address which exist in the process can be accessed.
112Reads and writes to this file modify the process.
113Writes to the text segment remain private to the process.
114.It Pa note
115Used for sending signals to the process.
116Not implemented.
117.It Pa notepg
118Used for sending signal to the process group.
119Not implemented.
120.It Pa osrel
121Allows read and write of the kernel osrel value assigned to the process.
122It affects the compatibility shims that are turned on and off
123depending on the value.
124Initial process value is read from the ABI note tag in the executed ELF image,
125and is zero if the tag not supported by binary format or was not found.
126.It Pa regs
127Allows read and write access to the process' register set.
128This file contains a binary data structure
129.Dv "struct regs"
130defined in
131.In machine/reg.h .
132.Pa regs
133can only be written when the process is stopped.
134.It Pa rlimit
135This is a read-only file containing the process current and maximum
136limits.
137Each line is of the format
138.Ar rlimit current max ,
139with -1
140indicating infinity.
141.It Pa status
142The process status.
143This file is read-only and returns a single line containing
144multiple space-separated fields as follows:
145.Pp
146.Bl -bullet -compact
147.It
148command name
149.It
150process id
151.It
152parent process id
153.It
154process group id
155.It
156session id
157.It
158.Ar major , Ns Ar minor
159of the controlling terminal, or
160.Dv -1,-1
161if there is no controlling terminal.
162.It
163a list of process flags:
164.Dv ctty
165if there is a controlling terminal,
166.Dv sldr
167if the process is a session leader,
168.Dv noflags
169if neither of the other two flags are set.
170.It
171the process start time in seconds and microseconds,
172comma separated.
173.It
174the user time in seconds and microseconds,
175comma separated.
176.It
177the system time in seconds and microseconds,
178comma separated.
179.It
180the wait channel message
181.It
182the process credentials consisting of
183the effective user id
184and the list of groups (whose first member
185is the effective group id)
186all comma separated.
187.It
188the hostname of the jail in which the process runs, or
189.Ql -
190to indicate that the process is not running within a jail.
191.El
192.El
193.Pp
194In a normal debugging environment,
195where the target is fork/exec'd by the debugger,
196the debugger should fork and the child should stop
197itself (with a self-inflicted
198.Dv SIGSTOP
199for example).
200The parent should issue a
201.Dv wait
202and then an
203.Dv attach
204command via the appropriate
205.Pa ctl
206file.
207The child process will receive a
208.Dv SIGTRAP
209immediately after the call to exec (see
210.Xr execve 2 ) .
211.Pp
212Each node is owned by the process's user, and belongs to that user's
213primary group, except for the
214.Pa mem
215node, which belongs to the
216.Li kmem
217group.
218.Sh FILES
219.Bl -tag -width /proc/curproc/XXXXXXX -compact
220.It Pa /proc
221normal mount point for the
222.Nm .
223.It Pa /proc/pid
224directory containing process information for process
225.Pa pid .
226.It Pa /proc/curproc
227directory containing process information for the current process
228.It Pa /proc/curproc/cmdline
229the process executable name
230.It Pa /proc/curproc/ctl
231used to send control messages to the process
232.It Pa /proc/curproc/etype
233executable type
234.It Pa /proc/curproc/file
235executable image
236.It Pa /proc/curproc/fpregs
237the process floating point register set
238.It Pa /proc/curproc/map
239virtual memory map of the process
240.It Pa /proc/curproc/mem
241the complete virtual address space of the process
242.It Pa /proc/curproc/note
243used for signaling the process
244.It Pa /proc/curproc/notepg
245used for signaling the process group
246.It Pa /proc/curproc/osrel
247the process osrel value
248.It Pa /proc/curproc/regs
249the process register set
250.It Pa /proc/curproc/rlimit
251the process current and maximum rlimit
252.It Pa /proc/curproc/status
253the process' current status
254.El
255.Sh EXAMPLES
256To mount a
257.Nm
258file system on
259.Pa /proc :
260.Pp
261.Dl "mount -t procfs proc /proc"
262.Sh SEE ALSO
263.Xr procstat 1 ,
264.Xr mount 2 ,
265.Xr sigaction 2 ,
266.Xr unmount 2 ,
267.Xr procctl 8 ,
268.Xr pseudofs 9
269.Sh AUTHORS
270.An -nosplit
271This manual page written by
272.An Garrett Wollman ,
273based on the description
274provided by
275.An Jan-Simon Pendry ,
276and revamped later by
277.An Mike Pritchard .