doc/help/api-filedir.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <!-- SECTION: Programming -->
   4 <head>
   5 <title>File and Directory APIs</title>
   6 <meta name="keywords" content="Programming">
   7 <meta name="creator" content="Mini-XML v2.6">
   8 <style type="text/css"><!--
   9 BODY {
  10   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  11 }
  12
  13 H1, H2, H3, H4, H5, H6, P, TD, TH {
  14   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  15 }
  16
  17 KBD {
  18   font-family: monaco, courier, monospace;
  19   font-weight: bold;
  20 }
  21
  22 PRE {
  23   font-family: monaco, courier, monospace;
  24 }
  25
  26 PRE.command {
  27   margin-left: 36pt;
  28 }
  29
  30 P.compact {
  31   margin: 0;
  32 }
  33
  34 P.example {
  35   font-style: italic;
  36   margin-left: 36pt;
  37 }
  38
  39 PRE.example {
  40   background: #eeeeee;
  41   border: dotted thin #999999;
  42   margin-left: 36pt;
  43   padding: 10pt;
  44 }
  45
  46 PRE.command EM, PRE.example EM {
  47   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  48 }
  49
  50 P.command {
  51   font-family: monaco, courier, monospace;
  52   margin-left: 36pt;
  53 }
  54
  55 P.formula {
  56   font-style: italic;
  57   margin-left: 36pt;
  58 }
  59
  60 BLOCKQUOTE {
  61   background: #eeeeee;
  62   border: solid thin #999999;
  63   padding: 10pt;
  64 }
  65
  66 A IMG {
  67   border: none;
  68 }
  69
  70 A:link:hover IMG {
  71   background: #f0f0f0;
  72   border-radius: 10px;
  73   -moz-border-radius: 10px;
  74 }
  75
  76 A:link, A:visited {
  77   font-weight: normal;
  78   text-decoration: none;
  79 }
  80
  81 A:link:hover, A:visited:hover, A:active {
  82   text-decoration: underline;
  83 }
  84
  85 SUB, SUP {
  86   font-size: 50%;
  87 }
  88
  89 TR.data, TD.data, TR.data TD {
  90   margin-top: 10pt;
  91   padding: 5pt;
  92   border-bottom: solid 1pt #999999;
  93 }
  94
  95 TR.data TH {
  96   border-bottom: solid 1pt #999999;
  97   padding-top: 10pt;
  98   padding-left: 5pt;
  99   text-align: left;
 100 }
 101
 102 DIV.table TABLE {
 103   border: solid thin #999999;
 104   border-collapse: collapse;
 105   border-spacing: 0;
 106   margin-left: auto;
 107   margin-right: auto;
 108 }
 109
 110 DIV.table CAPTION {
 111   caption-side: top;
 112   font-size: 120%;
 113   font-style: italic;
 114   font-weight: bold;
 115   margin-left: auto;
 116   margin-right: auto;
 117 }
 118
 119 DIV.table TABLE TD {
 120   border: solid thin #cccccc;
 121   padding-top: 5pt;
 122 }
 123
 124 DIV.table TABLE TH {
 125   background: #cccccc;
 126   border: none;
 127   border-bottom: solid thin #999999;
 128 }
 129
 130 DIV.figure TABLE {
 131   margin-left: auto;
 132   margin-right: auto;
 133 }
 134
 135 DIV.figure CAPTION {
 136   caption-side: bottom;
 137   font-size: 120%;
 138   font-style: italic;
 139   font-weight: bold;
 140   margin-left: auto;
 141   margin-right: auto;
 142 }
 143
 144 TH.label {
 145   text-align: right;
 146   vertical-align: top;
 147 }
 148
 149 TH.sublabel {
 150   text-align: right;
 151   font-weight: normal;
 152 }
 153
 154 HR {
 155   border: solid thin;
 156 }
 157
 158 SPAN.info {
 159   background: black;
 160   border: thin solid black;
 161   color: white;
 162   font-size: 80%;
 163   font-style: italic;
 164   font-weight: bold;
 165   white-space: nowrap;
 166 }
 167
 168 H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
 169   float: right;
 170   font-size: 100%;
 171 }
 172
 173 H1.title {
 174 }
 175
 176 H2.title, H3.title {
 177   border-bottom: solid 2pt #000000;
 178 }
 179
 180 DIV.indent, TABLE.indent {
 181   margin-top: 2em;
 182   margin-left: auto;
 183   margin-right: auto;
 184   width: 90%;
 185 }
 186
 187 TABLE.indent {
 188   border-collapse: collapse;
 189 }
 190
 191 TABLE.indent TD, TABLE.indent TH {
 192   padding: 0;
 193 }
 194
 195 TABLE.list {
 196   border-collapse: collapse;
 197   margin-left: auto;
 198   margin-right: auto;
 199   width: 90%;
 200 }
 201
 202 TABLE.list TH {
 203   background: white;
 204   border-bottom: solid thin #cccccc;
 205   color: #444444;
 206   padding-top: 10pt;
 207   padding-left: 5pt;
 208   text-align: left;
 209   vertical-align: bottom;
 210   white-space: nowrap;
 211 }
 212
 213 TABLE.list TH A {
 214   color: #4444cc;
 215 }
 216
 217 TABLE.list TD {
 218   border-bottom: solid thin #eeeeee;
 219   padding-top: 5pt;
 220   padding-left: 5pt;
 221 }
 222
 223 TABLE.list TR:nth-child(even) {
 224   background: #f8f8f8;
 225 }
 226
 227 TABLE.list TR:nth-child(odd) {
 228   background: #f4f4f4;
 229 }
 230
 231 DT {
 232   margin-left: 36pt;
 233   margin-top: 12pt;
 234 }
 235
 236 DD {
 237   margin-left: 54pt;
 238 }
 239
 240 DL.category DT {
 241   font-weight: bold;
 242 }
 243
 244 P.summary {
 245   margin-left: 36pt;
 246   font-family: monaco, courier, monospace;
 247 }
 248
 249 DIV.summary TABLE {
 250   border: solid thin #999999;
 251   border-collapse: collapse;
 252   border-spacing: 0;
 253   margin: 10px;
 254 }
 255
 256 DIV.summary TABLE TD, DIV.summary TABLE TH {
 257   border: solid thin #999999;
 258   padding: 5px;
 259   text-align: left;
 260   vertical-align: top;
 261 }
 262
 263 DIV.summary TABLE THEAD TH {
 264   background: #eeeeee;
 265 }
 266
 267 /* API documentation styles... */
 268 div.body h1 {
 269   margin: 0;
 270 }
 271 div.body h2 {
 272   margin-top: 1.5em;
 273 }
 274 div.body h3, div.body h4, div.body h5 {
 275   margin-bottom: 0.5em;
 276   margin-top: 1.5em;
 277 }
 278 .class, .enumeration, .function, .struct, .typedef, .union {
 279   border-bottom: solid thin #999999;
 280   margin-bottom: 0;
 281   margin-top: 2em;
 282 }
 283 .description {
 284   margin-top: 0.5em;
 285 }
 286 code, p.code, pre, ul.code li {
 287   font-family: monaco, courier, monospace;
 288   font-size: 90%;
 289 }
 290 ul.code, ul.contents, ul.subcontents {
 291   list-style-type: none;
 292   margin: 0;
 293   padding-left: 0;
 294 }
 295 ul.code li {
 296   margin: 0;
 297 }
 298 ul.contents > li {
 299   margin-top: 1em;
 300 }
 301 ul.contents li ul.code, ul.contents li ul.subcontents {
 302   padding-left: 2em;
 303 }
 304 div.body dl {
 305   margin-left: 0;
 306   margin-top: 0;
 307 }
 308 div.body dt {
 309   font-style: italic;
 310   margin-left: 0;
 311   margin-top: 0;
 312 }
 313 div.body dd {
 314   margin-bottom: 0.5em;
 315 }
 316
 317 /* This is just for the HTML files generated with the framedhelp target */
 318 div.contents {
 319   background: #e8e8e8;
 320   border: solid thin black;
 321   padding: 10px;
 322 }
 323 div.contents h1 {
 324   font-size: 110%;
 325 }
 326 div.contents h2 {
 327   font-size: 100%;
 328 }
 329 div.contents ul.contents {
 330   font-size: 80%;
 331 }
 332 div.contents ul.subcontents li {
 333   margin-left: 1em;
 334   text-indent: -1em;
 335 }
 336 --></style>
 337 </head>
 338 <body>
 339 <div class='body'>
 340 <!--
 341   "$Id$"
 342
 343   File and Directory API header for the Common UNIX Printing System (CUPS).
 344
 345   Copyright 2008-2009 by Apple Inc.
 346
 347   These coded instructions, statements, and computer programs are the
 348   property of Apple Inc. and are protected by Federal copyright
 349   law.  Distribution and use rights are outlined in the file "LICENSE.txt"
 350   which should have been included with this file.  If this file is
 351   file is missing or damaged, see the license at "http://www.cups.org/".
 352 -->
 353
 354 <h1 class='title'>File and Directory APIs</h1>
 355
 356 <div class='summary'><table summary='General Information'>
 357 <thead>
 358 <tr>
 359         <th>Headers</th>
 360         <th>cups/file.h<br>
 361         cups/dir.h</th>
 362 </tr>
 363 </thead>
 364 <tbody>
 365 <tr>
 366         <th>Library</th>
 367         <td>-lcups</td>
 368 </tr>
 369 <tr>
 370         <th>See Also</th>
 371         <td>Programming: <a href='api-overview.html' target='_top'>Introduction to CUPS Programming</a><br>
 372         Programming: <a href='api-cups.html' target='_top'>CUPS API</a></td>
 373 </tr>
 374 </tbody>
 375 </table></div>
 376 <h2 class="title">Contents</h2>
 377 <ul class="contents">
 378 <ul class="subcontents">
 379 <li><a href="#OVERVIEW">Overview</a></li>
 380 <li><a href="#FUNCTIONS">Functions</a><ul class="code">
 381 <li><a href="#cupsDirClose" title="Close a directory.">cupsDirClose</a></li>
 382 <li><a href="#cupsDirOpen" title="Open a directory.">cupsDirOpen</a></li>
 383 <li><a href="#cupsDirRead" title="Read the next directory entry.">cupsDirRead</a></li>
 384 <li><a href="#cupsDirRewind" title="Rewind to the start of the directory.">cupsDirRewind</a></li>
 385 <li><a href="#cupsFileClose" title="Close a CUPS file.">cupsFileClose</a></li>
 386 <li><a href="#cupsFileCompression" title="Return whether a file is compressed.">cupsFileCompression</a></li>
 387 <li><a href="#cupsFileEOF" title="Return the end-of-file status.">cupsFileEOF</a></li>
 388 <li><a href="#cupsFileFind" title="Find a file using the specified path.">cupsFileFind</a></li>
 389 <li><a href="#cupsFileFlush" title="Flush pending output.">cupsFileFlush</a></li>
 390 <li><a href="#cupsFileGetChar" title="Get a single character from a file.">cupsFileGetChar</a></li>
 391 <li><a href="#cupsFileGetConf" title="Get a line from a configuration file...">cupsFileGetConf</a></li>
 392 <li><a href="#cupsFileGetLine" title="Get a CR and/or LF-terminated line that may
 393 contain binary data.">cupsFileGetLine</a></li>
 394 <li><a href="#cupsFileGets" title="Get a CR and/or LF-terminated line.">cupsFileGets</a></li>
 395 <li><a href="#cupsFileLock" title="Temporarily lock access to a file.">cupsFileLock</a></li>
 396 <li><a href="#cupsFileNumber" title="Return the file descriptor associated with a CUPS file.">cupsFileNumber</a></li>
 397 <li><a href="#cupsFileOpen" title="Open a CUPS file.">cupsFileOpen</a></li>
 398 <li><a href="#cupsFileOpenFd" title="Open a CUPS file using a file descriptor.">cupsFileOpenFd</a></li>
 399 <li><a href="#cupsFilePeekChar" title="Peek at the next character from a file.">cupsFilePeekChar</a></li>
 400 <li><a href="#cupsFilePrintf" title="Write a formatted string.">cupsFilePrintf</a></li>
 401 <li><a href="#cupsFilePutChar" title="Write a character.">cupsFilePutChar</a></li>
 402 <li><a href="#cupsFilePutConf" title="Write a configuration line.">cupsFilePutConf</a></li>
 403 <li><a href="#cupsFilePuts" title="Write a string.">cupsFilePuts</a></li>
 404 <li><a href="#cupsFileRead" title="Read from a file.">cupsFileRead</a></li>
 405 <li><a href="#cupsFileRewind" title="Set the current file position to the beginning of the
 406 file.">cupsFileRewind</a></li>
 407 <li><a href="#cupsFileSeek" title="Seek in a file.">cupsFileSeek</a></li>
 408 <li><a href="#cupsFileStderr" title="Return a CUPS file associated with stderr.">cupsFileStderr</a></li>
 409 <li><a href="#cupsFileStdin" title="Return a CUPS file associated with stdin.">cupsFileStdin</a></li>
 410 <li><a href="#cupsFileStdout" title="Return a CUPS file associated with stdout.">cupsFileStdout</a></li>
 411 <li><a href="#cupsFileTell" title="Return the current file position.">cupsFileTell</a></li>
 412 <li><a href="#cupsFileUnlock" title="Unlock access to a file.">cupsFileUnlock</a></li>
 413 <li><a href="#cupsFileWrite" title="Write to a file.">cupsFileWrite</a></li>
 414 </ul></li>
 415 <li><a href="#TYPES">Data Types</a><ul class="code">
 416         <li><a href="#cups_dentry_t" title="Directory entry type">cups_dentry_t</a></li>
 417         <li><a href="#cups_dir_t" title="Directory type">cups_dir_t</a></li>
 418         <li><a href="#cups_file_t" title="CUPS file type">cups_file_t</a></li>
 419 </ul></li>
 420 <li><a href="#STRUCTURES">Structures</a><ul class="code">
 421         <li><a href="#cups_dentry_s" title="Directory entry type">cups_dentry_s</a></li>
 422 </ul></li>
 423 <!--
 424   "$Id$"
 425
 426   File and directory API introduction for the Common UNIX Printing System (CUPS).
 427
 428   Copyright 2007-2008 by Apple Inc.
 429   Copyright 1997-2005 by Easy Software Products, all rights reserved.
 430
 431   These coded instructions, statements, and computer programs are the
 432   property of Apple Inc. and are protected by Federal copyright
 433   law.  Distribution and use rights are outlined in the file "LICENSE.txt"
 434   which should have been included with this file.  If this file is
 435   file is missing or damaged, see the license at "http://www.cups.org/".
 436 -->
 437
 438 <h2 class='title'><a name="OVERVIEW">Overview</a></h2>
 439
 440 <p>The CUPS file and directory APIs provide portable interfaces
 441 for manipulating files and listing files and directories. Unlike
 442 stdio <code>FILE</code> streams, the <code>cupsFile</code> functions
 443 allow you to open more than 256 files at any given time. They
 444 also manage the platform-specific details of locking, large file
 445 support, line endings (CR, LF, or CR LF), and reading and writing
 446 files using Flate ("gzip") compression. Finally, you can also
 447 connect, read from, and write to network connections using the
 448 <code>cupsFile</code> functions.</p>
 449
 450 <p>The <code>cupsDir</code> functions manage the platform-specific
 451 details of directory access/listing and provide a convenient way
 452 to get both a list of files and the information (permissions,
 453 size, timestamp, etc.) for each of those files.</p>
 454 <h2 class="title"><a name="FUNCTIONS">Functions</a></h2>
 455 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsDirClose">cupsDirClose</a></h3>
 456 <p class="description">Close a directory.</p>
 457 <p class="code">
 458 void cupsDirClose (<br>
 459 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_dir_t">cups_dir_t</a> *dp<br>
 460 );</p>
 461 <h4 class="parameters">Parameters</h4>
 462 <dl>
 463 <dt>dp</dt>
 464 <dd class="description">Directory pointer</dd>
 465 </dl>
 466 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsDirOpen">cupsDirOpen</a></h3>
 467 <p class="description">Open a directory.</p>
 468 <p class="code">
 469 <a href="#cups_dir_t">cups_dir_t</a> *cupsDirOpen (<br>
 470 &nbsp;&nbsp;&nbsp;&nbsp;const char *directory<br>
 471 );</p>
 472 <h4 class="parameters">Parameters</h4>
 473 <dl>
 474 <dt>directory</dt>
 475 <dd class="description">Directory name</dd>
 476 </dl>
 477 <h4 class="returnvalue">Return Value</h4>
 478 <p class="description">Directory pointer or <code>NULL</code> if the directory could not be opened.</p>
 479 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsDirRead">cupsDirRead</a></h3>
 480 <p class="description">Read the next directory entry.</p>
 481 <p class="code">
 482 <a href="#cups_dentry_t">cups_dentry_t</a> *cupsDirRead (<br>
 483 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_dir_t">cups_dir_t</a> *dp<br>
 484 );</p>
 485 <h4 class="parameters">Parameters</h4>
 486 <dl>
 487 <dt>dp</dt>
 488 <dd class="description">Directory pointer</dd>
 489 </dl>
 490 <h4 class="returnvalue">Return Value</h4>
 491 <p class="description">Directory entry or <code>NULL</code> when there are no more</p>
 492 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsDirRewind">cupsDirRewind</a></h3>
 493 <p class="description">Rewind to the start of the directory.</p>
 494 <p class="code">
 495 void cupsDirRewind (<br>
 496 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_dir_t">cups_dir_t</a> *dp<br>
 497 );</p>
 498 <h4 class="parameters">Parameters</h4>
 499 <dl>
 500 <dt>dp</dt>
 501 <dd class="description">Directory pointer</dd>
 502 </dl>
 503 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsFileClose">cupsFileClose</a></h3>
 504 <p class="description">Close a CUPS file.</p>
 505 <p class="code">
 506 int cupsFileClose (<br>
 507 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp<br>
 508 );</p>
 509 <h4 class="parameters">Parameters</h4>
 510 <dl>
 511 <dt>fp</dt>
 512 <dd class="description">CUPS file</dd>
 513 </dl>
 514 <h4 class="returnvalue">Return Value</h4>
 515 <p class="description">0 on success, -1 on error</p>
 516 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsFileCompression">cupsFileCompression</a></h3>
 517 <p class="description">Return whether a file is compressed.</p>
 518 <p class="code">
 519 int cupsFileCompression (<br>
 520 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp<br>
 521 );</p>
 522 <h4 class="parameters">Parameters</h4>
 523 <dl>
 524 <dt>fp</dt>
 525 <dd class="description">CUPS file</dd>
 526 </dl>
 527 <h4 class="returnvalue">Return Value</h4>
 528 <p class="description"><code>CUPS_FILE_NONE</code> or <code>CUPS_FILE_GZIP</code></p>
 529 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsFileEOF">cupsFileEOF</a></h3>
 530 <p class="description">Return the end-of-file status.</p>
 531 <p class="code">
 532 int cupsFileEOF (<br>
 533 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp<br>
 534 );</p>
 535 <h4 class="parameters">Parameters</h4>
 536 <dl>
 537 <dt>fp</dt>
 538 <dd class="description">CUPS file</dd>
 539 </dl>
 540 <h4 class="returnvalue">Return Value</h4>
 541 <p class="description">1 on end of file, 0 otherwise</p>
 542 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsFileFind">cupsFileFind</a></h3>
 543 <p class="description">Find a file using the specified path.</p>
 544 <p class="code">
 545 const char *cupsFileFind (<br>
 546 &nbsp;&nbsp;&nbsp;&nbsp;const char *filename,<br>
 547 &nbsp;&nbsp;&nbsp;&nbsp;const char *path,<br>
 548 &nbsp;&nbsp;&nbsp;&nbsp;int executable,<br>
 549 &nbsp;&nbsp;&nbsp;&nbsp;char *buffer,<br>
 550 &nbsp;&nbsp;&nbsp;&nbsp;int bufsize<br>
 551 );</p>
 552 <h4 class="parameters">Parameters</h4>
 553 <dl>
 554 <dt>filename</dt>
 555 <dd class="description">File to find</dd>
 556 <dt>path</dt>
 557 <dd class="description">Colon/semicolon-separated path</dd>
 558 <dt>executable</dt>
 559 <dd class="description">1 = executable files, 0 = any file/dir</dd>
 560 <dt>buffer</dt>
 561 <dd class="description">Filename buffer</dd>
 562 <dt>bufsize</dt>
 563 <dd class="description">Size of filename buffer</dd>
 564 </dl>
 565 <h4 class="returnvalue">Return Value</h4>
 566 <p class="description">Full path to file or <code>NULL</code> if not found</p>
 567 <h4 class="discussion">Discussion</h4>
 568 <p class="discussion">This function allows the paths in the path string to be separated by
 569 colons (UNIX standard) or semicolons (Windows standard) and stores the
 570 result in the buffer supplied.  If the file cannot be found in any of
 571 the supplied paths, <code>NULL</code> is returned. A <code>NULL</code> path only
 572 matches the current directory.
 573
 574 </p>
 575 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsFileFlush">cupsFileFlush</a></h3>
 576 <p class="description">Flush pending output.</p>
 577 <p class="code">
 578 int cupsFileFlush (<br>
 579 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp<br>
 580 );</p>
 581 <h4 class="parameters">Parameters</h4>
 582 <dl>
 583 <dt>fp</dt>
 584 <dd class="description">CUPS file</dd>
 585 </dl>
 586 <h4 class="returnvalue">Return Value</h4>
 587 <p class="description">0 on success, -1 on error</p>
 588 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsFileGetChar">cupsFileGetChar</a></h3>
 589 <p class="description">Get a single character from a file.</p>
 590 <p class="code">
 591 int cupsFileGetChar (<br>
 592 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp<br>
 593 );</p>
 594 <h4 class="parameters">Parameters</h4>
 595 <dl>
 596 <dt>fp</dt>
 597 <dd class="description">CUPS file</dd>
 598 </dl>
 599 <h4 class="returnvalue">Return Value</h4>
 600 <p class="description">Character or -1 on end of file</p>
 601 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsFileGetConf">cupsFileGetConf</a></h3>
 602 <p class="description">Get a line from a configuration file...</p>
 603 <p class="code">
 604 char *cupsFileGetConf (<br>
 605 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp,<br>
 606 &nbsp;&nbsp;&nbsp;&nbsp;char *buf,<br>
 607 &nbsp;&nbsp;&nbsp;&nbsp;size_t buflen,<br>
 608 &nbsp;&nbsp;&nbsp;&nbsp;char **value,<br>
 609 &nbsp;&nbsp;&nbsp;&nbsp;int *linenum<br>
 610 );</p>
 611 <h4 class="parameters">Parameters</h4>
 612 <dl>
 613 <dt>fp</dt>
 614 <dd class="description">CUPS file</dd>
 615 <dt>buf</dt>
 616 <dd class="description">String buffer</dd>
 617 <dt>buflen</dt>
 618 <dd class="description">Size of string buffer</dd>
 619 <dt>value</dt>
 620 <dd class="description">Pointer to value</dd>
 621 <dt>linenum</dt>
 622 <dd class="description">Current line number</dd>
 623 </dl>
 624 <h4 class="returnvalue">Return Value</h4>
 625 <p class="description">Line read or <code>NULL</code> on end of file or error</p>
 626 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsFileGetLine">cupsFileGetLine</a></h3>
 627 <p class="description">Get a CR and/or LF-terminated line that may
 628 contain binary data.</p>
 629 <p class="code">
 630 size_t cupsFileGetLine (<br>
 631 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp,<br>
 632 &nbsp;&nbsp;&nbsp;&nbsp;char *buf,<br>
 633 &nbsp;&nbsp;&nbsp;&nbsp;size_t buflen<br>
 634 );</p>
 635 <h4 class="parameters">Parameters</h4>
 636 <dl>
 637 <dt>fp</dt>
 638 <dd class="description">File to read from</dd>
 639 <dt>buf</dt>
 640 <dd class="description">Buffer</dd>
 641 <dt>buflen</dt>
 642 <dd class="description">Size of buffer</dd>
 643 </dl>
 644 <h4 class="returnvalue">Return Value</h4>
 645 <p class="description">Number of bytes on line or 0 on end of file</p>
 646 <h4 class="discussion">Discussion</h4>
 647 <p class="discussion">This function differs from <a href="#cupsFileGets"><code>cupsFileGets</code></a> in that the trailing CR
 648 and LF are preserved, as is any binary data on the line. The buffer is
 649 nul-terminated, however you should use the returned length to determine
 650 the number of bytes on the line.
 651
 652 </p>
 653 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsFileGets">cupsFileGets</a></h3>
 654 <p class="description">Get a CR and/or LF-terminated line.</p>
 655 <p class="code">
 656 char *cupsFileGets (<br>
 657 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp,<br>
 658 &nbsp;&nbsp;&nbsp;&nbsp;char *buf,<br>
 659 &nbsp;&nbsp;&nbsp;&nbsp;size_t buflen<br>
 660 );</p>
 661 <h4 class="parameters">Parameters</h4>
 662 <dl>
 663 <dt>fp</dt>
 664 <dd class="description">CUPS file</dd>
 665 <dt>buf</dt>
 666 <dd class="description">String buffer</dd>
 667 <dt>buflen</dt>
 668 <dd class="description">Size of string buffer</dd>
 669 </dl>
 670 <h4 class="returnvalue">Return Value</h4>
 671 <p class="description">Line read or <code>NULL</code> on end of file or error</p>
 672 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsFileLock">cupsFileLock</a></h3>
 673 <p class="description">Temporarily lock access to a file.</p>
 674 <p class="code">
 675 int cupsFileLock (<br>
 676 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp,<br>
 677 &nbsp;&nbsp;&nbsp;&nbsp;int block<br>
 678 );</p>
 679 <h4 class="parameters">Parameters</h4>
 680 <dl>
 681 <dt>fp</dt>
 682 <dd class="description">CUPS file</dd>
 683 <dt>block</dt>
 684 <dd class="description">1 to wait for the lock, 0 to fail right away</dd>
 685 </dl>
 686 <h4 class="returnvalue">Return Value</h4>
 687 <p class="description">0 on success, -1 on error</p>
 688 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsFileNumber">cupsFileNumber</a></h3>
 689 <p class="description">Return the file descriptor associated with a CUPS file.</p>
 690 <p class="code">
 691 int cupsFileNumber (<br>
 692 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp<br>
 693 );</p>
 694 <h4 class="parameters">Parameters</h4>
 695 <dl>
 696 <dt>fp</dt>
 697 <dd class="description">CUPS file</dd>
 698 </dl>
 699 <h4 class="returnvalue">Return Value</h4>
 700 <p class="description">File descriptor</p>
 701 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsFileOpen">cupsFileOpen</a></h3>
 702 <p class="description">Open a CUPS file.</p>
 703 <p class="code">
 704 <a href="#cups_file_t">cups_file_t</a> *cupsFileOpen (<br>
 705 &nbsp;&nbsp;&nbsp;&nbsp;const char *filename,<br>
 706 &nbsp;&nbsp;&nbsp;&nbsp;const char *mode<br>
 707 );</p>
 708 <h4 class="parameters">Parameters</h4>
 709 <dl>
 710 <dt>filename</dt>
 711 <dd class="description">Name of file</dd>
 712 <dt>mode</dt>
 713 <dd class="description">Open mode</dd>
 714 </dl>
 715 <h4 class="returnvalue">Return Value</h4>
 716 <p class="description">CUPS file or <code>NULL</code> if the file or socket cannot be opened</p>
 717 <h4 class="discussion">Discussion</h4>
 718 <p class="discussion">The &quot;mode&quot; parameter can be &quot;r&quot; to read, &quot;w&quot; to write, overwriting any
 719 existing file, &quot;a&quot; to append to an existing file or create a new file,
 720 or &quot;s&quot; to open a socket connection.<br>
 721 <br>
 722 When opening for writing (&quot;w&quot;), an optional number from 1 to 9 can be
 723 supplied which enables Flate compression of the file.  Compression is
 724 not supported for the &quot;a&quot; (append) mode.<br>
 725 <br>
 726 When opening a socket connection, the filename is a string of the form
 727 &quot;address:port&quot; or &quot;hostname:port&quot;. The socket will make an IPv4 or IPv6
 728 connection as needed, generally preferring IPv6 connections when there is
 729 a choice.
 730
 731 </p>
 732 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsFileOpenFd">cupsFileOpenFd</a></h3>
 733 <p class="description">Open a CUPS file using a file descriptor.</p>
 734 <p class="code">
 735 <a href="#cups_file_t">cups_file_t</a> *cupsFileOpenFd (<br>
 736 &nbsp;&nbsp;&nbsp;&nbsp;int fd,<br>
 737 &nbsp;&nbsp;&nbsp;&nbsp;const char *mode<br>
 738 );</p>
 739 <h4 class="parameters">Parameters</h4>
 740 <dl>
 741 <dt>fd</dt>
 742 <dd class="description">File descriptor</dd>
 743 <dt>mode</dt>
 744 <dd class="description">Open mode</dd>
 745 </dl>
 746 <h4 class="returnvalue">Return Value</h4>
 747 <p class="description">CUPS file or <code>NULL</code> if the file could not be opened</p>
 748 <h4 class="discussion">Discussion</h4>
 749 <p class="discussion">The &quot;mode&quot; parameter can be &quot;r&quot; to read, &quot;w&quot; to write, &quot;a&quot; to append,
 750 or &quot;s&quot; to treat the file descriptor as a bidirectional socket connection.<br>
 751 <br>
 752 When opening for writing (&quot;w&quot;), an optional number from 1 to 9 can be
 753 supplied which enables Flate compression of the file.  Compression is
 754 not supported for the &quot;a&quot; (append) mode.
 755
 756 </p>
 757 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsFilePeekChar">cupsFilePeekChar</a></h3>
 758 <p class="description">Peek at the next character from a file.</p>
 759 <p class="code">
 760 int cupsFilePeekChar (<br>
 761 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp<br>
 762 );</p>
 763 <h4 class="parameters">Parameters</h4>
 764 <dl>
 765 <dt>fp</dt>
 766 <dd class="description">CUPS file</dd>
 767 </dl>
 768 <h4 class="returnvalue">Return Value</h4>
 769 <p class="description">Character or -1 on end of file</p>
 770 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsFilePrintf">cupsFilePrintf</a></h3>
 771 <p class="description">Write a formatted string.</p>
 772 <p class="code">
 773 int cupsFilePrintf (<br>
 774 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp,<br>
 775 &nbsp;&nbsp;&nbsp;&nbsp;const char *format,<br>
 776 &nbsp;&nbsp;&nbsp;&nbsp;...<br>
 777 );</p>
 778 <h4 class="parameters">Parameters</h4>
 779 <dl>
 780 <dt>fp</dt>
 781 <dd class="description">CUPS file</dd>
 782 <dt>format</dt>
 783 <dd class="description">Printf-style format string</dd>
 784 <dt>...</dt>
 785 <dd class="description">Additional args as necessary</dd>
 786 </dl>
 787 <h4 class="returnvalue">Return Value</h4>
 788 <p class="description">Number of bytes written or -1 on error</p>
 789 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsFilePutChar">cupsFilePutChar</a></h3>
 790 <p class="description">Write a character.</p>
 791 <p class="code">
 792 int cupsFilePutChar (<br>
 793 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp,<br>
 794 &nbsp;&nbsp;&nbsp;&nbsp;int c<br>
 795 );</p>
 796 <h4 class="parameters">Parameters</h4>
 797 <dl>
 798 <dt>fp</dt>
 799 <dd class="description">CUPS file</dd>
 800 <dt>c</dt>
 801 <dd class="description">Character to write</dd>
 802 </dl>
 803 <h4 class="returnvalue">Return Value</h4>
 804 <p class="description">0 on success, -1 on error</p>
 805 <h3 class="function"><span class="info">&nbsp;CUPS 1.4/Mac OS X 10.6&nbsp;</span><a name="cupsFilePutConf">cupsFilePutConf</a></h3>
 806 <p class="description">Write a configuration line.</p>
 807 <p class="code">
 808 ssize_t cupsFilePutConf (<br>
 809 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp,<br>
 810 &nbsp;&nbsp;&nbsp;&nbsp;const char *directive,<br>
 811 &nbsp;&nbsp;&nbsp;&nbsp;const char *value<br>
 812 );</p>
 813 <h4 class="parameters">Parameters</h4>
 814 <dl>
 815 <dt>fp</dt>
 816 <dd class="description">CUPS file</dd>
 817 <dt>directive</dt>
 818 <dd class="description">Directive</dd>
 819 <dt>value</dt>
 820 <dd class="description">Value</dd>
 821 </dl>
 822 <h4 class="returnvalue">Return Value</h4>
 823 <p class="description">Number of bytes written or -1 on error</p>
 824 <h4 class="discussion">Discussion</h4>
 825 <p class="discussion">This function handles any comment escaping of the value.
 826
 827 </p>
 828 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsFilePuts">cupsFilePuts</a></h3>
 829 <p class="description">Write a string.</p>
 830 <p class="code">
 831 int cupsFilePuts (<br>
 832 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp,<br>
 833 &nbsp;&nbsp;&nbsp;&nbsp;const char *s<br>
 834 );</p>
 835 <h4 class="parameters">Parameters</h4>
 836 <dl>
 837 <dt>fp</dt>
 838 <dd class="description">CUPS file</dd>
 839 <dt>s</dt>
 840 <dd class="description">String to write</dd>
 841 </dl>
 842 <h4 class="returnvalue">Return Value</h4>
 843 <p class="description">Number of bytes written or -1 on error</p>
 844 <h4 class="discussion">Discussion</h4>
 845 <p class="discussion">Like the <code>fputs</code> function, no newline is appended to the string.
 846
 847 </p>
 848 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsFileRead">cupsFileRead</a></h3>
 849 <p class="description">Read from a file.</p>
 850 <p class="code">
 851 ssize_t cupsFileRead (<br>
 852 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp,<br>
 853 &nbsp;&nbsp;&nbsp;&nbsp;char *buf,<br>
 854 &nbsp;&nbsp;&nbsp;&nbsp;size_t bytes<br>
 855 );</p>
 856 <h4 class="parameters">Parameters</h4>
 857 <dl>
 858 <dt>fp</dt>
 859 <dd class="description">CUPS file</dd>
 860 <dt>buf</dt>
 861 <dd class="description">Buffer</dd>
 862 <dt>bytes</dt>
 863 <dd class="description">Number of bytes to read</dd>
 864 </dl>
 865 <h4 class="returnvalue">Return Value</h4>
 866 <p class="description">Number of bytes read or -1 on error</p>
 867 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsFileRewind">cupsFileRewind</a></h3>
 868 <p class="description">Set the current file position to the beginning of the
 869 file.</p>
 870 <p class="code">
 871 off_t cupsFileRewind (<br>
 872 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp<br>
 873 );</p>
 874 <h4 class="parameters">Parameters</h4>
 875 <dl>
 876 <dt>fp</dt>
 877 <dd class="description">CUPS file</dd>
 878 </dl>
 879 <h4 class="returnvalue">Return Value</h4>
 880 <p class="description">New file position or -1 on error</p>
 881 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsFileSeek">cupsFileSeek</a></h3>
 882 <p class="description">Seek in a file.</p>
 883 <p class="code">
 884 off_t cupsFileSeek (<br>
 885 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp,<br>
 886 &nbsp;&nbsp;&nbsp;&nbsp;off_t pos<br>
 887 );</p>
 888 <h4 class="parameters">Parameters</h4>
 889 <dl>
 890 <dt>fp</dt>
 891 <dd class="description">CUPS file</dd>
 892 <dt>pos</dt>
 893 <dd class="description">Position in file</dd>
 894 </dl>
 895 <h4 class="returnvalue">Return Value</h4>
 896 <p class="description">New file position or -1 on error</p>
 897 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsFileStderr">cupsFileStderr</a></h3>
 898 <p class="description">Return a CUPS file associated with stderr.</p>
 899 <p class="code">
 900 <a href="#cups_file_t">cups_file_t</a> *cupsFileStderr (void);</p>
 901 <h4 class="returnvalue">Return Value</h4>
 902 <p class="description">CUPS file</p>
 903 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsFileStdin">cupsFileStdin</a></h3>
 904 <p class="description">Return a CUPS file associated with stdin.</p>
 905 <p class="code">
 906 <a href="#cups_file_t">cups_file_t</a> *cupsFileStdin (void);</p>
 907 <h4 class="returnvalue">Return Value</h4>
 908 <p class="description">CUPS file</p>
 909 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsFileStdout">cupsFileStdout</a></h3>
 910 <p class="description">Return a CUPS file associated with stdout.</p>
 911 <p class="code">
 912 <a href="#cups_file_t">cups_file_t</a> *cupsFileStdout (void);</p>
 913 <h4 class="returnvalue">Return Value</h4>
 914 <p class="description">CUPS file</p>
 915 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsFileTell">cupsFileTell</a></h3>
 916 <p class="description">Return the current file position.</p>
 917 <p class="code">
 918 off_t cupsFileTell (<br>
 919 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp<br>
 920 );</p>
 921 <h4 class="parameters">Parameters</h4>
 922 <dl>
 923 <dt>fp</dt>
 924 <dd class="description">CUPS file</dd>
 925 </dl>
 926 <h4 class="returnvalue">Return Value</h4>
 927 <p class="description">File position</p>
 928 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsFileUnlock">cupsFileUnlock</a></h3>
 929 <p class="description">Unlock access to a file.</p>
 930 <p class="code">
 931 int cupsFileUnlock (<br>
 932 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp<br>
 933 );</p>
 934 <h4 class="parameters">Parameters</h4>
 935 <dl>
 936 <dt>fp</dt>
 937 <dd class="description">CUPS file</dd>
 938 </dl>
 939 <h4 class="returnvalue">Return Value</h4>
 940 <p class="description">0 on success, -1 on error</p>
 941 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/Mac OS X 10.5&nbsp;</span><a name="cupsFileWrite">cupsFileWrite</a></h3>
 942 <p class="description">Write to a file.</p>
 943 <p class="code">
 944 ssize_t cupsFileWrite (<br>
 945 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp,<br>
 946 &nbsp;&nbsp;&nbsp;&nbsp;const char *buf,<br>
 947 &nbsp;&nbsp;&nbsp;&nbsp;size_t bytes<br>
 948 );</p>
 949 <h4 class="parameters">Parameters</h4>
 950 <dl>
 951 <dt>fp</dt>
 952 <dd class="description">CUPS file</dd>
 953 <dt>buf</dt>
 954 <dd class="description">Buffer</dd>
 955 <dt>bytes</dt>
 956 <dd class="description">Number of bytes to write</dd>
 957 </dl>
 958 <h4 class="returnvalue">Return Value</h4>
 959 <p class="description">Number of bytes written or -1 on error</p>
 960 <h2 class="title"><a name="TYPES">Data Types</a></h2>
 961 <h3 class="typedef"><a name="cups_dentry_t">cups_dentry_t</a></h3>
 962 <p class="description">Directory entry type</p>
 963 <p class="code">
 964 typedef struct <a href="#cups_dentry_s">cups_dentry_s</a> cups_dentry_t;
 965 </p>
 966 <h3 class="typedef"><a name="cups_dir_t">cups_dir_t</a></h3>
 967 <p class="description">Directory type</p>
 968 <p class="code">
 969 typedef struct _cups_dir_s cups_dir_t;
 970 </p>
 971 <h3 class="typedef"><a name="cups_file_t">cups_file_t</a></h3>
 972 <p class="description">CUPS file type</p>
 973 <p class="code">
 974 typedef struct _cups_file_s cups_file_t;
 975 </p>
 976 <h2 class="title"><a name="STRUCTURES">Structures</a></h2>
 977 <h3 class="struct"><a name="cups_dentry_s">cups_dentry_s</a></h3>
 978 <p class="description">Directory entry type</p>
 979 <p class="code">struct cups_dentry_s {<br>
 980 &nbsp;&nbsp;&nbsp;&nbsp;struct stat fileinfo;<br>
 981 &nbsp;&nbsp;&nbsp;&nbsp;char filename[260];<br>
 982 };</p>
 983 <h4 class="members">Members</h4>
 984 <dl>
 985 <dt>fileinfo </dt>
 986 <dd class="description">File information</dd>
 987 <dt>filename[260] </dt>
 988 <dd class="description">File name</dd>
 989 </dl>
 990 </div>
 991 </body>
 992 </html>