This is Info file ../../info/internals.info, produced by Makeinfo version 1.68 from the input file internals.texi. Copyright (C) 1992 - 1996 Ben Wing. Copyright (C) 1996, 1997 Sun Microsystems. Copyright (C) 1994, 1995 Free Software Foundation. Copyright (C) 1994, 1995 Board of Trustees, University of Illinois. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the Free Software Foundation instead of in the original English.  File: internals.info, Node: Basic Lisp Modules, Next: Modules for Standard Editing Operations, Prev: Low-Level Modules, Up: A Summary of the Various XEmacs Modules Basic Lisp Modules ================== size name ------- --------------------- 70167 emacsfns.h 6305 lisp-disunion.h 7086 lisp-union.h 54929 lisp.h 14235 lrecord.h 10728 symsinit.h These are the basic header files for all XEmacs modules. Each module includes `lisp.h', which brings the other header files in. `lisp.h' contains the definitions of the structures and extractor and constructor macros for the basic Lisp objects and various other basic definitions for the Lisp environment, as well as some general-purpose definitions (e.g. `min()' and `max()'). `lisp.h' includes either `lisp-disunion.h' or `lisp-union.h', depending on whether `NO_UNION_TYPE' is defined. These files define the typedef of the Lisp object itself (as described above) and the low-level macros that hide the actual implementation of the Lisp object. All extractor and constructor macros for particular types of Lisp objects are defined in terms of these low-level macros. As a general rule, all typedefs should go into the typedefs section of `lisp.h' rather than into a module-specific header file even if the structure is defined elsewhere. This allows function prototypes that use the typedef to be placed into `emacsfns.h'. Forward structure declarations (i.e. a simple declaration like `struct foo;' where the structure itself is defined elsewhere) should be placed into the typedefs section as necessary. `lrecord.h' contains the basic structures and macros that implement all record-type Lisp objects - i.e. all objects whose type is a field in their C structure, which includes all objects except the few most basic ones. `emacsfns.h' contains prototypes for most of the exported functions in the various modules. (In particular, prototypes for Lisp primitives should always go into this header file. Prototypes for other functions can either go here or in a module-specific header file, depending on how general-purpose the function is and whether it has special-purpose argument types requiring definitions not in `lisp.h'.) All initialization functions are prototyped in `symsinit.h'. 120478 alloc.c 1029 pure.c 2506 puresize.h The large module `alloc.c' implements all of the basic allocation and garbage collection for Lisp objects. The most commonly used Lisp objects are allocated in chunks, similar to the Blocktype data type described above; others are allocated in individually `malloc()'ed blocks. This module provides the foundation on which all other aspects of the Lisp environment sit, and is the first module initialized at startup. Note that `alloc.c' provides a series of generic functions that are not dependent on any particular object type, and interfaces to particular types of objects using a standardized interface of type-specific methods. This scheme is a fundamental principle of object-oriented programming and is heavily used throughout XEmacs. The great advantage of this is that it allows for a clean separation of functionality into different modules - new classes of Lisp objects, new event interfaces, new device types, new stream interfaces, etc. can be added transparently without affecting code anywhere else in XEmacs. Because the different subsystems are divided into general and specific code, adding a new subtype within a subsystem will in general not require changes to the generic subsystem code or affect any of the other subtypes in the subsystem; this provides a great deal of robustness to the XEmacs code. `pure.c' contains the declaration of the "purespace" array. Pure space is a hack used to place some constant Lisp data into the code segment of the XEmacs executable, even though the data needs to be initialized through function calls. (See above in section VIII for more info about this.) During startup, certain sorts of data is automatically copied into pure space, and other data is copied manually in some of the basic Lisp files by calling the function `purecopy', which copies the object if possible (this only works in temacs, of course) and returns the new object. In particular, while temacs is executing, the Lisp reader automatically copies all compiled-function objects that it reads into pure space. Since compiled-function objects are large, are never modified, and typically comprise the majority of the contents of a compiled-Lisp file, this works well. While XEmacs is running, any attempt to modify an object that resides in pure space causes an error. Objects in pure space are never garbage collected - almost all of the time, they're intended to be permanent, and in any case you can't write into pure space to set the mark bits. `puresize.h' contains the declaration of the size of the pure space array. This depends on the optional features that are compiled in, any extra purespace requested by the user at compile time, and certain other factors (e.g. 64-bit machines need more pure space because their Lisp objects are larger). The smallest size that suffices should be used, so that there's no wasted space. If there's not enough pure space, you will get an error during the build process, specifying how much more pure space is needed. 122243 eval.c 2305 backtrace.h This module contains all of the functions to handle the flow of control. This includes the mechanisms of defining functions, calling functions, traversing stack frames, and binding variables; the control primitives and other special forms such as `while', `if', `eval', `let', `and', `or', `progn', etc.; handling of non-local exits, unwind-protects, and exception handlers; entering the debugger; methods for the subr Lisp object type; etc. It does *not* include the `read' function, the `print' function, or the handling of symbols and obarrays. `backtrace.h' contains some structures related to stack frames and the flow of control. 64949 lread.c This module implements the Lisp reader and the `read' function, which converts text into Lisp objects, according to the read syntax of the objects, as described above. This is similar to the parser that is a part of all compilers. 40900 print.c This module implements the Lisp print mechanism and the `print' function and related functions. This is the inverse of the Lisp reader - it converts Lisp objects to a printed, textual representation. (Hopefully something that can be read back in using `read' to get an equivalent object.) 4518 general.c 60220 symbols.c 9966 symeval.h `symbols.c' implements the handling of symbols, obarrays, and retrieving the values of symbols. Much of the code is devoted to handling the special "symbol-value-magic" objects that define special types of variables - this includes buffer-local variables, variable aliases, variables that forward into C variables, etc. This module is initialized extremely early (right after `alloc.c'), because it is here that the basic symbols `t' and `nil' are created, and those symbols are used everywhere throughout XEmacs. `symeval.h' contains the definitions of symbol structures and the `DEFVAR_LISP()' and related macros for declaring variables. 48973 data.c 25694 floatfns.c 71049 fns.c These modules implement the methods and standard Lisp primitives for all the basic Lisp object types other than symbols (which are described above). `data.c' contains all the predicates (primitives that return whether an object is of a particular type); the integer arithmetic functions; and the basic accessor and mutator primitives for the various object types. `fns.c' contains all the standard predicates for working with sequences (where, abstractly speaking, a sequence is an ordered set of objects, and can be represented by a list, string, vector, or bit-vector); it also contains `equal', perhaps on the grounds that bulk of the operation of `equal' is comparing sequences. `floatfns.c' contains methods and primitives for floats and floating-point arithmetic. 23555 bytecode.c 3358 bytecode.h `bytecode.c' implements the byte-code interpreter, and `bytecode.h' contains associated structures. Note that the byte-code *compiler* is written in Lisp.  File: internals.info, Node: Modules for Standard Editing Operations, Next: Editor-Level Control Flow Modules, Prev: Basic Lisp Modules, Up: A Summary of the Various XEmacs Modules Modules for Standard Editing Operations ======================================= size name ------- --------------------- 82900 buffer.c 60964 buffer.h 6059 bufslots.h `buffer.c' implements the "buffer" Lisp object type. This includes functions that create and destroy buffers; retrieve buffers by name or by other properties; manipulate lists of buffers (remember that buffers are permanent objects and stored in various ordered lists); retrieve or change buffer properties; etc. It also contains the definitions of all the built-in buffer-local variables (which can be viewed as buffer properties). It does *not* contain code to manipulate buffer-local variables (that's in `symbols.c', described above); or code to manipulate the text in a buffer. `buffer.h' defines the structures associated with a buffer and the various macros for retrieving text from a buffer and special buffer positions (e.g. `point', the default location for text insertion). It also contains macros for working with buffer positions and converting between their representations as character offsets and as byte offsets (under MULE, they are different, because characters can be multi-byte). It is one of the largest header files. `bufslots.h' defines the fields in the buffer structure that correspond to the built-in buffer-local variables. It is its own header file because it is included many times in `buffer.c', as a way of iterating over all the built-in buffer-local variables. 79888 insdel.c 6103 insdel.h `insdel.c' contains low-level functions for inserting and deleting text in a buffer, keeping track of changed regions for use by redisplay, and calling any before-change and after-change functions that may have been registered for the buffer. It also contains the actual functions that convert between byte offsets and character offsets. `insdel.h' contains associated headers. 10975 marker.c This module implements the "marker" Lisp object type, which conceptually is a pointer to a text position in a buffer that moves around as text is inserted and deleted, so as to remain in the same relative position. This module doesn't actually move the markers around - that's handled in `insdel.c'. This module just creates them and implements the primitives for working with them. As markers are simple objects, this does not entail much. Note that the standard arithmetic primitives (e.g. `+') accept markers in place of integers and automatically substitute the value of `marker-position' for the marker, i.e. an integer describing the current buffer position of the marker. 193714 extents.c 15686 extents.h This module implements the "extent" Lisp object type, which is like a marker that works over a range of text rather than a single position. Extents are also much more complex and powerful than markers and have a more efficient (and more algorithmically complex) implementation. The implementation is described in detail in comments in `extents.c'. The code in `extents.c' works closely with `insdel.c' so that extents are properly moved around as text is inserted and deleted. There is also code in `extents.c' that provides information needed by the redisplay mechanism for efficient operation. (Remember that extents can have display properties that affect [sometimes drastically, as in the `invisible' property] the display of the text they cover.) 60155 editfns.c `editfns.c' contains the standard Lisp primitives for working with a buffer's text, and calls the low-level functions in `insdel.c'. It also contains primitives for working with `point' (the default buffer insertion location). `editfns.c' also contains functions for retrieving various characteristics from the external environment: the current time, the process ID of the running XEmacs process, the name of the user who ran this XEmacs process, etc. It's not clear why this code is in `editfns.c'. 26081 callint.c 12577 cmds.c 2749 commands.h These modules implement the basic "interactive" commands, i.e. user-callable functions. Commands, as opposed to other functions, have special ways of getting their parameters interactively (by querying the user), as opposed to having them passed in a normal function invocation. Many commands are not really meant to be called from other Lisp functions, because they modify global state in a way that's often undesired as part of other Lisp functions. `callint.c' implements the mechanism for querying the user for parameters and calling interactive commands. The bulk of this module is code that parses the interactive spec that is supplied with an interactive command. `cmds.c' implements the basic, most commonly used editing commands: commands to move around the current buffer and insert and delete characters. These commands are implemented using the Lisp primitives defined in `editfns.c'. `commands.h' contains associated structure definitions and prototypes. 194863 regex.c 18968 regex.h 79800 search.c `search.c' implements the Lisp primitives for searching for text in a buffer, and some of the low-level algorithms for doing this. In particular, the fast fixed-string Boyer-Moore search algorithm is implemented in `search.c'. The low-level algorithms for doing regular-expression searching, however, are implemented in `regex.c' and `regex.h'. These two modules are largely independent of XEmacs, and are similar to (and based upon) the regular-expression routines used in `grep' and other GNU utilities. 20476 doprnt.c `doprnt.c' implements formatted-string processing, similar to `printf()' command in C. 15372 undo.c This module implements the undo mechanism for tracking buffer changes. Most of this could be implemented in Lisp.  File: internals.info, Node: Editor-Level Control Flow Modules, Next: Modules for the Basic Displayable Lisp Objects, Prev: Modules for Standard Editing Operations, Up: A Summary of the Various XEmacs Modules Editor-Level Control Flow Modules ================================= size name ------- --------------------- 84546 event-Xt.c 121483 event-stream.c 6658 event-tty.c 49271 events.c 14459 events.h These implement the handling of events (user input and other system notifications). `events.c' and `events.h' define the "event" Lisp object type and primitives for manipulating it. `event-stream.c' implements the basic functions for working with event queues, dispatching an event by looking it up in relevant keymaps and such, and handling timeouts; this includes the primitives `next-event' and `dispatch-event', as well as related primitives such as `sit-for', `sleep-for', and `accept-process-output'. (`event-stream.c' is one of the hairiest and trickiest modules in XEmacs. Beware! You can easily mess things up here.) `event-Xt.c' and `event-tty.c' implement the low-level interfaces onto retrieving events from Xt (the X toolkit) and from TTY's (using `read()' and `select()'), respectively. The event interface enforces a clean separation between the specific code for interfacing with the operating system and the generic code for working with events, by defining an API of basic, low-level event methods; `event-Xt.c' and `event-tty.c' are two different implementations of this API. To add support for a new operating system (e.g. NeXTstep), one merely needs to provide another implementation of those API functions. Note that the choice of whether to use `event-Xt.c' or `event-tty.c' is made at compile time! Or at the very latest, it is made at startup time. `event-Xt.c' handles events for *both* X and TTY frames; `event-tty.c' is only used when X support is not compiled into XEmacs. The reason for this is that there is only one event loop in XEmacs: thus, it needs to be able to receive events from all different kinds of frames. 129583 keymap.c 2621 keymap.h `keymap.c' and `keymap.h' define the "keymap" Lisp object type and associated methods and primitives. (Remember that keymaps are objects that associate event descriptions with functions to be called to "execute" those events; `dispatch-event' looks up events in the relevant keymaps.) 25212 keyboard.c `keyboard.c' contains functions that implement the actual editor command loop - i.e. the event loop that cyclically retrieves and dispatches events. This code is also rather tricky, just like `event-stream.c'. 9973 macros.c 1397 macros.h These two modules contain the basic code for defining keyboard macros. These functions don't actually do much; most of the code that handles keyboard macros is mixed in with the event-handling code in `event-stream.c'. 23234 minibuf.c This contains some miscellaneous code related to the minibuffer (most of the minibuffer code was moved into Lisp by Richard Mlynarik). This includes the primitives for completion (although filename completion is in `dired.c'), the lowest-level interface to the minibuffer (if the command loop were cleaned up, this too could be in Lisp), and code for dealing with the echo area (this, too, was mostly moved into Lisp, and the only code remaining is code to call out to Lisp or provide simple bootstrapping implementations early in temacs, before the echo-area Lisp code is loaded).  File: internals.info, Node: Modules for the Basic Displayable Lisp Objects, Next: Modules for other Display-Related Lisp Objects, Prev: Editor-Level Control Flow Modules, Up: A Summary of the Various XEmacs Modules Modules for the Basic Displayable Lisp Objects ============================================== size name ------- --------------------- 985 device-ns.h 6454 device-stream.c 1196 device-stream.h 9526 device-tty.c 8660 device-tty.h 43798 device-x.c 11667 device-x.h 26056 device.c 22993 device.h These modules implement the "device" Lisp object type. This abstracts a particular screen or connection on which frames are displayed. As with Lisp objects, event interfaces, and other subsystems, the device code is separated into a generic component that contains a standardized interface (in the form of a set of methods) onto particular device types. The device subsystem defines all the methods and provides method services for not only device operations but also for the frame, window, menubar, scrollbar, toolbar, and other displayable-object subsystems. The reason for this is that all of these subsystems have the same subtypes (X, TTY, NeXTstep, Microsoft Windows, etc.) as devices do. 934 frame-ns.h 2303 frame-tty.c 69205 frame-x.c 5976 frame-x.h 68175 frame.c 15080 frame.h Each device contains one or more frames in which objects (e.g. text) are displayed. A frame corresponds to a window in the window system; usually this is a top-level window but it could potentially be one of a number of overlapping child windows within a top-level window, using the MDI (Multiple Document Interface) protocol in Microsoft Windows or a similar scheme. The `frame-*' files implement the "frame" Lisp object type and provide the generic and device-type-specific operations on frames (e.g. raising, lowering, resizing, moving, etc.). 160783 window.c 15974 window.h Each frame consists of one or more non-overlapping "windows" (better known as "panes" in standard window-system terminology) in which a buffer's text can be displayed. Windows can also have scrollbars displayed around their edges. `window.c' and `window.h' implement the "window" Lisp object type and provide code to manage windows. Since windows have no associated resources in the window system (the window system knows only about the frame; no child windows or anything are used for XEmacs windows), there is no device-type-specific code here; all of that code is part of the redisplay mechanism or the code for particular object types such as scrollbars.  File: internals.info, Node: Modules for other Display-Related Lisp Objects, Next: Modules for the Redisplay Mechanism, Prev: Modules for the Basic Displayable Lisp Objects, Up: A Summary of the Various XEmacs Modules Modules for other Display-Related Lisp Objects ============================================== size name ------- --------------------- 54397 faces.c 15173 faces.h 4961 bitmaps.h 954 glyphs-ns.h 105345 glyphs-x.c 4288 glyphs-x.h 72102 glyphs.c 16356 glyphs.h 952 objects-ns.h 9971 objects-tty.c 1465 objects-tty.h 32326 objects-x.c 2806 objects-x.h 31944 objects.c 6809 objects.h 57511 menubar-x.c 11243 menubar.c 25012 scrollbar-x.c 2554 scrollbar-x.h 26954 scrollbar.c 2778 scrollbar.h 23117 toolbar-x.c 43456 toolbar.c 4280 toolbar.h 25070 font-lock.c This file provides C support for syntax highlighting - i.e. highlighting different syntactic constructs of a source file in different colors, for easy reading. The C support is provided so that this is fast. 32180 dgif_lib.c 3999 gif_err.c 10697 gif_lib.h 9371 gifalloc.c These modules decode GIF-format image files, for use with glyphs.  File: internals.info, Node: Modules for the Redisplay Mechanism, Next: Modules for Interfacing with the File System, Prev: Modules for other Display-Related Lisp Objects, Up: A Summary of the Various XEmacs Modules Modules for the Redisplay Mechanism =================================== size name ------- --------------------- 38692 redisplay-output.c 40835 redisplay-tty.c 65069 redisplay-x.c 234142 redisplay.c 17026 redisplay.h These files provide the redisplay mechanism. As with many other subsystems in XEmacs, there is a clean separation between the general and device-specific support. `redisplay.c' contains the bulk of the redisplay engine. These functions update the redisplay structures (which describe how the screen is to appear) to reflect any changes made to the state of any displayable objects (buffer, frame, window, etc.) since the last time that redisplay was called. These functions are highly optimized to avoid doing more work than necessary (since redisplay is called extremely often and is potentially a huge time sink), and depend heavily on notifications from the objects themselves that changes have occurred, so that redisplay doesn't explicitly have to check each possible object. The redisplay mechanism also contains a great deal of caching to further speed things up; some of this caching is contained within the various displayable objects. `redisplay-output.c' goes through the redisplay structures and converts them into calls to device-specific methods to actually output the screen changes. `redisplay-x.c' and `redisplay-tty.c' are two implementations of these redisplay output methods, for X frames and TTY frames, respectively. 14129 indent.c This module contains various functions and Lisp primitives for converting between buffer positions and screen positions. These functions call the redisplay mechanism to do most of the work, and then examine the redisplay structures to get the necessary information. This module needs work. 14754 termcap.c 2141 terminfo.c 7253 tparam.c These files contain functions for working with the termcap (BSD-style) and terminfo (System V style) databases of terminal capabilities and escape sequences, used when XEmacs is displaying in a TTY. 10869 cm.c 5876 cm.h These files provide some miscellaneous TTY-output functions and should probably be merged into `redisplay-tty.c'.  File: internals.info, Node: Modules for Interfacing with the File System, Next: Modules for Other Aspects of the Lisp Interpreter and Object System, Prev: Modules for the Redisplay Mechanism, Up: A Summary of the Various XEmacs Modules Modules for Interfacing with the File System ============================================ size name ------- --------------------- 43362 lstream.c 14240 lstream.h These modules implement the "stream" Lisp object type. This is an internal-only Lisp object that implements a generic buffering stream. The idea is to provide a uniform interface onto all sources and sinks of data, including file descriptors, stdio streams, chunks of memory, Lisp buffers, Lisp strings, etc. That way, I/O functions can be written to the stream interface and can transparently handle all possible sources and sinks. (For example, the `read' function can read data from a file, a string, a buffer, or even a function that is called repeatedly to return data, without worrying about where the data is coming from or what-size chunks it is returned in.) Note that in the C code, streams are called "lstreams" (for "Lisp streams") to distinguish them from other kinds of streams, e.g. stdio streams and C++ I/O streams. Similar to other subsystems in XEmacs, lstreams are separated into generic functions and a set of methods for the different types of lstreams. `lstream.c' provides implementations of many different types of streams; others are provided, e.g., in `mule-coding.c'. 126926 fileio.c This implements the basic primitives for interfacing with the file system. This includes primitives for reading files into buffers, writing buffers into files, checking for the presence or accessibility of files, canonicalizing file names, etc. Note that these primitives are usually not invoked directly by the user: There is a great deal of higher-level Lisp code that implements the user commands such as `find-file' and `save-buffer'. This is similar to the distinction between the lower-level primitives in `editfns.c' and the higher-level user commands in `commands.c' and `simple.el'. 10960 filelock.c This file provides functions for detecting clashes between different processes (e.g. XEmacs and some external process, or two different XEmacs processes) modifying the same file. (XEmacs can optionally use the `lock/' subdirectory to provide a form of "locking" between different XEmacs processes.) This module is also used by the low-level functions in `insdel.c' to ensure that, if the first modification is being made to a buffer whose corresponding file has been externally modified, the user is made aware of this so that the buffer can be synched up with the external changes if necessary. 4527 filemode.c This file provides some miscellaneous functions that construct a `rwxr-xr-x'-type permissions string (as might appear in an `ls'-style directory listing) given the information returned by the `stat()' system call. 22855 dired.c 2094 ndir.h These files implement the XEmacs interface to directory searching. This includes a number of primitives for determining the files in a directory and for doing filename completion. (Remember that generic completion is handled by a different mechanism, in `minibuf.c'.) `ndir.h' is a header file used for the directory-searching emulation functions provided in `sysdep.c' (see section J below), for systems that don't provide any directory-searching functions. (On those systems, directories can be read directly as files, and parsed.) 4311 realpath.c This file provides an implementation of the `realpath()' function for expanding symbolic links, on systems that don't implement it or have a broken implementation.  File: internals.info, Node: Modules for Other Aspects of the Lisp Interpreter and Object System, Next: Modules for Interfacing with the Operating System, Prev: Modules for Interfacing with the File System, Up: A Summary of the Various XEmacs Modules Modules for Other Aspects of the Lisp Interpreter and Object System =================================================================== size name ------- --------------------- 22290 elhash.c 2454 elhash.h 12169 hash.c 3369 hash.h These files implement the "hashtable" Lisp object type. `hash.c' and `hash.h' provide a generic C implementation of hash tables (which can stand independently of XEmacs), and `elhash.c' and `elhash.h' provide a Lisp interface onto the C hash tables using the hashtable Lisp object type. 95691 specifier.c 11167 specifier.h This module implements the "specifier" Lisp object type. This is primarily used for displayable properties, and allows for values that are specific to a particular buffer, window, frame, device, or device class, as well as a default value existing. This is used, for example, to control the height of the horizontal scrollbar or the appearance of the `default', `bold', or other faces. The specifier object consists of a number of specifications, each of which maps from a buffer, window, etc. to a value. The function `specifier-instance' looks up a value given a window (from which a buffer, frame, and device can be derived). 43058 chartab.c 6503 chartab.h 9918 casetab.c `chartab.c' and `chartab.h' implement the "char table" Lisp object type, which maps from characters or certain sorts of character ranges to Lisp objects. The implementation of this object type is optimized for the internal representation of characters. Char tables come in different types, which affect the allowed object types to which a character can be mapped and also dictate certain other properties of the char table. `casetab.c' implements one sort of char table, the "case table", which maps characters to other characters of possibly different case. These are used by XEmacs to implement case-changing primitives and to do case-insensitive searching. 49593 syntax.c 10200 syntax.h This module implements "syntax tables", another sort of char table that maps characters into syntax classes that define the syntax of these characters (e.g. a parenthesis belongs to a class of `open' characters that have corresponding `close' characters and can be nested). This module also implements the Lisp "scanner", a set of primitives for scanning over text based on syntax tables. This is used, for example, to find the matching parenthesis in a command such as `forward-sexp', and by `font-lock.c' to locate quoted strings, comments, etc. 10438 casefiddle.c This module implements various Lisp primitives for upcasing, downcasing and capitalizing strings or regions of buffers. 20234 rangetab.c This module implements the "range table" Lisp object type, which provides for a mapping from ranges of integers to arbitrary Lisp objects. 3201 opaque.c 2206 opaque.h This module implements the "opaque" Lisp object type, an internal-only Lisp object that encapsulates an arbitrary block of memory so that it can be managed by the Lisp allocation system. To create an opaque object, you call `make_opaque()', passing a pointer to a block of memory. An object is created that is big enough to hold the memory, which is copied into the object's storage. The object will then stick around as long as you keep pointers to it, after which it will be automatically reclaimed. Opaque objects can also have an arbitrary "mark method" associated with them, in case the block of memory contains other Lisp objects that need to be marked for garbage-collection purposes. (If you need other object methods, such as a finalize method, you should just go ahead and create a new Lisp object type - it's not hard.) 8783 abbrev.c This function provides a few primitives for doing dynamic abbreviation expansion. In XEmacs, most of the code for this has been moved into Lisp. Some C code remains for speed and because the primitive `self-insert-command' (which is executed for all self-inserting characters) hooks into the abbrev mechanism. (`self-insert-command' is itself in C only for speed.) 21934 doc.c This function provides primitives for retrieving the documentation strings of functions and variables. These documentation strings contain certain special markers that get dynamically expanded (e.g. a reverse-lookup is performed on some named functions to retrieve their current key bindings). Some documentation strings (in particular, for the built-in primitives and pre-loaded Lisp functions) are stored externally in a file `DOC' in the `lib-src/' directory and need to be fetched from that file. (Part of the build stage involves building this file, and another part involves constructing an index for this file and embedding it into the executable, so that the functions in `doc.c' do not have to search the entire `DOC' file to find the appropriate documentation string.) 13197 md5.c This function provides a Lisp primitive that implements the MD5 secure hashing scheme, used to create a large hash value of a string of data such that the data cannot be derived from the hash value. This is used for various security applications on the Internet.  File: internals.info, Node: Modules for Interfacing with the Operating System, Next: Modules for Interfacing with X Windows, Prev: Modules for Other Aspects of the Lisp Interpreter and Object System, Up: A Summary of the Various XEmacs Modules Modules for Interfacing with the Operating System ================================================= size name ------- --------------------- 33533 callproc.c 89697 process.c 4663 process.h These modules allow XEmacs to spawn and communicate with subprocesses and network connections. `callproc.c' implements (through the `call-process' primitive) what are called "synchronous subprocesses". This means that XEmacs runs a program, waits till it's done, and retrieves its output. A typical example might be calling the `ls' program to get a directory listing. `process.c' and `process.h' implement "asynchronous subprocesses". This means that XEmacs starts a program and then continues normally, not waiting for the process to finish. Data can be sent to the process or retrieved from it as it's running. This is used for the `shell' command (which provides a front end onto a shell program such as `csh'), the mail and news readers implemented in XEmacs, etc. The result of calling `start-process' to start a subprocess is a process object, a particular kind of object used to communicate with the subprocess. You can send data to the process by passing the process object and the data to `send-process', and you can specify what happens to data retrieved from the process by setting properties of the process object. (When the process sends data, XEmacs receives a process event, which says that there is data ready. When `dispatch-event' is called on this event, it reads the data from the process and does something with it, as specified by the process object's properties. Typically, this means inserting the data into a buffer or calling a function.) Another property of the process object is called the "sentinel", which is a function that is called when the process terminates. Process objects are also used for network connections (connections to a process running on another machine). Network connections are started with `open-network-stream' but otherwise work just like subprocesses. 136029 sysdep.c 5986 sysdep.h These modules implement most of the low-level, messy operating-system interface code. This includes various device control (ioctl) operations for file descriptors, TTY's, pseudo-terminals, etc. (usually this stuff is fairly system-dependent; thus the name of this module), and emulation of standard library functions and system calls on systems that don't provide them or have broken versions. 3605 sysdir.h 6708 sysfile.h 2027 sysfloat.h 2918 sysproc.h 745 syspwd.h 7643 syssignal.h 6892 systime.h 12477 systty.h 3487 syswait.h These header files provide consistent interfaces onto system-dependent header files and system calls. The idea is that, instead of including a standard header file like `' (which may or may not exist on various systems) or having to worry about whether all system provide a particular preprocessor constant, or having to deal with the four different paradigms for manipulating signals, you just include the appropriate `sys*.h' header file, which includes all the right system header files, defines and missing preprocessor constants, provides a uniform interface onto system calls, etc. `sysdir.h' provides a uniform interface onto directory-querying functions. (In some cases, this is in conjunction with emulation functions in `sysdep.c'.) `sysfile.h' includes all the necessary header files for standard system calls (e.g. `read()'), ensures that all necessary `open()' and `stat()' preprocessor constants are defined, and possibly (usually) substitutes sugared versions of `read()', `write()', etc. that automatically restart interrupted I/O operations. `sysfloat.h' includes the necessary header files for floating-point operations. `sysproc.h' includes the necessary header files for calling `select()', `fork()', `execve()', socket operations, and the like, and ensures that the `FD_*()' macros for descriptor-set manipulations are available. `syspwd.h' includes the necessary header files for obtaining information from `/etc/passwd' (the functions are emulated under VMS). `syssignal.h' includes the necessary header files for signal-handling and provides a uniform interface onto the different signal-handling and signal-blocking paradigms. `systime.h' includes the necessary header files and provides uniform interfaces for retrieving the time of day, setting file access/modification times, getting the amount of time used by the XEmacs process, etc. `systty.h' buffers against the infinitude of different ways of controlling TTY's. `syswait.h' provides a uniform way of retrieving the exit status from a `wait()'ed-on process (some systems use a union, others use an int). 7940 hpplay.c 10920 libsst.c 1480 libsst.h 3260 libst.h 15355 linuxplay.c 15849 nas.c 19133 sgiplay.c 15411 sound.c 7358 sunplay.c These files implement the ability to play various sounds on some types of computers. You have to configure your XEmacs with sound support in order to get this capability. `sound.c' provides the generic interface. It implements various Lisp primitives and variables that let you specify which sounds should be played in certain conditions. (The conditions are identified by symbols, which are passed to `ding' to make a sound. Various standard functions call this function at certain times; if sound support does not exist, a simple beep results. `sgiplay.c', `sunplay.c', `hpplay.c', and `linuxplay.c' interface to the machine's speaker for various different kind of machines. This is called "native" sound. `nas.c' interfaces to a computer somewhere else on the network using the NAS (Network Audio Server) protocol, playing sounds on that machine. This allows you to run XEmacs on a remote machine, with its display set to your local machine, and have the sounds be made on your local machine, provided that you have a NAS server running on your local machine. `libsst.c', `libsst.h', and `libst.h' provide some additional functions for playing sound on a Sun SPARC but are not currently in use. 44368 tooltalk.c 2137 tooltalk.h These two modules implement an interface to the ToolTalk protocol, which is an interprocess communication protocol implemented on some versions of Unix. ToolTalk is a high-level protocol that allows processes to register themselves as providers of particular services; other processes can then request a service without knowing or caring exactly who is providing the service. It is similar in spirit to the DDE protocol provided under Microsoft Windows. ToolTalk is a part of the new CDE (Common Desktop Environment) specification and is used to connect the parts of the SPARCWorks development environment. 22695 getloadavg.c This module provides the ability to retrieve the system's current load average. (The way to do this is highly system-specific, unfortunately, and requires a lot of special-case code.) 148520 energize.c 6896 energize.h This module provides code to interface to an Energize server (when XEmacs is used as part of Lucid's Energize development environment) and provides some other Energize-specific functions. Much of the code in this module should be made more general-purpose and moved elsewhere, but is no longer very relevant now that Lucid is defunct. It also hasn't worked since version 19.12, since nobody has been maintaining it. 2861 sunpro.c This module provides a small amount of code used internally at Sun to keep statistics on the usage of XEmacs. 5548 broken-sun.h 3468 strcmp.c 2179 strcpy.c 1650 sunOS-fix.c These files provide replacement functions and prototypes to fix numerous bugs in early releases of SunOS 4.1. 11669 hftctl.c This module provides some terminal-control code necessary on versions of AIX prior to 4.1. 1776 acldef.h 1602 chpdef.h 9032 uaf.h 105 vlimit.h 7145 vms-pp.c 1158 vms-pwd.h 26532 vmsfns.c 6038 vmsmap.c 695 vmspaths.h 17482 vmsproc.c 469 vmsproc.h All of these files are used for VMS support, which has never worked in XEmacs. 28316 msdos.c 1472 msdos.h These modules are used for MS-DOS support, which does not work in XEmacs.  File: internals.info, Node: Modules for Interfacing with X Windows, Next: Modules for Internationalization, Prev: Modules for Interfacing with the Operating System, Up: A Summary of the Various XEmacs Modules Modules for Interfacing with X Windows ====================================== size name ------- --------------------- 3196 Emacs.ad.h A file generated from `Emacs.ad', which contains XEmacs-supplied fallback resources (so that XEmacs has pretty defaults). 24242 EmacsFrame.c 6979 EmacsFrame.h 3351 EmacsFrameP.h These modules implement an Xt widget class that encapsulates a frame. This is for ease in integrating with Xt. The EmacsFrame widget covers the entire X window except for the menubar; the scrollbars are positioned on top of the EmacsFrame widget. *Warning:* Abandon hope, all ye who enter here. This code took an ungodly amount of time to get right, and is likely to fall apart mercilessly at the slightest change. Such is life under Xt. 8178 EmacsManager.c 1967 EmacsManager.h 1895 EmacsManagerP.h These modules implement a simple Xt manager (i.e. composite) widget class that simply lets its children set whatever geometry they want. It's amazing that Xt doesn't provide this standardly, but on second thought, it makes sense, considering how amazingly broken Xt is. 13188 EmacsShell-sub.c 4588 EmacsShell.c 2180 EmacsShell.h 3133 EmacsShellP.h These modules implement two Xt widget classes that are subclasses of the TopLevelShell and TransientShell classes. This is necessary to deal with more brokenness that Xt has sadistically thrust onto the backs of developers. 9673 xgccache.c 1111 xgccache.h These modules provide functions for maintenance and caching of GC's (graphics contexts) under the X Window System. This code is junky and needs to be rewritten. 69181 xselect.c This module provides an interface to the X Window System's concept of "selections", the standard way for X applications to communicate with each other. 929 xintrinsic.h 1038 xintrinsicp.h 1579 xmmanagerp.h 1585 xmprimitivep.h These header files are similar in spirit to the `sys*.h' files and buffer against different implementations of Xt and Motif. * `xintrinsic.h' should be included in place of `'. * `xintrinsicp.h' should be included in place of `'. * `xmmanagerp.h' should be included in place of `'. * `xmprimitivep.h' should be included in place of `'. 16930 xmu.c 936 xmu.h These files provide an emulation of the Xmu library for those systems (i.e. HPUX) that don't provide it as a standard part of X. 4201 ExternalClient-Xlib.c 18083 ExternalClient.c 2035 ExternalClient.h 2104 ExternalClientP.h 22684 ExternalShell.c 1709 ExternalShell.h 1971 ExternalShellP.h 2478 extw-Xlib.c 1481 extw-Xlib.h 6565 extw-Xt.c 1430 extw-Xt.h These files provide the "external widget" interface, which allows an XEmacs frame to appear as a widget in another application. To do this, you have to configure with `--external-widget'. `ExternalShell*' provides the server (XEmacs) side of the connection. `ExternalClient*' provides the client (other application) side of the connection. These files are not compiled into XEmacs but are compiled into libraries that are then linked into your application. `extw-*' is common code that is used for both the client and server. Don't touch this code; something is liable to break if you do. 31014 epoch.c This file provides some additional, Epoch-compatible, functionality for interfacing to the X Window System.  File: internals.info, Node: Modules for Internationalization, Prev: Modules for Interfacing with X Windows, Up: A Summary of the Various XEmacs Modules Modules for Internationalization ================================ size name ------- --------------------- 42836 mule-canna.c 16737 mule-ccl.c 41080 mule-charset.c 30176 mule-charset.h 146844 mule-coding.c 16588 mule-coding.h 6996 mule-mcpath.c 2899 mule-mcpath.h 57158 mule-wnnfns.c 3351 mule.c These files implement the MULE (Asian-language) support. Note that MULE actually provides a general interface for all sorts of languages, not just Asian languages (although they are generally the most complicated to support). This code is still in beta. `mule-charset.*' and `mule-coding.*' provide the heart of the XEmacs MULE support. `mule-charset.*' implements the "charset" Lisp object type, which encapsulates a character set (an ordered one- or two-dimensional set of characters, such as US ASCII or JISX0208 Japanese Kanji). `mule-coding.*' implements the "coding-system" Lisp object type, which encapsulates a method of converting between different encodings. An encoding is a representation of a stream of characters, possibly from multiple character sets, using a stream of bytes or words, and defines (e.g.) which escape sequences are used to specify particular character sets, how the indices for a character are converted into bytes (sometimes this involves setting the high bit; sometimes complicated rearranging of the values takes place, as in the Shift-JIS encoding), etc. `mule-ccl.c' provides the CCL (Code Conversion Language) interpreter. CCL is similar in spirit to Lisp byte code and is used to implement converters for custom encodings. `mule-canna.c' and `mule-wnnfns.c' implement interfaces to external programs used to implement the Canna and WNN input methods, respectively. This is currently in beta. `mule-mcpath.c' provides some functions to allow for pathnames containing extended characters. This code is fragmentary, obsolete, and completely non-working. Instead, PATHNAME-CODING-SYSTEM is used to specify conversions of names of files and directories. The standard C I/O functions like `open()' are wrapped so that conversion occurs automatically. `mule.c' provides a few miscellaneous things that should probably be elsewhere. 9400 intl.c This provides some miscellaneous internationalization code for implementing message translation and interfacing to the Ximp input method. None of this code is currently working. 1764 iso-wide.h This contains leftover code from an earlier implementation of Asian-language support, and is not currently used.