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