www.delorie.com/gnu/docs/elisp-manual-21/elisp_602.html   search  
Buy the book!

GNU Emacs Lisp Reference Manual

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

37.1 Functions that Create Subprocesses

There are three functions that create a new subprocess in which to run a program. One of them, start-process, creates an asynchronous process and returns a process object (see section 37.4 Creating an Asynchronous Process). The other two, call-process and call-process-region, create a synchronous process and do not return a process object (see section 37.3 Creating a Synchronous Process).

Synchronous and asynchronous processes are explained in the following sections. Since the three functions are all called in a similar fashion, their common arguments are described here.

In all cases, the function's program argument specifies the program to be run. An error is signaled if the file is not found or cannot be executed. If the file name is relative, the variable exec-path contains a list of directories to search. Emacs initializes exec-path when it starts up, based on the value of the environment variable PATH. The standard file name constructs, `~', `.', and `..', are interpreted as usual in exec-path, but environment variable substitutions (`$HOME', etc.) are not recognized; use substitute-in-file-name to perform them (see section 25.8.4 Functions that Expand Filenames).

Each of the subprocess-creating functions has a buffer-or-name argument which specifies where the standard output from the program will go. It should be a buffer or a buffer name; if it is a buffer name, that will create the buffer if it does not already exist. It can also be nil, which says to discard the output unless a filter function handles it. (See section 37.9.2 Process Filter Functions, and 19. Reading and Printing Lisp Objects.) Normally, you should avoid having multiple processes send output to the same buffer because their output would be intermixed randomly.

All three of the subprocess-creating functions have a &rest argument, args. The args must all be strings, and they are supplied to program as separate command line arguments. Wildcard characters and other shell constructs have no special meanings in these strings, since the whole strings are passed directly to the specified program.

Please note: The argument program contains only the name of the program; it may not contain any command-line arguments. You must use args to provide those.

The subprocess gets its current directory from the value of default-directory (see section 25.8.4 Functions that Expand Filenames).

The subprocess inherits its environment from Emacs, but you can specify overrides for it with process-environment. See section 40.3 Operating System Environment.

Variable: exec-directory
The value of this variable is a string, the name of a directory that contains programs that come with GNU Emacs, programs intended for Emacs to invoke. The program movemail is an example of such a program; Rmail uses it to fetch new mail from an inbox.

User Option: exec-path
The value of this variable is a list of directories to search for programs to run in subprocesses. Each element is either the name of a directory (i.e., a string), or nil, which stands for the default directory (which is the value of default-directory).

The value of exec-path is used by call-process and start-process when the program argument is not an absolute file name.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

  webmaster   donations   bookstore     delorie software   privacy  
  Copyright 2003   by The Free Software Foundation     Updated Jun 2003