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