# johnpgarry/sg3_utils architecture

> Architecture diagram of the GitHub repository johnpgarry/sg3_utils, 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/johnpgarry/sg3_utils
- Repository: https://github.com/johnpgarry/sg3_utils

## Overview

sg3_utils is a suite of command-line tools for issuing SCSI and related storage commands, plus the shared libsgutils runtime. The usual workflow is an operator invoking a utility, which interprets options and requests device operations through shared command and pass-through layers; results are decoded or displayed. Copy utilities provide a distinct data-transfer workflow. The README documents ATA/SAT and NVMe support, including NVMe-aware behavior in sg_inq and sg_ses. Some subsystem links below rely on README or SOURCE INDEX references rather than sampled implementation excerpts.

Main entry points: [`include/sg_pt.h`](https://github.com/johnpgarry/sg3_utils/blob/master/include/sg_pt.h) (Pass-through API), [`include/sg_cmds_basic.h`](https://github.com/johnpgarry/sg3_utils/blob/master/include/sg_cmds_basic.h) (Basic command API), [`src/sg_ses.c`](https://github.com/johnpgarry/sg3_utils/blob/master/src/sg_ses.c) (Enclosure services), [`lib/sg_pt_linux.c`](https://github.com/johnpgarry/sg3_utils/blob/master/lib/sg_pt_linux.c) (Linux transport)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Command-line utilities"]
  node_single["SCSI utilities"]
  node_raw["Raw commands<br/>[sg_raw.c]"]
  node_copy["Copy utilities<br/>[sg_dd.c]"]
  node_inquiry["Inquiry<br/>[sg_inq.c]"]
  node_logs["Log pages<br/>[sg_logs.c]"]
  node_enclosure["Enclosure services<br/>[sg_ses.c]"]
  node_vpd["VPD data<br/>[sg_vpd.c]"]
  node_zone["Zone query<br/>[sg_z_act_query.c]"]
end

subgraph group_commands["Command and decode library"]
  node_basiccmd["Basic commands<br/>[sg_cmds_basic.c]"]
  node_extracmd["Extended commands<br/>[sg_cmds_extra.c]"]
  node_decode["SCSI decoding<br/>[sg_lib.c]"]
  node_codedata["Decode tables<br/>[sg_lib_data.c]"]
end

subgraph group_transport["Pass-through transport"]
  node_linuxpt["Linux transport<br/>[sg_pt_linux.c]"]
  node_nvmept["Linux NVMe<br/>[sg_pt_linux_nvme.c]"]
  node_freebsdpt["FreeBSD transport<br/>[sg_pt_freebsd.c]"]
  node_winpt["Windows transport<br/>[sg_pt_win32.c]"]
end

subgraph group_interfaces["Runtime interfaces"]
  node_basicapi["Basic command API<br/>[sg_cmds_basic.h]"]
  node_extraapi["Extended command API<br/>[sg_cmds_extra.h]"]
  node_libapi["Library API<br/>[sg_lib.h]"]
  node_dataapi["Data definitions<br/>[sg_lib_data.h]"]
  node_ptapi["Pass-through API<br/>[sg_pt.h]"]
  node_linuxio["Linux I/O definitions<br/>[sg_io_linux.h]"]
  node_linuxinc["Linux definitions<br/>[sg_linux_inc.h]"]
  node_nvmeapi["NVMe interface<br/>[sg_pt_nvme.h]"]
  node_winapi["Windows interface<br/>[sg_pt_win32.h]"]
  node_diagnostics["Diagnostics output<br/>[sg_pr2serr.h]"]
  node_unaligned["Byte conversions<br/>[sg_unaligned.h]"]
  node_uapi["SG kernel interface<br/>[uapi_sg.h]"]
  node_corelinux["Linux pass-through API<br/>[sg_pt_linux.h]"]
  node_names["Name tables API<br/>[sg_lib_names.h]"]
end

node_operator(("Operator"))
node_device{{"Storage device"}}

node_operator -->|"invokes"| node_single
node_operator -->|"invokes"| node_raw
node_operator -->|"invokes"| node_copy
node_single -.->|"requests commands"| node_basiccmd
node_raw -.->|"submits commands"| node_ptapi
node_copy -.->|"requests I/O"| node_basiccmd
node_inquiry -->|"uses command API"| node_basicapi
node_inquiry -->|"uses pass-through"| node_ptapi
node_logs -->|"uses command API"| node_basicapi
node_logs -->|"uses pass-through"| node_ptapi
node_enclosure -->|"uses command API"| node_basicapi
node_enclosure -->|"uses extended API"| node_extraapi
node_enclosure -->|"uses pass-through"| node_ptapi
node_vpd -->|"uses command API"| node_basicapi
node_zone -->|"uses command API"| node_basicapi
node_basiccmd -.->|"uses pass-through"| node_ptapi
node_extracmd -->|"uses pass-through"| node_ptapi
node_decode -->|"uses tables"| node_codedata
node_decode -->|"uses definitions"| node_dataapi
node_inquiry -->|"queries SCSI or NVMe"| node_device
node_enclosure -->|"queries SCSI or NVMe"| node_device
node_single -->|"sends SCSI commands"| node_device
node_copy -->|"copies device data"| node_device
node_ptapi -.->|"implemented by"| node_linuxpt
node_ptapi -.->|"implemented by"| node_freebsdpt
node_ptapi -.->|"implemented by"| node_winpt
node_linuxpt -->|"supports NVMe"| node_nvmept
node_linuxpt -.->|"uses definitions"| node_linuxio
node_linuxpt -.->|"uses interface"| node_corelinux
node_nvmept -->|"uses interface"| node_nvmeapi
node_freebsdpt -->|"uses interface"| node_nvmeapi
node_winpt -->|"uses interface"| node_winapi
node_linuxio -->|"includes definitions"| node_linuxinc
node_uapi -.->|"complements interface"| node_linuxio
node_basicapi -.->|"documents output"| node_diagnostics
node_libapi -.->|"supports decoding"| node_unaligned
node_names -->|"uses definitions"| node_dataapi

click node_single "https://github.com/johnpgarry/sg3_utils/tree/master/src"
click node_raw "https://github.com/johnpgarry/sg3_utils/blob/master/src/sg_raw.c"
click node_copy "https://github.com/johnpgarry/sg3_utils/blob/master/src/sg_dd.c"
click node_inquiry "https://github.com/johnpgarry/sg3_utils/blob/master/src/sg_inq.c"
click node_logs "https://github.com/johnpgarry/sg3_utils/blob/master/src/sg_logs.c"
click node_enclosure "https://github.com/johnpgarry/sg3_utils/blob/master/src/sg_ses.c"
click node_vpd "https://github.com/johnpgarry/sg3_utils/blob/master/src/sg_vpd.c"
click node_zone "https://github.com/johnpgarry/sg3_utils/blob/master/src/sg_z_act_query.c"
click node_basiccmd "https://github.com/johnpgarry/sg3_utils/blob/master/lib/sg_cmds_basic.c"
click node_basicapi "https://github.com/johnpgarry/sg3_utils/blob/master/include/sg_cmds_basic.h"
click node_extracmd "https://github.com/johnpgarry/sg3_utils/blob/master/lib/sg_cmds_extra.c"
click node_extraapi "https://github.com/johnpgarry/sg3_utils/blob/master/include/sg_cmds_extra.h"
click node_decode "https://github.com/johnpgarry/sg3_utils/blob/master/lib/sg_lib.c"
click node_codedata "https://github.com/johnpgarry/sg3_utils/blob/master/lib/sg_lib_data.c"
click node_libapi "https://github.com/johnpgarry/sg3_utils/blob/master/include/sg_lib.h"
click node_dataapi "https://github.com/johnpgarry/sg3_utils/blob/master/include/sg_lib_data.h"
click node_ptapi "https://github.com/johnpgarry/sg3_utils/blob/master/include/sg_pt.h"
click node_linuxpt "https://github.com/johnpgarry/sg3_utils/blob/master/lib/sg_pt_linux.c"
click node_nvmept "https://github.com/johnpgarry/sg3_utils/blob/master/lib/sg_pt_linux_nvme.c"
click node_freebsdpt "https://github.com/johnpgarry/sg3_utils/blob/master/lib/sg_pt_freebsd.c"
click node_winpt "https://github.com/johnpgarry/sg3_utils/blob/master/lib/sg_pt_win32.c"
click node_linuxio "https://github.com/johnpgarry/sg3_utils/blob/master/include/sg_io_linux.h"
click node_linuxinc "https://github.com/johnpgarry/sg3_utils/blob/master/include/sg_linux_inc.h"
click node_nvmeapi "https://github.com/johnpgarry/sg3_utils/blob/master/include/sg_pt_nvme.h"
click node_winapi "https://github.com/johnpgarry/sg3_utils/blob/master/include/sg_pt_win32.h"
click node_diagnostics "https://github.com/johnpgarry/sg3_utils/blob/master/include/sg_pr2serr.h"
click node_unaligned "https://github.com/johnpgarry/sg3_utils/blob/master/include/sg_unaligned.h"
click node_uapi "https://github.com/johnpgarry/sg3_utils/blob/master/testing/uapi_sg.h"
click node_corelinux "https://github.com/johnpgarry/sg3_utils/blob/master/include/sg_pt_linux.h"
click node_names "https://github.com/johnpgarry/sg3_utils/blob/master/include/sg_lib_names.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_single,node_raw,node_copy,node_inquiry,node_logs,node_enclosure,node_vpd,node_zone toneBlue
class node_basiccmd,node_extracmd,node_decode,node_codedata,node_device toneAmber
class node_linuxpt,node_nvmept,node_freebsdpt,node_winpt toneMint
class node_basicapi,node_extraapi,node_libapi,node_dataapi,node_ptapi,node_linuxio,node_linuxinc,node_nvmeapi,node_winapi,node_diagnostics,node_unaligned,node_uapi,node_corelinux,node_names toneRose
class node_operator toneIndigo
```

## Components

### Command-line utilities

- [SCSI utilities](https://github.com/johnpgarry/sg3_utils/tree/master/src): `src`
- [Raw commands](https://github.com/johnpgarry/sg3_utils/blob/master/src/sg_raw.c): `src/sg_raw.c`
- [Copy utilities](https://github.com/johnpgarry/sg3_utils/blob/master/src/sg_dd.c): `src/sg_dd.c`
- [Inquiry](https://github.com/johnpgarry/sg3_utils/blob/master/src/sg_inq.c): `src/sg_inq.c`
- [Log pages](https://github.com/johnpgarry/sg3_utils/blob/master/src/sg_logs.c): `src/sg_logs.c`
- [Enclosure services](https://github.com/johnpgarry/sg3_utils/blob/master/src/sg_ses.c): `src/sg_ses.c`
- [VPD data](https://github.com/johnpgarry/sg3_utils/blob/master/src/sg_vpd.c): `src/sg_vpd.c`
- [Zone query](https://github.com/johnpgarry/sg3_utils/blob/master/src/sg_z_act_query.c): `src/sg_z_act_query.c`

### Command and decode library

- [Basic commands](https://github.com/johnpgarry/sg3_utils/blob/master/lib/sg_cmds_basic.c): `lib/sg_cmds_basic.c`
- [Extended commands](https://github.com/johnpgarry/sg3_utils/blob/master/lib/sg_cmds_extra.c): `lib/sg_cmds_extra.c`
- [SCSI decoding](https://github.com/johnpgarry/sg3_utils/blob/master/lib/sg_lib.c): `lib/sg_lib.c`
- [Decode tables](https://github.com/johnpgarry/sg3_utils/blob/master/lib/sg_lib_data.c): `lib/sg_lib_data.c`

### Pass-through transport

- [Linux transport](https://github.com/johnpgarry/sg3_utils/blob/master/lib/sg_pt_linux.c): `lib/sg_pt_linux.c`
- [Linux NVMe](https://github.com/johnpgarry/sg3_utils/blob/master/lib/sg_pt_linux_nvme.c): `lib/sg_pt_linux_nvme.c`
- [FreeBSD transport](https://github.com/johnpgarry/sg3_utils/blob/master/lib/sg_pt_freebsd.c): `lib/sg_pt_freebsd.c`
- [Windows transport](https://github.com/johnpgarry/sg3_utils/blob/master/lib/sg_pt_win32.c): `lib/sg_pt_win32.c`

### Runtime interfaces

- [Basic command API](https://github.com/johnpgarry/sg3_utils/blob/master/include/sg_cmds_basic.h): `include/sg_cmds_basic.h`
- [Extended command API](https://github.com/johnpgarry/sg3_utils/blob/master/include/sg_cmds_extra.h): `include/sg_cmds_extra.h`
- [Library API](https://github.com/johnpgarry/sg3_utils/blob/master/include/sg_lib.h): `include/sg_lib.h`
- [Data definitions](https://github.com/johnpgarry/sg3_utils/blob/master/include/sg_lib_data.h): `include/sg_lib_data.h`
- [Pass-through API](https://github.com/johnpgarry/sg3_utils/blob/master/include/sg_pt.h): `include/sg_pt.h`
- [Linux I/O definitions](https://github.com/johnpgarry/sg3_utils/blob/master/include/sg_io_linux.h): `include/sg_io_linux.h`
- [Linux definitions](https://github.com/johnpgarry/sg3_utils/blob/master/include/sg_linux_inc.h): `include/sg_linux_inc.h`
- [NVMe interface](https://github.com/johnpgarry/sg3_utils/blob/master/include/sg_pt_nvme.h): `include/sg_pt_nvme.h`
- [Windows interface](https://github.com/johnpgarry/sg3_utils/blob/master/include/sg_pt_win32.h): `include/sg_pt_win32.h`
- [Diagnostics output](https://github.com/johnpgarry/sg3_utils/blob/master/include/sg_pr2serr.h): `include/sg_pr2serr.h`
- [Byte conversions](https://github.com/johnpgarry/sg3_utils/blob/master/include/sg_unaligned.h): `include/sg_unaligned.h`
- [SG kernel interface](https://github.com/johnpgarry/sg3_utils/blob/master/testing/uapi_sg.h): `testing/uapi_sg.h`
- [Linux pass-through API](https://github.com/johnpgarry/sg3_utils/blob/master/include/sg_pt_linux.h): `include/sg_pt_linux.h`
- [Name tables API](https://github.com/johnpgarry/sg3_utils/blob/master/include/sg_lib_names.h): `include/sg_lib_names.h`

### Other components

- **Operator**
- **Storage device**

## Connections

- Operator → SCSI utilities: invokes (evidence: `README`)
- Operator → Raw commands: invokes (evidence: `README`)
- Operator → Copy utilities: invokes (evidence: `README`)
- SCSI utilities → Basic commands: requests commands
- Raw commands → Pass-through API: submits commands
- Copy utilities → Basic commands: requests I/O
- Inquiry → Basic command API: uses command API (evidence: `src/sg_inq.c`)
- Inquiry → Pass-through API: uses pass-through (evidence: `src/sg_inq.c`)
- Log pages → Basic command API: uses command API (evidence: `src/sg_logs.c`)
- Log pages → Pass-through API: uses pass-through (evidence: `src/sg_logs.c`)
- Enclosure services → Basic command API: uses command API (evidence: `src/sg_ses.c`)
- Enclosure services → Extended command API: uses extended API (evidence: `src/sg_ses.c`)
- Enclosure services → Pass-through API: uses pass-through (evidence: `src/sg_ses.c`)
- VPD data → Basic command API: uses command API (evidence: `src/sg_vpd.c`)
- Zone query → Basic command API: uses command API (evidence: `src/sg_z_act_query.c`)
- Basic commands → Pass-through API: uses pass-through
- Extended commands → Pass-through API: uses pass-through (evidence: `lib/sg_cmds_extra.c`)
- SCSI decoding → Decode tables: uses tables (evidence: `lib/sg_lib.c`)
- SCSI decoding → Data definitions: uses definitions (evidence: `lib/sg_lib.c`)
- Inquiry → Storage device: queries SCSI or NVMe (evidence: `README`)
- Enclosure services → Storage device: queries SCSI or NVMe (evidence: `README`)
- SCSI utilities → Storage device: sends SCSI commands (evidence: `README`)
- Copy utilities → Storage device: copies device data (evidence: `README`)
- Pass-through API → Linux transport: implemented by
- Pass-through API → FreeBSD transport: implemented by (evidence: `lib/sg_pt_freebsd.c`)
- Pass-through API → Windows transport: implemented by (evidence: `lib/sg_pt_win32.c`)
- Linux transport → Linux NVMe: supports NVMe (evidence: `lib/sg_pt_linux_nvme.c`)
- Linux transport → Linux I/O definitions: uses definitions
- Linux transport → Linux pass-through API: uses interface
- Linux NVMe → NVMe interface: uses interface (evidence: `lib/sg_pt_linux_nvme.c`)
- FreeBSD transport → NVMe interface: uses interface (evidence: `lib/sg_pt_freebsd.c`)
- Windows transport → Windows interface: uses interface (evidence: `lib/sg_pt_win32.c`)
- Linux I/O definitions → Linux definitions: includes definitions (evidence: `include/sg_io_linux.h`)
- SG kernel interface → Linux I/O definitions: complements interface
- Basic command API → Diagnostics output: documents output
- Library API → Byte conversions: supports decoding
- Name tables API → Data definitions: uses definitions (evidence: `include/sg_lib_names.h`)