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.3'>
   8         <style type='text/css'><!--
   9         h1, h2, h3, p { font-family: sans-serif; text-align: justify; }
  10         tt, pre a:link, pre a:visited, tt a:link, tt a:visited { font-weight: bold; color: #7f0000; }
  11         pre { font-weight: bold; color: #7f0000; margin-left: 2em; }
  12         span.info { background: #000000; border: solid thin #000000; color: #ffffff; font-size: 80%; font-style: italic; font-weight: bold; white-space: nowrap; }
  13         h3 span.info { float: right; font-size: 100%; }
  14         h1.title, h2.title, h3.title { border-bottom: solid 2px #000000; }
  15         --></style>
  16 </head>
  17 <body>
  18 <!--
  19   "$Id: api-filedir.html 177 2006-06-21 00:20:03Z jlovell $"
  20
  21   File and directory API introduction for the Common UNIX Printing System (CUPS).
  22
  23   Copyright 1997-2005 by Easy Software Products.
  24
  25   These coded instructions, statements, and computer programs are the
  26   property of Easy Software Products and are protected by Federal
  27   copyright law.  Distribution and use rights are outlined in the file
  28   "LICENSE.txt" which should have been included with this file.  If this
  29   file is missing or damaged please contact Easy Software Products
  30   at:
  31
  32       Attn: CUPS Licensing Information
  33       Easy Software Products
  34       44141 Airport View Drive, Suite 204
  35       Hollywood, Maryland 20636 USA
  36
  37       Voice: (301) 373-9600
  38       EMail: cups-info@cups.org
  39         WWW: http://www.cups.org
  40 -->
  41
  42 <h2 class='title'>Introduction</h2>
  43
  44 <p>The CUPS file and directory APIs provide portable interfaces
  45 for manipulating files and listing files and directories. Unlike
  46 stdio <tt>FILE</tt> streams, the <tt>cupsFile</tt> functions
  47 allow you to open more than 256 files at any given time. They
  48 also manage the platform-specific details of locking, large file
  49 support, line endings (CR, LF, or CR LF), and reading and writing
  50 files using Flate ("gzip") compression. Finally, you can also
  51 connect, read from, and write to network connections using the
  52 <tt>cupsFile</tt> functions.</p>
  53
  54 <p>The <tt>cupsDir</tt> functions manage the platform-specific
  55 details of directory access/listing and provide a convenient way
  56 to get both a list of files and the information (permissions,
  57 size, timestamp, etc.) for each of those files.</p>
  58
  59 <p>The CUPS scheduler (<tt>cupsd</tt>), <tt>mailto</tt> notifier,
  60 and many of the CUPS API functions use these functions for
  61 everything except console (stdin, stdout, stderr) I/O.</p>
  62
  63 <h2 class='title'>General Usage</h2>
  64
  65 <p>The <var>&lt;cups/dir.h&gt;</var> and
  66 <var>&lt;cups/file.h&gt;</var> header files must be included to
  67 use the <tt>cupsDir</tt> and <tt>cupsFile</tt> functions,
  68 respectively.</p>
  69
  70 <p>Programs using these functions must be linked to the CUPS
  71 library: <var>libcups.a</var>, <var>libcups.so.2</var>,
  72 <var>libcups.2.dylib</var>, <var>libcups_s.a</var>, or
  73 <var>libcups2.lib</var> depending on the platform. The following
  74 command compiles <var>myprogram.c</var> using GCC and the CUPS
  75 library:</p>
  76
  77 <pre class='command'>
  78 <kbd>gcc -o myprogram myprogram.c -lcups</kbd>
  79 </pre>
  80
  81 <h2 class='title'>Compatibility</h2>
  82
  83 <p>All of these functions require CUPS 1.2 or higher.</p>
  84 <h2 class='title'>Contents</h2>
  85 <ul>
  86         <li><a href='#FUNCTIONS'>Functions</a></li>
  87         <li><a href='#STRUCTURES'>Structures</a></li>
  88         <li><a href='#TYPES'>Types</a></li>
  89 </ul>
  90 <!-- NEW PAGE -->
  91 <h2 class='title'><a name='FUNCTIONS'>Functions</a></h2>
  92 <ul>
  93         <li><a href='#cupsDirClose'><tt>cupsDirClose()</tt></a> </li>
  94         <li><a href='#cupsDirOpen'><tt>cupsDirOpen()</tt></a> </li>
  95         <li><a href='#cupsDirRead'><tt>cupsDirRead()</tt></a> </li>
  96         <li><a href='#cupsDirRewind'><tt>cupsDirRewind()</tt></a> </li>
  97         <li><a href='#cupsFileClose'><tt>cupsFileClose()</tt></a> </li>
  98         <li><a href='#cupsFileCompression'><tt>cupsFileCompression()</tt></a> </li>
  99         <li><a href='#cupsFileEOF'><tt>cupsFileEOF()</tt></a> </li>
 100         <li><a href='#cupsFileFind'><tt>cupsFileFind()</tt></a> </li>
 101         <li><a href='#cupsFileFlush'><tt>cupsFileFlush()</tt></a> </li>
 102         <li><a href='#cupsFileGetChar'><tt>cupsFileGetChar()</tt></a> </li>
 103         <li><a href='#cupsFileGetConf'><tt>cupsFileGetConf()</tt></a> </li>
 104         <li><a href='#cupsFileGetLine'><tt>cupsFileGetLine()</tt></a> </li>
 105         <li><a href='#cupsFileGets'><tt>cupsFileGets()</tt></a> </li>
 106         <li><a href='#cupsFileLock'><tt>cupsFileLock()</tt></a> </li>
 107         <li><a href='#cupsFileNumber'><tt>cupsFileNumber()</tt></a> </li>
 108         <li><a href='#cupsFileOpen'><tt>cupsFileOpen()</tt></a> </li>
 109         <li><a href='#cupsFileOpenFd'><tt>cupsFileOpenFd()</tt></a> </li>
 110         <li><a href='#cupsFilePeekChar'><tt>cupsFilePeekChar()</tt></a> </li>
 111         <li><a href='#cupsFilePrintf'><tt>cupsFilePrintf()</tt></a> </li>
 112         <li><a href='#cupsFilePutChar'><tt>cupsFilePutChar()</tt></a> </li>
 113         <li><a href='#cupsFilePuts'><tt>cupsFilePuts()</tt></a> </li>
 114         <li><a href='#cupsFileRead'><tt>cupsFileRead()</tt></a> </li>
 115         <li><a href='#cupsFileRewind'><tt>cupsFileRewind()</tt></a> </li>
 116         <li><a href='#cupsFileSeek'><tt>cupsFileSeek()</tt></a> </li>
 117         <li><a href='#cupsFileStderr'><tt>cupsFileStderr()</tt></a> </li>
 118         <li><a href='#cupsFileStdin'><tt>cupsFileStdin()</tt></a> </li>
 119         <li><a href='#cupsFileStdout'><tt>cupsFileStdout()</tt></a> </li>
 120         <li><a href='#cupsFileTell'><tt>cupsFileTell()</tt></a> </li>
 121         <li><a href='#cupsFileUnlock'><tt>cupsFileUnlock()</tt></a> </li>
 122         <li><a href='#cupsFileWrite'><tt>cupsFileWrite()</tt></a> </li>
 123 </ul>
 124 <!-- NEW PAGE -->
 125 <h3 class='title'><a name='cupsDirClose'>cupsDirClose()</a></h3>
 126 <h4>Description</h4>
 127 <p>Close a directory.</p>
 128 <h4>Syntax</h4>
 129 <pre>
 130 void
 131 cupsDirClose(
 132     <a href='#cups_dir_t'>cups_dir_t</a> * dp);
 133 </pre>
 134 <h4>Arguments</h4>
 135 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 136 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 137 <tbody>
 138 <tr><td><tt>dp</tt></td><td>Directory</td></tr>
 139 </tbody></table></div>
 140 <h4>Returns</h4>
 141 <p>Nothing.</p>
 142 <!-- NEW PAGE -->
 143 <h3 class='title'><a name='cupsDirOpen'>cupsDirOpen()</a></h3>
 144 <h4>Description</h4>
 145 <p>Open a directory.</p>
 146 <h4>Syntax</h4>
 147 <pre>
 148 <a href='#cups_dir_t'>cups_dir_t</a> *
 149 cupsDirOpen(
 150     const char * directory);
 151 </pre>
 152 <h4>Arguments</h4>
 153 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 154 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 155 <tbody>
 156 <tr><td><tt>directory</tt></td><td>Directory name</td></tr>
 157 </tbody></table></div>
 158 <h4>Returns</h4>
 159 <p>Directory</p>
 160 <!-- NEW PAGE -->
 161 <h3 class='title'><a name='cupsDirRead'>cupsDirRead()</a></h3>
 162 <h4>Description</h4>
 163 <p>Read the next directory entry.</p>
 164 <h4>Syntax</h4>
 165 <pre>
 166 <a href='#cups_dentry_t'>cups_dentry_t</a> *
 167 cupsDirRead(
 168     <a href='#cups_dir_t'>cups_dir_t</a> * dp);
 169 </pre>
 170 <h4>Arguments</h4>
 171 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 172 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 173 <tbody>
 174 <tr><td><tt>dp</tt></td><td>Directory</td></tr>
 175 </tbody></table></div>
 176 <h4>Returns</h4>
 177 <p>Directory entry</p>
 178 <!-- NEW PAGE -->
 179 <h3 class='title'><a name='cupsDirRewind'>cupsDirRewind()</a></h3>
 180 <h4>Description</h4>
 181 <p>Rewind to the start of the directory.</p>
 182 <h4>Syntax</h4>
 183 <pre>
 184 void
 185 cupsDirRewind(
 186     <a href='#cups_dir_t'>cups_dir_t</a> * dp);
 187 </pre>
 188 <h4>Arguments</h4>
 189 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 190 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 191 <tbody>
 192 <tr><td><tt>dp</tt></td><td>Directory</td></tr>
 193 </tbody></table></div>
 194 <h4>Returns</h4>
 195 <p>Nothing.</p>
 196 <!-- NEW PAGE -->
 197 <h3 class='title'><a name='cupsFileClose'>cupsFileClose()</a></h3>
 198 <h4>Description</h4>
 199 <p>Close a CUPS file.</p>
 200 <h4>Syntax</h4>
 201 <pre>
 202 int
 203 cupsFileClose(
 204     <a href='#cups_file_t'>cups_file_t</a> * fp);
 205 </pre>
 206 <h4>Arguments</h4>
 207 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 208 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 209 <tbody>
 210 <tr><td><tt>fp</tt></td><td>CUPS file</td></tr>
 211 </tbody></table></div>
 212 <h4>Returns</h4>
 213 <p>0 on success, -1 on error</p>
 214 <!-- NEW PAGE -->
 215 <h3 class='title'><a name='cupsFileCompression'>cupsFileCompression()</a></h3>
 216 <h4>Description</h4>
 217 <p>Return whether a file is compressed.</p>
 218 <h4>Syntax</h4>
 219 <pre>
 220 int
 221 cupsFileCompression(
 222     <a href='#cups_file_t'>cups_file_t</a> * fp);
 223 </pre>
 224 <h4>Arguments</h4>
 225 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 226 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 227 <tbody>
 228 <tr><td><tt>fp</tt></td><td>CUPS file</td></tr>
 229 </tbody></table></div>
 230 <h4>Returns</h4>
 231 <p>CUPS_FILE_NONE or CUPS_FILE_GZIP</p>
 232 <!-- NEW PAGE -->
 233 <h3 class='title'><a name='cupsFileEOF'>cupsFileEOF()</a></h3>
 234 <h4>Description</h4>
 235 <p>Return the end-of-file status.</p>
 236 <h4>Syntax</h4>
 237 <pre>
 238 int
 239 cupsFileEOF(
 240     <a href='#cups_file_t'>cups_file_t</a> * fp);
 241 </pre>
 242 <h4>Arguments</h4>
 243 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 244 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 245 <tbody>
 246 <tr><td><tt>fp</tt></td><td>CUPS file</td></tr>
 247 </tbody></table></div>
 248 <h4>Returns</h4>
 249 <p>1 on EOF, 0 otherwise</p>
 250 <!-- NEW PAGE -->
 251 <h3 class='title'><a name='cupsFileFind'>cupsFileFind()</a></h3>
 252 <h4>Description</h4>
 253 <p>Find a file using the specified path.
 254
 255 This function allows the paths in the path string to be separated by
 256 colons (UNIX standard) or semicolons (Windows standard) and stores the
 257 result in the buffer supplied.  If the file cannot be found in any of
 258 the supplied paths, NULL is returned. A NULL path only matches the
 259 current directory.</p>
 260 <h4>Syntax</h4>
 261 <pre>
 262 const char *
 263 cupsFileFind(
 264     const char * filename,
 265     const char * path,
 266     int executable,
 267     char * buffer,
 268     int bufsize);
 269 </pre>
 270 <h4>Arguments</h4>
 271 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 272 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 273 <tbody>
 274 <tr><td><tt>filename</tt></td><td>File to find</td></tr>
 275 <tr><td><tt>path</tt></td><td>Colon/semicolon-separated path</td></tr>
 276 <tr><td><tt>executable</tt></td><td>1 = executable files, 0 = any file/dir</td></tr>
 277 <tr><td><tt>buffer</tt></td><td>Filename buffer</td></tr>
 278 <tr><td><tt>bufsize</tt></td><td>Size of filename buffer</td></tr>
 279 </tbody></table></div>
 280 <h4>Returns</h4>
 281 <p>Full path to file or NULL</p>
 282 <!-- NEW PAGE -->
 283 <h3 class='title'><a name='cupsFileFlush'>cupsFileFlush()</a></h3>
 284 <h4>Description</h4>
 285 <p>Flush pending output.</p>
 286 <h4>Syntax</h4>
 287 <pre>
 288 int
 289 cupsFileFlush(
 290     <a href='#cups_file_t'>cups_file_t</a> * fp);
 291 </pre>
 292 <h4>Arguments</h4>
 293 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 294 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 295 <tbody>
 296 <tr><td><tt>fp</tt></td><td>CUPS file</td></tr>
 297 </tbody></table></div>
 298 <h4>Returns</h4>
 299 <p>0 on success, -1 on error</p>
 300 <!-- NEW PAGE -->
 301 <h3 class='title'><a name='cupsFileGetChar'>cupsFileGetChar()</a></h3>
 302 <h4>Description</h4>
 303 <p>Get a single character from a file.</p>
 304 <h4>Syntax</h4>
 305 <pre>
 306 int
 307 cupsFileGetChar(
 308     <a href='#cups_file_t'>cups_file_t</a> * fp);
 309 </pre>
 310 <h4>Arguments</h4>
 311 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 312 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 313 <tbody>
 314 <tr><td><tt>fp</tt></td><td>CUPS file</td></tr>
 315 </tbody></table></div>
 316 <h4>Returns</h4>
 317 <p>Character or -1 on EOF</p>
 318 <!-- NEW PAGE -->
 319 <h3 class='title'><a name='cupsFileGetConf'>cupsFileGetConf()</a></h3>
 320 <h4>Description</h4>
 321 <p>Get a line from a configuration file...</p>
 322 <h4>Syntax</h4>
 323 <pre>
 324 char *
 325 cupsFileGetConf(
 326     <a href='#cups_file_t'>cups_file_t</a> * fp,
 327     char * buf,
 328     size_t buflen,
 329     char ** value,
 330     int * linenum);
 331 </pre>
 332 <h4>Arguments</h4>
 333 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 334 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 335 <tbody>
 336 <tr><td><tt>fp</tt></td><td>CUPS file</td></tr>
 337 <tr><td><tt>buf</tt></td><td>String buffer</td></tr>
 338 <tr><td><tt>buflen</tt></td><td>Size of string buffer</td></tr>
 339 <tr><td><tt>value</tt></td><td>Pointer to value</td></tr>
 340 <tr><td><tt>linenum</tt></td><td>Current line number</td></tr>
 341 </tbody></table></div>
 342 <h4>Returns</h4>
 343 <p>Line read or NULL on eof/error</p>
 344 <!-- NEW PAGE -->
 345 <h3 class='title'><a name='cupsFileGetLine'>cupsFileGetLine()</a></h3>
 346 <h4>Description</h4>
 347 <p>Get a CR and/or LF-terminated line that may
 348 contain binary data.
 349
 350 This function differs from cupsFileGets() in that the trailing CR and LF
 351 are preserved, as is any binary data on the line. The buffer is nul-
 352 terminated, however you should use the returned length to determine
 353 the number of bytes on the line.</p>
 354 <h4>Syntax</h4>
 355 <pre>
 356 size_t
 357 cupsFileGetLine(
 358     <a href='#cups_file_t'>cups_file_t</a> * fp,
 359     char * buf,
 360     size_t buflen);
 361 </pre>
 362 <h4>Arguments</h4>
 363 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 364 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 365 <tbody>
 366 <tr><td><tt>fp</tt></td><td>File to read from</td></tr>
 367 <tr><td><tt>buf</tt></td><td>Buffer</td></tr>
 368 <tr><td><tt>buflen</tt></td><td>Size of buffer</td></tr>
 369 </tbody></table></div>
 370 <h4>Returns</h4>
 371 <p>Number of bytes on line or 0 on EOF</p>
 372 <!-- NEW PAGE -->
 373 <h3 class='title'><a name='cupsFileGets'>cupsFileGets()</a></h3>
 374 <h4>Description</h4>
 375 <p>Get a CR and/or LF-terminated line.</p>
 376 <h4>Syntax</h4>
 377 <pre>
 378 char *
 379 cupsFileGets(
 380     <a href='#cups_file_t'>cups_file_t</a> * fp,
 381     char * buf,
 382     size_t buflen);
 383 </pre>
 384 <h4>Arguments</h4>
 385 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 386 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 387 <tbody>
 388 <tr><td><tt>fp</tt></td><td>CUPS file</td></tr>
 389 <tr><td><tt>buf</tt></td><td>String buffer</td></tr>
 390 <tr><td><tt>buflen</tt></td><td>Size of string buffer</td></tr>
 391 </tbody></table></div>
 392 <h4>Returns</h4>
 393 <p>Line read or NULL on eof/error</p>
 394 <!-- NEW PAGE -->
 395 <h3 class='title'><a name='cupsFileLock'>cupsFileLock()</a></h3>
 396 <h4>Description</h4>
 397 <p>Temporarily lock access to a file.</p>
 398 <h4>Syntax</h4>
 399 <pre>
 400 int
 401 cupsFileLock(
 402     <a href='#cups_file_t'>cups_file_t</a> * fp,
 403     int block);
 404 </pre>
 405 <h4>Arguments</h4>
 406 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 407 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 408 <tbody>
 409 <tr><td><tt>fp</tt></td><td>File to lock</td></tr>
 410 <tr><td><tt>block</tt></td><td>1 to wait for the lock, 0 to fail right away</td></tr>
 411 </tbody></table></div>
 412 <h4>Returns</h4>
 413 <p>0 on success, -1 on error</p>
 414 <!-- NEW PAGE -->
 415 <h3 class='title'><a name='cupsFileNumber'>cupsFileNumber()</a></h3>
 416 <h4>Description</h4>
 417 <p>Return the file descriptor associated with a CUPS file.</p>
 418 <h4>Syntax</h4>
 419 <pre>
 420 int
 421 cupsFileNumber(
 422     <a href='#cups_file_t'>cups_file_t</a> * fp);
 423 </pre>
 424 <h4>Arguments</h4>
 425 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 426 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 427 <tbody>
 428 <tr><td><tt>fp</tt></td><td>CUPS file</td></tr>
 429 </tbody></table></div>
 430 <h4>Returns</h4>
 431 <p>File descriptor</p>
 432 <!-- NEW PAGE -->
 433 <h3 class='title'><a name='cupsFileOpen'>cupsFileOpen()</a></h3>
 434 <h4>Description</h4>
 435 <p>Open a CUPS file.</p>
 436 <h4>Syntax</h4>
 437 <pre>
 438 <a href='#cups_file_t'>cups_file_t</a> *
 439 cupsFileOpen(
 440     const char * filename,
 441     const char * mode);
 442 </pre>
 443 <h4>Arguments</h4>
 444 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 445 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 446 <tbody>
 447 <tr><td><tt>filename</tt></td><td>Name of file</td></tr>
 448 <tr><td><tt>mode</tt></td><td>Open mode</td></tr>
 449 </tbody></table></div>
 450 <h4>Returns</h4>
 451 <p>CUPS file or NULL</p>
 452 <!-- NEW PAGE -->
 453 <h3 class='title'><a name='cupsFileOpenFd'>cupsFileOpenFd()</a></h3>
 454 <h4>Description</h4>
 455 <p>Open a CUPS file using a file descriptor.</p>
 456 <h4>Syntax</h4>
 457 <pre>
 458 <a href='#cups_file_t'>cups_file_t</a> *
 459 cupsFileOpenFd(
 460     int fd,
 461     const char * mode);
 462 </pre>
 463 <h4>Arguments</h4>
 464 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 465 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 466 <tbody>
 467 <tr><td><tt>fd</tt></td><td>File descriptor</td></tr>
 468 <tr><td><tt>mode</tt></td><td>Open mode</td></tr>
 469 </tbody></table></div>
 470 <h4>Returns</h4>
 471 <p>CUPS file or NULL</p>
 472 <!-- NEW PAGE -->
 473 <h3 class='title'><a name='cupsFilePeekChar'>cupsFilePeekChar()</a></h3>
 474 <h4>Description</h4>
 475 <p>Peek at the next character from a file.</p>
 476 <h4>Syntax</h4>
 477 <pre>
 478 int
 479 cupsFilePeekChar(
 480     <a href='#cups_file_t'>cups_file_t</a> * fp);
 481 </pre>
 482 <h4>Arguments</h4>
 483 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 484 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 485 <tbody>
 486 <tr><td><tt>fp</tt></td><td>CUPS file</td></tr>
 487 </tbody></table></div>
 488 <h4>Returns</h4>
 489 <p>Character or -1 on EOF</p>
 490 <!-- NEW PAGE -->
 491 <h3 class='title'><a name='cupsFilePrintf'>cupsFilePrintf()</a></h3>
 492 <h4>Description</h4>
 493 <p>Write a formatted string.</p>
 494 <h4>Syntax</h4>
 495 <pre>
 496 int
 497 cupsFilePrintf(
 498     <a href='#cups_file_t'>cups_file_t</a> * fp,
 499     const char * format,
 500     ...);
 501 </pre>
 502 <h4>Arguments</h4>
 503 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 504 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 505 <tbody>
 506 <tr><td><tt>fp</tt></td><td>CUPS file</td></tr>
 507 <tr><td><tt>format</tt></td><td>Printf-style format string</td></tr>
 508 <tr><td><tt>...</tt></td><td>Additional args as necessary</td></tr>
 509 </tbody></table></div>
 510 <h4>Returns</h4>
 511 <p>Number of bytes written or -1</p>
 512 <!-- NEW PAGE -->
 513 <h3 class='title'><a name='cupsFilePutChar'>cupsFilePutChar()</a></h3>
 514 <h4>Description</h4>
 515 <p>Write a character.</p>
 516 <h4>Syntax</h4>
 517 <pre>
 518 int
 519 cupsFilePutChar(
 520     <a href='#cups_file_t'>cups_file_t</a> * fp,
 521     int c);
 522 </pre>
 523 <h4>Arguments</h4>
 524 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 525 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 526 <tbody>
 527 <tr><td><tt>fp</tt></td><td>CUPS file</td></tr>
 528 <tr><td><tt>c</tt></td><td>Character to write</td></tr>
 529 </tbody></table></div>
 530 <h4>Returns</h4>
 531 <p>0 on success, -1 on error</p>
 532 <!-- NEW PAGE -->
 533 <h3 class='title'><a name='cupsFilePuts'>cupsFilePuts()</a></h3>
 534 <h4>Description</h4>
 535 <p>Write a string.</p>
 536 <h4>Syntax</h4>
 537 <pre>
 538 int
 539 cupsFilePuts(
 540     <a href='#cups_file_t'>cups_file_t</a> * fp,
 541     const char * s);
 542 </pre>
 543 <h4>Arguments</h4>
 544 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 545 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 546 <tbody>
 547 <tr><td><tt>fp</tt></td><td>CUPS file</td></tr>
 548 <tr><td><tt>s</tt></td><td>String to write</td></tr>
 549 </tbody></table></div>
 550 <h4>Returns</h4>
 551 <p>Number of bytes written or -1</p>
 552 <!-- NEW PAGE -->
 553 <h3 class='title'><a name='cupsFileRead'>cupsFileRead()</a></h3>
 554 <h4>Description</h4>
 555 <p>Read from a file.</p>
 556 <h4>Syntax</h4>
 557 <pre>
 558 <a href='#ssize_t'>ssize_t</a>
 559 cupsFileRead(
 560     <a href='#cups_file_t'>cups_file_t</a> * fp,
 561     char * buf,
 562     size_t bytes);
 563 </pre>
 564 <h4>Arguments</h4>
 565 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 566 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 567 <tbody>
 568 <tr><td><tt>fp</tt></td><td>CUPS file</td></tr>
 569 <tr><td><tt>buf</tt></td><td>Buffer</td></tr>
 570 <tr><td><tt>bytes</tt></td><td>Number of bytes to read</td></tr>
 571 </tbody></table></div>
 572 <h4>Returns</h4>
 573 <p>Number of bytes read or -1</p>
 574 <!-- NEW PAGE -->
 575 <h3 class='title'><a name='cupsFileRewind'>cupsFileRewind()</a></h3>
 576 <h4>Description</h4>
 577 <p>Rewind a file.</p>
 578 <h4>Syntax</h4>
 579 <pre>
 580 off_t
 581 cupsFileRewind(
 582     <a href='#cups_file_t'>cups_file_t</a> * fp);
 583 </pre>
 584 <h4>Arguments</h4>
 585 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 586 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 587 <tbody>
 588 <tr><td><tt>fp</tt></td><td>CUPS file</td></tr>
 589 </tbody></table></div>
 590 <h4>Returns</h4>
 591 <p>New file position or -1</p>
 592 <!-- NEW PAGE -->
 593 <h3 class='title'><a name='cupsFileSeek'>cupsFileSeek()</a></h3>
 594 <h4>Description</h4>
 595 <p>Seek in a file.</p>
 596 <h4>Syntax</h4>
 597 <pre>
 598 off_t
 599 cupsFileSeek(
 600     <a href='#cups_file_t'>cups_file_t</a> * fp,
 601     off_t pos);
 602 </pre>
 603 <h4>Arguments</h4>
 604 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 605 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 606 <tbody>
 607 <tr><td><tt>fp</tt></td><td>CUPS file</td></tr>
 608 <tr><td><tt>pos</tt></td><td>Position in file</td></tr>
 609 </tbody></table></div>
 610 <h4>Returns</h4>
 611 <p>New file position or -1</p>
 612 <!-- NEW PAGE -->
 613 <h3 class='title'><a name='cupsFileStderr'>cupsFileStderr()</a></h3>
 614 <h4>Description</h4>
 615 <p>Just reposition the current pointer, since we have the right
 616 range...</p>
 617 <h4>Syntax</h4>
 618 <pre>
 619 <a href='#cups_file_t'>cups_file_t</a> *
 620 cupsFileStderr(void);
 621 </pre>
 622 <h4>Arguments</h4>
 623 <p>None.</p>
 624 <h4>Returns</h4>
 625 <p>Return a CUPS file associated with stderr.</p>
 626 <!-- NEW PAGE -->
 627 <h3 class='title'><a name='cupsFileStdin'>cupsFileStdin()</a></h3>
 628 <h4>Description</h4>
 629 <p>Open file descriptor 2...</p>
 630 <h4>Syntax</h4>
 631 <pre>
 632 <a href='#cups_file_t'>cups_file_t</a> *
 633 cupsFileStdin(void);
 634 </pre>
 635 <h4>Arguments</h4>
 636 <p>None.</p>
 637 <h4>Returns</h4>
 638 <p>Return a CUPS file associated with stdin.</p>
 639 <!-- NEW PAGE -->
 640 <h3 class='title'><a name='cupsFileStdout'>cupsFileStdout()</a></h3>
 641 <h4>Description</h4>
 642 <p>Open file descriptor 0...</p>
 643 <h4>Syntax</h4>
 644 <pre>
 645 <a href='#cups_file_t'>cups_file_t</a> *
 646 cupsFileStdout(void);
 647 </pre>
 648 <h4>Arguments</h4>
 649 <p>None.</p>
 650 <h4>Returns</h4>
 651 <p>Return a CUPS file associated with stdout.</p>
 652 <!-- NEW PAGE -->
 653 <h3 class='title'><a name='cupsFileTell'>cupsFileTell()</a></h3>
 654 <h4>Description</h4>
 655 <p>Return the current file position.</p>
 656 <h4>Syntax</h4>
 657 <pre>
 658 off_t
 659 cupsFileTell(
 660     <a href='#cups_file_t'>cups_file_t</a> * fp);
 661 </pre>
 662 <h4>Arguments</h4>
 663 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 664 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 665 <tbody>
 666 <tr><td><tt>fp</tt></td><td>CUPS file</td></tr>
 667 </tbody></table></div>
 668 <h4>Returns</h4>
 669 <p>File position</p>
 670 <!-- NEW PAGE -->
 671 <h3 class='title'><a name='cupsFileUnlock'>cupsFileUnlock()</a></h3>
 672 <h4>Description</h4>
 673 <p>Unlock access to a file.</p>
 674 <h4>Syntax</h4>
 675 <pre>
 676 int
 677 cupsFileUnlock(
 678     <a href='#cups_file_t'>cups_file_t</a> * fp);
 679 </pre>
 680 <h4>Arguments</h4>
 681 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 682 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 683 <tbody>
 684 <tr><td><tt>fp</tt></td><td>File to lock</td></tr>
 685 </tbody></table></div>
 686 <h4>Returns</h4>
 687 <p>0 on success, -1 on error</p>
 688 <!-- NEW PAGE -->
 689 <h3 class='title'><a name='cupsFileWrite'>cupsFileWrite()</a></h3>
 690 <h4>Description</h4>
 691 <p>Write to a file.</p>
 692 <h4>Syntax</h4>
 693 <pre>
 694 <a href='#ssize_t'>ssize_t</a>
 695 cupsFileWrite(
 696     <a href='#cups_file_t'>cups_file_t</a> * fp,
 697     const char * buf,
 698     size_t bytes);
 699 </pre>
 700 <h4>Arguments</h4>
 701 <div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
 702 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 703 <tbody>
 704 <tr><td><tt>fp</tt></td><td>CUPS file</td></tr>
 705 <tr><td><tt>buf</tt></td><td>Buffer</td></tr>
 706 <tr><td><tt>bytes</tt></td><td>Number of bytes to write</td></tr>
 707 </tbody></table></div>
 708 <h4>Returns</h4>
 709 <p>Number of bytes written</p>
 710 <!-- NEW PAGE -->
 711 <h2 class='title'><a name='STRUCTURES'>Structures</a></h2>
 712 <ul>
 713         <li><a href='#cups_dentry_s'><tt>cups_dentry_s</tt></a> </li>
 714 </ul>
 715 <!-- NEW PAGE -->
 716 <h3 class='title'><a name='cups_dentry_s'>cups_dentry_s</a></h3>
 717 <h4>Description</h4>
 718 <p>Directory entry type</p>
 719 <h4>Definition</h4>
 720 <pre>
 721 struct cups_dentry_s
 722 {
 723   struct stat fileinfo;
 724   char filename[260];
 725 };
 726 </pre>
 727 <h4>Members</h4>
 728 <div class='table'><table align='center' border='1' width='80%'>
 729 <thead><tr><th>Name</th><th>Description</th></tr></thead>
 730 <tbody>
 731 <tr><td><tt>fileinfo</tt> </td><td>File information</td></tr>
 732 <tr><td><tt>filename[260]</tt> </td><td>File name</td></tr>
 733 </tbody></table></div>
 734 <!-- NEW PAGE -->
 735 <h2 class='title'><a name='TYPES'>Types</a></h2>
 736 <ul>
 737         <li><a href='#cups_dentry_t'><tt>cups_dentry_t</tt></a> </li>
 738         <li><a href='#cups_dir_t'><tt>cups_dir_t</tt></a> </li>
 739         <li><a href='#cups_file_t'><tt>cups_file_t</tt></a> </li>
 740 </ul>
 741 <!-- NEW PAGE -->
 742 <h3 class='title'><a name='cups_dentry_t'>cups_dentry_t</a></h3>
 743 <h4>Description</h4>
 744 <p>Directory entry type</p>
 745 <h4>Definition</h4>
 746 <pre>
 747 typedef struct <a href='#cups_dentry_s'>cups_dentry_s</a> cups_dentry_t;
 748 </pre>
 749 <!-- NEW PAGE -->
 750 <h3 class='title'><a name='cups_dir_t'>cups_dir_t</a></h3>
 751 <h4>Description</h4>
 752 <p>Directory type</p>
 753 <h4>Definition</h4>
 754 <pre>
 755 typedef struct _cups_dir_s cups_dir_t;
 756 </pre>
 757 <!-- NEW PAGE -->
 758 <h3 class='title'><a name='cups_file_t'>cups_file_t</a></h3>
 759 <h4>Description</h4>
 760 <p>CUPS file type</p>
 761 <h4>Definition</h4>
 762 <pre>
 763 typedef struct _cups_file_s cups_file_t;
 764 </pre>
 765 </body>
 766 </html>