diff options
Diffstat (limited to 'doc/lispref/processes.texi')
| -rw-r--r-- | doc/lispref/processes.texi | 100 |
1 files changed, 88 insertions, 12 deletions
diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index 950dc9c6d49..064934cc662 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -512,20 +512,17 @@ inputinput@point{} @end smallexample For example, the @code{shell-command-on-region} command uses -@code{call-process-region} in a manner similar to this: +@code{call-shell-region} in a manner similar to this: @smallexample @group -(call-process-region +(call-shell-region start end - shell-file-name ; @r{name of program} + command ; @r{shell command} nil ; @r{do not delete region} - buffer ; @r{send output to @code{buffer}} - nil ; @r{no redisplay during output} - "-c" command) ; @r{arguments for the shell} + buffer) ; @r{send output to @code{buffer}} @end group @end smallexample -@c It actually uses shell-command-switch, but no need to mention that here. @end defun @defun call-process-shell-command command &optional infile destination display @@ -545,6 +542,15 @@ convention allowed passing any number of additional arguments after 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. @@ -1394,6 +1400,7 @@ Emacs tries to read it. * Filter Functions:: Filter functions accept output from the process. * Decoding Output:: Filters can get unibyte or multibyte strings. * Accepting Output:: How to wait until process output arrives. +* Processes and Threads:: How processes and threads interact. @end menu @node Process Buffers @@ -1785,6 +1792,35 @@ got output from @var{process}, or from any process if @var{process} is arrived. @end defun +@node Processes and Threads +@subsection Processes and Threads +@cindex processes, threads + + Because threads were a relatively late addition to Emacs Lisp, and +due to the way dynamic binding was sometimes used in conjunction with +@code{accept-process-output}, by default a process is locked to the +thread that created it. When a process is locked to a thread, output +from the process can only be accepted by that thread. + + A Lisp program can specify to which thread a process is to be +locked, or instruct Emacs to unlock a process, in which case its +output can be processed by any thread. Only a single thread will wait +for output from a given process at one time---once one thread begins +waiting for output, the process is temporarily locked until +@code{accept-process-output} or @code{sit-for} returns. + + If the thread exits, all the processes locked to it are unlocked. + +@defun process-thread process +Return the thread to which @var{process} is locked. If @var{process} +is unlocked, return @code{nil}. +@end defun + +@defun set-process-thread process thread +Set the locking thread of @var{process} to @var{thread}. @var{thread} +may be @code{nil}, in which case the process is unlocked. +@end defun + @node Sentinels @section Sentinels: Detecting Process Status Changes @cindex process sentinel @@ -1964,6 +2000,13 @@ shell process to avoid querying: @end smallexample @end defun +@defopt confirm-kill-processes +If this user option is set to @code{t} (the default), then Emacs asks +for confirmation before killing processes on exit. If it is +@code{nil}, Emacs kills processes without confirmation, i.e., the +query flag of all processes is ignored. +@end defopt + @node System Processes @section Accessing Other Processes @cindex system processes @@ -2288,7 +2331,8 @@ associated with any buffer. The arguments @var{host} and @var{service} specify where to connect to; @var{host} is the host name (a string), and @var{service} is the name of -a defined network service (a string) or a port number (an integer). +a defined network service (a string) or a port number (an integer like +@code{80} or an integer string like @code{"80"}). The remaining arguments @var{parameters} are keyword/argument pairs that are mainly relevant to encrypted connections: @@ -2512,8 +2556,9 @@ connecting to that address will be accepted. @item :service @var{service} @var{service} specifies a port number to connect to; or, for a server, -the port number to listen on. It should be a service name that -translates to a port number, or an integer specifying the port number +the port number to listen on. It should be a service name like +@samp{"http"} that translates to a port number, or an integer like @samp{80} +or an integer string like @samp{"80"} that specifies the port number directly. For a server, it can also be @code{t}, which means to let the system select an unused port number. @@ -2525,6 +2570,12 @@ automatically for the given @var{host} and @var{service}. ignored. @code{ipv4} and @code{ipv6} specify to use IPv4 and IPv6, respectively. +@item :use-external-socket @var{use-external-socket} +If @var{use-external-socket} is non-@code{nil} use any sockets passed +to Emacs on invocation instead of allocating one. This is used by the +Emacs server code to allow on-demand socket activation. If Emacs +wasn't passed a socket, this option is silently ignored. + @item :local @var{local-address} For a server process, @var{local-address} is the address to listen on. It overrides @var{family}, @var{host} and @var{service}, so you @@ -2575,8 +2626,33 @@ without waiting for the connection to complete. When the connection succeeds or fails, Emacs will call the sentinel function, with a second argument matching @code{"open"} (if successful) or @code{"failed"}. The default is to block, so that -@code{make-network-process} does not return until the connection -has succeeded or failed. +@code{make-network-process} does not return until the connection has +succeeded or failed. + +If you're setting up an asynchronous TLS connection, you have to also +provide the @code{:tls-parameters} parameter (see below). + +Depending on the capabilities of Emacs, how asynchronous +@code{:nowait} is may vary. The three elements that may (or may not) +be done asynchronously are domain name resolution, socket setup, and +(for TLS connections) TLS negotiation. + +Many functions that interact with process objects, (for instance, +@code{process-datagram-address}) rely on them at least having a socket +before they can return a useful value. These functions will block +until the socket has achieved the desired status. The recommended way +of interacting with asynchronous sockets is to place a sentinel on the +process, and not try to interact with it before it has changed status +to @samp{"run"}. That way, none of these functions will block. + +@item :tls-parameters +When opening a TLS connection, this should be where the first element +is the TLS type (which should either be @code{gnutls-x509pki} or +@code{gnutls-anon}, and the remaining elements should form a keyword +list acceptable for @code{gnutls-boot}. (This keyword list can be +obtained from the @code{gnutls-boot-parameters} function.) The TLS +connection will then be negotiated after completing the connection to +the host. @item :stop @var{stopped} If @var{stopped} is non-@code{nil}, start the network connection or |