* our own file functions allows us to provide transparent support of
* gzip'd print files, PPD files, etc.
*
- * Copyright 2007 by Apple Inc.
+ * Copyright 2007-2008 by Apple Inc.
* Copyright 1997-2007 by Easy Software Products, all rights reserved.
*
* These coded instructions, statements, and computer programs are the
* cupsFileFlush() - Flush pending output.
* cupsFileGetChar() - Get a single character from a file.
* cupsFileGetConf() - Get a line from a configuration file...
- * cupsFileGetLine() - Get a CR and/or LF-terminated line that may
- * contain binary data.
+ * cupsFileGetLine() - Get a CR and/or LF-terminated line that may contain
+ * binary data.
* cupsFileGets() - Get a CR and/or LF-terminated line.
* cupsFileLock() - Temporarily lock access to a file.
* cupsFileNumber() - Return the file descriptor associated with a CUPS
* cupsFilePutChar() - Write a character.
* cupsFilePuts() - Write a string.
* cupsFileRead() - Read from a file.
- * cupsFileRewind() - Rewind a file.
+ * cupsFileRewind() - Set the current file position to the beginning of
+ * the file.
* cupsFileSeek() - Seek in a file.
* cupsFileStderr() - Return a CUPS file associated with stderr.
* cupsFileStdin() - Return a CUPS file associated with stdin.
/*
* 'cupsFileClose()' - Close a CUPS file.
+ *
+ * @since CUPS 1.2@
*/
int /* O - 0 on success, -1 on error */
/*
* 'cupsFileCompression()' - Return whether a file is compressed.
+ *
+ * @since CUPS 1.2@
*/
-int /* O - CUPS_FILE_NONE or CUPS_FILE_GZIP */
+int /* O - @code CUPS_FILE_NONE@ or @code CUPS_FILE_GZIP@ */
cupsFileCompression(cups_file_t *fp) /* I - CUPS file */
{
return (fp ? fp->compressed : CUPS_FILE_NONE);
/*
* 'cupsFileEOF()' - Return the end-of-file status.
+ *
+ * @since CUPS 1.2@
*/
-int /* O - 1 on EOF, 0 otherwise */
+int /* O - 1 on end of file, 0 otherwise */
cupsFileEOF(cups_file_t *fp) /* I - CUPS file */
{
return (fp ? fp->eof : 1);
* 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, NULL is returned. A NULL path only matches the
- * current directory.
+ * the supplied paths, @code NULL@ is returned. A @code NULL@ path only
+ * matches the current directory.
+ *
+ * @since CUPS 1.2@
*/
-const char * /* O - Full path to file or NULL */
+const char * /* O - Full path to file or @code NULL@ if not found */
cupsFileFind(const char *filename, /* I - File to find */
const char *path, /* I - Colon/semicolon-separated path */
int executable, /* I - 1 = executable files, 0 = any file/dir */
/*
* 'cupsFileFlush()' - Flush pending output.
+ *
+ * @since CUPS 1.2@
*/
int /* O - 0 on success, -1 on error */
/*
* 'cupsFileGetChar()' - Get a single character from a file.
+ *
+ * @since CUPS 1.2@
*/
-int /* O - Character or -1 on EOF */
+int /* O - Character or -1 on end of file */
cupsFileGetChar(cups_file_t *fp) /* I - CUPS file */
{
/*
/*
* 'cupsFileGetConf()' - Get a line from a configuration file...
+ *
+ * @since CUPS 1.2@
*/
-char * /* O - Line read or NULL on eof/error */
+char * /* O - Line read or @code NULL@ on end of file or error */
cupsFileGetConf(cups_file_t *fp, /* I - CUPS file */
char *buf, /* O - String buffer */
size_t buflen, /* I - Size of string buffer */
* 'cupsFileGetLine()' - Get a CR and/or LF-terminated line that may
* contain binary data.
*
- * This function differs from cupsFileGets() 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
+ * This function differs from @link cupsFileGets@ 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.
+ *
+ * @since CUPS 1.2@
*/
-size_t /* O - Number of bytes on line or 0 on EOF */
+size_t /* O - Number of bytes on line or 0 on end of file */
cupsFileGetLine(cups_file_t *fp, /* I - File to read from */
char *buf, /* I - Buffer */
size_t buflen) /* I - Size of buffer */
/*
* 'cupsFileGets()' - Get a CR and/or LF-terminated line.
+ *
+ * @since CUPS 1.2@
*/
-char * /* O - Line read or NULL on eof/error */
+char * /* O - Line read or @code NULL@ on end of file or error */
cupsFileGets(cups_file_t *fp, /* I - CUPS file */
char *buf, /* O - String buffer */
size_t buflen) /* I - Size of string buffer */
/*
* 'cupsFileLock()' - Temporarily lock access to a file.
+ *
+ * @since CUPS 1.2@
*/
int /* O - 0 on success, -1 on error */
-cupsFileLock(cups_file_t *fp, /* I - File to lock */
+cupsFileLock(cups_file_t *fp, /* I - CUPS file */
int block) /* I - 1 to wait for the lock, 0 to fail right away */
{
/*
/*
* 'cupsFileNumber()' - Return the file descriptor associated with a CUPS file.
+ *
+ * @since CUPS 1.2@
*/
int /* O - File descriptor */
cupsFileNumber(cups_file_t *fp) /* I - CUPS file */
{
- return (fp->fd);
+ if (fp)
+ return (fp->fd);
+ else
+ return (-1);
}
/*
* 'cupsFileOpen()' - Open a CUPS file.
+ *
+ * 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.
+ *
+ * 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 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.
+ *
+ * @since CUPS 1.2@
*/
-cups_file_t * /* O - CUPS file or NULL */
+cups_file_t * /* O - CUPS file or @code NULL@ if the file or socket cannot be opened */
cupsFileOpen(const char *filename, /* I - Name of file */
const char *mode) /* I - Open mode */
{
/*
* 'cupsFileOpenFd()' - Open a CUPS file using a file descriptor.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * @since CUPS 1.2@
*/
-cups_file_t * /* O - CUPS file or NULL */
+cups_file_t * /* O - CUPS file or @code NULL@ if the file could not be opened */
cupsFileOpenFd(int fd, /* I - File descriptor */
const char *mode) /* I - Open mode */
{
/*
* 'cupsFilePeekChar()' - Peek at the next character from a file.
+ *
+ * @since CUPS 1.2@
*/
-int /* O - Character or -1 on EOF */
+int /* O - Character or -1 on end of file */
cupsFilePeekChar(cups_file_t *fp) /* I - CUPS file */
{
/*
/*
* 'cupsFilePrintf()' - Write a formatted string.
+ *
+ * @since CUPS 1.2@
*/
-int /* O - Number of bytes written or -1 */
+int /* O - Number of bytes written or -1 on error */
cupsFilePrintf(cups_file_t *fp, /* I - CUPS file */
const char *format, /* I - Printf-style format string */
...) /* I - Additional args as necessary */
/*
* 'cupsFilePutChar()' - Write a character.
+ *
+ * @since CUPS 1.2@
*/
int /* O - 0 on success, -1 on error */
/*
* 'cupsFilePuts()' - Write a string.
+ *
+ * Like the @code fputs@ function, no newline is appended to the string.
+ *
+ * @since CUPS 1.2@
*/
-int /* O - Number of bytes written or -1 */
+int /* O - Number of bytes written or -1 on error */
cupsFilePuts(cups_file_t *fp, /* I - CUPS file */
const char *s) /* I - String to write */
{
/*
* 'cupsFileRead()' - Read from a file.
+ *
+ * @since CUPS 1.2@
*/
-ssize_t /* O - Number of bytes read or -1 */
+ssize_t /* O - Number of bytes read or -1 on error */
cupsFileRead(cups_file_t *fp, /* I - CUPS file */
char *buf, /* O - Buffer */
size_t bytes) /* I - Number of bytes to read */
/*
- * 'cupsFileRewind()' - Rewind a file.
+ * 'cupsFileRewind()' - Set the current file position to the beginning of the
+ * file.
+ *
+ * @since CUPS 1.2@
*/
-off_t /* O - New file position or -1 */
+off_t /* O - New file position or -1 on error */
cupsFileRewind(cups_file_t *fp) /* I - CUPS file */
{
/*
/*
* 'cupsFileSeek()' - Seek in a file.
+ *
+ * @since CUPS 1.2@
*/
-off_t /* O - New file position or -1 */
+off_t /* O - New file position or -1 on error */
cupsFileSeek(cups_file_t *fp, /* I - CUPS file */
off_t pos) /* I - Position in file */
{
/*
* 'cupsFileStderr()' - Return a CUPS file associated with stderr.
+ *
+ * @since CUPS 1.2@
*/
-cups_file_t *
+cups_file_t * /* O - CUPS file */
cupsFileStderr(void)
{
_cups_globals_t *cg = _cupsGlobals(); /* Pointer to library globals... */
/*
* 'cupsFileStdin()' - Return a CUPS file associated with stdin.
+ *
+ * @since CUPS 1.2@
*/
-cups_file_t *
+cups_file_t * /* O - CUPS file */
cupsFileStdin(void)
{
_cups_globals_t *cg = _cupsGlobals(); /* Pointer to library globals... */
/*
* 'cupsFileStdout()' - Return a CUPS file associated with stdout.
+ *
+ * @since CUPS 1.2@
*/
-cups_file_t *
+cups_file_t * /* O - CUPS file */
cupsFileStdout(void)
{
_cups_globals_t *cg = _cupsGlobals(); /* Pointer to library globals... */
/*
* 'cupsFileTell()' - Return the current file position.
+ *
+ * @since CUPS 1.2@
*/
off_t /* O - File position */
/*
* 'cupsFileUnlock()' - Unlock access to a file.
+ *
+ * @since CUPS 1.2@
*/
int /* O - 0 on success, -1 on error */
-cupsFileUnlock(cups_file_t *fp) /* I - File to lock */
+cupsFileUnlock(cups_file_t *fp) /* I - CUPS file */
{
/*
* Range check...
/*
* 'cupsFileWrite()' - Write to a file.
+ *
+ * @since CUPS 1.2@
*/
-ssize_t /* O - Number of bytes written */
+ssize_t /* O - Number of bytes written or -1 on error */
cupsFileWrite(cups_file_t *fp, /* I - CUPS file */
const char *buf, /* I - Buffer */
size_t bytes) /* I - Number of bytes to write */
projects / thirdparty / cups.git / blobdiff