]>
Commit | Line | Data |
---|---|---|
766a8229 MS |
1 | .\" |
2 | .\" "$Id$" | |
3 | .\" | |
bf1bc4c6 | 4 | .\" ippfind man page for CUPS. |
766a8229 | 5 | .\" |
bf1bc4c6 | 6 | .\" Copyright 2013-2014 by Apple Inc. |
766a8229 | 7 | .\" |
bf1bc4c6 MS |
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/". | |
766a8229 | 13 | .\" |
bf1bc4c6 | 14 | .TH ippfind 1 "CUPS" "11 June 2014" "Apple Inc." |
766a8229 | 15 | .SH NAME |
bf1bc4c6 | 16 | ippfind \- find internet printing protocol printers |
766a8229 MS |
17 | .SH SYNOPSIS |
18 | .B ippfind | |
19 | [ | |
20 | .I options | |
bf1bc4c6 MS |
21 | ] \fIregtype\fR[\fB,\fIsubtype\fR][\fB.\fIdomain\fB.\fR] ... [ |
22 | .I expression | |
0d1da748 MS |
23 | ... ] |
24 | .br | |
766a8229 MS |
25 | .B ippfind |
26 | [ | |
27 | .I options | |
0d1da748 MS |
28 | ] \fIname\fR[\fB.\fIregtype\fR[\fB.\fIdomain\fB.\fR]] ... [ |
29 | .I expression | |
30 | ... ] | |
31 | .br | |
766a8229 | 32 | .B ippfind |
0d1da748 MS |
33 | .B \-\-help |
34 | .br | |
766a8229 | 35 | .B ippfind |
0d1da748 | 36 | .B \-\-version |
766a8229 | 37 | .SH DESCRIPTION |
0d1da748 MS |
38 | \fBippfind\fR finds services registered with a DNS server or available through local devices. |
39 | Its primary purpose is to find IPP printers and show their URIs, show their current status, or run commands. | |
40 | .SS REGISTRATION TYPES | |
41 | \fBippfind\fR supports the following registration types: | |
e5528d42 MS |
42 | .TP 5 |
43 | _http._tcp | |
44 | HyperText Transport Protocol (HTTP, RFC 2616) | |
45 | .TP 5 | |
46 | _https._tcp | |
47 | Secure HyperText Transport Protocol (HTTPS, RFC 2818) | |
48 | .TP 5 | |
49 | _ipp._tcp | |
50 | Internet Printing Protocol (IPP, RFC 2911) | |
51 | .TP 5 | |
52 | _ipps._tcp | |
53 | Secure Internet Printing Protocol (IPPS, draft) | |
54 | .TP 5 | |
55 | _printer._tcp | |
56 | Line Printer Daemon (LPD, RFC 1179) | |
0d1da748 MS |
57 | .SS EXPRESSIONS |
58 | \fBippfind\fR supports expressions much like the | |
59 | .BR find (1) | |
60 | utility. | |
61 | However, unlike | |
62 | .BR find (1), | |
63 | \fBippfind\fR uses POSIX regular expressions instead of shell filename matching patterns. | |
64 | If \fI\-\-exec\fR, \fI\-l\fR, \fI\-\-ls\fR, \fI\-p\fR, \fI\-\-print\fR, \fI\-\-print\-name\fR, \fI\-q\fR, \fI\-\-quiet\fR, \fI\-s\fR, or \fI\-x\fR is not specified, \fBippfind\fR adds \fI\-\-print\fR to print the service URI of anything it finds. | |
65 | The following expressions are supported: | |
66 | .TP 5 | |
67 | \fB\-d \fIregex\fR | |
68 | .TP 5 | |
69 | \fB\-\-domain \fIregex\fR | |
766a8229 MS |
70 | True if the domain matches the given regular expression. |
71 | .TP 5 | |
0d1da748 | 72 | .B \-\-false |
766a8229 MS |
73 | Always false. |
74 | .TP 5 | |
0d1da748 | 75 | \fB\-h \fIregex\fR |
41743200 | 76 | .TP 5 |
0d1da748 | 77 | \fB\-\-host \fIregex\fR |
41743200 MS |
78 | True is the hostname matches the given regular expression. |
79 | .TP 5 | |
0d1da748 | 80 | .B \-l |
766a8229 | 81 | .TP 5 |
0d1da748 MS |
82 | .B \-\-ls |
83 | Lists attributes returned by Get-Printer-Attributes for IPP printers and traditional \fIfind\fR "-ls" output for HTTP URLs. | |
84 | The result is true if the URI is accessible, false otherwise. | |
766a8229 | 85 | .TP 5 |
0d1da748 | 86 | .B \-\-local |
766a8229 MS |
87 | True if the service is local to this computer. |
88 | .TP 5 | |
0d1da748 | 89 | \fB\-n \fIregex\fR |
766a8229 | 90 | .TP 5 |
0d1da748 | 91 | \fB\-\-name \fIregex\fR |
766a8229 MS |
92 | True if the service instance name matches the given regular expression. |
93 | .TP 5 | |
0d1da748 | 94 | \fB\-\-path \fIregex\fR |
766a8229 MS |
95 | True if the URI resource path matches the given regular expression. |
96 | .TP 5 | |
0d1da748 | 97 | \fB\-P \fInumber\fR[\fB-\fInumber\fR] |
41743200 | 98 | .TP 5 |
0d1da748 | 99 | \fB\-\-port \fInumber\fR[\fB-\fInumber\fR] |
41743200 MS |
100 | True if the port matches the given number or range. |
101 | .TP 5 | |
0d1da748 | 102 | .B \-p |
766a8229 | 103 | .TP 5 |
0d1da748 MS |
104 | .B \-\-print |
105 | Prints the URI if the result of previous expressions is true. | |
106 | The result is always true. | |
766a8229 | 107 | .TP 5 |
0d1da748 | 108 | .B \-q |
766a8229 | 109 | .TP 5 |
0d1da748 | 110 | .B \-\-quiet |
766a8229 MS |
111 | Quiet mode - just returns the exit codes below. |
112 | .TP 5 | |
0d1da748 | 113 | .B \-r |
766a8229 | 114 | .TP 5 |
0d1da748 | 115 | .B \-\-remote |
766a8229 MS |
116 | True if the service is not local to this computer. |
117 | .TP 5 | |
0d1da748 | 118 | .B \-s |
766a8229 | 119 | .TP 5 |
0d1da748 MS |
120 | .B \-\-print\-name |
121 | Prints the service instance name if the result of previous expressions is true. | |
122 | The result is always true. | |
766a8229 | 123 | .TP 5 |
0d1da748 | 124 | .B \-\-true |
766a8229 MS |
125 | Always true. |
126 | .TP 5 | |
0d1da748 | 127 | \fB\-t \fIkey\fR |
766a8229 | 128 | .TP 5 |
0d1da748 | 129 | \fB\-\-txt \fIkey\fR |
766a8229 MS |
130 | True if the TXT record contains the named key. |
131 | .TP 5 | |
0d1da748 MS |
132 | \fB\-\-txt\-\fIkey regex\fR |
133 | True if the TXT record contains the named key and matches the given regular expression. | |
766a8229 | 134 | .TP 5 |
0d1da748 | 135 | \fB\-u \fIregex\fR |
766a8229 | 136 | .TP 5 |
0d1da748 | 137 | \fB\-\-uri \fIregex\fR |
766a8229 | 138 | True if the URI matches the given regular expression. |
e5528d42 | 139 | .TP 5 |
0d1da748 | 140 | \fB\-x \fIutility \fR[ \fIargument \fR... ] \fB;\fR |
e5528d42 | 141 | .TP 5 |
0d1da748 MS |
142 | \fB\-\-exec \fIutility \fR[ \fIargument \fR... ] \fB;\fR |
143 | Executes the specified program if the current result is true. | |
144 | "{foo}" arguments are replaced with the corresponding value - see SUBSTITUTIONS below. | |
766a8229 MS |
145 | .PP |
146 | Expressions may also contain modifiers: | |
147 | .TP 5 | |
0d1da748 | 148 | \fB( \fIexpression \fB)\fR |
766a8229 MS |
149 | Group the result of expressions. |
150 | .TP 5 | |
0d1da748 | 151 | \fB! \fIexpression\fR |
766a8229 | 152 | .TP 5 |
0d1da748 | 153 | \fB\-\-not \fIexpression\fR |
766a8229 MS |
154 | Unary NOT of the expression. |
155 | .TP 5 | |
0d1da748 | 156 | \fIexpression expression\fR |
766a8229 | 157 | .TP 5 |
0d1da748 | 158 | \fIexpression \fB\-\-and \fIexpression\fR |
766a8229 MS |
159 | Logical AND of expressions. |
160 | .TP 5 | |
0d1da748 | 161 | \fIexpression \fB\-\-or \fIexpression\fR |
766a8229 | 162 | Logical OR of expressions. |
0d1da748 MS |
163 | .SS SUBSTITUTIONS |
164 | The substitutions for "{foo}" in \fI\-e\fR and \fI\-\-exec\fR are: | |
766a8229 | 165 | .TP 5 |
0d1da748 | 166 | .B {service_domain} |
766a8229 MS |
167 | Domain name, e.g., "example.com.", "local.", etc. |
168 | .TP 5 | |
0d1da748 | 169 | .B {service_hostname} |
766a8229 MS |
170 | Fully-qualified domain name, e.g., "printer.example.com.", "printer.local.", etc. |
171 | .TP 5 | |
0d1da748 | 172 | .B {service_name} |
766a8229 MS |
173 | Service instance name, e.g., "My Fine Printer". |
174 | .TP 5 | |
0d1da748 | 175 | .B {service_port} |
766a8229 MS |
176 | Port number for server, typically 631 for IPP and 80 for HTTP. |
177 | .TP 5 | |
0d1da748 | 178 | .B {service_regtype} |
766a8229 MS |
179 | DNS-SD registration type, e.g., "_ipp._tcp", "_http._tcp", etc. |
180 | .TP 5 | |
0d1da748 | 181 | .B {service_scheme} |
766a8229 MS |
182 | URI scheme for DNS-SD registration type, e.g., "ipp", "http", etc. |
183 | .TP 5 | |
0d1da748 MS |
184 | .B {} |
185 | .TP 5 | |
186 | .B {service_uri} | |
766a8229 MS |
187 | URI for service, e.g., "ipp://printer.local./ipp/print", "http://printer.local./", etc. |
188 | .TP 5 | |
0d1da748 | 189 | \fB{txt_\fIkey\fB}\fR |
766a8229 | 190 | Value of TXT record \fIkey\fR (lowercase). |
0d1da748 | 191 | .SH OPTIONS |
52f7b14a | 192 | \fBippfind\fR supports the following options: |
0d1da748 MS |
193 | .TP 5 |
194 | .B \-\-help | |
195 | Show program help. | |
196 | .TP 5 | |
197 | .B \-\-version | |
198 | Show program version. | |
199 | .TP 5 | |
200 | .B \-4 | |
201 | Use IPv4 when listing. | |
202 | .TP 5 | |
203 | .B \-6 | |
204 | Use IPv6 when listing. | |
766a8229 | 205 | .TP 5 |
0d1da748 MS |
206 | \fB\-T \fIseconds\fR |
207 | Specify find timeout in seconds. | |
208 | If 1 or less, \fBippfind\fR stops as soon as it thinks it has found everything. | |
209 | The default timeout is 1 second. | |
210 | .TP 5 | |
211 | \fB\-V \fIversion\fR | |
212 | Specifies the IPP version when listing. | |
213 | Supported values are "1.1", "2.0", "2.1", and "2.2". | |
214 | .SH EXIT STATUS | |
215 | \fBippfind\fR 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. | |
216 | .SH ENVIRONMENT | |
217 | When executing a program, \fBippfind\fR sets the following environment variables for the matching service registration: | |
218 | .TP 5 | |
219 | .B IPPFIND_SERVICE_DOMAIN | |
766a8229 MS |
220 | Domain name, e.g., "example.com.", "local.", etc. |
221 | .TP 5 | |
0d1da748 | 222 | .B IPPFIND_SERVICE_HOSTNAME |
766a8229 MS |
223 | Fully-qualified domain name, e.g., "printer.example.com.", "printer.local.", etc. |
224 | .TP 5 | |
0d1da748 | 225 | .B IPPFIND_SERVICE_NAME |
766a8229 MS |
226 | Service instance name, e.g., "My Fine Printer". |
227 | .TP 5 | |
0d1da748 | 228 | .B IPPFIND_SERVICE_PORT |
766a8229 MS |
229 | Port number for server, typically 631 for IPP and 80 for HTTP. |
230 | .TP 5 | |
0d1da748 | 231 | .B IPPFIND_SERVICE_REGTYPE |
766a8229 MS |
232 | DNS-SD registration type, e.g., "_ipp._tcp", "_http._tcp", etc. |
233 | .TP 5 | |
0d1da748 | 234 | .B IPPFIND_SERVICE_SCHEME |
766a8229 MS |
235 | URI scheme for DNS-SD registration type, e.g., "ipp", "http", etc. |
236 | .TP 5 | |
0d1da748 | 237 | .B IPPFIND_SERVICE_URI |
766a8229 MS |
238 | URI for service, e.g., "ipp://printer.local./ipp/print", "http://printer.local./", etc. |
239 | .TP 5 | |
0d1da748 | 240 | .B IPPFIND_TXT_\fIKEY\fR |
766a8229 | 241 | Values of TXT record \fIKEY\fR (uppercase). |
0d1da748 MS |
242 | .SH EXAMPLES |
243 | To show the status of all registered IPP printers on your network, run: | |
244 | .nf | |
766a8229 | 245 | |
0d1da748 | 246 | ippfind \-\-ls |
766a8229 | 247 | |
0d1da748 MS |
248 | .fi |
249 | Similarly, to send a PostScript test page to every PostScript printer, run: | |
250 | .nf | |
766a8229 | 251 | |
0d1da748 MS |
252 | ippfind \-\-txt\-pdl application/postscript \-\-exec ipptool |
253 | \-f onepage\-letter.ps '{}' print\-job.test \\; | |
254 | .fi | |
255 | .SH SEE ALSO | |
256 | .BR ipptool (1) | |
766a8229 | 257 | .SH COPYRIGHT |
fbfee7a8 | 258 | Copyright \[co] 2013-2015 by Apple Inc. |
766a8229 MS |
259 | .\" |
260 | .\" End of "$Id$". | |
261 | .\" |