-This is ../info/lispref.info, produced by makeinfo version 4.0 from
+This is ../info/lispref.info, produced by makeinfo version 4.0b from
lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
Foundation instead of in the original English.
\1f
-File: lispref.info, Node: Process Buffers, Next: Filter Functions, Up: Output from Processes
-
-Process Buffers
----------------
-
- A process can (and usually does) have an "associated buffer", which
-is an ordinary Emacs buffer that is used for two purposes: storing the
-output from the process, and deciding when to kill the process. You
-can also use the buffer to identify a process to operate on, since in
-normal practice only one process is associated with any given buffer.
-Many applications of processes also use the buffer for editing input to
-be sent to the process, but this is not built into XEmacs Lisp.
-
- Unless the process has a filter function (*note Filter Functions::),
-its output is inserted in the associated buffer. The position to insert
-the output is determined by the `process-mark', which is then updated
-to point to the end of the text just inserted. Usually, but not
-always, the `process-mark' is at the end of the buffer.
-
- - Function: process-buffer process
- This function returns the associated buffer of the process PROCESS.
-
- (process-buffer (get-process "shell"))
- => #<buffer *shell*>
-
- - Function: process-mark process
- This function returns the process marker for PROCESS, which is the
- marker that says where to insert output from the process.
-
- If PROCESS does not have a buffer, `process-mark' returns a marker
- that points nowhere.
-
- Insertion of process output in a buffer uses this marker to decide
- where to insert, and updates it to point after the inserted text.
- That is why successive batches of output are inserted
- consecutively.
-
- Filter functions normally should use this marker in the same
- fashion as is done by direct insertion of output in the buffer. A
- good example of a filter function that uses `process-mark' is
- found at the end of the following section.
-
- When the user is expected to enter input in the process buffer for
- transmission to the process, the process marker is useful for
- distinguishing the new input from previous output.
-
- - Function: set-process-buffer process buffer
- This function sets the buffer associated with PROCESS to BUFFER.
- If BUFFER is `nil', the process becomes associated with no buffer.
-
- - Function: get-buffer-process buffer-or-name
- This function returns the process associated with BUFFER-OR-NAME.
- If there are several processes associated with it, then one is
- chosen. (Presently, the one chosen is the one most recently
- created.) It is usually a bad idea to have more than one process
- associated with the same buffer.
-
- (get-buffer-process "*shell*")
- => #<process shell>
-
- Killing the process's buffer deletes the process, which kills the
- subprocess with a `SIGHUP' signal (*note Signals to Processes::).
+File: lispref.info, Node: Active Display Table, Next: Character Descriptors, Prev: Display Table Format, Up: Display Tables
+
+Active Display Table
+--------------------
+
+ The active display table is controlled by the variable
+`current-display-table'. This is a specifier, which means that you can
+specify separate values for it in individual buffers, windows, frames,
+and devices, as well as a global value. It also means that you cannot
+set this variable using `setq'; use `set-specifier' instead. *Note
+Specifiers::. (FSF Emacs uses `window-display-table',
+`buffer-display-table', `standard-display-table', etc. to control the
+display table. However, specifiers are a cleaner and more powerful way
+of doing the same thing. FSF Emacs also uses a different format for
+the contents of a display table, using additional indirection to a
+"glyph table" and such. Note that "glyph" has a different meaning in
+XEmacs.)
+
+ - Variable: current-display-table
+ The display table currently in use. This is a specifier.
+
+ Display tables are used to control how characters are displayed.
+ Each time that redisplay processes a character, it is looked up in
+ all the display tables that apply (obtained by calling
+ `specifier-instance' on `current-display-table' and any overriding
+ display tables specified in currently active faces). The first
+ entry found that matches the character determines how the
+ character is displayed. If there is no matching entry, the
+ default display method is used. (Non-control characters are
+ displayed as themselves and control characters are displayed
+ according to the buffer-local variable `ctl-arrow'. Control
+ characters are further affected by `control-arrow-glyph' and
+ `octal-escape-glyph'.)
+
+ Each instantiator in this specifier and the display-table
+ specifiers in faces is a display table or a list of such tables.
+ If a list, each table will be searched in turn for an entry
+ matching a particular character. Each display table is one of
+
+ * A vector, specifying values for characters starting at 0.
+
+ * A char table, either of type `char' or `generic'.
+
+ * A range table.
+
+ Each entry in a display table should be one of
+
+ * nil (this entry is ignored and the search continues).
+
+ * A character (use this character; if it happens to be the same
+ as the original character, default processing happens,
+ otherwise redisplay attempts to display this character
+ directly; #### At some point recursive display-table lookup
+ will be implemented).
+
+ * A string (display each character in the string directly; ####
+ At some point recursive display-table lookup will be
+ implemented).
+
+ * A glyph (display the glyph; #### At some point recursive
+ display-table lookup will be implemented when a string glyph
+ is being processed).
+
+ * A cons of the form (format "STRING") where STRING is a
+ printf-like spec used to process the character. ####
+ Unfortunately no formatting directives other than %% are
+ implemented.
+
+ * A vector (each element of the vector is processed recursively;
+ in such a case, nil elements in the vector are simply
+ ignored).
+
+ #### At some point in the near future, display tables are
+ likely to be expanded to include other features, such as
+ referencing characters in particular fonts and allowing the
+ character search to continue all the way up the chain of
+ specifier instantiators. These features are necessary to
+ properly display Unicode characters.
+
+ Individual faces can also specify an overriding display table; this
+is set using `set-face-display-table'. *Note Faces::.
+
+ If no display table can be determined for a particular window, then
+XEmacs uses the usual display conventions. *Note Usual Display::.
\1f
-File: lispref.info, Node: Filter Functions, Next: Accepting Output, Prev: Process Buffers, Up: Output from Processes
-
-Process Filter Functions
-------------------------
-
- A process "filter function" is a function that receives the standard
-output from the associated process. If a process has a filter, then
-_all_ output from that process is passed to the filter. The process
-buffer is used directly for output from the process only when there is
-no filter.
-
- A filter function must accept two arguments: the associated process
-and a string, which is the output. The function is then free to do
-whatever it chooses with the output.
-
- A filter function runs only while XEmacs is waiting (e.g., for
-terminal input, or for time to elapse, or for process output). This
-avoids the timing errors that could result from running filters at
-random places in the middle of other Lisp programs. You may explicitly
-cause Emacs to wait, so that filter functions will run, by calling
-`sit-for' or `sleep-for' (*note Waiting::), or `accept-process-output'
-(*note Accepting Output::). Emacs is also waiting when the command loop
-is reading input.
-
- Quitting is normally inhibited within a filter function--otherwise,
-the effect of typing `C-g' at command level or to quit a user command
-would be unpredictable. If you want to permit quitting inside a filter
-function, bind `inhibit-quit' to `nil'. *Note Quitting::.
-
- If an error happens during execution of a filter function, it is
-caught automatically, so that it doesn't stop the execution of whatever
-program was running when the filter function was started. However, if
-`debug-on-error' is non-`nil', the error-catching is turned off. This
-makes it possible to use the Lisp debugger to debug the filter
-function. *Note Debugger::.
-
- Many filter functions sometimes or always insert the text in the
-process's buffer, mimicking the actions of XEmacs when there is no
-filter. Such filter functions need to use `set-buffer' in order to be
-sure to insert in that buffer. To avoid setting the current buffer
-semipermanently, these filter functions must use `unwind-protect' to
-make sure to restore the previous current buffer. They should also
-update the process marker, and in some cases update the value of point.
-Here is how to do these things:
-
- (defun ordinary-insertion-filter (proc string)
- (let ((old-buffer (current-buffer)))
- (unwind-protect
- (let (moving)
- (set-buffer (process-buffer proc))
- (setq moving (= (point) (process-mark proc)))
- (save-excursion
- ;; Insert the text, moving the process-marker.
- (goto-char (process-mark proc))
- (insert string)
- (set-marker (process-mark proc) (point)))
- (if moving (goto-char (process-mark proc))))
- (set-buffer old-buffer))))
-
-The reason to use an explicit `unwind-protect' rather than letting
-`save-excursion' restore the current buffer is so as to preserve the
-change in point made by `goto-char'.
-
- To make the filter force the process buffer to be visible whenever
-new text arrives, insert the following line just before the
-`unwind-protect':
-
- (display-buffer (process-buffer proc))
-
- To force point to move to the end of the new output no matter where
-it was previously, eliminate the variable `moving' and call `goto-char'
-unconditionally.
-
- In earlier Emacs versions, every filter function that did regexp
-searching or matching had to explicitly save and restore the match data.
-Now Emacs does this automatically; filter functions never need to do it
-explicitly. *Note Match Data::.
-
- A filter function that writes the output into the buffer of the
-process should check whether the buffer is still alive. If it tries to
-insert into a dead buffer, it will get an error. If the buffer is dead,
-`(buffer-name (process-buffer PROCESS))' returns `nil'.
-
- The output to the function may come in chunks of any size. A program
-that produces the same output twice in a row may send it as one batch
-of 200 characters one time, and five batches of 40 characters the next.
-
- - Function: set-process-filter process filter
- This function gives PROCESS the filter function FILTER. If FILTER
- is `nil', then the process will have no filter. If FILTER is `t',
- then no output from the process will be accepted until the filter
- is changed. (Output received during this time is not discarded,
- but is queued, and will be processed as soon as the filter is
- changed.)
-
- - Function: process-filter process
- This function returns the filter function of PROCESS, or `nil' if
- it has none. `t' means that output processing has been stopped.
-
- Here is an example of use of a filter function:
-
- (defun keep-output (process output)
- (setq kept (cons output kept)))
- => keep-output
- (setq kept nil)
- => nil
- (set-process-filter (get-process "shell") 'keep-output)
- => keep-output
- (process-send-string "shell" "ls ~/other\n")
- => nil
- kept
- => ("lewis@slug[8] % "
- "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
- address.txt backup.psf kolstad.psf
- backup.bib~ david.mss resume-Dec-86.mss~
- backup.err david.psf resume-Dec.psf
- backup.mss dland syllabus.mss
- "
- "#backups.mss# backup.mss~ kolstad.mss
- ")
+File: lispref.info, Node: Character Descriptors, Prev: Active Display Table, Up: Display Tables
-\1f
-File: lispref.info, Node: Accepting Output, Prev: Filter Functions, Up: Output from Processes
-
-Accepting Output from Processes
--------------------------------
-
- Output from asynchronous subprocesses normally arrives only while
-XEmacs is waiting for some sort of external event, such as elapsed time
-or terminal input. Occasionally it is useful in a Lisp program to
-explicitly permit output to arrive at a specific point, or even to wait
-until output arrives from a process.
-
- - Function: accept-process-output &optional process seconds millisec
- This function allows XEmacs to read pending output from processes.
- The output is inserted in the associated buffers or given to
- their filter functions. If PROCESS is non-`nil' then this
- function does not return until some output has been received from
- PROCESS.
-
- The arguments SECONDS and MILLISEC let you specify timeout
- periods. The former specifies a period measured in seconds and the
- latter specifies one measured in milliseconds. The two time
- periods thus specified are added together, and
- `accept-process-output' returns after that much time whether or
- not there has been any subprocess output. Note that SECONDS is
- allowed to be a floating-point number; thus, there is no need to
- ever use MILLISEC. (It is retained for compatibility purposes.)
-
- The function `accept-process-output' returns non-`nil' if it did
- get some output, or `nil' if the timeout expired before output
- arrived.
+Character Descriptors
+---------------------
-\1f
-File: lispref.info, Node: Sentinels, Next: Process Window Size, Prev: Output from Processes, Up: Processes
-
-Sentinels: Detecting Process Status Changes
-===========================================
-
- A "process sentinel" is a function that is called whenever the
-associated process changes status for any reason, including signals
-(whether sent by XEmacs or caused by the process's own actions) that
-terminate, stop, or continue the process. The process sentinel is also
-called if the process exits. The sentinel receives two arguments: the
-process for which the event occurred, and a string describing the type
-of event.
-
- The string describing the event looks like one of the following:
-
- * `"finished\n"'.
-
- * `"exited abnormally with code EXITCODE\n"'.
-
- * `"NAME-OF-SIGNAL\n"'.
-
- * `"NAME-OF-SIGNAL (core dumped)\n"'.
-
- A sentinel runs only while XEmacs is waiting (e.g., for terminal
-input, or for time to elapse, or for process output). This avoids the
-timing errors that could result from running them at random places in
-the middle of other Lisp programs. A program can wait, so that
-sentinels will run, by calling `sit-for' or `sleep-for' (*note
-Waiting::), or `accept-process-output' (*note Accepting Output::).
-Emacs is also waiting when the command loop is reading input.
-
- Quitting is normally inhibited within a sentinel--otherwise, the
-effect of typing `C-g' at command level or to quit a user command would
-be unpredictable. If you want to permit quitting inside a sentinel,
-bind `inhibit-quit' to `nil'. *Note Quitting::.
-
- A sentinel that writes the output into the buffer of the process
-should check whether the buffer is still alive. If it tries to insert
-into a dead buffer, it will get an error. If the buffer is dead,
-`(buffer-name (process-buffer PROCESS))' returns `nil'.
-
- If an error happens during execution of a sentinel, it is caught
-automatically, so that it doesn't stop the execution of whatever
-programs was running when the sentinel was started. However, if
-`debug-on-error' is non-`nil', the error-catching is turned off. This
-makes it possible to use the Lisp debugger to debug the sentinel.
-*Note Debugger::.
-
- In earlier Emacs versions, every sentinel that did regexp searching
-or matching had to explicitly save and restore the match data. Now
-Emacs does this automatically; sentinels never need to do it explicitly.
-*Note Match Data::.
-
- - Function: set-process-sentinel process sentinel
- This function associates SENTINEL with PROCESS. If SENTINEL is
- `nil', then the process will have no sentinel. The default
- behavior when there is no sentinel is to insert a message in the
- process's buffer when the process status changes.
-
- (defun msg-me (process event)
- (princ
- (format "Process: %s had the event `%s'" process event)))
- (set-process-sentinel (get-process "shell") 'msg-me)
- => msg-me
- (kill-process (get-process "shell"))
- -| Process: #<process shell> had the event `killed'
- => #<process shell>
+ Each element of the display-table vector describes how to display a
+particular character and is called a "character descriptor". A
+character descriptor can be:
- - Function: process-sentinel process
- This function returns the sentinel of PROCESS, or `nil' if it has
- none.
+a string
+ Display this particular string wherever the character is to be
+ displayed.
- - Function: waiting-for-user-input-p
- While a sentinel or filter function is running, this function
- returns non-`nil' if XEmacs was waiting for keyboard input from
- the user at the time the sentinel or filter function was called,
- `nil' if it was not.
+a glyph
+ Display this particular glyph wherever the character is to be
+ displayed.
-\1f
-File: lispref.info, Node: Process Window Size, Next: Transaction Queues, Prev: Sentinels, Up: Processes
-
-Process Window Size
-===================
+a vector
+ The vector may contain strings and/or glyphs. Display the
+ elements of the vector one after another wherever the character is
+ to be displayed.
- - Function: set-process-window-size process height width
- This function tells PROCESS that its logical window size is HEIGHT
- by WIDTH characters. This is principally useful with pty's.
+`nil'
+ Display according to the standard interpretation (*note Usual
+ Display::).
\1f
-File: lispref.info, Node: Transaction Queues, Next: Network, Prev: Process Window Size, Up: Processes
+File: lispref.info, Node: Beeping, Prev: Display Tables, Up: Display
-Transaction Queues
-==================
+Beeping
+=======
- You can use a "transaction queue" for more convenient communication
-with subprocesses using transactions. First use `tq-create' to create
-a transaction queue communicating with a specified process. Then you
-can call `tq-enqueue' to send a transaction.
+ You can make XEmacs ring a bell, play a sound, or blink the screen to
+attract the user's attention. Be conservative about how often you do
+this; frequent bells can become irritating. Also be careful not to use
+beeping alone when signaling an error is appropriate. (*Note Errors::.)
- - Function: tq-create process
- This function creates and returns a transaction queue
- communicating with PROCESS. The argument PROCESS should be a
- subprocess capable of sending and receiving streams of bytes. It
- may be a child process, or it may be a TCP connection to a server,
- possibly on another machine.
+ - Function: ding &optional dont-terminate sound device
+ This function beeps, or flashes the screen (see `visible-bell'
+ below). It also terminates any keyboard macro currently executing
+ unless DONT-TERMINATE is non-`nil'. If SOUND is specified, it
+ should be a symbol specifying which sound to make. This sound
+ will be played if `visible-bell' is `nil'. (This only works if
+ sound support was compiled into the executable and you are running
+ on the console of a Sun SparcStation, SGI, HP9000s700, or Linux
+ PC. Otherwise you just get a beep.) The optional third argument
+ specifies what device to make the sound on, and defaults to the
+ selected device.
- - Function: tq-enqueue queue question regexp closure fn
- This function sends a transaction to queue QUEUE. Specifying the
- queue has the effect of specifying the subprocess to talk to.
+ - Function: beep &optional dont-terminate sound device
+ This is a synonym for `ding'.
- The argument QUESTION is the outgoing message that starts the
- transaction. The argument FN is the function to call when the
- corresponding answer comes back; it is called with two arguments:
- CLOSURE, and the answer received.
+ - User Option: visible-bell
+ This variable determines whether XEmacs should flash the screen to
+ represent a bell. Non-`nil' means yes, `nil' means no. On TTY
+ devices, this is effective only if the Termcap entry for the
+ terminal type has the visible bell flag (`vb') set.
- The argument REGEXP is a regular expression that should match the
- entire answer, but nothing less; that's how `tq-enqueue' determines
- where the answer ends.
+ - Variable: sound-alist
+ This variable holds an alist associating names with sounds. When
+ `beep' or `ding' is called with one of the name symbols, the
+ associated sound will be generated instead of the standard beep.
- The return value of `tq-enqueue' itself is not meaningful.
+ Each element of `sound-alist' is a list describing a sound. The
+ first element of the list is the name of the sound being defined.
+ Subsequent elements of the list are alternating keyword/value
+ pairs:
- - Function: tq-close queue
- Shut down transaction queue QUEUE, waiting for all pending
- transactions to complete, and then terminate the connection or
- child process.
+ `sound'
+ A string of raw sound data, or the name of another sound to
+ play. The symbol `t' here means use the default X beep.
- Transaction queues are implemented by means of a filter function.
-*Note Filter Functions::.
+ `volume'
+ An integer from 0-100, defaulting to `bell-volume'.
-\1f
-File: lispref.info, Node: Network, Prev: Transaction Queues, Up: Processes
+ `pitch'
+ If using the default X beep, the pitch (Hz) to generate.
-Network Connections
-===================
+ `duration'
+ If using the default X beep, the duration (milliseconds).
- XEmacs Lisp programs can open TCP network connections to other
-processes on the same machine or other machines. A network connection
-is handled by Lisp much like a subprocess, and is represented by a
-process object. However, the process you are communicating with is not
-a child of the XEmacs process, so you can't kill it or send it signals.
-All you can do is send and receive data. `delete-process' closes the
-connection, but does not kill the process at the other end; that
-process must decide what to do about closure of the connection.
-
- You can distinguish process objects representing network connections
-from those representing subprocesses with the `process-status'
-function. It always returns either `open' or `closed' for a network
-connection, and it never returns either of those values for a real
-subprocess. *Note Process Information::.
-
- - Function: open-network-stream name buffer-or-name host service
- This function opens a TCP connection for a service to a host. It
- returns a process object to represent the connection.
-
- The NAME argument specifies the name for the process object. It
- is modified as necessary to make it unique.
-
- The BUFFER-OR-NAME argument is the buffer to associate with the
- connection. Output from the connection is inserted in the buffer,
- unless you specify a filter function to handle the output. If
- BUFFER-OR-NAME is `nil', it means that the connection is not
- associated with any buffer.
-
- The arguments HOST and SERVICE specify where to connect to; HOST
- is the host name or IP address (a string), and SERVICE is the name
- of a defined network service (a string) or a port number (an
- integer).
+ For compatibility, elements of `sound-alist' may also be:
-\1f
-File: lispref.info, Node: System Interface, Next: X-Windows, Prev: Processes, Up: Top
+ * `( sound-name . <sound> )'
-Operating System Interface
-**************************
+ * `( sound-name <volume> <sound> )'
- This chapter is about starting and getting out of Emacs, access to
-values in the operating system environment, and terminal input, output,
-and flow control.
+ You should probably add things to this list by calling the function
+ `load-sound-file'.
- *Note Building XEmacs::, for related information. See also *Note
-Display::, for additional operating system status information
-pertaining to the terminal and the screen.
+ Caveats:
-* Menu:
+ - You can only play audio data if running on the console screen
+ of a Sun SparcStation, SGI, or HP9000s700.
-* Starting Up:: Customizing XEmacs start-up processing.
-* Getting Out:: How exiting works (permanent or temporary).
-* 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.
-* Flow Control:: How to turn output flow control on or off.
-* Batch Mode:: Running XEmacs without terminal interaction.
+ - The pitch, duration, and volume options are available
+ everywhere, but many X servers ignore the `pitch' option.
-\1f
-File: lispref.info, Node: Starting Up, Next: Getting Out, Up: System Interface
+ The following beep-types are used by XEmacs itself:
-Starting Up XEmacs
-==================
+ `auto-save-error'
+ when an auto-save does not succeed
- This section describes what XEmacs does when it is started, and how
-you can customize these actions.
+ `command-error'
+ when the XEmacs command loop catches an error
-* Menu:
+ `undefined-key'
+ when you type a key that is undefined
-* Start-up Summary:: Sequence of actions XEmacs performs at start-up.
-* Init File:: Details on reading the init file (`.emacs').
-* Terminal-Specific:: How the terminal-specific Lisp file is read.
-* Command Line Arguments:: How command line arguments are processed,
- and how you can customize them.
+ `undefined-click'
+ when you use an undefined mouse-click combination
-\1f
-File: lispref.info, Node: Start-up Summary, Next: Init File, Up: Starting Up
+ `no-completion'
+ during completing-read
-Summary: Sequence of Actions at Start Up
-----------------------------------------
+ `y-or-n-p'
+ when you type something other than 'y' or 'n'
- The order of operations performed (in `startup.el') by XEmacs when
-it is started up is as follows:
+ `yes-or-no-p'
+ when you type something other than 'yes' or 'no'
- 1. It loads the initialization library for the window system, if you
- are using a window system. This library's name is
- `term/WINDOWSYSTEM-win.el'.
+ `default'
+ used when nothing else is appropriate.
- 2. It processes the initial options. (Some of them are handled even
- earlier than this.)
+ Other lisp packages may use other beep types, but these are the
+ ones that the C kernel of XEmacs uses.
- 3. It initializes the X window frame and faces, if appropriate.
+ - User Option: bell-volume
+ This variable specifies the default volume for sounds, from 0 to
+ 100.
- 4. It runs the normal hook `before-init-hook'.
+ - Command: load-default-sounds
+ This function loads and installs some sound files as beep-types.
- 5. It loads the library `site-start', unless the option
- `-no-site-file' was specified. The library's file name is usually
- `site-start.el'.
+ - Command: load-sound-file filename sound-name &optional volume
+ This function reads in an audio file and adds it to `sound-alist'.
+ The sound file must be in the Sun/NeXT U-LAW format. SOUND-NAME
+ should be a symbol, specifying the name of the sound. If VOLUME
+ is specified, the sound will be played at that volume; otherwise,
+ the value of BELL-VOLUME will be used.
- 6. It loads the file `~/.emacs' unless `-q' was specified on the
- command line. (This is not done in `-batch' mode.) The `-u'
- option can specify the user name whose home directory should be
- used instead of `~'.
+ - Function: play-sound sound &optional volume device
+ This function plays sound SOUND, which should be a symbol
+ mentioned in `sound-alist'. If VOLUME is specified, it overrides
+ the value (if any) specified in `sound-alist'. DEVICE specifies
+ the device to play the sound on, and defaults to the selected
+ device.
- 7. It loads the library `default' unless `inhibit-default-init' is
- non-`nil'. (This is not done in `-batch' mode or if `-q' was
- specified on the command line.) The library's file name is
- usually `default.el'.
+ - Command: play-sound-file file &optional volume device
+ This function plays the named sound file at volume VOLUME, which
+ defaults to `bell-volume'. DEVICE specifies the device to play
+ the sound on, and defaults to the selected device.
- 8. It runs the normal hook `after-init-hook'.
+\1f
+File: lispref.info, Node: Hash Tables, Next: Range Tables, Prev: Display, Up: Top
- 9. It sets the major mode according to `initial-major-mode', provided
- the buffer `*scratch*' is still current and still in Fundamental
- mode.
+Hash Tables
+***********
- 10. It loads the terminal-specific Lisp file, if any, except when in
- batch mode or using a window system.
+ - Function: hash-table-p object
+ This function returns `t' if OBJECT is a hash table, else `nil'.
- 11. It displays the initial echo area message, unless you have
- suppressed that with `inhibit-startup-echo-area-message'.
+* Menu:
- 12. It processes the action arguments from the command line.
+* Introduction to Hash Tables:: Hash tables are fast data structures for
+ implementing simple tables (i.e. finite
+ mappings from keys to values).
+* Working With Hash Tables:: Hash table functions.
+* Weak Hash Tables:: Hash tables with special garbage-collection
+ behavior.
- 13. It runs `term-setup-hook'.
+\1f
+File: lispref.info, Node: Introduction to Hash Tables, Next: Working With Hash Tables, Up: Hash Tables
+
+Introduction to Hash Tables
+===========================
+
+ A "hash table" is a data structure that provides mappings from
+arbitrary Lisp objects called "keys" to other arbitrary Lisp objects
+called "values". A key/value pair is sometimes called an "entry" in
+the hash table. There are many ways other than hash tables of
+implementing the same sort of mapping, e.g. association lists (*note
+Association Lists::) and property lists (*note Property Lists::), but
+hash tables provide much faster lookup when there are many entries in
+the mapping. Hash tables are an implementation of the abstract data
+type "dictionary", also known as "associative array".
+
+ Internally, hash tables are hashed using the "linear probing" hash
+table implementation method. This method hashes each key to a
+particular spot in the hash table, and then scans forward sequentially
+until a blank entry is found. To look up a key, hash to the appropriate
+spot, then search forward for the key until either a key is found or a
+blank entry stops the search. This method is used in preference to
+double hashing because of changes in recent hardware. The penalty for
+non-sequential access to memory has been increasing, and this
+compensates for the problem of clustering that linear probing entails.
+
+ When hash tables are created, the user may (but is not required to)
+specify initial properties that influence performance.
+
+ Use the `:size' parameter to specify the number of entries that are
+likely to be stored in the hash table, to avoid the overhead of resizing
+the table. But if the pre-allocated space for the entries is never
+used, it is simply wasted and makes XEmacs slower. Excess unused hash
+table entries exact a small continuous performance penalty, since they
+must be scanned at every garbage collection. If the number of entries
+in the hash table is unknown, simply avoid using the `:size' keyword.
+
+ Use the `:rehash-size' and `:rehash-threshold' keywords to adjust
+the algorithm for deciding when to rehash the hash table. For
+temporary hash tables that are going to be very heavily used, use a
+small rehash threshold, for example, 0.4 and a large rehash size, for
+example 2.0. For permanent hash tables that will be infrequently used,
+specify a large rehash threshold, for example 0.8.
+
+ Hash tables can also be created by the lisp reader using structure
+syntax, for example:
+ #s(hash-table size 20 data (foo 1 bar 2))
+
+ The structure syntax accepts the same keywords as `make-hash-table'
+(without the `:' character), as well as the additional keyword `data',
+which specifies the initial hash table contents.
+
+ - Function: make-hash-table &key `test' `size' `rehash-size'
+ `rehash-threshold' `weakness'
+ This function returns a new empty hash table object.
+
+ Keyword `:test' can be `eq', `eql' (default) or `equal'.
+ Comparison between keys is done using this function. If speed is
+ important, consider using `eq'. When storing strings in the hash
+ table, you will likely need to use `equal'.
+
+ Keyword `:size' specifies the number of keys likely to be inserted.
+ This number of entries can be inserted without enlarging the hash
+ table.
+
+ Keyword `:rehash-size' must be a float greater than 1.0, and
+ specifies the factor by which to increase the size of the hash
+ table when enlarging.
+
+ Keyword `:rehash-threshold' must be a float between 0.0 and 1.0,
+ and specifies the load factor of the hash table which triggers
+ enlarging.
+
+ Non-standard keyword `:weakness' can be `nil' (default), `t',
+ `key-and-value', `key', `value' or `key-or-value'. `t' is an
+ alias for `key-and-value'.
+
+ A key-and-value-weak hash table, also known as a fully-weak or
+ simply as a weak hash table, is one whose pointers do not count as
+ GC referents: for any key-value pair in the hash table, if the only
+ remaining pointer to either the key or the value is in a weak hash
+ table, then the pair will be removed from the hash table, and the
+ key and value collected. A non-weak hash table (or any other
+ pointer) would prevent the object from being collected.
+
+ A key-weak hash table is similar to a fully-weak hash table except
+ that a key-value pair will be removed only if the key remains
+ unmarked outside of weak hash tables. The pair will remain in the
+ hash table if the key is pointed to by something other than a weak
+ hash table, even if the value is not.
+
+ A value-weak hash table is similar to a fully-weak hash table
+ except that a key-value pair will be removed only if the value
+ remains unmarked outside of weak hash tables. The pair will
+ remain in the hash table if the value is pointed to by something
+ other than a weak hash table, even if the key is not.
+
+ A key-or-value-weak hash table is similar to a fully-weak hash
+ table except that a key-value pair will be removed only if the
+ value and the key remain unmarked outside of weak hash tables.
+ The pair will remain in the hash table if the value or key are
+ pointed to by something other than a weak hash table, even if the
+ other is not.
+
+ - Function: copy-hash-table hash-table
+ This function returns a new hash table which contains the same
+ keys and values as HASH-TABLE. The keys and values will not
+ themselves be copied.
+
+ - Function: hash-table-count hash-table
+ This function returns the number of entries in HASH-TABLE.
+
+ - Function: hash-table-test hash-table
+ This function returns the test function of HASH-TABLE. This can
+ be one of `eq', `eql' or `equal'.
+
+ - Function: hash-table-size hash-table
+ This function returns the current number of slots in HASH-TABLE,
+ whether occupied or not.
+
+ - Function: hash-table-rehash-size hash-table
+ This function returns the current rehash size of HASH-TABLE. This
+ is a float greater than 1.0; the factor by which HASH-TABLE is
+ enlarged when the rehash threshold is exceeded.
+
+ - Function: hash-table-rehash-threshold hash-table
+ This function returns the current rehash threshold of HASH-TABLE.
+ This is a float between 0.0 and 1.0; the maximum "load factor" of
+ HASH-TABLE, beyond which the HASH-TABLE is enlarged by rehashing.
+
+ - Function: hash-table-weakness hash-table
+ This function returns the weakness of HASH-TABLE. This can be one
+ of `nil', `t', `key' or `value'.
- 14. It calls `frame-notice-user-settings', which modifies the
- parameters of the selected frame according to whatever the init
- files specify.
+\1f
+File: lispref.info, Node: Working With Hash Tables, Next: Weak Hash Tables, Prev: Introduction to Hash Tables, Up: Hash Tables
- 15. It runs `window-setup-hook'. *Note Terminal-Specific::.
+Working With Hash Tables
+========================
- 16. It displays copyleft, nonwarranty, and basic use information,
- provided there were no remaining command line arguments (a few
- steps above) and the value of `inhibit-startup-message' is `nil'.
+ - Function: puthash key value hash-table
+ This function hashes KEY to VALUE in HASH-TABLE.
- - User Option: inhibit-startup-message
- This variable inhibits the initial startup messages (the
- nonwarranty, etc.). If it is non-`nil', then the messages are not
- printed.
+ - Function: gethash key hash-table &optional default
+ This function finds the hash value for KEY in HASH-TABLE. If
+ there is no entry for KEY in HASH-TABLE, DEFAULT is returned
+ (which in turn defaults to `nil').
- This variable exists so you can set it in your personal init file,
- once 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.
+ - Function: remhash key hash-table
+ This function removes the entry for KEY from HASH-TABLE. Does
+ nothing if there is no entry for KEY in HASH-TABLE.
- - User Option: inhibit-startup-echo-area-message
- This variable controls the display of the startup echo area
- message. You can suppress the startup echo area message by adding
- text with this form to your `.emacs' file:
+ - Function: clrhash hash-table
+ This function removes all entries from HASH-TABLE, leaving it
+ empty.
- (setq inhibit-startup-echo-area-message
- "YOUR-LOGIN-NAME")
+ - Function: maphash function hash-table
+ This function maps FUNCTION over entries in HASH-TABLE, calling it
+ with two args, each key and value in the hash table.
- Simply setting `inhibit-startup-echo-area-message' to your login
- name is not sufficient to inhibit the message; Emacs explicitly
- checks whether `.emacs' contains an expression as shown above.
- Your login name must appear in the expression as a Lisp string
- constant.
+ FUNCTION may not modify HASH-TABLE, with the one exception that
+ FUNCTION may remhash or puthash the entry currently being
+ processed by FUNCTION.
- This way, you can easily inhibit the message for yourself if you
- wish, but thoughtless copying of your `.emacs' file will not
- inhibit the message for someone else.
+\1f
+File: lispref.info, Node: Weak Hash Tables, Prev: Working With Hash Tables, Up: Hash Tables
+
+Weak Hash Tables
+================
+
+ A "weak hash table" is a special variety of hash table whose
+elements do not count as GC referents. For any key-value pair in such a
+hash table, if either the key or value (or in some cases, if one
+particular one of the two) has no references to it outside of weak hash
+tables (and similar structures such as weak lists), the pair will be
+removed from the table, and the key and value collected. A non-weak
+hash table (or any other pointer) would prevent the objects from being
+collected.
+
+ Weak hash tables are useful for keeping track of information in a
+non-obtrusive way, for example to implement caching. If the cache
+contains objects such as buffers, markers, image instances, etc. that
+will eventually disappear and get garbage-collected, using a weak hash
+table ensures that these objects are collected normally rather than
+remaining around forever, long past their actual period of use.
+(Otherwise, you'd have to explicitly map over the hash table every so
+often and remove unnecessary elements.)
+
+ There are four types of weak hash tables:
+
+key-and-value-weak hash tables
+ In these hash tables, also known as fully weak or simply as weak
+ hash tables, a pair disappears if either the key or the value is
+ unreferenced outside of the table.
+
+key-weak hash tables
+ In these hash tables, a pair disappears if the key is unreferenced
+ outside of the table, regardless of how the value is referenced.
+
+value-weak hash tables
+ In these hash tables, a pair disappears if the value is
+ unreferenced outside of the table, regardless of how the key is
+ referenced.
+
+key-or-value-weak hash tables
+ In these hash tables, a pair disappears if both the key and the
+ value are unreferenced outside of the table.
+
+ Also see *Note Weak Lists::.
+
+ Weak hash tables are created by specifying the `:weakness' keyword to
+`make-hash-table'.
\1f
-File: lispref.info, Node: Init File, Next: Terminal-Specific, Prev: Start-up Summary, Up: Starting Up
-
-The Init File: `.emacs'
------------------------
-
- When you start XEmacs, it normally attempts to load the file
-`.emacs' from your home directory. This file, if it exists, must
-contain Lisp code. It is called your "init file". The command line
-switches `-q' and `-u' affect the use of the init file; `-q' says not
-to load an init file, and `-u' says to load a specified user's init
-file instead of yours. *Note Entering XEmacs: (xemacs)Entering XEmacs.
-
- A site may have a "default init file", which is the library named
-`default.el'. XEmacs finds the `default.el' file through the standard
-search path for libraries (*note How Programs Do Loading::). The
-XEmacs distribution does not come with this file; sites may provide one
-for local customizations. If the default init file exists, it is
-loaded whenever you start Emacs, except in batch mode or if `-q' is
-specified. But your own personal init file, if any, is loaded first; if
-it sets `inhibit-default-init' to a non-`nil' value, then XEmacs does
-not subsequently load the `default.el' file.
-
- Another file for site-customization is `site-start.el'. Emacs loads
-this _before_ the user's init file. You can inhibit the loading of
-this file with the option `-no-site-file'.
-
- - Variable: site-run-file
- This variable specifies the site-customization file to load before
- the user's init file. Its normal value is `"site-start"'.
-
- If there is a great deal of code in your `.emacs' file, you should
-move it into another file named `SOMETHING.el', byte-compile it (*note
-Byte Compilation::), and make your `.emacs' file load the other file
-using `load' (*note Loading::).
-
- *Note Init File Examples: (xemacs)Init File Examples, for examples
-of how to make various commonly desired customizations in your `.emacs'
-file.
-
- - User Option: inhibit-default-init
- This variable prevents XEmacs from loading the default
- initialization library file for your session of XEmacs. If its
- value is non-`nil', then the default library is not loaded. The
- default value is `nil'.
+File: lispref.info, Node: Range Tables, Next: Databases, Prev: Hash Tables, Up: Top
+
+Range Tables
+************
+
+ A range table is a table that efficiently associated values with
+ranges of integers.
+
+ Note that range tables have a read syntax, like this:
+
+ #s(range-table data ((-3 2) foo (5 20) bar))
- - Variable: before-init-hook
- - Variable: after-init-hook
- These two normal hooks are run just before, and just after,
- loading of the user's init file, `default.el', and/or
- `site-start.el'.
+ This maps integers in the range (-3, 2) to `foo' and integers in the
+range (5, 20) to `bar'.
+
+ - Function: range-table-p object
+ Return non-`nil' if OBJECT is a range table.
+
+* Menu:
+
+* Introduction to Range Tables:: Range tables efficiently map ranges of
+ integers to values.
+* Working With Range Tables:: Range table functions.
\1f
-File: lispref.info, Node: Terminal-Specific, Next: Command Line Arguments, Prev: Init File, Up: Starting Up
-
-Terminal-Specific Initialization
---------------------------------
-
- Each terminal type can have its own Lisp library that XEmacs loads
-when run on that type of terminal. For a terminal type named TERMTYPE,
-the library is called `term/TERMTYPE'. XEmacs finds the file by
-searching the `load-path' directories as it does for other files, and
-trying the `.elc' and `.el' suffixes. Normally, terminal-specific Lisp
-library is located in `emacs/lisp/term', a subdirectory of the
-`emacs/lisp' directory in which most XEmacs Lisp libraries are kept.
-
- The library's name is constructed by concatenating the value of the
-variable `term-file-prefix' and the terminal type. Normally,
-`term-file-prefix' has the value `"term/"'; changing this is not
-recommended.
-
- The usual function of a terminal-specific library is to enable
-special keys to send sequences that XEmacs can recognize. It may also
-need to set or add to `function-key-map' if the Termcap entry does not
-specify all the terminal's function keys. *Note Terminal Input::.
-
- When the name of the terminal type contains a hyphen, only the part
-of the name before the first hyphen is significant in choosing the
-library name. Thus, terminal types `aaa-48' and `aaa-30-rv' both use
-the `term/aaa' library. If necessary, the library can evaluate
-`(getenv "TERM")' to find the full name of the terminal type.
-
- Your `.emacs' file can prevent the loading of the terminal-specific
-library by setting the variable `term-file-prefix' to `nil'. This
-feature is useful when experimenting with your own peculiar
-customizations.
-
- You can also arrange to override some of the actions of the
-terminal-specific library by setting the variable `term-setup-hook'.
-This is a normal hook which XEmacs runs using `run-hooks' at the end of
-XEmacs initialization, after loading both your `.emacs' file and any
-terminal-specific libraries. You can use this variable to define
-initializations for terminals that do not have their own libraries.
-*Note Hooks::.
-
- - Variable: term-file-prefix
- If the `term-file-prefix' variable is non-`nil', XEmacs loads a
- terminal-specific initialization file as follows:
-
- (load (concat term-file-prefix (getenv "TERM")))
-
- You may set the `term-file-prefix' variable to `nil' in your
- `.emacs' file if you do not wish to load the
- terminal-initialization file. To do this, put the following in
- your `.emacs' file: `(setq term-file-prefix nil)'.
-
- - Variable: term-setup-hook
- This variable is a normal hook that XEmacs runs after loading your
- `.emacs' file, the default initialization file (if any) and the
- terminal-specific Lisp file.
-
- You can use `term-setup-hook' to override the definitions made by a
- terminal-specific file.
-
- - Variable: window-setup-hook
- This variable is a normal hook which XEmacs runs after loading your
- `.emacs' file and the default initialization file (if any), after
- loading terminal-specific Lisp code, and after running the hook
- `term-setup-hook'.
+File: lispref.info, Node: Introduction to Range Tables, Next: Working With Range Tables, Up: Range Tables
+
+Introduction to Range Tables
+============================
+
+ - Function: make-range-table
+ Make a new, empty range table.
+
+ - Function: copy-range-table range-table
+ This function returns a new range table which contains the same
+ values for the same ranges as RANGE-TABLE. The values will not
+ themselves be copied.
\1f
-File: lispref.info, Node: Command Line Arguments, Prev: Terminal-Specific, Up: Starting Up
+File: lispref.info, Node: Working With Range Tables, Prev: Introduction to Range Tables, Up: Range Tables
-Command Line Arguments
-----------------------
+Working With Range Tables
+=========================
- You can use command line arguments to request various actions when
-you start XEmacs. Since you do not need to start XEmacs more than once
-per day, and will often leave your XEmacs session running longer than
-that, command line arguments are hardly ever used. As a practical
-matter, it is best to avoid making the habit of using them, since this
-habit would encourage you to kill and restart XEmacs unnecessarily
-often. These options exist for two reasons: to be compatible with
-other editors (for invocation by other programs) and to enable shell
-scripts to run specific Lisp programs.
+ - Function: get-range-table pos range-table &optional default
+ This function finds value for position POS in RANGE-TABLE. If
+ there is no corresponding value, return DEFAULT (defaults to
+ `nil').
- This section describes how Emacs processes command line arguments,
-and how you can customize them.
+ - Function: put-range-table start end value range-table
+ This function sets the value for range (START, END) to be VALUE in
+ RANGE-TABLE.
- - Function: command-line
- This function parses the command line that XEmacs was called with,
- processes it, loads the user's `.emacs' file and displays the
- startup messages.
+ - Function: remove-range-table start end range-table
+ This function removes the value for range (START, END) in
+ RANGE-TABLE.
- - Variable: command-line-processed
- The value of this variable is `t' once the command line has been
- processed.
+ - Function: clear-range-table range-table
+ This function flushes RANGE-TABLE.
- If you redump XEmacs by calling `dump-emacs', you may wish to set
- this variable to `nil' first in order to cause the new dumped
- XEmacs to process its new command line arguments.
+ - Function: map-range-table function range-table
+ This function maps FUNCTION over entries in RANGE-TABLE, calling
+ it with three args, the beginning and end of the range and the
+ corresponding value.
- - Variable: command-switch-alist
- The value of this variable is an alist of user-defined command-line
- options and associated handler functions. This variable exists so
- you can add elements to it.
+\1f
+File: lispref.info, Node: Databases, Next: Processes, Prev: Range Tables, Up: Top
- A "command line option" is an argument on the command line of the
- form:
+Databases
+*********
- -OPTION
+ - Function: databasep object
+ This function returns non-`nil' if OBJECT is a database.
- The elements of the `command-switch-alist' look like this:
+* Menu:
- (OPTION . HANDLER-FUNCTION)
+* Connecting to a Database::
+* Working With a Database::
+* Other Database Functions::
- The HANDLER-FUNCTION is called to handle OPTION and receives the
- option name as its sole argument.
+\1f
+File: lispref.info, Node: Connecting to a Database, Next: Working With a Database, Up: Databases
- In some cases, the option is followed in the command line by an
- argument. In these cases, the HANDLER-FUNCTION can find all the
- remaining command-line arguments in the variable
- `command-line-args-left'. (The entire list of command-line
- arguments is in `command-line-args'.)
+Connecting to a Database
+========================
- The command line arguments are parsed by the `command-line-1'
- function in the `startup.el' file. See also *Note Command Line
- Switches and Arguments: (xemacs)Command Switches.
+ - Function: open-database file &optional type subtype access mode
+ This function opens database FILE, using database method TYPE and
+ SUBTYPE, with access rights ACCESS and permissions MODE. ACCESS
+ can be any combination of `r' `w' and `+', for read, write, and
+ creation flags.
- - Variable: command-line-args
- The value of this variable is the list of command line arguments
- passed to XEmacs.
+ TYPE can have the value `'dbm' or `'berkeley-db' to select the
+ type of database file to use. (Note: XEmacs may not support both
+ of these types.)
- - Variable: command-line-functions
- This variable's value is a list of functions for handling an
- unrecognized command-line argument. Each time the next argument
- to be processed has no special meaning, the functions in this list
- are called, in order of appearance, until one of them returns a
- non-`nil' value.
+ For a TYPE of `'dbm', there are no subtypes, so SUBTYPE should be
+ `nil'.
- These functions are called with no arguments. They can access the
- command-line argument under consideration through the variable
- `argi'. The remaining arguments (not including the current one)
- are in the variable `command-line-args-left'.
+ For a TYPE of `'berkeley-db', the following subtypes are
+ available: `'hash', `'btree', and `'recno'. See the manpages for
+ the Berkeley DB functions for more information about these types.
- When a function recognizes and processes the argument in `argi', it
- should return a non-`nil' value to say it has dealt with that
- argument. If it has also dealt with some of the following
- arguments, it can indicate that by deleting them from
- `command-line-args-left'.
+ - Function: close-database database
+ This function closes database DATABASE.
- If all of these functions return `nil', then the argument is used
- as a file name to visit.
+ - Function: database-live-p object
+ This function returns `t' if OBJECT is an active database, else
+ `nil'.
\1f
-File: lispref.info, Node: Getting Out, Next: System Environment, Prev: Starting Up, Up: System Interface
+File: lispref.info, Node: Working With a Database, Next: Other Database Functions, Prev: Connecting to a Database, Up: Databases
-Getting out of XEmacs
-=====================
+Working With a Database
+=======================
- There are two ways to get out of XEmacs: you can kill the XEmacs job,
-which exits permanently, or you can suspend it, which permits you to
-reenter the XEmacs process later. As a practical matter, you seldom
-kill XEmacs--only when you are about to log out. Suspending is much
-more common.
+ - Function: get-database key database &optional default
+ This function finds the value for KEY in DATABASE. If there is no
+ corresponding value, DEFAULT is returned (`nil' if DEFAULT is
+ omitted).
-* Menu:
+ - Function: map-database function database
+ This function maps FUNCTION over entries in DATABASE, calling it
+ with two args, each key and value in the database.
-* Killing XEmacs:: Exiting XEmacs irreversibly.
-* Suspending XEmacs:: Exiting XEmacs reversibly.
+ - Function: put-database key value database &optional replace
+ This function stores KEY and VALUE in DATABASE. If optional
+ fourth arg REPLACE is non-`nil', replace any existing entry in the
+ database.
+
+ - Function: remove-database key database
+ This function removes KEY from DATABASE.
\1f
-File: lispref.info, Node: Killing XEmacs, Next: Suspending XEmacs, Up: Getting Out
+File: lispref.info, Node: Other Database Functions, Prev: Working With a Database, Up: Databases
-Killing XEmacs
---------------
+Other Database Functions
+========================
- Killing XEmacs means ending the execution of the XEmacs process. The
-parent process normally resumes control. The low-level primitive for
-killing XEmacs is `kill-emacs'.
+ - Function: database-file-name database
+ This function returns the filename associated with DATABASE.
- - Function: kill-emacs &optional exit-data
- This function exits the XEmacs process and kills it.
+ - Function: database-last-error &optional database
+ This function returns the last error associated with DATABASE.
- If EXIT-DATA is an integer, then it is used as the exit status of
- the XEmacs process. (This is useful primarily in batch operation;
- see *Note Batch Mode::.)
+ - Function: database-subtype database
+ This function returns the subtype of DATABASE, if any.
- If EXIT-DATA is a string, its contents are stuffed into the
- terminal input buffer so that the shell (or whatever program next
- reads input) can read them.
+ - Function: database-type database
+ This function returns the type of DATABASE.
- All the information in the XEmacs process, aside from files that have
-been saved, is lost when the XEmacs is killed. Because killing XEmacs
-inadvertently can lose a lot of work, XEmacs queries for confirmation
-before actually terminating if you have buffers that need saving or
-subprocesses that are running. This is done in the function
-`save-buffers-kill-emacs'.
+\1f
+File: lispref.info, Node: Processes, Next: System Interface, Prev: Databases, Up: Top
+
+Processes
+*********
+
+ In the terminology of operating systems, a "process" is a space in
+which a program can execute. XEmacs runs in a process. XEmacs Lisp
+programs can invoke other programs in processes of their own. These are
+called "subprocesses" or "child processes" of the XEmacs process, which
+is their "parent process".
+
+ A subprocess of XEmacs may be "synchronous" or "asynchronous",
+depending on how it is created. When you create a synchronous
+subprocess, the Lisp program waits for the subprocess to terminate
+before continuing execution. When you create an asynchronous
+subprocess, it can run in parallel with the Lisp program. This kind of
+subprocess is represented within XEmacs by a Lisp object which is also
+called a "process". Lisp programs can use this object to communicate
+with the subprocess or to control it. For example, you can send
+signals, obtain status information, receive output from the process, or
+send input to it.
+
+ - Function: processp object
+ This function returns `t' if OBJECT is a process, `nil' otherwise.
- - Variable: kill-emacs-query-functions
- After asking the standard questions, `save-buffers-kill-emacs'
- calls the functions in the list `kill-buffer-query-functions', in
- order of appearance, with no arguments. These functions can ask
- for additional confirmation from the user. If any of them returns
- non-`nil', XEmacs is not killed.
+* Menu:
+
+* Subprocess Creation:: Functions that start subprocesses.
+* Synchronous Processes:: Details of using synchronous subprocesses.
+* MS-DOS Subprocesses:: On MS-DOS, you must indicate text vs binary
+ for data sent to and from a subprocess.
+* Asynchronous Processes:: Starting up an asynchronous subprocess.
+* Deleting Processes:: Eliminating an asynchronous subprocess.
+* Process Information:: Accessing run-status and other attributes.
+* Input to Processes:: Sending input to an asynchronous subprocess.
+* Signals to Processes:: Stopping, continuing or interrupting
+ an asynchronous subprocess.
+* Output from Processes:: Collecting output from an asynchronous subprocess.
+* Sentinels:: Sentinels run when process run-status changes.
+* Process Window Size:: Changing the logical window size of a process.
+* Transaction Queues:: Transaction-based communication with subprocesses.
+* Network:: Opening network connections.
- - Variable: kill-emacs-hook
- This variable is a normal hook; once `save-buffers-kill-emacs' is
- finished with all file saving and confirmation, it runs the
- functions in this hook.
+\1f
+File: lispref.info, Node: Subprocess Creation, Next: Synchronous Processes, Up: Processes
+
+Functions that Create Subprocesses
+==================================
+
+ There are three functions that create a new subprocess in which to
+run a program. One of them, `start-process', creates an asynchronous
+process and returns a process object (*note Asynchronous Processes::).
+The other two, `call-process' and `call-process-region', create a
+synchronous process and do not return a process object (*note
+Synchronous Processes::).
+
+ Synchronous and asynchronous processes are explained in the following
+sections. Since the three functions are all called in a similar
+fashion, their common arguments are described here.
+
+ In all cases, the function's PROGRAM argument specifies the program
+to be run. An error is signaled if the file is not found or cannot be
+executed. If the file name is relative, the variable `exec-path'
+contains a list of directories to search. Emacs initializes
+`exec-path' when it starts up, based on the value of the environment
+variable `PATH'. The standard file name constructs, `~', `.', and
+`..', are interpreted as usual in `exec-path', but environment variable
+substitutions (`$HOME', etc.) are not recognized; use
+`substitute-in-file-name' to perform them (*note File Name Expansion::).
+
+ Each of the subprocess-creating functions has a BUFFER-OR-NAME
+argument which specifies where the standard output from the program will
+go. If BUFFER-OR-NAME is `nil', that says to discard the output unless
+a filter function handles it. (*Note Filter Functions::, and *Note
+Read and Print::.) Normally, you should avoid having multiple
+processes send output to the same buffer because their output would be
+intermixed randomly.
+
+ All three of the subprocess-creating functions have a `&rest'
+argument, ARGS. The ARGS must all be strings, and they are supplied to
+PROGRAM as separate command line arguments. Wildcard characters and
+other shell constructs are not allowed in these strings, since they are
+passed directly to the specified program.
+
+ *Please note:* The argument PROGRAM contains only the name of the
+program; it may not contain any command-line arguments. You must use
+ARGS to provide those.
+
+ If you want to use features of the shell, then invoke the shell
+directly using, for example, PROGRAM of `"sh"', and ARGS of `"-c"' and
+"COMMAND LINE...".
+
+ The subprocess gets its current directory from the value of
+`default-directory' (*note File Name Expansion::).
+
+ The subprocess inherits its environment from XEmacs; but you can
+specify overrides for it with `process-environment'. *Note System
+Environment::.
+
+ - Variable: exec-directory
+ The value of this variable is the name of a directory (a string)
+ that contains programs that come with XEmacs, that are intended
+ for XEmacs to invoke. The program `wakeup' is an example of such
+ a program; the `display-time' command uses it to get a reminder
+ once per minute.
+
+ - User Option: exec-path
+ The value of this variable is a list of directories to search for
+ programs to run in subprocesses. Each element is either the name
+ of a directory (i.e., a string), or `nil', which stands for the
+ default directory (which is the value of `default-directory').
+
+ The value of `exec-path' is used by `call-process' and
+ `start-process' when the PROGRAM argument is not an absolute file
+ name.
\1f
-File: lispref.info, Node: Suspending XEmacs, Prev: Killing XEmacs, Up: Getting Out
-
-Suspending XEmacs
------------------
-
- "Suspending XEmacs" means stopping XEmacs temporarily and returning
-control to its superior process, which is usually the shell. This
-allows you to resume editing later in the same XEmacs process, with the
-same buffers, the same kill ring, the same undo history, and so on. To
-resume XEmacs, use the appropriate command in the parent shell--most
-likely `fg'.
-
- Some operating systems do not support suspension of jobs; on these
-systems, "suspension" actually creates a new shell temporarily as a
-subprocess of XEmacs. Then you would exit the shell to return to
-XEmacs.
-
- Suspension is not useful with window systems such as X, because the
-XEmacs job 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 XEmacs is an X client.
-
- - Function: suspend-emacs string
- This function stops XEmacs and returns control to the superior
- process. If and when the superior process resumes XEmacs,
- `suspend-emacs' returns `nil' to its caller in Lisp.
-
- If STRING is non-`nil', its characters are sent to be read as
- terminal input by XEmacs's superior shell. The characters in
- STRING are not echoed by the superior shell; only the results
- appear.
-
- Before suspending, `suspend-emacs' runs the normal hook
- `suspend-hook'. In Emacs version 18, `suspend-hook' was not a
- normal hook; its value was a single function, and if its value was
- non-`nil', then `suspend-emacs' returned immediately without
- actually suspending anything.
-
- After the user resumes XEmacs, `suspend-emacs' runs the normal hook
- `suspend-resume-hook'. *Note Hooks::.
-
- The next redisplay after resumption will redraw the entire screen,
- unless the variable `no-redraw-on-reenter' is non-`nil' (*note
- Refresh Screen::).
-
- In the following example, note that `pwd' is not echoed after
- XEmacs is suspended. But it is read and executed by the shell.
-
- (suspend-emacs)
+File: lispref.info, Node: Synchronous Processes, Next: MS-DOS Subprocesses, Prev: Subprocess Creation, Up: Processes
+
+Creating a Synchronous Process
+==============================
+
+ After a "synchronous process" is created, XEmacs waits for the
+process to terminate before continuing. Starting Dired is an example of
+this: it runs `ls' in a synchronous process, then modifies the output
+slightly. Because the process is synchronous, the entire directory
+listing arrives in the buffer before XEmacs tries to do anything with
+it.
+
+ While Emacs waits for the synchronous subprocess to terminate, the
+user can quit by typing `C-g'. The first `C-g' tries to kill the
+subprocess with a `SIGINT' signal; but it waits until the subprocess
+actually terminates before quitting. If during that time the user
+types another `C-g', that kills the subprocess instantly with `SIGKILL'
+and quits immediately. *Note Quitting::.
+
+ The synchronous subprocess functions returned `nil' in version 18.
+In version 19, they return an indication of how the process terminated.
+
+ - Function: call-process program &optional infile destination display
+ &rest args
+ This function calls PROGRAM in a separate process and waits for it
+ to finish.
+
+ The standard input for the process comes from file INFILE if
+ INFILE is not `nil' and from `/dev/null' otherwise. The argument
+ DESTINATION says where to put the process output. Here are the
+ possibilities:
+
+ a buffer
+ Insert the output in that buffer, before point. This
+ includes both the standard output stream and the standard
+ error stream of the process.
+
+ a string
+ Find or create a buffer with that name, then insert the
+ output in that buffer, before point.
+
+ `t'
+ Insert the output in the current buffer, before point.
+
+ `nil'
+ Discard the output.
+
+ 0
+ Discard the output, and return immediately without waiting
+ for the subprocess to finish.
+
+ In this case, the process is not truly synchronous, since it
+ can run in parallel with Emacs; but you can think of it as
+ synchronous in that Emacs is essentially finished with the
+ subprocess as soon as this function returns.
+
+ (REAL-DESTINATION ERROR-DESTINATION)
+ Keep the standard output stream separate from the standard
+ error stream; deal with the ordinary output as specified by
+ REAL-DESTINATION, and dispose of the error output according
+ to ERROR-DESTINATION. The value `nil' means discard it, `t'
+ means mix it with the ordinary output, and a string specifies
+ a file name to redirect error output into.
+
+ You can't directly specify a buffer to put the error output
+ in; that is too difficult to implement. But you can achieve
+ this result by sending the error output to a temporary file
+ and then inserting the file into a buffer.
+
+ If DISPLAY is non-`nil', then `call-process' redisplays the buffer
+ as output is inserted. Otherwise the function does no redisplay,
+ and the results become visible on the screen only when XEmacs
+ redisplays that buffer in the normal course of events.
+
+ The remaining arguments, ARGS, are strings that specify command
+ line arguments for the program.
+
+ The value returned by `call-process' (unless you told it not to
+ wait) indicates the reason for process termination. A number
+ gives the exit status of the subprocess; 0 means success, and any
+ other value means failure. If the process terminated with a
+ signal, `call-process' returns a string describing the signal.
+
+ In the examples below, the buffer `foo' is current.
+
+ (call-process "pwd" nil t)
=> nil
- (add-hook 'suspend-hook
- (function (lambda ()
- (or (y-or-n-p
- "Really suspend? ")
- (error "Suspend cancelled")))))
- => (lambda nil
- (or (y-or-n-p "Really suspend? ")
- (error "Suspend cancelled")))
- (add-hook 'suspend-resume-hook
- (function (lambda () (message "Resumed!"))))
- => (lambda nil (message "Resumed!"))
- (suspend-emacs "pwd")
+ ---------- Buffer: foo ----------
+ /usr/user/lewis/manual
+ ---------- Buffer: foo ----------
+
+ (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
=> nil
- ---------- Buffer: Minibuffer ----------
- Really suspend? y
- ---------- Buffer: Minibuffer ----------
- ---------- Parent Shell ----------
- lewis@slug[23] % /user/lewis/manual
- lewis@slug[24] % fg
+ ---------- Buffer: bar ----------
+ lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
+
+ ---------- Buffer: bar ----------
+
+ The `insert-directory' function contains a good example of the use
+ of `call-process':
+
+ (call-process insert-directory-program nil t nil switches
+ (if full-directory-p
+ (concat (file-name-as-directory file) ".")
+ file))
+
+ - Function: call-process-region start end program &optional deletep
+ destination displayp &rest args
+ This function sends the text between START to END as standard
+ input to a process running PROGRAM. It deletes the text sent if
+ DELETEP is non-`nil'; this is useful when BUFFER is `t', to insert
+ the output in the current buffer.
+
+ The arguments DESTINATION and DISPLAYP control what to do with the
+ output from the subprocess, and whether to update the display as
+ it comes in. For details, see the description of `call-process',
+ above. If DESTINATION is the integer 0, `call-process-region'
+ discards the output and returns `nil' immediately, without waiting
+ for the subprocess to finish.
+
+ The remaining arguments, ARGS, are strings that specify command
+ line arguments for the program.
+
+ The return value of `call-process-region' is just like that of
+ `call-process': `nil' if you told it to return without waiting;
+ otherwise, a number or string which indicates how the subprocess
+ terminated.
+
+ In the following example, we use `call-process-region' to run the
+ `cat' utility, with standard input being the first five characters
+ in buffer `foo' (the word `input'). `cat' copies its standard
+ input into its standard output. Since the argument DESTINATION is
+ `t', this output is inserted in the current buffer.
+
+ ---------- Buffer: foo ----------
+ input-!-
+ ---------- Buffer: foo ----------
- ---------- Echo Area ----------
- Resumed!
+ (call-process-region 1 6 "cat" nil t)
+ => nil
+
+ ---------- Buffer: foo ----------
+ inputinput-!-
+ ---------- Buffer: foo ----------
- - Variable: suspend-hook
- This variable is a normal hook run before suspending.
+ The `shell-command-on-region' command uses `call-process-region'
+ like this:
- - Variable: suspend-resume-hook
- This variable is a normal hook run after suspending.
+ (call-process-region
+ start end
+ shell-file-name ; Name of program.
+ nil ; Do not delete region.
+ buffer ; Send output to `buffer'.
+ nil ; No redisplay during output.
+ "-c" command) ; Arguments for the shell.
\1f
-File: lispref.info, Node: System Environment, Next: User Identification, Prev: Getting Out, Up: System Interface
+File: lispref.info, Node: MS-DOS Subprocesses, Next: Asynchronous Processes, Prev: Synchronous Processes, Up: Processes
-Operating System Environment
-============================
+MS-DOS Subprocesses
+===================
+
+ On MS-DOS, you must indicate whether the data going to and from a
+synchronous subprocess are text or binary. Text data requires
+translation between the end-of-line convention used within Emacs (a
+single newline character) and the convention used outside Emacs (the
+two-character sequence, CRLF).
+
+ The variable `binary-process-input' applies to input sent to the
+subprocess, and `binary-process-output' applies to output received from
+it. A non-`nil' value means the data is non-text; `nil' means the data
+is text, and calls for conversion.
+
+ - Variable: binary-process-input
+ If this variable is `nil', convert newlines to CRLF sequences in
+ the input to a synchronous subprocess.
- 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: binary-process-output
+ If this variable is `nil', convert CRLF sequences to newlines in
+ the output from a synchronous subprocess.
- - 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:
+ *Note Files and MS-DOS::, for related information.
- `aix-v3'
- AIX.
+\1f
+File: lispref.info, Node: Asynchronous Processes, Next: Deleting Processes, Prev: MS-DOS Subprocesses, Up: Processes
+
+Creating an Asynchronous Process
+================================
+
+ After an "asynchronous process" is created, Emacs and the Lisp
+program both continue running immediately. The process may thereafter
+run in parallel with Emacs, and the two may communicate with each other
+using the functions described in following sections. Here we describe
+how to create an asynchronous process with `start-process'.
+
+ - Function: start-process name buffer-or-name program &rest args
+ This function creates a new asynchronous subprocess and starts the
+ program PROGRAM running in it. It returns a process object that
+ stands for the new subprocess in Lisp. The argument NAME
+ specifies the name for the process object; if a process with this
+ name already exists, then NAME is modified (by adding `<1>', etc.)
+ to be unique. The buffer BUFFER-OR-NAME is the buffer to
+ associate with the process.
+
+ The remaining arguments, ARGS, are strings that specify command
+ line arguments for the program.
+
+ In the example below, the first process is started and runs
+ (rather, sleeps) for 100 seconds. Meanwhile, the second process
+ is started, and given the name `my-process<1>' for the sake of
+ uniqueness. It inserts the directory listing at the end of the
+ buffer `foo', before the first process finishes. Then it
+ finishes, and a message to that effect is inserted in the buffer.
+ Much later, the first process finishes, and another message is
+ inserted in the buffer for it.
+
+ (start-process "my-process" "foo" "sleep" "100")
+ => #<process my-process>
+
+ (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
+ => #<process my-process<1>>
+
+ ---------- Buffer: foo ----------
+ total 2
+ lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs
+ -rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon
+
+ Process my-process<1> finished
+
+ Process my-process finished
+ ---------- Buffer: foo ----------
+
+ - Function: start-process-shell-command name buffer-or-name command
+ &rest command-args
+ This function is like `start-process' except that it uses a shell
+ to execute the specified command. The argument COMMAND is a shell
+ command name, and COMMAND-ARGS are the arguments for the shell
+ command.
+
+ - Variable: process-connection-type
+ This variable controls the type of device used to communicate with
+ asynchronous subprocesses. If it is non-`nil', then PTYs are
+ used, when available. Otherwise, pipes are used.
+
+ PTYs are usually preferable for processes visible to the user, as
+ in Shell mode, because they allow job control (`C-c', `C-z', etc.)
+ to work between the process and its children whereas pipes do not.
+ For subprocesses used for internal purposes by programs, it is
+ often better to use a pipe, because they are more efficient. In
+ addition, the total number of PTYs is limited on many systems and
+ it is good not to waste them. A rule of thumb is to use ptys for
+ processes the user interacts with directly, and pipes for
+ processes that are hidden from the user.
+
+ The value `process-connection-type' is used when `start-process'
+ is called. So you can specify how to communicate with one
+ subprocess by binding the variable around the call to
+ `start-process'.
+
+ (let ((process-connection-type nil)) ; Use a pipe.
+ (start-process ...))
+
+ To determine whether a given subprocess actually got a pipe or a
+ PTY, use the function `process-tty-name' (*note Process
+ Information::).
+
+ Lisp functions that manipulate processes usually accept a PROCESS
+argument. Besides using an actual process object for this argument, you
+can use a process name, a buffer object, the name of a buffer, or
+`nil'. Specifying a buffer or buffer name for the PROCESS argument
+means use the process associated with the buffer (or the most recent
+one, if there is more than one). `nil' means use the process
+associated with the current buffer. *Note Process Information::.
+*Note Process Buffers::.
- `berkeley-unix'
- Berkeley BSD.
+\1f
+File: lispref.info, Node: Deleting Processes, Next: Process Information, Prev: Asynchronous Processes, Up: Processes
+
+Deleting Processes
+==================
- `dgux'
- Data General DGUX operating system.
+ "Deleting a process" disconnects XEmacs immediately from the
+subprocess, and removes it from the list of active processes. It sends
+a signal to the subprocess to make the subprocess terminate, but this is
+not guaranteed to happen immediately. The process object itself
+continues to exist as long as other Lisp objects point to it.
+
+ You can delete a process explicitly at any time. Processes are
+deleted automatically after they terminate, but not necessarily right
+away. If you delete a terminated process explicitly before it is
+deleted automatically, no harm results.
+
+ - Variable: delete-exited-processes
+ This variable controls automatic deletion of processes that have
+ terminated (due to calling `exit' or to a signal). If it is
+ `nil', then they continue to exist until the user runs
+ `list-processes'. Otherwise, they are deleted immediately after
+ they exit.
+
+ - Function: delete-process name
+ This function deletes the process associated with NAME, killing it
+ with a `SIGHUP' signal. The argument NAME may be a process, the
+ name of a process, a buffer, or the name of a buffer.
+
+ (delete-process "*shell*")
+ => nil
- `gnu'
- A GNU system using the GNU HURD and Mach.
+ - Function: process-kill-without-query process &optional
+ require-query-p
+ This function declares that XEmacs need not query the user if
+ PROCESS is still running when XEmacs is exited. The process will
+ be deleted silently. If REQUIRE-QUERY-P is non-`nil', then XEmacs
+ _will_ query the user (this is the default). The return value is
+ `t' if a query was formerly required, and `nil' otherwise.
- `hpux'
- Hewlett-Packard HPUX operating system.
+ (process-kill-without-query (get-process "shell"))
+ => t
- `irix'
- Silicon Graphics Irix system.
+\1f
+File: lispref.info, Node: Process Information, Next: Input to Processes, Prev: Deleting Processes, Up: Processes
- `linux'
- A GNU system using the Linux kernel.
+Process Information
+===================
- `ms-dos'
- Microsoft MS-DOS "operating system."
+ Several functions return information about processes.
+`list-processes' is provided for interactive use.
- `next-mach'
- NeXT Mach-based system.
+ - Command: list-processes
+ This command displays a listing of all living processes. In
+ addition, it finally deletes any process whose status was `Exited'
+ or `Signaled'. It returns `nil'.
- `rtu'
- Masscomp RTU, UCB universe.
+ - Function: process-list
+ This function returns a list of all processes that have not been
+ deleted.
- `unisoft-unix'
- UniSoft UniPlus.
+ (process-list)
+ => (#<process display-time> #<process shell>)
- `usg-unix-v'
- AT&T System V.
+ - Function: get-process process-name
+ This function returns the process named PROCESS-NAME. If
+ PROCESS-NAME is a string and there is no process with that name,
+ the value is `nil'. If PROCESS-NAME is actually a process, it is
+ returned as given. (That is not very useful, so the argument is
+ usually a name.) For example:
- `vax-vms'
- VAX VMS.
+ (get-process "shell")
+ => #<process shell>
- `windows-nt'
- Microsoft windows NT.
+ - Function: process-command process
+ This function returns the command that was executed to start
+ PROCESS. This is a list of strings, the first string being the
+ program executed and the rest of the strings being the arguments
+ that were given to the program.
- `xenix'
- SCO Xenix 386.
+ (process-command (get-process "shell"))
+ => ("/bin/csh" "-i")
- 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.
+ - Function: process-id process
+ This function returns the PID of PROCESS. This is an integer that
+ distinguishes the process PROCESS from all other processes running
+ on the same computer at the current time. The PID of a process is
+ chosen by the operating system kernel when the process is started
+ and remains constant as long as the process exists.
- - 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: process-name process
+ This function returns the name of PROCESS.
- - Function: system-name
- This function returns the name of the machine you are running on.
- (system-name)
- => "prep.ai.mit.edu"
+ - Function: process-status process
+ This function returns the status of PROCESS as a symbol. The
+ argument PROCESS must be a process, a buffer, a process name
+ (string) or a buffer name (string).
- 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::).
+ The possible values for an actual subprocess are:
- - 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::.)
+ `run'
+ for a process that is running.
- - 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'.
+ `stop'
+ for a process that is stopped but continuable.
- (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.
+ `exit'
+ for a process that has exited.
- - 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
+ `signal'
+ for a process that has received a fatal signal.
- If the 5-minute or 15-minute load averages are not available,
- return a shortened list, containing only those averages which are
- available.
+ `open'
+ for a network connection that is open.
- 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.
+ `closed'
+ for a network connection that is closed. Once a connection
+ is closed, you cannot reopen it, though you might be able to
+ open a new connection to the same place.
- - Function: emacs-pid
- This function returns the process ID of the Emacs process.
+ `nil'
+ if PROCESS does not identify an existing 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.
+ (process-status "shell")
+ => run
+ (process-status (get-buffer "*shell*"))
+ => run
+ x
+ => #<process xx<1>>
+ (process-status x)
+ => exit
- 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.
+ For a network connection, `process-status' returns one of the
+ symbols `open' or `closed'. The latter means that the other side
+ closed the connection, or XEmacs did `delete-process'.
-\1f
-File: lispref.info, Node: User Identification, Next: Time of Day, Prev: System Environment, Up: System Interface
+ In earlier Emacs versions (prior to version 19), the status of a
+ network connection was `run' if open, and `exit' if closed.
-User Identification
-===================
+ - Function: process-kill-without-query-p process
+ This function returns whether PROCESS will be killed without
+ querying the user, if it is running when XEmacs is exited. The
+ default value is `nil'.
- - 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.
+ - Function: process-exit-status process
+ This function returns the exit status of PROCESS or the signal
+ number that killed it. (Use the result of `process-status' to
+ determine which of those it is.) If PROCESS has not yet
+ terminated, the value is 0.
+
+ - Function: process-tty-name process
+ This function returns the terminal name that PROCESS is using for
+ its communication with Emacs--or `nil' if it is using pipes
+ instead of a terminal (see `process-connection-type' in *Note
+ Asynchronous Processes::).