1 .\" Copyright (c) 2017, Joyent, Inc.
2 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright 1989 AT&T
4 .\" The contents of this file are subject to the terms of the
5 .\" Common Development and Distribution License (the "License").
6 .\" You may not use this file except in compliance with the License.
7 .\"
8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 .\" or http://www.opensolaris.org/os/licensing.
10 .\" See the License for the specific language governing permissions
11 .\" and limitations under the License.
12 .\"
13 .\" When distributing Covered Code, include this CDDL HEADER in each
14 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 .\" If applicable, add the following below this CDDL HEADER, with the
16 .\" fields enclosed by brackets "[]" replaced with your own identifying
17 .\" information: Portions Copyright [yyyy] [name of copyright owner]
18 .Dd October 29, 2017
19 .Dt STREAMIO 7I
20 .Os
21 .Sh NAME
22 .Nm streamio
23 .Nd STREAMS ioctl commands
24 .Sh SYNOPSIS
25 .In sys/types.h
26 .In stropts.h
27 .In sys/conf.h
28 .Ft int
29 .Fo ioctl
30 .Fa "int fildes"
31 .Fa "int command"
32 .Fa "\&... /*arg*/"
33 .Fc
34 .Sh DESCRIPTION
35 STREAMS (see
36 .Xr Intro 3 )
37 .Fn ioctl
38 commands are a subset of the
340 .Pp
341 Processes that wish to receive
342 .Dv SIGPOLL
343 signals must explicitly register
344 to receive them using
345 .Dv I_SETSIG .
346 If several processes register to receive
347 this signal for the same event on the same stream, each process will be
348 signaled when the event occurs.
349 .Pp
350 If the value of
351 .Fa arg
352 is zero, the calling process will be unregistered and
353 will not receive further
354 .Dv SIGPOLL
355 signals.
356 On failure,
357 .Va errno
358 is set to one of the following values:
359 .Bl -tag -width EINVAL
360 .It Sy EINVAL
361 .Fa arg
362 value is invalid or
363 .Fa arg
364 is zero and process is not registered to receive the
365 .Dv SIGPOLL
366 signal.
367 .It Sy EAGAIN
368 Allocation of a data structure to store the signal request failed.
369 .El
370 .It Dv I_GETSIG
371 Returns the events for which the calling process is currently registered to be
372 sent a
373 .Dv SIGPOLL
374 signal.
375 The events are returned as a bitmask pointed to by
376 .Va arg ,
377 where the events are those specified in the description of
378 .Dv I_SETSIG
379 above.
380 On failure,
381 .Va errno
382 is set to one of the following values:
383 .Bl -tag -width EINVAL
384 .It Sy EINVAL
385 Process not registered to receive the
386 .Dv SIGPOLL
387 signal.
388 .It Sy EFAULT
389 .Fa arg
390 points outside the allocated address space.
391 .El
392 .It Dv I_FIND
393 Compares the names of all modules currently present in the stream to the name
394 pointed to by
395 .Fa arg ,
396 and returns 1 if the named module is present in the stream.
397 It returns 0 if the named module is not present.
398 On failure,
399 .Va errno
400 is set to one of the following values:
401 .Bl -tag -width EINVAL
402 .It Sy EFAULT
403 .Fa arg
404 points outside the allocated address space.
405 .It Sy EINVAL
406 .Fa arg
407 does not contain a valid module name.
408 .El
409 .It Dv I_PEEK
410 Allows a user to retrieve the information in the first message on the stream
411 head read queue without taking the message off the queue.
412 .Dv I_PEEK
413 is analogous to
414 .Xr getmsg 2
415 except that it does not remove the message from the queue.
416 .Fa arg
417 points to a
418 .Vt strpeek
419 structure, which contains the following members:
420 .Bd -literal -offset 2n
421 struct strbuf ctlbuf;
422 struct strbuf databuf;
423 long flags;
424 .Ed
425 .Pp
790 .Fa ic_dp
791 is a pointer to the data argument.
792 The
793 .Fa ic_len
794 field has two uses: on input, it contains the length of the data
795 argument passed in, and on return from the command, it contains the number of
796 bytes being returned to the user (the buffer pointed to by
797 .Fa ic_dp
798 should be large enough to contain the maximum amount of data that any module or
799 the driver in the stream can return).
800 .Pp
801 At most one
802 .Dv I_STR
803 can be active on a stream.
804 Further
805 .Dv I_STR
806 calls
807 will block until the active
808 .Dv I_STR
809 completes via a positive or negative
810 acknowlegment, a timeout, or an error condition at the stream head.
811 By setting the
812 .Fa ic_timout
813 field to 0, the user is requesting STREAMS to provide
814 the
815 .Sy DEFAULT
816 timeout.
817 The default timeout is specific to the STREAMS
818 implementation and may vary depending on which release of Solaris you are
819 using.
820 For Solaris 8 (and earlier versions), the default timeout is fifteen
821 seconds.
822 The
823 .Dv O_NDELAY
824 and
825 .Dv O_NONBLOCK
826 (see
827 .Xr open 2 )
828 flags have no effect on this call.
829 .Pp
830 The stream head will convert the information pointed to by the
880 set to the value in the message.
881 .It Dv I_SWROPT
882 Sets the write mode using the value of the argument
883 .Fa arg .
884 Legal bit settings for
885 .Fa arg
886 are:
887 .Bl -tag -width SNDZERO
888 .It Dv SNDZERO
889 Send a zero-length message downstream when a write of 0 bytes occurs.
890 .El
891 .Pp
892 To not send a zero-length message when a write of 0 bytes occurs, this bit must
893 not be set in
894 .Fa arg .
895 .Pp
896 On failure,
897 .Va errno
898 may be set to the following value:
899 .Bl -tag -width EINVAL
900 .It Sy EINVAL
901 .Fa arg
902 is not the above legal value.
903 .El
904 .It Dv I_GWROPT
905 Returns the current write mode setting, as described above, in the
906 .Vt int
907 that is pointed to by the argument
908 .Fa arg .
909 .It Dv I_SENDFD
910 Requests the stream associated with
911 .Fa fildes
912 to send a message, containing
913 a file pointer, to the stream head at the other end of a stream pipe.
914 The file
915 pointer corresponds to
916 .Fa arg ,
917 which must be an open file descriptor.
918 .Pp
919 .Dv I_SENDFD
920 converts
1151 .It Er ENODATA
1152 No message on the stream head read queue.
1153 .El
1154 .It Dv I_CANPUT
1155 Check if a certain band is writable.
1156 .Fa arg
1157 is set to the priority band in question.
1158 The return value is
1159 .Sy 0
1160 if the priority band
1161 .Fa arg
1162 is flow controlled,
1163 .Sy 1
1164 if the band is writable, or
1165 .Sy \(mi1
1166 on error.
1167 On failure,
1168 .Va errno
1169 is set to the following value:
1170 .Bl -tag -width EINVAL
1171 .It Sy EINVAL
1172 Invalid
1173 .Va arg
1174 value.
1175 .El
1176 .It Dv I_SETCLTIME
1177 Allows the user to set the time the stream head will delay when a stream is
1178 closing and there are data on the write queues.
1179 Before closing each module and driver, the stream head will delay for the
1180 specified amount of time to allow the data to drain.
1181 Note, however, that the module or driver may itself delay in its close routine;
1182 this delay is independent of the stream head's delay and is not settable.
1183 If, after the delay, data are still present, data will be flushed.
1184 .Fa arg
1185 is a pointer to an integer containing the number of
1186 milliseconds to delay, rounded up to the nearest legal value on the system.
1187 The default is fifteen seconds.
1188 On failure,
1189 .Va errno
1190 is set to the following value:
1191 .Bl -tag -width EINVAL
1242 .Pp
1243 On failure,
1244 .Va errno
1245 is set to the following value:
1246 .Bl -tag -width EINVAL
1247 .It Er EINVAL
1248 .Va arg
1249 is not one of the above legal values.
1250 .El
1251 .It Dv I_GERROPT
1252 Returns the current error mode setting in an
1253 .Vt int
1254 pointed to by the argument
1255 .Fa arg .
1256 Error modes are described above for
1257 .Dv I_SERROPT .
1258 On failure,
1259 .Va errno
1260 is set to the following value:
1261 .Bl -tag -width EFAULT
1262 .It Sy EFAULT
1263 .Fa arg
1264 points outside the allocated address space.
1265 .El
1266 .El
1267 .Pp
1268 The following four commands are used for connecting and disconnecting
1269 multiplexed STREAMS configurations.
1270 .Bl -tag -width I_PUNLINK
1271 .It Dv I_LINK
1272 Connects two streams, where
1273 .Fa fildes
1274 is the file descriptor of the stream
1275 connected to the multiplexing driver, and
1276 .Fa arg
1277 is the file descriptor of the stream connected to another driver.
1278 The stream designated by
1279 .Va arg
1280 gets
1281 connected below the multiplexing driver.
1282 .Dv I_LINK
1478 is the file descriptor of the
1479 stream connected to the multiplexing driver.
1480 .Fa arg
1481 is the multiplexor ID number that was returned by
1482 .Dv I_PLINK
1483 when a stream was linked below the multiplexing driver.
1484 If
1485 .Fa arg
1486 is
1487 .Dv MUXID_ALL
1488 then all streams that are persistent links to
1489 .Fa fildes
1490 are disconnected.
1491 As in
1492 .Dv I_PLINK ,
1493 this command requires the multiplexing driver to acknowledge the unlink.
1494 On failure,
1495 .Va errno
1496 is set to one of the following values:
1497 .Bl -tag -width EAGAIN
1498 .It Sy ENXIO
1499 Hangup received on
1500 .Fa fildes .
1501 .It Er ETIME
1502 Time out before acknowledgement message was received at the stream head.
1503 .It Er EAGAIN
1504 Unable to allocate buffers for the acknowledgement message.
1505 .It Er EINVAL
1506 Invalid multiplexor ID number.
1507 .It Er EINVAL
1508 .Fa fildes
1509 is the file descriptor of a pipe or FIFO.
1510 .El
1511 .Pp
1512 An
1513 .Dv I_PUNLINK
1514 can also fail while waiting for the multiplexing driver to
1515 acknowledge the link request if a message indicating an error or a hangup is
1516 received at the stream head of
1517 .Fa fildes .
1518 In addition, an error code can be
|
1 .\" Copyright 2020 Peter Tribble.
2 .\" Copyright (c) 2017, Joyent, Inc.
3 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
4 .\" Copyright 1989 AT&T
5 .\" The contents of this file are subject to the terms of the
6 .\" Common Development and Distribution License (the "License").
7 .\" You may not use this file except in compliance with the License.
8 .\"
9 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
10 .\" or http://www.opensolaris.org/os/licensing.
11 .\" See the License for the specific language governing permissions
12 .\" and limitations under the License.
13 .\"
14 .\" When distributing Covered Code, include this CDDL HEADER in each
15 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
16 .\" If applicable, add the following below this CDDL HEADER, with the
17 .\" fields enclosed by brackets "[]" replaced with your own identifying
18 .\" information: Portions Copyright [yyyy] [name of copyright owner]
19 .Dd February 17, 2020
20 .Dt STREAMIO 7I
21 .Os
22 .Sh NAME
23 .Nm streamio
24 .Nd STREAMS ioctl commands
25 .Sh SYNOPSIS
26 .In sys/types.h
27 .In stropts.h
28 .In sys/conf.h
29 .Ft int
30 .Fo ioctl
31 .Fa "int fildes"
32 .Fa "int command"
33 .Fa "\&... /*arg*/"
34 .Fc
35 .Sh DESCRIPTION
36 STREAMS (see
37 .Xr Intro 3 )
38 .Fn ioctl
39 commands are a subset of the
341 .Pp
342 Processes that wish to receive
343 .Dv SIGPOLL
344 signals must explicitly register
345 to receive them using
346 .Dv I_SETSIG .
347 If several processes register to receive
348 this signal for the same event on the same stream, each process will be
349 signaled when the event occurs.
350 .Pp
351 If the value of
352 .Fa arg
353 is zero, the calling process will be unregistered and
354 will not receive further
355 .Dv SIGPOLL
356 signals.
357 On failure,
358 .Va errno
359 is set to one of the following values:
360 .Bl -tag -width EINVAL
361 .It Er EINVAL
362 .Fa arg
363 value is invalid or
364 .Fa arg
365 is zero and process is not registered to receive the
366 .Dv SIGPOLL
367 signal.
368 .It Er EAGAIN
369 Allocation of a data structure to store the signal request failed.
370 .El
371 .It Dv I_GETSIG
372 Returns the events for which the calling process is currently registered to be
373 sent a
374 .Dv SIGPOLL
375 signal.
376 The events are returned as a bitmask pointed to by
377 .Va arg ,
378 where the events are those specified in the description of
379 .Dv I_SETSIG
380 above.
381 On failure,
382 .Va errno
383 is set to one of the following values:
384 .Bl -tag -width EINVAL
385 .It Er EINVAL
386 Process not registered to receive the
387 .Dv SIGPOLL
388 signal.
389 .It Er EFAULT
390 .Fa arg
391 points outside the allocated address space.
392 .El
393 .It Dv I_FIND
394 Compares the names of all modules currently present in the stream to the name
395 pointed to by
396 .Fa arg ,
397 and returns 1 if the named module is present in the stream.
398 It returns 0 if the named module is not present.
399 On failure,
400 .Va errno
401 is set to one of the following values:
402 .Bl -tag -width EINVAL
403 .It Er EFAULT
404 .Fa arg
405 points outside the allocated address space.
406 .It Er EINVAL
407 .Fa arg
408 does not contain a valid module name.
409 .El
410 .It Dv I_PEEK
411 Allows a user to retrieve the information in the first message on the stream
412 head read queue without taking the message off the queue.
413 .Dv I_PEEK
414 is analogous to
415 .Xr getmsg 2
416 except that it does not remove the message from the queue.
417 .Fa arg
418 points to a
419 .Vt strpeek
420 structure, which contains the following members:
421 .Bd -literal -offset 2n
422 struct strbuf ctlbuf;
423 struct strbuf databuf;
424 long flags;
425 .Ed
426 .Pp
791 .Fa ic_dp
792 is a pointer to the data argument.
793 The
794 .Fa ic_len
795 field has two uses: on input, it contains the length of the data
796 argument passed in, and on return from the command, it contains the number of
797 bytes being returned to the user (the buffer pointed to by
798 .Fa ic_dp
799 should be large enough to contain the maximum amount of data that any module or
800 the driver in the stream can return).
801 .Pp
802 At most one
803 .Dv I_STR
804 can be active on a stream.
805 Further
806 .Dv I_STR
807 calls
808 will block until the active
809 .Dv I_STR
810 completes via a positive or negative
811 acknowledgement, a timeout, or an error condition at the stream head.
812 By setting the
813 .Fa ic_timout
814 field to 0, the user is requesting STREAMS to provide
815 the
816 .Sy DEFAULT
817 timeout.
818 The default timeout is specific to the STREAMS
819 implementation and may vary depending on which release of Solaris you are
820 using.
821 For Solaris 8 (and earlier versions), the default timeout is fifteen
822 seconds.
823 The
824 .Dv O_NDELAY
825 and
826 .Dv O_NONBLOCK
827 (see
828 .Xr open 2 )
829 flags have no effect on this call.
830 .Pp
831 The stream head will convert the information pointed to by the
881 set to the value in the message.
882 .It Dv I_SWROPT
883 Sets the write mode using the value of the argument
884 .Fa arg .
885 Legal bit settings for
886 .Fa arg
887 are:
888 .Bl -tag -width SNDZERO
889 .It Dv SNDZERO
890 Send a zero-length message downstream when a write of 0 bytes occurs.
891 .El
892 .Pp
893 To not send a zero-length message when a write of 0 bytes occurs, this bit must
894 not be set in
895 .Fa arg .
896 .Pp
897 On failure,
898 .Va errno
899 may be set to the following value:
900 .Bl -tag -width EINVAL
901 .It Er EINVAL
902 .Fa arg
903 is not the above legal value.
904 .El
905 .It Dv I_GWROPT
906 Returns the current write mode setting, as described above, in the
907 .Vt int
908 that is pointed to by the argument
909 .Fa arg .
910 .It Dv I_SENDFD
911 Requests the stream associated with
912 .Fa fildes
913 to send a message, containing
914 a file pointer, to the stream head at the other end of a stream pipe.
915 The file
916 pointer corresponds to
917 .Fa arg ,
918 which must be an open file descriptor.
919 .Pp
920 .Dv I_SENDFD
921 converts
1152 .It Er ENODATA
1153 No message on the stream head read queue.
1154 .El
1155 .It Dv I_CANPUT
1156 Check if a certain band is writable.
1157 .Fa arg
1158 is set to the priority band in question.
1159 The return value is
1160 .Sy 0
1161 if the priority band
1162 .Fa arg
1163 is flow controlled,
1164 .Sy 1
1165 if the band is writable, or
1166 .Sy \(mi1
1167 on error.
1168 On failure,
1169 .Va errno
1170 is set to the following value:
1171 .Bl -tag -width EINVAL
1172 .It Er EINVAL
1173 Invalid
1174 .Va arg
1175 value.
1176 .El
1177 .It Dv I_SETCLTIME
1178 Allows the user to set the time the stream head will delay when a stream is
1179 closing and there are data on the write queues.
1180 Before closing each module and driver, the stream head will delay for the
1181 specified amount of time to allow the data to drain.
1182 Note, however, that the module or driver may itself delay in its close routine;
1183 this delay is independent of the stream head's delay and is not settable.
1184 If, after the delay, data are still present, data will be flushed.
1185 .Fa arg
1186 is a pointer to an integer containing the number of
1187 milliseconds to delay, rounded up to the nearest legal value on the system.
1188 The default is fifteen seconds.
1189 On failure,
1190 .Va errno
1191 is set to the following value:
1192 .Bl -tag -width EINVAL
1243 .Pp
1244 On failure,
1245 .Va errno
1246 is set to the following value:
1247 .Bl -tag -width EINVAL
1248 .It Er EINVAL
1249 .Va arg
1250 is not one of the above legal values.
1251 .El
1252 .It Dv I_GERROPT
1253 Returns the current error mode setting in an
1254 .Vt int
1255 pointed to by the argument
1256 .Fa arg .
1257 Error modes are described above for
1258 .Dv I_SERROPT .
1259 On failure,
1260 .Va errno
1261 is set to the following value:
1262 .Bl -tag -width EFAULT
1263 .It Er EFAULT
1264 .Fa arg
1265 points outside the allocated address space.
1266 .El
1267 .El
1268 .Pp
1269 The following four commands are used for connecting and disconnecting
1270 multiplexed STREAMS configurations.
1271 .Bl -tag -width I_PUNLINK
1272 .It Dv I_LINK
1273 Connects two streams, where
1274 .Fa fildes
1275 is the file descriptor of the stream
1276 connected to the multiplexing driver, and
1277 .Fa arg
1278 is the file descriptor of the stream connected to another driver.
1279 The stream designated by
1280 .Va arg
1281 gets
1282 connected below the multiplexing driver.
1283 .Dv I_LINK
1479 is the file descriptor of the
1480 stream connected to the multiplexing driver.
1481 .Fa arg
1482 is the multiplexor ID number that was returned by
1483 .Dv I_PLINK
1484 when a stream was linked below the multiplexing driver.
1485 If
1486 .Fa arg
1487 is
1488 .Dv MUXID_ALL
1489 then all streams that are persistent links to
1490 .Fa fildes
1491 are disconnected.
1492 As in
1493 .Dv I_PLINK ,
1494 this command requires the multiplexing driver to acknowledge the unlink.
1495 On failure,
1496 .Va errno
1497 is set to one of the following values:
1498 .Bl -tag -width EAGAIN
1499 .It Er ENXIO
1500 Hangup received on
1501 .Fa fildes .
1502 .It Er ETIME
1503 Time out before acknowledgement message was received at the stream head.
1504 .It Er EAGAIN
1505 Unable to allocate buffers for the acknowledgement message.
1506 .It Er EINVAL
1507 Invalid multiplexor ID number.
1508 .It Er EINVAL
1509 .Fa fildes
1510 is the file descriptor of a pipe or FIFO.
1511 .El
1512 .Pp
1513 An
1514 .Dv I_PUNLINK
1515 can also fail while waiting for the multiplexing driver to
1516 acknowledge the link request if a message indicating an error or a hangup is
1517 received at the stream head of
1518 .Fa fildes .
1519 In addition, an error code can be
|