X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;ds=sidebyside;f=info%2Flispref.info-39;h=d11996e20111673bdd1a0fae4f4f04518310e368;hb=dbfc38b11cb852dc18107ed3822f6efb13630a8b;hp=9a6e07736cae159e6762ee481e5b33b740c668f3;hpb=f52a96980ed9280f8f906a20d4b899dc0b027644;p=chise%2Fxemacs-chise.git- diff --git a/info/lispref.info-39 b/info/lispref.info-39 index 9a6e077..d11996e 100644 --- a/info/lispref.info-39 +++ b/info/lispref.info-39 @@ -50,6 +50,901 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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 three types of weak hash tables: + +fully weak hash tables + In these 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. + + Also see *Note Weak Lists::. + + Weak hash tables are created by specifying the `:weakness' keyword to +`make-hash-table'. + + +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)) + + 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: 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 old-table + Make a new range table which contains the same values for the same + ranges as the given table. The values will not themselves be + copied. + + +File: lispref.info, Node: Working With Range Tables, Prev: Introduction to Range Tables, Up: Range Tables + +Working With Range Tables +========================= + + - Function: get-range-table pos table &optional default + This function finds value for position POS in TABLE. If there is + no corresponding value, return DEFAULT (defaults to `nil'). + + - Function: put-range-table start end val table + This function sets the value for range (START, END) to be VAL in + TABLE. + + - Function: remove-range-table start end table + This function removes the value for range (START, END) in TABLE. + + - Function: clear-range-table table + This function flushes TABLE. + + - Function: map-range-table function table + This function maps FUNCTION over entries in TABLE, calling it with + three args, the beginning and end of the range and the + corresponding value. + + +File: lispref.info, Node: Databases, Next: Processes, Prev: Range Tables, Up: Top + +Databases +********* + + - Function: databasep object + This function returns non-`nil' if OBJECT is a database. + +* Menu: + +* Connecting to a Database:: +* Working With a Database:: +* Other Database Functions:: + + +File: lispref.info, Node: Connecting to a Database, Next: Working With a Database, Up: Databases + +Connecting to a Database +======================== + + - 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. + + 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.) + + For a TYPE of `'dbm', there are no subtypes, so SUBTYPE should be + `nil'. + + For a TYPE of `'berkeley_db', the following subtypes are + available: `'hash', `'btree', and `'recno'. See the manpages for + the Berkeley DB functions to more information about these types. + + - Function: close-database obj + This function closes database OBJ. + + - Function: database-live-p obj + This function returns `t' iff OBJ is an active database, else + `nil'. + + +File: lispref.info, Node: Working With a Database, Next: Other Database Functions, Prev: Connecting to a Database, Up: Databases + +Working With a Database +======================= + + - Function: get-database key dbase &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). + + - Function: map-database function dbase + This function maps FUNCTION over entries in DATABASE, calling it + with two args, each key and value in the database. + + - Function: put-database key val dbase &optional replace + This function stores KEY and VAL in DATABASE. If optional fourth + arg REPLACE is non-`nil', replace any existing entry in the + database. + + - Function: remove-database key dbase + This function removes KEY from DATABASE. + + +File: lispref.info, Node: Other Database Functions, Prev: Working With a Database, Up: Databases + +Other Database Functions +======================== + + - Function: database-file-name obj + This function returns the filename associated with the database + OBJ. + + - Function: database-last-error &optional obj + This function returns the last error associated with database OBJ. + + - Function: database-subtype obj + This function returns the subtype of database OBJ, if any. + + - Function: database-type obj + This function returns the type of database OBJ. + + +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. + +* 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. + + +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 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. + + 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: 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 + + ---------- Buffer: foo ---------- + /usr/user/lewis/manual + ---------- Buffer: foo ---------- + + (call-process "grep" nil "bar" nil "lewis" "/etc/passwd") + => nil + + ---------- 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 delete + destination display &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 + DELETE is non-`nil'; this is useful when BUFFER is `t', to insert + the output in the current buffer. + + The arguments DESTINATION and DISPLAY 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 ---------- + + (call-process-region 1 6 "cat" nil t) + => nil + + ---------- Buffer: foo ---------- + inputinput-!- + ---------- Buffer: foo ---------- + + The `shell-command-on-region' command uses `call-process-region' + like this: + + (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: MS-DOS Subprocesses, Next: Asynchronous Processes, Prev: Synchronous Processes, Up: Processes + +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. + + - Variable: binary-process-output + If this variable is `nil', convert CRLF sequences to newlines in + the output from a synchronous subprocess. + + *Note Files and MS-DOS::, for related information. + + +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. + + 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::). + + +File: lispref.info, Node: Deleting Processes, Next: Process Information, Prev: Asynchronous Processes, Up: Processes + +Deleting Processes +================== + + "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 + + - 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. + + (process-kill-without-query (get-process "shell")) + => t + + +File: lispref.info, Node: Process Information, Next: Input to Processes, Prev: Deleting Processes, Up: Processes + +Process Information +=================== + + Several functions return information about processes. +`list-processes' is provided for interactive use. + + - 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'. + + - Function: process-list + This function returns a list of all processes that have not been + deleted. + + (process-list) + => (# #) + + - Function: get-process name + This function returns the process named NAME, or `nil' if there is + none. An error is signaled if NAME is not a string. + + (get-process "shell") + => # + + - 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. + + (process-command (get-process "shell")) + => ("/bin/csh" "-i") + + - 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. + + - Function: process-name process + This function returns the name of PROCESS. + + - Function: process-status process-name + This function returns the status of PROCESS-NAME as a symbol. The + argument PROCESS-NAME must be a process, a buffer, a process name + (string) or a buffer name (string). + + The possible values for an actual subprocess are: + + `run' + for a process that is running. + + `stop' + for a process that is stopped but continuable. + + `exit' + for a process that has exited. + + `signal' + for a process that has received a fatal signal. + + `open' + for a network connection that is open. + + `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. + + `nil' + if PROCESS-NAME is not the name of an existing process. + + (process-status "shell") + => run + (process-status (get-buffer "*shell*")) + => run + x + => #> + (process-status x) + => exit + + 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'. + + In earlier Emacs versions (prior to version 19), the status of a + network connection was `run' if open, and `exit' if closed. + + - 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'. + + - 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::). + + +File: lispref.info, Node: Input to Processes, Next: Signals to Processes, Prev: Process Information, Up: Processes + +Sending Input to Processes +========================== + + Asynchronous subprocesses receive input when it is sent to them by +XEmacs, which is done with the functions in this section. You must +specify the process to send input to, and the input data to send. The +data appears on the "standard input" of the subprocess. + + Some operating systems have limited space for buffered input in a +PTY. On these systems, Emacs sends an EOF periodically amidst the +other characters, to force them through. For most programs, these EOFs +do no harm. + + - Function: process-send-string process-name string + This function sends PROCESS-NAME the contents of STRING as + standard input. The argument PROCESS-NAME must be a process or + the name of a process. If it is `nil', the current buffer's + process is used. + + The function returns `nil'. + + (process-send-string "shell<1>" "ls\n") + => nil + + + ---------- Buffer: *shell* ---------- + ... + introduction.texi syntax-tables.texi~ + introduction.texi~ text.texi + introduction.txt text.texi~ + ... + ---------- Buffer: *shell* ---------- + + - Command: process-send-region process-name start end + This function sends the text in the region defined by START and + END as standard input to PROCESS-NAME, which is a process or a + process name. (If it is `nil', the current buffer's process is + used.) + + An error is signaled unless both START and END are integers or + markers that indicate positions in the current buffer. (It is + unimportant which number is larger.) + + - Function: process-send-eof &optional process-name + This function makes PROCESS-NAME see an end-of-file in its input. + The EOF comes after any text already sent to it. + + If PROCESS-NAME is not supplied, or if it is `nil', then this + function sends the EOF to the current buffer's process. An error + is signaled if the current buffer has no process. + + The function returns PROCESS-NAME. + + (process-send-eof "shell") + => "shell" + + +File: lispref.info, Node: Signals to Processes, Next: Output from Processes, Prev: Input to Processes, Up: Processes + +Sending Signals to Processes +============================ + + "Sending a signal" to a subprocess is a way of interrupting its +activities. There are several different signals, each with its own +meaning. The set of signals and their names is defined by the operating +system. For example, the signal `SIGINT' means that the user has typed +`C-c', or that some analogous thing has happened. + + Each signal has a standard effect on the subprocess. Most signals +kill the subprocess, but some stop or resume execution instead. Most +signals can optionally be handled by programs; if the program handles +the signal, then we can say nothing in general about its effects. + + The set of signals and their names is defined by the operating +system; XEmacs has facilities for sending only a few of the signals +that are defined. XEmacs can send signals only to its own subprocesses. + + You can send signals explicitly by calling the functions in this +section. XEmacs also sends signals automatically at certain times: +killing a buffer sends a `SIGHUP' signal to all its associated +processes; killing XEmacs sends a `SIGHUP' signal to all remaining +processes. (`SIGHUP' is a signal that usually indicates that the user +hung up the phone.) + + Each of the signal-sending functions takes two optional arguments: +PROCESS-NAME and CURRENT-GROUP. + + The argument PROCESS-NAME must be either a process, the name of one, +or `nil'. If it is `nil', the process defaults to the process +associated with the current buffer. An error is signaled if +PROCESS-NAME does not identify a process. + + The argument CURRENT-GROUP is a flag that makes a difference when +you are running a job-control shell as an XEmacs subprocess. If it is +non-`nil', then the signal is sent to the current process-group of the +terminal that XEmacs uses to communicate with the subprocess. If the +process is a job-control shell, this means the shell's current subjob. +If it is `nil', the signal is sent to the process group of the +immediate subprocess of XEmacs. If the subprocess is a job-control +shell, this is the shell itself. + + The flag CURRENT-GROUP has no effect when a pipe is used to +communicate with the subprocess, because the operating system does not +support the distinction in the case of pipes. For the same reason, +job-control shells won't work when a pipe is used. See +`process-connection-type' in *Note Asynchronous Processes::. + + - Function: interrupt-process &optional process-name current-group + This function interrupts the process PROCESS-NAME by sending the + signal `SIGINT'. Outside of XEmacs, typing the "interrupt + character" (normally `C-c' on some systems, and `DEL' on others) + sends this signal. When the argument CURRENT-GROUP is non-`nil', + you can think of this function as "typing `C-c'" on the terminal + by which XEmacs talks to the subprocess. + + - Function: kill-process &optional process-name current-group + This function kills the process PROCESS-NAME by sending the signal + `SIGKILL'. This signal kills the subprocess immediately, and + cannot be handled by the subprocess. + + - Function: quit-process &optional process-name current-group + This function sends the signal `SIGQUIT' to the process + PROCESS-NAME. This signal is the one sent by the "quit character" + (usually `C-b' or `C-\') when you are not inside XEmacs. + + - Function: stop-process &optional process-name current-group + This function stops the process PROCESS-NAME by sending the signal + `SIGTSTP'. Use `continue-process' to resume its execution. + + On systems with job control, the "stop character" (usually `C-z') + sends this signal (outside of XEmacs). When CURRENT-GROUP is + non-`nil', you can think of this function as "typing `C-z'" on the + terminal XEmacs uses to communicate with the subprocess. + + - Function: continue-process &optional process-name current-group + This function resumes execution of the process PROCESS by sending + it the signal `SIGCONT'. This presumes that PROCESS-NAME was + stopped previously. + + - Function: signal-process pid signal + This function sends a signal to process PID, which need not be a + child of XEmacs. The argument SIGNAL specifies which signal to + send; it should be an integer. + + +File: lispref.info, Node: Output from Processes, Next: Sentinels, Prev: Signals to Processes, Up: Processes + +Receiving Output from Processes +=============================== + + There are two ways to receive the output that a subprocess writes to +its standard output stream. The output can be inserted in a buffer, +which is called the associated buffer of the process, or a function +called the "filter function" can be called to act on the output. If +the process has no buffer and no filter function, its output is +discarded. + +* Menu: + +* Process Buffers:: If no filter, output is put in a buffer. +* Filter Functions:: Filter functions accept output from the process. +* Accepting Output:: Explicitly permitting subprocess output. + Waiting for subprocess output. + + File: lispref.info, Node: Process Buffers, Next: Filter Functions, Up: Output from Processes Process Buffers @@ -267,929 +1162,3 @@ until output arrives from a process. get some output, or `nil' if the timeout expired before output arrived. - -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' - => # - - - Function: process-sentinel process - This function returns the sentinel of PROCESS, or `nil' if it has - none. - - - 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. - - -File: lispref.info, Node: Process Window Size, Next: Transaction Queues, Prev: Sentinels, Up: Processes - -Process Window Size -=================== - - - 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. - - -File: lispref.info, Node: Transaction Queues, Next: Network, Prev: Process Window Size, Up: Processes - -Transaction Queues -================== - - 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. - - - 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: 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. - - 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. - - 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. - - The return value of `tq-enqueue' itself is not meaningful. - - - Function: tq-close queue - Shut down transaction queue QUEUE, waiting for all pending - transactions to complete, and then terminate the connection or - child process. - - Transaction queues are implemented by means of a filter function. -*Note Filter Functions::. - - -File: lispref.info, Node: Network, Prev: Transaction Queues, Up: Processes - -Network Connections -=================== - - 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). - - -File: lispref.info, Node: System Interface, Next: X-Windows, Prev: Processes, Up: Top - -Operating System Interface -************************** - - 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. - - *Note Building XEmacs::, for related information. See also *Note -Display::, for additional operating system status information -pertaining to the terminal and the screen. - -* Menu: - -* 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. - - -File: lispref.info, Node: Starting Up, Next: Getting Out, Up: System Interface - -Starting Up XEmacs -================== - - This section describes what XEmacs does when it is started, and how -you can customize these actions. - -* Menu: - -* 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. - - -File: lispref.info, Node: Start-up Summary, Next: Init File, Up: Starting Up - -Summary: Sequence of Actions at Start Up ----------------------------------------- - - The order of operations performed (in `startup.el') by XEmacs when -it is started up is as follows: - - 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'. - - 2. It processes the initial options. (Some of them are handled even - earlier than this.) - - 3. It initializes the X window frame and faces, if appropriate. - - 4. It runs the normal hook `before-init-hook'. - - 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'. - - 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 `~'. - - 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'. - - 8. It runs the normal hook `after-init-hook'. - - 9. It sets the major mode according to `initial-major-mode', provided - the buffer `*scratch*' is still current and still in Fundamental - mode. - - 10. It loads the terminal-specific Lisp file, if any, except when in - batch mode or using a window system. - - 11. It displays the initial echo area message, unless you have - suppressed that with `inhibit-startup-echo-area-message'. - - 12. It processes the action arguments from the command line. - - 13. It runs `term-setup-hook'. - - 14. It calls `frame-notice-user-settings', which modifies the - parameters of the selected frame according to whatever the init - files specify. - - 15. It runs `window-setup-hook'. *Note Terminal-Specific::. - - 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'. - - - 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. - - 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. - - - 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: - - (setq inhibit-startup-echo-area-message - "YOUR-LOGIN-NAME") - - 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. - - 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: 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'. - - - 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'. - - -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: Command Line Arguments, Prev: Terminal-Specific, Up: Starting Up - -Command Line Arguments ----------------------- - - 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. - - This section describes how Emacs processes command line arguments, -and how you can customize them. - - - 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. - - - Variable: command-line-processed - The value of this variable is `t' once the command line has been - processed. - - 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. - - - 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. - - A "command line option" is an argument on the command line of the - form: - - -OPTION - - The elements of the `command-switch-alist' look like this: - - (OPTION . HANDLER-FUNCTION) - - The HANDLER-FUNCTION is called to handle OPTION and receives the - option name as its sole argument. - - 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'.) - - 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. - - - Variable: command-line-args - The value of this variable is the list of command line arguments - passed to XEmacs. - - - 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. - - 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'. - - 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'. - - If all of these functions return `nil', then the argument is used - as a file name to visit. - - -File: lispref.info, Node: Getting Out, Next: System Environment, Prev: Starting Up, Up: System Interface - -Getting out of XEmacs -===================== - - 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. - -* Menu: - -* Killing XEmacs:: Exiting XEmacs irreversibly. -* Suspending XEmacs:: Exiting XEmacs reversibly. - - -File: lispref.info, Node: Killing XEmacs, Next: Suspending XEmacs, Up: Getting Out - -Killing XEmacs --------------- - - 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: kill-emacs &optional exit-data - This function exits the XEmacs process and kills it. - - 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::.) - - 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. - - 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'. - - - 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. - - - 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: 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) - => 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") - => nil - ---------- Buffer: Minibuffer ---------- - Really suspend? y - ---------- Buffer: Minibuffer ---------- - - ---------- Parent Shell ---------- - lewis@slug[23] % /user/lewis/manual - lewis@slug[24] % fg - - ---------- Echo Area ---------- - Resumed! - - - Variable: suspend-hook - This variable is a normal hook run before suspending. - - - Variable: suspend-resume-hook - This variable is a normal hook run after suspending. - - -File: lispref.info, Node: System Environment, Next: User Identification, Prev: Getting Out, Up: System Interface - -Operating System Environment -============================ - - XEmacs provides access to variables in the operating system -environment through various functions. These variables include the -name of the system, the user's UID, and so on. - - - Variable: system-type - The value of this variable is a symbol indicating the type of - operating system XEmacs is operating on. Here is a table of the - possible values: - - `aix-v3' - AIX. - - `berkeley-unix' - Berkeley BSD. - - `dgux' - Data General DGUX operating system. - - `gnu' - A GNU system using the GNU HURD and Mach. - - `hpux' - Hewlett-Packard HPUX operating system. - - `irix' - Silicon Graphics Irix system. - - `linux' - A GNU system using the Linux kernel. - - `ms-dos' - Microsoft MS-DOS "operating system." - - `next-mach' - NeXT Mach-based system. - - `rtu' - Masscomp RTU, UCB universe. - - `unisoft-unix' - UniSoft UniPlus. - - `usg-unix-v' - AT&T System V. - - `vax-vms' - VAX VMS. - - `windows-nt' - Microsoft windows NT. - - `xenix' - SCO Xenix 386. - - We do not wish to add new symbols to make finer distinctions - unless it is absolutely necessary! In fact, we hope to eliminate - some of these alternatives in the future. We recommend using - `system-configuration' to distinguish between different operating - systems. - - - Variable: system-configuration - This variable holds the three-part configuration name for the - hardware/software configuration of your system, as a string. The - convenient way to test parts of this string is with `string-match'. - - - Function: system-name - This function returns the name of the machine you are running on. - (system-name) - => "prep.ai.mit.edu" - - The symbol `system-name' is a variable as well as a function. In -fact, the function returns whatever value the variable `system-name' -currently holds. Thus, you can set the variable `system-name' in case -Emacs is confused about the name of your system. The variable is also -useful for constructing frame titles (*note Frame Titles::). - - - Variable: mail-host-address - If this variable is non-`nil', it is used instead of `system-name' - for purposes of generating email addresses. For example, it is - used when constructing the default value of `user-mail-address'. - *Note User Identification::. (Since this is done when XEmacs - starts up, the value actually used is the one saved when XEmacs - was dumped. *Note Building XEmacs::.) - - - Function: getenv var - This function returns the value of the environment variable VAR, - as a string. Within XEmacs, the environment variable values are - kept in the Lisp variable `process-environment'. - - (getenv "USER") - => "lewis" - - lewis@slug[10] % printenv - PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin - USER=lewis - TERM=ibmapa16 - SHELL=/bin/csh - HOME=/user/lewis - - - Command: setenv variable value - This command sets the value of the environment variable named - VARIABLE to VALUE. Both arguments should be strings. This - function works by modifying `process-environment'; binding that - variable with `let' is also reasonable practice. - - - Variable: process-environment - This variable is a list of strings, each describing one environment - variable. The functions `getenv' and `setenv' work by means of - this variable. - - process-environment - => ("l=/usr/stanford/lib/gnuemacs/lisp" - "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin" - "USER=lewis" - "TERM=ibmapa16" - "SHELL=/bin/csh" - "HOME=/user/lewis") - - - Variable: path-separator - This variable holds a string which says which character separates - directories in a search path (as found in an environment - variable). Its value is `":"' for Unix and GNU systems, and `";"' - for MS-DOS and Windows NT. - - - Variable: invocation-name - This variable holds the program name under which Emacs was - invoked. The value is a string, and does not include a directory - name. - - - Variable: invocation-directory - This variable holds the directory from which the Emacs executable - was invoked, or perhaps `nil' if that directory cannot be - determined. - - - Variable: installation-directory - If non-`nil', this is a directory within which to look for the - `lib-src' and `etc' subdirectories. This is non-`nil' when Emacs - can't find those directories in their standard installed - locations, but can find them in a directory related somehow to the - one containing the Emacs executable. - - - Function: load-average &optional use-floats - This function returns a list of the current 1-minute, 5-minute and - 15-minute load averages. The values are integers that are 100 - times the system load averages. (The load averages indicate the - number of processes trying to run.) - - When USE-FLOATS is non-`nil', floats will be returned instead of - integers. These floats are not multiplied by 100. - - (load-average) - => (169 158 164) - (load-average t) - => (1.69921875 1.58984375 1.640625) - - lewis@rocky[5] % uptime - 8:06pm up 16 day(s), 21:57, 40 users, - load average: 1.68, 1.59, 1.64 - - If the 5-minute or 15-minute load averages are not available, - return a shortened list, containing only those averages which are - available. - - On some systems, this function may require special privileges to - run, or it may be unimplemented for the particular system type. - In that case, the function will signal an error. - - - Function: emacs-pid - This function returns the process ID of the Emacs process. - - - Function: setprv privilege-name &optional setp getprv - This function sets or resets a VMS privilege. (It does not exist - on Unix.) The first arg is the privilege name, as a string. The - second argument, SETP, is `t' or `nil', indicating whether the - privilege is to be turned on or off. Its default is `nil'. The - function returns `t' if successful, `nil' otherwise. - - If the third argument, GETPRV, is non-`nil', `setprv' does not - change the privilege, but returns `t' or `nil' indicating whether - the privilege is currently enabled. - - -File: lispref.info, Node: User Identification, Next: Time of Day, Prev: System Environment, Up: System Interface - -User Identification -=================== - - - Variable: user-mail-address - This holds the nominal email address of the user who is using - Emacs. When Emacs starts up, it computes a default value that is - usually right, but users often set this themselves when the - default value is not right. - - - Function: user-login-name &optional uid - If you don't specify UID, this function returns the name under - which the user is logged in. If the environment variable `LOGNAME' - is set, that value is used. Otherwise, if the environment variable - `USER' is set, that value is used. Otherwise, the value is based - on the effective UID, not the real UID. - - If you specify UID, the value is the user name that corresponds to - UID (which should be an integer). - - (user-login-name) - => "lewis" - - - Function: user-real-login-name - This function returns the user name corresponding to Emacs's real - UID. This ignores the effective UID and ignores the environment - variables `LOGNAME' and `USER'. - - - Variable: user-full-name - This variable holds the name of the user running this Emacs. It is - initialized at startup time from the value of `NAME' environment - variable. You can change the value of this variable to alter the - result of the `user-full-name' function. - - - Function: user-full-name &optional user - This function returns the full name of USER. If USER is `nil', it - defaults to the user running this Emacs. In that case, the value - of `user-full-name' variable, if non-`nil', will be used. - - If USER is specified explicitly, `user-full-name' variable is - ignored. - - (user-full-name) - => "Hrvoje Niksic" - (setq user-full-name "Hrvoje \"Niksa\" Niksic") - (user-full-name) - => "Hrvoje \"Niksa\" Niksic" - (user-full-name "hniksic") - => "Hrvoje Niksic" - - The symbols `user-login-name', `user-real-login-name' and -`user-full-name' are variables as well as functions. The functions -return the same values that the variables hold. These variables allow -you to "fake out" Emacs by telling the functions what to return. The -variables are also useful for constructing frame titles (*note Frame -Titles::). - - - Function: user-real-uid - This function returns the real UID of the user. - - (user-real-uid) - => 19 - - - Function: user-uid - This function returns the effective UID of the user. - - - Function: user-home-directory - This function returns the "`HOME'" directory of the user, and is - intended to replace occurrences of "`(getenv "HOME")'". Under - Unix systems, the following is done: - - 1. Return the value of "`(getenv "HOME")'", if set. - - 2. Return "/", as a fallback, but issue a warning. (Future - versions of XEmacs will also attempt to lookup the `HOME' - directory via `getpwent()', but this has not yet been - implemented.) - - Under MS Windows, this is done: - - 1. Return the value of "`(getenv "HOME")'", if set. - - 2. If the environment variables `HOMEDRIVE' and `HOMEDIR' are - both set, return the concatenation (the following description - uses MS Windows environment variable substitution syntax): - `%HOMEDRIVE%%HOMEDIR%'. - - 3. Return "C:\", as a fallback, but issue a warning. -