Module Eio_net_unix.LocalSource

Unix-domain stream sockets.

Unix-domain stream sockets.

A socket is reached through a capability: connect and listen through the directory the Eio.Path.t they are handed is part of, whose descriptor resolves the socket's name, so a path of any length works and a confined directory confines it. No function here opens a file by a name of its own, changes the working directory of the process or its umask.

Sourceval max_path_length : int

max_path_length is the longest path, in bytes, a Unix-domain socket address holds: the size of sun_path less its terminating NUL, 103 on macOS and 107 on Linux. Eio.Net.connect ~sw net (`Unix path) refuses a longer path with ENAMETOOLONG; connect and listen reach one through its directory.

Sourceval connect : sw:Eio.Switch.t -> net:[> [ `Generic | `Unix ] Eio.Net.ty ] Eio.Resource.t -> _ Eio.Path.t -> [ `Unix_fd | Eio_unix.Net.stream_socket_ty ] Eio.Resource.t

connect ~sw ~net path connects to the Unix-domain stream socket at path, whatever its length. The directory that holds it is opened through path's own capability, which refuses a path that leaves a confined directory as Eio.Path.open_in does, and the socket is reached by its base name from that directory, as Git's unix-socket.c reaches it by changing into it: on macOS that directory is made the working directory of the connecting thread alone (pthread_fchdir_np), on FreeBSD the connection is made with connectat(2), and on Linux through the short link /proc/self/fd/<dir>/<name>. net is the host's network, whose authority a socket of the host needs: an in-memory network does not have the type.

A base name that is a symbolic link is refused with Eio.Fs.Symlink, as Eio.Path.open_in ~follow:false refuses one, since its target is not under the directory's authority. It is checked before the connect, which follows a link, so one who can write the directory can swap a link in between and have this process connect, with its own credentials, to a socket outside the directory. macOS gives no descriptor of a socket's file to connect through, and the window is left open on every system: connect is for a directory no untrusted user writes. The base name must fit an address: max_path_length bytes on macOS and FreeBSD, and on Linux max_path_length less the length of the /proc/self/fd/<dir>/ prefix; a longer one is refused with ENAMETOOLONG. On a Linux system with no /proc mounted, the link does not resolve and the connect fails as a missing socket does, with Eio.Fs.Not_found. Other systems refuse with ENOSYS. A failure is the Eio.Io error Eio.Net.connect raises: a missing socket or directory is Eio.Fs.Not_found, a socket nobody listens on Eio.Net.Connection_failure (Refused _). The connection keeps the Unix platform's type, so that it passes descriptors (Eio_unix.Net.send_msg).

While the listener's backlog is full, a connect on Linux waits for room, trying again after a pause of at most 0.1 seconds, and a cancellation, such as one from Eio.Time.with_timeout, ends the wait. macOS and FreeBSD refuse it at once with Eio.Net.Connection_failure (Refused _), as connect(2) refuses it there.

  • raises Invalid_argument

    if path names no file ("", "/", or a base name of "." or "..") or if its directory has no descriptor of the host, such as a directory of a mock file system.

Sourceval listen : ?replace:bool -> sw:Eio.Switch.t -> net:[> [ `Generic | `Unix ] Eio.Net.ty ] Eio.Resource.t -> backlog:int -> perm:int -> _ Eio.Path.t -> [ `Unix_fd | Eio_unix.Net.listening_socket_ty ] Eio.Resource.t

listen ~replace ~sw ~net ~backlog ~perm path is a stream socket listening at path, whatever its length, whose file has the permission bits perm from the moment a peer can reach it. The directory that holds path is opened through path's own capability, as for connect, and net is the host's network. The socket is bound and given its mode in a directory of its own, made in that one and that no other user can enter, and it listens before it is linked to path's base name; the process's umask is neither read nor changed. On Linux the bind goes through /proc, as connect does.

A file already at path is kept and the listen fails with EADDRINUSE, unclassified, as bind(2) fails. When replace is true (defaults to false) a socket there, whether a listener still serves it or not, is replaced; a file of any other kind is still kept. Releasing sw closes the socket and removes path while it is still that socket's file. Each is checked before the name is replaced or removed, so one who can write the directory can swap another file in between, which is then replaced or removed in its place. renameat(2) and unlinkat(2) act on the name and follow no link, so that is only a name the writer could itself remove or put there: no file outside the directory is reached. A failure is an Eio.Io error, made by Eio_unix.Err.v.

Eio.Net.listening_addr is `Unix p, with p the native path of path (Eio.Path.native), which may be longer than max_path_length. The kernel knows the socket only by the name it was bound at in its private directory, so that name, which reaches nothing, is what a client's getpeername(2) reports. Its connections keep the Unix platform's type, so that they pass descriptors (receive).

Sourceval receive : sw:Eio.Switch.t -> max_fds:int -> max_length:int -> [> `Platform of [> `Unix ] | `Socket | `Stream ] Eio.Resource.t -> (string * Eio_unix.Fd.t list, [ `Too_long ]) result

receive ~sw ~max_fds ~max_length flow is the message its peer wrote on flow up to its end of sending, and the descriptors sent with it, at most max_fds of them, attached to sw; the system closes any more. A peer that writes more than max_length bytes is Error `Too_long, read no further, and the descriptors it sent are closed. A failure of the socket is the Eio.Io error its read raises.