'\" te
.\" Copyright (C) 2006, Sun Microsystems, Inc. All Rights Reserved
.\" 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]
.TH PRINTERS 4 "Jun 5, 2006"
.SH NAME
printers \- user-configurable printer alias database
.SH SYNOPSIS
.LP
.nf
$HOME/.printers
.fi

.SH DESCRIPTION
.sp
.LP
The \fB$HOME/.printers\fR file is a simplified version of the system
\fB/etc/printers.conf\fR file. See \fBprinters.conf\fR(4). Users create the
\fB$HOME/.printers\fR file in their home directory. This optional file is
customizable by the user.
.sp
.LP
The \fB$HOME/.printers\fR file performs the following functions:
.RS +4
.TP
1.
Sets personal aliases for all print commands.
.RE
.RS +4
.TP
2.
Sets the interest list for the \fBlpget\fR, \fBlpstat\fR, and \fBcancel\fR
commands. See \fBlpget\fR(1M), \fBlpstat\fR(1) and \fBcancel\fR(1).
.RE
.RS +4
.TP
3.
Sets the default printer for the \fBlp\fR, \fBlpr\fR, \fBlpq\fR, and
\fBlprm\fR commands. See \fBlp\fR(1), \fBlpr\fR(1B), \fBlpq\fR(1B), and
\fBlprm\fR(1B).
.RE
.SS "Entries"
.sp
.LP
Use a line or full screen editor to create or modify the \fB$HOME/.printers\fR
file.
.sp
.LP
Each entry in \fB$HOME/.printers\fR describes one destination. Entries are one
line consisting of two fields separated by either BLANKs or TABs and terminated
by a NEWLINE. Format for an entry in \fB$HOME/.printers\fR varies according to
the purpose of the entry.
.sp
.LP
Empty lines can be included for readability. Entries can continue on to
multiple lines by adding a backslash (`\fB\e\fR\&') as the last character in
the line. The \fB$HOME/.printers\fR file can include comments. Comments have a
pound sign (`\fB#\fR') as the first character in the line, and are terminated
by a NEWLINE.
.SS "Setting Personal Aliases"
.sp
.LP
Specify the alias or aliases in the first field. Separate multiple aliases by a
pipe sign (`\fB|\fR'). Specify the destination in the second field. A
destination names a printer or class of printers, See \fBlpadmin\fR(1M).
Specify the destination using atomic, URI-style
(\fIscheme\fR\fB://\fR\fBendpoint\fR), or POSIX-style
(\fIserver\fR\fB:\fR\fIdestination\fR) names. See \fBprinters.conf\fR(4) for
information regarding the naming conventions for destination names.
.SS "Setting the Interest List for lpget, lpstat and cancel"
.sp
.LP
Specify \fB_all\fR in the first field. Specify the list of destinations for the
interest list in the second field. Separate each destinations by a comma
(`\fB,\fR'). Specify destinations using atomic, URI-style
(\fIscheme\fR\fB://\fR\fBendpoint\fR), or POSIX-style
(\fIserver\fR\fB:\fR\fIdestination\fR) names. See \fBprinters.conf\fR(4) for
information regarding the naming conventions for destination names. This list
of destinations can refer to an alias defined in \fB$HOME/.printers\fR.
.SS "Setting the Default Destination"
.sp
.LP
Specify \fB_default\fR in the first field. Specify the default destination in
the second field. Specify the default destination using atomic, URI-style
(\fIscheme\fR\fB://\fR\fBendpoint\fR), or POSIX-style
(\fIserver\fR\fB:\fR\fIdestination\fR) names. See \fBprinters.conf\fR(4) for
information regarding the naming conventions for destination names. The default
destination can refer to an alias defined in \fB$HOME/.printers\fR.
.SS "Locating Destination Information"
.sp
.LP
The print client commands locate destination information based on the
"printers" database entry in the \fB/etc/nsswitch.conf\fR file. See
\fBnsswitch.conf\fR(4).
.SS "Locating the Personal Default Destination"
.sp
.LP
The default destination is located differently depending on the command.
.sp
.LP
The \fBlp\fR command locates the default destination in the following order:
.RS +4
.TP
1.
\fBlp\fR command's \fB-d\fR \fIdestination\fR option.
.RE
.RS +4
.TP
2.
\fBLPDEST\fR environment variable.
.RE
.RS +4
.TP
3.
\fBPRINTER\fR environment variable.
.RE
.RS +4
.TP
4.
\fB_default\fR destination in \fB$HOME/.printers\fR.
.RE
.RS +4
.TP
5.
\fB_default\fR destination in \fB/etc/printers.conf\fR.
.RE
.sp
.LP
The \fBlpr\fR, \fBlpq\fR, and \fBlprm\fR commands locate the default
destination in the following order:
.RS +4
.TP
1.
\fBlpr\fR command's \fB-P\fR \fIdestination\fR option.
.RE
.RS +4
.TP
2.
\fBPRINTER\fR environment variable.
.RE
.RS +4
.TP
3.
\fBLPDEST\fR environment variable.
.RE
.RS +4
.TP
4.
\fB_default\fR destination in \fB$HOME/.printers\fR.
.RE
.RS +4
.TP
5.
\fB_default\fR destination in \fB/etc/printers.conf\fR.
.RE
.SS "Locating the Interest List for lpget, lpstat, and cancel"
.sp
.LP
The \fBlpget\fR, \fBlpstat\fR, and \fBcancel\fR commands locate the interest
list in the following order:
.RS +4
.TP
1.
\fB_all\fR list in \fB$HOME/.printers\fR.
.RE
.RS +4
.TP
2.
\fB_all\fR list in \fB/etc/printers.conf\fR.
.RE
.SH EXAMPLES
.LP
\fBExample 1 \fRSetting the Interest List
.sp
.LP
The following entry sets the interest list to destinations \fBps\fR,
\fBsecure\fR, and \fBdog\fR at server \fBwest\fR and \fBfinance_ps\fR:

.sp
.in +2
.nf
\fB_all		ps,secure,west:dog,lpd://server/printers/queue\fR
.fi
.in -2
.sp

.LP
\fBExample 2 \fRSetting Aliases to a Printer
.sp
.LP
The following entry sets the aliases \fBps\fR, \fBlp\fR, and \fBlw\fR to
\fBsparc_printer\fR:

.sp
.in +2
.nf
\fBps|lp|lw	sparc_printer\fR
.fi
.in -2
.sp

.LP
\fBExample 3 \fRSetting an Alias as a Default Destination
.sp
.LP
The following entry sets the alias \fBpcl\fR to \fBhplj\fR and sets it as the
default destination:

.sp
.in +2
.nf
\fBpcl|_default	hplj\fR
.fi
.in -2
.sp

.LP
\fBExample 4 \fRSetting an Alias to a Server Destination
.sp
.LP
The following entry sets the alias \fBsecure\fR to destination \fBcatalpa\fR at
server \fBtabloid\fR:

.sp
.in +2
.nf
\fBsecure	tabloid:catalpa\fR
.fi
.in -2
.sp

.LP
\fBExample 5 \fRSetting an Alias to a Site Destination
.sp
.LP
The following entry sets the alias \fBinsecure\fR to destination \fBlegal_ps\fR
using IPP:

.sp
.in +2
.nf
\fBinsecure	ipp://server/printers/legal_ps\fR
.fi
.in -2
.sp

.SH FILES
.sp
.ne 2
.na
\fB\fB/etc/printers.conf\fR\fR
.ad
.RS 24n
System printer configuration database
.RE

.sp
.ne 2
.na
\fB\fB$HOME/.printers\fR\fR
.ad
.RS 24n
User-configurable printer database
.RE

.sp
.ne 2
.na
\fB\fBou=printers\fR\fR
.ad
.RS 24n
LDAP version of \fB/etc/printers.conf\fR
.RE

.sp
.ne 2
.na
\fB\fBprinters.conf.byname\fR\fR
.ad
.RS 24n
\fBNIS\fR version of \fB/etc/printers.conf\fR
.RE

.sp
.ne 2
.na
\fB\fBprinters.org_dir\fR\fR
.ad
.RS 24n
\fBNIS+\fR version of \fB/etc/printers.conf\fR
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Stable
.TE

.SH SEE ALSO
.sp
.LP
\fBcancel\fR(1), \fBlp\fR(1), \fBlpq\fR(1B), \fBlpr\fR(1B), \fBlprm\fR(1B),
\fBlpstat\fR(1), \fBlpadmin\fR(1M), \fBlpget\fR(1M), \fBnsswitch.conf\fR(4),
\fBprinters.conf\fR(4), \fBattributes\fR(5), \fBstandards\fR(5)
.sp
.LP
\fISystem Administration Guide: Basic Administration\fR
.SH NOTES
.sp
.LP
\fB$HOME/.printers\fR is referenced by the printing commands before further
name resolution is made in \fB/etc/printers.conf\fR or the name service. If the
alias references a destination defined in \fB/etc/printers.conf\fR, it is
possible that the destination is defined differently on different systems. This
could cause output to be sent to an unintended destination if the user is
logged in to a different system.