man/ipptool.man

   1 .\"
   2 .\" "$Id$"
   3 .\"
   4 .\"   ipptool man page for CUPS.
   5 .\"
   6 .\"   Copyright 2010-2013 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" "13 May 2013" "Apple Inc."
  15 .SH NAME
  16 ipptool - perform internet printing protocol requests
  17 .SH SYNOPSIS
  18 .B ipptool
  19 [ --help ] [ --stop-after-include-error ] [ --version ]
  20 [ -4 ] [ -6 ] [ -C ] [ -E ] [ -I ] [ -L ] [ -S ] [ -T
  21 .I seconds
  22 ] [ -V
  23 .I version
  24 ] [ -X ] [ -c ] [ -d
  25 .I name=value
  26 ] [ -f
  27 .I filename
  28 ] [ -i
  29 .I seconds
  30 ] [ -n
  31 .I repeat-count
  32 ] [ -q ] [ -t ] [ -v ]
  33 .I URI
  34 .I filename
  35 [
  36 .I ... filenameN
  37 ]
  38 .SH DESCRIPTION
  39 \fIipptool\fR 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 \fIipptoolfile(5)\fR.
  40 .SH OPTIONS
  41 The following options are recognized by \fIipptool\fR:
  42 .TP 5
  43 --help
  44 Shows program help.
  45 --stop-after-include-error
  46 Tells \fIipptool\fR to stop if an error occurs in an included file. Normally \fIipptool\fR will continue with subsequent tests after the INCLUDE directive.
  47 --version
  48 Shows the version of \fIipptool\fR being used.
  49 .TP 5
  50 -4
  51 Specifies that \fIipptool\fR must connect to the printer or server using IPv4.
  52 .TP 5
  53 -6
  54 Specifies that \fIipptool\fR must connect to the printer or server using IPv6.
  55 .TP 5
  56 -C
  57 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.
  58 .TP 5
  59 -E
  60 Forces TLS encryption when connecting to the server using the HTTP "Upgrade" header.
  61 .TP 5
  62 -I
  63 Specifies that \fIipptool\fR will continue past errors.
  64 .TP 5
  65 -L
  66 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.
  67 .TP 5
  68 -S
  69 Forces (dedicated) SSL encryption when connecting to the server.
  70 .TP 5
  71 -T seconds
  72 Specifies a timeout for IPP requests in seconds.
  73 .TP 5
  74 -V version
  75 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.
  76 .TP 5
  77 -X
  78 Specifies that XML (Apple plist) output is desired instead of the plain text report. This option is incompatible with the \fI-i\fR (interval) and \fI-n\fR (repeat-count) options.
  79 .TP 5
  80 -c
  81 Specifies that CSV (comma-separated values) output is desired instead of the plain text output.
  82 .TP 5
  83 -d name=value
  84 Defines the named variable.
  85 .TP 5
  86 -f filename
  87 Defines the default request filename for tests.
  88 .TP 5
  89 -i seconds
  90 Specifies that the (last) file should be repeated at the specified interval. This option is incompatible with the \fI-X\fR (XML plist output) option.
  91 .TP 5
  92 -l
  93 Specifies that plain text output is desired.
  94 .TP 5
  95 -n repeat-count
  96 Specifies that the (last) file should be repeated the specified number of times. This option is incompatible with the \fI-X\fR (XML plist output) option.
  97 .TP 5
  98 -t
  99 Specifies that CUPS test report output is desired instead of the plain text output.
 100 .TP 5
 101 -v
 102 Specifies that all request and response attributes should be output in CUPS test mode (\fI-t\fR). This is the default for XML output.
 103 .SH EXIT CODE
 104 The \fIipptool\fR program returns 0 if all tests were sucessful and 1 otherwise.
 105 .SH COMPATIBILITY
 106 The \fIipptool\fR program is unique to CUPS.
 107 .SH EXAMPLES
 108 Get a list of completed jobs for "myprinter":
 109 .nf
 110     ipptool ipp://localhost/printers/myprinter get-completed-jobs.test
 111 .fi
 112 .LP
 113 Send email notifications to "user@example.com" when "myprinter" changes:
 114 .nf
 115     ipptool -d recipient=mailto:user@example.com \
 116         ipp://localhost/printers/myprinter create-printer-subscription.test
 117 .fi
 118 .SH STANDARD FILES
 119 The following standard files are available:
 120 .nf
 121     color.jpg
 122     create-printer-subscription.test
 123     document-a4.pdf
 124     document-a4.ps
 125     document-letter.pdf
 126     document-letter.ps
 127     get-completed-jobs.test
 128     get-jobs.test
 129     get-notifications.test
 130     get-printer-attributes.test
 131     get-subscriptions.test
 132     gray.jpg
 133     ipp-1.1.test
 134     ipp-2.0.test
 135     ipp-2.1.test
 136     ipp-2.2.test
 137     ipp-everywhere.test
 138     onepage-a4.pdf
 139     onepage-a4.ps
 140     onepage-letter.pdf
 141     onepage-letter.ps
 142     print-job.test
 143     print-job-deflate.test
 144     print-job-gzip.test
 145     testfile.jpg
 146     testfile.pcl
 147     testfile.pdf
 148     testfile.ps
 149     testfile.txt
 150     validate-job.test
 151 .fi
 152 .SH SEE ALSO
 153 \fIipptoolfile(5)\fR,
 154 .br
 155 http://localhost:631/help
 156 .SH COPYRIGHT
 157 Copyright 2007-2013 by Apple Inc.
 158 .\"
 159 .\" End of "$Id$".
 160 .\"