Syscall Classes - The Renacer Book - Pure Rust System Call Tracing
Description: A comprehensive guide to renacer: syscall tracing, DWARF correlation, and performance analysis

# Syscall Classes

Syscall classes are predefined groups of related system calls that make filtering easier. Instead of listing individual syscalls, you can use a class name to filter entire categories.

## Why Use Classes?

### Without Classes

    # Manually list all file-related syscalls
    renacer -e 'trace=open,openat,read,write,close,stat,fstat,lstat,access,chmod,chown' -- ls

Problem: Long, error-prone, easy to miss syscalls.

### With Classes

    # Use the 'file' class
    renacer -e 'trace=file' -- ls

Result: All file operations traced automatically.

## Available Classes

Renacer provides 7 predefined syscall classes covering common use cases.

### 1. File Class (`file`)

Description: All file system operations

Common Syscalls:

- `open`, `openat`, `creat` - Opening files
- `read`, `readv`, `pread64` - Reading data
- `write`, `writev`, `pwrite64` - Writing data
- `close` - Closing file descriptors
- `stat`, `fstat`, `lstat`, `fstatat` - Getting file metadata
- `access`, `faccessat` - Checking file permissions
- `chmod`, `fchmod`, `fchmodat` - Changing permissions
- `chown`, `fchown`, `lchown`, `fchownat` - Changing ownership
- `mkdir`, `mkdirat`, `rmdir` - Directory operations
- `unlink`, `unlinkat`, `rename`, `renameat` - File manipulation
- `link`, `linkat`, `symlink`, `symlinkat` - Link operations
- `readlink`, `readlinkat` - Reading symlinks
- `truncate`, `ftruncate` - Changing file size
- `getdents`, `getdents64` - Reading directory entries
- `chdir`, `fchdir`, `getcwd` - Working directory
- `dup`, `dup2`, `dup3` - File descriptor duplication
- `fcntl` - File control operations
- `ioctl` - Device control
- `lseek`, `llseek` - File positioning

Use Cases:

- Debugging file access issues
- Tracking configuration file loading
- Analyzing I/O patterns
- Finding missing files (ENOENT errors)

Example:

    $ renacer -e 'trace=file' -- cat /etc/hostname
    openat(AT_FDCWD, "/etc/hostname", O_RDONLY) = 3
    fstat(3, {st_mode=S_IFREG|0644, st_size=9, ...}) = 0
    read(3, "myserver\n", 131072) = 9
    write(1, "myserver\n", 9) = 9
    close(3) = 0

### 2. Network Class (`network`)

Description: All network-related operations

Common Syscalls:

- `socket` - Create socket
- `bind` - Bind socket to address
- `listen` - Listen for connections
- `accept`, `accept4` - Accept connections
- `connect` - Connect to remote address
- `send`, `sendto`, `sendmsg`, `sendmmsg` - Send data
- `recv`, `recvfrom`, `recvmsg`, `recvmmsg` - Receive data
- `shutdown` - Shutdown socket
- `setsockopt`, `getsockopt` - Socket options
- `getsockname`, `getpeername` - Socket addresses

Use Cases:

- Debugging network connectivity
- Monitoring API calls
- Tracking HTTP/HTTPS requests
- Analyzing network protocols

Example:

    $ renacer -e 'trace=network' -- curl https://example.com
    socket(AF_INET, SOCK_STREAM, IPPROTO_TCP) = 3
    connect(3, {sa_family=AF_INET, sin_port=htons(443), sin_addr=inet_addr("93.184.216.34")}, 16) = 0
    sendto(3, "\x16\x03\x01...", 517, MSG_NOSIGNAL, NULL, 0) = 517
    recvfrom(3, "\x16\x03\x03...", 16384, 0, NULL, NULL) = 1234
    close(3) = 0

### 3. Process Class (`process`)

Description: Process and thread management

Common Syscalls:

- `fork`, `vfork` - Create child process
- `clone`, `clone3` - Create thread/process
- `execve`, `execveat` - Execute program
- `wait`, `wait4`, `waitpid` - Wait for child
- `exit`, `exit_group` - Terminate process
- `kill`, `tkill`, `tgkill` - Send signals
- `getpid`, `gettid`, `getppid` - Get process IDs
- `setpgid`, `getpgid` - Process groups
- `setsid`, `getsid` - Session management

Use Cases:

- Understanding multi-process programs
- Tracking child process creation
- Debugging shell scripts
- Analyzing build systems (make, cargo)

Example:

    $ renacer -e 'trace=process' -- sh -c 'echo hello'
    clone(child_stack=NULL, flags=CLONE_CHILD_CLEARTID|CLONE_CHILD_SETTID|SIGCHLD) = 12345
    [pid 12345] execve("/bin/echo", ["echo", "hello"], ...) = 0
    [pid 12345] write(1, "hello\n", 6) = 6
    [pid 12345] exit_group(0) = ?
    wait4(12345, [{WIFEXITED(s) && WEXITSTATUS(s) == 0}], 0, NULL) = 12345

### 4. Memory Class (`memory`)

Description: Memory allocation and management

Common Syscalls:

- `brk`, `sbrk` - Change data segment size
- `mmap`, `mmap2` - Map memory
- `munmap` - Unmap memory
- `mprotect` - Change memory protection
- `madvise` - Memory usage advice
- `mlock`, `munlock`, `mlockall`, `munlockall` - Lock/unlock memory
- `mremap` - Remap memory

Use Cases:

- Analyzing memory allocation patterns
- Debugging out-of-memory issues
- Understanding heap vs. mmap allocation
- Tracking memory leaks

Example:

    $ renacer -e 'trace=memory' -- python3 -c 'print("hi")'
    brk(NULL) = 0x55e8f1a00000
    brk(0x55e8f1a21000) = 0x55e8f1a21000
    mmap(NULL, 262144, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, -1, 0) = 0x7f9a2c000000
    mmap(NULL, 2101248, PROT_READ, MAP_PRIVATE|MAP_DENYWRITE, 3, 0) = 0x7f9a2be00000
    munmap(0x7f9a2c000000, 262144) = 0

### 5. Signal Class (`signal`)

Description: Signal handling and delivery

Common Syscalls:

- `signal`, `sigaction`, `rt_sigaction` - Set signal handlers
- `sigreturn`, `rt_sigreturn` - Return from signal handler
- `kill`, `tkill`, `tgkill` - Send signals
- `sigprocmask`, `rt_sigprocmask` - Block/unblock signals
- `sigpending`, `rt_sigpending` - Check pending signals
- `sigsuspend`, `rt_sigsuspend` - Wait for signal
- `sigaltstack` - Set alternate signal stack

Use Cases:

- Debugging signal handling
- Understanding crash handling (SIGSEGV, SIGABRT)
- Tracking interrupt handling (SIGINT, SIGTERM)
- Analyzing async signal safety

Example:

    $ renacer -e 'trace=signal' -- ./signal-handler
    rt_sigaction(SIGINT, {sa_handler=0x55abc123def0, sa_flags=SA_RESTART}, NULL, 8) = 0
    rt_sigaction(SIGTERM, {sa_handler=0x55abc123def0, sa_flags=SA_RESTART}, NULL, 8) = 0
    # ... program waits ...
    # User presses Ctrl+C
    --- SIGINT {si_signo=SIGINT, si_code=SI_KERNEL} ---
    rt_sigreturn({mask=[]}) = 0

### 6. IPC Class (`ipc`)

Description: Inter-process communication

Common Syscalls:

- `pipe`, `pipe2` - Create pipe
- `msgget`, `msgsnd`, `msgrcv`, `msgctl` - Message queues
- `semget`, `semop`, `semctl`, `semtimedop` - Semaphores
- `shmget`, `shmat`, `shmdt`, `shmctl` - Shared memory
- `mq_open`, `mq_send`, `mq_receive`, `mq_notify` - POSIX message queues
- `eventfd`, `eventfd2` - Event notification
- `signalfd`, `signalfd4` - Signal file descriptor

Use Cases:

- Debugging IPC mechanisms
- Understanding message passing
- Tracking shared memory usage
- Analyzing producer/consumer patterns

Example:

    $ renacer -e 'trace=ipc' -- ./ipc-example
    pipe([3, 4]) = 0
    clone(...) = 12346
    [pid 12346] write(4, "message from child\n", 19) = 19
    [pid 12345] read(3, "message from child\n", 4096) = 19

### 7. Desc Class (`desc`)

Description: File descriptor operations

Common Syscalls:

- `dup`, `dup2`, `dup3` - Duplicate file descriptor
- `fcntl` - File control
- `ioctl` - Device I/O control
- `select`, `pselect6` - Synchronous I/O multiplexing
- `poll`, `ppoll` - Wait for events on file descriptors
- `epoll_create`, `epoll_ctl`, `epoll_wait` - Scalable I/O event notification

Use Cases:

- Understanding I/O multiplexing
- Debugging async I/O
- Analyzing event loops
- Tracking file descriptor management

Example:

    $ renacer -e 'trace=desc' -- node server.js
    epoll_create1(EPOLL_CLOEXEC) = 3
    epoll_ctl(3, EPOLL_CTL_ADD, 5, {EPOLLIN, {u32=5, u64=5}}) = 0
    epoll_wait(3, [{EPOLLIN, {u32=5, u64=5}}], 1024, -1) = 1

## Combining Classes

You can specify multiple classes in a single filter:

### Example: File + Network

    $ renacer -e 'trace=file,network' -- wget https://example.com/data.json
    socket(AF_INET, SOCK_STREAM, IPPROTO_TCP) = 3
    connect(3, {sin_addr=inet_addr("93.184.216.34"), ...}, 16) = 0
    openat(AT_FDCWD, "data.json", O_WRONLY|O_CREAT|O_TRUNC, 0666) = 4
    recvfrom(3, "{\"key\": \"value\"}\n", 16384, 0, NULL, NULL) = 17
    write(4, "{\"key\": \"value\"}\n", 17) = 17
    close(4) = 0
    close(3) = 0

Use Case: Trace file download operations (network receive + file write).

### Example: Process + IPC

    $ renacer -e 'trace=process,ipc' -- make
    clone(...) = 12347
    [pid 12347] execve("/usr/bin/gcc", ...) = 0
    pipe([3, 4]) = 0
    [pid 12347] write(4, "compilation output", 18) = 18
    [pid 12345] read(3, "compilation output", 4096) = 18
    wait4(12347, [{WIFEXITED(s) && WEXITSTATUS(s) == 0}], 0, NULL) = 12347

Use Case: Understand build system process spawning and communication.

## Class Implementation Details

### How Classes Work Internally

Renacer maintains a mapping from class names to syscall lists:

    match class_name {
        "file" => vec![
            "open", "openat", "creat", "read", "write", "close",
            "stat", "fstat", "lstat", // ... etc
        ],
        "network" => vec![
            "socket", "bind", "listen", "accept", "connect",
            "send", "recv", // ... etc
        ],
        // ... other classes
    }

When you use `-e 'trace=file'`, Renacer expands it to all syscalls in the `file` class.

### Class Overlap

Some syscalls belong to multiple classes:

- `close`: In both `file` and `network` (closes file descriptors and sockets)
- `ioctl`: In both `desc` and `file` (device control)
- `fcntl`: In both `desc` and `file` (file control)

This is intentional - classes represent common use cases, not mutually exclusive categories.

## Best Practices

### 1. Start Broad, Narrow Down

    # Step 1: Start with broad class
    renacer -e 'trace=file' -- ./app

    # Step 2: Identify noisy syscalls (e.g., fstat called 1000 times)
    # Step 3: Narrow with negation (see filtering-negation.md)
    renacer -e 'trace=file,!/fstat/' -- ./app

### 2. Use Classes for Exploration

    # Exploring unknown program behavior
    renacer -e 'trace=file,network,process' -- ./mystery-app

Classes give you a quick overview without needing to know every syscall.

### 3. Combine Classes with Statistics

    # Get aggregate data for all file operations
    renacer -e 'trace=file' -c -- ./app

See which file operations dominate (e.g., `read` taking 80% of time).

### 4. Use Specific Classes for Targeted Debugging

    # Network debugging only
    renacer -e 'trace=network' -- curl https://api.example.com

    # Memory debugging only
    renacer -e 'trace=memory' -- python memory_intensive.py

## Complete Syscall Class Reference

### File Class Members (Complete List)

    open, openat, creat, close, read, readv, pread64, preadv, preadv2,
    write, writev, pwrite64, pwritev, pwritev2, stat, fstat, lstat, fstatat,
    newfstatat, access, faccessat, faccessat2, chmod, fchmod, fchmodat,
    chown, fchown, lchown, fchownat, mkdir, mkdirat, rmdir, unlink, unlinkat,
    rename, renameat, renameat2, link, linkat, symlink, symlinkat, readlink,
    readlinkat, truncate, ftruncate, getdents, getdents64, chdir, fchdir,
    getcwd, dup, dup2, dup3, fcntl, ioctl, lseek, llseek, sendfile, splice,
    tee, vmsplice, copy_file_range, sync, fsync, fdatasync, syncfs

### Network Class Members (Complete List)

    socket, socketpair, bind, listen, accept, accept4, connect, getsockname,
    getpeername, send, sendto, sendmsg, sendmmsg, recv, recvfrom, recvmsg,
    recvmmsg, shutdown, setsockopt, getsockopt

### Process Class Members (Complete List)

    fork, vfork, clone, clone3, execve, execveat, wait, wait4, waitpid, waitid,
    exit, exit_group, kill, tkill, tgkill, getpid, gettid, getppid, setpgid,
    getpgid, setpgrp, getpgrp, setsid, getsid, getuid, geteuid, getgid, getegid,
    setuid, seteuid, setgid, setegid, setreuid, setregid, setresuid, setresgid,
    getresuid, getresgid, getgroups, setgroups, capget, capset, prctl, arch_prctl

### Memory Class Members (Complete List)

    brk, mmap, mmap2, munmap, mprotect, madvise, mlock, munlock, mlockall,
    munlockall, mincore, mremap, remap_file_pages, mbind, get_mempolicy,
    set_mempolicy, migrate_pages, move_pages, membarrier

### Signal Class Members (Complete List)

    signal, sigaction, rt_sigaction, sigreturn, rt_sigreturn, kill, tkill,
    tgkill, sigprocmask, rt_sigprocmask, sigpending, rt_sigpending, sigsuspend,
    rt_sigsuspend, sigaltstack, signalfd, signalfd4

### IPC Class Members (Complete List)

    pipe, pipe2, msgget, msgsnd, msgrcv, msgctl, semget, semop, semctl,
    semtimedop, shmget, shmat, shmdt, shmctl, mq_open, mq_unlink, mq_timedsend,
    mq_timedreceive, mq_notify, mq_getsetattr, eventfd, eventfd2

### Desc Class Members (Complete List)

    dup, dup2, dup3, fcntl, ioctl, select, pselect6, poll, ppoll, epoll_create,
    epoll_create1, epoll_ctl, epoll_wait, epoll_pwait, epoll_pwait2

## Summary

Syscall classes simplify filtering by grouping related syscalls:

- 7 predefined classes: `file`, `network`, `process`, `memory`, `signal`, `ipc`, `desc`
- Combine classes: Use multiple classes in one filter
- Class overlap: Some syscalls in multiple classes (expected)
- Best for exploration: Quick overview without knowing every syscall

Next Steps:

- Negation Operator - Exclude syscalls from classes
- Regex Patterns - Advanced pattern matching
- Filtering Syscalls - Main filtering guide