{ "content": [ { "type": "text", "text": "# sg_rbuf(8) (man)\n\n**Summary:** sgrbuf - reads data using SCSI READ BUFFER command\n\n**Synopsis:** sgrbuf [--buffer=EACH] [--dio] [--help] [--mmap] [--quick] [--size=OVERALL] [--verbose]\n[--version] DEVICE\nsgrbuf [-b=EACHKIB] [-d] [-m] [-q] [-s=OVERALLMIB] [-t] [-v] [-V] DEVICE\n\n## Flags\n\n| Flag | Long | Arg | Description |\n|------|------|-----|-------------|\n| -b | --buffer | — | where EACH is the number of bytes to be transferred by each READ BUFFER command. The default is the actual available buf |\n| -d | --dio | — | use direct IO if available. This option is only available if the DEVICE is a sg driver device node (e.g. /dev/sg1). In t |\n| -h | --help | — | print usage message then exit. |\n| -m | --mmap | — | use memory mapped IO if available. This option is only available if the DEVICE is a sg driver device node (e.g. /dev/sg1 |\n| -O | --old | — | Switch to older style options. Please use as first option. |\n| -q | --quick | — | only transfer the data into kernel buffers (typically by DMA from the SCSI adapter card) and do not move it into the use |\n| -s | --size | — | where OVERALL is the size of total transfer in bytes. The default is 200 MiB (200*1024*1024 bytes). The actual number of |\n| -t | --time | — | times the bulk data transfer component of this command. The elapsed time is printed out plus a MB/sec calculation. In th |\n| -v | --verbose | — | increase level of verbosity. Can be used multiple times. |\n| -V | --version | — | print out version string then exit. |\n\n## Examples\n\n- `On the test system /dev/sg0 corresponds to a fast disk on a U2W SCSI bus (max 80 MB/sec). The`\n- `disk specifications state that its cache is 4 MB.`\n- `$ time ./sgrbuf /dev/sg0`\n- `READ BUFFER reports: buffer capacity=3434944,`\n- `offset boundary=6`\n- `Read 200 MiB (actual 199 MiB, 209531584 bytes),`\n- `buffer size=3354 KiB`\n- `real 0m5.072s, user 0m0.000s, sys 0m2.280s`\n- `So that is approximately 40 MB/sec at 40 % utilization. Now with the addition of the \"-q\" op‐`\n- `tion this throughput improves and the utilization drops to 0%.`\n- `$ time ./sgrbuf -q /dev/sg0`\n- `READ BUFFER reports: buffer capacity=3434944,`\n- `offset boundary=6`\n- `Read 200 MiB (actual 199 MiB, 209531584 bytes),`\n- `buffer size=3354 KiB`\n- `real 0m2.784s, user 0m0.000s, sys 0m0.000s`\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **SYNOPSIS** (5 lines)\n- **DESCRIPTION** (18 lines)\n- **OPTIONS** (2 lines) — 10 subsections\n - -b --buffer (6 lines)\n - -d --dio (6 lines)\n - -h --help (2 lines)\n - -m --mmap (5 lines)\n - -O --old (2 lines)\n - -q --quick (4 lines)\n - -s --size (5 lines)\n - -t --time (4 lines)\n - -v --verbose (2 lines)\n - -V --version (2 lines)\n- **NOTES** (9 lines)\n- **EXAMPLES** (18 lines)\n- **EXIT STATUS** (3 lines)\n- **OLDER COMMAND LINE OPTIONS** (5 lines) — 9 subsections\n - -b (4 lines)\n - -d (1 lines)\n - -m (2 lines)\n - -N --new (2 lines)\n - -q (3 lines)\n - -s (3 lines)\n - -t (2 lines)\n - -v (1 lines)\n - -V (1 lines)\n- **ENVIRONMENT VARIABLES** (5 lines)\n- **AUTHOR** (2 lines)\n- **REPORTING BUGS** (2 lines)\n- **COPYRIGHT** (4 lines)\n- **SEE ALSO** (5 lines)\n\n## Full Content\n\n### NAME\n\nsgrbuf - reads data using SCSI READ BUFFER command\n\n### SYNOPSIS\n\nsgrbuf [--buffer=EACH] [--dio] [--help] [--mmap] [--quick] [--size=OVERALL] [--verbose]\n[--version] DEVICE\n\nsgrbuf [-b=EACHKIB] [-d] [-m] [-q] [-s=OVERALLMIB] [-t] [-v] [-V] DEVICE\n\n### DESCRIPTION\n\nThis command reads data with the SCSI READ BUFFER command and then discards it. Typically the\ndata being read is from a disk's memory cache. It is assumed that the data is sourced quickly\n(although this is not guaranteed by the SCSI standards) so that it is faster than reading\ndata from the media. This command is designed for timing transfer speeds across a SCSI\ntransport.\n\nTo fetch the data with a SCSI READ BUFFER command and optionally decode it see the\nsgreadbuffer utility. There is also a sgwritebuffer utility useful for downloading\nfirmware amongst other things.\n\nThis utility supports two command line syntaxes, the preferred one is shown first in the syn‐\nopsis and explained in this section. A later section on the old command line syntax outlines\nthe second group of options.\n\nThis is a Linux only utility and only works when DEVICE is an sg device (e.g. \"/dev/sg1\").\nThe sgreadbuffer utility has similar functionality and is ported to other OSes and within\nLinux can use bsg and normal block device names (e.g. \"/dev/sdc\").\n\n### OPTIONS\n\nArguments to long options are mandatory for short options as well.\n\n#### -b --buffer\n\nwhere EACH is the number of bytes to be transferred by each READ BUFFER command. The\ndefault is the actual available buffer size returned by the READ BUFFER (descriptor)\ncommand. The maximum is the same as the default, hence this argument can only be used\nto reduce the size of each transfer to less than the device's actual available buffer\nsize.\n\n#### -d --dio\n\nuse direct IO if available. This option is only available if the DEVICE is a sg driver\ndevice node (e.g. /dev/sg1). In this case the sg driver will attempt to configure the\nDMA from the SCSI adapter to transfer directly into user memory. This will eliminate\nthe copy via kernel buffers. If not available then this will be reported and indirect\nIO will be done instead.\n\n#### -h --help\n\nprint usage message then exit.\n\n#### -m --mmap\n\nuse memory mapped IO if available. This option is only available if the DEVICE is a sg\ndriver device node (e.g. /dev/sg1). In this case the sg driver will attempt to config‐\nure the DMA from the SCSI adapter to transfer directly into user memory. This will\neliminate the copy via kernel buffers.\n\n#### -O --old\n\nSwitch to older style options. Please use as first option.\n\n#### -q --quick\n\nonly transfer the data into kernel buffers (typically by DMA from the SCSI adapter\ncard) and do not move it into the user space. This option is only available if the DE‐\nVICE is a sg driver device node (e.g. /dev/sg1).\n\n#### -s --size\n\nwhere OVERALL is the size of total transfer in bytes. The default is 200 MiB\n(200*1024*1024 bytes). The actual number of bytes transferred may be slightly less\nthan requested since all transfers are the same size (and an integer division is in‐\nvolved rounding towards zero).\n\n#### -t --time\n\ntimes the bulk data transfer component of this command. The elapsed time is printed\nout plus a MB/sec calculation. In this case \"MB\" is 1,000,000 bytes. The gettimeof‐\nday() system call is used internally for the time calculation.\n\n#### -v --verbose\n\nincrease level of verbosity. Can be used multiple times.\n\n#### -V --version\n\nprint out version string then exit.\n\n### NOTES\n\nThis command is typically used on modern SCSI disks which have a RAM cache in their drive\nelectronics. If no IO to the magnetic media, or slower devices like flash RAM, is involved\nthen the disk may be able to source data fast enough to saturate the bandwidth of the SCSI\ntransport. The bottleneck may then be the DMA element in the HBA, the Linux drivers or the\nhost machine's hardware (e.g. speed of RAM).\n\nVarious numeric arguments (e.g. OVERALL) may include multiplicative suffixes or be given in\nhexadecimal. See the \"NUMERIC ARGUMENTS\" section in the sg3utils(8) man page.\n\n### EXAMPLES\n\nOn the test system /dev/sg0 corresponds to a fast disk on a U2W SCSI bus (max 80 MB/sec). The\ndisk specifications state that its cache is 4 MB.\n$ time ./sgrbuf /dev/sg0\nREAD BUFFER reports: buffer capacity=3434944,\noffset boundary=6\nRead 200 MiB (actual 199 MiB, 209531584 bytes),\nbuffer size=3354 KiB\nreal 0m5.072s, user 0m0.000s, sys 0m2.280s\n\nSo that is approximately 40 MB/sec at 40 % utilization. Now with the addition of the \"-q\" op‐\ntion this throughput improves and the utilization drops to 0%.\n$ time ./sgrbuf -q /dev/sg0\nREAD BUFFER reports: buffer capacity=3434944,\noffset boundary=6\nRead 200 MiB (actual 199 MiB, 209531584 bytes),\nbuffer size=3354 KiB\nreal 0m2.784s, user 0m0.000s, sys 0m0.000s\n\n### EXIT STATUS\n\nThe exit status of sgrbuf is 0 when it is successful. Otherwise see the sg3utils(8) man\npage.\n\n### OLDER COMMAND LINE OPTIONS\n\nThe options in this section were the only ones available prior to sg3utils version 1.23 .\nSince then this utility defaults to the newer command line options which can be overridden by\nusing --old (or -O) as the first option. See the ENVIRONMENT VARIABLES section for another\nway to force the use of these older command line options.\n\n#### -b\n\nwhere EACHKIB is the number of Kilobytes (i.e. 1024 byte units) to be transferred by\neach READ BUFFER command. Similar to the --buffer=EACH option in the main description\nbut the units are different.\n\n#### -d\n\n#### -m\n\nscription.\n\n#### -N --new\n\nSwitch to the newer style options.\n\n#### -q\n\ncard) and do not move it into the user space. Equivalent to the --quick option in the\nmain description.\n\n#### -s\n\nwhere OVERALLMIB is the size of total transfer in Megabytes (1048576 bytes). Similar\nto the --size=OVERALL option in the main description but the units are different.\n\n#### -t\n\ntion in the main description.\n\n#### -v\n\n#### -V\n\n### ENVIRONMENT VARIABLES\n\nSince sg3utils version 1.23 the environment variable SG3UTILSOLDOPTS can be given. When\nit is present this utility will expect the older command line options. So the presence of\nthis environment variable is equivalent to using --old (or -O) as the first command line op‐\ntion.\n\n### AUTHOR\n\nWritten by Douglas Gilbert\n\n### REPORTING BUGS\n\nReport bugs to .\n\n### COPYRIGHT\n\nCopyright © 2000-2017 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\nsgreadbuffer, sgwritebuffer, sgtestrwbuf(all in sg3utils)\n\n\n\nsg3utils-1.43 October 2017 SGRBUF(8)\n\n" } ], "structuredContent": { "command": "sg_rbuf", "section": "8", "mode": "man", "summary": "sgrbuf - reads data using SCSI READ BUFFER command", "synopsis": "sgrbuf [--buffer=EACH] [--dio] [--help] [--mmap] [--quick] [--size=OVERALL] [--verbose]\n[--version] DEVICE\nsgrbuf [-b=EACHKIB] [-d] [-m] [-q] [-s=OVERALLMIB] [-t] [-v] [-V] DEVICE", "flags": [ { "flag": "-b", "long": "--buffer", "arg": null, "description": "where EACH is the number of bytes to be transferred by each READ BUFFER command. The default is the actual available buffer size returned by the READ BUFFER (descriptor) command. The maximum is the same as the default, hence this argument can only be used to reduce the size of each transfer to less than the device's actual available buffer size." }, { "flag": "-d", "long": "--dio", "arg": null, "description": "use direct IO if available. This option is only available if the DEVICE is a sg driver device node (e.g. /dev/sg1). In this case the sg driver will attempt to configure the DMA from the SCSI adapter to transfer directly into user memory. This will eliminate the copy via kernel buffers. If not available then this will be reported and indirect IO will be done instead." }, { "flag": "-h", "long": "--help", "arg": null, "description": "print usage message then exit." }, { "flag": "-m", "long": "--mmap", "arg": null, "description": "use memory mapped IO if available. This option is only available if the DEVICE is a sg driver device node (e.g. /dev/sg1). In this case the sg driver will attempt to config‐ ure the DMA from the SCSI adapter to transfer directly into user memory. This will eliminate the copy via kernel buffers." }, { "flag": "-O", "long": "--old", "arg": null, "description": "Switch to older style options. Please use as first option." }, { "flag": "-q", "long": "--quick", "arg": null, "description": "only transfer the data into kernel buffers (typically by DMA from the SCSI adapter card) and do not move it into the user space. This option is only available if the DE‐ VICE is a sg driver device node (e.g. /dev/sg1)." }, { "flag": "-s", "long": "--size", "arg": null, "description": "where OVERALL is the size of total transfer in bytes. The default is 200 MiB (200*1024*1024 bytes). The actual number of bytes transferred may be slightly less than requested since all transfers are the same size (and an integer division is in‐ volved rounding towards zero)." }, { "flag": "-t", "long": "--time", "arg": null, "description": "times the bulk data transfer component of this command. The elapsed time is printed out plus a MB/sec calculation. In this case \"MB\" is 1,000,000 bytes. The gettimeof‐ day() system call is used internally for the time calculation." }, { "flag": "-v", "long": "--verbose", "arg": null, "description": "increase level of verbosity. Can be used multiple times." }, { "flag": "-V", "long": "--version", "arg": null, "description": "print out version string then exit." } ], "examples": [ "On the test system /dev/sg0 corresponds to a fast disk on a U2W SCSI bus (max 80 MB/sec). The", "disk specifications state that its cache is 4 MB.", "$ time ./sgrbuf /dev/sg0", "READ BUFFER reports: buffer capacity=3434944,", "offset boundary=6", "Read 200 MiB (actual 199 MiB, 209531584 bytes),", "buffer size=3354 KiB", "real 0m5.072s, user 0m0.000s, sys 0m2.280s", "So that is approximately 40 MB/sec at 40 % utilization. Now with the addition of the \"-q\" op‐", "tion this throughput improves and the utilization drops to 0%.", "$ time ./sgrbuf -q /dev/sg0", "READ BUFFER reports: buffer capacity=3434944,", "offset boundary=6", "Read 200 MiB (actual 199 MiB, 209531584 bytes),", "buffer size=3354 KiB", "real 0m2.784s, user 0m0.000s, sys 0m0.000s" ], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 5, "subsections": [] }, { "name": "DESCRIPTION", "lines": 18, "subsections": [] }, { "name": "OPTIONS", "lines": 2, "subsections": [ { "name": "-b --buffer", "lines": 6, "flag": "-b", "long": "--buffer" }, { "name": "-d --dio", "lines": 6, "flag": "-d", "long": "--dio" }, { "name": "-h --help", "lines": 2, "flag": "-h", "long": "--help" }, { "name": "-m --mmap", "lines": 5, "flag": "-m", "long": "--mmap" }, { "name": "-O --old", "lines": 2, "flag": "-O", "long": "--old" }, { "name": "-q --quick", "lines": 4, "flag": "-q", "long": "--quick" }, { "name": "-s --size", "lines": 5, "flag": "-s", "long": "--size" }, { "name": "-t --time", "lines": 4, "flag": "-t", "long": "--time" }, { "name": "-v --verbose", "lines": 2, "flag": "-v", "long": "--verbose" }, { "name": "-V --version", "lines": 2, "flag": "-V", "long": "--version" } ] }, { "name": "NOTES", "lines": 9, "subsections": [] }, { "name": "EXAMPLES", "lines": 18, "subsections": [] }, { "name": "EXIT STATUS", "lines": 3, "subsections": [] }, { "name": "OLDER COMMAND LINE OPTIONS", "lines": 5, "subsections": [ { "name": "-b", "lines": 4, "flag": "-b" }, { "name": "-d", "lines": 1, "flag": "-d" }, { "name": "-m", "lines": 2, "flag": "-m" }, { "name": "-N --new", "lines": 2, "flag": "-N", "long": "--new" }, { "name": "-q", "lines": 3, "flag": "-q" }, { "name": "-s", "lines": 3, "flag": "-s" }, { "name": "-t", "lines": 2, "flag": "-t" }, { "name": "-v", "lines": 1, "flag": "-v" }, { "name": "-V", "lines": 1, "flag": "-V" } ] }, { "name": "ENVIRONMENT VARIABLES", "lines": 5, "subsections": [] }, { "name": "AUTHOR", "lines": 2, "subsections": [] }, { "name": "REPORTING BUGS", "lines": 2, "subsections": [] }, { "name": "COPYRIGHT", "lines": 4, "subsections": [] }, { "name": "SEE ALSO", "lines": 5, "subsections": [] } ] } }