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: Sentinels, Next: Process Window Size, Prev: Output from Processes, Up: Processes
55 Sentinels: Detecting Process Status Changes
56 ===========================================
58 A "process sentinel" is a function that is called whenever the
59 associated process changes status for any reason, including signals
60 (whether sent by XEmacs or caused by the process's own actions) that
61 terminate, stop, or continue the process. The process sentinel is also
62 called if the process exits. The sentinel receives two arguments: the
63 process for which the event occurred, and a string describing the type
66 The string describing the event looks like one of the following:
70 * `"exited abnormally with code EXITCODE\n"'.
72 * `"NAME-OF-SIGNAL\n"'.
74 * `"NAME-OF-SIGNAL (core dumped)\n"'.
76 A sentinel runs only while XEmacs is waiting (e.g., for terminal
77 input, or for time to elapse, or for process output). This avoids the
78 timing errors that could result from running them at random places in
79 the middle of other Lisp programs. A program can wait, so that
80 sentinels will run, by calling `sit-for' or `sleep-for' (*note
81 Waiting::), or `accept-process-output' (*note Accepting Output::).
82 Emacs is also waiting when the command loop is reading input.
84 Quitting is normally inhibited within a sentinel--otherwise, the
85 effect of typing `C-g' at command level or to quit a user command would
86 be unpredictable. If you want to permit quitting inside a sentinel,
87 bind `inhibit-quit' to `nil'. *Note Quitting::.
89 A sentinel that writes the output into the buffer of the process
90 should check whether the buffer is still alive. If it tries to insert
91 into a dead buffer, it will get an error. If the buffer is dead,
92 `(buffer-name (process-buffer PROCESS))' returns `nil'.
94 If an error happens during execution of a sentinel, it is caught
95 automatically, so that it doesn't stop the execution of whatever
96 programs was running when the sentinel was started. However, if
97 `debug-on-error' is non-`nil', the error-catching is turned off. This
98 makes it possible to use the Lisp debugger to debug the sentinel.
101 In earlier Emacs versions, every sentinel that did regexp searching
102 or matching had to explicitly save and restore the match data. Now
103 Emacs does this automatically; sentinels never need to do it explicitly.
106 - Function: set-process-sentinel process sentinel
107 This function associates SENTINEL with PROCESS. If SENTINEL is
108 `nil', then the process will have no sentinel. The default
109 behavior when there is no sentinel is to insert a message in the
110 process's buffer when the process status changes.
112 (defun msg-me (process event)
114 (format "Process: %s had the event `%s'" process event)))
115 (set-process-sentinel (get-process "shell") 'msg-me)
117 (kill-process (get-process "shell"))
118 -| Process: #<process shell> had the event `killed'
121 - Function: process-sentinel process
122 This function returns the sentinel of PROCESS, or `nil' if it has
125 - Function: waiting-for-user-input-p
126 While a sentinel or filter function is running, this function
127 returns non-`nil' if XEmacs was waiting for keyboard input from
128 the user at the time the sentinel or filter function was called,
132 File: lispref.info, Node: Process Window Size, Next: Transaction Queues, Prev: Sentinels, Up: Processes
137 - Function: set-process-window-size process height width
138 This function tells PROCESS that its logical window size is HEIGHT
139 by WIDTH characters. This is principally useful with pty's.
142 File: lispref.info, Node: Transaction Queues, Next: Network, Prev: Process Window Size, Up: Processes
147 You can use a "transaction queue" for more convenient communication
148 with subprocesses using transactions. First use `tq-create' to create
149 a transaction queue communicating with a specified process. Then you
150 can call `tq-enqueue' to send a transaction.
152 - Function: tq-create process
153 This function creates and returns a transaction queue
154 communicating with PROCESS. The argument PROCESS should be a
155 subprocess capable of sending and receiving streams of bytes. It
156 may be a child process, or it may be a TCP connection to a server,
157 possibly on another machine.
159 - Function: tq-enqueue queue question regexp closure fn
160 This function sends a transaction to queue QUEUE. Specifying the
161 queue has the effect of specifying the subprocess to talk to.
163 The argument QUESTION is the outgoing message that starts the
164 transaction. The argument FN is the function to call when the
165 corresponding answer comes back; it is called with two arguments:
166 CLOSURE, and the answer received.
168 The argument REGEXP is a regular expression that should match the
169 entire answer, but nothing less; that's how `tq-enqueue' determines
170 where the answer ends.
172 The return value of `tq-enqueue' itself is not meaningful.
174 - Function: tq-close queue
175 Shut down transaction queue QUEUE, waiting for all pending
176 transactions to complete, and then terminate the connection or
179 Transaction queues are implemented by means of a filter function.
180 *Note Filter Functions::.
183 File: lispref.info, Node: Network, Prev: Transaction Queues, Up: Processes
188 XEmacs Lisp programs can open TCP network connections to other
189 processes on the same machine or other machines. A network connection
190 is handled by Lisp much like a subprocess, and is represented by a
191 process object. However, the process you are communicating with is not
192 a child of the XEmacs process, so you can't kill it or send it signals.
193 All you can do is send and receive data. `delete-process' closes the
194 connection, but does not kill the process at the other end; that
195 process must decide what to do about closure of the connection.
197 You can distinguish process objects representing network connections
198 from those representing subprocesses with the `process-status'
199 function. It always returns either `open' or `closed' for a network
200 connection, and it never returns either of those values for a real
201 subprocess. *Note Process Information::.
203 - Function: open-network-stream name buffer-or-name host service
204 This function opens a TCP connection for a service to a host. It
205 returns a process object to represent the connection.
207 The NAME argument specifies the name for the process object. It
208 is modified as necessary to make it unique.
210 The BUFFER-OR-NAME argument is the buffer to associate with the
211 connection. Output from the connection is inserted in the buffer,
212 unless you specify a filter function to handle the output. If
213 BUFFER-OR-NAME is `nil', it means that the connection is not
214 associated with any buffer.
216 The arguments HOST and SERVICE specify where to connect to; HOST
217 is the host name or IP address (a string), and SERVICE is the name
218 of a defined network service (a string) or a port number (an
222 File: lispref.info, Node: System Interface, Next: X-Windows, Prev: Processes, Up: Top
224 Operating System Interface
225 **************************
227 This chapter is about starting and getting out of Emacs, access to
228 values in the operating system environment, and terminal input, output,
231 *Note Building XEmacs::, for related information. See also *Note
232 Display::, for additional operating system status information
233 pertaining to the terminal and the screen.
237 * Starting Up:: Customizing XEmacs start-up processing.
238 * Getting Out:: How exiting works (permanent or temporary).
239 * System Environment:: Distinguish the name and kind of system.
240 * User Identification:: Finding the name and user id of the user.
241 * Time of Day:: Getting the current time.
242 * Time Conversion:: Converting a time from numeric form to a string, or
243 to calendrical data (or vice versa).
244 * Timers:: Setting a timer to call a function at a certain time.
245 * Terminal Input:: Recording terminal input for debugging.
246 * Terminal Output:: Recording terminal output for debugging.
247 * Flow Control:: How to turn output flow control on or off.
248 * Batch Mode:: Running XEmacs without terminal interaction.
251 File: lispref.info, Node: Starting Up, Next: Getting Out, Up: System Interface
256 This section describes what XEmacs does when it is started, and how
257 you can customize these actions.
261 * Start-up Summary:: Sequence of actions XEmacs performs at start-up.
262 * Init File:: Details on reading the init file (`.emacs').
263 * Terminal-Specific:: How the terminal-specific Lisp file is read.
264 * Command Line Arguments:: How command line arguments are processed,
265 and how you can customize them.
268 File: lispref.info, Node: Start-up Summary, Next: Init File, Up: Starting Up
270 Summary: Sequence of Actions at Start Up
271 ----------------------------------------
273 The order of operations performed (in `startup.el') by XEmacs when
274 it is started up is as follows:
276 1. It loads the initialization library for the window system, if you
277 are using a window system. This library's name is
278 `term/WINDOWSYSTEM-win.el'.
280 2. It processes the initial options. (Some of them are handled even
283 3. It initializes the X window frame and faces, if appropriate.
285 4. It runs the normal hook `before-init-hook'.
287 5. It loads the library `site-start', unless the option
288 `-no-site-file' was specified. The library's file name is usually
291 6. It loads the file `~/.emacs' unless `-q' was specified on the
292 command line. (This is not done in `-batch' mode.) The `-u'
293 option can specify the user name whose home directory should be
296 7. It loads the library `default' unless `inhibit-default-init' is
297 non-`nil'. (This is not done in `-batch' mode or if `-q' was
298 specified on the command line.) The library's file name is
299 usually `default.el'.
301 8. It runs the normal hook `after-init-hook'.
303 9. It sets the major mode according to `initial-major-mode', provided
304 the buffer `*scratch*' is still current and still in Fundamental
307 10. It loads the terminal-specific Lisp file, if any, except when in
308 batch mode or using a window system.
310 11. It displays the initial echo area message, unless you have
311 suppressed that with `inhibit-startup-echo-area-message'.
313 12. It processes the action arguments from the command line.
315 13. It runs `term-setup-hook'.
317 14. It calls `frame-notice-user-settings', which modifies the
318 parameters of the selected frame according to whatever the init
321 15. It runs `window-setup-hook'. *Note Terminal-Specific::.
323 16. It displays copyleft, nonwarranty, and basic use information,
324 provided there were no remaining command line arguments (a few
325 steps above) and the value of `inhibit-startup-message' is `nil'.
327 - User Option: inhibit-startup-message
328 This variable inhibits the initial startup messages (the
329 nonwarranty, etc.). If it is non-`nil', then the messages are not
332 This variable exists so you can set it in your personal init file,
333 once you are familiar with the contents of the startup message.
334 Do not set this variable in the init file of a new user, or in a
335 way that affects more than one user, because that would prevent
336 new users from receiving the information they are supposed to see.
338 - User Option: inhibit-startup-echo-area-message
339 This variable controls the display of the startup echo area
340 message. You can suppress the startup echo area message by adding
341 text with this form to your `.emacs' file:
343 (setq inhibit-startup-echo-area-message
346 Simply setting `inhibit-startup-echo-area-message' to your login
347 name is not sufficient to inhibit the message; Emacs explicitly
348 checks whether `.emacs' contains an expression as shown above.
349 Your login name must appear in the expression as a Lisp string
352 This way, you can easily inhibit the message for yourself if you
353 wish, but thoughtless copying of your `.emacs' file will not
354 inhibit the message for someone else.
357 File: lispref.info, Node: Init File, Next: Terminal-Specific, Prev: Start-up Summary, Up: Starting Up
359 The Init File: `.emacs'
360 -----------------------
362 When you start XEmacs, it normally attempts to load the file
363 `.emacs' from your home directory. This file, if it exists, must
364 contain Lisp code. It is called your "init file". The command line
365 switches `-q' and `-u' affect the use of the init file; `-q' says not
366 to load an init file, and `-u' says to load a specified user's init
367 file instead of yours. *Note Entering XEmacs: (xemacs)Entering XEmacs.
369 A site may have a "default init file", which is the library named
370 `default.el'. XEmacs finds the `default.el' file through the standard
371 search path for libraries (*note How Programs Do Loading::). The
372 XEmacs distribution does not come with this file; sites may provide one
373 for local customizations. If the default init file exists, it is
374 loaded whenever you start Emacs, except in batch mode or if `-q' is
375 specified. But your own personal init file, if any, is loaded first; if
376 it sets `inhibit-default-init' to a non-`nil' value, then XEmacs does
377 not subsequently load the `default.el' file.
379 Another file for site-customization is `site-start.el'. Emacs loads
380 this _before_ the user's init file. You can inhibit the loading of
381 this file with the option `-no-site-file'.
383 - Variable: site-run-file
384 This variable specifies the site-customization file to load before
385 the user's init file. Its normal value is `"site-start"'.
387 If there is a great deal of code in your `.emacs' file, you should
388 move it into another file named `SOMETHING.el', byte-compile it (*note
389 Byte Compilation::), and make your `.emacs' file load the other file
390 using `load' (*note Loading::).
392 *Note Init File Examples: (xemacs)Init File Examples, for examples
393 of how to make various commonly desired customizations in your `.emacs'
396 - User Option: inhibit-default-init
397 This variable prevents XEmacs from loading the default
398 initialization library file for your session of XEmacs. If its
399 value is non-`nil', then the default library is not loaded. The
400 default value is `nil'.
402 - Variable: before-init-hook
403 - Variable: after-init-hook
404 These two normal hooks are run just before, and just after,
405 loading of the user's init file, `default.el', and/or
409 File: lispref.info, Node: Terminal-Specific, Next: Command Line Arguments, Prev: Init File, Up: Starting Up
411 Terminal-Specific Initialization
412 --------------------------------
414 Each terminal type can have its own Lisp library that XEmacs loads
415 when run on that type of terminal. For a terminal type named TERMTYPE,
416 the library is called `term/TERMTYPE'. XEmacs finds the file by
417 searching the `load-path' directories as it does for other files, and
418 trying the `.elc' and `.el' suffixes. Normally, terminal-specific Lisp
419 library is located in `emacs/lisp/term', a subdirectory of the
420 `emacs/lisp' directory in which most XEmacs Lisp libraries are kept.
422 The library's name is constructed by concatenating the value of the
423 variable `term-file-prefix' and the terminal type. Normally,
424 `term-file-prefix' has the value `"term/"'; changing this is not
427 The usual function of a terminal-specific library is to enable
428 special keys to send sequences that XEmacs can recognize. It may also
429 need to set or add to `function-key-map' if the Termcap entry does not
430 specify all the terminal's function keys. *Note Terminal Input::.
432 When the name of the terminal type contains a hyphen, only the part
433 of the name before the first hyphen is significant in choosing the
434 library name. Thus, terminal types `aaa-48' and `aaa-30-rv' both use
435 the `term/aaa' library. If necessary, the library can evaluate
436 `(getenv "TERM")' to find the full name of the terminal type.
438 Your `.emacs' file can prevent the loading of the terminal-specific
439 library by setting the variable `term-file-prefix' to `nil'. This
440 feature is useful when experimenting with your own peculiar
443 You can also arrange to override some of the actions of the
444 terminal-specific library by setting the variable `term-setup-hook'.
445 This is a normal hook which XEmacs runs using `run-hooks' at the end of
446 XEmacs initialization, after loading both your `.emacs' file and any
447 terminal-specific libraries. You can use this variable to define
448 initializations for terminals that do not have their own libraries.
451 - Variable: term-file-prefix
452 If the `term-file-prefix' variable is non-`nil', XEmacs loads a
453 terminal-specific initialization file as follows:
455 (load (concat term-file-prefix (getenv "TERM")))
457 You may set the `term-file-prefix' variable to `nil' in your
458 `.emacs' file if you do not wish to load the
459 terminal-initialization file. To do this, put the following in
460 your `.emacs' file: `(setq term-file-prefix nil)'.
462 - Variable: term-setup-hook
463 This variable is a normal hook that XEmacs runs after loading your
464 `.emacs' file, the default initialization file (if any) and the
465 terminal-specific Lisp file.
467 You can use `term-setup-hook' to override the definitions made by a
468 terminal-specific file.
470 - Variable: window-setup-hook
471 This variable is a normal hook which XEmacs runs after loading your
472 `.emacs' file and the default initialization file (if any), after
473 loading terminal-specific Lisp code, and after running the hook
477 File: lispref.info, Node: Command Line Arguments, Prev: Terminal-Specific, Up: Starting Up
479 Command Line Arguments
480 ----------------------
482 You can use command line arguments to request various actions when
483 you start XEmacs. Since you do not need to start XEmacs more than once
484 per day, and will often leave your XEmacs session running longer than
485 that, command line arguments are hardly ever used. As a practical
486 matter, it is best to avoid making the habit of using them, since this
487 habit would encourage you to kill and restart XEmacs unnecessarily
488 often. These options exist for two reasons: to be compatible with
489 other editors (for invocation by other programs) and to enable shell
490 scripts to run specific Lisp programs.
492 This section describes how Emacs processes command line arguments,
493 and how you can customize them.
495 - Function: command-line
496 This function parses the command line that XEmacs was called with,
497 processes it, loads the user's `.emacs' file and displays the
500 - Variable: command-line-processed
501 The value of this variable is `t' once the command line has been
504 If you redump XEmacs by calling `dump-emacs', you may wish to set
505 this variable to `nil' first in order to cause the new dumped
506 XEmacs to process its new command line arguments.
508 - Variable: command-switch-alist
509 The value of this variable is an alist of user-defined command-line
510 options and associated handler functions. This variable exists so
511 you can add elements to it.
513 A "command line option" is an argument on the command line of the
518 The elements of the `command-switch-alist' look like this:
520 (OPTION . HANDLER-FUNCTION)
522 The HANDLER-FUNCTION is called to handle OPTION and receives the
523 option name as its sole argument.
525 In some cases, the option is followed in the command line by an
526 argument. In these cases, the HANDLER-FUNCTION can find all the
527 remaining command-line arguments in the variable
528 `command-line-args-left'. (The entire list of command-line
529 arguments is in `command-line-args'.)
531 The command line arguments are parsed by the `command-line-1'
532 function in the `startup.el' file. See also *Note Command Line
533 Switches and Arguments: (xemacs)Command Switches.
535 - Variable: command-line-args
536 The value of this variable is the list of command line arguments
539 - Variable: command-line-functions
540 This variable's value is a list of functions for handling an
541 unrecognized command-line argument. Each time the next argument
542 to be processed has no special meaning, the functions in this list
543 are called, in order of appearance, until one of them returns a
546 These functions are called with no arguments. They can access the
547 command-line argument under consideration through the variable
548 `argi'. The remaining arguments (not including the current one)
549 are in the variable `command-line-args-left'.
551 When a function recognizes and processes the argument in `argi', it
552 should return a non-`nil' value to say it has dealt with that
553 argument. If it has also dealt with some of the following
554 arguments, it can indicate that by deleting them from
555 `command-line-args-left'.
557 If all of these functions return `nil', then the argument is used
558 as a file name to visit.
561 File: lispref.info, Node: Getting Out, Next: System Environment, Prev: Starting Up, Up: System Interface
563 Getting out of XEmacs
564 =====================
566 There are two ways to get out of XEmacs: you can kill the XEmacs job,
567 which exits permanently, or you can suspend it, which permits you to
568 reenter the XEmacs process later. As a practical matter, you seldom
569 kill XEmacs--only when you are about to log out. Suspending is much
574 * Killing XEmacs:: Exiting XEmacs irreversibly.
575 * Suspending XEmacs:: Exiting XEmacs reversibly.
578 File: lispref.info, Node: Killing XEmacs, Next: Suspending XEmacs, Up: Getting Out
583 Killing XEmacs means ending the execution of the XEmacs process. The
584 parent process normally resumes control. The low-level primitive for
585 killing XEmacs is `kill-emacs'.
587 - Function: kill-emacs &optional exit-data
588 This function exits the XEmacs process and kills it.
590 If EXIT-DATA is an integer, then it is used as the exit status of
591 the XEmacs process. (This is useful primarily in batch operation;
592 see *Note Batch Mode::.)
594 If EXIT-DATA is a string, its contents are stuffed into the
595 terminal input buffer so that the shell (or whatever program next
596 reads input) can read them.
598 All the information in the XEmacs process, aside from files that have
599 been saved, is lost when the XEmacs is killed. Because killing XEmacs
600 inadvertently can lose a lot of work, XEmacs queries for confirmation
601 before actually terminating if you have buffers that need saving or
602 subprocesses that are running. This is done in the function
603 `save-buffers-kill-emacs'.
605 - Variable: kill-emacs-query-functions
606 After asking the standard questions, `save-buffers-kill-emacs'
607 calls the functions in the list `kill-buffer-query-functions', in
608 order of appearance, with no arguments. These functions can ask
609 for additional confirmation from the user. If any of them returns
610 non-`nil', XEmacs is not killed.
612 - Variable: kill-emacs-hook
613 This variable is a normal hook; once `save-buffers-kill-emacs' is
614 finished with all file saving and confirmation, it runs the
615 functions in this hook.
618 File: lispref.info, Node: Suspending XEmacs, Prev: Killing XEmacs, Up: Getting Out
623 "Suspending XEmacs" means stopping XEmacs temporarily and returning
624 control to its superior process, which is usually the shell. This
625 allows you to resume editing later in the same XEmacs process, with the
626 same buffers, the same kill ring, the same undo history, and so on. To
627 resume XEmacs, use the appropriate command in the parent shell--most
630 Some operating systems do not support suspension of jobs; on these
631 systems, "suspension" actually creates a new shell temporarily as a
632 subprocess of XEmacs. Then you would exit the shell to return to
635 Suspension is not useful with window systems such as X, because the
636 XEmacs job may not have a parent that can resume it again, and in any
637 case you can give input to some other job such as a shell merely by
638 moving to a different window. Therefore, suspending is not allowed
639 when XEmacs is an X client.
641 - Function: suspend-emacs string
642 This function stops XEmacs and returns control to the superior
643 process. If and when the superior process resumes XEmacs,
644 `suspend-emacs' returns `nil' to its caller in Lisp.
646 If STRING is non-`nil', its characters are sent to be read as
647 terminal input by XEmacs's superior shell. The characters in
648 STRING are not echoed by the superior shell; only the results
651 Before suspending, `suspend-emacs' runs the normal hook
652 `suspend-hook'. In Emacs version 18, `suspend-hook' was not a
653 normal hook; its value was a single function, and if its value was
654 non-`nil', then `suspend-emacs' returned immediately without
655 actually suspending anything.
657 After the user resumes XEmacs, `suspend-emacs' runs the normal hook
658 `suspend-resume-hook'. *Note Hooks::.
660 The next redisplay after resumption will redraw the entire screen,
661 unless the variable `no-redraw-on-reenter' is non-`nil' (*note
664 In the following example, note that `pwd' is not echoed after
665 XEmacs is suspended. But it is read and executed by the shell.
670 (add-hook 'suspend-hook
674 (error "Suspend cancelled")))))
676 (or (y-or-n-p "Really suspend? ")
677 (error "Suspend cancelled")))
678 (add-hook 'suspend-resume-hook
679 (function (lambda () (message "Resumed!"))))
680 => (lambda nil (message "Resumed!"))
681 (suspend-emacs "pwd")
683 ---------- Buffer: Minibuffer ----------
685 ---------- Buffer: Minibuffer ----------
687 ---------- Parent Shell ----------
688 lewis@slug[23] % /user/lewis/manual
691 ---------- Echo Area ----------
694 - Variable: suspend-hook
695 This variable is a normal hook run before suspending.
697 - Variable: suspend-resume-hook
698 This variable is a normal hook run after suspending.
701 File: lispref.info, Node: System Environment, Next: User Identification, Prev: Getting Out, Up: System Interface
703 Operating System Environment
704 ============================
706 XEmacs provides access to variables in the operating system
707 environment through various functions. These variables include the
708 name of the system, the user's UID, and so on.
710 - Variable: system-type
711 The value of this variable is a symbol indicating the type of
712 operating system XEmacs is operating on. Here is a table of the
722 Data General DGUX operating system.
725 A GNU system using the GNU HURD and Mach.
728 Hewlett-Packard HPUX operating system.
731 Silicon Graphics Irix system.
734 A GNU system using the Linux kernel.
737 Microsoft MS-DOS "operating system."
740 NeXT Mach-based system.
743 Masscomp RTU, UCB universe.
755 Microsoft windows NT.
760 We do not wish to add new symbols to make finer distinctions
761 unless it is absolutely necessary! In fact, we hope to eliminate
762 some of these alternatives in the future. We recommend using
763 `system-configuration' to distinguish between different operating
766 - Variable: system-configuration
767 This variable holds the three-part configuration name for the
768 hardware/software configuration of your system, as a string. The
769 convenient way to test parts of this string is with `string-match'.
771 - Function: system-name
772 This function returns the name of the machine you are running on.
776 The symbol `system-name' is a variable as well as a function. In
777 fact, the function returns whatever value the variable `system-name'
778 currently holds. Thus, you can set the variable `system-name' in case
779 Emacs is confused about the name of your system. The variable is also
780 useful for constructing frame titles (*note Frame Titles::).
782 - Variable: mail-host-address
783 If this variable is non-`nil', it is used instead of `system-name'
784 for purposes of generating email addresses. For example, it is
785 used when constructing the default value of `user-mail-address'.
786 *Note User Identification::. (Since this is done when XEmacs
787 starts up, the value actually used is the one saved when XEmacs
788 was dumped. *Note Building XEmacs::.)
790 - Function: getenv var
791 This function returns the value of the environment variable VAR,
792 as a string. Within XEmacs, the environment variable values are
793 kept in the Lisp variable `process-environment'.
798 lewis@slug[10] % printenv
799 PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
805 - Command: setenv variable value
806 This command sets the value of the environment variable named
807 VARIABLE to VALUE. Both arguments should be strings. This
808 function works by modifying `process-environment'; binding that
809 variable with `let' is also reasonable practice.
811 - Variable: process-environment
812 This variable is a list of strings, each describing one environment
813 variable. The functions `getenv' and `setenv' work by means of
817 => ("l=/usr/stanford/lib/gnuemacs/lisp"
818 "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
824 - Variable: path-separator
825 This variable holds a string which says which character separates
826 directories in a search path (as found in an environment
827 variable). Its value is `":"' for Unix and GNU systems, and `";"'
828 for MS-DOS and Windows NT.
830 - Variable: invocation-name
831 This variable holds the program name under which Emacs was
832 invoked. The value is a string, and does not include a directory
835 - Variable: invocation-directory
836 This variable holds the directory from which the Emacs executable
837 was invoked, or perhaps `nil' if that directory cannot be
840 - Variable: installation-directory
841 If non-`nil', this is a directory within which to look for the
842 `lib-src' and `etc' subdirectories. This is non-`nil' when Emacs
843 can't find those directories in their standard installed
844 locations, but can find them in a directory related somehow to the
845 one containing the Emacs executable.
847 - Function: load-average &optional use-floats
848 This function returns a list of the current 1-minute, 5-minute and
849 15-minute load averages. The values are integers that are 100
850 times the system load averages. (The load averages indicate the
851 number of processes trying to run.)
853 When USE-FLOATS is non-`nil', floats will be returned instead of
854 integers. These floats are not multiplied by 100.
859 => (1.69921875 1.58984375 1.640625)
861 lewis@rocky[5] % uptime
862 8:06pm up 16 day(s), 21:57, 40 users,
863 load average: 1.68, 1.59, 1.64
865 If the 5-minute or 15-minute load averages are not available,
866 return a shortened list, containing only those averages which are
869 On some systems, this function may require special privileges to
870 run, or it may be unimplemented for the particular system type.
871 In that case, the function will signal an error.
873 - Function: emacs-pid
874 This function returns the process ID of the Emacs process.
876 - Function: setprv privilege-name &optional setp getprv
877 This function sets or resets a VMS privilege. (It does not exist
878 on Unix.) The first arg is the privilege name, as a string. The
879 second argument, SETP, is `t' or `nil', indicating whether the
880 privilege is to be turned on or off. Its default is `nil'. The
881 function returns `t' if successful, `nil' otherwise.
883 If the third argument, GETPRV, is non-`nil', `setprv' does not
884 change the privilege, but returns `t' or `nil' indicating whether
885 the privilege is currently enabled.
888 File: lispref.info, Node: User Identification, Next: Time of Day, Prev: System Environment, Up: System Interface
893 - Variable: user-mail-address
894 This holds the nominal email address of the user who is using
895 Emacs. When Emacs starts up, it computes a default value that is
896 usually right, but users often set this themselves when the
897 default value is not right.
899 - Function: user-login-name &optional uid
900 If you don't specify UID, this function returns the name under
901 which the user is logged in. If the environment variable `LOGNAME'
902 is set, that value is used. Otherwise, if the environment variable
903 `USER' is set, that value is used. Otherwise, the value is based
904 on the effective UID, not the real UID.
906 If you specify UID, the value is the user name that corresponds to
907 UID (which should be an integer).
912 - Function: user-real-login-name
913 This function returns the user name corresponding to Emacs's real
914 UID. This ignores the effective UID and ignores the environment
915 variables `LOGNAME' and `USER'.
917 - Variable: user-full-name
918 This variable holds the name of the user running this Emacs. It is
919 initialized at startup time from the value of `NAME' environment
920 variable. You can change the value of this variable to alter the
921 result of the `user-full-name' function.
923 - Function: user-full-name &optional user
924 This function returns the full name of USER. If USER is `nil', it
925 defaults to the user running this Emacs. In that case, the value
926 of `user-full-name' variable, if non-`nil', will be used.
928 If USER is specified explicitly, `user-full-name' variable is
933 (setq user-full-name "Hrvoje \"Niksa\" Niksic")
935 => "Hrvoje \"Niksa\" Niksic"
936 (user-full-name "hniksic")
939 The symbols `user-login-name', `user-real-login-name' and
940 `user-full-name' are variables as well as functions. The functions
941 return the same values that the variables hold. These variables allow
942 you to "fake out" Emacs by telling the functions what to return. The
943 variables are also useful for constructing frame titles (*note Frame
946 - Function: user-real-uid
947 This function returns the real UID of the user.
953 This function returns the effective UID of the user.
955 - Function: user-home-directory
956 This function returns the "`HOME'" directory of the user, and is
957 intended to replace occurrences of "`(getenv "HOME")'". Under
958 Unix systems, the following is done:
960 1. Return the value of "`(getenv "HOME")'", if set.
962 2. Return "/", as a fallback, but issue a warning. (Future
963 versions of XEmacs will also attempt to lookup the `HOME'
964 directory via `getpwent()', but this has not yet been
967 Under MS Windows, this is done:
969 1. Return the value of "`(getenv "HOME")'", if set.
971 2. If the environment variables `HOMEDRIVE' and `HOMEDIR' are
972 both set, return the concatenation (the following description
973 uses MS Windows environment variable substitution syntax):
974 `%HOMEDRIVE%%HOMEDIR%'.
976 3. Return "C:\", as a fallback, but issue a warning.
979 File: lispref.info, Node: Time of Day, Next: Time Conversion, Prev: User Identification, Up: System Interface
984 This section explains how to determine the current time and the time
987 - Function: current-time-string &optional time-value
988 This function returns the current time and date as a
989 humanly-readable string. The format of the string is unvarying;
990 the number of characters used for each part is always the same, so
991 you can reliably use `substring' to extract pieces of it. It is
992 wise to count the characters from the beginning of the string
993 rather than from the end, as additional information may be added
996 The argument TIME-VALUE, if given, specifies a time to format
997 instead of the current time. The argument should be a list whose
998 first two elements are integers. Thus, you can use times obtained
999 from `current-time' (see below) and from `file-attributes' (*note
1002 (current-time-string)
1003 => "Wed Oct 14 22:21:05 1987"
1005 - Function: current-time
1006 This function returns the system's time value as a list of three
1007 integers: `(HIGH LOW MICROSEC)'. The integers HIGH and LOW
1008 combine to give the number of seconds since 0:00 January 1, 1970,
1009 which is HIGH * 2**16 + LOW.
1011 The third element, MICROSEC, gives the microseconds since the
1012 start of the current second (or 0 for systems that return time
1013 only on the resolution of a second).
1015 The first two elements can be compared with file time values such
1016 as you get with the function `file-attributes'. *Note File
1019 - Function: current-time-zone &optional time-value
1020 This function returns a list describing the time zone that the
1023 The value has the form `(OFFSET NAME)'. Here OFFSET is an integer
1024 giving the number of seconds ahead of UTC (east of Greenwich). A
1025 negative value means west of Greenwich. The second element, NAME
1026 is a string giving the name of the time zone. Both elements
1027 change when daylight savings time begins or ends; if the user has
1028 specified a time zone that does not use a seasonal time
1029 adjustment, then the value is constant through time.
1031 If the operating system doesn't supply all the information
1032 necessary to compute the value, both elements of the list are
1035 The argument TIME-VALUE, if given, specifies a time to analyze
1036 instead of the current time. The argument should be a cons cell
1037 containing two integers, or a list whose first two elements are
1038 integers. Thus, you can use times obtained from `current-time'
1039 (see above) and from `file-attributes' (*note File Attributes::).
1042 File: lispref.info, Node: Time Conversion, Next: Timers, Prev: Time of Day, Up: System Interface
1047 These functions convert time values (lists of two or three integers)
1048 to strings or to calendrical information. There is also a function to
1049 convert calendrical information to a time value. You can get time
1050 values from the functions `current-time' (*note Time of Day::) and
1051 `file-attributes' (*note File Attributes::).
1053 - Function: format-time-string format-string &optional time
1054 This function converts TIME to a string according to
1055 FORMAT-STRING. If TIME is omitted, it defaults to the current
1056 time. The argument FORMAT-STRING may contain `%'-sequences which
1057 say to substitute parts of the time. Here is a table of what the
1061 This stands for the abbreviated name of the day of week.
1064 This stands for the full name of the day of week.
1067 This stands for the abbreviated name of the month.
1070 This stands for the full name of the month.
1073 This is a synonym for `%x %X'.
1076 This has a locale-specific meaning. In the default locale
1077 (named C), it is equivalent to `%A, %B %e, %Y'.
1080 This stands for the day of month, zero-padded.
1083 This is a synonym for `%m/%d/%y'.
1086 This stands for the day of month, blank-padded.
1089 This is a synonym for `%b'.
1092 This stands for the hour (00-23).
1095 This stands for the hour (00-12).
1098 This stands for the day of the year (001-366).
1101 This stands for the hour (0-23), blank padded.
1104 This stands for the hour (1-12), blank padded.
1107 This stands for the month (01-12).
1110 This stands for the minute (00-59).
1113 This stands for a newline.
1116 This stands for `AM' or `PM', as appropriate.
1119 This is a synonym for `%I:%M:%S %p'.
1122 This is a synonym for `%H:%M'.
1125 This stands for the seconds (00-60).
1128 This stands for a tab character.
1131 This is a synonym for `%H:%M:%S'.
1134 This stands for the week of the year (01-52), assuming that
1135 weeks start on Sunday.
1138 This stands for the numeric day of week (0-6). Sunday is day
1142 This stands for the week of the year (01-52), assuming that
1143 weeks start on Monday.
1146 This has a locale-specific meaning. In the default locale
1147 (named C), it is equivalent to `%D'.
1150 This has a locale-specific meaning. In the default locale
1151 (named C), it is equivalent to `%T'.
1154 This stands for the year without century (00-99).
1157 This stands for the year with century.
1160 This stands for the time zone abbreviation.
1162 - Function: decode-time time
1163 This function converts a time value into calendrical information.
1164 The return value is a list of nine elements, as follows:
1166 (SECONDS MINUTES HOUR DAY MONTH YEAR DOW DST ZONE)
1168 Here is what the elements mean:
1171 The number of seconds past the minute, as an integer between
1175 The number of minutes past the hour, as an integer between 0
1179 The hour of the day, as an integer between 0 and 23.
1182 The day of the month, as an integer between 1 and 31.
1185 The month of the year, as an integer between 1 and 12.
1188 The year, an integer typically greater than 1900.
1191 The day of week, as an integer between 0 and 6, where 0
1195 `t' if daylight savings time is effect, otherwise `nil'.
1198 An integer indicating the time zone, as the number of seconds
1201 Note that Common Lisp has different meanings for DOW and ZONE.
1203 - Function: encode-time seconds minutes hour day month year &optional
1205 This function is the inverse of `decode-time'. It converts seven
1206 items of calendrical data into a time value. For the meanings of
1207 the arguments, see the table above under `decode-time'.
1209 Year numbers less than 100 are treated just like other year
1210 numbers. If you want them to stand for years above 1900, you must
1211 alter them yourself before you call `encode-time'.
1213 The optional argument ZONE defaults to the current time zone and
1214 its daylight savings time rules. If specified, it can be either a
1215 list (as you would get from `current-time-zone') or an integer (as
1216 you would get from `decode-time'). The specified zone is used
1217 without any further alteration for daylight savings time.
1220 File: lispref.info, Node: Timers, Next: Terminal Input, Prev: Time Conversion, Up: System Interface
1222 Timers for Delayed Execution
1223 ============================
1225 You can set up a timer to call a function at a specified future time.
1227 - Function: add-timeout secs function object &optional resignal
1228 This function adds a timeout, to be signaled after the timeout
1229 period has elapsed. SECS is a number of seconds, expressed as an
1230 integer or a float. FUNCTION will be called after that many
1231 seconds have elapsed, with one argument, the given OBJECT. If the
1232 optional RESIGNAL argument is provided, then after this timeout
1233 expires, `add-timeout' will automatically be called again with
1234 RESIGNAL as the first argument.
1236 This function returns an object which is the "id" of this
1237 particular timeout. You can pass that object to `disable-timeout'
1238 to turn off the timeout before it has been signalled.
1240 The number of seconds may be expressed as a floating-point number,
1241 in which case some fractional part of a second will be used.
1242 Caveat: the usable timeout granularity will vary from system to
1245 Adding a timeout causes a timeout event to be returned by
1246 `next-event', and the function will be invoked by
1247 `dispatch-event', so if XEmacs is in a tight loop, the function
1248 will not be invoked until the next call to sit-for or until the
1249 return to top-level (the same is true of process filters).
1251 WARNING: if you are thinking of calling add-timeout from inside of
1252 a callback function as a way of resignalling a timeout, think
1253 again. There is a race condition. That's why the RESIGNAL
1256 (NOTE: In FSF Emacs, this function is called `run-at-time' and has
1257 different semantics.)
1259 - Function: disable-timeout id
1260 Cancel the requested action for ID, which should be a value
1261 previously returned by `add-timeout'. This cancels the effect of
1262 that call to `add-timeout'; the arrival of the specified time will
1263 not cause anything special to happen. (NOTE: In FSF Emacs, this
1264 function is called `cancel-timer'.)
1267 File: lispref.info, Node: Terminal Input, Next: Terminal Output, Prev: Timers, Up: System Interface
1272 This section describes functions and variables for recording or
1273 manipulating terminal input. See *Note Display::, for related
1278 * Input Modes:: Options for how input is processed.
1279 * Translating Input:: Low level conversion of some characters or events
1281 * Recording Input:: Saving histories of recent or all input events.
projects / chise / xemacs-chise.git- / blob