doc/help/man-ippfind.html

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