logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

ioctl.3p (31745B)


  1. '\" et
  2. .TH IOCTL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. ioctl
  12. \(em control a STREAMS device (\fBSTREAMS\fP)
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <stropts.h>
  17. .P
  18. int ioctl(int \fIfildes\fP, int \fIrequest\fP, ... /* arg */);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIioctl\fR()
  23. function shall perform a variety of control functions on STREAMS
  24. devices. For non-STREAMS devices, the functions performed by this call
  25. are unspecified. The
  26. .IR request
  27. argument and an optional third argument (with varying type) shall be
  28. passed to and interpreted by the appropriate part of the STREAM
  29. associated with
  30. .IR fildes .
  31. .P
  32. The
  33. .IR fildes
  34. argument is an open file descriptor that refers to a device.
  35. .P
  36. The
  37. .IR request
  38. argument selects the control function to be performed and shall
  39. depend on the STREAMS device being addressed.
  40. .P
  41. The
  42. .IR arg
  43. argument represents additional information that is needed by this
  44. specific STREAMS device to perform the requested function. The type of
  45. .IR arg
  46. depends upon the particular control request, but it shall be either an
  47. integer or a pointer to a device-specific data structure.
  48. .P
  49. The
  50. \fIioctl\fR()
  51. commands applicable to STREAMS, their arguments, and error conditions
  52. that apply to each individual command are described below.
  53. .P
  54. The following
  55. \fIioctl\fR()
  56. commands, with error values indicated, are applicable to all STREAMS
  57. files:
  58. .IP I_PUSH 12
  59. Pushes the module whose name is pointed to by
  60. .IR arg
  61. onto the top of the current STREAM, just below the STREAM head. It then
  62. calls the
  63. \fIopen\fR()
  64. function of the newly-pushed module.
  65. .RS 12
  66. .P
  67. The
  68. \fIioctl\fR()
  69. function with the I_PUSH command shall fail if:
  70. .TP
  71. .BR EINVAL
  72. Invalid module name.
  73. .TP
  74. .BR ENXIO
  75. Open function of new module failed.
  76. .TP
  77. .BR ENXIO
  78. Hangup received on
  79. .IR fildes .
  80. .RE
  81. .IP I_POP 12
  82. Removes the module just below the STREAM head of the STREAM pointed to
  83. by
  84. .IR fildes .
  85. The
  86. .IR arg
  87. argument should be 0 in an I_POP request.
  88. .RS 12
  89. .P
  90. The
  91. \fIioctl\fR()
  92. function with the I_POP command shall fail if:
  93. .TP
  94. .BR EINVAL
  95. No module present in the STREAM.
  96. .TP
  97. .BR ENXIO
  98. Hangup received on
  99. .IR fildes .
  100. .RE
  101. .IP I_LOOK 12
  102. Retrieves the name of the module just below the STREAM head of the
  103. STREAM pointed to by
  104. .IR fildes ,
  105. and places it in a character string pointed to by
  106. .IR arg .
  107. The buffer pointed to by
  108. .IR arg
  109. should be at least FMNAMESZ+1
  110. bytes long, where FMNAMESZ is defined in
  111. .IR <stropts.h> .
  112. .RS 12
  113. .P
  114. The
  115. \fIioctl\fR()
  116. function with the I_LOOK command shall fail if:
  117. .TP
  118. .BR EINVAL
  119. No module present in the STREAM.
  120. .RE
  121. .IP I_FLUSH 12
  122. Flushes read and/or write queues, depending on the value of
  123. .IR arg .
  124. Valid
  125. .IR arg
  126. values are:
  127. .RS 12
  128. .IP FLUSHR 12
  129. Flush all read queues.
  130. .IP FLUSHW 12
  131. Flush all write queues.
  132. .IP FLUSHRW 12
  133. Flush all read and all write queues.
  134. .P
  135. The
  136. \fIioctl\fR()
  137. function with the I_FLUSH command shall fail if:
  138. .TP
  139. .BR EINVAL
  140. Invalid
  141. .IR arg
  142. value.
  143. .TP
  144. .BR EAGAIN " or " ENOSR
  145. .br
  146. Unable to allocate buffers for flush message.
  147. .TP
  148. .BR ENXIO
  149. Hangup received on
  150. .IR fildes .
  151. .RE
  152. .IP I_FLUSHBAND 12
  153. Flushes a particular band of messages. The
  154. .IR arg
  155. argument points to a
  156. .BR bandinfo
  157. structure. The
  158. .IR bi_flag
  159. member may be one of FLUSHR, FLUSHW, or FLUSHRW as described above. The
  160. .IR bi_pri
  161. member determines the priority band to be flushed.
  162. .IP I_SETSIG 12
  163. Requests that the STREAMS implementation send the SIGPOLL signal to the
  164. calling process when a particular event has occurred on
  165. the STREAM associated with
  166. .IR fildes .
  167. I_SETSIG supports an asynchronous processing capability in STREAMS. The
  168. value of
  169. .IR arg
  170. is a bitmask that specifies the events for which the process should be
  171. signaled. It is the bitwise-inclusive OR of any combination of the
  172. following constants:
  173. .RS 12
  174. .IP S_RDNORM 12
  175. A normal (priority band set to 0) message has arrived at the head of a
  176. STREAM head read queue. A signal shall be generated even if the message
  177. is of zero length.
  178. .IP S_RDBAND 12
  179. A message with a non-zero priority band has arrived at the head of a
  180. STREAM head read queue. A signal shall be generated even if the message
  181. is of zero length.
  182. .IP S_INPUT 12
  183. A message, other than a high-priority message, has arrived at the head
  184. of a STREAM head read queue. A signal shall be generated even if the
  185. message is of zero length.
  186. .IP S_HIPRI 12
  187. A high-priority message is present on a STREAM head read queue. A
  188. signal shall be generated even if the message is of zero length.
  189. .IP S_OUTPUT 12
  190. The write queue for normal data (priority band 0) just below the STREAM
  191. head is no longer full. This notifies the process that there is room
  192. on the queue for sending (or writing) normal data downstream.
  193. .IP S_WRNORM 12
  194. Equivalent to S_OUTPUT.
  195. .IP S_WRBAND 12
  196. The write queue for a non-zero priority band just below the STREAM head
  197. is no longer full. This notifies the process that there is room on the
  198. queue for sending (or writing) priority data downstream.
  199. .IP S_MSG 12
  200. A STREAMS signal message that contains the SIGPOLL signal has reached
  201. the front of the STREAM head read queue.
  202. .IP S_ERROR 12
  203. Notification of an error condition has reached the STREAM head.
  204. .IP S_HANGUP 12
  205. Notification of a hangup has reached the STREAM head.
  206. .IP S_BANDURG 12
  207. When used in conjunction with S_RDBAND, SIGURG is generated instead of
  208. SIGPOLL when a priority message reaches the front of the STREAM head
  209. read queue.
  210. .P
  211. If
  212. .IR arg
  213. is 0, the calling process shall be unregistered and shall not receive
  214. further SIGPOLL signals for the stream associated with
  215. .IR fildes .
  216. .P
  217. Processes that wish to receive SIGPOLL signals shall ensure that they
  218. explicitly register to receive them using I_SETSIG. If several
  219. processes register to receive this
  220. signal for the same event on the same STREAM, each process shall be
  221. signaled when the event occurs.
  222. .P
  223. The
  224. \fIioctl\fR()
  225. function with the I_SETSIG command shall fail if:
  226. .TP
  227. .BR EINVAL
  228. The value of
  229. .IR arg
  230. is invalid.
  231. .TP
  232. .BR EINVAL
  233. The value of
  234. .IR arg
  235. is 0 and the calling process is not registered to receive
  236. the SIGPOLL signal.
  237. .TP
  238. .BR EAGAIN
  239. There were insufficient resources to store the signal request.
  240. .RE
  241. .IP I_GETSIG 12
  242. Returns the events for which the calling process is currently
  243. registered to be sent a SIGPOLL signal. The events are returned as a
  244. bitmask in an
  245. .BR int
  246. pointed to by
  247. .IR arg ,
  248. where the events are those specified in the description of
  249. I_SETSIG above.
  250. .RS 12
  251. .P
  252. The
  253. \fIioctl\fR()
  254. function with the I_GETSIG command shall fail if:
  255. .TP
  256. .BR EINVAL
  257. Process is not registered to receive the SIGPOLL signal.
  258. .RE
  259. .IP I_FIND 12
  260. Compares the names of all modules currently present in the STREAM to
  261. the name pointed to by
  262. .IR arg ,
  263. and returns 1 if the named module is present in the STREAM, or returns
  264. 0 if the named module is not present.
  265. .RS 12
  266. .P
  267. The
  268. \fIioctl\fR()
  269. function with the I_FIND command shall fail if:
  270. .TP
  271. .BR EINVAL
  272. .IR arg
  273. does not contain a valid module name.
  274. .RE
  275. .IP I_PEEK 12
  276. Retrieves the information in the first message on the STREAM head read
  277. queue without taking the message off the queue. It is analogous to
  278. \fIgetmsg\fR()
  279. except that this command does not remove the message from the queue.
  280. The
  281. .IR arg
  282. argument points to a
  283. .BR strpeek
  284. structure.
  285. .RS 12
  286. .P
  287. The application shall ensure that the
  288. .IR maxlen
  289. member in the
  290. .BR ctlbuf
  291. and
  292. .BR "databuf strbuf"
  293. structures is set to the number of bytes of control information and/or
  294. data information, respectively, to retrieve. The
  295. .IR flags
  296. member may be marked RS_HIPRI or 0, as described by
  297. \fIgetmsg\fR().
  298. If the process sets
  299. .IR flags
  300. to RS_HIPRI, for example, I_PEEK shall only look for a high-priority
  301. message on the STREAM head read queue.
  302. .P
  303. I_PEEK returns 1 if a message was retrieved, and returns 0 if no
  304. message was found on the STREAM head read queue, or if the RS_HIPRI
  305. flag was set in
  306. .IR flags
  307. and a high-priority message was not present on the STREAM head read
  308. queue. It does not wait for a message to arrive. On return,
  309. .BR ctlbuf
  310. specifies information in the control buffer,
  311. .BR databuf
  312. specifies information in the data buffer, and
  313. .IR flags
  314. contains the value RS_HIPRI or 0.
  315. .RE
  316. .IP I_SRDOPT 12
  317. Sets the read mode using the value of the argument
  318. .IR arg .
  319. Read modes are described in
  320. \fIread\fR().
  321. Valid
  322. .IR arg
  323. flags are:
  324. .RS 12
  325. .IP RNORM 12
  326. Byte-stream mode, the default.
  327. .IP RMSGD 12
  328. Message-discard mode.
  329. .IP RMSGN 12
  330. Message-nondiscard mode.
  331. .P
  332. The bitwise-inclusive OR of RMSGD and RMSGN shall return
  333. .BR [EINVAL] .
  334. The bitwise-inclusive OR of RNORM and either RMSGD or RMSGN shall
  335. result in the other flag overriding RNORM which is the default.
  336. .P
  337. In addition, treatment of control messages by the STREAM head may be
  338. changed by setting any of the following flags in
  339. .IR arg :
  340. .IP RPROTNORM 12
  341. Fail
  342. \fIread\fR()
  343. with
  344. .BR [EBADMSG]
  345. if a message containing a control part is at the front of the
  346. STREAM head read queue.
  347. .IP RPROTDAT 12
  348. Deliver the control part of a message as data when a process issues a
  349. \fIread\fR().
  350. .IP RPROTDIS 12
  351. Discard the control part of a message, delivering any data portion,
  352. when a process issues a
  353. \fIread\fR().
  354. .P
  355. The
  356. \fIioctl\fR()
  357. function with the I_SRDOPT command shall fail if:
  358. .TP
  359. .BR EINVAL
  360. The
  361. .IR arg
  362. argument is not valid.
  363. .RE
  364. .IP I_GRDOPT 12
  365. Returns the current read mode setting, as described above, in an
  366. .BR int
  367. pointed to by the argument
  368. .IR arg .
  369. Read modes are described in
  370. \fIread\fR().
  371. .IP I_NREAD 12
  372. Counts the number of data bytes in the data part of the first message
  373. on the STREAM head read queue and places this value in the
  374. .BR int
  375. pointed to by
  376. .IR arg .
  377. The return value for the command shall be the number of messages on the
  378. STREAM head read queue. For example, if 0 is returned in
  379. .IR arg ,
  380. but the
  381. \fIioctl\fR()
  382. return value is greater than 0, this indicates that a zero-length
  383. message is next on the queue.
  384. .IP I_FDINSERT 12
  385. Creates a message from specified buffer(s), adds information about
  386. another STREAM, and sends the message downstream. The message contains
  387. a control part and an optional data part. The data and control parts to
  388. be sent are distinguished by placement in separate buffers, as
  389. described below. The
  390. .IR arg
  391. argument points to a
  392. .BR strfdinsert
  393. structure.
  394. .RS 12
  395. .P
  396. The application shall ensure that the
  397. .IR len
  398. member in the
  399. .BR "ctlbuf strbuf"
  400. structure is set to the size of a
  401. .BR t_uscalar_t
  402. plus the number of bytes of control information to be sent with the
  403. message. The
  404. .IR fildes
  405. member specifies the file descriptor of the other STREAM, and the
  406. .IR offset
  407. member, which must be suitably aligned for use as a
  408. .BR t_uscalar_t ,
  409. specifies the offset from the start of the control buffer where
  410. I_FDINSERT shall store a
  411. .BR t_uscalar_t
  412. whose interpretation is specific to the STREAM end. The application
  413. shall ensure that the
  414. .IR len
  415. member in the
  416. .BR "databuf strbuf"
  417. structure is set to the number of bytes of data information to be sent
  418. with the message, or to 0 if no data part is to be sent.
  419. .P
  420. The
  421. .IR flags
  422. member specifies the type of message to be created. A normal message is
  423. created if
  424. .IR flags
  425. is set to 0, and a high-priority message is created if
  426. .IR flags
  427. is set to RS_HIPRI. For non-priority messages, I_FDINSERT shall block if
  428. the STREAM write queue is full due to internal flow control conditions.
  429. For priority messages, I_FDINSERT does not block on this condition. For
  430. non-priority messages, I_FDINSERT does not block when the write queue
  431. is full and O_NONBLOCK is set. Instead, it fails and sets
  432. .IR errno
  433. to
  434. .BR [EAGAIN] .
  435. .P
  436. I_FDINSERT also blocks, unless prevented by lack of internal resources,
  437. waiting for the availability of message blocks in the STREAM,
  438. regardless of priority or whether O_NONBLOCK has been specified. No
  439. partial message is sent.
  440. .P
  441. The
  442. \fIioctl\fR()
  443. function with the I_FDINSERT command shall fail if:
  444. .TP
  445. .BR EAGAIN
  446. A non-priority message is specified, the O_NONBLOCK flag is set, and
  447. the STREAM write queue is full due to internal flow control
  448. conditions.
  449. .TP
  450. .BR EAGAIN " or " ENOSR
  451. .br
  452. Buffers cannot be allocated for the message that is to be created.
  453. .TP
  454. .BR EINVAL
  455. One of the following:
  456. .RS 12
  457. .IP -- 4
  458. The
  459. .IR fildes
  460. member of the
  461. .BR strfdinsert
  462. structure is not a valid, open STREAM file descriptor.
  463. .IP -- 4
  464. The size of a
  465. .BR t_uscalar_t
  466. plus
  467. .IR offset
  468. is greater than the
  469. .IR len
  470. member for the buffer specified through
  471. .BR ctlbuf .
  472. .IP -- 4
  473. The
  474. .IR offset
  475. member does not specify a properly-aligned location in the data buffer.
  476. .IP -- 4
  477. An undefined value is stored in
  478. .IR flags .
  479. .RE
  480. .TP
  481. .BR ENXIO
  482. Hangup received on the STREAM identified by either the
  483. .IR fildes
  484. argument or the
  485. .IR fildes
  486. member of the
  487. .BR strfdinsert
  488. structure.
  489. .TP
  490. .BR ERANGE
  491. The
  492. .IR len
  493. member for the buffer specified through
  494. .BR databuf
  495. does not fall within the range specified by the maximum and minimum
  496. packet sizes of the topmost STREAM module; or the
  497. .IR len
  498. member for the buffer specified through
  499. .BR databuf
  500. is larger than the maximum configured size of the data part of a
  501. message; or the
  502. .IR len
  503. member for the buffer specified through
  504. .BR ctlbuf
  505. is larger than the maximum configured size of the control part of a
  506. message.
  507. .RE
  508. .IP I_STR 12
  509. Constructs an internal STREAMS
  510. \fIioctl\fR()
  511. message from the data pointed to by
  512. .IR arg ,
  513. and sends that message downstream.
  514. .RS 12
  515. .P
  516. This mechanism is provided to send
  517. \fIioctl\fR()
  518. requests to downstream modules and drivers. It allows information to be
  519. sent with
  520. \fIioctl\fR(),
  521. and returns to the process any information sent upstream by the
  522. downstream recipient. I_STR shall block until the system responds with
  523. either a positive or negative acknowledgement message, or until the
  524. request times out after some period of time. If the request times out,
  525. it shall fail with
  526. .IR errno
  527. set to
  528. .BR [ETIME] .
  529. .P
  530. At most, one I_STR can be active on a STREAM. Further I_STR calls shall
  531. block until the active I_STR completes at the STREAM head. The default
  532. timeout interval for these requests is 15 seconds. The O_NONBLOCK flag
  533. has no effect on this call.
  534. .P
  535. To send requests downstream, the application shall ensure that
  536. .IR arg
  537. points to a
  538. .BR strioctl
  539. structure.
  540. .P
  541. The
  542. .IR ic_cmd
  543. member is the internal
  544. \fIioctl\fR()
  545. command intended for a downstream module or driver and
  546. .IR ic_timout
  547. is the number of seconds (\-1=infinite, 0=use
  548. implementation-defined timeout interval, >0=as specified) an I_STR
  549. request shall wait for acknowledgement before timing out.
  550. .IR ic_len
  551. is the number of bytes in the data argument, and
  552. .IR ic_dp
  553. is a pointer to the data argument. The
  554. .IR ic_len
  555. member has two uses: on input, it contains the length of the data
  556. argument passed in, and on return from the command, it contains the
  557. number of bytes being returned to the process (the buffer pointed to by
  558. .IR ic_dp
  559. should be large enough to contain the maximum amount of data that any
  560. module or the driver in the STREAM can return).
  561. .P
  562. The STREAM head shall convert the information pointed to by the
  563. .BR strioctl
  564. structure to an internal
  565. \fIioctl\fR()
  566. command message and send it downstream.
  567. .P
  568. The
  569. \fIioctl\fR()
  570. function with the I_STR command shall fail if:
  571. .TP
  572. .BR EAGAIN " or " ENOSR
  573. .br
  574. Unable to allocate buffers for the
  575. \fIioctl\fR()
  576. message.
  577. .TP
  578. .BR EINVAL
  579. The
  580. .IR ic_len
  581. member is less than 0 or larger than the maximum configured size of the
  582. data part of a message, or
  583. .IR ic_timout
  584. is less than \-1.
  585. .TP
  586. .BR ENXIO
  587. Hangup received on
  588. .IR fildes .
  589. .TP
  590. .BR ETIME
  591. A downstream
  592. \fIioctl\fR()
  593. timed out before acknowledgement was received.
  594. .P
  595. An I_STR can also fail while waiting for an acknowledgement if a
  596. message indicating an error or a hangup is received at the STREAM head.
  597. In addition, an error code can be returned in the positive or negative
  598. acknowledgement message, in the event the
  599. \fIioctl\fR()
  600. command sent downstream fails. For these cases, I_STR shall fail with
  601. .IR errno
  602. set to the value in the message.
  603. .RE
  604. .IP I_SWROPT 12
  605. Sets the write mode using the value of the argument
  606. .IR arg .
  607. Valid bit settings for
  608. .IR arg
  609. are:
  610. .RS 12
  611. .IP SNDZERO 12
  612. Send a zero-length message downstream when a
  613. \fIwrite\fR()
  614. of 0 bytes occurs. To not send a zero-length message when a
  615. \fIwrite\fR()
  616. of 0 bytes occurs, the application shall ensure that this bit is not
  617. set in
  618. .IR arg
  619. (for example,
  620. .IR arg
  621. would be set to 0).
  622. .P
  623. The
  624. \fIioctl\fR()
  625. function with the I_SWROPT command shall fail if:
  626. .TP
  627. .BR EINVAL
  628. .IR arg
  629. is not the above value.
  630. .RE
  631. .IP I_GWROPT 12
  632. Returns the current write mode setting, as described above, in the
  633. .BR int
  634. that is pointed to by the argument
  635. .IR arg .
  636. .IP I_SENDFD 12
  637. Creates a new reference to the open file description associated with
  638. the file descriptor
  639. .IR arg ,
  640. and writes a message on the STREAMS-based pipe
  641. .IR fildes
  642. containing this reference, together with the user ID and group ID of
  643. the calling process.
  644. .RS 12
  645. .P
  646. The
  647. \fIioctl\fR()
  648. function with the I_SENDFD command shall fail if:
  649. .TP
  650. .BR EAGAIN
  651. The sending STREAM is unable to allocate a message block to contain the
  652. file pointer; or the read queue of the receiving STREAM head is full
  653. and cannot accept the message sent by I_SENDFD.
  654. .TP
  655. .BR EBADF
  656. The
  657. .IR arg
  658. argument is not a valid, open file descriptor.
  659. .TP
  660. .BR EINVAL
  661. The
  662. .IR fildes
  663. argument is not connected to a STREAM pipe.
  664. .TP
  665. .BR ENXIO
  666. Hangup received on
  667. .IR fildes .
  668. .P
  669. The
  670. \fIioctl\fR()
  671. function with the I_SENDFD command may fail if:
  672. .TP
  673. .BR EINVAL
  674. The
  675. .IR arg
  676. argument is equal to the
  677. .IR fildes
  678. argument.
  679. .RE
  680. .IP I_RECVFD 12
  681. Retrieves the reference to an open file description from a message
  682. written to a STREAMS-based pipe using the I_SENDFD command, and
  683. allocates a new file descriptor in the calling process that refers to
  684. this open file description. The
  685. .IR arg
  686. argument is a pointer to a
  687. .BR strrecvfd
  688. data structure as defined in
  689. .IR <stropts.h> .
  690. .RS 12
  691. .P
  692. The
  693. .IR fd
  694. member is a file descriptor. The
  695. .IR uid
  696. and
  697. .IR gid
  698. members are the effective user ID and effective group ID, respectively,
  699. of the sending process.
  700. .P
  701. If O_NONBLOCK is not set, I_RECVFD shall block until a message is
  702. present at the STREAM head. If O_NONBLOCK is set, I_RECVFD shall fail
  703. with
  704. .IR errno
  705. set to
  706. .BR [EAGAIN]
  707. if no message is present at the STREAM head.
  708. .P
  709. If the message at the STREAM head is a message sent by an I_SENDFD, a
  710. new file
  711. descriptor shall be allocated for the open file descriptor referenced
  712. in the message. The new file descriptor is placed in the
  713. .IR fd
  714. member of the
  715. .BR strrecvfd
  716. structure pointed to by
  717. .IR arg .
  718. .P
  719. The
  720. \fIioctl\fR()
  721. function with the I_RECVFD command shall fail if:
  722. .TP
  723. .BR EAGAIN
  724. A message is not present at the STREAM head read queue and the
  725. O_NONBLOCK flag is set.
  726. .TP
  727. .BR EBADMSG
  728. The message at the STREAM head read queue is not a message containing a
  729. passed file descriptor.
  730. .TP
  731. .BR EMFILE
  732. All file descriptors available to the process are currently open.
  733. .TP
  734. .BR ENXIO
  735. Hangup received on
  736. .IR fildes .
  737. .RE
  738. .IP I_LIST 12
  739. Allows the process to list all the module names on the STREAM, up to
  740. and including the topmost driver name. If
  741. .IR arg
  742. is a null pointer, the return value shall be the number of modules,
  743. including the driver, that are on the STREAM pointed to by
  744. .IR fildes .
  745. This lets the process allocate enough space for the module names.
  746. Otherwise, it should point to a
  747. .BR str_list
  748. structure.
  749. .RS 12
  750. .P
  751. The
  752. .IR sl_nmods
  753. member indicates the number of entries the process has allocated in the
  754. array. Upon return, the
  755. .IR sl_modlist
  756. member of the
  757. .BR str_list
  758. structure shall contain the list of module names, and the number of
  759. entries that have been filled into the
  760. .IR sl_modlist
  761. array is found in the
  762. .IR sl_nmods
  763. member (the number includes the number of modules including the
  764. driver). The return value from
  765. \fIioctl\fR()
  766. shall be 0. The entries are filled in starting at the top of the STREAM
  767. and continuing downstream until either the end of the STREAM is
  768. reached, or the number of requested modules (\c
  769. .IR sl_nmods )
  770. is satisfied.
  771. .P
  772. The
  773. \fIioctl\fR()
  774. function with the I_LIST command shall fail if:
  775. .TP
  776. .BR EINVAL
  777. The
  778. .IR sl_nmods
  779. member is less than 1.
  780. .TP
  781. .BR EAGAIN " or " ENOSR
  782. .br
  783. Unable to allocate buffers.
  784. .RE
  785. .IP I_ATMARK 12
  786. Allows the process to see if the message at the head of the STREAM head
  787. read queue is marked by some module downstream. The
  788. .IR arg
  789. argument determines how the checking is done when there may be multiple
  790. marked messages on the STREAM head read queue. It may take on the
  791. following values:
  792. .RS 12
  793. .IP ANYMARK 12
  794. Check if the message is marked.
  795. .IP LASTMARK 12
  796. Check if the message is the last one marked on the queue.
  797. .P
  798. The bitwise-inclusive OR of the flags ANYMARK and LASTMARK is permitted.
  799. .P
  800. The return value shall be 1 if the mark condition is satisfied;
  801. otherwise, the value shall be 0.
  802. .P
  803. The
  804. \fIioctl\fR()
  805. function with the I_ATMARK command shall fail if:
  806. .TP
  807. .BR EINVAL
  808. Invalid
  809. .IR arg
  810. value.
  811. .RE
  812. .IP I_CKBAND 12
  813. Checks if the message of a given priority band exists on the STREAM
  814. head read queue. This shall return 1 if a message of the given priority
  815. exists, 0 if no such message exists, or \-1 on error.
  816. .IR arg
  817. should be of type
  818. .BR int .
  819. .RS 12
  820. .P
  821. The
  822. \fIioctl\fR()
  823. function with the I_CKBAND command shall fail if:
  824. .TP
  825. .BR EINVAL
  826. Invalid
  827. .IR arg
  828. value.
  829. .RE
  830. .IP I_GETBAND 12
  831. Returns the priority band of the first message on the STREAM head read
  832. queue in the integer referenced by
  833. .IR arg .
  834. .RS 12
  835. .P
  836. The
  837. \fIioctl\fR()
  838. function with the I_GETBAND command shall fail if:
  839. .TP
  840. .BR ENODATA
  841. No message on the STREAM head read queue.
  842. .RE
  843. .IP I_CANPUT 12
  844. Checks if a certain band is writable.
  845. .IR arg
  846. is set to the priority band in question. The return value shall be 0 if
  847. the band is flow-controlled, 1 if the band is writable, or \-1 on
  848. error.
  849. .RS 12
  850. .P
  851. The
  852. \fIioctl\fR()
  853. function with the I_CANPUT command shall fail if:
  854. .TP
  855. .BR EINVAL
  856. Invalid
  857. .IR arg
  858. value.
  859. .RE
  860. .IP I_SETCLTIME 12
  861. This request allows the process to set the time the STREAM head shall
  862. delay when a STREAM is closing and there is data on the write queues.
  863. Before closing each module or driver, if there is data on its write
  864. queue, the STREAM head shall delay for the specified amount of time to
  865. allow the data to drain. If, after the delay, data is still present, it
  866. shall be flushed. The
  867. .IR arg
  868. argument is a pointer to an integer specifying the number of
  869. milliseconds to delay, rounded up to the nearest valid value. If
  870. I_SETCLTIME is not performed on a STREAM, an implementation-defined
  871. default timeout interval is used.
  872. .br
  873. .RS 12
  874. .P
  875. The
  876. \fIioctl\fR()
  877. function with the I_SETCLTIME command shall fail if:
  878. .TP
  879. .BR EINVAL
  880. Invalid
  881. .IR arg
  882. value.
  883. .RE
  884. .IP I_GETCLTIME 12
  885. Returns the close time delay in the integer pointed to by
  886. .IR arg .
  887. .SS "Multiplexed STREAMS Configurations"
  888. .P
  889. The following commands are used for connecting and disconnecting
  890. multiplexed STREAMS configurations. These commands use an
  891. implementation-defined default timeout interval.
  892. .IP I_LINK 12
  893. Connects two STREAMs, where
  894. .IR fildes
  895. is the file descriptor of the STREAM connected to the multiplexing
  896. driver, and
  897. .IR arg
  898. is the file descriptor of the STREAM connected to another driver. The
  899. STREAM designated by
  900. .IR arg
  901. is connected below the multiplexing driver. I_LINK requires the
  902. multiplexing driver to send an acknowledgement message to the STREAM
  903. head regarding the connection. This call shall return a multiplexer ID
  904. number (an identifier used to disconnect the multiplexer; see I_UNLINK)
  905. on success, and \-1 on failure.
  906. .RS 12
  907. .P
  908. The
  909. \fIioctl\fR()
  910. function with the I_LINK command shall fail if:
  911. .TP
  912. .BR ENXIO
  913. Hangup received on
  914. .IR fildes .
  915. .TP
  916. .BR ETIME
  917. Timeout before acknowledgement message was received at STREAM head.
  918. .TP
  919. .BR EAGAIN " or " ENOSR
  920. .br
  921. Unable to allocate STREAMS storage to perform the I_LINK.
  922. .TP
  923. .BR EBADF
  924. The
  925. .IR arg
  926. argument is not a valid, open file descriptor.
  927. .TP
  928. .BR EINVAL
  929. The
  930. .IR fildes
  931. argument does not support multiplexing; or
  932. .IR arg
  933. is not a STREAM or is already connected downstream from a multiplexer;
  934. or the specified I_LINK operation would connect the STREAM head in more
  935. than one place in the multiplexed STREAM.
  936. .P
  937. An I_LINK can also fail while waiting for the multiplexing driver to
  938. acknowledge the request, if a message indicating an error or a hangup
  939. is received at the STREAM head of
  940. .IR fildes .
  941. In addition, an error code can be returned in the positive or negative
  942. acknowledgement message. For these cases, I_LINK fails with
  943. .IR errno
  944. set to the value in the message.
  945. .RE
  946. .IP I_UNLINK 12
  947. Disconnects the two STREAMs specified by
  948. .IR fildes
  949. and
  950. .IR arg .
  951. .IR fildes
  952. is the file descriptor of the STREAM connected to the multiplexing
  953. driver. The
  954. .IR arg
  955. argument is the multiplexer ID number that was returned by the I_LINK
  956. \fIioctl\fR()
  957. command when a STREAM was connected downstream from the multiplexing
  958. driver. If
  959. .IR arg
  960. is MUXID_ALL, then all STREAMs that were connected to
  961. .IR fildes
  962. shall be disconnected. As in I_LINK, this command requires
  963. acknowledgement.
  964. .RS 12
  965. .P
  966. The
  967. \fIioctl\fR()
  968. function with the I_UNLINK command shall fail if:
  969. .TP
  970. .BR ENXIO
  971. Hangup received on
  972. .IR fildes .
  973. .TP
  974. .BR ETIME
  975. Timeout before acknowledgement message was received at STREAM head.
  976. .TP
  977. .BR EAGAIN " or " ENOSR
  978. .br
  979. Unable to allocate buffers for the acknowledgement message.
  980. .TP
  981. .BR EINVAL
  982. Invalid multiplexer ID number.
  983. .P
  984. An I_UNLINK can also fail while waiting for the multiplexing driver to
  985. acknowledge the request if a message indicating an error or a hangup is
  986. received at the STREAM head of
  987. .IR fildes .
  988. In addition, an error code can be returned in the positive or negative
  989. acknowledgement message. For these cases, I_UNLINK shall fail with
  990. .IR errno
  991. set to the value in the message.
  992. .RE
  993. .IP I_PLINK 12
  994. Creates a
  995. .IR "persistent connection"
  996. between two STREAMs, where
  997. .IR fildes
  998. is the file descriptor of the STREAM connected to the multiplexing
  999. driver, and
  1000. .IR arg
  1001. is the file descriptor of the STREAM connected to another driver. This
  1002. call shall create a persistent connection which can exist even if the
  1003. file descriptor
  1004. .IR fildes
  1005. associated with the upper STREAM to the multiplexing driver is closed.
  1006. The STREAM designated by
  1007. .IR arg
  1008. gets connected via a persistent connection below the multiplexing
  1009. driver. I_PLINK requires the multiplexing driver to send an
  1010. acknowledgement message to the STREAM head. This call shall return a
  1011. multiplexer ID number (an identifier that may be used to disconnect the
  1012. multiplexer; see I_PUNLINK) on success, and \-1 on failure.
  1013. .RS 12
  1014. .P
  1015. The
  1016. \fIioctl\fR()
  1017. function with the I_PLINK command shall fail if:
  1018. .TP
  1019. .BR ENXIO
  1020. Hangup received on
  1021. .IR fildes .
  1022. .TP
  1023. .BR ETIME
  1024. Timeout before acknowledgement message was received at STREAM head.
  1025. .TP
  1026. .BR EAGAIN " or " ENOSR
  1027. .br
  1028. Unable to allocate STREAMS storage to perform the I_PLINK.
  1029. .TP
  1030. .BR EBADF
  1031. The
  1032. .IR arg
  1033. argument is not a valid, open file descriptor.
  1034. .TP
  1035. .BR EINVAL
  1036. The
  1037. .IR fildes
  1038. argument does not support multiplexing; or
  1039. .IR arg
  1040. is not a STREAM or is already connected downstream from a multiplexer;
  1041. or the specified I_PLINK operation would connect the STREAM head in
  1042. more than one place in the multiplexed STREAM.
  1043. .P
  1044. An I_PLINK can also fail while waiting for the multiplexing driver to
  1045. acknowledge the request, if a message indicating an error or a hangup
  1046. is received at the STREAM head of
  1047. .IR fildes .
  1048. In addition, an error code can be returned in the positive or negative
  1049. acknowledgement message. For these cases, I_PLINK shall fail with
  1050. .IR errno
  1051. set to the value in the message.
  1052. .RE
  1053. .IP I_PUNLINK 12
  1054. Disconnects the two STREAMs specified by
  1055. .IR fildes
  1056. and
  1057. .IR arg
  1058. from a persistent connection. The
  1059. .IR fildes
  1060. argument is the file descriptor of the STREAM connected to the
  1061. multiplexing driver. The
  1062. .IR arg
  1063. argument is the multiplexer ID number that was returned by the I_PLINK
  1064. \fIioctl\fR()
  1065. command when a STREAM was connected downstream from the multiplexing
  1066. driver. If
  1067. .IR arg
  1068. is MUXID_ALL, then all STREAMs which are persistent connections
  1069. to
  1070. .IR fildes
  1071. shall be disconnected. As in I_PLINK, this command requires the
  1072. multiplexing driver to acknowledge the request.
  1073. .br
  1074. .RS 12
  1075. .P
  1076. The
  1077. \fIioctl\fR()
  1078. function with the I_PUNLINK command shall fail if:
  1079. .TP
  1080. .BR ENXIO
  1081. Hangup received on
  1082. .IR fildes .
  1083. .TP
  1084. .BR ETIME
  1085. Timeout before acknowledgement message was received at STREAM head.
  1086. .TP
  1087. .BR EAGAIN " or " ENOSR
  1088. .br
  1089. Unable to allocate buffers for the acknowledgement message.
  1090. .TP
  1091. .BR EINVAL
  1092. Invalid multiplexer ID number.
  1093. .P
  1094. An I_PUNLINK can also fail while waiting for the multiplexing driver to
  1095. acknowledge the request if a message indicating an error or a hangup is
  1096. received at the STREAM head of
  1097. .IR fildes .
  1098. In addition, an error code can be returned in the positive or negative
  1099. acknowledgement message. For these cases, I_PUNLINK shall fail with
  1100. .IR errno
  1101. set to the value in the message.
  1102. .RE
  1103. .SH "RETURN VALUE"
  1104. Upon successful completion,
  1105. \fIioctl\fR()
  1106. shall return a value other than \-1 that depends upon the STREAMS device
  1107. control function. Otherwise, it shall return \-1 and set
  1108. .IR errno
  1109. to indicate the error.
  1110. .SH ERRORS
  1111. Under the following general conditions,
  1112. \fIioctl\fR()
  1113. shall fail if:
  1114. .TP
  1115. .BR EBADF
  1116. The
  1117. .IR fildes
  1118. argument is not a valid open file descriptor.
  1119. .TP
  1120. .BR EINTR
  1121. A signal was caught during the
  1122. \fIioctl\fR()
  1123. operation.
  1124. .TP
  1125. .BR EINVAL
  1126. The STREAM or multiplexer referenced by
  1127. .IR fildes
  1128. is linked (directly or indirectly) downstream from a multiplexer.
  1129. .P
  1130. If an underlying device driver detects an error, then
  1131. \fIioctl\fR()
  1132. shall fail if:
  1133. .TP
  1134. .BR EINVAL
  1135. The
  1136. .IR request
  1137. or
  1138. .IR arg
  1139. argument is not valid for this device.
  1140. .TP
  1141. .BR EIO
  1142. Some physical I/O error has occurred.
  1143. .TP
  1144. .BR ENOTTY
  1145. The file associated with the
  1146. .IR fildes
  1147. argument is not a STREAMS device that accepts control functions.
  1148. .TP
  1149. .BR ENXIO
  1150. The
  1151. .IR request
  1152. and
  1153. .IR arg
  1154. arguments are valid for this device driver, but the service requested
  1155. cannot be performed on this particular sub-device.
  1156. .TP
  1157. .BR ENODEV
  1158. The
  1159. .IR fildes
  1160. argument refers to a valid STREAMS device, but the corresponding device
  1161. driver does not support the
  1162. \fIioctl\fR()
  1163. function.
  1164. .P
  1165. If a STREAM is connected downstream from a multiplexer, any
  1166. \fIioctl\fR()
  1167. command except I_UNLINK and I_PUNLINK shall set
  1168. .IR errno
  1169. to
  1170. .BR [EINVAL] .
  1171. .LP
  1172. .IR "The following sections are informative."
  1173. .SH EXAMPLES
  1174. None.
  1175. .SH "APPLICATION USAGE"
  1176. The implementation-defined timeout interval for STREAMS has
  1177. historically been 15 seconds.
  1178. .SH RATIONALE
  1179. None.
  1180. .SH "FUTURE DIRECTIONS"
  1181. The
  1182. \fIioctl\fR()
  1183. function may be removed in a future version.
  1184. .SH "SEE ALSO"
  1185. .IR "Section 2.6" ", " "STREAMS",
  1186. .IR "\fIclose\fR\^(\|)",
  1187. .IR "\fIfcntl\fR\^(\|)",
  1188. .IR "\fIgetmsg\fR\^(\|)",
  1189. .IR "\fIopen\fR\^(\|)",
  1190. .IR "\fIpipe\fR\^(\|)",
  1191. .IR "\fIpoll\fR\^(\|)",
  1192. .IR "\fIputmsg\fR\^(\|)",
  1193. .IR "\fIread\fR\^(\|)",
  1194. .IR "\fIsigaction\fR\^(\|)",
  1195. .IR "\fIwrite\fR\^(\|)"
  1196. .P
  1197. The Base Definitions volume of POSIX.1\(hy2017,
  1198. .IR "\fB<stropts.h>\fP"
  1199. .\"
  1200. .SH COPYRIGHT
  1201. Portions of this text are reprinted and reproduced in electronic form
  1202. from IEEE Std 1003.1-2017, Standard for Information Technology
  1203. -- Portable Operating System Interface (POSIX), The Open Group Base
  1204. Specifications Issue 7, 2018 Edition,
  1205. Copyright (C) 2018 by the Institute of
  1206. Electrical and Electronics Engineers, Inc and The Open Group.
  1207. In the event of any discrepancy between this version and the original IEEE and
  1208. The Open Group Standard, the original IEEE and The Open Group Standard
  1209. is the referee document. The original Standard can be obtained online at
  1210. http://www.opengroup.org/unix/online.html .
  1211. .PP
  1212. Any typographical or formatting errors that appear
  1213. in this page are most likely
  1214. to have been introduced during the conversion of the source files to
  1215. man page format. To report such errors, see
  1216. https://www.kernel.org/doc/man-pages/reporting_bugs.html .