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: