1 files changed, 278 insertions, 0 deletions
diff --git a/share/man/man5/procfs.5 b/share/man/man5/procfs.5
new file mode 100644
index 0000000..684f9f3
--- /dev/null
+++ b/share/man/man5/procfs.5
@@ -0,0 +1,278 @@
+.\" $FreeBSD$
+.\" Written by Garrett Wollman
+.\" This file is in the public domain.
+.\"
+.Dd April 22, 2013
+.Dt PROCFS 5
+.Os
+.Sh NAME
+.Nm procfs
+.Nd process file system
+.Sh SYNOPSIS
+.Bd -literal
+proc		/proc	procfs	rw 0 0
+.Ed
+.Sh DESCRIPTION
+The process file system, or
+.Nm ,
+implements a view of the system process table inside the file system.
+It is normally mounted on
+.Pa /proc ,
+and is required for the complete operation of programs such as
+.Xr ps 1
+and
+.Xr w 1 .
+.Pp
+The
+.Nm
+provides a two-level view of process space, unlike the previous
+.Fx 1.1
+.Nm
+implementation.
+At the highest level, processes themselves are named, according to
+their process ids in decimal, with no leading zeros.
+There is also a
+special node called
+.Pa curproc
+which always refers to the process making the lookup request.
+.Pp
+Each node is a directory which contains the following entries:
+.Pp
+Each directory contains several files:
+.Bl -tag -width status
+.It Pa ctl
+a write-only file which supports a variety
+of control operations.
+Control commands are written as strings to the
+.Pa ctl
+file.
+The control commands are:
+.Bl -tag -width detach -compact
+.It attach
+stops the target process and arranges for the sending
+process to become the debug control process.
+.It detach
+continue execution of the target process and
+remove it from control by the debug process (which
+need not be the sending process).
+.It run
+continue running the target process until
+a signal is delivered, a breakpoint is hit, or the
+target process exits.
+.It step
+single step the target process, with no signal delivery.
+.It wait
+wait for the target process to come to a steady
+state ready for debugging.
+The target process must be in this state before
+any of the other commands are allowed.
+.El
+.Pp
+The string can also be the name of a signal, lower case
+and without the
+.Dv SIG
+prefix,
+in which case that signal is delivered to the process
+(see
+.Xr sigaction 2 ) .
+.Pp
+The
+.Xr procctl 8
+utility can be used to clear tracepoints in a stuck process.
+.It Pa dbregs
+The debug registers as defined by
+.Dv "struct dbregs"
+in
+.In machine/reg.h .
+.Pa dbregs
+is currently only implemented on the i386 architecture.
+.It Pa etype
+The type of the executable referenced by the
+.Pa file
+entry.
+.It Pa file
+A symbolic link to the file from which the process text was read.
+This can be used to gain access to the process' symbol table,
+or to start another copy of the process.
+If the file cannot be found, the link target is
+.Ql unknown .
+.It Pa fpregs
+The floating point registers as defined by
+.Dv "struct fpregs"
+in
+.In machine/reg.h .
+.Pa fpregs
+is only implemented on machines which have distinct general
+purpose and floating point register sets.
+.It Pa map
+A map of the process' virtual memory.
+.It Pa mem
+The complete virtual memory image of the process.
+Only those address which exist in the process can be accessed.
+Reads and writes to this file modify the process.
+Writes to the text segment remain private to the process.
+.It Pa note
+Used for sending signals to the process.
+Not implemented.
+.It Pa notepg
+Used for sending signal to the process group.
+Not implemented.
+.It Pa osrel
+Allows read and write of the kernel osrel value assigned to the process.
+It affects the compatibility shims that are turned on and off
+depending on the value.
+Initial process value is read from the ABI note tag in the executed ELF image,
+and is zero if the tag not supported by binary format or was not found.
+.It Pa regs
+Allows read and write access to the process' register set.
+This file contains a binary data structure
+.Dv "struct regs"
+defined in
+.In machine/reg.h .
+.Pa regs
+can only be written when the process is stopped.
+.It Pa rlimit
+This is a read-only file containing the process current and maximum
+limits.
+Each line is of the format
+.Ar rlimit current max ,
+with -1
+indicating infinity.
+.It Pa status
+The process status.
+This file is read-only and returns a single line containing
+multiple space-separated fields as follows:
+.Pp
+.Bl -bullet -compact
+.It
+command name
+.It
+process id
+.It
+parent process id
+.It
+process group id
+.It
+session id
+.It
+device name
+of the controlling terminal, or
+a minus sign
+.Pq Dq -
+if there is no controlling terminal.
+.It
+a list of process flags:
+.Dv ctty
+if there is a controlling terminal,
+.Dv sldr
+if the process is a session leader,
+.Dv noflags
+if neither of the other two flags are set.
+.It
+the process start time in seconds and microseconds,
+comma separated.
+.It
+the user time in seconds and microseconds,
+comma separated.
+.It
+the system time in seconds and microseconds,
+comma separated.
+.It
+the wait channel message
+.It
+the process credentials consisting of
+the effective user id
+and the list of groups (whose first member
+is the effective group id)
+all comma separated.
+.It
+the hostname of the jail in which the process runs, or
+.Ql -
+to indicate that the process is not running within a jail.
+.El
+.El
+.Pp
+In a normal debugging environment,
+where the target is fork/exec'd by the debugger,
+the debugger should fork and the child should stop
+itself (with a self-inflicted
+.Dv SIGSTOP
+for example).
+The parent should issue a
+.Dv wait
+and then an
+.Dv attach
+command via the appropriate
+.Pa ctl
+file.
+The child process will receive a
+.Dv SIGTRAP
+immediately after the call to exec (see
+.Xr execve 2 ) .
+.Pp
+Each node is owned by the process's user, and belongs to that user's
+primary group, except for the
+.Pa mem
+node, which belongs to the
+.Li kmem
+group.
+.Sh FILES
+.Bl -tag -width /proc/curproc/XXXXXXX -compact
+.It Pa /proc
+normal mount point for the
+.Nm .
+.It Pa /proc/pid
+directory containing process information for process
+.Pa pid .
+.It Pa /proc/curproc
+directory containing process information for the current process
+.It Pa /proc/curproc/cmdline
+the process executable name
+.It Pa /proc/curproc/ctl
+used to send control messages to the process
+.It Pa /proc/curproc/etype
+executable type
+.It Pa /proc/curproc/file
+executable image
+.It Pa /proc/curproc/fpregs
+the process floating point register set
+.It Pa /proc/curproc/map
+virtual memory map of the process
+.It Pa /proc/curproc/mem
+the complete virtual address space of the process
+.It Pa /proc/curproc/note
+used for signaling the process
+.It Pa /proc/curproc/notepg
+used for signaling the process group
+.It Pa /proc/curproc/osrel
+the process osrel value
+.It Pa /proc/curproc/regs
+the process register set
+.It Pa /proc/curproc/rlimit
+the process current and maximum rlimit
+.It Pa /proc/curproc/status
+the process' current status
+.El
+.Sh EXAMPLES
+To mount a
+.Nm
+file system on
+.Pa /proc :
+.Pp
+.Dl "mount -t procfs proc /proc"
+.Sh SEE ALSO
+.Xr procstat 1 ,
+.Xr mount 2 ,
+.Xr sigaction 2 ,
+.Xr unmount 2 ,
+.Xr procctl 8 ,
+.Xr pseudofs 9
+.Sh AUTHORS
+.An -nosplit
+This manual page written by
+.An Garrett Wollman ,
+based on the description
+provided by
+.An Jan-Simon Pendry ,
+and revamped later by
+.An Mike Pritchard .