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