]> git.ipfire.org Git - thirdparty/cups.git/blame - doc/help/man-ippfind.html
Initial work on man page modernization (STR #4372)
[thirdparty/cups.git] / doc / help / man-ippfind.html
CommitLineData
c277f98c 1<!DOCTYPE HTML>
766a8229
MS
2<html>
3<!-- SECTION: Man Pages -->
4<head>
5 <link rel="stylesheet" type="text/css" href="../cups-printable.css">
6 <title>ippfind(1)</title>
7</head>
8<body>
9<h1 class="title">ippfind(1)</h1>
10<h2 class="title"><a name="NAME">Name</a></h2>
11ippfind - find internet printing protocol printers
12<h2 class="title"><a name="SYNOPSIS">Synopsis</a></h2>
c277f98c
MS
13<b>ippfind</b>
14[
15<i>options</i>
16] regtype[,subtype][.domain.] ... [
17<i>expression</i> <i>...</i>
18]
19<b>ippfind</b>
20[
21<i>options</i>
22] name[.regtype[.domain.]] ... [
23<i>expression</i> <i>...</i>
24]
25<b>ippfind</b>
26--help
27<b>ippfind</b>
28--version
766a8229 29<h2 class="title"><a name="OPTIONS">Options</a></h2>
c277f98c
MS
30<p style="margin-left: 5.0em; text-indent: -5.0em">--help
31<br>
32Show program help
33<p style="margin-left: 5.0em; text-indent: -5.0em">--version
34<br>
35Show program version
36<p style="margin-left: 5.0em; text-indent: -5.0em">-4
37<br>
38Use IPv4 when listing
39<p style="margin-left: 5.0em; text-indent: -5.0em">-6
40<br>
41Use IPv6 when listing
42<p style="margin-left: 5.0em; text-indent: -5.0em">-T seconds
43<br>
44Specify find timeout in seconds. If 1 or less, <i>ippfind</i> stops as soon as it thinks it has found everything. The default is 1 second.
45<p style="margin-left: 5.0em; text-indent: -5.0em">-V version
46<br>
47Specifies the IPP version when listing. Supported values are 1.1, 2.0, 2.1, and 2.2.
766a8229 48
766a8229 49<h2 class="title"><a name="DESCRIPTION">Description</a></h2>
e5528d42
MS
50<i>ippfind</i> finds services registered with a DNS server or available through local devices. Its primary purpose is to find IPP printers and show their URIs, show their current status, or run commands. For example, to show the status of all registered IPP printers on your network, run:
51<pre>
52 ippfind --ls
53</pre>
54Similarly, to send a PostScript test page to every PostScript printer, run:
55<pre>
56 ippfind --txt-pdl application/postscript --exec ipptool \
57 -f onepage-letter.ps '{}' print-job.test \;
58</pre>
59
60<h2 class="title"><a name="REGISTRATION_TYPES">Registration Types</a></h2>
61<i>ippfind</i> supports the following registration types:
c277f98c
MS
62<p style="margin-left: 5.0em; text-indent: -5.0em">_http._tcp
63<br>
64HyperText Transport Protocol (HTTP, RFC 2616)
65<p style="margin-left: 5.0em; text-indent: -5.0em">_https._tcp
66<br>
67Secure HyperText Transport Protocol (HTTPS, RFC 2818)
68<p style="margin-left: 5.0em; text-indent: -5.0em">_ipp._tcp
69<br>
70Internet Printing Protocol (IPP, RFC 2911)
71<p style="margin-left: 5.0em; text-indent: -5.0em">_ipps._tcp
72<br>
73Secure Internet Printing Protocol (IPPS, draft)
74<p style="margin-left: 5.0em; text-indent: -5.0em">_printer._tcp
75<br>
76Line Printer Daemon (LPD, RFC 1179)
766a8229
MS
77
78<h2 class="title"><a name="EXPRESSIONS">Expressions</a></h2>
e5528d42 79<i>ippfind</i> supports expressions much like the <i>find(1)</i> utility. However, unlike <i>find</i>, <i>ippfind</i> uses POSIX regular expressions instead of shell filename matching patterns. If --exec, -l, --ls, -p, --print, --print-name, -q, --quiet, -s, or -x is not specified, <i>ippfind</i> adds --print to print the service URI of anything it finds. The following expressions are supported:
c277f98c
MS
80<p style="margin-left: 5.0em; text-indent: -5.0em">-d regex
81<br>
82<p style="margin-left: 5.0em; text-indent: -5.0em">--domain regex
83<br>
84True if the domain matches the given regular expression.
85<p style="margin-left: 5.0em; text-indent: -5.0em">--false
86<br>
87Always false.
88<p style="margin-left: 5.0em; text-indent: -5.0em">-h regex
89<br>
90<p style="margin-left: 5.0em; text-indent: -5.0em">--host regex
91<br>
92True is the hostname matches the given regular expression.
93<p style="margin-left: 5.0em; text-indent: -5.0em">-l
94<br>
95<p style="margin-left: 5.0em; text-indent: -5.0em">--ls
96<br>
97Lists attributes returned by Get-Printer-Attributes for IPP printers and traditional <i>find</i> "-ls" output for HTTP URLs. The result is true if the URI is accessible, false otherwise.
98<p style="margin-left: 5.0em; text-indent: -5.0em">--local
99<br>
100True if the service is local to this computer.
101<p style="margin-left: 5.0em; text-indent: -5.0em">-n regex
102<br>
103<p style="margin-left: 5.0em; text-indent: -5.0em">--name regex
104<br>
105True if the service instance name matches the given regular expression.
106<p style="margin-left: 5.0em; text-indent: -5.0em">--path regex
107<br>
108True if the URI resource path matches the given regular expression.
109<p style="margin-left: 5.0em; text-indent: -5.0em">-P number[-number]
110<br>
111<p style="margin-left: 5.0em; text-indent: -5.0em">--port number[-number]
112<br>
113True if the port matches the given number or range.
114<p style="margin-left: 5.0em; text-indent: -5.0em">-p
115<br>
116<p style="margin-left: 5.0em; text-indent: -5.0em">--print
117<br>
118Prints the URI if the result of previous expressions is true. The result is always true.
119<p style="margin-left: 5.0em; text-indent: -5.0em">-q
120<br>
121<p style="margin-left: 5.0em; text-indent: -5.0em">--quiet
122<br>
123Quiet mode - just returns the exit codes below.
124<p style="margin-left: 5.0em; text-indent: -5.0em">-r
125<br>
126<p style="margin-left: 5.0em; text-indent: -5.0em">--remote
127<br>
128True if the service is not local to this computer.
129<p style="margin-left: 5.0em; text-indent: -5.0em">-s
130<br>
131<p style="margin-left: 5.0em; text-indent: -5.0em">--print-name
132<br>
133Prints the service instance name if the result of previous expressions is true. The result is always true.
134<p style="margin-left: 5.0em; text-indent: -5.0em">--true
135<br>
136Always true.
137<p style="margin-left: 5.0em; text-indent: -5.0em">-t key
138<br>
139<p style="margin-left: 5.0em; text-indent: -5.0em">--txt key
140<br>
141True if the TXT record contains the named key.
142<p style="margin-left: 5.0em; text-indent: -5.0em">--txt-<i>key</i> regex
143<br>
144True if the TXT record contains the named key and matches the given regular
766a8229 145expression.
c277f98c
MS
146<p style="margin-left: 5.0em; text-indent: -5.0em">-u regex
147<br>
148<p style="margin-left: 5.0em; text-indent: -5.0em">--uri regex
149<br>
150True if the URI matches the given regular expression.
151<p style="margin-left: 5.0em; text-indent: -5.0em">-x utility [argument ...] ;
152<br>
153<p style="margin-left: 5.0em; text-indent: -5.0em">--exec utility [argument ...] ;
154<br>
155Executes the specified program if the current result is true. "{foo}" arguments are replaced with the corresponding value - see SUBSTITUTIONS below.
766a8229 156<p>Expressions may also contain modifiers:
c277f98c
MS
157<p style="margin-left: 5.0em; text-indent: -5.0em">( expression )
158<br>
159Group the result of expressions.
160<p style="margin-left: 5.0em; text-indent: -5.0em">! expression
161<br>
162<p style="margin-left: 5.0em; text-indent: -5.0em">--not expression
163<br>
164Unary NOT of the expression.
165<p style="margin-left: 5.0em; text-indent: -5.0em">expression expression
166<br>
167<p style="margin-left: 5.0em; text-indent: -5.0em">expression --and expression
168<br>
169Logical AND of expressions.
170<p style="margin-left: 5.0em; text-indent: -5.0em">expression --or expression
171<br>
172Logical OR of expressions.
766a8229 173
766a8229
MS
174<h2 class="title"><a name="SUBSTITUTIONS">Substitutions</a></h2>
175The substitutions for "{foo}" in -e and --exec are:
c277f98c
MS
176<p style="margin-left: 5.0em; text-indent: -5.0em">{}
177<br>
178URI
179<p style="margin-left: 5.0em; text-indent: -5.0em">{service_domain}
180<br>
181Domain name, e.g., "example.com.", "local.", etc.
182<p style="margin-left: 5.0em; text-indent: -5.0em">{service_hostname}
183<br>
184Fully-qualified domain name, e.g., "printer.example.com.", "printer.local.", etc.
185<p style="margin-left: 5.0em; text-indent: -5.0em">{service_name}
186<br>
187Service instance name, e.g., "My Fine Printer".
188<p style="margin-left: 5.0em; text-indent: -5.0em">{service_port}
189<br>
190Port number for server, typically 631 for IPP and 80 for HTTP.
191<p style="margin-left: 5.0em; text-indent: -5.0em">{service_regtype}
192<br>
193DNS-SD registration type, e.g., "_ipp._tcp", "_http._tcp", etc.
194<p style="margin-left: 5.0em; text-indent: -5.0em">{service_scheme}
195<br>
196URI scheme for DNS-SD registration type, e.g., "ipp", "http", etc.
197<p style="margin-left: 5.0em; text-indent: -5.0em">{service_uri}
198<br>
199URI for service, e.g., "ipp://printer.local./ipp/print", "<a href="http://printer.local./", etc.">http://printer.local./", etc.</a> etc.
200<p style="margin-left: 5.0em; text-indent: -5.0em">{txt_<i>key</i>}
201<br>
202Value of TXT record <i>key</i> (lowercase).
766a8229 203
766a8229
MS
204<h2 class="title"><a name="ENVIRONMENT_VARIABLES">Environment Variables</a></h2>
205When executing a program, <i>ippfind</i> sets the following environment variables for the matching service registration:
c277f98c
MS
206<p style="margin-left: 5.0em; text-indent: -5.0em">IPPFIND_SERVICE_DOMAIN
207<br>
208Domain name, e.g., "example.com.", "local.", etc.
209<p style="margin-left: 5.0em; text-indent: -5.0em">IPPFIND_SERVICE_HOSTNAME
210<br>
211Fully-qualified domain name, e.g., "printer.example.com.", "printer.local.", etc.
212<p style="margin-left: 5.0em; text-indent: -5.0em">IPPFIND_SERVICE_NAME
213<br>
214Service instance name, e.g., "My Fine Printer".
215<p style="margin-left: 5.0em; text-indent: -5.0em">IPPFIND_SERVICE_PORT
216<br>
217Port number for server, typically 631 for IPP and 80 for HTTP.
218<p style="margin-left: 5.0em; text-indent: -5.0em">IPPFIND_SERVICE_REGTYPE
219<br>
220DNS-SD registration type, e.g., "_ipp._tcp", "_http._tcp", etc.
221<p style="margin-left: 5.0em; text-indent: -5.0em">IPPFIND_SERVICE_SCHEME
222<br>
223URI scheme for DNS-SD registration type, e.g., "ipp", "http", etc.
224<p style="margin-left: 5.0em; text-indent: -5.0em">IPPFIND_SERVICE_URI
225<br>
226URI for service, e.g., "ipp://printer.local./ipp/print", "<a href="http://printer.local./", etc.">http://printer.local./", etc.</a> etc.
227<p style="margin-left: 5.0em; text-indent: -5.0em">IPPFIND_TXT_<i>KEY</i>
228<br>
229Values of TXT record <i>KEY</i> (uppercase).
766a8229 230
766a8229
MS
231<h2 class="title"><a name="EXIT_CODES">Exit Codes</a></h2>
232<i>ippfind</i> returns 0 if the result for all processed expressions is true, 1 if the result of any processed expression is false, 2 if browsing or any query or resolution failed, 3 if an undefined option or invalid expression was specified, and 4 if it ran out of memory.
233
234<h2 class="title"><a name="SEE_ALSO">See Also</a></h2>
c277f98c 235<i>ipptool(1)</i>
766a8229
MS
236
237<h2 class="title"><a name="COPYRIGHT">Copyright</a></h2>
238Copyright 2013 by Apple Inc.
239
240</body>
241</html>