diff options
Diffstat (limited to 'usr/src/man/man4i/prnio.4i')
| -rw-r--r-- | usr/src/man/man4i/prnio.4i | 370 |
1 files changed, 370 insertions, 0 deletions
diff --git a/usr/src/man/man4i/prnio.4i b/usr/src/man/man4i/prnio.4i new file mode 100644 index 0000000000..be44b17a66 --- /dev/null +++ b/usr/src/man/man4i/prnio.4i @@ -0,0 +1,370 @@ +.\" Copyright (c) 20002 Sun Microsystems, Inc. +.\" All Rights Reserved. +.\" Copyright 2018, Joyent, Inc. +.\" The contents of this file are subject to the terms of the +.\" Common Development and Distribution License (the "License"). +.\" You may not use this file except in compliance with the License. +.\" +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE +.\" or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions +.\" and limitations under the License. +.\" +.\" When distributing Covered Code, include this CDDL HEADER in each +.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. +.\" If applicable, add the following below this CDDL HEADER, with the +.\" fields enclosed by brackets "[]" replaced with your own identifying +.\" information: Portions Copyright [yyyy] [name of copyright owner] +.Dd August 31, 2018 +.Dt PRNIO 4I +.Os +.Sh NAME +.Nm prnio +.Nd generic printer interface +.Sh SYNOPSIS +.In sys/prnio.h +.Sh DESCRIPTION +The +.Nm +generic printer interface defines ioctl commands and data +structures for printer device drivers. +.Pp +.Nm +defines and provides facilities for five basic phases of the printing process: +.Bl -bullet -offset indent +.It +Identification \(em Retrieve device information/attributes +.It +Setup \(em Set device attributes +.It +Transfer \(em Transfer data to or from the device +.It +Cleanup \(em Transfer phase conclusion +.It +Abort \(em Transfer phase interruption +.El +.Pp +During the Identification phase, the application retrieves a set of device +capabilities and additional information using the +.Dv PRNIOC_GET_IFCAP , +.Dv PRNIOC_GET_STATUS , +.Dv PRNIOC_GET_TIMEOUTS , +.Dv PRNIOC_GET_IFINFO , +and +.Dv PRNIOC_GET_1284_DEVID +commands. +.Pp +During the Setup phase the application sets some interface attributes and +probably resets the printer as described in the +.Dv PRNIOC_SET_IFCAP , +.Dv PRNIOC_SET_TIMEOUTS , +and +.Dv PRNIOC_RESET +sections. +.Pp +During the Transfer phase, data is transferred in a forward (host to +peripheral) or reverse direction (peripheral to host). +Transfer is accomplished +using +.Xr write 2 +and +.Xr read 2 +system calls. +For +.Nm +compliant +printer drivers, forward transfer support is mandatory, while reverse transfer +support is optional. +Applications can also use +.Dv PRNIOC_GET_STATUS +and +.Dv PRNIOC_GET_1284_STATUS +commands during the transfer to monitor the device state. +.Pp +The Cleanup phase is accomplished by closing the device using +.Xr close 2 . +Device drivers supporting +.Nm +may set non-zero error code as appropriate. +Applications should explicitly +.Xr close 2 +a device before +exiting and check +.Va errno +value. +.Pp +The Abort phase is accomplished by interrupting the +.Xr write 2 +and +.Xr read 2 +system calls. +The application can perform some additional cleanup +during the Abort phase as described in +.Dv PRNIOC_GET_IFCAP +section. +.Sh IOCTLS +.Bl -tag -width PRNIOC_GET_IFINFO +.It Dv PRNIOC_GET_IFCAP +Application can retrieve printer interface capabilities using this command. +The +.Xr ioctl 2 +argument is a pointer to +.Vt uint_t , +a bit field representing +a set of properties and services provided by a printer driver. +Set bit means supported capability. +The following values are defined: +.Bl -tag -width PRN_1284_STATUS +.It Dv PRN_BIDI +When this bit is set, the interface operates in a +bidirectional mode, instead of forward-only mode. +.It Dv PRN_HOTPLUG +If this bit is set, the interface allows device hot-plugging. +.It Dv PRN_1284_DEVID +If this bit is set, the device is capable of returning +.Em 1284 +device ID (see +.Dv PRNIOC_GET_1284_DEVID ) . +.It Dv PRN_1284_STATUS +If this bit is set, the device driver can return device +status lines (see +.Dv PRNIOC_GET_1284_STATUS ) . +Some devices support this +ioctl in unidirectional mode only. +.It Dv PRN_TIMEOUTS +If this bit is set the peripheral may stall during the +transfer phase and the driver can timeout and return from the +.Xr write 2 +and +.Xr read 2 +returning the number of bytes that have been transferred. +If +.Dv PRN_TIMEOUTS +is set, the driver supports this functionality and the +timeout values can be retrieved and modified via the +.Dv PRNIOC_GET_TIMEOUTS +and +.Dv PRNIOC_SET_TIMEOUTS +ioctls. +Otherwise, applications can implement +their own timeouts and abort phase. +.It Dv PRN_STREAMS +This bit impacts the application abort phase behaviour. +If the device claimed +.Dv PRN_STREAMS +capability, the application must issue an +.Dv I_FLUSH +.Xr ioctl 2 +before +.Xr close 2 +to dismiss the untransferred +data. +Only STREAMS drivers can support this capability. +.El +.It Dv PRNIOC_SET_IFCAP +This ioctl can be used to change interface capabilities. +The argument is a pointer to +.Vt uint_t +bit field that is described in detail in the +.Dv PRNIOC_GET_IFCAP +section. +Capabilities should be set one at a time; +otherwise the command will return +.Er EINVAL . +The following capabilities can be changed by this ioctl: +.Bl -tag -width PRN_BIDI +.It Dv PRN_BIDI +When this capability is set, the interface operates in a +bidirectional mode, instead of forward-only mode. +Devices that support only one +mode will not return error; applications should use +.Dv PRNIOC_GET_IFCAP +to check if the mode was successfully changed. +Because some capabilities may be +altered as a side effect of changing other capabilities, this command should be +followed by +.Dv PRNIOC_GET_IFCAP . +.El +.It Dv PRNIOC_GET_IFINFO +This command can be used to retrieve printer interface info string, which is an +arbitrary format string usually describing the bus type. +The argument is a +pointer to +.Vt struct prn_interface_info +as described below. +.Bd -literal -offset 2n +struct prn_interface_info { + uint_t if_len; /* length of buffer */ + uint_t if_rlen; /* actual info length */ + char *if_data; /* buffer address */ +}; +.Ed +.Pp +The application allocates a buffer and sets +.Fa if_data +and +.Fa if_len +values to its address and length, respectively. +The driver returns the string +to this buffer and sets +.Fa if_len +to its length. +If +.Fa if_len +is less +than +.Fa if_rlen , +the driver must return the first +.Fa if_len +bytes of the string. +The application may then repeat the command with a bigger buffer. +.Pp +Although +.Nm +does not limit the contents of the interface info string, +some values are recommended and defined in +.In sys/prnio.h +by the following macros: +.Pp +.Bl -tag -width PRN_PARALLEL -compact +.It Dv PRN_PARALLEL +Centronics or +.Em IEEE 1284 +compatible devices +.It Dv PRN_SERIAL +EIA-232/EIA-485 serial ports +.It Dv PRN_USB +Universal Serial Bus printers +.It Dv PRN_1394 +.Em IEEE 1394 +peripherals +.El +.Pp +Printer interface info string is for information only: no implications should +be made from its value. +.It Dv PRNIOC_RESET +Some applications may want to reset the printer state during Setup and/or +Cleanup phase using +.Dv PRNIOC_RESET +command. +Reset semantics are +device-specific, and in general, applications using this command should be +aware of the printer type. +.Pp +Each +.Nm +compliant driver is required to accept this request, although +performed actions are completely driver-dependent. +More information on the +.Dv PRNIOC_RESET +implementation for the particular driver is available in the +corresponding man page and printer manual. +.It Dv PRNIOC_GET_1284_DEVID +This command can be used to retrieve printer device ID as defined by +.Em IEEE 1284-1994 . +The +.Xr ioctl 2 +argument is a pointer to +.Vt struct prn_1284_device_id +as described below. +.Bd -literal -offset 2n +struct prn_1284_device_id { + uint_t id_len; /* length of buffer */ + uint_t id_rlen; /* actual ID length */ + char *id_data; /* buffer address */ +}; +.Ed +.Pp +For convenience, the two-byte length field is not considered part of device ID +string and is not returned in the user buffer. +Instead, +.Fa id_rlen +value shall be set to (length - 2) by the driver, where length is the ID +length field value. +If buffer length is less than +.Fa id_rlen , +the driver returns the first +.Fa id_len +bytes of the ID. +.Pp +The printer driver must return the most up-to-date value of the device ID. +.It Dv PRNIOC_GET_STATUS +This command can be used by applications to retrieve current device status. +The argument is a pointer to +.Vt uint_t , +where the status word is returned. +Status is a combination of the following bits: +.Bl -tag -width PRN_ONLINE +.It Dv PRN_ONLINE +For devices that support +.Dv PRN_HOTPLUG +capability, this bit is set when the device is online, otherwise the device is +offline. +Devices without +.Dv PRN_HOTPLUG +support should always have this bit set. +.It Dv PRN_READY +This bit indicates if the device is ready to receive/send data. +Applications may use this bit for an outbound flow control. +.El +.It Dv PRNIOC_GET_1284_STATUS +Devices that support +.Dv PRN_1284_STATUS +capability accept this ioctl to +retrieve the device status lines defined in +.Em IEEE 1284 +for use in Compatibility mode. +The following bits may be set by the driver: +.Pp +.Bl -tag -width PRN_1284_NOFAULT -compact +.It Dv PRN_1284_NOFAULT +Device is not in error state +.It Dv PRN_1284_SELECT +Device is selected +.It Dv PRN_1284_PE +Paper error +.It Dv PRN_1284_BUSY +Device is busy +.El +.It Dv PRNIOC_GET_TIMEOUTS +This command retrieves current transfer timeout values for the driver. +The argument is a pointer to +.Vt struct prn_timeouts +as described below. +.Bd -literal -offset 2n +struct prn_timeouts { + uint_t tmo_forward; /* forward transfer timeout */ + uint_t tmo_reverse; /* reverse transfer timeout */ +}; +.Ed +.Pp +.Fa tmo_forward +and +.Fa tmo_reverse +define forward and reverse transfer timeouts in seconds. +This command is only valid for drivers that support +.Dv PRN_TIMEOUTS +capability. +.It Dv PRNIOC_SET_TIMEOUTS +This command sets current transfer timeout values for the driver. +The argument is a pointer to +.Vt struct prn_timeouts . +See +.Sx PRNIOC_GET_TIMEOUTS +for description of this structure. +This command is only valid for drivers that support +.Dv PRN_TIMEOUTS +capability. +.El +.Sh SEE ALSO +.Xr close 2 , +.Xr ioctl 2 , +.Xr read 2 , +.Xr write 2 , +.Xr ecpp 4D , +.Xr lp 4D , +.Xr usbprn 4D , +.Xr attributes 7 +.Rs +.%T IEEE Std 1284-1994 +.Re |