[Emacs-diffs] Changes to emacs/doc/lispref/processes.texi,v

[Eli Zaretskii]

CVSROOT:        /cvsroot/emacs
Module name:    emacs
Changes by:     Eli Zaretskii <eliz>    08/10/14 15:36:55

Index: processes.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/doc/lispref/processes.texi,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -b -r1.6 -r1.7
--- processes.texi      13 Jun 2008 08:05:52 -0000      1.6
+++ processes.texi      14 Oct 2008 15:36:55 -0000      1.7
@@ -29,10 +29,14 @@
 send input to it.
 
 @defun processp object
-This function returns @code{t} if @var{object} is a process,
address@hidden otherwise.
+This function returns @code{t} if @var{object} represents an Emacs
+subprocess, @code{nil} otherwise.
 @end defun
 
+  In addition to subprocesses of the current Emacs session, you can
+also access other processes running on your machine.  @xref{System
+Processes}.
+
 @menu
 * Subprocess Creation::      Functions that start subprocesses.
 * Shell Arguments::          Quoting an argument to pass it to a shell.
@@ -46,6 +50,7 @@
 * Output from Processes::    Collecting output from an asynchronous subprocess.
 * Sentinels::                Sentinels run when process run-status changes.
 * Query Before Exit::        Whether to query if exiting will kill a process.
+* System Processes::         Accessing other processes running on your system.
 * Transaction Queues::      Transaction-based communication with subprocesses.
 * Network::                  Opening network connections.
 * Network Servers::          Network servers let Emacs accept net connections.
@@ -1028,7 +1033,7 @@
 
 The @var{process} argument can be a system process @acronym{ID}; that
 allows you to send signals to processes that are not children of
-Emacs.
+Emacs.  @xref{System Processes}.
 @end defun
 
 @node Output from Processes
@@ -1566,6 +1571,185 @@
 @end smallexample
 @end defun
 
address@hidden System Processes
address@hidden Accessing Other Processes
address@hidden system processes
+
+  In addition to accessing and manipulating processes that are
+subprocesses of the current Emacs session, Emacs Lisp programs can
+also access other processes running on the same machine.  We call
+these @dfn{system processes}, to distinguish between them and Emacs
+subprocesses.
+
+  Emacs provides several primitives for accessing system processes.
+Not all platforms support these primitives; on those which don't,
+these primitives return @code{nil}.
+
address@hidden list-system-processes
+This function returns a list of all the processes running on the
+system.  Each process is identified by its @acronym{PID}, a numerical
+process ID that is assigned by the OS and distinguishes the process
+from all the other processes running on the same machine at the same
+time.
address@hidden defun
+
address@hidden system-process-attributes pid
+This function returns an alist of attributes for the process specified
+by its process ID @var{pid}.  Each association in the alist is of the
+form @code{(@var{key} . @var{value})}, where @var{key} designates the
+attribute and @var{value} is the value of that attribute.  The various
+attribute @var{key}'s that this function can return are listed below.
+Not all platforms support all of these attributes; if an attribute is
+not supported, its association will not appear in the returned alist.
+Values that are numbers can be either integer or floating-point,
+depending on the magnitude of the value.
+
address@hidden @code
address@hidden euid
+The effective user ID of the user who invoked the process.  The
+corresponding @var{value} is a number.  If the process was invoked by
+the same user who runs the current Emacs session, the value is
+identical to what @code{user-uid} returns (@pxref{User
+Identification}).
+
address@hidden user
+User name corresponding to the process's effective user ID, a string.
+
address@hidden egid
+The group ID of the effective user ID, a number.
+
address@hidden group
+Group name corresponding to the effective user's group ID, a string.
+
address@hidden comm
+The name of the command that runs in the process.  This is a string
+that usually specifies the name of the executable file of the process,
+without the leading directories.  However, some special system
+processes can report strings that do not correspond to an executable
+file of a program.
+
address@hidden state
+The state code of the process.  This is a short string that encodes
+the scheduling state of the process.  Here's a list of the most
+frequently seen codes:
+
address@hidden @code
address@hidden ``D''
+uninterruptible sleep (usually I/O)
address@hidden ``R''
+running
address@hidden ``S''
+interruptible sleep (waiting for some event)
address@hidden ``T''
+stopped, e.g., by a job control signal
address@hidden ``Z''
+``zombie'': a process that terminated, but not reaped by its parent
address@hidden table
+
address@hidden
+For the full list of the possible states, see the manual page of the
address@hidden command.
+
address@hidden ppid
+The process ID of the parent process, a number.
+
address@hidden pgrp
+The process group ID of the process, a number.
+
address@hidden sess
+The session ID of the process.  This is a number that is the process
+ID of the process's @dfn{session leader}.
+
address@hidden ttname
+A string that is the name of the process's controlling terminal.  On
+Unix and GNU systems, this is normally the file name of the
+corresponding terminal device, such as @file{/dev/pts65}.
+
address@hidden tpgid
+The numerical process group ID of the foreground process group that
+uses the process's terminal.
+
address@hidden minflt
+The number of minor page faults caused by the process since its
+beginning.  (Minor page faults are those that don't involve reading
+from disk.)
+
address@hidden majflt
+The number of major page faults caused by the process since its
+beginning.  (Major page faults require a disk to be read, and are thus
+more expensive than minor page faults.)
+
address@hidden cminflt
address@hidden cmajflt
+Like @code{minflt} and @code{majflt}, but include the number of page
+faults for all the child processes of the given process.
+
address@hidden utime
+Time spent by the process in the user context, for running the
+application's code.  The corresponding @var{value} is in the
address@hidden@code{(@var{high} @var{low} @var{microsec})}} format, the same
+format used by functions @code{current-time} (@pxref{Time of Day,
+current-time}) and @code{file-attributes} (@pxref{File Attributes}).
+
address@hidden stime
+Time spent by the process in the system (kernel) context, for
+processing system calls.  The corresponding @var{value} is in the same
+format as for @code{utime}.
+
address@hidden cutime
address@hidden cstime
+Like @code{utime} and @code{stime}, but includes the times of all the
+child processes of the given process.
+
address@hidden pri
+The numerical priority of the process.
+
address@hidden nice
+The @dfn{nice value} of the process, a number.  Processes with smaller
+nice value get scheduled more favorably.
+
address@hidden thcount
+The number of threads in the process.
+
address@hidden start
+The time the process was started, in the @address@hidden(@var{high}
address@hidden @var{microsec})}} format used by @code{current-time} and
address@hidden
+
address@hidden etime
+The time elapsed since the process started, in the @address@hidden(@var{high}
address@hidden @var{microsec})}} format.
+
address@hidden vsize
+The virtual memory size of the process, measured in kilobytes.
+
address@hidden rss
+The size of the process's @dfn{resident set}, the number of kilobytes
+occupied by the process in the machine's physical memory.
+
address@hidden pcpu
+The percentage of the CPU time used by the process since it started.
+The corresponding @var{value} is a floating-point number between 0 and
+100.
+
address@hidden pmem
+The percentage of the total physical memory installed on the machine
+used by the process's resident set.  The value is a floating-point
+number between 0 and 100.
+
address@hidden args
+The command-line with which the process was invoked.  This is a string
+in which individual command-line arguments are separated by blanks;
+whitespace characters that are embedded in the arguments are quoted as
+appropriate for the system's shell: escaped by backslash characters on
+GNU and Unix, and enclosed in double quote characters on Windows.
+Thus, this command-line string can be directly used in primitives such
+as @code{shell-command}.
address@hidden table
+
address@hidden defun
+
+
 @node Transaction Queues
 @section Transaction Queues
 @cindex transaction queue