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