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