Next: Asynchronous Processes, Previous: Shell Arguments, Up: Processes
After a synchronous process is created, Emacs waits for the
process to terminate before continuing. Starting Dired on GNU or
Unix1 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 (except on MS-DOS, where killing
other processes doesn't work). See Quitting.
The synchronous subprocess functions return an indication of how the process terminated.
The output from a synchronous subprocess is generally decoded using a
coding system, much like text read from a file. The input sent to a
subprocess by call-process-region
is encoded using a coding
system, much like text written into a file. See Coding Systems.
This function calls program in a separate process and waits for it to finish.
The standard input for the process comes from file infile if infile is not
nil
, and from the null device otherwise. The argument destination says where to put the process output. Here are the possibilities:
- a buffer
- Insert the output in that buffer, before point. This includes both the standard output stream and the standard error stream of the process.
- a string
- Insert the output in a buffer with that name, before point.
t
- Insert the output in the current buffer, before point.
nil
- Discard the output.
- 0
- Discard the output, and return
nil
immediately without waiting for the subprocess to finish.In this case, the process is not truly synchronous, since it can run in parallel with Emacs; but you can think of it as synchronous in that Emacs is essentially finished with the subprocess as soon as this function returns.
MS-DOS doesn't support asynchronous subprocesses, so this option doesn't work there.
(
real-destination error-destination)
- Keep the standard output stream separate from the standard error stream; deal with the ordinary output as specified by real-destination, and dispose of the error output according to error-destination. If error-destination is
nil
, that means to discard the error output,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
, thencall-process
redisplays the buffer as output is inserted. (However, if the coding system chosen for decoding output isundecided
, meaning deduce the encoding from the actual data, then redisplay sometimes cannot continue once non-ascii characters are encountered. There are fundamental reasons why it is hard to fix this; see Output from Processes.)Otherwise the function
call-process
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) => 0 ---------- Buffer: foo ---------- /usr/user/lewis/manual ---------- Buffer: foo ---------- (call-process "grep" nil "bar" nil "lewis" "/etc/passwd") => 0 ---------- Buffer: bar ---------- lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh ---------- Buffer: bar ----------Here is a good example of the use of
call-process
, which used to be found in the definition ofinsert-directory
:(call-process insert-directory-program nil t nil switches (if full-directory-p (concat (file-name-as-directory file) ".") file))
This function sends the text from start to end as standard input to a process running program. It deletes the text sent if delete is non-
nil
; this is useful when destination ist
, to insert the output in the current buffer in place of the input.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 returnsnil
immediately, without waiting for the subprocess to finish (this only works if asynchronous subprocesses are supported).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 ofcall-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 thecat
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 ist
, this output is inserted in the current buffer.---------- Buffer: foo ---------- input-!- ---------- Buffer: foo ---------- (call-process-region 1 6 "cat" nil t) => 0 ---------- Buffer: foo ---------- inputinput-!- ---------- Buffer: foo ----------The
shell-command-on-region
command usescall-process-region
like this:(call-process-region start end shell-file-name ; Name of program. nil ; Do not delete region. buffer ; Send output tobuffer
. nil ; No redisplay during output. "-c" command) ; Arguments for the shell.