man/ipptool.man

   1 .\"
   2 .\" "$Id: ipptool.man 11880 2014-05-16 06:14:11Z msweet $"
   3 .\"
   4 .\" ipptool man page for CUPS.
   5 .\"
   6 .\" Copyright 2010-2014 by Apple Inc.
   7 .\"
   8 .\" These coded instructions, statements, and computer programs are the
   9 .\" property of Apple Inc. and are protected by Federal copyright
  10 .\" law.  Distribution and use rights are outlined in the file "LICENSE.txt"
  11 .\" which should have been included with this file.  If this file is
  12 .\" file is missing or damaged, see the license at "http://www.cups.org/".
  13 .\"
  14 .TH ipptool 1 "CUPS" "15 May 2014" "Apple Inc."
  15 .SH NAME
  16 ipptool \- perform internet printing protocol requests
  17 .SH SYNOPSIS
  18 .B ipptool
  19 [
  20 .B \-\-help
  21 ] [
  22 .B \-\-stop\-after\-include\-error
  23 ] [
  24 .B \-\-version
  25 ] [
  26 .B \-4
  27 ] [
  28 .B \-6
  29 ] [
  30 .B \-C
  31 ] [
  32 .B \-E
  33 ] [
  34 .B \-I
  35 ] [
  36 .B \-L
  37 ] [
  38 .B \-P
  39 .I filename.plist
  40 ] [
  41 .B \-S
  42 ] [
  43 .B \-T
  44 .I seconds
  45 ] [
  46 .B \-V
  47 .I version
  48 ] [
  49 .B \-X
  50 ] [
  51 .B \-c
  52 ] [
  53 .B \-d
  54 .I name=value
  55 ] [
  56 .B \-f
  57 .I filename
  58 ] [
  59 .B \-i
  60 .I seconds
  61 ] [
  62 .B \-n
  63 .I repeat-count
  64 ] [
  65 .B \-q
  66 ] [
  67 .B \-t
  68 ] [
  69 .B \-v ]
  70 .I printer-uri
  71 .I testfile
  72 [ ...
  73 .I testfile
  74 ]
  75 .SH DESCRIPTION
  76 .B ipptool
  77 sends IPP requests to the specified
  78 .I printer-uri
  79 and tests and/or displays the results. Each named
  80 .I testfile
  81 defines one or more requests, including the expected response status, attributes, and values. Output is either a plain text, formatted text, CSV, or XML report on the standard output, with a non-zero exit status indicating that one or more tests have failed. The
  82 .I testfile
  83 format is described in
  84 .BR ipptoolfile (5).
  85 .SH OPTIONS
  86 The following options are recognized by
  87 .B ipptool:
  88 .TP 5
  89 .B \-\-help
  90 Shows program help.
  91 .TP 5
  92 .B \-\-stop-after-include-error
  93 Tells
  94 .B ipptool
  95 to stop if an error occurs in an included file. Normally
  96 .B ipptool
  97 will continue with subsequent tests after the INCLUDE directive.
  98 .TP 5
  99 .B \-\-version
 100 Shows the version of
 101 .B ipptool
 102 being used.
 103 .TP 5
 104 .B \-4
 105 Specifies that
 106 .B ipptool
 107 must connect to the printer or server using IPv4.
 108 .TP 5
 109 .B \-6
 110 Specifies that
 111 .B ipptool
 112 must connect to the printer or server using IPv6.
 113 .TP 5
 114 .B \-C
 115 Specifies that requests should be sent using the HTTP/1.1 "Transfer\-Encoding: chunked" header, which is required for conformance by all versions of IPP. The default is to use "Transfer\-Encoding: chunked" for requests with attached files and "Content\-Length:" for requests without attached files.
 116 .TP 5
 117 .B \-E
 118 Forces TLS encryption when connecting to the server using the HTTP "Upgrade" header.
 119 .TP 5
 120 .B \-I
 121 Specifies that
 122 .B ipptool
 123 will continue past errors.
 124 .TP 5
 125 .B \-L
 126 Specifies that requests should be sent using the HTTP/1.0 "Content\-Length:" header, which is required for conformance by all versions of IPP. The default is to use "Transfer\-Encoding: chunked" for requests with attached files and "Content\-Length:" for requests without attached files.
 127 .TP 5
 128 .BI \-P \ filename.plist
 129 Specifies that the test results should be written to the named XML (Apple plist) file in addition to the plain text report. This option is incompatible with the \fB\-i\fR (interval) and \fB\-n\fR (repeat\-count) options.
 130 .TP 5
 131 .B \-S
 132 Forces (dedicated) TLS encryption when connecting to the server.
 133 .TP 5
 134 .BI \-T \ seconds
 135 Specifies a timeout for IPP requests in seconds.
 136 .TP 5
 137 .BI \-V \ version
 138 Specifies the default IPP version to use: 1.0, 1.1, 2.0, 2.1, or 2.2. If not specified, version 1.1 is used.
 139 .TP 5
 140 .B \-X
 141 Specifies that XML (Apple plist) output is desired instead of the plain text report. This option is incompatible with the \fB\-i\fR (interval) and \fB\-n\fR (repeat\-count) options.
 142 .TP 5
 143 .B \-c
 144 Specifies that CSV (comma\-separated values) output is desired instead of the plain text output.
 145 .TP 5
 146 .BI \-d \ name=value
 147 Defines the named variable.
 148 .TP 5
 149 .BI \-f \ filename
 150 Defines the default request filename for tests.
 151 .TP 5
 152 .BI \-i \ seconds
 153 Specifies that the (last)
 154 .I testfile
 155 should be repeated at the specified interval. This option is incompatible with the \fB\-X\fR (XML plist output) option.
 156 .TP 5
 157 .B \-l
 158 Specifies that plain text output is desired.
 159 .TP 5
 160 .BI \-n \ repeat\-count
 161 Specifies that the (last)
 162 .I testfile
 163 should be repeated the specified number of times. This option is incompatible with the \fI\-X\fR (XML plist output) option.
 164 .TP 5
 165 .B \-t
 166 Specifies that CUPS test report output is desired instead of the plain text output.
 167 .TP 5
 168 .B \-v
 169 Specifies that all request and response attributes should be output in CUPS test mode (\fB\-t\fR). This is the default for XML output.
 170 .SH EXIT STATUS
 171 The
 172 .B ipptool
 173 program returns 0 if all tests were sucessful and 1 otherwise.
 174 .SH FILES
 175 The following standard files are available:
 176 .nf
 177 .I color.jpg
 178 .I create\-printer\-subscription.test
 179 .I document\-a4.pdf
 180 .I document\-a4.ps
 181 .I document\-letter.pdf
 182 .I document\-letter.ps
 183 .I get\-completed\-jobs.test
 184 .I get\-jobs.test
 185 .I get\-notifications.test
 186 .I get\-printer\-attributes.test
 187 .I get\-subscriptions.test
 188 .I gray.jpg
 189 .I ipp\-1.1.test
 190 .I ipp\-2.0.test
 191 .I ipp\-2.1.test
 192 .I ipp\-2.2.test
 193 .I ipp\-everywhere.test
 194 .I onepage\-a4.pdf
 195 .I onepage\-a4.ps
 196 .I onepage\-letter.pdf
 197 .I onepage\-letter.ps
 198 .I print\-job.test
 199 .I print\-job\-deflate.test
 200 .I print\-job\-gzip.test
 201 .I testfile.jpg
 202 .I testfile.pcl
 203 .I testfile.pdf
 204 .I testfile.ps
 205 .I testfile.txt
 206 .I validate\-job.test
 207 .fi
 208 .SH CONFORMING TO
 209 The
 210 .B ipptool
 211 program is unique to CUPS and conforms to the Internet Printing Protocol up to version 2.2.
 212 .SH EXAMPLES
 213 Get a list of completed jobs for "myprinter":
 214 .nf
 215
 216     ipptool ipp://localhost/printers/myprinter get\-completed\-jobs.test
 217 .fi
 218 .LP
 219 Send email notifications to "user@example.com" when "myprinter" changes:
 220 .nf
 221
 222     ipptool \-d recipient=mailto:user@example.com \\
 223         ipp://localhost/printers/myprinter create\-printer\-subscription.test
 224 .fi
 225 .SH SEE ALSO
 226 .BR ipptoolfile (5),
 227 CUPS Online Help (http://localhost:631/help),
 228 IANA IPP Registry (http://www.iana.org/assignments/ipp\-registrations),
 229 PWG Internet Printing Protocol Workgroup (http://www.pwg.org/ipp)
 230 RFC 2911 (http://tools.ietf.org/html/rfc2911),
 231 .SH COPYRIGHT
 232 Copyright \[co] 2007-2014 by Apple Inc.
 233 .\"
 234 .\" End of "$Id: ipptool.man 11880 2014-05-16 06:14:11Z msweet $".
 235 .\"