48 |
* Query Before Exit:: Whether to query if exiting will kill a process. |
* Query Before Exit:: Whether to query if exiting will kill a process. |
49 |
* Transaction Queues:: Transaction-based communication with subprocesses. |
* Transaction Queues:: Transaction-based communication with subprocesses. |
50 |
* Network:: Opening network connections. |
* Network:: Opening network connections. |
51 |
|
* Network Servers:: Network servers let Emacs accept net connections. |
52 |
|
* Datagrams:: |
53 |
|
* Low-Level Network:: Lower-level but more general function |
54 |
|
to create connections and servers. |
55 |
@end menu |
@end menu |
56 |
|
|
57 |
@node Subprocess Creation |
@node Subprocess Creation |
83 |
@code{substitute-in-file-name} to perform them (@pxref{File Name |
@code{substitute-in-file-name} to perform them (@pxref{File Name |
84 |
Expansion}). |
Expansion}). |
85 |
|
|
86 |
|
Executing a program can also try adding suffixes to the specified |
87 |
|
name: |
88 |
|
|
89 |
|
@defvar exec-suffixes |
90 |
|
This variable is a list of suffixes (strings) to try adding to the |
91 |
|
specified program file name. The list should include @code{""} if you |
92 |
|
want the name to be tried exactly as specified. The default value is |
93 |
|
system-dependent. |
94 |
|
@end defvar |
95 |
|
|
96 |
Each of the subprocess-creating functions has a @var{buffer-or-name} |
Each of the subprocess-creating functions has a @var{buffer-or-name} |
97 |
argument which specifies where the standard output from the program will |
argument which specifies where the standard output from the program will |
98 |
go. It should be a buffer or a buffer name; if it is a buffer name, |
go. It should be a buffer or a buffer name; if it is a buffer name, |
380 |
@end smallexample |
@end smallexample |
381 |
@end defun |
@end defun |
382 |
|
|
383 |
|
@defun call-process-shell-command command &optional infile destination display &rest args |
384 |
|
This function executes the shell command @var{command} synchronously |
385 |
|
in separate process. The final arguments @var{args} are additional |
386 |
|
arguments to add at the end of @var{command}. The other arguments |
387 |
|
are handled as in @code{call-process}. |
388 |
|
@end defun |
389 |
|
|
390 |
@defun shell-command-to-string command |
@defun shell-command-to-string command |
391 |
This function executes @var{command} (a string) as a shell command, |
This function executes @var{command} (a string) as a shell command, |
392 |
then returns the command's output as a string. |
then returns the command's output as a string. |
550 |
Several functions return information about processes. |
Several functions return information about processes. |
551 |
@code{list-processes} is provided for interactive use. |
@code{list-processes} is provided for interactive use. |
552 |
|
|
553 |
@deffn Command list-processes |
@deffn Command list-processes &optional query-only |
554 |
This command displays a listing of all living processes. In addition, |
This command displays a listing of all living processes. In addition, |
555 |
it finally deletes any process whose status was @samp{Exited} or |
it finally deletes any process whose status was @samp{Exited} or |
556 |
@samp{Signaled}. It returns @code{nil}. |
@samp{Signaled}. It returns @code{nil}. |
557 |
|
|
558 |
|
If @var{query-only} is non-@code{nil} then it lists only processes |
559 |
|
whose query flag is non-@code{nil}. @xref{Query Before Exit}. |
560 |
@end deffn |
@end deffn |
561 |
|
|
562 |
@defun process-list |
@defun process-list |
608 |
This function returns the name of @var{process}. |
This function returns the name of @var{process}. |
609 |
@end defun |
@end defun |
610 |
|
|
|
@defun process-contact process |
|
|
This function returns @code{t} for an ordinary child process, and |
|
|
@code{(@var{hostname} @var{service})} for a net connection |
|
|
(@pxref{Network}). |
|
|
@end defun |
|
|
|
|
611 |
@defun process-status process-name |
@defun process-status process-name |
612 |
This function returns the status of @var{process-name} as a symbol. |
This function returns the status of @var{process-name} as a symbol. |
613 |
The argument @var{process-name} must be a process, a buffer, a |
The argument @var{process-name} must be a process, a buffer, a |
630 |
for a network connection that is closed. Once a connection |
for a network connection that is closed. Once a connection |
631 |
is closed, you cannot reopen it, though you might be able to open |
is closed, you cannot reopen it, though you might be able to open |
632 |
a new connection to the same place. |
a new connection to the same place. |
633 |
|
@item connect |
634 |
|
for a non-blocking connection that is waiting to complete. |
635 |
|
@item failed |
636 |
|
for a non-blocking connection that has failed to complete. |
637 |
|
@item listen |
638 |
|
for a network server that is listening. |
639 |
@item nil |
@item nil |
640 |
if @var{process-name} is not the name of an existing process. |
if @var{process-name} is not the name of an existing process. |
641 |
@end table |
@end table |
693 |
input. |
input. |
694 |
@end defun |
@end defun |
695 |
|
|
696 |
|
Every process also has a property list that you can use to store |
697 |
|
miscellaneous values associated with the process. |
698 |
|
|
699 |
|
@defun process-get process propname |
700 |
|
This function returns the value of the @var{propname} property |
701 |
|
of @var{process}. |
702 |
|
@end defun |
703 |
|
|
704 |
|
@defun process-put process propname value |
705 |
|
This function sets the value of the @var{propname} property |
706 |
|
of @var{process} to @var{value}. |
707 |
|
@end defun |
708 |
|
|
709 |
|
@defun process-plist process |
710 |
|
This function returns the process plist of @var{process}. |
711 |
|
@end defun |
712 |
|
|
713 |
|
@defun set-process-plist process plist |
714 |
|
This function sets the process plist of @var{process} to @var{plist}. |
715 |
|
@end defun |
716 |
|
|
717 |
@node Input to Processes |
@node Input to Processes |
718 |
@section Sending Input to Processes |
@section Sending Input to Processes |
719 |
@cindex process input |
@cindex process input |
894 |
@end defun |
@end defun |
895 |
|
|
896 |
@c Emacs 19 feature |
@c Emacs 19 feature |
897 |
@defun signal-process pid signal |
@defun signal-process process signal |
898 |
This function sends a signal to process @var{pid}, which need not be |
This function sends a signal to process @var{process}. The argument |
899 |
a child of Emacs. The argument @var{signal} specifies which signal |
@var{signal} specifies which signal to send; it should be an integer. |
900 |
to send; it should be an integer. |
|
901 |
|
You can specify the target process by its process @sc{id}; that allows |
902 |
|
you to send signals to processes that are not children of Emacs. |
903 |
@end defun |
@end defun |
904 |
|
|
905 |
@node Output from Processes |
@node Output from Processes |
935 |
redirect one of them to a file--for example, by using an appropriate |
redirect one of them to a file--for example, by using an appropriate |
936 |
shell command. |
shell command. |
937 |
|
|
|
Subprocess output is normally decoded using a coding system before the |
|
|
buffer or filter function receives it, much like text read from a file. |
|
|
You can use @code{set-process-coding-system} to specify which coding |
|
|
system to use (@pxref{Process Information}). Otherwise, the coding |
|
|
system comes from @code{coding-system-for-read}, if that is |
|
|
non-@code{nil}; or else from the defaulting mechanism (@pxref{Default |
|
|
Coding Systems}). |
|
|
|
|
|
@strong{Warning:} Coding systems such as @code{undecided} which |
|
|
determine the coding system from the data do not work entirely reliably |
|
|
with asynchronous subprocess output. This is because Emacs has to |
|
|
process asynchronous subprocess output in batches, as it arrives. Emacs |
|
|
must try to detect the proper coding system from one batch at a time, |
|
|
and this does not always work. Therefore, if at all possible, use a |
|
|
coding system which determines both the character code conversion and |
|
|
the end of line conversion---that is, one like @code{latin-1-unix}, |
|
|
rather than @code{undecided} or @code{latin-1}. |
|
|
|
|
938 |
@menu |
@menu |
939 |
* Process Buffers:: If no filter, output is put in a buffer. |
* Process Buffers:: If no filter, output is put in a buffer. |
940 |
* Filter Functions:: Filter functions accept output from the process. |
* Filter Functions:: Filter functions accept output from the process. |
941 |
* Accepting Output:: Explicitly permitting subprocess output. |
* Decoding Output:: Filters can get unibyte or multibyte strings. |
942 |
Waiting for subprocess output. |
* Accepting Output:: How to wait until process output arrives. |
943 |
@end menu |
@end menu |
944 |
|
|
945 |
@node Process Buffers |
@node Process Buffers |
1181 |
@end smallexample |
@end smallexample |
1182 |
@end ignore |
@end ignore |
1183 |
|
|
1184 |
|
@node Decoding Output |
1185 |
|
@subsection Decoding Process Output |
1186 |
|
|
1187 |
|
When Emacs writes process output directly into a multibyte buffer, |
1188 |
|
it decodes the output according to the process output coding system. |
1189 |
|
If the coding system is @code{raw-text} or @code{no-conversion}, Emacs |
1190 |
|
converts the unibyte output to multibyte using |
1191 |
|
@code{string-to-multibyte}, inserts the resulting multibyte text. |
1192 |
|
|
1193 |
|
You can use @code{set-process-coding-system} to specify which coding |
1194 |
|
system to use (@pxref{Process Information}). Otherwise, the coding |
1195 |
|
system comes from @code{coding-system-for-read}, if that is |
1196 |
|
non-@code{nil}; or else from the defaulting mechanism (@pxref{Default |
1197 |
|
Coding Systems}). |
1198 |
|
|
1199 |
|
@strong{Warning:} Coding systems such as @code{undecided} which |
1200 |
|
determine the coding system from the data do not work entirely |
1201 |
|
reliably with asynchronous subprocess output. This is because Emacs |
1202 |
|
has to process asynchronous subprocess output in batches, as it |
1203 |
|
arrives. Emacs must try to detect the proper coding system from one |
1204 |
|
batch at a time, and this does not always work. Therefore, if at all |
1205 |
|
possible, specify a coding system that determines both the character |
1206 |
|
code conversion and the end of line conversion---that is, one like |
1207 |
|
@code{latin-1-unix}, rather than @code{undecided} or @code{latin-1}. |
1208 |
|
|
1209 |
|
@cindex filter multibyte flag, of process |
1210 |
|
@cindex process filter multibyte flag |
1211 |
|
When Emacs calls a process filter function, it provides the process |
1212 |
|
output as a multibyte string or as a unibyte string according to the |
1213 |
|
process's filter multibyte flag. If the flag is non-@code{nil}, Emacs |
1214 |
|
decodes the output according to the process output coding system to |
1215 |
|
produce a multibyte string, and passes that to the process. If the |
1216 |
|
flag is @code{nil}, Emacs puts the output into a unibyte string, with |
1217 |
|
no decoding, and passes that. |
1218 |
|
|
1219 |
|
When you create a process, the filter multibyte flag takes its |
1220 |
|
initial value from @code{default-enable-multibyte-characters}. If you |
1221 |
|
want to change the flag later on, use |
1222 |
|
@code{set-process-filter-multibyte}. |
1223 |
|
|
1224 |
|
@defun set-process-filter-multibyte process multibyte |
1225 |
|
This function sets the filter multibyte flag of @var{process} |
1226 |
|
to @var{multibyte}. |
1227 |
|
@end defun |
1228 |
|
|
1229 |
|
@defun process-filter-multibyte-p process |
1230 |
|
This function returns the filter multibyte flag of @var{process}. |
1231 |
|
@end defun |
1232 |
|
|
1233 |
@node Accepting Output |
@node Accepting Output |
1234 |
@subsection Accepting Output from Processes |
@subsection Accepting Output from Processes |
1235 |
|
|
1473 |
@section Network Connections |
@section Network Connections |
1474 |
@cindex network connection |
@cindex network connection |
1475 |
@cindex TCP |
@cindex TCP |
1476 |
|
@cindex UDP |
1477 |
|
|
1478 |
Emacs Lisp programs can open TCP network connections to other processes on |
Emacs Lisp programs can open stream (TCP) and datagram (UDP) network |
1479 |
the same machine or other machines. A network connection is handled by Lisp |
connections to other processes on the same machine or other machines. |
1480 |
much like a subprocess, and is represented by a process object. |
A network connection is handled by Lisp much like a subprocess, and is |
1481 |
However, the process you are communicating with is not a child of the |
represented by a process object. However, the process you are |
1482 |
Emacs process, so you can't kill it or send it signals. All you can do |
communicating with is not a child of the Emacs process, so it has no |
1483 |
is send and receive data. @code{delete-process} closes the connection, |
process @sc{id}, and you can't kill it or send it signals. All you |
1484 |
but does not kill the process at the other end; that process must decide |
can do is send and receive data. @code{delete-process} closes the |
1485 |
what to do about closure of the connection. |
connection, but does not kill the program at the other end; that |
1486 |
|
program must decide what to do about closure of the connection. |
1487 |
|
|
1488 |
|
Lisp programs can listen for connections by creating network |
1489 |
|
servers. A network server is also represented by a kind of process |
1490 |
|
object, but unlike a network connection, the network server never |
1491 |
|
transfers data itself. When it receives a connection request, it |
1492 |
|
creates a new network connection to represent the connection just |
1493 |
|
made. (The network connection inherits certain information, including |
1494 |
|
the process plist, from the server.) The network server then goes |
1495 |
|
back to listening for more connection requests. |
1496 |
|
|
1497 |
|
Network connections and servers are created by calling |
1498 |
|
@code{make-network-process} with an argument list consisting of |
1499 |
|
keyword/argument pairs, for example @code{:server t} to create a |
1500 |
|
server process, or @code{:type 'datagram} to create a datagram |
1501 |
|
connection. @xref{Low-Level Network}, for details. You can also use |
1502 |
|
one of the @code{open-network-...} functions descibed below; |
1503 |
|
internally, they just call @code{make-network-process} with suitable |
1504 |
|
arguments. |
1505 |
|
|
1506 |
You can distinguish process objects representing network connections |
You can distinguish process objects representing network connections |
1507 |
from those representing subprocesses with the @code{process-status} |
and servers from those representing subprocesses with the |
1508 |
function. It always returns either @code{open} or @code{closed} for a |
@code{process-status} function. The possible status values for |
1509 |
network connection, and it never returns either of those values for a |
network connections are @code{open}, @code{closed}, @code{connect}, |
1510 |
real subprocess. @xref{Process Information}. |
and @code{failed}. For a network server, the status is always |
1511 |
|
@code{listen}. None of those values is possible for a real |
1512 |
|
subprocess. @xref{Process Information}. |
1513 |
|
|
1514 |
|
You can stop and resume operation of a network processes by calling |
1515 |
|
@code{stop-process} and @code{continue-process}. For a server |
1516 |
|
process, being stopped means not accepting new connections. (Up to 5 |
1517 |
|
connection requests will be queued for when you resume the server; you |
1518 |
|
can increase this limit, unless it is imposed by the operating |
1519 |
|
systems.) For a network stream connection, being stopped means not |
1520 |
|
processing input (any arriving input waits until you resume the |
1521 |
|
connection). For a datagram connection, some number of packets may be |
1522 |
|
queued but input may be lost. You can use the function |
1523 |
|
@code{process-command} to determine whether a network connection or |
1524 |
|
server is stopped; a non-@code{nil} value means yes. |
1525 |
|
|
1526 |
@defun open-network-stream name buffer-or-name host service |
@defun open-network-stream name buffer-or-name host service |
1527 |
This function opens a TCP connection for a service to a host. It |
This function opens a TCP connection, and returns a process object |
1528 |
returns a process object to represent the connection. |
that represents the connection. |
1529 |
|
|
1530 |
The @var{name} argument specifies the name for the process object. It |
The @var{name} argument specifies the name for the process object. It |
1531 |
is modified as necessary to make it unique. |
is modified as necessary to make it unique. |
1540 |
@var{host} is the host name (a string), and @var{service} is the name of |
@var{host} is the host name (a string), and @var{service} is the name of |
1541 |
a defined network service (a string) or a port number (an integer). |
a defined network service (a string) or a port number (an integer). |
1542 |
@end defun |
@end defun |
1543 |
|
|
1544 |
|
@defun open-network-stream-nowait name buffer-or-name host service &optional sentinel filter |
1545 |
|
This function opens a TCP connection, like @code{open-network-stream}, |
1546 |
|
but it returns immediately without waiting for the request to be |
1547 |
|
accepted or rejected by the remote server. When the request is |
1548 |
|
subsequently accepted or rejected, the process's sentinel function |
1549 |
|
will be called with a string that starts with @code{"open"} (on |
1550 |
|
success) or @code{"failed"} (on error). |
1551 |
|
|
1552 |
|
Some systems do not support non-blocking connections; on those |
1553 |
|
systems, @code{open-network-stream-nowait} returns @code{nil} |
1554 |
|
and does nothing. |
1555 |
|
|
1556 |
|
The optional arguments @var{sentinel} and @var{filter} specify the |
1557 |
|
sentinel and filter functions for this network connection. It is |
1558 |
|
useful to specify them when opening the connection, because they will |
1559 |
|
be used later asynchronously. The other arguments mean the same as in |
1560 |
|
@code{open-network-stream}. |
1561 |
|
@end defun |
1562 |
|
|
1563 |
|
@defun process-contact process &optional key |
1564 |
|
This function returns information about how a network process was set |
1565 |
|
up. For a connection, when @var{key} is @code{nil}, it returns |
1566 |
|
@code{(@var{hostname} @var{service})} which specifies what you |
1567 |
|
connected to. |
1568 |
|
|
1569 |
|
If @var{key} is @code{t}, the value is the complete status information |
1570 |
|
for the connection or server; that is, the list of keywords and values |
1571 |
|
specified in @code{make-network-process}, except that some of the |
1572 |
|
values represent the current status instead of what you specified: |
1573 |
|
|
1574 |
|
@table @code |
1575 |
|
@item :buffer |
1576 |
|
The associated value is the process buffer. |
1577 |
|
@item :filter |
1578 |
|
The associated value is the process filter function. |
1579 |
|
@item :sentinel |
1580 |
|
The associated value is the process sentinel function. |
1581 |
|
@item :remote |
1582 |
|
In a connection, this is the address in internal format of the remote peer. |
1583 |
|
@item :local |
1584 |
|
The local address, in internal format. |
1585 |
|
@item :service |
1586 |
|
In a server, if you specified @code{t} for @var{service}, |
1587 |
|
this value is the actual port number. |
1588 |
|
@end table |
1589 |
|
|
1590 |
|
@code{:local} and @code{:remote} are included even if they were not |
1591 |
|
specified explicitly in @code{make-network-process}. |
1592 |
|
|
1593 |
|
If @var{key} is a keyword, the function returns the value corresponding |
1594 |
|
to that keyword. |
1595 |
|
|
1596 |
|
For an ordinary child process, this function always returns @code{t}. |
1597 |
|
@end defun |
1598 |
|
|
1599 |
|
@node Network Servers |
1600 |
|
@section Network Servers |
1601 |
|
|
1602 |
|
You create a server by calling @code{make-network-process} with |
1603 |
|
@code{:server t}. The server will listen for connection requests from |
1604 |
|
clients. When it accepts a client connection request, that creates a |
1605 |
|
new network connection, itself a process object, with the following |
1606 |
|
parameters: |
1607 |
|
|
1608 |
|
@itemize @bullet |
1609 |
|
@item |
1610 |
|
The connection's process name is constructed by concatenating the |
1611 |
|
server process' @var{name} with a client identification string. The |
1612 |
|
client identification string for an IPv4 connection looks like |
1613 |
|
@samp{<@var{a}.@var{b}.@var{c}.@var{d}:@var{p}>}. Otherwise, it is a |
1614 |
|
unique number in brackets, as in @samp{<@var{nnn}>}. The number |
1615 |
|
is unique for each connection in the Emacs session. |
1616 |
|
|
1617 |
|
@item |
1618 |
|
If the server's filter is non-@code{nil}, the connection process does |
1619 |
|
not get a separate process buffer; otherwise, Emacs creates a new |
1620 |
|
buffer for the purpose. The buffer name is the server's buffer name |
1621 |
|
or process name, concatenated with the client identification string. |
1622 |
|
|
1623 |
|
The server's process buffer value is never used directly by Emacs, but |
1624 |
|
it is passed to the log function, which can log connections by |
1625 |
|
inserting text there. |
1626 |
|
|
1627 |
|
@item |
1628 |
|
The communication type and the process filter and sentinel are |
1629 |
|
inherited from those of the server. The server never directly |
1630 |
|
uses its filter and sentinel; their sole purpose is to initialize |
1631 |
|
connections made to the server. |
1632 |
|
|
1633 |
|
@item |
1634 |
|
The connection's process contact info is set according to the client's |
1635 |
|
addressing information (typically an IP address and a port number). |
1636 |
|
This information is associated with the @code{process-contact} |
1637 |
|
keywords @code{:host}, @code{:service}, @code{:remote}. |
1638 |
|
|
1639 |
|
@item |
1640 |
|
The connection's local address is set up according to the port |
1641 |
|
number used for the connection. |
1642 |
|
|
1643 |
|
@item |
1644 |
|
The client process' plist is initialized from the server's plist. |
1645 |
|
@end itemize |
1646 |
|
|
1647 |
|
@defun open-network-stream-server name buffer-or-name service &optional sentinel filter |
1648 |
|
Create a network server process for a TCP service. |
1649 |
|
It returns nil if server processes are not supported; otherwise, |
1650 |
|
it returns a subprocess-object to represent the server. |
1651 |
|
|
1652 |
|
When a client connects to the specified service, Emacs creates a new |
1653 |
|
subprocess to handle the new connection, and then calls its sentinel |
1654 |
|
function (which it has inherited from the server). |
1655 |
|
|
1656 |
|
The optional arguments @var{sentinel} and @var{filter} specify the |
1657 |
|
sentinel and filter functions for the server. It is useful to specify |
1658 |
|
them now, because they will be used later asynchronously when the |
1659 |
|
server receives a connection request. The three arguments @var{name}, |
1660 |
|
@var{buffer-or-name} and @var{service} mean the same thing as in |
1661 |
|
@code{open-network-stream}, but @var{service} can be @code{t} |
1662 |
|
meaning ask the system to allocate an unused port to listen on. |
1663 |
|
@end defun |
1664 |
|
|
1665 |
|
@node Datagrams |
1666 |
|
@section Datagrams |
1667 |
|
@cindex datagrams |
1668 |
|
|
1669 |
|
A datagram connection communicates with individual packets |
1670 |
|
rather than streams of data. Each call to @code{process-send} |
1671 |
|
sends one datagram packet, and each datagram received results |
1672 |
|
in one call to the filter function. |
1673 |
|
|
1674 |
|
The datagram connection doesn't have to talk with the same remote |
1675 |
|
peer all the time. It has a @dfn{remote peer address} which specifies |
1676 |
|
where to send datagrams to. Each time an incoming datagram is passed |
1677 |
|
to the filter function, the peer address is set to the address that |
1678 |
|
datagram came from; that way, if the filter function sends a datagram, |
1679 |
|
it will go back to that place. You can specify the remote peer |
1680 |
|
address when you create the datagram connection using the |
1681 |
|
@code{:remote} keyword. You can change it later on by calling |
1682 |
|
@code{set-process-datagram-address}. |
1683 |
|
|
1684 |
|
@defun process-datagram-address process |
1685 |
|
If @var{process} is a datagram connection or server, this function |
1686 |
|
returns its remote peer address. |
1687 |
|
@end defun |
1688 |
|
|
1689 |
|
@defun set-process-datagram-address process address |
1690 |
|
If @var{process} is a datagram connection or server, this function |
1691 |
|
sets its remote peer address to @var{address}. |
1692 |
|
@end defun |
1693 |
|
|
1694 |
|
@node Low-Level Network |
1695 |
|
@section Low-Level Network Access |
1696 |
|
|
1697 |
|
The basic function for creating network connections and network |
1698 |
|
servers is @code{make-network-process}. It can do either of those |
1699 |
|
jobs, depending on the arguments you give it. |
1700 |
|
|
1701 |
|
@defun make-network-process &rest args |
1702 |
|
This function creates a network connection or server and returns the |
1703 |
|
process object that represents it. The arguments @var{args} are a |
1704 |
|
list of keyword/argument pairs. Omitting a keyword is always |
1705 |
|
equivalent to specifying it with value @code{nil}, except for |
1706 |
|
@code{:coding}, @code{:filter-multibyte}, and @code{:reuseaddr}. Here |
1707 |
|
are the meaningful keywords: |
1708 |
|
|
1709 |
|
@table @asis |
1710 |
|
@item :name name |
1711 |
|
Use the string @var{name} as the process name. It is modified if |
1712 |
|
necessary to make it unique. |
1713 |
|
|
1714 |
|
@item :type @var{type} |
1715 |
|
Specify the communication type. A value of @code{nil} specifies a |
1716 |
|
stream connection (the default); @code{datagram} specifies a datagram |
1717 |
|
connection. Both connections and servers can be of either type. |
1718 |
|
|
1719 |
|
@item :server @var{server-flag} |
1720 |
|
If @var{server-flag} is non-@code{nil}, create a server. Otherwise, |
1721 |
|
create a connection. For a stream type server, @var{server-flag} may |
1722 |
|
be an integer which then specifies the length of the queue of pending |
1723 |
|
connections to the server. The default queue length is 5. |
1724 |
|
|
1725 |
|
@item :host @var{host} |
1726 |
|
Specify the host to connect to. @var{host} should be a host name or |
1727 |
|
internet address, as a string, or the symbol @code{local} to specify |
1728 |
|
the local host. If you specify @var{host} for a server, it must |
1729 |
|
specify a valid address for the local host, and only clients |
1730 |
|
connecting to that address will be accepted. |
1731 |
|
|
1732 |
|
@item :service @var{service} |
1733 |
|
@var{service} specifies a port number to connect to, or, for a server, |
1734 |
|
the port number to listen on. It should be a service name that |
1735 |
|
translates to a port number, or an integer specifying the port number |
1736 |
|
directly. For a server, it can also be @code{t}, which means to let |
1737 |
|
the system select an unused port number. |
1738 |
|
|
1739 |
|
@item :family @var{family} |
1740 |
|
@var{family} specifies the address (and protocol) family for |
1741 |
|
communication. @code{nil} stands for IPv4. @code{local} specifies a |
1742 |
|
Unix socket, in which case @var{host} is ignored. |
1743 |
|
|
1744 |
|
@item :local @var{local-address} |
1745 |
|
For a server process, @var{local-address} is the address to listen on. |
1746 |
|
It overrides @var{family}, @var{host} and @var{service}, and you |
1747 |
|
may as well not specify them. |
1748 |
|
|
1749 |
|
@item :remote @var{remote-address} |
1750 |
|
For a connection, @var{remote-address} is the address to connect to. |
1751 |
|
It overrides @var{family}, @var{host} and @var{service}, and you |
1752 |
|
may as well not specify them. |
1753 |
|
|
1754 |
|
For a datagram server, @var{remote-address} specifies the initial |
1755 |
|
setting of the remote datagram address. |
1756 |
|
|
1757 |
|
The format of @var{local-address} or @var{remote-address} depends on |
1758 |
|
the address family: |
1759 |
|
|
1760 |
|
@itemize - |
1761 |
|
@item |
1762 |
|
An IPv4 address is represented as a vector of integers @code{[@var{a} |
1763 |
|
@var{b} @var{c} @var{d} @var{p}]} corresponding to numeric IP address |
1764 |
|
@var{a}.@var{b}.@var{c}.@var{d} and port number @var{p}. |
1765 |
|
|
1766 |
|
@item |
1767 |
|
A local address is represented as a string which specifies the address |
1768 |
|
in the local address space. |
1769 |
|
|
1770 |
|
@item |
1771 |
|
An ``unsupported family'' address is represented by a cons |
1772 |
|
@code{(@var{f} . @var{av})}, where @var{f} is the family number and |
1773 |
|
@var{av} is a vector specifying the socket address using with one |
1774 |
|
element per address data byte. Do not rely on this format in portable |
1775 |
|
code, as it may depend on implementation defined constants, data |
1776 |
|
sizes, and data structure alignment. |
1777 |
|
@end itemize |
1778 |
|
|
1779 |
|
@item :nowait @var{bool} |
1780 |
|
If @var{bool} is non-@code{nil} for a stream connection, return |
1781 |
|
without waiting for the connection to complete. When the connection |
1782 |
|
succeeds or fails, Emacs will call the sentinel function, with a |
1783 |
|
second argument matching @code{"open"} (if successful) or |
1784 |
|
@code{"failed"}. The default is to block, so that |
1785 |
|
@code{make-network-process} does not return until the connection |
1786 |
|
has succeeded or failed. |
1787 |
|
|
1788 |
|
@item :stop @var{stopped} |
1789 |
|
Start the network connection or server in the `stopped' state if |
1790 |
|
@var{stopped} is non-@code{nil}. |
1791 |
|
|
1792 |
|
@item :buffer @var{buffer} |
1793 |
|
Use @var{buffer} as the process buffer. |
1794 |
|
|
1795 |
|
@item :coding @var{coding} |
1796 |
|
Use @var{coding} as the coding system for this process. To specify |
1797 |
|
different coding systems for decoding data from the connection and for |
1798 |
|
encoding data sent to it, specify @code{(@var{decoding} . |
1799 |
|
@var{encoding})} for @var{coding}. |
1800 |
|
|
1801 |
|
If you don't specify this keyword at all, the default |
1802 |
|
is to determine the coding systems from the data. |
1803 |
|
|
1804 |
|
@item :noquery @var{query-flag} |
1805 |
|
Initialize the process query flag to @var{query-flag}. @xref{Query Before Exit}. |
1806 |
|
|
1807 |
|
@item :filter @var{filter} |
1808 |
|
Initialize the process filter to @var{filter}. |
1809 |
|
|
1810 |
|
@item :filter-multibyte @var{bool} |
1811 |
|
If @var{bool} is non-@code{nil}, strings given to the process filter |
1812 |
|
are multibyte, otherwise they are unibyte. If you don't specify this |
1813 |
|
keyword at all, the default is that the strings are multibyte if |
1814 |
|
@code{default-enable-multibyte-characters} is non-@code{nil}. |
1815 |
|
|
1816 |
|
@item :sentinel @var{sentinel} |
1817 |
|
Initialize the process sentinel to @var{sentinel}. |
1818 |
|
|
1819 |
|
@item :log @var{log} |
1820 |
|
Initialize the log function of a server process to @var{log}. The log |
1821 |
|
function is called each time the server accepts a network connection |
1822 |
|
from a client. The arguments passed to the log function are |
1823 |
|
@var{server}, @var{connection}, and @var{message}, where @var{server} |
1824 |
|
is the server process, @var{connection} is the new process for the |
1825 |
|
connection, and @var{message} is a string describing what has |
1826 |
|
happened. |
1827 |
|
|
1828 |
|
@item :plist @var{plist} |
1829 |
|
Initialize the process plist to @var{plist}. |
1830 |
|
@end table |
1831 |
|
|
1832 |
|
The following network options can be specified for the network |
1833 |
|
process. Except for @code{:reuseaddr}, you can set or modify these |
1834 |
|
options later using @code{set-network-process-option}. |
1835 |
|
|
1836 |
|
For a server process, the options specified with |
1837 |
|
@code{make-network-process} are not inherited by the client |
1838 |
|
connections, so you will need to set the necessary options for each |
1839 |
|
child connection as they are created. |
1840 |
|
|
1841 |
|
@table @asis |
1842 |
|
@item :bindtodevice @var{device-name} |
1843 |
|
If @var{device-name} is a non-empty string identifying a network |
1844 |
|
interface name (see @code{network-interface-list}), only handle |
1845 |
|
packets received on that interface. If @var{device-name} is nil (the |
1846 |
|
default), handle packets received on any interface. |
1847 |
|
|
1848 |
|
Using this option may require special privileges on some systems. |
1849 |
|
|
1850 |
|
@item :broadcast @var{broadcast-flag} |
1851 |
|
If @var{broadcast-flag} is non-@code{nil} for a datagram process, the |
1852 |
|
process will receive datagram packet sent to a broadcast address, and |
1853 |
|
be able to send packets to a broadcast address. Ignored for a stream |
1854 |
|
connection. |
1855 |
|
|
1856 |
|
@item :dontroute @var{dontroute-flag} |
1857 |
|
If @var{dontroute-flag} is non-@code{nil}, the process can only send |
1858 |
|
to hosts on the same network as the local host. |
1859 |
|
|
1860 |
|
@item :keepalive @var{keepalive-flag} |
1861 |
|
If @var{keepalive-flag} is non-@code{nil} for a stream connection, |
1862 |
|
enable exchange of low-level keep-alive messa |
1863 |
|
|
1864 |
|
@item :linger @var{linger-arg} |
1865 |
|
If @var{linger-arg} is non-@code{nil}, wait for successful |
1866 |
|
transmission of all queued packets on the connection before it is |
1867 |
|
deleted (see @code{delete-process}). If @var{linger-arg} is an |
1868 |
|
integer, it specifies the maximum time in seconds to wait for queued |
1869 |
|
packets to be sent before closing the connection. Default is |
1870 |
|
@code{nil} which means to discard unsent queued packets when the |
1871 |
|
process is deleted. |
1872 |
|
|
1873 |
|
@item :oobinline @var{oobinline-flag} |
1874 |
|
If @var{oobinline-flag} is non-@code{nil} for a stream connection, |
1875 |
|
receive out-of-band data in the normal data stream. Otherwise, ignore |
1876 |
|
out-of-band data. |
1877 |
|
|
1878 |
|
@item :priority @var{priority} |
1879 |
|
Set the priority for packets sent on this connection to the integer |
1880 |
|
@var{priority}. The interpretation of this number is protocol |
1881 |
|
specific, such as setting the TOS (type of service) field on IP |
1882 |
|
packets sent on this connection. It may also have system dependent |
1883 |
|
effects, such as selecting a specific output queue on the network |
1884 |
|
interface. |
1885 |
|
|
1886 |
|
@item :reuseaddr @var{reuseaddr-flag} |
1887 |
|
If @var{reuseaddr-flag} is non-@code{nil} (the default) for a stream |
1888 |
|
server process, allow this server to reuse a specific port number (see |
1889 |
|
@code{:service}) unless another process on this host is already |
1890 |
|
listening on that port. If @var{reuseaddr-flag} is @code{nil}, there |
1891 |
|
may be a period of time after the last use of that port (by any |
1892 |
|
process on the host), where it is not possible to make a new server on |
1893 |
|
that port. |
1894 |
|
|
1895 |
|
@end table |
1896 |
|
|
1897 |
|
The original argument list, modified with the actual connection |
1898 |
|
information, is available via the `process-contact' function. |
1899 |
|
@end defun |
1900 |
|
|
1901 |
|
@defun set-network-process-option process option value |
1902 |
|
This function sets or modifies a network option for network process |
1903 |
|
@var{process}. See @code{make-network-process} for details of options |
1904 |
|
@var{option} and their corresponding values @var{value}. |
1905 |
|
|
1906 |
|
The current setting of an option is available via the |
1907 |
|
`process-contact' function. |
1908 |
|
@end defun |
1909 |
|
|
1910 |
|
@defun network-interface-list |
1911 |
|
This function returns a list describing the network interfaces |
1912 |
|
of the machine you are using. The value is an alist whose |
1913 |
|
elements have the form @code{(@var{name} . @var{address})}. |
1914 |
|
@var{address} has the same form as the @var{local-address} |
1915 |
|
and @var{remote-address} arguments to @code{make-network-process}. |
1916 |
|
@end defun |
1917 |
|
|
1918 |
|
@defun network-interface-info ifname |
1919 |
|
This function returns information about the network interface named |
1920 |
|
@var{ifname}. The value is a list of the form @code{(@var{addr} @var{bcast} @var{netmask} @var{hwaddr} @var{flags})}. |
1921 |
|
|
1922 |
|
@table @var |
1923 |
|
@item addr |
1924 |
|
The internet protocol address. |
1925 |
|
@item bcast |
1926 |
|
The broadcast address. |
1927 |
|
@item netmask |
1928 |
|
The network mask. |
1929 |
|
@item hwaddr |
1930 |
|
The layer 2 address (Ethernet MAC address, for instance). |
1931 |
|
@item flags |
1932 |
|
The current flags of the interface. |
1933 |
|
@end table |
1934 |
|
@end defun |
1935 |
|
|
1936 |
|
@defun format-network-address address &optional omit-port |
1937 |
|
This function converts the Lisp representation of a network address to |
1938 |
|
a string. For example, a five-element vector @code{[@var{a} @var{b} |
1939 |
|
@var{c} @var{d} @var{p}]} represents an IP address |
1940 |
|
@var{a}.@var{b}.@var{c}.@var{d} and port number @var{p}. |
1941 |
|
@code{format-network-address} converts that to the string |
1942 |
|
@code{"@var{a}.@var{b}.@var{c}.@var{d}:@var{p}"}. |
1943 |
|
|
1944 |
|
If @var{omit-port} is non-@code{nil}, the value does not include |
1945 |
|
the port number. |
1946 |
|
@end defun |
1947 |
|
|
1948 |
|
To test for the availability of a given network feature, use |
1949 |
|
@code{featurep} like this: |
1950 |
|
|
1951 |
|
@example |
1952 |
|
(featurep 'make-network-process '(@var{keyword} @var{value})) |
1953 |
|
@end example |
1954 |
|
|
1955 |
|
@noindent |
1956 |
|
The result of the first form is @code{t} if it works to specify |
1957 |
|
@var{keyword} with value @var{value} in @code{make-network-process}. |
1958 |
|
The result of the second form is @code{t} if @var{keyword} is |
1959 |
|
supported by @code{make-network-process}. Here are some of the |
1960 |
|
@var{keyword}---@var{value} pairs you can test in |
1961 |
|
this way. |
1962 |
|
|
1963 |
|
@table @code |
1964 |
|
@item (:nowait t) |
1965 |
|
Non-@code{nil} if non-blocking connect is supported. |
1966 |
|
@item (:type datagram) |
1967 |
|
Non-@code{nil} if datagrams are supported. |
1968 |
|
@item (:family local) |
1969 |
|
Non-@code{nil} if local (aka ``UNIX domain'') sockets are supported. |
1970 |
|
@item (:service t) |
1971 |
|
Non-@code{nil} if the system can select the port for a server. |
1972 |
|
@end table |
1973 |
|
|
1974 |
|
To test for the availability of a given network option, use |
1975 |
|
@code{featurep} like this: |
1976 |
|
|
1977 |
|
@example |
1978 |
|
(featurep 'make-network-process '@var{keyword}) |
1979 |
|
@end example |
1980 |
|
|
1981 |
|
Here are some of the option @var{keyword}s you can test in |
1982 |
|
this way. |
1983 |
|
|
1984 |
|
@table @code |
1985 |
|
@item :bindtodevice |
1986 |
|
@itemx :broadcast |
1987 |
|
@itemx :dontroute |
1988 |
|
@itemx :keepalive |
1989 |
|
@itemx :linger |
1990 |
|
@itemx :oobinline |
1991 |
|
@itemx :priority |
1992 |
|
@itemx :reuseaddr |
1993 |
|
That particular network option is supported by |
1994 |
|
@code{make-network-process} and @code{set-network-process-option}. |
1995 |
|
@end table |
1996 |
|
|
1997 |
|
@ignore |
1998 |
|
arch-tag: ba9da253-e65f-4e7f-b727-08fba0a1df7a |
1999 |
|
@end ignore |
2000 |
|
|