doc/help/api-filedir.html

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