diff options
Diffstat (limited to 'doc/lispref/processes.texi')
| -rw-r--r-- | doc/lispref/processes.texi | 234 |
1 files changed, 171 insertions, 63 deletions
diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index 3fa6c844ae9..db6b4c35ef7 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -197,7 +197,7 @@ 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 +@defun shell-quote-argument argument &optional posix 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 @@ -227,6 +227,15 @@ a shell command: " " (shell-quote-argument newfile)) @end example + +If the optional @var{posix} argument is non-@code{nil}, @var{argument} +is quoted according to POSIX shell quoting rules, regardless of the +system’s shell. This is useful when your shell could run on a remote +host, which requires a POSIX shell in general. + +@example +(shell-quote-argument "foo > bar" (file-remote-p default-directory)) +@end example @end defun @cindex quoting and unquoting command-line arguments @@ -696,12 +705,13 @@ coding system will apply. @xref{Default Coding Systems}. 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. +@code{process-connection-type} variable. If @var{type} is a cons cell +@w{@code{(@var{input} . @var{output})}}, then @var{input} will be used +for standard input and @var{output} for standard output (and standard +error if @code{:stderr} is @code{nil}). + +On systems where ptys are not available (MS-Windows), this parameter +is ignored, and pipes are used unconditionally. @item :noquery @var{query-flag} Initialize the process query flag to @var{query-flag}. @@ -966,6 +976,15 @@ use the function @code{process-tty-name} (@pxref{Process Information}). @end defvar +@defvar process-error-pause-time +If a process sentinel/filter function has an error, Emacs will (by +default) pause Emacs for @code{process-error-pause-time} seconds after +displaying this error, so that users will see the error in question. +However, this can lead to situations where Emacs becomes unresponsive +(if there's a lot of these errors happening), so this can be disabled +by setting @code{process-error-pause-time} to 0. +@end defvar + @node Deleting Processes @section Deleting Processes @cindex deleting processes @@ -993,16 +1012,18 @@ terminated (due to calling @code{exit} or to a signal). If it is they exit. @end defopt -@defun delete-process process +@defun delete-process &optional 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 -@code{get-buffer-process} returns.) Calling @code{delete-process} on -a running process terminates it, updates the process status, and runs -the sentinel immediately. If the process has already terminated, -calling @code{delete-process} has no effect on its status, or on the -running of its sentinel (which will happen sooner or later). +@code{get-buffer-process} returns, and a missing or @code{nil} +@var{process} means that the current buffer's process should be +killed.) Calling @code{delete-process} on a running process +terminates it, updates the process status, and runs the sentinel +immediately. If the process has already terminated, calling +@code{delete-process} has no effect on its status, or on the running +of its sentinel (which will happen sooner or later). If the process object represents a network, serial, or pipe connection, its status changes to @code{closed}; otherwise, it changes @@ -1222,15 +1243,24 @@ that are already closed, the value is either 0 or 256, depending on whether the connection was closed normally or abnormally. @end defun -@defun process-tty-name process +@defun process-tty-name process &optional stream This function returns the terminal name that @var{process} is using for its communication with Emacs---or @code{nil} if it is using pipes instead of a pty (see @code{process-connection-type} in -@ref{Asynchronous Processes}). If @var{process} represents a program -running on a remote host, the terminal name used by that program on -the remote host is provided as process property @code{remote-tty}. If -@var{process} represents a network, serial, or pipe connection, the -value is @code{nil}. +@ref{Asynchronous Processes}). By default, this function returns the +terminal name if any of @var{process}'s standard streams use a +terminal. If @var{stream} is one of @code{stdin}, @code{stdout}, or +@code{stderr}, this function returns the terminal name (or @code{nil}, +as above) that @var{process} uses for that stream specifically. You +can use this to determine whether a particular stream uses a pipe or a +pty. + +If @var{process} represents a program running on a remote host, this +function returns the @emph{local} terminal name that communicates with +@var{process}; you can get the terminal name used by that program on +the remote host with the process property @code{remote-tty}. If +@var{process} represents a network, serial, or pipe connection, this +function always returns @code{nil}. @end defun @defun process-coding-system process @@ -1413,11 +1443,13 @@ non-@code{nil}, you can think of this function as typing @kbd{C-c} on the terminal by which Emacs talks to the subprocess. @end defun -@defun kill-process &optional process current-group -This function kills the process @var{process} by sending the +@deffn Command kill-process &optional process current-group +This command kills the process @var{process} by sending the signal @code{SIGKILL}. This signal kills the subprocess immediately, -and cannot be handled by the subprocess. -@end defun +and cannot be handled by the subprocess. Interactively, it'll prompt +the user for a process name, defaulting to the process (if any) in the +current buffer. +@end deffn @defun quit-process &optional process current-group This function sends the signal @code{SIGQUIT} to the process @@ -1452,7 +1484,7 @@ incoming data from the connection. For serial connections, data that arrived during the time the process was stopped might be lost. @end defun -@deffn Command signal-process process signal +@deffn Command signal-process process signal &optional remote This function sends a signal to process @var{process}. The argument @var{signal} specifies which signal to send; it should be an integer, or a symbol whose name is a signal. @@ -1460,12 +1492,18 @@ or a symbol whose name is a signal. The @var{process} argument can be a system process @acronym{ID} (an integer); that allows you to send signals to processes that are not children of Emacs. @xref{System Processes}. + +If @var{process} is a process object which contains the property +@code{remote-pid}, or @var{process} is a number and @var{remote} is a +remote file name, @var{process} is interpreted as process on the +respective remote host, which will be the process to signal. @end deffn Sometimes, it is necessary to send a signal to a non-local asynchronous process. This is possible by writing an own -@code{interrupt-process} implementation. This function must be added -then to @code{interrupt-process-functions}. +@code{interrupt-process} or @code{signal-process} implementation. +This function must be added then to @code{interrupt-process-functions} +or @code{signal-process-functions}, respectively. @defvar interrupt-process-functions This variable is a list of functions to be called for @@ -1478,6 +1516,17 @@ default function, which shall always be the last in this list, is This is the mechanism, how Tramp implements @code{interrupt-process}. @end defvar +@defvar signal-process-functions +This variable is a list of functions to be called for +@code{signal-process}. The arguments of the functions are the same as +for @code{signal-process}. These functions are called in the order of +the list, until one of them returns non-@code{nil}. The default +function, which shall always be the last in this list, is +@code{internal-default-signal-process}. + +This is the mechanism, how Tramp implements @code{signal-process}. +@end defvar + @node Output from Processes @section Receiving Output from Processes @cindex process output @@ -1491,20 +1540,11 @@ a buffer, which is called the associated buffer of the process default filter discards the output. If the subprocess writes to its standard error stream, by default -the error output is also passed to the process filter function. If -Emacs uses a pseudo-TTY (pty) for communication with the subprocess, -then it is impossible to separate the standard output and standard -error streams of the subprocess, because a pseudo-TTY has only one -output channel. In that case, if you want to keep the output to those -streams separate, you should redirect one of them to a file---for -example, by using an appropriate shell command via -@code{start-process-shell-command} or a similar function. - - Alternatively, you could use the @code{:stderr} parameter with a +the error output is also passed to the process filter function. +Alternatively, you could use the @code{:stderr} parameter with a non-@code{nil} value in a call to @code{make-process} (@pxref{Asynchronous Processes, make-process}) to make the destination -of the error output separate from the standard output; in that case, -Emacs will use pipes for communicating with the subprocess. +of the error output separate from the standard output. When a subprocess terminates, Emacs reads any pending output, then stops reading output from that subprocess. Therefore, if the @@ -1920,7 +1960,6 @@ because @var{seconds} can be floating point to specify waiting a fractional number of seconds. If @var{seconds} is 0, the function accepts whatever output is pending but does not wait. -@c Emacs 22.1 feature If @var{process} is a process, and the argument @var{just-this-one} is non-@code{nil}, only output from that process is handled, suspending output from other processes until some output has been received from that @@ -2221,9 +2260,8 @@ query flag of all processes is ignored. In addition to accessing and manipulating processes that are subprocesses of the current Emacs session, Emacs Lisp programs can -also access other processes running on the same machine. We call -these @dfn{system processes}, to distinguish them from Emacs -subprocesses. +also access other processes. We call these @dfn{system processes}, to +distinguish them from Emacs subprocesses. Emacs provides several primitives for accessing system processes. Not all platforms support these primitives; on those which don't, @@ -2235,6 +2273,9 @@ system. Each process is identified by its @acronym{PID}, a numerical process ID that is assigned by the OS and distinguishes the process from all the other processes running on the same machine at the same time. + +If @code{default-directory} points to a remote host, processes of that +host are returned. @end defun @defun process-attributes pid @@ -2246,6 +2287,9 @@ attribute @var{key}s that this function can return are listed below. Not all platforms support all of these attributes; if an attribute is not supported, its association will not appear in the returned alist. +If @code{default-directory} points to a remote host, @var{pid} is +regarded as process of that host. + @table @code @item euid The effective user ID of the user who invoked the process. The @@ -2371,8 +2415,9 @@ occupied by the process in the machine's physical memory. @item pcpu The percentage of the CPU time used by the process since it started. -The corresponding @var{value} is a floating-point number between 0 and -100. +The corresponding @var{value} is a nonnegative floating-point number. +Although in theory the number can exceed 100 on a multicore platform, +it is usually less than 100 because Emacs is typically single-threaded. @item pmem The percentage of the total physical memory installed on the machine @@ -3159,20 +3204,39 @@ If the vector does not include the port number, @var{p}, or if @code{:@var{p}} suffix. @end defun -@defun network-lookup-address-info name &optional family -This function is used to perform hostname lookups on @var{name}, which -is expected to be an ASCII-only string, otherwise an error is -signaled. Call @code{puny-encode-domain} on @var{name} -first if you wish to lookup internationalized hostnames. +@defun network-lookup-address-info name &optional family hints +This function perform hostname lookups on @var{name}, which is +expected to be an ASCII-only string, otherwise it signals an error. Call +@code{puny-encode-domain} on @var{name} first if you wish to lookup +internationalized hostnames. -If successful it returns a list of Lisp representations of network -addresses, otherwise it returns @code{nil}. In the latter case, it -also displays the error message hopefully explaining what went wrong. +If successful, this function returns a list of Lisp representations of network +addresses (@pxref{Network Processes}, for a description of the +format), otherwise return @code{nil}. In the latter case, it also logs +an error message hopefully explaining what went wrong. -By default both IPv4 and IPv6 lookups are attempted. The optional -argument @var{family} controls this behavior, specifying the symbol -@code{ipv4} or @code{ipv6} restricts lookups to IPv4 and IPv6 +By default, this function attempts both IPv4 and IPv6 lookups. The +optional argument @var{family} controls this behavior, specifying the +symbol @code{ipv4} or @code{ipv6} restricts lookups to IPv4 and IPv6 respectively. + +If optional argument @var{hints} is @code{numeric}, the function +treats the @var{name} as a numerical IP address (and does not perform DNS +lookups). This can be used to check whether a string is a valid +numerical representation of an IP address, or to convert a numerical +string to its canonical representation. e.g.@: + +@example +(network-lookup-address-info "127.1" 'ipv4 'numeric) + @result{} ([127 0 0 1 0]) + +(network-lookup-address-info "::1" nil 'numeric) + @result{} ([0 0 0 0 0 0 0 1 0]) +@end example + +Be warned that there are some surprising valid forms, +especially for IPv4, e.g @samp{0xe3010203} and @samp{0343.1.2.3} are both +valid, as are @samp{0} and @samp{1} (but they are invalid for IPv6). @end defun @node Serial Ports @@ -3425,20 +3489,64 @@ type values: @itemx byte Unsigned byte, with length 1. -@item uint @var{bitlen} -Unsigned integer in network byte order, with @var{bitlen} bits. +@item uint @var{bitlen} &optional @var{le} +Unsigned integer in network byte order (big-endian), with @var{bitlen} bits. @var{bitlen} has to be a multiple of 8. +If @var{le} is non-@code{nil}, then use little-endian byte order. -@item uintr @var{bitlen} -Unsigned integer in little endian order, with @var{bitlen} bits. +@item sint @var{bitlen} @var{le} +Signed integer in network byte order (big-endian), with @var{bitlen} bits. @var{bitlen} has to be a multiple of 8. +If @var{le} is non-@code{nil}, then use little-endian byte order. @item str @var{len} -String of bytes of length @var{len}. +Unibyte string (@pxref{Text Representations}) of length @var{len} bytes. +When packing, the first @var{len} bytes of the input string are copied +to the packed output. If the input string is shorter than @var{len}, +the remaining bytes will be null (zero) unless a pre-allocated string +was provided to @code{bindat-pack}, in which case the remaining bytes +are left unmodified. If the input string is multibyte with only ASCII +and @code{eight-bit} characters, it is converted to unibyte before it +is packed; other multibyte strings signal an error. When unpacking, +any null bytes in the packed input string will appear in the unpacked +output. @item strz &optional @var{len} -Zero-terminated string of bytes, can be of arbitrary length or in a fixed-size -field with length @var{len}. +If @var{len} is not provided, this is a variable-length +null-terminated unibyte string (@pxref{Text Representations}). When +packing into @code{strz}, the entire input string is copied to the +packed output followed by a null (zero) byte. (If pre-allocated +string is provided for packing into @code{strz}, that pre-allocated +string should have enough space for the additional null byte appended +to the output string contents, @pxref{Bindat Functions}). The length +of the packed output is the length of the input string plus one (for +the null terminator). The input string must not contain any null +bytes. If the input string is multibyte with only ASCII and +@code{eight-bit} characters, it is converted to unibyte before it is +packed; other multibyte strings signal an error. When unpacking a +@code{strz}, the resulting output string will contain all bytes up to +(but excluding) the null byte that terminated the input string. + +If @var{len} is provided, @code{strz} behaves the same as @code{str}, +but with a couple of differences: + +@itemize @bullet +@item +When packing, a null terminator is written after the packed input +string if the number of characters in the input string is less than +@var{len}. + +@item +When unpacking, the first null byte encountered in the packed string +is interpreted as the terminating byte, and it and all subsequent +bytes are excluded from the result of the unpacking. +@end itemize + +@quotation Caution +The packed output will not be null-terminated unless the input string +is shorter than @var{len} bytes or it contains a null byte within the +first @var{len} bytes. +@end quotation @item vec @var{len} [@var{type}] Vector of @var{len} elements. The type of the elements is given by @@ -3458,7 +3566,7 @@ and @code{#x1c} @code{#x28} to @w{@code{(3 5 10 11 12)}}. @item fill @var{len} @var{len} bytes used as a mere filler. In packing, these bytes are -are left unchanged, which normally means they remain zero. +left unchanged, which normally means they remain zero. When unpacking, this just returns nil. @item align @var{len} |