X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-39;h=89f09edb4c55dd9f4e65a91a6c5882572e58861b;hb=c461477e9d1c45206851e095d1398498d09d040c;hp=9a6e07736cae159e6762ee481e5b33b740c668f3;hpb=f52a96980ed9280f8f906a20d4b899dc0b027644;p=chise%2Fxemacs-chise.git diff --git a/info/lispref.info-39 b/info/lispref.info-39 index 9a6e077..89f09ed 100644 --- a/info/lispref.info-39 +++ b/info/lispref.info-39 @@ -1,4 +1,4 @@ -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 @@ -50,1146 +50,1176 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  -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")) - => # - - - 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*") - => # - - 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::.  -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 - -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 +--------------------- - -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: # had the event `killed' - => # + 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. - -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::).  -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'. - -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: - -File: lispref.info, Node: System Interface, Next: X-Windows, Prev: Processes, Up: Top + * `( sound-name . )' -Operating System Interface -************************** + * `( sound-name )' - 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. - -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 - -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'. + +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'. + +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. + +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. + +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'.  -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.  -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.  -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. + +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. + +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'.  -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.  -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'. + +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. + +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.  -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.  -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. + +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") + => # + + (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin") + => #> + + ---------- 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. + +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. + +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) + => (# #) - `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") + => # - `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-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'. - -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::).