| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <!-- SECTION: Programming --> |
| <head> |
| <title>File and Directory APIs </title> |
| <meta name="keywords" content="Programming"> |
| <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> |
| <meta name="creator" content="Mini-XML v2.7"> |
| <style type="text/css"><!-- |
| BODY { |
| font-family: lucida grande, geneva, helvetica, arial, sans-serif; |
| } |
| |
| H1, H2, H3, H4, H5, H6, P, TD, TH { |
| font-family: lucida grande, geneva, helvetica, arial, sans-serif; |
| } |
| |
| KBD { |
| font-family: monaco, courier, monospace; |
| font-weight: bold; |
| } |
| |
| PRE { |
| font-family: monaco, courier, monospace; |
| } |
| |
| PRE.command { |
| border: dotted thin #7f7f7f; |
| margin-left: 36pt; |
| padding: 10px; |
| } |
| |
| P.compact { |
| margin: 0; |
| } |
| |
| P.example { |
| font-style: italic; |
| margin-left: 36pt; |
| } |
| |
| PRE.example { |
| background: #eeeeee; |
| border: dotted thin #999999; |
| margin-left: 36pt; |
| padding: 10pt; |
| } |
| |
| PRE.command EM, PRE.example EM { |
| font-family: lucida grande, geneva, helvetica, arial, sans-serif; |
| } |
| |
| P.command { |
| font-family: monaco, courier, monospace; |
| margin-left: 36pt; |
| } |
| |
| P.formula { |
| font-style: italic; |
| margin-left: 36pt; |
| } |
| |
| BLOCKQUOTE { |
| background: #eeeeee; |
| border: solid thin #999999; |
| padding: 10pt; |
| } |
| |
| A IMG { |
| border: none; |
| } |
| |
| A:link:hover IMG { |
| background: #f0f0f0; |
| border-radius: 10px; |
| -moz-border-radius: 10px; |
| } |
| |
| A:link, A:visited { |
| font-weight: normal; |
| text-decoration: none; |
| } |
| |
| A:link:hover, A:visited:hover, A:active { |
| text-decoration: underline; |
| } |
| |
| SUB, SUP { |
| font-size: 50%; |
| } |
| |
| TR.data, TD.data, TR.data TD { |
| margin-top: 10pt; |
| padding: 5pt; |
| border-bottom: solid 1pt #999999; |
| } |
| |
| TR.data TH { |
| border-bottom: solid 1pt #999999; |
| padding-top: 10pt; |
| padding-left: 5pt; |
| text-align: left; |
| } |
| |
| DIV.table TABLE { |
| border: solid thin #999999; |
| border-collapse: collapse; |
| border-spacing: 0; |
| margin-left: auto; |
| margin-right: auto; |
| } |
| |
| DIV.table CAPTION { |
| caption-side: top; |
| font-size: 120%; |
| font-style: italic; |
| font-weight: bold; |
| margin-left: auto; |
| margin-right: auto; |
| } |
| |
| DIV.table TABLE TD { |
| border: solid thin #cccccc; |
| padding-top: 5pt; |
| } |
| |
| DIV.table TABLE TH { |
| background: #cccccc; |
| border: none; |
| border-bottom: solid thin #999999; |
| } |
| |
| DIV.figure TABLE { |
| margin-left: auto; |
| margin-right: auto; |
| } |
| |
| DIV.figure CAPTION { |
| caption-side: bottom; |
| font-size: 120%; |
| font-style: italic; |
| font-weight: bold; |
| margin-left: auto; |
| margin-right: auto; |
| } |
| |
| TH.label { |
| text-align: right; |
| vertical-align: top; |
| } |
| |
| TH.sublabel { |
| text-align: right; |
| font-weight: normal; |
| } |
| |
| HR { |
| border: solid thin; |
| } |
| |
| SPAN.info { |
| background: black; |
| border: thin solid black; |
| color: white; |
| font-size: 80%; |
| font-style: italic; |
| font-weight: bold; |
| white-space: nowrap; |
| } |
| |
| H2 SPAN.info, H3 SPAN.info, H4 SPAN.info { |
| float: right; |
| font-size: 100%; |
| } |
| |
| H1.title { |
| } |
| |
| H2.title, H3.title { |
| border-bottom: solid 2pt #000000; |
| } |
| |
| DIV.indent, TABLE.indent { |
| margin-top: 2em; |
| margin-left: auto; |
| margin-right: auto; |
| width: 90%; |
| } |
| |
| TABLE.indent { |
| border-collapse: collapse; |
| } |
| |
| TABLE.indent TD, TABLE.indent TH { |
| padding: 0; |
| } |
| |
| TABLE.list { |
| border-collapse: collapse; |
| margin-left: auto; |
| margin-right: auto; |
| width: 90%; |
| } |
| |
| TABLE.list TH { |
| background: white; |
| border-bottom: solid thin #cccccc; |
| color: #444444; |
| padding-top: 10pt; |
| padding-left: 5pt; |
| text-align: left; |
| vertical-align: bottom; |
| white-space: nowrap; |
| } |
| |
| TABLE.list TH A { |
| color: #4444cc; |
| } |
| |
| TABLE.list TD { |
| border-bottom: solid thin #eeeeee; |
| padding-top: 5pt; |
| padding-left: 5pt; |
| } |
| |
| TABLE.list TR:nth-child(even) { |
| background: #f8f8f8; |
| } |
| |
| TABLE.list TR:nth-child(odd) { |
| background: #f4f4f4; |
| } |
| |
| DT { |
| margin-left: 36pt; |
| margin-top: 12pt; |
| } |
| |
| DD { |
| margin-left: 54pt; |
| } |
| |
| DL.category DT { |
| font-weight: bold; |
| } |
| |
| P.summary { |
| margin-left: 36pt; |
| font-family: monaco, courier, monospace; |
| } |
| |
| DIV.summary TABLE { |
| border: solid thin #999999; |
| border-collapse: collapse; |
| border-spacing: 0; |
| margin: 10px; |
| } |
| |
| DIV.summary TABLE TD, DIV.summary TABLE TH { |
| border: solid thin #999999; |
| padding: 5px; |
| text-align: left; |
| vertical-align: top; |
| } |
| |
| DIV.summary TABLE THEAD TH { |
| background: #eeeeee; |
| } |
| |
| /* API documentation styles... */ |
| div.body h1 { |
| margin: 0; |
| } |
| div.body h2 { |
| margin-top: 1.5em; |
| } |
| div.body h3, div.body h4, div.body h5 { |
| margin-bottom: 0.5em; |
| margin-top: 1.5em; |
| } |
| .class, .enumeration, .function, .struct, .typedef, .union { |
| border-bottom: solid thin #999999; |
| margin-bottom: 0; |
| margin-top: 2em; |
| } |
| .description { |
| margin-top: 0.5em; |
| } |
| code, p.code, pre, ul.code li { |
| font-family: monaco, courier, monospace; |
| font-size: 90%; |
| } |
| ul.code, ul.contents, ul.subcontents { |
| list-style-type: none; |
| margin: 0; |
| padding-left: 0; |
| } |
| ul.code li { |
| margin: 0; |
| } |
| ul.contents > li { |
| margin-top: 1em; |
| } |
| ul.contents li ul.code, ul.contents li ul.subcontents { |
| padding-left: 2em; |
| } |
| div.body dl { |
| margin-left: 0; |
| margin-top: 0; |
| } |
| div.body dt { |
| font-style: italic; |
| margin-left: 0; |
| margin-top: 0; |
| } |
| div.body dd { |
| margin-bottom: 0.5em; |
| } |
| |
| /* This is just for the HTML files generated with the framedhelp target */ |
| div.contents { |
| background: #e8e8e8; |
| border: solid thin black; |
| padding: 10px; |
| } |
| div.contents h1 { |
| font-size: 110%; |
| } |
| div.contents h2 { |
| font-size: 100%; |
| } |
| div.contents ul.contents { |
| font-size: 80%; |
| } |
| div.contents ul.subcontents li { |
| margin-left: 1em; |
| text-indent: -1em; |
| } |
| --></style> |
| </head> |
| <body> |
| <div class='body'> |
| <!-- |
| "$Id$" |
| |
| File and Directory API header for CUPS. |
| |
| Copyright 2008-2011 by Apple Inc. |
| |
| These coded instructions, statements, and computer programs are the |
| property of Apple Inc. and are protected by Federal copyright |
| law. Distribution and use rights are outlined in the file "LICENSE.txt" |
| which should have been included with this file. If this file is |
| file is missing or damaged, see the license at "http://www.cups.org/". |
| --> |
| |
| <h1 class='title'>File and Directory APIs</h1> |
| |
| <div class='summary'><table summary='General Information'> |
| <thead> |
| <tr> |
| <th>Headers</th> |
| <th>cups/file.h<br> |
| cups/dir.h</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <th>Library</th> |
| <td>-lcups</td> |
| </tr> |
| <tr> |
| <th>See Also</th> |
| <td>Programming: <a href='api-overview.html' target='_top'>Introduction to CUPS Programming</a><br> |
| Programming: <a href='api-cups.html' target='_top'>CUPS API</a></td> |
| </tr> |
| </tbody> |
| </table></div> |
| <h2 class="title">Contents</h2> |
| <ul class="contents"> |
| <li><a href="#OVERVIEW">Overview</a></li> |
| <li><a href="#FUNCTIONS">Functions</a><ul class="code"> |
| <li><a href="#cupsDirClose" title="Close a directory.">cupsDirClose</a></li> |
| <li><a href="#cupsDirOpen" title="Open a directory.">cupsDirOpen</a></li> |
| <li><a href="#cupsDirRead" title="Read the next directory entry.">cupsDirRead</a></li> |
| <li><a href="#cupsDirRewind" title="Rewind to the start of the directory.">cupsDirRewind</a></li> |
| <li><a href="#cupsFileClose" title="Close a CUPS file.">cupsFileClose</a></li> |
| <li><a href="#cupsFileCompression" title="Return whether a file is compressed.">cupsFileCompression</a></li> |
| <li><a href="#cupsFileEOF" title="Return the end-of-file status.">cupsFileEOF</a></li> |
| <li><a href="#cupsFileFind" title="Find a file using the specified path.">cupsFileFind</a></li> |
| <li><a href="#cupsFileFlush" title="Flush pending output.">cupsFileFlush</a></li> |
| <li><a href="#cupsFileGetChar" title="Get a single character from a file.">cupsFileGetChar</a></li> |
| <li><a href="#cupsFileGetConf" title="Get a line from a configuration file.">cupsFileGetConf</a></li> |
| <li><a href="#cupsFileGetLine" title="Get a CR and/or LF-terminated line that may |
| contain binary data.">cupsFileGetLine</a></li> |
| <li><a href="#cupsFileGets" title="Get a CR and/or LF-terminated line.">cupsFileGets</a></li> |
| <li><a href="#cupsFileLock" title="Temporarily lock access to a file.">cupsFileLock</a></li> |
| <li><a href="#cupsFileNumber" title="Return the file descriptor associated with a CUPS file.">cupsFileNumber</a></li> |
| <li><a href="#cupsFileOpen" title="Open a CUPS file.">cupsFileOpen</a></li> |
| <li><a href="#cupsFileOpenFd" title="Open a CUPS file using a file descriptor.">cupsFileOpenFd</a></li> |
| <li><a href="#cupsFilePeekChar" title="Peek at the next character from a file.">cupsFilePeekChar</a></li> |
| <li><a href="#cupsFilePrintf" title="Write a formatted string.">cupsFilePrintf</a></li> |
| <li><a href="#cupsFilePutChar" title="Write a character.">cupsFilePutChar</a></li> |
| <li><a href="#cupsFilePutConf" title="Write a configuration line.">cupsFilePutConf</a></li> |
| <li><a href="#cupsFilePuts" title="Write a string.">cupsFilePuts</a></li> |
| <li><a href="#cupsFileRead" title="Read from a file.">cupsFileRead</a></li> |
| <li><a href="#cupsFileRewind" title="Set the current file position to the beginning of the |
| file.">cupsFileRewind</a></li> |
| <li><a href="#cupsFileSeek" title="Seek in a file.">cupsFileSeek</a></li> |
| <li><a href="#cupsFileStderr" title="Return a CUPS file associated with stderr.">cupsFileStderr</a></li> |
| <li><a href="#cupsFileStdin" title="Return a CUPS file associated with stdin.">cupsFileStdin</a></li> |
| <li><a href="#cupsFileStdout" title="Return a CUPS file associated with stdout.">cupsFileStdout</a></li> |
| <li><a href="#cupsFileTell" title="Return the current file position.">cupsFileTell</a></li> |
| <li><a href="#cupsFileUnlock" title="Unlock access to a file.">cupsFileUnlock</a></li> |
| <li><a href="#cupsFileWrite" title="Write to a file.">cupsFileWrite</a></li> |
| </ul></li> |
| <li><a href="#TYPES">Data Types</a><ul class="code"> |
| <li><a href="#cups_dentry_t" title="Directory entry type">cups_dentry_t</a></li> |
| <li><a href="#cups_dir_t" title="Directory type">cups_dir_t</a></li> |
| <li><a href="#cups_file_t" title="CUPS file type">cups_file_t</a></li> |
| </ul></li> |
| <li><a href="#STRUCTURES">Structures</a><ul class="code"> |
| <li><a href="#cups_dentry_s" title="Directory entry type">cups_dentry_s</a></li> |
| </ul></li> |
| </ul> |
| <!-- |
| "$Id$" |
| |
| File and directory API introduction for CUPS. |
| |
| Copyright 2007-2011 by Apple Inc. |
| Copyright 1997-2005 by Easy Software Products, all rights reserved. |
| |
| These coded instructions, statements, and computer programs are the |
| property of Apple Inc. and are protected by Federal copyright |
| law. Distribution and use rights are outlined in the file "LICENSE.txt" |
| which should have been included with this file. If this file is |
| file is missing or damaged, see the license at "http://www.cups.org/". |
| --> |
| |
| <h2 class='title'><a name="OVERVIEW">Overview</a></h2> |
| |
| <p>The CUPS file and directory APIs provide portable interfaces |
| for manipulating files and listing files and directories. Unlike |
| stdio <code>FILE</code> streams, the <code>cupsFile</code> functions |
| allow you to open more than 256 files at any given time. They |
| also manage the platform-specific details of locking, large file |
| support, line endings (CR, LF, or CR LF), and reading and writing |
| files using Flate ("gzip") compression. Finally, you can also |
| connect, read from, and write to network connections using the |
| <code>cupsFile</code> functions.</p> |
| |
| <p>The <code>cupsDir</code> functions manage the platform-specific |
| details of directory access/listing and provide a convenient way |
| to get both a list of files and the information (permissions, |
| size, timestamp, etc.) for each of those files.</p> |
| <h2 class="title"><a name="FUNCTIONS">Functions</a></h2> |
| <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsDirClose">cupsDirClose</a></h3> |
| <p class="description">Close a directory.</p> |
| <p class="code"> |
| void cupsDirClose (<br> |
| <a href="#cups_dir_t">cups_dir_t</a> *dp<br> |
| );</p> |
| <h4 class="parameters">Parameters</h4> |
| <dl> |
| <dt>dp</dt> |
| <dd class="description">Directory pointer</dd> |
| </dl> |
| <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsDirOpen">cupsDirOpen</a></h3> |
| <p class="description">Open a directory.</p> |
| <p class="code"> |
| <a href="#cups_dir_t">cups_dir_t</a> *cupsDirOpen (<br> |
| const char *directory<br> |
| );</p> |
| <h4 class="parameters">Parameters</h4> |
| <dl> |
| <dt>directory</dt> |
| <dd class="description">Directory name</dd> |
| </dl> |
| <h4 class="returnvalue">Return Value</h4> |
| <p class="description">Directory pointer or <code>NULL</code> if the directory could not be opened.</p> |
| <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsDirRead">cupsDirRead</a></h3> |
| <p class="description">Read the next directory entry.</p> |
| <p class="code"> |
| <a href="#cups_dentry_t">cups_dentry_t</a> *cupsDirRead (<br> |
| <a href="#cups_dir_t">cups_dir_t</a> *dp<br> |
| );</p> |
| <h4 class="parameters">Parameters</h4> |
| <dl> |
| <dt>dp</dt> |
| <dd class="description">Directory pointer</dd> |
| </dl> |
| <h4 class="returnvalue">Return Value</h4> |
| <p class="description">Directory entry or <code>NULL</code> when there are no more</p> |
| <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsDirRewind">cupsDirRewind</a></h3> |
| <p class="description">Rewind to the start of the directory.</p> |
| <p class="code"> |
| void cupsDirRewind (<br> |
| <a href="#cups_dir_t">cups_dir_t</a> *dp<br> |
| );</p> |
| <h4 class="parameters">Parameters</h4> |
| <dl> |
| <dt>dp</dt> |
| <dd class="description">Directory pointer</dd> |
| </dl> |
| <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileClose">cupsFileClose</a></h3> |
| <p class="description">Close a CUPS file.</p> |
| <p class="code"> |
| int cupsFileClose (<br> |
| <a href="#cups_file_t">cups_file_t</a> *fp<br> |
| );</p> |
| <h4 class="parameters">Parameters</h4> |
| <dl> |
| <dt>fp</dt> |
| <dd class="description">CUPS file</dd> |
| </dl> |
| <h4 class="returnvalue">Return Value</h4> |
| <p class="description">0 on success, -1 on error</p> |
| <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileCompression">cupsFileCompression</a></h3> |
| <p class="description">Return whether a file is compressed.</p> |
| <p class="code"> |
| int cupsFileCompression (<br> |
| <a href="#cups_file_t">cups_file_t</a> *fp<br> |
| );</p> |
| <h4 class="parameters">Parameters</h4> |
| <dl> |
| <dt>fp</dt> |
| <dd class="description">CUPS file</dd> |
| </dl> |
| <h4 class="returnvalue">Return Value</h4> |
| <p class="description"><code>CUPS_FILE_NONE</code> or <code>CUPS_FILE_GZIP</code></p> |
| <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileEOF">cupsFileEOF</a></h3> |
| <p class="description">Return the end-of-file status.</p> |
| <p class="code"> |
| int cupsFileEOF (<br> |
| <a href="#cups_file_t">cups_file_t</a> *fp<br> |
| );</p> |
| <h4 class="parameters">Parameters</h4> |
| <dl> |
| <dt>fp</dt> |
| <dd class="description">CUPS file</dd> |
| </dl> |
| <h4 class="returnvalue">Return Value</h4> |
| <p class="description">1 on end of file, 0 otherwise</p> |
| <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileFind">cupsFileFind</a></h3> |
| <p class="description">Find a file using the specified path.</p> |
| <p class="code"> |
| const char *cupsFileFind (<br> |
| const char *filename,<br> |
| const char *path,<br> |
| int executable,<br> |
| char *buffer,<br> |
| int bufsize<br> |
| );</p> |
| <h4 class="parameters">Parameters</h4> |
| <dl> |
| <dt>filename</dt> |
| <dd class="description">File to find</dd> |
| <dt>path</dt> |
| <dd class="description">Colon/semicolon-separated path</dd> |
| <dt>executable</dt> |
| <dd class="description">1 = executable files, 0 = any file/dir</dd> |
| <dt>buffer</dt> |
| <dd class="description">Filename buffer</dd> |
| <dt>bufsize</dt> |
| <dd class="description">Size of filename buffer</dd> |
| </dl> |
| <h4 class="returnvalue">Return Value</h4> |
| <p class="description">Full path to file or <code>NULL</code> if not found</p> |
| <h4 class="discussion">Discussion</h4> |
| <p class="discussion">This function allows the paths in the path string to be separated by |
| colons (UNIX standard) or semicolons (Windows standard) and stores the |
| result in the buffer supplied. If the file cannot be found in any of |
| the supplied paths, <code>NULL</code> is returned. A <code>NULL</code> path only |
| matches the current directory. |
| |
| </p> |
| <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileFlush">cupsFileFlush</a></h3> |
| <p class="description">Flush pending output.</p> |
| <p class="code"> |
| int cupsFileFlush (<br> |
| <a href="#cups_file_t">cups_file_t</a> *fp<br> |
| );</p> |
| <h4 class="parameters">Parameters</h4> |
| <dl> |
| <dt>fp</dt> |
| <dd class="description">CUPS file</dd> |
| </dl> |
| <h4 class="returnvalue">Return Value</h4> |
| <p class="description">0 on success, -1 on error</p> |
| <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileGetChar">cupsFileGetChar</a></h3> |
| <p class="description">Get a single character from a file.</p> |
| <p class="code"> |
| int cupsFileGetChar (<br> |
| <a href="#cups_file_t">cups_file_t</a> *fp<br> |
| );</p> |
| <h4 class="parameters">Parameters</h4> |
| <dl> |
| <dt>fp</dt> |
| <dd class="description">CUPS file</dd> |
| </dl> |
| <h4 class="returnvalue">Return Value</h4> |
| <p class="description">Character or -1 on end of file</p> |
| <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileGetConf">cupsFileGetConf</a></h3> |
| <p class="description">Get a line from a configuration file.</p> |
| <p class="code"> |
| char *cupsFileGetConf (<br> |
| <a href="#cups_file_t">cups_file_t</a> *fp,<br> |
| char *buf,<br> |
| size_t buflen,<br> |
| char **value,<br> |
| int *linenum<br> |
| );</p> |
| <h4 class="parameters">Parameters</h4> |
| <dl> |
| <dt>fp</dt> |
| <dd class="description">CUPS file</dd> |
| <dt>buf</dt> |
| <dd class="description">String buffer</dd> |
| <dt>buflen</dt> |
| <dd class="description">Size of string buffer</dd> |
| <dt>value</dt> |
| <dd class="description">Pointer to value</dd> |
| <dt>linenum</dt> |
| <dd class="description">Current line number</dd> |
| </dl> |
| <h4 class="returnvalue">Return Value</h4> |
| <p class="description">Line read or <code>NULL</code> on end of file or error</p> |
| <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileGetLine">cupsFileGetLine</a></h3> |
| <p class="description">Get a CR and/or LF-terminated line that may |
| contain binary data.</p> |
| <p class="code"> |
| size_t cupsFileGetLine (<br> |
| <a href="#cups_file_t">cups_file_t</a> *fp,<br> |
| char *buf,<br> |
| size_t buflen<br> |
| );</p> |
| <h4 class="parameters">Parameters</h4> |
| <dl> |
| <dt>fp</dt> |
| <dd class="description">File to read from</dd> |
| <dt>buf</dt> |
| <dd class="description">Buffer</dd> |
| <dt>buflen</dt> |
| <dd class="description">Size of buffer</dd> |
| </dl> |
| <h4 class="returnvalue">Return Value</h4> |
| <p class="description">Number of bytes on line or 0 on end of file</p> |
| <h4 class="discussion">Discussion</h4> |
| <p class="discussion">This function differs from <a href="#cupsFileGets"><code>cupsFileGets</code></a> in that the trailing CR |
| and LF are preserved, as is any binary data on the line. The buffer is |
| nul-terminated, however you should use the returned length to determine |
| the number of bytes on the line. |
| |
| </p> |
| <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileGets">cupsFileGets</a></h3> |
| <p class="description">Get a CR and/or LF-terminated line.</p> |
| <p class="code"> |
| char *cupsFileGets (<br> |
| <a href="#cups_file_t">cups_file_t</a> *fp,<br> |
| char *buf,<br> |
| size_t buflen<br> |
| );</p> |
| <h4 class="parameters">Parameters</h4> |
| <dl> |
| <dt>fp</dt> |
| <dd class="description">CUPS file</dd> |
| <dt>buf</dt> |
| <dd class="description">String buffer</dd> |
| <dt>buflen</dt> |
| <dd class="description">Size of string buffer</dd> |
| </dl> |
| <h4 class="returnvalue">Return Value</h4> |
| <p class="description">Line read or <code>NULL</code> on end of file or error</p> |
| <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileLock">cupsFileLock</a></h3> |
| <p class="description">Temporarily lock access to a file.</p> |
| <p class="code"> |
| int cupsFileLock (<br> |
| <a href="#cups_file_t">cups_file_t</a> *fp,<br> |
| int block<br> |
| );</p> |
| <h4 class="parameters">Parameters</h4> |
| <dl> |
| <dt>fp</dt> |
| <dd class="description">CUPS file</dd> |
| <dt>block</dt> |
| <dd class="description">1 to wait for the lock, 0 to fail right away</dd> |
| </dl> |
| <h4 class="returnvalue">Return Value</h4> |
| <p class="description">0 on success, -1 on error</p> |
| <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileNumber">cupsFileNumber</a></h3> |
| <p class="description">Return the file descriptor associated with a CUPS file.</p> |
| <p class="code"> |
| int cupsFileNumber (<br> |
| <a href="#cups_file_t">cups_file_t</a> *fp<br> |
| );</p> |
| <h4 class="parameters">Parameters</h4> |
| <dl> |
| <dt>fp</dt> |
| <dd class="description">CUPS file</dd> |
| </dl> |
| <h4 class="returnvalue">Return Value</h4> |
| <p class="description">File descriptor</p> |
| <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileOpen">cupsFileOpen</a></h3> |
| <p class="description">Open a CUPS file.</p> |
| <p class="code"> |
| <a href="#cups_file_t">cups_file_t</a> *cupsFileOpen (<br> |
| const char *filename,<br> |
| const char *mode<br> |
| );</p> |
| <h4 class="parameters">Parameters</h4> |
| <dl> |
| <dt>filename</dt> |
| <dd class="description">Name of file</dd> |
| <dt>mode</dt> |
| <dd class="description">Open mode</dd> |
| </dl> |
| <h4 class="returnvalue">Return Value</h4> |
| <p class="description">CUPS file or <code>NULL</code> if the file or socket cannot be opened</p> |
| <h4 class="discussion">Discussion</h4> |
| <p class="discussion">The "mode" parameter can be "r" to read, "w" to write, overwriting any |
| existing file, "a" to append to an existing file or create a new file, |
| or "s" to open a socket connection.<br> |
| <br> |
| When opening for writing ("w"), an optional number from 1 to 9 can be |
| supplied which enables Flate compression of the file. Compression is |
| not supported for the "a" (append) mode.<br> |
| <br> |
| When opening a socket connection, the filename is a string of the form |
| "address:port" or "hostname:port". The socket will make an IPv4 or IPv6 |
| connection as needed, generally preferring IPv6 connections when there is |
| a choice. |
| |
| </p> |
| <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileOpenFd">cupsFileOpenFd</a></h3> |
| <p class="description">Open a CUPS file using a file descriptor.</p> |
| <p class="code"> |
| <a href="#cups_file_t">cups_file_t</a> *cupsFileOpenFd (<br> |
| int fd,<br> |
| const char *mode<br> |
| );</p> |
| <h4 class="parameters">Parameters</h4> |
| <dl> |
| <dt>fd</dt> |
| <dd class="description">File descriptor</dd> |
| <dt>mode</dt> |
| <dd class="description">Open mode</dd> |
| </dl> |
| <h4 class="returnvalue">Return Value</h4> |
| <p class="description">CUPS file or <code>NULL</code> if the file could not be opened</p> |
| <h4 class="discussion">Discussion</h4> |
| <p class="discussion">The "mode" parameter can be "r" to read, "w" to write, "a" to append, |
| or "s" to treat the file descriptor as a bidirectional socket connection.<br> |
| <br> |
| When opening for writing ("w"), an optional number from 1 to 9 can be |
| supplied which enables Flate compression of the file. Compression is |
| not supported for the "a" (append) mode. |
| |
| </p> |
| <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFilePeekChar">cupsFilePeekChar</a></h3> |
| <p class="description">Peek at the next character from a file.</p> |
| <p class="code"> |
| int cupsFilePeekChar (<br> |
| <a href="#cups_file_t">cups_file_t</a> *fp<br> |
| );</p> |
| <h4 class="parameters">Parameters</h4> |
| <dl> |
| <dt>fp</dt> |
| <dd class="description">CUPS file</dd> |
| </dl> |
| <h4 class="returnvalue">Return Value</h4> |
| <p class="description">Character or -1 on end of file</p> |
| <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFilePrintf">cupsFilePrintf</a></h3> |
| <p class="description">Write a formatted string.</p> |
| <p class="code"> |
| int cupsFilePrintf (<br> |
| <a href="#cups_file_t">cups_file_t</a> *fp,<br> |
| const char *format,<br> |
| ...<br> |
| );</p> |
| <h4 class="parameters">Parameters</h4> |
| <dl> |
| <dt>fp</dt> |
| <dd class="description">CUPS file</dd> |
| <dt>format</dt> |
| <dd class="description">Printf-style format string</dd> |
| <dt>...</dt> |
| <dd class="description">Additional args as necessary</dd> |
| </dl> |
| <h4 class="returnvalue">Return Value</h4> |
| <p class="description">Number of bytes written or -1 on error</p> |
| <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFilePutChar">cupsFilePutChar</a></h3> |
| <p class="description">Write a character.</p> |
| <p class="code"> |
| int cupsFilePutChar (<br> |
| <a href="#cups_file_t">cups_file_t</a> *fp,<br> |
| int c<br> |
| );</p> |
| <h4 class="parameters">Parameters</h4> |
| <dl> |
| <dt>fp</dt> |
| <dd class="description">CUPS file</dd> |
| <dt>c</dt> |
| <dd class="description">Character to write</dd> |
| </dl> |
| <h4 class="returnvalue">Return Value</h4> |
| <p class="description">0 on success, -1 on error</p> |
| <h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsFilePutConf">cupsFilePutConf</a></h3> |
| <p class="description">Write a configuration line.</p> |
| <p class="code"> |
| ssize_t cupsFilePutConf (<br> |
| <a href="#cups_file_t">cups_file_t</a> *fp,<br> |
| const char *directive,<br> |
| const char *value<br> |
| );</p> |
| <h4 class="parameters">Parameters</h4> |
| <dl> |
| <dt>fp</dt> |
| <dd class="description">CUPS file</dd> |
| <dt>directive</dt> |
| <dd class="description">Directive</dd> |
| <dt>value</dt> |
| <dd class="description">Value</dd> |
| </dl> |
| <h4 class="returnvalue">Return Value</h4> |
| <p class="description">Number of bytes written or -1 on error</p> |
| <h4 class="discussion">Discussion</h4> |
| <p class="discussion">This function handles any comment escaping of the value. |
| |
| </p> |
| <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFilePuts">cupsFilePuts</a></h3> |
| <p class="description">Write a string.</p> |
| <p class="code"> |
| int cupsFilePuts (<br> |
| <a href="#cups_file_t">cups_file_t</a> *fp,<br> |
| const char *s<br> |
| );</p> |
| <h4 class="parameters">Parameters</h4> |
| <dl> |
| <dt>fp</dt> |
| <dd class="description">CUPS file</dd> |
| <dt>s</dt> |
| <dd class="description">String to write</dd> |
| </dl> |
| <h4 class="returnvalue">Return Value</h4> |
| <p class="description">Number of bytes written or -1 on error</p> |
| <h4 class="discussion">Discussion</h4> |
| <p class="discussion">Like the <code>fputs</code> function, no newline is appended to the string. |
| |
| </p> |
| <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileRead">cupsFileRead</a></h3> |
| <p class="description">Read from a file.</p> |
| <p class="code"> |
| ssize_t cupsFileRead (<br> |
| <a href="#cups_file_t">cups_file_t</a> *fp,<br> |
| char *buf,<br> |
| size_t bytes<br> |
| );</p> |
| <h4 class="parameters">Parameters</h4> |
| <dl> |
| <dt>fp</dt> |
| <dd class="description">CUPS file</dd> |
| <dt>buf</dt> |
| <dd class="description">Buffer</dd> |
| <dt>bytes</dt> |
| <dd class="description">Number of bytes to read</dd> |
| </dl> |
| <h4 class="returnvalue">Return Value</h4> |
| <p class="description">Number of bytes read or -1 on error</p> |
| <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileRewind">cupsFileRewind</a></h3> |
| <p class="description">Set the current file position to the beginning of the |
| file.</p> |
| <p class="code"> |
| off_t cupsFileRewind (<br> |
| <a href="#cups_file_t">cups_file_t</a> *fp<br> |
| );</p> |
| <h4 class="parameters">Parameters</h4> |
| <dl> |
| <dt>fp</dt> |
| <dd class="description">CUPS file</dd> |
| </dl> |
| <h4 class="returnvalue">Return Value</h4> |
| <p class="description">New file position or -1 on error</p> |
| <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileSeek">cupsFileSeek</a></h3> |
| <p class="description">Seek in a file.</p> |
| <p class="code"> |
| off_t cupsFileSeek (<br> |
| <a href="#cups_file_t">cups_file_t</a> *fp,<br> |
| off_t pos<br> |
| );</p> |
| <h4 class="parameters">Parameters</h4> |
| <dl> |
| <dt>fp</dt> |
| <dd class="description">CUPS file</dd> |
| <dt>pos</dt> |
| <dd class="description">Position in file</dd> |
| </dl> |
| <h4 class="returnvalue">Return Value</h4> |
| <p class="description">New file position or -1 on error</p> |
| <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileStderr">cupsFileStderr</a></h3> |
| <p class="description">Return a CUPS file associated with stderr.</p> |
| <p class="code"> |
| <a href="#cups_file_t">cups_file_t</a> *cupsFileStderr (void);</p> |
| <h4 class="returnvalue">Return Value</h4> |
| <p class="description">CUPS file</p> |
| <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileStdin">cupsFileStdin</a></h3> |
| <p class="description">Return a CUPS file associated with stdin.</p> |
| <p class="code"> |
| <a href="#cups_file_t">cups_file_t</a> *cupsFileStdin (void);</p> |
| <h4 class="returnvalue">Return Value</h4> |
| <p class="description">CUPS file</p> |
| <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileStdout">cupsFileStdout</a></h3> |
| <p class="description">Return a CUPS file associated with stdout.</p> |
| <p class="code"> |
| <a href="#cups_file_t">cups_file_t</a> *cupsFileStdout (void);</p> |
| <h4 class="returnvalue">Return Value</h4> |
| <p class="description">CUPS file</p> |
| <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileTell">cupsFileTell</a></h3> |
| <p class="description">Return the current file position.</p> |
| <p class="code"> |
| off_t cupsFileTell (<br> |
| <a href="#cups_file_t">cups_file_t</a> *fp<br> |
| );</p> |
| <h4 class="parameters">Parameters</h4> |
| <dl> |
| <dt>fp</dt> |
| <dd class="description">CUPS file</dd> |
| </dl> |
| <h4 class="returnvalue">Return Value</h4> |
| <p class="description">File position</p> |
| <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileUnlock">cupsFileUnlock</a></h3> |
| <p class="description">Unlock access to a file.</p> |
| <p class="code"> |
| int cupsFileUnlock (<br> |
| <a href="#cups_file_t">cups_file_t</a> *fp<br> |
| );</p> |
| <h4 class="parameters">Parameters</h4> |
| <dl> |
| <dt>fp</dt> |
| <dd class="description">CUPS file</dd> |
| </dl> |
| <h4 class="returnvalue">Return Value</h4> |
| <p class="description">0 on success, -1 on error</p> |
| <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileWrite">cupsFileWrite</a></h3> |
| <p class="description">Write to a file.</p> |
| <p class="code"> |
| ssize_t cupsFileWrite (<br> |
| <a href="#cups_file_t">cups_file_t</a> *fp,<br> |
| const char *buf,<br> |
| size_t bytes<br> |
| );</p> |
| <h4 class="parameters">Parameters</h4> |
| <dl> |
| <dt>fp</dt> |
| <dd class="description">CUPS file</dd> |
| <dt>buf</dt> |
| <dd class="description">Buffer</dd> |
| <dt>bytes</dt> |
| <dd class="description">Number of bytes to write</dd> |
| </dl> |
| <h4 class="returnvalue">Return Value</h4> |
| <p class="description">Number of bytes written or -1 on error</p> |
| <h2 class="title"><a name="TYPES">Data Types</a></h2> |
| <h3 class="typedef"><a name="cups_dentry_t">cups_dentry_t</a></h3> |
| <p class="description">Directory entry type</p> |
| <p class="code"> |
| typedef struct <a href="#cups_dentry_s">cups_dentry_s</a> cups_dentry_t; |
| </p> |
| <h3 class="typedef"><a name="cups_dir_t">cups_dir_t</a></h3> |
| <p class="description">Directory type</p> |
| <p class="code"> |
| typedef struct _cups_dir_s cups_dir_t; |
| </p> |
| <h3 class="typedef"><a name="cups_file_t">cups_file_t</a></h3> |
| <p class="description">CUPS file type</p> |
| <p class="code"> |
| typedef struct _cups_file_s cups_file_t; |
| </p> |
| <h2 class="title"><a name="STRUCTURES">Structures</a></h2> |
| <h3 class="struct"><a name="cups_dentry_s">cups_dentry_s</a></h3> |
| <p class="description">Directory entry type</p> |
| <p class="code">struct cups_dentry_s {<br> |
| struct stat fileinfo;<br> |
| char filename[260];<br> |
| };</p> |
| <h4 class="members">Members</h4> |
| <dl> |
| <dt>fileinfo </dt> |
| <dd class="description">File information</dd> |
| <dt>filename[260] </dt> |
| <dd class="description">File name</dd> |
| </dl> |
| </div> |
| </body> |
| </html> |