2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
4 @c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
5 @c Free Software Foundation, Inc.
6 @c See the file elisp.texi for copying conditions.
7 @setfilename ../../info/os
8 @node System Interface, Packaging, Display, Top
9 @chapter Operating System Interface
11 This chapter is about starting and getting out of Emacs, access to
12 values in the operating system environment, and terminal input, output,
15 @xref{Building Emacs}, for related information. @xref{Display}, for
16 additional operating system status information pertaining to the
17 terminal and the screen.
20 * Starting Up:: Customizing Emacs startup processing.
21 * Getting Out:: How exiting works (permanent or temporary).
22 * System Environment:: Distinguish the name and kind of system.
23 * User Identification:: Finding the name and user id of the user.
24 * Time of Day:: Getting the current time.
25 * Time Conversion:: Converting a time from numeric form to
26 calendrical data and vice versa.
27 * Time Parsing:: Converting a time from numeric form to text
29 * Processor Run Time:: Getting the run time used by Emacs.
30 * Time Calculations:: Adding, subtracting, comparing times, etc.
31 * Timers:: Setting a timer to call a function at a certain time.
32 * Idle Timers:: Setting a timer to call a function when Emacs has
33 been idle for a certain length of time.
34 * Terminal Input:: Accessing and recording terminal input.
35 * Terminal Output:: Controlling and recording terminal output.
36 * Sound Output:: Playing sounds on the computer's speaker.
37 * X11 Keysyms:: Operating on key symbols for X Windows.
38 * Batch Mode:: Running Emacs without terminal interaction.
39 * Session Management:: Saving and restoring state with X Session Management.
40 * Dynamic Libraries:: On-demand loading of support libraries.
44 @section Starting Up Emacs
46 This section describes what Emacs does when it is started, and how you
47 can customize these actions.
50 * Startup Summary:: Sequence of actions Emacs performs at startup.
51 * Init File:: Details on reading the init file.
52 * Terminal-Specific:: How the terminal-specific Lisp file is read.
53 * Command-Line Arguments:: How command-line arguments are processed,
54 and how you can customize them.
58 @subsection Summary: Sequence of Actions at Startup
59 @cindex initialization of Emacs
60 @cindex startup of Emacs
61 @cindex @file{startup.el}
63 When Emacs is started up, it performs the following operations
64 (which are defined in @file{startup.el}):
68 It adds subdirectories to @code{load-path}, by running the file named
69 @file{subdirs.el} in each directory in the list. Normally, this file
70 adds the directory's subdirectories to the list, and those are scanned
71 in their turn. The files @file{subdirs.el} are normally generated
72 automatically when Emacs is installed.
74 @vindex before-init-time
76 It sets the variable @code{before-init-time} to the value of
77 @code{current-time} (@pxref{Time of Day}). It also sets
78 @code{after-init-time} to @code{nil}, which signals to Lisp programs
79 that Emacs is being initialized.
81 @vindex initial-window-system@r{, and startup}
82 @vindex window-system-initialization-alist
84 It loads the initialization library for the window system specified by
85 the variable @code{initial-window-system} (@pxref{Window Systems,
86 initial-window-system}). This library's name is
87 @file{term/@var{windowsystem}-win.el}, where @var{windowsystem} is the
88 value of @code{initial-window-system}. From that library, it calls
89 the appropriate initialization function. The initialization function
90 for each supported window system is specified by
91 @code{window-system-initialization-alist}.
94 It sets the language environment and the terminal coding system,
95 if requested by environment variables such as @code{LANG}.
98 It processes the initial options. (Some of them are handled
99 even earlier than this.)
102 It runs the normal hook @code{before-init-hook}.
105 It initializes the window frame and faces, if appropriate, and turns
106 on the menu bar and tool bar, if the initial frame needs them.
109 It loads the library @file{site-start}, if it exists. This is not
110 done if the options @samp{-Q} or @samp{--no-site-file} were specified.
111 @cindex @file{site-start.el}
114 It loads your init file (@pxref{Init File}). This is not done if the
115 options @samp{-q}, @samp{-Q}, or @samp{--batch} were specified. If
116 the @samp{-u} option was specified, Emacs looks for the init file in
117 that user's home directory instead.
120 It loads the library @file{default}, if it exists. This is not done
121 if @code{inhibit-default-init} is non-@code{nil}, nor if the options
122 @samp{-q}, @samp{-Q}, or @samp{--batch} were specified.
123 @cindex @file{default.el}
126 It loads your abbrevs from the file specified by
127 @code{abbrev-file-name}, if that file exists and can be read
128 (@pxref{Abbrev Files, abbrev-file-name}). This is not done if the
129 option @samp{--batch} was specified.
131 @vindex after-init-time
133 It sets the variable @code{after-init-time} to the value of
134 @code{current-time}. This variable was set to @code{nil} earlier;
135 setting it to the current time signals that the initialization phase
136 is over, and, together with @code{before-init-time}, provides the
137 measurement of how long it took.
140 It runs the normal hook @code{after-init-hook}.
143 If the buffer @samp{*scratch*} exists and is still in Fundamental mode
144 (as it should be by default), it sets its major mode according to
145 @code{initial-major-mode}.
148 If started on a text-only terminal, it loads the terminal-specific
149 Lisp library, which is specified by the variable
150 @code{term-file-prefix} (@pxref{Terminal-Specific}). This is not done
151 in @code{--batch} mode, nor if @code{term-file-prefix} is @code{nil}.
154 It displays the initial echo area message, unless you have suppressed
155 that with @code{inhibit-startup-echo-area-message}.
158 It processes the action arguments from the command line.
161 It now exits if the option @code{--batch} was specified.
164 If @code{initial-buffer-choice} is a string, it visits the file with
165 that name. Furthermore, if the @samp{*scratch*} buffer exists and is
166 empty, it inserts @code{initial-scratch-message} into that buffer.
169 It runs @code{emacs-startup-hook} and then @code{term-setup-hook}.
172 It calls @code{frame-notice-user-settings}, which modifies the
173 parameters of the selected frame according to whatever the init files
177 It runs @code{window-setup-hook}. @xref{Window Systems}.
180 If the option @code{--daemon} was specified, it calls
181 @code{server-start} and detaches from the controlling terminal.
182 @xref{Emacs Server,,, emacs, The GNU Emacs Manual}.
185 It displays the @dfn{startup screen}, which is a special buffer that
186 contains information about copyleft and basic Emacs usage. This is
187 not done if @code{initial-buffer-choice} or
188 @code{inhibit-startup-screen} are @code{nil}, nor if the
189 @samp{--no-splash} or @samp{-Q} command-line options were specified.
192 If started by the X session manager, it calls
193 @code{emacs-session-restore} passing it as argument the ID of the
194 previous session. @xref{Session Management}.
197 @defopt inhibit-startup-screen
198 This variable, if non-@code{nil}, inhibits the startup screen. In
199 that case, Emacs typically displays the @samp{*scratch*} buffer; but
200 see @code{initial-buffer-choice}, below.
202 Do not set this variable in the init file of a new user, or in a way
203 that affects more than one user, as that would prevent new users from
204 receiving information about copyleft and basic Emacs usage.
206 @vindex inhibit-startup-message
207 @vindex inhibit-splash-screen
208 @code{inhibit-startup-message} and @code{inhibit-splash-screen} are
209 aliases for this variable.
212 @defopt initial-buffer-choice
213 This variable, if non-@code{nil}, determines a file or buffer for
214 Emacs to display after starting up, instead of the startup screen. If
215 its value is @code{t}, Emacs displays the @samp{*scratch*} buffer. If
216 its value is a string, that specifies the name of a file for Emacs to
220 @defopt inhibit-startup-echo-area-message
221 This variable controls the display of the startup echo area message.
222 You can suppress the startup echo area message by adding text with this
223 form to your init file:
226 (setq inhibit-startup-echo-area-message
227 "@var{your-login-name}")
230 Emacs explicitly checks for an expression as shown above in your init
231 file; your login name must appear in the expression as a Lisp string
232 constant. Other methods of setting
233 @code{inhibit-startup-echo-area-message} to the same value do not
234 inhibit the startup message. This way, you can easily inhibit the
235 message for yourself if you wish, but thoughtless copying of your init
236 file will not inhibit the message for someone else.
239 @defopt initial-scratch-message
240 This variable, if non-@code{nil}, should be a string, which is
241 inserted into the @samp{*scratch*} buffer when Emacs starts up. If it
242 is @code{nil}, the @samp{*scratch*} buffer is empty.
246 @subsection The Init File, @file{.emacs}
248 @cindex @file{.emacs}
250 When you start Emacs, it normally attempts to load your @dfn{init
251 file}. This is either a file named @file{.emacs} or @file{.emacs.el}
252 in your home directory, or a file named @file{init.el} in a
253 subdirectory named @file{.emacs.d} in your home directory. Whichever
254 place you use, you can also compile the file (@pxref{Byte
255 Compilation}); then the actual file loaded will be @file{.emacs.elc}
258 The command-line switches @samp{-q}, @samp{-Q}, and @samp{-u}
259 control whether and where to find the init file; @samp{-q} (and the
260 stronger @samp{-Q}) says not to load an init file, while @samp{-u
261 @var{user}} says to load @var{user}'s init file instead of yours.
262 @xref{Entering Emacs,,, emacs, The GNU Emacs Manual}. If neither
263 option is specified, Emacs uses the @code{LOGNAME} environment
264 variable, or the @code{USER} (most systems) or @code{USERNAME} (MS
265 systems) variable, to find your home directory and thus your init
266 file; this way, even if you have su'd, Emacs still loads your own init
267 file. If those environment variables are absent, though, Emacs uses
268 your user-id to find your home directory.
270 @cindex default init file
271 A site may have a @dfn{default init file}, which is the library
272 named @file{default.el}. Emacs finds the @file{default.el} file
273 through the standard search path for libraries (@pxref{How Programs Do
274 Loading}). The Emacs distribution does not come with this file; sites
275 may provide one for local customizations. If the default init file
276 exists, it is loaded whenever you start Emacs, except in batch mode or
277 if @samp{-q} (or @samp{-Q}) is specified. But your own personal init
278 file, if any, is loaded first; if it sets @code{inhibit-default-init}
279 to a non-@code{nil} value, then Emacs does not subsequently load the
280 @file{default.el} file.
282 Another file for site-customization is @file{site-start.el}. Emacs
283 loads this @emph{before} the user's init file. You can inhibit the
284 loading of this file with the option @samp{--no-site-file}.
286 @defopt site-run-file
287 This variable specifies the site-customization file to load before the
288 user's init file. Its normal value is @code{"site-start"}. The only
289 way you can change it with real effect is to do so before dumping
293 @xref{Init Examples,, Init File Examples, emacs, The GNU Emacs Manual}, for
294 examples of how to make various commonly desired customizations in your
297 @defopt inhibit-default-init
298 This variable prevents Emacs from loading the default initialization
299 library file for your session of Emacs. If its value is non-@code{nil},
300 then the default library is not loaded. The default value is
304 @defvar before-init-hook
305 This normal hook is run, once, just before loading all the init files
306 (the user's init file, @file{default.el}, and/or @file{site-start.el}).
307 (The only way to change it with real effect is before dumping Emacs.)
310 @defvar after-init-hook
311 This normal hook is run, once, just after loading all the init files
312 (the user's init file, @file{default.el}, and/or @file{site-start.el}),
313 before loading the terminal-specific library and processing the
314 command-line action arguments.
317 @defvar emacs-startup-hook
318 This normal hook is run, once, just after handling the command line
319 arguments, just before @code{term-setup-hook}.
322 @defvar user-init-file
323 This variable holds the absolute file name of the user's init file. If the
324 actual init file loaded is a compiled file, such as @file{.emacs.elc},
325 the value refers to the corresponding source file.
328 @defvar user-emacs-directory
329 This variable holds the name of the @file{.emacs.d} directory. It is
330 ordinarily @file{~/.emacs.d}, but differs on some platforms.
333 @node Terminal-Specific
334 @subsection Terminal-Specific Initialization
335 @cindex terminal-specific initialization
337 Each terminal type can have its own Lisp library that Emacs loads when
338 run on that type of terminal. The library's name is constructed by
339 concatenating the value of the variable @code{term-file-prefix} and the
340 terminal type (specified by the environment variable @code{TERM}).
341 Normally, @code{term-file-prefix} has the value
342 @code{"term/"}; changing this is not recommended. Emacs finds the file
343 in the normal manner, by searching the @code{load-path} directories, and
344 trying the @samp{.elc} and @samp{.el} suffixes.
347 The usual function of a terminal-specific library is to enable
348 special keys to send sequences that Emacs can recognize. It may also
349 need to set or add to @code{input-decode-map} if the Termcap or
350 Terminfo entry does not specify all the terminal's function keys.
351 @xref{Terminal Input}.
353 When the name of the terminal type contains a hyphen, and no library
354 is found whose name is identical to the terminal's name, Emacs strips
355 from the terminal's name the last hyphen and everything that follows
356 it, and tries again. This process is repeated until Emacs finds a
357 matching library or until there are no more hyphens in the name (the
358 latter means the terminal doesn't have any library specific to it).
359 Thus, for example, if there are no @samp{aaa-48} and @samp{aaa-30}
360 libraries, Emacs will try the same library @file{term/aaa.el} for
361 terminal types @samp{aaa-48} and @samp{aaa-30-rv}. If necessary, the
362 library can evaluate @code{(getenv "TERM")} to find the full name of
363 the terminal type.@refill
365 Your init file can prevent the loading of the
366 terminal-specific library by setting the variable
367 @code{term-file-prefix} to @code{nil}. This feature is useful when
368 experimenting with your own peculiar customizations.
370 You can also arrange to override some of the actions of the
371 terminal-specific library by setting the variable
372 @code{term-setup-hook}. This is a normal hook which Emacs runs using
373 @code{run-hooks} at the end of Emacs initialization, after loading both
374 your init file and any terminal-specific libraries. You can
375 use this variable to define initializations for terminals that do not
376 have their own libraries. @xref{Hooks}.
378 @defvar term-file-prefix
379 @cindex @code{TERM} environment variable
380 If the @code{term-file-prefix} variable is non-@code{nil}, Emacs loads
381 a terminal-specific initialization file as follows:
384 (load (concat term-file-prefix (getenv "TERM")))
388 You may set the @code{term-file-prefix} variable to @code{nil} in your
389 init file if you do not wish to load the
390 terminal-initialization file. To do this, put the following in
391 your init file: @code{(setq term-file-prefix nil)}.
393 On MS-DOS, if the environment variable @code{TERM} is not set, Emacs
394 uses @samp{internal} as the terminal type.
397 @defvar term-setup-hook
398 This variable is a normal hook that Emacs runs after loading your
399 init file, the default initialization file (if any) and the
400 terminal-specific Lisp file.
402 You can use @code{term-setup-hook} to override the definitions made by a
403 terminal-specific file.
406 See @code{window-setup-hook} in @ref{Window Systems}, for a related
409 @node Command-Line Arguments
410 @subsection Command-Line Arguments
411 @cindex command-line arguments
413 You can use command-line arguments to request various actions when you
414 start Emacs. Since you do not need to start Emacs more than once per
415 day, and will often leave your Emacs session running longer than that,
416 command-line arguments are hardly ever used. As a practical matter, it
417 is best to avoid making the habit of using them, since this habit would
418 encourage you to kill and restart Emacs unnecessarily often. These
419 options exist for two reasons: to be compatible with other editors (for
420 invocation by other programs) and to enable shell scripts to run
421 specific Lisp programs.
423 This section describes how Emacs processes command-line arguments,
424 and how you can customize them.
427 (Note that some other editors require you to start afresh each time
428 you want to edit a file. With this kind of editor, you will probably
429 specify the file as a command-line argument. The recommended way to
430 use GNU Emacs is to start it only once, just after you log in, and do
431 all your editing in the same Emacs process. Each time you want to edit
432 a different file, you visit it with the existing Emacs, which eventually
433 comes to have many files in it ready for editing. Usually you do not
434 kill the Emacs until you are about to log out.)
438 This function parses the command line that Emacs was called with,
439 processes it, loads the user's init file and displays the
443 @defvar command-line-processed
444 The value of this variable is @code{t} once the command line has been
447 If you redump Emacs by calling @code{dump-emacs}, you may wish to set
448 this variable to @code{nil} first in order to cause the new dumped Emacs
449 to process its new command-line arguments.
452 @defvar command-switch-alist
453 @cindex switches on command line
454 @cindex options on command line
455 @cindex command-line options
456 The value of this variable is an alist of user-defined command-line
457 options and associated handler functions. This variable exists so you
458 can add elements to it.
460 A @dfn{command-line option} is an argument on the command line, which
467 The elements of the @code{command-switch-alist} look like this:
470 (@var{option} . @var{handler-function})
473 The @sc{car}, @var{option}, is a string, the name of a command-line
474 option (not including the initial hyphen). The @var{handler-function}
475 is called to handle @var{option}, and receives the option name as its
478 In some cases, the option is followed in the command line by an
479 argument. In these cases, the @var{handler-function} can find all the
480 remaining command-line arguments in the variable
481 @code{command-line-args-left}. (The entire list of command-line
482 arguments is in @code{command-line-args}.)
484 The command-line arguments are parsed by the @code{command-line-1}
485 function in the @file{startup.el} file. See also @ref{Emacs
486 Invocation, , Command Line Arguments for Emacs Invocation, emacs, The
490 @defvar command-line-args
491 The value of this variable is the list of command-line arguments passed
495 @defvar command-line-args-left
497 The value of this variable is the list of command-line arguments that
498 have not yet been processed. @code{argv} is an alias for this.
501 @defvar command-line-functions
502 This variable's value is a list of functions for handling an
503 unrecognized command-line argument. Each time the next argument to be
504 processed has no special meaning, the functions in this list are called,
505 in order of appearance, until one of them returns a non-@code{nil}
508 These functions are called with no arguments. They can access the
509 command-line argument under consideration through the variable
510 @code{argi}, which is bound temporarily at this point. The remaining
511 arguments (not including the current one) are in the variable
512 @code{command-line-args-left}.
514 When a function recognizes and processes the argument in @code{argi}, it
515 should return a non-@code{nil} value to say it has dealt with that
516 argument. If it has also dealt with some of the following arguments, it
517 can indicate that by deleting them from @code{command-line-args-left}.
519 If all of these functions return @code{nil}, then the argument is used
520 as a file name to visit.
524 @section Getting Out of Emacs
525 @cindex exiting Emacs
527 There are two ways to get out of Emacs: you can kill the Emacs job,
528 which exits permanently, or you can suspend it, which permits you to
529 reenter the Emacs process later. As a practical matter, you seldom kill
530 Emacs---only when you are about to log out. Suspending is much more
534 * Killing Emacs:: Exiting Emacs irreversibly.
535 * Suspending Emacs:: Exiting Emacs reversibly.
539 @comment node-name, next, previous, up
540 @subsection Killing Emacs
541 @cindex killing Emacs
543 Killing Emacs means ending the execution of the Emacs process. The
544 parent process normally resumes control. The low-level primitive for
545 killing Emacs is @code{kill-emacs}.
547 @deffn Command kill-emacs &optional exit-data
548 This command exits the Emacs process and kills it.
550 If @var{exit-data} is an integer, then it is used as the exit status
551 of the Emacs process. (This is useful primarily in batch operation; see
554 If @var{exit-data} is a string, its contents are stuffed into the
555 terminal input buffer so that the shell (or whatever program next reads
556 input) can read them.
559 All the information in the Emacs process, aside from files that have
560 been saved, is lost when the Emacs process is killed. Because killing
561 Emacs inadvertently can lose a lot of work, Emacs queries for
562 confirmation before actually terminating if you have buffers that need
563 saving or subprocesses that are running. This is done in the function
564 @code{save-buffers-kill-emacs}, the higher level function from which
565 @code{kill-emacs} is usually called.
567 @defvar kill-emacs-query-functions
568 After asking the standard questions, @code{save-buffers-kill-emacs}
569 calls the functions in the list @code{kill-emacs-query-functions}, in
570 order of appearance, with no arguments. These functions can ask for
571 additional confirmation from the user. If any of them returns
572 @code{nil}, @code{save-buffers-kill-emacs} does not kill Emacs, and
573 does not run the remaining functions in this hook. Calling
574 @code{kill-emacs} directly does not run this hook.
577 @defvar kill-emacs-hook
578 This variable is a normal hook; once @code{save-buffers-kill-emacs} is
579 finished with all file saving and confirmation, it calls
580 @code{kill-emacs} which runs the functions in this hook.
582 @code{kill-emacs} may be invoked directly (that is not via
583 @code{save-buffers-kill-emacs}) if the terminal is disconnected, or in
584 similar situations where interaction with the user is not possible.
585 Thus, if your hook needs to interact with the user, put it on
586 @code{kill-emacs-query-functions}; if it needs to run regardless of
587 how Emacs is killed, put it on @code{kill-emacs-hook}.
590 @node Suspending Emacs
591 @subsection Suspending Emacs
592 @cindex suspending Emacs
594 On text-only terminals, it is possible to @dfn{suspend Emacs}, which
595 means stopping Emacs temporarily and returning control to its superior
596 process, which is usually the shell. This allows you to resume
597 editing later in the same Emacs process, with the same buffers, the
598 same kill ring, the same undo history, and so on. To resume Emacs,
599 use the appropriate command in the parent shell---most likely
602 @cindex controlling terminal
603 Suspending works only on a terminal device from which the Emacs
604 session was started. We call that device the @dfn{controlling
605 terminal} of the session. Suspending is not allowed if the
606 controlling terminal is a graphical terminal.
608 Some operating systems do not support suspension of jobs; on these
609 systems, ``suspension'' actually creates a new shell temporarily as a
610 subprocess of Emacs. Then you would exit the shell to return to Emacs.
612 @deffn Command suspend-emacs &optional string
613 This function stops Emacs and returns control to the superior process.
614 If and when the superior process resumes Emacs, @code{suspend-emacs}
615 returns @code{nil} to its caller in Lisp.
617 This function works only on the controlling terminal of the Emacs
618 session; to relinquish control of other tty devices, use
619 @code{suspend-tty} (see below). If the Emacs session uses more than
620 one terminal, you must delete the frames on all the other terminals
621 before suspending Emacs, or this function signals an error.
622 @xref{Multiple Terminals}.
624 If @var{string} is non-@code{nil}, its characters are sent to Emacs's
625 superior shell, to be read as terminal input. The characters in
626 @var{string} are not echoed by the superior shell; only the results
629 Before suspending, @code{suspend-emacs} runs the normal hook
630 @code{suspend-hook}. After the user resumes Emacs,
631 @code{suspend-emacs} runs the normal hook @code{suspend-resume-hook}.
634 The next redisplay after resumption will redraw the entire screen,
635 unless the variable @code{no-redraw-on-reenter} is non-@code{nil}.
636 @xref{Refresh Screen}.
638 In the following example, note that @samp{pwd} is not echoed after
639 Emacs is suspended. But it is read and executed by the shell.
648 (add-hook 'suspend-hook
652 (error "Suspend canceled")))))
653 @result{} (lambda nil
654 (or (y-or-n-p "Really suspend? ")
655 (error "Suspend canceled")))
658 (add-hook 'suspend-resume-hook
659 (function (lambda () (message "Resumed!"))))
660 @result{} (lambda nil (message "Resumed!"))
663 (suspend-emacs "pwd")
667 ---------- Buffer: Minibuffer ----------
668 Really suspend? @kbd{y}
669 ---------- Buffer: Minibuffer ----------
673 ---------- Parent Shell ----------
674 lewis@@slug[23] % /user/lewis/manual
679 ---------- Echo Area ----------
686 This variable is a normal hook that Emacs runs before suspending.
689 @defvar suspend-resume-hook
690 This variable is a normal hook that Emacs runs on resuming
694 @defun suspend-tty &optional tty
695 If @var{tty} specifies a terminal device used by Emacs, this function
696 relinquishes the device and restores it to its prior state. Frames
697 that used the device continue to exist, but are not updated and Emacs
698 doesn't read input from them. @var{tty} can be a terminal object, a
699 frame (meaning the terminal for that frame), or @code{nil} (meaning
700 the terminal for the selected frame). @xref{Multiple Terminals}.
702 If @var{tty} is already suspended, this function does nothing.
704 @vindex suspend-tty-functions
705 This function runs the hook @code{suspend-tty-functions}, passing the
706 terminal object as an argument to each function.
709 @defun resume-tty &optional tty
710 This function resumes the previously suspended terminal device
711 @var{tty}; @var{tty} can be a terminal object, a frame (meaning the
712 terminal for that frame), or @code{nil} (meaning the terminal for the
715 @vindex resume-tty-functions
716 This function reopens the terminal device, re-initializes it, and
717 redraws its with that terminal's selected frame. It then runs the
718 hook @code{resume-tty-functions}, passing the terminal object as an
719 argument to each function.
721 If the same device is already used by another Emacs terminal, this
722 function signals an error.
725 @defun controlling-tty-p &optional terminal
726 This function returns non-@code{nil} if @var{terminal} is the
727 controlling terminal of the Emacs session; @code{terminal} can be a
728 terminal object, a frame (meaning the terminal for that frame), or
729 @code{nil} (meaning the terminal for the selected frame).
732 @deffn Command suspend-frame
733 This command @dfn{suspends} a frame. For GUI frames, it calls
734 @code{iconify-frame} (@pxref{Visibility of Frames}); for text-only
735 frames, it calls either @code{suspend-emacs} or @code{suspend-tty},
736 depending on whether the frame is displayed on the controlling
737 terminal device or not.
740 @node System Environment
741 @section Operating System Environment
742 @cindex operating system environment
744 Emacs provides access to variables in the operating system environment
745 through various functions. These variables include the name of the
746 system, the user's @acronym{UID}, and so on.
748 @defvar system-configuration
749 This variable holds the standard GNU configuration name for the
750 hardware/software configuration of your system, as a string. The
751 convenient way to test parts of this string is with
755 @cindex system type and name
757 The value of this variable is a symbol indicating the type of operating
758 system Emacs is operating on. Here is a table of the possible values:
765 Berkeley BSD and its variants.
768 Cygwin, a Posix layer on top of MS-Windows.
774 The GNU system (using the GNU kernel, which consists of the HURD and Mach).
777 A GNU/Linux system---that is, a variant GNU system, using the Linux
778 kernel. (These systems are the ones people often call ``Linux,'' but
779 actually Linux is just the kernel, not the whole system.)
782 A GNU (glibc-based) system with a FreeBSD kernel.
785 Hewlett-Packard HPUX operating system.
788 Silicon Graphics Irix system.
791 Microsoft MS-DOS ``operating system.'' Emacs compiled with DJGPP for
792 MS-DOS binds @code{system-type} to @code{ms-dos} even when you run it on
799 Microsoft Windows NT and later. The same executable supports Windows
800 9X, but the value of @code{system-type} is @code{windows-nt} in either
805 We do not wish to add new symbols to make finer distinctions unless it
806 is absolutely necessary! In fact, we hope to eliminate some of these
807 alternatives in the future. We recommend using
808 @code{system-configuration} to distinguish between different operating
813 This function returns the name of the machine you are running on.
816 @result{} "www.gnu.org"
820 The symbol @code{system-name} is a variable as well as a function. In
821 fact, the function returns whatever value the variable
822 @code{system-name} currently holds. Thus, you can set the variable
823 @code{system-name} in case Emacs is confused about the name of your
824 system. The variable is also useful for constructing frame titles
825 (@pxref{Frame Titles}).
827 @defopt mail-host-address
828 If this variable is non-@code{nil}, it is used instead of
829 @code{system-name} for purposes of generating email addresses. For
830 example, it is used when constructing the default value of
831 @code{user-mail-address}. @xref{User Identification}. (Since this is
832 done when Emacs starts up, the value actually used is the one saved when
833 Emacs was dumped. @xref{Building Emacs}.)
836 @deffn Command getenv var &optional frame
837 @cindex environment variable access
838 This function returns the value of the environment variable @var{var},
839 as a string. @var{var} should be a string. If @var{var} is undefined
840 in the environment, @code{getenv} returns @code{nil}. If returns
841 @samp{""} if @var{var} is set but null. Within Emacs, the environment
842 variable values are kept in the Lisp variable @code{process-environment}.
851 lewis@@slug[10] % printenv
852 PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
864 @deffn Command setenv variable &optional value
865 This command sets the value of the environment variable named
866 @var{variable} to @var{value}. @var{variable} should be a string.
867 Internally, Emacs Lisp can handle any string. However, normally
868 @var{variable} should be a valid shell identifier, that is, a sequence
869 of letters, digits and underscores, starting with a letter or
870 underscore. Otherwise, errors may occur if subprocesses of Emacs try
871 to access the value of @var{variable}. If @var{value} is omitted or
872 @code{nil}, @code{setenv} removes @var{variable} from the environment.
873 Otherwise, @var{value} should be a string.
875 @code{setenv} works by modifying @code{process-environment}; binding
876 that variable with @code{let} is also reasonable practice.
878 @code{setenv} returns the new value of @var{variable}, or @code{nil}
879 if it removed @var{variable} from the environment.
882 @defvar process-environment
883 This variable is a list of strings, each describing one environment
884 variable. The functions @code{getenv} and @code{setenv} work by means
890 @result{} ("l=/usr/stanford/lib/gnuemacs/lisp"
891 "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
901 If @code{process-environment} contains ``duplicate'' elements that
902 specify the same environment variable, the first of these elements
903 specifies the variable, and the other ``duplicates'' are ignored.
906 @defvar initial-environment
907 This variable holds the list of environment variables Emacs inherited
908 from its parent process. It is computed during startup, see
909 @ref{Startup Summary}.
912 @defvar path-separator
913 This variable holds a string which says which character separates
914 directories in a search path (as found in an environment variable). Its
915 value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS
919 @defun parse-colon-path path
920 This function takes a search path string such as would be the value of
921 the @code{PATH} environment variable, and splits it at the separators,
922 returning a list of directory names. @code{nil} in this list stands for
923 ``use the current directory.'' Although the function's name says
924 ``colon,'' it actually uses the value of @code{path-separator}.
927 (parse-colon-path ":/foo:/bar")
928 @result{} (nil "/foo/" "/bar/")
932 @defvar invocation-name
933 This variable holds the program name under which Emacs was invoked. The
934 value is a string, and does not include a directory name.
937 @defvar invocation-directory
938 This variable holds the directory from which the Emacs executable was
939 invoked, or perhaps @code{nil} if that directory cannot be determined.
942 @defvar installation-directory
943 If non-@code{nil}, this is a directory within which to look for the
944 @file{lib-src} and @file{etc} subdirectories. This is non-@code{nil}
945 when Emacs can't find those directories in their standard installed
946 locations, but can find them in a directory related somehow to the one
947 containing the Emacs executable.
950 @defun load-average &optional use-float
951 This function returns the current 1-minute, 5-minute, and 15-minute load
954 By default, the values are integers that are 100 times the system load
955 averages, which indicate the average number of processes trying to run.
956 If @var{use-float} is non-@code{nil}, then they are returned
957 as floating point numbers and without multiplying by 100.
959 If it is impossible to obtain the load average, this function signals
960 an error. On some platforms, access to load averages requires
961 installing Emacs as setuid or setgid so that it can read kernel
962 information, and that usually isn't advisable.
964 If the 1-minute load average is available, but the 5- or 15-minute
965 averages are not, this function returns a shortened list containing
966 the available averages.
971 @result{} (169 48 36)
975 @result{} (1.69 0.48 0.36)
979 lewis@@rocky[5] % uptime
980 11:55am up 1 day, 19:37, 3 users,
981 load average: 1.69, 0.48, 0.36
987 This function returns the process @acronym{ID} of the Emacs process,
991 @defvar tty-erase-char
992 This variable holds the erase character that was selected
993 in the system's terminal driver, before Emacs was started.
994 The value is @code{nil} if Emacs is running under a window system.
997 @node User Identification
998 @section User Identification
999 @cindex user identification
1001 @defvar init-file-user
1002 This variable says which user's init files should be used by
1003 Emacs---or @code{nil} if none. @code{""} stands for the user who
1004 originally logged in. The value reflects command-line options such as
1005 @samp{-q} or @samp{-u @var{user}}.
1007 Lisp packages that load files of customizations, or any other sort of
1008 user profile, should obey this variable in deciding where to find it.
1009 They should load the profile of the user name found in this variable.
1010 If @code{init-file-user} is @code{nil}, meaning that the @samp{-q}
1011 option was used, then Lisp packages should not load any customization
1012 files or user profile.
1015 @defopt user-mail-address
1016 This holds the nominal email address of the user who is using Emacs.
1017 Emacs normally sets this variable to a default value after reading your
1018 init files, but not if you have already set it. So you can set the
1019 variable to some other value in your init file if you do not
1020 want to use the default value.
1023 @defun user-login-name &optional uid
1024 If you don't specify @var{uid}, this function returns the name under
1025 which the user is logged in. If the environment variable @code{LOGNAME}
1026 is set, that value is used. Otherwise, if the environment variable
1027 @code{USER} is set, that value is used. Otherwise, the value is based
1028 on the effective @acronym{UID}, not the real @acronym{UID}.
1030 If you specify @var{uid}, the value is the user name that corresponds
1031 to @var{uid} (which should be an integer), or @code{nil} if there is
1042 @defun user-real-login-name
1043 This function returns the user name corresponding to Emacs's real
1044 @acronym{UID}. This ignores the effective @acronym{UID} and ignores the
1045 environment variables @code{LOGNAME} and @code{USER}.
1048 @defun user-full-name &optional uid
1049 This function returns the full name of the logged-in user---or the value
1050 of the environment variable @code{NAME}, if that is set.
1052 @c "Bil" is the correct spelling.
1056 @result{} "Bil Lewis"
1060 If the Emacs job's user-id does not correspond to any known user (and
1061 provided @code{NAME} is not set), the value is @code{"unknown"}.
1063 If @var{uid} is non-@code{nil}, then it should be a number (a user-id)
1064 or a string (a login name). Then @code{user-full-name} returns the full
1065 name corresponding to that user-id or login name. If you specify a
1066 user-id or login name that isn't defined, it returns @code{nil}.
1069 @vindex user-full-name
1070 @vindex user-real-login-name
1071 @vindex user-login-name
1072 The symbols @code{user-login-name}, @code{user-real-login-name} and
1073 @code{user-full-name} are variables as well as functions. The functions
1074 return the same values that the variables hold. These variables allow
1075 you to ``fake out'' Emacs by telling the functions what to return. The
1076 variables are also useful for constructing frame titles (@pxref{Frame
1079 @defun user-real-uid
1080 This function returns the real @acronym{UID} of the user.
1081 The value may be a floating point number.
1092 This function returns the effective @acronym{UID} of the user.
1093 The value may be a floating point number.
1097 @section Time of Day
1099 This section explains how to determine the current time and the time
1102 @defun current-time-string &optional time-value
1103 This function returns the current time and date as a human-readable
1104 string. The format of the string is unvarying; the number of characters
1105 used for each part is always the same, so you can reliably use
1106 @code{substring} to extract pieces of it. It is wise to count the
1107 characters from the beginning of the string rather than from the end, as
1108 additional information may some day be added at the end.
1110 The argument @var{time-value}, if given, specifies a time to format
1111 instead of the current time. This argument should have the same form
1112 as the times obtained from @code{current-time} (see below) and from
1113 @code{file-attributes} (@pxref{Definition of file-attributes}). It
1114 should be a list whose first two elements are integers; a third
1115 (microsecond) element, if present, is ignored. @var{time-value} can
1116 also be a cons of two integers, but this usage is obsolete.
1120 (current-time-string)
1121 @result{} "Wed Oct 14 22:21:05 1987"
1127 This function returns the system's time value as a list of three
1128 integers: @code{(@var{high} @var{low} @var{microsec})}. The integers
1129 @var{high} and @var{low} combine to give the number of seconds since
1130 0:00 January 1, 1970 UTC (Coordinated Universal Time), which is
1132 @var{high} * 2**16 + @var{low}.
1138 The third element, @var{microsec}, gives the microseconds since the
1139 start of the current second (or 0 for systems that return time with
1140 the resolution of only one second).
1142 The first two elements can be compared with file time values such as you
1143 get with the function @code{file-attributes}.
1144 @xref{Definition of file-attributes}.
1147 @defun current-time-zone &optional time-value
1148 This function returns a list describing the time zone that the user is
1151 The value has the form @code{(@var{offset} @var{name})}. Here
1152 @var{offset} is an integer giving the number of seconds ahead of UTC
1153 (east of Greenwich). A negative value means west of Greenwich. The
1154 second element, @var{name}, is a string giving the name of the time
1155 zone. Both elements change when daylight saving time begins or ends;
1156 if the user has specified a time zone that does not use a seasonal time
1157 adjustment, then the value is constant through time.
1159 If the operating system doesn't supply all the information necessary to
1160 compute the value, the unknown elements of the list are @code{nil}.
1162 The argument @var{time-value}, if given, specifies a time to analyze
1163 instead of the current time. The argument should have the same form
1164 as for @code{current-time-string} (see above). Thus, you can use
1165 times obtained from @code{current-time} (see above) and from
1166 @code{file-attributes}. @xref{Definition of file-attributes}.
1169 @defun set-time-zone-rule tz
1170 This function specifies the local time zone according to @var{tz}. If
1171 @var{tz} is @code{nil}, that means to use an implementation-defined
1172 default time zone. If @var{tz} is @code{t}, that means to use
1173 Universal Time. Otherwise, @var{tz} should be a string specifying a
1177 @defun float-time &optional time-value
1178 This function returns the current time as a floating-point number of
1179 seconds since the epoch. The argument @var{time-value}, if given,
1180 specifies a time to convert instead of the current time. The argument
1181 should have the same form as for @code{current-time-string} (see
1182 above). Thus, it accepts the output of @code{current-time} and
1183 @code{file-attributes} (@pxref{Definition of file-attributes}).
1185 @emph{Warning}: Since the result is floating point, it may not be
1186 exact. Do not use this function if precise time stamps are required.
1189 @node Time Conversion
1190 @section Time Conversion
1192 These functions convert time values (lists of two or three integers)
1193 to calendrical information and vice versa. You can get time values
1194 from the functions @code{current-time} (@pxref{Time of Day}) and
1195 @code{file-attributes} (@pxref{Definition of file-attributes}).
1197 Many operating systems are limited to time values that contain 32 bits
1198 of information; these systems typically handle only the times from
1199 1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC. However, some
1200 operating systems have larger time values, and can represent times far
1201 in the past or future.
1203 Time conversion functions always use the Gregorian calendar, even
1204 for dates before the Gregorian calendar was introduced. Year numbers
1205 count the number of years since the year 1 B.C., and do not skip zero
1206 as traditional Gregorian years do; for example, the year number
1207 @minus{}37 represents the Gregorian year 38 B.C@.
1209 @defun decode-time &optional time
1210 This function converts a time value into calendrical information. If
1211 you don't specify @var{time}, it decodes the current time. The return
1212 value is a list of nine elements, as follows:
1215 (@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone})
1218 Here is what the elements mean:
1222 The number of seconds past the minute, as an integer between 0 and 59.
1223 On some operating systems, this is 60 for leap seconds.
1225 The number of minutes past the hour, as an integer between 0 and 59.
1227 The hour of the day, as an integer between 0 and 23.
1229 The day of the month, as an integer between 1 and 31.
1231 The month of the year, as an integer between 1 and 12.
1233 The year, an integer typically greater than 1900.
1235 The day of week, as an integer between 0 and 6, where 0 stands for
1238 @code{t} if daylight saving time is effect, otherwise @code{nil}.
1240 An integer indicating the time zone, as the number of seconds east of
1244 @strong{Common Lisp Note:} Common Lisp has different meanings for
1245 @var{dow} and @var{zone}.
1248 @defun encode-time seconds minutes hour day month year &optional zone
1249 This function is the inverse of @code{decode-time}. It converts seven
1250 items of calendrical data into a time value. For the meanings of the
1251 arguments, see the table above under @code{decode-time}.
1253 Year numbers less than 100 are not treated specially. If you want them
1254 to stand for years above 1900, or years above 2000, you must alter them
1255 yourself before you call @code{encode-time}.
1257 The optional argument @var{zone} defaults to the current time zone and
1258 its daylight saving time rules. If specified, it can be either a list
1259 (as you would get from @code{current-time-zone}), a string as in the
1260 @code{TZ} environment variable, @code{t} for Universal Time, or an
1261 integer (as you would get from @code{decode-time}). The specified
1262 zone is used without any further alteration for daylight saving time.
1264 If you pass more than seven arguments to @code{encode-time}, the first
1265 six are used as @var{seconds} through @var{year}, the last argument is
1266 used as @var{zone}, and the arguments in between are ignored. This
1267 feature makes it possible to use the elements of a list returned by
1268 @code{decode-time} as the arguments to @code{encode-time}, like this:
1271 (apply 'encode-time (decode-time @dots{}))
1274 You can perform simple date arithmetic by using out-of-range values for
1275 the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month}
1276 arguments; for example, day 0 means the day preceding the given month.
1278 The operating system puts limits on the range of possible time values;
1279 if you try to encode a time that is out of range, an error results.
1280 For instance, years before 1970 do not work on some systems;
1281 on others, years as early as 1901 do work.
1285 @section Parsing and Formatting Times
1287 These functions convert time values (lists of two or three integers)
1288 to text in a string, and vice versa.
1290 @defun date-to-time string
1291 This function parses the time-string @var{string} and returns the
1292 corresponding time value.
1295 @defun format-time-string format-string &optional time universal
1296 This function converts @var{time} (or the current time, if @var{time} is
1297 omitted) to a string according to @var{format-string}. The argument
1298 @var{format-string} may contain @samp{%}-sequences which say to
1299 substitute parts of the time. Here is a table of what the
1300 @samp{%}-sequences mean:
1304 This stands for the abbreviated name of the day of week.
1306 This stands for the full name of the day of week.
1308 This stands for the abbreviated name of the month.
1310 This stands for the full name of the month.
1312 This is a synonym for @samp{%x %X}.
1314 This has a locale-specific meaning. In the default locale (named C), it
1315 is equivalent to @samp{%A, %B %e, %Y}.
1317 This stands for the day of month, zero-padded.
1319 This is a synonym for @samp{%m/%d/%y}.
1321 This stands for the day of month, blank-padded.
1323 This is a synonym for @samp{%b}.
1325 This stands for the hour (00-23).
1327 This stands for the hour (01-12).
1329 This stands for the day of the year (001-366).
1331 This stands for the hour (0-23), blank padded.
1333 This stands for the hour (1-12), blank padded.
1335 This stands for the month (01-12).
1337 This stands for the minute (00-59).
1339 This stands for a newline.
1341 This stands for @samp{AM} or @samp{PM}, as appropriate.
1343 This is a synonym for @samp{%I:%M:%S %p}.
1345 This is a synonym for @samp{%H:%M}.
1347 This stands for the seconds (00-59).
1349 This stands for a tab character.
1351 This is a synonym for @samp{%H:%M:%S}.
1353 This stands for the week of the year (01-52), assuming that weeks
1356 This stands for the numeric day of week (0-6). Sunday is day 0.
1358 This stands for the week of the year (01-52), assuming that weeks
1361 This has a locale-specific meaning. In the default locale (named
1362 @samp{C}), it is equivalent to @samp{%D}.
1364 This has a locale-specific meaning. In the default locale (named
1365 @samp{C}), it is equivalent to @samp{%T}.
1367 This stands for the year without century (00-99).
1369 This stands for the year with century.
1371 This stands for the time zone abbreviation (e.g., @samp{EST}).
1373 This stands for the time zone numerical offset (e.g., @samp{-0500}).
1376 You can also specify the field width and type of padding for any of
1377 these @samp{%}-sequences. This works as in @code{printf}: you write
1378 the field width as digits in the middle of a @samp{%}-sequences. If you
1379 start the field width with @samp{0}, it means to pad with zeros. If you
1380 start the field width with @samp{_}, it means to pad with spaces.
1382 For example, @samp{%S} specifies the number of seconds since the minute;
1383 @samp{%03S} means to pad this with zeros to 3 positions, @samp{%_3S} to
1384 pad with spaces to 3 positions. Plain @samp{%3S} pads with zeros,
1385 because that is how @samp{%S} normally pads to two positions.
1387 The characters @samp{E} and @samp{O} act as modifiers when used between
1388 @samp{%} and one of the letters in the table above. @samp{E} specifies
1389 using the current locale's ``alternative'' version of the date and time.
1390 In a Japanese locale, for example, @code{%Ex} might yield a date format
1391 based on the Japanese Emperors' reigns. @samp{E} is allowed in
1392 @samp{%Ec}, @samp{%EC}, @samp{%Ex}, @samp{%EX}, @samp{%Ey}, and
1395 @samp{O} means to use the current locale's ``alternative''
1396 representation of numbers, instead of the ordinary decimal digits. This
1397 is allowed with most letters, all the ones that output numbers.
1399 If @var{universal} is non-@code{nil}, that means to describe the time as
1400 Universal Time; @code{nil} means describe it using what Emacs believes
1401 is the local time zone (see @code{current-time-zone}).
1403 This function uses the C library function @code{strftime}
1404 (@pxref{Formatting Calendar Time,,, libc, The GNU C Library Reference
1405 Manual}) to do most of the work. In order to communicate with that
1406 function, it first encodes its argument using the coding system
1407 specified by @code{locale-coding-system} (@pxref{Locales}); after
1408 @code{strftime} returns the resulting string,
1409 @code{format-time-string} decodes the string using that same coding
1413 @defun seconds-to-time seconds
1414 This function converts @var{seconds}, a floating point number of
1415 seconds since the epoch, to a time value and returns that. To perform
1416 the inverse conversion, use @code{float-time}.
1419 @defun format-seconds format-string seconds
1420 This function converts its argument @var{seconds} into a string of
1421 years, days, hours, etc., according to @var{format-string}. The
1422 argument @var{format-string} may contain @samp{%}-sequences which
1423 control the conversion. Here is a table of what the
1424 @samp{%}-sequences mean:
1429 The integer number of 365-day years.
1432 The integer number of days.
1435 The integer number of hours.
1438 The integer number of minutes.
1441 The integer number of seconds.
1443 Non-printing control flag. When it is used, other specifiers must be
1444 given in the order of decreasing size, i.e.@: years before days, hours
1445 before minutes, etc. Nothing will be produced in the result string to
1446 the left of @samp{%z} until the first non-zero conversion is
1447 encountered. For example, the default format used by
1448 @code{emacs-uptime} (@pxref{Processor Run Time, emacs-uptime})
1449 @w{@code{"%Y, %D, %H, %M, %z%S"}} means that the number of seconds
1450 will always be produced, but years, days, hours, and minutes will only
1451 be shown if they are non-zero.
1453 Produces a literal @samp{%}.
1456 Upper-case format sequences produce the units in addition to the
1457 numbers, lower-case formats produce only the numbers.
1459 You can also specify the field width by following the @samp{%} with a
1460 number; shorter numbers will be padded with blanks. An optional
1461 period before the width requests zero-padding instead. For example,
1462 @code{"%.3Y"} might produce @code{"004 years"}.
1464 @emph{Warning:} This function works only with values of @var{seconds}
1465 that don't exceed @code{most-positive-fixnum} (@pxref{Integer Basics,
1466 most-positive-fixnum}).
1469 @node Processor Run Time
1470 @section Processor Run time
1471 @cindex processor run time
1472 @cindex Emacs process run time
1474 Emacs provides several functions and primitives that return time,
1475 both elapsed and processor time, used by the Emacs process.
1477 @deffn Command emacs-uptime &optional format
1478 This function returns a string representing the Emacs
1479 @dfn{uptime}---the elapsed wall-clock time this instance of Emacs is
1480 running. The string is formatted by @code{format-seconds} according
1481 to the optional argument @var{format}. For the available format
1482 descriptors, see @ref{Time Parsing, format-seconds}. If @var{format}
1483 is @code{nil} or omitted, it defaults to @code{"%Y, %D, %H, %M,
1486 When called interactively, it prints the uptime in the echo area.
1489 @defun get-internal-run-time
1490 This function returns the processor run time used by Emacs as a list
1491 of three integers: @code{(@var{high} @var{low} @var{microsec})}. The
1492 integers @var{high} and @var{low} combine to give the number of
1495 @var{high} * 2**16 + @var{low}.
1501 The third element, @var{microsec}, gives the microseconds (or 0 for
1502 systems that return time with the resolution of only one second).
1504 Note that the time returned by this function excludes the time Emacs
1505 was not using the processor, and if the Emacs process has several
1506 threads, the returned value is the sum of the processor times used up
1507 by all Emacs threads.
1509 If the system doesn't provide a way to determine the processor run
1510 time, @code{get-internal-run-time} returns the same time as
1511 @code{current-time}.
1514 @deffn Command emacs-init-time
1515 This function returns the duration of the Emacs initialization
1516 (@pxref{Startup Summary}) in seconds, as a string. When called
1517 interactively, it prints the duration in the echo area.
1520 @node Time Calculations
1521 @section Time Calculations
1523 These functions perform calendrical computations using time values
1524 (the kind of list that @code{current-time} returns).
1526 @defun time-less-p t1 t2
1527 This returns @code{t} if time value @var{t1} is less than time value
1531 @defun time-subtract t1 t2
1532 This returns the time difference @var{t1} @minus{} @var{t2} between
1533 two time values, in the same format as a time value.
1536 @defun time-add t1 t2
1537 This returns the sum of two time values, one of which ought to
1538 represent a time difference rather than a point in time.
1539 Here is how to add a number of seconds to a time value:
1542 (time-add @var{time} (seconds-to-time @var{seconds}))
1546 @defun time-to-days time
1547 This function returns the number of days between the beginning of year
1551 @defun time-to-day-in-year time
1552 This returns the day number within the year corresponding to @var{time}.
1555 @defun date-leap-year-p year
1556 This function returns @code{t} if @var{year} is a leap year.
1560 @section Timers for Delayed Execution
1563 You can set up a @dfn{timer} to call a function at a specified
1564 future time or after a certain length of idleness.
1566 Emacs cannot run timers at any arbitrary point in a Lisp program; it
1567 can run them only when Emacs could accept output from a subprocess:
1568 namely, while waiting or inside certain primitive functions such as
1569 @code{sit-for} or @code{read-event} which @emph{can} wait. Therefore, a
1570 timer's execution may be delayed if Emacs is busy. However, the time of
1571 execution is very precise if Emacs is idle.
1573 Emacs binds @code{inhibit-quit} to @code{t} before calling the timer
1574 function, because quitting out of many timer functions can leave
1575 things in an inconsistent state. This is normally unproblematical
1576 because most timer functions don't do a lot of work. Indeed, for a
1577 timer to call a function that takes substantial time to run is likely
1578 to be annoying. If a timer function needs to allow quitting, it
1579 should use @code{with-local-quit} (@pxref{Quitting}). For example, if
1580 a timer function calls @code{accept-process-output} to receive output
1581 from an external process, that call should be wrapped inside
1582 @code{with-local-quit}, to ensure that @kbd{C-g} works if the external
1585 It is usually a bad idea for timer functions to alter buffer
1586 contents. When they do, they usually should call @code{undo-boundary}
1587 both before and after changing the buffer, to separate the timer's
1588 changes from user commands' changes and prevent a single undo entry
1589 from growing to be quite large.
1591 Timer functions should also avoid calling functions that cause Emacs
1592 to wait, such as @code{sit-for} (@pxref{Waiting}). This can lead to
1593 unpredictable effects, since other timers (or even the same timer) can
1594 run while waiting. If a timer function needs to perform an action
1595 after a certain time has elapsed, it can do this by scheduling a new
1598 If a timer function calls functions that can change the match data,
1599 it should save and restore the match data. @xref{Saving Match Data}.
1601 @deffn Command run-at-time time repeat function &rest args
1602 This sets up a timer that calls the function @var{function} with
1603 arguments @var{args} at time @var{time}. If @var{repeat} is a number
1604 (integer or floating point), the timer is scheduled to run again every
1605 @var{repeat} seconds after @var{time}. If @var{repeat} is @code{nil},
1606 the timer runs only once.
1608 @var{time} may specify an absolute or a relative time.
1610 Absolute times may be specified using a string with a limited variety
1611 of formats, and are taken to be times @emph{today}, even if already in
1612 the past. The recognized forms are @samp{@var{xxxx}},
1613 @samp{@var{x}:@var{xx}}, or @samp{@var{xx}:@var{xx}} (military time),
1614 and @samp{@var{xx}am}, @samp{@var{xx}AM}, @samp{@var{xx}pm},
1615 @samp{@var{xx}PM}, @samp{@var{xx}:@var{xx}am},
1616 @samp{@var{xx}:@var{xx}AM}, @samp{@var{xx}:@var{xx}pm}, or
1617 @samp{@var{xx}:@var{xx}PM}. A period can be used instead of a colon
1618 to separate the hour and minute parts.
1620 To specify a relative time as a string, use numbers followed by units.
1625 denotes 1 minute from now.
1627 denotes 65 seconds from now.
1628 @item 1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year
1629 denotes exactly 103 months, 123 days, and 10862 seconds from now.
1632 For relative time values, Emacs considers a month to be exactly thirty
1633 days, and a year to be exactly 365.25 days.
1635 Not all convenient formats are strings. If @var{time} is a number
1636 (integer or floating point), that specifies a relative time measured in
1637 seconds. The result of @code{encode-time} can also be used to specify
1638 an absolute value for @var{time}.
1640 In most cases, @var{repeat} has no effect on when @emph{first} call
1641 takes place---@var{time} alone specifies that. There is one exception:
1642 if @var{time} is @code{t}, then the timer runs whenever the time is a
1643 multiple of @var{repeat} seconds after the epoch. This is useful for
1644 functions like @code{display-time}.
1646 The function @code{run-at-time} returns a timer value that identifies
1647 the particular scheduled future action. You can use this value to call
1648 @code{cancel-timer} (see below).
1651 A repeating timer nominally ought to run every @var{repeat} seconds,
1652 but remember that any invocation of a timer can be late. Lateness of
1653 one repetition has no effect on the scheduled time of the next
1654 repetition. For instance, if Emacs is busy computing for long enough
1655 to cover three scheduled repetitions of the timer, and then starts to
1656 wait, it will immediately call the timer function three times in
1657 immediate succession (presuming no other timers trigger before or
1658 between them). If you want a timer to run again no less than @var{n}
1659 seconds after the last invocation, don't use the @var{repeat} argument.
1660 Instead, the timer function should explicitly reschedule the timer.
1662 @defvar timer-max-repeats
1663 This variable's value specifies the maximum number of times to repeat
1664 calling a timer function in a row, when many previously scheduled
1665 calls were unavoidably delayed.
1668 @defmac with-timeout (seconds timeout-forms@dots{}) body@dots{}
1669 Execute @var{body}, but give up after @var{seconds} seconds. If
1670 @var{body} finishes before the time is up, @code{with-timeout} returns
1671 the value of the last form in @var{body}. If, however, the execution of
1672 @var{body} is cut short by the timeout, then @code{with-timeout}
1673 executes all the @var{timeout-forms} and returns the value of the last
1676 This macro works by setting a timer to run after @var{seconds} seconds. If
1677 @var{body} finishes before that time, it cancels the timer. If the
1678 timer actually runs, it terminates execution of @var{body}, then
1679 executes @var{timeout-forms}.
1681 Since timers can run within a Lisp program only when the program calls a
1682 primitive that can wait, @code{with-timeout} cannot stop executing
1683 @var{body} while it is in the midst of a computation---only when it
1684 calls one of those primitives. So use @code{with-timeout} only with a
1685 @var{body} that waits for input, not one that does a long computation.
1688 The function @code{y-or-n-p-with-timeout} provides a simple way to use
1689 a timer to avoid waiting too long for an answer. @xref{Yes-or-No
1692 @defun cancel-timer timer
1693 This cancels the requested action for @var{timer}, which should be a
1694 timer---usually, one previously returned by @code{run-at-time} or
1695 @code{run-with-idle-timer}. This cancels the effect of that call to
1696 one of these functions; the arrival of the specified time will not
1697 cause anything special to happen.
1701 @section Idle Timers
1703 Here is how to set up a timer that runs when Emacs is idle for a
1704 certain length of time. Aside from how to set them up, idle timers
1705 work just like ordinary timers.
1707 @deffn Command run-with-idle-timer secs repeat function &rest args
1708 Set up a timer which runs when Emacs has been idle for @var{secs}
1709 seconds. The value of @var{secs} may be an integer or a floating point
1710 number; a value of the type returned by @code{current-idle-time}
1713 If @var{repeat} is @code{nil}, the timer runs just once, the first time
1714 Emacs remains idle for a long enough time. More often @var{repeat} is
1715 non-@code{nil}, which means to run the timer @emph{each time} Emacs
1716 remains idle for @var{secs} seconds.
1718 The function @code{run-with-idle-timer} returns a timer value which you
1719 can use in calling @code{cancel-timer} (@pxref{Timers}).
1723 Emacs becomes ``idle'' when it starts waiting for user input, and it
1724 remains idle until the user provides some input. If a timer is set for
1725 five seconds of idleness, it runs approximately five seconds after Emacs
1726 first becomes idle. Even if @var{repeat} is non-@code{nil}, this timer
1727 will not run again as long as Emacs remains idle, because the duration
1728 of idleness will continue to increase and will not go down to five
1731 Emacs can do various things while idle: garbage collect, autosave or
1732 handle data from a subprocess. But these interludes during idleness do
1733 not interfere with idle timers, because they do not reset the clock of
1734 idleness to zero. An idle timer set for 600 seconds will run when ten
1735 minutes have elapsed since the last user command was finished, even if
1736 subprocess output has been accepted thousands of times within those ten
1737 minutes, and even if there have been garbage collections and autosaves.
1739 When the user supplies input, Emacs becomes non-idle while executing the
1740 input. Then it becomes idle again, and all the idle timers that are
1741 set up to repeat will subsequently run another time, one by one.
1744 @defun current-idle-time
1745 If Emacs is idle, this function returns the length of time Emacs has
1746 been idle, as a list of three integers: @code{(@var{high} @var{low}
1747 @var{microsec})}. The integers @var{high} and @var{low} combine to
1748 give the number of seconds of idleness, which is
1750 @var{high} * 2**16 + @var{low}.
1756 The third element, @var{microsec}, gives the microseconds since the
1757 start of the current second (or 0 for systems that return time with
1758 the resolution of only one second).
1760 When Emacs is not idle, @code{current-idle-time} returns @code{nil}.
1761 This is a convenient way to test whether Emacs is idle.
1763 The main use of this function is when an idle timer function wants to
1764 ``take a break'' for a while. It can set up another idle timer to
1765 call the same function again, after a few seconds more idleness.
1769 (defvar resume-timer nil
1770 "Timer that `timer-function' used to reschedule itself, or nil.")
1772 (defun timer-function ()
1773 ;; @r{If the user types a command while @code{resume-timer}}
1774 ;; @r{is active, the next time this function is called from}
1775 ;; @r{its main idle timer, deactivate @code{resume-timer}.}
1777 (cancel-timer resume-timer))
1778 ...@var{do the work for a while}...
1779 (when @var{taking-a-break}
1781 (run-with-idle-timer
1782 ;; Compute an idle time @var{break-length}
1783 ;; more than the current value.
1784 (time-add (current-idle-time)
1785 (seconds-to-time @var{break-length}))
1791 Some idle timer functions in user Lisp packages have a loop that
1792 does a certain amount of processing each time around, and exits when
1793 @code{(input-pending-p)} is non-@code{nil}. That approach seems very
1794 natural but has two problems:
1798 It blocks out all process output (since Emacs accepts process output
1799 only while waiting).
1802 It blocks out any idle timers that ought to run during that time.
1806 To avoid these problems, don't use that technique. Instead, write
1807 such idle timers to reschedule themselves after a brief pause, using
1808 the method in the @code{timer-function} example above.
1810 @node Terminal Input
1811 @section Terminal Input
1812 @cindex terminal input
1814 This section describes functions and variables for recording or
1815 manipulating terminal input. See @ref{Display}, for related
1819 * Input Modes:: Options for how input is processed.
1820 * Recording Input:: Saving histories of recent or all input events.
1824 @subsection Input Modes
1826 @cindex terminal input modes
1828 @defun set-input-mode interrupt flow meta &optional quit-char
1829 This function sets the mode for reading keyboard input. If
1830 @var{interrupt} is non-null, then Emacs uses input interrupts. If it is
1831 @code{nil}, then it uses @sc{cbreak} mode. The default setting is
1832 system-dependent. Some systems always use @sc{cbreak} mode regardless
1833 of what is specified.
1835 When Emacs communicates directly with X, it ignores this argument and
1836 uses interrupts if that is the way it knows how to communicate.
1838 If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff}
1839 (@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal. This
1840 has no effect except in @sc{cbreak} mode.
1843 The argument @var{meta} controls support for input character codes
1844 above 127. If @var{meta} is @code{t}, Emacs converts characters with
1845 the 8th bit set into Meta characters. If @var{meta} is @code{nil},
1846 Emacs disregards the 8th bit; this is necessary when the terminal uses
1847 it as a parity bit. If @var{meta} is neither @code{t} nor @code{nil},
1848 Emacs uses all 8 bits of input unchanged. This is good for terminals
1849 that use 8-bit character sets.
1852 If @var{quit-char} is non-@code{nil}, it specifies the character to
1853 use for quitting. Normally this character is @kbd{C-g}.
1857 The @code{current-input-mode} function returns the input mode settings
1858 Emacs is currently using.
1861 @defun current-input-mode
1862 This function returns the current mode for reading keyboard input. It
1863 returns a list, corresponding to the arguments of @code{set-input-mode},
1864 of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in
1868 is non-@code{nil} when Emacs is using interrupt-driven input. If
1869 @code{nil}, Emacs is using @sc{cbreak} mode.
1871 is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s})
1872 flow control for output to the terminal. This value is meaningful only
1873 when @var{interrupt} is @code{nil}.
1875 is @code{t} if Emacs treats the eighth bit of input characters as
1876 the meta bit; @code{nil} means Emacs clears the eighth bit of every
1877 input character; any other value means Emacs uses all eight bits as the
1878 basic character code.
1880 is the character Emacs currently uses for quitting, usually @kbd{C-g}.
1884 @node Recording Input
1885 @subsection Recording Input
1886 @cindex recording input
1889 This function returns a vector containing the last 300 input events from
1890 the keyboard or mouse. All input events are included, whether or not
1891 they were used as parts of key sequences. Thus, you always get the last
1892 100 input events, not counting events generated by keyboard macros.
1893 (These are excluded because they are less interesting for debugging; it
1894 should be enough to see the events that invoked the macros.)
1896 A call to @code{clear-this-command-keys} (@pxref{Command Loop Info})
1897 causes this function to return an empty vector immediately afterward.
1900 @deffn Command open-dribble-file filename
1901 @cindex dribble file
1902 This function opens a @dfn{dribble file} named @var{filename}. When a
1903 dribble file is open, each input event from the keyboard or mouse (but
1904 not those from keyboard macros) is written in that file. A
1905 non-character event is expressed using its printed representation
1906 surrounded by @samp{<@dots{}>}.
1908 You close the dribble file by calling this function with an argument
1911 This function is normally used to record the input necessary to
1912 trigger an Emacs bug, for the sake of a bug report.
1916 (open-dribble-file "~/dribble")
1922 See also the @code{open-termscript} function (@pxref{Terminal Output}).
1924 @node Terminal Output
1925 @section Terminal Output
1926 @cindex terminal output
1928 The terminal output functions send output to a text terminal, or keep
1929 track of output sent to the terminal. The variable @code{baud-rate}
1930 tells you what Emacs thinks is the output speed of the terminal.
1933 This variable's value is the output speed of the terminal, as far as
1934 Emacs knows. Setting this variable does not change the speed of actual
1935 data transmission, but the value is used for calculations such as
1938 It also affects decisions about whether to scroll part of the
1939 screen or repaint on text terminals. @xref{Forcing Redisplay},
1940 for the corresponding functionality on graphical terminals.
1942 The value is measured in baud.
1945 If you are running across a network, and different parts of the
1946 network work at different baud rates, the value returned by Emacs may be
1947 different from the value used by your local terminal. Some network
1948 protocols communicate the local terminal speed to the remote machine, so
1949 that Emacs and other programs can get the proper value, but others do
1950 not. If Emacs has the wrong value, it makes decisions that are less
1951 than optimal. To fix the problem, set @code{baud-rate}.
1953 @defun send-string-to-terminal string &optional terminal
1954 This function sends @var{string} to @var{terminal} without alteration.
1955 Control characters in @var{string} have terminal-dependent effects.
1956 This function operates only on text terminals. @var{terminal} may be
1957 a terminal object, a frame, or @code{nil} for the selected frame's
1958 terminal. In batch mode, @var{string} is sent to @code{stdout} when
1959 @var{terminal} is @code{nil}.
1961 One use of this function is to define function keys on terminals that
1962 have downloadable function key definitions. For example, this is how (on
1963 certain terminals) to define function key 4 to move forward four
1964 characters (by transmitting the characters @kbd{C-u C-f} to the
1969 (send-string-to-terminal "\eF4\^U\^F")
1975 @deffn Command open-termscript filename
1976 @cindex termscript file
1977 This function is used to open a @dfn{termscript file} that will record
1978 all the characters sent by Emacs to the terminal. It returns
1979 @code{nil}. Termscript files are useful for investigating problems
1980 where Emacs garbles the screen, problems that are due to incorrect
1981 Termcap entries or to undesirable settings of terminal options more
1982 often than to actual Emacs bugs. Once you are certain which characters
1983 were actually output, you can determine reliably whether they correspond
1984 to the Termcap specifications in use.
1986 You close the termscript file by calling this function with an
1987 argument of @code{nil}.
1989 See also @code{open-dribble-file} in @ref{Recording Input}.
1993 (open-termscript "../junk/termscript")
2000 @section Sound Output
2003 To play sound using Emacs, use the function @code{play-sound}. Only
2004 certain systems are supported; if you call @code{play-sound} on a system
2005 which cannot really do the job, it gives an error. Emacs version 20 and
2006 earlier did not support sound at all.
2008 The sound must be stored as a file in RIFF-WAVE format (@samp{.wav})
2009 or Sun Audio format (@samp{.au}).
2011 @defun play-sound sound
2012 This function plays a specified sound. The argument, @var{sound}, has
2013 the form @code{(sound @var{properties}...)}, where the @var{properties}
2014 consist of alternating keywords (particular symbols recognized
2015 specially) and values corresponding to them.
2017 Here is a table of the keywords that are currently meaningful in
2018 @var{sound}, and their meanings:
2021 @item :file @var{file}
2022 This specifies the file containing the sound to play.
2023 If the file name is not absolute, it is expanded against
2024 the directory @code{data-directory}.
2026 @item :data @var{data}
2027 This specifies the sound to play without need to refer to a file. The
2028 value, @var{data}, should be a string containing the same bytes as a
2029 sound file. We recommend using a unibyte string.
2031 @item :volume @var{volume}
2032 This specifies how loud to play the sound. It should be a number in the
2033 range of 0 to 1. The default is to use whatever volume has been
2036 @item :device @var{device}
2037 This specifies the system device on which to play the sound, as a
2038 string. The default device is system-dependent.
2041 Before actually playing the sound, @code{play-sound}
2042 calls the functions in the list @code{play-sound-functions}.
2043 Each function is called with one argument, @var{sound}.
2046 @defun play-sound-file file &optional volume device
2047 This function is an alternative interface to playing a sound @var{file}
2048 specifying an optional @var{volume} and @var{device}.
2051 @defvar play-sound-functions
2052 A list of functions to be called before playing a sound. Each function
2053 is called with one argument, a property list that describes the sound.
2057 @section Operating on X11 Keysyms
2060 To define system-specific X11 keysyms, set the variable
2061 @code{system-key-alist}.
2063 @defvar system-key-alist
2064 This variable's value should be an alist with one element for each
2065 system-specific keysym. Each element has the form @code{(@var{code}
2066 . @var{symbol})}, where @var{code} is the numeric keysym code (not
2067 including the ``vendor specific'' bit,
2074 and @var{symbol} is the name for the function key.
2076 For example @code{(168 . mute-acute)} defines a system-specific key (used
2077 by HP X servers) whose numeric code is
2086 It is not crucial to exclude from the alist the keysyms of other X
2087 servers; those do no harm, as long as they don't conflict with the ones
2088 used by the X server actually in use.
2090 The variable is always local to the current terminal, and cannot be
2091 buffer-local. @xref{Multiple Terminals}.
2094 You can specify which keysyms Emacs should use for the Meta, Alt, Hyper, and Super modifiers by setting these variables:
2096 @defvar x-alt-keysym
2097 @defvarx x-meta-keysym
2098 @defvarx x-hyper-keysym
2099 @defvarx x-super-keysym
2100 The name of the keysym that should stand for the Alt modifier
2101 (respectively, for Meta, Hyper, and Super). For example, here is
2102 how to swap the Meta and Alt modifiers within Emacs:
2104 (setq x-alt-keysym 'meta)
2105 (setq x-meta-keysym 'alt)
2113 The command-line option @samp{-batch} causes Emacs to run
2114 noninteractively. In this mode, Emacs does not read commands from the
2115 terminal, it does not alter the terminal modes, and it does not expect
2116 to be outputting to an erasable screen. The idea is that you specify
2117 Lisp programs to run; when they are finished, Emacs should exit. The
2118 way to specify the programs to run is with @samp{-l @var{file}}, which
2119 loads the library named @var{file}, or @samp{-f @var{function}}, which
2120 calls @var{function} with no arguments, or @samp{--eval @var{form}}.
2122 Any Lisp program output that would normally go to the echo area,
2123 either using @code{message}, or using @code{prin1}, etc., with @code{t}
2124 as the stream, goes instead to Emacs's standard error descriptor when
2125 in batch mode. Similarly, input that would normally come from the
2126 minibuffer is read from the standard input descriptor.
2127 Thus, Emacs behaves much like a noninteractive
2128 application program. (The echo area output that Emacs itself normally
2129 generates, such as command echoing, is suppressed entirely.)
2131 @defvar noninteractive
2132 This variable is non-@code{nil} when Emacs is running in batch mode.
2135 @node Session Management
2136 @section Session Management
2137 @cindex session manager
2139 Emacs supports the X Session Management Protocol, which is used to
2140 suspend and restart applications. In the X Window System, a program
2141 called the @dfn{session manager} is responsible for keeping track of
2142 the applications that are running. When the X server shuts down, the
2143 session manager asks applications to save their state, and delays the
2144 actual shutdown until they respond. An application can also cancel
2147 When the session manager restarts a suspended session, it directs
2148 these applications to individually reload their saved state. It does
2149 this by specifying a special command-line argument that says what
2150 saved session to restore. For Emacs, this argument is @samp{--smid
2153 @defvar emacs-save-session-functions
2154 Emacs supports saving state via a hook called
2155 @code{emacs-save-session-functions}. Emacs runs this hook when the
2156 session manager tells it that the window system is shutting down. The
2157 functions are called with no arguments, and with the current buffer
2158 set to a temporary buffer. Each function can use @code{insert} to add
2159 Lisp code to this buffer. At the end, Emacs saves the buffer in a
2160 file, called the @dfn{session file}.
2162 @findex emacs-session-restore
2163 Subsequently, when the session manager restarts Emacs, it loads the
2164 session file automatically (@pxref{Loading}). This is performed by a
2165 function named @code{emacs-session-restore}, which is called during
2166 startup. @xref{Startup Summary}.
2168 If a function in @code{emacs-save-session-functions} returns
2169 non-@code{nil}, Emacs tells the session manager to cancel the
2173 Here is an example that just inserts some text into @samp{*scratch*} when
2174 Emacs is restarted by the session manager.
2178 (add-hook 'emacs-save-session-functions 'save-yourself-test)
2182 (defun save-yourself-test ()
2183 (insert "(save-current-buffer
2184 (switch-to-buffer \"*scratch*\")
2185 (insert \"I am restored\"))")
2190 @node Dynamic Libraries
2191 @section Dynamically Loaded Libraries
2192 @cindex dynamic libraries
2194 A @dfn{dynamically loaded library} is a library that is loaded on
2195 demand, when its facilities are first needed. Emacs supports such
2196 on-demand loading of support libraries for some of its features.
2198 @defvar dynamic-library-alist
2199 This is an alist of dynamic libraries and external library files
2202 Each element is a list of the form
2203 @w{@code{(@var{library} @var{files}@dots{})}}, where the @code{car} is
2204 a symbol representing a supported external library, and the rest are
2205 strings giving alternate filenames for that library.
2207 Emacs tries to load the library from the files in the order they
2208 appear in the list; if none is found, the running session of Emacs
2209 won't have access to that library, and the features that depend on the
2210 library will be unavailable.
2212 Image support on some platforms uses this facility. Here's an example
2213 of setting this variable for supporting images on MS-Windows:
2216 (setq dynamic-library-alist
2217 '((xpm "libxpm.dll" "xpm4.dll" "libXpm-nox4.dll")
2218 (png "libpng12d.dll" "libpng12.dll" "libpng.dll"
2219 "libpng13d.dll" "libpng13.dll")
2220 (jpeg "jpeg62.dll" "libjpeg.dll" "jpeg-62.dll" "jpeg.dll")
2221 (tiff "libtiff3.dll" "libtiff.dll")
2222 (gif "giflib4.dll" "libungif4.dll" "libungif.dll")
2223 (svg "librsvg-2-2.dll")
2224 (gdk-pixbuf "libgdk_pixbuf-2.0-0.dll")
2225 (glib "libglib-2.0-0.dll")
2226 (gobject "libgobject-2.0-0.dll")))
2229 Note that image types @code{pbm} and @code{xbm} do not need entries in
2230 this variable because they do not depend on external libraries and are
2231 always available in Emacs.
2233 Also note that this variable is not meant to be a generic facility for
2234 accessing external libraries; only those already known by Emacs can
2235 be loaded through it.
2237 This variable is ignored if the given @var{library} is statically
2242 arch-tag: 8378814a-30d7-467c-9615-74a80b9988a7