-\1f
-File: lispref.info, Node: Input to Processes, Next: Signals to Processes, Prev: Process Information, Up: Processes
-
-Sending Input to Processes
-==========================
-
- Asynchronous subprocesses receive input when it is sent to them by
-XEmacs, which is done with the functions in this section. You must
-specify the process to send input to, and the input data to send. The
-data appears on the "standard input" of the subprocess.
-
- Some operating systems have limited space for buffered input in a
-PTY. On these systems, Emacs sends an EOF periodically amidst the
-other characters, to force them through. For most programs, these EOFs
-do no harm.
-
- - Function: process-send-string process-name string
- This function sends PROCESS-NAME the contents of STRING as
- standard input. The argument PROCESS-NAME must be a process or
- the name of a process. If it is `nil', the current buffer's
- process is used.
-
- The function returns `nil'.
-
- (process-send-string "shell<1>" "ls\n")
- => nil
-
-
- ---------- Buffer: *shell* ----------
- ...
- introduction.texi syntax-tables.texi~
- introduction.texi~ text.texi
- introduction.txt text.texi~
- ...
- ---------- Buffer: *shell* ----------
-
- - Command: process-send-region process-name start end
- This function sends the text in the region defined by START and
- END as standard input to PROCESS-NAME, which is a process or a
- process name. (If it is `nil', the current buffer's process is
- used.)
-
- An error is signaled unless both START and END are integers or
- markers that indicate positions in the current buffer. (It is
- unimportant which number is larger.)
-
- - Function: process-send-eof &optional process-name
- This function makes PROCESS-NAME see an end-of-file in its input.
- The EOF comes after any text already sent to it.
-
- If PROCESS-NAME is not supplied, or if it is `nil', then this
- function sends the EOF to the current buffer's process. An error
- is signaled if the current buffer has no process.
-
- The function returns PROCESS-NAME.
-
- (process-send-eof "shell")
- => "shell"
-
-\1f
-File: lispref.info, Node: Signals to Processes, Next: Output from Processes, Prev: Input to Processes, Up: Processes
-
-Sending Signals to Processes
-============================
-
- "Sending a signal" to a subprocess is a way of interrupting its
-activities. There are several different signals, each with its own
-meaning. The set of signals and their names is defined by the operating
-system. For example, the signal `SIGINT' means that the user has typed
-`C-c', or that some analogous thing has happened.
-
- Each signal has a standard effect on the subprocess. Most signals
-kill the subprocess, but some stop or resume execution instead. Most
-signals can optionally be handled by programs; if the program handles
-the signal, then we can say nothing in general about its effects.
-
- The set of signals and their names is defined by the operating
-system; XEmacs has facilities for sending only a few of the signals
-that are defined. XEmacs can send signals only to its own subprocesses.
-
- You can send signals explicitly by calling the functions in this
-section. XEmacs also sends signals automatically at certain times:
-killing a buffer sends a `SIGHUP' signal to all its associated
-processes; killing XEmacs sends a `SIGHUP' signal to all remaining
-processes. (`SIGHUP' is a signal that indicates that the connection
-between the user and the process is broken, for example if a connection
-via a telephone line is hung up.)
-
- Each of the signal-sending functions takes two optional arguments:
-PROCESS and CURRENT-GROUP.
-
- The argument PROCESS must be either a process or a buffer, the name
-of one, or `nil'. If it is `nil', the process defaults to the process
-associated with the current buffer. An error is signaled if PROCESS
-does not identify a process.
-
- The argument CURRENT-GROUP is a flag that makes a difference when
-you are running a job-control shell as an XEmacs subprocess. If it is
-non-`nil', then the signal is sent to the current foreground process
-group of the terminal that XEmacs uses to communicate with the
-subprocess. If the process is a job-control shell, this means the
-shell's current subjob. If it is `nil', the signal is sent to the
-process group of the immediate subprocess of XEmacs. If the subprocess
-is a job-control shell, this is the shell itself.
-
- The flag CURRENT-GROUP has no effect when a pipe is used to
-communicate with the subprocess, because the operating system does not
-support the distinction in the case of pipes. For the same reason,
-job-control shells won't work when a pipe is used. See
-`process-connection-type' in *Note Asynchronous Processes::.
-
- Some of the functions below take a SIGNAL argument, which identifies
-a signal to be sent. It must be either an integer or a symbol which
-names the signal, like `SIGSEGV'.
-
- - Function: process-send-signal signal &optional process current-group
- This function sends the signal SIGNAL to the process PROCESS. The
- following functions can be implemented in terms of
- `process-send-signal'.
-
- - Function: interrupt-process &optional process current-group
- This function interrupts the process PROCESS by sending the signal
- `SIGINT'. Outside of XEmacs, typing the "interrupt character"
- (normally `C-c') sends this signal. When the argument
- CURRENT-GROUP is non-`nil', you can think of this function as
- "typing `C-c'" on the terminal by which XEmacs talks to the
- subprocess.
-
- - Function: kill-process &optional process current-group
- This function kills the process PROCESS by sending the signal
- `SIGKILL'. This signal kills the subprocess immediately, and
- cannot be handled by the subprocess.
-
- - Function: quit-process &optional process current-group
- This function sends the signal `SIGQUIT' to the process PROCESS.
- This signal is the one sent by the "quit character" (usually
- `C-\') when you are not inside XEmacs.
-
- - Function: stop-process &optional process current-group
- This function stops the process PROCESS by sending the signal
- `SIGTSTP'. Use `continue-process' to resume its execution.
-
- On systems with job control, the "stop character" (usually `C-z')
- sends this signal (outside of XEmacs). When CURRENT-GROUP is
- non-`nil', you can think of this function as "typing `C-z'" on the
- terminal XEmacs uses to communicate with the subprocess.
-
- - Function: continue-process &optional process current-group
- This function resumes execution of the process PROCESS by sending
- it the signal `SIGCONT'. This presumes that PROCESS was stopped
- previously.
-
- - Function: signal-process pid signal
- This function sends a signal to the process with process id PID,
- which need not be a child of XEmacs. The argument SIGNAL
- specifies which signal to send.
-
-\1f
-File: lispref.info, Node: Output from Processes, Next: Sentinels, Prev: Signals to Processes, Up: Processes
-
-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.
-
-* Menu:
-
-* Process Buffers:: If no filter, output is put in a buffer.
-* Filter Functions:: Filter functions accept output from the process.
-* Accepting Output:: Explicitly permitting subprocess output.
- Waiting for subprocess output.
-
-\1f
-File: lispref.info, Node: Process Buffers, Next: Filter Functions, Up: Output from Processes
-
-Process Buffers
----------------
-
- A process can (and usually does) have an "associated buffer", which
-is an ordinary Emacs buffer that is used for two purposes: storing the
-output from the process, and deciding when to kill the process. You
-can also use the buffer to identify a process to operate on, since in
-normal practice only one process is associated with any given buffer.
-Many applications of processes also use the buffer for editing input to
-be sent to the process, but this is not built into XEmacs Lisp.
-
- Unless the process has a filter function (*note Filter Functions::),
-its output is inserted in the associated buffer. The position to insert
-the output is determined by the `process-mark', which is then updated
-to point to the end of the text just inserted. Usually, but not
-always, the `process-mark' is at the end of the buffer.
-
- - Function: process-buffer process
- This function returns the associated buffer of the process PROCESS.
-
- (process-buffer (get-process "shell"))
- => #<buffer *shell*>
-
- - Function: process-mark process
- This function returns the process marker for PROCESS, which is the
- marker that says where to insert output from the process.
-
- If PROCESS does not have a buffer, `process-mark' returns a marker
- that points nowhere.
-
- Insertion of process output in a buffer uses this marker to decide
- where to insert, and updates it to point after the inserted text.
- That is why successive batches of output are inserted
- consecutively.
-
- Filter functions normally should use this marker in the same
- fashion as is done by direct insertion of output in the buffer. A
- good example of a filter function that uses `process-mark' is
- found at the end of the following section.
-
- When the user is expected to enter input in the process buffer for
- transmission to the process, the process marker is useful for
- distinguishing the new input from previous output.
-
- - Function: set-process-buffer process buffer
- This function sets the buffer associated with PROCESS to BUFFER.
- If BUFFER is `nil', the process becomes associated with no buffer.
-
- - Function: get-buffer-process buffer-or-name
- This function returns the process associated with BUFFER-OR-NAME.
- If there are several processes associated with it, then one is
- chosen. (Presently, the one chosen is the one most recently
- created.) It is usually a bad idea to have more than one process
- associated with the same buffer.
-
- (get-buffer-process "*shell*")
- => #<process shell>
-
- Killing the process's buffer deletes the process, which kills the
- subprocess with a `SIGHUP' signal (*note Signals to Processes::).
-
-\1f
-File: lispref.info, Node: Filter Functions, Next: Accepting Output, Prev: Process Buffers, Up: Output from Processes
-
-Process Filter Functions
-------------------------
-
- A process "filter function" is a function that receives the standard
-output from the associated process. If a process has a filter, then
-_all_ output from that process is passed to the filter. The process
-buffer is used directly for output from the process only when there is
-no filter.
-
- A filter function must accept two arguments: the associated process
-and a string, which is the output. The function is then free to do
-whatever it chooses with the output.
-
- A filter function runs only while XEmacs is waiting (e.g., for
-terminal input, or for time to elapse, or for process output). This
-avoids the timing errors that could result from running filters at
-random places in the middle of other Lisp programs. You may explicitly
-cause Emacs to wait, so that filter functions will run, by calling
-`sit-for' or `sleep-for' (*note Waiting::), or `accept-process-output'
-(*note Accepting Output::). Emacs is also waiting when the command loop
-is reading input.
-
- Quitting is normally inhibited within a filter function--otherwise,
-the effect of typing `C-g' at command level or to quit a user command
-would be unpredictable. If you want to permit quitting inside a filter
-function, bind `inhibit-quit' to `nil'. *Note Quitting::.
-
- If an error happens during execution of a filter function, it is
-caught automatically, so that it doesn't stop the execution of whatever
-program was running when the filter function was started. However, if
-`debug-on-error' is non-`nil', the error-catching is turned off. This
-makes it possible to use the Lisp debugger to debug the filter
-function. *Note Debugger::.
-
- Many filter functions sometimes or always insert the text in the
-process's buffer, mimicking the actions of XEmacs when there is no
-filter. Such filter functions need to use `set-buffer' in order to be
-sure to insert in that buffer. To avoid setting the current buffer
-semipermanently, these filter functions must use `unwind-protect' to
-make sure to restore the previous current buffer. They should also
-update the process marker, and in some cases update the value of point.
-Here is how to do these things:
-
- (defun ordinary-insertion-filter (proc string)
- (let ((old-buffer (current-buffer)))
- (unwind-protect
- (let (moving)
- (set-buffer (process-buffer proc))
- (setq moving (= (point) (process-mark proc)))
- (save-excursion
- ;; Insert the text, moving the process-marker.
- (goto-char (process-mark proc))
- (insert string)
- (set-marker (process-mark proc) (point)))
- (if moving (goto-char (process-mark proc))))
- (set-buffer old-buffer))))
-
-The reason to use an explicit `unwind-protect' rather than letting
-`save-excursion' restore the current buffer is so as to preserve the
-change in point made by `goto-char'.
-
- To make the filter force the process buffer to be visible whenever
-new text arrives, insert the following line just before the
-`unwind-protect':
-
- (display-buffer (process-buffer proc))
-
- To force point to move to the end of the new output no matter where
-it was previously, eliminate the variable `moving' and call `goto-char'
-unconditionally.
-
- In earlier Emacs versions, every filter function that did regexp
-searching or matching had to explicitly save and restore the match data.
-Now Emacs does this automatically; filter functions never need to do it
-explicitly. *Note Match Data::.
-
- A filter function that writes the output into the buffer of the
-process should check whether the buffer is still alive. If it tries to
-insert into a dead buffer, it will get an error. If the buffer is dead,
-`(buffer-name (process-buffer PROCESS))' returns `nil'.
-
- The output to the function may come in chunks of any size. A program
-that produces the same output twice in a row may send it as one batch
-of 200 characters one time, and five batches of 40 characters the next.
-
- - Function: set-process-filter process filter
- This function gives PROCESS the filter function FILTER. If FILTER
- is `nil', then the process will have no filter. If FILTER is `t',
- then no output from the process will be accepted until the filter
- is changed. (Output received during this time is not discarded,
- but is queued, and will be processed as soon as the filter is
- changed.)
-
- - Function: process-filter process
- This function returns the filter function of PROCESS, or `nil' if
- it has none. `t' means that output processing has been stopped.
-
- Here is an example of use of a filter function:
-
- (defun keep-output (process output)
- (setq kept (cons output kept)))
- => keep-output
- (setq kept nil)
- => nil
- (set-process-filter (get-process "shell") 'keep-output)
- => keep-output
- (process-send-string "shell" "ls ~/other\n")
- => nil
- kept
- => ("lewis@slug[8] % "
- "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
- address.txt backup.psf kolstad.psf
- backup.bib~ david.mss resume-Dec-86.mss~
- backup.err david.psf resume-Dec.psf
- backup.mss dland syllabus.mss
- "
- "#backups.mss# backup.mss~ kolstad.mss
- ")
-
-\1f
-File: lispref.info, Node: Accepting Output, Prev: Filter Functions, Up: Output from Processes
-
-Accepting Output from Processes
--------------------------------
-
- Output from asynchronous subprocesses normally arrives only while
-XEmacs is waiting for some sort of external event, such as elapsed time
-or terminal input. Occasionally it is useful in a Lisp program to
-explicitly permit output to arrive at a specific point, or even to wait
-until output arrives from a process.
-
- - Function: accept-process-output &optional process seconds millisec
- This function allows XEmacs to read pending output from processes.
- The output is inserted in the associated buffers or given to
- their filter functions. If PROCESS is non-`nil' then this
- function does not return until some output has been received from
- PROCESS.
-
- The arguments SECONDS and MILLISEC let you specify timeout
- periods. The former specifies a period measured in seconds and the
- latter specifies one measured in milliseconds. The two time
- periods thus specified are added together, and
- `accept-process-output' returns after that much time whether or
- not there has been any subprocess output. Note that SECONDS is
- allowed to be a floating-point number; thus, there is no need to
- ever use MILLISEC. (It is retained for compatibility purposes.)
-
- The function `accept-process-output' returns non-`nil' if it did
- get some output, or `nil' if the timeout expired before output
- arrived.
-