{
  "slug": "sg-io-residual-count",
  "term": "SG_IO residual count",
  "aliases": [
    "sg_io_hdr.resid"
  ],
  "definition": "The SG_IO residual count is a signed byte count reporting the difference between the requested data-transfer length and the length actually transferred through the Linux SCSI generic v3 interface.",
  "note": "The ABI defines resid as dxfer_len minus actual transferred bytes. It is not a command status or the length of sense data; sb_len_wr reports the latter. [linux-sgio-header]\n\nLinux v6.12's block-device SG_IO completion copies SCSI and host status into separate fields. Its system-call result can remain successful while those fields report a problem. Inspect the complete response before interpreting transferred data. [linux-sgio-completion]\n\nA positive residual need not mean failure when the command permits a shorter response. Conversely, the historical SG HOWTO warns that unsupported or inaccurate reporting can yield misleading values, including zero. That warning is not a measurement of current adapters: validate the reporting path and the command's expected length. [sg-resid-howto]",
  "status": "shipping",
  "advantages": [],
  "limitations": [],
  "related": [
    "scsi",
    "scsi-check-condition",
    "scsi-deferred-error"
  ],
  "supersedes": [],
  "supersededBy": [],
  "firstSeen": null,
  "lastSeen": null,
  "updated": "2026-10-25",
  "citations": [
    {
      "id": "linux-sgio-header",
      "title": "Linux v6.12: sg_io_hdr fields and SG_INFO status mask",
      "url": "https://github.com/torvalds/linux/blob/v6.12/include/scsi/sg.h",
      "accessed": "2026-10-25"
    },
    {
      "id": "linux-sgio-completion",
      "title": "Linux v6.12: scsi_complete_sghdr_rq and sg_io in scsi_ioctl.c",
      "url": "https://github.com/torvalds/linux/blob/v6.12/drivers/scsi/scsi_ioctl.c",
      "accessed": "2026-10-25"
    },
    {
      "id": "sg-resid-howto",
      "title": "Douglas Gilbert, Linux SCSI Generic HOWTO, section 6.20: resid (historical driver caveat)",
      "url": "https://tldp.org/HOWTO/SCSI-Generic-HOWTO/x356.html",
      "accessed": "2026-10-25"
    },
    {
      "id": "hesela-sgio",
      "title": "Hesela: SG_IO completion is not one success bit",
      "url": "https://hesela.com/analyses/scsi-sense-kernel-log-signatures/#sgio-completion",
      "accessed": "2026-10-25"
    }
  ],
  "provenance": [
    "Source review of Linux v6.12 and the historical SG HOWTO. No commands sent to hardware, no driver-validation experiment and no measured failure rate."
  ]
}