X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/ffe832ea680b4820f5ff399191f7f2d41350ee2e..4b0f717890dd0951bf68ebccada20f90580cdc30:/doc/lispref/os.texi diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index 0519e7dfa3..ddca40dc5d 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -1,7 +1,7 @@ @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 @@ -69,24 +69,42 @@ adds the directory's subdirectories to the list, and these will be 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 @@ -107,6 +125,21 @@ It loads the library @file{default} (if any), unless 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}. @@ -116,8 +149,13 @@ the buffer @samp{*scratch*} is still current and still in Fundamental 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 @@ -139,11 +177,21 @@ It runs @code{window-setup-hook}. @xref{Window Systems}. @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. @@ -152,6 +200,9 @@ you are familiar with the contents of the startup message. Do not set 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 @@ -526,6 +577,11 @@ same buffers, the same kill ring, the same undo history, and so on. To 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. @@ -534,13 +590,20 @@ 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 @@ -612,6 +675,47 @@ This variable is a normal hook that Emacs runs on resuming 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 @@ -633,9 +737,6 @@ 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 alpha-vms -VMS on the Alpha. - @item aix-v3 AIX. @@ -664,18 +765,13 @@ Microsoft MS-DOS ``operating system.'' Emacs compiled with DJGPP for 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 @@ -780,6 +876,12 @@ specify the same environment variable, the first of these elements 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 @@ -865,19 +967,6 @@ in the system's terminal driver, before Emacs was started. 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 @@ -1302,9 +1391,73 @@ seconds since the epoch, to a time value and returns that. To perform 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 @@ -1321,8 +1474,19 @@ $high*2^{16}+low$. 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