Function: call-process

call-process is a function defined in callproc.c.

Signature

(call-process PROGRAM &optional INFILE DESTINATION DISPLAY &rest ARGS)

Documentation

Call PROGRAM synchronously in separate process.

The remaining arguments are optional.

The program's input comes from file INFILE (nil means null-device(var)/null-device(fun)). If INFILE is a relative path, it will be looked for relative to the directory where the process is run (see below). If you want to make the input come from an Emacs buffer, use call-process-region instead.

Third argument DESTINATION specifies how to handle program's output.
("Output" here means both standard output and standard error
output.) If DESTINATION is a buffer or the name of a buffer, or t (which stands for the current buffer), it means insert output in that buffer before point. If DESTINATION is nil, it means discard output; 0 means discard
 and don't wait for the program to terminate.
If DESTINATION is (:file FILE), where FILE is a file name string,
 it means that output should be written to that file (if the file
 already exists it is overwritten).
DESTINATION can also have the form (REAL-BUFFER STDERR-FILE); in that case,
 REAL-BUFFER says what to do with standard output, as above,
 while STDERR-FILE says what to do with standard error in the child.
 STDERR-FILE may be nil (discard standard error output),
 t (mix it with ordinary output), or a file name string.

Fourth arg DISPLAY non-nil means redisplay buffer as output is inserted. Remaining arguments ARGS are strings passed as command arguments to PROGRAM.

If PROGRAM is not an absolute file name, call-process will look for PROGRAM in exec-path(var)/exec-path(fun) (which is a list of directories).

If executable PROGRAM can't be found as an executable, call-process signals a Lisp error. call-process reports errors in execution of the program only through its return and output.

If DESTINATION is 0, call-process returns immediately with value nil. Otherwise it waits for PROGRAM to terminate and returns a numeric exit status or a signal description string. If you quit, the process is killed with SIGINT, or SIGKILL if you quit again.

The process runs in default-directory if that is local (as determined by unhandled-file-name-directory), or "~" otherwise. If you want to run a process in a remote directory use process-file.

View in manual

Probably introduced at or before Emacs version 18.

Source Code

// Defined in /usr/src/emacs/src/callproc.c
{
  Lisp_Object infile, encoded_infile;
  int filefd;
  specpdl_ref count = SPECPDL_INDEX ();

  if (nargs >= 2 && ! NILP (args[1]))
    {
      /* Expand infile relative to the current buffer's current
	 directory, or its unhandled equivalent ("~").  */
      infile = Fexpand_file_name (args[1], get_current_directory (false));
      CHECK_STRING (infile);
    }
  else
    infile = build_string (NULL_DEVICE);

  /* Remove "/:" from INFILE.  */
  infile = remove_slash_colon (infile);

  encoded_infile = ENCODE_FILE (infile);

  filefd = emacs_open (SSDATA (encoded_infile), O_RDONLY, 0);
  if (filefd < 0)
    report_file_error ("Opening process input file", infile);
  record_unwind_protect_int (close_file_unwind, filefd);
  return unbind_to (count, call_process (nargs, args, filefd,
					 make_invalid_specpdl_ref ()));
}