mirrored from git://git.sv.gnu.org/emacs.git
/
processes.texi
3636 lines (3040 loc) · 147 KB
/
processes.texi
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990--1995, 1998--1999, 2001--2021 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Processes
@chapter Processes
@cindex child process
@cindex parent process
@cindex subprocess
@cindex process
In the terminology of operating systems, a @dfn{process} is a space in
which a program can execute. Emacs runs in a process. Emacs Lisp
programs can invoke other programs in processes of their own. These are
called @dfn{subprocesses} or @dfn{child processes} of the Emacs process,
which is their @dfn{parent process}.
A subprocess of Emacs may be @dfn{synchronous} or @dfn{asynchronous},
depending on how it is created. When you create a synchronous
subprocess, the Lisp program waits for the subprocess to terminate
before continuing execution. When you create an asynchronous
subprocess, it can run in parallel with the Lisp program. This kind of
subprocess is represented within Emacs by a Lisp object which is also
called a ``process''. Lisp programs can use this object to communicate
with the subprocess or to control it. For example, you can send
signals, obtain status information, receive output from the process, or
send input to it.
In addition to processes that run programs, Lisp programs can open
connections of several types to devices or processes running on the
same machine or on other machines. The supported connection types
are: TCP and UDP network connections, serial port connections, and
pipe connections. Each such connection is also represented by a
process object.
@defun processp object
This function returns @code{t} if @var{object} represents an Emacs
process object, @code{nil} otherwise. The process object can
represent a subprocess running a program or a connection of any
supported type.
@end defun
In addition to subprocesses of the current Emacs session, you can
also access other processes running on your machine. @xref{System
Processes}.
@menu
* Subprocess Creation:: Functions that start subprocesses.
* Shell Arguments:: Quoting an argument to pass it to a shell.
* Synchronous Processes:: Details of using synchronous subprocesses.
* Asynchronous Processes:: Starting up an asynchronous subprocess.
* Deleting Processes:: Eliminating an asynchronous subprocess.
* Process Information:: Accessing run-status and other attributes.
* Input to Processes:: Sending input to an asynchronous subprocess.
* Signals to Processes:: Stopping, continuing or interrupting
an asynchronous subprocess.
* Output from Processes:: Collecting output from an asynchronous subprocess.
* Sentinels:: Sentinels run when process run-status changes.
* Query Before Exit:: Whether to query if exiting will kill a process.
* System Processes:: Accessing other processes running on your system.
* Transaction Queues:: Transaction-based communication with subprocesses.
* Network:: Opening network connections.
* Network Servers:: Network servers let Emacs accept net connections.
* Datagrams:: UDP network connections.
* Low-Level Network:: Lower-level but more general function
to create connections and servers.
* Misc Network:: Additional relevant functions for net connections.
* Serial Ports:: Communicating with serial ports.
* Byte Packing:: Using bindat to pack and unpack binary data.
@end menu
@node Subprocess Creation
@section Functions that Create Subprocesses
@cindex create subprocess
@cindex process creation
There are three primitives that create a new subprocess in which to run
a program. One of them, @code{make-process}, creates an asynchronous
process and returns a process object (@pxref{Asynchronous Processes}).
The other two, @code{call-process} and @code{call-process-region},
create a synchronous process and do not return a process object
(@pxref{Synchronous Processes}). There are various higher-level
functions that make use of these primitives to run particular types of
process.
Synchronous and asynchronous processes are explained in the following
sections. Since the three functions are all called in a similar
fashion, their common arguments are described here.
@cindex execute program
@cindex @env{PATH} environment variable
@cindex @env{HOME} environment variable
In all cases, the functions specify the program to be run. An error
is signaled if the file is not found or cannot be executed. If the
file name is relative, the variable @code{exec-path} contains a list
of directories to search. Emacs initializes @code{exec-path} when it
starts up, based on the value of the environment variable @env{PATH}.
The standard file name constructs, @samp{~}, @samp{.}, and @samp{..},
are interpreted as usual in @code{exec-path}, but environment variable
substitutions (@samp{$HOME}, etc.)@: are not recognized; use
@code{substitute-in-file-name} to perform them (@pxref{File Name
Expansion}). @code{nil} in this list refers to
@code{default-directory}.
Executing a program can also try adding suffixes to the specified
name:
@defopt exec-suffixes
This variable is a list of suffixes (strings) to try adding to the
specified program file name. The list should include @code{""} if you
want the name to be tried exactly as specified. The default value is
system-dependent.
@end defopt
@strong{Please note:} The argument @var{program} contains only the
name of the program file; it may not contain any command-line
arguments. You must use a separate argument, @var{args}, to provide
those, as described below.
Each of the subprocess-creating functions has a @var{buffer-or-name}
argument that specifies where the output from the program will go. It
should be a buffer or a buffer name; if it is a buffer name, that will
create the buffer if it does not already exist. It can also be
@code{nil}, which says to discard the output, unless a custom filter
function handles it. (@xref{Filter Functions}, and @ref{Read and
Print}.) Normally, you should avoid having multiple processes send
output to the same buffer because their output would be intermixed
randomly. For synchronous processes, you can send the output to a
file instead of a buffer (and the corresponding argument is therefore
more appropriately called @var{destination}). By default, both
standard output and standard error streams go to the same destination,
but all the 3 primitives allow optionally to direct the standard error
stream to a different destination.
@cindex program arguments
All three of the subprocess-creating functions allow to specify
command-line arguments for the process to run. For @code{call-process}
and @code{call-process-region}, these come in the form of a
@code{&rest} argument, @var{args}. For @code{make-process}, both the
program to run and its command-line arguments are specified as a list
of strings. The command-line arguments must all be strings, and they
are supplied to the program as separate argument strings. Wildcard
characters and other shell constructs have no special meanings in
these strings, since the strings are passed directly to the specified
program.
@cindex environment variables, subprocesses
The subprocess inherits its environment from Emacs, but you can
specify overrides for it with @code{process-environment}. @xref{System
Environment}. The subprocess gets its current directory from the
value of @code{default-directory}.
@defvar exec-directory
@pindex movemail
The value of this variable is a string, the name of a directory that
contains programs that come with GNU Emacs and are intended for Emacs
to invoke. The program @code{movemail} is an example of such a program;
Rmail uses it to fetch new mail from an inbox.
@end defvar
@defopt exec-path
The value of this variable is a list of directories to search for
programs to run in subprocesses. Each element is either the name of a
directory (i.e., a string), or @code{nil}, which stands for the default
directory (which is the value of @code{default-directory}).
@xref{Locating Files, executable-find}, for the details of this search.
@cindex program directories
The value of @code{exec-path} is used by @code{call-process} and
@code{start-process} when the @var{program} argument is not an absolute
file name.
Generally, you should not modify @code{exec-path} directly. Instead,
ensure that your @env{PATH} environment variable is set appropriately
before starting Emacs. Trying to modify @code{exec-path}
independently of @env{PATH} can lead to confusing results.
@end defopt
@defun exec-path
This function is an extension of the variable @code{exec-path}. If
@code{default-directory} indicates a remote directory, this function
returns a list of directories used for searching programs on the
respective remote host. In case of a local @code{default-directory},
the function returns just the value of the variable @code{exec-path}.
@end defun
@node Shell Arguments
@section Shell Arguments
@cindex arguments for shell commands
@cindex shell command arguments
Lisp programs sometimes need to run a shell and give it a command
that contains file names that were specified by the user. These
programs ought to be able to support any valid file name. But the shell
gives special treatment to certain characters, and if these characters
occur in the file name, they will confuse the shell. To handle these
characters, use the function @code{shell-quote-argument}:
@defun shell-quote-argument argument
This function returns a string that represents, in shell syntax,
an argument whose actual contents are @var{argument}. It should
work reliably to concatenate the return value into a shell command
and then pass it to a shell for execution.
Precisely what this function does depends on your operating system. The
function is designed to work with the syntax of your system's standard
shell; if you use an unusual shell, you will need to redefine this
function. @xref{Security Considerations}.
@example
;; @r{This example shows the behavior on GNU and Unix systems.}
(shell-quote-argument "foo > bar")
@result{} "foo\\ \\>\\ bar"
;; @r{This example shows the behavior on MS-DOS and MS-Windows.}
(shell-quote-argument "foo > bar")
@result{} "\"foo > bar\""
@end example
Here's an example of using @code{shell-quote-argument} to construct
a shell command:
@example
(concat "diff -u "
(shell-quote-argument oldfile)
" "
(shell-quote-argument newfile))
@end example
@end defun
@cindex quoting and unquoting command-line arguments
@cindex minibuffer input, and command-line arguments
@cindex @code{call-process}, command-line arguments from minibuffer
@cindex @code{start-process}, command-line arguments from minibuffer
The following two functions are useful for combining a list of
individual command-line argument strings into a single string, and
taking a string apart into a list of individual command-line
arguments. These functions are mainly intended for converting user
input in the minibuffer, a Lisp string, into a list of string
arguments to be passed to @code{make-process}, @code{call-process} or
@code{start-process}, or for converting such lists of arguments into a
single Lisp string to be presented in the minibuffer or echo area.
Note that if a shell is involved (e.g., if using
@code{call-process-shell-command}), arguments should still be
protected by @code{shell-quote-argument};
@code{combine-and-quote-strings} is @emph{not} intended to protect
special characters from shell evaluation.
@defun split-string-shell-command string
This function splits @var{string} into substrings, respecting double
and single quotes, as well as backslash quoting.
@smallexample
(split-string-shell-command "ls /tmp/'foo bar'")
@result{} ("ls" "/tmp/foo bar")
@end smallexample
@end defun
@defun split-string-and-unquote string &optional separators
This function splits @var{string} into substrings at matches for the
regular expression @var{separators}, like @code{split-string} does
(@pxref{Creating Strings}); in addition, it removes quoting from the
substrings. It then makes a list of the substrings and returns it.
If @var{separators} is omitted or @code{nil}, it defaults to
@code{"\\s-+"}, which is a regular expression that matches one or more
characters with whitespace syntax (@pxref{Syntax Class Table}).
This function supports two types of quoting: enclosing a whole string
in double quotes @code{"@dots{}"}, and quoting individual characters
with a backslash escape @samp{\}. The latter is also used in Lisp
strings, so this function can handle those as well.
@end defun
@defun combine-and-quote-strings list-of-strings &optional separator
This function concatenates @var{list-of-strings} into a single string,
quoting each string as necessary. It also sticks the @var{separator}
string between each pair of strings; if @var{separator} is omitted or
@code{nil}, it defaults to @code{" "}. The return value is the
resulting string.
The strings in @var{list-of-strings} that need quoting are those that
include @var{separator} as their substring. Quoting a string encloses
it in double quotes @code{"@dots{}"}. In the simplest case, if you
are consing a command from the individual command-line arguments,
every argument that includes embedded blanks will be quoted.
@end defun
@node Synchronous Processes
@section Creating a Synchronous Process
@cindex synchronous subprocess
After a @dfn{synchronous process} is created, Emacs waits for the
process to terminate before continuing. Starting Dired on GNU or
Unix@footnote{On other systems, Emacs uses a Lisp emulation of
@code{ls}; see @ref{Contents of Directories}.} is an example of this: it
runs @code{ls} in a synchronous process, then modifies the output
slightly. Because the process is synchronous, the entire directory
listing arrives in the buffer before Emacs tries to do anything with it.
While Emacs waits for the synchronous subprocess to terminate, the
user can quit by typing @kbd{C-g}. The first @kbd{C-g} tries to kill
the subprocess with a @code{SIGINT} signal; but it waits until the
subprocess actually terminates before quitting. If during that time the
user types another @kbd{C-g}, that kills the subprocess instantly with
@code{SIGKILL} and quits immediately (except on MS-DOS, where killing
other processes doesn't work). @xref{Quitting}.
The synchronous subprocess functions return an indication of how the
process terminated.
The output from a synchronous subprocess is generally decoded using a
coding system, much like text read from a file. The input sent to a
subprocess by @code{call-process-region} is encoded using a coding
system, much like text written into a file. @xref{Coding Systems}.
@defun call-process program &optional infile destination display &rest args
This function calls @var{program} and waits for it to finish.
The current working directory of the subprocess is set to the current
buffer's value of @code{default-directory} if that is local (as
determined by @code{unhandled-file-name-directory}), or "~" otherwise.
If you want to run a process in a remote directory use
@code{process-file}.
The standard input for the new process comes from file @var{infile} if
@var{infile} is not @code{nil}, and from the null device otherwise.
The argument @var{destination} says where to put the process output.
Here are the possibilities:
@table @asis
@item a buffer
Insert the output in that buffer, before point. This includes both the
standard output stream and the standard error stream of the process.
@item a buffer name (a string)
Insert the output in a buffer with that name, before point.
@item @code{t}
Insert the output in the current buffer, before point.
@item @code{nil}
Discard the output.
@item 0
Discard the output, and return @code{nil} immediately without waiting
for the subprocess to finish.
In this case, the process is not truly synchronous, since it can run in
parallel with Emacs; but you can think of it as synchronous in that
Emacs is essentially finished with the subprocess as soon as this
function returns.
MS-DOS doesn't support asynchronous subprocesses, so this option doesn't
work there.
@item @code{(:file @var{file-name})}
Send the output to the file name specified, overwriting it if it
already exists.
@item @code{(@var{real-destination} @var{error-destination})}
Keep the standard output stream separate from the standard error stream;
deal with the ordinary output as specified by @var{real-destination},
and dispose of the error output according to @var{error-destination}.
If @var{error-destination} is @code{nil}, that means to discard the
error output, @code{t} means mix it with the ordinary output, and a
string specifies a file name to redirect error output into.
You can't directly specify a buffer to put the error output in; that is
too difficult to implement. But you can achieve this result by sending
the error output to a temporary file and then inserting the file into a
buffer when the subprocess finishes.
@end table
If @var{display} is non-@code{nil}, then @code{call-process} redisplays
the buffer as output is inserted. (However, if the coding system chosen
for decoding output is @code{undecided}, meaning deduce the encoding
from the actual data, then redisplay sometimes cannot continue once
non-@acronym{ASCII} characters are encountered. There are fundamental
reasons why it is hard to fix this; see @ref{Output from Processes}.)
Otherwise the function @code{call-process} does no redisplay, and the
results become visible on the screen only when Emacs redisplays that
buffer in the normal course of events.
The remaining arguments, @var{args}, are strings that specify command
line arguments for the program. Each string is passed to
@var{program} as a separate argument.
The value returned by @code{call-process} (unless you told it not to
wait) indicates the reason for process termination. A number gives the
exit status of the subprocess; 0 means success, and any other value
means failure. If the process terminated with a signal,
@code{call-process} returns a string describing the signal. If you
told @code{call-process} not to wait, it returns @code{nil}.
In the examples below, the buffer @samp{foo} is current.
@smallexample
@group
(call-process "pwd" nil t)
@result{} 0
---------- Buffer: foo ----------
/home/lewis/manual
---------- Buffer: foo ----------
@end group
@group
(call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
@result{} 0
---------- Buffer: bar ----------
lewis:x:1001:1001:Bil Lewis,,,,:/home/lewis:/bin/bash
---------- Buffer: bar ----------
@end group
@end smallexample
Here is an example of the use of @code{call-process}, as used to
be found in the definition of the @code{insert-directory} function:
@smallexample
@group
(call-process insert-directory-program nil t nil switches
(if full-directory-p
(concat (file-name-as-directory file) ".")
file))
@end group
@end smallexample
@end defun
@defun process-file program &optional infile buffer display &rest args
This function processes files synchronously in a separate process. It
is similar to @code{call-process}, but may invoke a file name handler
based on the value of the variable @code{default-directory}, which
specifies the current working directory of the subprocess.
The arguments are handled in almost the same way as for
@code{call-process}, with the following differences:
Some file name handlers may not support all combinations and forms of the
arguments @var{infile}, @var{buffer}, and @var{display}. For example,
some file name handlers might behave as if @var{display} were @code{nil},
regardless of the value actually passed. As another example, some
file name handlers might not support separating standard output and error
output by way of the @var{buffer} argument.
If a file name handler is invoked, it determines the program to run based
on the first argument @var{program}. For instance, suppose that a
handler for remote files is invoked. Then the path that is used for
searching for the program might be different from @code{exec-path}.
The second argument @var{infile} may invoke a file name handler. The file
name handler could be different from the handler chosen for the
@code{process-file} function itself. (For example,
@code{default-directory} could be on one remote host, and
@var{infile} on a different remote host. Or @code{default-directory}
could be non-special, whereas @var{infile} is on a remote host.)
If @var{buffer} is a list of the form @code{(@var{real-destination}
@var{error-destination})}, and @var{error-destination} names a file,
then the same remarks as for @var{infile} apply.
The remaining arguments (@var{args}) will be passed to the process
verbatim. Emacs is not involved in processing file names that are
present in @var{args}. To avoid confusion, it may be best to avoid
absolute file names in @var{args}, but rather to specify all file
names as relative to @code{default-directory}. The function
@code{file-relative-name} is useful for constructing such relative
file names. Alternatively, you can use @code{file-local-name}
(@pxref{Magic File Names}) to obtain an absolute file name as seen
from the remote host's perspective.
@end defun
@defvar process-file-side-effects
This variable indicates whether a call of @code{process-file} changes
remote files.
By default, this variable is always set to @code{t}, meaning that a
call of @code{process-file} could potentially change any file on a
remote host. When set to @code{nil}, a file name handler could optimize
its behavior with respect to remote file attribute caching.
You should only ever change this variable with a let-binding; never
with @code{setq}.
@end defvar
@defopt process-file-return-signal-string
This user option indicates whether a call of @code{process-file}
returns a string describing the signal interrupting a remote process.
When a process returns an exit code greater than 128, it is
interpreted as a signal. @code{process-file} requires to return a
string describing this signal.
Since there are processes violating this rule, returning exit codes
greater than 128 which are not bound to a signal, @code{process-file}
returns always the exit code as natural number for remote processes.
Setting this user option to non-nil forces @code{process-file} to
interpret such exit codes as signals, and to return a corresponding
string.
@end defopt
@defun call-process-region start end program &optional delete destination display &rest args
This function sends the text from @var{start} to @var{end} as
standard input to a process running @var{program}. It deletes the text
sent if @var{delete} is non-@code{nil}; this is useful when
@var{destination} is @code{t}, to insert the output in the current
buffer in place of the input.
The arguments @var{destination} and @var{display} control what to do
with the output from the subprocess, and whether to update the display
as it comes in. For details, see the description of
@code{call-process}, above. If @var{destination} is the integer 0,
@code{call-process-region} discards the output and returns @code{nil}
immediately, without waiting for the subprocess to finish (this only
works if asynchronous subprocesses are supported; i.e., not on MS-DOS).
The remaining arguments, @var{args}, are strings that specify command
line arguments for the program.
The return value of @code{call-process-region} is just like that of
@code{call-process}: @code{nil} if you told it to return without
waiting; otherwise, a number or string which indicates how the
subprocess terminated.
In the following example, we use @code{call-process-region} to run the
@code{cat} utility, with standard input being the first five characters
in buffer @samp{foo} (the word @samp{input}). @code{cat} copies its
standard input into its standard output. Since the argument
@var{destination} is @code{t}, this output is inserted in the current
buffer.
@smallexample
@group
---------- Buffer: foo ----------
input@point{}
---------- Buffer: foo ----------
@end group
@group
(call-process-region 1 6 "cat" nil t)
@result{} 0
---------- Buffer: foo ----------
inputinput@point{}
---------- Buffer: foo ----------
@end group
@end smallexample
For example, the @code{shell-command-on-region} command uses
@code{call-shell-region} in a manner similar to this:
@smallexample
@group
(call-shell-region
start end
command ; @r{shell command}
nil ; @r{do not delete region}
buffer) ; @r{send output to @code{buffer}}
@end group
@end smallexample
@end defun
@defun call-process-shell-command command &optional infile destination display
This function executes the shell command @var{command} synchronously.
The other arguments are handled as in @code{call-process}. An old
calling convention allowed passing any number of additional arguments
after @var{display}, which were concatenated to @var{command}; this is
still supported, but strongly discouraged.
@end defun
@defun process-file-shell-command command &optional infile destination display
This function is like @code{call-process-shell-command}, but uses
@code{process-file} internally. Depending on @code{default-directory},
@var{command} can be executed also on remote hosts. An old calling
convention allowed passing any number of additional arguments after
@var{display}, which were concatenated to @var{command}; this is still
supported, but strongly discouraged.
@end defun
@defun call-shell-region start end command &optional delete destination
This function sends the text from @var{start} to @var{end} as
standard input to an inferior shell running @var{command}. This function
is similar than @code{call-process-region}, with process being a shell.
The arguments @code{delete}, @code{destination} and the return value
are like in @code{call-process-region}.
Note that this function doesn't accept additional arguments.
@end defun
@defun shell-command-to-string command
This function executes @var{command} (a string) as a shell command,
then returns the command's output as a string.
@end defun
@c There is also shell-command-on-region, but that is more of a user
@c command, not something to use in programs.
@defun process-lines program &rest args
This function runs @var{program}, waits for it to finish, and returns
its output as a list of strings. Each string in the list holds a
single line of text output by the program; the end-of-line characters
are stripped from each line. The arguments beyond @var{program},
@var{args}, are strings that specify command-line arguments with which
to run the program.
If @var{program} exits with a non-zero exit status, this function
signals an error.
This function works by calling @code{call-process}, so program output
is decoded in the same way as for @code{call-process}.
@end defun
@defun process-lines-ignore-status program &rest args
This function is just like @code{process-lines}, but does not signal
an error if @var{program} exits with a non-zero exit status.
@end defun
@node Asynchronous Processes
@section Creating an Asynchronous Process
@cindex asynchronous subprocess
In this section, we describe how to create an @dfn{asynchronous
process}. After an asynchronous process is created, it runs in
parallel with Emacs, and Emacs can communicate with it using the
functions described in the following sections (@pxref{Input to
Processes}, and @pxref{Output from Processes}). Note that process
communication is only partially asynchronous: Emacs sends and receives
data to and from a process only when those functions are called.
@cindex pty, when to use for subprocess communications
@cindex pipe, when to use for subprocess communications
An asynchronous process is controlled either via a @dfn{pty}
(pseudo-terminal) or a @dfn{pipe}. The choice of pty or pipe is made
when creating the process, by default based on the value of the
variable @code{process-connection-type} (see below). If available,
ptys are usually preferable for processes visible to the user, as in
Shell mode, because they allow for job control (@kbd{C-c}, @kbd{C-z},
etc.)@: between the process and its children, and because interactive
programs treat ptys as terminal devices, whereas pipes don't support
these features. However, for subprocesses used by Lisp programs for
internal purposes (i.e., no user interaction with the subprocess is
required), where significant amounts of data need to be exchanged
between the subprocess and the Lisp program, it is often better to use
a pipe, because pipes are more efficient. Also, the total number of
ptys is limited on many systems, and it is good not to waste them
unnecessarily.
@defun make-process &rest args
This function is the basic low-level primitive for starting
asynchronous subprocesses. It returns a process object representing
the subprocess. Compared to the more high-level @code{start-process},
described below, it takes keyword arguments, is more flexible, and
allows to specify process filters and sentinels in a single call.
The arguments @var{args} are a list of keyword/argument pairs.
Omitting a keyword is always equivalent to specifying it with value
@code{nil}. Here are the meaningful keywords:
@table @asis
@item :name @var{name}
Use the string @var{name} as the process name; if a process with this
name already exists, then @var{name} is modified (by appending
@samp{<1>}, etc.)@: to be unique.
@item :buffer @var{buffer}
Use @var{buffer} as the process buffer. If the value is @code{nil},
the subprocess is not associated with any buffer.
@item :command @var{command}
Use @var{command} as the command line of the process. The value
should be a list starting with the program's executable file name,
followed by strings to give to the program as its arguments. If
the first element of the list is @code{nil}, Emacs opens a new
pseudoterminal (pty) and associates its input and output with
@var{buffer}, without actually running any program; the rest of the
list elements are ignored in that case.
@item :coding @var{coding}
If @var{coding} is a symbol, it specifies the coding system to be
used for both reading and writing of data from and to the
connection. If @var{coding} is a cons cell
@w{@code{(@var{decoding} . @var{encoding})}}, then @var{decoding}
will be used for reading and @var{encoding} for writing. The coding
system used for encoding the data written to the program is also used
for encoding the command-line arguments (but not the program itself,
whose file name is encoded as any other file name; @pxref{Encoding and
I/O, file-name-coding-system}).
If @var{coding} is @code{nil}, the default rules for finding the
coding system will apply. @xref{Default Coding Systems}.
@item :connection-type @var{type}
Initialize the type of device used to communicate with the subprocess.
Possible values are @code{pty} to use a pty, @code{pipe} to use a
pipe, or @code{nil} to use the default derived from the value of the
@code{process-connection-type} variable. This parameter and the value
of @code{process-connection-type} are ignored if a non-@code{nil}
value is specified for the @code{:stderr} parameter; in that case, the
type will always be @code{pipe}. On systems where ptys are not
available (MS-Windows), this parameter is likewise ignored, and pipes
are used unconditionally.
@item :noquery @var{query-flag}
Initialize the process query flag to @var{query-flag}.
@xref{Query Before Exit}.
@item :stop @var{stopped}
If provided, @var{stopped} must be @code{nil}; it is an error to use
any non-@code{nil} value. The @code{:stop} key is ignored otherwise
and is retained for compatibility with other process types such as
pipe processes. Asynchronous subprocesses never start in the stopped
state.
@item :filter @var{filter}
Initialize the process filter to @var{filter}. If not specified, a
default filter will be provided, which can be overridden later.
@xref{Filter Functions}.
@item :sentinel @var{sentinel}
Initialize the process sentinel to @var{sentinel}. If not specified,
a default sentinel will be used, which can be overridden later.
@xref{Sentinels}.
@item :stderr @var{stderr}
Associate @var{stderr} with the standard error of the process. A
non-@code{nil} value should be either a buffer or a pipe process
created with @code{make-pipe-process}, described below. If
@var{stderr} is @code{nil}, standard error is mixed with standard
output, and both are sent to @var{buffer} or @var{filter}.
@cindex standard error process
If @var{stderr} is a buffer, Emacs will create a pipe process, the
@dfn{standard error process}. This process will have the default
filter (@pxref{Filter Functions}), sentinel (@pxref{Sentinels}), and
coding systems (@pxref{Default Coding Systems}). On the other hand,
it will use @var{query-flag} as its query-on-exit flag (@pxref{Query
Before Exit}). It will be associated with the @var{stderr} buffer
(@pxref{Process Buffers}) and send its output (which is the standard
error of the main process) there. To get the process object for the
standard error process, pass the @var{stderr} buffer to
@code{get-buffer-process}.
If @var{stderr} is a pipe process, Emacs will use it as standard error
process for the new process.
@item :file-handler @var{file-handler}
If @var{file-handler} is non-@code{nil}, then look for a file name
handler for the current buffer's @code{default-directory}, and invoke
that file name handler to make the process. If there is no such
handler, proceed as if @var{file-handler} were @code{nil}.
@end table
The original argument list, modified with the actual connection
information, is available via the @code{process-contact} function.
The current working directory of the subprocess is set to the current
buffer's value of @code{default-directory} if that is local (as
determined by @code{unhandled-file-name-directory}), or @file{~}
otherwise. If you want to run a process in a remote directory, pass
@code{:file-handler t} to @code{make-process}. In that case, the
current working directory is the local name component of
@code{default-directory} (as determined by @code{file-local-name}).
Depending on the implementation of the file name handler, it might not
be possible to apply @var{filter} or @var{sentinel} to the resulting
process object. The @code{:stderr} argument cannot be a pipe process,
file name handlers do not support pipe processes for this. A buffer
as @code{:stderr} argument is accepted, its contents is shown without
the use of pipe processes. @xref{Filter Functions}, @ref{Sentinels},
and @ref{Accepting Output}.
Some file name handlers may not support @code{make-process}. In such
cases, this function does nothing and returns @code{nil}.
@end defun
@anchor{Pipe Processes}
@defun make-pipe-process &rest args
This function creates a bidirectional pipe which can be attached to a
child process. This is useful with the @code{:stderr} keyword of
@code{make-process}. The function returns a process object.
The arguments @var{args} are a list of keyword/argument pairs.
Omitting a keyword is always equivalent to specifying it with value
@code{nil}.
Here are the meaningful keywords:
@table @asis
@item :name @var{name}
Use the string @var{name} as the process name. As with
@code{make-process}, it is modified if necessary to make it unique.
@item :buffer @var{buffer}
Use @var{buffer} as the process buffer.
@item :coding @var{coding}
If @var{coding} is a symbol, it specifies the coding system to be
used for both reading and writing of data from and to the
connection. If @var{coding} is a cons cell
@w{@code{(@var{decoding} . @var{encoding})}}, then @var{decoding}
will be used for reading and @var{encoding} for writing.
If @var{coding} is @code{nil}, the default rules for finding the
coding system will apply. @xref{Default Coding Systems}.
@item :noquery @var{query-flag}
Initialize the process query flag to @var{query-flag}.
@xref{Query Before Exit}.
@item :stop @var{stopped}
If @var{stopped} is non-@code{nil}, start the process in the stopped
state. In the stopped state, a pipe process does not accept incoming
data, but you can send outgoing data. The stopped state is set by
@code{stop-process} and cleared by @code{continue-process}
(@pxref{Signals to Processes}).
@item :filter @var{filter}
Initialize the process filter to @var{filter}. If not specified, a
default filter will be provided, which can be changed later.
@xref{Filter Functions}.
@item :sentinel @var{sentinel}
Initialize the process sentinel to @var{sentinel}. If not specified,
a default sentinel will be used, which can be changed later.
@xref{Sentinels}.
@end table
The original argument list, modified with the actual connection
information, is available via the @code{process-contact} function.
@end defun
@defun start-process name buffer-or-name program &rest args
This function is a higher-level wrapper around @code{make-process},
exposing an interface that is similar to @code{call-process}. It
creates a new asynchronous subprocess and starts the specified
@var{program} running in it. It returns a process object that stands
for the new subprocess in Lisp. The argument @var{name} specifies the
name for the process object; as with @code{make-process}, it is
modified if necessary to make it unique. The buffer
@var{buffer-or-name} is the buffer to associate with the process.
If @var{program} is @code{nil}, Emacs opens a new pseudoterminal (pty)
and associates its input and output with @var{buffer-or-name}, without
creating a subprocess. In that case, the remaining arguments
@var{args} are ignored.
The rest of @var{args} are strings that specify command line arguments
for the subprocess.
In the example below, the first process is started and runs (rather,
sleeps) for 100 seconds (the output buffer @samp{foo} is created
immediately). Meanwhile, the second process is started, and
given the name @samp{my-process<1>} for the sake of uniqueness. It
inserts the directory listing at the end of the buffer @samp{foo},
before the first process finishes. Then it finishes, and a message to
that effect is inserted in the buffer. Much later, the first process
finishes, and another message is inserted in the buffer for it.
@smallexample
@group
(start-process "my-process" "foo" "sleep" "100")
@result{} #<process my-process>
@end group
@group
(start-process "my-process" "foo" "ls" "-l" "/bin")
@result{} #<process my-process<1>>
---------- Buffer: foo ----------
total 8336
-rwxr-xr-x 1 root root 971384 Mar 30 10:14 bash
-rwxr-xr-x 1 root root 146920 Jul 5 2011 bsd-csh
@dots{}
-rwxr-xr-x 1 root root 696880 Feb 28 15:55 zsh4
Process my-process<1> finished
Process my-process finished
---------- Buffer: foo ----------
@end group
@end smallexample
@end defun
@defun start-file-process name buffer-or-name program &rest args
Like @code{start-process}, this function starts a new asynchronous
subprocess running @var{program} in it, and returns its process
object.
The difference from @code{start-process} is that this function may
invoke a file name handler based on the value of @code{default-directory}.
This handler ought to run @var{program}, perhaps on the local host,
perhaps on a remote host that corresponds to @code{default-directory}.
In the latter case, the local part of @code{default-directory} becomes
the working directory of the process.
This function does not try to invoke file name handlers for
@var{program} or for the rest of @var{args}. For that reason, if
@var{program} or any of @var{args} use the remote-file syntax
(@pxref{Magic File Names}), they must be converted either to file
names relative to @code{default-directory}, or to names that identify
the files locally on the remote host, by running them through
@code{file-local-name}.
Depending on the implementation of the file name handler, it might not be
possible to apply @code{process-filter} or @code{process-sentinel} to
the resulting process object. @xref{Filter Functions}, and @ref{Sentinels}.
@c FIXME Can we find a better example (i.e., a more modern function
@c that is actually documented).
Some file name handlers may not support @code{start-file-process} (for
example the function @code{ange-ftp-hook-function}). In such cases,
this function does nothing and returns @code{nil}.
@end defun
@defun start-process-shell-command name buffer-or-name command
This function is like @code{start-process}, except that it uses a
shell to execute the specified @var{command}. The argument
@var{command} is a shell command string. The variable
@code{shell-file-name} specifies which shell to use.
The point of running a program through the shell, rather than directly
with @code{make-process} or @code{start-process}, is so that you can
employ shell features such as wildcards in the arguments. It follows
that if you include any arbitrary user-specified arguments in the
command, you should quote them with @code{shell-quote-argument} first,
so that any special shell characters do @emph{not} have their special
shell meanings. @xref{Shell Arguments}. Of course, when executing
commands based on user input you should also consider the security
implications.
@end defun
@defun start-file-process-shell-command name buffer-or-name command
This function is like @code{start-process-shell-command}, but uses
@code{start-file-process} internally. Because of this, @var{command}
can also be executed on remote hosts, depending on @code{default-directory}.
@end defun
@defvar process-connection-type
This variable controls the type of device used to communicate with
asynchronous subprocesses. If it is non-@code{nil}, then ptys are
used, when available. Otherwise, pipes are used.
The value of @code{process-connection-type} takes effect when
@code{make-process} or @code{start-process} is called. So you can
specify how to communicate with one subprocess by binding the variable
around the call to these functions.
Note that the value of this variable is ignored when
@code{make-process} is called with a non-@code{nil} value of the
@code{:stderr} parameter; in that case, Emacs will communicate with
the process using pipes. It is also ignored if ptys are unavailable
(MS-Windows).
@smallexample
@group
(let ((process-connection-type nil)) ; @r{use a pipe}
(start-process @dots{}))
@end group
@end smallexample
To determine whether a given subprocess actually got a pipe or a pty,
use the function @code{process-tty-name} (@pxref{Process
Information}).
@end defvar
@node Deleting Processes
@section Deleting Processes
@cindex deleting processes
@dfn{Deleting a process} disconnects Emacs immediately from the
subprocess. Processes are deleted automatically after they terminate,
but not necessarily right away. You can delete a process explicitly
at any time. If you explicitly delete a terminated process before it
is deleted automatically, no harm results. Deleting a running
process sends a signal to terminate it (and its child processes, if
any), and calls the process sentinel. @xref{Sentinels}.
When a process is deleted, the process object itself continues to
exist as long as other Lisp objects point to it. All the Lisp
primitives that work on process objects accept deleted processes, but
those that do I/O or send signals will report an error. The process
mark continues to point to the same place as before, usually into a
buffer where output from the process was being inserted.
@defopt delete-exited-processes
This variable controls automatic deletion of processes that have
terminated (due to calling @code{exit} or to a signal). If it is
@code{nil}, then they continue to exist until the user runs
@code{list-processes}. Otherwise, they are deleted immediately after
they exit.
@end defopt
@defun delete-process process
This function deletes a process, killing it with a @code{SIGKILL}
signal if the process was running a program. The argument may be a
process, the name of a process, a buffer, or the name of a buffer. (A
buffer or buffer-name stands for the process that