-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.
+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.