Mercurial > hg > xemacs-beta
annotate man/lispref/processes.texi @ 5157:1fae11d56ad2
redo memory-usage mechanism, add way of dynamically initializing Lisp objects
-------------------- ChangeLog entries follow: --------------------
lisp/ChangeLog addition:
2010-03-18 Ben Wing <ben@xemacs.org>
* diagnose.el (show-memory-usage):
Rewrite to take into account API changes in memory-usage functions.
src/ChangeLog addition:
2010-03-18 Ben Wing <ben@xemacs.org>
* alloc.c:
* alloc.c (disksave_object_finalization_1):
* alloc.c (lisp_object_storage_size):
* alloc.c (listu):
* alloc.c (listn):
* alloc.c (Fobject_memory_usage_stats):
* alloc.c (compute_memusage_stats_length):
* alloc.c (Fobject_memory_usage):
* alloc.c (Ftotal_object_memory_usage):
* alloc.c (malloced_storage_size):
* alloc.c (common_init_alloc_early):
* alloc.c (reinit_alloc_objects_early):
* alloc.c (reinit_alloc_early):
* alloc.c (init_alloc_once_early):
* alloc.c (syms_of_alloc):
* alloc.c (reinit_vars_of_alloc):
* buffer.c:
* buffer.c (struct buffer_stats):
* buffer.c (compute_buffer_text_usage):
* buffer.c (compute_buffer_usage):
* buffer.c (buffer_memory_usage):
* buffer.c (buffer_objects_create):
* buffer.c (syms_of_buffer):
* buffer.c (vars_of_buffer):
* console-impl.h (struct console_methods):
* dynarr.c (Dynarr_memory_usage):
* emacs.c (main_1):
* events.c (clear_event_resource):
* extents.c:
* extents.c (compute_buffer_extent_usage):
* extents.c (extent_objects_create):
* extents.h:
* faces.c:
* faces.c (compute_face_cachel_usage):
* faces.c (face_objects_create):
* faces.h:
* general-slots.h:
* glyphs.c:
* glyphs.c (compute_glyph_cachel_usage):
* glyphs.c (glyph_objects_create):
* glyphs.h:
* lisp.h:
* lisp.h (struct usage_stats):
* lrecord.h:
* lrecord.h (enum lrecord_type):
* lrecord.h (struct lrecord_implementation):
* lrecord.h (MC_ALLOC_CALL_FINALIZER_FOR_DISKSAVE):
* lrecord.h (DEFINE_DUMPABLE_LISP_OBJECT):
* lrecord.h (DEFINE_DUMPABLE_SIZABLE_LISP_OBJECT):
* lrecord.h (DEFINE_DUMPABLE_FROB_BLOCK_LISP_OBJECT):
* lrecord.h (DEFINE_DUMPABLE_FROB_BLOCK_SIZABLE_LISP_OBJECT):
* lrecord.h (DEFINE_DUMPABLE_INTERNAL_LISP_OBJECT):
* lrecord.h (DEFINE_DUMPABLE_SIZABLE_INTERNAL_LISP_OBJECT):
* lrecord.h (DEFINE_NODUMP_LISP_OBJECT):
* lrecord.h (DEFINE_NODUMP_SIZABLE_LISP_OBJECT):
* lrecord.h (DEFINE_NODUMP_FROB_BLOCK_LISP_OBJECT):
* lrecord.h (DEFINE_NODUMP_FROB_BLOCK_SIZABLE_LISP_OBJECT):
* lrecord.h (DEFINE_NODUMP_INTERNAL_LISP_OBJECT):
* lrecord.h (DEFINE_NODUMP_SIZABLE_INTERNAL_LISP_OBJECT):
* lrecord.h (MAKE_LISP_OBJECT):
* lrecord.h (DEFINE_DUMPABLE_MODULE_LISP_OBJECT):
* lrecord.h (DEFINE_DUMPABLE_MODULE_SIZABLE_LISP_OBJECT):
* lrecord.h (DEFINE_NODUMP_MODULE_LISP_OBJECT):
* lrecord.h (DEFINE_NODUMP_MODULE_SIZABLE_LISP_OBJECT):
* lrecord.h (MAKE_MODULE_LISP_OBJECT):
* lrecord.h (INIT_LISP_OBJECT):
* lrecord.h (INIT_MODULE_LISP_OBJECT):
* lrecord.h (UNDEF_LISP_OBJECT):
* lrecord.h (UNDEF_MODULE_LISP_OBJECT):
* lrecord.h (DECLARE_LISP_OBJECT):
* lrecord.h (DECLARE_MODULE_API_LISP_OBJECT):
* lrecord.h (DECLARE_MODULE_LISP_OBJECT):
* lstream.c:
* lstream.c (syms_of_lstream):
* lstream.c (vars_of_lstream):
* marker.c:
* marker.c (compute_buffer_marker_usage):
* mc-alloc.c (mc_alloced_storage_size):
* mc-alloc.h:
* mule-charset.c:
* mule-charset.c (struct charset_stats):
* mule-charset.c (compute_charset_usage):
* mule-charset.c (charset_memory_usage):
* mule-charset.c (mule_charset_objects_create):
* mule-charset.c (syms_of_mule_charset):
* mule-charset.c (vars_of_mule_charset):
* redisplay.c:
* redisplay.c (compute_rune_dynarr_usage):
* redisplay.c (compute_display_block_dynarr_usage):
* redisplay.c (compute_glyph_block_dynarr_usage):
* redisplay.c (compute_display_line_dynarr_usage):
* redisplay.c (compute_line_start_cache_dynarr_usage):
* redisplay.h:
* scrollbar-gtk.c (gtk_compute_scrollbar_instance_usage):
* scrollbar-msw.c (mswindows_compute_scrollbar_instance_usage):
* scrollbar-x.c (x_compute_scrollbar_instance_usage):
* scrollbar.c (compute_scrollbar_instance_usage):
* scrollbar.h:
* symbols.c:
* symbols.c (reinit_symbol_objects_early):
* symbols.c (init_symbols_once_early):
* symbols.c (reinit_symbols_early):
* symbols.c (defsymbol_massage_name_1):
* symsinit.h:
* ui-gtk.c:
* ui-gtk.c (emacs_gtk_object_getprop):
* ui-gtk.c (emacs_gtk_object_putprop):
* ui-gtk.c (ui_gtk_objects_create):
* unicode.c (compute_from_unicode_table_size_1):
* unicode.c (compute_to_unicode_table_size_1):
* unicode.c (compute_from_unicode_table_size):
* unicode.c (compute_to_unicode_table_size):
* window.c:
* window.c (struct window_stats):
* window.c (compute_window_mirror_usage):
* window.c (compute_window_usage):
* window.c (window_memory_usage):
* window.c (window_objects_create):
* window.c (syms_of_window):
* window.c (vars_of_window):
* window.h:
Redo memory-usage mechanism, make it general; add way of dynamically
initializing Lisp object types -- OBJECT_HAS_METHOD(), similar to
CONSOLE_HAS_METHOD().
(1) Create OBJECT_HAS_METHOD(), OBJECT_HAS_PROPERTY() etc. for
specifying that a Lisp object type has a particular method or
property. Call such methods with OBJECT_METH, MAYBE_OBJECT_METH,
OBJECT_METH_OR_GIVEN; retrieve properties with OBJECT_PROPERTY.
Methods that formerly required a DEFINE_*GENERAL_LISP_OBJECT() to
specify them (getprop, putprop, remprop, plist, disksave) now
instead use the dynamic-method mechanism. The main benefit of
this is that new methods or properties can be added without
requiring that the declaration statements of all existing methods
be modified. We have to make the `struct lrecord_implementation'
non-const, but I don't think this should have any effect on speed --
the only possible method that's really speed-critical is the
mark method, and we already extract those out into a separate
(non-const) array for increased cache locality.
Object methods need to be reinitialized after pdump, so we put
them in separate functions such as face_objects_create(),
extent_objects_create() and call them appropriately from emacs.c
The only current object property (`memusage_stats_list') that
objects can specify is a Lisp object and gets staticpro()ed so it
only needs to be set during dump time, but because it references
symbols that might not exist in a syms_of_() function, we
initialize it in vars_of_(). There is also an object property
(`num_extra_memusage_stats') that is automatically initialized based
on `memusage_stats_list'; we do that in reinit_vars_of_alloc(),
which is called after all vars_of_() functions are called.
`disksaver' method was renamed `disksave' to correspond with the
name normally given to the function (e.g. disksave_lstream()).
(2) Generalize the memory-usage mechanism in `buffer-memory-usage',
`window-memory-usage', `charset-memory-usage' into an object-type-
specific mechanism called by a single function
`object-memory-usage'. (Former function `object-memory-usage'
renamed to `total-object-memory-usage'). Generalize the mechanism
of different "slices" so that we can have different "classes" of
memory described and different "slices" onto each class; `t'
separates classes, `nil' separates slices. Currently we have
three classes defined: the memory of an object itself,
non-Lisp-object memory associated with the object (e.g. arrays or
dynarrs stored as fields in the object), and Lisp-object memory
associated with the object (other internal Lisp objects stored in
the object). This isn't completely finished yet and we might need
to further separate the "other internal Lisp objects" class into
two classes.
The memory-usage mechanism uses a `struct usage_stats' (renamed
from `struct overhead_stats') to describe a malloc-view onto a set
of allocated memory (listing how much was requested and various
types of overhead) and a more general `struct generic_usage_stats'
(with a `struct usage_stats' in it) to hold all statistics about
object memory. `struct generic_usage_stats' contains an array of
32 Bytecounts, which are statistics of unspecified semantics. The
intention is that individual types declare a corresponding struct
(e.g. `struct window_stats') with the same structure but with
specific fields in place of the array, corresponding to specific
statistics. The number of such statistics is an object property
computed from the list of tags (Lisp symbols describing the
statistics) stored in `memusage_stats_list'. The idea here is to
allow particular object types to customize the number and
semantics of the statistics where completely avoiding consing.
This doesn't matter so much yet, but the intention is to have the
memory usage of all objects computed at the end of GC, at the same
time as other statistics are currently computed. The values for
all statistics for a single type would be added up to compute
aggregate values for all objects of a specific type. To make this
efficient, we can't allow any memory allocation at all.
(3) Create some additional functions for creating lists that
specify the elements directly as args rather than indirectly through
an array: listn() (number of args given), listu() (list terminated
by Qunbound).
(4) Delete a bit of remaining unused C window_config stuff, also
unused lrecord_type_popup_data.
| author | Ben Wing <ben@xemacs.org> |
|---|---|
| date | Thu, 18 Mar 2010 10:50:06 -0500 |
| parents | 99f8ebc082d9 |
| children | 965a9ddc915a |
| rev | line source |
|---|---|
| 0 | 1 @c -*-texinfo-*- |
| 2 @c This is part of the XEmacs Lisp Reference Manual. | |
| 442 | 3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. |
| 0 | 4 @c See the file lispref.texi for copying conditions. |
| 5 @setfilename ../../info/processes.info | |
| 6 @node Processes, System Interface, Databases, Top | |
| 7 @chapter Processes | |
| 8 @cindex child process | |
| 9 @cindex parent process | |
| 10 @cindex subprocess | |
| 11 @cindex process | |
| 12 | |
| 13 In the terminology of operating systems, a @dfn{process} is a space in | |
| 14 which a program can execute. XEmacs runs in a process. XEmacs Lisp | |
| 15 programs can invoke other programs in processes of their own. These are | |
| 16 called @dfn{subprocesses} or @dfn{child processes} of the XEmacs process, | |
| 17 which is their @dfn{parent process}. | |
| 18 | |
| 19 A subprocess of XEmacs may be @dfn{synchronous} or @dfn{asynchronous}, | |
| 20 depending on how it is created. When you create a synchronous | |
| 21 subprocess, the Lisp program waits for the subprocess to terminate | |
| 22 before continuing execution. When you create an asynchronous | |
| 23 subprocess, it can run in parallel with the Lisp program. This kind of | |
| 24 subprocess is represented within XEmacs by a Lisp object which is also | |
| 25 called a ``process''. Lisp programs can use this object to communicate | |
| 26 with the subprocess or to control it. For example, you can send | |
| 27 signals, obtain status information, receive output from the process, or | |
| 28 send input to it. | |
| 29 | |
| 30 @defun processp object | |
| 31 This function returns @code{t} if @var{object} is a process, | |
| 32 @code{nil} otherwise. | |
| 33 @end defun | |
| 34 | |
| 35 @menu | |
| 36 * Subprocess Creation:: Functions that start subprocesses. | |
| 37 * Synchronous Processes:: Details of using synchronous subprocesses. | |
| 38 * MS-DOS Subprocesses:: On MS-DOS, you must indicate text vs binary | |
| 39 for data sent to and from a subprocess. | |
| 40 * Asynchronous Processes:: Starting up an asynchronous subprocess. | |
| 41 * Deleting Processes:: Eliminating an asynchronous subprocess. | |
| 42 * Process Information:: Accessing run-status and other attributes. | |
| 43 * Input to Processes:: Sending input to an asynchronous subprocess. | |
| 44 * Signals to Processes:: Stopping, continuing or interrupting | |
| 45 an asynchronous subprocess. | |
| 46 * Output from Processes:: Collecting output from an asynchronous subprocess. | |
| 47 * Sentinels:: Sentinels run when process run-status changes. | |
| 48 * Process Window Size:: Changing the logical window size of a process. | |
| 49 * Transaction Queues:: Transaction-based communication with subprocesses. | |
| 50 * Network:: Opening network connections. | |
| 51 @end menu | |
| 52 | |
| 53 @node Subprocess Creation | |
| 54 @section Functions that Create Subprocesses | |
| 55 | |
| 56 There are three functions that create a new subprocess in which to run | |
| 57 a program. One of them, @code{start-process}, creates an asynchronous | |
| 58 process and returns a process object (@pxref{Asynchronous Processes}). | |
| 59 The other two, @code{call-process} and @code{call-process-region}, | |
| 60 create a synchronous process and do not return a process object | |
| 61 (@pxref{Synchronous Processes}). | |
| 62 | |
| 444 | 63 Synchronous and asynchronous processes are explained in the following |
| 0 | 64 sections. Since the three functions are all called in a similar |
| 65 fashion, their common arguments are described here. | |
| 66 | |
| 67 @cindex execute program | |
| 68 @cindex @code{PATH} environment variable | |
| 69 @cindex @code{HOME} environment variable | |
| 70 In all cases, the function's @var{program} argument specifies the | |
| 71 program to be run. An error is signaled if the file is not found or | |
| 72 cannot be executed. If the file name is relative, the variable | |
| 73 @code{exec-path} contains a list of directories to search. Emacs | |
| 74 initializes @code{exec-path} when it starts up, based on the value of | |
| 75 the environment variable @code{PATH}. The standard file name | |
| 76 constructs, @samp{~}, @samp{.}, and @samp{..}, are interpreted as usual | |
| 77 in @code{exec-path}, but environment variable substitutions | |
| 78 (@samp{$HOME}, etc.) are not recognized; use | |
| 79 @code{substitute-in-file-name} to perform them (@pxref{File Name | |
| 80 Expansion}). | |
| 81 | |
| 82 Each of the subprocess-creating functions has a @var{buffer-or-name} | |
| 83 argument which specifies where the standard output from the program will | |
| 84 go. If @var{buffer-or-name} is @code{nil}, that says to discard the | |
| 85 output unless a filter function handles it. (@xref{Filter Functions}, | |
| 86 and @ref{Read and Print}.) Normally, you should avoid having multiple | |
| 87 processes send output to the same buffer because their output would be | |
| 88 intermixed randomly. | |
| 89 | |
| 90 @cindex program arguments | |
| 91 All three of the subprocess-creating functions have a @code{&rest} | |
| 92 argument, @var{args}. The @var{args} must all be strings, and they are | |
| 93 supplied to @var{program} as separate command line arguments. Wildcard | |
| 94 characters and other shell constructs are not allowed in these strings, | |
| 442 | 95 since they are passed directly to the specified program. |
| 0 | 96 |
| 97 @strong{Please note:} The argument @var{program} contains only the | |
| 98 name of the program; it may not contain any command-line arguments. You | |
| 99 must use @var{args} to provide those. | |
| 100 | |
| 444 | 101 If you want to use features of the shell, then invoke the shell directly |
| 102 using, for example, @var{program} of @code{"sh"}, and @var{args} of | |
| 103 @code{"-c"} and @var{"command line..."}. | |
| 104 | |
| 0 | 105 The subprocess gets its current directory from the value of |
| 106 @code{default-directory} (@pxref{File Name Expansion}). | |
| 107 | |
| 108 @cindex environment variables, subprocesses | |
| 109 The subprocess inherits its environment from XEmacs; but you can | |
| 110 specify overrides for it with @code{process-environment}. @xref{System | |
| 111 Environment}. | |
| 112 | |
| 442 | 113 @defvar exec-directory |
| 4771 | 114 @pindex etags |
| 0 | 115 The value of this variable is the name of a directory (a string) that |
| 116 contains programs that come with XEmacs, that are intended for XEmacs | |
| 4771 | 117 to invoke. The program @code{etags} is an example of such a program. |
| 0 | 118 @end defvar |
| 119 | |
| 120 @defopt exec-path | |
| 121 The value of this variable is a list of directories to search for | |
| 122 programs to run in subprocesses. Each element is either the name of a | |
| 123 directory (i.e., a string), or @code{nil}, which stands for the default | |
| 124 directory (which is the value of @code{default-directory}). | |
| 125 @cindex program directories | |
| 126 | |
| 127 The value of @code{exec-path} is used by @code{call-process} and | |
| 128 @code{start-process} when the @var{program} argument is not an absolute | |
| 129 file name. | |
| 130 @end defopt | |
| 131 | |
| 132 @node Synchronous Processes | |
| 133 @section Creating a Synchronous Process | |
| 134 @cindex synchronous subprocess | |
| 135 | |
| 136 After a @dfn{synchronous process} is created, XEmacs waits for the | |
| 137 process to terminate before continuing. Starting Dired is an example of | |
| 138 this: it runs @code{ls} in a synchronous process, then modifies the | |
| 139 output slightly. Because the process is synchronous, the entire | |
| 140 directory listing arrives in the buffer before XEmacs tries to do | |
| 141 anything with it. | |
| 142 | |
| 143 While Emacs waits for the synchronous subprocess to terminate, the | |
| 144 user can quit by typing @kbd{C-g}. The first @kbd{C-g} tries to kill | |
| 145 the subprocess with a @code{SIGINT} signal; but it waits until the | |
| 146 subprocess actually terminates before quitting. If during that time the | |
| 147 user types another @kbd{C-g}, that kills the subprocess instantly with | |
| 148 @code{SIGKILL} and quits immediately. @xref{Quitting}. | |
| 149 | |
| 150 The synchronous subprocess functions returned @code{nil} in version | |
| 151 18. In version 19, they return an indication of how the process | |
| 152 terminated. | |
| 153 | |
| 154 @defun call-process program &optional infile destination display &rest args | |
| 155 This function calls @var{program} in a separate process and waits for | |
| 156 it to finish. | |
| 157 | |
| 158 The standard input for the process comes from file @var{infile} if | |
| 159 @var{infile} is not @code{nil} and from @file{/dev/null} otherwise. | |
| 160 The argument @var{destination} says where to put the process output. | |
| 161 Here are the possibilities: | |
| 162 | |
| 163 @table @asis | |
| 164 @item a buffer | |
| 165 Insert the output in that buffer, before point. This includes both the | |
| 166 standard output stream and the standard error stream of the process. | |
| 167 | |
| 168 @item a string | |
| 169 Find or create a buffer with that name, then insert | |
| 170 the output in that buffer, before point. | |
| 171 | |
| 172 @item @code{t} | |
| 173 Insert the output in the current buffer, before point. | |
| 174 | |
| 175 @item @code{nil} | |
| 176 Discard the output. | |
| 177 | |
| 178 @item 0 | |
| 179 Discard the output, and return immediately without waiting | |
| 180 for the subprocess to finish. | |
| 181 | |
| 182 In this case, the process is not truly synchronous, since it can run in | |
| 183 parallel with Emacs; but you can think of it as synchronous in that | |
| 184 Emacs is essentially finished with the subprocess as soon as this | |
| 185 function returns. | |
| 186 | |
| 187 @item (@var{real-destination} @var{error-destination}) | |
| 188 Keep the standard output stream separate from the standard error stream; | |
| 189 deal with the ordinary output as specified by @var{real-destination}, | |
| 190 and dispose of the error output according to @var{error-destination}. | |
| 191 The value @code{nil} means discard it, @code{t} means mix it with the | |
| 192 ordinary output, and a string specifies a file name to redirect error | |
| 193 output into. | |
| 194 | |
| 195 You can't directly specify a buffer to put the error output in; that is | |
| 196 too difficult to implement. But you can achieve this result by sending | |
| 197 the error output to a temporary file and then inserting the file into a | |
| 198 buffer. | |
| 199 @end table | |
| 200 | |
| 201 If @var{display} is non-@code{nil}, then @code{call-process} redisplays | |
| 202 the buffer as output is inserted. Otherwise the function does no | |
| 203 redisplay, and the results become visible on the screen only when XEmacs | |
| 204 redisplays that buffer in the normal course of events. | |
| 205 | |
| 206 The remaining arguments, @var{args}, are strings that specify command | |
| 207 line arguments for the program. | |
| 208 | |
| 209 The value returned by @code{call-process} (unless you told it not to | |
| 210 wait) indicates the reason for process termination. A number gives the | |
| 211 exit status of the subprocess; 0 means success, and any other value | |
| 212 means failure. If the process terminated with a signal, | |
| 213 @code{call-process} returns a string describing the signal. | |
| 214 | |
| 215 In the examples below, the buffer @samp{foo} is current. | |
| 216 | |
| 217 @smallexample | |
| 218 @group | |
| 219 (call-process "pwd" nil t) | |
| 220 @result{} nil | |
| 221 | |
| 222 ---------- Buffer: foo ---------- | |
| 223 /usr/user/lewis/manual | |
| 224 ---------- Buffer: foo ---------- | |
| 225 @end group | |
| 226 | |
| 227 @group | |
| 228 (call-process "grep" nil "bar" nil "lewis" "/etc/passwd") | |
| 229 @result{} nil | |
| 230 | |
| 231 ---------- Buffer: bar ---------- | |
| 232 lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh | |
| 233 | |
| 234 ---------- Buffer: bar ---------- | |
| 235 @end group | |
| 236 @end smallexample | |
| 237 | |
| 238 The @code{insert-directory} function contains a good example of the use | |
| 239 of @code{call-process}: | |
| 240 | |
| 241 @smallexample | |
| 242 @group | |
| 243 (call-process insert-directory-program nil t nil switches | |
| 244 (if full-directory-p | |
| 245 (concat (file-name-as-directory file) ".") | |
| 246 file)) | |
| 247 @end group | |
| 248 @end smallexample | |
| 249 @end defun | |
| 250 | |
| 444 | 251 @defun call-process-region start end program &optional deletep destination displayp &rest args |
| 0 | 252 This function sends the text between @var{start} to @var{end} as |
| 253 standard input to a process running @var{program}. It deletes the text | |
| 444 | 254 sent if @var{deletep} is non-@code{nil}; this is useful when @var{buffer} |
| 0 | 255 is @code{t}, to insert the output in the current buffer. |
| 256 | |
| 444 | 257 The arguments @var{destination} and @var{displayp} control what to do |
| 0 | 258 with the output from the subprocess, and whether to update the display |
| 259 as it comes in. For details, see the description of | |
| 260 @code{call-process}, above. If @var{destination} is the integer 0, | |
| 261 @code{call-process-region} discards the output and returns @code{nil} | |
| 262 immediately, without waiting for the subprocess to finish. | |
| 263 | |
| 264 The remaining arguments, @var{args}, are strings that specify command | |
| 265 line arguments for the program. | |
| 266 | |
| 267 The return value of @code{call-process-region} is just like that of | |
| 268 @code{call-process}: @code{nil} if you told it to return without | |
| 269 waiting; otherwise, a number or string which indicates how the | |
| 270 subprocess terminated. | |
| 271 | |
| 272 In the following example, we use @code{call-process-region} to run the | |
| 273 @code{cat} utility, with standard input being the first five characters | |
| 274 in buffer @samp{foo} (the word @samp{input}). @code{cat} copies its | |
| 275 standard input into its standard output. Since the argument | |
| 276 @var{destination} is @code{t}, this output is inserted in the current | |
| 277 buffer. | |
| 278 | |
| 279 @smallexample | |
| 280 @group | |
| 281 ---------- Buffer: foo ---------- | |
| 282 input@point{} | |
| 283 ---------- Buffer: foo ---------- | |
| 284 @end group | |
| 285 | |
| 286 @group | |
| 287 (call-process-region 1 6 "cat" nil t) | |
| 288 @result{} nil | |
| 289 | |
| 290 ---------- Buffer: foo ---------- | |
| 291 inputinput@point{} | |
| 292 ---------- Buffer: foo ---------- | |
| 293 @end group | |
| 294 @end smallexample | |
| 295 | |
| 296 The @code{shell-command-on-region} command uses | |
| 297 @code{call-process-region} like this: | |
| 298 | |
| 299 @smallexample | |
| 300 @group | |
| 442 | 301 (call-process-region |
| 302 start end | |
| 0 | 303 shell-file-name ; @r{Name of program.} |
| 304 nil ; @r{Do not delete region.} | |
| 305 buffer ; @r{Send output to @code{buffer}.} | |
| 306 nil ; @r{No redisplay during output.} | |
| 307 "-c" command) ; @r{Arguments for the shell.} | |
| 308 @end group | |
| 309 @end smallexample | |
| 310 @end defun | |
| 311 | |
| 312 @node MS-DOS Subprocesses | |
| 313 @section MS-DOS Subprocesses | |
| 314 | |
| 315 On MS-DOS, you must indicate whether the data going to and from | |
| 316 a synchronous subprocess are text or binary. Text data requires | |
| 317 translation between the end-of-line convention used within Emacs | |
| 318 (a single newline character) and the convention used outside Emacs | |
| 319 (the two-character sequence, @sc{crlf}). | |
| 320 | |
| 321 The variable @code{binary-process-input} applies to input sent to the | |
| 322 subprocess, and @code{binary-process-output} applies to output received | |
| 323 from it. A non-@code{nil} value means the data is non-text; @code{nil} | |
| 324 means the data is text, and calls for conversion. | |
| 325 | |
| 326 @defvar binary-process-input | |
| 327 If this variable is @code{nil}, convert newlines to @sc{crlf} sequences in | |
| 328 the input to a synchronous subprocess. | |
| 329 @end defvar | |
| 330 | |
| 331 @defvar binary-process-output | |
| 332 If this variable is @code{nil}, convert @sc{crlf} sequences to newlines in | |
| 333 the output from a synchronous subprocess. | |
| 334 @end defvar | |
| 335 | |
| 336 @xref{Files and MS-DOS}, for related information. | |
| 337 | |
| 338 @node Asynchronous Processes | |
| 339 @section Creating an Asynchronous Process | |
| 340 @cindex asynchronous subprocess | |
| 341 | |
| 342 After an @dfn{asynchronous process} is created, Emacs and the Lisp | |
| 343 program both continue running immediately. The process may thereafter | |
| 344 run in parallel with Emacs, and the two may communicate with each other | |
| 345 using the functions described in following sections. Here we describe | |
| 346 how to create an asynchronous process with @code{start-process}. | |
| 347 | |
| 348 @defun start-process name buffer-or-name program &rest args | |
| 349 This function creates a new asynchronous subprocess and starts the | |
| 350 program @var{program} running in it. It returns a process object that | |
| 351 stands for the new subprocess in Lisp. The argument @var{name} | |
| 352 specifies the name for the process object; if a process with this name | |
| 353 already exists, then @var{name} is modified (by adding @samp{<1>}, etc.) | |
| 354 to be unique. The buffer @var{buffer-or-name} is the buffer to | |
| 355 associate with the process. | |
| 356 | |
| 357 The remaining arguments, @var{args}, are strings that specify command | |
| 358 line arguments for the program. | |
| 359 | |
| 360 In the example below, the first process is started and runs (rather, | |
| 361 sleeps) for 100 seconds. Meanwhile, the second process is started, and | |
| 362 given the name @samp{my-process<1>} for the sake of uniqueness. It | |
| 363 inserts the directory listing at the end of the buffer @samp{foo}, | |
| 364 before the first process finishes. Then it finishes, and a message to | |
| 365 that effect is inserted in the buffer. Much later, the first process | |
| 366 finishes, and another message is inserted in the buffer for it. | |
| 367 | |
| 368 @smallexample | |
| 369 @group | |
| 370 (start-process "my-process" "foo" "sleep" "100") | |
| 371 @result{} #<process my-process> | |
| 372 @end group | |
| 373 | |
| 374 @group | |
| 375 (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin") | |
| 376 @result{} #<process my-process<1>> | |
| 377 | |
| 378 ---------- Buffer: foo ---------- | |
| 379 total 2 | |
| 380 lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs | |
| 381 -rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon | |
| 382 | |
| 383 Process my-process<1> finished | |
| 384 | |
| 385 Process my-process finished | |
| 386 ---------- Buffer: foo ---------- | |
| 387 @end group | |
| 388 @end smallexample | |
| 389 @end defun | |
| 390 | |
| 391 @defun start-process-shell-command name buffer-or-name command &rest command-args | |
| 392 This function is like @code{start-process} except that it uses a shell | |
| 393 to execute the specified command. The argument @var{command} is a shell | |
| 394 command name, and @var{command-args} are the arguments for the shell | |
| 395 command. | |
| 396 @end defun | |
| 397 | |
| 398 @defvar process-connection-type | |
| 399 @cindex pipes | |
| 400 @cindex @sc{pty}s | |
| 401 This variable controls the type of device used to communicate with | |
| 402 asynchronous subprocesses. If it is non-@code{nil}, then @sc{pty}s are | |
| 403 used, when available. Otherwise, pipes are used. | |
| 404 | |
| 405 @sc{pty}s are usually preferable for processes visible to the user, as | |
| 406 in Shell mode, because they allow job control (@kbd{C-c}, @kbd{C-z}, | |
| 407 etc.) to work between the process and its children whereas pipes do not. | |
| 408 For subprocesses used for internal purposes by programs, it is often | |
| 409 better to use a pipe, because they are more efficient. In addition, the | |
| 410 total number of @sc{pty}s is limited on many systems and it is good not | |
| 444 | 411 to waste them. A rule of thumb is to use ptys for processes the user |
| 412 interacts with directly, and pipes for processes that are hidden from | |
| 413 the user. | |
| 0 | 414 |
| 415 The value @code{process-connection-type} is used when | |
| 416 @code{start-process} is called. So you can specify how to communicate | |
| 417 with one subprocess by binding the variable around the call to | |
| 418 @code{start-process}. | |
| 419 | |
| 420 @smallexample | |
| 421 @group | |
| 422 (let ((process-connection-type nil)) ; @r{Use a pipe.} | |
| 423 (start-process @dots{})) | |
| 424 @end group | |
| 425 @end smallexample | |
| 426 | |
| 427 To determine whether a given subprocess actually got a pipe or a | |
| 428 @sc{pty}, use the function @code{process-tty-name} (@pxref{Process | |
| 429 Information}). | |
| 430 @end defvar | |
| 431 | |
| 444 | 432 Lisp functions that manipulate processes usually accept a @var{process} |
| 433 argument. Besides using an actual process object for this argument, you | |
| 434 can use a process name, a buffer object, the name of a buffer, or | |
| 435 @code{nil}. Specifying a buffer or buffer name for the @var{process} | |
| 436 argument means use the process associated with the buffer (or the most | |
| 437 recent one, if there is more than one). @code{nil} means use the | |
| 438 process associated with the current buffer. | |
| 439 @xref{Process Information}. | |
| 440 @xref{Process Buffers}. | |
| 441 | |
| 0 | 442 @node Deleting Processes |
| 443 @section Deleting Processes | |
| 444 @cindex deleting processes | |
| 445 | |
| 446 @dfn{Deleting a process} disconnects XEmacs immediately from the | |
| 447 subprocess, and removes it from the list of active processes. It sends | |
| 448 a signal to the subprocess to make the subprocess terminate, but this is | |
| 449 not guaranteed to happen immediately. The process object itself | |
| 450 continues to exist as long as other Lisp objects point to it. | |
| 451 | |
| 452 You can delete a process explicitly at any time. Processes are | |
| 453 deleted automatically after they terminate, but not necessarily right | |
| 454 away. If you delete a terminated process explicitly before it is | |
| 455 deleted automatically, no harm results. | |
| 456 | |
| 457 @defvar delete-exited-processes | |
| 458 This variable controls automatic deletion of processes that have | |
| 459 terminated (due to calling @code{exit} or to a signal). If it is | |
| 460 @code{nil}, then they continue to exist until the user runs | |
| 461 @code{list-processes}. Otherwise, they are deleted immediately after | |
| 462 they exit. | |
| 463 @end defvar | |
| 464 | |
| 465 @defun delete-process name | |
| 466 This function deletes the process associated with @var{name}, killing it | |
| 467 with a @code{SIGHUP} signal. The argument @var{name} may be a process, | |
| 468 the name of a process, a buffer, or the name of a buffer. | |
| 469 | |
| 470 @smallexample | |
| 471 @group | |
| 472 (delete-process "*shell*") | |
| 473 @result{} nil | |
| 474 @end group | |
| 475 @end smallexample | |
| 476 @end defun | |
| 477 | |
| 478 @defun process-kill-without-query process &optional require-query-p | |
| 479 This function declares that XEmacs need not query the user if | |
| 480 @var{process} is still running when XEmacs is exited. The process will | |
| 481 be deleted silently. If @var{require-query-p} is non-@code{nil}, | |
| 482 then XEmacs @emph{will} query the user (this is the default). The | |
| 483 return value is @code{t} if a query was formerly required, and | |
| 484 @code{nil} otherwise. | |
| 485 | |
| 486 @smallexample | |
| 487 @group | |
| 488 (process-kill-without-query (get-process "shell")) | |
| 489 @result{} t | |
| 490 @end group | |
| 491 @end smallexample | |
| 492 @end defun | |
| 493 | |
| 494 @node Process Information | |
| 495 @section Process Information | |
| 496 | |
| 497 Several functions return information about processes. | |
| 498 @code{list-processes} is provided for interactive use. | |
| 499 | |
| 500 @deffn Command list-processes | |
| 501 This command displays a listing of all living processes. In addition, | |
| 502 it finally deletes any process whose status was @samp{Exited} or | |
| 503 @samp{Signaled}. It returns @code{nil}. | |
| 504 @end deffn | |
| 505 | |
| 506 @defun process-list | |
| 507 This function returns a list of all processes that have not been deleted. | |
| 508 | |
| 509 @smallexample | |
| 510 @group | |
| 511 (process-list) | |
| 512 @result{} (#<process display-time> #<process shell>) | |
| 513 @end group | |
| 514 @end smallexample | |
| 515 @end defun | |
| 516 | |
| 444 | 517 @defun get-process process-name |
| 518 This function returns the process named @var{process-name}. If | |
| 519 @var{process-name} is a string and there is no process with that name, the | |
| 520 value is @code{nil}. If @var{process-name} is actually a process, it is | |
| 521 returned as given. (That is not very useful, so the argument is usually | |
| 522 a name.) For example: | |
| 0 | 523 |
| 524 @smallexample | |
| 525 @group | |
| 526 (get-process "shell") | |
| 527 @result{} #<process shell> | |
| 528 @end group | |
| 529 @end smallexample | |
| 530 @end defun | |
| 531 | |
| 532 @defun process-command process | |
| 533 This function returns the command that was executed to start | |
| 534 @var{process}. This is a list of strings, the first string being the | |
| 535 program executed and the rest of the strings being the arguments that | |
| 536 were given to the program. | |
| 537 | |
| 538 @smallexample | |
| 539 @group | |
| 540 (process-command (get-process "shell")) | |
| 541 @result{} ("/bin/csh" "-i") | |
| 542 @end group | |
| 543 @end smallexample | |
| 544 @end defun | |
| 545 | |
| 546 @defun process-id process | |
| 547 This function returns the @sc{pid} of @var{process}. This is an | |
| 548 integer that distinguishes the process @var{process} from all other | |
| 549 processes running on the same computer at the current time. The | |
| 550 @sc{pid} of a process is chosen by the operating system kernel when the | |
| 551 process is started and remains constant as long as the process exists. | |
| 552 @end defun | |
| 553 | |
| 554 @defun process-name process | |
| 555 This function returns the name of @var{process}. | |
| 556 @end defun | |
| 557 | |
| 444 | 558 @defun process-status process |
| 559 This function returns the status of @var{process} as a symbol. | |
| 560 The argument @var{process} must be a process, a buffer, a | |
| 0 | 561 process name (string) or a buffer name (string). |
| 562 | |
| 563 The possible values for an actual subprocess are: | |
| 564 | |
| 565 @table @code | |
| 566 @item run | |
| 567 for a process that is running. | |
| 568 @item stop | |
| 569 for a process that is stopped but continuable. | |
| 570 @item exit | |
| 571 for a process that has exited. | |
| 572 @item signal | |
| 573 for a process that has received a fatal signal. | |
| 574 @item open | |
| 575 for a network connection that is open. | |
| 576 @item closed | |
| 577 for a network connection that is closed. Once a connection | |
| 578 is closed, you cannot reopen it, though you might be able to open | |
| 579 a new connection to the same place. | |
| 580 @item nil | |
| 444 | 581 if @var{process} does not identify an existing process. |
| 0 | 582 @end table |
| 583 | |
| 584 @smallexample | |
| 585 @group | |
| 586 (process-status "shell") | |
| 587 @result{} run | |
| 588 @end group | |
| 589 @group | |
| 590 (process-status (get-buffer "*shell*")) | |
| 591 @result{} run | |
| 592 @end group | |
| 593 @group | |
| 594 x | |
| 595 @result{} #<process xx<1>> | |
| 596 (process-status x) | |
| 597 @result{} exit | |
| 598 @end group | |
| 599 @end smallexample | |
| 600 | |
| 601 For a network connection, @code{process-status} returns one of the symbols | |
| 602 @code{open} or @code{closed}. The latter means that the other side | |
| 603 closed the connection, or XEmacs did @code{delete-process}. | |
| 604 | |
| 605 In earlier Emacs versions (prior to version 19), the status of a network | |
| 606 connection was @code{run} if open, and @code{exit} if closed. | |
| 607 @end defun | |
| 608 | |
| 609 @defun process-kill-without-query-p process | |
| 610 This function returns whether @var{process} will be killed without | |
| 611 querying the user, if it is running when XEmacs is exited. The default | |
| 612 value is @code{nil}. | |
| 613 @end defun | |
| 614 | |
| 615 @defun process-exit-status process | |
| 616 This function returns the exit status of @var{process} or the signal | |
| 617 number that killed it. (Use the result of @code{process-status} to | |
| 618 determine which of those it is.) If @var{process} has not yet | |
| 619 terminated, the value is 0. | |
| 620 @end defun | |
| 621 | |
| 622 @defun process-tty-name process | |
| 623 This function returns the terminal name that @var{process} is using for | |
| 624 its communication with Emacs---or @code{nil} if it is using pipes | |
| 625 instead of a terminal (see @code{process-connection-type} in | |
| 626 @ref{Asynchronous Processes}). | |
| 627 @end defun | |
| 628 | |
| 629 @node Input to Processes | |
| 630 @section Sending Input to Processes | |
| 631 @cindex process input | |
| 632 | |
| 633 Asynchronous subprocesses receive input when it is sent to them by | |
| 634 XEmacs, which is done with the functions in this section. You must | |
| 635 specify the process to send input to, and the input data to send. The | |
| 636 data appears on the ``standard input'' of the subprocess. | |
| 637 | |
| 638 Some operating systems have limited space for buffered input in a | |
| 444 | 639 @sc{pty}. On these systems, XEmacs sends long input in chunks, with |
| 640 @sc{eof} characters added amidst the other characters, to force the | |
| 641 operating system to periodically drain the input buffer. For most | |
| 642 programs, these @sc{eof}s do no harm. | |
| 0 | 643 |
| 444 | 644 @defun process-send-string process string &optional start end |
| 645 This function sends @var{process} the contents of @var{string} as | |
| 646 standard input. | |
| 647 | |
| 648 The argument @var{process} may be a process or the name of a process, or | |
| 649 a buffer or the name of a buffer, in which case the buffer's process is | |
| 650 used. If it is @code{nil}, the current buffer's process is used. | |
| 651 | |
| 652 Optional arguments @var{start} and @var{end} specify part of @var{string}; | |
|
5089
99f8ebc082d9
Make #'substring an alias of #'subseq; give the latter the byte code.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
653 see @code{subseq}. |
| 0 | 654 |
| 655 The function returns @code{nil}. | |
| 656 | |
| 657 @smallexample | |
| 658 @group | |
| 659 (process-send-string "shell<1>" "ls\n") | |
| 660 @result{} nil | |
| 661 @end group | |
| 662 | |
| 663 | |
| 664 @group | |
| 665 ---------- Buffer: *shell* ---------- | |
| 666 ... | |
| 667 introduction.texi syntax-tables.texi~ | |
| 668 introduction.texi~ text.texi | |
| 669 introduction.txt text.texi~ | |
| 670 ... | |
| 671 ---------- Buffer: *shell* ---------- | |
| 672 @end group | |
| 673 @end smallexample | |
| 674 @end defun | |
| 675 | |
| 444 | 676 @defun process-send-region process start end &optional buffer |
| 0 | 677 This function sends the text in the region defined by @var{start} and |
| 444 | 678 @var{end} as standard input to @var{process}. |
| 679 | |
| 680 The argument @var{process} may be a process or the name of a process, or | |
| 681 a buffer or the name of a buffer, in which case the buffer's process is | |
| 682 used. If it is @code{nil}, the current buffer's process is used. | |
| 0 | 683 |
| 684 An error is signaled unless both @var{start} and @var{end} are | |
| 685 integers or markers that indicate positions in the current buffer. (It | |
| 686 is unimportant which number is larger.) | |
| 444 | 687 @end defun |
| 0 | 688 |
| 444 | 689 @defun process-send-eof &optional process |
| 690 This function makes @var{process} see an end-of-file in its | |
| 0 | 691 input. The @sc{eof} comes after any text already sent to it. |
| 692 | |
| 444 | 693 @var{process} may be a process, a buffer, the name of a process or |
| 694 buffer, or @code{nil}, indicating the current buffer's process. An | |
| 695 error is signaled if @var{process} does not identify any process. | |
| 0 | 696 |
| 444 | 697 The function returns the process object identified by @var{process}. |
| 0 | 698 |
| 699 @smallexample | |
| 700 @group | |
| 701 (process-send-eof "shell") | |
| 702 @result{} "shell" | |
| 703 @end group | |
| 704 @end smallexample | |
| 705 @end defun | |
| 706 | |
| 707 @node Signals to Processes | |
| 708 @section Sending Signals to Processes | |
| 709 @cindex process signals | |
| 710 @cindex sending signals | |
| 711 @cindex signals | |
| 712 | |
| 713 @dfn{Sending a signal} to a subprocess is a way of interrupting its | |
| 714 activities. There are several different signals, each with its own | |
| 715 meaning. The set of signals and their names is defined by the operating | |
| 716 system. For example, the signal @code{SIGINT} means that the user has | |
| 717 typed @kbd{C-c}, or that some analogous thing has happened. | |
| 718 | |
| 719 Each signal has a standard effect on the subprocess. Most signals | |
| 720 kill the subprocess, but some stop or resume execution instead. Most | |
| 721 signals can optionally be handled by programs; if the program handles | |
| 722 the signal, then we can say nothing in general about its effects. | |
| 723 | |
| 724 The set of signals and their names is defined by the operating system; | |
| 725 XEmacs has facilities for sending only a few of the signals that are | |
| 726 defined. XEmacs can send signals only to its own subprocesses. | |
| 727 | |
| 728 You can send signals explicitly by calling the functions in this | |
| 729 section. XEmacs also sends signals automatically at certain times: | |
| 730 killing a buffer sends a @code{SIGHUP} signal to all its associated | |
| 731 processes; killing XEmacs sends a @code{SIGHUP} signal to all remaining | |
| 442 | 732 processes. (@code{SIGHUP} is a signal that indicates that the |
| 733 connection between the user and the process is broken, for example if a | |
| 734 connection via a telephone line is hung up.) | |
| 0 | 735 |
| 736 Each of the signal-sending functions takes two optional arguments: | |
| 442 | 737 @var{process} and @var{current-group}. |
| 0 | 738 |
| 442 | 739 The argument @var{process} must be either a process or a buffer, |
| 740 the name of one, or @code{nil}. If it is @code{nil}, the process | |
| 741 defaults to the process associated with the current buffer. An error is | |
| 742 signaled if @var{process} does not identify a process. | |
| 0 | 743 |
| 744 The argument @var{current-group} is a flag that makes a difference | |
| 745 when you are running a job-control shell as an XEmacs subprocess. If it | |
| 442 | 746 is non-@code{nil}, then the signal is sent to the current foreground |
| 747 process group of the terminal that XEmacs uses to communicate with the | |
| 748 subprocess. If the process is a job-control shell, this means the | |
| 749 shell's current subjob. If it is @code{nil}, the signal is sent to the | |
| 750 process group of the immediate subprocess of XEmacs. If the subprocess | |
| 751 is a job-control shell, this is the shell itself. | |
| 0 | 752 |
| 753 The flag @var{current-group} has no effect when a pipe is used to | |
| 754 communicate with the subprocess, because the operating system does not | |
| 755 support the distinction in the case of pipes. For the same reason, | |
| 756 job-control shells won't work when a pipe is used. See | |
| 757 @code{process-connection-type} in @ref{Asynchronous Processes}. | |
| 758 | |
| 442 | 759 Some of the functions below take a @var{signal} argument, which |
|
4885
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4771
diff
changeset
|
760 identifies a signal to be sent. It must be either a fixnum or a |
| 442 | 761 symbol which names the signal, like @code{SIGSEGV}. |
| 762 | |
| 763 @defun process-send-signal signal &optional process current-group | |
| 764 This function sends the signal @var{signal} to the process @var{process}. | |
| 765 The following functions can be implemented in terms of | |
| 766 @code{process-send-signal}. | |
| 0 | 767 @end defun |
| 768 | |
| 442 | 769 @defun interrupt-process &optional process current-group |
| 770 This function interrupts the process @var{process} by sending the signal | |
| 771 @code{SIGINT}. Outside of XEmacs, typing the ``interrupt character'' | |
| 772 (normally @kbd{C-c}) sends this signal. When the argument | |
| 773 @var{current-group} is non-@code{nil}, you can think of this function as | |
| 774 ``typing @kbd{C-c}'' on the terminal by which XEmacs talks to the | |
| 775 subprocess. | |
| 776 @end defun | |
| 777 | |
| 778 @defun kill-process &optional process current-group | |
| 779 This function kills the process @var{process} by sending the | |
| 0 | 780 signal @code{SIGKILL}. This signal kills the subprocess immediately, |
| 781 and cannot be handled by the subprocess. | |
| 782 @end defun | |
| 783 | |
| 442 | 784 @defun quit-process &optional process current-group |
| 0 | 785 This function sends the signal @code{SIGQUIT} to the process |
| 442 | 786 @var{process}. This signal is the one sent by the ``quit |
| 787 character'' (usually @kbd{C-\}) when you are not inside XEmacs. | |
| 0 | 788 @end defun |
| 789 | |
| 442 | 790 @defun stop-process &optional process current-group |
| 791 This function stops the process @var{process} by sending the | |
| 0 | 792 signal @code{SIGTSTP}. Use @code{continue-process} to resume its |
| 793 execution. | |
| 794 | |
| 795 On systems with job control, the ``stop character'' (usually @kbd{C-z}) | |
| 796 sends this signal (outside of XEmacs). When @var{current-group} is | |
| 797 non-@code{nil}, you can think of this function as ``typing @kbd{C-z}'' | |
| 798 on the terminal XEmacs uses to communicate with the subprocess. | |
| 799 @end defun | |
| 800 | |
| 442 | 801 @defun continue-process &optional process current-group |
| 0 | 802 This function resumes execution of the process @var{process} by sending |
| 442 | 803 it the signal @code{SIGCONT}. This presumes that @var{process} was |
| 0 | 804 stopped previously. |
| 805 @end defun | |
| 806 | |
| 444 | 807 @deffn Command signal-process pid signal |
| 442 | 808 This function sends a signal to the process with process id @var{pid}, |
| 809 which need not be a child of XEmacs. The argument @var{signal} | |
| 810 specifies which signal to send. | |
| 444 | 811 @end deffn |
| 0 | 812 |
| 813 @node Output from Processes | |
| 814 @section Receiving Output from Processes | |
| 815 @cindex process output | |
| 816 @cindex output from processes | |
| 817 | |
| 818 There are two ways to receive the output that a subprocess writes to | |
| 819 its standard output stream. The output can be inserted in a buffer, | |
| 820 which is called the associated buffer of the process, or a function | |
| 821 called the @dfn{filter function} can be called to act on the output. If | |
| 822 the process has no buffer and no filter function, its output is | |
| 823 discarded. | |
| 824 | |
| 825 @menu | |
| 826 * Process Buffers:: If no filter, output is put in a buffer. | |
| 827 * Filter Functions:: Filter functions accept output from the process. | |
| 828 * Accepting Output:: Explicitly permitting subprocess output. | |
| 829 Waiting for subprocess output. | |
| 830 @end menu | |
| 831 | |
| 832 @node Process Buffers | |
| 833 @subsection Process Buffers | |
| 834 | |
| 835 A process can (and usually does) have an @dfn{associated buffer}, | |
| 836 which is an ordinary Emacs buffer that is used for two purposes: storing | |
| 837 the output from the process, and deciding when to kill the process. You | |
| 838 can also use the buffer to identify a process to operate on, since in | |
| 839 normal practice only one process is associated with any given buffer. | |
| 840 Many applications of processes also use the buffer for editing input to | |
| 841 be sent to the process, but this is not built into XEmacs Lisp. | |
| 842 | |
| 843 Unless the process has a filter function (@pxref{Filter Functions}), | |
| 844 its output is inserted in the associated buffer. The position to insert | |
| 845 the output is determined by the @code{process-mark}, which is then | |
| 846 updated to point to the end of the text just inserted. Usually, but not | |
| 847 always, the @code{process-mark} is at the end of the buffer. | |
| 848 | |
| 849 @defun process-buffer process | |
| 850 This function returns the associated buffer of the process | |
| 851 @var{process}. | |
| 852 | |
| 853 @smallexample | |
| 854 @group | |
| 855 (process-buffer (get-process "shell")) | |
| 856 @result{} #<buffer *shell*> | |
| 857 @end group | |
| 858 @end smallexample | |
| 859 @end defun | |
| 860 | |
| 861 @defun process-mark process | |
| 862 This function returns the process marker for @var{process}, which is the | |
| 863 marker that says where to insert output from the process. | |
| 864 | |
| 865 If @var{process} does not have a buffer, @code{process-mark} returns a | |
| 866 marker that points nowhere. | |
| 867 | |
| 868 Insertion of process output in a buffer uses this marker to decide where | |
| 869 to insert, and updates it to point after the inserted text. That is why | |
| 870 successive batches of output are inserted consecutively. | |
| 871 | |
| 872 Filter functions normally should use this marker in the same fashion | |
| 873 as is done by direct insertion of output in the buffer. A good | |
| 874 example of a filter function that uses @code{process-mark} is found at | |
| 875 the end of the following section. | |
| 876 | |
| 877 When the user is expected to enter input in the process buffer for | |
| 878 transmission to the process, the process marker is useful for | |
| 879 distinguishing the new input from previous output. | |
| 880 @end defun | |
| 881 | |
| 882 @defun set-process-buffer process buffer | |
| 883 This function sets the buffer associated with @var{process} to | |
| 884 @var{buffer}. If @var{buffer} is @code{nil}, the process becomes | |
| 885 associated with no buffer. | |
| 886 @end defun | |
| 887 | |
| 888 @defun get-buffer-process buffer-or-name | |
| 889 This function returns the process associated with @var{buffer-or-name}. | |
| 444 | 890 If there are several processes associated with @var{buffer-or-name}, |
| 891 then one is chosen. (Presently, the one chosen is the one most recently | |
| 892 created.) It is usually a bad idea to have more than one process | |
| 893 associated with the same buffer. | |
| 0 | 894 |
| 895 @smallexample | |
| 896 @group | |
| 897 (get-buffer-process "*shell*") | |
| 898 @result{} #<process shell> | |
| 899 @end group | |
| 900 @end smallexample | |
| 901 | |
| 902 Killing the process's buffer deletes the process, which kills the | |
| 903 subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}). | |
| 904 @end defun | |
| 905 | |
| 906 @node Filter Functions | |
| 907 @subsection Process Filter Functions | |
| 908 @cindex filter function | |
| 909 @cindex process filter | |
| 910 | |
| 911 A process @dfn{filter function} is a function that receives the | |
| 912 standard output from the associated process. If a process has a filter, | |
| 913 then @emph{all} output from that process is passed to the filter. The | |
| 914 process buffer is used directly for output from the process only when | |
| 915 there is no filter. | |
| 916 | |
| 917 A filter function must accept two arguments: the associated process and | |
| 918 a string, which is the output. The function is then free to do whatever it | |
| 919 chooses with the output. | |
| 920 | |
| 921 A filter function runs only while XEmacs is waiting (e.g., for terminal | |
| 922 input, or for time to elapse, or for process output). This avoids the | |
| 923 timing errors that could result from running filters at random places in | |
| 924 the middle of other Lisp programs. You may explicitly cause Emacs to | |
| 925 wait, so that filter functions will run, by calling @code{sit-for} or | |
| 926 @code{sleep-for} (@pxref{Waiting}), or @code{accept-process-output} | |
| 927 (@pxref{Accepting Output}). Emacs is also waiting when the command loop | |
| 928 is reading input. | |
| 929 | |
| 930 Quitting is normally inhibited within a filter function---otherwise, | |
| 931 the effect of typing @kbd{C-g} at command level or to quit a user | |
| 932 command would be unpredictable. If you want to permit quitting inside a | |
| 933 filter function, bind @code{inhibit-quit} to @code{nil}. | |
| 934 @xref{Quitting}. | |
| 935 | |
| 936 If an error happens during execution of a filter function, it is | |
| 937 caught automatically, so that it doesn't stop the execution of whatever | |
| 938 program was running when the filter function was started. However, if | |
| 939 @code{debug-on-error} is non-@code{nil}, the error-catching is turned | |
| 940 off. This makes it possible to use the Lisp debugger to debug the | |
| 941 filter function. @xref{Debugger}. | |
| 942 | |
| 943 Many filter functions sometimes or always insert the text in the | |
| 944 process's buffer, mimicking the actions of XEmacs when there is no | |
| 945 filter. Such filter functions need to use @code{set-buffer} in order to | |
| 946 be sure to insert in that buffer. To avoid setting the current buffer | |
| 947 semipermanently, these filter functions must use @code{unwind-protect} | |
| 948 to make sure to restore the previous current buffer. They should also | |
| 949 update the process marker, and in some cases update the value of point. | |
| 950 Here is how to do these things: | |
| 951 | |
| 952 @smallexample | |
| 953 @group | |
| 444 | 954 (defun ordinary-insertion-filter (process string) |
| 0 | 955 (let ((old-buffer (current-buffer))) |
| 956 (unwind-protect | |
| 957 (let (moving) | |
| 444 | 958 (set-buffer (process-buffer process)) |
| 959 (setq moving (= (point) (process-mark process))) | |
| 0 | 960 @end group |
| 961 @group | |
| 962 (save-excursion | |
| 963 ;; @r{Insert the text, moving the process-marker.} | |
| 444 | 964 (goto-char (process-mark process)) |
| 0 | 965 (insert string) |
| 444 | 966 (set-marker (process-mark process) (point))) |
| 967 (if moving (goto-char (process-mark process)))) | |
| 0 | 968 (set-buffer old-buffer)))) |
| 969 @end group | |
| 970 @end smallexample | |
| 971 | |
| 972 @noindent | |
| 973 The reason to use an explicit @code{unwind-protect} rather than letting | |
| 974 @code{save-excursion} restore the current buffer is so as to preserve | |
| 975 the change in point made by @code{goto-char}. | |
| 976 | |
| 977 To make the filter force the process buffer to be visible whenever new | |
| 978 text arrives, insert the following line just before the | |
| 979 @code{unwind-protect}: | |
| 980 | |
| 981 @smallexample | |
| 444 | 982 (display-buffer (process-buffer process)) |
| 0 | 983 @end smallexample |
| 984 | |
| 985 To force point to move to the end of the new output no matter where | |
| 986 it was previously, eliminate the variable @code{moving} and call | |
| 987 @code{goto-char} unconditionally. | |
| 988 | |
| 989 In earlier Emacs versions, every filter function that did regexp | |
| 990 searching or matching had to explicitly save and restore the match data. | |
| 991 Now Emacs does this automatically; filter functions never need to do it | |
| 992 explicitly. @xref{Match Data}. | |
| 993 | |
| 994 A filter function that writes the output into the buffer of the | |
| 995 process should check whether the buffer is still alive. If it tries to | |
| 996 insert into a dead buffer, it will get an error. If the buffer is dead, | |
| 997 @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}. | |
| 998 | |
| 999 The output to the function may come in chunks of any size. A program | |
| 1000 that produces the same output twice in a row may send it as one batch | |
| 1001 of 200 characters one time, and five batches of 40 characters the next. | |
| 1002 | |
| 1003 @defun set-process-filter process filter | |
| 1004 This function gives @var{process} the filter function @var{filter}. If | |
| 1005 @var{filter} is @code{nil}, then the process will have no filter. If | |
| 1006 @var{filter} is @code{t}, then no output from the process will be | |
| 1007 accepted until the filter is changed. (Output received during this | |
| 1008 time is not discarded, but is queued, and will be processed as soon | |
| 1009 as the filter is changed.) | |
| 1010 @end defun | |
| 1011 | |
| 1012 @defun process-filter process | |
| 1013 This function returns the filter function of @var{process}, or @code{nil} | |
| 1014 if it has none. @code{t} means that output processing has been stopped. | |
| 1015 @end defun | |
| 1016 | |
| 1017 Here is an example of use of a filter function: | |
| 1018 | |
| 1019 @smallexample | |
| 1020 @group | |
| 1021 (defun keep-output (process output) | |
| 1022 (setq kept (cons output kept))) | |
| 1023 @result{} keep-output | |
| 1024 @end group | |
| 1025 @group | |
| 1026 (setq kept nil) | |
| 1027 @result{} nil | |
| 1028 @end group | |
| 1029 @group | |
| 1030 (set-process-filter (get-process "shell") 'keep-output) | |
| 1031 @result{} keep-output | |
| 1032 @end group | |
| 1033 @group | |
| 1034 (process-send-string "shell" "ls ~/other\n") | |
| 1035 @result{} nil | |
| 1036 kept | |
| 1037 @result{} ("lewis@@slug[8] % " | |
| 1038 @end group | |
| 1039 @group | |
| 1040 "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~ | |
| 1041 address.txt backup.psf kolstad.psf | |
| 1042 backup.bib~ david.mss resume-Dec-86.mss~ | |
| 1043 backup.err david.psf resume-Dec.psf | |
| 1044 backup.mss dland syllabus.mss | |
| 1045 " | |
| 1046 "#backups.mss# backup.mss~ kolstad.mss | |
| 1047 ") | |
| 1048 @end group | |
| 1049 @end smallexample | |
| 1050 | |
| 1051 @ignore @c The code in this example doesn't show the right way to do things. | |
| 1052 Here is another, more realistic example, which demonstrates how to use | |
| 1053 the process mark to do insertion in the same fashion as is done when | |
| 1054 there is no filter function: | |
| 1055 | |
| 1056 @smallexample | |
| 1057 @group | |
| 1058 ;; @r{Insert input in the buffer specified by @code{my-shell-buffer}} | |
| 1059 ;; @r{and make sure that buffer is shown in some window.} | |
| 444 | 1060 (defun my-process-filter (process string) |
| 0 | 1061 (let ((cur (selected-window)) |
| 1062 (pop-up-windows t)) | |
| 1063 (pop-to-buffer my-shell-buffer) | |
| 1064 @end group | |
| 1065 @group | |
| 1066 (goto-char (point-max)) | |
| 444 | 1067 (insert string) |
| 1068 (set-marker (process-mark process) (point-max)) | |
| 0 | 1069 (select-window cur))) |
| 1070 @end group | |
| 1071 @end smallexample | |
| 1072 @end ignore | |
| 1073 | |
| 1074 @node Accepting Output | |
| 1075 @subsection Accepting Output from Processes | |
| 1076 | |
| 1077 Output from asynchronous subprocesses normally arrives only while | |
| 1078 XEmacs is waiting for some sort of external event, such as elapsed time | |
| 1079 or terminal input. Occasionally it is useful in a Lisp program to | |
| 1080 explicitly permit output to arrive at a specific point, or even to wait | |
| 1081 until output arrives from a process. | |
| 1082 | |
| 1083 @defun accept-process-output &optional process seconds millisec | |
| 1084 This function allows XEmacs to read pending output from processes. The | |
| 1085 output is inserted in the associated buffers or given to their filter | |
| 1086 functions. If @var{process} is non-@code{nil} then this function does | |
| 1087 not return until some output has been received from @var{process}. | |
| 1088 | |
| 1089 @c Emacs 19 feature | |
| 1090 The arguments @var{seconds} and @var{millisec} let you specify timeout | |
| 1091 periods. The former specifies a period measured in seconds and the | |
| 1092 latter specifies one measured in milliseconds. The two time periods | |
| 1093 thus specified are added together, and @code{accept-process-output} | |
| 1094 returns after that much time whether or not there has been any | |
| 1095 subprocess output. Note that @var{seconds} is allowed to be a | |
| 1096 floating-point number; thus, there is no need to ever use | |
| 1097 @var{millisec}. (It is retained for compatibility purposes.) | |
| 1098 @ignore Not in XEmacs | |
| 1099 | |
| 1100 The argument @var{seconds} need not be an integer. If it is a floating | |
| 1101 point number, this function waits for a fractional number of seconds. | |
| 1102 Some systems support only a whole number of seconds; on these systems, | |
| 1103 @var{seconds} is rounded down. If the system doesn't support waiting | |
| 1104 fractions of a second, you get an error if you specify nonzero | |
| 1105 @var{millisec}. | |
| 1106 | |
| 1107 Not all operating systems support waiting periods other than multiples | |
| 1108 of a second; on those that do not, you get an error if you specify | |
| 1109 nonzero @var{millisec}. | |
| 1110 @end ignore | |
| 1111 | |
| 1112 The function @code{accept-process-output} returns non-@code{nil} if it | |
| 1113 did get some output, or @code{nil} if the timeout expired before output | |
| 1114 arrived. | |
| 1115 @end defun | |
| 1116 | |
| 1117 @node Sentinels | |
| 1118 @section Sentinels: Detecting Process Status Changes | |
| 1119 @cindex process sentinel | |
| 1120 @cindex sentinel | |
| 1121 | |
| 1122 A @dfn{process sentinel} is a function that is called whenever the | |
| 1123 associated process changes status for any reason, including signals | |
| 1124 (whether sent by XEmacs or caused by the process's own actions) that | |
| 1125 terminate, stop, or continue the process. The process sentinel is also | |
| 1126 called if the process exits. The sentinel receives two arguments: the | |
| 1127 process for which the event occurred, and a string describing the type | |
| 1128 of event. | |
| 1129 | |
| 1130 The string describing the event looks like one of the following: | |
| 1131 | |
| 1132 @itemize @bullet | |
| 442 | 1133 @item |
| 0 | 1134 @code{"finished\n"}. |
| 1135 | |
| 1136 @item | |
| 1137 @code{"exited abnormally with code @var{exitcode}\n"}. | |
| 1138 | |
| 1139 @item | |
| 1140 @code{"@var{name-of-signal}\n"}. | |
| 1141 | |
| 1142 @item | |
| 1143 @code{"@var{name-of-signal} (core dumped)\n"}. | |
| 1144 @end itemize | |
| 1145 | |
| 1146 A sentinel runs only while XEmacs is waiting (e.g., for terminal input, | |
| 1147 or for time to elapse, or for process output). This avoids the timing | |
| 1148 errors that could result from running them at random places in the | |
| 1149 middle of other Lisp programs. A program can wait, so that sentinels | |
| 1150 will run, by calling @code{sit-for} or @code{sleep-for} | |
| 1151 (@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting | |
| 1152 Output}). Emacs is also waiting when the command loop is reading input. | |
| 1153 | |
| 1154 Quitting is normally inhibited within a sentinel---otherwise, the | |
| 1155 effect of typing @kbd{C-g} at command level or to quit a user command | |
| 1156 would be unpredictable. If you want to permit quitting inside a | |
| 1157 sentinel, bind @code{inhibit-quit} to @code{nil}. @xref{Quitting}. | |
| 1158 | |
| 1159 A sentinel that writes the output into the buffer of the process | |
| 1160 should check whether the buffer is still alive. If it tries to insert | |
| 1161 into a dead buffer, it will get an error. If the buffer is dead, | |
| 1162 @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}. | |
| 1163 | |
| 1164 If an error happens during execution of a sentinel, it is caught | |
| 1165 automatically, so that it doesn't stop the execution of whatever | |
| 1166 programs was running when the sentinel was started. However, if | |
| 1167 @code{debug-on-error} is non-@code{nil}, the error-catching is turned | |
| 1168 off. This makes it possible to use the Lisp debugger to debug the | |
| 1169 sentinel. @xref{Debugger}. | |
| 1170 | |
| 1171 In earlier Emacs versions, every sentinel that did regexp searching or | |
| 1172 matching had to explicitly save and restore the match data. Now Emacs | |
| 1173 does this automatically; sentinels never need to do it explicitly. | |
| 1174 @xref{Match Data}. | |
| 1175 | |
| 1176 @defun set-process-sentinel process sentinel | |
| 1177 This function associates @var{sentinel} with @var{process}. If | |
| 1178 @var{sentinel} is @code{nil}, then the process will have no sentinel. | |
| 1179 The default behavior when there is no sentinel is to insert a message in | |
| 1180 the process's buffer when the process status changes. | |
| 1181 | |
| 1182 @smallexample | |
| 1183 @group | |
| 1184 (defun msg-me (process event) | |
| 1185 (princ | |
| 1186 (format "Process: %s had the event `%s'" process event))) | |
| 1187 (set-process-sentinel (get-process "shell") 'msg-me) | |
| 1188 @result{} msg-me | |
| 1189 @end group | |
| 1190 @group | |
| 1191 (kill-process (get-process "shell")) | |
| 1192 @print{} Process: #<process shell> had the event `killed' | |
| 1193 @result{} #<process shell> | |
| 1194 @end group | |
| 1195 @end smallexample | |
| 1196 @end defun | |
| 1197 | |
| 1198 @defun process-sentinel process | |
| 1199 This function returns the sentinel of @var{process}, or @code{nil} if it | |
| 1200 has none. | |
| 1201 @end defun | |
| 1202 | |
| 1203 @defun waiting-for-user-input-p | |
| 1204 While a sentinel or filter function is running, this function returns | |
| 1205 non-@code{nil} if XEmacs was waiting for keyboard input from the user at | |
| 1206 the time the sentinel or filter function was called, @code{nil} if it | |
| 1207 was not. | |
| 1208 @end defun | |
| 1209 | |
| 1210 @c XEmacs feature | |
| 1211 @node Process Window Size | |
| 1212 @section Process Window Size | |
| 1213 @cindex process window size | |
| 1214 | |
| 1215 @defun set-process-window-size process height width | |
| 1216 This function tells @var{process} that its logical window size is | |
| 1217 @var{height} by @var{width} characters. This is principally useful | |
| 1218 with pty's. | |
| 1219 @end defun | |
| 1220 | |
| 1221 @node Transaction Queues | |
| 1222 @section Transaction Queues | |
| 1223 @cindex transaction queue | |
| 1224 | |
| 1225 You can use a @dfn{transaction queue} for more convenient communication | |
| 1226 with subprocesses using transactions. First use @code{tq-create} to | |
| 1227 create a transaction queue communicating with a specified process. Then | |
| 1228 you can call @code{tq-enqueue} to send a transaction. | |
| 1229 | |
| 1230 @defun tq-create process | |
| 1231 This function creates and returns a transaction queue communicating with | |
| 1232 @var{process}. The argument @var{process} should be a subprocess | |
| 1233 capable of sending and receiving streams of bytes. It may be a child | |
| 1234 process, or it may be a TCP connection to a server, possibly on another | |
| 1235 machine. | |
| 1236 @end defun | |
| 1237 | |
| 1238 @defun tq-enqueue queue question regexp closure fn | |
| 1239 This function sends a transaction to queue @var{queue}. Specifying the | |
| 1240 queue has the effect of specifying the subprocess to talk to. | |
| 1241 | |
| 1242 The argument @var{question} is the outgoing message that starts the | |
| 1243 transaction. The argument @var{fn} is the function to call when the | |
| 1244 corresponding answer comes back; it is called with two arguments: | |
| 1245 @var{closure}, and the answer received. | |
| 1246 | |
| 1247 The argument @var{regexp} is a regular expression that should match the | |
| 1248 entire answer, but nothing less; that's how @code{tq-enqueue} determines | |
| 1249 where the answer ends. | |
| 1250 | |
| 1251 The return value of @code{tq-enqueue} itself is not meaningful. | |
| 1252 @end defun | |
| 1253 | |
| 1254 @defun tq-close queue | |
| 1255 Shut down transaction queue @var{queue}, waiting for all pending transactions | |
| 1256 to complete, and then terminate the connection or child process. | |
| 1257 @end defun | |
| 1258 | |
| 1259 Transaction queues are implemented by means of a filter function. | |
| 1260 @xref{Filter Functions}. | |
| 1261 | |
| 1262 @node Network | |
| 1263 @section Network Connections | |
| 1264 @cindex network connection | |
| 1265 @cindex TCP | |
| 1266 | |
| 1267 XEmacs Lisp programs can open TCP network connections to other processes on | |
| 1268 the same machine or other machines. A network connection is handled by Lisp | |
| 1269 much like a subprocess, and is represented by a process object. | |
| 1270 However, the process you are communicating with is not a child of the | |
| 1271 XEmacs process, so you can't kill it or send it signals. All you can do | |
| 1272 is send and receive data. @code{delete-process} closes the connection, | |
| 1273 but does not kill the process at the other end; that process must decide | |
| 1274 what to do about closure of the connection. | |
| 1275 | |
| 1276 You can distinguish process objects representing network connections | |
| 1277 from those representing subprocesses with the @code{process-status} | |
| 1278 function. It always returns either @code{open} or @code{closed} for a | |
| 1279 network connection, and it never returns either of those values for a | |
| 1280 real subprocess. @xref{Process Information}. | |
| 1281 | |
| 444 | 1282 @defun open-network-stream name buffer-or-name host service &optional protocol |
| 0 | 1283 This function opens a TCP connection for a service to a host. It |
| 1284 returns a process object to represent the connection. | |
| 1285 | |
| 444 | 1286 Input and output work as for other process objects. |
| 1287 @code{delete-process} closes the connection. | |
| 1288 | |
| 0 | 1289 The @var{name} argument specifies the name for the process object. It |
| 1290 is modified as necessary to make it unique. | |
| 1291 | |
| 1292 The @var{buffer-or-name} argument is the buffer to associate with the | |
| 444 | 1293 connection. It can be a buffer or the name of one. Output from the |
| 1294 connection is inserted in the buffer, unless you specify a filter | |
| 1295 function to handle the output. If @var{buffer-or-name} is @code{nil}, | |
| 1296 it means that the connection is not associated with any buffer. | |
| 0 | 1297 |
| 1298 The arguments @var{host} and @var{service} specify where to connect to; | |
| 1299 @var{host} is the host name or IP address (a string), and @var{service} | |
| 1300 is the name of a defined network service (a string) or a port number (an | |
| 1301 integer). | |
| 444 | 1302 |
| 1303 Optional fifth arg @var{protocol} is the network protocol to use. | |
| 1304 Currently only @code{tcp} (Transmission Control Protocol) and @code{udp} | |
| 1305 (User Datagram Protocol) are supported. When omitted, @code{tcp} is assumed. | |
| 1306 | |
| 1307 Output via @code{process-send-string} and input via buffer or filter | |
| 1308 (see @code{set-process-filter}) are stream-oriented. That means | |
| 1309 UDP datagrams are not guaranteed to be sent and received in | |
| 1310 discrete packets. (But small datagrams around 500 bytes that are not | |
| 1311 truncated by @code{process-send-string} are usually fine.) Note further | |
| 1312 that the UDP protocol does not guard against lost packets. | |
| 0 | 1313 @end defun |