15 Ports and Port Drivers

Examples of how to use ports and port drivers are provided in Interoperability Tutorial. For information about the BIFs mentioned, see the erlang(3) manual page in ERTS.

15.1 Ports

Ports provide the basic mechanism for communication with the external world, from Erlang's point of view. They provide a byte-oriented interface to an external program. When a port has been created, Erlang can communicate with it by sending and receiving lists of bytes, including binaries.

The Erlang process creating a port is said to be the port owner, or the connected process of the port. All communication to and from the port must go through the port owner. If the port owner terminates, so does the port (and the external program, if it is written correctly).

The external program resides in another OS process. By default, it reads from standard input (file descriptor 0) and writes to standard output (file descriptor 1). The external program is to terminate when the port is closed.

15.2 Port Drivers

It is possible to write a driver in C according to certain principles and dynamically link it to the Erlang runtime system. The linked-in driver looks like a port from the Erlang programmer's point of view and is called a port driver.

For information about port drivers, see the erl_driver(4) manual page in ERTS, driver_entry(1) manual page in ERTS, and erl_ddll(3) manual page in Kernel.

15.3 Port BIFs

To create a port:

PortName is usually a tuple {spawn,Command}, where the string Command is the name of the external program. The external program runs outside the Erlang workspace, unless a port driver with the name Command is found. If Command is found, that driver is started.

PortSettings is a list of settings (options) for the port. The list typically contains at least a tuple {packet,N}, which specifies that data sent between the port and the external program are preceded by an N-byte length indicator. Valid values for N are 1, 2, or 4. If binaries are to be used instead of lists of bytes, the option binary must be included.

The port owner Pid can communicate with the port Port by sending and receiving messages. (In fact, any process can send the messages to the port, but the port owner must be identified in the message).

As of Erlang/OTP R16, messages sent to ports are delivered truly asynchronously. The underlying implementation previously delivered messages to ports synchronously. Message passing has however always been documented as an asynchronous operation. Hence, this is not to be an issue for an Erlang program communicating with ports, unless false assumptions about ports have been made.

In the following tables of examples, Data must be an I/O list. An I/O list is a binary or a (possibly deep) list of binaries or integers in the range 0..255:

Instead of sending and receiving messages, there are also a number of BIFs that can be used:

Some additional BIFs that apply to port drivers: port_control/3 and erlang:port_call/3.