fd

README

fd

Package fd provides a simple API to pass file descriptors between different OS processes.

It can be useful if you want to inherit network connections from another process without closing them.

Example scenario:

• Running server receives a "let's upgrade" message
• Server opens a Unix domain socket for the "upgrade"
• Server starts a new copy of itself and passes Unix domain socket name
• New copy starts reading data from the socket
• Server sends its state over the socket, also sending the number of network connections to inherit, then it sends those connections using fd.Put()
• New server copy reads the state and inherits connections using fd.Get(), checks that everything is OK and writes an "OK" message to the socket
• Server receives "OK" message and kills itself

Documentation

fd on godoc.org

Documentation

Overview

Package fd provides a simple API to pass file descriptors between different OS processes.

It can be useful if you want to inherit network connections from another process without closing them.

Example scenario:

1. Running server receives a "let's upgrade" message
2. Server opens a Unix domain socket for the "upgrade"
3. Server starts a new copy of itself and passes Unix domain socket name
4. New copy starts reading for the socket
5. Server sends its state over the socket, also sending the number of network connections to inherit, then it sends those connections using fd.Put()
6. New copy reads the state and inherits connections using fd.Get(), checks that everything is OK and sends the "OK" message to the socket
7. Server receives "OK" message and kills itself

Index

• func Get(via *net.UnixConn, num int, filenames []string) ([]*os.File, error)
• func Put(via *net.UnixConn, files ...*os.File) error

Functions

func Get

func Get(via *net.UnixConn, num int, filenames []string) ([]*os.File, error)

Get receives file descriptors from a Unix domain socket.

Num specifies the expected number of file descriptors in one message. Internal files' names to be assigned are specified via optional filenames argument.

You need to close all files in the returned slice. The slice can be non-empty even if this function returns an error.

Use net.FileConn() if you're receiving a network connection.

func Put

func Put(via *net.UnixConn, files ...*os.File) error

Put sends file descriptors to Unix domain socket.

Please note that the number of descriptors in one message is limited and is rather small. Use conn.File() to get a file if you want to put a network connection.