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

rust extern crate tiny_nix_ipc; use tiny_nix_ipc::Socket;

Create a socket pair:

rust 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):

rust chld.no_cloexec().unwrap();

Send bytes:

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

Receive bytes:

rust 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):

rust 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:

rust 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.!):

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

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

Receive a struct:

rust 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):

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

rust 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:

rust 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.