@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
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.
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}).
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
@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,
@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}.}
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
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
@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
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:
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
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}.
@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
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
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.
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
@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
@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
@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
@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
The string describing the event looks like one of the following:
@itemize @bullet
-@item
+@item
@code{"finished\n"}.
@item
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
projects / chise / xemacs-chise.git.1 / blobdiff