# sahlberg/libnfs architecture

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

- Interactive diagram: https://gitdiagram.com/sahlberg/libnfs
- Repository: https://github.com/sahlberg/libnfs

## Overview

libnfs is a network NFS client library with raw asynchronous RPC, high-level asynchronous VFS operations, and synchronous VFS operations. The main workflow is an application issuing a filesystem request, libnfs translating it to NFSv3 or NFSv4 operations, then RPC transport sending it to an NFS server and returning a result. The README also documents NFSv4.2 sparse-file operations, optional TLS, and RPC server support. The excerpts do not establish every internal call path, so uncertain wiring is omitted.

Main entry points: [`lib/pdu.c`](https://github.com/sahlberg/libnfs/blob/master/lib/pdu.c) (RPC requests), [`lib/libnfs.c`](https://github.com/sahlberg/libnfs/blob/master/lib/libnfs.c) (Client context), [`lib/socket.c`](https://github.com/sahlberg/libnfs/blob/master/lib/socket.c) (RPC socket), [`include/nfsc/libnfs.h`](https://github.com/sahlberg/libnfs/blob/master/include/nfsc/libnfs.h) (VFS API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Client APIs"]
  node_highapi["VFS API<br/>[libnfs.h]"]
  node_rawapi["Raw RPC API<br/>[libnfs-raw.h]"]
  node_sync["Sync wrappers<br/>[libnfs-sync.c]"]
  node_client["Client context<br/>[libnfs.c]"]
end

subgraph group_protocol["NFS Protocols"]
  node_nfs3["NFSv3 operations<br/>[nfs_v3.c]"]
  node_nfs4["NFSv4 operations<br/>[nfs_v4.c]"]
  node_mount["Mount protocol<br/>[mount.c]"]
  node_portmap["Portmapper<br/>[portmap.c]"]
end

subgraph group_transport["RPC Transport"]
  node_zdr["ZDR encoding<br/>[libnfs-zdr.c]"]
  node_pdu["RPC requests<br/>[pdu.c]"]
  node_socket["RPC socket<br/>[socket.c]"]
  node_tls["TLS transport<br/>[handshake.c]"]
end

subgraph group_server["RPC Servers"]
  node_nfsserver["NFS server<br/>[nfsd.c]"]
  node_mountserver["Mount server<br/>[mountd.c]"]
  node_rpcbindserver["RPC bind server<br/>[rpcbind.c]"]
end

node_app(("Application"))
node_peer(("NFS server"))
node_wire(("Network"))

node_app -->|"issues VFS calls"| node_highapi
node_app -->|"issues RPC tasks"| node_rawapi
node_sync -->|"offers sync calls"| node_highapi
node_highapi -->|"uses context"| node_client
node_client -->|"dispatches NFSv3"| node_nfs3
node_client -->|"dispatches NFSv4"| node_nfs4
node_nfs3 -->|"queues RPCs"| node_pdu
node_nfs4 -->|"queues RPCs"| node_pdu
node_rawapi -->|"queues RPC tasks"| node_pdu
node_pdu -->|"encodes messages"| node_zdr
node_pdu -->|"transmits RPCs"| node_socket
node_socket -->|"sends and receives"| node_wire
node_wire -->|"carries RPC traffic"| node_peer
node_socket -.->|"secures connection"| node_tls
node_nfsserver -->|"serves NFS"| node_peer
node_mountserver -->|"serves mounts"| node_peer
node_rpcbindserver -->|"registers services"| node_peer
node_mount -->|"queues mount RPCs"| node_pdu
node_portmap -->|"queues portmap RPCs"| node_pdu

click node_highapi "https://github.com/sahlberg/libnfs/blob/master/include/nfsc/libnfs.h"
click node_rawapi "https://github.com/sahlberg/libnfs/blob/master/include/nfsc/libnfs-raw.h"
click node_sync "https://github.com/sahlberg/libnfs/blob/master/lib/libnfs-sync.c"
click node_client "https://github.com/sahlberg/libnfs/blob/master/lib/libnfs.c"
click node_nfs3 "https://github.com/sahlberg/libnfs/blob/master/lib/nfs_v3.c"
click node_nfs4 "https://github.com/sahlberg/libnfs/blob/master/lib/nfs_v4.c"
click node_mount "https://github.com/sahlberg/libnfs/blob/master/mount/mount.c"
click node_portmap "https://github.com/sahlberg/libnfs/blob/master/portmap/portmap.c"
click node_zdr "https://github.com/sahlberg/libnfs/blob/master/lib/libnfs-zdr.c"
click node_pdu "https://github.com/sahlberg/libnfs/blob/master/lib/pdu.c"
click node_socket "https://github.com/sahlberg/libnfs/blob/master/lib/socket.c"
click node_tls "https://github.com/sahlberg/libnfs/blob/master/tls/handshake.c"
click node_nfsserver "https://github.com/sahlberg/libnfs/blob/master/servers/nfsd/nfsd.c"
click node_mountserver "https://github.com/sahlberg/libnfs/blob/master/servers/nfsd/mountd.c"
click node_rpcbindserver "https://github.com/sahlberg/libnfs/blob/master/servers/rpcbind/rpcbind.c"

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_highapi,node_rawapi,node_sync,node_client toneBlue
class node_nfs3,node_nfs4,node_mount,node_portmap toneAmber
class node_zdr,node_pdu,node_socket,node_tls,node_peer toneMint
class node_nfsserver,node_mountserver,node_rpcbindserver toneRose
class node_app,node_wire toneIndigo
```

## Components

### Client APIs

- [VFS API](https://github.com/sahlberg/libnfs/blob/master/include/nfsc/libnfs.h): `include/nfsc/libnfs.h`
- [Raw RPC API](https://github.com/sahlberg/libnfs/blob/master/include/nfsc/libnfs-raw.h): `include/nfsc/libnfs-raw.h`
- [Sync wrappers](https://github.com/sahlberg/libnfs/blob/master/lib/libnfs-sync.c): `lib/libnfs-sync.c`
- [Client context](https://github.com/sahlberg/libnfs/blob/master/lib/libnfs.c): `lib/libnfs.c`

### NFS Protocols

- [NFSv3 operations](https://github.com/sahlberg/libnfs/blob/master/lib/nfs_v3.c): `lib/nfs_v3.c`
- [NFSv4 operations](https://github.com/sahlberg/libnfs/blob/master/lib/nfs_v4.c): `lib/nfs_v4.c`
- [Mount protocol](https://github.com/sahlberg/libnfs/blob/master/mount/mount.c): `mount/mount.c`
- [Portmapper](https://github.com/sahlberg/libnfs/blob/master/portmap/portmap.c): `portmap/portmap.c`

### RPC Transport

- [ZDR encoding](https://github.com/sahlberg/libnfs/blob/master/lib/libnfs-zdr.c): `lib/libnfs-zdr.c`
- [RPC requests](https://github.com/sahlberg/libnfs/blob/master/lib/pdu.c): `lib/pdu.c`
- [RPC socket](https://github.com/sahlberg/libnfs/blob/master/lib/socket.c): `lib/socket.c`
- [TLS transport](https://github.com/sahlberg/libnfs/blob/master/tls/handshake.c): `tls/handshake.c`

### RPC Servers

- [NFS server](https://github.com/sahlberg/libnfs/blob/master/servers/nfsd/nfsd.c): `servers/nfsd/nfsd.c`
- [Mount server](https://github.com/sahlberg/libnfs/blob/master/servers/nfsd/mountd.c): `servers/nfsd/mountd.c`
- [RPC bind server](https://github.com/sahlberg/libnfs/blob/master/servers/rpcbind/rpcbind.c): `servers/rpcbind/rpcbind.c`

### Other components

- **Application**
- **NFS server**
- **Network**

## Connections

- Application → VFS API: issues VFS calls
- Application → Raw RPC API: issues RPC tasks
- Sync wrappers → VFS API: offers sync calls
- VFS API → Client context: uses context
- Client context → NFSv3 operations: dispatches NFSv3
- Client context → NFSv4 operations: dispatches NFSv4
- NFSv3 operations → RPC requests: queues RPCs
- NFSv4 operations → RPC requests: queues RPCs
- Raw RPC API → RPC requests: queues RPC tasks
- RPC requests → ZDR encoding: encodes messages
- RPC requests → RPC socket: transmits RPCs
- RPC socket → Network: sends and receives
- Network → NFS server: carries RPC traffic
- RPC socket → TLS transport: secures connection
- NFS server → NFS server: serves NFS
- Mount server → NFS server: serves mounts
- RPC bind server → NFS server: registers services
- Mount protocol → RPC requests: queues mount RPCs
- Portmapper → RPC requests: queues portmap RPCs