{
    "content": [
        {
            "type": "text",
            "text": "# sg_read(8) (man)\n\n**Summary:** sgread - read multiple blocks of data, optionally with SCSI READ commands\n\n**Synopsis:** sgread  [blksgio=0|1]  [bpt=BPT] [bs=BS] [cdbsz=6|10|12|16] count=COUNT [dio=0|1] [dpo=0|1]\n[fua=0|1] if=IFILE [mmap=0|1] [nodxfer=0|1] [odir=0|1] [skip=SKIP] [time=TI]  [verbose=VERB]\n[--help] [--version]\n\n## Flags\n\n| Flag | Long | Arg | Description |\n|------|------|-----|-------------|\n| — | --version | — | Output the version string then exit. |\n\n## Examples\n\n- `Let us assume that /dev/sg0 is a disk and we wish to time the disk's cache performance.`\n- `sgread if=/dev/sg0 bs=512 count=1MB mmap=1 time=2`\n- `This  command  will continually read 128  512 byte blocks from block 0.  The \"128\" is the de‐`\n- `fault value for 'bpt' while \"block 0\" is chosen because the 'skip' argument  was  not  given.`\n- `This  will  continue  until 1,000,000 blocks are read. The idea behind using 'time=2' is that`\n- `the first 64 KiB read operation will involve reading the magnetic media while  the  remaining`\n- `read operations will \"hit\" the disk's cache. The output of third command will look like this:`\n- `time from second command to end was 4.50 secs, 113.70 MB/sec`\n- `Average number of READ commands per second was 1735.27`\n- `1000000+0 records in, SCSI commands issued: 7813`\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **SYNOPSIS** (4 lines)\n- **DESCRIPTION** (19 lines)\n- **OPTIONS** (78 lines) — 1 subsections\n  - --version (2 lines)\n- **NOTES** (10 lines)\n- **SIGNALS** (5 lines)\n- **EXAMPLES** (14 lines)\n- **EXIT STATUS** (3 lines)\n- **AUTHORS** (2 lines)\n- **REPORTING BUGS** (2 lines)\n- **COPYRIGHT** (4 lines)\n- **SEE ALSO** (2 lines) — 1 subsections\n  - raw(8), dd(1) (1 lines)\n\n## Full Content\n\n### NAME\n\nsgread - read multiple blocks of data, optionally with SCSI READ commands\n\n### SYNOPSIS\n\nsgread  [blksgio=0|1]  [bpt=BPT] [bs=BS] [cdbsz=6|10|12|16] count=COUNT [dio=0|1] [dpo=0|1]\n[fua=0|1] if=IFILE [mmap=0|1] [nodxfer=0|1] [odir=0|1] [skip=SKIP] [time=TI]  [verbose=VERB]\n[--help] [--version]\n\n### DESCRIPTION\n\nRead  data  from  a Linux SCSI generic (sg) device, a block device or a normal file with each\nread command issued to the same offset or logical block address (lba). This can  be  used  to\ntest  (or  time) disk caching, SCSI (or some other) transport throughput, and/or SCSI command\noverhead.\n\nWhen the COUNT value is positive, then up to BPT blocks are read at a time, until  the  COUNT\nis  exhausted. Each read operation starts at the same lba which, if SKIP is not given, is the\nbeginning of the file or device.\n\nThe COUNT value may be negative when IFILE  is  a  sg  device  or  is  a  block  device  with\n'blksgio=1'  set.  Alternatively  'bpt=0'  may be given. In these cases |COUNT| \"zero block\"\nSCSI READ commands are issued. \"Zero block\" means \"do nothing\" for SCSI READ 10,  12  and  16\nbyte  commands  (but not for the 6 byte variant). In practice \"zero block\" SCSI READ commands\nhave low latency and so are one way to measure SCSI command overhead.\n\nPlease note: this is a very old utility that uses 32 bit  integers  for  disk  LBAs  and  the\ncount.  Hence it will not be able to address beyond 2 Terabytes on a disk with logical blocks\nthat are 512 bytes long.  Alternatives are the sgdd and ddpt utilities.\n\n### OPTIONS\n\nblksgio=0 | 1\nThe default action of this utility is to use the Unix read() command when the IFILE is\na  block  device. In lk 2.6 many block devices can handle SCSI commands issued via the\nSGIO ioctl. So when this option is set the SGIO ioctl sends SCSI  READ  commands  to\nIFILE if it is a block device.\n\nbpt=BPT\nwhere  BPT  is the maximum number of blocks each read operation fetches.  Fewer blocks\nwill be fetched when the remaining COUNT is less than BPT. The default value  for  BPT\nis 128. Note that each read operation starts at the same lba (as given by skip=SKIP or\n0).  If 'bpt=0' then the COUNT is interpreted as the number of zero  block  SCSI  READ\ncommands to issue.\n\nbs=BS  where BS is the size (in bytes) of each block read. This must be the block size of the\nphysical device (defaults to 512) if SCSI commands are being issued to IFILE.\n\ncdbsz=6 | 10 | 12 | 16\nsize of SCSI READ commands issued on sg device names, or block devices if 'blksgio=1'\nis given. Default is 10 byte SCSI READ cdbs.\n\ncount=COUNT\nwhen  COUNT  is a positive number, read that number of blocks, typically with multiple\nread operations. When COUNT is negative then |COUNT| SCSI READ commands are  performed\nrequesting zero blocks to be transferred. This option is mandatory.\n\ndio=0 | 1\ndefault  is  0  which selects indirect IO. Value of 1 attempts direct IO which, if not\navailable, falls back to indirect IO and notes this at completion. This option is only\nactive if IFILE is an sg device.  If direct IO is selected and /proc/scsi/sg/allowdio\nhas the value of 0 then a warning is issued (and indirect IO is performed)\n\ndpo=0 | 1\nwhen set the disable page out (DPO) bit in SCSI READ commands is set.   Otherwise  the\nDPO bit is cleared (default).\n\nfua=0 | 1\nwhen  set the force unit access (FUA) bit in SCSI READ commands is set.  Otherwise the\nFUA bit is cleared (default).\n\nif=IFILE\nread from this IFILE. This argument must be given. If the IFILE is a normal file  then\nit  must  be seekable (if (COUNT > BPT) or skip=SKIP is given). Hence stdin is not ac‐\nceptable (and giving \"-\" as the IFILE argument is reported as an error).\n\nmmap=0 | 1\ndefault is 0 which selects indirect IO. Value of 1 causes memory mapped IO to be  per‐\nformed.  Selecting  both dio and mmap is an error. This option is only active if IFILE\nis an sg device.\n\nnodxfer=0 | 1\nwhen set then DMA transfers from the device are made into kernel buffers but  no  fur‐\nther  (i.e.  there  is  no second copy into the user space). The default value is 0 in\nwhich case transfers are made into the user space.  When neither mmap nor dio  is  set\nthen  data  transfer  are  copied  via kernel buffers (i.e. a double copy). Mainly for\ntesting.\n\nodir=0 | 1\nwhen set opens an IFILE which is a block device with an additional ODIRECT flag.  The\ndefault value is 0 (i.e. don't open block devices ODIRECT).\n\nskip=SKIP\nall  read  operations  will start offset by SKIP bs-sized blocks from the start of the\ninput file (or device).\n\ntime=TI\nWhen TI is 0 (default) doesn't perform  timing.   When  1,  times  transfer  and  does\nthroughput calculation, starting at the first issued command until completion. When 2,\ntimes transfer and does throughput calculation, starting at the second issued  command\nuntil  completion. When 3 times from third command, etc. An average number of commands\n(SCSI READs or Unix read()s) executed per second is also output.\n\nverbose=VERB\nas VERB increases so does the amount of debug output sent to stderr.  Default value is\nzero  which yields the minimum amount of debug output.  A value of 1 reports extra in‐\nformation that is not repetitive.\n\n--help Output the usage message then exit.\n\n#### --version\n\nOutput the version string then exit.\n\n### NOTES\n\nVarious numeric arguments (e.g. SKIP) may include multiplicative  suffixes  or  be  given  in\nhexadecimal. See the \"NUMERIC ARGUMENTS\" section in the sg3utils(8) man page.\n\nData  usually  gets  to the user space in a 2 stage process: first the SCSI adapter DMAs into\nkernel buffers and then the sg driver copies this data into user memory.  This is called \"in‐\ndirect  IO\"  and  there  is a \"dio\" option to select \"direct IO\" which will DMA directly into\nuser memory. Due to some issues \"direct IO\" is disabled in the sg driver and needs a configu‐\nration change to activate it. This is typically done with \"echo 1 > /proc/scsi/sg/allowdio\".\nAn alternate way to avoid the 2 stage copy is to select memory mapped IO with 'mmap=1'.\n\n### SIGNALS\n\nThe signal handling has been borrowed from dd: SIGINT, SIGQUIT and SIGPIPE output the  number\nof  remaining  blocks to be transferred; then they have their default action.  SIGUSR1 causes\nthe same information to be output yet the copy continues.  All output caused  by  signals  is\nsent to stderr.\n\n### EXAMPLES\n\nLet us assume that /dev/sg0 is a disk and we wish to time the disk's cache performance.\n\nsgread if=/dev/sg0 bs=512 count=1MB mmap=1 time=2\n\nThis  command  will continually read 128  512 byte blocks from block 0.  The \"128\" is the de‐\nfault value for 'bpt' while \"block 0\" is chosen because the 'skip' argument  was  not  given.\nThis  will  continue  until 1,000,000 blocks are read. The idea behind using 'time=2' is that\nthe first 64 KiB read operation will involve reading the magnetic media while  the  remaining\nread operations will \"hit\" the disk's cache. The output of third command will look like this:\n\ntime from second command to end was 4.50 secs, 113.70 MB/sec\nAverage number of READ commands per second was 1735.27\n1000000+0 records in, SCSI commands issued: 7813\n\n### EXIT STATUS\n\nThe  exit  status  of  sgread is 0 when it is successful. Otherwise see the sg3utils(8) man\npage.\n\n### AUTHORS\n\nWritten by Douglas Gilbert.\n\n### REPORTING BUGS\n\nReport bugs to <dgilbert at interlog dot com>.\n\n### COPYRIGHT\n\nCopyright © 2000-2019 Douglas Gilbert\nThis software is distributed under the GPL version 2. There is NO warranty; not even for MER‐\nCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n\n### SEE ALSO\n\nTo  time streaming media read or write time see sgdd is in the sg3utils package and ddpt in\na package of the same name.  The lmbench package contains lmdd  which  is  also  interesting.\n\n#### raw(8), dd(1)\n\nsg3utils-1.45                             September 2019                                 SGREAD(8)\n\n"
        }
    ],
    "structuredContent": {
        "command": "sg_read",
        "section": "8",
        "mode": "man",
        "summary": "sgread - read multiple blocks of data, optionally with SCSI READ commands",
        "synopsis": "sgread  [blksgio=0|1]  [bpt=BPT] [bs=BS] [cdbsz=6|10|12|16] count=COUNT [dio=0|1] [dpo=0|1]\n[fua=0|1] if=IFILE [mmap=0|1] [nodxfer=0|1] [odir=0|1] [skip=SKIP] [time=TI]  [verbose=VERB]\n[--help] [--version]",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [
            {
                "flag": "",
                "long": "--version",
                "arg": null,
                "description": "Output the version string then exit."
            }
        ],
        "examples": [
            "Let us assume that /dev/sg0 is a disk and we wish to time the disk's cache performance.",
            "sgread if=/dev/sg0 bs=512 count=1MB mmap=1 time=2",
            "This  command  will continually read 128  512 byte blocks from block 0.  The \"128\" is the de‐",
            "fault value for 'bpt' while \"block 0\" is chosen because the 'skip' argument  was  not  given.",
            "This  will  continue  until 1,000,000 blocks are read. The idea behind using 'time=2' is that",
            "the first 64 KiB read operation will involve reading the magnetic media while  the  remaining",
            "read operations will \"hit\" the disk's cache. The output of third command will look like this:",
            "time from second command to end was 4.50 secs, 113.70 MB/sec",
            "Average number of READ commands per second was 1735.27",
            "1000000+0 records in, SCSI commands issued: 7813"
        ],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 4,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 19,
                "subsections": []
            },
            {
                "name": "OPTIONS",
                "lines": 78,
                "subsections": [
                    {
                        "name": "--version",
                        "lines": 2,
                        "long": "--version"
                    }
                ]
            },
            {
                "name": "NOTES",
                "lines": 10,
                "subsections": []
            },
            {
                "name": "SIGNALS",
                "lines": 5,
                "subsections": []
            },
            {
                "name": "EXAMPLES",
                "lines": 14,
                "subsections": []
            },
            {
                "name": "EXIT STATUS",
                "lines": 3,
                "subsections": []
            },
            {
                "name": "AUTHORS",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "REPORTING BUGS",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "COPYRIGHT",
                "lines": 4,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 2,
                "subsections": [
                    {
                        "name": "raw(8), dd(1)",
                        "lines": 1
                    }
                ]
            }
        ]
    }
}