From bf1bc4c6d3387819bbb125ac8cd007bada572a62 Mon Sep 17 00:00:00 2001 From: msweet Date: Wed, 11 Jun 2014 19:03:59 +0000 Subject: More man page updates. git-svn-id: svn+ssh://src.apple.com/svn/cups/cups.org/trunk@11920 a1ca3aef-8c08-0410-bb20-df032aa958be --- man/cupsaddsmb.man.in | 189 +++++++++++++--------------------- man/cupsctl.man | 97 ++++++++++-------- man/cupsd-logs.man | 273 ++++++++++++++++++++++++++++++++++++++------------ man/cupsenable.man | 127 ++++++++++++----------- man/cupsfilter.man | 86 ++++++++++------ man/cupstestdsc.man | 59 +++++------ man/cupstestppd.man | 162 ++++++++++++++---------------- man/ippfind.man | 24 ++--- 8 files changed, 578 insertions(+), 439 deletions(-) (limited to 'man') diff --git a/man/cupsaddsmb.man.in b/man/cupsaddsmb.man.in index 74cb0adb0..89b93b8c0 100644 --- a/man/cupsaddsmb.man.in +++ b/man/cupsaddsmb.man.in @@ -1,81 +1,63 @@ .\" .\" "$Id$" .\" -.\" cupsaddsmb man page for CUPS. +.\" cupsaddsmb man page for CUPS. .\" -.\" Copyright 2007-2013 by Apple Inc. -.\" Copyright 1997-2006 by Easy Software Products. +.\" Copyright 2007-2014 by Apple Inc. +.\" Copyright 1997-2006 by Easy Software Products. .\" -.\" These coded instructions, statements, and computer programs are the -.\" property of Apple Inc. and are protected by Federal copyright -.\" law. Distribution and use rights are outlined in the file "LICENSE.txt" -.\" which should have been included with this file. If this file is -.\" file is missing or damaged, see the license at "http://www.cups.org/". +.\" These coded instructions, statements, and computer programs are the +.\" property of Apple Inc. and are protected by Federal copyright +.\" law. Distribution and use rights are outlined in the file "LICENSE.txt" +.\" which should have been included with this file. If this file is +.\" file is missing or damaged, see the license at "http://www.cups.org/". .\" -.TH cupsaddsmb 8 "CUPS" "8 July 2013" "Apple Inc." +.TH cupsaddsmb 8 "CUPS" "11 June 2014" "Apple Inc." .SH NAME cupsaddsmb \- export printers to samba for windows clients .SH SYNOPSIS .B cupsaddsmb -[ -H +[ +.B \-H .I samba-server -] [ -U +] [ +.B \-U .I samba-user[%samba-password] -] [ -h +] [ +.B \-h .I cups-server[:port] -] [ -v ] -a +] [ +.B \-v +] +.B \-a .br .B cupsaddsmb -[ -H +[ +.B \-H .I samba-server -] [ -U +] [ +.B \-U .I samba-user[%samba-password] -] [ -h +] [ +.B \-h .I cups-server[:port] -] [ -v ] printer [ ... printer ] - +] [ +.B \-v +] +.I printer +[ ... +.I printer +] .SH DESCRIPTION -\fIcupsaddsmb\fR exports printers to the SAMBA software (version -2.2.0 or higher) for use with Windows clients. Depending on the -SAMBA configuration, you may need to provide a password to -export the printers. This program requires the Windows printer -driver files described below. - -.SH OPTIONS -\fIcupsaddsmb\fR supports the following options: -.TP 5 --H samba-server -.br -Specifies the SAMBA server which defaults to the CUPS server. -.TP 5 --U samba-user[%samba-password] -.br -Specifies the SAMBA print admin username which defaults to your -current username. If the username contains a percent (%) -character, then the text following the percent is treated as the -SAMBA password to use. -.TP 5 --a -.br -Exports all known printers. Otherwise only the named printers are -exported. -.TP 5 --h cups-server[:port] -.br -Specifies a different CUPS server to use. -.TP 5 --v -.br -Specifies that verbose information should be shown. This is -useful for debugging SAMBA configuration problems. - -.SH SAMBA CONFIGURATION -\fIcupsaddsmb\fR uses the new RPC-based printing support in -SAMBA 2.2.x to provide printer drivers and PPD files to Windows -client machines. In order to use this functionality, you must -first configure the SAMBA \fIsmb.conf(5)\fR file to support -printing through CUPS and provide a printer driver download +The \fBcupsaddsmb\fR program exports printers to the SAMBA software (version 2.2.0 or higher) for use with Windows clients. +Depending on the SAMBA configuration, you may need to provide a password to export the printers. +This program requires the Windows printer driver files described below. +.SS SAMBA CONFIGURATION +\fBcupsaddsmb\fR uses the RPC-based printing support in SAMBA to provide printer drivers and PPD files to Windows client machines. +In order to use this functionality, you must first configure the SAMBA +.BR smb.conf (5) +file to support printing through CUPS and provide a printer driver download share, as follows: .nf @@ -100,77 +82,50 @@ share, as follows: guest ok = no read only = yes write list = root -.fi -.LP -This configuration assumes a FHS-compliant installation of -SAMBA; adjust the [printers] and [print$] share paths -accordingly on your system as needed. -.SH MICROSOFT POSTSCRIPT DRIVERS FOR WINDOWS -The base driver for Windows 2000 and higher is the Microsoft -PostScript driver, which is available on any system running -Windows 2000 or higher in the -%WINDIR%\\SYSTEM32\\SPOOL\\DRIVERS\\W32X86\\3 folder for 32-bit -drivers and -%WINDIR%\\SYSTEM32\\SPOOL\\DRIVERS\\X64\\3 folder for 64-bit -drivers. -.LP -However, currently only Windows 2000 and higher is supported by the Microsoft -driver, so you will also need to get the Adobe driver to support -Windows 95, 98, and Me clients. The Adobe and Microsoft drivers -for Windows 2000 are identical. +.fi +This configuration assumes a FHS-compliant installation of SAMBA; adjust the [printers] and [print$] share paths accordingly on your system as needed. +.SS MICROSOFT POSTSCRIPT DRIVERS FOR WINDOWS +The base driver for Windows 2000 and higher is the Microsoft PostScript driver, which is available on any system running Windows 2000 or higher in the %WINDIR%\\SYSTEM32\\SPOOL\\DRIVERS\\W32X86\\3 folder for 32-bit drivers and %WINDIR%\\SYSTEM32\\SPOOL\\DRIVERS\\X64\\3 folder for 64-bit drivers. .LP -Once you have extracted the driver files, copy the 32-bit drivers -to the \fI/usr/share/cups/drivers\fR directory and the 64-bit -drivers to the \fI/usr/share/cups/drivers/x64\fR directory exactly -as named below: +Copy the 32-bit drivers to the \fI/usr/share/cups/drivers\fR directory and the 64-bit drivers to the \fI/usr/share/cups/drivers/x64\fR directory exactly as named below: .nf - [Windows 2000 and higher] ps5ui.dll pscript.hlp pscript.ntf pscript5.dll -.fi -.LP -\fBNote:\fR Unlike Windows, case is significant - make sure that -you use the lowercase filenames shown above, otherwise -\fIcupsaddsmb\fR will fail to export the drivers. - -.SH ADOBE POSTSCRIPT DRIVERS FOR WINDOWS 95, 98, AND ME -\fIcupsaddsmb\fR can use the Adobe PostScript printer driver for -Windows 95, 98, and ME, which are available for download from the -Adobe web site (http://www.adobe.com). -.LP -The Adobe driver does not support the page-label, job-billing, or -job-hold-until options. -.LP -Once you have installed the driver on a Windows system, copy the -following files to the \fI/usr/share/cups/drivers\fR directory -exactly as named below: -.nf - [Windows 95, 98, and Me] - ADFONTS.MFM - ADOBEPS4.DRV - ADOBEPS4.HLP - ICONLIB.DLL - PSMON.DLL .fi -.LP -\fBNote:\fR Unlike Windows, case is significant - make sure that -you use the UPPERCASE filenames shown above, otherwise -\fIcupsaddsmb\fR will fail to export the drivers. - -.SH KNOWN ISSUES -Getting the full set of Windows driver files should be easier. - +\fBNote:\fR Unlike Windows, case is significant - make sure that you use the lowercase filenames shown above, otherwise \fBcupsaddsmb\fR will fail to export the drivers. +.SH OPTIONS +\fBcupsaddsmb\fR supports the following options: +.TP 5 +\fB\-H \fIsamba-server\fR +Specifies the SAMBA server which defaults to the CUPS server. +.TP 5 +\fB\-U \fIsamba-user\fR[\fB%\fIsamba-password\fR] +Specifies the SAMBA print admin username which defaults to your current username. +If the username contains a percent (%) character, then the text following the percent is treated as the SAMBA password to use. +.TP 5 +.B \-a +Exports all known printers. +Otherwise only the named printers are exported. +.TP 5 +\fB\-h \fIcups-server\fR[\fB:\fIport\fR] +Specifies a different CUPS server to use. +.TP 5 +.B \-v +Specifies that verbose information should be shown. +This is useful for debugging SAMBA configuration problems. .SH SEE ALSO -\fIsmbd(8)\fR, \fIsmb.conf(5)\fR, -http://localhost:631/help - +.BR rpcclient (1), +.BR smbclient (1), +.BR smbd (8), +.BR smb.conf (5), +CUPS Online Help (http://localhost:631/help) .SH COPYRIGHT -Copyright 2007-2013 by Apple Inc. +Copyright \[co] 2007-2014 by Apple Inc. .\" .\" End of "$Id$". .\" diff --git a/man/cupsctl.man b/man/cupsctl.man index 68953c064..b3703d237 100644 --- a/man/cupsctl.man +++ b/man/cupsctl.man @@ -1,97 +1,106 @@ .\" .\" "$Id$" .\" -.\" cupsctl man page for CUPS. +.\" cupsctl man page for CUPS. .\" -.\" Copyright 2007-2013 by Apple Inc. -.\" Copyright 2007 by Easy Software Products. +.\" Copyright 2007-2014 by Apple Inc. +.\" Copyright 2007 by Easy Software Products. .\" -.\" These coded instructions, statements, and computer programs are the -.\" property of Apple Inc. and are protected by Federal copyright -.\" law. Distribution and use rights are outlined in the file "LICENSE.txt" -.\" which should have been included with this file. If this file is -.\" file is missing or damaged, see the license at "http://www.cups.org/". +.\" These coded instructions, statements, and computer programs are the +.\" property of Apple Inc. and are protected by Federal copyright +.\" law. Distribution and use rights are outlined in the file "LICENSE.txt" +.\" which should have been included with this file. If this file is +.\" file is missing or damaged, see the license at "http://www.cups.org/". .\" -.TH cupsctl 8 "CUPS" "11 January 2013" "Apple Inc." +.TH cupsctl 8 "CUPS" "11 June 2014" "Apple Inc." .SH NAME cupsctl \- configure cupsd.conf options .SH SYNOPSIS .B cupsctl -[ -E ] [-U -.I username -] [ -h -.I server[:port] -] [ --[no-]debug-logging ] [ --[no-]remote-admin ] [ --[no-]remote-any ] -[ --[no-]share-printers ] [ --[no-]user-cancel-any ] [ +.B \-E +] [ +.B \-U +.I username +] [ +.B \-h +\fIserver\fR[\fB:\fIport\fR] +] [ +\fB\-\-\fR[\fBno\-\fR]\fBdebug\-logging\fR +] [ +\fB\-\-\fR[\fBno\-\fR]\fBremote\-admin\fR +] [ +\fB\-\-\fR[\fBno\-\fR]\fBremote\-any\fR +] [ +\fB\-\-\fR[\fBno\-\fR]\fBshare\-printers\fR +] [ +\fB\-\-\fR[\fBno\-\fR]\fBuser\-cancel\-any\fR +] [ .I name=value ] .SH DESCRIPTION -\fIcupsctl\fR updates or queries the \fBcupsd.conf\fR file for a server. When +\fBcupsctl\fR updates or queries the \fIcupsd.conf\fR file for a server. When no changes are requested, the current configuration values are written to the standard output in the format "name=value", one per line. .SH OPTIONS The following options are recognized: .TP 5 --E -.br +.B \-E Enables encryption on the connection to the scheduler. .TP 5 --U \fIusername\fR -.br +\fB\-U \fIusername\fR Specifies an alternate username to use when authenticating with the scheduler. .TP 5 --h \fIserver[:port]\fR -.br +\fB\-h \fIserver\fR[\fB:\fIport\fR] Specifies the server address. .TP 5 ---[no-]debug-logging -.br -Enables or disables debug logging in the \fBerror_log\fR file. +.B \-\-\fR[\fBno\-\fR]\fBdebug\-logging +Enables (disables) debug logging to the \fIerror_log\fR file. .TP 5 ---[no-]remote-admin -.br -Enables or disables remote administration. +.B \-\-\fR[\fBno\-\fR]\fBremote\-admin +Enables (disables) remote administration. .TP 5 ---[no-]remote-any -.br -Enables or disables printing from any address, e.g. the Internet. +.B \-\-\fR[\fBno\-\fR]\fBremote\-any +Enables (disables) printing from any address, e.g., the Internet. .TP 5 ---[no-]share-printers -.br -Enables or disables sharing of local printers with other computers. +.B \-\-\fR[\fBno\-\fR]\fBshare\-printers +Enables (disables) sharing of local printers with other computers. .TP 5 ---[no-]user-cancel-any -.br -Allows or prevents users from canceling jobs owned by others. +.B \-\-\fR[\fBno\-\fR]\fBuser\-cancel\-any +Allows (prevents) users to cancel jobs owned by others. .SH EXAMPLES Display the current settings: .nf + cupsctl + .fi -.LP Enable debug logging: .nf + cupsctl --debug-logging + .fi -.LP Get the current debug logging state: .nf + cupsctl | grep '^_debug_logging' | awk -F= '{print $2}' + .fi -.LP Disable printer sharing: .nf + cupsctl --no-share-printers .fi .SH KNOWN ISSUES -You cannot set the Listen or Port directives using \fIcupsctl\fR. +You cannot set the Listen or Port directives using \fBcupsctl\fR. .SH SEE ALSO -\fIcupsd.conf(5)\fR, \fIcupsd(8)\fR, +.BR cupsd.conf (5), +.BR cupsd (8), .br -http://localhost:631/help +CUPS Online Help (http://localhost:631/help) .SH COPYRIGHT -Copyright 2007-2013 by Apple Inc. +Copyright \[co] 2007-2014 by Apple Inc. .\" .\" End of "$Id$". .\" diff --git a/man/cupsd-logs.man b/man/cupsd-logs.man index 7d2cfefea..b28a3ab77 100644 --- a/man/cupsd-logs.man +++ b/man/cupsd-logs.man @@ -1,7 +1,7 @@ .\" .\" "$Id$" .\" -.\" cupsd-helper man page for CUPS. +.\" cupsd-logs man page for CUPS. .\" .\" Copyright 2007-2014 by Apple Inc. .\" Copyright 1997-2006 by Easy Software Products. @@ -12,80 +12,227 @@ .\" which should have been included with this file. If this file is .\" file is missing or damaged, see the license at "http://www.cups.org/". .\" -.TH cupsd-helper 8 "CUPS" "15 April 2014" "Apple Inc." +.TH cupsd-logs 5 "CUPS" "11 June 2014" "Apple Inc." .SH NAME -cupsd\-helper \- cupsd helper programs -.SH SYNOPSIS -.B cups\-deviced -.I request-id -.I limit -.I user-id -.I options -.br -.B cups\-driverd -.B cat -.I ppd-name -.br -.B cups\-driverd -.B list -.I request_id -.I limit -.I options -.br -.B cups\-exec -.I sandbox-profile -[ -.I \-g -.I group-id -] [ -.I \-n -.I nice-value -] [ -.I \-u -.I user-id -] -.I /path/to/program -.I argv0 -.I ... -.I argvN +cupsd\-logs \- cupsd log files (access_log, error_log, and page_log) .SH DESCRIPTION -The \fBcupsd\-helper\fR programs perform long-running operations on behalf of the scheduler, -.BR cupsd (8). -The \fBcups-deviced\fR helper program runs each CUPS -.BR backend (7) -with no arguments in order to discover the available printers. +.BR cupsd (8) +normally maintains three log files: \fIaccess_log\fR to track requests that are submitted to the scheduler, \fIerror_log\fR to track progress and errors, and \fIpage_log\fR to track pages that are printed. +Configuration directives in +.BR cupsd.conf (5) +and +.BR cups-files.conf (5) +control what information is logged and where it is stored. +.SS ACCESS LOG FILE FORMAT +The \fIaccess_log\fR file lists each HTTP resource that is accessed by a web browser or client. +Each line is in an extended version of the so-called "Common Log Format" used by many web servers and web reporting tools: +.nf + + \fIhost group user date-time \fR"\fImethod resource version\fR" \fIstatus bytes + ipp-operation ipp-status\fR + +.fi +For example: +.nf + + 10.0.1.2 - - [01/Dec/2005:21:50:28 +0000] "POST / HTTP/1.1" 200 317 + CUPS-Get-Printers successful-ok-ignored-or-substituted-attributes + localhost - - [01/Dec/2005:21:50:32 +0000] "GET /admin HTTP/1.1" + 200 0 - - + localhost - - [01/Dec/2005:21:50:32 +0000] "POST / HTTP/1.1" + 200 157 CUPS-Get-Printers + successful-ok-ignored-or-substituted-attributes + localhost - - [01/Dec/2005:21:50:32 +0000] "POST / HTTP/1.1" + 200 1411 CUPS-Get-Devices - + localhost - - [01/Dec/2005:21:50:32 +0000] "GET /admin HTTP/1.1" + 200 6667 - - + +.fi +The \fIhost\fR field will normally only be an IP address unless you have enabled the HostNameLookups directive in the \fIcupsd.conf\fR file or if the IP address corresponds to your local machine. +.LP +The \fIgroup\fR field always contains "-". +.LP +The \fIuser\fR field is the authenticated username of the requesting user. +If no username and password is supplied for the request then this field contains "-". +.LP +The \fIdate-time\fR field is the date and time of the request in local time and is in the format "[DD/MON/YYYY:HH:MM:SS +ZZZZ]". +.LP +The \fImethod\fR field is the HTTP method used: "GET", "HEAD", "OPTIONS", "POST", or "PUT". +"GET" requests are used to get files from the server, both for the web interface and to get configuration and log files. +"HEAD" requests are used to get information about a resource prior to a "GET". +"OPTIONS" requests are used to upgrade connections to TLS encryption. +"POST" requests are used for web interface forms and IPP requests. +"PUT" requests are used to upload configuration files. +.LP +The \fIresource\fR field is the filename of the requested resource. +.LP +The \fIversion\fR field is the HTTP specification version used by the client. +For CUPS clients this will always be "HTTP/1.1". +.LP +The \fIstatus\fR field contains the HTTP result status of the request, as follows: +.RS 5 +.TP 5 +200 +Successful operation. +.TP 5 +201 +File created/modified successfully. +.TP 5 +304 +The requested file has not changed. +.TP 5 +400 +Bad HTTP request; typically this means that you have a malicious program trying to access your server. +.TP 5 +401 +Unauthorized, authentication (username + password) is required. +.TP 5 +403 +Access is forbidden; typically this means that a client tried to access a file or resource they do not have permission to access. +.TP 5 +404 +The file or resource does not exist. +.TP 5 +405 +URL access method is not allowed; typically this means you have a web browser using your server as a proxy. +.TP 5 +413 +Request too large; typically this means that a client tried to print a file larger than the MaxRequestSize allows. +.TP 5 +426 +Upgrading to TLS-encrypted connection. +.TP 5 +500 +Server error; typically this happens when the server is unable to open/create a file - consult the error_log file for details. +.TP 5 +501 +The client requested encryption but encryption support is not enabled/compiled in. +.TP 5 +505 +HTTP version number not supported; typically this means that you have a malicious program trying to access your server. +.RE +.LP +The \fIbytes\fR field contains the number of bytes in the request. +For POST requests the bytes field contains the number of bytes of non-IPP data that is received from the client. +.LP +The \fIipp-operation\fR field contains either "-" for non-IPP requests or the IPP operation name for POST requests containing an IPP request. +.LP +The \fIipp-status\fR field contains either "-" for non-IPP requests or the IPP status code name for POST requests containing an IPP response. +.SS ERROR LOG FILE FORMAT +The \fIerror_log\fR file lists messages from the scheduler - errors, warnings, etc. The LogLevel directive in the +.BR cupsd.conf (5) +file controls which messages are logged: +.nf + + level date-time message + +.fi +For example: +.nf + + I [20/May/1999:19:18:28 +0000] [Job 1] Queued on 'DeskJet' by 'mike'. + D [20/May/1999:19:18:28 +0000] [Job 1] argv[0]="DeskJet" + D [20/May/1999:19:18:28 +0000] [Job 1] argv[1]="1" + D [20/May/1999:19:18:28 +0000] [Job 1] argv[2]="mike" + D [20/May/1999:19:18:28 +0000] [Job 1] argv[3]="myjob" + D [20/May/1999:19:18:28 +0000] [Job 1] argv[4]="1" + D [20/May/1999:19:18:28 +0000] [Job 1] argv[5]="media= + na_letter_8.5x11in sides=one-sided" + D [20/May/1999:19:18:28 +0000] [Job 1] argv[6]="/var/spool/cups/ + d000001-001" + I [20/May/1999:19:21:02 +0000] [Job 2] Queued on 'DeskJet' by 'mike'. + I [20/May/1999:19:22:24 +0000] [Job 2] Canceled by 'mike'. + +.fi +The \fIlevel\fR field contains the type of message: +.TP 5 +A +Alert message (LogLevel alert) +.TP 5 +C +Critical error message (LogLevel crit) +.TP 5 +D +Debugging message (LogLevel debug) +.TP 5 +d +Detailed debugging message (LogLevel debug2) +.TP 5 +E +Normal error message (LogLevel error) +.TP 5 +I +Informational message (LogLevel info) +.TP 5 +N +Notice message (LogLevel notice) +.TP 5 +W +Warning message (LogLevel warn) +.TP 5 +X +Emergency error message (LogLevel emerg) .LP -The \fBcups-driverd\fR helper program lists all available printer drivers, a subset of "matching" printer drivers, or a copy of a specific driver PPD file. +The \fIdate-time\fR field contains the date and time of when the page started printing. The format of this field is identical to the data-time field in the \fIaccess_log\fR file. .LP -The \fBcups-exec\fR helper program runs backends, filters, and other programs. On OS X these programs are run in a secure sandbox. -.SH FILES -The \fBcups-driverd\fR program looks for PPD and driver information files in the following directories: +The \fImessage\fR field contains a free-form textual message. +Messages from job filters are prefixed with "[Job NNN]" where "NNN" is the job ID. +.SS PAGE LOG FILE FORMAT +The \fIpage_log\fR file lists each page or group of pages that are sent to a printer. +By default, each line contains the following information: .nf - \fI/Library/Printers\fR - \fI/opt/share/ppd\fR - \fI/System/Library/Printers\fR - \fI/usr/local/share/ppd\fR - \fI/usr/share/cups/drv\fR - \fI/usr/share/cups/model\fR - \fI/usr/share/ppd\fR + \fIprinter user job-id date-time page-number num-copies job-billing + job-originating-host-name job-name media sides\fR + + \fIprinter user job-id date-time \fBtotal \fInum-impressions job-billing + job-originating-host-name job-name media sides\fR + .fi +For example the entries for a two page job called "myjob" might look like: +.nf + + DeskJet root 1 [20/May/1999:19:21:05 +0000] 1 1 acme-123 + localhost myjob na_letter_8.5x11in one-sided + DeskJet root 1 [20/May/1999:19:21:05 +0000] 2 1 acme-123 + localhost myjob na_letter_8.5x11in one-sided + + DeskJet root 1 [20/May/1999:19:21:06 +0000] total 2 acme-123 + localhost myjob na_letter_8.5x11in one-sided + +.fi +The PageLogFormat directive in the +.BR cupsd.conf (5) +file can be used to change this information. +.LP +The \fIprinter\fR field contains the name of the printer that printed the page. +If you send a job to a printer class, this field will contain the name of the printer that was assigned the job. +.LP +The \fIuser\fR field contains the name of the user (the IPP requesting-user-name attribute) that submitted this file for printing. +.LP +The \fIjob-id\fR field contains the job number of the page being printed. +.LP +The \fIdate-time\fR field contains the date and time of when the page started printing. +The format of this field is identical to the data-time field in the \fIaccess_log\fR file. +.LP +The \fIpage-number\fR and \fInum-copies\fR fields contain the page number and number of copies being printed of that page. +For printers that cannot produce copies on their own, the num-copies field will always be 1. +.LP +Lines containing the keyword "total" have a \fInum-impressions\fR field instead which provides the total number of impressions (sides) that have been printed on for the job. +.LP +The \fIjob-billing\fR field contains a copy of the job-billing or job-account-id attributes provided with the IPP Create-Job or Print-Job requests or "-" if neither was provided. +.LP +The \fIjob-originating-host-name\fR field contains the hostname or IP address of the client that printed the job. +.LP +The \fIjob-name\fR field contains a copy of the job-name attribute provided with the IPP Create-Job or Print-Job requests or "-" if none was provided. .LP -PPD files can be compressed using the -.BR gzip (1) -program or placed in compressed -.BR tar (1) -archives to further reduce their size. +The \fImedia\fR field contains a copy of the media or media-col/media-size attribute provided with the IPP Create-Job or Print-Job requests or "-" if none was provided. .LP -Driver information files must conform to the format defined in -.BR ppdcfile (5). +The \fIsides\fR field contains a copy of the sides attribute provided with the IPP Create-Job or Print-Job requests or "-" if none was provided. .SH SEE ALSO -.BR backend (7), -.BR cups (1), .BR cupsd (8), .BR cupsd.conf (5), -.BR filter (7), -.BR ppdcfile (5), +.BR cups-files.conf (5), CUPS Online Help (http://localhost:631/help) .SH COPYRIGHT Copyright \[co] 2007-2014 by Apple Inc. diff --git a/man/cupsenable.man b/man/cupsenable.man index e65a3b8ee..0972caa9f 100644 --- a/man/cupsenable.man +++ b/man/cupsenable.man @@ -1,92 +1,105 @@ .\" .\" "$Id$" .\" -.\" cupsenable/cupsdisable man page for CUPS. +.\" cupsenable/cupsdisable man page for CUPS. .\" -.\" Copyright 2007-2013 by Apple Inc. -.\" Copyright 1997-2006 by Easy Software Products. +.\" Copyright 2007-2014 by Apple Inc. +.\" Copyright 1997-2006 by Easy Software Products. .\" -.\" These coded instructions, statements, and computer programs are the -.\" property of Apple Inc. and are protected by Federal copyright -.\" law. Distribution and use rights are outlined in the file "LICENSE.txt" -.\" which should have been included with this file. If this file is -.\" file is missing or damaged, see the license at "http://www.cups.org/". +.\" These coded instructions, statements, and computer programs are the +.\" property of Apple Inc. and are protected by Federal copyright +.\" law. Distribution and use rights are outlined in the file "LICENSE.txt" +.\" which should have been included with this file. If this file is +.\" file is missing or damaged, see the license at "http://www.cups.org/". .\" -.TH cupsenable 8 "CUPS" "9 October 2008" "Apple Inc." +.TH cupsenable 8 "CUPS" "11 June 2014" "Apple Inc." .SH NAME cupsdisable, cupsenable \- stop/start printers and classes .SH SYNOPSIS .B cupsdisable -[ -E ] [-U +[ +.B \-E +] [ +.B \-U .I username -] [ -c ] [ -h -.I server[:port] -] [ -r +] [ +.B \-c +] [ +\fB\-h \fIserver\fR[\fB:\fIport\fR] +] [ +.B \-r .I reason -] [ --hold ] destination(s) +] [ +.B \-\-hold +] +.I destination(s) .br .B cupsenable -[ -E ] [-U +[ +.B \-E +] [ +.B \-U .I username -] [ -c ] [ -h -.I server[:port] -] [ --release ] destination(s) +] [ +.B \-c +] [ +\fB\-h \fIserver\fR[\fB:\fIport\fR] +] [ +.B \-\-release +] +.I destination(s) .SH DESCRIPTION -\fIcupsenable\fR starts the named printers or classes. -.LP -\fIcupsdisable\fR stops the named printers or classes. The -following options may be used: +.B cupsenable +starts the named printers or classes while +.B cupsdisable +stops the named printers or classes. +.SH OPTIONS +The following options may be used: .TP 5 --E -.br +.B \-E Forces encryption of the connection to the server. .TP 5 --U username -.br +\fB\-U \fIusername\fR Uses the specified username when connecting to the server. .TP 5 --c -.br +.B \-c Cancels all jobs on the named destination. .TP 5 --h server[:port] -.br +\fB\-h \fIserver\fR[\fB:\fIport\fR] Uses the specified server and port. .TP 5 ---hold -.br -Holds remaining jobs on the named printer. Useful for allowing the current -job to complete before performing maintenance. +.B \-\-hold +Holds remaining jobs on the named printer. +Useful for allowing the current job to complete before performing maintenance. .TP 5 --r "reason" -.br -Sets the message associated with the stopped state. If no reason is specified -then the message is set to "Reason Unknown". +\fB\-r "\fIreason\fB"\fR +Sets the message associated with the stopped state. +If no reason is specified then the message is set to "Reason Unknown". .TP 5 ---release -.br -Releases pending jobs for printing. Use after running \fIcupsdisable\fR with -the \fI--hold\fR option to resume printing. -.SH COMPATIBILITY -Unlike the System V printing system, CUPS allows printer names to -contain any printable character except SPACE, TAB, "/", or "#". +.B \-\-release +Releases pending jobs for printing. +Use after running \fBcupsdisable\fR with the \fI\-\-hold\fR option to resume printing. +.SH CONFORMING TO +Unlike the System V printing system, CUPS allows printer names to contain any printable character except SPACE, TAB, "/", or "#". Also, printer and class names are \fInot\fR case-sensitive. .LP -The System V versions of these commands are \fIdisable\fR and -\fIenable\fR. They have been renamed to avoid conflicts with the -\fIbash(1)\fR build-in commands of the same name. +The System V versions of these commands are \fBdisable\fR and \fBenable\fR, respectively. +They have been renamed to avoid conflicts with the +.BR bash (1) +build-in commands of the same names. .LP -The CUPS versions of \fIdisable\fR and \fIenable\fR may ask the -user for an access password depending on the printing system -configuration. This differs from the System V versions which -require the root user to execute these commands. +The CUPS versions of \fBdisable\fR and \fBenable\fR may ask the user for an access password depending on the printing system configuration. +This differs from the System V versions which require the root user to execute these commands. .SH SEE ALSO -\fIcupsaccept(8)\fR, \fIcupsreject(8)\fR, \fIcancel(1)\fR, \fIlp(1)\fR, -\fIlpadmin(8)\fR, \fIlpstat(1)\fR, -.br -http://localhost:631/help +.BR cupsaccept (8), +.BR cupsreject (8), +.BR cancel (1), +.BR lp (1), +.BR lpadmin (8), +.BR lpstat (1), +CUPS Online Help (http://localhost:631/help) .SH COPYRIGHT -Copyright 2007-2013 by Apple Inc. +Copyright \[co] 2007-2014 by Apple Inc. .\" .\" End of "$Id$". diff --git a/man/cupsfilter.man b/man/cupsfilter.man index 03bc4a67b..2d6f785e1 100644 --- a/man/cupsfilter.man +++ b/man/cupsfilter.man @@ -11,32 +11,50 @@ .\" which should have been included with this file. If this file is .\" file is missing or damaged, see the license at "http://www.cups.org/". .\" -.TH cupsfilter 8 "CUPS" "28 March 2014" "Apple Inc." +.TH cupsfilter 8 "CUPS" "11 June 2014" "Apple Inc." .SH NAME cupsfilter \- convert a file to another format using cups filters .SH SYNOPSIS .B cupsfilter -[ --list-filters] [ -D ] [ -U +[ +.B \-\-list\-filters +] [ +.B \-D +] [ +.B \-U .I user -] [ -c +] [ +.B \-c .I config-file -] [ -d +] [ +.B \-d .I printer -] [ -e ] [ -i +] [ +.B \-e +] [ +.B \-i .I mime/type -] [ -j +] [ +.B \-j .I job-id[,N] -] [ -m +] [ +.B \-m .I mime/type -] [ -n +] [ +.B \-n .I copies -] [ -o +] [ +.B \-o .I name=value -] [ -p +] [ +.B \-p .I filename.ppd -] [ -t +] [ +.B \-t .I title -] [ -u ] +] [ +.B \-u +] .I filename .SH DESCRIPTION .B cupsfilter @@ -45,46 +63,46 @@ is a front-end to the CUPS filter subsystem which allows you to convert a file t generates a PDF file. The converted file is sent to the standard output. .SH OPTIONS .TP 5 ---list-filters +.B \-\-list\-filters Do not actually run the filters, just print the filters used to stdout. .TP 5 --D +.B \-D Delete the input file after conversion. .TP 5 --U user +\fB\-U \fIuser\fR Specifies the username passed to the filters. The default is the name of the current user. .TP 5 --c config-file +\fB\-c \fIconfig-file\fR Uses the named cups-files.conf configuration file. .TP 5 --d printer +\fB\-d \fIprinter\fR Uses information from the named printer. .TP 5 --e +.B \-e Use every filter from the PPD file. .TP 5 --i mime/type +\fB\-i \fImime/type\fR Specifies the source file type. The default file type is guessed using the filename and contents of the file. .TP 5 --j job-id[,N] +\fB\-j \fIjob-id[,N]\fR Converts document N from the specified job. If N is omitted, document 1 is converted. .TP 5 --m mime/type +\fB\-m \fImime/type\fR Specifies the destination file type. The default file type is application/pdf. Use printer/foo to convert to the printer format defined by the filters in the PPD file. .TP 5 --n copies +\fB\-n \fIcopies\fR Specifies the number of copies to generate. .TP 5 --o name=value +\fB\-o \fIname=value\fR Specifies options to pass to the CUPS filters. .TP 5 --p filename.ppd +\fB\-p \fIfilename.ppd\fR Specifies the PPD file to use. .TP 5 --t title +\fB\-t \fItitle\fR Specifies the document title. .TP 5 --u +.B \-u Delete the PPD file after conversion. .SH EXIT STATUS .B cupsfilter @@ -95,7 +113,12 @@ All of the standard environment variables affect the operation of .BR cupsfilter . .SH FILES -/etc/cups/cups-files.conf, /etc/cups/*.convs, /etc/cups/*.types, /usr/share/cups/mime/*.convs, /usr/share/cups/mime/*.types +.nf +/etc/cups/cups-files.conf +/etc/cups/*.convs +/etc/cups/*.types +/usr/share/cups/mime/*.convs +/usr/share/cups/mime/*.types .SH NOTES Unlike when printing, filters run using the .B cupsfilter @@ -103,11 +126,16 @@ command use the current user and security session. This may result in different .SH EXAMPLE The following command will generate a PDF preview of job 42 for a printer named "myprinter" and save it to a file named "preview.pdf": .nf + cupsfilter -m application/pdf -d myprinter -j 42 >preview.pdf .fi .SH SEE ALSO -.BR cups (1), cupsd.conf (5), filter(7), mime.convs (7), mime.types (7), -http://localhost:631/help +.BR cups (1), +.BR cupsd.conf (5), +.BR filter(7), +.BR mime.convs (7), +.BR mime.types (7), +CUPS Online Help (http://localhost:631/help) .SH COPYRIGHT Copyright \[co] 2007-2014 by Apple Inc. .\" diff --git a/man/cupstestdsc.man b/man/cupstestdsc.man index aea170bd1..313bd8994 100644 --- a/man/cupstestdsc.man +++ b/man/cupstestdsc.man @@ -1,50 +1,51 @@ .\" .\" "$Id$" .\" -.\" cupstestdsc man page for CUPS. +.\" cupstestdsc man page for CUPS. .\" -.\" Copyright 2007-2013 by Apple Inc. -.\" Copyright 2006 by Easy Software Products. +.\" Copyright 2007-2014 by Apple Inc. +.\" Copyright 2006 by Easy Software Products. .\" -.\" These coded instructions, statements, and computer programs are the -.\" property of Apple Inc. and are protected by Federal copyright -.\" law. Distribution and use rights are outlined in the file "LICENSE.txt" -.\" which should have been included with this file. If this file is -.\" file is missing or damaged, see the license at "http://www.cups.org/". +.\" These coded instructions, statements, and computer programs are the +.\" property of Apple Inc. and are protected by Federal copyright +.\" law. Distribution and use rights are outlined in the file "LICENSE.txt" +.\" which should have been included with this file. If this file is +.\" file is missing or damaged, see the license at "http://www.cups.org/". .\" -.TH cupstestdsc 1 "CUPS" "20 March 2006" "Apple Inc." +.TH cupstestdsc 1 "CUPS" "11 June 2014" "Apple Inc." .SH NAME -cupstestdsc \- test conformance of postscript files +cupstestdsc \- test conformance of postscript files (deprecated) .SH SYNOPSIS .B cupstestdsc -[ -h ] filename.ps [ ... +[ +.B \-h +] +.I filename.ps +[ ... .I filenameN.ps ] .br .B cupstestdsc -[ -h ] - +[ +.B \-h +] +.B \- .SH DESCRIPTION -\fIcupstestdsc\fR tests the conformance of PostScript files to -the Adobe PostScript Language Document Structuring Conventions -Specification version 3.0. The results of testing and any other -output are sent to the standard output. The second form of the -command reads PostScript from the standard input. -.SH LIMITATIONS -\fIcupstestdsc\fR only validates the DSC comments in a PostScript -file and does not attempt to validate the PostScript code itself. -Developers must ensure that the PostScript they generate follows -the rules defined by Adobe. Specifically, all pages must be -independent of each other, code outside page descriptions may not -affect the graphics state (current font, color, transform matrix, -etc.), and device-specific commands such as setpagedevice should -not be used. +\fBcupstestdsc\fR tests the conformance of PostScript files to the Adobe PostScript Language Document Structuring Conventions Specification version 3.0. +The results of testing and any other output are sent to the standard output. +The second form of the command reads PostScript from the standard input. +.SH NOTES +\fIThis program is deprecated and will be removed in a future release of CUPS.\fR +.LP +\fBcupstestdsc\fR only validates the DSC comments in a PostScript file and does not attempt to validate the PostScript code itself. +Developers must ensure that the PostScript they generate follows the rules defined by Adobe. +Specifically, all pages must be independent of each other, code outside page descriptions may not affect the graphics state (current font, color, transform matrix, etc.), and device-specific commands such as setpagedevice should not be used. .SH SEE ALSO -http://localhost:631/help -.br +CUPS Online Help (http://localhost:631/help), Adobe PostScript Language Document Structuring Conventions Specification, Version 3.0. .SH COPYRIGHT -Copyright 2007-2013 by Apple Inc. +Copyright \[co] 2007-2014 by Apple Inc. .\" .\" End of "$Id$". .\" diff --git a/man/cupstestppd.man b/man/cupstestppd.man index 56ac582b9..550e21fa5 100644 --- a/man/cupstestppd.man +++ b/man/cupstestppd.man @@ -1,165 +1,151 @@ .\" .\" "$Id$" .\" -.\" cupstestppd man page for CUPS. +.\" cupstestppd man page for CUPS. .\" -.\" Copyright 2007-2013 by Apple Inc. -.\" Copyright 1997-2006 by Easy Software Products. +.\" Copyright 2007-2014 by Apple Inc. +.\" Copyright 1997-2006 by Easy Software Products. .\" -.\" These coded instructions, statements, and computer programs are the -.\" property of Apple Inc. and are protected by Federal copyright -.\" law. Distribution and use rights are outlined in the file "LICENSE.txt" -.\" which should have been included with this file. If this file is -.\" file is missing or damaged, see the license at "http://www.cups.org/". +.\" These coded instructions, statements, and computer programs are the +.\" property of Apple Inc. and are protected by Federal copyright +.\" law. Distribution and use rights are outlined in the file "LICENSE.txt" +.\" which should have been included with this file. If this file is +.\" file is missing or damaged, see the license at "http://www.cups.org/". .\" -.TH cupstestppd 1 "CUPS" "19 November 2009" "Apple Inc." +.TH cupstestppd 1 "CUPS" "11 June 2014" "Apple Inc." .SH NAME cupstestppd \- test conformance of ppd files .SH SYNOPSIS .B cupstestppd -[ -I +[ +.B \-I .I category -] [ -R +] [ +.B \-R .I rootdir -] [ -W +] [ +.B \-W .I category -] [ -q ] [-r] [ -v[v] ] filename.ppd[.gz] [ ... filenameN.ppd[.gz] ] +] [ +.B \-q +] [ +.B \-r +] [ +\fB\-v\fR[\fBv\fR] +] +.I filename.ppd[.gz] +[ ... +.I filename.ppd[.gz] +] .br .B cupstestppd -[ -R +[ +.B \-R .I rootdir -] [ -W +] [ +.B \-W .I category -] [ -q ] [-r] [ -v[v] ] - +] [ +.B \-q +] [ +.B \-r +] [ +\fB\-v\fR[\fBv\fR] +] +.B \- .SH DESCRIPTION -\fIcupstestppd\fR tests the conformance of PPD files to the -Adobe PostScript Printer Description file format specification -version 4.3. It can also be used to list the supported options -and available fonts in a PPD file. The results of testing and -any other output are sent to the standard output. +\fBcupstestppd\fR tests the conformance of PPD files to the Adobe PostScript Printer Description file format specification version 4.3. +It can also be used to list the supported options and available fonts in a PPD file. +The results of testing and any other output are sent to the standard output. .LP -The first form of \fIcupstestppd\fR tests one or more PPD files -on the command-line. The second form tests the PPD file provided -on the standard input. +The first form of \fBcupstestppd\fR tests one or more PPD files on the command-line. +The second form tests the PPD file provided on the standard input. .SH OPTIONS -\fIcupstestppd\fR supports the following options: +\fBcupstestppd\fR supports the following options: .TP 5 --I filename -.br +\fB\-I filename\fR Ignores all PCFileName warnings. .TP 5 --I filters -.br +\fB\-I filters\fR Ignores all filter errors. .TP 5 --I profiles -.br +\fB\-I profiles\fR Ignores all profile errors. .TP 5 --R rootdir -.br -Specifies an alternate root directory for the filter, pre-filter, -and other support file checks. +\fB\-R \fIrootdir\fR +Specifies an alternate root directory for the filter, pre-filter, and other support file checks. .TP 5 --W constraints -.br +\fB\-W constraints\fR Report all UIConstraint errors as warnings. .TP 5 --W defaults -.br +\fB\-W defaults\fR Except for size-related options, report all default option errors as warnings. .TP 5 --W filters -.br +\fB\-W filters\fR Report all filter errors as warnings. .TP 5 --W profiles -.br +\fB\-W profiles\fR Report all profile errors as warnings. .TP 5 --W sizes -.br +\fB\-W sizes\fR Report all media size errors as warnings. .TP 5 --W translations -.br +\fB\-W translations\fR Report all translation errors as warnings. .TP 5 --W all -.br +\fB\-W all\fR Report all of the previous errors as warnings. .TP 5 --W none -.br +\fB\-W none\fR Report all of the previous errors as errors. .TP 5 --q -.br +.B \-q Specifies that no information should be displayed. .TP 5 --r -.br -Relaxes the PPD conformance requirements so that common -whitespace, control character, and formatting problems are not -treated as hard errors. +.B \-r +Relaxes the PPD conformance requirements so that common whitespace, control character, and formatting problems are not treated as hard errors. .TP 5 --v -.br -Specifies that detailed conformance testing results should be -displayed rather than the concise PASS/FAIL/ERROR status. +.B \-v +Specifies that detailed conformance testing results should be displayed rather than the concise PASS/FAIL/ERROR status. .TP 5 --vv -.br -Specifies that all information in the PPD file should be -displayed in addition to the detailed conformance testing -results. +.B \-vv +Specifies that all information in the PPD file should be displayed in addition to the detailed conformance testing results. .LP The \fI-q\fR, \fI-v\fR, and \fI-vv\fR options are mutually exclusive. .SH EXIT STATUS -\fIcupstestppd\fR returns zero on success and non-zero on error. The -error codes are as follows: +\fBcupstestppd\fR returns zero on success and non-zero on error. +The error codes are as follows: .TP 5 1 -.br Bad command-line arguments or missing PPD filename. .TP 5 2 -.br Unable to open or read PPD file. .TP 5 3 -.br The PPD file contains format errors that cannot be skipped. .TP 5 4 -.br The PPD file does not conform to the Adobe PPD specification. .SH EXAMPLES -The following command will test all PPD files under the current -directory and print the names of each file that does not -conform: +The following command will test all PPD files under the current directory and print the names of each file that does not conform: .nf - find . -name \\*.ppd \\! -exec cupstestppd -q '{}' \\; -print + find . \-name \\*.ppd \\! \-exec cupstestppd \-q '{}' \\; \-print .fi -The next command tests all PPD files under the current directory -and print detailed conformance testing results for the files -that do not conform: +The next command tests all PPD files under the current directory and print detailed conformance testing results for the files that do not conform: .nf - find . -name \\*.ppd \\! -exec cupstestppd -q '{}' \\; \\ - -exec cupstestppd -v '{}' \\; - + find . \-name \\*.ppd \\! \-exec cupstestppd \-q '{}' \\; \\ + \-exec cupstestppd \-v '{}' \\; .fi .SH SEE ALSO -\fIlpadmin(8)\fR, -.br -http://localhost:631/help -.br +.BR lpadmin (8), +CUPS Online Help (http://localhost:631/help), Adobe PostScript Printer Description File Format Specification, Version 4.3. .SH COPYRIGHT -Copyright 2007-2013 by Apple Inc. +Copyright \[co] 2007-2014 by Apple Inc. .\" .\" End of "$Id$". .\" diff --git a/man/ippfind.man b/man/ippfind.man index 24c5a2660..3b0b013ef 100644 --- a/man/ippfind.man +++ b/man/ippfind.man @@ -1,26 +1,26 @@ .\" .\" "$Id$" .\" -.\" ippfind man page for CUPS. +.\" ippfind man page for CUPS. .\" -.\" Copyright 2013 by Apple Inc. +.\" Copyright 2013-2014 by Apple Inc. .\" -.\" These coded instructions, statements, and computer programs are the -.\" property of Apple Inc. and are protected by Federal copyright -.\" law. Distribution and use rights are outlined in the file "LICENSE.txt" -.\" which should have been included with this file. If this file is -.\" file is missing or damaged, see the license at "http://www.cups.org/". +.\" These coded instructions, statements, and computer programs are the +.\" property of Apple Inc. and are protected by Federal copyright +.\" law. Distribution and use rights are outlined in the file "LICENSE.txt" +.\" which should have been included with this file. If this file is +.\" file is missing or damaged, see the license at "http://www.cups.org/". .\" -.TH ippfind 1 "CUPS" "6 June 2013" "Apple Inc." +.TH ippfind 1 "CUPS" "11 June 2014" "Apple Inc." .SH NAME -ippfind - find internet printing protocol printers +ippfind \- find internet printing protocol printers .SH SYNOPSIS .B ippfind [ .I options -] regtype[,subtype][.domain.] ... [ -.I expression ... -] +] \fIregtype\fR[\fB,\fIsubtype\fR][\fB.\fIdomain\fB.\fR] ... [ +.I expression +... ] .B ippfind [ .I options -- cgit v1.2.1