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