Greatly simplify the man page handling.
[thirdparty/cups.git] / doc / help / man-ipptool.html
1 <!DOCTYPE HTML>
2 <html>
3 <!-- SECTION: Man Pages -->
4 <head>
5         <link rel="stylesheet" type="text/css" href="../cups-printable.css">
6         <title>ipptool(1)</title>
7 </head>
8 <body>
9 <h1 class="title">ipptool(1)</h1>
10 <h2 class="title"><a name="NAME">Name</a></h2>
11 ipptool - perform internet printing protocol requests
12 <h2 class="title"><a name="SYNOPSIS">Synopsis</a></h2>
13 <b>ipptool</b>
14 [
15 <b>--help</b>
16 ] [
17 <b>--ippserver</b>
18 <i>filename</i>
19 ] [
20 <b>--stop-after-include-error</b>
21 ] [
22 <b>--version</b>
23 ] [
24 <b>-4</b>
25 ] [
26 <b>-6</b>
27 ] [
28 <b>-C</b>
29 ] [
30 <b>-E</b>
31 ] [
32 <b>-I</b>
33 ] [
34 <b>-L</b>
35 ] [
36 <b>-P</b>
37 <i>filename.plist</i>
38 ] [
39 <b>-S</b>
40 ] [
41 <b>-T</b>
42 <i>seconds</i>
43 ] [
44 <b>-V</b>
45 <i>version</i>
46 ] [
47 <b>-X</b>
48 ] [
49 <b>-c</b>
50 ] [
51 <b>-d</b>
52 <i>name=value</i>
53 ] [
54 <b>-f</b>
55 <i>filename</i>
56 ] [
57 <b>-h</b>
58 ] [
59 <b>-i</b>
60 <i>seconds</i>
61 ] [
62 <b>-n</b>
63 <i>repeat-count</i>
64 ] [
65 <b>-q</b>
66 ] [
67 <b>-t</b>
68 ] [
69 <b>-v</b><b>]</b>
70 <i>printer-uri</i>
71 <i>testfile</i>
72 [ ...
73 <i>testfile</i>
74 ]
75 <h2 class="title"><a name="DESCRIPTION">Description</a></h2>
76 <b>ipptool</b>
77 sends IPP requests to the specified
78 <i>printer-uri</i>
79 and tests and/or displays the results.
80 Each named
81 <i>testfile</i>
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</i>
86 format is described in
87 <b>ipptoolfile</b>(5).
88 <h2 class="title"><a name="OPTIONS">Options</a></h2>
89 The following options are recognized by
90 <b>ipptool:</b>
91 <dl class="man">
92 <dt><b>--help</b>
93 <dd style="margin-left: 5.0em">Shows program help.
94 <dt><b>--ippserver </b><i>filename</i>
95 <dd style="margin-left: 5.0em">Specifies that the test results should be written to the named
96 <b>ippserver</b>
97 attributes file.
98 <dt><b>--stop-after-include-error</b>
99 <dd style="margin-left: 5.0em">Tells
100 <b>ipptool</b>
101 to stop if an error occurs in an included file. Normally
102 <b>ipptool</b>
103 will continue with subsequent tests after the INCLUDE directive.
104 <dt><b>--version</b>
105 <dd style="margin-left: 5.0em">Shows the version of
106 <b>ipptool</b>
107 being used.
108 <dt><b>-4</b>
109 <dd style="margin-left: 5.0em">Specifies that
110 <b>ipptool</b>
111 must connect to the printer or server using IPv4.
112 <dt><b>-6</b>
113 <dd style="margin-left: 5.0em">Specifies that
114 <b>ipptool</b>
115 must connect to the printer or server using IPv6.
116 <dt><b>-C</b>
117 <dd style="margin-left: 5.0em">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.
118 The default is to use "Transfer-Encoding: chunked" for requests with attached files and "Content-Length:" for requests without attached files.
119 <dt><b>-E</b>
120 <dd style="margin-left: 5.0em">Forces TLS encryption when connecting to the server using the HTTP "Upgrade" header.
121 <dt><b>-I</b>
122 <dd style="margin-left: 5.0em">Specifies that
123 <b>ipptool</b>
124 will continue past errors.
125 <dt><b>-L</b>
126 <dd style="margin-left: 5.0em">Specifies that requests should be sent using the HTTP/1.0 "Content-Length:" header, which is required for conformance by all versions of IPP.
127 The default is to use "Transfer-Encoding: chunked" for requests with attached files and "Content-Length:" for requests without attached files.
128 <dt><b>-P</b><i> filename.plist</i>
129 <dd style="margin-left: 5.0em">Specifies that the test results should be written to the named XML (Apple plist) file in addition to the regular test report (<b>-t</b>).
130 This option is incompatible with the <b>-i</b> (interval) and <b>-n</b> (repeat-count) options.
131 <dt><b>-S</b>
132 <dd style="margin-left: 5.0em">Forces (dedicated) TLS encryption when connecting to the server.
133 <dt><b>-T</b><i> seconds</i>
134 <dd style="margin-left: 5.0em">Specifies a timeout for IPP requests in seconds.
135 <dt><b>-V</b><i> version</i>
136 <dd style="margin-left: 5.0em">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.
137 <dt><b>-X</b>
138 <dd style="margin-left: 5.0em">Specifies that XML (Apple plist) output is desired instead of the plain text report.
139 This option is incompatible with the <b>-i</b> (interval) and <b>-n</b> (repeat-count) options.
140 <dt><b>-c</b>
141 <dd style="margin-left: 5.0em">Specifies that CSV (comma-separated values) output is desired instead of the plain text output.
142 <dt><b>-d</b><i> name=value</i>
143 <dd style="margin-left: 5.0em">Defines the named variable.
144 <dt><b>-f</b><i> filename</i>
145 <dd style="margin-left: 5.0em">Defines the default request filename for tests.
146 <dt><b>-h</b>
147 <dd style="margin-left: 5.0em">Validate HTTP response headers.
148 <dt><b>-i</b><i> seconds</i>
149 <dd style="margin-left: 5.0em">Specifies that the (last)
150 <i>testfile</i>
151 should be repeated at the specified interval.
152 This option is incompatible with the <b>-X</b> (XML plist output) option.
153 <dt><b>-l</b>
154 <dd style="margin-left: 5.0em">Specifies that plain text output is desired.
155 <dt><b>-n</b><i> repeat-count</i>
156 <dd style="margin-left: 5.0em">Specifies that the (last)
157 <i>testfile</i>
158 should be repeated the specified number of times.
159 This option is incompatible with the <i>-X</i> (XML plist output) option.
160 <dt><b>-q</b>
161 <dd style="margin-left: 5.0em">Be quiet and produce no output.
162 <dt><b>-t</b>
163 <dd style="margin-left: 5.0em">Specifies that CUPS test report output is desired instead of the plain text output.
164 <dt><b>-v</b>
165 <dd style="margin-left: 5.0em">Specifies that all request and response attributes should be output in CUPS test mode (<b>-t</b>).
166 This is the default for XML output.
167 </dl>
168 <h2 class="title"><a name="EXIT_STATUS">Exit Status</a></h2>
169 The
170 <b>ipptool</b>
171 program returns 0 if all tests were successful and 1 otherwise.
172 <h2 class="title"><a name="FILES">Files</a></h2>
173 The following standard files are available:
174 <pre class="man">
175 <i>color.jpg</i>
176 <i>create-printer-subscription.test</i>
177 <i>document-a4.pdf</i>
178 <i>document-a4.ps</i>
179 <i>document-letter.pdf</i>
180 <i>document-letter.ps</i>
181 <i>get-completed-jobs.test</i>
182 <i>get-jobs.test</i>
183 <i>get-notifications.test</i>
184 <i>get-printer-attributes.test</i>
185 <i>get-subscriptions.test</i>
186 <i>gray.jpg</i>
187 <i>ipp-1.1.test</i>
188 <i>ipp-2.0.test</i>
189 <i>ipp-2.1.test</i>
190 <i>ipp-2.2.test</i>
191 <i>ipp-everywhere.test</i>
192 <i>onepage-a4.pdf</i>
193 <i>onepage-a4.ps</i>
194 <i>onepage-letter.pdf</i>
195 <i>onepage-letter.ps</i>
196 <i>print-job.test</i>
197 <i>print-job-deflate.test</i>
198 <i>print-job-gzip.test</i>
199 <i>testfile.jpg</i>
200 <i>testfile.pcl</i>
201 <i>testfile.pdf</i>
202 <i>testfile.ps</i>
203 <i>testfile.txt</i>
204 <i>validate-job.test</i>
205 </pre>
206 <h2 class="title"><a name="CONFORMING_TO">Conforming To</a></h2>
207 The
208 <b>ipptool</b>
209 program is unique to CUPS and conforms to the Internet Printing Protocol up to version 2.2.
210 <h2 class="title"><a name="EXAMPLES">Examples</a></h2>
211 Get a list of completed jobs for "myprinter":
212 <pre class="man">
213
214     ipptool ipp://localhost/printers/myprinter get-completed-jobs.test
215 </pre>
216 <p>Send email notifications to "user@example.com" when "myprinter" changes:
217 <pre class="man">
218
219     ipptool -d recipient=mailto:user@example.com \
220         ipp://localhost/printers/myprinter create-printer-subscription.test
221 </pre>
222 <h2 class="title"><a name="SEE_ALSO">See Also</a></h2>
223 <b>ipptoolfile</b>(5),
224 IANA IPP Registry (<a href="http://www.iana.org/assignments/ipp\-registrations)">http://www.iana.org/assignments/ipp\-registrations)</a>,
225 PWG Internet Printing Protocol Workgroup (<a href="http://www.pwg.org/ipp">http://www.pwg.org/ipp</a>)
226 RFC 8011 (<a href="http://tools.ietf.org/html/rfc8011)">http://tools.ietf.org/html/rfc8011)</a>,
227 <h2 class="title"><a name="COPYRIGHT">Copyright</a></h2>
228 Copyright &copy; 2007-2019 by Apple Inc.
229
230 </body>
231 </html>