Ports

Elixir Ports

Ports are Elixir's mechanism for communicating with external OS programs via stdin/stdout. A Port is not a network port — it is a process-like entity that manages an external OS program, forwarding messages as bytes and delivering responses back to the owning Elixir process.

Port Fundamentals

Open a port with Port.open/2. The most common name forms are {:spawn, command} and {:spawn_executable, path}.

# Spawn by shell command string (uses shell, PATH lookups apply)
port = Port.open({:spawn, "cat"}, [:binary])

# Spawn executable directly (no shell, preferred for security)
port = Port.open({:spawn_executable, "/usr/bin/python3"}, [
  :binary,
  args: ["-u", "my_script.py"]
])

Send data to the port and receive from it:

# Send bytes to the external process's stdin
Port.command(port, "hello\n")

# Receive response — messages arrive in the process mailbox
receive do
  {^port, {:data, data}} ->
    IO.puts("Got: #{data}")
end

Close the port explicitly or let it close when the owner process exits:

Port.close(port)
# The port will reply {port, :closed} after the external process exits

Port Options Reference

Note on {:env, env_list}: This option extends the environment the BEAM already holds — the spawned process inherits every existing variable, and env_list adds to or overrides individual entries. There is no replace-all option. To withhold an inherited variable, pair its name with false (an empty charlist — ~c"" or [] — also unsets; Elixir's "" is a binary and raises). See the Security section.

Communication Patterns

Stream Mode (default)

Bytes are delivered as they arrive with no framing. Use :binary to get binaries instead of charlists.

port = Port.open({:spawn_executable, "/bin/cat"}, [:binary, :stream])

Port.command(port, "some data")

receive do
  {^port, {:data, chunk}} -> IO.inspect(chunk)
end

Packet Mode

Use {:packet, N} for message framing. The external program must also implement the same N-byte big-endian length prefix.

# Elixir side
port = Port.open({:spawn_executable, "/usr/local/bin/my_worker"}, [
  :binary,
  {:packet, 4}
])

Port.command(port, encode_message("hello"))

receive do
  {^port, {:data, response}} -> decode_message(response)
end

The external program reads a 4-byte big-endian integer as the message length, then reads that many bytes. It writes responses with the same framing.

Line Mode

port = Port.open({:spawn_executable, "/usr/bin/python3"}, [
  :binary,
  {:line, 4096},
  args: ["script.py"]
])

receive do
  {^port, {:data, {:eol, line}}} ->
    IO.puts("Complete line: #{line}")

  {^port, {:data, {:noeol, partial}}} ->
    IO.puts("Partial line (too long): #{partial}")
end

Receiving Exit Status

port = Port.open({:spawn, "false"}, [:binary, :exit_status])

receive do
  {^port, {:exit_status, code}} ->
    IO.puts("Exited with code #{code}")
end

GenServer Port Wrapper

Wrapping a port in a GenServer is the standard OTP pattern for managing external processes. The GenServer owns the port, handles messages, and exposes a clean API.

defmodule MyApp.ExternalWorker do
  use GenServer

  @timeout 5_000

  # Client API

  def start_link(opts \\ []) do
    GenServer.start_link(__MODULE__, opts, name: __MODULE__)
  end

  def call(payload) do
    GenServer.call(__MODULE__, {:call, payload}, @timeout)
  end

  # Server Callbacks

  @impl true
  def init(_opts) do
    executable = System.find_executable("my_worker") ||
      raise "my_worker not found in PATH"

    port =
      Port.open({:spawn_executable, executable}, [
        :binary,
        {:packet, 4},
        :exit_status
      ])

    ref = Port.monitor(port)

    {:ok, %{port: port, ref: ref, caller: nil}}
  end

  @impl true
  def handle_call({:call, payload}, from, %{port: port} = state) do
    encoded = :erlang.term_to_binary(payload)
    Port.command(port, encoded)
    {:noreply, %{state | caller: from}}
  end

  @impl true
  def handle_info({port, {:data, data}}, %{port: port, caller: caller} = state) do
    response = :erlang.binary_to_term(data)
    GenServer.reply(caller, {:ok, response})
    {:noreply, %{state | caller: nil}}
  end

  @impl true
  def handle_info({port, {:exit_status, code}}, %{port: port} = state) do
    {:stop, {:port_exited, code}, state}
  end

  @impl true
  def handle_info({:DOWN, ref, :port, _port, reason}, %{ref: ref} = state) do
    {:stop, {:port_down, reason}, state}
  end

  @impl true
  def terminate(_reason, %{port: port}) do
    if Port.info(port) != nil do
      Port.close(port)
    end

    :ok
  end
end

Key points in this pattern:

• Store the port in GenServer state
• Monitor the port with Port.monitor/1 to receive :DOWN messages
• Use {:packet, N} for reliable message framing
• Store the calling from pid when waiting for a response
• Reply via GenServer.reply/2 from handle_info when data arrives
• Always check Port.info(port) before closing in terminate/2

Supervision

Add the GenServer to a supervision tree:

children = [
  {MyApp.ExternalWorker, []},
  # ...
]

Supervisor.start_link(children, strategy: :one_for_one)

When the external process crashes, the port sends an exit message, the GenServer stops, and the supervisor restarts it.

Port Lifecycle and Error Handling

Port Monitor

Use Port.monitor/1 (available since Elixir v1.6) to receive a {:DOWN, ref, :port, object, reason} message when a port closes:

port = Port.open({:spawn, "my_cmd"}, [:binary])
ref = Port.monitor(port)

receive do
  {:DOWN, ^ref, :port, _port, reason} ->
    IO.puts("Port closed: #{inspect(reason)}")
end

Checking if a Port is Alive

case Port.info(port) do
  nil -> :port_closed
  info -> {:alive, info}
end

Port Ownership Transfer

Transfer ownership with Port.connect/2. The old owner receives {port, :connected}:

Port.connect(port, new_owner_pid)

Crash Semantics

• When the port owner process terminates, the port closes automatically, and the external program receives SIGTERM.
• When the external program exits, the port sends {port, {:exit_status, code}} (if :exit_status was set) and closes.
• Ports are linked to their owning process by default.

Decision Guide: Port vs NIF vs C Node vs System.cmd

Use Port when: the external program runs continuously, streams data, or must be isolated from VM crashes.

Use System.cmd/3 when: running a command once, synchronously, and the result is needed before proceeding. Returns {output, exit_status}.

Use NIF when: calling a C function with sub-millisecond latency requirements. Use dirty NIFs (ERL_NIF_DIRTY_JOB_CPU_BOUND or ERL_NIF_DIRTY_JOB_IO_BOUND) for work exceeding ~1ms to avoid blocking schedulers.

Use C Node when: integrating with an existing large C codebase that uses erl_interface/ei.

System.cmd Example

{output, 0} = System.cmd("ls", ["-la", "/tmp"],
  cd: "/",
  stderr_to_stdout: true
)

System.cmd/3 blocks the calling process until the command completes. It does not stream data.

Security Considerations

Prefer :spawn_executable Over :spawn

{:spawn, command} passes the command through a shell, which enables shell injection:

# UNSAFE — shell injection risk
user_input = "file.txt; rm -rf /"
Port.open({:spawn, "cat #{user_input}"}, [:binary])

# SAFE — no shell, arguments passed directly
Port.open({:spawn_executable, "/bin/cat"}, [
  :binary,
  args: [user_input]
])

Always use {:spawn_executable, path} with args: when any part of the command comes from user input or external data.

Validate Executable Paths

# Find and validate the executable at startup, not per-request
executable = System.find_executable("my_tool") ||
  raise "my_tool executable not found in PATH"

Store the validated path in process state so it is resolved once at startup.

Environment Variable Inheritance

{:env, env_list} extends the spawned process's environment — it does not replace it. OTP documents this directly: "The environment of the started process is extended using the environment specifications in Env." The child therefore inherits every variable the BEAM holds, including any secrets in it, whether or not they appear in env_list.

The security consequence is the part that is easy to get backwards: passing a short env_list does not sandbox the child. There is no replace-all option, so a variable is only withheld if you name it and pair it with false. The OTP 27 and 28 docs also treat an empty Erlang string as unset, "just as if os:unsetenv/1 had been called" — so an empty value cannot be passed through to a child at all. From Elixir that means ~c"" or []; the Elixir literal "" is a binary and raises ArgumentError.

Do not build a "clean" environment by enumerating System.get_env/0 and passing it back in — the child already has those variables, so it withholds nothing, and it copies every secret value into a BEAM term where it can surface in crash dumps, :sys.get_state/1, exception messages, and any stray IO.inspect/1.

See references/erlang-ports.md for a deny example and a minimal allowlist helper.

Note: Name and Val must be Erlang strings (charlists). Binaries raise ArgumentError — unlike :cd, :args, and :arg0, whose typespecs explicitly allow binary(), the :env typespec does not. Convert with String.to_charlist/1. System.cmd/3 differs: it accepts binaries and takes nil (not false) as its unset marker, converting both before reaching the port.

Windows Batch File Injection

On Windows, spawning .bat or .cmd files via :spawn passes through cmd.exe, which has its own injection vectors. Use explicit executable paths and validate all arguments.

Testing Port-Based Code

Mock the Port Interaction

Test the GenServer wrapper by sending fake port messages directly:

defmodule MyApp.ExternalWorkerTest do
  use ExUnit.Case, async: true

  test "call sends to port and returns response" do
    {:ok, pid} = MyApp.ExternalWorker.start_link([])

    # Retrieve the port from state for inspection
    %{port: port} = :sys.get_state(pid)

    # Simulate the port sending a response
    fake_response = :erlang.term_to_binary({:ok, "result"})
    send(pid, {port, {:data, fake_response}})

    # Verify state updated (caller cleared)
    %{caller: nil} = :sys.get_state(pid)
  end

  test "handles port exit" do
    {:ok, pid} = MyApp.ExternalWorker.start_link([])
    ref = Process.monitor(pid)

    %{port: port} = :sys.get_state(pid)
    send(pid, {port, {:exit_status, 1}})

    assert_receive {:DOWN, ^ref, :process, ^pid, {:port_exited, 1}}
  end
end

Integration Test with a Real Port

For integration tests, use a real external program:

test "communicates with cat process" do
  port = Port.open({:spawn_executable, "/bin/cat"}, [:binary, :stream])

  Port.command(port, "hello")

  assert_receive {^port, {:data, "hello"}}, 1_000

  Port.close(port)
end

Use assert_receive with a timeout rather than bare receive in tests to avoid hanging on failure.

Common Pitfalls

Orphan processes on VM crash: If the BEAM VM is killed with SIGKILL (not SIGTERM), external port processes may not receive SIGTERM and can persist. Design external programs to detect closed stdin and exit.

Charlists vs binaries: Without :binary, data arrives as charlists (lists of integers). Always use :binary unless working with legacy code that expects charlists.

Assuming {:env, list} sandboxes the child: it extends the environment rather than replacing it, so the spawned process inherits everything the BEAM holds no matter how short the list is. Withholding a variable requires naming it explicitly with false. See the Security section.

Blocking the GenServer: A GenServer that sends a command and awaits a reply synchronously in handle_call will block the entire GenServer during the wait. The pattern above avoids this by storing the from and replying in handle_info.

Not monitoring the port: Without Port.monitor/1 or :exit_status, a silently exiting external process leaves the GenServer in a state where it will never receive a reply.

Packet mode mismatch: If the Elixir side uses {:packet, 4} but the external program uses a different framing, all messages will be corrupted or silently dropped. Verify the framing protocol matches on both sides.

References

See references/erlang-ports.md for:

• Complete open_port/2 Erlang option reference
• Binary protocol wire format and byte calculations
• erl_interface / ei C library overview
• Port driver architecture (linked-in drivers)
• ERTS scheduling and backpressure options

Anti-Fabrication

Verify all port behavior claims through tool execution. Use Port.info/1 to confirm port state before asserting properties. Run actual port commands and check exit statuses rather than assuming behavior. Reference core:anti-fabrication for the complete validation methodology.

Key Principles

• Use :spawn_executable: Avoid shell injection by passing arguments directly
• Wrap ports in GenServer: Follow OTP patterns for lifecycle management and supervision
• Monitor the port: Use Port.monitor/1 to detect unexpected port closure
• Use {:packet, N} for framing: Stream mode requires external framing logic
• Design for orphan processes: External programs should detect stdin closure and exit
• Test with assert_receive: Avoid bare receive in tests to prevent hangs
• Prefer Port over NIF for isolation: NIF crashes bring down the entire VM