GNU Info

Info Node: (elisp)Synchronous Processes

(elisp)Synchronous Processes


Next: Asynchronous Processes Prev: Shell Arguments Up: Processes
Enter node , (file) or (file)node

Creating a Synchronous Process
==============================

   After a "synchronous process" is created, Emacs waits for the
process to terminate before continuing.  Starting Dired on GNU or
Unix(1) 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 (except on MS-DOS, where killing other processes
doesn't work).  Note: Quitting.

   The synchronous subprocess functions return an indication of how the
process terminated.

   The output from a synchronous subprocess is generally decoded using a
coding system, much like text read from a file.  The input sent to a
subprocess by `call-process-region' is encoded using a coding system,
much like text written into a file.  Note: Coding Systems.

 - 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 the null device 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
          Insert the output in a buffer with that name, before point.

    `t'
          Insert the output in the current buffer, before point.

    `nil'
          Discard the output.

    0
          Discard the output, and return `nil' 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.

          MS-DOS doesn't support asynchronous subprocesses, so this
          option doesn't work there.

    `(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.  If ERROR-DESTINATION is `nil', that
          means to discard the error output, `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.  (However, if the coding system chosen for
     decoding output is `undecided', meaning deduce the encoding from
     the actual data, then redisplay sometimes cannot continue once
     non-ASCII characters are encountered.  There are fundamental
     reasons why it is hard to fix this; see Note: Output from
     Processes.)

     Otherwise the function `call-process' 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)
               => 0
          
          ---------- Buffer: foo ----------
          /usr/user/lewis/manual
          ---------- Buffer: foo ----------
          
          (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
               => 0
          
          ---------- Buffer: bar ----------
          lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
          
          ---------- Buffer: bar ----------

     Here is a good example of the use of `call-process', which used to
     be found in the definition of `insert-directory':

          (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 from 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 DESTINATION is `t', to insert
     the output in the current buffer in place of the input.

     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 (this only works if asynchronous
     subprocesses are supported).

     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)
               => 0
          
          ---------- 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.

 - Function: shell-command-to-string command
     This function executes COMMAND (a string) as a shell command, then
     returns the command's output as a string.

   ---------- Footnotes ----------

   (1) On other systems, Emacs uses a Lisp emulation of `ls'; see Note:
Contents of Directories.


automatically generated by info2www version 1.2.2.9