doc/help/api-filedir.html

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