scorpiox-beam Networking
Zero-copy file transfer over TCP. No config, no dependencies — just send and receive.
Overview
scorpiox-beam is a single-binary file transfer tool built in pure C.
It uses kernel-level zero-copy mechanisms (sendfile() on Linux/macOS,
TransmitFile() on Windows) to move files over TCP with minimal CPU overhead.
No configuration files. No package dependencies. Just a sender and a receiver.
Source: scorpiox/scorpiox-beam.c
Features
Zero-Copy Transfer
Uses sendfile() / TransmitFile() to bypass userspace copying. Data moves directly from file descriptor to socket in kernel space.
Cross-Platform
Native support for Linux, macOS, and Windows. Uses the optimal zero-copy syscall for each platform automatically.
xxHash64 Checksum
Every transfer is verified with xxHash64 — a non-cryptographic hash optimized for speed. Catches corruption instantly.
Binary Header Protocol
Custom binary header encodes filename and file size before data transfer begins. No parsing overhead, no ambiguity.
ACK/NAK Confirmation
Receiver sends explicit ACK or NAK after checksum verification. Sender knows immediately if the transfer succeeded.
Progress Display
Real-time transfer progress shown in terminal. Bytes transferred, speed, and completion percentage.
Wire Protocol
scorpiox-beam uses a simple binary protocol over TCP. No TLS, no HTTP, no framing libraries — just raw bytes with a structured header.
┌──────────────────────────────────────────────────────────────┐
│ scorpiox-beam Protocol │
├──────────────────────────────────────────────────────────────┤
│ │
│ SENDER RECEIVER │
│ │ │ │
│ │──── TCP Connect (port 9876) ────────────────▶│ │
│ │ │ │
│ │──── Header [filename_len | filename | size] ─▶│ │
│ │ │ │
│ │──── File Data (sendfile / TransmitFile) ────▶│ │
│ │ │ │
│ │──── xxHash64 Checksum (8 bytes) ────────────▶│ │
│ │ │ │
│ │◀─── ACK (checksum match) ────────────────────│ │
│ │◀─── NAK (checksum mismatch) ─────────────────│ │
│ │ │ │
└──────────────────────────────────────────────────────────────┘
Header Structure
// Header (variable length) uint16_t filename_len; // 2 bytes — length of filename char filename[]; // N bytes — filename (no null terminator) uint64_t file_size; // 8 bytes — total file size in bytes // Data uint8_t data[]; // file_size bytes — raw file content // Trailer uint64_t xxhash64; // 8 bytes — xxHash64 of file content // Response uint8_t ack; // 1 byte — 0x01 = ACK, 0x00 = NAK
How It Works
Receiver Listens
The receiver starts scorpiox-beam receive and binds to TCP port 9876. It waits for an incoming connection.
Sender Connects
The sender runs scorpiox-beam send <file> <host>. It opens a TCP connection to the receiver and sends the binary header with the filename and file size.
Zero-Copy Transfer
File data is sent directly from the file descriptor to the TCP socket using sendfile() (Linux/macOS) or TransmitFile() (Windows). No intermediate buffer in userspace.
Checksum Verification
After all data is received, the sender sends the xxHash64 checksum. The receiver computes its own hash of the received data and compares. ACK on match, NAK on mismatch.
Usage Examples
Receive a file
# Start listening on port 9876 (default) $ scorpiox-beam receive # Listen on a custom port $ scorpiox-beam receive --port 4444 # Save to a specific directory $ scorpiox-beam receive --dir /tmp/incoming
Send a file
# Send a file to a host $ scorpiox-beam send ./backup.tar.gz 192.168.1.50 # Send to a custom port $ scorpiox-beam send ./data.bin 10.0.0.5 --port 4444 # Send to a hostname $ scorpiox-beam send ./release.zip build-server.local
Typical output
# Sender scorpiox-beam: sending backup.tar.gz (2.4 GB) to 192.168.1.50:9876 [████████████████████████████████████] 100% 2.4 GB 890 MB/s scorpiox-beam: transfer complete — checksum ACK # Receiver scorpiox-beam: listening on :9876 scorpiox-beam: incoming backup.tar.gz (2.4 GB) from 192.168.1.100 [████████████████████████████████████] 100% 2.4 GB scorpiox-beam: xxhash64 verified — OK
Comparison
How scorpiox-beam compares to other file transfer tools.
| Feature | scorpiox-beam | scp | rsync | netcat | croc |
|---|---|---|---|---|---|
| Zero-copy I/O | ✓ sendfile() | ✗ | ✗ | ✗ | ✗ |
| Dependencies | None | OpenSSH | rsync + ssh | None | Go runtime |
| Checksum | xxHash64 | SSH MAC | MD5/xxhash | None | PAKE |
| Encryption | None (LAN use) | SSH | SSH | None | PAKE |
| Static binary | ✓ ~100KB | ✗ | ✗ | ✓ | ✓ ~15MB |
| Cross-platform | Linux/macOS/Win | Linux/macOS | Linux/macOS | Linux/macOS | All |
| Progress display | ✓ | ✓ | ✓ | ✗ | ✓ |
Network Stack Context
scorpiox-beam is one component in the broader scorpiox networking stack — 15 pure C networking tools covering DNS, tunneling, proxying, email, and more.