1 This is ../info/lispref.info, produced by makeinfo version 4.0b from
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: Input to Processes, Next: Signals to Processes, Prev: Process Information, Up: Processes
55 Sending Input to Processes
56 ==========================
58 Asynchronous subprocesses receive input when it is sent to them by
59 XEmacs, which is done with the functions in this section. You must
60 specify the process to send input to, and the input data to send. The
61 data appears on the "standard input" of the subprocess.
63 Some operating systems have limited space for buffered input in a
64 PTY. On these systems, XEmacs sends long input in chunks, with EOF
65 characters added amidst the other characters, to force the operating
66 system to periodically drain the input buffer. For most programs,
67 these EOFs do no harm.
69 - Function: process-send-string process string &optional start end
70 This function sends PROCESS the contents of STRING as standard
73 The argument PROCESS may be a process or the name of a process, or
74 a buffer or the name of a buffer, in which case the buffer's
75 process is used. If it is `nil', the current buffer's process is
78 Optional arguments START and END specify part of STRING; see
81 The function returns `nil'.
83 (process-send-string "shell<1>" "ls\n")
87 ---------- Buffer: *shell* ----------
89 introduction.texi syntax-tables.texi~
90 introduction.texi~ text.texi
91 introduction.txt text.texi~
93 ---------- Buffer: *shell* ----------
95 - Function: process-send-region process start end &optional buffer
96 This function sends the text in the region defined by START and
97 END as standard input to PROCESS.
99 The argument PROCESS may be a process or the name of a process, or
100 a buffer or the name of a buffer, in which case the buffer's
101 process is used. If it is `nil', the current buffer's process is
104 An error is signaled unless both START and END are integers or
105 markers that indicate positions in the current buffer. (It is
106 unimportant which number is larger.)
108 - Function: process-send-eof &optional process
109 This function makes PROCESS see an end-of-file in its input. The
110 EOF comes after any text already sent to it.
112 PROCESS may be a process, a buffer, the name of a process or
113 buffer, or `nil', indicating the current buffer's process. An
114 error is signaled if PROCESS does not identify any process.
116 The function returns the process object identified by PROCESS.
118 (process-send-eof "shell")
122 File: lispref.info, Node: Signals to Processes, Next: Output from Processes, Prev: Input to Processes, Up: Processes
124 Sending Signals to Processes
125 ============================
127 "Sending a signal" to a subprocess is a way of interrupting its
128 activities. There are several different signals, each with its own
129 meaning. The set of signals and their names is defined by the operating
130 system. For example, the signal `SIGINT' means that the user has typed
131 `C-c', or that some analogous thing has happened.
133 Each signal has a standard effect on the subprocess. Most signals
134 kill the subprocess, but some stop or resume execution instead. Most
135 signals can optionally be handled by programs; if the program handles
136 the signal, then we can say nothing in general about its effects.
138 The set of signals and their names is defined by the operating
139 system; XEmacs has facilities for sending only a few of the signals
140 that are defined. XEmacs can send signals only to its own subprocesses.
142 You can send signals explicitly by calling the functions in this
143 section. XEmacs also sends signals automatically at certain times:
144 killing a buffer sends a `SIGHUP' signal to all its associated
145 processes; killing XEmacs sends a `SIGHUP' signal to all remaining
146 processes. (`SIGHUP' is a signal that indicates that the connection
147 between the user and the process is broken, for example if a connection
148 via a telephone line is hung up.)
150 Each of the signal-sending functions takes two optional arguments:
151 PROCESS and CURRENT-GROUP.
153 The argument PROCESS must be either a process or a buffer, the name
154 of one, or `nil'. If it is `nil', the process defaults to the process
155 associated with the current buffer. An error is signaled if PROCESS
156 does not identify a process.
158 The argument CURRENT-GROUP is a flag that makes a difference when
159 you are running a job-control shell as an XEmacs subprocess. If it is
160 non-`nil', then the signal is sent to the current foreground process
161 group of the terminal that XEmacs uses to communicate with the
162 subprocess. If the process is a job-control shell, this means the
163 shell's current subjob. If it is `nil', the signal is sent to the
164 process group of the immediate subprocess of XEmacs. If the subprocess
165 is a job-control shell, this is the shell itself.
167 The flag CURRENT-GROUP has no effect when a pipe is used to
168 communicate with the subprocess, because the operating system does not
169 support the distinction in the case of pipes. For the same reason,
170 job-control shells won't work when a pipe is used. See
171 `process-connection-type' in *Note Asynchronous Processes::.
173 Some of the functions below take a SIGNAL argument, which identifies
174 a signal to be sent. It must be either an integer or a symbol which
175 names the signal, like `SIGSEGV'.
177 - Function: process-send-signal signal &optional process current-group
178 This function sends the signal SIGNAL to the process PROCESS. The
179 following functions can be implemented in terms of
180 `process-send-signal'.
182 - Function: interrupt-process &optional process current-group
183 This function interrupts the process PROCESS by sending the signal
184 `SIGINT'. Outside of XEmacs, typing the "interrupt character"
185 (normally `C-c') sends this signal. When the argument
186 CURRENT-GROUP is non-`nil', you can think of this function as
187 "typing `C-c'" on the terminal by which XEmacs talks to the
190 - Function: kill-process &optional process current-group
191 This function kills the process PROCESS by sending the signal
192 `SIGKILL'. This signal kills the subprocess immediately, and
193 cannot be handled by the subprocess.
195 - Function: quit-process &optional process current-group
196 This function sends the signal `SIGQUIT' to the process PROCESS.
197 This signal is the one sent by the "quit character" (usually
198 `C-\') when you are not inside XEmacs.
200 - Function: stop-process &optional process current-group
201 This function stops the process PROCESS by sending the signal
202 `SIGTSTP'. Use `continue-process' to resume its execution.
204 On systems with job control, the "stop character" (usually `C-z')
205 sends this signal (outside of XEmacs). When CURRENT-GROUP is
206 non-`nil', you can think of this function as "typing `C-z'" on the
207 terminal XEmacs uses to communicate with the subprocess.
209 - Function: continue-process &optional process current-group
210 This function resumes execution of the process PROCESS by sending
211 it the signal `SIGCONT'. This presumes that PROCESS was stopped
214 - Command: signal-process pid signal
215 This function sends a signal to the process with process id PID,
216 which need not be a child of XEmacs. The argument SIGNAL
217 specifies which signal to send.
220 File: lispref.info, Node: Output from Processes, Next: Sentinels, Prev: Signals to Processes, Up: Processes
222 Receiving Output from Processes
223 ===============================
225 There are two ways to receive the output that a subprocess writes to
226 its standard output stream. The output can be inserted in a buffer,
227 which is called the associated buffer of the process, or a function
228 called the "filter function" can be called to act on the output. If
229 the process has no buffer and no filter function, its output is
234 * Process Buffers:: If no filter, output is put in a buffer.
235 * Filter Functions:: Filter functions accept output from the process.
236 * Accepting Output:: Explicitly permitting subprocess output.
237 Waiting for subprocess output.
240 File: lispref.info, Node: Process Buffers, Next: Filter Functions, Up: Output from Processes
245 A process can (and usually does) have an "associated buffer", which
246 is an ordinary Emacs buffer that is used for two purposes: storing the
247 output from the process, and deciding when to kill the process. You
248 can also use the buffer to identify a process to operate on, since in
249 normal practice only one process is associated with any given buffer.
250 Many applications of processes also use the buffer for editing input to
251 be sent to the process, but this is not built into XEmacs Lisp.
253 Unless the process has a filter function (*note Filter Functions::),
254 its output is inserted in the associated buffer. The position to insert
255 the output is determined by the `process-mark', which is then updated
256 to point to the end of the text just inserted. Usually, but not
257 always, the `process-mark' is at the end of the buffer.
259 - Function: process-buffer process
260 This function returns the associated buffer of the process PROCESS.
262 (process-buffer (get-process "shell"))
265 - Function: process-mark process
266 This function returns the process marker for PROCESS, which is the
267 marker that says where to insert output from the process.
269 If PROCESS does not have a buffer, `process-mark' returns a marker
272 Insertion of process output in a buffer uses this marker to decide
273 where to insert, and updates it to point after the inserted text.
274 That is why successive batches of output are inserted
277 Filter functions normally should use this marker in the same
278 fashion as is done by direct insertion of output in the buffer. A
279 good example of a filter function that uses `process-mark' is
280 found at the end of the following section.
282 When the user is expected to enter input in the process buffer for
283 transmission to the process, the process marker is useful for
284 distinguishing the new input from previous output.
286 - Function: set-process-buffer process buffer
287 This function sets the buffer associated with PROCESS to BUFFER.
288 If BUFFER is `nil', the process becomes associated with no buffer.
290 - Function: get-buffer-process buffer-or-name
291 This function returns the process associated with BUFFER-OR-NAME.
292 If there are several processes associated with BUFFER-OR-NAME,
293 then one is chosen. (Presently, the one chosen is the one most
294 recently created.) It is usually a bad idea to have more than one
295 process associated with the same buffer.
297 (get-buffer-process "*shell*")
300 Killing the process's buffer deletes the process, which kills the
301 subprocess with a `SIGHUP' signal (*note Signals to Processes::).
304 File: lispref.info, Node: Filter Functions, Next: Accepting Output, Prev: Process Buffers, Up: Output from Processes
306 Process Filter Functions
307 ------------------------
309 A process "filter function" is a function that receives the standard
310 output from the associated process. If a process has a filter, then
311 _all_ output from that process is passed to the filter. The process
312 buffer is used directly for output from the process only when there is
315 A filter function must accept two arguments: the associated process
316 and a string, which is the output. The function is then free to do
317 whatever it chooses with the output.
319 A filter function runs only while XEmacs is waiting (e.g., for
320 terminal input, or for time to elapse, or for process output). This
321 avoids the timing errors that could result from running filters at
322 random places in the middle of other Lisp programs. You may explicitly
323 cause Emacs to wait, so that filter functions will run, by calling
324 `sit-for' or `sleep-for' (*note Waiting::), or `accept-process-output'
325 (*note Accepting Output::). Emacs is also waiting when the command loop
328 Quitting is normally inhibited within a filter function--otherwise,
329 the effect of typing `C-g' at command level or to quit a user command
330 would be unpredictable. If you want to permit quitting inside a filter
331 function, bind `inhibit-quit' to `nil'. *Note Quitting::.
333 If an error happens during execution of a filter function, it is
334 caught automatically, so that it doesn't stop the execution of whatever
335 program was running when the filter function was started. However, if
336 `debug-on-error' is non-`nil', the error-catching is turned off. This
337 makes it possible to use the Lisp debugger to debug the filter
338 function. *Note Debugger::.
340 Many filter functions sometimes or always insert the text in the
341 process's buffer, mimicking the actions of XEmacs when there is no
342 filter. Such filter functions need to use `set-buffer' in order to be
343 sure to insert in that buffer. To avoid setting the current buffer
344 semipermanently, these filter functions must use `unwind-protect' to
345 make sure to restore the previous current buffer. They should also
346 update the process marker, and in some cases update the value of point.
347 Here is how to do these things:
349 (defun ordinary-insertion-filter (process string)
350 (let ((old-buffer (current-buffer)))
353 (set-buffer (process-buffer process))
354 (setq moving (= (point) (process-mark process)))
356 ;; Insert the text, moving the process-marker.
357 (goto-char (process-mark process))
359 (set-marker (process-mark process) (point)))
360 (if moving (goto-char (process-mark process))))
361 (set-buffer old-buffer))))
363 The reason to use an explicit `unwind-protect' rather than letting
364 `save-excursion' restore the current buffer is so as to preserve the
365 change in point made by `goto-char'.
367 To make the filter force the process buffer to be visible whenever
368 new text arrives, insert the following line just before the
371 (display-buffer (process-buffer process))
373 To force point to move to the end of the new output no matter where
374 it was previously, eliminate the variable `moving' and call `goto-char'
377 In earlier Emacs versions, every filter function that did regexp
378 searching or matching had to explicitly save and restore the match data.
379 Now Emacs does this automatically; filter functions never need to do it
380 explicitly. *Note Match Data::.
382 A filter function that writes the output into the buffer of the
383 process should check whether the buffer is still alive. If it tries to
384 insert into a dead buffer, it will get an error. If the buffer is dead,
385 `(buffer-name (process-buffer PROCESS))' returns `nil'.
387 The output to the function may come in chunks of any size. A program
388 that produces the same output twice in a row may send it as one batch
389 of 200 characters one time, and five batches of 40 characters the next.
391 - Function: set-process-filter process filter
392 This function gives PROCESS the filter function FILTER. If FILTER
393 is `nil', then the process will have no filter. If FILTER is `t',
394 then no output from the process will be accepted until the filter
395 is changed. (Output received during this time is not discarded,
396 but is queued, and will be processed as soon as the filter is
399 - Function: process-filter process
400 This function returns the filter function of PROCESS, or `nil' if
401 it has none. `t' means that output processing has been stopped.
403 Here is an example of use of a filter function:
405 (defun keep-output (process output)
406 (setq kept (cons output kept)))
410 (set-process-filter (get-process "shell") 'keep-output)
412 (process-send-string "shell" "ls ~/other\n")
415 => ("lewis@slug[8] % "
416 "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
417 address.txt backup.psf kolstad.psf
418 backup.bib~ david.mss resume-Dec-86.mss~
419 backup.err david.psf resume-Dec.psf
420 backup.mss dland syllabus.mss
422 "#backups.mss# backup.mss~ kolstad.mss
426 File: lispref.info, Node: Accepting Output, Prev: Filter Functions, Up: Output from Processes
428 Accepting Output from Processes
429 -------------------------------
431 Output from asynchronous subprocesses normally arrives only while
432 XEmacs is waiting for some sort of external event, such as elapsed time
433 or terminal input. Occasionally it is useful in a Lisp program to
434 explicitly permit output to arrive at a specific point, or even to wait
435 until output arrives from a process.
437 - Function: accept-process-output &optional process seconds millisec
438 This function allows XEmacs to read pending output from processes.
439 The output is inserted in the associated buffers or given to
440 their filter functions. If PROCESS is non-`nil' then this
441 function does not return until some output has been received from
444 The arguments SECONDS and MILLISEC let you specify timeout
445 periods. The former specifies a period measured in seconds and the
446 latter specifies one measured in milliseconds. The two time
447 periods thus specified are added together, and
448 `accept-process-output' returns after that much time whether or
449 not there has been any subprocess output. Note that SECONDS is
450 allowed to be a floating-point number; thus, there is no need to
451 ever use MILLISEC. (It is retained for compatibility purposes.)
453 The function `accept-process-output' returns non-`nil' if it did
454 get some output, or `nil' if the timeout expired before output
458 File: lispref.info, Node: Sentinels, Next: Process Window Size, Prev: Output from Processes, Up: Processes
460 Sentinels: Detecting Process Status Changes
461 ===========================================
463 A "process sentinel" is a function that is called whenever the
464 associated process changes status for any reason, including signals
465 (whether sent by XEmacs or caused by the process's own actions) that
466 terminate, stop, or continue the process. The process sentinel is also
467 called if the process exits. The sentinel receives two arguments: the
468 process for which the event occurred, and a string describing the type
471 The string describing the event looks like one of the following:
475 * `"exited abnormally with code EXITCODE\n"'.
477 * `"NAME-OF-SIGNAL\n"'.
479 * `"NAME-OF-SIGNAL (core dumped)\n"'.
481 A sentinel runs only while XEmacs is waiting (e.g., for terminal
482 input, or for time to elapse, or for process output). This avoids the
483 timing errors that could result from running them at random places in
484 the middle of other Lisp programs. A program can wait, so that
485 sentinels will run, by calling `sit-for' or `sleep-for' (*note
486 Waiting::), or `accept-process-output' (*note Accepting Output::).
487 Emacs is also waiting when the command loop is reading input.
489 Quitting is normally inhibited within a sentinel--otherwise, the
490 effect of typing `C-g' at command level or to quit a user command would
491 be unpredictable. If you want to permit quitting inside a sentinel,
492 bind `inhibit-quit' to `nil'. *Note Quitting::.
494 A sentinel that writes the output into the buffer of the process
495 should check whether the buffer is still alive. If it tries to insert
496 into a dead buffer, it will get an error. If the buffer is dead,
497 `(buffer-name (process-buffer PROCESS))' returns `nil'.
499 If an error happens during execution of a sentinel, it is caught
500 automatically, so that it doesn't stop the execution of whatever
501 programs was running when the sentinel was started. However, if
502 `debug-on-error' is non-`nil', the error-catching is turned off. This
503 makes it possible to use the Lisp debugger to debug the sentinel.
506 In earlier Emacs versions, every sentinel that did regexp searching
507 or matching had to explicitly save and restore the match data. Now
508 Emacs does this automatically; sentinels never need to do it explicitly.
511 - Function: set-process-sentinel process sentinel
512 This function associates SENTINEL with PROCESS. If SENTINEL is
513 `nil', then the process will have no sentinel. The default
514 behavior when there is no sentinel is to insert a message in the
515 process's buffer when the process status changes.
517 (defun msg-me (process event)
519 (format "Process: %s had the event `%s'" process event)))
520 (set-process-sentinel (get-process "shell") 'msg-me)
522 (kill-process (get-process "shell"))
523 -| Process: #<process shell> had the event `killed'
526 - Function: process-sentinel process
527 This function returns the sentinel of PROCESS, or `nil' if it has
530 - Function: waiting-for-user-input-p
531 While a sentinel or filter function is running, this function
532 returns non-`nil' if XEmacs was waiting for keyboard input from
533 the user at the time the sentinel or filter function was called,
537 File: lispref.info, Node: Process Window Size, Next: Transaction Queues, Prev: Sentinels, Up: Processes
542 - Function: set-process-window-size process height width
543 This function tells PROCESS that its logical window size is HEIGHT
544 by WIDTH characters. This is principally useful with pty's.
547 File: lispref.info, Node: Transaction Queues, Next: Network, Prev: Process Window Size, Up: Processes
552 You can use a "transaction queue" for more convenient communication
553 with subprocesses using transactions. First use `tq-create' to create
554 a transaction queue communicating with a specified process. Then you
555 can call `tq-enqueue' to send a transaction.
557 - Function: tq-create process
558 This function creates and returns a transaction queue
559 communicating with PROCESS. The argument PROCESS should be a
560 subprocess capable of sending and receiving streams of bytes. It
561 may be a child process, or it may be a TCP connection to a server,
562 possibly on another machine.
564 - Function: tq-enqueue queue question regexp closure fn
565 This function sends a transaction to queue QUEUE. Specifying the
566 queue has the effect of specifying the subprocess to talk to.
568 The argument QUESTION is the outgoing message that starts the
569 transaction. The argument FN is the function to call when the
570 corresponding answer comes back; it is called with two arguments:
571 CLOSURE, and the answer received.
573 The argument REGEXP is a regular expression that should match the
574 entire answer, but nothing less; that's how `tq-enqueue' determines
575 where the answer ends.
577 The return value of `tq-enqueue' itself is not meaningful.
579 - Function: tq-close queue
580 Shut down transaction queue QUEUE, waiting for all pending
581 transactions to complete, and then terminate the connection or
584 Transaction queues are implemented by means of a filter function.
585 *Note Filter Functions::.
588 File: lispref.info, Node: Network, Prev: Transaction Queues, Up: Processes
593 XEmacs Lisp programs can open TCP network connections to other
594 processes on the same machine or other machines. A network connection
595 is handled by Lisp much like a subprocess, and is represented by a
596 process object. However, the process you are communicating with is not
597 a child of the XEmacs process, so you can't kill it or send it signals.
598 All you can do is send and receive data. `delete-process' closes the
599 connection, but does not kill the process at the other end; that
600 process must decide what to do about closure of the connection.
602 You can distinguish process objects representing network connections
603 from those representing subprocesses with the `process-status'
604 function. It always returns either `open' or `closed' for a network
605 connection, and it never returns either of those values for a real
606 subprocess. *Note Process Information::.
608 - Function: open-network-stream name buffer-or-name host service
610 This function opens a TCP connection for a service to a host. It
611 returns a process object to represent the connection.
613 Input and output work as for other process objects.
614 `delete-process' closes the connection.
616 The NAME argument specifies the name for the process object. It
617 is modified as necessary to make it unique.
619 The BUFFER-OR-NAME argument is the buffer to associate with the
620 connection. It can be a buffer or the name of one. Output from
621 the connection is inserted in the buffer, unless you specify a
622 filter function to handle the output. If BUFFER-OR-NAME is `nil',
623 it means that the connection is not associated with any buffer.
625 The arguments HOST and SERVICE specify where to connect to; HOST
626 is the host name or IP address (a string), and SERVICE is the name
627 of a defined network service (a string) or a port number (an
630 Optional fifth arg PROTOCOL is the network protocol to use.
631 Currently only `tcp' (Transmission Control Protocol) and `udp'
632 (User Datagram Protocol) are supported. When omitted, `tcp' is
635 Output via `process-send-string' and input via buffer or filter
636 (see `set-process-filter') are stream-oriented. That means UDP
637 datagrams are not guaranteed to be sent and received in discrete
638 packets. (But small datagrams around 500 bytes that are not
639 truncated by `process-send-string' are usually fine.) Note further
640 that the UDP protocol does not guard against lost packets.
643 File: lispref.info, Node: System Interface, Next: X-Windows, Prev: Processes, Up: Top
645 Operating System Interface
646 **************************
648 This chapter is about starting and getting out of Emacs, access to
649 values in the operating system environment, and terminal input, output,
652 *Note Building XEmacs::, for related information. See also *Note
653 Display::, for additional operating system status information
654 pertaining to the terminal and the screen.
658 * Starting Up:: Customizing XEmacs start-up processing.
659 * Getting Out:: How exiting works (permanent or temporary).
660 * System Environment:: Distinguish the name and kind of system.
661 * User Identification:: Finding the name and user id of the user.
662 * Time of Day:: Getting the current time.
663 * Time Conversion:: Converting a time from numeric form to a string, or
664 to calendrical data (or vice versa).
665 * Timers:: Setting a timer to call a function at a certain time.
666 * Terminal Input:: Recording terminal input for debugging.
667 * Terminal Output:: Recording terminal output for debugging.
668 * Flow Control:: How to turn output flow control on or off.
669 * Batch Mode:: Running XEmacs without terminal interaction.
672 File: lispref.info, Node: Starting Up, Next: Getting Out, Up: System Interface
677 This section describes what XEmacs does when it is started, and how
678 you can customize these actions.
682 * Start-up Summary:: Sequence of actions XEmacs performs at start-up.
683 * Init File:: Details on reading the init file (`.emacs').
684 * Terminal-Specific:: How the terminal-specific Lisp file is read.
685 * Command Line Arguments:: How command line arguments are processed,
686 and how you can customize them.
689 File: lispref.info, Node: Start-up Summary, Next: Init File, Up: Starting Up
691 Summary: Sequence of Actions at Start Up
692 ----------------------------------------
694 The order of operations performed (in `startup.el') by XEmacs when
695 it is started up is as follows:
697 1. It loads the initialization library for the window system, if you
698 are using a window system. This library's name is
699 `term/WINDOWSYSTEM-win.el'.
701 2. It processes the initial options. (Some of them are handled even
704 3. It initializes the X window frame and faces, if appropriate.
706 4. It runs the normal hook `before-init-hook'.
708 5. It loads the library `site-start', unless the option
709 `-no-site-file' was specified. The library's file name is usually
712 6. It loads the file `~/.emacs' unless `-q' was specified on the
713 command line. (This is not done in `-batch' mode.) The `-u'
714 option can specify the user name whose home directory should be
717 7. It loads the library `default' unless `inhibit-default-init' is
718 non-`nil'. (This is not done in `-batch' mode or if `-q' was
719 specified on the command line.) The library's file name is
720 usually `default.el'.
722 8. It runs the normal hook `after-init-hook'.
724 9. It sets the major mode according to `initial-major-mode', provided
725 the buffer `*scratch*' is still current and still in Fundamental
728 10. It loads the terminal-specific Lisp file, if any, except when in
729 batch mode or using a window system.
731 11. It displays the initial echo area message, unless you have
732 suppressed that with `inhibit-startup-echo-area-message'.
734 12. It processes the action arguments from the command line.
736 13. It runs `term-setup-hook'.
738 14. It calls `frame-notice-user-settings', which modifies the
739 parameters of the selected frame according to whatever the init
742 15. It runs `window-setup-hook'. *Note Terminal-Specific::.
744 16. It displays copyleft, nonwarranty, and basic use information,
745 provided there were no remaining command line arguments (a few
746 steps above) and the value of `inhibit-startup-message' is `nil'.
748 - User Option: inhibit-startup-message
749 This variable inhibits the initial startup messages (the
750 nonwarranty, etc.). If it is non-`nil', then the messages are not
753 This variable exists so you can set it in your personal init file,
754 once you are familiar with the contents of the startup message.
755 Do not set this variable in the init file of a new user, or in a
756 way that affects more than one user, because that would prevent
757 new users from receiving the information they are supposed to see.
759 - User Option: inhibit-startup-echo-area-message
760 This variable controls the display of the startup echo area
761 message. You can suppress the startup echo area message by adding
762 text with this form to your `.emacs' file:
764 (setq inhibit-startup-echo-area-message
767 Simply setting `inhibit-startup-echo-area-message' to your login
768 name is not sufficient to inhibit the message; Emacs explicitly
769 checks whether `.emacs' contains an expression as shown above.
770 Your login name must appear in the expression as a Lisp string
773 This way, you can easily inhibit the message for yourself if you
774 wish, but thoughtless copying of your `.emacs' file will not
775 inhibit the message for someone else.
778 File: lispref.info, Node: Init File, Next: Terminal-Specific, Prev: Start-up Summary, Up: Starting Up
780 The Init File: `.emacs'
781 -----------------------
783 When you start XEmacs, it normally attempts to load the file
784 `.emacs' from your home directory. This file, if it exists, must
785 contain Lisp code. It is called your "init file". The command line
786 switches `-q' and `-u' affect the use of the init file; `-q' says not
787 to load an init file, and `-u' says to load a specified user's init
788 file instead of yours. *Note Entering XEmacs: (xemacs)Entering XEmacs.
790 A site may have a "default init file", which is the library named
791 `default.el'. XEmacs finds the `default.el' file through the standard
792 search path for libraries (*note How Programs Do Loading::). The
793 XEmacs distribution does not come with this file; sites may provide one
794 for local customizations. If the default init file exists, it is
795 loaded whenever you start Emacs, except in batch mode or if `-q' is
796 specified. But your own personal init file, if any, is loaded first; if
797 it sets `inhibit-default-init' to a non-`nil' value, then XEmacs does
798 not subsequently load the `default.el' file.
800 Another file for site-customization is `site-start.el'. Emacs loads
801 this _before_ the user's init file. You can inhibit the loading of
802 this file with the option `-no-site-file'.
804 - Variable: site-run-file
805 This variable specifies the site-customization file to load before
806 the user's init file. Its normal value is `"site-start"'.
808 If there is a great deal of code in your `.emacs' file, you should
809 move it into another file named `SOMETHING.el', byte-compile it (*note
810 Byte Compilation::), and make your `.emacs' file load the other file
811 using `load' (*note Loading::).
813 *Note Init File Examples: (xemacs)Init File Examples, for examples
814 of how to make various commonly desired customizations in your `.emacs'
817 - User Option: inhibit-default-init
818 This variable prevents XEmacs from loading the default
819 initialization library file for your session of XEmacs. If its
820 value is non-`nil', then the default library is not loaded. The
821 default value is `nil'.
823 - Variable: before-init-hook
824 - Variable: after-init-hook
825 These two normal hooks are run just before, and just after,
826 loading of the user's init file, `default.el', and/or
830 File: lispref.info, Node: Terminal-Specific, Next: Command Line Arguments, Prev: Init File, Up: Starting Up
832 Terminal-Specific Initialization
833 --------------------------------
835 Each terminal type can have its own Lisp library that XEmacs loads
836 when run on that type of terminal. For a terminal type named TERMTYPE,
837 the library is called `term/TERMTYPE'. XEmacs finds the file by
838 searching the `load-path' directories as it does for other files, and
839 trying the `.elc' and `.el' suffixes. Normally, terminal-specific Lisp
840 library is located in `emacs/lisp/term', a subdirectory of the
841 `emacs/lisp' directory in which most XEmacs Lisp libraries are kept.
843 The library's name is constructed by concatenating the value of the
844 variable `term-file-prefix' and the terminal type. Normally,
845 `term-file-prefix' has the value `"term/"'; changing this is not
848 The usual function of a terminal-specific library is to enable
849 special keys to send sequences that XEmacs can recognize. It may also
850 need to set or add to `function-key-map' if the Termcap entry does not
851 specify all the terminal's function keys. *Note Terminal Input::.
853 When the name of the terminal type contains a hyphen, only the part
854 of the name before the first hyphen is significant in choosing the
855 library name. Thus, terminal types `aaa-48' and `aaa-30-rv' both use
856 the `term/aaa' library. If necessary, the library can evaluate
857 `(getenv "TERM")' to find the full name of the terminal type.
859 Your `.emacs' file can prevent the loading of the terminal-specific
860 library by setting the variable `term-file-prefix' to `nil'. This
861 feature is useful when experimenting with your own peculiar
864 You can also arrange to override some of the actions of the
865 terminal-specific library by setting the variable `term-setup-hook'.
866 This is a normal hook which XEmacs runs using `run-hooks' at the end of
867 XEmacs initialization, after loading both your `.emacs' file and any
868 terminal-specific libraries. You can use this variable to define
869 initializations for terminals that do not have their own libraries.
872 - Variable: term-file-prefix
873 If the `term-file-prefix' variable is non-`nil', XEmacs loads a
874 terminal-specific initialization file as follows:
876 (load (concat term-file-prefix (getenv "TERM")))
878 You may set the `term-file-prefix' variable to `nil' in your
879 `.emacs' file if you do not wish to load the
880 terminal-initialization file. To do this, put the following in
881 your `.emacs' file: `(setq term-file-prefix nil)'.
883 - Variable: term-setup-hook
884 This variable is a normal hook that XEmacs runs after loading your
885 `.emacs' file, the default initialization file (if any) and the
886 terminal-specific Lisp file.
888 You can use `term-setup-hook' to override the definitions made by a
889 terminal-specific file.
891 - Variable: window-setup-hook
892 This variable is a normal hook which XEmacs runs after loading your
893 `.emacs' file and the default initialization file (if any), after
894 loading terminal-specific Lisp code, and after running the hook
898 File: lispref.info, Node: Command Line Arguments, Prev: Terminal-Specific, Up: Starting Up
900 Command Line Arguments
901 ----------------------
903 You can use command line arguments to request various actions when
904 you start XEmacs. Since you do not need to start XEmacs more than once
905 per day, and will often leave your XEmacs session running longer than
906 that, command line arguments are hardly ever used. As a practical
907 matter, it is best to avoid making the habit of using them, since this
908 habit would encourage you to kill and restart XEmacs unnecessarily
909 often. These options exist for two reasons: to be compatible with
910 other editors (for invocation by other programs) and to enable shell
911 scripts to run specific Lisp programs.
913 This section describes how Emacs processes command line arguments,
914 and how you can customize them.
916 - Function: command-line
917 This function parses the command line that XEmacs was called with,
918 processes it, loads the user's `.emacs' file and displays the
921 - Variable: command-line-processed
922 The value of this variable is `t' once the command line has been
925 If you redump XEmacs by calling `dump-emacs', you may wish to set
926 this variable to `nil' first in order to cause the new dumped
927 XEmacs to process its new command line arguments.
929 - Variable: command-switch-alist
930 The value of this variable is an alist of user-defined command-line
931 options and associated handler functions. This variable exists so
932 you can add elements to it.
934 A "command line option" is an argument on the command line of the
939 The elements of the `command-switch-alist' look like this:
941 (OPTION . HANDLER-FUNCTION)
943 The HANDLER-FUNCTION is called to handle OPTION and receives the
944 option name as its sole argument.
946 In some cases, the option is followed in the command line by an
947 argument. In these cases, the HANDLER-FUNCTION can find all the
948 remaining command-line arguments in the variable
949 `command-line-args-left'. (The entire list of command-line
950 arguments is in `command-line-args'.)
952 The command line arguments are parsed by the `command-line-1'
953 function in the `startup.el' file. See also *Note Command Line
954 Switches and Arguments: (xemacs)Command Switches.
956 - Variable: command-line-args
957 The value of this variable is the list of command line arguments
960 - Variable: command-line-functions
961 This variable's value is a list of functions for handling an
962 unrecognized command-line argument. Each time the next argument
963 to be processed has no special meaning, the functions in this list
964 are called, in order of appearance, until one of them returns a
967 These functions are called with no arguments. They can access the
968 command-line argument under consideration through the variable
969 `argi'. The remaining arguments (not including the current one)
970 are in the variable `command-line-args-left'.
972 When a function recognizes and processes the argument in `argi', it
973 should return a non-`nil' value to say it has dealt with that
974 argument. If it has also dealt with some of the following
975 arguments, it can indicate that by deleting them from
976 `command-line-args-left'.
978 If all of these functions return `nil', then the argument is used
979 as a file name to visit.
982 File: lispref.info, Node: Getting Out, Next: System Environment, Prev: Starting Up, Up: System Interface
984 Getting out of XEmacs
985 =====================
987 There are two ways to get out of XEmacs: you can kill the XEmacs job,
988 which exits permanently, or you can suspend it, which permits you to
989 reenter the XEmacs process later. As a practical matter, you seldom
990 kill XEmacs--only when you are about to log out. Suspending is much
995 * Killing XEmacs:: Exiting XEmacs irreversibly.
996 * Suspending XEmacs:: Exiting XEmacs reversibly.
999 File: lispref.info, Node: Killing XEmacs, Next: Suspending XEmacs, Up: Getting Out
1004 Killing XEmacs means ending the execution of the XEmacs process. The
1005 parent process normally resumes control. The low-level primitive for
1006 killing XEmacs is `kill-emacs'.
1008 - Command: kill-emacs &optional exit-data
1009 This function exits the XEmacs process and kills it.
1011 If EXIT-DATA is an integer, then it is used as the exit status of
1012 the XEmacs process. (This is useful primarily in batch operation;
1013 see *Note Batch Mode::.)
1015 If EXIT-DATA is a string, its contents are stuffed into the
1016 terminal input buffer so that the shell (or whatever program next
1017 reads input) can read them.
1019 All the information in the XEmacs process, aside from files that have
1020 been saved, is lost when the XEmacs is killed. Because killing XEmacs
1021 inadvertently can lose a lot of work, XEmacs queries for confirmation
1022 before actually terminating if you have buffers that need saving or
1023 subprocesses that are running. This is done in the function
1024 `save-buffers-kill-emacs'.
1026 - Variable: kill-emacs-query-functions
1027 After asking the standard questions, `save-buffers-kill-emacs'
1028 calls the functions in the list `kill-buffer-query-functions', in
1029 order of appearance, with no arguments. These functions can ask
1030 for additional confirmation from the user. If any of them returns
1031 non-`nil', XEmacs is not killed.
1033 - Variable: kill-emacs-hook
1034 This variable is a normal hook; once `save-buffers-kill-emacs' is
1035 finished with all file saving and confirmation, it runs the
1036 functions in this hook.
1039 File: lispref.info, Node: Suspending XEmacs, Prev: Killing XEmacs, Up: Getting Out
1044 "Suspending XEmacs" means stopping XEmacs temporarily and returning
1045 control to its superior process, which is usually the shell. This
1046 allows you to resume editing later in the same XEmacs process, with the
1047 same buffers, the same kill ring, the same undo history, and so on. To
1048 resume XEmacs, use the appropriate command in the parent shell--most
1051 Some operating systems do not support suspension of jobs; on these
1052 systems, "suspension" actually creates a new shell temporarily as a
1053 subprocess of XEmacs. Then you would exit the shell to return to
1056 Suspension is not useful with window systems such as X, because the
1057 XEmacs job may not have a parent that can resume it again, and in any
1058 case you can give input to some other job such as a shell merely by
1059 moving to a different window. Therefore, suspending is not allowed
1060 when XEmacs is an X client.
1062 - Command: suspend-emacs &optional stuffstring
1063 This function stops XEmacs and returns control to the superior
1064 process. If and when the superior process resumes XEmacs,
1065 `suspend-emacs' returns `nil' to its caller in Lisp.
1067 If optional arg STUFFSTRING is non-`nil', its characters are sent
1068 to be read as terminal input by XEmacs's superior shell. The
1069 characters in STUFFSTRING are not echoed by the superior shell;
1070 only the results appear.
1072 Before suspending, `suspend-emacs' runs the normal hook
1073 `suspend-hook'. In Emacs version 18, `suspend-hook' was not a
1074 normal hook; its value was a single function, and if its value was
1075 non-`nil', then `suspend-emacs' returned immediately without
1076 actually suspending anything.
1078 After the user resumes XEmacs, `suspend-emacs' runs the normal hook
1079 `suspend-resume-hook'. *Note Hooks::.
1081 The next redisplay after resumption will redraw the entire screen,
1082 unless the variable `no-redraw-on-reenter' is non-`nil' (*note
1085 In the following example, note that `pwd' is not echoed after
1086 XEmacs is suspended. But it is read and executed by the shell.
1091 (add-hook 'suspend-hook
1092 (function (lambda ()
1095 (error "Suspend cancelled")))))
1097 (or (y-or-n-p "Really suspend? ")
1098 (error "Suspend cancelled")))
1099 (add-hook 'suspend-resume-hook
1100 (function (lambda () (message "Resumed!"))))
1101 => (lambda nil (message "Resumed!"))
1102 (suspend-emacs "pwd")
1104 ---------- Buffer: Minibuffer ----------
1106 ---------- Buffer: Minibuffer ----------
1108 ---------- Parent Shell ----------
1109 lewis@slug[23] % /user/lewis/manual
1112 ---------- Echo Area ----------
1115 - Variable: suspend-hook
1116 This variable is a normal hook run before suspending.
1118 - Variable: suspend-resume-hook
1119 This variable is a normal hook run after suspending.
projects / chise / xemacs-chise.git / blob