tiny-nix-ipc

A small and convenient Rust library for using (UNIX domain) sockets for simple synchronous IPC.

• Socket::new_socketpair makes a socketpair with the settings you want (AF_UNIX/SOCK_SEQPACKET/CLOEXEC), but you can use FromRawFd of course
• if you want to poll (using poll, select, kqueue, epoll, abstractions like mio, etc.), get the fd using AsRawFd
• all send/recv methods allow file descriptor (fd) passing
• you can send/recv raw iovecs (scatter-gather vectors), buffers, structs and serde-serialized objects
• serde is optional, select a Cargo feature for the format you want (ser_cbor, ser_json, ser_bincode)

Usage

extern crate tiny_nix_ipc;
use tiny_nix_ipc::Socket;

Create a socket pair:

let (mut prnt, mut chld) = Socket::new_socketpair().unwrap();

Make a socket non-CLOEXEC (e.g. if you want to fork/exec a different program that should inherit the socket):

chld.no_cloexec().unwrap();

Send bytes:

let data = [0xDE, 0xAD, 0xBE, 0xEF];
let sent_bytes = prnt.send_slice(&data[..], None).unwrap();
// sent_bytes == 4

Receive bytes:

let mut rdata = [0; 4];
let (recvd_bytes, rfds) = chld.recv_into_slice::<[RawFd; 0]>(&mut rdata[..]).unwrap();
// recvd_bytes == 4, rfds == None

Send bytes with a file descriptor (shmemfdrs creates an anonymous file, used as an example here, can be any descriptor of course):

let fd = shmemfdrs::create_shmem(CString::new("/test").unwrap(), 123);
let data = [0xDE, 0xAD, 0xBE, 0xEF];
let sent_bytes = prnt.send_slice(&data[..], Some(&[fd])).unwrap();
// sent_bytes == 4

Receive bytes and the file descriptor:

let mut rdata = [0; 4];
let (recvd_bytes, rfds) = chld.recv_into_slice::<[RawFd; 1]>(&mut rdata[..]).unwrap();
// recvd_bytes == 4, rfds == Some([6])

Send a struct, just as its raw bytes (does not work with pointers/references/boxes/etc.!):

struct TestStruct {
    one: i8,
    two: u32,
}

let data = TestStruct { one: -65, two: 0xDEADBEEF, };
let _ = prnt.send_struct(&data, None).unwrap();

Receive a struct:

let (rdata, rfds) = chld.recv_struct::<TestStruct, [RawFd; 0]>().unwrap();
// rdata == TestStruct { one: -65, two: 0xDEADBEEF, }, rfds == None

Send a Serde-serializable value serialized as CBOR (via serde_cbor):

tiny-nix-ipc = { version = "0", features = ["ser_cbor"] }

use serde_cbor::value::Value;
let data = Value::U64(123456); // can be your Serializable
let sent_bytes = prnt.send_cbor(&data, None).unwrap();
// sent_bytes == 4

Receive a Serde-deserializable value serialized as CBOR:

let (rdata, rfds) = chld.recv_cbor::<Value, [RawFd; 0]>(24).unwrap();
// rdata == Value::U64(123456)

Contributing

Please feel free to submit pull requests!

By participating in this project you agree to follow the Contributor Code of Conduct.

The list of contributors is available on GitHub.

License

This is free and unencumbered software released into the public domain.
For more information, please refer to the UNLICENSE file or unlicense.org.