X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-41;h=db6a20fd80e4de34f3c60da508c656f829b1c552;hb=70241ad4f7ff48fd1aa7c62c4b72fa18463f6aee;hp=a0cdfc28811d669b1eef93ce5033aa25f7d86e44;hpb=f52a96980ed9280f8f906a20d4b899dc0b027644;p=chise%2Fxemacs-chise.git diff --git a/info/lispref.info-41 b/info/lispref.info-41 index a0cdfc2..db6a20f 100644 --- a/info/lispref.info-41 +++ b/info/lispref.info-41 @@ -1,4 +1,4 @@ -This is ../info/lispref.info, produced by makeinfo version 4.0 from +This is ../info/lispref.info, produced by makeinfo version 4.0b from lispref/lispref.texi. INFO-DIR-SECTION XEmacs Editor @@ -50,904 +50,1225 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  -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_' 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. +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. + + `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::.) + + - Command: getenv var &optional interactivep + 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'. + + When invoked interactively, `getenv' prints the value in the echo + area. + + (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 &optional value unset + 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 + manipulating 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.  -File: lispref.info, Node: Receiving Messages, Prev: Sending Messages, Up: ToolTalk Support +File: lispref.info, Node: User Identification, Next: Time of Day, Prev: System Environment, Up: System Interface -Receiving Messages -================== +User Identification +=================== -* Menu: + - 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. -* Example of Receiving Messages:: -* Elisp Interface for Receiving Messages:: + - 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. - -File: lispref.info, Node: Example of Receiving Messages, Next: Elisp Interface for Receiving Messages, Up: Receiving Messages + If you specify UID, the value is the user name that corresponds to + UID (which should be an integer). -Example of Receiving Messages ------------------------------ + (user-login-name) + => "lewis" - 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. + - 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'. - (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)) + - 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. - -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. + - 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. - -File: lispref.info, Node: LDAP Support, Next: PostgreSQL Support, Prev: ToolTalk Support, Up: Top + If USER is specified explicitly, `user-full-name' variable is + ignored. -LDAP Support -************ + (user-full-name) + => "Hrvoje Niksic" + (setq user-full-name "Hrvoje \"Niksa\" Niksic") + (user-full-name) + => "Hrvoje \"Niksa\" Niksic" + (user-full-name "hniksic") + => "Hrvoje Niksic" - XEmacs can be linked with a LDAP client library to provide Elisp -primitives to access directory servers using the Lightweight Directory -Access Protocol. + 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::). -* Menu: + - Function: user-real-uid + This function returns the real UID of the user. -* 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 + (user-real-uid) + => 19 - -File: lispref.info, Node: Building XEmacs with LDAP support, Next: XEmacs LDAP API, Prev: LDAP Support, Up: LDAP Support + - Function: user-uid + This function returns the effective UID of the user. + + - Function: user-home-directory + This function returns the "`HOME'" directory of the user, and is + intended to replace occurrences of "`(getenv "HOME")'". Under + Unix systems, the following is done: -Building XEmacs with LDAP support -================================= + 1. Return the value of "`(getenv "HOME")'", if set. - 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 + 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.) - * OpenLDAP 1.2 () + Under MS Windows, this is done: - * University of Michigan's LDAP 3.3 - () + 1. Return the value of "`(getenv "HOME")'", if set. - * LDAP SDK 1.0 from Netscape Corp. () + 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%'. - Other libraries conforming to RFC 1823 will probably work also but -may require some minor tweaking at C level. + 3. Return "C:\", as a fallback, but issue a warning. - The standard XEmacs configure script auto-detects 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. + +File: lispref.info, Node: Time of Day, Next: Time Conversion, Prev: User Identification, Up: System Interface + +Time of Day +=========== + + This section explains how to determine the current time and the time +zone. + + - Function: current-time-string &optional time-value + This function returns the current time and date as a + humanly-readable string. The format of the string is unvarying; + the number of characters used for each part is always the same, so + you can reliably use `substring' to extract pieces of it. It is + wise to count the characters from the beginning of the string + rather than from the end, as additional information may be added + at the end. + + The argument TIME-VALUE, if given, specifies a time to format + instead of the current time. The argument should be a list whose + first two elements are integers. Thus, you can use times obtained + from `current-time' (see below) and from `file-attributes' (*note + File Attributes::). + + (current-time-string) + => "Wed Oct 14 22:21:05 1987" + + - Function: current-time + This function returns the system's time value as a list of three + integers: `(HIGH LOW MICROSEC)'. The integers HIGH and LOW + combine to give the number of seconds since 0:00 January 1, 1970, + which is HIGH * 2**16 + LOW. + + The third element, MICROSEC, gives the microseconds since the + start of the current second (or 0 for systems that return time + only on the resolution of a second). + + The first two elements can be compared with file time values such + as you get with the function `file-attributes'. *Note File + Attributes::. + + - Function: current-time-zone &optional time-value + This function returns a list describing the time zone that the + user is in. + + The value has the form `(OFFSET NAME)'. Here OFFSET is an integer + giving the number of seconds ahead of UTC (east of Greenwich). A + negative value means west of Greenwich. The second element, NAME + is a string giving the name of the time zone. Both elements + change when daylight savings time begins or ends; if the user has + specified a time zone that does not use a seasonal time + adjustment, then the value is constant through time. + + If the operating system doesn't supply all the information + necessary to compute the value, both elements of the list are + `nil'. + + The argument TIME-VALUE, if given, specifies a time to analyze + instead of the current time. The argument should be a cons cell + containing two integers, or a list whose first two elements are + integers. Thus, you can use times obtained from `current-time' + (see above) and from `file-attributes' (*note File Attributes::).  -File: lispref.info, Node: XEmacs LDAP API, Next: Syntax of Search Filters, Prev: Building XEmacs with LDAP support, Up: LDAP Support +File: lispref.info, Node: Time Conversion, Next: Timers, Prev: Time of Day, Up: System Interface -XEmacs LDAP API +Time Conversion =============== - 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. + 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 low-level API should be used directly for very specific purposes -(such as multiple operations on a connection) only. The higher-level -functions provide a more convenient way to access LDAP directories -hiding the subtleties of handling the connection, translating arguments -and ensuring compliance with LDAP internationalization rules and formats -(currently partly implemented only). + - 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: -* Menu: + `%a' + This stands for the abbreviated name of the day of week. -* 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 -* LDAP Internationalization:: I18n variables and functions + `%A' + This stands for the full name of the day of week. - -File: lispref.info, Node: LDAP Variables, Next: The High-Level LDAP API, Prev: XEmacs LDAP API, Up: XEmacs LDAP API - -LDAP Variables --------------- - - - 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=ACME, c=US" 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 `cn=Babs Jensen,o=ACME,c=US', 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. - - - Variable: ldap-verbose - If non-`nil', LDAP operations will echo progress messages. - Defaults to `nil'. + `%b' + This stands for the abbreviated name of the month. - -File: lispref.info, Node: The High-Level LDAP API, Next: The Low-Level LDAP API, Prev: LDAP Variables, Up: XEmacs LDAP API + `%B' + This stands for the full name of the month. -The High-Level LDAP API ------------------------ + `%c' + This is a synonym for `%x %X'. - The following functions provide the most convenient interface to -perform LDAP operations. All of them open a connection to a host, -perform an operation (add/search/modify/delete) on one or several -entries and cleanly close 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::. - - Note that `ldap-search' which used to be the name of the high-level -search function in XEmacs 21.1 is now obsolete. For consistency in the -naming as well as backward compatibility, that function now acts as a -wrapper that calls either `ldap-search-basic' (low-level search -function) or `ldap-search-entries' (high-level search function) -according to the actual parameters. A direct call to one of these two -functions is preferred since it is faster and unambiguous. - - - Function: ldap-search-entries filter &optional host attributes - attrsonly withdn - 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. If WITHDN is - non-`nil' each entry in the result will be prepended with its - distinguished name DN. Additional search parameters can be - specified through `ldap-host-parameters-alist'. The function - returns a list of matching entries. Each entry is itself an alist - of attribute/value pairs optionally preceded by the DN of the - entry according to the value of WITHDN. - - - Function: ldap-add-entries entries &optional host binddn passwd - Add entries to an LDAP directory. ENTRIES is a list of entry - specifications of the form `(DN (ATTR . VALUE) (ATTR . VALUE) ...)' - where DN the distinguished name of an entry to add, the following - are cons cells containing attribute/value string pairs. HOST is - the LDAP host, defaulting to `ldap-default-host' BINDDN is the DN - to bind as to the server PASSWD is the corresponding password. - - - Function: ldap-modify-entries entry-mods &optional host binddn passwd - Modify entries of an LDAP directory. ENTRY_MODS is a list of - entry modifications of the form `(DN MOD-SPEC1 MOD-SPEC2 ...)' - where DN is the distinguished name of the entry to modify, the - following are modification specifications. A modification - specification is itself a list of the form `(MOD-OP ATTR VALUE1 - VALUE2 ...)' MOD-OP and ATTR are mandatory, VALUES are optional - depending on MOD-OP. MOD-OP is the type of modification, one of - the symbols `add', `delete' or `replace'. ATTR is the LDAP - attribute type to modify. HOST is the LDAP host, defaulting to - `ldap-default-host' BINDDN is the DN to bind as to the server - PASSWD is the corresponding password" - - - Function: ldap-delete-entries dn &optional host binddn passwd - Delete an entry from an LDAP directory. DN is the distinguished - name of an entry to delete or a list of those. HOST is the LDAP - host, defaulting to `ldap-default-host' BINDDN is the DN to bind - as to the server PASSWD is the corresponding password. + `%C' + This has a locale-specific meaning. In the default locale + (named C), it is equivalent to `%A, %B %e, %Y'. - -File: lispref.info, Node: The Low-Level LDAP API, Next: LDAP Internationalization, Prev: The High-Level LDAP API, Up: XEmacs LDAP API + `%d' + This stands for the day of month, zero-padded. -The Low-Level LDAP API ----------------------- + `%D' + This is a synonym for `%m/%d/%y'. - The low-level API should be used directly for very specific purposes -(such as multiple operations on a connection) only. The higher-level -functions provide a more convenient way to access LDAP directories -hiding the subtleties of handling the connection, translating arguments -and ensuring compliance with LDAP internationalization rules and formats -(currently partly implemented only). See *note The High-Level LDAP API:: + `%e' + This stands for the day of month, blank-padded. - Note that the former functions `ldap-*-internal' functions have been -renamed in XEmacs 21.2 + `%h' + This is a synonym for `%b'. -* Menu: + `%H' + This stands for the hour (00-23). -* The LDAP Lisp Object:: -* Opening and Closing a LDAP Connection:: -* Low-level Operations on a LDAP Server:: + `%I' + This stands for the hour (00-12). - -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 + `%j' + This stands for the day of the year (001-366). -The LDAP Lisp Object -.................... + `%k' + This stands for the hour (0-23), blank padded. - An internal built-in `ldap' lisp object represents a LDAP connection. + `%l' + This stands for the hour (1-12), blank padded. - - Function: ldapp object - This function returns non-`nil' if OBJECT is a `ldap' object. + `%m' + This stands for the month (01-12). - - Function: ldap-host ldap - Return the server host of the connection represented by LDAP + `%M' + This stands for the minute (00-59). - - Function: ldap-live-p ldap - Return non-`nil' if LDAP is an active LDAP connection + `%n' + This stands for a newline. - -File: lispref.info, Node: Opening and Closing a LDAP Connection, Next: Low-level Operations on a LDAP Server, Prev: The LDAP Lisp Object, Up: The Low-Level LDAP API + `%p' + This stands for `AM' or `PM', as appropriate. -Opening and Closing a LDAP Connection -..................................... + `%r' + This is a synonym for `%I:%M:%S %p'. - - 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 + `%R' + This is a synonym for `%H:%M'. - `auth' - The authentication method to use, possible values depend on - the LDAP library XEmacs was compiled with, they may include - `simple', `krbv41' and `krbv42'. + `%S' + This stands for the seconds (00-60). - `binddn' - The distinguished name of the user to bind as. This may look - like `c=com, o=Acme, cn=Babs Jensen', see RFC 1779 for - details. + `%t' + This stands for a tab character. - `passwd' - The password to use for authentication. + `%T' + This is a synonym for `%H:%M:%S'. - `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 + `%U' + This stands for the week of the year (01-52), assuming that + weeks start on Sunday. - `always' - Aliases are always dereferenced + `%w' + This stands for the numeric day of week (0-6). Sunday is day + 0. - `search' - Aliases are dereferenced when searching + `%W' + This stands for the week of the year (01-52), assuming that + weeks start on Monday. - `find' - Aliases are dereferenced when locating the base object - for the search The default is `never'. + `%x' + This has a locale-specific meaning. In the default locale + (named C), it is equivalent to `%D'. - `timelimit' - The timeout limit for the connection in seconds. + `%X' + This has a locale-specific meaning. In the default locale + (named C), it is equivalent to `%T'. - `sizelimit' - The maximum number of matches to return for searches - performed on this connection. + `%y' + This stands for the year without century (00-99). - - Function: ldap-close ldap - Close the connection represented by LDAP + `%Y' + This stands for the year with century. - -File: lispref.info, Node: Low-level Operations on a LDAP Server, Prev: Opening and Closing a LDAP Connection, Up: The Low-Level LDAP API - -Low-level Operations on a LDAP Server -..................................... - - `ldap-search-basic' 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-basic 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 - If `withdn' is non-`nil' then each entry in the result is - prepended with its distinguished name DN If `verbose' is non-`nil' - then progress messages are echoed The function returns a list of - matching entries. Each entry is itself an alist of - attribute/value pairs optionally preceded by the DN of the entry - according to the value of `withdn'. - - - Function: ldap-add ldap dn entry - Add ENTRY to a LDAP directory which a connection LDAP has been - opened to with `ldap-open'. DN is the distinguished name of the - entry to add. ENTRY is an entry specification, i.e., a list of - cons cells containing attribute/value string pairs. - - - Function: ldap-modify ldap dn mods - Modify an entry in an LDAP directory. LDAP is an LDAP connection - object created with `ldap-open'. DN is the distinguished name of - the entry to modify. MODS is a list of modifications to apply. A - modification is a list of the form `(MOD-OP ATTR VALUE1 VALUE2 - ...)' MOD-OP and ATTR are mandatory, VALUES are optional - depending on MOD-OP. MOD-OP is the type of modification, one of - the symbols `add', `delete' or `replace'. ATTR is the LDAP - attribute type to modify - - - Function: ldap-delete ldap dn - Delete an entry to an LDAP directory. LDAP is an LDAP connection - object created with `ldap-open'. DN is the distinguished name of - the entry to delete + `%Z' + This stands for the time zone abbreviation. + + - Function: decode-time &optional specified-time + This function converts a time value into calendrical information. + The optional SPECIFIED-TIME should be a list of (HIGH LOW . + IGNORED) or (HIGH . LOW), as from `current-time' and + `file-attributes', or `nil' to use the current time. + + The return value is a list of nine elements, as follows: + + (SECONDS MINUTES HOUR DAY MONTH YEAR DOW DST ZONE) + + Here is what the elements mean: + + SEC + The number of seconds past the minute, as an integer between + 0 and 59. + + MINUTE + The number of minutes past the hour, as an integer between 0 + and 59. + + HOUR + The hour of the day, as an integer between 0 and 23. + + DAY + The day of the month, as an integer between 1 and 31. + + MONTH + The month of the year, as an integer between 1 and 12. + + YEAR + The year, an integer typically greater than 1900. + + DOW + The day of week, as an integer between 0 and 6, where 0 + stands for Sunday. + + DST + `t' if daylight savings time is effect, otherwise `nil'. + + ZONE + An integer indicating the time zone, as the number of seconds + east of Greenwich. + + Note that Common Lisp has different meanings for DOW and ZONE. + + - 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'. + + 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'. + + 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.  -File: lispref.info, Node: LDAP Internationalization, Prev: The Low-Level LDAP API, Up: XEmacs LDAP API +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'.) -LDAP Internationalization -------------------------- + +File: lispref.info, Node: Terminal Input, Next: Terminal Output, Prev: Timers, Up: System Interface - The XEmacs LDAP API provides basic internationalization features -based on the LDAP v3 specification (essentially RFC2252 on "LDAP v3 -Attribute Syntax Definitions"). Unfortunately since there is currently -no free LDAP v3 server software, this part has not received much -testing and should be considered experimental. The framework is in -place though. +Terminal Input +============== - - Function: ldap-decode-attribute attr - Decode the attribute/value pair ATTR according to LDAP rules. The - attribute name is looked up in `ldap-attribute-syntaxes-alist' and - the corresponding decoder is then retrieved from - `ldap-attribute-syntax-decoders'' and applied on the value(s). + This section describes functions and variables for recording or +manipulating terminal input. See *Note Display::, for related +functions. * Menu: -* LDAP Internationalization Variables:: -* Encoder/Decoder Functions:: +* Input Modes:: Options for how input is processed. +* Translating Input:: Low level conversion of some characters or events + into others. +* Recording Input:: Saving histories of recent or all input events.  -File: lispref.info, Node: LDAP Internationalization Variables, Next: Encoder/Decoder Functions, Prev: LDAP Internationalization, Up: LDAP Internationalization - -LDAP Internationalization Variables -................................... - - - Variable: ldap-ignore-attribute-codings - If non-`nil', no encoding/decoding will be performed LDAP - attribute values - - - Variable: ldap-coding-system - Coding system of LDAP string values. LDAP v3 specifies the coding - system of strings to be UTF-8. You need an XEmacs with Mule - support for this. - - - Variable: ldap-default-attribute-decoder - Decoder function to use for attributes whose syntax is unknown. - Such a function receives an encoded attribute value as a string - and should return the decoded value as a string - - - Variable: ldap-attribute-syntax-encoders - A vector of functions used to encode LDAP attribute values. The - sequence of functions corresponds to the sequence of LDAP - attribute syntax object identifiers of the form - 1.3.6.1.4.1.1466.1115.121.1.* as defined in RFC2252 section 4.3.2. - As of this writing, only a few encoder functions are available. - - - Variable: ldap-attribute-syntax-decoders - A vector of functions used to decode LDAP attribute values. The - sequence of functions corresponds to the sequence of LDAP - attribute syntax object identifiers of the form - 1.3.6.1.4.1.1466.1115.121.1.* as defined in RFC2252 section 4.3.2. - As of this writing, only a few decoder functions are available. - - - Variable: ldap-attribute-syntaxes-alist - A map of LDAP attribute names to their type object id minor number. - This table is built from RFC2252 Section 5 and RFC2256 Section 5 +File: lispref.info, Node: Input Modes, Next: Translating Input, Up: Terminal Input + +Input Modes +----------- + + - Function: set-input-mode interrupt flow meta &optional quit-char + console + This function sets the mode for reading keyboard input. If + INTERRUPT is non-null, then XEmacs uses input interrupts. If it is + `nil', then it uses CBREAK mode. When XEmacs communicates + directly with X, it ignores this argument and uses interrupts if + that is the way it knows how to communicate. + + If FLOW is non-`nil', then XEmacs uses XON/XOFF (`C-q', `C-s') + flow control for output to the terminal. This has no effect except + in CBREAK mode. *Note Flow Control::. + + The default setting is system dependent. Some systems always use + CBREAK mode regardless of what is specified. + + The argument META controls support for input character codes above + 127. If META is `t', XEmacs converts characters with the 8th bit + set into Meta characters. If META is `nil', XEmacs disregards the + 8th bit; this is necessary when the terminal uses it as a parity + bit. If META is neither `t' nor `nil', XEmacs uses all 8 bits of + input unchanged. This is good for terminals using European 8-bit + character sets. + + If QUIT-CHAR is non-`nil', it specifies the character to use for + quitting. Normally this character is `C-g'. *Note Quitting::. + + The `current-input-mode' function returns the input mode settings +XEmacs is currently using. + + - Function: current-input-mode &optional console + This function returns current mode for reading keyboard input. It + returns a list, corresponding to the arguments of `set-input-mode', + of the form `(INTERRUPT FLOW META QUIT)' in which: + INTERRUPT + is non-`nil' when XEmacs is using interrupt-driven input. If + `nil', Emacs is using CBREAK mode. + + FLOW + is non-`nil' if XEmacs uses XON/XOFF (`C-q', `C-s') flow + control for output to the terminal. This value has no effect + unless INTERRUPT is non-`nil'. + + META + is `t' if XEmacs treats the eighth bit of input characters as + the meta bit; `nil' means XEmacs clears the eighth bit of + every input character; any other value means XEmacs uses all + eight bits as the basic character code. + + QUIT + is the character XEmacs currently uses for quitting, usually + `C-g'.  -File: lispref.info, Node: Encoder/Decoder Functions, Prev: LDAP Internationalization Variables, Up: LDAP Internationalization +File: lispref.info, Node: Translating Input, Next: Recording Input, Prev: Input Modes, Up: Terminal Input + +Translating Input Events +------------------------ + + This section describes features for translating input events into +other input events before they become part of key sequences. + + - Variable: function-key-map + This variable holds a keymap that describes the character sequences + sent by function keys on an ordinary character terminal. This + keymap uses the same data structure as other keymaps, but is used + differently: it specifies translations to make while reading + events. + + If `function-key-map' "binds" a key sequence K to a vector V, then + when K appears as a subsequence _anywhere_ in a key sequence, it + is replaced with the events in V. + + For example, VT100 terminals send ` O P' when the keypad PF1 + key is pressed. Therefore, we want XEmacs to translate that + sequence of events into the single event `pf1'. We accomplish + this by "binding" ` O P' to `[pf1]' in `function-key-map', + when using a VT100. + + Thus, typing `C-c ' sends the character sequence `C-c O + P'; later the function `read-key-sequence' translates this back + into `C-c ', which it returns as the vector `[?\C-c pf1]'. + + Entries in `function-key-map' are ignored if they conflict with + bindings made in the minor mode, local, or global keymaps. The + intent is that the character sequences that function keys send + should not have command bindings in their own right. + + The value of `function-key-map' is usually set up automatically + according to the terminal's Terminfo or Termcap entry, but + sometimes those need help from terminal-specific Lisp files. + XEmacs comes with terminal-specific files for many common + terminals; their main purpose is to make entries in + `function-key-map' beyond those that can be deduced from Termcap + and Terminfo. *Note Terminal-Specific::. + + Emacs versions 18 and earlier used totally different means of + detecting the character sequences that represent function keys. + + - Variable: key-translation-map + This variable is another keymap used just like `function-key-map' + to translate input events into other events. It differs from + `function-key-map' in two ways: + + * `key-translation-map' goes to work after `function-key-map' is + finished; it receives the results of translation by + `function-key-map'. + + * `key-translation-map' overrides actual key bindings. + + The intent of `key-translation-map' is for users to map one + character set to another, including ordinary characters normally + bound to `self-insert-command'. + + You can use `function-key-map' or `key-translation-map' for more +than simple aliases, by using a function, instead of a key sequence, as +the "translation" of a key. Then this function is called to compute +the translation of that key. + + The key translation function receives one argument, which is the +prompt that was specified in `read-key-sequence'--or `nil' if the key +sequence is being read by the editor command loop. In most cases you +can ignore the prompt value. + + If the function reads input itself, it can have the effect of +altering the event that follows. For example, here's how to define +`C-c h' to turn the character that follows into a Hyper character: + + (defun hyperify (prompt) + (let ((e (read-event))) + (vector (if (numberp e) + (logior (lsh 1 20) e) + (if (memq 'hyper (event-modifiers e)) + e + (add-event-modifier "H-" e)))))) + + (defun add-event-modifier (string e) + (let ((symbol (if (symbolp e) e (car e)))) + (setq symbol (intern (concat string + (symbol-name symbol)))) + (if (symbolp e) + symbol + (cons symbol (cdr e))))) + + (define-key function-key-map "\C-ch" 'hyperify) -Encoder/Decoder Functions -......................... + The `iso-transl' library uses this feature to provide a way of +inputting non-ASCII Latin-1 characters. - - Function: ldap-encode-boolean bool - A function that encodes an elisp boolean BOOL into a LDAP boolean - string representation + +File: lispref.info, Node: Recording Input, Prev: Translating Input, Up: Terminal Input - - Function: ldap-decode-boolean str - A function that decodes a LDAP boolean string representation STR - into an elisp boolean +Recording Input +--------------- - - Function: ldap-decode-string str - Decode a string STR according to `ldap-coding-system' + - Function: recent-keys &optional number + This function returns a vector containing recent input events from + the keyboard or mouse. By default, 100 events are recorded, which + is how many `recent-keys' returns. - - Function: ldap-encode-string str - Encode a string STR according to `ldap-coding-system' + All input events are included, whether or not they were used as + parts of key sequences. Thus, you always get the last 100 inputs, + not counting keyboard macros. (Events from keyboard macros are + excluded because they are less interesting for debugging; it + should be enough to see the events that invoked the macros.) - - Function: ldap-decode-address str - Decode an address STR according to `ldap-coding-system' and - replacing $ signs with newlines as specified by LDAP encoding - rules for addresses + If NUMBER is specified, not more than NUMBER events will be + returned. You may change the number of stored events using + `set-recent-keys-ring-size'. - - Function: ldap-encode-address str - Encode an address STR according to `ldap-coding-system' and - replacing newlines with $ signs as specified by LDAP encoding - rules for addresses + - Function: recent-keys-ring-size + This function returns the number of recent events stored + internally. This is also the maximum number of events + `recent-keys' can return. By default, 100 events are stored. - -File: lispref.info, Node: Syntax of Search Filters, Prev: XEmacs LDAP API, Up: LDAP Support + - Function: set-recent-keys-ring-size size + This function changes the number of events stored by XEmacs and + returned by `recent-keys'. -Syntax of Search Filters -======================== + For example, `(set-recent-keys-ring-size 250)' will make XEmacs + remember last 250 events and will make `recent-keys' return last + 250 events by default. - LDAP search functions use RFC1558 syntax to describe the search -filter. In that syntax simple filters have the form: + - Command: open-dribble-file filename + This function opens a "dribble file" named FILENAME. When a + dribble file is open, each input event from the keyboard or mouse + (but not those from keyboard macros) is written in that file. A + non-character event is expressed using its printed representation + surrounded by `<...>'. - ( ) + You close the dribble file by calling this function with an + argument of `nil'. - `' is an attribute name such as `cn' for Common Name, `o' for -Organization, etc... + This function is normally used to record the input necessary to + trigger an XEmacs bug, for the sake of a bug report. - `' is the corresponding value. This is generally an exact -string but may also contain `*' characters as wildcards + (open-dribble-file "~/dribble") + => nil - `filtertype' is one `=' `~=', `<=', `>=' which respectively describe -equality, approximate equality, inferiority and superiority. + See also the `open-termscript' function (*note Terminal Output::). - Thus `(cn=John Smith)' matches all records having a canonical name -equal to John Smith. + +File: lispref.info, Node: Terminal Output, Next: Flow Control, Prev: Terminal Input, Up: System Interface + +Terminal Output +=============== - A special case is the presence filter `(=*' which matches -records containing a particular attribute. For instance `(mail=*)' -matches all records containing a `mail' attribute. + 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 device baud-rate + This function sets the output speed of DEVICE. See + `device-baud-rate'. DEVICE defaults to the selected device + (usually the only device) if `nil'. + + - 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 + + - Command: open-termscript filename + This function is used to open a "termscript file" that will record + all the characters sent by XEmacs to the terminal. (If there are + multiple tty or stream devices, all characters sent to all such + devices are recorded.) The function returns `nil'. Termscript + files are useful for investigating problems where XEmacs garbles + the screen, problems that are due to incorrect Termcap entries or + to undesirable settings of terminal options more often than to + actual XEmacs bugs. Once you are certain which characters were + actually output, you can determine reliably whether they + correspond to the Termcap specifications in use. + + A `nil' value for FILENAME stops recording terminal output. + + See also `open-dribble-file' in *Note Terminal Input::. + + (open-termscript "../junk/termscript") + => nil - Simple filters can be connected together with the logical operators -`&', `|' and `!' which stand for the usual and, or and not operators. + +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'. + + - Command: enable-flow-control &optional argument + 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::). + + With optional argument ARGUMENT (interactively the prefix + argument), enable flow control mode if ARGUMENT is positive; else + disable it. + + 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::. - `(&(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'. + +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. + + - 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.  -File: lispref.info, Node: PostgreSQL Support, Next: Internationalization, Prev: LDAP Support, Up: Top +File: lispref.info, Node: X-Windows, Next: ToolTalk Support, Prev: System Interface, Up: Top -PostgreSQL Support -****************** +Functions Specific to the X Window System +***************************************** - XEmacs can be linked with PostgreSQL libpq run-time support to -provide relational database access from Emacs Lisp code. + 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. * Menu: -* Building XEmacs with PostgreSQL support:: -* XEmacs PostgreSQL libpq API:: -* XEmacs PostgreSQL libpq Examples:: +* 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.  -File: lispref.info, Node: Building XEmacs with PostgreSQL support, Next: XEmacs PostgreSQL libpq API, Up: PostgreSQL Support - -Building XEmacs with PostgreSQL support -======================================= - - XEmacs PostgreSQL support requires linking to the PostgreSQL libpq.so -library. Describing how to build and install PostgreSQL is beyond the -scope of this document, see the PostgreSQL manual for details. - - If you have installed XEmacs from one of the binary kits on -(), or are using an XEmacs binary from a CD ROM, -you should have XEmacs PostgreSQL support by default. If you are -building XEmacs from source on a Linux system with PostgreSQL installed -into the default location, it should be autodetected when you run -configure. If you have installed PostgreSQL into its non-Linux default -location, `/usr/local/pgsql', you must specify -`--site-prefixes=/usr/local/pgsql' when you run configure. If you -installed PostgreSQL into another location, use that instead of -`/usr/local/pgsql' when specifying `--site-prefixes'. - - As of XEmacs 21.2, PostgreSQL versions 6.5.3 and 7.0 are supported. -XEmacs Lisp support for V7.0 is somewhat more extensive than support for -V6.5. In particular, asynchronous queries are supported. +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 &optional push + This function stores STRING into the first cut buffer (cut buffer + 0). + + Normally, the contents of the first cut buffer are simply replaced + by STRING. However, if optional argument PUSH is non-`nil', the + cut buffers are rotated. This means that the previous value of + the first cut buffer moves to the second cut buffer, and the + second to the third, and so on, moving the other values down + through the series of cut buffers, kill-ring-style. There are 8 + cut buffers altogether. + + Cut buffers are considered obsolete; you should use selections + instead. + + This function has no effect if support for cut buffers was not + compiled in. + + This function is called `x-set-cut-buffer' in FSF Emacs.  -File: lispref.info, Node: XEmacs PostgreSQL libpq API, Next: XEmacs PostgreSQL libpq Examples, Prev: Building XEmacs with PostgreSQL support, Up: PostgreSQL Support - -XEmacs PostgreSQL libpq API -=========================== - - XEmacs PostgreSQL API is intended to be a policy-free, low-level -binding to libpq. The intent is to provide all the basic functionality -and then let high level Lisp code decide its own policies. - - This documentation assumes that the reader has knowledge of SQL, but -requires no prior knowledge of libpq. - - There are many examples in this manual and some setup will be -required. In order to run most of the following examples, the -following code needs to be executed. In addition to the data is in -this table, nearly all of the examples will assume that the free -variable `P' refers to this database connection. The examples in the -original edition of this manual were run against Postgres 7.0beta1. - - (progn - (setq P (pq-connectdb "")) - ;; id is the primary key, shikona is a Japanese word that - ;; means `the professional name of a Sumo wrestler', and - ;; rank is the Sumo rank name. - (pq-exec P (concat "CREATE TABLE xemacs_test" - " (id int, shikona text, rank text);")) - (pq-exec P "COPY xemacs_test FROM stdin;") - (pq-put-line P "1\tMusashimaru\tYokuzuna\n") - (pq-put-line P "2\tDejima\tOozeki\n") - (pq-put-line P "3\tMusoyama\tSekiwake\n") - (pq-put-line P "4\tMiyabiyama\tSekiwake\n") - (pq-put-line P "5\tWakanoyama\tMaegashira\n") - (pq-put-line P "\\.\n") - (pq-end-copy P)) - => nil +File: lispref.info, Node: X Server, Next: X Miscellaneous, Prev: X Selections, Up: X-Windows + +X Server +======== + + This section describes how to access and change the overall status of +the X server XEmacs is using. * Menu: -* libpq Lisp Variables:: -* libpq Lisp Symbols and DataTypes:: -* Synchronous Interface Functions:: -* Asynchronous Interface Functions:: -* Large Object Support:: -* Other libpq Functions:: -* Unimplemented libpq Functions:: +* Resources:: Getting resource values from the server. +* Server Data:: Getting info about the X server. +* Grabs:: Restricting access to the server by other apps.  -File: lispref.info, Node: libpq Lisp Variables, Next: libpq Lisp Symbols and DataTypes, Prev: XEmacs PostgreSQL libpq API, Up: XEmacs PostgreSQL libpq API +File: lispref.info, Node: Resources, Next: Server Data, Up: X Server + +Resources +--------- -libpq Lisp Variables --------------------- + - Function: default-x-device + This function return the default X device for resourcing. This is + the first-created X device that still exists. - Various Unix environment variables are used by libpq to provide -defaults to the many different parameters. In the XEmacs Lisp API, -these environment variables are bound to Lisp variables to provide more -convenient access to Lisp Code. These variables are passed to the -backend database server during the establishment of a database -connection and when the `pq-setenv' call is made. + - Function: x-get-resource name class type &optional locale device + noerror + This function retrieves a resource value from the X resource + manager. - - Variable: pg:host - Initialized from the PGHOST environment variable. The default - host to connect to. + * The first arg is the name of the resource to retrieve, such as + `"font"'. - - Variable: pg:user - Initialized from the PGUSER environment variable. The default - database user name. + * The second arg is the class of the resource to retrieve, like + `"Font"'. - - Variable: pg:options - Initialized from the PGOPTIONS environment variable. Default - additional server options. + * 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. - - Variable: pg:port - Initialized from the PGPORT environment variable. The default TCP - port to connect to. + * 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'. - - Variable: pg:tty - Initialized from the PGTTY environment variable. The default - debugging TTY. + * 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'. - Compatibility note: Debugging TTYs are turned off in the XEmacs - Lisp binding. + * 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. - - Variable: pg:database - Initialized from the PGDATABASE environment variable. The default - database to connect to. + The resource names passed to this function are looked up relative + to the locale. - - Variable: pg:realm - Initialized from the PGREALM environment variable. The default - Kerberos realm. + 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"'. - - Variable: pg:client-encoding - Initialized from the PGCLIENTENCODING environment variable. The - default client encoding. + Specifically, - Compatibility note: This variable is not present in non-Mule - XEmacsen. This variable is not present in versions of libpq prior - to 7.0. In the current implementation, client encoding is - equivalent to the `file-name-coding-system' format. + 1. If LOCALE is a buffer, a call - - Variable: pg:authtype - Initialized from the PGAUTHTYPE environment variable. The default - authentication scheme used. + `(x-get-resource "foreground" "Foreground" 'string SOME-BUFFER)' - Compatibility note: This variable is unused in versions of libpq - after 6.5. It is not implemented at all in the XEmacs Lisp - binding. + is an interface to a C call something like - - Variable: pg:geqo - Initialized from the PGGEQO environment variable. Genetic - optimizer options. + `XrmGetResource (db, "xemacs.buffer.BUFFER-NAME.foreground", + "Emacs.EmacsLocaleType.EmacsBuffer.Foreground", + "String");' - - Variable: pg:cost-index - Initialized from the PGCOSTINDEX environment variable. Cost index - options. + 2. If LOCALE is a frame, a call - - Variable: pg:cost-heap - Initialized from the PGCOSTHEAP environment variable. Cost heap - options. + `(x-get-resource "foreground" "Foreground" 'string SOME-FRAME)' - - Variable: pg:tz - Initialized from the PGTZ environment variable. Default timezone. + is an interface to a C call something like - - Variable: pg:date-style - Initialized from the PGDATESTYLE environment variable. Default - date style in returned date objects. + `XrmGetResource (db, "xemacs.frame.FRAME-NAME.foreground", + "Emacs.EmacsLocaleType.EmacsFrame.Foreground", + "String");' - - Variable: pg-coding-system - This is a variable controlling which coding system is used to - encode non-ASCII strings sent to the database. + 3. If LOCALE is a device, a call + + `(x-get-resource "foreground" "Foreground" 'string SOME-DEVICE)' + + is an interface to a C call something like + + `XrmGetResource (db, "xemacs.device.DEVICE-NAME.foreground", + "Emacs.EmacsLocaleType.EmacsDevice.Foreground", + "String");' + + 4. If LOCALE is the symbol `global', a call + + `(x-get-resource "foreground" "Foreground" 'string 'global)' + + is an interface to a C call something like + + `XrmGetResource (db, "xemacs.foreground", + "Emacs.Foreground", + "String");' + + 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. + + 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". + + - 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. + + - 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'. + + 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". + + +File: lispref.info, Node: Server Data, Next: Grabs, Prev: Resources, Up: X Server + +Data about the X Server +----------------------- - Compatibility Note: This variable is not present in InfoDock. + 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. + + - 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. + + - Function: x-server-vendor &optional device + This function returns the vendor supporting the X server DEVICE is + on. + + - 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.)