mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2024-12-03 08:30:09 +00:00
Code Issues Releases Activity

Doc and manual fixes related to processes

Browse Source 
* doc/lispref/processes.texi (Processes, Subprocess Creation, Shell Arguments):
(Synchronous Processes): Copyedits.
(Subprocess Creation): Discourage modifying exec-path directly.
(Synchronous Processes): Update some example output.
(Process Information): Fix typo.
(Bindat Spec): Use Texinfo-recommended form of quote+punctuation.

* lisp/simple.el (process-file-side-effects): Doc fix.
This commit is contained in:
Glenn Morris 2012-04-14 18:37:16 -07:00
parent 764a3017e2
commit e153c13643
4 changed files with 69 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
doc/lispref/ChangeLog
View File

@ -1,3 +1,12 @@
2012-04-15 Glenn Morris <rgm@gnu.org>
* processes.texi (Processes, Subprocess Creation, Shell Arguments):
(Synchronous Processes): Copyedits.
(Subprocess Creation): Discourage modifying exec-path directly.
(Synchronous Processes): Update some example output.
(Process Information): Fix typo.
(Bindat Spec): Use Texinfo-recommended form of quote+punctuation.
2012-04-14 Glenn Morris <rgm@gnu.org>
* anti.texi (Antinews): Copyedits. Don't @dfn anything here.

91
doc/lispref/processes.texi
View File

@ -23,7 +23,7 @@ subprocess, the Lisp program waits for the subprocess to terminate
before continuing execution. When you create an asynchronous
subprocess, it can run in parallel with the Lisp program. This kind of
subprocess is represented within Emacs by a Lisp object which is also
called a ``process.'' Lisp programs can use this object to communicate
called a ``process''. Lisp programs can use this object to communicate
with the subprocess or to control it. For example, you can send
signals, obtain status information, receive output from the process, or
send input to it.
@ -70,7 +70,9 @@ a program. One of them, @code{start-process}, creates an asynchronous
process and returns a process object (@pxref{Asynchronous Processes}).
The other two, @code{call-process} and @code{call-process-region},
create a synchronous process and do not return a process object
(@pxref{Synchronous Processes}).
(@pxref{Synchronous Processes}). There are various higher-level
functions that make use of these primitives to run particular types of
process.
Synchronous and asynchronous processes are explained in the following
sections. Since the three functions are all called in a similar
@ -104,16 +106,19 @@ system-dependent.
@strong{Please note:} The argument @var{program} contains only the
name of the program; it may not contain any command-line arguments. You
must use @var{args} to provide those.
must use a separate argument, @var{args}, to provide those, as
described below.
Each of the subprocess-creating functions has a @var{buffer-or-name}
argument which specifies where the standard output from the program will
argument that specifies where the standard output from the program will
go. It should be a buffer or a buffer name; if it is a buffer name,
that will create the buffer if it does not already exist. It can also
be @code{nil}, which says to discard the output unless a filter function
handles it. (@xref{Filter Functions}, and @ref{Read and Print}.)
Normally, you should avoid having multiple processes send output to the
same buffer because their output would be intermixed randomly.
For synchronous processes, you can send the output to a file instead
of a buffer.
@cindex program arguments
All three of the subprocess-creating functions have a @code{&rest}
@ -122,18 +127,16 @@ supplied to @var{program} as separate command line arguments. Wildcard
characters and other shell constructs have no special meanings in these
strings, since the strings are passed directly to the specified program.
The subprocess gets its current directory from the value of
@code{default-directory} (@pxref{File Name Expansion}).
@cindex environment variables, subprocesses
The subprocess inherits its environment from Emacs, but you can
specify overrides for it with @code{process-environment}. @xref{System
Environment}.
Environment}. The subprocess gets its current directory from the
value of @code{default-directory}.
@defvar exec-directory
@pindex movemail
The value of this variable is a string, the name of a directory that
contains programs that come with GNU Emacs, programs intended for Emacs
contains programs that come with GNU Emacs and are intended for Emacs
to invoke. The program @code{movemail} is an example of such a program;
Rmail uses it to fetch new mail from an inbox.
@end defvar
@ -148,6 +151,11 @@ directory (which is the value of @code{default-directory}).
The value of @code{exec-path} is used by @code{call-process} and
@code{start-process} when the @var{program} argument is not an absolute
file name.
Generally, you should not modify @code{exec-path} directly. Instead,
ensure that your @env{PATH} environment variable is set appropriately
before starting Emacs. Trying to modify @code{exec-path}
independently of @env{PATH} can lead to confusing results.
@end defopt
@node Shell Arguments
@ -163,7 +171,7 @@ occur in the file name, they will confuse the shell. To handle these
characters, use the function @code{shell-quote-argument}:
@defun shell-quote-argument argument
This function returns a string which represents, in shell syntax,
This function returns a string that represents, in shell syntax,
an argument whose actual contents are @var{argument}. It should
work reliably to concatenate the return value into a shell command
and then pass it to a shell for execution.
@ -201,10 +209,10 @@ a shell command:
The following two functions are useful for combining a list of
individual command-line argument strings into a single string, and
taking a string apart into a list of individual command-line
arguments. These functions are mainly intended to be used for
arguments. These functions are mainly intended for
converting user input in the minibuffer, a Lisp string, into a list of
string arguments to be passed to @code{call-process} or
@code{start-process}, or for the converting such lists of arguments in
@code{start-process}, or for converting such lists of arguments into
a single Lisp string to be presented in the minibuffer or echo area.
@defun split-string-and-unquote string &optional separators
@ -345,7 +353,7 @@ In the examples below, the buffer @samp{foo} is current.
@result{} 0
---------- Buffer: foo ----------
/usr/user/lewis/manual
/home/lewis/manual
---------- Buffer: foo ----------
@end group
@ -354,18 +362,18 @@ In the examples below, the buffer @samp{foo} is current.
@result{} 0
---------- Buffer: bar ----------
lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
lewis:x:1001:1001:Bil Lewis,,,,:/home/lewis:/bin/bash
---------- Buffer: bar ----------
@end group
@end smallexample
Here is a good example of the use of @code{call-process}, which used to
be found in the definition of @code{insert-directory}:
Here is an example of the use of @code{call-process}, as used to
be found in the definition of the @code{insert-directory} function:
@smallexample
@group
(call-process insert-directory-program nil t nil @var{switches}
(call-process insert-directory-program nil t nil switches
(if full-directory-p
(concat (file-name-as-directory file) ".")
file))
@ -375,9 +383,9 @@ be found in the definition of @code{insert-directory}:
@defun process-file program &optional infile buffer display &rest args
This function processes files synchronously in a separate process. It
is similar to @code{call-process} but may invoke a file handler based
on the value of the variable @code{default-directory}. The current
working directory of the subprocess is @code{default-directory}.
is similar to @code{call-process}, but may invoke a file handler based
on the value of the variable @code{default-directory}, which specifies
the current working directory of the subprocess.
The arguments are handled in almost the same way as for
@code{call-process}, with the following differences:
@ -390,15 +398,15 @@ file handlers might not support separating standard output and error
output by way of the @var{buffer} argument.
If a file handler is invoked, it determines the program to run based
on the first argument @var{program}. For instance, consider that a
on the first argument @var{program}. For instance, suppose that a
handler for remote files is invoked. Then the path that is used for
searching the program might be different than @code{exec-path}.
searching for the program might be different from @code{exec-path}.
The second argument @var{infile} may invoke a file handler. The file
handler could be different from the handler chosen for the
@code{process-file} function itself. (For example,
@code{default-directory} could be on a remote host, whereas
@var{infile} is on another remote host. Or @code{default-directory}
@code{default-directory} could be on one remote host, and
@var{infile} on a different remote host. Or @code{default-directory}
could be non-special, whereas @var{infile} is on a remote host.)
If @var{buffer} is a list of the form @code{(@var{real-destination}
@ -415,16 +423,16 @@ file names.
@end defun
@defvar process-file-side-effects
This variable indicates, whether a call of @code{process-file} changes
This variable indicates whether a call of @code{process-file} changes
remote files.
Per default, this variable is always set to @code{t}, meaning that a
By default, this variable is always set to @code{t}, meaning that a
call of @code{process-file} could potentially change any file on a
remote host. When set to @code{nil}, a file handler could optimize
its behavior with respect to remote file attributes caching.
its behavior with respect to remote file attribute caching.
This variable should never be changed by @code{setq}. Instead of, it
shall be set only by let-binding.
You should only ever change this variable with a let-binding; never
with @code{setq}.
@end defvar
@defun call-process-region start end program &optional delete destination display &rest args
@ -440,7 +448,7 @@ as it comes in. For details, see the description of
@code{call-process}, above. If @var{destination} is the integer 0,
@code{call-process-region} discards the output and returns @code{nil}
immediately, without waiting for the subprocess to finish (this only
works if asynchronous subprocesses are supported).
works if asynchronous subprocesses are supported; i.e. not on MS-DOS).
The remaining arguments, @var{args}, are strings that specify command
line arguments for the program.
@ -474,18 +482,18 @@ inputinput@point{}
@end group
@end smallexample
The @code{shell-command-on-region} command uses
@code{call-process-region} like this:
For example, the @code{shell-command-on-region} command uses
@code{call-process-region} in a manner similar to this:
@smallexample
@group
(call-process-region
start end
shell-file-name ; @r{Name of program.}
nil ; @r{Do not delete region.}
buffer ; @r{Send output to @code{buffer}.}
nil ; @r{No redisplay during output.}
"-c" command) ; @r{Arguments for the shell.}
shell-file-name ; @r{name of program}
nil ; @r{do not delete region}
buffer ; @r{send output to @code{buffer}}
nil ; @r{no redisplay during output}
"-c" command) ; @r{arguments for the shell}
@end group
@end smallexample
@end defun
@ -508,6 +516,9 @@ This function executes @var{command} (a string) as a shell command,
then returns the command's output as a string.
@end defun
@c There is also shell-command-on-region, but that is more of a user
@c command, not something to use in programs.
@defun process-lines program &rest args
This function runs @var{program}, waits for it to finish, and returns
its output as a list of strings. Each string in the list holds a
@ -864,7 +875,7 @@ closed the connection, or Emacs did @code{delete-process}.
@end defun
@defun process-live-p process
This function returns nin-@code{nil} if @var{process} is alive. A
This function returns non-@code{nil} if @var{process} is alive. A
process is considered alive if its status is @code{run}, @code{open},
@code{listen}, @code{connect} or @code{stop}.
@end defun
@ -2662,7 +2673,7 @@ specification}, a special nested list describing named and typed
@dfn{fields}. This specification controls length of each field to be
processed, and how to pack or unpack it. We normally keep bindat specs
in variables whose names end in @samp{-bindat-spec}; that kind of name
is automatically recognized as ``risky.''
is automatically recognized as ``risky''.
@cindex endianness
@cindex big endian
@ -2672,7 +2683,7 @@ is automatically recognized as ``risky.''
that the field represents and, in the case of multibyte fields, how
the bytes are ordered within the field. The two possible orderings
are ``big endian'' (also known as ``network byte ordering'') and
``little endian.'' For instance, the number @code{#x23cd} (decimal
``little endian''. For instance, the number @code{#x23cd} (decimal
9165) in big endian would be the two bytes @code{#x23} @code{#xcd};
and in little endian, @code{#xcd} @code{#x23}. Here are the possible
type values:

4
lisp/ChangeLog
View File

@ -1,3 +1,7 @@
2012-04-15 Glenn Morris <rgm@gnu.org>
* simple.el (process-file-side-effects): Doc fix.
2012-04-14 Glenn Morris <rgm@gnu.org>
* international/mule-cmds.el (set-language-environment): Doc fix.

10
lisp/simple.el
View File

@ -1,6 +1,6 @@
;;; simple.el --- basic editing commands for Emacs
;; Copyright (C) 1985-1987, 1993-2012 Free Software Foundation, Inc.
;; Copyright (C) 1985-1987, 1993-2012 Free Software Foundation, Inc.
;; Maintainer: FSF
;; Keywords: internal
@ -2677,13 +2677,13 @@ value passed."
(defvar process-file-side-effects t
"Whether a call of `process-file' changes remote files.
Per default, this variable is always set to `t', meaning that a
By default, this variable is always set to `t', meaning that a
call of `process-file' could potentially change any file on a
remote host. When set to `nil', a file handler could optimize
its behavior with respect to remote file attributes caching.
its behavior with respect to remote file attribute caching.
This variable should never be changed by `setq'. Instead of, it
shall be set only by let-binding.")
You should only ever change this variable with a let-binding;
never with `setq'.")
(defun start-file-process (name buffer program &rest program-args)
"Start a program in a subprocess. Return the process object for it.