Next: Asynchronous Processes, Previous: Subprocess Creation, Up: Processes [Contents][Index]
After a synchronous process is created, SXEmacs 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 SXEmacs tries to do
anything with it.
While SXEmacs 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.
Note: The synchronous subprocess functions returned nil
in
FSF Emacs 18. In version 19, they return an indication of how the
process terminated.
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:
Insert the output in that buffer, before point. This includes both the standard output stream and the standard error stream of the process.
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.
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 SXEmacs; but you can think of it as synchronous in that SXEmacs is essentially finished with the subprocess as soon as this function returns.
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 SXEmacs
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))
This function sends the text between start to end as
standard input to a process running program. It deletes the text
sent if deletep is non-nil
; this is useful when buffer
is t
, to insert the output in the current buffer.
The arguments destination and displayp 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.
Next: Asynchronous Processes, Previous: Subprocess Creation, Up: Processes [Contents][Index]