[thirdparty/cups.git] / doc / help / api-filedir.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/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">
<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 {
  margin-left: 36pt;
}

PRE.example {
  background: #eeeeee;
  border: dotted thin #999999;
  margin-left: 36pt;
  padding: 10px;
}

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: #cccccc;
  border: solid thin #999999;
  padding: 10pt;
}

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%;
}

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 {
  padding-top: 5pt;
  text-align: right;
  vertical-align: top;
}

HR {
  border: solid thin;
}

SPAN.info {
  background: #000000;
  border: thin solid #000000;
  color: #ffffff;
  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%;
}

H2.title, H3.title {
  border-bottom: solid 2pt #000000;
}

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;
}

SPAN.message {
  font-style: italic;
  font-size: smaller;
}

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: api-filedir.header 7279 2008-01-31 01:50:44Z mike $"

  File and Directory API header for the Common UNIX Printing System (CUPS).

  Copyright 2008 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>
<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="#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><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: api-filedir.shtml 7279 2008-01-31 01:50:44Z mike $"

  File and directory API introduction for the Common UNIX Printing System (CUPS).

  Copyright 2007-2008 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">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsDirClose">cupsDirClose</a></h3>
<p class="description">Close a directory.</p>
<p class="code">
void cupsDirClose (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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">&nbsp;CUPS 1.2&nbsp;</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>
&nbsp;&nbsp;&nbsp;&nbsp;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">&nbsp;CUPS 1.2&nbsp;</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>
&nbsp;&nbsp;&nbsp;&nbsp;<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">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsDirRewind">cupsDirRewind</a></h3>
<p class="description">Rewind to the start of the directory.</p>
<p class="code">
void cupsDirRewind (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsFileClose">cupsFileClose</a></h3>
<p class="description">Close a CUPS file.</p>
<p class="code">
int cupsFileClose (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsFileCompression">cupsFileCompression</a></h3>
<p class="description">Return whether a file is compressed.</p>
<p class="code">
int cupsFileCompression (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsFileEOF">cupsFileEOF</a></h3>
<p class="description">Return the end-of-file status.</p>
<p class="code">
int cupsFileEOF (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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">&nbsp;CUPS 1.2&nbsp;</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>
&nbsp;&nbsp;&nbsp;&nbsp;const char *filename,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *path,<br>
&nbsp;&nbsp;&nbsp;&nbsp;int executable,<br>
&nbsp;&nbsp;&nbsp;&nbsp;char *buffer,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsFileFlush">cupsFileFlush</a></h3>
<p class="description">Flush pending output.</p>
<p class="code">
int cupsFileFlush (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsFileGetChar">cupsFileGetChar</a></h3>
<p class="description">Get a single character from a file.</p>
<p class="code">
int cupsFileGetChar (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsFileGetConf">cupsFileGetConf</a></h3>
<p class="description">Get a line from a configuration file...</p>
<p class="code">
char *cupsFileGetConf (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp,<br>
&nbsp;&nbsp;&nbsp;&nbsp;char *buf,<br>
&nbsp;&nbsp;&nbsp;&nbsp;size_t buflen,<br>
&nbsp;&nbsp;&nbsp;&nbsp;char **value,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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">&nbsp;CUPS 1.2&nbsp;</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>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp,<br>
&nbsp;&nbsp;&nbsp;&nbsp;char *buf,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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">&nbsp;CUPS 1.2&nbsp;</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>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp,<br>
&nbsp;&nbsp;&nbsp;&nbsp;char *buf,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsFileLock">cupsFileLock</a></h3>
<p class="description">Temporarily lock access to a file.</p>
<p class="code">
int cupsFileLock (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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">&nbsp;CUPS 1.2&nbsp;</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>
&nbsp;&nbsp;&nbsp;&nbsp;<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">&nbsp;CUPS 1.2&nbsp;</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>
&nbsp;&nbsp;&nbsp;&nbsp;const char *filename,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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 &quot;mode&quot; parameter can be &quot;r&quot; to read, &quot;w&quot; to write, overwriting any
existing file, &quot;a&quot; to append to an existing file or create a new file,
or &quot;s&quot; to open a socket connection.<br>
<br>
When opening for writing (&quot;w&quot;), an optional number from 1 to 9 can be
supplied which enables Flate compression of the file.  Compression is
not supported for the &quot;a&quot; (append) mode.<br>
<br>
When opening a socket connection, the filename is a string of the form
&quot;address:port&quot; or &quot;hostname:port&quot;. 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">&nbsp;CUPS 1.2&nbsp;</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>
&nbsp;&nbsp;&nbsp;&nbsp;int fd,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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 &quot;mode&quot; parameter can be &quot;r&quot; to read, &quot;w&quot; to write, &quot;a&quot; to append,
or &quot;s&quot; to treat the file descriptor as a bidirectional socket connection.<br>
<br>
When opening for writing (&quot;w&quot;), an optional number from 1 to 9 can be
supplied which enables Flate compression of the file.  Compression is
not supported for the &quot;a&quot; (append) mode.

</p>
<h3 class="function"><span class="info">&nbsp;CUPS 1.2&nbsp;</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>
&nbsp;&nbsp;&nbsp;&nbsp;<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">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsFilePrintf">cupsFilePrintf</a></h3>
<p class="description">Write a formatted string.</p>
<p class="code">
int cupsFilePrintf (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *format,<br>
&nbsp;&nbsp;&nbsp;&nbsp;...<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">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsFilePutChar">cupsFilePutChar</a></h3>
<p class="description">Write a character.</p>
<p class="code">
int cupsFilePutChar (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsFilePuts">cupsFilePuts</a></h3>
<p class="description">Write a string.</p>
<p class="code">
int cupsFilePuts (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsFileRead">cupsFileRead</a></h3>
<p class="description">Read from a file.</p>
<p class="code">
ssize_t cupsFileRead (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp,<br>
&nbsp;&nbsp;&nbsp;&nbsp;char *buf,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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">&nbsp;CUPS 1.2&nbsp;</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>
&nbsp;&nbsp;&nbsp;&nbsp;<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">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsFileSeek">cupsFileSeek</a></h3>
<p class="description">Seek in a file.</p>
<p class="code">
off_t cupsFileSeek (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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">&nbsp;CUPS 1.2&nbsp;</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">&nbsp;CUPS 1.2&nbsp;</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">&nbsp;CUPS 1.2&nbsp;</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">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsFileTell">cupsFileTell</a></h3>
<p class="description">Return the current file position.</p>
<p class="code">
off_t cupsFileTell (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsFileUnlock">cupsFileUnlock</a></h3>
<p class="description">Unlock access to a file.</p>
<p class="code">
int cupsFileUnlock (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<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">&nbsp;CUPS 1.2&nbsp;</span><a name="cupsFileWrite">cupsFileWrite</a></h3>
<p class="description">Write to a file.</p>
<p class="code">
ssize_t cupsFileWrite (<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_file_t">cups_file_t</a> *fp,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *buf,<br>
&nbsp;&nbsp;&nbsp;&nbsp;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>
&nbsp;&nbsp;&nbsp;&nbsp;struct stat fileinfo;<br>
&nbsp;&nbsp;&nbsp;&nbsp;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>