1SG_STREAM_CTL(8) SG3_UTILS SG_STREAM_CTL(8)
2
6 sg_stream_ctl - send SCSI STREAM CONTROL or GET STREAM STATUS command
7
9 sg_stream_ctl [--brief] [--close] [--ctl=CTL] [--get] [--help]
10 [--id=SID] [--maxlen=LEN] [--open] [--readonly] [--verbose] [--version]
11 DEVICE
12
14 Sends a SCSI STREAM CONTROL or GET STREAM STATUS command to the DEVICE.
15 These commands, together with WRITE STREAM(16 and 32) and several
16 fields in the Block Limits Extension VPD page [0xb7] support the
17 streams concept. The stream commands were added in SBC-4 draft 8 (Sep‐
18 tember 2015).
19 Both STREAM CONTROL and GET STREAM STATUS commands expect data from the
21 DEVICE (referred to as 'data-in'). In the case of STREAM CONTROL only
22 the 'open' (STR_CTL<--0x1) actually needs the data-in as it contains
23 the "Assigned stream id" if the open was successful. The assigned
24 stream id should be used by subsequent WRITE STREAM commands and ulti‐
25 mately by the STREAM CONTROL close (STR_CTL<--0x2). Valid stream ids
26 are between 1 and 65535 inclusive.
27
29 Arguments to long options are mandatory for short options as well.
30 -b, --brief
32 this option reduces the output of the GET STREAM STATUS command
33 to just one number (in decimal) per line sent to stdout. Those
34 numbers are the currently open stream ids. If an error occurs
35 then -1 is sent to stdout and error related messages are sent to
36 stderr. The default is to print more words (and fields) from the
37 GET STREAM STATUS response.
38 -c, --close
40 selects the STREAM CONTROL command and sets STR_CTL<--0x2 (i.e.
41 'close'). The --id=SID option should also be given because it
42 defaults to 0 which is not a valid stream id.
43 -C, --ctl=CTL
45 CTL is the value placed in the STR_CTL field of the STREAM CON‐
46 TROL command (cdb). It is a two bit field so has 4 variants: 0
47 and 3 are reserved; 1 opens are new stream and 2 closes the
48 given stream id. '--ctl=1' is equivalent to '--open' while
49 '--ctl=2' is equivalent to '--close'.
50 -g, --get
52 selects the GET STREAM STATUS command. If the --id=SID option is
53 also given the the response starts lists open stream ids from
54 and including SID. If the --id=SID option is not given (or SID
55 is 0) then all open stream id will be returned in the response
56 (data-in) as long as the allocation length (defaults to 248
57 bytes which can be overridden by the --maxlen=LEN option) is
58 long enough. This is the default action of this utility (i.e.
59 GET STREAM STATUS command) if no "selecting" options are given.
60 -h, --help
62 output the usage message then exit.
63 -i, --id=SID
65 SID is a stream id, a value between 1 and 65535. It is used by
66 STREAM CONTROL (close) to identify the stream to close. It is
67 used by the GET STREAM STATUS command as the starting stream id
68 (from and including); so stream ids that are less than SID will
69 not appear in the response.
70 -m, --maxlen=LEN
72 LEN is the maximum length the response can be. It becomes the
73 ALLOCATION LENGTH field in both commands. The default (in the
74 absence of this option) is 8 bytes for STREAM CONTROL and 248
75 bytes for GET STREAM STATUS.
76 -o, --open
78 selects the STREAM CONTROL command and sets STR_CTL<--0x1 (i.e.
79 'open'). If the --id=SID option is given then it is ignored.
80 The user should observe the response as the "Assigned stream id"
81 is printed on stdout if the open is successful, if not '-1' is
82 sent to stdout and error messages are sent to stderr. If the
83 --brief option is also given then the only thing sent to stdout
84 is a number of the assigned stream id (1 to 65535 inclusive) or
85 '-1' if there is an error.
86 -r, --readonly
88 this option sets a 'read-only' flag when the underlying operat‐
89 ing system opens the given DEVICE. This may not work since oper‐
90 ating systems can not easily determine whether a pass-through
91 command is a logical read or write operation on the media (or
92 its metadata) so they take a risk averse stance and require
93 read-write type permissions on the DEVICE open irrespective of
94 what is performed by the pass-through.
95 -v, --verbose
97 increase the level of verbosity, (i.e. debug output).
98 -V, --version
100 print the version string and then exit.
101
103 There are no special read commands for streams. This implies that "nor‐
104 mal" READs (6, 10, 12, 16 or 32) can be used. Note that when a stream
105 is closed, all resources associated with that stream id are removed,
106 apart from the data in the written LBAs. To make sure the reading back
107 data is not delayed too much by error recovery (in the presence of
108 media errors) the user may set the RECOVERY TIME LIMIT field (RTL,
109 units for non-zero values: milliseconds) in the 'Read-write error
110 recovery' mode page. This can be done with the sdparm utility.
111 The SCSI WRITE STREAM (16 and 32) commands can be found in the
113 sg_write_x utility in this package.
114
116 The exit status of sg_stream_ctl is 0 when it is successful. Otherwise
117 see the sg3_utils(8) man page.
118
120 Written by Douglas Gilbert.
121
123 Report bugs to <dgilbert at interlog dot com>.
124
126 Copyright © 2018 Douglas Gilbert
127 This software is distributed under a FreeBSD license. There is NO war‐
128 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
129 POSE.
130
132 sg_vpd,sg_write_x(sg3_utils); sdparm(sdparm)
133sg3_utils-1.43 March 2018 SG_STREAM_CTL(8)