man/ipptool.man

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