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="#cupsFilePutConf" title="Write a configuration line.">cupsFilePutConf</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;), an optional number from 1 to 9 can be
 639 supplied which enables Flate compression of the file.  Compression is
 640 not supported for the &quot;a&quot; (append) mode.<br>
 641 <br>
 642 When opening a socket connection, the filename is a string of the form
 643 &quot;address:port&quot; or &quot;hostname:port&quot;. The socket will make an IPv4 or IPv6
 644 connection as needed, generally preferring IPv6 connections when there is
 645 a choice.
 646
 647 </p>
 648 <h3 class="function"><span class="info">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsFileOpenFd">cupsFileOpenFd</a></h3>
 649 <p class="description">Open a CUPS file using a file descriptor.</p>
 650 <p class="code">
 651 <a href="#cups_file_t">cups_file_t</a> *cupsFileOpenFd (<br>
 652 &nbsp;&nbsp;&nbsp;&nbsp;int fd,<br>
 653 &nbsp;&nbsp;&nbsp;&nbsp;const char *mode<br>
 654 );</p>
 655 <h4 class="parameters">Parameters</h4>
 656 <dl>
 657 <dt>fd</dt>
 658 <dd class="description">File descriptor</dd>
 659 <dt>mode</dt>
 660 <dd class="description">Open mode</dd>
 661 </dl>
 662 <h4 class="returnvalue">Return Value</h4>
 663 <p class="description">CUPS file or <code>NULL</code> if the file could not be opened</p>
 664 <h4 class="discussion">Discussion</h4>
 665 <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,
 666 or &quot;s&quot; to treat the file descriptor as a bidirectional socket connection.<br>
 667 <br>
 668 When opening for writing (&quot;w&quot;), an optional number from 1 to 9 can be
 669 supplied which enables Flate compression of the file.  Compression is
 670 not supported for the &quot;a&quot; (append) mode.
 671
 672 </p>
 673 <h3 class="function"><span class="info">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsFilePeekChar">cupsFilePeekChar</a></h3>
 674 <p class="description">Peek at the next character from a file.</p>
 675 <p class="code">
 676 int cupsFilePeekChar (<br>
 677 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp<br>
 678 );</p>
 679 <h4 class="parameters">Parameters</h4>
 680 <dl>
 681 <dt>fp</dt>
 682 <dd class="description">CUPS file</dd>
 683 </dl>
 684 <h4 class="returnvalue">Return Value</h4>
 685 <p class="description">Character or -1 on end of file</p>
 686 <h3 class="function"><span class="info">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsFilePrintf">cupsFilePrintf</a></h3>
 687 <p class="description">Write a formatted string.</p>
 688 <p class="code">
 689 int cupsFilePrintf (<br>
 690 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp,<br>
 691 &nbsp;&nbsp;&nbsp;&nbsp;const char *format,<br>
 692 &nbsp;&nbsp;&nbsp;&nbsp;...<br>
 693 );</p>
 694 <h4 class="parameters">Parameters</h4>
 695 <dl>
 696 <dt>fp</dt>
 697 <dd class="description">CUPS file</dd>
 698 <dt>format</dt>
 699 <dd class="description">Printf-style format string</dd>
 700 <dt>...</dt>
 701 <dd class="description">Additional args as necessary</dd>
 702 </dl>
 703 <h4 class="returnvalue">Return Value</h4>
 704 <p class="description">Number of bytes written or -1 on error</p>
 705 <h3 class="function"><span class="info">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsFilePutChar">cupsFilePutChar</a></h3>
 706 <p class="description">Write a character.</p>
 707 <p class="code">
 708 int cupsFilePutChar (<br>
 709 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp,<br>
 710 &nbsp;&nbsp;&nbsp;&nbsp;int c<br>
 711 );</p>
 712 <h4 class="parameters">Parameters</h4>
 713 <dl>
 714 <dt>fp</dt>
 715 <dd class="description">CUPS file</dd>
 716 <dt>c</dt>
 717 <dd class="description">Character to write</dd>
 718 </dl>
 719 <h4 class="returnvalue">Return Value</h4>
 720 <p class="description">0 on success, -1 on error</p>
 721 <h3 class="function"><span class="info">&nbsp;CUPS 1.4&nbsp;</span><a name="cupsFilePutConf">cupsFilePutConf</a></h3>
 722 <p class="description">Write a configuration line.</p>
 723 <p class="code">
 724 ssize_t cupsFilePutConf (<br>
 725 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp,<br>
 726 &nbsp;&nbsp;&nbsp;&nbsp;const char *directive,<br>
 727 &nbsp;&nbsp;&nbsp;&nbsp;const char *value<br>
 728 );</p>
 729 <h4 class="parameters">Parameters</h4>
 730 <dl>
 731 <dt>fp</dt>
 732 <dd class="description">CUPS file</dd>
 733 <dt>directive</dt>
 734 <dd class="description">Directive</dd>
 735 <dt>value</dt>
 736 <dd class="description">Value</dd>
 737 </dl>
 738 <h4 class="returnvalue">Return Value</h4>
 739 <p class="description">Number of bytes written or -1 on error</p>
 740 <h4 class="discussion">Discussion</h4>
 741 <p class="discussion">This function handles any comment escaping of the value.
 742
 743 </p>
 744 <h3 class="function"><span class="info">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsFilePuts">cupsFilePuts</a></h3>
 745 <p class="description">Write a string.</p>
 746 <p class="code">
 747 int cupsFilePuts (<br>
 748 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp,<br>
 749 &nbsp;&nbsp;&nbsp;&nbsp;const char *s<br>
 750 );</p>
 751 <h4 class="parameters">Parameters</h4>
 752 <dl>
 753 <dt>fp</dt>
 754 <dd class="description">CUPS file</dd>
 755 <dt>s</dt>
 756 <dd class="description">String to write</dd>
 757 </dl>
 758 <h4 class="returnvalue">Return Value</h4>
 759 <p class="description">Number of bytes written or -1 on error</p>
 760 <h4 class="discussion">Discussion</h4>
 761 <p class="discussion">Like the <code>fputs</code> function, no newline is appended to the string.
 762
 763 </p>
 764 <h3 class="function"><span class="info">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsFileRead">cupsFileRead</a></h3>
 765 <p class="description">Read from a file.</p>
 766 <p class="code">
 767 ssize_t cupsFileRead (<br>
 768 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp,<br>
 769 &nbsp;&nbsp;&nbsp;&nbsp;char *buf,<br>
 770 &nbsp;&nbsp;&nbsp;&nbsp;size_t bytes<br>
 771 );</p>
 772 <h4 class="parameters">Parameters</h4>
 773 <dl>
 774 <dt>fp</dt>
 775 <dd class="description">CUPS file</dd>
 776 <dt>buf</dt>
 777 <dd class="description">Buffer</dd>
 778 <dt>bytes</dt>
 779 <dd class="description">Number of bytes to read</dd>
 780 </dl>
 781 <h4 class="returnvalue">Return Value</h4>
 782 <p class="description">Number of bytes read or -1 on error</p>
 783 <h3 class="function"><span class="info">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsFileRewind">cupsFileRewind</a></h3>
 784 <p class="description">Set the current file position to the beginning of the
 785 file.</p>
 786 <p class="code">
 787 off_t cupsFileRewind (<br>
 788 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp<br>
 789 );</p>
 790 <h4 class="parameters">Parameters</h4>
 791 <dl>
 792 <dt>fp</dt>
 793 <dd class="description">CUPS file</dd>
 794 </dl>
 795 <h4 class="returnvalue">Return Value</h4>
 796 <p class="description">New file position or -1 on error</p>
 797 <h3 class="function"><span class="info">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsFileSeek">cupsFileSeek</a></h3>
 798 <p class="description">Seek in a file.</p>
 799 <p class="code">
 800 off_t cupsFileSeek (<br>
 801 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp,<br>
 802 &nbsp;&nbsp;&nbsp;&nbsp;off_t pos<br>
 803 );</p>
 804 <h4 class="parameters">Parameters</h4>
 805 <dl>
 806 <dt>fp</dt>
 807 <dd class="description">CUPS file</dd>
 808 <dt>pos</dt>
 809 <dd class="description">Position in file</dd>
 810 </dl>
 811 <h4 class="returnvalue">Return Value</h4>
 812 <p class="description">New file position or -1 on error</p>
 813 <h3 class="function"><span class="info">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsFileStderr">cupsFileStderr</a></h3>
 814 <p class="description">Return a CUPS file associated with stderr.</p>
 815 <p class="code">
 816 <a href="#cups_file_t">cups_file_t</a> *cupsFileStderr (void);</p>
 817 <h4 class="returnvalue">Return Value</h4>
 818 <p class="description">CUPS file</p>
 819 <h3 class="function"><span class="info">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsFileStdin">cupsFileStdin</a></h3>
 820 <p class="description">Return a CUPS file associated with stdin.</p>
 821 <p class="code">
 822 <a href="#cups_file_t">cups_file_t</a> *cupsFileStdin (void);</p>
 823 <h4 class="returnvalue">Return Value</h4>
 824 <p class="description">CUPS file</p>
 825 <h3 class="function"><span class="info">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsFileStdout">cupsFileStdout</a></h3>
 826 <p class="description">Return a CUPS file associated with stdout.</p>
 827 <p class="code">
 828 <a href="#cups_file_t">cups_file_t</a> *cupsFileStdout (void);</p>
 829 <h4 class="returnvalue">Return Value</h4>
 830 <p class="description">CUPS file</p>
 831 <h3 class="function"><span class="info">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsFileTell">cupsFileTell</a></h3>
 832 <p class="description">Return the current file position.</p>
 833 <p class="code">
 834 off_t cupsFileTell (<br>
 835 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp<br>
 836 );</p>
 837 <h4 class="parameters">Parameters</h4>
 838 <dl>
 839 <dt>fp</dt>
 840 <dd class="description">CUPS file</dd>
 841 </dl>
 842 <h4 class="returnvalue">Return Value</h4>
 843 <p class="description">File position</p>
 844 <h3 class="function"><span class="info">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsFileUnlock">cupsFileUnlock</a></h3>
 845 <p class="description">Unlock access to a file.</p>
 846 <p class="code">
 847 int cupsFileUnlock (<br>
 848 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp<br>
 849 );</p>
 850 <h4 class="parameters">Parameters</h4>
 851 <dl>
 852 <dt>fp</dt>
 853 <dd class="description">CUPS file</dd>
 854 </dl>
 855 <h4 class="returnvalue">Return Value</h4>
 856 <p class="description">0 on success, -1 on error</p>
 857 <h3 class="function"><span class="info">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsFileWrite">cupsFileWrite</a></h3>
 858 <p class="description">Write to a file.</p>
 859 <p class="code">
 860 ssize_t cupsFileWrite (<br>
 861 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp,<br>
 862 &nbsp;&nbsp;&nbsp;&nbsp;const char *buf,<br>
 863 &nbsp;&nbsp;&nbsp;&nbsp;size_t bytes<br>
 864 );</p>
 865 <h4 class="parameters">Parameters</h4>
 866 <dl>
 867 <dt>fp</dt>
 868 <dd class="description">CUPS file</dd>
 869 <dt>buf</dt>
 870 <dd class="description">Buffer</dd>
 871 <dt>bytes</dt>
 872 <dd class="description">Number of bytes to write</dd>
 873 </dl>
 874 <h4 class="returnvalue">Return Value</h4>
 875 <p class="description">Number of bytes written or -1 on error</p>
 876 <h2 class="title"><a name="TYPES">Data Types</a></h2>
 877 <h3 class="typedef"><a name="cups_dentry_t">cups_dentry_t</a></h3>
 878 <p class="description">Directory entry type</p>
 879 <p class="code">
 880 typedef struct <a href="#cups_dentry_s">cups_dentry_s</a> cups_dentry_t;
 881 </p>
 882 <h3 class="typedef"><a name="cups_dir_t">cups_dir_t</a></h3>
 883 <p class="description">Directory type</p>
 884 <p class="code">
 885 typedef struct _cups_dir_s cups_dir_t;
 886 </p>
 887 <h3 class="typedef"><a name="cups_file_t">cups_file_t</a></h3>
 888 <p class="description">CUPS file type</p>
 889 <p class="code">
 890 typedef struct _cups_file_s cups_file_t;
 891 </p>
 892 <h2 class="title"><a name="STRUCTURES">Structures</a></h2>
 893 <h3 class="struct"><a name="cups_dentry_s">cups_dentry_s</a></h3>
 894 <p class="description">Directory entry type</p>
 895 <p class="code">struct cups_dentry_s {<br>
 896 &nbsp;&nbsp;&nbsp;&nbsp;struct stat fileinfo;<br>
 897 &nbsp;&nbsp;&nbsp;&nbsp;char filename[260];<br>
 898 };</p>
 899 <h4 class="members">Members</h4>
 900 <dl>
 901 <dt>fileinfo </dt>
 902 <dd class="description">File information</dd>
 903 <dt>filename[260] </dt>
 904 <dd class="description">File name</dd>
 905 </dl>
 906 </div>
 907 </body>
 908 </html>