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