-This is ../info/lispref.info, produced by makeinfo version 3.12s from
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
Foundation instead of in the original English.
\1f
-File: lispref.info, Node: Terminal Output, Next: Flow Control, Prev: Terminal Input, Up: System Interface
+File: lispref.info, Node: Sentinels, Next: Process Window Size, Prev: Output from Processes, Up: Processes
+
+Sentinels: Detecting Process Status Changes
+===========================================
+
+ A "process sentinel" is a function that is called whenever the
+associated process changes status for any reason, including signals
+(whether sent by XEmacs or caused by the process's own actions) that
+terminate, stop, or continue the process. The process sentinel is also
+called if the process exits. The sentinel receives two arguments: the
+process for which the event occurred, and a string describing the type
+of event.
+
+ The string describing the event looks like one of the following:
+
+ * `"finished\n"'.
+
+ * `"exited abnormally with code EXITCODE\n"'.
+
+ * `"NAME-OF-SIGNAL\n"'.
+
+ * `"NAME-OF-SIGNAL (core dumped)\n"'.
+
+ A sentinel runs only while XEmacs is waiting (e.g., for terminal
+input, or for time to elapse, or for process output). This avoids the
+timing errors that could result from running them at random places in
+the middle of other Lisp programs. A program can wait, so that
+sentinels will run, by calling `sit-for' or `sleep-for' (*note
+Waiting::), or `accept-process-output' (*note Accepting Output::).
+Emacs is also waiting when the command loop is reading input.
+
+ Quitting is normally inhibited within a sentinel--otherwise, the
+effect of typing `C-g' at command level or to quit a user command would
+be unpredictable. If you want to permit quitting inside a sentinel,
+bind `inhibit-quit' to `nil'. *Note Quitting::.
+
+ A sentinel that writes the output into the buffer of the process
+should check whether the buffer is still alive. If it tries to insert
+into a dead buffer, it will get an error. If the buffer is dead,
+`(buffer-name (process-buffer PROCESS))' returns `nil'.
+
+ If an error happens during execution of a sentinel, it is caught
+automatically, so that it doesn't stop the execution of whatever
+programs was running when the sentinel was started. However, if
+`debug-on-error' is non-`nil', the error-catching is turned off. This
+makes it possible to use the Lisp debugger to debug the sentinel.
+*Note Debugger::.
+
+ In earlier Emacs versions, every sentinel that did regexp searching
+or matching had to explicitly save and restore the match data. Now
+Emacs does this automatically; sentinels never need to do it explicitly.
+*Note Match Data::.
+
+ - Function: set-process-sentinel process sentinel
+ This function associates SENTINEL with PROCESS. If SENTINEL is
+ `nil', then the process will have no sentinel. The default
+ behavior when there is no sentinel is to insert a message in the
+ process's buffer when the process status changes.
+
+ (defun msg-me (process event)
+ (princ
+ (format "Process: %s had the event `%s'" process event)))
+ (set-process-sentinel (get-process "shell") 'msg-me)
+ => msg-me
+ (kill-process (get-process "shell"))
+ -| Process: #<process shell> had the event `killed'
+ => #<process shell>
+
+ - 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.
-Terminal Output
-===============
+\1f
+File: lispref.info, Node: Process Window Size, Next: Transaction Queues, Prev: Sentinels, Up: Processes
- 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
+Process Window Size
+===================
- - 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.
+ - 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.
- A `nil' value for FILENAME stops recording terminal output.
+\1f
+File: lispref.info, Node: Transaction Queues, Next: Network, Prev: Process Window Size, Up: Processes
- See also `open-dribble-file' in *Note Terminal Input::.
+Transaction Queues
+==================
- (open-termscript "../junk/termscript")
- => nil
+ 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.
-\1f
-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::.
+ - 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.
-\1f
-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.
+ - 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.
- - 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.
+ 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.
-\1f
-File: lispref.info, Node: X-Windows, Next: ToolTalk Support, Prev: System Interface, Up: Top
-
-Functions Specific to the X Window System
-*****************************************
+ 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.
- 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.
+ The return value of `tq-enqueue' itself is not meaningful.
-* Menu:
+ - Function: tq-close queue
+ Shut down transaction queue QUEUE, waiting for all pending
+ transactions to complete, and then terminate the connection or
+ child process.
-* 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.
+ Transaction queues are implemented by means of a filter function.
+*Note Filter Functions::.
\1f
-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: 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).
\1f
-File: lispref.info, Node: X Server, Next: X Miscellaneous, Prev: X Selections, Up: X-Windows
+File: lispref.info, Node: System Interface, Next: X-Windows, Prev: Processes, Up: Top
+
+Operating System Interface
+**************************
-X Server
-========
+ 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.
- This section describes how to access and change the overall status of
-the X server XEmacs is using.
+ *Note Building XEmacs::, for related information. See also *Note
+Display::, for additional operating system status information
+pertaining to the terminal and the screen.
* Menu:
-* Resources:: Getting resource values from the server.
-* Server Data:: Getting info about the X server.
-* Grabs:: Restricting access to the server by other apps.
+* 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.
\1f
-File: lispref.info, Node: Resources, Next: Server Data, Up: X Server
+File: lispref.info, Node: Starting Up, Next: Getting Out, Up: System Interface
-Resources
----------
+Starting Up XEmacs
+==================
- - Function: default-x-device
- This function return the default X device for resourcing. This is
- the first-created X device that still exists.
+ This section describes what XEmacs does when it is started, and how
+you can customize these actions.
- - Function: x-get-resource name class type &optional locale device
- noerror
- This function retrieves a resource value from the X resource
- manager.
+* Menu:
- * The first arg is the name of the resource to retrieve, such as
- `"font"'.
+* 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.
- * The second arg is the class of the resource to retrieve, like
- `"Font"'.
+\1f
+File: lispref.info, Node: Start-up Summary, Next: Init File, Up: Starting Up
- * 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.
+Summary: Sequence of Actions at Start Up
+----------------------------------------
- * 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'.
+ The order of operations performed (in `startup.el') by XEmacs when
+it is started up is as follows:
- * 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'.
+ 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'.
- * 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.
+ 2. It processes the initial options. (Some of them are handled even
+ earlier than this.)
- The resource names passed to this function are looked up relative
- to the locale.
+ 3. It initializes the X window frame and faces, if appropriate.
- 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"'.
+ 4. It runs the normal hook `before-init-hook'.
- Specifically,
+ 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'.
- 1. If LOCALE is a buffer, a call
+ 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 `~'.
- `(x-get-resource "foreground" "Foreground" 'string SOME-BUFFER)'
+ 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'.
- is an interface to a C call something like
+ 8. It runs the normal hook `after-init-hook'.
- `XrmGetResource (db, "xemacs.buffer.BUFFER-NAME.foreground",
- "Emacs.EmacsLocaleType.EmacsBuffer.Foreground",
- "String");'
+ 9. It sets the major mode according to `initial-major-mode', provided
+ the buffer `*scratch*' is still current and still in Fundamental
+ mode.
- 2. If LOCALE is a frame, a call
+ 10. It loads the terminal-specific Lisp file, if any, except when in
+ batch mode or using a window system.
- `(x-get-resource "foreground" "Foreground" 'string SOME-FRAME)'
+ 11. It displays the initial echo area message, unless you have
+ suppressed that with `inhibit-startup-echo-area-message'.
- is an interface to a C call something like
+ 12. It processes the action arguments from the command line.
- `XrmGetResource (db, "xemacs.frame.FRAME-NAME.foreground",
- "Emacs.EmacsLocaleType.EmacsFrame.Foreground",
- "String");'
+ 13. It runs `term-setup-hook'.
- 3. If LOCALE is a device, a call
+ 14. It calls `frame-notice-user-settings', which modifies the
+ parameters of the selected frame according to whatever the init
+ files specify.
- `(x-get-resource "foreground" "Foreground" 'string SOME-DEVICE)'
+ 15. It runs `window-setup-hook'. *Note Terminal-Specific::.
- is an interface to a C call something like
+ 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'.
- `XrmGetResource (db, "xemacs.device.DEVICE-NAME.foreground",
- "Emacs.EmacsLocaleType.EmacsDevice.Foreground",
- "String");'
+ - 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.
- 4. If LOCALE is the symbol `global', a call
+ 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.
- `(x-get-resource "foreground" "Foreground" 'string 'global)'
+ - 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:
- is an interface to a C call something like
+ (setq inhibit-startup-echo-area-message
+ "YOUR-LOGIN-NAME")
- `XrmGetResource (db, "xemacs.foreground",
- "Emacs.Foreground",
- "String");'
+ 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.
- 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.
+ 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.
- 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".
+\1f
+File: lispref.info, Node: Init File, Next: Terminal-Specific, Prev: Start-up Summary, Up: Starting Up
- - 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.
+The Init File: `.emacs'
+-----------------------
- - 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'.
+ 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'.
- 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".
+\1f
+File: lispref.info, Node: Terminal-Specific, Next: Command Line Arguments, Prev: Init File, Up: Starting Up
+
+Terminal-Specific Initialization
+--------------------------------
+
+ Each terminal type can have its own Lisp library that XEmacs loads
+when run on that type of terminal. For a terminal type named TERMTYPE,
+the library is called `term/TERMTYPE'. XEmacs finds the file by
+searching the `load-path' directories as it does for other files, and
+trying the `.elc' and `.el' suffixes. Normally, terminal-specific Lisp
+library is located in `emacs/lisp/term', a subdirectory of the
+`emacs/lisp' directory in which most XEmacs Lisp libraries are kept.
+
+ The library's name is constructed by concatenating the value of the
+variable `term-file-prefix' and the terminal type. Normally,
+`term-file-prefix' has the value `"term/"'; changing this is not
+recommended.
+
+ The usual function of a terminal-specific library is to enable
+special keys to send sequences that XEmacs can recognize. It may also
+need to set or add to `function-key-map' if the Termcap entry does not
+specify all the terminal's function keys. *Note Terminal Input::.
+
+ When the name of the terminal type contains a hyphen, only the part
+of the name before the first hyphen is significant in choosing the
+library name. Thus, terminal types `aaa-48' and `aaa-30-rv' both use
+the `term/aaa' library. If necessary, the library can evaluate
+`(getenv "TERM")' to find the full name of the terminal type.
+
+ Your `.emacs' file can prevent the loading of the terminal-specific
+library by setting the variable `term-file-prefix' to `nil'. This
+feature is useful when experimenting with your own peculiar
+customizations.
+
+ You can also arrange to override some of the actions of the
+terminal-specific library by setting the variable `term-setup-hook'.
+This is a normal hook which XEmacs runs using `run-hooks' at the end of
+XEmacs initialization, after loading both your `.emacs' file and any
+terminal-specific libraries. You can use this variable to define
+initializations for terminals that do not have their own libraries.
+*Note Hooks::.
+
+ - Variable: term-file-prefix
+ If the `term-file-prefix' variable is non-`nil', XEmacs loads a
+ terminal-specific initialization file as follows:
+
+ (load (concat term-file-prefix (getenv "TERM")))
+
+ You may set the `term-file-prefix' variable to `nil' in your
+ `.emacs' file if you do not wish to load the
+ terminal-initialization file. To do this, put the following in
+ your `.emacs' file: `(setq term-file-prefix nil)'.
+
+ - Variable: term-setup-hook
+ This variable is a normal hook that XEmacs runs after loading your
+ `.emacs' file, the default initialization file (if any) and the
+ terminal-specific Lisp file.
+
+ You can use `term-setup-hook' to override the definitions made by a
+ terminal-specific file.
+
+ - Variable: window-setup-hook
+ This variable is a normal hook which XEmacs runs after loading your
+ `.emacs' file and the default initialization file (if any), after
+ loading terminal-specific Lisp code, and after running the hook
+ `term-setup-hook'.
\1f
-File: lispref.info, Node: Server Data, Next: Grabs, Prev: Resources, Up: X Server
+File: lispref.info, Node: Command Line Arguments, Prev: Terminal-Specific, Up: Starting Up
-Data about the X Server
------------------------
+Command Line Arguments
+----------------------
- 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.
+ You can use command line arguments to request various actions when
+you start XEmacs. Since you do not need to start XEmacs more than once
+per day, and will often leave your XEmacs session running longer than
+that, command line arguments are hardly ever used. As a practical
+matter, it is best to avoid making the habit of using them, since this
+habit would encourage you to kill and restart XEmacs unnecessarily
+often. These options exist for two reasons: to be compatible with
+other editors (for invocation by other programs) and to enable shell
+scripts to run specific Lisp programs.
- - Function: 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.
+ This section describes how Emacs processes command line arguments,
+and how you can customize them.
- - Function: x-server-vendor &optional device
- This function returns the vendor supporting the X server DEVICE is
- on.
+ - Function: command-line
+ This function parses the command line that XEmacs was called with,
+ processes it, loads the user's `.emacs' file and displays the
+ startup messages.
- - Function: 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-processed
+ The value of this variable is `t' once the command line has been
+ processed.
-\1f
-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.
+ 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.
-\1f
-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
+ - Variable: command-switch-alist
+ The value of this variable is an alist of user-defined command-line
+ options and associated handler functions. This variable exists so
+ you can add elements to it.
-\1f
-File: lispref.info, Node: ToolTalk Support, Next: LDAP Support, Prev: X-Windows, Up: Top
+ A "command line option" is an argument on the command line of the
+ form:
-ToolTalk Support
-****************
+ -OPTION
-* Menu:
+ The elements of the `command-switch-alist' look like this:
-* XEmacs ToolTalk API Summary::
-* Sending Messages::
-* Receiving Messages::
+ (OPTION . HANDLER-FUNCTION)
-\1f
-File: lispref.info, Node: XEmacs ToolTalk API Summary, Next: Sending Messages, Up: ToolTalk Support
+ The HANDLER-FUNCTION is called to handle OPTION and receives the
+ option name as its sole argument.
-XEmacs ToolTalk API Summary
-===========================
+ 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 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:
+ 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.
- * 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.
+ - Variable: command-line-args
+ The value of this variable is the list of command line arguments
+ passed to XEmacs.
- * There are fewer entry points; polymorphic functions with keyword
- arguments are used instead.
+ - 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.
- * 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).
+ 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'.
- * The session attribute for messages and patterns is always
- initialized to the default session.
+ 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'.
- * 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 all of these functions return `nil', then the argument is used
+ as a file name to visit.
\1f
-File: lispref.info, Node: Sending Messages, Next: Receiving Messages, Prev: XEmacs ToolTalk API Summary, Up: ToolTalk Support
+File: lispref.info, Node: Getting Out, Next: System Environment, Prev: Starting Up, Up: System Interface
-Sending Messages
-================
+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:
-* Example of Sending Messages::
-* Elisp Interface for Sending Messages::
+* Killing XEmacs:: Exiting XEmacs irreversibly.
+* Suspending XEmacs:: Exiting XEmacs reversibly.
\1f
-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: Killing XEmacs, Next: Suspending XEmacs, Up: Getting Out
-\1f
-File: lispref.info, Node: Elisp Interface for Sending Messages, Prev: Example of Sending Messages, Up: Sending Messages
-
-Elisp Interface for Sending Messages
-------------------------------------
-
- - Function: make-tooltalk-message attributes
- Create a ToolTalk message and initialize its attributes. The
- value of ATTRIBUTES must be a list of alternating keyword/values,
- where keywords are symbols that name valid message attributes.
- For example:
-
- (make-tooltalk-message
- '(class TT_NOTICE
- scope TT_SESSION
- address TT_PROCEDURE
- op "do-something"
- args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
-
- Values must always be strings, integers, or symbols that represent
- ToolTalk constants. Attribute names are the same as those
- supported by `set-tooltalk-message-attribute', plus `args'.
-
- The value of `args' should be a list of message arguments where
- each message argument has the following form:
-
- `(mode [value [type]])' or just `value'
-
- Where MODE is one of `TT_IN', `TT_OUT', or `TT_INOUT' and TYPE is
- a string. If TYPE isn't specified then `int' is used if VALUE is
- a number; otherwise `string' is used. If TYPE is `string' then
- VALUE is converted to a string (if it isn't a string already) with
- `prin1-to-string'. If only a value is specified then MODE
- defaults to `TT_IN'. If MODE is `TT_OUT' then VALUE and TYPE
- don't need to be specified. You can find out more about the
- semantics and uses of ToolTalk message arguments in chapter 4 of
- the `ToolTalk Programmer's Guide'.
-
-
- - Function: send-tooltalk-message msg
- Send the message on its way. Once the message has been sent it's
- almost always a good idea to get rid of it with
- `destroy-tooltalk-message'.
-
-
- - Function: return-tooltalk-message msg &optional mode
- Send a reply to this message. The second argument can be `reply',
- `reject' or `fail'; the default is `reply'. Before sending a
- reply, all message arguments whose mode is `TT_INOUT' or `TT_OUT'
- should have been filled in - see `set-tooltalk-message-attribute'.
-
-
- - Function: get-tooltalk-message-attribute msg attribute &optional argn
- Returns the indicated ToolTalk message attribute. Attributes are
- identified by symbols with the same name (underscores and all) as
- the suffix of the ToolTalk `tt_message_<attribute>' function that
- extracts the value. String attribute values are copied and
- enumerated type values (except disposition) are converted to
- symbols; e.g. `TT_HANDLER' is `'TT_HANDLER', `uid' and `gid' are
- represented by fixnums (small integers), `opnum' is converted to a
- string, and `disposition' is converted to a fixnum. We convert
- `opnum' (a C int) to a string (e.g. `123' => `"123"') because
- there's no guarantee that opnums will fit within the range of
- XEmacs Lisp integers.
-
- [TBD] Use the `plist' attribute instead of C API `user' attribute
- for user-defined message data. To retrieve the value of a message
- property, specify the indicator for ARGN. For example, to get the
- value of a property called `rflag', use
-
- (get-tooltalk-message-attribute msg 'plist 'rflag)
-
- To get the value of a message argument use one of the `arg_val'
- (strings), `arg_ival' (integers), or `arg_bval' (strings with
- embedded nulls), attributes. For example, to get the integer
- value of the third argument:
-
- (get-tooltalk-message-attribute msg 'arg_ival 2)
-
- As you can see, argument numbers are zero-based. The type of each
- arguments can be retrieved with the `arg_type' attribute; however
- ToolTalk doesn't define any semantics for the string value of
- `arg_type'. Conventionally `string' is used for strings and `int'
- for 32 bit integers. Note that XEmacs Lisp stores the lengths of
- strings explicitly (unlike C) so treating the value returned by
- `arg_bval' like a string is fine.
-
-
- - Function: set-tooltalk-message-attribute value msg attribute
- &optional argn
- Initialize one ToolTalk message attribute.
-
- Attribute names and values are the same as for
- `get-tooltalk-message-attribute'. A property list is provided for
- user data (instead of the `user' message attribute); see
- `get-tooltalk-message-attribute'.
-
- Callbacks are handled slightly differently than in the C ToolTalk
- API. The value of CALLBACK should be the name of a function of one
- argument. It will be called each time the state of the message
- changes. This is usually used to notice when the message's state
- has changed to `TT_HANDLED' (or `TT_FAILED'), so that reply
- argument values can be used.
-
- If one of the argument attributes is specified as `arg_val',
- `arg_ival', or `arg_bval', then ARGN must be the number of an
- already created argument. Arguments can be added to a message
- with `add-tooltalk-message-arg'.
-
-
- - Function: add-tooltalk-message-arg msg mode type &optional value
- Append one new argument to the message. MODE must be one of
- `TT_IN', `TT_INOUT', or `TT_OUT', TYPE must be a string, and VALUE
- can be a string or an integer. ToolTalk doesn't define any
- semantics for TYPE, so only the participants in the protocol
- you're using need to agree what types mean (if anything).
- Conventionally `string' is used for strings and `int' for 32 bit
- integers. Arguments can initialized by providing a value or with
- `set-tooltalk-message-attribute'; the latter is necessary if you
- want to initialize the argument with a string that can contain
- embedded nulls (use `arg_bval').
-
-
- - Function: create-tooltalk-message
- Create a new ToolTalk message. The message's session attribute is
- initialized to the default session. Other attributes can be
- initialized with `set-tooltalk-message-attribute'.
- `make-tooltalk-message' is the preferred way to create and
- initialize a message.
-
-
- - Function: destroy-tooltalk-message msg
- Apply `tt_message_destroy' to the message. It's not necessary to
- destroy messages after they've been processed by a message or
- pattern callback, the Lisp/ToolTalk callback machinery does this
- for you.
+Killing XEmacs
+--------------
-\1f
-File: lispref.info, Node: Receiving Messages, Prev: Sending Messages, Up: ToolTalk Support
+ 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'.
-Receiving Messages
-==================
+ - Function: kill-emacs &optional exit-data
+ This function exits the XEmacs process and kills it.
-* Menu:
+ 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::.)
-* Example of Receiving Messages::
-* Elisp Interface for Receiving Messages::
+ 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.
\1f
-File: lispref.info, Node: Example of Receiving Messages, Next: Elisp Interface for Receiving Messages, Up: Receiving Messages
-
-Example of Receiving Messages
------------------------------
-
- Here's a simple example of a handler for a message that tells XEmacs
-to display a string in the mini-buffer area. The message operation is
-called `emacs-display-string'. Its first (0th) argument is the string
-to display.
-
- (defun tooltalk-display-string-handler (msg)
- (message (get-tooltalk-message-attribute msg 'arg_val 0)))
-
- (defvar display-string-pattern
- '(category TT_HANDLE
- scope TT_SESSION
- op "emacs-display-string"
- callback tooltalk-display-string-handler))
-
- (let ((p (make-tooltalk-pattern display-string-pattern)))
- (register-tooltalk-pattern p))
+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.
\1f
-File: lispref.info, Node: Elisp Interface for Receiving Messages, Prev: Example of Receiving Messages, Up: Receiving Messages
-
-Elisp Interface for Receiving Messages
---------------------------------------
-
- - Function: make-tooltalk-pattern attributes
- Create a ToolTalk pattern and initialize its attributes. The
- value of attributes must be a list of alternating keyword/values,
- where keywords are symbols that name valid pattern attributes or
- lists of valid attributes. For example:
-
- (make-tooltalk-pattern
- '(category TT_OBSERVE
- scope TT_SESSION
- op ("operation1" "operation2")
- args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
-
- Attribute names are the same as those supported by
- `add-tooltalk-pattern-attribute', plus `'args'.
-
- Values must always be strings, integers, or symbols that represent
- ToolTalk constants or lists of same. When a list of values is
- provided all of the list elements are added to the attribute. In
- the example above, messages whose `op' attribute is `"operation1"'
- or `"operation2"' would match the pattern.
-
- The value of ARGS should be a list of pattern arguments where each
- pattern argument has the following form:
-
- `(mode [value [type]])' or just `value'
-
- Where MODE is one of `TT_IN', `TT_OUT', or `TT_INOUT' and TYPE is
- a string. If TYPE isn't specified then `int' is used if VALUE is
- a number; otherwise `string' is used. If TYPE is `string' then
- VALUE is converted to a string (if it isn't a string already) with
- `prin1-to-string'. If only a value is specified then MODE
- defaults to `TT_IN'. If MODE is `TT_OUT' then VALUE and TYPE
- don't need to be specified. You can find out more about the
- semantics and uses of ToolTalk pattern arguments in chapter 3 of
- the `ToolTalk Programmer's Guide'.
-
-
- - Function: register-tooltalk-pattern pat
- XEmacs will begin receiving messages that match this pattern.
-
- - Function: unregister-tooltalk-pattern pat
- XEmacs will stop receiving messages that match this pattern.
-
- - Function: add-tooltalk-pattern-attribute value pat indicator
- Add one value to the indicated pattern attribute. The names of
- attributes are the same as the ToolTalk accessors used to set them
- less the `tooltalk_pattern_' prefix and the `_add' suffix. For
- example, the name of the attribute for the
- `tt_pattern_disposition_add' attribute is `disposition'. The
- `category' attribute is handled specially, since a pattern can only
- be a member of one category (`TT_OBSERVE' or `TT_HANDLE').
-
- Callbacks are handled slightly differently than in the C ToolTalk
- API. The value of CALLBACK should be the name of a function of one
- argument. It will be called each time the pattern matches an
- incoming message.
-
- - Function: add-tooltalk-pattern-arg pat mode type value
- Add one fully-specified argument to a ToolTalk pattern. MODE must
- be one of `TT_IN', `TT_INOUT', or `TT_OUT'. TYPE must be a
- string. VALUE can be an integer, string or `nil'. If VALUE is an
- integer then an integer argument (`tt_pattern_iarg_add') is added;
- otherwise a string argument is added. At present there's no way
- to add a binary data argument.
-
-
- - Function: create-tooltalk-pattern
- Create a new ToolTalk pattern and initialize its session attribute
- to be the default session.
-
- - Function: destroy-tooltalk-pattern pat
- Apply `tt_pattern_destroy' to the pattern. This effectively
- unregisters the pattern.
-
- - Function: describe-tooltalk-message msg &optional stream
- Print the message's attributes and arguments to STREAM. This is
- often useful for debugging.
+File: lispref.info, Node: System Environment, Next: User Identification, Prev: Getting Out, Up: System Interface
+
+Operating System Environment
+============================
+
+ XEmacs provides access to variables in the operating system
+environment through various functions. These variables include the
+name of the system, the user's UID, and so on.
+
+ - Variable: system-type
+ The value of this variable is a symbol indicating the type of
+ operating system XEmacs is operating on. Here is a table of the
+ possible values:
+
+ `aix-v3'
+ AIX.
+
+ `berkeley-unix'
+ Berkeley BSD.
+
+ `dgux'
+ Data General DGUX operating system.
+
+ `gnu'
+ A GNU system using the GNU HURD and Mach.
+
+ `hpux'
+ Hewlett-Packard HPUX operating system.
+
+ `irix'
+ Silicon Graphics Irix system.
+
+ `linux'
+ A GNU system using the Linux kernel.
+
+ `ms-dos'
+ Microsoft MS-DOS "operating system."
+
+ `next-mach'
+ NeXT Mach-based system.
+
+ `rtu'
+ Masscomp RTU, UCB universe.
+
+ `unisoft-unix'
+ UniSoft UniPlus.
+
+ `usg-unix-v'
+ AT&T System V.
+
+ `vax-vms'
+ VAX VMS.
+
+ `windows-nt'
+ Microsoft windows NT.
+
+ `xenix'
+ SCO Xenix 386.
+
+ We do not wish to add new symbols to make finer distinctions
+ unless it is absolutely necessary! In fact, we hope to eliminate
+ some of these alternatives in the future. We recommend using
+ `system-configuration' to distinguish between different operating
+ systems.
+
+ - Variable: system-configuration
+ This variable holds the three-part configuration name for the
+ hardware/software configuration of your system, as a string. The
+ convenient way to test parts of this string is with `string-match'.
+
+ - Function: system-name
+ This function returns the name of the machine you are running on.
+ (system-name)
+ => "prep.ai.mit.edu"
+
+ The symbol `system-name' is a variable as well as a function. In
+fact, the function returns whatever value the variable `system-name'
+currently holds. Thus, you can set the variable `system-name' in case
+Emacs is confused about the name of your system. The variable is also
+useful for constructing frame titles (*note Frame Titles::).
+
+ - Variable: mail-host-address
+ If this variable is non-`nil', it is used instead of `system-name'
+ for purposes of generating email addresses. For example, it is
+ used when constructing the default value of `user-mail-address'.
+ *Note User Identification::. (Since this is done when XEmacs
+ starts up, the value actually used is the one saved when XEmacs
+ was dumped. *Note Building XEmacs::.)
+
+ - Function: getenv var
+ This function returns the value of the environment variable VAR,
+ as a string. Within XEmacs, the environment variable values are
+ kept in the Lisp variable `process-environment'.
+
+ (getenv "USER")
+ => "lewis"
+
+ lewis@slug[10] % printenv
+ PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
+ USER=lewis
+ TERM=ibmapa16
+ SHELL=/bin/csh
+ HOME=/user/lewis
+
+ - Command: setenv variable value
+ This command sets the value of the environment variable named
+ VARIABLE to VALUE. Both arguments should be strings. This
+ function works by modifying `process-environment'; binding that
+ variable with `let' is also reasonable practice.
+
+ - Variable: process-environment
+ This variable is a list of strings, each describing one environment
+ variable. The functions `getenv' and `setenv' work by means of
+ this variable.
+
+ process-environment
+ => ("l=/usr/stanford/lib/gnuemacs/lisp"
+ "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
+ "USER=lewis"
+ "TERM=ibmapa16"
+ "SHELL=/bin/csh"
+ "HOME=/user/lewis")
+
+ - Variable: path-separator
+ This variable holds a string which says which character separates
+ directories in a search path (as found in an environment
+ variable). Its value is `":"' for Unix and GNU systems, and `";"'
+ for MS-DOS and Windows NT.
+
+ - Variable: invocation-name
+ This variable holds the program name under which Emacs was
+ invoked. The value is a string, and does not include a directory
+ name.
+
+ - Variable: invocation-directory
+ This variable holds the directory from which the Emacs executable
+ was invoked, or perhaps `nil' if that directory cannot be
+ determined.
+
+ - Variable: installation-directory
+ If non-`nil', this is a directory within which to look for the
+ `lib-src' and `etc' subdirectories. This is non-`nil' when Emacs
+ can't find those directories in their standard installed
+ locations, but can find them in a directory related somehow to the
+ one containing the Emacs executable.
+
+ - Function: load-average &optional use-floats
+ This function returns a list of the current 1-minute, 5-minute and
+ 15-minute load averages. The values are integers that are 100
+ times the system load averages. (The load averages indicate the
+ number of processes trying to run.)
+
+ When USE-FLOATS is non-`nil', floats will be returned instead of
+ integers. These floats are not multiplied by 100.
+
+ (load-average)
+ => (169 158 164)
+ (load-average t)
+ => (1.69921875 1.58984375 1.640625)
+
+ lewis@rocky[5] % uptime
+ 8:06pm up 16 day(s), 21:57, 40 users,
+ load average: 1.68, 1.59, 1.64
+
+ If the 5-minute or 15-minute load averages are not available,
+ return a shortened list, containing only those averages which are
+ available.
+
+ On some systems, this function may require special privileges to
+ run, or it may be unimplemented for the particular system type.
+ In that case, the function will signal an error.
+
+ - Function: emacs-pid
+ This function returns the process ID of the Emacs process.
+
+ - Function: setprv privilege-name &optional setp getprv
+ This function sets or resets a VMS privilege. (It does not exist
+ on Unix.) The first arg is the privilege name, as a string. The
+ second argument, SETP, is `t' or `nil', indicating whether the
+ privilege is to be turned on or off. Its default is `nil'. The
+ function returns `t' if successful, `nil' otherwise.
+
+ If the third argument, GETPRV, is non-`nil', `setprv' does not
+ change the privilege, but returns `t' or `nil' indicating whether
+ the privilege is currently enabled.
\1f
-File: lispref.info, Node: LDAP Support, Next: Internationalization, Prev: ToolTalk Support, Up: Top
+File: lispref.info, Node: User Identification, Next: Time of Day, Prev: System Environment, Up: System Interface
-LDAP Support
-************
+User Identification
+===================
- XEmacs can be linked with a LDAP client library to provide Elisp
-primitives to access directory servers using the Lightweight Directory
-Access Protocol.
+ - 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.
-* Menu:
+ - 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.
-* Building XEmacs with LDAP support:: How to add LDAP support to XEmacs
-* XEmacs LDAP API:: Lisp access to LDAP functions
-* Syntax of Search Filters:: A brief summary of RFC 1558
+ If you specify UID, the value is the user name that corresponds to
+ UID (which should be an integer).
-\1f
-File: lispref.info, Node: Building XEmacs with LDAP support, Next: XEmacs LDAP API, Prev: LDAP Support, Up: LDAP Support
+ (user-login-name)
+ => "lewis"
-Building XEmacs with LDAP support
-=================================
+ - 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'.
- LDAP support must be added to XEmacs at build time since it requires
-linking to an external LDAP client library. As of 21.2, XEmacs has been
-successfully built and tested with
+ - 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.
- * OpenLDAP 1.0.3 (<http://www.openldap.org/>)
+ - 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.
- * University of Michigan's LDAP 3.3
- (<http://www.umich.edu/~dirsvcs/ldap/>)
+ If USER is specified explicitly, `user-full-name' variable is
+ ignored.
- * LDAP SDK 1.0 from Netscape Corp. (<http://developer.netscape.com/>)
+ (user-full-name)
+ => "Hrvoje Niksic"
+ (setq user-full-name "Hrvoje \"Niksa\" Niksic")
+ (user-full-name)
+ => "Hrvoje \"Niksa\" Niksic"
+ (user-full-name "hniksic")
+ => "Hrvoje Niksic"
- Other libraries conforming to RFC 1823 will probably work also but
-may require some minor tweaking at C level.
+ 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::).
- The standard XEmacs configure script autodetects an installed LDAP
-library provided the library itself and the corresponding header files
-can be found in the library and include paths. A successful detection
-will be signalled in the final output of the configure script.
+ - Function: user-real-uid
+ This function returns the real UID of the user.
-\1f
-File: lispref.info, Node: XEmacs LDAP API, Next: Syntax of Search Filters, Prev: Building XEmacs with LDAP support, Up: LDAP Support
+ (user-real-uid)
+ => 19
-XEmacs LDAP API
-===============
+ - Function: user-uid
+ This function returns the effective UID of the user.
- XEmacs LDAP API consists of two layers: a low-level layer which
-tries to stay as close as possible to the C API (where practical) and a
-higher-level layer which provides more convenient primitives to
-effectively use LDAP.
+ - 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:
- As of XEmacs 21.0, only interfaces to basic LDAP search functions are
-provided, broader support is planned in future versions.
+ 1. Return the value of "`(getenv "HOME")'", if set.
-* Menu:
+ 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.)
-* LDAP Variables:: Lisp variables related to LDAP
-* The High-Level LDAP API:: High-level LDAP lisp functions
-* The Low-Level LDAP API:: Low-level LDAP lisp primitives
+ Under MS Windows, this is done:
-\1f
-File: lispref.info, Node: LDAP Variables, Next: The High-Level LDAP API, Prev: XEmacs LDAP API, Up: XEmacs LDAP API
+ 1. Return the value of "`(getenv "HOME")'", if set.
-LDAP Variables
---------------
+ 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%'.
- - Variable: ldap-default-host
- The default LDAP server hostname. A TCP port number can be
- appended to that name using a colon as a separator.
-
- - Variable: ldap-default-port
- Default TCP port for LDAP connections. Initialized from the LDAP
- library. Default value is 389.
-
- - Variable: ldap-default-base
- Default base for LDAP searches. This is a string using the syntax
- of RFC 1779. For instance, "o¬ME, cÿ" limits the search to the
- Acme organization in the United States.
-
- - Variable: ldap-host-parameters-alist
- An alist of per host options for LDAP transactions. The list
- elements look like `(HOST PROP1 VAL1 PROP2 VAL2 ...)' HOST is the
- name of an LDAP server. A TCP port number can be appended to that
- name using a colon as a separator. PROPN and VALN are
- property/value pairs describing parameters for the server. Valid
- properties:
- `binddn'
- The distinguished name of the user to bind as. This may look
- like `cÿ, o¬me, cnÿnny Bugs', see RFC 1779 for details.
-
- `passwd'
- The password to use for authentication.
-
- `auth'
- The authentication method to use, possible values depend on
- the LDAP library XEmacs was compiled with, they may include
- `simple', `krbv41' and `krbv42'.
-
- `base'
- The base for the search. This may look like `cÿ, o¬me', see
- RFC 1779 for syntax details.
-
- `scope'
- One of the symbols `base', `onelevel' or `subtree' indicating
- the scope of the search limited to a base object, to a single
- level or to the whole subtree.
-
- `deref'
- The dereference policy is one of the symbols `never',
- `always', `search' or `find' and defines how aliases are
- dereferenced.
- `never'
- Aliases are never dereferenced
-
- `always'
- Aliases are always dereferenced
-
- `search'
- Aliases are dereferenced when searching
-
- `find'
- Aliases are dereferenced when locating the base object
- for the search
-
- `timelimit'
- The timeout limit for the connection in seconds.
-
- `sizelimit'
- The maximum number of matches to return for searches
- performed on this connection.
+ 3. Return "C:\", as a fallback, but issue a warning.
\1f
-File: lispref.info, Node: The High-Level LDAP API, Next: The Low-Level LDAP API, Prev: LDAP Variables, Up: XEmacs LDAP API
+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::).
-The High-Level LDAP API
------------------------
+\1f
+File: lispref.info, Node: Time Conversion, Next: Timers, Prev: Time of Day, Up: System Interface
+
+Time Conversion
+===============
- As of this writing the high-level Lisp LDAP API only provides for
-LDAP searches. Further support is planned in the future.
+ 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::).
- The `ldap-search' function provides the most convenient interface to
-perform LDAP searches. It opens a connection to a host, performs the
-query and cleanly closes the connection thus insulating the user from
-all the details of the low-level interface such as LDAP Lisp objects
-*note The Low-Level LDAP API::
+ - 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:
- - Function: ldap-search filter &optional host attributes attrsonly
- Perform an LDAP search. FILTER is the search filter *note Syntax
- of Search Filters:: HOST is the LDAP host on which to perform the
- search ATTRIBUTES is the specific attributes to retrieve, `nil'
- means retrieve all ATTRSONLY if non-`nil' retrieves the attributes
- only without their associated values. Additional search
- parameters can be specified through `ldap-host-parameters-alist'.
+ `%a'
+ This stands for the abbreviated name of the day of week.
-\1f
-File: lispref.info, Node: The Low-Level LDAP API, Prev: The High-Level LDAP API, Up: XEmacs LDAP API
+ `%A'
+ This stands for the full name of the day of week.
-The Low-Level LDAP API
-----------------------
+ `%b'
+ This stands for the abbreviated name of the month.
-* Menu:
+ `%B'
+ This stands for the full name of the month.
-* The LDAP Lisp Object::
-* Opening and Closing a LDAP Connection::
-* Searching on a LDAP Server (Low-level)::
+ `%c'
+ This is a synonym for `%x %X'.
-\1f
-File: lispref.info, Node: The LDAP Lisp Object, Next: Opening and Closing a LDAP Connection, Prev: The Low-Level LDAP API, Up: The Low-Level LDAP API
+ `%C'
+ This has a locale-specific meaning. In the default locale
+ (named C), it is equivalent to `%A, %B %e, %Y'.
-The LDAP Lisp Object
-....................
+ `%d'
+ This stands for the day of month, zero-padded.
- An internal built-in `ldap' lisp object represents a LDAP connection.
+ `%D'
+ This is a synonym for `%m/%d/%y'.
- - Function: ldapp object
- This function returns non-`nil' if OBJECT is a `ldap' object.
+ `%e'
+ This stands for the day of month, blank-padded.
- - Function: ldap-host ldap
- Return the server host of the connection represented by LDAP
+ `%h'
+ This is a synonym for `%b'.
- - Function: ldap-live-p ldap
- Return non-`nil' if LDAP is an active LDAP connection
+ `%H'
+ This stands for the hour (00-23).
-\1f
-File: lispref.info, Node: Opening and Closing a LDAP Connection, Next: Searching on a LDAP Server (Low-level), Prev: The LDAP Lisp Object, Up: The Low-Level LDAP API
+ `%I'
+ This stands for the hour (00-12).
-Opening and Closing a LDAP Connection
-.....................................
+ `%j'
+ This stands for the day of the year (001-366).
- - Function: ldap-open host &optional plist
- Open a LDAP connection to HOST. PLIST is a property list
- containing additional parameters for the connection. Valid keys
- in that list are:
- `port'
- The TCP port to use for the connection if different from
- `ldap-default-port' or the library builtin value
+ `%k'
+ This stands for the hour (0-23), blank padded.
- `auth'
- The authentication method to use, possible values depend on
- the LDAP library XEmacs was compiled with, they may include
- `simple', `krbv41' and `krbv42'.
+ `%l'
+ This stands for the hour (1-12), blank padded.
- `binddn'
- The distinguished name of the user to bind as. This may look
- like `cÿ, o¬me, cnÿnny Bugs', see RFC 1779 for details.
+ `%m'
+ This stands for the month (01-12).
- `passwd'
- The password to use for authentication.
+ `%M'
+ This stands for the minute (00-59).
- `deref'
- The dereference policy is one of the symbols `never',
- `always', `search' or `find' and defines how aliases are
- dereferenced.
- `never'
- Aliases are never dereferenced
+ `%n'
+ This stands for a newline.
- `always'
- Aliases are always dereferenced
+ `%p'
+ This stands for `AM' or `PM', as appropriate.
- `search'
- Aliases are dereferenced when searching
+ `%r'
+ This is a synonym for `%I:%M:%S %p'.
- `find'
- Aliases are dereferenced when locating the base object
- for the search The default is `never'.
+ `%R'
+ This is a synonym for `%H:%M'.
- `timelimit'
- The timeout limit for the connection in seconds.
+ `%S'
+ This stands for the seconds (00-60).
- `sizelimit'
- The maximum number of matches to return for searches
- performed on this connection.
+ `%t'
+ This stands for a tab character.
- - Function: ldap-close ldap
- Close the connection represented by LDAP
+ `%T'
+ This is a synonym for `%H:%M:%S'.
-\1f
-File: lispref.info, Node: Searching on a LDAP Server (Low-level), Prev: Opening and Closing a LDAP Connection, Up: The Low-Level LDAP API
-
-Searching on a LDAP Server (Low-level)
-......................................
-
- `ldap-search-internal' is the low-level primitive to perform a
-search on a LDAP server. It works directly on an open LDAP connection
-thus requiring a preliminary call to `ldap-open'. Multiple searches
-can be made on the same connection, then the session must be closed
-with `ldap-close'.
-
- - Function: ldap-search-internal ldap filter base scope attrs attrsonly
- Perform a search on an open connection LDAP created with
- `ldap-open'. FILTER is a filter string for the search *note
- Syntax of Search Filters:: BASE is the distinguished name at which
- to start the search. SCOPE is one of the symbols `base',
- `onelevel' or `subtree' indicating the scope of the search limited
- to a base object, to a single level or to the whole subtree. The
- default is `subtree'. `attrs' is a list of strings indicating
- which attributes to retrieve for each matching entry. If `nil' all
- available attributes are returned. If `attrsonly' is non-`nil'
- then only the attributes are retrieved, not their associated values
- The function returns a list of matching entries. Each entry being
- itself an alist of attribute/values.
+ `%U'
+ This stands for the week of the year (01-52), assuming that
+ weeks start on Sunday.
-\1f
-File: lispref.info, Node: Syntax of Search Filters, Prev: XEmacs LDAP API, Up: LDAP Support
+ `%w'
+ This stands for the numeric day of week (0-6). Sunday is day
+ 0.
-Syntax of Search Filters
-========================
+ `%W'
+ This stands for the week of the year (01-52), assuming that
+ weeks start on Monday.
- LDAP search functions use RFC1558 syntax to describe the search
-filter. In that syntax simple filters have the form:
+ `%x'
+ This has a locale-specific meaning. In the default locale
+ (named C), it is equivalent to `%D'.
- (<attr> <filtertype> <value>)
+ `%X'
+ This has a locale-specific meaning. In the default locale
+ (named C), it is equivalent to `%T'.
- `<attr>' is an attribute name such as `cn' for Common Name, `o' for
-Organization, etc...
+ `%y'
+ This stands for the year without century (00-99).
- `<value>' is the corresponding value. This is generally an exact
-string but may also contain `*' characters as wildcards
+ `%Y'
+ This stands for the year with century.
- `filtertype' is one `=' `~=', `<=', `>=' which respectively describe
-equality, approximate equality, inferiority and superiority.
+ `%Z'
+ This stands for the time zone abbreviation.
- Thus `(cn=John Smith)' matches all records having a canonical name
-equal to John Smith.
+ - Function: decode-time time
+ This function converts a time value into calendrical information.
+ The return value is a list of nine elements, as follows:
- A special case is the presence filter `(<attr>=*' which matches
-records containing a particular attribute. For instance `(mail=*)'
-matches all records containing a `mail' attribute.
+ (SECONDS MINUTES HOUR DAY MONTH YEAR DOW DST ZONE)
- Simple filters can be connected together with the logical operators
-`&', `|' and `!' which stand for the usual and, or and not operators.
+ Here is what the elements mean:
- `(&(objectClass=Person)(mail=*)(|(sn=Smith)(givenname=John)))'
-matches records of class `Person' containing a `mail' attribute and
-corresponding to people whose last name is `Smith' or whose first name
-is `John'.
+ SEC
+ The number of seconds past the minute, as an integer between
+ 0 and 59.
-\1f
-File: lispref.info, Node: Internationalization, Next: MULE, Prev: LDAP Support, Up: Top
+ MINUTE
+ The number of minutes past the hour, as an integer between 0
+ and 59.
-Internationalization
-********************
+ HOUR
+ The hour of the day, as an integer between 0 and 23.
-* Menu:
+ DAY
+ The day of the month, as an integer between 1 and 31.
-* I18N Levels 1 and 2:: Support for different time, date, and currency formats.
-* I18N Level 3:: Support for localized messages.
-* I18N Level 4:: Support for Asian languages.
+ MONTH
+ The month of the year, as an integer between 1 and 12.
-\1f
-File: lispref.info, Node: I18N Levels 1 and 2, Next: I18N Level 3, Up: Internationalization
+ YEAR
+ The year, an integer typically greater than 1900.
-I18N Levels 1 and 2
-===================
+ DOW
+ The day of week, as an integer between 0 and 6, where 0
+ stands for Sunday.
- XEmacs is now compliant with I18N levels 1 and 2. Specifically,
-this means that it is 8-bit clean and correctly handles time and date
-functions. XEmacs will correctly display the entire ISO-Latin 1
-character set.
+ DST
+ `t' if daylight savings time is effect, otherwise `nil'.
- The compose key may now be used to create any character in the
-ISO-Latin 1 character set not directly available via the keyboard.. In
-order for the compose key to work it is necessary to load the file
-`x-compose.el'. At any time while composing a character, `C-h' will
-display all valid completions and the character which would be produced.
+ ZONE
+ An integer indicating the time zone, as the number of seconds
+ east of Greenwich.
-\1f
-File: lispref.info, Node: I18N Level 3, Next: I18N Level 4, Prev: I18N Levels 1 and 2, Up: Internationalization
+ Note that Common Lisp has different meanings for DOW and ZONE.
-I18N Level 3
-============
+ - 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'.
-* Menu:
+ 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'.
-* Level 3 Basics::
-* Level 3 Primitives::
-* Dynamic Messaging::
-* Domain Specification::
-* Documentation String Extraction::
+ The optional argument ZONE defaults to the current time zone and
+ its daylight savings time rules. If specified, it can be either a
+ list (as you would get from `current-time-zone') or an integer (as
+ you would get from `decode-time'). The specified zone is used
+ without any further alteration for daylight savings time.
\1f
-File: lispref.info, Node: Level 3 Basics, Next: Level 3 Primitives, Up: I18N Level 3
+File: lispref.info, Node: Timers, Next: Terminal Input, Prev: Time Conversion, Up: System Interface
+
+Timers for Delayed Execution
+============================
+
+ You can set up a timer to call a function at a specified future time.
+
+ - Function: add-timeout secs function object &optional resignal
+ This function adds a timeout, to be signaled after the timeout
+ period has elapsed. SECS is a number of seconds, expressed as an
+ integer or a float. FUNCTION will be called after that many
+ seconds have elapsed, with one argument, the given OBJECT. If the
+ optional RESIGNAL argument is provided, then after this timeout
+ expires, `add-timeout' will automatically be called again with
+ RESIGNAL as the first argument.
+
+ This function returns an object which is the "id" of this
+ particular timeout. You can pass that object to `disable-timeout'
+ to turn off the timeout before it has been signalled.
+
+ The number of seconds may be expressed as a floating-point number,
+ in which case some fractional part of a second will be used.
+ Caveat: the usable timeout granularity will vary from system to
+ system.
+
+ Adding a timeout causes a timeout event to be returned by
+ `next-event', and the function will be invoked by
+ `dispatch-event', so if XEmacs is in a tight loop, the function
+ will not be invoked until the next call to sit-for or until the
+ return to top-level (the same is true of process filters).
+
+ WARNING: if you are thinking of calling add-timeout from inside of
+ a callback function as a way of resignalling a timeout, think
+ again. There is a race condition. That's why the RESIGNAL
+ argument exists.
+
+ (NOTE: In FSF Emacs, this function is called `run-at-time' and has
+ different semantics.)
+
+ - Function: disable-timeout id
+ Cancel the requested action for ID, which should be a value
+ previously returned by `add-timeout'. This cancels the effect of
+ that call to `add-timeout'; the arrival of the specified time will
+ not cause anything special to happen. (NOTE: In FSF Emacs, this
+ function is called `cancel-timer'.)
-Level 3 Basics
---------------
+\1f
+File: lispref.info, Node: Terminal Input, Next: Terminal Output, Prev: Timers, Up: System Interface
- XEmacs now provides alpha-level functionality for I18N Level 3.
-This means that everything necessary for full messaging is available,
-but not every file has been converted.
+Terminal Input
+==============
- The two message files which have been created are `src/emacs.po' and
-`lisp/packages/mh-e.po'. Both files need to be converted using
-`msgfmt', and the resulting `.mo' files placed in some locale's
-`LC_MESSAGES' directory. The test "translations" in these files are
-the original messages prefixed by `TRNSLT_'.
+ This section describes functions and variables for recording or
+manipulating terminal input. See *Note Display::, for related
+functions.
+
+* Menu:
- The domain for a variable is stored on the variable's property list
-under the property name VARIABLE-DOMAIN. The function
-`documentation-property' uses this information when translating a
-variable's documentation.
+* 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.
projects / chise / xemacs-chise.git- / blobdiff