man/ippfind.man

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