Erlang -- Ports and Port Drivers

User's Guide
PDF
Top

Erlang Reference Manual
User's Guide
Version 5.8.3

Expand All
Contract All

Chapters

- Introduction
  - Top of chapter
  - Purpose
  - Prerequisites
  - Document Conventions
  - Complete List of BIFs
  - Reserved Words
  - Character Set
- Data Types
  - Top of chapter
  - Terms
  - Number
  - Atom
  - Bit Strings and Binaries
  - Reference
  - Fun
  - Port Identifier
  - Pid
  - Tuple
  - List
  - String
  - Record
  - Boolean
  - Escape Sequences
  - Type Conversions
- Pattern Matching
  - Top of chapter
  - Pattern Matching
- Modules
  - Top of chapter
  - Module Syntax
  - Module Attributes
  - Comments
  - The module_info/0 and module_info/1 functions
- Functions
  - Top of chapter
  - Function Declaration Syntax
  - Function Evaluation
  - Tail recursion
  - Built-In Functions, BIFs
- Types and Function Specifications
  - Top of chapter
  - Introduction of Types
  - Types and their Syntax
  - Type declarations of user-defined types
  - Type information in record declarations
  - Specifications for functions
- Expressions
  - Top of chapter
  - Expression Evaluation
  - Terms
  - Variables
  - Patterns
  - Match
  - Function Calls
  - If
  - Case
  - Send
  - Receive
  - Term Comparisons
  - Arithmetic Expressions
  - Boolean Expressions
  - Short-Circuit Expressions
  - List Operations
  - Bit Syntax Expressions
  - Fun Expressions
  - Catch and Throw
  - Try
  - Parenthesized Expressions
  - Block Expressions
  - List Comprehensions
  - Bit String Comprehensions
  - Guard Sequences
  - Operator Precedence
- The Preprocessor
  - Top of chapter
  - File Inclusion
  - Defining and Using Macros
  - Predefined Macros
  - Macros Overloading
  - Flow Control in Macros
  - Stringifying Macro Arguments
- Records
  - Top of chapter
  - Defining Records
  - Creating Records
  - Accessing Record Fields
  - Updating Records
  - Records in Guards
  - Records in Patterns
  - Nested records
  - Internal Representation of Records
- Errors and Error Handling
  - Top of chapter
  - Terminology
  - Exceptions
  - Handling of Run-Time Errors in Erlang
  - Exit Reasons
- Processes
  - Top of chapter
  - Processes
  - Process Creation
  - Registered Processes
  - Process Termination
  - Message Sending
  - Links
  - Error Handling
  - Monitors
  - Process Dictionary
- Distributed Erlang
  - Top of chapter
  - Distributed Erlang System
  - Nodes
  - Node Connections
  - epmd
  - Hidden Nodes
  - C Nodes
  - Security
  - Distribution BIFs
  - Distribution Command Line Flags
  - Distribution Modules
- Compilation and Code Loading
  - Top of chapter
  - Compilation
  - Code Loading
  - Code Replacement
  - Running a function when a module is loaded
- Ports and Port Drivers
  - Top of chapter
  - Ports
  - Port Drivers
  - Port BIFs

# 14 Ports and Port Drivers

Examples of how to use ports and port drivers can be found in Interoperability Tutorial. The BIFs mentioned are as usual documented in erlang(3).

### 14.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 which creates a port is said to be the port owner, or the connected process of the port. All communication to and from the port should go via the port owner. If the port owner terminates, so will the port (and the external program, if it is written correctly).

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

### 14.2 Port Drivers

It is also 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.

Warning

An erroneous port driver will cause the entire Erlang runtime system to leak memory, hang or crash.

Port drivers are documented in erl_driver(4), driver_entry(1) and erl_ddll(3).

### 14.3 Port BIFs

To create a port:

open_port(PortName, PortSettings | Returns a port identifier Portas the result of opening a new Erlang port. Messages can be sent to and received from a port identifier, just like a pid. Port identifiers can also be linked to or registered under a name using link/1and register/2.

Table 14.1: Port Creation BIF.

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 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 should 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 messages from the port always go to the port owner).

Below, 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.

{Pid,{command,Data}} | Sends Datato the port.
{Pid,close} | Closes the port. Unless the port is already closed, the port replies with {Port,closed}when all buffers have been flushed and the port really closes.
{Pid,{connect,NewPid}} | Sets the port owner of Portto NewPid. Unless the port is already closed, the port replies with{Port,connected}to the old port owner. Note that the old port owner is still linked to the port, but the new port owner is not.

Table 14.2: Messages Sent To a Port.

{Port,{data,Data}} | Datais received from the external program.
{Port,closed} | Reply to Port ! {Pid,close}.
{Port,connected} | Reply to Port ! {Pid,{connect,NewPid}}
{'EXIT',Port,Reason} | If the port has terminated for some reason.

Table 14.3: Messages Received From a Port.

Instead of sending and receiving messages, there are also a number of BIFs that can be used. These can be called by any process, not only the port owner.

port_command(Port,Data) | Sends Datato the port.
port_close(Port) | Closes the port.
port_connect(Port,NewPid) | Sets the port owner of Portto NewPid. The old port owner Pidstays linked to the port and have to call unlink(Port)if this is not desired.
erlang:port_info(Port,Item) | Returns information as specified by Item.
erlang:ports() | Returns a list of all ports on the current node.

Table 14.4: Port BIFs.

There are some additional BIFs that only apply to port drivers: port_control/3 and erlang:port_call/3.