1 This is Info file ../../info/lispref.info, produced by Makeinfo version
2 1.68 from the input file lispref.texi.
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Working With a Database, Next: Other Database Functions, Prev: Connecting to a Database, Up: Databases
55 Working With a Database
56 =======================
58 - Function: get-database KEY DBASE &optional DEFAULT
59 This function finds the value for KEY in DATABASE. If there is no
60 corresponding value, DEFAULT is returned (`nil' if DEFAULT is
63 - Function: map-database FUNCTION DBASE
64 This function maps FUNCTION over entries in DATABASE, calling it
65 with two args, each key and value in the database.
67 - Function: put-database KEY VAL DBASE &optional REPLACE
68 This function stores KEY and VAL in DATABASE. If optional fourth
69 arg REPLACE is non-`nil', replace any existing entry in the
72 - Function: remove-database KEY DBASE
73 This function removes KEY from DATABASE.
76 File: lispref.info, Node: Other Database Functions, Prev: Working With a Database, Up: Databases
78 Other Database Functions
79 ========================
81 - Function: database-file-name OBJ
82 This function returns the filename associated with the database
85 - Function: database-last-error &optional OBJ
86 This function returns the last error associated with database OBJ.
88 - Function: database-subtype OBJ
89 This function returns the subtype of database OBJ, if any.
91 - Function: database-type OBJ
92 This function returns the type of database OBJ.
95 File: lispref.info, Node: Processes, Next: System Interface, Prev: Databases, Up: Top
100 In the terminology of operating systems, a "process" is a space in
101 which a program can execute. XEmacs runs in a process. XEmacs Lisp
102 programs can invoke other programs in processes of their own. These are
103 called "subprocesses" or "child processes" of the XEmacs process, which
104 is their "parent process".
106 A subprocess of XEmacs may be "synchronous" or "asynchronous",
107 depending on how it is created. When you create a synchronous
108 subprocess, the Lisp program waits for the subprocess to terminate
109 before continuing execution. When you create an asynchronous
110 subprocess, it can run in parallel with the Lisp program. This kind of
111 subprocess is represented within XEmacs by a Lisp object which is also
112 called a "process". Lisp programs can use this object to communicate
113 with the subprocess or to control it. For example, you can send
114 signals, obtain status information, receive output from the process, or
117 - Function: processp OBJECT
118 This function returns `t' if OBJECT is a process, `nil' otherwise.
122 * Subprocess Creation:: Functions that start subprocesses.
123 * Synchronous Processes:: Details of using synchronous subprocesses.
124 * MS-DOS Subprocesses:: On MS-DOS, you must indicate text vs binary
125 for data sent to and from a subprocess.
126 * Asynchronous Processes:: Starting up an asynchronous subprocess.
127 * Deleting Processes:: Eliminating an asynchronous subprocess.
128 * Process Information:: Accessing run-status and other attributes.
129 * Input to Processes:: Sending input to an asynchronous subprocess.
130 * Signals to Processes:: Stopping, continuing or interrupting
131 an asynchronous subprocess.
132 * Output from Processes:: Collecting output from an asynchronous subprocess.
133 * Sentinels:: Sentinels run when process run-status changes.
134 * Process Window Size:: Changing the logical window size of a process.
135 * Transaction Queues:: Transaction-based communication with subprocesses.
136 * Network:: Opening network connections.
139 File: lispref.info, Node: Subprocess Creation, Next: Synchronous Processes, Up: Processes
141 Functions that Create Subprocesses
142 ==================================
144 There are three functions that create a new subprocess in which to
145 run a program. One of them, `start-process', creates an asynchronous
146 process and returns a process object (*note Asynchronous Processes::.).
147 The other two, `call-process' and `call-process-region', create a
148 synchronous process and do not return a process object (*note
149 Synchronous Processes::.).
151 Synchronous and asynchronous processes are explained in following
152 sections. Since the three functions are all called in a similar
153 fashion, their common arguments are described here.
155 In all cases, the function's PROGRAM argument specifies the program
156 to be run. An error is signaled if the file is not found or cannot be
157 executed. If the file name is relative, the variable `exec-path'
158 contains a list of directories to search. Emacs initializes
159 `exec-path' when it starts up, based on the value of the environment
160 variable `PATH'. The standard file name constructs, `~', `.', and
161 `..', are interpreted as usual in `exec-path', but environment variable
162 substitutions (`$HOME', etc.) are not recognized; use
163 `substitute-in-file-name' to perform them (*note File Name
166 Each of the subprocess-creating functions has a BUFFER-OR-NAME
167 argument which specifies where the standard output from the program will
168 go. If BUFFER-OR-NAME is `nil', that says to discard the output unless
169 a filter function handles it. (*Note Filter Functions::, and *Note
170 Read and Print::.) Normally, you should avoid having multiple
171 processes send output to the same buffer because their output would be
174 All three of the subprocess-creating functions have a `&rest'
175 argument, ARGS. The ARGS must all be strings, and they are supplied to
176 PROGRAM as separate command line arguments. Wildcard characters and
177 other shell constructs are not allowed in these strings, since they are
178 passed directly to the specified program.
180 *Please note:* The argument PROGRAM contains only the name of the
181 program; it may not contain any command-line arguments. You must use
182 ARGS to provide those.
184 The subprocess gets its current directory from the value of
185 `default-directory' (*note File Name Expansion::.).
187 The subprocess inherits its environment from XEmacs; but you can
188 specify overrides for it with `process-environment'. *Note System
191 - Variable: exec-directory
192 The value of this variable is the name of a directory (a string)
193 that contains programs that come with XEmacs, that are intended
194 for XEmacs to invoke. The program `wakeup' is an example of such
195 a program; the `display-time' command uses it to get a reminder
198 - User Option: exec-path
199 The value of this variable is a list of directories to search for
200 programs to run in subprocesses. Each element is either the name
201 of a directory (i.e., a string), or `nil', which stands for the
202 default directory (which is the value of `default-directory').
204 The value of `exec-path' is used by `call-process' and
205 `start-process' when the PROGRAM argument is not an absolute file
209 File: lispref.info, Node: Synchronous Processes, Next: MS-DOS Subprocesses, Prev: Subprocess Creation, Up: Processes
211 Creating a Synchronous Process
212 ==============================
214 After a "synchronous process" is created, XEmacs waits for the
215 process to terminate before continuing. Starting Dired is an example of
216 this: it runs `ls' in a synchronous process, then modifies the output
217 slightly. Because the process is synchronous, the entire directory
218 listing arrives in the buffer before XEmacs tries to do anything with
221 While Emacs waits for the synchronous subprocess to terminate, the
222 user can quit by typing `C-g'. The first `C-g' tries to kill the
223 subprocess with a `SIGINT' signal; but it waits until the subprocess
224 actually terminates before quitting. If during that time the user
225 types another `C-g', that kills the subprocess instantly with `SIGKILL'
226 and quits immediately. *Note Quitting::.
228 The synchronous subprocess functions returned `nil' in version 18.
229 In version 19, they return an indication of how the process terminated.
231 - Function: call-process PROGRAM &optional INFILE DESTINATION DISPLAY
233 This function calls PROGRAM in a separate process and waits for it
236 The standard input for the process comes from file INFILE if
237 INFILE is not `nil' and from `/dev/null' otherwise. The argument
238 DESTINATION says where to put the process output. Here are the
242 Insert the output in that buffer, before point. This
243 includes both the standard output stream and the standard
244 error stream of the process.
247 Find or create a buffer with that name, then insert the
248 output in that buffer, before point.
251 Insert the output in the current buffer, before point.
257 Discard the output, and return immediately without waiting
258 for the subprocess to finish.
260 In this case, the process is not truly synchronous, since it
261 can run in parallel with Emacs; but you can think of it as
262 synchronous in that Emacs is essentially finished with the
263 subprocess as soon as this function returns.
265 (REAL-DESTINATION ERROR-DESTINATION)
266 Keep the standard output stream separate from the standard
267 error stream; deal with the ordinary output as specified by
268 REAL-DESTINATION, and dispose of the error output according
269 to ERROR-DESTINATION. The value `nil' means discard it, `t'
270 means mix it with the ordinary output, and a string specifies
271 a file name to redirect error output into.
273 You can't directly specify a buffer to put the error output
274 in; that is too difficult to implement. But you can achieve
275 this result by sending the error output to a temporary file
276 and then inserting the file into a buffer.
278 If DISPLAY is non-`nil', then `call-process' redisplays the buffer
279 as output is inserted. Otherwise the function does no redisplay,
280 and the results become visible on the screen only when XEmacs
281 redisplays that buffer in the normal course of events.
283 The remaining arguments, ARGS, are strings that specify command
284 line arguments for the program.
286 The value returned by `call-process' (unless you told it not to
287 wait) indicates the reason for process termination. A number
288 gives the exit status of the subprocess; 0 means success, and any
289 other value means failure. If the process terminated with a
290 signal, `call-process' returns a string describing the signal.
292 In the examples below, the buffer `foo' is current.
294 (call-process "pwd" nil t)
297 ---------- Buffer: foo ----------
298 /usr/user/lewis/manual
299 ---------- Buffer: foo ----------
301 (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
304 ---------- Buffer: bar ----------
305 lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
307 ---------- Buffer: bar ----------
309 The `insert-directory' function contains a good example of the use
312 (call-process insert-directory-program nil t nil switches
314 (concat (file-name-as-directory file) ".")
317 - Function: call-process-region START END PROGRAM &optional DELETE
318 DESTINATION DISPLAY &rest ARGS
319 This function sends the text between START to END as standard
320 input to a process running PROGRAM. It deletes the text sent if
321 DELETE is non-`nil'; this is useful when BUFFER is `t', to insert
322 the output in the current buffer.
324 The arguments DESTINATION and DISPLAY control what to do with the
325 output from the subprocess, and whether to update the display as
326 it comes in. For details, see the description of `call-process',
327 above. If DESTINATION is the integer 0, `call-process-region'
328 discards the output and returns `nil' immediately, without waiting
329 for the subprocess to finish.
331 The remaining arguments, ARGS, are strings that specify command
332 line arguments for the program.
334 The return value of `call-process-region' is just like that of
335 `call-process': `nil' if you told it to return without waiting;
336 otherwise, a number or string which indicates how the subprocess
339 In the following example, we use `call-process-region' to run the
340 `cat' utility, with standard input being the first five characters
341 in buffer `foo' (the word `input'). `cat' copies its standard
342 input into its standard output. Since the argument DESTINATION is
343 `t', this output is inserted in the current buffer.
345 ---------- Buffer: foo ----------
347 ---------- Buffer: foo ----------
349 (call-process-region 1 6 "cat" nil t)
352 ---------- Buffer: foo ----------
354 ---------- Buffer: foo ----------
356 The `shell-command-on-region' command uses `call-process-region'
361 shell-file-name ; Name of program.
362 nil ; Do not delete region.
363 buffer ; Send output to `buffer'.
364 nil ; No redisplay during output.
365 "-c" command) ; Arguments for the shell.
368 File: lispref.info, Node: MS-DOS Subprocesses, Next: Asynchronous Processes, Prev: Synchronous Processes, Up: Processes
373 On MS-DOS, you must indicate whether the data going to and from a
374 synchronous subprocess are text or binary. Text data requires
375 translation between the end-of-line convention used within Emacs (a
376 single newline character) and the convention used outside Emacs (the
377 two-character sequence, CRLF).
379 The variable `binary-process-input' applies to input sent to the
380 subprocess, and `binary-process-output' applies to output received from
381 it. A non-`nil' value means the data is non-text; `nil' means the data
382 is text, and calls for conversion.
384 - Variable: binary-process-input
385 If this variable is `nil', convert newlines to CRLF sequences in
386 the input to a synchronous subprocess.
388 - Variable: binary-process-output
389 If this variable is `nil', convert CRLF sequences to newlines in
390 the output from a synchronous subprocess.
392 *Note Files and MS-DOS::, for related information.
395 File: lispref.info, Node: Asynchronous Processes, Next: Deleting Processes, Prev: MS-DOS Subprocesses, Up: Processes
397 Creating an Asynchronous Process
398 ================================
400 After an "asynchronous process" is created, Emacs and the Lisp
401 program both continue running immediately. The process may thereafter
402 run in parallel with Emacs, and the two may communicate with each other
403 using the functions described in following sections. Here we describe
404 how to create an asynchronous process with `start-process'.
406 - Function: start-process NAME BUFFER-OR-NAME PROGRAM &rest ARGS
407 This function creates a new asynchronous subprocess and starts the
408 program PROGRAM running in it. It returns a process object that
409 stands for the new subprocess in Lisp. The argument NAME
410 specifies the name for the process object; if a process with this
411 name already exists, then NAME is modified (by adding `<1>', etc.)
412 to be unique. The buffer BUFFER-OR-NAME is the buffer to
413 associate with the process.
415 The remaining arguments, ARGS, are strings that specify command
416 line arguments for the program.
418 In the example below, the first process is started and runs
419 (rather, sleeps) for 100 seconds. Meanwhile, the second process
420 is started, and given the name `my-process<1>' for the sake of
421 uniqueness. It inserts the directory listing at the end of the
422 buffer `foo', before the first process finishes. Then it
423 finishes, and a message to that effect is inserted in the buffer.
424 Much later, the first process finishes, and another message is
425 inserted in the buffer for it.
427 (start-process "my-process" "foo" "sleep" "100")
428 => #<process my-process>
430 (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
431 => #<process my-process<1>>
433 ---------- Buffer: foo ----------
435 lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs
436 -rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon
438 Process my-process<1> finished
440 Process my-process finished
441 ---------- Buffer: foo ----------
443 - Function: start-process-shell-command NAME BUFFER-OR-NAME COMMAND
445 This function is like `start-process' except that it uses a shell
446 to execute the specified command. The argument COMMAND is a shell
447 command name, and COMMAND-ARGS are the arguments for the shell
450 - Variable: process-connection-type
451 This variable controls the type of device used to communicate with
452 asynchronous subprocesses. If it is non-`nil', then PTYs are
453 used, when available. Otherwise, pipes are used.
455 PTYs are usually preferable for processes visible to the user, as
456 in Shell mode, because they allow job control (`C-c', `C-z', etc.)
457 to work between the process and its children whereas pipes do not.
458 For subprocesses used for internal purposes by programs, it is
459 often better to use a pipe, because they are more efficient. In
460 addition, the total number of PTYs is limited on many systems and
461 it is good not to waste them.
463 The value `process-connection-type' is used when `start-process'
464 is called. So you can specify how to communicate with one
465 subprocess by binding the variable around the call to
468 (let ((process-connection-type nil)) ; Use a pipe.
471 To determine whether a given subprocess actually got a pipe or a
472 PTY, use the function `process-tty-name' (*note Process
476 File: lispref.info, Node: Deleting Processes, Next: Process Information, Prev: Asynchronous Processes, Up: Processes
481 "Deleting a process" disconnects XEmacs immediately from the
482 subprocess, and removes it from the list of active processes. It sends
483 a signal to the subprocess to make the subprocess terminate, but this is
484 not guaranteed to happen immediately. The process object itself
485 continues to exist as long as other Lisp objects point to it.
487 You can delete a process explicitly at any time. Processes are
488 deleted automatically after they terminate, but not necessarily right
489 away. If you delete a terminated process explicitly before it is
490 deleted automatically, no harm results.
492 - Variable: delete-exited-processes
493 This variable controls automatic deletion of processes that have
494 terminated (due to calling `exit' or to a signal). If it is
495 `nil', then they continue to exist until the user runs
496 `list-processes'. Otherwise, they are deleted immediately after
499 - Function: delete-process NAME
500 This function deletes the process associated with NAME, killing it
501 with a `SIGHUP' signal. The argument NAME may be a process, the
502 name of a process, a buffer, or the name of a buffer.
504 (delete-process "*shell*")
507 - Function: process-kill-without-query PROCESS &optional
509 This function declares that XEmacs need not query the user if
510 PROCESS is still running when XEmacs is exited. The process will
511 be deleted silently. If REQUIRE-QUERY-P is non-`nil', then XEmacs
512 *will* query the user (this is the default). The return value is
513 `t' if a query was formerly required, and `nil' otherwise.
515 (process-kill-without-query (get-process "shell"))
519 File: lispref.info, Node: Process Information, Next: Input to Processes, Prev: Deleting Processes, Up: Processes
524 Several functions return information about processes.
525 `list-processes' is provided for interactive use.
527 - Command: list-processes
528 This command displays a listing of all living processes. In
529 addition, it finally deletes any process whose status was `Exited'
530 or `Signaled'. It returns `nil'.
532 - Function: process-list
533 This function returns a list of all processes that have not been
537 => (#<process display-time> #<process shell>)
539 - Function: get-process NAME
540 This function returns the process named NAME, or `nil' if there is
541 none. An error is signaled if NAME is not a string.
543 (get-process "shell")
546 - Function: process-command PROCESS
547 This function returns the command that was executed to start
548 PROCESS. This is a list of strings, the first string being the
549 program executed and the rest of the strings being the arguments
550 that were given to the program.
552 (process-command (get-process "shell"))
555 - Function: process-id PROCESS
556 This function returns the PID of PROCESS. This is an integer that
557 distinguishes the process PROCESS from all other processes running
558 on the same computer at the current time. The PID of a process is
559 chosen by the operating system kernel when the process is started
560 and remains constant as long as the process exists.
562 - Function: process-name PROCESS
563 This function returns the name of PROCESS.
565 - Function: process-status PROCESS-NAME
566 This function returns the status of PROCESS-NAME as a symbol. The
567 argument PROCESS-NAME must be a process, a buffer, a process name
568 (string) or a buffer name (string).
570 The possible values for an actual subprocess are:
573 for a process that is running.
576 for a process that is stopped but continuable.
579 for a process that has exited.
582 for a process that has received a fatal signal.
585 for a network connection that is open.
588 for a network connection that is closed. Once a connection
589 is closed, you cannot reopen it, though you might be able to
590 open a new connection to the same place.
593 if PROCESS-NAME is not the name of an existing process.
595 (process-status "shell")
598 (process-status (get-buffer "*shell*"))
606 For a network connection, `process-status' returns one of the
607 symbols `open' or `closed'. The latter means that the other side
608 closed the connection, or XEmacs did `delete-process'.
610 In earlier Emacs versions (prior to version 19), the status of a
611 network connection was `run' if open, and `exit' if closed.
613 - Function: process-kill-without-query-p PROCESS
614 This function returns whether PROCESS will be killed without
615 querying the user, if it is running when XEmacs is exited. The
616 default value is `nil'.
618 - Function: process-exit-status PROCESS
619 This function returns the exit status of PROCESS or the signal
620 number that killed it. (Use the result of `process-status' to
621 determine which of those it is.) If PROCESS has not yet
622 terminated, the value is 0.
624 - Function: process-tty-name PROCESS
625 This function returns the terminal name that PROCESS is using for
626 its communication with Emacs--or `nil' if it is using pipes
627 instead of a terminal (see `process-connection-type' in *Note
628 Asynchronous Processes::).
631 File: lispref.info, Node: Input to Processes, Next: Signals to Processes, Prev: Process Information, Up: Processes
633 Sending Input to Processes
634 ==========================
636 Asynchronous subprocesses receive input when it is sent to them by
637 XEmacs, which is done with the functions in this section. You must
638 specify the process to send input to, and the input data to send. The
639 data appears on the "standard input" of the subprocess.
641 Some operating systems have limited space for buffered input in a
642 PTY. On these systems, Emacs sends an EOF periodically amidst the
643 other characters, to force them through. For most programs, these EOFs
646 - Function: process-send-string PROCESS-NAME STRING
647 This function sends PROCESS-NAME the contents of STRING as
648 standard input. The argument PROCESS-NAME must be a process or
649 the name of a process. If it is `nil', the current buffer's
652 The function returns `nil'.
654 (process-send-string "shell<1>" "ls\n")
657 ---------- Buffer: *shell* ----------
659 introduction.texi syntax-tables.texi~
660 introduction.texi~ text.texi
661 introduction.txt text.texi~
663 ---------- Buffer: *shell* ----------
665 - Command: process-send-region PROCESS-NAME START END
666 This function sends the text in the region defined by START and
667 END as standard input to PROCESS-NAME, which is a process or a
668 process name. (If it is `nil', the current buffer's process is
671 An error is signaled unless both START and END are integers or
672 markers that indicate positions in the current buffer. (It is
673 unimportant which number is larger.)
675 - Function: process-send-eof &optional PROCESS-NAME
676 This function makes PROCESS-NAME see an end-of-file in its input.
677 The EOF comes after any text already sent to it.
679 If PROCESS-NAME is not supplied, or if it is `nil', then this
680 function sends the EOF to the current buffer's process. An error
681 is signaled if the current buffer has no process.
683 The function returns PROCESS-NAME.
685 (process-send-eof "shell")
689 File: lispref.info, Node: Signals to Processes, Next: Output from Processes, Prev: Input to Processes, Up: Processes
691 Sending Signals to Processes
692 ============================
694 "Sending a signal" to a subprocess is a way of interrupting its
695 activities. There are several different signals, each with its own
696 meaning. The set of signals and their names is defined by the operating
697 system. For example, the signal `SIGINT' means that the user has typed
698 `C-c', or that some analogous thing has happened.
700 Each signal has a standard effect on the subprocess. Most signals
701 kill the subprocess, but some stop or resume execution instead. Most
702 signals can optionally be handled by programs; if the program handles
703 the signal, then we can say nothing in general about its effects.
705 The set of signals and their names is defined by the operating
706 system; XEmacs has facilities for sending only a few of the signals
707 that are defined. XEmacs can send signals only to its own subprocesses.
709 You can send signals explicitly by calling the functions in this
710 section. XEmacs also sends signals automatically at certain times:
711 killing a buffer sends a `SIGHUP' signal to all its associated
712 processes; killing XEmacs sends a `SIGHUP' signal to all remaining
713 processes. (`SIGHUP' is a signal that usually indicates that the user
716 Each of the signal-sending functions takes two optional arguments:
717 PROCESS-NAME and CURRENT-GROUP.
719 The argument PROCESS-NAME must be either a process, the name of one,
720 or `nil'. If it is `nil', the process defaults to the process
721 associated with the current buffer. An error is signaled if
722 PROCESS-NAME does not identify a process.
724 The argument CURRENT-GROUP is a flag that makes a difference when
725 you are running a job-control shell as an XEmacs subprocess. If it is
726 non-`nil', then the signal is sent to the current process-group of the
727 terminal that XEmacs uses to communicate with the subprocess. If the
728 process is a job-control shell, this means the shell's current subjob.
729 If it is `nil', the signal is sent to the process group of the
730 immediate subprocess of XEmacs. If the subprocess is a job-control
731 shell, this is the shell itself.
733 The flag CURRENT-GROUP has no effect when a pipe is used to
734 communicate with the subprocess, because the operating system does not
735 support the distinction in the case of pipes. For the same reason,
736 job-control shells won't work when a pipe is used. See
737 `process-connection-type' in *Note Asynchronous Processes::.
739 - Function: interrupt-process &optional PROCESS-NAME CURRENT-GROUP
740 This function interrupts the process PROCESS-NAME by sending the
741 signal `SIGINT'. Outside of XEmacs, typing the "interrupt
742 character" (normally `C-c' on some systems, and `DEL' on others)
743 sends this signal. When the argument CURRENT-GROUP is non-`nil',
744 you can think of this function as "typing `C-c'" on the terminal
745 by which XEmacs talks to the subprocess.
747 - Function: kill-process &optional PROCESS-NAME CURRENT-GROUP
748 This function kills the process PROCESS-NAME by sending the signal
749 `SIGKILL'. This signal kills the subprocess immediately, and
750 cannot be handled by the subprocess.
752 - Function: quit-process &optional PROCESS-NAME CURRENT-GROUP
753 This function sends the signal `SIGQUIT' to the process
754 PROCESS-NAME. This signal is the one sent by the "quit character"
755 (usually `C-b' or `C-\') when you are not inside XEmacs.
757 - Function: stop-process &optional PROCESS-NAME CURRENT-GROUP
758 This function stops the process PROCESS-NAME by sending the signal
759 `SIGTSTP'. Use `continue-process' to resume its execution.
761 On systems with job control, the "stop character" (usually `C-z')
762 sends this signal (outside of XEmacs). When CURRENT-GROUP is
763 non-`nil', you can think of this function as "typing `C-z'" on the
764 terminal XEmacs uses to communicate with the subprocess.
766 - Function: continue-process &optional PROCESS-NAME CURRENT-GROUP
767 This function resumes execution of the process PROCESS by sending
768 it the signal `SIGCONT'. This presumes that PROCESS-NAME was
771 - Function: signal-process PID SIGNAL
772 This function sends a signal to process PID, which need not be a
773 child of XEmacs. The argument SIGNAL specifies which signal to
774 send; it should be an integer.
777 File: lispref.info, Node: Output from Processes, Next: Sentinels, Prev: Signals to Processes, Up: Processes
779 Receiving Output from Processes
780 ===============================
782 There are two ways to receive the output that a subprocess writes to
783 its standard output stream. The output can be inserted in a buffer,
784 which is called the associated buffer of the process, or a function
785 called the "filter function" can be called to act on the output. If
786 the process has no buffer and no filter function, its output is
791 * Process Buffers:: If no filter, output is put in a buffer.
792 * Filter Functions:: Filter functions accept output from the process.
793 * Accepting Output:: Explicitly permitting subprocess output.
794 Waiting for subprocess output.
797 File: lispref.info, Node: Process Buffers, Next: Filter Functions, Up: Output from Processes
802 A process can (and usually does) have an "associated buffer", which
803 is an ordinary Emacs buffer that is used for two purposes: storing the
804 output from the process, and deciding when to kill the process. You
805 can also use the buffer to identify a process to operate on, since in
806 normal practice only one process is associated with any given buffer.
807 Many applications of processes also use the buffer for editing input to
808 be sent to the process, but this is not built into XEmacs Lisp.
810 Unless the process has a filter function (*note Filter Functions::.),
811 its output is inserted in the associated buffer. The position to insert
812 the output is determined by the `process-mark', which is then updated
813 to point to the end of the text just inserted. Usually, but not
814 always, the `process-mark' is at the end of the buffer.
816 - Function: process-buffer PROCESS
817 This function returns the associated buffer of the process PROCESS.
819 (process-buffer (get-process "shell"))
822 - Function: process-mark PROCESS
823 This function returns the process marker for PROCESS, which is the
824 marker that says where to insert output from the process.
826 If PROCESS does not have a buffer, `process-mark' returns a marker
829 Insertion of process output in a buffer uses this marker to decide
830 where to insert, and updates it to point after the inserted text.
831 That is why successive batches of output are inserted
834 Filter functions normally should use this marker in the same
835 fashion as is done by direct insertion of output in the buffer. A
836 good example of a filter function that uses `process-mark' is
837 found at the end of the following section.
839 When the user is expected to enter input in the process buffer for
840 transmission to the process, the process marker is useful for
841 distinguishing the new input from previous output.
843 - Function: set-process-buffer PROCESS BUFFER
844 This function sets the buffer associated with PROCESS to BUFFER.
845 If BUFFER is `nil', the process becomes associated with no buffer.
847 - Function: get-buffer-process BUFFER-OR-NAME
848 This function returns the process associated with BUFFER-OR-NAME.
849 If there are several processes associated with it, then one is
850 chosen. (Presently, the one chosen is the one most recently
851 created.) It is usually a bad idea to have more than one process
852 associated with the same buffer.
854 (get-buffer-process "*shell*")
857 Killing the process's buffer deletes the process, which kills the
858 subprocess with a `SIGHUP' signal (*note Signals to Processes::.).
861 File: lispref.info, Node: Filter Functions, Next: Accepting Output, Prev: Process Buffers, Up: Output from Processes
863 Process Filter Functions
864 ------------------------
866 A process "filter function" is a function that receives the standard
867 output from the associated process. If a process has a filter, then
868 *all* output from that process is passed to the filter. The process
869 buffer is used directly for output from the process only when there is
872 A filter function must accept two arguments: the associated process
873 and a string, which is the output. The function is then free to do
874 whatever it chooses with the output.
876 A filter function runs only while XEmacs is waiting (e.g., for
877 terminal input, or for time to elapse, or for process output). This
878 avoids the timing errors that could result from running filters at
879 random places in the middle of other Lisp programs. You may explicitly
880 cause Emacs to wait, so that filter functions will run, by calling
881 `sit-for' or `sleep-for' (*note Waiting::.), or `accept-process-output'
882 (*note Accepting Output::.). Emacs is also waiting when the command
883 loop is reading input.
885 Quitting is normally inhibited within a filter function--otherwise,
886 the effect of typing `C-g' at command level or to quit a user command
887 would be unpredictable. If you want to permit quitting inside a filter
888 function, bind `inhibit-quit' to `nil'. *Note Quitting::.
890 If an error happens during execution of a filter function, it is
891 caught automatically, so that it doesn't stop the execution of whatever
892 program was running when the filter function was started. However, if
893 `debug-on-error' is non-`nil', the error-catching is turned off. This
894 makes it possible to use the Lisp debugger to debug the filter
895 function. *Note Debugger::.
897 Many filter functions sometimes or always insert the text in the
898 process's buffer, mimicking the actions of XEmacs when there is no
899 filter. Such filter functions need to use `set-buffer' in order to be
900 sure to insert in that buffer. To avoid setting the current buffer
901 semipermanently, these filter functions must use `unwind-protect' to
902 make sure to restore the previous current buffer. They should also
903 update the process marker, and in some cases update the value of point.
904 Here is how to do these things:
906 (defun ordinary-insertion-filter (proc string)
907 (let ((old-buffer (current-buffer)))
910 (set-buffer (process-buffer proc))
911 (setq moving (= (point) (process-mark proc)))
914 ;; Insert the text, moving the process-marker.
915 (goto-char (process-mark proc))
917 (set-marker (process-mark proc) (point)))
918 (if moving (goto-char (process-mark proc))))
919 (set-buffer old-buffer))))
921 The reason to use an explicit `unwind-protect' rather than letting
922 `save-excursion' restore the current buffer is so as to preserve the
923 change in point made by `goto-char'.
925 To make the filter force the process buffer to be visible whenever
926 new text arrives, insert the following line just before the
929 (display-buffer (process-buffer proc))
931 To force point to move to the end of the new output no matter where
932 it was previously, eliminate the variable `moving' and call `goto-char'
935 In earlier Emacs versions, every filter function that did regexp
936 searching or matching had to explicitly save and restore the match data.
937 Now Emacs does this automatically; filter functions never need to do it
938 explicitly. *Note Match Data::.
940 A filter function that writes the output into the buffer of the
941 process should check whether the buffer is still alive. If it tries to
942 insert into a dead buffer, it will get an error. If the buffer is dead,
943 `(buffer-name (process-buffer PROCESS))' returns `nil'.
945 The output to the function may come in chunks of any size. A program
946 that produces the same output twice in a row may send it as one batch
947 of 200 characters one time, and five batches of 40 characters the next.
949 - Function: set-process-filter PROCESS FILTER
950 This function gives PROCESS the filter function FILTER. If FILTER
951 is `nil', then the process will have no filter. If FILTER is `t',
952 then no output from the process will be accepted until the filter
953 is changed. (Output received during this time is not discarded,
954 but is queued, and will be processed as soon as the filter is
957 - Function: process-filter PROCESS
958 This function returns the filter function of PROCESS, or `nil' if
959 it has none. `t' means that output processing has been stopped.
961 Here is an example of use of a filter function:
963 (defun keep-output (process output)
964 (setq kept (cons output kept)))
970 (set-process-filter (get-process "shell") 'keep-output)
973 (process-send-string "shell" "ls ~/other\n")
976 => ("lewis@slug[8] % "
978 "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
979 address.txt backup.psf kolstad.psf
980 backup.bib~ david.mss resume-Dec-86.mss~
981 backup.err david.psf resume-Dec.psf
982 backup.mss dland syllabus.mss
984 "#backups.mss# backup.mss~ kolstad.mss
988 File: lispref.info, Node: Accepting Output, Prev: Filter Functions, Up: Output from Processes
990 Accepting Output from Processes
991 -------------------------------
993 Output from asynchronous subprocesses normally arrives only while
994 XEmacs is waiting for some sort of external event, such as elapsed time
995 or terminal input. Occasionally it is useful in a Lisp program to
996 explicitly permit output to arrive at a specific point, or even to wait
997 until output arrives from a process.
999 - Function: accept-process-output &optional PROCESS SECONDS MILLISEC
1000 This function allows XEmacs to read pending output from processes.
1001 The output is inserted in the associated buffers or given to
1002 their filter functions. If PROCESS is non-`nil' then this
1003 function does not return until some output has been received from
1006 The arguments SECONDS and MILLISEC let you specify timeout
1007 periods. The former specifies a period measured in seconds and the
1008 latter specifies one measured in milliseconds. The two time
1009 periods thus specified are added together, and
1010 `accept-process-output' returns after that much time whether or
1011 not there has been any subprocess output. Note that SECONDS is
1012 allowed to be a floating-point number; thus, there is no need to
1013 ever use MILLISEC. (It is retained for compatibility purposes.)
1015 The function `accept-process-output' returns non-`nil' if it did
1016 get some output, or `nil' if the timeout expired before output
1020 File: lispref.info, Node: Sentinels, Next: Process Window Size, Prev: Output from Processes, Up: Processes
1022 Sentinels: Detecting Process Status Changes
1023 ===========================================
1025 A "process sentinel" is a function that is called whenever the
1026 associated process changes status for any reason, including signals
1027 (whether sent by XEmacs or caused by the process's own actions) that
1028 terminate, stop, or continue the process. The process sentinel is also
1029 called if the process exits. The sentinel receives two arguments: the
1030 process for which the event occurred, and a string describing the type
1033 The string describing the event looks like one of the following:
1037 * `"exited abnormally with code EXITCODE\n"'.
1039 * `"NAME-OF-SIGNAL\n"'.
1041 * `"NAME-OF-SIGNAL (core dumped)\n"'.
1043 A sentinel runs only while XEmacs is waiting (e.g., for terminal
1044 input, or for time to elapse, or for process output). This avoids the
1045 timing errors that could result from running them at random places in
1046 the middle of other Lisp programs. A program can wait, so that
1047 sentinels will run, by calling `sit-for' or `sleep-for' (*note
1048 Waiting::.), or `accept-process-output' (*note Accepting Output::.).
1049 Emacs is also waiting when the command loop is reading input.
1051 Quitting is normally inhibited within a sentinel--otherwise, the
1052 effect of typing `C-g' at command level or to quit a user command would
1053 be unpredictable. If you want to permit quitting inside a sentinel,
1054 bind `inhibit-quit' to `nil'. *Note Quitting::.
1056 A sentinel that writes the output into the buffer of the process
1057 should check whether the buffer is still alive. If it tries to insert
1058 into a dead buffer, it will get an error. If the buffer is dead,
1059 `(buffer-name (process-buffer PROCESS))' returns `nil'.
1061 If an error happens during execution of a sentinel, it is caught
1062 automatically, so that it doesn't stop the execution of whatever
1063 programs was running when the sentinel was started. However, if
1064 `debug-on-error' is non-`nil', the error-catching is turned off. This
1065 makes it possible to use the Lisp debugger to debug the sentinel.
1068 In earlier Emacs versions, every sentinel that did regexp searching
1069 or matching had to explicitly save and restore the match data. Now
1070 Emacs does this automatically; sentinels never need to do it explicitly.
1073 - Function: set-process-sentinel PROCESS SENTINEL
1074 This function associates SENTINEL with PROCESS. If SENTINEL is
1075 `nil', then the process will have no sentinel. The default
1076 behavior when there is no sentinel is to insert a message in the
1077 process's buffer when the process status changes.
1079 (defun msg-me (process event)
1081 (format "Process: %s had the event `%s'" process event)))
1082 (set-process-sentinel (get-process "shell") 'msg-me)
1085 (kill-process (get-process "shell"))
1086 -| Process: #<process shell> had the event `killed'
1089 - Function: process-sentinel PROCESS
1090 This function returns the sentinel of PROCESS, or `nil' if it has
1093 - Function: waiting-for-user-input-p
1094 While a sentinel or filter function is running, this function
1095 returns non-`nil' if XEmacs was waiting for keyboard input from
1096 the user at the time the sentinel or filter function was called,
1097 `nil' if it was not.
1100 File: lispref.info, Node: Process Window Size, Next: Transaction Queues, Prev: Sentinels, Up: Processes
1105 - Function: set-process-window-size PROCESS HEIGHT WIDTH
1106 This function tells PROCESS that its logical window size is HEIGHT
1107 by WIDTH characters. This is principally useful with pty's.
1110 File: lispref.info, Node: Transaction Queues, Next: Network, Prev: Process Window Size, Up: Processes
1115 You can use a "transaction queue" for more convenient communication
1116 with subprocesses using transactions. First use `tq-create' to create
1117 a transaction queue communicating with a specified process. Then you
1118 can call `tq-enqueue' to send a transaction.
1120 - Function: tq-create PROCESS
1121 This function creates and returns a transaction queue
1122 communicating with PROCESS. The argument PROCESS should be a
1123 subprocess capable of sending and receiving streams of bytes. It
1124 may be a child process, or it may be a TCP connection to a server,
1125 possibly on another machine.
1127 - Function: tq-enqueue QUEUE QUESTION REGEXP CLOSURE FN
1128 This function sends a transaction to queue QUEUE. Specifying the
1129 queue has the effect of specifying the subprocess to talk to.
1131 The argument QUESTION is the outgoing message that starts the
1132 transaction. The argument FN is the function to call when the
1133 corresponding answer comes back; it is called with two arguments:
1134 CLOSURE, and the answer received.
1136 The argument REGEXP is a regular expression that should match the
1137 entire answer, but nothing less; that's how `tq-enqueue' determines
1138 where the answer ends.
1140 The return value of `tq-enqueue' itself is not meaningful.
1142 - Function: tq-close QUEUE
1143 Shut down transaction queue QUEUE, waiting for all pending
1144 transactions to complete, and then terminate the connection or
1147 Transaction queues are implemented by means of a filter function.
1148 *Note Filter Functions::.
1151 File: lispref.info, Node: Network, Prev: Transaction Queues, Up: Processes
1156 XEmacs Lisp programs can open TCP network connections to other
1157 processes on the same machine or other machines. A network connection
1158 is handled by Lisp much like a subprocess, and is represented by a
1159 process object. However, the process you are communicating with is not
1160 a child of the XEmacs process, so you can't kill it or send it signals.
1161 All you can do is send and receive data. `delete-process' closes the
1162 connection, but does not kill the process at the other end; that
1163 process must decide what to do about closure of the connection.
1165 You can distinguish process objects representing network connections
1166 from those representing subprocesses with the `process-status'
1167 function. It always returns either `open' or `closed' for a network
1168 connection, and it never returns either of those values for a real
1169 subprocess. *Note Process Information::.
1171 - Function: open-network-stream NAME BUFFER-OR-NAME HOST SERVICE
1172 This function opens a TCP connection for a service to a host. It
1173 returns a process object to represent the connection.
1175 The NAME argument specifies the name for the process object. It
1176 is modified as necessary to make it unique.
1178 The BUFFER-OR-NAME argument is the buffer to associate with the
1179 connection. Output from the connection is inserted in the buffer,
1180 unless you specify a filter function to handle the output. If
1181 BUFFER-OR-NAME is `nil', it means that the connection is not
1182 associated with any buffer.
1184 The arguments HOST and SERVICE specify where to connect to; HOST
1185 is the host name or IP address (a string), and SERVICE is the name
1186 of a defined network service (a string) or a port number (an
projects / chise / xemacs-chise.git.1 / blob