X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/78608595650c2428069026304d2d24cdb7d1f838..7d1db39e07eb8e671b64faa3096cd9c4c7787e68:/lispref/os.texi diff --git a/lispref/os.texi b/lispref/os.texi index e7b7b076e0..a21107bf4f 100644 --- a/lispref/os.texi +++ b/lispref/os.texi @@ -20,6 +20,8 @@ pertaining to the terminal and the screen. * 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. @@ -57,6 +59,10 @@ 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}. +@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. @@ -99,7 +105,7 @@ It displays the initial echo area message, unless you have suppressed 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}. @@ -177,6 +183,11 @@ Emacs does not subsequently load the @file{default.el} file. 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} @@ -541,9 +552,8 @@ through various functions. These variables include the name of the 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 @@ -552,14 +562,26 @@ AIX. @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. @@ -573,6 +595,9 @@ AT&T System V. @item vax-vms VAX VMS. +@item windows-nt +Microsoft windows NT. + @item xenix SCO Xenix 386. @end table @@ -598,6 +623,23 @@ This function returns the name of the machine you are running on. @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}, @@ -651,6 +693,13 @@ process-environment @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. @@ -708,12 +757,21 @@ indicating whether the privilege is currently enabled. @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 @@ -740,6 +798,16 @@ This function returns the full name of the user. @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. @@ -765,16 +833,16 @@ zone. 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 @@ -825,11 +893,152 @@ The argument @var{time-value}, if given, specifies a time to analyze 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. @@ -901,7 +1110,9 @@ functions. @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 @@ -943,7 +1154,7 @@ is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s}) 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. @@ -952,14 +1163,6 @@ is the character Emacs currently uses for quitting, usually @kbd{C-g}. @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 @@ -986,7 +1189,7 @@ The @key{META} key. 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 @@ -1271,6 +1474,9 @@ by HP X servers whose numeric code is (1 << 28) + 168. 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 @@ -1311,8 +1517,10 @@ for flow control is not an official standard. Interestingly, on the 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 @@ -1373,7 +1581,7 @@ 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 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.)