Print this page
10530 Convert prnio(7I) to mandoc

Split Close
Expand all
Collapse all
          --- old/usr/src/man/man7i/prnio.7i.man.txt
          +++ new/usr/src/man/man7i/prnio.7i.man.txt
   1    1  PRNIO(7I)                       Ioctl Requests                       PRNIO(7I)
   2    2  
   3      -
   4      -
   5    3  NAME
   6      -       prnio - generic printer interface
        4 +     prnio - generic printer interface
   7    5  
   8    6  SYNOPSIS
   9      -       #include <sys/prnio.h>
        7 +     #include <sys/prnio.h>
  10    8  
  11      -
  12    9  DESCRIPTION
  13      -       The prnio generic printer interface defines ioctl commands and data
  14      -       structures for printer device drivers.
       10 +     The prnio generic printer interface defines ioctl commands and data
       11 +     structures for printer device drivers.
  15   12  
       13 +     prnio defines and provides facilities for five basic phases of the
       14 +     printing process:
  16   15  
  17      -       prnio defines and provides facilities for five basic phases of the
  18      -       printing process:
       16 +           o   Identification -- Retrieve device information/attributes
  19   17  
  20      -           o      Identification -- Retrieve device information/attributes
       18 +           o   Setup -- Set device attributes
  21   19  
  22      -           o      Setup -- Set device attributes
       20 +           o   Transfer -- Transfer data to or from the device
  23   21  
  24      -           o      Transfer -- Transfer data to or from the device
       22 +           o   Cleanup -- Transfer phase conclusion
  25   23  
  26      -           o      Cleanup -- Transfer phase conclusion
       24 +           o   Abort -- Transfer phase interruption
  27   25  
  28      -           o      Abort -- Transfer phase interruption
       26 +     During the Identification phase, the application retrieves a set of
       27 +     device capabilities and additional information using the
       28 +     PRNIOC_GET_IFCAP, PRNIOC_GET_STATUS, PRNIOC_GET_TIMEOUTS,
       29 +     PRNIOC_GET_IFINFO, and PRNIOC_GET_1284_DEVID commands.
  29   30  
       31 +     During the Setup phase the application sets some interface attributes and
       32 +     probably resets the printer as described in the PRNIOC_SET_IFCAP,
       33 +     PRNIOC_SET_TIMEOUTS, and PRNIOC_RESET sections.
  30   34  
  31      -       During the Identification phase, the application retrieves a set of
  32      -       device capabilities and additional information using the
  33      -       PRNIOC_GET_IFCAP, PRNIOC_GET_STATUS, PRNIOC_GET_TIMEOUTS,
  34      -       PRNIOC_GET_IFINFO and PRNIOC_GET_1284_DEVID commands.
       35 +     During the Transfer phase, data is transferred in a forward (host to
       36 +     peripheral) or reverse direction (peripheral to host).  Transfer is
       37 +     accomplished using write(2) and read(2) system calls.  For prnio
       38 +     compliant printer drivers, forward transfer support is mandatory, while
       39 +     reverse transfer support is optional.  Applications can also use
       40 +     PRNIOC_GET_STATUS and PRNIOC_GET_1284_STATUS commands during the transfer
       41 +     to monitor the device state.
  35   42  
       43 +     The Cleanup phase is accomplished by closing the device using close(2).
       44 +     Device drivers supporting prnio may set non-zero error code as
       45 +     appropriate.  Applications should explicitly close(2) a device before
       46 +     exiting and check errno value.
  36   47  
  37      -       During the Setup phase the application sets some interface attributes
  38      -       and probably resets the printer as described in the PRNIOC_SET_IFCAP,
  39      -       PRNIOC_SET_TIMEOUTS and PRNIOC_RESET sections.
       48 +     The Abort phase is accomplished by interrupting the write(2) and read(2)
       49 +     system calls.  The application can perform some additional cleanup during
       50 +     the Abort phase as described in PRNIOC_GET_IFCAP section.
  40   51  
  41      -
  42      -       During the Transfer phase, data is transferred in a forward (host to
  43      -       peripheral) or reverse direction (peripheral to host). Transfer is
  44      -       accomplished using write(2) and read(2) system calls. For prnio
  45      -       compliant printer drivers, forward transfer support is mandatory, while
  46      -       reverse transfer support is optional. Applications can also use
  47      -       PRNIOC_GET_STATUS and PRNIOC_GET_1284_STATUS commands during the
  48      -       transfer to monitor the device state.
  49      -
  50      -
  51      -       The Cleanup phase is accomplished by closing the device using close(2).
  52      -       Device drivers supporting prnio may set non-zero error code as
  53      -       appropriate. Applications should explicitly close(2) a device before
  54      -       exiting and check errno value.
  55      -
  56      -
  57      -       The Abort phase is accomplished by interrupting the write(2) and
  58      -       read(2) system calls. The application can perform some additional
  59      -       cleanup during the Abort phase as described in PRNIOC_GET_IFCAP
  60      -       section.
  61      -
  62   52  IOCTLS
  63      -       PRNIOC_GET_IFCAP
  64      -                            Application can retrieve printer interface
  65      -                            capabilities using this command. The ioctl(2)
  66      -                            argument is a pointer to uint_t, a bit field
  67      -                            representing a set of properties and services
  68      -                            provided by a printer driver. Set bit means
  69      -                            supported capability. The following values are
  70      -                            defined:
  71      -                              PRN_BIDI - When this bit is set,  the interface
  72      -                              operates in a bidirectional mode,  instead of
  73      -                              forward-only mode.
  74      -                              PRN_HOTPLUG - If this bit is set, the interface
  75      -                              allows device hot-plugging.
  76      -                              PRN_1284_DEVID - If this bit is set, the device
  77      -                              is capable of returning 1284 device ID (see
  78      -                              PRNIOC_GET_1284_DEVID.)
  79      -                              PRN_1284_STATUS - If this bit is set, the device
  80      -                              driver can return device status lines (see
  81      -                              PRNIOC_GET_1284_STATUS). Some devices support
  82      -                              this ioctl in unidirectional mode only.
  83      -                              PRN_TIMEOUTS - If this bit is set the peripheral
  84      -                              may stall during the transfer phase and the
  85      -                              driver can timeout and return from the write(2)
  86      -                              and read(2) returning the number of bytes that
  87      -                              have been transferred. If PRN_TIMEOUTS is set,
  88      -                              the driver supports this functionality and the
  89      -                              timeout values can be retrieved and modified via
  90      -                              the PRNIOC_GET_TIMEOUTS and PRNIOC_SET_TIMEOUTS
  91      -                              ioctls. Otherwise, applications can implement
  92      -                              their own timeouts and abort phase.
  93      -                              PRN_STREAMS - This bit impacts the application
  94      -                              abort phase behaviour. If the device claimed
  95      -                              PRN_STREAMS capability, the application must
  96      -                              issue an I_FLUSH ioctl(2) before close(2) to
  97      -                              dismiss the untransferred data. Only STREAMS
  98      -                              drivers can support this capability.
       53 +     PRNIOC_GET_IFCAP   Application can retrieve printer interface
       54 +                        capabilities using this command.  The ioctl(2)
       55 +                        argument is a pointer to uint_t, a bit field
       56 +                        representing a set of properties and services provided
       57 +                        by a printer driver.  Set bit means supported
       58 +                        capability.  The following values are defined:
  99   59  
       60 +                        PRN_BIDI         When this bit is set, the interface
       61 +                                         operates in a bidirectional mode,
       62 +                                         instead of forward-only mode.
 100   63  
 101      -       PRNIOC_SET_IFCAP
 102      -                            This ioctl can be used to change interface
 103      -                            capabilities. The argument is a pointer to uint_t
 104      -                            bit field that is described in detail in the
 105      -                            PRNIOC_GET_IFCAP section. Capabilities should be
 106      -                            set one at a time; otherwise the command will
 107      -                            return EINVAL. The following capabilities can be
 108      -                            changed by this ioctl:
 109      -                              PRN_BIDI - When this capability is set, the
 110      -                              interface operates in a bidirectional mode,
 111      -                              instead of forward-only mode. Devices that
 112      -                              support only one mode will not return error;
 113      -                              applications should use PRNIOC_GET_IFCAP to
 114      -                              check if the mode was successfully changed.
 115      -                              Because some capabilities may be altered as a
 116      -                              side effect of changing other capabilities, this
 117      -                              command should be followed by PRNIOC_GET_IFCAP.
       64 +                        PRN_HOTPLUG      If this bit is set, the interface
       65 +                                         allows device hot-plugging.
 118   66  
       67 +                        PRN_1284_DEVID   If this bit is set, the device is
       68 +                                         capable of returning 1284 device ID
       69 +                                         (see PRNIOC_GET_1284_DEVID).
 119   70  
 120      -       PRNIOC_GET_IFINFO
 121      -                            This command can be used to retrieve printer
 122      -                            interface info string, which is an arbitrary
 123      -                            format string usually describing the bus type. The
 124      -                            argument is a pointer to struct prn_interface_info
 125      -                            as described below.
       71 +                        PRN_1284_STATUS  If this bit is set, the device driver
       72 +                                         can return device status lines (see
       73 +                                         PRNIOC_GET_1284_STATUS).  Some
       74 +                                         devices support this ioctl in
       75 +                                         unidirectional mode only.
 126   76  
       77 +                        PRN_TIMEOUTS     If this bit is set the peripheral may
       78 +                                         stall during the transfer phase and
       79 +                                         the driver can timeout and return
       80 +                                         from the write(2) and read(2)
       81 +                                         returning the number of bytes that
       82 +                                         have been transferred.  If
       83 +                                         PRN_TIMEOUTS is set, the driver
       84 +                                         supports this functionality and the
       85 +                                         timeout values can be retrieved and
       86 +                                         modified via the PRNIOC_GET_TIMEOUTS
       87 +                                         and PRNIOC_SET_TIMEOUTS ioctls.
       88 +                                         Otherwise, applications can implement
       89 +                                         their own timeouts and abort phase.
 127   90  
 128      -         struct prn_interface_info {
 129      -           uint_t    if_len;   /* length of buffer */
 130      -           uint_t    if_rlen;  /* actual info length */
 131      -           char   *if_data;  /* buffer address */
 132      -         };
       91 +                        PRN_STREAMS      This bit impacts the application
       92 +                                         abort phase behaviour.  If the device
       93 +                                         claimed PRN_STREAMS capability, the
       94 +                                         application must issue an I_FLUSH
       95 +                                         ioctl(2) before close(2) to dismiss
       96 +                                         the untransferred data.  Only STREAMS
       97 +                                         drivers can support this capability.
 133   98  
       99 +     PRNIOC_SET_IFCAP   This ioctl can be used to change interface
      100 +                        capabilities.  The argument is a pointer to uint_t bit
      101 +                        field that is described in detail in the
      102 +                        PRNIOC_GET_IFCAP section.  Capabilities should be set
      103 +                        one at a time; otherwise the command will return
      104 +                        EINVAL.  The following capabilities can be changed by
      105 +                        this ioctl:
 134  106  
      107 +                        PRN_BIDI  When this capability is set, the interface
      108 +                                  operates in a bidirectional mode, instead of
      109 +                                  forward-only mode.  Devices that support
      110 +                                  only one mode will not return error;
      111 +                                  applications should use PRNIOC_GET_IFCAP to
      112 +                                  check if the mode was successfully changed.
      113 +                                  Because some capabilities may be altered as
      114 +                                  a side effect of changing other
      115 +                                  capabilities, this command should be
      116 +                                  followed by PRNIOC_GET_IFCAP.
 135  117  
 136      -       The application allocates a buffer and sets if_data and if_len values
 137      -       to its address and length, respectively. The driver returns the string
 138      -       to this buffer and sets  if_len to its length. If   if_len is less that
 139      -       if_rlen, the driver must return the first if_len bytes of the string.
 140      -       The application  may then repeat the command with a bigger buffer.
      118 +     PRNIOC_GET_IFINFO  This command can be used to retrieve printer interface
      119 +                        info string, which is an arbitrary format string
      120 +                        usually describing the bus type.  The argument is a
      121 +                        pointer to struct prn_interface_info as described
      122 +                        below.
 141  123  
      124 +                          struct prn_interface_info {
      125 +                            uint_t          if_len;   /* length of buffer */
      126 +                            uint_t          if_rlen;  /* actual info length */
      127 +                            char   *if_data;          /* buffer address */
      128 +                          };
 142  129  
 143      -       Although prnio does not limit the contents of the interface info
 144      -       string, some values are recommended and defined in <sys/prnio.h> by the
 145      -       following macros:
 146      -         PRN_PARALLEL - Centronics or IEEE 1284 compatible devices
 147      -         PRN_SERIAL - EIA-232/EIA-485 serial ports
 148      -         PRN_USB - Universal Serial Bus printers
 149      -         PRN_1394 - IEEE 1394 peripherals
 150      -         Printer interface info string is for information only: no
 151      -         implications should be made from its value.
      130 +                        The application allocates a buffer and sets if_data
      131 +                        and if_len values to its address and length,
      132 +                        respectively.  The driver returns the string to this
      133 +                        buffer and sets if_len to its length.  If if_len is
      134 +                        less than if_rlen, the driver must return the first
      135 +                        if_len bytes of the string.  The application may then
      136 +                        repeat the command with a bigger buffer.
 152  137  
 153      -       PRNIOC_RESET
 154      -                                Some applications may want to reset the
 155      -                                printer state during Setup and/or Cleanup
 156      -                                phase using PRNIOC_RESET command. Reset
 157      -                                semantics are device-specific, and in general,
 158      -                                applications using this command should be
 159      -                                aware of the printer type.
      138 +                        Although prnio does not limit the contents of the
      139 +                        interface info string, some values are recommended and
      140 +                        defined in <sys/prnio.h> by the following macros:
 160  141  
 161      -                                Each prnio compliant driver is required to
 162      -                                accept this request, although performed
 163      -                                actions are completely driver-dependent. More
 164      -                                information on the PRNIOC_RESET implementation
 165      -                                for the particular driver is available in the
 166      -                                corresponding man page and printer manual.
      142 +                        PRN_PARALLEL  Centronics or IEEE 1284 compatible
      143 +                                      devices
      144 +                        PRN_SERIAL    EIA-232/EIA-485 serial ports
      145 +                        PRN_USB       Universal Serial Bus printers
      146 +                        PRN_1394      IEEE 1394 peripherals
 167  147  
      148 +                        Printer interface info string is for information only:
      149 +                        no implications should be made from its value.
 168  150  
 169      -       PRNIOC_GET_1284_DEVID
 170      -                                This command can be used to retrieve printer
 171      -                                device ID as defined by IEEE 1284-1994.The
 172      -                                ioctl(2) argument is a pointer to struct
 173      -                                prn_1284_device_id as described below.
      151 +     PRNIOC_RESET       Some applications may want to reset the printer state
      152 +                        during Setup and/or Cleanup phase using PRNIOC_RESET
      153 +                        command.  Reset semantics are device-specific, and in
      154 +                        general, applications using this command should be
      155 +                        aware of the printer type.
 174  156  
      157 +                        Each prnio compliant driver is required to accept this
      158 +                        request, although performed actions are completely
      159 +                        driver-dependent.  More information on the
      160 +                        PRNIOC_RESET implementation for the particular driver
      161 +                        is available in the corresponding man page and printer
      162 +                        manual.
 175  163  
 176      -         struct prn_1284_device_id {
 177      -            uint_t   id_len;   /* length of buffer */
 178      -            uint_t   id_rlen;  /* actual ID length */
 179      -            char      *id_data;  /* buffer address */
 180      -         };
      164 +     PRNIOC_GET_1284_DEVID
      165 +                        This command can be used to retrieve printer device ID
      166 +                        as defined by IEEE 1284-1994.  The ioctl(2) argument
      167 +                        is a pointer to struct prn_1284_device_id as described
      168 +                        below.
 181  169  
      170 +                          struct prn_1284_device_id {
      171 +                             uint_t         id_len;   /* length of buffer */
      172 +                             uint_t         id_rlen;  /* actual ID length */
      173 +                             char           *id_data; /* buffer address */
      174 +                          };
 182  175  
      176 +                        For convenience, the two-byte length field is not
      177 +                        considered part of device ID string and is not
      178 +                        returned in the user buffer.  Instead, id_rlen value
      179 +                        shall be set to (length - 2) by the driver, where
      180 +                        length is the ID length field value.  If buffer length
      181 +                        is less than id_rlen, the driver returns the first
      182 +                        id_len bytes of the ID.
 183  183  
 184      -       For convenience, the two-byte length field is not considered part of
 185      -       device ID string and is not returned in the user buffer. Instead,
 186      -       id_rlen  value shall be set to (length - 2) by the driver, where length
 187      -       is the ID length field value. If buffer length is less than id_rlen,
 188      -       the driver returns the first id_len bytes of the ID.
      184 +                        The printer driver must return the most up-to-date
      185 +                        value of the device ID.
 189  186  
      187 +     PRNIOC_GET_STATUS  This command can be used by applications to retrieve
      188 +                        current device status.  The argument is a pointer to
      189 +                        uint_t, where the status word is returned.  Status is
      190 +                        a combination of the following bits:
 190  191  
 191      -       The printer driver must return the most up-to-date value of the device
 192      -       ID.
      192 +                        PRN_ONLINE  For devices that support PRN_HOTPLUG
      193 +                                    capability, this bit is set when the
      194 +                                    device is online, otherwise the device is
      195 +                                    offline.  Devices without PRN_HOTPLUG
      196 +                                    support should always have this bit set.
 193  197  
 194      -       PRNIOC_GET_STATUS
 195      -                            This command can be used by applications to
 196      -                            retrieve current device status. The argument is a
 197      -                            pointer to uint_t, where the status word is
 198      -                            returned.  Status is a combination of the
 199      -                            following bits:
      198 +                        PRN_READY   This bit indicates if the device is ready
      199 +                                    to receive/send data.  Applications may
      200 +                                    use this bit for an outbound flow control.
 200  201  
 201      -         PRN_ONLINE - For devices that support PRN_HOTPLUG capability, this
 202      -         bit is set when the device is online, otherwise the device is
 203      -         offline.  Devices without PRN_HOTPLUG support should always have this
 204      -         bit set.
 205      -         PRN_READY - This bit indicates if the device is ready to receive/send
 206      -         data. Applications may use this bit for an outbound flow control
      202 +     PRNIOC_GET_1284_STATUS
      203 +                        Devices that support PRN_1284_STATUS capability accept
      204 +                        this ioctl to retrieve the device status lines defined
      205 +                        in IEEE 1284 for use in Compatibility mode.  The
      206 +                        following bits may be set by the driver:
 207  207  
 208      -       PRNIOC_GET_1284_STATUS
 209      -                                 Devices that support PRN_1284_STATUS
 210      -                                 capability accept this ioctl to retrieve the
 211      -                                 device status lines defined in IEEE 1284 for
 212      -                                 use in Compatibility mode. The following bits
 213      -                                 may be set by the driver:
 214      -                                   PRN_1284_NOFAULT - Device is not in error
 215      -                                   state
 216      -                                   PRN_1284_SELECT - Device is selected
 217      -                                   PRN_1284_PE - Paper error
 218      -                                   PRN_1284_BUSY - Device is busy
      208 +                        PRN_1284_NOFAULT  Device is not in error state
      209 +                        PRN_1284_SELECT   Device is selected
      210 +                        PRN_1284_PE       Paper error
      211 +                        PRN_1284_BUSY     Device is busy
 219  212  
      213 +     PRNIOC_GET_TIMEOUTS
      214 +                        This command retrieves current transfer timeout values
      215 +                        for the driver.  The argument is a pointer to struct
      216 +                        prn_timeouts as described below.
 220  217  
 221      -       PRNIOC_GET_TIMEOUTS
 222      -                                 This command  retrieves current transfer
 223      -                                 timeout values for  the driver. The argument
 224      -                                 is  a pointer to struct prn_timeouts as
 225      -                                 described below.
      218 +                          struct prn_timeouts {
      219 +                              uint_t tmo_forward; /* forward transfer timeout */
      220 +                              uint_t tmo_reverse; /* reverse transfer timeout */
      221 +                          };
 226  222  
      223 +                        tmo_forward and tmo_reverse define forward and reverse
      224 +                        transfer timeouts in seconds.  This command is only
      225 +                        valid for drivers that support PRN_TIMEOUTS
      226 +                        capability.
 227  227  
 228      -         struct prn_timeouts {
 229      -           uint_t  tmo_forward;  /* forward transfer timeout */
 230      -           uint_t  tmo_reverse;  /* reverse transfer timeout */
 231      -              };
      228 +     PRNIOC_SET_TIMEOUTS
      229 +                        This command sets current transfer timeout values for
      230 +                        the driver.  The argument is a pointer to struct
      231 +                        prn_timeouts.  See PRNIOC_GET_TIMEOUTS for description
      232 +                        of this structure.  This command is only valid for
      233 +                        drivers that support PRN_TIMEOUTS capability.
 232  234  
 233      -
 234      -
 235      -       tmo_forward and tmo_reverse define forward and reverse transfer
 236      -       timeouts in seconds. This command is only valid for drivers that
 237      -       support PRN_TIMEOUTS capability.
 238      -
 239      -       PRNIOC_SET_TIMEOUTS
 240      -                              This command sets current transfer  timeout
 241      -                              values for the driver. The argument is  a
 242      -                              pointer to struct prn_timeouts. See
 243      -                              PRNIOC_GET_TIMEOUTS for description of  this
 244      -                              structure. This  command is only valid for
 245      -                              drivers that support PRN_TIMEOUTS capability.
 246      -
 247      -
 248      -ATTRIBUTES
 249      -       See attributes(5) for descriptions of the following attributes:
 250      -
 251      -
 252      -
 253      -
 254      -       +--------------------+-----------------+
 255      -       |  ATTRIBUTE TYPE    | ATTRIBUTE VALUE |
 256      -       +--------------------+-----------------+
 257      -       |Architecture        |  SPARC, IA      |
 258      -       +--------------------+-----------------+
 259      -       |Interface Stability | Evolving        |
 260      -       +--------------------+-----------------+
 261      -
 262  235  SEE ALSO
 263      -       close(2), ioctl(2), read(2), write(2), attributes(5), ecpp(7D),
 264      -       usbprn(7D), lp(7D)
      236 +     close(2), ioctl(2), read(2), write(2), attributes(5), ecpp(7D), lp(7D),
      237 +     usbprn(7D)
 265  238  
      239 +     IEEE Std 1284-1994.
 266  240  
 267      -       IEEE Std 1284-1994
 268      -
 269      -
 270      -
 271      -                                January 2, 2002                      PRNIO(7I)
      241 +illumos                         August 31, 2018                        illumos
    
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX