| Headers | cups/file.h cups/dir.h |
|---|---|
| Library | -lcups |
| See Also | Programming: Introduction to CUPS Programming Programming: CUPS API |
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.
Close a directory.
void cupsDirClose (
cups_dir_t *dp
);
Open a directory.
cups_dir_t *cupsDirOpen (
const char *directory
);
Directory pointer or NULL if the directory could not be opened.
Read the next directory entry.
cups_dentry_t *cupsDirRead (
cups_dir_t *dp
);
Directory entry or NULL when there are no more
Rewind to the start of the directory.
void cupsDirRewind (
cups_dir_t *dp
);
Close a CUPS file.
int cupsFileClose (
cups_file_t *fp
);
0 on success, -1 on error
Return whether a file is compressed.
int cupsFileCompression (
cups_file_t *fp
);
CUPS_FILE_NONE or CUPS_FILE_GZIP
Return the end-of-file status.
int cupsFileEOF (
cups_file_t *fp
);
1 on end of file, 0 otherwise
Find a file using the specified path.
const char *cupsFileFind (
const char *filename,
const char *path,
int executable,
char *buffer,
int bufsize
);
Full path to file or NULL if not found
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.
Flush pending output.
int cupsFileFlush (
cups_file_t *fp
);
0 on success, -1 on error
Get a single character from a file.
int cupsFileGetChar (
cups_file_t *fp
);
Character or -1 on end of file
Get a line from a configuration file.
char *cupsFileGetConf (
cups_file_t *fp,
char *buf,
size_t buflen,
char **value,
int *linenum
);
Line read or NULL on end of file or error
Get a CR and/or LF-terminated line that may contain binary data.
size_t cupsFileGetLine (
cups_file_t *fp,
char *buf,
size_t buflen
);
Number of bytes on line or 0 on end of file
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.
Get a CR and/or LF-terminated line.
char *cupsFileGets (
cups_file_t *fp,
char *buf,
size_t buflen
);
Line read or NULL on end of file or error
Temporarily lock access to a file.
int cupsFileLock (
cups_file_t *fp,
int block
);
0 on success, -1 on error
Return the file descriptor associated with a CUPS file.
int cupsFileNumber (
cups_file_t *fp
);
File descriptor
Open a CUPS file.
cups_file_t *cupsFileOpen (
const char *filename,
const char *mode
);
CUPS file or NULL if the file or socket cannot be opened
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"), 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.
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.
Open a CUPS file using a file descriptor.
cups_file_t *cupsFileOpenFd (
int fd,
const char *mode
);
CUPS file or NULL if the file could not be opened
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.
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.
Peek at the next character from a file.
int cupsFilePeekChar (
cups_file_t *fp
);
Character or -1 on end of file
Write a formatted string.
int cupsFilePrintf (
cups_file_t *fp,
const char *format,
...
);
Number of bytes written or -1 on error
Write a character.
int cupsFilePutChar (
cups_file_t *fp,
int c
);
0 on success, -1 on error
Write a configuration line.
ssize_t cupsFilePutConf (
cups_file_t *fp,
const char *directive,
const char *value
);
Number of bytes written or -1 on error
This function handles any comment escaping of the value.
Write a string.
int cupsFilePuts (
cups_file_t *fp,
const char *s
);
Number of bytes written or -1 on error
Like the fputs function, no newline is appended to the string.
Read from a file.
ssize_t cupsFileRead (
cups_file_t *fp,
char *buf,
size_t bytes
);
Number of bytes read or -1 on error
Set the current file position to the beginning of the file.
off_t cupsFileRewind (
cups_file_t *fp
);
New file position or -1 on error
Seek in a file.
off_t cupsFileSeek (
cups_file_t *fp,
off_t pos
);
New file position or -1 on error
Return a CUPS file associated with stderr.
cups_file_t *cupsFileStderr (void);
CUPS file
Return a CUPS file associated with stdin.
cups_file_t *cupsFileStdin (void);
CUPS file
Return a CUPS file associated with stdout.
cups_file_t *cupsFileStdout (void);
CUPS file
Return the current file position.
off_t cupsFileTell (
cups_file_t *fp
);
File position
Unlock access to a file.
int cupsFileUnlock (
cups_file_t *fp
);
0 on success, -1 on error
Write to a file.
ssize_t cupsFileWrite (
cups_file_t *fp,
const char *buf,
size_t bytes
);
Number of bytes written or -1 on error
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;
Directory entry type
struct cups_dentry_s {
struct stat fileinfo;
char filename[260];
};