-\1f
-File: lispref.info, Node: System Environment, Next: User Identification, Prev: Getting Out, Up: System Interface
-
-Operating System Environment
-============================
-
- XEmacs provides access to variables in the operating system
-environment through various functions. These variables include the
-name of the system, the user's UID, and so on.
-
- - Variable: system-type
- The value of this variable is a symbol indicating the type of
- operating system XEmacs is operating on. Here is a table of the
- possible values:
-
- `aix-v3'
- AIX.
-
- `berkeley-unix'
- Berkeley BSD.
-
- `dgux'
- Data General DGUX operating system.
-
- `gnu'
- A GNU system using the GNU HURD and Mach.
-
- `hpux'
- Hewlett-Packard HPUX operating system.
-
- `irix'
- Silicon Graphics Irix system.
-
- `linux'
- A GNU system using the Linux kernel.
-
- `ms-dos'
- Microsoft MS-DOS "operating system."
-
- `next-mach'
- NeXT Mach-based system.
-
- `rtu'
- Masscomp RTU, UCB universe.
-
- `unisoft-unix'
- UniSoft UniPlus.
-
- `usg-unix-v'
- AT&T System V.
-
- `vax-vms'
- VAX VMS.
-
- `windows-nt'
- Microsoft windows NT.
-
- `xenix'
- SCO Xenix 386.
-
- We do not wish to add new symbols to make finer distinctions
- unless it is absolutely necessary! In fact, we hope to eliminate
- some of these alternatives in the future. We recommend using
- `system-configuration' to distinguish between different operating
- systems.
-
- - Variable: system-configuration
- This variable holds the three-part configuration name for the
- hardware/software configuration of your system, as a string. The
- convenient way to test parts of this string is with `string-match'.
-
- - Function: system-name
- This function returns the name of the machine you are running on.
- (system-name)
- => "prep.ai.mit.edu"
-
- The symbol `system-name' is a variable as well as a function. In
-fact, the function returns whatever value the variable `system-name'
-currently holds. Thus, you can set the variable `system-name' in case
-Emacs is confused about the name of your system. The variable is also
-useful for constructing frame titles (*note Frame Titles::).
-
- - Variable: mail-host-address
- If this variable is non-`nil', it is used instead of `system-name'
- for purposes of generating email addresses. For example, it is
- used when constructing the default value of `user-mail-address'.
- *Note User Identification::. (Since this is done when XEmacs
- starts up, the value actually used is the one saved when XEmacs
- was dumped. *Note Building XEmacs::.)
-
- - Function: getenv var
- This function returns the value of the environment variable VAR,
- as a string. Within XEmacs, the environment variable values are
- kept in the Lisp variable `process-environment'.
-
- (getenv "USER")
- => "lewis"
-
- lewis@slug[10] % printenv
- PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
- USER=lewis
- TERM=ibmapa16
- SHELL=/bin/csh
- HOME=/user/lewis
-
- - Command: setenv variable value
- This command sets the value of the environment variable named
- VARIABLE to VALUE. Both arguments should be strings. This
- function works by modifying `process-environment'; binding that
- variable with `let' is also reasonable practice.
-
- - Variable: process-environment
- This variable is a list of strings, each describing one environment
- variable. The functions `getenv' and `setenv' work by means of
- this variable.
-
- process-environment
- => ("l=/usr/stanford/lib/gnuemacs/lisp"
- "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
- "USER=lewis"
- "TERM=ibmapa16"
- "SHELL=/bin/csh"
- "HOME=/user/lewis")
-
- - Variable: 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 `":"' for Unix and GNU systems, and `";"'
- for MS-DOS and Windows NT.
-
- - Variable: 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.
-
- - Variable: invocation-directory
- This variable holds the directory from which the Emacs executable
- was invoked, or perhaps `nil' if that directory cannot be
- determined.
-
- - Variable: installation-directory
- If non-`nil', this is a directory within which to look for the
- `lib-src' and `etc' subdirectories. This is non-`nil' when Emacs
- can't find those directories in their standard installed
- locations, but can find them in a directory related somehow to the
- one containing the Emacs executable.
-
- - Function: load-average &optional use-floats
- This function returns a list of the current 1-minute, 5-minute and
- 15-minute load averages. The values are integers that are 100
- times the system load averages. (The load averages indicate the
- number of processes trying to run.)
-
- When USE-FLOATS is non-`nil', floats will be returned instead of
- integers. These floats are not multiplied by 100.
-
- (load-average)
- => (169 158 164)
- (load-average t)
- => (1.69921875 1.58984375 1.640625)
-
- lewis@rocky[5] % uptime
- 8:06pm up 16 day(s), 21:57, 40 users,
- load average: 1.68, 1.59, 1.64
-
- If the 5-minute or 15-minute load averages are not available,
- return a shortened list, containing only those averages which are
- available.
-
- On some systems, this function may require special privileges to
- run, or it may be unimplemented for the particular system type.
- In that case, the function will signal an error.
-
- - Function: emacs-pid
- This function returns the process ID of the Emacs process.
-
- - Function: setprv privilege-name &optional setp getprv
- This function sets or resets a VMS privilege. (It does not exist
- on Unix.) The first arg is the privilege name, as a string. The
- second argument, SETP, is `t' or `nil', indicating whether the
- privilege is to be turned on or off. Its default is `nil'. The
- function returns `t' if successful, `nil' otherwise.
-
- If the third argument, GETPRV, is non-`nil', `setprv' does not
- change the privilege, but returns `t' or `nil' indicating whether
- the privilege is currently enabled.
-
-\1f
-File: lispref.info, Node: User Identification, Next: Time of Day, Prev: System Environment, Up: System Interface
-
-User Identification
-===================
-
- - Variable: 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.
-
- - Function: user-login-name &optional uid
- If you don't specify UID, this function returns the name under
- which the user is logged in. If the environment variable `LOGNAME'
- is set, that value is used. Otherwise, if the environment variable
- `USER' is set, that value is used. Otherwise, the value is based
- on the effective UID, not the real UID.
-
- If you specify UID, the value is the user name that corresponds to
- UID (which should be an integer).
-
- (user-login-name)
- => "lewis"
-
- - Function: user-real-login-name
- This function returns the user name corresponding to Emacs's real
- UID. This ignores the effective UID and ignores the environment
- variables `LOGNAME' and `USER'.
-
- - Variable: user-full-name
- This variable holds the name of the user running this Emacs. It is
- initialized at startup time from the value of `NAME' environment
- variable. You can change the value of this variable to alter the
- result of the `user-full-name' function.
-
- - Function: user-full-name &optional user
- This function returns the full name of USER. If USER is `nil', it
- defaults to the user running this Emacs. In that case, the value
- of `user-full-name' variable, if non-`nil', will be used.
-
- If USER is specified explicitly, `user-full-name' variable is
- ignored.
-
- (user-full-name)
- => "Hrvoje Niksic"
- (setq user-full-name "Hrvoje \"Niksa\" Niksic")
- (user-full-name)
- => "Hrvoje \"Niksa\" Niksic"
- (user-full-name "hniksic")
- => "Hrvoje Niksic"
-
- The symbols `user-login-name', `user-real-login-name' and
-`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 (*note Frame
-Titles::).
-
- - Function: user-real-uid
- This function returns the real UID of the user.
-
- (user-real-uid)
- => 19
-
- - Function: user-uid
- This function returns the effective UID of the user.
-
- - Function: user-home-directory
- This function returns the "`HOME'" directory of the user, and is
- intended to replace occurrences of "`(getenv "HOME")'". Under
- Unix systems, the following is done:
-
- 1. Return the value of "`(getenv "HOME")'", if set.
-
- 2. Return "/", as a fallback, but issue a warning. (Future
- versions of XEmacs will also attempt to lookup the `HOME'
- directory via `getpwent()', but this has not yet been
- implemented.)
-
- Under MS Windows, this is done:
-
- 1. Return the value of "`(getenv "HOME")'", if set.
-
- 2. If the environment variables `HOMEDRIVE' and `HOMEDIR' are
- both set, return the concatenation (the following description
- uses MS Windows environment variable substitution syntax):
- `%HOMEDRIVE%%HOMEDIR%'.
-
- 3. Return "C:\", as a fallback, but issue a warning.
-
-\1f
-File: lispref.info, Node: Time of Day, Next: Time Conversion, Prev: User Identification, Up: System Interface
-
-Time of Day
-===========
-
- This section explains how to determine the current time and the time
-zone.
-
- - Function: current-time-string &optional time-value
- 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 `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.
-
- The argument TIME-VALUE, if given, specifies a time to format
- instead of the current time. The argument should be a list whose
- first two elements are integers. Thus, you can use times obtained
- from `current-time' (see below) and from `file-attributes' (*note
- File Attributes::).
-
- (current-time-string)
- => "Wed Oct 14 22:21:05 1987"
-
- - Function: current-time
- This function returns the system's time value as a list of three
- integers: `(HIGH LOW MICROSEC)'. The integers HIGH and LOW
- combine to give the number of seconds since 0:00 January 1, 1970,
- which is HIGH * 2**16 + LOW.
-
- The third element, MICROSEC, gives the microseconds since the
- start of the current second (or 0 for systems that return time
- only on the resolution of a second).
-
- The first two elements can be compared with file time values such
- as you get with the function `file-attributes'. *Note File
- Attributes::.
-
- - Function: current-time-zone &optional time-value
- This function returns a list describing the time zone that the
- user is in.
-
- The value has the form `(OFFSET NAME)'. Here OFFSET is an integer
- giving the number of seconds ahead of UTC (east of Greenwich). A
- negative value means west of Greenwich. The second element, NAME
- is a string giving the name of the time zone. Both elements
- change when daylight savings time begins or ends; if the user has
- specified a time zone that does not use a seasonal time
- adjustment, then the value is constant through time.
-
- If the operating system doesn't supply all the information
- necessary to compute the value, both elements of the list are
- `nil'.
-
- The argument 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 `current-time'
- (see above) and from `file-attributes' (*note File Attributes::).
-
-\1f
-File: lispref.info, Node: Time Conversion, Next: Timers, Prev: Time of Day, Up: System Interface
-
-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 `current-time' (*note Time of Day::) and
-`file-attributes' (*note File Attributes::).
-
- - Function: format-time-string format-string &optional time
- This function converts TIME to a string according to
- FORMAT-STRING. If TIME is omitted, it defaults to the current
- time. The argument FORMAT-STRING may contain `%'-sequences which
- say to substitute parts of the time. Here is a table of what the
- `%'-sequences mean:
-
- `%a'
- This stands for the abbreviated name of the day of week.
-
- `%A'
- This stands for the full name of the day of week.
-
- `%b'
- This stands for the abbreviated name of the month.
-
- `%B'
- This stands for the full name of the month.
-
- `%c'
- This is a synonym for `%x %X'.
-
- `%C'
- This has a locale-specific meaning. In the default locale
- (named C), it is equivalent to `%A, %B %e, %Y'.
-
- `%d'
- This stands for the day of month, zero-padded.
-
- `%D'
- This is a synonym for `%m/%d/%y'.
-
- `%e'
- This stands for the day of month, blank-padded.
-
- `%h'
- This is a synonym for `%b'.
-
- `%H'
- This stands for the hour (00-23).
-
- `%I'
- This stands for the hour (00-12).
-
- `%j'
- This stands for the day of the year (001-366).
-
- `%k'
- This stands for the hour (0-23), blank padded.
-
- `%l'
- This stands for the hour (1-12), blank padded.
-
- `%m'
- This stands for the month (01-12).
-
- `%M'
- This stands for the minute (00-59).
-
- `%n'
- This stands for a newline.
-
- `%p'
- This stands for `AM' or `PM', as appropriate.
-
- `%r'
- This is a synonym for `%I:%M:%S %p'.
-
- `%R'
- This is a synonym for `%H:%M'.
-
- `%S'
- This stands for the seconds (00-60).
-
- `%t'
- This stands for a tab character.
-
- `%T'
- This is a synonym for `%H:%M:%S'.
-
- `%U'
- This stands for the week of the year (01-52), assuming that
- weeks start on Sunday.
-
- `%w'
- This stands for the numeric day of week (0-6). Sunday is day
- 0.
-
- `%W'
- This stands for the week of the year (01-52), assuming that
- weeks start on Monday.
-
- `%x'
- This has a locale-specific meaning. In the default locale
- (named C), it is equivalent to `%D'.
-
- `%X'
- This has a locale-specific meaning. In the default locale
- (named C), it is equivalent to `%T'.
-
- `%y'
- This stands for the year without century (00-99).
-
- `%Y'
- This stands for the year with century.
-
- `%Z'
- This stands for the time zone abbreviation.
-
- - Function: decode-time time
- This function converts a time value into calendrical information.
- The return value is a list of nine elements, as follows:
-
- (SECONDS MINUTES HOUR DAY MONTH YEAR DOW DST ZONE)
-
- Here is what the elements mean:
-
- SEC
- The number of seconds past the minute, as an integer between
- 0 and 59.
-
- MINUTE
- The number of minutes past the hour, as an integer between 0
- and 59.
-
- HOUR
- The hour of the day, as an integer between 0 and 23.
-
- DAY
- The day of the month, as an integer between 1 and 31.
-
- MONTH
- The month of the year, as an integer between 1 and 12.
-
- YEAR
- The year, an integer typically greater than 1900.
-
- DOW
- The day of week, as an integer between 0 and 6, where 0
- stands for Sunday.
-
- DST
- `t' if daylight savings time is effect, otherwise `nil'.
-
- ZONE
- An integer indicating the time zone, as the number of seconds
- east of Greenwich.
-
- Note that Common Lisp has different meanings for DOW and ZONE.
-
- - Function: encode-time seconds minutes hour day month year &optional
- zone
- This function is the inverse of `decode-time'. It converts seven
- items of calendrical data into a time value. For the meanings of
- the arguments, see the table above under `decode-time'.
-
- Year numbers less than 100 are treated just like other year
- numbers. If you want them to stand for years above 1900, you must
- alter them yourself before you call `encode-time'.
-
- The optional argument 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 `current-time-zone') or an integer (as
- you would get from `decode-time'). The specified zone is used
- without any further alteration for daylight savings time.
-
-\1f
-File: lispref.info, Node: Timers, Next: Terminal Input, Prev: Time Conversion, Up: System Interface
-
-Timers for Delayed Execution
-============================
-
- You can set up a timer to call a function at a specified future time.
-
- - Function: add-timeout secs function object &optional resignal
- This function adds a timeout, to be signaled after the timeout
- period has elapsed. SECS is a number of seconds, expressed as an
- integer or a float. FUNCTION will be called after that many
- seconds have elapsed, with one argument, the given OBJECT. If the
- optional RESIGNAL argument is provided, then after this timeout
- expires, `add-timeout' will automatically be called again with
- RESIGNAL as the first argument.
-
- This function returns an object which is the "id" of this
- particular timeout. You can pass that object to `disable-timeout'
- to turn off the timeout before it has been signalled.
-
- The number of seconds may be expressed as a floating-point number,
- in which case some fractional part of a second will be used.
- Caveat: the usable timeout granularity will vary from system to
- system.
-
- Adding a timeout causes a timeout event to be returned by
- `next-event', and the function will be invoked by
- `dispatch-event', so if XEmacs is in a tight loop, the function
- will not be invoked until the next call to sit-for or until the
- return to top-level (the same is true of process filters).
-
- WARNING: if you are thinking of calling add-timeout from inside of
- a callback function as a way of resignalling a timeout, think
- again. There is a race condition. That's why the RESIGNAL
- argument exists.
-
- (NOTE: In FSF Emacs, this function is called `run-at-time' and has
- different semantics.)
-
- - Function: disable-timeout id
- Cancel the requested action for ID, which should be a value
- previously returned by `add-timeout'. This cancels the effect of
- that call to `add-timeout'; the arrival of the specified time will
- not cause anything special to happen. (NOTE: In FSF Emacs, this
- function is called `cancel-timer'.)
-
-\1f
-File: lispref.info, Node: Terminal Input, Next: Terminal Output, Prev: Timers, Up: System Interface
-
-Terminal Input
-==============
-
- This section describes functions and variables for recording or
-manipulating terminal input. See *Note Display::, for related
-functions.
-
-* Menu:
-
-* Input Modes:: Options for how input is processed.
-* Translating Input:: Low level conversion of some characters or events
- into others.
-* Recording Input:: Saving histories of recent or all input events.
-