@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/os
@node System Interface, Antinews, Display, Top
scanned in their turn. The files @file{subdirs.el} are normally
generated automatically by Emacs installation.
+@vindex before-init-time
@item
-It sets the language environment and the terminal coding system,
-if requested by environment variables such as @code{LANG}.
+It records in the variable @code{before-init-time} the value of
+@code{current-time} (@pxref{Time of Day}). It also sets
+@code{after-init-time} to @code{nil}, so as to signal Lisp programs
+that Emacs initialization is in progress.
+
+@vindex initial-window-system@r{, and startup}
+@vindex window-system-initialization-alist
+@item
+It loads the initialization library for the window system specified by
+the variable @code{initial-window-system} (@pxref{Window Systems,
+initial-window-system}). This library's name is
+@file{term/@var{windowsystem}-win.el}, where @var{windowsystem} is the
+value of @code{initial-window-system}. From that library, it calls
+the appropriate initialization function. The initialization function
+is specified by @code{window-system-initialization-alist}, for each
+supported window system.
@item
-It loads the initialization library for the window system, if you are
-using a window system. This library's name is
-@file{term/@var{windowsystem}-win.el}.
+It sets the language environment and the terminal coding system,
+if requested by environment variables such as @code{LANG}.
@item
It processes the initial options. (Some of them are handled
even earlier than this.)
@item
-It initializes the window frame and faces, if appropriate.
+It runs the normal hook @code{before-init-hook}.
@item
-It runs the normal hook @code{before-init-hook}.
+It initializes the window frame and faces, if appropriate, and turns
+on the menu bar and tool bar, if the initial frame needs them.
+
+@item
+It registers the default colors for text-only terminals.
@item
It loads the library @file{site-start} (if any), unless the option
command line.) The library's file name is usually @file{default.el}.
@cindex @file{default.el}
+@item
+It loads your abbrevs from the file specified by
+@code{abbrev-file-name} (@pxref{Abbrev Files, abbrev-file-name}), if
+that file exists and can be read. (This is not done in @samp{-batch}
+mode.)
+
+@vindex after-init-time
+@item
+It records in the variable @code{after-init-time} the value of
+@code{current-time}. This variable was set to @code{nil} at the
+beginning of the Emacs session initialization (see above), so setting
+it to the current time both signals that the initialization phase is
+over, and, together with @code{before-init-time}, provides the
+measurement of how long it took.
+
@item
It runs the normal hook @code{after-init-hook}.
mode.
@item
-It loads the terminal-specific Lisp file, if any, except when in batch
-mode or using a window system.
+It loads the terminal-specific Lisp library, if any, except when in
+batch mode or when the variable @code{initial-window-system} (see
+above) specifies a non-@code{nil} window system. The name of this
+library is computed from the value of the variable
+@code{term-file-prefix}; for the details, see @ref{Terminal-Specific}.
+
+If the value of @code{term-file-prefix} is @code{nil}, this step is skipped.
@item
It displays the initial echo area message, unless you have suppressed
@item
It displays copyleft, nonwarranty, and basic use information, provided
-the value of @code{inhibit-startup-message} is @code{nil}, you didn't
+the value of @code{inhibit-startup-screen} is @code{nil}, you didn't
specify @samp{--no-splash} or @samp{-Q}.
+
+@item
+If the command-line arguments specified @option{--daemon}, @c FIXME: xref
+it calls @code{server-start} (@pxref{Emacs Server,,, emacs, The GNU
+Emacs Manual}).
+
+@item
+If started by the X session manager, it calls
+@code{emacs-session-restore} passing it as argument the ID of the
+previous session. @c FIXME: add an xref to the Emacs manual!
@end enumerate
-@defopt inhibit-startup-message
+@defopt inhibit-startup-screen
This variable inhibits the initial startup messages (the nonwarranty,
etc.). If it is non-@code{nil}, then the messages are not printed.
this variable in the init file of a new user, or in a way that affects
more than one user, because that would prevent new users from receiving
the information they are supposed to see.
+
+@code{inhibit-startup-message} is an alias for this variable, for
+back-compatibility.
@end defopt
@defopt inhibit-startup-echo-area-message
resume Emacs, use the appropriate command in the parent shell---most
likely @code{fg}.
+@cindex controlling terminal
+ Suspending works only on a terminal device from which the Emacs
+session was started. We call that device the @dfn{controlling
+terminal} of the session.
+
Some operating systems do not support suspension of jobs; on these
systems, ``suspension'' actually creates a new shell temporarily as a
subprocess of Emacs. Then you would exit the shell to return to Emacs.
may not have a parent that can resume it again, and in any case you can
give input to some other job such as a shell merely by moving to a
different window. Therefore, suspending is not allowed when Emacs is using
-a window system (X, MS Windows, or Mac).
+a window system (X, MS Windows).
@defun suspend-emacs &optional string
This function stops Emacs and returns control to the superior process.
If and when the superior process resumes Emacs, @code{suspend-emacs}
returns @code{nil} to its caller in Lisp.
+This function works only on the controlling terminal of the Emacs
+session; to relinquish control of other tty devices, use
+@code{suspend-tty} (see below). If the Emacs session uses more than
+one terminal device, you will need to delete the frames on all the
+other devices before suspending Emacs, otherwise this function signals
+an error.
+
If @var{string} is non-@code{nil}, its characters are sent to be read
as terminal input by Emacs's superior shell. The characters in
@var{string} are not echoed by the superior shell; only the results
after a suspension.
@end defvar
+@defun suspend-tty &optional tty
+If @var{tty} specifies a terminal device used by Emacs, this function
+relinquishes the device and restores it to its prior state. Frames
+that used the device continue to exist, but are not updated and Emacs
+doesn't read input from them. If @var{tty} is a frame, it means that
+frame's terminal; if it is @code{nil}, the function uses the selected
+frame's terminal. If @var{tty} is already suspended, the function
+does nothing.
+
+This function runs the hook @code{suspend-tty-functions} (each
+function gets one argument, the terminal that corresponds to
+@var{tty}).
+@end defun
+
+@defun resume-tty &optional tty
+Resume the previously suspended terminal device @var{tty}. If
+@var{tty} is a frame, it means resume that frame's terminal;
+@code{nil} means the selected frame.
+
+This function reopens the terminal device, re-initializes it, and
+redraws its with that terminal's selected frame. It then runs the
+hook @code{resume-tty-functions}, passing each function the terminal
+which corresponds to @var{tty}.
+
+If the same device is already used by another Emacs terminal, this
+function signals an error.
+@end defun
+
+@defun controlling-tty-p &optional terminal
+This function returns non-@code{nil} if @var{terminal} is the
+controlling terminal device of the Emacs session.
+@end defun
+
+@deffn Command suspend-frame
+This command @dfn{suspends} a frame. For GUI frames, it calls
+@code{iconify-frame} (@pxref{Visibility of Frames}); for text-only
+frames, it calls either @code{suspend-emacs} or @code{suspend-tty},
+depending on whether the frame is displayed on the controlling
+terminal device or not.
+@end deffn
+
@node System Environment
@section Operating System Environment
@cindex operating system environment
system Emacs is operating on. Here is a table of the possible values:
@table @code
-@item alpha-vms
-VMS on the Alpha.
-
@item aix-v3
AIX.
MS-DOS binds @code{system-type} to @code{ms-dos} even when you run it on
MS-Windows.
-@item next-mach
-NeXT Mach-based system.
-
@item usg-unix-v
AT&T System V.
-@item vax-vms
-VAX VMS.
-
@item windows-nt
-Microsoft windows NT. The same executable supports Windows 9X, but the
-value of @code{system-type} is @code{windows-nt} in either case.
+Microsoft Windows NT and later. The same executable supports Windows
+9X, but the value of @code{system-type} is @code{windows-nt} in either
+case.
@end table
specifies the variable, and the other ``duplicates'' are ignored.
@end defvar
+@defvar initial-environment
+This variable holds the list of environment variables Emacs inherited
+from its parent process. It is computed during startup, see
+@ref{Startup Summary}.
+@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
The value is @code{nil} if Emacs is running under a window system.
@end defvar
-@defun setprv privilege-name &optional setp getprv
-This function sets or resets a VMS privilege. (It does not exist on
-other systems.) The first argument is the privilege name, as a string.
-The second argument, @var{setp}, is @code{t} or @code{nil}, indicating
-whether the privilege is to be turned on or off. Its default is
-@code{nil}. The function returns @code{t} if successful, @code{nil}
-otherwise.
-
-If the third argument, @var{getprv}, is non-@code{nil}, @code{setprv}
-does not change the privilege, but returns @code{t} or @code{nil}
-indicating whether the privilege is currently enabled.
-@end defun
-
@node User Identification
@section User Identification
@cindex user identification
the inverse conversion, use @code{float-time}.
@end defun
+@defun format-seconds format-string seconds
+This function converts its argument @var{seconds} into a string of
+years, days, hours, etc., according to @var{format-string}. The
+argument @var{format-string} may contain @samp{%}-sequences which
+control the conversion. Here is a table of what the
+@samp{%}-sequences mean:
+
+@table @samp
+@item %y
+@itemx %Y
+The integer number of 365-day years.
+@item %d
+@itemx %D
+The integer number of days.
+@item %h
+@itemx %H
+The integer number of hours.
+@item %m
+@itemx %M
+The integer number of minutes.
+@item %s
+@itemx %S
+The integer number of seconds.
+@item %z
+Non-printing control flag. When it is used, other specifiers must be
+given in the order of decreasing size, i.e.@: years before days, hours
+before minutes, etc. Nothing will be produced in the result string to
+the left of @samp{%z} until the first non-zero conversion is
+encountered. For example, the default format used by
+@code{emacs-uptime} (@pxref{Processor Run Time, emacs-uptime})
+@w{@code{"%Y, %D, %H, %M, %z%S"}} means that the number of seconds
+will always be produced, but years, days, hours, and minutes will only
+be shown if they are non-zero.
+@item %%
+Produces a literal @samp{%}.
+@end table
+
+Upper-case format sequences produce the units in addition to the
+numbers, lower-case formats produce only the numbers.
+
+You can also specify the field width by following the @samp{%} with a
+number; shorter numbers will be padded with blanks. An optional
+period before the width requests zero-padding instead. For example,
+@code{"%.3Y"} might produce @code{"004 years"}.
+
+@emph{Warning:} This function works only with values of @var{seconds}
+that don't exceed @code{most-positive-fixnum} (@pxref{Integer Basics,
+most-positive-fixnum}).
+@end defun
+
@node Processor Run Time
@section Processor Run time
@cindex processor run time
+@cindex Emacs process run time
+
+ Emacs provides several functions and primitives that return time,
+both elapsed and processor time, used by the Emacs process.
+
+@defun emacs-uptime &optional format
+This function returns a string representing the Emacs
+@dfn{uptime}---the elapsed wall-clock time this instance of Emacs is
+running. The string is formatted by @code{format-seconds} according
+to the optional argument @var{format}. For the available format
+descriptors, see @ref{Time Parsing, format-seconds}. If @var{format}
+is @code{nil} or omitted, it defaults to @code{"%Y, %D, %H, %M,
+%z%S"}.
+@end defun
@defun get-internal-run-time
This function returns the processor run time used by Emacs as a list
The third element, @var{microsec}, gives the microseconds (or 0 for
systems that return time with the resolution of only one second).
+Note that the time returned by this function excludes the time Emacs
+was not using the processor, and if the Emacs process has several
+threads, the returned value is the sum of the processor times used up
+by all Emacs threads.
+
If the system doesn't provide a way to determine the processor run
-time, get-internal-run-time returns the same time as current-time.
+time, @code{get-internal-run-time} returns the same time as
+@code{current-time}.
+@end defun
+
+@defun emacs-init-time
+This function returns the duration of the Emacs initialization
+(@pxref{Startup Summary}) in seconds, as a string.
@end defun
@node Time Calculations