man/ipptool.man

   1 .\"
   2 .\" "$Id$"
   3 .\"
   4 .\" ipptool man page for CUPS.
   5 .\"
   6 .\" Copyright 2010-2015 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" "26 August 2015" "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.
  80 Each named
  81 .I testfile
  82 defines one or more requests, including the expected response status, attributes, and values.
  83 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.
  84 The
  85 .I testfile
  86 format is described in
  87 .BR ipptoolfile (5).
  88 .SH OPTIONS
  89 The following options are recognized by
  90 .B ipptool:
  91 .TP 5
  92 .B \-\-help
  93 Shows program help.
  94 .TP 5
  95 .B \-\-stop-after-include-error
  96 Tells
  97 .B ipptool
  98 to stop if an error occurs in an included file. Normally
  99 .B ipptool
 100 will continue with subsequent tests after the INCLUDE directive.
 101 .TP 5
 102 .B \-\-version
 103 Shows the version of
 104 .B ipptool
 105 being used.
 106 .TP 5
 107 .B \-4
 108 Specifies that
 109 .B ipptool
 110 must connect to the printer or server using IPv4.
 111 .TP 5
 112 .B \-6
 113 Specifies that
 114 .B ipptool
 115 must connect to the printer or server using IPv6.
 116 .TP 5
 117 .B \-C
 118 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.
 119 The default is to use "Transfer\-Encoding: chunked" for requests with attached files and "Content\-Length:" for requests without attached files.
 120 .TP 5
 121 .B \-E
 122 Forces TLS encryption when connecting to the server using the HTTP "Upgrade" header.
 123 .TP 5
 124 .B \-I
 125 Specifies that
 126 .B ipptool
 127 will continue past errors.
 128 .TP 5
 129 .B \-L
 130 Specifies that requests should be sent using the HTTP/1.0 "Content\-Length:" header, which is required for conformance by all versions of IPP.
 131 The default is to use "Transfer\-Encoding: chunked" for requests with attached files and "Content\-Length:" for requests without attached files.
 132 .TP 5
 133 .BI \-P \ filename.plist
 134 Specifies that the test results should be written to the named XML (Apple plist) file in addition to the regular test report (\fB\-t\fR).
 135 This option is incompatible with the \fB\-i\fR (interval) and \fB\-n\fR (repeat\-count) options.
 136 .TP 5
 137 .B \-S
 138 Forces (dedicated) TLS encryption when connecting to the server.
 139 .TP 5
 140 .BI \-T \ seconds
 141 Specifies a timeout for IPP requests in seconds.
 142 .TP 5
 143 .BI \-V \ version
 144 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.
 145 .TP 5
 146 .B \-X
 147 Specifies that XML (Apple plist) output is desired instead of the plain text report.
 148 This option is incompatible with the \fB\-i\fR (interval) and \fB\-n\fR (repeat\-count) options.
 149 .TP 5
 150 .B \-c
 151 Specifies that CSV (comma\-separated values) output is desired instead of the plain text output.
 152 .TP 5
 153 .BI \-d \ name=value
 154 Defines the named variable.
 155 .TP 5
 156 .BI \-f \ filename
 157 Defines the default request filename for tests.
 158 .TP 5
 159 .BI \-i \ seconds
 160 Specifies that the (last)
 161 .I testfile
 162 should be repeated at the specified interval.
 163 This option is incompatible with the \fB\-X\fR (XML plist output) option.
 164 .TP 5
 165 .B \-l
 166 Specifies that plain text output is desired.
 167 .TP 5
 168 .BI \-n \ repeat\-count
 169 Specifies that the (last)
 170 .I testfile
 171 should be repeated the specified number of times.
 172 This option is incompatible with the \fI\-X\fR (XML plist output) option.
 173 .TP 5
 174 .B \-q
 175 Be quiet and produce no output.
 176 .TP 5
 177 .B \-t
 178 Specifies that CUPS test report output is desired instead of the plain text output.
 179 .TP 5
 180 .B \-v
 181 Specifies that all request and response attributes should be output in CUPS test mode (\fB\-t\fR).
 182 This is the default for XML output.
 183 .SH EXIT STATUS
 184 The
 185 .B ipptool
 186 program returns 0 if all tests were successful and 1 otherwise.
 187 .SH FILES
 188 The following standard files are available:
 189 .nf
 190 .I color.jpg
 191 .I create\-printer\-subscription.test
 192 .I document\-a4.pdf
 193 .I document\-a4.ps
 194 .I document\-letter.pdf
 195 .I document\-letter.ps
 196 .I get\-completed\-jobs.test
 197 .I get\-jobs.test
 198 .I get\-notifications.test
 199 .I get\-printer\-attributes.test
 200 .I get\-subscriptions.test
 201 .I gray.jpg
 202 .I ipp\-1.1.test
 203 .I ipp\-2.0.test
 204 .I ipp\-2.1.test
 205 .I ipp\-2.2.test
 206 .I ipp\-everywhere.test
 207 .I onepage\-a4.pdf
 208 .I onepage\-a4.ps
 209 .I onepage\-letter.pdf
 210 .I onepage\-letter.ps
 211 .I print\-job.test
 212 .I print\-job\-deflate.test
 213 .I print\-job\-gzip.test
 214 .I testfile.jpg
 215 .I testfile.pcl
 216 .I testfile.pdf
 217 .I testfile.ps
 218 .I testfile.txt
 219 .I validate\-job.test
 220 .fi
 221 .SH CONFORMING TO
 222 The
 223 .B ipptool
 224 program is unique to CUPS and conforms to the Internet Printing Protocol up to version 2.2.
 225 .SH EXAMPLES
 226 Get a list of completed jobs for "myprinter":
 227 .nf
 228
 229     ipptool ipp://localhost/printers/myprinter get\-completed\-jobs.test
 230 .fi
 231 .LP
 232 Send email notifications to "user@example.com" when "myprinter" changes:
 233 .nf
 234
 235     ipptool \-d recipient=mailto:user@example.com \\
 236         ipp://localhost/printers/myprinter create\-printer\-subscription.test
 237 .fi
 238 .SH SEE ALSO
 239 .BR ipptoolfile (5),
 240 CUPS Online Help (http://localhost:631/help),
 241 IANA IPP Registry (http://www.iana.org/assignments/ipp\-registrations),
 242 PWG Internet Printing Protocol Workgroup (http://www.pwg.org/ipp)
 243 RFC 2911 (http://tools.ietf.org/html/rfc2911),
 244 .SH COPYRIGHT
 245 Copyright \[co] 2007-2015 by Apple Inc.
 246 .\"
 247 .\" End of "$Id$".
 248 .\"