@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2004
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
+@c 2004, 2005 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/os
-@node System Interface, Antinews, Calendar, Top
+@node System Interface, Antinews, Display, Top
@chapter Operating System Interface
This chapter is about starting and getting out of Emacs, access to
* System Environment:: Distinguish the name and kind of system.
* User Identification:: Finding the name and user id of the user.
* Time of Day:: Getting the current time.
-* Time Conversion:: Converting a time from numeric form to a string, or
- to calendrical data (or vice versa).
+* Time Conversion:: Converting a time from numeric form
+ to calendrical data, and vice versa).
+* Time Parsing:: Converting a time from numeric form to text
+ and vice versa.
* Processor Run Time:: Getting the run time used by Emacs.
* Time Calculations:: Adding, subtracting, comparing times, etc.
* Timers:: Setting a timer to call a function at a certain time.
* Terminal Output:: Recording terminal output for debugging.
* Sound Output:: Playing sounds on the computer's speaker.
* X11 Keysyms:: Operating on key symbols for X Windows
-* Flow Control:: How to turn output flow control on or off.
* Batch Mode:: Running Emacs without terminal interaction.
* Session Management:: Saving and restoring state with X Session Management.
@end menu
It runs the normal hook @code{before-init-hook}.
@item
-It loads the library @file{site-start}, unless the option
-@samp{-no-site-file} was specified. The library's file name is usually
-@file{site-start.el}.
+It loads the library @file{site-start} (if any), unless the option
+@samp{-Q} (or @samp{--no-site-file}) was specified. The library's file
+name is usually @file{site-start.el}.
@cindex @file{site-start.el}
@item
-It loads your init file (usually @file{~/.emacs}), unless @samp{-q},
-@samp{-no-init-file}, or @samp{-batch} was specified on the command line.
-The @samp{-u} option can specify another user whose home directory
-should be used instead of @file{~}.
+It loads your init file (usually @file{~/.emacs}), unless the option
+@samp{-q} (or @samp{--no-init-file}), @samp{-Q}, or @samp{--batch} was
+specified on the command line. The @samp{-u} option can specify
+another user whose home directory should be used instead of @file{~}.
@item
-It loads the library @file{default}, unless @code{inhibit-default-init}
-is non-@code{nil}. (This is not done in @samp{-batch} mode or if
-@samp{-q} was specified on the command line.) The library's file name
-is usually @file{default.el}.
+It loads the library @file{default} (if any), unless
+@code{inhibit-default-init} is non-@code{nil}. (This is not done in
+@samp{-batch} mode, or if @samp{-Q} or @samp{-q} was specified on the
+command line.) The library's file name is usually @file{default.el}.
@cindex @file{default.el}
@item
@item
It displays copyleft, nonwarranty, and basic use information, provided
-there were no remaining command-line arguments (a few steps above),
-the value of @code{inhibit-startup-message} is @code{nil}, and the
-buffer is still empty.
+the value of @code{inhibit-startup-message} is @code{nil}, you didn't
+specify @samp{--no-splash} or @samp{-Q}.
@end enumerate
@defopt inhibit-startup-message
@cindex @file{.emacs}
When you start Emacs, it normally attempts to load your @dfn{init
-file}, a file in your home directory. Its normal name is @file{.emacs},
-but you can alternatively call it @file{.emacs.el}, which enables you to
-byte-compile it (@pxref{Byte Compilation}); then the actual file loaded
-will be @file{.emacs.elc}.
-
- The command-line switches @samp{-q} and @samp{-u} control whether and
-where to find the init file; @samp{-q} says not to load an init file,
-and @samp{-u @var{user}} says to load @var{user}'s init file instead of
-yours. @xref{Entering Emacs,,, emacs, The GNU Emacs Manual}. If
-neither option is specified, Emacs uses the @code{LOGNAME} environment
+file}, a file in your home directory. Its normal name is
+@file{.emacs}, but you can alternatively call it @file{.emacs.el}.
+You can also store it inside a subdirectory @file{.emacs.d}.
+Whichever place you use, you can also compile the file (@pxref{Byte
+Compilation}); then the actual file loaded will be @file{.emacs.elc}.
+
+ The command-line switches @samp{-q}, @samp{-Q}, and @samp{-u}
+control whether and where to find the init file; @samp{-q} (and the
+stronger @samp{-Q}) says not to load an init file, while @samp{-u
+@var{user}} says to load @var{user}'s init file instead of yours.
+@xref{Entering Emacs,,, emacs, The GNU Emacs Manual}. If neither
+option is specified, Emacs uses the @code{LOGNAME} environment
variable, or the @code{USER} (most systems) or @code{USERNAME} (MS
-systems) variable, to find your home directory and thus your init file;
-this way, even if you have su'd, Emacs still loads your own init file.
-If those environment variables are absent, though, Emacs uses your
-user-id to find your home directory.
+systems) variable, to find your home directory and thus your init
+file; this way, even if you have su'd, Emacs still loads your own init
+file. If those environment variables are absent, though, Emacs uses
+your user-id to find your home directory.
@cindex default init file
- A site may have a @dfn{default init file}, which is the library named
-@file{default.el}. Emacs finds the @file{default.el} file through the
-standard search path for libraries (@pxref{How Programs Do Loading}).
-The Emacs distribution does not come with this file; sites may provide
-one for local customizations. If the default init file exists, it is
-loaded whenever you start Emacs, except in batch mode or if @samp{-q} is
-specified. But your own personal init file, if any, is loaded first; if
-it sets @code{inhibit-default-init} to a non-@code{nil} value, then
-Emacs does not subsequently load the @file{default.el} file.
+ A site may have a @dfn{default init file}, which is the library
+named @file{default.el}. Emacs finds the @file{default.el} file
+through the standard search path for libraries (@pxref{How Programs Do
+Loading}). The Emacs distribution does not come with this file; sites
+may provide one for local customizations. If the default init file
+exists, it is loaded whenever you start Emacs, except in batch mode or
+if @samp{-q} (or @samp{-Q}) is specified. But your own personal init
+file, if any, is loaded first; if it sets @code{inhibit-default-init}
+to a non-@code{nil} value, then Emacs does not subsequently load the
+@file{default.el} file.
Another file for site-customization is @file{site-start.el}. Emacs
loads this @emph{before} the user's init file. You can inhibit the
-loading of this file with the option @samp{-no-site-file}.
+loading of this file with the option @samp{--no-site-file}.
@defvar site-run-file
This variable specifies the site-customization file to load before the
system, the user's @acronym{UID}, and so on.
@defvar system-configuration
-This variable holds the GNU configuration name for the hardware/software
-configuration of your system, as a string. The convenient way to test
-parts of this string is with @code{string-match}.
+This variable holds the standard GNU configuration name for the
+hardware/software configuration of your system, as a string. The
+convenient way to test parts of this string is with
+@code{string-match}.
@end defvar
@defvar system-type
@section Time Conversion
These functions convert time values (lists of two or three integers)
-to strings or to calendrical information. There is also a function to
-convert calendrical information to a time value. You can get time
-values from the functions @code{current-time} (@pxref{Time of Day}) and
+to calendrical information and vice versa. You can get time values
+from the functions @code{current-time} (@pxref{Time of Day}) and
@code{file-attributes} (@pxref{Definition of file-attributes}).
-Many operating systems are limited to time values that contain 32 bits
+ Many operating systems are limited to time values that contain 32 bits
of information; these systems typically handle only the times from
1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC. However, some
operating systems have larger time values, and can represent times far
in the past or future.
-Time conversion functions always use the Gregorian calendar, even for
-dates before the Gregorian calendar was introduced. Year numbers count
-the number of years since the year 1 B.C., and do not skip zero as
-traditional Gregorian years do; for example, the year number @minus{}37
-represents the Gregorian year 38 B.C@.
+ Time conversion functions always use the Gregorian calendar, even
+for dates before the Gregorian calendar was introduced. Year numbers
+count the number of years since the year 1 B.C., and do not skip zero
+as traditional Gregorian years do; for example, the year number
+@minus{}37 represents the Gregorian year 38 B.C@.
+
+@defun decode-time &optional time
+This function converts a time value into calendrical information. If
+you don't specify @var{time}, it decodes the current time. The return
+value is a list of nine elements, as follows:
+
+@example
+(@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone})
+@end example
+
+Here is what the elements mean:
+
+@table @var
+@item seconds
+The number of seconds past the minute, as an integer between 0 and 59.
+On some operating systems, this is 60 for leap seconds.
+@item minutes
+The number of minutes past the hour, as an integer between 0 and 59.
+@item hour
+The hour of the day, as an integer between 0 and 23.
+@item day
+The day of the month, as an integer between 1 and 31.
+@item month
+The month of the year, as an integer between 1 and 12.
+@item year
+The year, an integer typically greater than 1900.
+@item dow
+The day of week, as an integer between 0 and 6, where 0 stands for
+Sunday.
+@item dst
+@code{t} if daylight savings time is effect, otherwise @code{nil}.
+@item zone
+An integer indicating the time zone, as the number of seconds east of
+Greenwich.
+@end table
+
+@strong{Common Lisp Note:} Common Lisp has different meanings for
+@var{dow} and @var{zone}.
+@end defun
+
+@defun encode-time seconds minutes hour day month year &optional zone
+This function is the inverse of @code{decode-time}. It converts seven
+items of calendrical data into a time value. For the meanings of the
+arguments, see the table above under @code{decode-time}.
+
+Year numbers less than 100 are not treated specially. If you want them
+to stand for years above 1900, or years above 2000, you must alter them
+yourself before you call @code{encode-time}.
+
+The optional argument @var{zone} defaults to the current time zone and
+its daylight savings time rules. If specified, it can be either a list
+(as you would get from @code{current-time-zone}), a string as in the
+@code{TZ} environment variable, @code{t} for Universal Time, or an
+integer (as you would get from @code{decode-time}). The specified
+zone is used without any further alteration for daylight savings time.
+
+If you pass more than seven arguments to @code{encode-time}, the first
+six are used as @var{seconds} through @var{year}, the last argument is
+used as @var{zone}, and the arguments in between are ignored. This
+feature makes it possible to use the elements of a list returned by
+@code{decode-time} as the arguments to @code{encode-time}, like this:
+
+@example
+(apply 'encode-time (decode-time @dots{}))
+@end example
+
+You can perform simple date arithmetic by using out-of-range values for
+the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month}
+arguments; for example, day 0 means the day preceding the given month.
+
+The operating system puts limits on the range of possible time values;
+if you try to encode a time that is out of range, an error results.
+For instance, years before 1970 do not work on some systems;
+on others, years as early as 1901 do work.
+@end defun
+
+@node Time Parsing
+@section Parsing and Formatting Times
+
+ These functions convert time values (lists of two or three integers)
+to text in a string, and vice versa.
@defun date-to-time string
This function parses the time-string @var{string} and returns the
the inverse conversion, use @code{float-time}.
@end defun
-@defun decode-time &optional time
-This function converts a time value into calendrical information. If
-you don't specify @var{time}, it decodes the current time. The return
-value is a list of nine elements, as follows:
-
-@example
-(@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone})
-@end example
-
-Here is what the elements mean:
-
-@table @var
-@item seconds
-The number of seconds past the minute, as an integer between 0 and 59.
-On some operating systems, this is 60 for leap seconds.
-@item minutes
-The number of minutes past the hour, as an integer between 0 and 59.
-@item hour
-The hour of the day, as an integer between 0 and 23.
-@item day
-The day of the month, as an integer between 1 and 31.
-@item month
-The month of the year, as an integer between 1 and 12.
-@item year
-The year, an integer typically greater than 1900.
-@item dow
-The day of week, as an integer between 0 and 6, where 0 stands for
-Sunday.
-@item dst
-@code{t} if daylight savings time is effect, otherwise @code{nil}.
-@item zone
-An integer indicating the time zone, as the number of seconds east of
-Greenwich.
-@end table
-
-@strong{Common Lisp Note:} Common Lisp has different meanings for
-@var{dow} and @var{zone}.
-@end defun
-
-@defun encode-time seconds minutes hour day month year &optional zone
-This function is the inverse of @code{decode-time}. It converts seven
-items of calendrical data into a time value. For the meanings of the
-arguments, see the table above under @code{decode-time}.
-
-Year numbers less than 100 are not treated specially. If you want them
-to stand for years above 1900, or years above 2000, you must alter them
-yourself before you call @code{encode-time}.
-
-The optional argument @var{zone} defaults to the current time zone and
-its daylight savings time rules. If specified, it can be either a list
-(as you would get from @code{current-time-zone}), a string as in the
-@code{TZ} environment variable, @code{t} for Universal Time, or an
-integer (as you would get from @code{decode-time}). The specified
-zone is used without any further alteration for daylight savings time.
-
-If you pass more than seven arguments to @code{encode-time}, the first
-six are used as @var{seconds} through @var{year}, the last argument is
-used as @var{zone}, and the arguments in between are ignored. This
-feature makes it possible to use the elements of a list returned by
-@code{decode-time} as the arguments to @code{encode-time}, like this:
-
-@example
-(apply 'encode-time (decode-time @dots{}))
-@end example
-
-You can perform simple date arithmetic by using out-of-range values for
-the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month}
-arguments; for example, day 0 means the day preceding the given month.
-
-The operating system puts limits on the range of possible time values;
-if you try to encode a time that is out of range, an error results.
-For instance, years before 1970 do not work on some systems;
-on others, years as early as 1901 do work.
-@end defun
-
@node Processor Run Time
@section Processor Run time
timer to call a function that takes substantial time to run is likely
to be annoying.
+ It is usually a bad idea for timer functions to alter buffer
+contents. When they do, they usually should call @code{undo-boundary}
+both before and after changing the buffer, to separate the timer's
+changes from user commands' changes and prevent a single undo entry
+from growing to be quite large.
+
+ If a timer function calls functions that can change the match data,
+it should save and restore the match data. @xref{Saving Match Data}.
+
@deffn Command run-at-time time repeat function &rest args
This sets up a timer that calls the function @var{function} with
arguments @var{args} at time @var{time}. If @var{repeat} is a number
If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff}
(@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal. This
-has no effect except in @sc{cbreak} mode. @xref{Flow Control}.
+has no effect except in @sc{cbreak} mode.
@c Emacs 19 feature
The argument @var{meta} controls support for input character codes
looked up in this char-table. If the value found there is
non-@code{nil}, then it is used instead of the actual input character.
-In the example below, we set @code{keyboard-translate-table} to a
-char-table. Then we fill it in to swap the characters @kbd{C-s} and
-@kbd{C-\} and the characters @kbd{C-q} and @kbd{C-^}. Subsequently,
-typing @kbd{C-\} has all the usual effects of typing @kbd{C-s}, and vice
-versa. (@xref{Flow Control}, for more information on this subject.)
-
-@cindex flow control example
-@example
-@group
-(defun evade-flow-control ()
- "Replace C-s with C-\ and C-q with C-^."
- (interactive)
-@end group
-@group
- (setq keyboard-translate-table
- (make-char-table 'keyboard-translate-table nil))
-@end group
-@group
- ;; @r{Swap @kbd{C-s} and @kbd{C-\}.}
- (aset keyboard-translate-table ?\034 ?\^s)
- (aset keyboard-translate-table ?\^s ?\034)
-@end group
-@group
- ;; @r{Swap @kbd{C-q} and @kbd{C-^}.}
- (aset keyboard-translate-table ?\036 ?\^q)
- (aset keyboard-translate-table ?\^q ?\036))
-@end group
-@end example
-
Note that this translation is the first thing that happens to a
character after it is read from the terminal. Record-keeping features
such as @code{recent-keys} and dribble files record the characters after
the keyboard translate table if necessary.
@end defun
+ Here's an example of using the @code{keyboard-translate-table} to
+make @kbd{C-x}, @kbd{C-c} and @kbd{C-v} perform the cut, copy and paste
+operations:
+
+@example
+(keyboard-translate ?\C-x 'control-x)
+(keyboard-translate ?\C-c 'control-c)
+(keyboard-translate ?\C-v 'control-v)
+(global-set-key [control-x] 'kill-region)
+(global-set-key [control-c] 'kill-ring-save)
+(global-set-key [control-v] 'yank)
+@end example
+
+@noindent
+On a graphical terminal that supports extended @acronym{ASCII} input,
+you can still get the standard Emacs meanings of one of those
+characters by typing it with the shift key. That makes it a different
+character as far as keyboard translation is concerned, but it has the
+same usual meaning.
+
The remaining translation features translate subsequences of key
sequences being read. They are implemented in @code{read-key-sequence}
and have no effect on input read with @code{read-event}.
@code{key-translation-map}, even though they are overridden by it.
Indeed, actual key bindings override @code{function-key-map} and thus
may alter the key sequence that @code{key-translation-map} receives.
-Clearly, it is better to avoid to avoid this type of situation.
+Clearly, it is better to avoid this type of situation.
The intent of @code{key-translation-map} is for users to map one
character set to another, including ordinary characters normally bound
@section Terminal Output
@cindex terminal output
- The terminal output functions send output to the terminal, or keep
+ The terminal output functions send output to a text terminal, or keep
track of output sent to the terminal. The variable @code{baud-rate}
tells you what Emacs thinks is the output speed of the terminal.
@defun send-string-to-terminal string
This function sends @var{string} to the terminal without alteration.
Control characters in @var{string} have terminal-dependent effects.
+This function operates only on text terminals.
One use of this function is to define function keys on terminals that
have downloadable function key definitions. For example, this is how (on
@end lisp
@end defvar
-@node Flow Control
-@section Flow Control
-@cindex flow control characters
-
- This section attempts to answer the question ``Why does Emacs use
-flow-control characters in its command character set?'' For a second
-view on this issue, read the comments on flow control in the
-@file{emacs/INSTALL} file from the distribution; for help with Termcap
-entries and DEC terminal concentrators, see @file{emacs/etc/TERMS}.
-
-@cindex @kbd{C-s}
-@cindex @kbd{C-q}
- At one time, most terminals did not need flow control, and none used
-@code{C-s} and @kbd{C-q} for flow control. Therefore, the choice of
-@kbd{C-s} and @kbd{C-q} as command characters for searching and quoting
-was natural and uncontroversial. With so many commands needing key
-assignments, of course we assigned meanings to nearly all @acronym{ASCII}
-control characters.
-
- Later, some terminals were introduced which required these characters
-for flow control. They were not very good terminals for full-screen
-editing, so Emacs maintainers ignored them. In later years, flow
-control with @kbd{C-s} and @kbd{C-q} became widespread among terminals,
-but by this time it was usually an option. And the majority of Emacs
-users, who can turn flow control off, did not want to switch to less
-mnemonic key bindings for the sake of flow control.
-
- So which usage is ``right''---Emacs's or that of some terminal and
-concentrator manufacturers? This question has no simple answer.
-
- One reason why we are reluctant to cater to the problems caused by
-@kbd{C-s} and @kbd{C-q} is that they are gratuitous. There are other
-techniques (albeit less common in practice) for flow control that
-preserve transparency of the character stream. Note also that their use
-for flow control is not an official standard. Interestingly, on the
-model 33 teletype with a paper tape punch (around 1970), @kbd{C-s} and
-@kbd{C-q} were sent by the computer to turn the punch on and off!
-
- As window systems and PC terminal emulators replace character-only
-terminals, the flow control problem is gradually disappearing. For the
-mean time, Emacs provides a convenient way of enabling flow control if
-you want it: call the function @code{enable-flow-control}.
-
-@deffn Command enable-flow-control &optional arg
-When @var{arg} is a positive integer, this function enables use of
-@kbd{C-s} and @kbd{C-q} for output flow control, and provides the
-characters @kbd{C-\} and @kbd{C-^} as aliases for them using
-@code{keyboard-translate-table} (@pxref{Translating Input}).
-
-When @var{arg} is a negative integer or zero, it disables these
-features. When @var{arg} is @code{nil} or omitted, it toggles.
-Interactively, @var{arg} is the prefix argument. If non-@code{nil},
-its numeric value is used.
-@end deffn
-
-You can use the function @code{enable-flow-control-on} in your
-init file to enable flow control automatically on certain
-terminal types.
-
-@defun enable-flow-control-on &rest termtypes
-This function enables flow control, and the aliases @kbd{C-\} and @kbd{C-^},
-if the terminal type is one of @var{termtypes}. For example:
-
-@smallexample
-(enable-flow-control-on "vt200" "vt300" "vt101" "vt131")
-@end smallexample
-@end defun
-
- Here is how @code{enable-flow-control} does its job:
-
-@enumerate
-@item
-@cindex @sc{cbreak}
-It sets @sc{cbreak} mode for terminal input, and tells the operating
-system to handle flow control. This is done using @code{set-input-mode}.
-
-@item
-It sets up @code{keyboard-translate-table} to translate @kbd{C-\} and
-@kbd{C-^} into @kbd{C-s} and @kbd{C-q}. Except at its very
-lowest level, Emacs never knows that the characters typed were anything
-but @kbd{C-s} and @kbd{C-q}, so you can in effect type them as @kbd{C-\}
-and @kbd{C-^} even when they are input for other commands.
-@xref{Translating Input}.
-@end enumerate
-
-If the terminal is the source of the flow control characters, then once
-you enable kernel flow control handling, you probably can make do with
-less padding than normal for that terminal. You can reduce the amount
-of padding by customizing the Termcap entry. You can also reduce it by
-setting @code{baud-rate} to a smaller value so that Emacs uses a smaller
-speed when calculating the padding needed. @xref{Terminal Output}.
-
@node Batch Mode
@section Batch Mode
@cindex batch mode
to be outputting to an erasable screen. The idea is that you specify
Lisp programs to run; when they are finished, Emacs should exit. The
way to specify the programs to run is with @samp{-l @var{file}}, which
-loads the library named @var{file}, and @samp{-f @var{function}}, which
-calls @var{function} with no arguments.
+loads the library named @var{file}, or @samp{-f @var{function}}, which
+calls @var{function} with no arguments, or @samp{--eval @var{form}}.
Any Lisp program output that would normally go to the echo area,
either using @code{message}, or using @code{prin1}, etc., with @code{t}