Next: , Previous: Transaction Queues, Up: Processes

37.13 Network Connections

Emacs Lisp programs can open stream (TCP) and datagram (UDP) network connections to other processes on the same machine or other machines. A network connection is handled by Lisp much like a subprocess, and is represented by a process object. However, the process you are communicating with is not a child of the Emacs process, so it has no process ID, and you can't kill it or send it signals. All you can do is send and receive data. delete-process closes the connection, but does not kill the program at the other end; that program must decide what to do about closure of the connection.

Lisp programs can listen for connections by creating network servers. A network server is also represented by a kind of process object, but unlike a network connection, the network server never transfers data itself. When it receives a connection request, it creates a new network connection to represent the connection just made. (The network connection inherits certain information, including the process plist, from the server.) The network server then goes back to listening for more connection requests.

Network connections and servers are created by calling make-network-process with an argument list consisting of keyword/argument pairs, for example :server t to create a server process, or :type 'datagram to create a datagram connection. See Low-Level Network, for details. You can also use the open-network-stream function described below.

You can distinguish process objects representing network connections and servers from those representing subprocesses with the process-status function. The possible status values for network connections are open, closed, connect, and failed. For a network server, the status is always listen. None of those values is possible for a real subprocess. See Process Information.

You can stop and resume operation of a network process by calling stop-process and continue-process. For a server process, being stopped means not accepting new connections. (Up to 5 connection requests will be queued for when you resume the server; you can increase this limit, unless it is imposed by the operating system.) For a network stream connection, being stopped means not processing input (any arriving input waits until you resume the connection). For a datagram connection, some number of packets may be queued but input may be lost. You can use the function process-command to determine whether a network connection or server is stopped; a non-nil value means yes.

— Function: open-network-stream name buffer-or-name host service

This function opens a TCP connection, and returns a process object that represents the connection.

The name argument specifies the name for the process object. It is modified as necessary to make it unique.

The 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 buffer-or-name is nil, it means that the connection is not associated with any buffer.

The arguments host and service specify where to connect to; host is the host name (a string), and service is the name of a defined network service (a string) or a port number (an integer).

— Function: process-contact process &optional key

This function returns information about how a network process was set up. For a connection, when key is nil, it returns (hostname service) which specifies what you connected to.

If key is t, the value is the complete status information for the connection or server; that is, the list of keywords and values specified in make-network-process, except that some of the values represent the current status instead of what you specified:

:buffer
The associated value is the process buffer.
:filter
The associated value is the process filter function.
:sentinel
The associated value is the process sentinel function.
:remote
In a connection, the address in internal format of the remote peer.
:local
The local address, in internal format.
:service
In a server, if you specified t for service, this value is the actual port number.

:local and :remote are included even if they were not specified explicitly in make-network-process.

If key is a keyword, the function returns the value corresponding to that keyword.

For an ordinary child process, this function always returns t.