Erlang -- Socket Usage

Erlang Run-Time System Application (ERTS)

User's Guide

Version 10.5

- User's Guide
- Reference Manual
- Internal Documentation
- Release Notes
- PDF
- Top

- Expand All
- Contract All

### Chapters

- Introduction
  - Top of chapter
  - Scope
  - Prerequisites
- Communication in Erlang
  - Top of chapter
  - Passing of Signals
  - Synchronous Communication
  - Implementation
- Time and Time Correction in Erlang
  - Top of chapter
  - New Extended Time Functionality
  - Terminology
  - Introduction
  - Time Correction
  - Time Warp Safe Code
  - Time Warp Modes
  - New Time API
  - Support of Both New and Old OTP Releases
- Match Specifications in Erlang
  - Top of chapter
  - Grammar
  - Function Descriptions
  - Match target
  - Variables and Literals
  - Execution of the Match
  - Differences between Match Specifications in ETS and Tracing
  - Tracing Examples
  - ETS Examples
- How to Interpret the Erlang Crash Dumps
  - Top of chapter
  - General Information
  - Scheduler Information
  - Memory Information
  - Internal Table Information
  - Allocated Areas
  - Allocator
  - Process Information
  - Port Information
  - ETS Tables
  - Timers
  - Distribution Information
  - Loaded Module Information
  - Fun Information
  - Process Data
  - Atoms
  - Disclaimer
- How to Implement an Alternative Carrier for the Erlang Distribution
  - Top of chapter
  - Introduction
  - Distribution Module
  - The Driver
  - Putting It All Together
- How to Implement an Alternative Service Discovery for Erlang Distribution
  - Top of chapter
  - Introduction
  - Discovery module
- The Abstract Format
  - Top of chapter
  - Module Declarations and Forms
  - Atomic Literals
  - Patterns
  - Expressions
  - Clauses
  - Guards
  - Types
  - The Abstract Format after Preprocessing
- tty - A Command-Line Interface
  - Top of chapter
  - Normal Mode
  - Shell Break Mode
- How to Implement a Driver
  - Top of chapter
  - Introduction
  - Sample Driver
  - Compiling and Linking the Sample Driver
  - Calling a Driver as a Port in Erlang
  - Sample Asynchronous Driver
  - An Asynchronous Driver Using driver_async
- Inet Configuration
  - Top of chapter
  - Introduction
  - Configuration Data
  - User Configuration Example
- Socket Usage
  - Top of chapter
  - Introduction
  - Socket Options
- External Term Format
  - Top of chapter
  - Introduction
  - Distribution Header
  - ATOM_CACHE_REF
  - SMALL_INTEGER_EXT
  - INTEGER_EXT
  - FLOAT_EXT
  - PORT_EXT
  - NEW_PORT_EXT
  - PID_EXT
  - NEW_PID_EXT
  - SMALL_TUPLE_EXT
  - LARGE_TUPLE_EXT
  - MAP_EXT
  - NIL_EXT
  - STRING_EXT
  - LIST_EXT
  - BINARY_EXT
  - SMALL_BIG_EXT
  - LARGE_BIG_EXT
  - REFERENCE_EXT (deprecated)
  - NEW_REFERENCE_EXT
  - NEWER_REFERENCE_EXT
  - FUN_EXT
  - NEW_FUN_EXT
  - EXPORT_EXT
  - BIT_BINARY_EXT
  - NEW_FLOAT_EXT
  - ATOM_UTF8_EXT
  - SMALL_ATOM_UTF8_EXT
  - ATOM_EXT (deprecated)
  - SMALL_ATOM_EXT (deprecated)
- Distribution Protocol
  - Top of chapter
  - EPMD Protocol
  - Distribution Handshake
  - Protocol between Connected Nodes
  - New Ctrlmessages for distrvsn = 1 (Erlang/OTP R4)
  - New Ctrlmessages for distrvsn = 2
  - New Ctrlmessages for distrvsn = 3 (Erlang/OTP R5C)
  - New Ctrlmessages for distrvsn = 4 (Erlang/OTP R6)
  - New Ctrlmessages for Erlang/OTP 21
  - New Ctrlmessages for Erlang/OTP 22

# 12 Socket Usage

### 12.1 Introduction

The socket interface (module) is basically an "thin" layer on top of the OS socket interface. It is assumed that, unless you have special needs, gen_[tcp|udp|sctp] should be sufficent (when they become available).

Note that just because we have a documented and described option, it does not mean that the OS supports it. So its recommended that the user reads the platform specific documentation for the option used.

#### Asynchronous calls

Some functions allow for an asynchronous call (accept/2, connect/3, recv/3,4, recvfrom/3,4, recvmsg/2,3,5, send/3,4, sendmsg/3,4 and sendto/4,5). This is achieved by setting the Timeout argument to nowait. For instance, if calling the recv/3 function with Timeout set to nowait (i.e. recv(Sock, 0, nowait)) when there is actually nothing to read, it will return with {select, SelectInfo} (SelectInfo contains the SelectRef). When data eventually arrives a 'select message' will be sent to the caller:

  {'$socket', socket(), select, SelectRef}

The caller can then make another call to the recv function and now expect data.

The user must also be prepared to receive an abort message:

  {'$socket', socket(), abort, Info}

If the operation is aborted for whatever reason (e.g. if the socket is closed "by someone else"). The Info part contains the abort reason (in this case that the socket has been closed Info = {SelectRef, closed}).

Note that all other users are locked out until the 'current user' has called the function (recv in this case). So either immediately call the function or cancel.

The general form of the 'socket' message is:

  {'$socket', Sock :: socket(), Tag :: atom(), Info :: term()}

Where the format of Info is a function of Tag:

Tag | Info value type
select | select_ref()
abort | {select_ref(), Reason :: term()}

Table 12.1: socket message info value type

The select_ref() is the same as was received in the SelectInfo.

### 12.2 Socket Options

Options for level otp:

Option Name | Value Type | Set | Get | Other Requirements and comments
assoc_id | integer() | no | yes | type = seqpacket, protocol = sctp, is an association
debug | boolean() | yes | yes | none
iow | boolean() | yes | yes | none
controlling_process | pid() | yes | yes | none
rcvbuf | default | pos_integer() | {pos_integer(), pos_ineteger()} | yes | yes | 'default' only valid for set. The tuple form is only valid for type 'stream' and protocol 'tcp'.
rcvctrlbuf | default | pos_integer() | yes | yes | default only valid for set
sndctrlbuf | default | pos_integer() | yes | yes | default only valid for set
fd | integer() | no | yes | none

Table 12.2: option levels

Options for level socket:

Option Name | Value Type | Set | Get | Other Requirements and comments
acceptconn | boolean() | no | yes | none
bindtodevice | string() | yes | yes | Before Linux 3.8, this socket option could be set, but not get. Only works for some socket types (e.g. inet). If empty value is set, the binding is removed.
broadcast | boolean() | yes | yes | type = dgram
debug | integer() | yes | yes | may require admin capability
domain | domain() | no | yes | Not on FreeBSD (for instance)
dontroute | boolean() | yes | yes | none
keepalive | boolean() | yes | yes | none
linger | abort | linger() | yes | yes | none
oobinline | boolean() | yes | yes | none
peek_off | integer() | yes | yes | domain = local (unix)
priority | integer() | yes | yes | none
protocol | protocol() | no | yes | Not on (some) Darwin (for instance)
rcvbuf | non_neg_integer() | yes | yes | none
rcvlowat | non_neg_integer() | yes | yes | none
rcvtimeo | timeval() | yes | yes | none
reuseaddr | boolean() | yes | yes | none
reuseport | boolean() | yes | yes | domain = inet | inet6
sndbuf | non_neg_integer() | yes | yes | none
sndlowat | non_neg_integer() | yes | yes | not changeable on Linux
sndtimeo | timeval() | yes | yes | none
timestamp | boolean() | yes | yes | none
type | type() | no | yes | none

Table 12.3: socket options

Options for level ip:

Option Name | Value Type | Set | Get | Other Requirements and comments
add_membership | ip_mreq() | yes | no | none
add_source_membership | ip_mreq_source() | yes | no | none
block_source | ip_mreq_source() | yes | no | none
drop_membership | ip_mreq() | yes | no | none
drop_source_membership | ip_mreq_source() | yes | no | none
freebind | boolean() | yes | yes | none
hdrincl | boolean() | yes | yes | type = raw
minttl | integer() | yes | yes | type = raw
msfilter | null | ip_msfilter() | yes | no | none
mtu | integer() | no | yes | type = raw
mtu_discover | ip_pmtudisc() | yes | yes | none
multicast_all | boolean() | yes | yes | none
multicast_if | any | ip4_address() | yes | yes | none
multicast_loop | boolean() | yes | yes | none
multicast_ttl | uint8() | yes | yes | none
nodefrag | boolean() | yes | yes | type = raw
pktinfo | boolean() | yes | yes | type = dgram
recvdstaddr | boolean() | yes | yes | type = dgram
recverr | boolean() | yes | yes | none
recvif | boolean() | yes | yes | type = dgram | raw
recvopts | boolean() | yes | yes | type =/= stream
recvorigdstaddr | boolean() | yes | yes | none
recvttl | boolean() | yes | yes | type =/= stream
retopts | boolean() | yes | yes | type =/= stream
router_alert | integer() | yes | yes | type = raw
sendsrcaddr | boolean() | yes | yes | none
tos | ip_tos() | yes | yes | some high-priority levels may require superuser capability
transparent | boolean() | yes | yes | requires admin capability
ttl | integer() | yes | yes | none
unblock_source | ip_mreq_source() | yes | no | none

Table 12.4: ip options

Options for level ipv6:

Option Name | Value Type | Set | Get | Other Requirements and comments
addrform | inet | yes | no | allowed only for IPv6 sockets that are connected and bound to a v4-mapped-on-v6 address
add_membership | ipv6_mreq() | yes | no | none
authhdr | boolean() | yes | yes | type = dgram | raw, obsolete?
drop_membership | ipv6_mreq() | yes | no | none
dstopts | boolean() | yes | yes | type = dgram | raw, requires superuser privileges to update
flowinfo | boolean() | yes | yes | type = dgram | raw, requires superuser privileges to update
hoplimit | boolean() | yes | yes | type = dgram | raw, requires superuser privileges to update
hopopts | boolean() | yes | yes | type = dgram | raw, requires superuser privileges to update
mtu | boolean() | yes | yes | Get: Only after the socket has been connected
mtu_discover | ipv6_pmtudisc() | yes | yes | none
multicast_hops | default | uint8() | yes | yes | none
multicast_if | integer() | yes | yes | type = dgram | raw
multicast_loop | boolean() | yes | yes | none
recverr | boolean() | yes | yes | none
recvpktinfo | pktinfo | boolean() | yes | yes | type = dgram | raw
router_alert | integer() | yes | yes | type = raw
rthdr | boolean() | yes | yes | type = dgram | raw, requires superuser privileges to update
unicast_hops | default | uint8() | yes | yes | none
v6only | boolean() | yes | no | none

Table 12.5: ipv6 options

Options for level tcp:

Option Name | Value Type | Set | Get | Other Requirements and comments
congestion | string() | yes | yes | none
maxseg | integer() | yes | yes | none
nodelay | boolean() | yes | yes | none

Table 12.6: tcp options

Options for level udp:

Option Name | Value Type | Set | Get | Other Requirements and comments
cork | boolean() | yes | yes | none

Table 12.7: udp options

Options for level sctp:

Option Name | Value Type | Set | Get | Other Requirements and comments
associnfo | sctp_assocparams() | yes | yes | none
autoclose | non_neg_integer() | yes | yes | none
disable_fragments | boolean() | yes | yes | none
events | sctp_event_subscribe() | yes | no | none
initmsg | sctp_initmsg() | yes | yes | none
maxseg | non_neg_integer() | yes | yes | none
nodelay | boolean() | yes | yes | none
rtoinfo | sctp_rtoinfo() | yes | yes | none

Table 12.8: sctp options