lp Special File

Purpose

Provides access to the line printer device driver.

Description

The lp driver provides an interface to the port used by a printer.

Printer Modes

The lp driver interprets carriage returns, backspaces, line feeds, tabs, and form feeds in accordance with the modes that are set in the driver (through the splp command or configuration). The number of lines per page, columns per line, and the indentation at the beginning of each line can also be selected. The default for these modes can be found using the lsattr command. The following modes can be set with the LPRMODS ioctl operation:

Item Description
PLOT Determines if the data stream is interpreted by the device driver when formatting the text. If the PLOT mode is off, the text is formatted using the current values set with the LPRSET ioctl operation.

If the PLOT mode is set, no interpretation of the data stream is performed and the bytes are sent to the printer without modification. Setting the PLOT mode causes other formatting modes, such as NOFF and NOFL, to be ignored. The default printer backend, piobe, sends all output in PLOT mode.

When in PLOT mode, the application must send a final form-feed character. If the last write operation was performed while not in PLOT mode, the final form-feed character will be sent by the device driver.
NOFF If this mode is on, each form-feed character is replaced with a line-feed character, based on the current line value set with the LPRSET ioctl operation. This mode is ignored if the PLOT mode is active.
NONL If this mode is on, each line-feed character is replaced with a carriage return. This mode is ignored if the PLOT mode is active.
NOCL If this mode is off, a carriage return is inserted after each line-feed character. If the mode is on, no carriage return is inserted after the line-feed character. This mode is ignored if the PLOT mode is active.
NOTAB If this mode off, 8 position tabs are simulated using spaces. If the NOTAB mode is on, the tab character is replaced with a space. This mode is ignored if the PLOT mode is active.
NOBS If this mode off, backspaces are sent to the printers. If the NOBS mode is on, the backspace is simulated by sending a carriage return followed by spaces to the proper print position. This mode is ignored if the PLOT mode is active.
NOCR If this mode on, each carriage return is replaced with a line-feed character. This mode is ignored if the PLOT mode is active.
CAPS If this mode on, lowercase characters are converted to uppercase. This mode is ignored if the PLOT mode is active.
WRAP If this mode off, the line is truncated at the right margin and any characters received past the right margin are discarded. If the WRAP mode is on, the characters received after the right margin are printed on the next line preceded by ... (ellipsis). This mode is ignored if the PLOT mode is active.
FONTINIT The FONTINIT mode is initially off. It is turned on by an application when a printer font has been initialized. It can be turned off in the following two cases:
  • An application needs fonts to be reinitialized.
  • A fatal printer error occurs. In this case, the lp device driver turns the FONTINIT mode off.
RPTERR If the RPTERR mode is off and an error occurs, the device driver does not return until the error has been cleared or a cancel signal is received. If the RPTERR mode is on, the device driver waits the amount of time specified by a previous LPRSTOV ioctl operation and then returns with an error.
IGNOREPE If IGNOREPE mode is on, the device driver allows writes to the device regardless of the state of the PE (paper-end) line on the parallel interface. An application can make use of this mode, for example, to change the paper tray of a printer under software control when detecting that the printer is out of paper.

Error Handling When the RPTERR Mode Is Off

If the RPTERR mode is off, no error reporting is performed. The device driver waits for the error to be cleared or a cancel signal to be received before returning to the application. RPTERR is the default mode and is intended for existing applications that do not perform error recovery.

If a signal is received by the device driver, the current operation is returned incomplete with an EINTR error code.

If printing is canceled and the printer is in PLOT mode, it is the application must send the final form-feed character to eject the partial page. If the printer is not in PLOT mode, the final form-feed character after cancelation will be sent by the device driver.

Error Handling When the RPTERR Mode Is On

If the RPTERR mode is on, the device driver will wait for the time specified in the v_timeout configuration parameter and then return the uncompleted operation with an error code. This return allows the application to get the printer status and possibly display an error message.
Note: When a device driver returns an incomplete operation with an error code (as previously described), the application must resend any data not printed.

Usage Considerations

Device-Dependent Subroutines

Most printer operations are implemented using the open, read, write, and close subroutines. However, these subroutines provide little or no information to the calling program about the configuration and state of the printer. The ioctl subroutine provides a more device-specific interface to the printer device driver.

Most of these subroutines pass data contained in structures. In all cases, a structure of the type indicated should be allocated in the calling routine. A pointer to this structure should then be passed to the device driver.

open and close Subroutines

If an adapter for a printer is not installed, an attempt to open fails. If the printer adapter is busy, the open subroutine returns an error. However, all child processes created by a parent process that successfully opens the lp special file inherit the open printer.

The driver allows multiple open subroutines to occur if they all have a mode parameter value of read-only. Thus, the splp command can perform inquiries when the printer adapter is currently in use. The lp driver allows only one process to write to a printer adapter at a time.

The close subroutine waits until all output completes before returning to the user.

read and write Subroutines

The read subroutine is not implemented for the native I/O parallel port.

When printing to a parallel printer that is offline, the write subroutine may return one fewer than the actual number of bytes that are buffered and ready to be written when the printer is put back online. This is used as a mechanism to indicate to the calling application that there is a problem with the printer requiring user intervention, possibly allowing the user to put the printer online and continue with printing. In this situation, no error is returned by the write subroutine.

ioctl Subroutine

The possible ioctl operations and their descriptions are:

Item Description
IOCINFO Returns a structure defined in the /usr/include/sys/devinfo.h file, which describes the device.
LPQUERY Provides access to the printer status. Refer to the /usr/include/sys/lpio.h file for value definitions. The types of errors are the following:
  • The printer is out of paper.
  • No select bit: the printer may be turned off or not installed.
  • The printer is busy.
  • The printer is unknown.
LPRGET Returns the page length, width and indentation values. These values are used by the device driver when PLOT mode is not set. The default printer backend, piobe, sends all print jobs with PLOT mode set. The LPRGET operation uses the lprio structure, as defined in the /usr/include/sys/lpio.h file.
LPRGETA Gets the RS232 parameters. These are the values for baud rate, character rate, character size, stop bits and parity. Refer to the LPR232 structure and to the termio structure, as defined in the termios.h file.
Note: This operation is supported for compatibility reasons. The use of the tcgetattr subroutine is recommended.
LPRGTOV Gets the current time-out value and stores it in the lptimer structure defined in the /usr/include/sys/lpio.h file. The time-out value is measured in seconds.
LPRMODG Gets the printer modes. These printer modes support the various formatting options and error reporting. This ioctl operation uses the LPRMOD structure, as defined in the /usr/include/sys/lpio.h file.
LPRMODS Sets the printer modes. These printer modes support the various formatting options and error reporting. This ioctl operation uses the LPRMOD structure, as defined in the /usr/include/sys/lpio.h file.
LPRSET Sets the page length, width and indent values. These values are used by the device driver when PLOT mode is not set. The default printer backend, piobe, sends all print jobs with PLOT mode set. The LPRSET operation uses the lprio structure, as defined in the /usr/include/sys/lpio.h file.
LPRSETA Sets the RS232 parameters. These are the values for baud rate, character rate, character size, stop bits and parity. Refer to the LPR232 structure and to the termio structure, as defined in the termios.h header file.
Note: This operation is supported for compatibility reasons. The use of the tcsetattr subroutine is recommended.
LPRSTOV Sets the time-out value. The arg parameter to this ioctl operation points to a lptimer structure defined in the /usr/include/sys/lpio.h file. The time-out value must be given in seconds.