[thirdparty/cups.git] / doc / help / man-ipptool.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- SECTION: Man Pages -->
<head>
	<link rel="stylesheet" type="text/css" href="../cups-printable.css">
	<title>ipptool(1)</title>
</head>
<body>
<h1 class="title">ipptool(1)</h1>
<h2 class="title"><a name="NAME">Name</a></h2>
ipptool - perform internet printing protocol requests
<h2 class="title"><a name="SYNOPSIS">Synopsis</a></h2>
<b>ipptool
</b>[ --help ] [ --stop-after-include-error ] [ --version ]
[ -4 ] [ -6 ] [ -C ] [ -E ] [ -I ] [ -L ] [ -S ] [ -T
<i>seconds
</i>] [ -V
<i>version
</i>] [ -X ] [ -c ] [ -d
<i>name=value
</i>] [ -f
<i>filename
</i>] [ -i
<i>seconds
</i>] [ -n
<i>repeat-count
</i>] [ -q ] [ -t ] [ -v ]
<i>URI
</i><i>filename
</i>[
<i>... filenameN
</i>]
<h2 class="title"><a name="DESCRIPTION">Description</a></h2>
<i>ipptool</i> sends IPP requests to the specified URI and tests and/or displays the results. Each named file 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 file format is described in <a href='man-ipptoolfile.html?TOPIC=Man+Pages'>ipptoolfile(5)</a>.
<h2 class="title"><a name="OPTIONS">Options</a></h2>
The following options are recognized by <i>ipptool</i>:
<dl>
<dt>--help
</dt>
<dd>Shows program help.
</dd>
<dt>--stop-after-include-error
</dt>
<dd>Tells <i>ipptool</i> to stop if an error occurs in an included file. Normally <i>ipptool</i> will continue with subsequent tests after the INCLUDE directive.
</dd>
<dt>--version
</dt>
<dd>Shows the version of <i>ipptool</i> being used.
</dd>
<dt>-4
</dt>
<dd>Specifies that <i>ipptool</i> must connect to the printer or server using IPv4.
</dd>
<dt>-6
</dt>
<dd>Specifies that <i>ipptool</i> must connect to the printer or server using IPv6.
</dd>
<dt>-C
</dt>
<dd>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.
</dd>
<dt>-E
</dt>
<dd>Forces TLS encryption when connecting to the server using the HTTP "Upgrade" header.
</dd>
<dt>-I
</dt>
<dd>Specifies that <i>ipptool</i> will continue past errors.
</dd>
<dt>-L
</dt>
<dd>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.
</dd>
<dt>-S
</dt>
<dd>Forces (dedicated) SSL encryption when connecting to the server.
</dd>
<dt>-T seconds
</dt>
<dd>Specifies a timeout for IPP requests in seconds.
</dd>
<dt>-V version
</dt>
<dd>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.
</dd>
<dt>-X
</dt>
<dd>Specifies that XML (Apple plist) output is desired instead of the plain text report. This option is incompatible with the <i>-i</i> (interval) and <i>-n</i> (repeat-count) options.
</dd>
<dt>-c
</dt>
<dd>Specifies that CSV (comma-separated values) output is desired instead of the plain text output.
</dd>
<dt>-d name=value
</dt>
<dd>Defines the named variable.
</dd>
<dt>-f filename
</dt>
<dd>Defines the default request filename for tests.
</dd>
<dt>-i seconds
</dt>
<dd>Specifies that the (last) file should be repeated at the specified interval. This option is incompatible with the <i>-X</i> (XML plist output) option.
</dd>
<dt>-l
</dt>
<dd>Specifies that plain text output is desired.
</dd>
<dt>-n repeat-count
</dt>
<dd>Specifies that the (last) file should be repeated the specified number of times. This option is incompatible with the <i>-X</i> (XML plist output) option.
</dd>
<dt>-t
</dt>
<dd>Specifies that CUPS test report output is desired instead of the plain text output.
</dd>
<dt>-v
</dt>
<dd>Specifies that all request and response attributes should be output in CUPS test mode (<i>-t</i>). This is the default for XML output.
</dd>
</dl>
<h2 class="title"><a name="EXIT_CODE">Exit Code</a></h2>
The <i>ipptool</i> program returns 0 if all tests were sucessful and 1 otherwise.
<h2 class="title"><a name="COMPATIBILITY">Compatibility</a></h2>
The <i>ipptool</i> program is unique to CUPS.
<h2 class="title"><a name="EXAMPLES">Examples</a></h2>
Get a list of completed jobs for "myprinter":
<pre>
    ipptool ipp://localhost/printers/myprinter get-completed-jobs.test
</pre>
<p>Send email notifications to "user@example.com" when "myprinter" changes:
<pre>
    ipptool -d recipient=mailto:user@example.com 
        ipp://localhost/printers/myprinter create-printer-subscription.test
</pre>
<h2 class="title"><a name="STANDARD_FILES">Standard Files</a></h2>
The following standard files are available:
<pre>
    color.jpg
    create-printer-subscription.test
    document-a4.pdf
    document-a4.ps
    document-letter.pdf
    document-letter.ps
    get-completed-jobs.test
    get-jobs.test
    get-notifications.test
    get-printer-attributes.test
    get-subscriptions.test
    gray.jpg
    ipp-1.1.test
    ipp-2.0.test
    ipp-2.1.test
    ipp-2.2.test
    ipp-everywhere.test
    onepage-a4.pdf
    onepage-a4.ps
    onepage-letter.pdf
    onepage-letter.ps
    print-job.test
    print-job-deflate.test
    print-job-gzip.test
    testfile.jpg
    testfile.pcl
    testfile.pdf
    testfile.ps
    testfile.txt
    validate-job.test
</pre>
<h2 class="title"><a name="SEE_ALSO">See Also</a></h2>
<a href='man-ipptoolfile.html?TOPIC=Man+Pages'>ipptoolfile(5)</a>, RFC 2911,
<br>
<a href='http://localhost:631/help'>http://localhost:631/help</a>
<br>
<a href='http://www.iana.org/assignments/ipp-registrations'>http://www.iana.org/assignments/ipp-registrations</a>
<br>
<a href='http://www.pwg.org/ipp'>http://www.pwg.org/ipp</a>
<h2 class="title"><a name="COPYRIGHT">Copyright</a></h2>
Copyright 2007-2014 by Apple Inc.

</body>
</html>
Commit	Line	Data
a2326b5b MS	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
	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
9475ec92 MS	14	</b>[ --help ] [ --stop-after-include-error ] [ --version ]
9475ec92 MS	15	[ -4 ] [ -6 ] [ -C ] [ -E ] [ -I ] [ -L ] [ -S ] [ -T
a2326b5b MS	16	<i>seconds
	17	</i>] [ -V
	18	<i>version
	19	</i>] [ -X ] [ -c ] [ -d
	20	<i>name=value
	21	</i>] [ -f
	22	<i>filename
	23	</i>] [ -i
	24	<i>seconds
	25	</i>] [ -n
	26	<i>repeat-count
	27	</i>] [ -q ] [ -t ] [ -v ]
	28	<i>URI
	29	</i><i>filename
	30	</i>[
	31	<i>... filenameN
	32	</i>]
	33	<h2 class="title"><a name="DESCRIPTION">Description</a></h2>
	34	<i>ipptool</i> sends IPP requests to the specified URI and tests and/or displays the results. Each named file 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 file format is described in <a href='man-ipptoolfile.html?TOPIC=Man+Pages'>ipptoolfile(5)</a>.
	35	<h2 class="title"><a name="OPTIONS">Options</a></h2>
	36	The following options are recognized by <i>ipptool</i>:
	37	<dl>
9475ec92 MS	38	<dt>--help
	39	</dt>
	40	<dd>Shows program help.
71f63681 MS	41	</dd>
	42	<dt>--stop-after-include-error
	43	</dt>
	44	<dd>Tells <i>ipptool</i> to stop if an error occurs in an included file. Normally <i>ipptool</i> will continue with subsequent tests after the INCLUDE directive.
	45	</dd>
	46	<dt>--version
	47	</dt>
	48	<dd>Shows the version of <i>ipptool</i> being used.
9475ec92	49	</dd>
a2326b5b MS	50	<dt>-4
	51	</dt>
	52	<dd>Specifies that <i>ipptool</i> must connect to the printer or server using IPv4.
	53	</dd>
	54	<dt>-6
	55	</dt>
	56	<dd>Specifies that <i>ipptool</i> must connect to the printer or server using IPv6.
	57	</dd>
	58	<dt>-C
	59	</dt>
	60	<dd>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.
	61	</dd>
	62	<dt>-E
	63	</dt>
	64	<dd>Forces TLS encryption when connecting to the server using the HTTP "Upgrade" header.
	65	</dd>
	66	<dt>-I
	67	</dt>
	68	<dd>Specifies that <i>ipptool</i> will continue past errors.
	69	</dd>
	70	<dt>-L
	71	</dt>
	72	<dd>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.
	73	</dd>
	74	<dt>-S
	75	</dt>
	76	<dd>Forces (dedicated) SSL encryption when connecting to the server.
	77	</dd>
	78	<dt>-T seconds
	79	</dt>
	80	<dd>Specifies a timeout for IPP requests in seconds.
	81	</dd>
	82	<dt>-V version
	83	</dt>
	84	<dd>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.
	85	</dd>
	86	<dt>-X
	87	</dt>
	88	<dd>Specifies that XML (Apple plist) output is desired instead of the plain text report. This option is incompatible with the <i>-i</i> (interval) and <i>-n</i> (repeat-count) options.
	89	</dd>
	90	<dt>-c
	91	</dt>
	92	<dd>Specifies that CSV (comma-separated values) output is desired instead of the plain text output.
	93	</dd>
	94	<dt>-d name=value
	95	</dt>
	96	<dd>Defines the named variable.
	97	</dd>
	98	<dt>-f filename
	99	</dt>
	100	<dd>Defines the default request filename for tests.
	101	</dd>
	102	<dt>-i seconds
	103	</dt>
	104	<dd>Specifies that the (last) file should be repeated at the specified interval. This option is incompatible with the <i>-X</i> (XML plist output) option.
	105	</dd>
	106	<dt>-l
	107	</dt>
	108	<dd>Specifies that plain text output is desired.
	109	</dd>
	110	<dt>-n repeat-count
	111	</dt>
	112	<dd>Specifies that the (last) file should be repeated the specified number of times. This option is incompatible with the <i>-X</i> (XML plist output) option.
	113	</dd>
114	<dt>-t
115	</dt>
116	<dd>Specifies that CUPS test report output is desired instead of the plain text output.
117	</dd>
118	<dt>-v
119	</dt>
120	<dd>Specifies that all request and response attributes should be output in CUPS test mode (<i>-t</i>). This is the default for XML output.
121	</dd>
122	</dl>
9475ec92 MS	123	<h2 class="title"><a name="EXIT_CODE">Exit Code</a></h2>
9475ec92 MS	124	The <i>ipptool</i> program returns 0 if all tests were sucessful and 1 otherwise.
a2326b5b MS	125	<h2 class="title"><a name="COMPATIBILITY">Compatibility</a></h2>
	126	The <i>ipptool</i> program is unique to CUPS.
	127	<h2 class="title"><a name="EXAMPLES">Examples</a></h2>
	128	Get a list of completed jobs for "myprinter":
	129	<pre>
	130	ipptool ipp://localhost/printers/myprinter get-completed-jobs.test
	131	</pre>
	132	<p>Send email notifications to "user@example.com" when "myprinter" changes:
	133	<pre>
	134	ipptool -d recipient=mailto:user@example.com
	135	ipp://localhost/printers/myprinter create-printer-subscription.test
	136	</pre>
	137	<h2 class="title"><a name="STANDARD_FILES">Standard Files</a></h2>
	138	The following standard files are available:
	139	<pre>
f3c17241	140	color.jpg
a2326b5b	141	create-printer-subscription.test
f3c17241 MS	142	document-a4.pdf
	143	document-a4.ps
	144	document-letter.pdf
	145	document-letter.ps
a2326b5b MS	146	get-completed-jobs.test
a2326b5b MS	147	get-jobs.test
9475ec92	148	get-notifications.test
f3c17241	149	get-printer-attributes.test
9475ec92	150	get-subscriptions.test
f3c17241	151	gray.jpg
a2326b5b MS	152	ipp-1.1.test
	153	ipp-2.0.test
	154	ipp-2.1.test
f3c17241	155	ipp-2.2.test
9475ec92	156	ipp-everywhere.test
f3c17241 MS	157	onepage-a4.pdf
	158	onepage-a4.ps
	159	onepage-letter.pdf
	160	onepage-letter.ps
	161	print-job.test
9475ec92 MS	162	print-job-deflate.test
9475ec92 MS	163	print-job-gzip.test
a2326b5b	164	testfile.jpg
9475ec92	165	testfile.pcl
a2326b5b MS	166	testfile.pdf
	167	testfile.ps
	168	testfile.txt
9475ec92	169	validate-job.test
a2326b5b MS	170	</pre>
a2326b5b MS	171	<h2 class="title"><a name="SEE_ALSO">See Also</a></h2>
71f63681	172	<a href='man-ipptoolfile.html?TOPIC=Man+Pages'>ipptoolfile(5)</a>, RFC 2911,
a2326b5b MS	173	<br>
a2326b5b MS	174	<a href='http://localhost:631/help'>http://localhost:631/help</a>
71f63681 MS	175	<br>
	176	<a href='http://www.iana.org/assignments/ipp-registrations'>http://www.iana.org/assignments/ipp-registrations</a>
	177	<br>
	178	<a href='http://www.pwg.org/ipp'>http://www.pwg.org/ipp</a>
a2326b5b	179	<h2 class="title"><a name="COPYRIGHT">Copyright</a></h2>
71f63681	180	Copyright 2007-2014 by Apple Inc.
a2326b5b MS	181
	182	</body>
	183	</html>