The 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.
The <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
All of these functions require CUPS 1.2 or higher.
Close a directory.
void
cupsDirClose(
cups_dir_t * dp);
| Name | Description |
|---|---|
| dp | Directory |
Nothing.
Open a directory.
cups_dir_t *
cupsDirOpen(
const char * directory);
| Name | Description |
|---|---|
| directory | Directory name |
Directory
Read the next directory entry.
cups_dentry_t *
cupsDirRead(
cups_dir_t * dp);
| Name | Description |
|---|---|
| dp | Directory |
Directory entry
Rewind to the start of the directory.
void
cupsDirRewind(
cups_dir_t * dp);
| Name | Description |
|---|---|
| dp | Directory |
Nothing.
Close a CUPS file.
int
cupsFileClose(
cups_file_t * fp);
| Name | Description |
|---|---|
| fp | CUPS file |
0 on success, -1 on error
Return whether a file is compressed.
int
cupsFileCompression(
cups_file_t * fp);
| Name | Description |
|---|---|
| fp | CUPS file |
CUPS_FILE_NONE or CUPS_FILE_GZIP
Return the end-of-file status.
int
cupsFileEOF(
cups_file_t * fp);
| Name | Description |
|---|---|
| fp | CUPS file |
1 on EOF, 0 otherwise
Find 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.
const char *
cupsFileFind(
const char * filename,
const char * path,
int executable,
char * buffer,
int bufsize);
| Name | Description |
|---|---|
| filename | File to find |
| path | Colon/semicolon-separated path |
| executable | 1 = executable files, 0 = any file/dir |
| buffer | Filename buffer |
| bufsize | Size of filename buffer |
Full path to file or NULL
Flush pending output.
int
cupsFileFlush(
cups_file_t * fp);
| Name | Description |
|---|---|
| fp | CUPS file |
0 on success, -1 on error
Get a single character from a file.
int
cupsFileGetChar(
cups_file_t * fp);
| Name | Description |
|---|---|
| fp | CUPS file |
Character or -1 on EOF
Get a line from a configuration file...
char *
cupsFileGetConf(
cups_file_t * fp,
char * buf,
size_t buflen,
char ** value,
int * linenum);
| Name | Description |
|---|---|
| fp | CUPS file |
| buf | String buffer |
| buflen | Size of string buffer |
| value | Pointer to value |
| linenum | Current line number |
Line read or NULL on eof/error
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 the number of bytes on the line.
size_t
cupsFileGetLine(
cups_file_t * fp,
char * buf,
size_t buflen);
| Name | Description |
|---|---|
| fp | File to read from |
| buf | Buffer |
| buflen | Size of buffer |
Number of bytes on line or 0 on EOF
Get a CR and/or LF-terminated line.
char *
cupsFileGets(
cups_file_t * fp,
char * buf,
size_t buflen);
| Name | Description |
|---|---|
| fp | CUPS file |
| buf | String buffer |
| buflen | Size of string buffer |
Line read or NULL on eof/error
Temporarily lock access to a file.
int
cupsFileLock(
cups_file_t * fp,
int block);
| Name | Description |
|---|---|
| fp | File to lock |
| block | 1 to wait for the lock, 0 to fail right away |
0 on success, -1 on error
Return the file descriptor associated with a CUPS file.
int
cupsFileNumber(
cups_file_t * fp);
| Name | Description |
|---|---|
| fp | CUPS file |
File descriptor
Open a CUPS file.
cups_file_t *
cupsFileOpen(
const char * filename,
const char * mode);
| Name | Description |
|---|---|
| filename | Name of file |
| mode | Open mode |
CUPS file or NULL
Open a CUPS file using a file descriptor.
cups_file_t *
cupsFileOpenFd(
int fd,
const char * mode);
| Name | Description |
|---|---|
| fd | File descriptor |
| mode | Open mode |
CUPS file or NULL
Peek at the next character from a file.
int
cupsFilePeekChar(
cups_file_t * fp);
| Name | Description |
|---|---|
| fp | CUPS file |
Character or -1 on EOF
Write a formatted string.
int
cupsFilePrintf(
cups_file_t * fp,
const char * format,
...);
| Name | Description |
|---|---|
| fp | CUPS file |
| format | Printf-style format string |
| ... | Additional args as necessary |
Number of bytes written or -1
Write a character.
int
cupsFilePutChar(
cups_file_t * fp,
int c);
| Name | Description |
|---|---|
| fp | CUPS file |
| c | Character to write |
0 on success, -1 on error
Write a string.
int
cupsFilePuts(
cups_file_t * fp,
const char * s);
| Name | Description |
|---|---|
| fp | CUPS file |
| s | String to write |
Number of bytes written or -1
Read from a file.
ssize_t
cupsFileRead(
cups_file_t * fp,
char * buf,
size_t bytes);
| Name | Description |
|---|---|
| fp | CUPS file |
| buf | Buffer |
| bytes | Number of bytes to read |
Number of bytes read or -1
Rewind a file.
off_t
cupsFileRewind(
cups_file_t * fp);
| Name | Description |
|---|---|
| fp | CUPS file |
New file position or -1
Seek in a file.
off_t
cupsFileSeek(
cups_file_t * fp,
off_t pos);
| Name | Description |
|---|---|
| fp | CUPS file |
| pos | Position in file |
New file position or -1
Just reposition the current pointer, since we have the right range...
cups_file_t *
cupsFileStderr(void);
None.
Return a CUPS file associated with stderr.
Open file descriptor 2...
cups_file_t *
cupsFileStdin(void);
None.
Return a CUPS file associated with stdin.
Open file descriptor 0...
cups_file_t *
cupsFileStdout(void);
None.
Return a CUPS file associated with stdout.
Return the current file position.
off_t
cupsFileTell(
cups_file_t * fp);
| Name | Description |
|---|---|
| fp | CUPS file |
File position
Unlock access to a file.
int
cupsFileUnlock(
cups_file_t * fp);
| Name | Description |
|---|---|
| fp | File to lock |
0 on success, -1 on error
Write to a file.
ssize_t
cupsFileWrite(
cups_file_t * fp,
const char * buf,
size_t bytes);
| Name | Description |
|---|---|
| fp | CUPS file |
| buf | Buffer |
| bytes | Number of bytes to write |
Number of bytes written
Directory entry type
struct cups_dentry_s
{
struct stat fileinfo;
char filename[260];
};
| Name | Description |
|---|---|
| fileinfo | File information |
| filename[260] | File name |
Directory entry type
typedef struct cups_dentry_s cups_dentry_t;
Directory type
typedef struct _cups_dir_s cups_dir_t;
CUPS file type
typedef struct _cups_file_s cups_file_t;