X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-40;h=130bece6264514c3ada15642a053e9ae4726cf85;hb=c461477e9d1c45206851e095d1398498d09d040c;hp=69a170af6adb1c7231c2a413f694a48d4c5e477e;hpb=f52a96980ed9280f8f906a20d4b899dc0b027644;p=chise%2Fxemacs-chise.git diff --git a/info/lispref.info-40 b/info/lispref.info-40 index 69a170a..130bece 100644 --- a/info/lispref.info-40 +++ b/info/lispref.info-40 @@ -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,1106 +50,1071 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  -File: lispref.info, Node: Time of Day, Next: Time Conversion, Prev: User Identification, Up: System Interface - -Time of Day -=========== - - This section explains how to determine the current time and the time -zone. - - - Function: current-time-string &optional time-value - This function returns the current time and date as a - humanly-readable string. The format of the string is unvarying; - the number of characters used for each part is always the same, so - you can reliably use `substring' to extract pieces of it. It is - wise to count the characters from the beginning of the string - rather than from the end, as additional information may be added - at the end. - - The argument TIME-VALUE, if given, specifies a time to format - instead of the current time. The argument should be a list whose - first two elements are integers. Thus, you can use times obtained - from `current-time' (see below) and from `file-attributes' (*note - File Attributes::). - - (current-time-string) - => "Wed Oct 14 22:21:05 1987" - - - Function: current-time - This function returns the system's time value as a list of three - integers: `(HIGH LOW MICROSEC)'. The integers HIGH and LOW - combine to give the number of seconds since 0:00 January 1, 1970, - which is HIGH * 2**16 + LOW. - - The third element, MICROSEC, gives the microseconds since the - start of the current second (or 0 for systems that return time - only on the resolution of a second). - - The first two elements can be compared with file time values such - as you get with the function `file-attributes'. *Note File - Attributes::. - - - Function: current-time-zone &optional time-value - This function returns a list describing the time zone that the - user is in. - - The value has the form `(OFFSET NAME)'. Here OFFSET is an integer - giving the number of seconds ahead of UTC (east of Greenwich). A - negative value means west of Greenwich. The second element, NAME - is a string giving the name of the time zone. Both elements - change when daylight savings time begins or ends; if the user has - specified a time zone that does not use a seasonal time - adjustment, then the value is constant through time. - - If the operating system doesn't supply all the information - necessary to compute the value, both elements of the list are - `nil'. - - The argument TIME-VALUE, if given, specifies a time to analyze - instead of the current time. The argument should be a cons cell - containing two integers, or a list whose first two elements are - integers. Thus, you can use times obtained from `current-time' - (see above) and from `file-attributes' (*note File Attributes::). +File: lispref.info, Node: Input to Processes, Next: Signals to Processes, Prev: Process Information, Up: Processes - -File: lispref.info, Node: Time Conversion, Next: Timers, Prev: Time of Day, Up: System Interface - -Time Conversion -=============== - - These functions convert time values (lists of two or three integers) -to strings or to calendrical information. There is also a function to -convert calendrical information to a time value. You can get time -values from the functions `current-time' (*note Time of Day::) and -`file-attributes' (*note File Attributes::). - - - Function: format-time-string format-string &optional time - This function converts TIME to a string according to - FORMAT-STRING. If TIME is omitted, it defaults to the current - time. The argument FORMAT-STRING may contain `%'-sequences which - say to substitute parts of the time. Here is a table of what the - `%'-sequences mean: - - `%a' - This stands for the abbreviated name of the day of week. - - `%A' - This stands for the full name of the day of week. - - `%b' - This stands for the abbreviated name of the month. - - `%B' - This stands for the full name of the month. - - `%c' - This is a synonym for `%x %X'. - - `%C' - This has a locale-specific meaning. In the default locale - (named C), it is equivalent to `%A, %B %e, %Y'. - - `%d' - This stands for the day of month, zero-padded. - - `%D' - This is a synonym for `%m/%d/%y'. - - `%e' - This stands for the day of month, blank-padded. - - `%h' - This is a synonym for `%b'. - - `%H' - This stands for the hour (00-23). - - `%I' - This stands for the hour (00-12). - - `%j' - This stands for the day of the year (001-366). - - `%k' - This stands for the hour (0-23), blank padded. +Sending Input to Processes +========================== - `%l' - This stands for the hour (1-12), blank padded. + 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. - `%m' - This stands for the month (01-12). + Some operating systems have limited space for buffered input in a +PTY. On these systems, XEmacs sends long input in chunks, with EOF +characters added amidst the other characters, to force the operating +system to periodically drain the input buffer. For most programs, +these EOFs do no harm. - `%M' - This stands for the minute (00-59). + - Function: process-send-string process string &optional start end + This function sends PROCESS the contents of STRING as standard + input. - `%n' - This stands for a newline. + The argument PROCESS may be a process or the name of a process, or + a buffer or the name of a buffer, in which case the buffer's + process is used. If it is `nil', the current buffer's process is + used. - `%p' - This stands for `AM' or `PM', as appropriate. + Optional arguments START and END specify part of STRING; see + `substring'. - `%r' - This is a synonym for `%I:%M:%S %p'. + The function returns `nil'. - `%R' - This is a synonym for `%H:%M'. - - `%S' - This stands for the seconds (00-60). - - `%t' - This stands for a tab character. - - `%T' - This is a synonym for `%H:%M:%S'. - - `%U' - This stands for the week of the year (01-52), assuming that - weeks start on Sunday. + (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* ---------- + + - Function: process-send-region process start end &optional buffer + This function sends the text in the region defined by START and + END as standard input to PROCESS. + + The argument PROCESS may be a process or the name of a process, or + a buffer or the name of a buffer, in which case the buffer's + process is used. 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 + This function makes PROCESS see an end-of-file in its input. The + EOF comes after any text already sent to it. + + PROCESS may be a process, a buffer, the name of a process or + buffer, or `nil', indicating the current buffer's process. An + error is signaled if PROCESS does not identify any process. + + The function returns the process object identified by PROCESS. + + (process-send-eof "shell") + => "shell" - `%w' - This stands for the numeric day of week (0-6). Sunday is day - 0. + +File: lispref.info, Node: Signals to Processes, Next: Output from Processes, Prev: Input to Processes, Up: Processes - `%W' - This stands for the week of the year (01-52), assuming that - weeks start on Monday. +Sending Signals to Processes +============================ - `%x' - This has a locale-specific meaning. In the default locale - (named C), it is equivalent to `%D'. + "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 indicates that the connection +between the user and the process is broken, for example if a connection +via a telephone line is hung up.) + + Each of the signal-sending functions takes two optional arguments: +PROCESS and CURRENT-GROUP. + + The argument PROCESS must be either a process or a buffer, 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 +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 foreground 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::. + + Some of the functions below take a SIGNAL argument, which identifies +a signal to be sent. It must be either an integer or a symbol which +names the signal, like `SIGSEGV'. + + - Function: process-send-signal signal &optional process current-group + This function sends the signal SIGNAL to the process PROCESS. The + following functions can be implemented in terms of + `process-send-signal'. + + - Function: interrupt-process &optional process current-group + This function interrupts the process PROCESS by sending the signal + `SIGINT'. Outside of XEmacs, typing the "interrupt character" + (normally `C-c') 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 current-group + This function kills the process PROCESS by sending the signal + `SIGKILL'. This signal kills the subprocess immediately, and + cannot be handled by the subprocess. + + - Function: quit-process &optional process current-group + This function sends the signal `SIGQUIT' to the process PROCESS. + This signal is the one sent by the "quit character" (usually + `C-\') when you are not inside XEmacs. + + - Function: stop-process &optional process current-group + This function stops the process PROCESS 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 current-group + This function resumes execution of the process PROCESS by sending + it the signal `SIGCONT'. This presumes that PROCESS was stopped + previously. + + - Command: signal-process pid signal + This function sends a signal to the process with process id PID, + which need not be a child of XEmacs. The argument SIGNAL + specifies which signal to send. - `%X' - This has a locale-specific meaning. In the default locale - (named C), it is equivalent to `%T'. + +File: lispref.info, Node: Output from Processes, Next: Sentinels, Prev: Signals to Processes, Up: Processes - `%y' - This stands for the year without century (00-99). +Receiving Output from Processes +=============================== - `%Y' - This stands for the year with century. + 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. - `%Z' - This stands for the time zone abbreviation. +* Menu: - - Function: decode-time time - This function converts a time value into calendrical information. - The return value is a list of nine elements, as follows: +* 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. - (SECONDS MINUTES HOUR DAY MONTH YEAR DOW DST ZONE) + +File: lispref.info, Node: Process Buffers, Next: Filter Functions, Up: Output from Processes - Here is what the elements mean: +Process Buffers +--------------- - SEC - The number of seconds past the minute, as an integer between - 0 and 59. + 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. - MINUTE - The number of minutes past the hour, as an integer between 0 - and 59. + 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. - HOUR - The hour of the day, as an integer between 0 and 23. + - Function: process-buffer process + This function returns the associated buffer of the process PROCESS. - DAY - The day of the month, as an integer between 1 and 31. + (process-buffer (get-process "shell")) + => # - MONTH - The month of the year, as an integer between 1 and 12. + - 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. - YEAR - The year, an integer typically greater than 1900. + If PROCESS does not have a buffer, `process-mark' returns a marker + that points nowhere. - DOW - The day of week, as an integer between 0 and 6, where 0 - stands for Sunday. + 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. - DST - `t' if daylight savings time is effect, otherwise `nil'. + 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. - ZONE - An integer indicating the time zone, as the number of seconds - east of Greenwich. + 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. - Note that Common Lisp has different meanings for DOW and ZONE. + - 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: encode-time seconds minutes hour day month year &optional - zone - This function is the inverse of `decode-time'. It converts seven - items of calendrical data into a time value. For the meanings of - the arguments, see the table above under `decode-time'. + - Function: get-buffer-process buffer-or-name + This function returns the process associated with BUFFER-OR-NAME. + If there are several processes associated with BUFFER-OR-NAME, + 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. - Year numbers less than 100 are treated just like other year - numbers. If you want them to stand for years above 1900, you must - alter them yourself before you call `encode-time'. + (get-buffer-process "*shell*") + => # - The optional argument ZONE defaults to the current time zone and - its daylight savings time rules. If specified, it can be either a - list (as you would get from `current-time-zone') or an integer (as - you would get from `decode-time'). The specified zone is used - without any further alteration for daylight savings time. + Killing the process's buffer deletes the process, which kills the + subprocess with a `SIGHUP' signal (*note Signals to Processes::).  -File: lispref.info, Node: Timers, Next: Terminal Input, Prev: Time Conversion, Up: System Interface +File: lispref.info, Node: Filter Functions, Next: Accepting Output, Prev: Process Buffers, Up: Output from Processes -Timers for Delayed Execution -============================ +Process Filter Functions +------------------------ - You can set up a timer to call a function at a specified future time. - - - Function: add-timeout secs function object &optional resignal - This function adds a timeout, to be signaled after the timeout - period has elapsed. SECS is a number of seconds, expressed as an - integer or a float. FUNCTION will be called after that many - seconds have elapsed, with one argument, the given OBJECT. If the - optional RESIGNAL argument is provided, then after this timeout - expires, `add-timeout' will automatically be called again with - RESIGNAL as the first argument. - - This function returns an object which is the "id" of this - particular timeout. You can pass that object to `disable-timeout' - to turn off the timeout before it has been signalled. - - The number of seconds may be expressed as a floating-point number, - in which case some fractional part of a second will be used. - Caveat: the usable timeout granularity will vary from system to - system. - - Adding a timeout causes a timeout event to be returned by - `next-event', and the function will be invoked by - `dispatch-event', so if XEmacs is in a tight loop, the function - will not be invoked until the next call to sit-for or until the - return to top-level (the same is true of process filters). - - WARNING: if you are thinking of calling add-timeout from inside of - a callback function as a way of resignalling a timeout, think - again. There is a race condition. That's why the RESIGNAL - argument exists. - - (NOTE: In FSF Emacs, this function is called `run-at-time' and has - different semantics.) - - - Function: disable-timeout id - Cancel the requested action for ID, which should be a value - previously returned by `add-timeout'. This cancels the effect of - that call to `add-timeout'; the arrival of the specified time will - not cause anything special to happen. (NOTE: In FSF Emacs, this - function is called `cancel-timer'.) + 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 (process string) + (let ((old-buffer (current-buffer))) + (unwind-protect + (let (moving) + (set-buffer (process-buffer process)) + (setq moving (= (point) (process-mark process))) + (save-excursion + ;; Insert the text, moving the process-marker. + (goto-char (process-mark process)) + (insert string) + (set-marker (process-mark process) (point))) + (if moving (goto-char (process-mark process)))) + (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 process)) + + 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: Terminal Input, Next: Terminal Output, Prev: Timers, Up: System Interface - -Terminal Input -============== - - This section describes functions and variables for recording or -manipulating terminal input. See *Note Display::, for related -functions. - -* Menu: - -* Input Modes:: Options for how input is processed. -* Translating Input:: Low level conversion of some characters or events - into others. -* Recording Input:: Saving histories of recent or all input events. +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.  -File: lispref.info, Node: Input Modes, Next: Translating Input, Up: Terminal Input - -Input Modes ------------ - - - Function: set-input-mode interrupt flow meta quit-char - This function sets the mode for reading keyboard input. If - INTERRUPT is non-null, then XEmacs uses input interrupts. If it is - `nil', then it uses CBREAK mode. When XEmacs communicates - directly with X, it ignores this argument and uses interrupts if - that is the way it knows how to communicate. - - If FLOW is non-`nil', then XEmacs uses XON/XOFF (`C-q', `C-s') - flow control for output to the terminal. This has no effect except - in CBREAK mode. *Note Flow Control::. - - The default setting is system dependent. Some systems always use - CBREAK mode regardless of what is specified. - - The argument META controls support for input character codes above - 127. If META is `t', XEmacs converts characters with the 8th bit - set into Meta characters. If META is `nil', XEmacs disregards the - 8th bit; this is necessary when the terminal uses it as a parity - bit. If META is neither `t' nor `nil', XEmacs uses all 8 bits of - input unchanged. This is good for terminals using European 8-bit - character sets. - - If QUIT-CHAR is non-`nil', it specifies the character to use for - quitting. Normally this character is `C-g'. *Note Quitting::. - - The `current-input-mode' function returns the input mode settings -XEmacs is currently using. - - - Function: current-input-mode - This function returns current mode for reading keyboard input. It - returns a list, corresponding to the arguments of `set-input-mode', - of the form `(INTERRUPT FLOW META QUIT)' in which: - INTERRUPT - is non-`nil' when XEmacs is using interrupt-driven input. If - `nil', Emacs is using CBREAK mode. - - FLOW - is non-`nil' if XEmacs uses XON/XOFF (`C-q', `C-s') flow - control for output to the terminal. This value has no effect - unless INTERRUPT is non-`nil'. - - META - is `t' if XEmacs treats the eighth bit of input characters as - the meta bit; `nil' means XEmacs clears the eighth bit of - every input character; any other value means XEmacs uses all - eight bits as the basic character code. - - QUIT - is the character XEmacs currently uses for quitting, usually - `C-g'. +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: Translating Input, Next: Recording Input, Prev: Input Modes, Up: Terminal Input +File: lispref.info, Node: Process Window Size, Next: Transaction Queues, Prev: Sentinels, Up: Processes -Translating Input Events ------------------------- +Process Window Size +=================== - This section describes features for translating input events into -other input events before they become part of key sequences. - - - Variable: function-key-map - This variable holds a keymap that describes the character sequences - sent by function keys on an ordinary character terminal. This - keymap uses the same data structure as other keymaps, but is used - differently: it specifies translations to make while reading - events. - - If `function-key-map' "binds" a key sequence K to a vector V, then - when K appears as a subsequence _anywhere_ in a key sequence, it - is replaced with the events in V. - - For example, VT100 terminals send ` O P' when the keypad PF1 - key is pressed. Therefore, we want XEmacs to translate that - sequence of events into the single event `pf1'. We accomplish - this by "binding" ` O P' to `[pf1]' in `function-key-map', - when using a VT100. - - Thus, typing `C-c ' sends the character sequence `C-c O - P'; later the function `read-key-sequence' translates this back - into `C-c ', which it returns as the vector `[?\C-c pf1]'. - - Entries in `function-key-map' are ignored if they conflict with - bindings made in the minor mode, local, or global keymaps. The - intent is that the character sequences that function keys send - should not have command bindings in their own right. - - The value of `function-key-map' is usually set up automatically - according to the terminal's Terminfo or Termcap entry, but - sometimes those need help from terminal-specific Lisp files. - XEmacs comes with terminal-specific files for many common - terminals; their main purpose is to make entries in - `function-key-map' beyond those that can be deduced from Termcap - and Terminfo. *Note Terminal-Specific::. - - Emacs versions 18 and earlier used totally different means of - detecting the character sequences that represent function keys. - - - Variable: key-translation-map - This variable is another keymap used just like `function-key-map' - to translate input events into other events. It differs from - `function-key-map' in two ways: - - * `key-translation-map' goes to work after `function-key-map' is - finished; it receives the results of translation by - `function-key-map'. - - * `key-translation-map' overrides actual key bindings. - - The intent of `key-translation-map' is for users to map one - character set to another, including ordinary characters normally - bound to `self-insert-command'. - - You can use `function-key-map' or `key-translation-map' for more -than simple aliases, by using a function, instead of a key sequence, as -the "translation" of a key. Then this function is called to compute -the translation of that key. - - The key translation function receives one argument, which is the -prompt that was specified in `read-key-sequence'--or `nil' if the key -sequence is being read by the editor command loop. In most cases you -can ignore the prompt value. - - If the function reads input itself, it can have the effect of -altering the event that follows. For example, here's how to define -`C-c h' to turn the character that follows into a Hyper character: - - (defun hyperify (prompt) - (let ((e (read-event))) - (vector (if (numberp e) - (logior (lsh 1 20) e) - (if (memq 'hyper (event-modifiers e)) - e - (add-event-modifier "H-" e)))))) - - (defun add-event-modifier (string e) - (let ((symbol (if (symbolp e) e (car e)))) - (setq symbol (intern (concat string - (symbol-name symbol)))) - (if (symbolp e) - symbol - (cons symbol (cdr e))))) - - (define-key function-key-map "\C-ch" 'hyperify) - - The `iso-transl' library uses this feature to provide a way of -inputting non-ASCII Latin-1 characters. + - 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: Recording Input, Prev: Translating Input, Up: Terminal Input - -Recording Input ---------------- +File: lispref.info, Node: Transaction Queues, Next: Network, Prev: Process Window Size, Up: Processes - - Function: recent-keys &optional number - This function returns a vector containing recent input events from - the keyboard or mouse. By default, 100 events are recorded, which - is how many `recent-keys' returns. +Transaction Queues +================== - All input events are included, whether or not they were used as - parts of key sequences. Thus, you always get the last 100 inputs, - not counting keyboard macros. (Events from keyboard macros are - excluded because they are less interesting for debugging; it - should be enough to see the events that invoked the macros.) + 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. - If NUMBER is specified, not more than NUMBER events will be - returned. You may change the number of stored events using - `set-recent-keys-ring-size'. + - 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: recent-keys-ring-size - This function returns the number of recent events stored - internally. This is also the maximum number of events - `recent-keys' can return. By default, 100 events are stored. + - 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: set-recent-keys-ring-size size - This function changes the number of events stored by XEmacs and - returned by `recent-keys'. + 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. - For example, `(set-recent-keys-ring-size 250)' will make XEmacs - remember last 250 events and will make `recent-keys' return last - 250 events by default. + 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. - - Command: open-dribble-file filename - This function opens a "dribble file" named FILENAME. When a - dribble file is open, each input event from the keyboard or mouse - (but not those from keyboard macros) is written in that file. A - non-character event is expressed using its printed representation - surrounded by `<...>'. + The return value of `tq-enqueue' itself is not meaningful. - You close the dribble file by calling this function with an - argument of `nil'. + - Function: tq-close queue + Shut down transaction queue QUEUE, waiting for all pending + transactions to complete, and then terminate the connection or + child process. - This function is normally used to record the input necessary to - trigger an XEmacs bug, for the sake of a bug report. - - (open-dribble-file "~/dribble") - => nil - - See also the `open-termscript' function (*note Terminal Output::). + Transaction queues are implemented by means of a filter function. +*Note Filter Functions::.  -File: lispref.info, Node: Terminal Output, Next: Flow Control, Prev: Terminal Input, Up: System Interface - -Terminal Output -=============== - - The terminal output functions send output to the terminal or keep -track of output sent to the terminal. The function `device-baud-rate' -tells you what XEmacs thinks is the output speed of the terminal. - - - Function: device-baud-rate &optional device - This function's value is the output speed of the terminal - associated with DEVICE, as far as XEmacs knows. DEVICE defaults - to the selected device (usually the only device) if omitted. - Changing this value does not change the speed of actual data - transmission, but the value is used for calculations such as - padding. This value has no effect for window-system devices. - (This is different in FSF Emacs, where the baud rate also affects - decisions about whether to scroll part of the screen or repaint, - even when using a window system.) - - The value is measured in bits per second. - - XEmacs attempts to automatically initialize the baud rate by querying -the terminal. If you are running across a network, however, and -different parts of the network work are at different baud rates, the -value returned by XEmacs may be different from the value used by your -local terminal. Some network protocols communicate the local terminal -speed to the remote machine, so that XEmacs and other programs can get -the proper value, but others do not. If XEmacs has the wrong value, it -makes decisions that are less than optimal. To fix the problem, use -`set-device-baud-rate'. - - - Function: set-device-baud-rate &optional device - This function sets the output speed of DEVICE. See - `device-baud-rate'. DEVICE defaults to the selected device - (usually the only device) if omitted. - - - Function: send-string-to-terminal char-or-string &optional stdout-p - device - This function sends CHAR-OR-STRING to the terminal without - alteration. Control characters in CHAR-OR-STRING have - terminal-dependent effects. - - If DEVICE is `nil', this function writes to XEmacs's stderr, or to - stdout if STDOUT-P is non-`nil'. Otherwise, DEVICE should be a - tty or stream device, and the function writes to the device's - normal or error output, according to STDOUT-P. - - One use of this function is to define function keys on terminals - that have downloadable function key definitions. For example, - this is how on certain terminals to define function key 4 to move - forward four characters (by transmitting the characters `C-u C-f' - to the computer): - - (send-string-to-terminal "\eF4\^U\^F") - => nil +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 + &optional protocol + This function opens a TCP connection for a service to a host. It + returns a process object to represent the connection. + + Input and output work as for other process objects. + `delete-process' closes 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. It can be a buffer or the name of one. 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). + + Optional fifth arg PROTOCOL is the network protocol to use. + Currently only `tcp' (Transmission Control Protocol) and `udp' + (User Datagram Protocol) are supported. When omitted, `tcp' is + assumed. + + Output via `process-send-string' and input via buffer or filter + (see `set-process-filter') are stream-oriented. That means UDP + datagrams are not guaranteed to be sent and received in discrete + packets. (But small datagrams around 500 bytes that are not + truncated by `process-send-string' are usually fine.) Note further + that the UDP protocol does not guard against lost packets. - - Command: open-termscript filename - This function is used to open a "termscript file" that will record - all the characters sent by XEmacs to the terminal. (If there are - multiple tty or stream devices, all characters sent to all such - devices are recorded.) The function returns `nil'. Termscript - files are useful for investigating problems where XEmacs garbles - the screen, problems that are due to incorrect Termcap entries or - to undesirable settings of terminal options more often than to - actual XEmacs bugs. Once you are certain which characters were - actually output, you can determine reliably whether they - correspond to the Termcap specifications in use. - - A `nil' value for FILENAME stops recording terminal output. + +File: lispref.info, Node: System Interface, Next: X-Windows, Prev: Processes, Up: Top - See also `open-dribble-file' in *Note Terminal Input::. +Operating System Interface +************************** - (open-termscript "../junk/termscript") - => nil + 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. - -File: lispref.info, Node: Flow Control, Next: Batch Mode, Prev: Terminal Output, Up: System Interface - -Flow Control -============ - - This section attempts to answer the question "Why does XEmacs choose -to use flow-control characters in its command character set?" For a -second view on this issue, read the comments on flow control in the -`emacs/INSTALL' file from the distribution; for help with Termcap -entries and DEC terminal concentrators, see `emacs/etc/TERMS'. - - At one time, most terminals did not need flow control, and none used -`C-s' and `C-q' for flow control. Therefore, the choice of `C-s' and -`C-q' as command characters was uncontroversial. XEmacs, for economy -of keystrokes and portability, used nearly all the ASCII control -characters, with mnemonic meanings when possible; thus, `C-s' for -search and `C-q' for quote. - - Later, some terminals were introduced which required these characters -for flow control. They were not very good terminals for full-screen -editing, so XEmacs maintainers did not pay attention. In later years, -flow control with `C-s' and `C-q' became widespread among terminals, -but by this time it was usually an option. And the majority of users, -who can turn flow control off, were unwilling to switch to less -mnemonic key bindings for the sake of flow control. - - So which usage is "right", XEmacs's or that of some terminal and -concentrator manufacturers? This question has no simple answer. - - One reason why we are reluctant to cater to the problems caused by -`C-s' and `C-q' is that they are gratuitous. There are other -techniques (albeit less common in practice) for flow control that -preserve transparency of the character stream. Note also that their use -for flow control is not an official standard. Interestingly, on the -model 33 teletype with a paper tape punch (which is very old), `C-s' -and `C-q' were sent by the computer to turn the punch on and off! - - As X servers and other window systems replace character-only -terminals, this problem is gradually being cured. For the mean time, -XEmacs provides a convenient way of enabling flow control if you want -it: call the function `enable-flow-control'. - - - Function: enable-flow-control - This function enables use of `C-s' and `C-q' for output flow - control, and provides the characters `C-\' and `C-^' as aliases - for them using `keyboard-translate-table' (*note Translating - Input::). - - You can use the function `enable-flow-control-on' in your `.emacs' -file to enable flow control automatically on certain terminal types. - - - Function: enable-flow-control-on &rest termtypes - This function enables flow control, and the aliases `C-\' and - `C-^', if the terminal type is one of TERMTYPES. For example: - - (enable-flow-control-on "vt200" "vt300" "vt101" "vt131") - - Here is how `enable-flow-control' does its job: - - 1. It sets CBREAK mode for terminal input, and tells the operating - system to handle flow control, with `(set-input-mode nil t)'. - - 2. It sets up `keyboard-translate-table' to translate `C-\' and `C-^' - into `C-s' and `C-q'. Except at its very lowest level, XEmacs - never knows that the characters typed were anything but `C-s' and - `C-q', so you can in effect type them as `C-\' and `C-^' even when - they are input for other commands. *Note Translating Input::. - - If the terminal is the source of the flow control characters, then -once you enable kernel flow control handling, you probably can make do -with less padding than normal for that terminal. You can reduce the -amount of padding by customizing the Termcap entry. You can also -reduce it by setting `baud-rate' to a smaller value so that XEmacs uses -a smaller speed when calculating the padding needed. *Note Terminal -Output::. + *Note Building XEmacs::, for related information. See also *Note +Display::, for additional operating system status information +pertaining to the terminal and the screen. - -File: lispref.info, Node: Batch Mode, Prev: Flow Control, Up: System Interface - -Batch Mode -========== - - The command line option `-batch' causes XEmacs to run -noninteractively. In this mode, XEmacs does not read commands from the -terminal, it does not alter the terminal modes, and it does not expect -to be outputting to an erasable screen. The idea is that you specify -Lisp programs to run; when they are finished, XEmacs should exit. The -way to specify the programs to run is with `-l FILE', which loads the -library named FILE, and `-f FUNCTION', which calls FUNCTION with no -arguments. - - Any Lisp program output that would normally go to the echo area, -either using `message' or using `prin1', etc., with `t' as the stream, -goes instead to XEmacs's standard error descriptor when in batch mode. -Thus, XEmacs behaves much like a noninteractive application program. -(The echo area output that XEmacs itself normally generates, such as -command echoing, is suppressed entirely.) - - - Function: noninteractive - This function returns non-`nil' when XEmacs is running in batch - mode. +* Menu: - - Variable: noninteractive - This variable is non-`nil' when XEmacs is running in batch mode. - Setting this variable to `nil', however, will not change whether - XEmacs is running in batch mode, and will not change the return - value of the `noninteractive' function. +* 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: X-Windows, Next: ToolTalk Support, Prev: System Interface, Up: Top +File: lispref.info, Node: Starting Up, Next: Getting Out, Up: System Interface -Functions Specific to the X Window System -***************************************** +Starting Up XEmacs +================== - XEmacs provides the concept of "devices", which generalizes -connections to an X server, a TTY device, etc. Most information about -an X server that XEmacs is connected to can be determined through -general console and device functions. *Note Consoles and Devices::. -However, there are some features of the X Window System that do not -generalize well, and they are covered specially here. + This section describes what XEmacs does when it is started, and how +you can customize these actions. * Menu: -* X Selections:: Transferring text to and from other X clients. -* X Server:: Information about the X server connected to - a particular device. -* X Miscellaneous:: Other X-specific functions and variables. +* 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: X Selections, Next: X Server, Up: X-Windows - -X Selections -============ - - The X server records a set of "selections" which permit transfer of -data between application programs. The various selections are -distinguished by "selection types", represented in XEmacs by symbols. -X clients including XEmacs can read or set the selection for any given -type. - - - Function: x-own-selection data &optional type - This function sets a "selection" in the X server. It takes two - arguments: a value, DATA, and the selection type TYPE to assign it - to. DATA may be a string, a cons of two markers, or an extent. - In the latter cases, the selection is considered to be the text - between the markers, or between the extent's endpoints. - - Each possible TYPE has its own selection value, which changes - independently. The usual values of TYPE are `PRIMARY' and - `SECONDARY'; these are symbols with upper-case names, in accord - with X Windows conventions. The default is `PRIMARY'. - - (In FSF Emacs, this function is called `x-set-selection' and takes - different arguments.) - - - Function: x-get-selection - This function accesses selections set up by XEmacs or by other X - clients. It returns the value of the current primary selection. - - - Function: x-disown-selection &optional secondary-p - Assuming we own the selection, this function disowns it. If - SECONDARY-P is non-`nil', the secondary selection instead of the - primary selection is discarded. - - The X server also has a set of numbered "cut buffers" which can -store text or other data being moved between applications. Cut buffers -are considered obsolete, but XEmacs supports them for the sake of X -clients that still use them. - - - Function: x-get-cutbuffer &optional n - This function returns the contents of cut buffer number N. (This - function is called `x-get-cut-buffer' in FSF Emacs.) - - - Function: x-store-cutbuffer string - This function stores STRING into the first cut buffer (cut buffer - 0), moving the other values down through the series of cut buffers, - kill-ring-style. (This function is called `x-set-cut-buffer' in FSF - Emacs.) +File: lispref.info, Node: Start-up Summary, Next: Init File, Up: Starting Up - -File: lispref.info, Node: X Server, Next: X Miscellaneous, Prev: X Selections, Up: X-Windows +Summary: Sequence of Actions at Start Up +---------------------------------------- -X Server -======== + The order of operations performed (in `startup.el') by XEmacs when +it is started up is as follows: - This section describes how to access and change the overall status of -the X server XEmacs is using. + 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'. -* Menu: + 2. It processes the initial options. (Some of them are handled even + earlier than this.) -* Resources:: Getting resource values from the server. -* Server Data:: Getting info about the X server. -* Grabs:: Restricting access to the server by other apps. + 3. It initializes the X window frame and faces, if appropriate. - -File: lispref.info, Node: Resources, Next: Server Data, Up: X Server + 4. It runs the normal hook `before-init-hook'. -Resources ---------- + 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'. - - Function: default-x-device - This function return the default X device for resourcing. This is - the first-created X device that still exists. + 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: x-get-resource name class type &optional locale device - noerror - This function retrieves a resource value from the X resource - manager. + 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'. - * The first arg is the name of the resource to retrieve, such as - `"font"'. + 8. It runs the normal hook `after-init-hook'. - * The second arg is the class of the resource to retrieve, like - `"Font"'. + 9. It sets the major mode according to `initial-major-mode', provided + the buffer `*scratch*' is still current and still in Fundamental + mode. - * The third arg should be one of the symbols `string', - `integer', `natnum', or `boolean', specifying the type of - object that the database is searched for. + 10. It loads the terminal-specific Lisp file, if any, except when in + batch mode or using a window system. - * The fourth arg is the locale to search for the resources on, - and can currently be a a buffer, a frame, a device, or the - symbol `global'. If omitted, it defaults to `global'. + 11. It displays the initial echo area message, unless you have + suppressed that with `inhibit-startup-echo-area-message'. - * The fifth arg is the device to search for the resources on. - (The resource database for a particular device is constructed - by combining non-device- specific resources such any - command-line resources specified and any app-defaults files - found [or the fallback resources supplied by XEmacs, if no - app-defaults file is found] with device-specific resources - such as those supplied using `xrdb'.) If omitted, it defaults - to the device of LOCALE, if a device can be derived (i.e. if - LOCALE is a frame or device), and otherwise defaults to the - value of `default-x-device'. + 12. It processes the action arguments from the command line. - * The sixth arg NOERROR, if non-`nil', means do not signal an - error if a bogus resource specification was retrieved (e.g. - if a non-integer was given when an integer was requested). - In this case, a warning is issued instead. + 13. It runs `term-setup-hook'. - The resource names passed to this function are looked up relative - to the locale. + 14. It calls `frame-notice-user-settings', which modifies the + parameters of the selected frame according to whatever the init + files specify. - If you want to search for a subresource, you just need to specify - the resource levels in NAME and CLASS. For example, NAME could be - `"modeline.attributeFont"', and CLASS `"Face.AttributeFont"'. + 15. It runs `window-setup-hook'. *Note Terminal-Specific::. - Specifically, + 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'. - 1. If LOCALE is a buffer, a call + - 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. - `(x-get-resource "foreground" "Foreground" 'string SOME-BUFFER)' + 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. - is an interface to a C call something like + - 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: - `XrmGetResource (db, "xemacs.buffer.BUFFER-NAME.foreground", - "Emacs.EmacsLocaleType.EmacsBuffer.Foreground", - "String");' + (setq inhibit-startup-echo-area-message + "YOUR-LOGIN-NAME") - 2. If LOCALE is a frame, a call + 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. - `(x-get-resource "foreground" "Foreground" 'string SOME-FRAME)' + 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. - is an interface to a C call something like + +File: lispref.info, Node: Init File, Next: Terminal-Specific, Prev: Start-up Summary, Up: Starting Up - `XrmGetResource (db, "xemacs.frame.FRAME-NAME.foreground", - "Emacs.EmacsLocaleType.EmacsFrame.Foreground", - "String");' +The Init File: `.emacs' +----------------------- - 3. If LOCALE is a device, a call + 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'. - `(x-get-resource "foreground" "Foreground" 'string SOME-DEVICE)' + +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'. - is an interface to a C call something like + +File: lispref.info, Node: Command Line Arguments, Prev: Terminal-Specific, Up: Starting Up - `XrmGetResource (db, "xemacs.device.DEVICE-NAME.foreground", - "Emacs.EmacsLocaleType.EmacsDevice.Foreground", - "String");' +Command Line Arguments +---------------------- - 4. If LOCALE is the symbol `global', a call + 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. - `(x-get-resource "foreground" "Foreground" 'string 'global)' + This section describes how Emacs processes command line arguments, +and how you can customize them. - is an interface to a C call something like + - 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. - `XrmGetResource (db, "xemacs.foreground", - "Emacs.Foreground", - "String");' + - Variable: command-line-processed + The value of this variable is `t' once the command line has been + processed. - Note that for `global', no prefix is added other than that of the - application itself; thus, you can use this locale to retrieve - arbitrary application resources, if you really want to. + 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. - The returned value of this function is `nil' if the queried - resource is not found. If TYPE is `string', a string is returned, - and if it is `integer', an integer is returned. If TYPE is - `boolean', then the returned value is the list `(t)' for true, - `(nil)' for false, and is `nil' to mean "unspecified". + - 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. - - Function: x-put-resource resource-line &optional device - This function adds a resource to the resource database for DEVICE. - RESOURCE-LINE specifies the resource to add and should be a - standard resource specification. + A "command line option" is an argument on the command line of the + form: - - Variable: x-emacs-application-class - This variable holds The X application class of the XEmacs process. - This controls, among other things, the name of the "app-defaults" - file that XEmacs will use. For changes to this variable to take - effect, they must be made before the connection to the X server is - initialized, that is, this variable may only be changed before - XEmacs is dumped, or by setting it in the file - `lisp/term/x-win.el'. + -OPTION - By default, this variable is nil at startup. When the connection - to the X server is first initialized, the X resource database will - be consulted and the value will be set according to whether any - resources are found for the application class "XEmacs". + The elements of the `command-switch-alist' look like this: - -File: lispref.info, Node: Server Data, Next: Grabs, Prev: Resources, Up: X Server + (OPTION . HANDLER-FUNCTION) -Data about the X Server ------------------------ + The HANDLER-FUNCTION is called to handle OPTION and receives the + option name as its sole argument. - This section describes functions and a variable that you can use to -get information about the capabilities and origin of the X server -corresponding to a particular device. The device argument is generally -optional and defaults to the selected device. + 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'.) - - Function: x-server-version &optional device - This function returns the list of version numbers of the X server - DEVICE is on. The returned value is a list of three integers: the - major and minor version numbers of the X protocol in use, and the - vendor-specific release number. + 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: x-server-vendor &optional device - This function returns the vendor supporting the X server DEVICE is - on. + - Variable: command-line-args + The value of this variable is the list of command line arguments + passed to XEmacs. - - Function: x-display-visual-class &optional device - This function returns the visual class of the display DEVICE is - on. The value is one of the symbols `static-gray', `gray-scale', - `static-color', `pseudo-color', `true-color', and `direct-color'. - (Note that this is different from previous versions of XEmacs, - which returned `StaticGray', `GrayScale', etc.) + - 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. - -File: lispref.info, Node: Grabs, Prev: Server Data, Up: X Server - -Restricting Access to the Server by Other Apps ----------------------------------------------- - - - Function: x-grab-keyboard &optional device - This function grabs the keyboard on the given device (defaulting - to the selected one). So long as the keyboard is grabbed, all - keyboard events will be delivered to XEmacs--it is not possible - for other X clients to eavesdrop on them. Ungrab the keyboard - with `x-ungrab-keyboard' (use an `unwind-protect'). Returns `t' - if the grab was successful; `nil' otherwise. - - - Function: x-ungrab-keyboard &optional device - This function releases a keyboard grab made with `x-grab-keyboard'. - - - Function: x-grab-pointer &optional device cursor ignore-keyboard - This function grabs the pointer and restricts it to its current - window. If optional DEVICE argument is `nil', the selected device - will be used. If optional CURSOR argument is non-`nil', change - the pointer shape to that until `x-ungrab-pointer' is called (it - should be an object returned by the `make-cursor' function). If - the second optional argument IGNORE-KEYBOARD is non-`nil', ignore - all keyboard events during the grab. Returns `t' if the grab is - successful, `nil' otherwise. - - - Function: x-ungrab-pointer &optional device - This function releases a pointer grab made with `x-grab-pointer'. - If optional first arg DEVICE is `nil' the selected device is used. - If it is `t' the pointer will be released on all X devices. + 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'. - -File: lispref.info, Node: X Miscellaneous, Prev: X Server, Up: X-Windows - -Miscellaneous X Functions and Variables -======================================= - - - Variable: x-bitmap-file-path - This variable holds a list of the directories in which X bitmap - files may be found. If `nil', this is initialized from the - `"*bitmapFilePath"' resource. This is used by the - `make-image-instance' function (however, note that if the - environment variable `XBMLANGPATH' is set, it is consulted first). - - - Variable: x-library-search-path - This variable holds the search path used by `read-color' to find - `rgb.txt'. - - - Function: x-valid-keysym-name-p keysym - This function returns true if KEYSYM names a keysym that the X - library knows about. Valid keysyms are listed in the files - `/usr/include/X11/keysymdef.h' and in `/usr/lib/X11/XKeysymDB', or - whatever the equivalents are on your system. - - - Function: x-window-id &optional frame - This function returns the ID of the X11 window. This gives us a - chance to manipulate the Emacs window from within a different - program. Since the ID is an unsigned long, we return it as a - string. - - - Variable: x-allow-sendevents - If non-`nil', synthetic events are allowed. `nil' means they are - ignored. Beware: allowing XEmacs to process SendEvents opens a - big security hole. - - - Function: x-debug-mode arg &optional device - With a true arg, make the connection to the X server synchronous. - With false, make it asynchronous. Synchronous connections are - much slower, but are useful for debugging. (If you get X errors, - make the connection synchronous, and use a debugger to set a - breakpoint on `x_error_handler'. Your backtrace of the C stack - will now be useful. In asynchronous mode, the stack above - `x_error_handler' isn't helpful because of buffering.) If DEVICE - is not specified, the selected device is assumed. - - Calling this function is the same as calling the C function - `XSynchronize', or starting the program with the `-sync' command - line argument. - - - Variable: x-debug-events - If non-zero, debug information about events that XEmacs sees is - displayed. Information is displayed on stderr. Currently defined - values are: - - * 1 == non-verbose output - - * 2 == verbose output + 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: ToolTalk Support, Next: LDAP Support, Prev: X-Windows, Up: Top +File: lispref.info, Node: Getting Out, Next: System Environment, Prev: Starting Up, Up: System Interface -ToolTalk Support -**************** +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: -* XEmacs ToolTalk API Summary:: -* Sending Messages:: -* Receiving Messages:: +* Killing XEmacs:: Exiting XEmacs irreversibly. +* Suspending XEmacs:: Exiting XEmacs reversibly.  -File: lispref.info, Node: XEmacs ToolTalk API Summary, Next: Sending Messages, Up: ToolTalk Support - -XEmacs ToolTalk API Summary -=========================== - - The XEmacs Lisp interface to ToolTalk is similar, at least in spirit, -to the standard C ToolTalk API. Only the message and pattern parts of -the API are supported at present; more of the API could be added if -needed. The Lisp interface departs from the C API in a few ways: - - * ToolTalk is initialized automatically at XEmacs startup-time. - Messages can only be sent other ToolTalk applications connected to - the same X11 server that XEmacs is running on. +File: lispref.info, Node: Killing XEmacs, Next: Suspending XEmacs, Up: Getting Out - * There are fewer entry points; polymorphic functions with keyword - arguments are used instead. +Killing XEmacs +-------------- - * The callback interface is simpler and marginally less functional. - A single callback may be associated with a message or a pattern; - the callback is specified with a Lisp symbol (the symbol should - have a function binding). + 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'. - * The session attribute for messages and patterns is always - initialized to the default session. + - Command: kill-emacs &optional exit-data + This function exits the XEmacs process and kills it. - * Anywhere a ToolTalk enum constant, e.g. `TT_SESSION', is valid, one - can substitute the corresponding symbol, e.g. `'TT_SESSION'. This - simplifies building lists that represent messages and patterns. + 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::.) - -File: lispref.info, Node: Sending Messages, Next: Receiving Messages, Prev: XEmacs ToolTalk API Summary, Up: ToolTalk Support + 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. -Sending Messages -================ + 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'. -* Menu: + - 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. -* Example of Sending Messages:: -* Elisp Interface for Sending Messages:: + - 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: Example of Sending Messages, Next: Elisp Interface for Sending Messages, Up: Sending Messages - -Example of Sending Messages ---------------------------- - - Here's a simple example that sends a query to another application -and then displays its reply. Both the query and the reply are stored -in the first argument of the message. - - (defun tooltalk-random-query-handler (msg) - (let ((state (get-tooltalk-message-attribute msg 'state))) - (cond - ((eq state 'TT_HANDLED) - (message (get-tooltalk-message-attribute msg arg_val 0))) - ((memq state '(TT_FAILED TT_REJECTED)) - (message "Random query turns up nothing"))))) - - (defvar random-query-message - '( class TT_REQUEST - scope TT_SESSION - address TT_PROCEDURE - op "random-query" - args '((TT_INOUT "?" "string")) - callback tooltalk-random-query-handler)) - - (let ((m (make-tooltalk-message random-query-message))) - (send-tooltalk-message m)) +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. + + - Command: suspend-emacs &optional stuffstring + 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 optional arg STUFFSTRING is non-`nil', its characters are sent + to be read as terminal input by XEmacs's superior shell. The + characters in STUFFSTRING 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.