X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/37680279159b37e6bcb20039988aff6a26204ad4..8325c01e4ba922ee7d6bb60651c25db3b0adbbce:/lispref/os.texi diff --git a/lispref/os.texi b/lispref/os.texi index 824d492e07..d6a58910f4 100644 --- a/lispref/os.texi +++ b/lispref/os.texi @@ -27,7 +27,7 @@ pertaining to the terminal and the screen. * Terminal Input:: Recording terminal input for debugging. * Terminal Output:: Recording terminal output for debugging. * Sound Output:: Playing sounds on the computer's speaker. -* Special Keysyms:: Defining system-specific key symbols for X windows. +* Special Keysyms:: Defining system-specific key symbols for X. * Flow Control:: How to turn output flow control on or off. * Batch Mode:: Running Emacs without terminal interaction. @end menu @@ -57,8 +57,11 @@ it is started up is as follows: @enumerate @item -It adds subdirectories to @code{load-path}, by running the file -named @file{subdirs.el} in each directory that is listed. +It adds subdirectories to @code{load-path}, by running the file named +@file{subdirs.el} in each directory in the list. Normally this file +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. @item It sets the language environment and the terminal coding system, @@ -118,7 +121,7 @@ that with @code{inhibit-startup-echo-area-message}. It processes the action arguments from the command line. @item -It runs @code{term-setup-hook}. +It runs @code{emacs-startup-hook} and then @code{term-setup-hook}. @item It calls @code{frame-notice-user-settings}, which modifies the @@ -231,7 +234,21 @@ This normal hook is run, once, just before loading all the init files @defvar after-init-hook This normal hook is run, once, just after loading all the init files (the user's init file, @file{default.el}, and/or @file{site-start.el}), -before the terminal-specific initialization. +before loading the terminal-specific library and processing the +command-line arguments. +@end defvar + +@defvar emacs-startup-hook +@tindex emacs-startup-hook +This normal hook is run, once, just after handling the command line +arguments, just before @code{term-setup-hook}. +@end defvar + +@defvar user-init-file +@tindex user-init-file +This variable holds the file name of the user's init file. If the +actual init file loaded is a compiled file, such as @file{.emacs.elc}, +the value refers to the corresponding source file. @end defvar @node Terminal-Specific @@ -488,7 +505,7 @@ 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 Windows or MS Windows). +a window system (X or MS Windows). @defun suspend-emacs string This function stops Emacs and returns control to the superior process. @@ -670,7 +687,7 @@ 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 +@deffn Command getenv var @cindex environment variable access This function returns the value of the environment variable @var{var}, as a string. Within Emacs, the environment variable values are kept in @@ -693,7 +710,7 @@ SHELL=/bin/csh HOME=/user/lewis @end group @end example -@end defun +@end deffn @c Emacs 19 feature @deffn Command setenv variable value @@ -721,6 +738,10 @@ process-environment "HOME=/user/lewis") @end group @end smallexample + +If @code{process-environment} contains ``duplicate'' elements that +specify the same environment variable, the first of these elements +specifies the variable, and the other ``duplicates'' are ignored. @end defvar @defvar path-separator @@ -730,6 +751,20 @@ value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS and MS-Windows. @end defvar +@defun parse-colon-path path +@tindex parse-colon-path +This function takes a search path string such as would be the value of +the @code{PATH} environment variable, and splits it at the separators, +returning a list of directory names. @code{nil} in this list stands for +``use the current directory.'' Although the function's name says +``colon,'' it actually uses the value of @code{path-separator}. + +@example +(parse-colon-path ":/foo:/bar") + @result{} (nil "/foo/" "/bar/") +@end example +@end defun + @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. @@ -964,6 +999,18 @@ integers. Thus, you can use times obtained from @code{current-time} (see above) and from @code{file-attributes} (@pxref{File Attributes}). @end defun +@defun float-time &optional time-value +This function returns the current time as a floating-point number of +seconds since the epoch. The argument @var{time-value}, if given, +specifies a time to convert instead of the current time. The argument +should have the same form as for @code{current-time-string} (see +above), and it also accepts the output of @code{current-time} and +@code{file-attributes}. + +@emph{Warning}: Since the result is floating point, it may not be +exact. Do not use this function if precise time stamps are required. +@end defun + @node Time Conversion @section Time Conversion @@ -1136,14 +1183,14 @@ Greenwich. @var{dow} and @var{zone}. @end defun -@defun encode-time seconds minutes hour day month year &optional @dots{}zone +@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, you must alter them yourself before you -call @code{encode-time}. +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 @@ -1588,6 +1635,9 @@ they were used as parts of key sequences. Thus, you always get the last 100 input events, not counting events generated by keyboard macros. (These are excluded because they are less interesting for debugging; it should be enough to see the events that invoked the macros.) + +A call to @code{clear-this-command-keys} (@pxref{Command Loop Info}) +causes this function to return an empty vector immediately afterward. @end defun @deffn Command open-dribble-file filename @@ -1714,10 +1764,19 @@ This specifies the file containing the sound to play. If the file name is not absolute, it is expanded against the directory @code{data-directory}. +@item :data @var{data} +This specifies the sound to play without need to refer to a file. The +value, @var{data}, should be a string containing the same bytes as a +sound file. We recommend using a unibyte string. + @item :volume @var{volume} This specifies how loud to play the sound. It should be a number in the range of 0 to 1. The default is to use whatever volume has been specified before. + +@item :device @var{device} +This specifies the system device on which to play the sound, as a +string. The default device is system-dependent. @end table Before actually playing the sound, @code{play-sound} @@ -1725,6 +1784,12 @@ calls the functions in the list @code{play-sound-functions}. Each function is called with one argument, @var{sound}. @end defun +@defun play-sound-file file &optional volume device +@tindex play-sound-file +This function is an alternative interface to playing a sound @var{file} +specifying an optional @var{volume} and @var{device}. +@end defun + @tindex play-sound-functions @defvar play-sound-functions A list of functions to be called before playing a sound. Each function @@ -1871,7 +1936,9 @@ calls @var{function} with no arguments. 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 error descriptor when -in batch mode. Thus, Emacs behaves much like a noninteractive +in batch mode. Similarly, input that would normally come from the +minibuffer is read from the standard input descriptor. +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.)