# tjmers/freestanding-custom-c-library architecture

> Architecture diagram of the GitHub repository tjmers/freestanding-custom-c-library, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tjmers/freestanding-custom-c-library
- Repository: https://github.com/tjmers/freestanding-custom-c-library

## Overview

This repository is a freestanding Linux x86_64 C library: an application links it instead of system libc, and its custom startup shim initializes runtime state, calls `main`, then exits through the library. The runtime spans buffered output and formatting, heap allocation, conversions, strings and memory routines, exit callbacks, and raw Linux syscall wrappers. Startup and several documented capabilities were not shown in implementation excerpts, so those links rely on the README; relationships between unsampled internals are omitted.

Main entry points: [`src/stdio.c`](https://github.com/tjmers/freestanding-custom-c-library/blob/main/src/stdio.c) (Buffered stdio), [`src/stdlib.c`](https://github.com/tjmers/freestanding-custom-c-library/blob/main/src/stdlib.c) (Heap allocator), [`src/entry.asm`](https://github.com/tjmers/freestanding-custom-c-library/blob/main/src/entry.asm) (Startup shim), [`src/exit.c`](https://github.com/tjmers/freestanding-custom-c-library/blob/main/src/exit.c) (Exit callbacks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup and exit"]
  node_entry["Startup shim<br/>[entry.asm]"]
  node_exit["Exit callbacks<br/>[exit.c]"]
  node_exit_api["Exit API<br/>[exit.h]"]
end

subgraph group_io["Output and syscalls"]
  node_stdio["Buffered stdio<br/>[stdio.c]"]
  node_stdio_internal["Stream internals<br/>[_stdio.h]"]
  node_stdio_api["stdio API<br/>[stdio.h]"]
  node_syscall_api["Syscall interface<br/>[syscalls.h]"]
  node_syscalls["Linux syscall wrappers<br/>[syscalls.asm]"]
  node_mmap_api["Mapping constants<br/>[mmap_macros.h]"]
end

subgraph group_runtime["Memory and allocation"]
  node_heap["Heap allocator<br/>[stdlib.c]"]
  node_memory["Memory routines<br/>[memory.c]"]
  node_memory_api["Memory API<br/>[memory.h]"]
  node_stdlib_api["stdlib API<br/>[stdlib.h]"]
end

subgraph group_utilities["C utilities"]
  node_conversions["Integer conversions<br/>[conversions.c]"]
  node_strings["String routines"]
  node_string_api["String API<br/>[string.h]"]
  node_assertions["Assertions<br/>[assert.c]"]
  node_types["Core types<br/>[stdint.h]"]
  node_varargs["Varargs interface<br/>[stdarg.h]"]
end

node_application(("C application"))

node_application -->|"links against"| node_entry
node_entry -->|"initializes heap"| node_heap
node_entry -->|"initializes streams"| node_stdio
node_entry -->|"calls main"| node_application
node_entry -->|"routes return to"| node_exit
node_stdio -->|"uses"| node_stdio_internal
node_stdio -->|"writes through"| node_syscalls
node_stdio -->|"formats integers with"| node_conversions
node_stdio -->|"uses string routines"| node_strings
node_stdio -->|"registers flush callback"| node_exit
node_heap -->|"grows heap with"| node_syscalls
node_heap -->|"uses memory routines"| node_memory
node_heap -->|"uses string routines"| node_strings
node_heap -->|"formats diagnostics with"| node_conversions
node_memory -->|"implements"| node_memory_api
node_strings -->|"strdup allocates with"| node_stdlib_api
node_assertions -->|"uses"| node_syscalls
node_exit -.->|"terminates through"| node_syscalls
node_syscall_api -->|"defines mapping flags"| node_mmap_api
node_stdio_api -->|"declares interface for"| node_stdio
node_stdlib_api -->|"declares allocator API for"| node_heap
node_string_api -->|"declares string API for"| node_strings
node_exit_api -->|"declares exit API for"| node_exit
node_varargs -->|"supplies formatting arguments"| node_stdio

click node_entry "https://github.com/tjmers/freestanding-custom-c-library/blob/main/src/entry.asm"
click node_exit "https://github.com/tjmers/freestanding-custom-c-library/blob/main/src/exit.c"
click node_stdio "https://github.com/tjmers/freestanding-custom-c-library/blob/main/src/stdio.c"
click node_stdio_internal "https://github.com/tjmers/freestanding-custom-c-library/blob/main/src/_stdio.h"
click node_stdio_api "https://github.com/tjmers/freestanding-custom-c-library/blob/main/intf/stdio.h"
click node_syscall_api "https://github.com/tjmers/freestanding-custom-c-library/blob/main/intf/syscalls.h"
click node_syscalls "https://github.com/tjmers/freestanding-custom-c-library/blob/main/src/syscalls.asm"
click node_heap "https://github.com/tjmers/freestanding-custom-c-library/blob/main/src/stdlib.c"
click node_memory "https://github.com/tjmers/freestanding-custom-c-library/blob/main/src/memory.c"
click node_memory_api "https://github.com/tjmers/freestanding-custom-c-library/blob/main/intf/memory.h"
click node_conversions "https://github.com/tjmers/freestanding-custom-c-library/blob/main/src/conversions.c"
click node_strings "https://github.com/tjmers/freestanding-custom-c-library/tree/main/src/string"
click node_string_api "https://github.com/tjmers/freestanding-custom-c-library/blob/main/intf/string.h"
click node_assertions "https://github.com/tjmers/freestanding-custom-c-library/blob/main/src/assert.c"
click node_types "https://github.com/tjmers/freestanding-custom-c-library/blob/main/intf/stdint.h"
click node_varargs "https://github.com/tjmers/freestanding-custom-c-library/blob/main/intf/stdarg.h"
click node_stdlib_api "https://github.com/tjmers/freestanding-custom-c-library/blob/main/intf/stdlib.h"
click node_exit_api "https://github.com/tjmers/freestanding-custom-c-library/blob/main/intf/exit.h"
click node_mmap_api "https://github.com/tjmers/freestanding-custom-c-library/blob/main/intf/mmap_macros.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_exit,node_exit_api toneBlue
class node_stdio,node_stdio_internal,node_stdio_api,node_syscall_api,node_syscalls,node_mmap_api toneAmber
class node_heap,node_memory,node_memory_api,node_stdlib_api toneMint
class node_conversions,node_strings,node_string_api,node_assertions,node_types,node_varargs toneRose
class node_application toneIndigo
```

## Components

### Startup and exit

- [Startup shim](https://github.com/tjmers/freestanding-custom-c-library/blob/main/src/entry.asm): `src/entry.asm`
- [Exit callbacks](https://github.com/tjmers/freestanding-custom-c-library/blob/main/src/exit.c): `src/exit.c`
- [Exit API](https://github.com/tjmers/freestanding-custom-c-library/blob/main/intf/exit.h): `intf/exit.h`

### Output and syscalls

- [Buffered stdio](https://github.com/tjmers/freestanding-custom-c-library/blob/main/src/stdio.c): `src/stdio.c`
- [Stream internals](https://github.com/tjmers/freestanding-custom-c-library/blob/main/src/_stdio.h): `src/_stdio.h`
- [stdio API](https://github.com/tjmers/freestanding-custom-c-library/blob/main/intf/stdio.h): `intf/stdio.h`
- [Syscall interface](https://github.com/tjmers/freestanding-custom-c-library/blob/main/intf/syscalls.h): `intf/syscalls.h`
- [Linux syscall wrappers](https://github.com/tjmers/freestanding-custom-c-library/blob/main/src/syscalls.asm): `src/syscalls.asm`
- [Mapping constants](https://github.com/tjmers/freestanding-custom-c-library/blob/main/intf/mmap_macros.h): `intf/mmap_macros.h`

### Memory and allocation

- [Heap allocator](https://github.com/tjmers/freestanding-custom-c-library/blob/main/src/stdlib.c): `src/stdlib.c`
- [Memory routines](https://github.com/tjmers/freestanding-custom-c-library/blob/main/src/memory.c): `src/memory.c`
- [Memory API](https://github.com/tjmers/freestanding-custom-c-library/blob/main/intf/memory.h): `intf/memory.h`
- [stdlib API](https://github.com/tjmers/freestanding-custom-c-library/blob/main/intf/stdlib.h): `intf/stdlib.h`

### C utilities

- [Integer conversions](https://github.com/tjmers/freestanding-custom-c-library/blob/main/src/conversions.c): `src/conversions.c`
- [String routines](https://github.com/tjmers/freestanding-custom-c-library/tree/main/src/string): `src/string`
- [String API](https://github.com/tjmers/freestanding-custom-c-library/blob/main/intf/string.h): `intf/string.h`
- [Assertions](https://github.com/tjmers/freestanding-custom-c-library/blob/main/src/assert.c): `src/assert.c`
- [Core types](https://github.com/tjmers/freestanding-custom-c-library/blob/main/intf/stdint.h): `intf/stdint.h`
- [Varargs interface](https://github.com/tjmers/freestanding-custom-c-library/blob/main/intf/stdarg.h): `intf/stdarg.h`

### Other components

- **C application**

## Connections

- C application → Startup shim: links against (evidence: `README.md`)
- Startup shim → Heap allocator: initializes heap (evidence: `README.md`)
- Startup shim → Buffered stdio: initializes streams (evidence: `README.md`)
- Startup shim → C application: calls main (evidence: `README.md`)
- Startup shim → Exit callbacks: routes return to (evidence: `README.md`)
- Buffered stdio → Stream internals: uses (evidence: `src/stdio.c`)
- Buffered stdio → Linux syscall wrappers: writes through (evidence: `src/stdio.c`)
- Buffered stdio → Integer conversions: formats integers with (evidence: `src/stdio.c`)
- Buffered stdio → String routines: uses string routines (evidence: `src/stdio.c`)
- Buffered stdio → Exit callbacks: registers flush callback (evidence: `src/stdio.c`)
- Heap allocator → Linux syscall wrappers: grows heap with (evidence: `src/stdlib.c`)
- Heap allocator → Memory routines: uses memory routines (evidence: `src/stdlib.c`)
- Heap allocator → String routines: uses string routines (evidence: `src/stdlib.c`)
- Heap allocator → Integer conversions: formats diagnostics with (evidence: `src/stdlib.c`)
- Memory routines → Memory API: implements (evidence: `src/memory.c`)
- String routines → stdlib API: strdup allocates with (evidence: `src/string/strdup.c`)
- Assertions → Linux syscall wrappers: uses (evidence: `src/assert.c`)
- Exit callbacks → Linux syscall wrappers: terminates through
- Syscall interface → Mapping constants: defines mapping flags (evidence: `intf/syscalls.h`)
- stdio API → Buffered stdio: declares interface for (evidence: `src/stdio.c`)
- stdlib API → Heap allocator: declares allocator API for (evidence: `src/stdlib.c`)
- String API → String routines: declares string API for (evidence: `src/string/strtok.c`)
- Exit API → Exit callbacks: declares exit API for (evidence: `src/exit.c`)
- Varargs interface → Buffered stdio: supplies formatting arguments (evidence: `src/stdio.c`)