doc/help/api-filedir.html

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