-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
+<!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 name="creator" content="Mini-XML v2.5">
+<meta name="creator" content="Mini-XML v2.6">
<style type="text/css"><!--
BODY {
font-family: lucida grande, geneva, helvetica, arial, sans-serif;
margin-left: 36pt;
}
+P.compact {
+ margin: 0;
+}
+
+P.example {
+ font-style: italic;
+ margin-left: 36pt;
+}
+
PRE.example {
background: #eeeeee;
border: dotted thin #999999;
margin-left: 36pt;
- padding: 10px;
+ padding: 10pt;
}
PRE.command EM, PRE.example EM {
}
BLOCKQUOTE {
- background: #cccccc;
+ 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;
- font-weight: bold;
}
A:link:hover, A:visited:hover, A:active {
text-decoration: underline;
- font-weight: bold;
}
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;
}
TH.label {
- padding-top: 5pt;
text-align: right;
vertical-align: top;
}
+TH.sublabel {
+ text-align: right;
+ font-weight: normal;
+}
+
HR {
border: solid thin;
}
SPAN.info {
- background: #000000;
- border: thin solid #000000;
- color: #ffffff;
+ background: black;
+ border: thin solid black;
+ color: white;
font-size: 80%;
font-style: italic;
font-weight: bold;
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;
font-family: monaco, courier, monospace;
}
-SPAN.message {
- font-style: italic;
- font-size: smaller;
-}
-
DIV.summary TABLE {
border: solid thin #999999;
border-collapse: collapse;
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: api-filedir.header 7279 2008-01-31 01:50:44Z mike $"
+ "$Id: api-filedir.header 8627 2009-05-13 21:39:17Z mike $"
File and Directory API header for the Common UNIX Printing System (CUPS).
- Copyright 2008 by Apple Inc.
+ Copyright 2008-2009 by Apple Inc.
These coded instructions, statements, and computer programs are the
property of Apple Inc. and are protected by Federal copyright
file is missing or damaged, see the license at "http://www.cups.org/".
-->
-<h1 class="title">File and Directory APIs</h1>
+<h1 class='title'>File and Directory APIs</h1>
<div class='summary'><table summary='General Information'>
<thead>
</table></div>
<h2 class="title">Contents</h2>
<ul class="contents">
-</li>
+<ul class="subcontents">
<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="#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
<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>
+</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="#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: api-filedir.shtml 7279 2008-01-31 01:50:44Z mike $"
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 </span><a name="cupsDirClose">cupsDirClose</a></h3>
+<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>
<dt>dp</dt>
<dd class="description">Directory pointer</dd>
</dl>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsDirOpen">cupsDirOpen</a></h3>
+<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>
</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 </span><a name="cupsDirRead">cupsDirRead</a></h3>
+<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>
</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 </span><a name="cupsDirRewind">cupsDirRewind</a></h3>
+<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>
<dt>dp</dt>
<dd class="description">Directory pointer</dd>
</dl>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsFileClose">cupsFileClose</a></h3>
+<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>
</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 </span><a name="cupsFileCompression">cupsFileCompression</a></h3>
+<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>
</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 </span><a name="cupsFileEOF">cupsFileEOF</a></h3>
+<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>
</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 </span><a name="cupsFileFind">cupsFileFind</a></h3>
+<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>
matches the current directory.
</p>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsFileFlush">cupsFileFlush</a></h3>
+<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>
</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 </span><a name="cupsFileGetChar">cupsFileGetChar</a></h3>
+<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>
</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 </span><a name="cupsFileGetConf">cupsFileGetConf</a></h3>
+<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>
</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 </span><a name="cupsFileGetLine">cupsFileGetLine</a></h3>
+<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">
the number of bytes on the line.
</p>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsFileGets">cupsFileGets</a></h3>
+<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>
</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 </span><a name="cupsFileLock">cupsFileLock</a></h3>
+<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>
</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 </span><a name="cupsFileNumber">cupsFileNumber</a></h3>
+<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>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">File descriptor</p>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsFileOpen">cupsFileOpen</a></h3>
+<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>
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") or appending ("a"), an optional number from
-1 to 9 can be supplied which enables Flate compression of the file.<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
a choice.
</p>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsFileOpenFd">cupsFileOpenFd</a></h3>
+<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>
<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, "a" or "w" to write, or "s"
-to treat the file descriptor as a bidirectional socket connection.<br>
+<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") or appending ("a"), an optional number from
-1 to 9 can be supplied which enables Flate compression of the file.
+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 </span><a name="cupsFilePeekChar">cupsFilePeekChar</a></h3>
+<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>
</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 </span><a name="cupsFilePrintf">cupsFilePrintf</a></h3>
+<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>
</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 </span><a name="cupsFilePutChar">cupsFilePutChar</a></h3>
+<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>
</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 </span><a name="cupsFilePuts">cupsFilePuts</a></h3>
+<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>
<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 </span><a name="cupsFileRead">cupsFileRead</a></h3>
+<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>
</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 </span><a name="cupsFileRewind">cupsFileRewind</a></h3>
+<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">
</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 </span><a name="cupsFileSeek">cupsFileSeek</a></h3>
+<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>
</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 </span><a name="cupsFileStderr">cupsFileStderr</a></h3>
+<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 </span><a name="cupsFileStdin">cupsFileStdin</a></h3>
+<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 </span><a name="cupsFileStdout">cupsFileStdout</a></h3>
+<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 </span><a name="cupsFileTell">cupsFileTell</a></h3>
+<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>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">File position</p>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsFileUnlock">cupsFileUnlock</a></h3>
+<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>
</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 </span><a name="cupsFileWrite">cupsFileWrite</a></h3>
+<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>
projects / thirdparty / cups.git / blobdiff