{
    "mode": "man",
    "parameter": "sg_stream_ctl",
    "section": "8",
    "url": "https://www.chedong.com/phpMan.php/man/sg_stream_ctl/8/json",
    "generated": "2026-06-10T16:22:36Z",
    "synopsis": "sgstreamctl  [--brief]  [--close]  [--ctl=CTL]  [--get]  [--help] [--id=SID] [--maxlen=LEN]\n[--open] [--readonly] [--verbose] [--version] DEVICE",
    "sections": {
        "NAME": {
            "content": "sgstreamctl - send SCSI STREAM CONTROL or GET STREAM STATUS command\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "sgstreamctl  [--brief]  [--close]  [--ctl=CTL]  [--get]  [--help] [--id=SID] [--maxlen=LEN]\n[--open] [--readonly] [--verbose] [--version] DEVICE\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "Sends a SCSI STREAM CONTROL or GET STREAM STATUS command to the DEVICE.  These commands,  to‐\ngether with WRITE STREAM(16 and 32) and several fields in the Block Limits Extension VPD page\n[0xb7] support the streams concept.  The stream commands were added in SBC-4 draft 8 (Septem‐\nber 2015).\n\nBoth  STREAM  CONTROL and GET STREAM STATUS commands expect data from the DEVICE (referred to\nas 'data-in'). In the case of STREAM CONTROL only the 'open' (STRCTL<--0x1)  actually  needs\nthe  data-in as it contains the \"Assigned stream id\" if the open was successful. The assigned\nstream id should be used by subsequent WRITE STREAM commands and  ultimately  by  the  STREAM\nCONTROL close (STRCTL<--0x2). Valid stream ids are between 1 and 65535 inclusive.\n",
            "subsections": []
        },
        "OPTIONS": {
            "content": "Arguments to long options are mandatory for short options as well.\n",
            "subsections": [
                {
                    "name": "-b --brief",
                    "content": "this option reduces the output of the GET STREAM STATUS command to just one number (in\ndecimal) per line sent to stdout. Those numbers are the currently open stream ids.  If\nan  error  occurs  then  -1  is  sent to stdout and error related messages are sent to\nstderr. The default is to print more words (and fields) from the GET STREAM STATUS re‐\nsponse.\n",
                    "flag": "-b",
                    "long": "--brief"
                },
                {
                    "name": "-c --close",
                    "content": "selects  the  STREAM  CONTROL  command  and  sets  STRCTL<--0x2  (i.e. 'close').  The\n--id=SID option should also be given because it defaults to 0 which  is  not  a  valid\nstream id.\n",
                    "flag": "-c",
                    "long": "--close"
                },
                {
                    "name": "-C --ctl",
                    "content": "CTL  is  the value placed in the STRCTL field of the STREAM CONTROL command (cdb). It\nis a two bit field so has 4 variants: 0 and 3 are reserved; 1 opens are new stream and\n2  closes  the given stream id. '--ctl=1' is equivalent to '--open' while '--ctl=2' is\nequivalent to '--close'.\n",
                    "flag": "-C",
                    "long": "--ctl"
                },
                {
                    "name": "-g --get",
                    "content": "selects the GET STREAM STATUS command. If the --id=SID option is also  given  the  the\nresponse  starts  lists open stream ids from and including SID. If the --id=SID option\nis not given (or SID is 0) then all open stream id will be returned  in  the  response\n(data-in)  as  long as the allocation length (defaults to 248 bytes which can be over‐\nridden by the --maxlen=LEN option) is long enough. This is the default action of  this\nutility (i.e. GET STREAM STATUS command) if no \"selecting\" options are given.\n",
                    "flag": "-g",
                    "long": "--get"
                },
                {
                    "name": "-h --help",
                    "content": "output the usage message then exit.\n",
                    "flag": "-h",
                    "long": "--help"
                },
                {
                    "name": "-i --id",
                    "content": "SID  is a stream id, a value between 1 and 65535. It is used by STREAM CONTROL (close)\nto identify the stream to close. It is used by the GET STREAM STATUS  command  as  the\nstarting stream id (from and including); so stream ids that are less than SID will not\nappear in the response.\n",
                    "flag": "-i",
                    "long": "--id"
                },
                {
                    "name": "-m --maxlen",
                    "content": "LEN is the maximum length the response can be. It becomes the ALLOCATION LENGTH  field\nin  both  commands.  The default (in the absence of this option) is 8 bytes for STREAM\nCONTROL and 248 bytes for GET STREAM STATUS.\n",
                    "flag": "-m",
                    "long": "--maxlen"
                },
                {
                    "name": "-o --open",
                    "content": "selects the STREAM CONTROL command and  sets  STRCTL<--0x1  (i.e.  'open').   If  the\n--id=SID  option  is given then it is ignored. The user should observe the response as\nthe \"Assigned stream id\" is printed on stdout if the open is successful, if  not  '-1'\nis sent to stdout and error messages are sent to stderr. If the --brief option is also\ngiven then the only thing sent to stdout is a number of the assigned stream id  (1  to\n65535 inclusive) or '-1' if there is an error.\n",
                    "flag": "-o",
                    "long": "--open"
                },
                {
                    "name": "-r --readonly",
                    "content": "this  option  sets  a  'read-only' flag when the underlying operating system opens the\ngiven DEVICE. This may not work since  operating  systems  can  not  easily  determine\nwhether  a  pass-through command is a logical read or write operation on the media (or\nits metadata) so they take a risk averse stance and require  read-write  type  permis‐\nsions on the DEVICE open irrespective of what is performed by the pass-through.\n",
                    "flag": "-r",
                    "long": "--readonly"
                },
                {
                    "name": "-v --verbose",
                    "content": "increase the level of verbosity, (i.e. debug output).\n",
                    "flag": "-v",
                    "long": "--verbose"
                },
                {
                    "name": "-V --version",
                    "content": "print the version string and then exit.\n",
                    "flag": "-V",
                    "long": "--version"
                }
            ]
        },
        "NOTES": {
            "content": "There  are no special read commands for streams. This implies that \"normal\" READs (6, 10, 12,\n16 or 32) can be used. Note that when a stream is closed, all resources associated with  that\nstream id are removed, apart from the data in the written LBAs. To make sure the reading back\ndata is not delayed too much by error recovery (in the presence of media errors) the user may\nset  the  RECOVERY  TIME  LIMIT  field  (RTL, units for non-zero values: milliseconds) in the\n'Read-write error recovery' mode page. This can be done with the sdparm utility.\n\nThe SCSI WRITE STREAM (16 and 32) commands can be found in the  sgwritex  utility  in  this\npackage.\n",
            "subsections": []
        },
        "EXIT STATUS": {
            "content": "The  exit  status of sgstreamctl is 0 when it is successful. Otherwise see the sg3utils(8)\nman page.\n",
            "subsections": []
        },
        "AUTHORS": {
            "content": "Written by Douglas Gilbert.\n",
            "subsections": []
        },
        "REPORTING BUGS": {
            "content": "Report bugs to <dgilbert at interlog dot com>.\n",
            "subsections": []
        },
        "COPYRIGHT": {
            "content": "Copyright © 2018 Douglas Gilbert\nThis software is distributed under a FreeBSD license. There is NO warranty; not even for MER‐\nCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "sgvpd,sgwritex(sg3utils); sdparm(sdparm)\n\n\n\nsg3utils-1.43                               March 2018                             SGSTREAMCTL(8)",
            "subsections": []
        }
    },
    "summary": "sgstreamctl - send SCSI STREAM CONTROL or GET STREAM STATUS command",
    "flags": [
        {
            "flag": "-b",
            "long": "--brief",
            "arg": null,
            "description": "this option reduces the output of the GET STREAM STATUS command to just one number (in decimal) per line sent to stdout. Those numbers are the currently open stream ids. If an error occurs then -1 is sent to stdout and error related messages are sent to stderr. The default is to print more words (and fields) from the GET STREAM STATUS re‐ sponse."
        },
        {
            "flag": "-c",
            "long": "--close",
            "arg": null,
            "description": "selects the STREAM CONTROL command and sets STRCTL<--0x2 (i.e. 'close'). The --id=SID option should also be given because it defaults to 0 which is not a valid stream id."
        },
        {
            "flag": "-C",
            "long": "--ctl",
            "arg": null,
            "description": "CTL is the value placed in the STRCTL field of the STREAM CONTROL command (cdb). It is a two bit field so has 4 variants: 0 and 3 are reserved; 1 opens are new stream and 2 closes the given stream id. '--ctl=1' is equivalent to '--open' while '--ctl=2' is equivalent to '--close'."
        },
        {
            "flag": "-g",
            "long": "--get",
            "arg": null,
            "description": "selects the GET STREAM STATUS command. If the --id=SID option is also given the the response starts lists open stream ids from and including SID. If the --id=SID option is not given (or SID is 0) then all open stream id will be returned in the response (data-in) as long as the allocation length (defaults to 248 bytes which can be over‐ ridden by the --maxlen=LEN option) is long enough. This is the default action of this utility (i.e. GET STREAM STATUS command) if no \"selecting\" options are given."
        },
        {
            "flag": "-h",
            "long": "--help",
            "arg": null,
            "description": "output the usage message then exit."
        },
        {
            "flag": "-i",
            "long": "--id",
            "arg": null,
            "description": "SID is a stream id, a value between 1 and 65535. It is used by STREAM CONTROL (close) to identify the stream to close. It is used by the GET STREAM STATUS command as the starting stream id (from and including); so stream ids that are less than SID will not appear in the response."
        },
        {
            "flag": "-m",
            "long": "--maxlen",
            "arg": null,
            "description": "LEN is the maximum length the response can be. It becomes the ALLOCATION LENGTH field in both commands. The default (in the absence of this option) is 8 bytes for STREAM CONTROL and 248 bytes for GET STREAM STATUS."
        },
        {
            "flag": "-o",
            "long": "--open",
            "arg": null,
            "description": "selects the STREAM CONTROL command and sets STRCTL<--0x1 (i.e. 'open'). If the --id=SID option is given then it is ignored. The user should observe the response as the \"Assigned stream id\" is printed on stdout if the open is successful, if not '-1' is sent to stdout and error messages are sent to stderr. If the --brief option is also given then the only thing sent to stdout is a number of the assigned stream id (1 to 65535 inclusive) or '-1' if there is an error."
        },
        {
            "flag": "-r",
            "long": "--readonly",
            "arg": null,
            "description": "this option sets a 'read-only' flag when the underlying operating system opens the given DEVICE. This may not work since operating systems can not easily determine whether a pass-through command is a logical read or write operation on the media (or its metadata) so they take a risk averse stance and require read-write type permis‐ sions on the DEVICE open irrespective of what is performed by the pass-through."
        },
        {
            "flag": "-v",
            "long": "--verbose",
            "arg": null,
            "description": "increase the level of verbosity, (i.e. debug output)."
        },
        {
            "flag": "-V",
            "long": "--version",
            "arg": null,
            "description": "print the version string and then exit."
        }
    ],
    "examples": [],
    "see_also": [
        {
            "name": "sgwritex",
            "section": "sg3utils",
            "url": "https://www.chedong.com/phpMan.php/man/sgwritex/sg3utils/json"
        },
        {
            "name": "sdparm",
            "section": "sdparm",
            "url": "https://www.chedong.com/phpMan.php/man/sdparm/sdparm/json"
        }
    ]
}