37.9 Receiving Output from Processes

There are two ways to receive the output that a subprocess writes to its standard output stream. The output can be inserted in a buffer, which is called the associated buffer of the process, or a function called the filter function can be called to act on the output. If the process has no buffer and no filter function, its output is discarded. Output from a subprocess can arrive only while Emacs is waiting: when reading terminal input, in sit-for and sleep-for (see section 21.9 Waiting for Elapsed Time or Input), and in accept-process-output (see section 37.9.3 Accepting Output from Processes). This minimizes the problem of timing errors that usually plague parallel programming. For example, you can safely create a process and only then specify its buffer or filter function; no output can arrive before you finish, if the code in between does not call any primitive that waits.

It is impossible to separate the standard output and standard error streams of the subprocess, because Emacs normally spawns the subprocess inside a pseudo-TTY, and a pseudo-TTY has only one output channel. If you want to keep the output to those streams separate, you should redirect one of them to a file--for example, by using an appropriate shell command.

Subprocess output is normally decoded using a coding system before the buffer or filter function receives it, much like text read from a file. You can use set-process-coding-system to specify which coding system to use (see section 37.6 Process Information). Otherwise, the coding system comes from coding-system-for-read, if that is non-nil; or else from the defaulting mechanism (see section 33.10.5 Default Coding Systems).

Warning: Coding systems such as undecided which determine the coding system from the data do not work entirely reliably with asynchronous subprocess output. This is because Emacs has to process asynchronous subprocess output in batches, as it arrives. Emacs must try to detect the proper coding system from one batch at a time, and this does not always work. Therefore, if at all possible, use a coding system which determines both the character code conversion and the end of line conversion--that is, one like latin-1-unix, rather than undecided or latin-1.

37.9.1 Process Buffers		If no filter, output is put in a buffer.
37.9.2 Process Filter Functions		Filter functions accept output from the process.
37.9.3 Accepting Output from Processes		Explicitly permitting subprocess output. Waiting for subprocess output.