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