1 This is ../info/lispref.info, produced by makeinfo version 4.0 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: Process Buffers, Next: Filter Functions, Up: Output from Processes
58 A process can (and usually does) have an "associated buffer", which
59 is an ordinary Emacs buffer that is used for two purposes: storing the
60 output from the process, and deciding when to kill the process. You
61 can also use the buffer to identify a process to operate on, since in
62 normal practice only one process is associated with any given buffer.
63 Many applications of processes also use the buffer for editing input to
64 be sent to the process, but this is not built into XEmacs Lisp.
66 Unless the process has a filter function (*note Filter Functions::),
67 its output is inserted in the associated buffer. The position to insert
68 the output is determined by the `process-mark', which is then updated
69 to point to the end of the text just inserted. Usually, but not
70 always, the `process-mark' is at the end of the buffer.
72 - Function: process-buffer process
73 This function returns the associated buffer of the process PROCESS.
75 (process-buffer (get-process "shell"))
78 - Function: process-mark process
79 This function returns the process marker for PROCESS, which is the
80 marker that says where to insert output from the process.
82 If PROCESS does not have a buffer, `process-mark' returns a marker
85 Insertion of process output in a buffer uses this marker to decide
86 where to insert, and updates it to point after the inserted text.
87 That is why successive batches of output are inserted
90 Filter functions normally should use this marker in the same
91 fashion as is done by direct insertion of output in the buffer. A
92 good example of a filter function that uses `process-mark' is
93 found at the end of the following section.
95 When the user is expected to enter input in the process buffer for
96 transmission to the process, the process marker is useful for
97 distinguishing the new input from previous output.
99 - Function: set-process-buffer process buffer
100 This function sets the buffer associated with PROCESS to BUFFER.
101 If BUFFER is `nil', the process becomes associated with no buffer.
103 - Function: get-buffer-process buffer-or-name
104 This function returns the process associated with BUFFER-OR-NAME.
105 If there are several processes associated with it, then one is
106 chosen. (Presently, the one chosen is the one most recently
107 created.) It is usually a bad idea to have more than one process
108 associated with the same buffer.
110 (get-buffer-process "*shell*")
113 Killing the process's buffer deletes the process, which kills the
114 subprocess with a `SIGHUP' signal (*note Signals to Processes::).
117 File: lispref.info, Node: Filter Functions, Next: Accepting Output, Prev: Process Buffers, Up: Output from Processes
119 Process Filter Functions
120 ------------------------
122 A process "filter function" is a function that receives the standard
123 output from the associated process. If a process has a filter, then
124 _all_ output from that process is passed to the filter. The process
125 buffer is used directly for output from the process only when there is
128 A filter function must accept two arguments: the associated process
129 and a string, which is the output. The function is then free to do
130 whatever it chooses with the output.
132 A filter function runs only while XEmacs is waiting (e.g., for
133 terminal input, or for time to elapse, or for process output). This
134 avoids the timing errors that could result from running filters at
135 random places in the middle of other Lisp programs. You may explicitly
136 cause Emacs to wait, so that filter functions will run, by calling
137 `sit-for' or `sleep-for' (*note Waiting::), or `accept-process-output'
138 (*note Accepting Output::). Emacs is also waiting when the command loop
141 Quitting is normally inhibited within a filter function--otherwise,
142 the effect of typing `C-g' at command level or to quit a user command
143 would be unpredictable. If you want to permit quitting inside a filter
144 function, bind `inhibit-quit' to `nil'. *Note Quitting::.
146 If an error happens during execution of a filter function, it is
147 caught automatically, so that it doesn't stop the execution of whatever
148 program was running when the filter function was started. However, if
149 `debug-on-error' is non-`nil', the error-catching is turned off. This
150 makes it possible to use the Lisp debugger to debug the filter
151 function. *Note Debugger::.
153 Many filter functions sometimes or always insert the text in the
154 process's buffer, mimicking the actions of XEmacs when there is no
155 filter. Such filter functions need to use `set-buffer' in order to be
156 sure to insert in that buffer. To avoid setting the current buffer
157 semipermanently, these filter functions must use `unwind-protect' to
158 make sure to restore the previous current buffer. They should also
159 update the process marker, and in some cases update the value of point.
160 Here is how to do these things:
162 (defun ordinary-insertion-filter (proc string)
163 (let ((old-buffer (current-buffer)))
166 (set-buffer (process-buffer proc))
167 (setq moving (= (point) (process-mark proc)))
169 ;; Insert the text, moving the process-marker.
170 (goto-char (process-mark proc))
172 (set-marker (process-mark proc) (point)))
173 (if moving (goto-char (process-mark proc))))
174 (set-buffer old-buffer))))
176 The reason to use an explicit `unwind-protect' rather than letting
177 `save-excursion' restore the current buffer is so as to preserve the
178 change in point made by `goto-char'.
180 To make the filter force the process buffer to be visible whenever
181 new text arrives, insert the following line just before the
184 (display-buffer (process-buffer proc))
186 To force point to move to the end of the new output no matter where
187 it was previously, eliminate the variable `moving' and call `goto-char'
190 In earlier Emacs versions, every filter function that did regexp
191 searching or matching had to explicitly save and restore the match data.
192 Now Emacs does this automatically; filter functions never need to do it
193 explicitly. *Note Match Data::.
195 A filter function that writes the output into the buffer of the
196 process should check whether the buffer is still alive. If it tries to
197 insert into a dead buffer, it will get an error. If the buffer is dead,
198 `(buffer-name (process-buffer PROCESS))' returns `nil'.
200 The output to the function may come in chunks of any size. A program
201 that produces the same output twice in a row may send it as one batch
202 of 200 characters one time, and five batches of 40 characters the next.
204 - Function: set-process-filter process filter
205 This function gives PROCESS the filter function FILTER. If FILTER
206 is `nil', then the process will have no filter. If FILTER is `t',
207 then no output from the process will be accepted until the filter
208 is changed. (Output received during this time is not discarded,
209 but is queued, and will be processed as soon as the filter is
212 - Function: process-filter process
213 This function returns the filter function of PROCESS, or `nil' if
214 it has none. `t' means that output processing has been stopped.
216 Here is an example of use of a filter function:
218 (defun keep-output (process output)
219 (setq kept (cons output kept)))
223 (set-process-filter (get-process "shell") 'keep-output)
225 (process-send-string "shell" "ls ~/other\n")
228 => ("lewis@slug[8] % "
229 "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
230 address.txt backup.psf kolstad.psf
231 backup.bib~ david.mss resume-Dec-86.mss~
232 backup.err david.psf resume-Dec.psf
233 backup.mss dland syllabus.mss
235 "#backups.mss# backup.mss~ kolstad.mss
239 File: lispref.info, Node: Accepting Output, Prev: Filter Functions, Up: Output from Processes
241 Accepting Output from Processes
242 -------------------------------
244 Output from asynchronous subprocesses normally arrives only while
245 XEmacs is waiting for some sort of external event, such as elapsed time
246 or terminal input. Occasionally it is useful in a Lisp program to
247 explicitly permit output to arrive at a specific point, or even to wait
248 until output arrives from a process.
250 - Function: accept-process-output &optional process seconds millisec
251 This function allows XEmacs to read pending output from processes.
252 The output is inserted in the associated buffers or given to
253 their filter functions. If PROCESS is non-`nil' then this
254 function does not return until some output has been received from
257 The arguments SECONDS and MILLISEC let you specify timeout
258 periods. The former specifies a period measured in seconds and the
259 latter specifies one measured in milliseconds. The two time
260 periods thus specified are added together, and
261 `accept-process-output' returns after that much time whether or
262 not there has been any subprocess output. Note that SECONDS is
263 allowed to be a floating-point number; thus, there is no need to
264 ever use MILLISEC. (It is retained for compatibility purposes.)
266 The function `accept-process-output' returns non-`nil' if it did
267 get some output, or `nil' if the timeout expired before output
271 File: lispref.info, Node: Sentinels, Next: Process Window Size, Prev: Output from Processes, Up: Processes
273 Sentinels: Detecting Process Status Changes
274 ===========================================
276 A "process sentinel" is a function that is called whenever the
277 associated process changes status for any reason, including signals
278 (whether sent by XEmacs or caused by the process's own actions) that
279 terminate, stop, or continue the process. The process sentinel is also
280 called if the process exits. The sentinel receives two arguments: the
281 process for which the event occurred, and a string describing the type
284 The string describing the event looks like one of the following:
288 * `"exited abnormally with code EXITCODE\n"'.
290 * `"NAME-OF-SIGNAL\n"'.
292 * `"NAME-OF-SIGNAL (core dumped)\n"'.
294 A sentinel runs only while XEmacs is waiting (e.g., for terminal
295 input, or for time to elapse, or for process output). This avoids the
296 timing errors that could result from running them at random places in
297 the middle of other Lisp programs. A program can wait, so that
298 sentinels will run, by calling `sit-for' or `sleep-for' (*note
299 Waiting::), or `accept-process-output' (*note Accepting Output::).
300 Emacs is also waiting when the command loop is reading input.
302 Quitting is normally inhibited within a sentinel--otherwise, the
303 effect of typing `C-g' at command level or to quit a user command would
304 be unpredictable. If you want to permit quitting inside a sentinel,
305 bind `inhibit-quit' to `nil'. *Note Quitting::.
307 A sentinel that writes the output into the buffer of the process
308 should check whether the buffer is still alive. If it tries to insert
309 into a dead buffer, it will get an error. If the buffer is dead,
310 `(buffer-name (process-buffer PROCESS))' returns `nil'.
312 If an error happens during execution of a sentinel, it is caught
313 automatically, so that it doesn't stop the execution of whatever
314 programs was running when the sentinel was started. However, if
315 `debug-on-error' is non-`nil', the error-catching is turned off. This
316 makes it possible to use the Lisp debugger to debug the sentinel.
319 In earlier Emacs versions, every sentinel that did regexp searching
320 or matching had to explicitly save and restore the match data. Now
321 Emacs does this automatically; sentinels never need to do it explicitly.
324 - Function: set-process-sentinel process sentinel
325 This function associates SENTINEL with PROCESS. If SENTINEL is
326 `nil', then the process will have no sentinel. The default
327 behavior when there is no sentinel is to insert a message in the
328 process's buffer when the process status changes.
330 (defun msg-me (process event)
332 (format "Process: %s had the event `%s'" process event)))
333 (set-process-sentinel (get-process "shell") 'msg-me)
335 (kill-process (get-process "shell"))
336 -| Process: #<process shell> had the event `killed'
339 - Function: process-sentinel process
340 This function returns the sentinel of PROCESS, or `nil' if it has
343 - Function: waiting-for-user-input-p
344 While a sentinel or filter function is running, this function
345 returns non-`nil' if XEmacs was waiting for keyboard input from
346 the user at the time the sentinel or filter function was called,
350 File: lispref.info, Node: Process Window Size, Next: Transaction Queues, Prev: Sentinels, Up: Processes
355 - Function: set-process-window-size process height width
356 This function tells PROCESS that its logical window size is HEIGHT
357 by WIDTH characters. This is principally useful with pty's.
360 File: lispref.info, Node: Transaction Queues, Next: Network, Prev: Process Window Size, Up: Processes
365 You can use a "transaction queue" for more convenient communication
366 with subprocesses using transactions. First use `tq-create' to create
367 a transaction queue communicating with a specified process. Then you
368 can call `tq-enqueue' to send a transaction.
370 - Function: tq-create process
371 This function creates and returns a transaction queue
372 communicating with PROCESS. The argument PROCESS should be a
373 subprocess capable of sending and receiving streams of bytes. It
374 may be a child process, or it may be a TCP connection to a server,
375 possibly on another machine.
377 - Function: tq-enqueue queue question regexp closure fn
378 This function sends a transaction to queue QUEUE. Specifying the
379 queue has the effect of specifying the subprocess to talk to.
381 The argument QUESTION is the outgoing message that starts the
382 transaction. The argument FN is the function to call when the
383 corresponding answer comes back; it is called with two arguments:
384 CLOSURE, and the answer received.
386 The argument REGEXP is a regular expression that should match the
387 entire answer, but nothing less; that's how `tq-enqueue' determines
388 where the answer ends.
390 The return value of `tq-enqueue' itself is not meaningful.
392 - Function: tq-close queue
393 Shut down transaction queue QUEUE, waiting for all pending
394 transactions to complete, and then terminate the connection or
397 Transaction queues are implemented by means of a filter function.
398 *Note Filter Functions::.
401 File: lispref.info, Node: Network, Prev: Transaction Queues, Up: Processes
406 XEmacs Lisp programs can open TCP network connections to other
407 processes on the same machine or other machines. A network connection
408 is handled by Lisp much like a subprocess, and is represented by a
409 process object. However, the process you are communicating with is not
410 a child of the XEmacs process, so you can't kill it or send it signals.
411 All you can do is send and receive data. `delete-process' closes the
412 connection, but does not kill the process at the other end; that
413 process must decide what to do about closure of the connection.
415 You can distinguish process objects representing network connections
416 from those representing subprocesses with the `process-status'
417 function. It always returns either `open' or `closed' for a network
418 connection, and it never returns either of those values for a real
419 subprocess. *Note Process Information::.
421 - Function: open-network-stream name buffer-or-name host service
422 This function opens a TCP connection for a service to a host. It
423 returns a process object to represent the connection.
425 The NAME argument specifies the name for the process object. It
426 is modified as necessary to make it unique.
428 The BUFFER-OR-NAME argument is the buffer to associate with the
429 connection. Output from the connection is inserted in the buffer,
430 unless you specify a filter function to handle the output. If
431 BUFFER-OR-NAME is `nil', it means that the connection is not
432 associated with any buffer.
434 The arguments HOST and SERVICE specify where to connect to; HOST
435 is the host name or IP address (a string), and SERVICE is the name
436 of a defined network service (a string) or a port number (an
440 File: lispref.info, Node: System Interface, Next: X-Windows, Prev: Processes, Up: Top
442 Operating System Interface
443 **************************
445 This chapter is about starting and getting out of Emacs, access to
446 values in the operating system environment, and terminal input, output,
449 *Note Building XEmacs::, for related information. See also *Note
450 Display::, for additional operating system status information
451 pertaining to the terminal and the screen.
455 * Starting Up:: Customizing XEmacs start-up processing.
456 * Getting Out:: How exiting works (permanent or temporary).
457 * System Environment:: Distinguish the name and kind of system.
458 * User Identification:: Finding the name and user id of the user.
459 * Time of Day:: Getting the current time.
460 * Time Conversion:: Converting a time from numeric form to a string, or
461 to calendrical data (or vice versa).
462 * Timers:: Setting a timer to call a function at a certain time.
463 * Terminal Input:: Recording terminal input for debugging.
464 * Terminal Output:: Recording terminal output for debugging.
465 * Flow Control:: How to turn output flow control on or off.
466 * Batch Mode:: Running XEmacs without terminal interaction.
469 File: lispref.info, Node: Starting Up, Next: Getting Out, Up: System Interface
474 This section describes what XEmacs does when it is started, and how
475 you can customize these actions.
479 * Start-up Summary:: Sequence of actions XEmacs performs at start-up.
480 * Init File:: Details on reading the init file (`.emacs').
481 * Terminal-Specific:: How the terminal-specific Lisp file is read.
482 * Command Line Arguments:: How command line arguments are processed,
483 and how you can customize them.
486 File: lispref.info, Node: Start-up Summary, Next: Init File, Up: Starting Up
488 Summary: Sequence of Actions at Start Up
489 ----------------------------------------
491 The order of operations performed (in `startup.el') by XEmacs when
492 it is started up is as follows:
494 1. It loads the initialization library for the window system, if you
495 are using a window system. This library's name is
496 `term/WINDOWSYSTEM-win.el'.
498 2. It processes the initial options. (Some of them are handled even
501 3. It initializes the X window frame and faces, if appropriate.
503 4. It runs the normal hook `before-init-hook'.
505 5. It loads the library `site-start', unless the option
506 `-no-site-file' was specified. The library's file name is usually
509 6. It loads the file `~/.emacs' unless `-q' was specified on the
510 command line. (This is not done in `-batch' mode.) The `-u'
511 option can specify the user name whose home directory should be
514 7. It loads the library `default' unless `inhibit-default-init' is
515 non-`nil'. (This is not done in `-batch' mode or if `-q' was
516 specified on the command line.) The library's file name is
517 usually `default.el'.
519 8. It runs the normal hook `after-init-hook'.
521 9. It sets the major mode according to `initial-major-mode', provided
522 the buffer `*scratch*' is still current and still in Fundamental
525 10. It loads the terminal-specific Lisp file, if any, except when in
526 batch mode or using a window system.
528 11. It displays the initial echo area message, unless you have
529 suppressed that with `inhibit-startup-echo-area-message'.
531 12. It processes the action arguments from the command line.
533 13. It runs `term-setup-hook'.
535 14. It calls `frame-notice-user-settings', which modifies the
536 parameters of the selected frame according to whatever the init
539 15. It runs `window-setup-hook'. *Note Terminal-Specific::.
541 16. It displays copyleft, nonwarranty, and basic use information,
542 provided there were no remaining command line arguments (a few
543 steps above) and the value of `inhibit-startup-message' is `nil'.
545 - User Option: inhibit-startup-message
546 This variable inhibits the initial startup messages (the
547 nonwarranty, etc.). If it is non-`nil', then the messages are not
550 This variable exists so you can set it in your personal init file,
551 once you are familiar with the contents of the startup message.
552 Do not set this variable in the init file of a new user, or in a
553 way that affects more than one user, because that would prevent
554 new users from receiving the information they are supposed to see.
556 - User Option: inhibit-startup-echo-area-message
557 This variable controls the display of the startup echo area
558 message. You can suppress the startup echo area message by adding
559 text with this form to your `.emacs' file:
561 (setq inhibit-startup-echo-area-message
564 Simply setting `inhibit-startup-echo-area-message' to your login
565 name is not sufficient to inhibit the message; Emacs explicitly
566 checks whether `.emacs' contains an expression as shown above.
567 Your login name must appear in the expression as a Lisp string
570 This way, you can easily inhibit the message for yourself if you
571 wish, but thoughtless copying of your `.emacs' file will not
572 inhibit the message for someone else.
575 File: lispref.info, Node: Init File, Next: Terminal-Specific, Prev: Start-up Summary, Up: Starting Up
577 The Init File: `.emacs'
578 -----------------------
580 When you start XEmacs, it normally attempts to load the file
581 `.emacs' from your home directory. This file, if it exists, must
582 contain Lisp code. It is called your "init file". The command line
583 switches `-q' and `-u' affect the use of the init file; `-q' says not
584 to load an init file, and `-u' says to load a specified user's init
585 file instead of yours. *Note Entering XEmacs: (xemacs)Entering XEmacs.
587 A site may have a "default init file", which is the library named
588 `default.el'. XEmacs finds the `default.el' file through the standard
589 search path for libraries (*note How Programs Do Loading::). The
590 XEmacs distribution does not come with this file; sites may provide one
591 for local customizations. If the default init file exists, it is
592 loaded whenever you start Emacs, except in batch mode or if `-q' is
593 specified. But your own personal init file, if any, is loaded first; if
594 it sets `inhibit-default-init' to a non-`nil' value, then XEmacs does
595 not subsequently load the `default.el' file.
597 Another file for site-customization is `site-start.el'. Emacs loads
598 this _before_ the user's init file. You can inhibit the loading of
599 this file with the option `-no-site-file'.
601 - Variable: site-run-file
602 This variable specifies the site-customization file to load before
603 the user's init file. Its normal value is `"site-start"'.
605 If there is a great deal of code in your `.emacs' file, you should
606 move it into another file named `SOMETHING.el', byte-compile it (*note
607 Byte Compilation::), and make your `.emacs' file load the other file
608 using `load' (*note Loading::).
610 *Note Init File Examples: (xemacs)Init File Examples, for examples
611 of how to make various commonly desired customizations in your `.emacs'
614 - User Option: inhibit-default-init
615 This variable prevents XEmacs from loading the default
616 initialization library file for your session of XEmacs. If its
617 value is non-`nil', then the default library is not loaded. The
618 default value is `nil'.
620 - Variable: before-init-hook
621 - Variable: after-init-hook
622 These two normal hooks are run just before, and just after,
623 loading of the user's init file, `default.el', and/or
627 File: lispref.info, Node: Terminal-Specific, Next: Command Line Arguments, Prev: Init File, Up: Starting Up
629 Terminal-Specific Initialization
630 --------------------------------
632 Each terminal type can have its own Lisp library that XEmacs loads
633 when run on that type of terminal. For a terminal type named TERMTYPE,
634 the library is called `term/TERMTYPE'. XEmacs finds the file by
635 searching the `load-path' directories as it does for other files, and
636 trying the `.elc' and `.el' suffixes. Normally, terminal-specific Lisp
637 library is located in `emacs/lisp/term', a subdirectory of the
638 `emacs/lisp' directory in which most XEmacs Lisp libraries are kept.
640 The library's name is constructed by concatenating the value of the
641 variable `term-file-prefix' and the terminal type. Normally,
642 `term-file-prefix' has the value `"term/"'; changing this is not
645 The usual function of a terminal-specific library is to enable
646 special keys to send sequences that XEmacs can recognize. It may also
647 need to set or add to `function-key-map' if the Termcap entry does not
648 specify all the terminal's function keys. *Note Terminal Input::.
650 When the name of the terminal type contains a hyphen, only the part
651 of the name before the first hyphen is significant in choosing the
652 library name. Thus, terminal types `aaa-48' and `aaa-30-rv' both use
653 the `term/aaa' library. If necessary, the library can evaluate
654 `(getenv "TERM")' to find the full name of the terminal type.
656 Your `.emacs' file can prevent the loading of the terminal-specific
657 library by setting the variable `term-file-prefix' to `nil'. This
658 feature is useful when experimenting with your own peculiar
661 You can also arrange to override some of the actions of the
662 terminal-specific library by setting the variable `term-setup-hook'.
663 This is a normal hook which XEmacs runs using `run-hooks' at the end of
664 XEmacs initialization, after loading both your `.emacs' file and any
665 terminal-specific libraries. You can use this variable to define
666 initializations for terminals that do not have their own libraries.
669 - Variable: term-file-prefix
670 If the `term-file-prefix' variable is non-`nil', XEmacs loads a
671 terminal-specific initialization file as follows:
673 (load (concat term-file-prefix (getenv "TERM")))
675 You may set the `term-file-prefix' variable to `nil' in your
676 `.emacs' file if you do not wish to load the
677 terminal-initialization file. To do this, put the following in
678 your `.emacs' file: `(setq term-file-prefix nil)'.
680 - Variable: term-setup-hook
681 This variable is a normal hook that XEmacs runs after loading your
682 `.emacs' file, the default initialization file (if any) and the
683 terminal-specific Lisp file.
685 You can use `term-setup-hook' to override the definitions made by a
686 terminal-specific file.
688 - Variable: window-setup-hook
689 This variable is a normal hook which XEmacs runs after loading your
690 `.emacs' file and the default initialization file (if any), after
691 loading terminal-specific Lisp code, and after running the hook
695 File: lispref.info, Node: Command Line Arguments, Prev: Terminal-Specific, Up: Starting Up
697 Command Line Arguments
698 ----------------------
700 You can use command line arguments to request various actions when
701 you start XEmacs. Since you do not need to start XEmacs more than once
702 per day, and will often leave your XEmacs session running longer than
703 that, command line arguments are hardly ever used. As a practical
704 matter, it is best to avoid making the habit of using them, since this
705 habit would encourage you to kill and restart XEmacs unnecessarily
706 often. These options exist for two reasons: to be compatible with
707 other editors (for invocation by other programs) and to enable shell
708 scripts to run specific Lisp programs.
710 This section describes how Emacs processes command line arguments,
711 and how you can customize them.
713 - Function: command-line
714 This function parses the command line that XEmacs was called with,
715 processes it, loads the user's `.emacs' file and displays the
718 - Variable: command-line-processed
719 The value of this variable is `t' once the command line has been
722 If you redump XEmacs by calling `dump-emacs', you may wish to set
723 this variable to `nil' first in order to cause the new dumped
724 XEmacs to process its new command line arguments.
726 - Variable: command-switch-alist
727 The value of this variable is an alist of user-defined command-line
728 options and associated handler functions. This variable exists so
729 you can add elements to it.
731 A "command line option" is an argument on the command line of the
736 The elements of the `command-switch-alist' look like this:
738 (OPTION . HANDLER-FUNCTION)
740 The HANDLER-FUNCTION is called to handle OPTION and receives the
741 option name as its sole argument.
743 In some cases, the option is followed in the command line by an
744 argument. In these cases, the HANDLER-FUNCTION can find all the
745 remaining command-line arguments in the variable
746 `command-line-args-left'. (The entire list of command-line
747 arguments is in `command-line-args'.)
749 The command line arguments are parsed by the `command-line-1'
750 function in the `startup.el' file. See also *Note Command Line
751 Switches and Arguments: (xemacs)Command Switches.
753 - Variable: command-line-args
754 The value of this variable is the list of command line arguments
757 - Variable: command-line-functions
758 This variable's value is a list of functions for handling an
759 unrecognized command-line argument. Each time the next argument
760 to be processed has no special meaning, the functions in this list
761 are called, in order of appearance, until one of them returns a
764 These functions are called with no arguments. They can access the
765 command-line argument under consideration through the variable
766 `argi'. The remaining arguments (not including the current one)
767 are in the variable `command-line-args-left'.
769 When a function recognizes and processes the argument in `argi', it
770 should return a non-`nil' value to say it has dealt with that
771 argument. If it has also dealt with some of the following
772 arguments, it can indicate that by deleting them from
773 `command-line-args-left'.
775 If all of these functions return `nil', then the argument is used
776 as a file name to visit.
779 File: lispref.info, Node: Getting Out, Next: System Environment, Prev: Starting Up, Up: System Interface
781 Getting out of XEmacs
782 =====================
784 There are two ways to get out of XEmacs: you can kill the XEmacs job,
785 which exits permanently, or you can suspend it, which permits you to
786 reenter the XEmacs process later. As a practical matter, you seldom
787 kill XEmacs--only when you are about to log out. Suspending is much
792 * Killing XEmacs:: Exiting XEmacs irreversibly.
793 * Suspending XEmacs:: Exiting XEmacs reversibly.
796 File: lispref.info, Node: Killing XEmacs, Next: Suspending XEmacs, Up: Getting Out
801 Killing XEmacs means ending the execution of the XEmacs process. The
802 parent process normally resumes control. The low-level primitive for
803 killing XEmacs is `kill-emacs'.
805 - Function: kill-emacs &optional exit-data
806 This function exits the XEmacs process and kills it.
808 If EXIT-DATA is an integer, then it is used as the exit status of
809 the XEmacs process. (This is useful primarily in batch operation;
810 see *Note Batch Mode::.)
812 If EXIT-DATA is a string, its contents are stuffed into the
813 terminal input buffer so that the shell (or whatever program next
814 reads input) can read them.
816 All the information in the XEmacs process, aside from files that have
817 been saved, is lost when the XEmacs is killed. Because killing XEmacs
818 inadvertently can lose a lot of work, XEmacs queries for confirmation
819 before actually terminating if you have buffers that need saving or
820 subprocesses that are running. This is done in the function
821 `save-buffers-kill-emacs'.
823 - Variable: kill-emacs-query-functions
824 After asking the standard questions, `save-buffers-kill-emacs'
825 calls the functions in the list `kill-buffer-query-functions', in
826 order of appearance, with no arguments. These functions can ask
827 for additional confirmation from the user. If any of them returns
828 non-`nil', XEmacs is not killed.
830 - Variable: kill-emacs-hook
831 This variable is a normal hook; once `save-buffers-kill-emacs' is
832 finished with all file saving and confirmation, it runs the
833 functions in this hook.
836 File: lispref.info, Node: Suspending XEmacs, Prev: Killing XEmacs, Up: Getting Out
841 "Suspending XEmacs" means stopping XEmacs temporarily and returning
842 control to its superior process, which is usually the shell. This
843 allows you to resume editing later in the same XEmacs process, with the
844 same buffers, the same kill ring, the same undo history, and so on. To
845 resume XEmacs, use the appropriate command in the parent shell--most
848 Some operating systems do not support suspension of jobs; on these
849 systems, "suspension" actually creates a new shell temporarily as a
850 subprocess of XEmacs. Then you would exit the shell to return to
853 Suspension is not useful with window systems such as X, because the
854 XEmacs job may not have a parent that can resume it again, and in any
855 case you can give input to some other job such as a shell merely by
856 moving to a different window. Therefore, suspending is not allowed
857 when XEmacs is an X client.
859 - Function: suspend-emacs string
860 This function stops XEmacs and returns control to the superior
861 process. If and when the superior process resumes XEmacs,
862 `suspend-emacs' returns `nil' to its caller in Lisp.
864 If STRING is non-`nil', its characters are sent to be read as
865 terminal input by XEmacs's superior shell. The characters in
866 STRING are not echoed by the superior shell; only the results
869 Before suspending, `suspend-emacs' runs the normal hook
870 `suspend-hook'. In Emacs version 18, `suspend-hook' was not a
871 normal hook; its value was a single function, and if its value was
872 non-`nil', then `suspend-emacs' returned immediately without
873 actually suspending anything.
875 After the user resumes XEmacs, `suspend-emacs' runs the normal hook
876 `suspend-resume-hook'. *Note Hooks::.
878 The next redisplay after resumption will redraw the entire screen,
879 unless the variable `no-redraw-on-reenter' is non-`nil' (*note
882 In the following example, note that `pwd' is not echoed after
883 XEmacs is suspended. But it is read and executed by the shell.
888 (add-hook 'suspend-hook
892 (error "Suspend cancelled")))))
894 (or (y-or-n-p "Really suspend? ")
895 (error "Suspend cancelled")))
896 (add-hook 'suspend-resume-hook
897 (function (lambda () (message "Resumed!"))))
898 => (lambda nil (message "Resumed!"))
899 (suspend-emacs "pwd")
901 ---------- Buffer: Minibuffer ----------
903 ---------- Buffer: Minibuffer ----------
905 ---------- Parent Shell ----------
906 lewis@slug[23] % /user/lewis/manual
909 ---------- Echo Area ----------
912 - Variable: suspend-hook
913 This variable is a normal hook run before suspending.
915 - Variable: suspend-resume-hook
916 This variable is a normal hook run after suspending.
919 File: lispref.info, Node: System Environment, Next: User Identification, Prev: Getting Out, Up: System Interface
921 Operating System Environment
922 ============================
924 XEmacs provides access to variables in the operating system
925 environment through various functions. These variables include the
926 name of the system, the user's UID, and so on.
928 - Variable: system-type
929 The value of this variable is a symbol indicating the type of
930 operating system XEmacs is operating on. Here is a table of the
940 Data General DGUX operating system.
943 A GNU system using the GNU HURD and Mach.
946 Hewlett-Packard HPUX operating system.
949 Silicon Graphics Irix system.
952 A GNU system using the Linux kernel.
955 Microsoft MS-DOS "operating system."
958 NeXT Mach-based system.
961 Masscomp RTU, UCB universe.
973 Microsoft windows NT.
978 We do not wish to add new symbols to make finer distinctions
979 unless it is absolutely necessary! In fact, we hope to eliminate
980 some of these alternatives in the future. We recommend using
981 `system-configuration' to distinguish between different operating
984 - Variable: system-configuration
985 This variable holds the three-part configuration name for the
986 hardware/software configuration of your system, as a string. The
987 convenient way to test parts of this string is with `string-match'.
989 - Function: system-name
990 This function returns the name of the machine you are running on.
994 The symbol `system-name' is a variable as well as a function. In
995 fact, the function returns whatever value the variable `system-name'
996 currently holds. Thus, you can set the variable `system-name' in case
997 Emacs is confused about the name of your system. The variable is also
998 useful for constructing frame titles (*note Frame Titles::).
1000 - Variable: mail-host-address
1001 If this variable is non-`nil', it is used instead of `system-name'
1002 for purposes of generating email addresses. For example, it is
1003 used when constructing the default value of `user-mail-address'.
1004 *Note User Identification::. (Since this is done when XEmacs
1005 starts up, the value actually used is the one saved when XEmacs
1006 was dumped. *Note Building XEmacs::.)
1008 - Function: getenv var
1009 This function returns the value of the environment variable VAR,
1010 as a string. Within XEmacs, the environment variable values are
1011 kept in the Lisp variable `process-environment'.
1016 lewis@slug[10] % printenv
1017 PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
1023 - Command: setenv variable value
1024 This command sets the value of the environment variable named
1025 VARIABLE to VALUE. Both arguments should be strings. This
1026 function works by modifying `process-environment'; binding that
1027 variable with `let' is also reasonable practice.
1029 - Variable: process-environment
1030 This variable is a list of strings, each describing one environment
1031 variable. The functions `getenv' and `setenv' work by means of
1035 => ("l=/usr/stanford/lib/gnuemacs/lisp"
1036 "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
1042 - Variable: path-separator
1043 This variable holds a string which says which character separates
1044 directories in a search path (as found in an environment
1045 variable). Its value is `":"' for Unix and GNU systems, and `";"'
1046 for MS-DOS and Windows NT.
1048 - Variable: invocation-name
1049 This variable holds the program name under which Emacs was
1050 invoked. The value is a string, and does not include a directory
1053 - Variable: invocation-directory
1054 This variable holds the directory from which the Emacs executable
1055 was invoked, or perhaps `nil' if that directory cannot be
1058 - Variable: installation-directory
1059 If non-`nil', this is a directory within which to look for the
1060 `lib-src' and `etc' subdirectories. This is non-`nil' when Emacs
1061 can't find those directories in their standard installed
1062 locations, but can find them in a directory related somehow to the
1063 one containing the Emacs executable.
1065 - Function: load-average &optional use-floats
1066 This function returns a list of the current 1-minute, 5-minute and
1067 15-minute load averages. The values are integers that are 100
1068 times the system load averages. (The load averages indicate the
1069 number of processes trying to run.)
1071 When USE-FLOATS is non-`nil', floats will be returned instead of
1072 integers. These floats are not multiplied by 100.
1077 => (1.69921875 1.58984375 1.640625)
1079 lewis@rocky[5] % uptime
1080 8:06pm up 16 day(s), 21:57, 40 users,
1081 load average: 1.68, 1.59, 1.64
1083 If the 5-minute or 15-minute load averages are not available,
1084 return a shortened list, containing only those averages which are
1087 On some systems, this function may require special privileges to
1088 run, or it may be unimplemented for the particular system type.
1089 In that case, the function will signal an error.
1091 - Function: emacs-pid
1092 This function returns the process ID of the Emacs process.
1094 - Function: setprv privilege-name &optional setp getprv
1095 This function sets or resets a VMS privilege. (It does not exist
1096 on Unix.) The first arg is the privilege name, as a string. The
1097 second argument, SETP, is `t' or `nil', indicating whether the
1098 privilege is to be turned on or off. Its default is `nil'. The
1099 function returns `t' if successful, `nil' otherwise.
1101 If the third argument, GETPRV, is non-`nil', `setprv' does not
1102 change the privilege, but returns `t' or `nil' indicating whether
1103 the privilege is currently enabled.
1106 File: lispref.info, Node: User Identification, Next: Time of Day, Prev: System Environment, Up: System Interface
1111 - Variable: user-mail-address
1112 This holds the nominal email address of the user who is using
1113 Emacs. When Emacs starts up, it computes a default value that is
1114 usually right, but users often set this themselves when the
1115 default value is not right.
1117 - Function: user-login-name &optional uid
1118 If you don't specify UID, this function returns the name under
1119 which the user is logged in. If the environment variable `LOGNAME'
1120 is set, that value is used. Otherwise, if the environment variable
1121 `USER' is set, that value is used. Otherwise, the value is based
1122 on the effective UID, not the real UID.
1124 If you specify UID, the value is the user name that corresponds to
1125 UID (which should be an integer).
1130 - Function: user-real-login-name
1131 This function returns the user name corresponding to Emacs's real
1132 UID. This ignores the effective UID and ignores the environment
1133 variables `LOGNAME' and `USER'.
1135 - Variable: user-full-name
1136 This variable holds the name of the user running this Emacs. It is
1137 initialized at startup time from the value of `NAME' environment
1138 variable. You can change the value of this variable to alter the
1139 result of the `user-full-name' function.
1141 - Function: user-full-name &optional user
1142 This function returns the full name of USER. If USER is `nil', it
1143 defaults to the user running this Emacs. In that case, the value
1144 of `user-full-name' variable, if non-`nil', will be used.
1146 If USER is specified explicitly, `user-full-name' variable is
1151 (setq user-full-name "Hrvoje \"Niksa\" Niksic")
1153 => "Hrvoje \"Niksa\" Niksic"
1154 (user-full-name "hniksic")
1157 The symbols `user-login-name', `user-real-login-name' and
1158 `user-full-name' are variables as well as functions. The functions
1159 return the same values that the variables hold. These variables allow
1160 you to "fake out" Emacs by telling the functions what to return. The
1161 variables are also useful for constructing frame titles (*note Frame
1164 - Function: user-real-uid
1165 This function returns the real UID of the user.
1170 - Function: user-uid
1171 This function returns the effective UID of the user.
1173 - Function: user-home-directory
1174 This function returns the "`HOME'" directory of the user, and is
1175 intended to replace occurrences of "`(getenv "HOME")'". Under
1176 Unix systems, the following is done:
1178 1. Return the value of "`(getenv "HOME")'", if set.
1180 2. Return "/", as a fallback, but issue a warning. (Future
1181 versions of XEmacs will also attempt to lookup the `HOME'
1182 directory via `getpwent()', but this has not yet been
1185 Under MS Windows, this is done:
1187 1. Return the value of "`(getenv "HOME")'", if set.
1189 2. If the environment variables `HOMEDRIVE' and `HOMEDIR' are
1190 both set, return the concatenation (the following description
1191 uses MS Windows environment variable substitution syntax):
1192 `%HOMEDRIVE%%HOMEDIR%'.
1194 3. Return "C:\", as a fallback, but issue a warning.
projects / chise / xemacs-chise.git- / blob