X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;ds=sidebyside;f=man%2Flispref%2Fprocesses.texi;h=d7500747f477fd925502c8cc77c155559a14be0d;hb=3088145e65ca6d9b6eb9a4f807809efc521a1c3f;hp=fbc71b67cbc17e693d83d994b5741bbdb588e489;hpb=6883ee56ec887c2c48abe5b06b5e66aa74031910;p=chise%2Fxemacs-chise.git diff --git a/man/lispref/processes.texi b/man/lispref/processes.texi index fbc71b6..d750074 100644 --- a/man/lispref/processes.texi +++ b/man/lispref/processes.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the XEmacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. @c See the file lispref.texi for copying conditions. @setfilename ../../info/processes.info @node Processes, System Interface, Databases, Top @@ -60,7 +60,7 @@ 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}). - Synchronous and asynchronous processes are explained in following + 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. @@ -92,12 +92,16 @@ intermixed randomly. argument, @var{args}. The @var{args} must all be strings, and they are supplied to @var{program} as separate command line arguments. Wildcard characters and other shell constructs are not allowed in these strings, -since they are passed directly to the specified program. +since they are passed directly to the specified program. @strong{Please note:} The argument @var{program} contains only the name of the program; it may not contain any command-line arguments. You must use @var{args} to provide those. +If you want to use features of the shell, then invoke the shell directly +using, for example, @var{program} of @code{"sh"}, and @var{args} of +@code{"-c"} and @var{"command line..."}. + The subprocess gets its current directory from the value of @code{default-directory} (@pxref{File Name Expansion}). @@ -106,7 +110,7 @@ must use @var{args} to provide those. specify overrides for it with @code{process-environment}. @xref{System Environment}. -@defvar exec-directory +@defvar exec-directory @pindex wakeup The value of this variable is the name of a directory (a string) that contains programs that come with XEmacs, that are intended for XEmacs @@ -246,13 +250,13 @@ of @code{call-process}: @end smallexample @end defun -@defun call-process-region start end program &optional delete destination display &rest args +@defun call-process-region start end program &optional deletep destination displayp &rest args This function sends the text between @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{buffer} +sent if @var{deletep} is non-@code{nil}; this is useful when @var{buffer} is @code{t}, to insert the output in the current buffer. -The arguments @var{destination} and @var{display} control what to do +The arguments @var{destination} and @var{displayp} 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, @@ -296,8 +300,8 @@ inputinput@point{} @smallexample @group -(call-process-region - start end +(call-process-region + start end shell-file-name ; @r{Name of program.} nil ; @r{Do not delete region.} buffer ; @r{Send output to @code{buffer}.} @@ -406,7 +410,9 @@ etc.) to work between the process and its children whereas pipes do not. For subprocesses used for internal purposes by programs, it is often better to use a pipe, because they are more efficient. In addition, the total number of @sc{pty}s is limited on many systems and it is good not -to waste them. +to waste them. A rule of thumb is to use ptys for processes the user +interacts with directly, and pipes for processes that are hidden from +the user. The value @code{process-connection-type} is used when @code{start-process} is called. So you can specify how to communicate @@ -425,6 +431,16 @@ To determine whether a given subprocess actually got a pipe or a Information}). @end defvar +Lisp functions that manipulate processes usually accept a @var{process} +argument. Besides using an actual process object for this argument, you +can use a process name, a buffer object, the name of a buffer, or +@code{nil}. Specifying a buffer or buffer name for the @var{process} +argument means use the process associated with the buffer (or the most +recent one, if there is more than one). @code{nil} means use the +process associated with the current buffer. +@xref{Process Information}. +@xref{Process Buffers}. + @node Deleting Processes @section Deleting Processes @cindex deleting processes @@ -500,9 +516,12 @@ This function returns a list of all processes that have not been deleted. @end smallexample @end defun -@defun get-process name -This function returns the process named @var{name}, or @code{nil} if -there is none. An error is signaled if @var{name} is not a string. +@defun get-process process-name +This function returns the process named @var{process-name}. If +@var{process-name} is a string and there is no process with that name, the +value is @code{nil}. If @var{process-name} is actually a process, it is +returned as given. (That is not very useful, so the argument is usually +a name.) For example: @smallexample @group @@ -538,9 +557,9 @@ process is started and remains constant as long as the process exists. This function returns the name of @var{process}. @end defun -@defun process-status process-name -This function returns the status of @var{process-name} as a symbol. -The argument @var{process-name} must be a process, a buffer, a +@defun process-status process +This function returns the status of @var{process} as a symbol. +The argument @var{process} must be a process, a buffer, a process name (string) or a buffer name (string). The possible values for an actual subprocess are: @@ -561,7 +580,7 @@ for a network connection that is closed. Once a connection is closed, you cannot reopen it, though you might be able to open a new connection to the same place. @item nil -if @var{process-name} is not the name of an existing process. +if @var{process} does not identify an existing process. @end table @smallexample @@ -619,15 +638,21 @@ specify the process to send input to, and the input data to send. The data appears on the ``standard input'' of the subprocess. Some operating systems have limited space for buffered input in a -@sc{pty}. On these systems, Emacs sends an @sc{eof} periodically amidst -the other characters, to force them through. For most programs, -these @sc{eof}s do no harm. +@sc{pty}. On these systems, XEmacs sends long input in chunks, with +@sc{eof} characters added amidst the other characters, to force the +operating system to periodically drain the input buffer. For most +programs, these @sc{eof}s do no harm. + +@defun process-send-string process string &optional start end +This function sends @var{process} the contents of @var{string} as +standard input. -@defun process-send-string process-name string -This function sends @var{process-name} the contents of @var{string} as -standard input. The argument @var{process-name} must be a process or -the name of a process. If it is @code{nil}, the current buffer's -process is used. +The argument @var{process} may be a process or the name of a process, or +a buffer or the name of a buffer, in which case the buffer's process is +used. If it is @code{nil}, the current buffer's process is used. + +Optional arguments @var{start} and @var{end} specify part of @var{string}; +see @code{substring}. The function returns @code{nil}. @@ -650,26 +675,28 @@ introduction.txt text.texi~ @end smallexample @end defun -@deffn Command process-send-region process-name start end +@defun process-send-region process start end &optional buffer This function sends the text in the region defined by @var{start} and -@var{end} as standard input to @var{process-name}, which is a process or -a process name. (If it is @code{nil}, the current buffer's process is -used.) +@var{end} as standard input to @var{process}. + +The argument @var{process} may be a process or the name of a process, or +a buffer or the name of a buffer, in which case the buffer's process is +used. If it is @code{nil}, the current buffer's process is used. An error is signaled unless both @var{start} and @var{end} are integers or markers that indicate positions in the current buffer. (It is unimportant which number is larger.) -@end deffn +@end defun -@defun process-send-eof &optional process-name - This function makes @var{process-name} see an end-of-file in its +@defun process-send-eof &optional process + This function makes @var{process} see an end-of-file in its input. The @sc{eof} comes after any text already sent to it. - If @var{process-name} is not supplied, or if it is @code{nil}, then -this function sends the @sc{eof} to the current buffer's process. An -error is signaled if the current buffer has no process. +@var{process} may be a process, a buffer, the name of a process or +buffer, or @code{nil}, indicating the current buffer's process. An +error is signaled if @var{process} does not identify any process. - The function returns @var{process-name}. +The function returns the process object identified by @var{process}. @smallexample @group @@ -704,25 +731,26 @@ defined. XEmacs can send signals only to its own subprocesses. section. XEmacs also sends signals automatically at certain times: killing a buffer sends a @code{SIGHUP} signal to all its associated processes; killing XEmacs sends a @code{SIGHUP} signal to all remaining -processes. (@code{SIGHUP} is a signal that usually indicates that the -user hung up the phone.) +processes. (@code{SIGHUP} is a signal that indicates that the +connection between the user and the process is broken, for example if a +connection via a telephone line is hung up.) Each of the signal-sending functions takes two optional arguments: -@var{process-name} and @var{current-group}. +@var{process} and @var{current-group}. - The argument @var{process-name} must be either a process, the name of -one, or @code{nil}. If it is @code{nil}, the process defaults to the -process associated with the current buffer. An error is signaled if -@var{process-name} does not identify a process. + The argument @var{process} must be either a process or a buffer, +the name of one, or @code{nil}. If it is @code{nil}, the process +defaults to the process associated with the current buffer. An error is +signaled if @var{process} does not identify a process. The argument @var{current-group} is a flag that makes a difference when you are running a job-control shell as an XEmacs subprocess. If it -is non-@code{nil}, then the signal is sent to the current process-group -of the terminal that XEmacs uses to communicate with the subprocess. If -the process is a job-control shell, this means the shell's current -subjob. If it is @code{nil}, the signal is sent to the process group of -the immediate subprocess of XEmacs. If the subprocess is a job-control -shell, this is the shell itself. +is non-@code{nil}, then the signal is sent to the current foreground +process group of the terminal that XEmacs uses to communicate with the +subprocess. If the process is a job-control shell, this means the +shell's current subjob. If it is @code{nil}, the signal is sent to the +process group of the immediate subprocess of XEmacs. If the subprocess +is a job-control shell, this is the shell itself. The flag @var{current-group} has no effect when a pipe is used to communicate with the subprocess, because the operating system does not @@ -730,30 +758,39 @@ support the distinction in the case of pipes. For the same reason, job-control shells won't work when a pipe is used. See @code{process-connection-type} in @ref{Asynchronous Processes}. -@defun interrupt-process &optional process-name current-group -This function interrupts the process @var{process-name} by sending the -signal @code{SIGINT}. Outside of XEmacs, typing the ``interrupt -character'' (normally @kbd{C-c} on some systems, and @code{DEL} on -others) sends this signal. When the argument @var{current-group} is -non-@code{nil}, you can think of this function as ``typing @kbd{C-c}'' -on the terminal by which XEmacs talks to the subprocess. + Some of the functions below take a @var{signal} argument, which +identifies a signal to be sent. It must be either an integer or a +symbol which names the signal, like @code{SIGSEGV}. + +@defun process-send-signal signal &optional process current-group +This function sends the signal @var{signal} to the process @var{process}. +The following functions can be implemented in terms of +@code{process-send-signal}. @end defun -@defun kill-process &optional process-name current-group -This function kills the process @var{process-name} by sending the +@defun interrupt-process &optional process current-group +This function interrupts the process @var{process} by sending the signal +@code{SIGINT}. Outside of XEmacs, typing the ``interrupt character'' +(normally @kbd{C-c}) sends this signal. When the argument +@var{current-group} is non-@code{nil}, you can think of this function as +``typing @kbd{C-c}'' on the terminal by which XEmacs talks to the +subprocess. +@end defun + +@defun kill-process &optional process current-group +This function 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 -@defun quit-process &optional process-name current-group +@defun quit-process &optional process current-group This function sends the signal @code{SIGQUIT} to the process -@var{process-name}. This signal is the one sent by the ``quit -character'' (usually @kbd{C-b} or @kbd{C-\}) when you are not inside -XEmacs. +@var{process}. This signal is the one sent by the ``quit +character'' (usually @kbd{C-\}) when you are not inside XEmacs. @end defun -@defun stop-process &optional process-name current-group -This function stops the process @var{process-name} by sending the +@defun stop-process &optional process current-group +This function stops the process @var{process} by sending the signal @code{SIGTSTP}. Use @code{continue-process} to resume its execution. @@ -763,18 +800,17 @@ non-@code{nil}, you can think of this function as ``typing @kbd{C-z}'' on the terminal XEmacs uses to communicate with the subprocess. @end defun -@defun continue-process &optional process-name current-group +@defun continue-process &optional process current-group This function resumes execution of the process @var{process} by sending -it the signal @code{SIGCONT}. This presumes that @var{process-name} was +it the signal @code{SIGCONT}. This presumes that @var{process} was stopped previously. @end defun -@c Emacs 19 feature -@defun signal-process pid signal -This function sends a signal to process @var{pid}, which need not be -a child of XEmacs. The argument @var{signal} specifies which signal -to send; it should be an integer. -@end defun +@deffn Command signal-process pid signal +This function sends a signal to the process with process id @var{pid}, +which need not be a child of XEmacs. The argument @var{signal} +specifies which signal to send. +@end deffn @node Output from Processes @section Receiving Output from Processes @@ -853,10 +889,10 @@ associated with no buffer. @defun get-buffer-process buffer-or-name This function returns the process associated with @var{buffer-or-name}. -If there are several processes associated with it, then one is chosen. -(Presently, the one chosen is the one most recently created.) It is -usually a bad idea to have more than one process associated with the -same buffer. +If there are several processes associated with @var{buffer-or-name}, +then one is chosen. (Presently, the one chosen is the one most recently +created.) It is usually a bad idea to have more than one process +associated with the same buffer. @smallexample @group @@ -917,20 +953,20 @@ Here is how to do these things: @smallexample @group -(defun ordinary-insertion-filter (proc string) +(defun ordinary-insertion-filter (process string) (let ((old-buffer (current-buffer))) (unwind-protect (let (moving) - (set-buffer (process-buffer proc)) - (setq moving (= (point) (process-mark proc))) + (set-buffer (process-buffer process)) + (setq moving (= (point) (process-mark process))) @end group @group (save-excursion ;; @r{Insert the text, moving the process-marker.} - (goto-char (process-mark proc)) + (goto-char (process-mark process)) (insert string) - (set-marker (process-mark proc) (point))) - (if moving (goto-char (process-mark proc)))) + (set-marker (process-mark process) (point))) + (if moving (goto-char (process-mark process)))) (set-buffer old-buffer)))) @end group @end smallexample @@ -945,7 +981,7 @@ text arrives, insert the following line just before the @code{unwind-protect}: @smallexample -(display-buffer (process-buffer proc)) +(display-buffer (process-buffer process)) @end smallexample To force point to move to the end of the new output no matter where @@ -1023,15 +1059,15 @@ there is no filter function: @group ;; @r{Insert input in the buffer specified by @code{my-shell-buffer}} ;; @r{and make sure that buffer is shown in some window.} -(defun my-process-filter (proc str) +(defun my-process-filter (process string) (let ((cur (selected-window)) (pop-up-windows t)) (pop-to-buffer my-shell-buffer) @end group @group (goto-char (point-max)) - (insert str) - (set-marker (process-mark proc) (point-max)) + (insert string) + (set-marker (process-mark process) (point-max)) (select-window cur))) @end group @end smallexample @@ -1096,7 +1132,7 @@ of event. The string describing the event looks like one of the following: @itemize @bullet -@item +@item @code{"finished\n"}. @item @@ -1245,21 +1281,35 @@ function. It always returns either @code{open} or @code{closed} for a network connection, and it never returns either of those values for a real subprocess. @xref{Process Information}. -@defun open-network-stream name buffer-or-name host service +@defun open-network-stream name buffer-or-name host service &optional protocol This function opens a TCP connection for a service to a host. It returns a process object to represent the connection. +Input and output work as for other process objects. +@code{delete-process} closes the connection. + The @var{name} argument specifies the name for the process object. It is modified as necessary to make it unique. The @var{buffer-or-name} argument is the buffer to associate with the -connection. Output from the connection is inserted in the buffer, -unless you specify a filter function to handle the output. If -@var{buffer-or-name} is @code{nil}, it means that the connection is not -associated with any buffer. +connection. It can be a buffer or the name of one. Output from the +connection is inserted in the buffer, unless you specify a filter +function to handle the output. If @var{buffer-or-name} is @code{nil}, +it means that the connection is not associated with any buffer. The arguments @var{host} and @var{service} specify where to connect to; @var{host} is the host name or IP address (a string), and @var{service} is the name of a defined network service (a string) or a port number (an integer). + +Optional fifth arg @var{protocol} is the network protocol to use. +Currently only @code{tcp} (Transmission Control Protocol) and @code{udp} +(User Datagram Protocol) are supported. When omitted, @code{tcp} is assumed. + +Output via @code{process-send-string} and input via buffer or filter +(see @code{set-process-filter}) are stream-oriented. That means +UDP datagrams are not guaranteed to be sent and received in +discrete packets. (But small datagrams around 500 bytes that are not +truncated by @code{process-send-string} are usually fine.) Note further +that the UDP protocol does not guard against lost packets. @end defun