After a synchronous process is created, Emacs waits for the
process to terminate before continuing. Starting Dired is an example of
this: it runs ls
in a synchronous process, then modifies the
output slightly. Because the process is synchronous, the entire
directory listing arrives in the buffer before Emacs tries to do
anything with it.
While Emacs waits for the synchronous subprocess to terminate, the
user can quit by typing C-g. The first C-g tries to kill
the subprocess with a SIGINT
signal; but it waits until the
subprocess actually terminates before quitting. If during that time the
user types another C-g, that kills the subprocess instantly with
SIGKILL
and quits immediately. See section Quitting.
The synchronous subprocess functions returned nil
in version
18. In version 19, they return an indication of how the process
terminated.
The standard input for the process comes from file infile if
infile is not nil
and from `/dev/null' otherwise.
The argument destination says where to put the process output.
Here are the possibilities:
t
nil
nil
means discard it, t
means mix it with the
ordinary output, and a string specifies a file name to redirect error
output into.
You can't directly specify a buffer to put the error output in; that is
too difficult to implement. But you can achieve this result by sending
the error output to a temporary file and then inserting the file into a
buffer.
If display is non-nil
, then call-process
redisplays
the buffer as output is inserted. Otherwise the function does no
redisplay, and the results become visible on the screen only when Emacs
redisplays that buffer in the normal course of events.
The remaining arguments, args, are strings that specify command line arguments for the program.
The value returned by call-process
(unless you told it not to
wait) indicates the reason for process termination. A number gives the
exit status of the subprocess; 0 means success, and any other value
means failure. If the process terminated with a signal,
call-process
returns a string describing the signal.
In the examples below, the buffer `foo' is current.
(call-process "pwd" nil t) => nil ---------- Buffer: foo ---------- /usr/user/lewis/manual ---------- Buffer: foo ---------- (call-process "grep" nil "bar" nil "lewis" "/etc/passwd") => nil ---------- Buffer: bar ---------- lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh ---------- Buffer: bar ----------
The insert-directory
function contains a good example of the use
of call-process
:
(call-process insert-directory-program nil t nil switches (if full-directory-p (concat (file-name-as-directory file) ".") file))
nil
; this is useful when buffer
is t
, to insert the output in the current buffer.
The arguments destination and display control what to do
with the output from the subprocess, and whether to update the display
as it comes in. For details, see the description of
call-process
, above. If destination is the integer 0,
call-process-region
discards the output and returns nil
immediately, without waiting for the subprocess to finish.
The remaining arguments, args, are strings that specify command line arguments for the program.
The return value of call-process-region
is just like that of
call-process
: nil
if you told it to return without
waiting; otherwise, a number or string which indicates how the
subprocess terminated.
In the following example, we use call-process-region
to run the
cat
utility, with standard input being the first five characters
in buffer `foo' (the word `input'). cat
copies its
standard input into its standard output. Since the argument
destination is t
, this output is inserted in the current
buffer.
---------- Buffer: foo ---------- input-!- ---------- Buffer: foo ---------- (call-process-region 1 6 "cat" nil t) => nil ---------- Buffer: foo ---------- inputinput-!- ---------- Buffer: foo ----------
The shell-command-on-region
command uses
call-process-region
like this:
(call-process-region
start end
shell-file-name ; Name of program.
nil ; Do not delete region.
buffer ; Send output to buffer
.
nil ; No redisplay during output.
"-c" command) ; Arguments for the shell.
Go to the first, previous, next, last section, table of contents.