{"id":29169359,"url":"https://github.com/jesuisstan/strace-clone","last_synced_at":"2026-04-13T22:34:40.803Z","repository":{"id":301767278,"uuid":"1010159161","full_name":"jesuisstan/strace-clone","owner":"jesuisstan","description":"This project aims to recode the strace command","archived":false,"fork":false,"pushed_at":"2025-06-28T18:26:50.000Z","size":149,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-28T18:32:51.800Z","etag":null,"topics":["c-language","linux","low-level-programming","makefile","processing","strace","system-calls"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jesuisstan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-28T13:28:51.000Z","updated_at":"2025-06-28T18:28:25.000Z","dependencies_parsed_at":"2025-06-28T18:33:46.495Z","dependency_job_id":"b9d510db-89ca-4463-aa83-b657cb6cde0f","html_url":"https://github.com/jesuisstan/strace-clone","commit_stats":null,"previous_names":["jesuisstan/strace-clone"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jesuisstan/strace-clone","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jesuisstan%2Fstrace-clone","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jesuisstan%2Fstrace-clone/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jesuisstan%2Fstrace-clone/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jesuisstan%2Fstrace-clone/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jesuisstan","download_url":"https://codeload.github.com/jesuisstan/strace-clone/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jesuisstan%2Fstrace-clone/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262959555,"owners_count":23391055,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c-language","linux","low-level-programming","makefile","processing","strace","system-calls"],"created_at":"2025-07-01T12:00:48.844Z","updated_at":"2026-04-13T22:34:40.793Z","avatar_url":"https://github.com/jesuisstan.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# strace-clone\n\nA custom implementation of the Linux `strace` utility, designed to trace system calls and signals of a running process. This project demonstrates advanced system programming concepts including process tracing, signal handling, and system call interception.\n\n## 🎯 Project Overview\n\nThis project recreates the core functionality of the original `strace` utility, which is a powerful diagnostic, instructional, and debugging tool for Linux. It allows you to monitor the system calls used by a program and the signals received by it.\n\n### Key Features\n\n- **System Call Tracing**: Monitor all system calls made by a traced process\n- **Real-time Output**: Display system calls as they occur with detailed parameter information\n- **Symbolic Constants**: Show human-readable symbolic names for flags and constants\n- **Binary Data Display**: Properly format binary data in system calls like `read`, `write`, `getrandom`\n- **Error Handling**: Display meaningful error messages and codes\n- **Process Management**: Handle process creation, execution, and termination\n- **Signal Handling**: Intercept and display signal information\n\n## 🚀 Features\n\n### Core Functionality\n\n- ✅ **Process Tracing**: Attach to running processes or trace new processes\n- ✅ **System Call Interception**: Capture both entry and exit of system calls\n- ✅ **Parameter Decoding**: Display system call parameters in human-readable format\n- ✅ **Return Value Display**: Show system call return values with proper formatting\n- ✅ **Error Reporting**: Display error codes and descriptions for failed system calls\n\n### Advanced Features\n\n- ✅ **Symbolic Constants**: Convert numeric flags to symbolic names (e.g., `O_RDONLY|O_CLOEXEC`)\n- ✅ **String Truncation**: Intelligently truncate long strings with `...` notation\n- ✅ **Binary Data Formatting**: Display binary data in hex format with escape sequences\n- ✅ **Special Syscall Handling**: Custom formatting for complex system calls like `execve`, `mmap`, `ioctl`\n- ✅ **Memory Safety**: Safe reading of process memory using `process_vm_readv`\n\n### Supported System Calls\n\n- **File Operations**: `open`, `openat`, `read`, `write`, `pread64`, `close`, `fstat`\n- **Memory Management**: `mmap`, `munmap`, `mprotect`, `brk`\n- **Process Control**: `execve`, `exit`, `exit_group`, `fork`, `clone`, `clone3`\n- **System Information**: `getrandom`, `arch_prctl`, `set_tid_address`\n- **File System**: `access`, `statfs`, `getdents64`\n- **And many more...**\n\n## 🛠️ Technical Implementation\n\n### Architecture\n\n- **Process Tracing**: Uses `ptrace(PTRACE_SEIZE)` for attaching to processes and `ptrace(PTRACE_INTERRUPT)` for starting tracing\n- **System Call Interception**: Monitors syscall entry/exit using `PTRACE_SYSCALL`\n- **Memory Reading**: Safely reads process memory using `process_vm_readv` system call\n- **Signal Handling**: Blocks and handles signals to prevent interference\n\n### Allowed PTRACE Options\n\nThis implementation strictly follows the subject requirements and uses only the following PTRACE options:\n\n- `PTRACE_SYSCALL` - Monitor system call entry and exit\n- `PTRACE_GETREGSET` - Get register sets from traced process\n- `PTRACE_SETOPTIONS` - Set tracing options\n- `PTRACE_GETSIGINFO` - Get signal information\n- `PTRACE_SEIZE` - Attach to running process\n- `PTRACE_INTERRUPT` - Interrupt traced process\n- `PTRACE_LISTEN` - Listen for process events\n\n### Key Components\n\n- **Main Loop**: Coordinates process tracing and system call monitoring\n- **Syscall Handler**: Decodes and formats system call information\n- **Parameter Logger**: Handles different parameter types (strings, integers, structures)\n- **Memory Reader**: Safely reads data from traced process memory using `process_vm_readv`\n- **Error Handler**: Manages and displays error conditions\n\n### Architecture\n\n```mermaid\ngraph TB\n    subgraph \"ft_strace Architecture\"\n        A[main.c] --\u003e B[config_parse]\n        A --\u003e C[statistics_init]\n        A --\u003e D[exec_program]\n\n        D --\u003e E[fork]\n        E --\u003e F[Child Process]\n        E --\u003e G[Parent Process]\n\n        F --\u003e H[execvp target program]\n\n        G --\u003e I[PTRACE_SEIZE]\n        G --\u003e J[PTRACE_INTERRUPT]\n        G --\u003e K[analysis_routine]\n\n        K --\u003e L[waitpid loop]\n        L --\u003e M{Signal Type?}\n\n        M --\u003e|SIGTRAP| N[Syscall Entry/Exit]\n        M --\u003e|Other Signal| O[Signal Handler]\n\n        N --\u003e P{Entry or Exit?}\n        P --\u003e|Entry| Q[Get syscall number\u003cbr/\u003eStart timer]\n        P --\u003e|Exit| R[Get return value\u003cbr/\u003eStop timer\u003cbr/\u003eLog syscall]\n\n        Q --\u003e S[syscall_handle]\n        R --\u003e T[statistics_add_entry]\n\n        S --\u003e U[syscall_log_param]\n        U --\u003e V[100+ param loggers\u003cbr/\u003elog_string.c\u003cbr/\u003elog_int.c\u003cbr/\u003elog_ptr.c\u003cbr/\u003e...]\n\n        T --\u003e W[Statistics Table]\n\n        O --\u003e X[Print signal info\u003cbr/\u003eif not quiet_mode]\n\n        L --\u003e Y{Process Exited?}\n        Y --\u003e|No| L\n        Y --\u003e|Yes| Z[statistics_log\u003cbr/\u003ePrint table]\n    end\n\n    style A fill:#e1f5fe\n    style K fill:#f3e5f5\n    style W fill:#e8f5e8\n    style V fill:#fff3e0\n```\n\n## 📦 Building and Installation\n\n### Prerequisites\n\n- Linux operating system (tested on Ubuntu 22.04+)\n- GCC compiler with C99 support\n- Make build system\n- Standard C library headers\n\n### Build Instructions\n\n1. **Clone the repository**:\n\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd strace-clone\n   ```\n\n2. **Build the project**:\n\n   ```bash\n   make\n   ```\n\n3. **Clean build artifacts** (optional):\n   ```bash\n   make clean\n   ```\n\n### Build Options\n\n- **Release build** (default): `make`\n- **Debug build**: `make debug`\n- **Clean build**: `make clean`\n- **Reinstall**: `make re`\n- **Compile all tests**: `make compile_tests`\n- **Compile individual tests**: `make test_1`, `make test_2`, etc.\n- **Test kill cmd**: `make test_kill`\n- **Test close cmd**: `make test_close`\n\n## 🎮 Usage\n\n### Basic Usage\n\n```bash\n# Trace a new process\n./ft_strace \u003ccommand\u003e\n\n# Examples\n./ft_strace ls\n./ft_strace echo \"Hello, World!\"\n./ft_strace cat /etc/passwd\n```\n\n### Advanced Usage\n\n```bash\n# Trace with specific system calls\n./ft_strace -c echo \"Hello, World!\"\n```\n\n## 🧪 Testing\n\nThe project includes comprehensive test programs to verify different aspects of the `ft_strace` implementation.\n\n### Compiling Tests\n\n```bash\n# Compile all test programs\nmake compile_tests\n\n# Compile individual tests\nmake test_1\nmake test_2\nmake test_3\nmake test_4\nmake test_5\nmake test_close\nmake test_kill\n```\n\n### Running Tests\n\nAfter compilation, you can run the tests manually with `ft_strace`:\n\n#### Basic Tests (test_1 - test_5)\n\n**test_1** - Process Creation and Synchronization\n\n```bash\n./ft_strace ./test_1\n```\n\n**Description**: Tests `fork()`, `wait()`, and `write()` syscalls. Creates a child process that writes \"child\", parent waits for child completion, then writes \"parent\". Verifies process creation, synchronization, and basic I/O operations.\n\n**test_2** - Signal Handling and Input/Output\n\n```bash\necho \"test input\" | ./ft_strace ./test_2\n```\n\n**Description**: Tests signal handling (`signal(SIGINT, ...)`), input reading (`read()`), and output writing (`write()`). Sets up a signal handler for SIGINT, reads from stdin, and writes to stderr. The `echo \"test input\" |` is required because the program calls `read(0, buf, 1024)` which blocks waiting for stdin input - without this input, the program would hang indefinitely.\n\n**test_3** - Memory Mapping and File Operations\n\n```bash\n./ft_strace ./test_3\n```\n\n**Description**: Tests `mmap()`, `fork()`, `open()`, and `close()` syscalls in a loop. Attempts to open `/tmp/delme`, map it to memory, and perform file operations. Demonstrates memory mapping, process creation, and file handling.\n\n**test_4** - Signal Masking and Signal Raising\n\n```bash\n./ft_strace ./test_4\n```\n\n**Description**: Tests `sigprocmask()`, `signal()`, and `raise()` syscalls. Blocks specific signals (SIGCHLD, 33, 35, 63, 64), sets up a signal handler for SIGWINCH, and raises the signal. Verifies signal masking and signal delivery.\n\n**test_5** - Multi-threading and Process Management\n\n```bash\n./ft_strace ./test_5\n```\n\n**Description**: Tests `pthread_create()`, `fork()`, `waitpid()`, `sleep()`, and `exit()` syscalls. Creates a thread that pauses, forks a child process that creates a thread and exits, then waits for the child. Demonstrates multi-threading, process creation, and synchronization.\n\n#### Additional Tests\n\n**test_close** - File Descriptor Operations\n\n```bash\n./ft_strace ./test_close\n```\n\n**Description**: Tests `close()` syscall with various file descriptors including standard ones (stdin, stdout, stderr) and invalid descriptors. Verifies proper handling of file descriptor operations and error conditions.\n\n**test_kill** - Process Control and Signal Sending\n\n```bash\n./ft_strace ./test_kill\n```\n\n**Description**: Tests `kill()` syscall with various signals and process IDs. Sends signals to the current process and invalid PIDs, verifying signal delivery and error handling.\n\n### Test Output Analysis\n\nEach test produces specific system call patterns that can be analyzed:\n\n- **Process Creation**: Look for `fork()`, `clone()`, `clone3()` syscalls\n- **File Operations**: Check `open()`, `read()`, `write()`, `close()` syscalls\n- **Memory Management**: Examine `mmap()`, `munmap()`, `brk()` syscalls\n- **Signal Handling**: Verify `sigprocmask()`, `rt_sigaction()`, `kill()` syscalls\n- **Threading**: Look for `pthread_create()`, `futex()` syscalls\n- **Process Termination**: Check `exit()`, `exit_group()` syscalls\n\n### Comparing with Original strace\n\nTo compare output with the original `strace`:\n\n```bash\n# Run with ft_strace\n./ft_strace ./test_1\n\n# Run with original strace\nstrace ./test_1\n\n# Compare filtered outputs\n./ft_strace ./test_1 | grep -E \"(child|parent|write|exit_group)\" \u003e ft_strace_output.log\nstrace ./test_1 | grep -E \"(child|parent|write|exit_group)\" \u003e original_strace_output.log\ndiff ft_strace_output.log original_strace_output.log\n```\n\n### Output Format\n\nThe output follows the standard `strace` format:\n\n```\nsyscall_name(parameters) = return_value\n```\n\n**Examples**:\n\n```\nexecve(\"/usr/bin/ls\", ...) = 0\nopenat(AT_FDCWD, \"/etc/ld.so.cache\", O_RDONLY|O_CLOEXEC, 0) = 3\nread(3, \"\\177ELF\\002\\001\\001\\000\\000\\000\\000\\000\\000\\000\\000\\000\\003\\000\u003e\\000\\001\\000\\000\\000\\000\\000\\000\\000\\000\\000\"..., 832) = 832\nwrite(1, \"file1  file2  file3\"..., 47) = 47\n```\n\n## 🔍 Features in Detail\n\n### Symbolic Constants\n\nThe tool automatically converts numeric flags to symbolic names:\n\n- `4` → `R_OK`\n- `-100` → `AT_FDCWD`\n- `0x8000` → `O_RDONLY|O_CLOEXEC`\n\n### Binary Data Display\n\nBinary data is displayed in a readable format:\n\n- Printable ASCII characters shown as-is\n- Non-printable characters shown as escape sequences (`\\t`, `\\n`, `\\r`)\n- Other bytes shown in octal format (`\\177`)\n\n### String Truncation\n\nLong strings are intelligently truncated:\n\n```\nwrite(1, \"This is a very long string that will be truncated...\"..., 100) = 100\n```\n\n### Error Handling\n\nFailed system calls show detailed error information:\n\n```\nopenat(AT_FDCWD, \"/nonexistent/file\", O_RDONLY|O_CLOEXEC, 0) = -1 ENOENT (No such file or directory)\n```\n\n## 🎯 Educational Value\n\nThis project demonstrates several important system programming concepts:\n\n### Process Management\n\n- Process creation and execution\n- Parent-child process relationships\n- Process state monitoring\n\n### System Call Interception\n\n- Using `ptrace` for process tracing\n- System call entry/exit monitoring\n- Parameter and return value extraction\n\n### Memory Management\n\n- Safe reading of process memory using `process_vm_readv`\n- Handling different data types\n- Memory layout understanding\n\n### Signal Handling\n\n- Signal blocking and unblocking\n- Signal delivery mechanisms\n- Process control flow\n\n## 🔗 References\n\n### Original strace Documentation\n\n- **Official strace**: [https://strace.io/](https://strace.io/)\n- **Linux man page**: `man strace`\n- **GitHub repository**: [https://github.com/strace/strace](https://github.com/strace/strace)\n\n### Related Documentation\n\n- **ptrace(2)**: `man 2 ptrace`\n- **syscalls(2)**: `man 2 syscalls`\n- **signal(7)**: `man 7 signal`\n- **process_vm_readv(2)**: `man 2 process_vm_readv`\n\n### Learning Resources\n\n- **Linux System Programming**: Understanding system calls and process management\n- **Advanced Programming in the UNIX Environment**: Process control and interprocess communication\n- **The Linux Programming Interface**: Comprehensive guide to Linux system programming\n\n## 🏗️ Project Structure\n\n```\nstrace-clone/\n├── includes/                # Header files\n│   ├── analysis.h           # Analysis routine declarations\n│   ├── config.h             # Configuration structures\n│   ├── execution.h          # Process execution functions\n│   ├── ft_strace_utils.h    # Utility functions\n│   ├── statistics.h         # Statistics tracking\n│   ├── syscall_strace.h     # System call handling\n│   └── types.h              # Common type definitions\n├── srcs/                    # Source code\n│   ├── analysis/            # System call analysis\n│   │   └── analysis_routine.c\n│   ├── execution/           # Process execution\n│   │   └── exec_program.c\n│   ├── syscall/             # System call handling\n│   │   ├── param_log/       # Parameter logging functions\n│   │   │   ├── utils/       # Parameter logging utilities\n│   │   │   └── *.c          # Individual parameter type handlers\n│   │   ├── syscall_64.c     # 64-bit syscall table\n│   │   ├── syscall_32.h     # 32-bit syscall table\n│   │   ├── syscall_handle.c # Main syscall processing\n│   │   └── syscall_get_description.c\n│   ├── statistics/          # Statistics tracking\n│   │   ├── statistics_init.c\n│   │   ├── statistics_add_entry.c\n│   │   ├── statistics_get.c\n│   │   ├── statistics_log.c\n│   │   └── statistics_destroy.c\n│   ├── utils/               # Utility functions\n│   │   └── ft_strace_utils.c\n│   ├── config.c             # Configuration management\n│   └── main.c               # Main entry point\n├── tests/                   # Test programs\n│   ├── test_1.c             # Process creation and synchronization\n│   ├── test_2.c             # Signal handling and I/O\n│   ├── test_3.c             # Memory mapping and file operations\n│   ├── test_4.c             # Signal masking and raising\n│   ├── test_5.c             # Multi-threading and process management\n│   ├── test_close.c         # File descriptor operations\n│   └── test_kill.c          # Process control and signal sending\n├── .build/                  # Build artifacts (auto-generated)\n├── Makefile                 # Build configuration\n├── .gitignore              # Git ignore rules\n└── README.md               # This file\n```\n\n## 🐛 Known Limitations\n\n- **32-bit Support**: Currently optimized for 64-bit systems\n- **Complex Structures**: Some complex data structures (like `stat`) are shown as addresses\n- **Signal Handling**: Limited signal tracing compared to original strace\n- **Performance**: May have higher overhead than the original strace\n\n## 🤝 Contributing\n\nThis is an educational project, but contributions are welcome! Areas for improvement:\n\n- Enhanced signal handling\n- Support for more system calls\n- Better structure decoding\n- Performance optimizations\n- Additional formatting options\n\n## 📄 License\n\nThis project is created for educational purposes. The original `strace` utility is licensed under the LGPL-2.1+ license.\n\n## 🙏 Acknowledgments\n\n- **Original strace developers**: For creating the excellent reference implementation\n- **Linux kernel developers**: For the comprehensive system call interface\n- **System programming community**: For documentation and examples\n\n---\n\n**Note**: This is an educational implementation and should not be used in production environments. For production use, please use the official `strace` utility.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjesuisstan%2Fstrace-clone","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjesuisstan%2Fstrace-clone","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjesuisstan%2Fstrace-clone/lists"}