Documentation
Login 
CUPS Book DDK Printer Drivers ESP Ghostscript Forums Links Windows
IntroductionThe CUPS file and directory APIs provide portable interfaces for manipulating files and listing files and directories. Unlike stdio FILE streams, the cupsFile 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 cupsFile functions. The cupsDir 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. The CUPS scheduler (cupsd), mailto notifier, and many of the CUPS API functions use these functions for everything except console (stdin, stdout, stderr) I/O. General UsageThe <cups/dir.h> and <cups/file.h> header files must be included to use the cupsDir and cupsFile functions, respectively. Programs using these functions must be linked to the CUPS library: libcups.a, libcups.so.2, libcups.2.dylib, libcups_s.a, or libcups2.lib depending on the platform. The following command compiles myprogram.c using GCC and the CUPS library: gcc -o myprogram myprogram.c -lcups CompatibilityAll of these functions require CUPS 1.2 or higher. ContentsFunctions
cupsDirClose()DescriptionClose a directory. Syntax
void Arguments
ReturnsNothing. cupsDirOpen()DescriptionOpen a directory. Syntax
cups_dir_t * Arguments
ReturnsDirectory cupsDirRead()DescriptionRead the next directory entry. Syntax
cups_dentry_t * Arguments
ReturnsDirectory entry cupsDirRewind()DescriptionRewind to the start of the directory. Syntax
void Arguments
ReturnsNothing. cupsFileClose()DescriptionClose a CUPS file. Syntax
int Arguments
Returns0 on success, -1 on error cupsFileCompression()DescriptionReturn whether a file is compressed. Syntax
int Arguments
ReturnsCUPS_FILE_NONE or CUPS_FILE_GZIP cupsFileEOF()DescriptionReturn the end-of-file status. Syntax
int Arguments
Returns1 on EOF, 0 otherwise cupsFileFind()DescriptionFind a file using the specified path. 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. Syntax
const char * Arguments
ReturnsFull path to file or NULL cupsFileFlush()DescriptionFlush pending output. Syntax
int Arguments
Returns0 on success, -1 on error cupsFileGetChar()DescriptionGet a single character from a file. Syntax
int Arguments
ReturnsCharacter or -1 on EOF cupsFileGetConf()DescriptionGet a line from a configuration file... Syntax
char * Arguments
ReturnsLine read or NULL on eof/error cupsFileGetLine()DescriptionGet 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 the number of bytes on the line. Syntax
size_t Arguments
ReturnsNumber of bytes on line or 0 on EOF cupsFileGets()DescriptionGet a CR and/or LF-terminated line. Syntax
char * Arguments
ReturnsLine read or NULL on eof/error cupsFileLock()DescriptionTemporarily lock access to a file. Syntax
int Arguments
Returns0 on success, -1 on error cupsFileNumber()DescriptionReturn the file descriptor associated with a CUPS file. Syntax
int Arguments
ReturnsFile descriptor cupsFileOpen()DescriptionOpen a CUPS file. Syntax
cups_file_t * Arguments
ReturnsCUPS file or NULL cupsFileOpenFd()DescriptionOpen a CUPS file using a file descriptor. Syntax
cups_file_t * Arguments
ReturnsCUPS file or NULL cupsFilePeekChar()DescriptionPeek at the next character from a file. Syntax
int Arguments
ReturnsCharacter or -1 on EOF cupsFilePrintf()DescriptionWrite a formatted string. Syntax
int Arguments
ReturnsNumber of bytes written or -1 cupsFilePutChar()DescriptionWrite a character. Syntax
int Arguments
Returns0 on success, -1 on error cupsFilePuts()DescriptionWrite a string. Syntax
int Arguments
ReturnsNumber of bytes written or -1 cupsFileRead()DescriptionRead from a file. Syntax
ssize_t Arguments
ReturnsNumber of bytes read or -1 cupsFileRewind()DescriptionRewind a file. Syntax
off_t Arguments
ReturnsNew file position or -1 cupsFileSeek()DescriptionSeek in a file. Syntax
off_t Arguments
ReturnsNew file position or -1 cupsFileStderr()DescriptionJust reposition the current pointer, since we have the right range... Syntax
cups_file_t * ArgumentsNone. ReturnsReturn a CUPS file associated with stderr. cupsFileStdin()DescriptionOpen file descriptor 2... Syntax
cups_file_t * ArgumentsNone. ReturnsReturn a CUPS file associated with stdin. cupsFileStdout()DescriptionOpen file descriptor 0... Syntax
cups_file_t * ArgumentsNone. ReturnsReturn a CUPS file associated with stdout. cupsFileTell()DescriptionReturn the current file position. Syntax
off_t Arguments
ReturnsFile position cupsFileUnlock()DescriptionUnlock access to a file. Syntax
int Arguments
Returns0 on success, -1 on error cupsFileWrite()DescriptionWrite to a file. Syntax
ssize_t Arguments
ReturnsNumber of bytes written Structurescups_dentry_sDescriptionDirectory entry type Definition
struct cups_dentry_s Members
Typescups_dentry_tDescriptionDirectory entry type Definitiontypedef struct cups_dentry_s cups_dentry_t; cups_dir_tDescriptionDirectory type Definitiontypedef struct _cups_dir_s cups_dir_t; cups_file_tDescriptionCUPS file type Definitiontypedef struct _cups_file_s cups_file_t; |
Comments are owned by the poster. All other content is copyright 2007-2008 by Apple Inc. CUPS, the Common UNIX Printing System, and the CUPS logo are the trademark property of Apple Inc. All other trademarks are the property of their respective owners. Please report site problems to 'webmaster@cups.org'.
