GNU Emacs Lisp Reference Manual

33.2: Creating a Synchronous Process

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 Quitting.

The synchronous subprocess functions returned nil in version 18. In version 19, they return an indication of how the process terminated.

Function: call-process program &optional infile destination display &rest args

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 /dev/null 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

Find or create a buffer with that name, then insert the output in that buffer, before point.

t

Insert the output in the current buffer, before point.

nil

Discard the output.

0

Discard the output, and return 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.

(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. The value 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))

Function: call-process-region start end program &optional delete destination display &rest args

This function sends the text between 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 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.