Make procfs(5) the definitive source of information on /proc.

Most of this information was pulled from the man page for
mount_procfs(8).

Closes PR# 1681.

1 files changed, 161 insertions, 20 deletions

diff --git a/share/man/man5/procfs.5 b/share/man/man5/procfs.5
index bda70d1..668e659 100644
--- a/share/man/man5/procfs.5
+++ b/share/man/man5/procfs.5
@@ -1,4 +1,4 @@
-.\" $Id: procfs.5,v 1.3 1996/12/09 07:45:50 mpp Exp $
+.\" $Id: procfs.5,v 1.4 1996/12/14 19:09:58 mpp Exp $
 .\" Written by Garrett Wollman
 .\" This file is in the public domain.
 .\"
@@ -36,46 +36,187 @@ special node called
 which always refers to the process making the lookup request.
 .Pp
 Each node is a directory which contains the following entries:
-.Bl -tag -width fpregsxx
+.Pp
+Each directory contains several files:
+.Bl -tag -width status
 .It Pa ctl
-used to send control messages to the process, such as might be used by
-a debugger
+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 ).
 .It Pa etype
-the type of the current executable image
+The type of the executable referenced by the
+.Pa file
+entry.
 .It Pa file
-the executable image 
+A reference to the vnode 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.
 .It Pa fpregs
-the process floating point register set
+The floating point registers as defined by
+.Dv "struct fpregs"
+in
+.Pa <machine/reg.h> .
+.Pa fpregs
+is only implemented on machines which have distinct general
+purpose and floating point register sets.
 .It Pa map
-map of the process' address space
+A map of the process' virtual memory.
 .It Pa mem
-the complete virtual address space of the process
+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 to send signals to the process (not currently implemented)
+Used for sending signals to the process.  Not implemented.
 .It Pa notepg
-used to send signals to the process group that the process belongs to
-(not currently implemented)
+Used for sending signal to the process group.  Not implemented.
 .It Pa regs
-the process register set
+Allows read and write access to the process' register set.
+This file contains a binary data structure
+.Dv "struct regs"
+defined in
+.Pa <machine/reg.h> .
+.Pa regs
+can only be written when the process is stopped.
 .It Pa status
-the process's current 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
+.Ar major,minor
+of the controlling terminal, or
+.Dv -1,-1
+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.
 .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 instead.
-.Pp
-This manual page should eventually document what you can do with all
-these nodes.
 .Sh FILES
-.Bl -tag -width /procxx
+.Bl -tag -width /proc/curproc/XXXXXXX -compact
 .It Pa /proc
 normal mount point for the
 .Nm procfs .
+.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/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/regs
+the process register set
+.It Pa /proc/curproc/status
+the process' current status
 .El
+.Sh SEE ALSO
+.Xr sigaction 2 ,
+.Xr mount 2 ,
+.Xr unmount 2 ,
+.Xr mount_procfs 8
 .Sh AUTHOR
 This manual page written by Garrett Wollman, based on the description
-provided by Jan-Simon Pendry.
+provided by Jan-Simon Pendry, and revamped later by Mike Pritchard.