* 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).
* Timers:: Setting a timer to call a function at a certain time.
* Terminal Input:: Recording terminal input for debugging.
* Terminal Output:: Recording terminal output for debugging.
using a window system. This library's name is
@file{term/@var{windowsystem}-win.el}.
+@item
+It processes the initial options. (Some of them are handled
+even earlier than this.)
+
@item
It initializes the X window frame and faces, if appropriate.
that with @code{inhibit-startup-echo-area-message}.
@item
-It processes any remaining command line arguments.
+It processes the action arguments from the command line.
@item
It runs @code{term-setup-hook}.
loads this @emph{before} the user's init file. You can inhibit the
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 user's init file. Its normal value is @code{"site-start"}.
+@end defvar
+
If there is a great deal of code in your @file{.emacs} file, you
should move it into another file named @file{@var{something}.el},
byte-compile it (@pxref{Byte Compilation}), and make your @file{.emacs}
system, the user's @sc{uid}, and so on.
@defvar system-type
-The value of this variable is a symbol indicating the type of
-operating system Emacs is operating on. Here is a table of the symbols
-for the operating systems that Emacs can run on up to version 19.1.
+The value of this variable is a symbol indicating the type of operating
+system Emacs is operating on. Here is a table of the possible values:
@table @code
@item aix-v3
@item berkeley-unix
Berkeley BSD.
+@item dgux
+Data General DGUX operating system.
+
+@item gnu
+A GNU system using the GNU HURD and Mach.
+
@item hpux
-Hewlett-Packard operating system.
+Hewlett-Packard HPUX operating system.
@item irix
Silicon Graphics Irix system.
@item linux
-The free Linux operating system.
+A GNU system using the Linux kernel.
+
+@item ms-dos
+Microsoft MS-DOS ``operating system.''
+
+@item next-mach
+NeXT Mach-based system.
@item rtu
Masscomp RTU, UCB universe.
@item vax-vms
VAX VMS.
+@item windows-nt
+Microsoft windows NT.
+
@item xenix
SCO Xenix 386.
@end table
@end example
@end defun
+@vindex system-name
+ The symbol @code{system-name} is a variable as well as a function. In
+fact, the function returns whatever value the variable
+@code{system-name} currently holds. Thus, you can set the variable
+@code{system-name} in case Emacs is confused about the name of your
+system. The variable is also useful for constructing frame titles
+(@pxref{Frame Titles}).
+
+@defvar mail-host-address
+If this variable is non-@code{nil}, it is used instead of
+@code{system-name} for purposes of generating email addresses. For
+example, it is used when constructing the default value of
+@code{user-mail-address}. @xref{User Identification}. (Since this is
+done when Emacs starts up, the value actually used is the one saved when
+Emacs was dumped. @xref{Building Emacs}.)
+@end defvar
+
@defun getenv var
@cindex environment variable access
This function returns the value of the environment variable @var{var},
@end smallexample
@end defvar
+@defvar path-separator
+This variable holds a string which says which character separates
+directories in a search path (as found in an environment variable). Its
+value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS
+and Windows NT.
+@end defvar
+
@defvar invocation-name
This variable holds the program name under which Emacs was invoked. The
value is a string, and does not include a directory name.
@node User Identification
@section User Identification
-@defun user-login-name
-This function returns the name under which the user is logged in. If
-the environment variable @code{LOGNAME} is set, that value is used.
-Otherwise, if the environment variable @code{USER} is set, that value is
-used. Otherwise, the value is based on the effective @sc{uid}, not the
-real @sc{uid}.
+@defvar user-mail-address
+This holds the nominal email address of the user who is using Emacs.
+When Emacs starts up, it computes a default value that is usually right,
+but users often set this themselves when the default value is not right.
+@end defvar
+
+@defun user-login-name &optional uid
+If you don't specify @var{uid}, this function returns the name under
+which the user is logged in. If the environment variable @code{LOGNAME}
+is set, that value is used. Otherwise, if the environment variable
+@code{USER} is set, that value is used. Otherwise, the value is based
+on the effective @sc{uid}, not the real @sc{uid}.
+
+If you specify @var{uid}, the value is the user name that corresponds
+to @var{uid} (which should be an integer).
@example
@group
@end example
@end defun
+@vindex user-full-name
+@vindex user-real-login-name
+@vindex user-login-name
+ The symbols @code{user-login-name}, @code{user-real-login-name} and
+@code{user-full-name} are variables as well as functions. The functions
+return the same values that the variables hold. These variables allow
+you to ``fake out'' Emacs by telling the functions what to return. The
+variables are also useful for constructing frame titles (@pxref{Frame
+Titles}).
+
@defun user-real-uid
This function returns the real @sc{uid} of the user.
This function returns the current time and date as a humanly-readable
string. The format of the string is unvarying; the number of characters
used for each part is always the same, so you can reliably use
-@code{substring} to extract pieces of it. However, it would be wise to
-count the characters from the beginning of the string rather than from
-the end, as additional information may be added at the end.
+@code{substring} to extract pieces of it. It is wise to count the
+characters from the beginning of the string rather than from the end, as
+additional information may be added at the end.
@c Emacs 19 feature
The argument @var{time-value}, if given, specifies a time to format
-instead of the current time. The argument should be a cons cell
-containing two integers, or a list whose first two elements are
-integers. Thus, you can use times obtained from @code{current-time}
-(see below) and from @code{file-attributes} (@pxref{File Attributes}).
+instead of the current time. The argument should be a list whose first
+two elements are integers. Thus, you can use times obtained from
+@code{current-time} (see below) and from @code{file-attributes}
+(@pxref{File Attributes}).
@example
@group
instead of the current time. The argument should be a cons cell
containing two integers, or a list whose first two elements are
integers. Thus, you can use times obtained from @code{current-time}
-(see below) and from @code{file-attributes} (@pxref{File Attributes}).
+(see above) and from @code{file-attributes} (@pxref{File Attributes}).
+@end defun
+
+@node Time Conversion
+@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
+@code{file-attributes} (@pxref{File Attributes}).
+
+@defun format-time-string format-string time
+This function converts @var{time} to a string according to
+@var{format-string}. The argument @var{format-string} may contain
+@samp{%}-sequences which say to substitute parts of the time. Here is a
+table of what the @samp{%}-sequences mean:
+
+@table @samp
+@item %a
+This stands for the abbreviated name of the day of week.
+@item %A
+This stands for the full name of the day of week.
+@item %b
+This stands for the abbreviated name of the month.
+@item %B
+This stands for the full name of the month.
+@item %c
+This is a synonym for @samp{%x %X}.
+@item %C
+This has a locale-specific meaning. In the default locale (named C), it
+is equivalent to @samp{%A, %B %e, %Y}.
+@item %d
+This stands for the day of month, zero-padded.
+@item %D
+This is a synonym for @samp{%m/%d/%y}.
+@item %e
+This stands for the day of month, blank-padded.
+@item %h
+This is a synonym for @samp{%b}.
+@item %H
+This stands for the hour (00-23).
+@item %I
+This stands for the hour (00-12).
+@item %j
+This stands for the day of the year (001-366).
+@item %k
+This stands for the hour (0-23), blank padded.
+@item %l
+This stands for the hour (1-12), blank padded.
+@item %m
+This stands for the month (01-12).
+@item %M
+This stands for the minute (00-59).
+@item %n
+This stands for a newline.
+@item %p
+This stands for @samp{AM} or @samp{PM}, as appropriate.
+@item %r
+This is a synonym for @samp{%I:%M:%S %p}.
+@item %R
+This is a synonym for @samp{%H:%M}.
+@item %S
+This stands for the seconds (00-60).
+@item %t
+This stands for a tab character.
+@item %T
+This is a synonym for @samp{%H:%M:%S}.
+@item %U
+This stands for the week of the year (01-52), assuming that weeks
+start on Sunday.
+@item %w
+This stands for the numeric day of week (0-6). Sunday is day 0.
+@item %W
+This stands for the week of the year (01-52), assuming that weeks
+start on Monday.
+@item %x
+This has a locale-specific meaning. In the default locale (named C), it
+is equivalent to @samp{%D}.
+@item %X
+This has a locale-specific meaning. In the default locale (named C), it
+is equivalent to @samp{%T}.
+@item %y
+This stands for the year without century (00-99).
+@item %Y
+This stands for the year with century.
+@item %Z
+This stands for the time zone abbreviation.
+@end table
+@end defun
+
+@defun decode-time time
+This function converts a time value into calendrical information. 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 sec
+The number of seconds past the minute, as an integer between 0 and 59.
+@item minute
+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
+
+Note that 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 treated just like other year numbers. If
+you them to stand for years above 1900, 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}) or an integer (as you
+would get from @code{decode-time}). The specified zone is used without
+any further alteration for daylight savings time.
@end defun
@node Timers
-@section Timers
+@section Timers for Delayed Execution
You can set up a timer to call a function at a specified future time.
@defun set-input-mode interrupt flow meta quit-char
This function sets the mode for reading keyboard input. If
@var{interrupt} is non-null, then Emacs uses input interrupts. If it is
-@code{nil}, then it uses @sc{cbreak} mode.
+@code{nil}, then it uses @sc{cbreak} mode. When Emacs communicates
+directly with X, it ignores this argument and uses interrupts if that is
+the way it knows how to communicate.
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
flow control for output to the terminal. This value has no effect
unless @var{interrupt} is non-@code{nil}.
@item meta
-is non-@code{t} if Emacs treats the eighth bit of input characters as
+is @code{t} if Emacs treats the eighth bit of input characters as
the meta bit; @code{nil} means Emacs clears the eighth bit of every
input character; any other value means Emacs uses all eight bits as the
basic character code.
@end table
@end defun
-@defvar meta-flag
-This variable used to control whether to treat the eight bit in keyboard
-input characters as the @key{Meta} bit. @code{nil} meant no, and
-anything else meant yes. This variable existed in Emacs versions 18 and
-earlier but no longer exists in Emacs 19; use @code{set-input-mode}
-instead.
-@end defvar
-
@node Translating Input
@subsection Translating Input Events
@cindex translating input events
Each time the user types a keyboard key, it is altered as if the
modifier keys specified in the bit mask were held down.
-When you use X windows, the program can ``press'' any of the modifier
+When using X windows, the program can ``press'' any of the modifier
keys in this way. Otherwise, only the @key{CTL} and @key{META} keys can
be virtually pressed.
@end defvar
It is not a problem if the alist defines keysyms for other X servers, as
long as they don't conflict with the ones used by the X server actually
in use.
+
+The variable is always local to the current X terminal and cannot be
+buffer-local. @xref{Multiple Displays}.
@end defvar
@node Flow Control
model 33 teletype with a paper tape punch (which is very old), @kbd{C-s}
and @kbd{C-q} were sent by the computer to turn the punch on and off!
- GNU Emacs version 19 provides a convenient way of enabling flow
-control if you want it: call the function @code{enable-flow-control}.
+ As X servers and other window systems replace character-only
+terminals, this problem is gradually being cured. For the mean time,
+Emacs provides a convenient way of enabling flow control if you want it:
+call the function @code{enable-flow-control}.
@defun enable-flow-control
This function enables use of @kbd{C-s} and @kbd{C-q} for output flow
Any Lisp program output that would normally go to the echo area,
either using @code{message} or using @code{prin1}, etc., with @code{t}
-as the stream, goes instead to Emacs's standard output descriptor when
+as the stream, goes instead to Emacs's standard error descriptor when
in batch mode. Thus, Emacs behaves much like a noninteractive
application program. (The echo area output that Emacs itself normally
generates, such as command echoing, is suppressed entirely.)