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 and datagram network connections to |
Emacs Lisp programs can open stream (TCP) and datagram (UDP) network |
1479 |
other processes on the same machine or other machines. A network |
connections to other processes on the same machine or other machines. |
1480 |
connection is handled by Lisp much like a subprocess, and is |
A network connection is handled by Lisp much like a subprocess, and is |
1481 |
represented by a process object. However, the process you are |
represented by a process object. However, the process you are |
1482 |
communicating with is not a child of the Emacs process, so it has no |
communicating with is not a child of the Emacs process, so it has no |
1483 |
process @sc{id}, and you can't kill it or send it signals. All you |
process @sc{id}, and you can't kill it or send it signals. All you |
1505 |
You can stop and resume operation of a network processes by calling |
You can stop and resume operation of a network processes by calling |
1506 |
@code{stop-process} and @code{continue-process}. For a server |
@code{stop-process} and @code{continue-process}. For a server |
1507 |
process, being stopped means not accepting new connections. (Up to 5 |
process, being stopped means not accepting new connections. (Up to 5 |
1508 |
connection requests will be queued for when you resume the server; |
connection requests will be queued for when you resume the server; you |
1509 |
this limit is imposed by the operating system.) For a network |
can increase this limit, unless it is imposed by the operating |
1510 |
connection, being stopped means not processing input (any arriving |
systems.) For a network connection, being stopped means not |
1511 |
input waits until you resume the connection). You can use the |
processing input (any arriving input waits until you resume the |
1512 |
function @code{process-command} to determine whether a network |
connection). You can use the function @code{process-command} to |
1513 |
connection or server is stopped; a non-@code{nil} value means yes. |
determine whether a network connection or server is stopped; a |
1514 |
|
non-@code{nil} value means yes. |
1515 |
|
|
1516 |
@defun open-network-stream name buffer-or-name host service |
@defun open-network-stream name buffer-or-name host service |
1517 |
This function opens a TCP connection, and returns a process object |
This function opens a TCP connection, and returns a process object |
1567 |
@item :filter |
@item :filter |
1568 |
The associated value is the process filter function. |
The associated value is the process filter function. |
1569 |
@item :sentinel |
@item :sentinel |
1570 |
The associated value is the process filter function. |
The associated value is the process sentinel function. |
1571 |
@item :remote |
@item :remote |
1572 |
In a connection, this is the address in internal format of the remote peer. |
In a connection, this is the address in internal format of the remote peer. |
1573 |
@item :local |
@item :local |
1601 |
server process' @var{name} with a client identification string. The |
server process' @var{name} with a client identification string. The |
1602 |
client identification string for an IPv4 connection looks like |
client identification string for an IPv4 connection looks like |
1603 |
@samp{<@var{a}.@var{b}.@var{c}.@var{d}:@var{p}>}. Otherwise, it is a |
@samp{<@var{a}.@var{b}.@var{c}.@var{d}:@var{p}>}. Otherwise, it is a |
1604 |
unique number in brackets, as in @samp{<@var{nnn>}}. The number |
unique number in brackets, as in @samp{<@var{nnn}>}. The number |
1605 |
is unique for each connection in the Emacs session. |
is unique for each connection in the Emacs session. |
1606 |
|
|
1607 |
@item |
@item |
1608 |
If the server's filter is non-@code{nil}, the connection process does |
If the server's filter is non-@code{nil}, the connection process does |
1609 |
not get a separate process buffer; otherwise, Emacs creates a bew |
not get a separate process buffer; otherwise, Emacs creates a new |
1610 |
buffer for the purpose. The buffer name is the server's buffer name |
buffer for the purpose. The buffer name is the server's buffer name |
1611 |
or process name, concatenated with the client identification string. |
or process name, concatenated with the client identification string. |
1612 |
|
|
1693 |
process object that represents it. The arguments @var{args} are a |
process object that represents it. The arguments @var{args} are a |
1694 |
list of keyword/argument pairs. Omitting a keyword is always |
list of keyword/argument pairs. Omitting a keyword is always |
1695 |
equivalent to specifying it with value @code{nil}, except for |
equivalent to specifying it with value @code{nil}, except for |
1696 |
@code{:coding} and @code{:filter-multibyte}. Here are the meaningful |
@code{:coding}, @code{:filter-multibyte}, and @code{:reuseaddr}. Here |
1697 |
keywords: |
are the meaningful keywords: |
1698 |
|
|
1699 |
@table @asis |
@table @asis |
1700 |
@item :name name |
@item :name name |
1708 |
|
|
1709 |
@item :server @var{server-flag} |
@item :server @var{server-flag} |
1710 |
If @var{server-flag} is non-@code{nil}, create a server. Otherwise, |
If @var{server-flag} is non-@code{nil}, create a server. Otherwise, |
1711 |
create a connection. |
create a connection. For a stream type server, @var{server-flag} may |
1712 |
|
be an integer which then specifies the length of the queue of pending |
1713 |
|
connections to the server. The default queue length is 5. |
1714 |
|
|
1715 |
@item :host @var{host} |
@item :host @var{host} |
1716 |
Specify the host to connect to. @var{host} should be a host name or |
Specify the host to connect to. @var{host} should be a host name or |
1789 |
@var{encoding})} for @var{coding}. |
@var{encoding})} for @var{coding}. |
1790 |
|
|
1791 |
If you don't specify this keyword at all, the default |
If you don't specify this keyword at all, the default |
1792 |
is to determine the coding systemx from the data. |
is to determine the coding systems from the data. |
|
|
|
|
@item :options @var{options} |
|
|
Set the specified options for the network process. See |
|
|
@code{set-network-process-options} for details. |
|
1793 |
|
|
1794 |
@item :noquery @var{query-flag} |
@item :noquery @var{query-flag} |
1795 |
Initialize the process query flag to @var{query-flag}. |
Initialize the process query flag to @var{query-flag}. @xref{Query Before Exit}. |
1796 |
|
|
1797 |
@item :filter @var{filter} |
@item :filter @var{filter} |
1798 |
Initialize the process filter to @var{filter}. |
Initialize the process filter to @var{filter}. |
1819 |
Initialize the process plist to @var{plist}. |
Initialize the process plist to @var{plist}. |
1820 |
@end table |
@end table |
1821 |
|
|
1822 |
|
The following network options can be specified for the network |
1823 |
|
process. Except for @code{:reuseaddr}, you can set or modify these |
1824 |
|
options later using @code{set-network-process-option}. |
1825 |
|
|
1826 |
|
For a server process, the options specified with |
1827 |
|
@code{make-network-process} are not inherited by the client |
1828 |
|
connections, so you will need to set the necessary options for each |
1829 |
|
child connection as they are created. |
1830 |
|
|
1831 |
|
@table asis |
1832 |
|
@item :bindtodevice @var{device-name} |
1833 |
|
If @var{device-name} is a non-empty string identifying a network |
1834 |
|
interface name (see @code{network-interface-list}), only handle |
1835 |
|
packets received on that interface. If @var{device-name} is nil (the |
1836 |
|
default), handle packets received on any interface. |
1837 |
|
|
1838 |
|
Using this option may require special privileges on some systems. |
1839 |
|
|
1840 |
|
@item :broadcast @var{broadcast-flag} |
1841 |
|
If @var{broadcast-flag} is non-@code{nil} for a datagram process, the |
1842 |
|
process will receive datagram packet sent to a broadcast address, and |
1843 |
|
be able to send packets to a broadcast address. Ignored for a stream |
1844 |
|
connection. |
1845 |
|
|
1846 |
|
@item :dontroute @var{dontroute-flag} |
1847 |
|
If @var{dontroute-flag} is non-@code{nil}, the process can only send |
1848 |
|
to hosts on the same network as the local host. |
1849 |
|
|
1850 |
|
@item :keepalive @var{keepalive-flag} |
1851 |
|
If @var{keepalive-flag} is non-@code{nil} for a stream connection, |
1852 |
|
enable exchange of low-level keep-alive messa |
1853 |
|
|
1854 |
|
@item :linger @var{linger-arg} |
1855 |
|
If @var{linger-arg} is non-@code{nil}, wait for successful |
1856 |
|
transmission of all queued packets on the connection before it is |
1857 |
|
deleted (see @code{delete-process}). If @var{linger-arg} is an |
1858 |
|
integer, it specifies the maximum time in seconds to wait for queued |
1859 |
|
packets to be sent before closing the connection. Default is |
1860 |
|
@code{nil} which means to discard unsent queued packets when the |
1861 |
|
process is deleted. |
1862 |
|
|
1863 |
|
@item :oobinline @var{oobinline-flag} |
1864 |
|
If @var{oobinline-flag} is non-@code{nil} for a stream connection, |
1865 |
|
receive out-of-band data in the normal data stream. Otherwise, ignore |
1866 |
|
out-of-band data. |
1867 |
|
|
1868 |
|
@item :priority @var{priority} |
1869 |
|
Set the priority for packets sent on this connection to the integer |
1870 |
|
@var{priority}. The interpretation of this number is protocol |
1871 |
|
specific, such as setting the TOS (type of service) field on IP |
1872 |
|
packets sent on this connection. It may also have system dependent |
1873 |
|
effects, such as selecting a specific output queue on the network |
1874 |
|
interface. |
1875 |
|
|
1876 |
|
@item :reuseaddr @var{reuseaddr-flag} |
1877 |
|
If @var{reuseaddr-flag} is non-@code{nil} (the default) for a stream |
1878 |
|
server process, allow this server to reuse a specific port number (see |
1879 |
|
@code{:service}) unless another process on this host is already |
1880 |
|
listening on that port. If @var{reuseaddr-flag} is @code{nil}, there |
1881 |
|
may be a period of time after the last use of that port (by any |
1882 |
|
process on the host), where it is not possible to make a new server on |
1883 |
|
that port. |
1884 |
|
|
1885 |
|
@end table |
1886 |
|
|
1887 |
The original argument list, modified with the actual connection |
The original argument list, modified with the actual connection |
1888 |
information, is available via the `process-contact' function. |
information, is available via the `process-contact' function. |
1889 |
@end defun |
@end defun |
1890 |
|
|
1891 |
|
@defun set-network-process-option process option value |
1892 |
|
This function sets or modifies a network option for network process |
1893 |
|
@var{process}. See @code{make-network-process} for details of options |
1894 |
|
@var{option} and their corresponding values @var{value}. |
1895 |
|
|
1896 |
|
The current setting of an option is available via the |
1897 |
|
`process-contact' function. |
1898 |
|
@end defun |
1899 |
|
|
1900 |
@defun network-interface-list |
@defun network-interface-list |
1901 |
This function returns a list describing the network interfaces |
This function returns a list describing the network interfaces |
1902 |
of the machine you are using. The value is an alist whose |
of the machine you are using. The value is an alist whose |
1943 |
@end example |
@end example |
1944 |
|
|
1945 |
@noindent |
@noindent |
1946 |
The result is @code{t} if it works to specify @var{keyword} with value |
The result of the first form is @code{t} if it works to specify |
1947 |
@var{value} in @code{make-network-process}. Here are some of the |
@var{keyword} with value @var{value} in @code{make-network-process}. |
1948 |
@var{keyword}---@var{value} pairs you can test in this way. |
The result of the second form is @code{t} if @var{keyword} is |
1949 |
|
supported by @code{make-network-process}. Here are some of the |
1950 |
|
@var{keyword}---@var{value} pairs you can test in |
1951 |
|
this way. |
1952 |
|
|
1953 |
@table @code |
@table @code |
1954 |
@item (:nowait t) |
@item (:nowait t) |
1959 |
Non-@code{nil} if local (aka ``UNIX domain'') sockets are supported. |
Non-@code{nil} if local (aka ``UNIX domain'') sockets are supported. |
1960 |
@item (:service t) |
@item (:service t) |
1961 |
Non-@code{nil} if the system can select the port for a server. |
Non-@code{nil} if the system can select the port for a server. |
1962 |
@item (:options bindtodevice) |
@end table |
1963 |
@itemx (:options broadcast) |
|
1964 |
@itemx (:options dontroute) |
To test for the availability of a given network option, use |
1965 |
@itemx (:options keepalive) |
@code{featurep} like this: |
1966 |
@itemx (:options linger) |
|
1967 |
@itemx (:options oobinline) |
@example |
1968 |
@itemx (:options priority) |
(featurep 'make-network-process '@var{keyword}) |
1969 |
@itemx (:options reuseaddr) |
@end example |
1970 |
That particular socket option is supported. |
|
1971 |
|
Here are some of the option @var{keyword}s you can test in |
1972 |
|
this way. |
1973 |
|
|
1974 |
|
@table @code |
1975 |
|
@item :bindtodevice |
1976 |
|
@itemx :broadcast |
1977 |
|
@itemx :dontroute |
1978 |
|
@itemx :keepalive |
1979 |
|
@itemx :linger |
1980 |
|
@itemx :oobinline |
1981 |
|
@itemx :priority |
1982 |
|
@itemx :reuseaddr |
1983 |
|
That particular network option is supported by |
1984 |
|
@code{make-network-process} and @code{set-network-process-option}. |
1985 |
@end table |
@end table |
1986 |
|
|
1987 |
@ignore |
@ignore |