| 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
+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.
cupsFile functions.
-The cupsDir functions manage the platform-specific +
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.
-
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.
- -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.
-
The <cups/dir.h> and -<cups/file.h> header files must be included to -use the cupsDir and cupsFile functions, -respectively.
+ +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.
-
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:
+ +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.
-
-gcc -o myprogram myprogram.c -lcups -+ +
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.
-
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.
--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
- -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
-+ +CUPS 1.2/Mac OS X 10.5 cupsFileRead
+Read from a file.
++ssize_t cupsFileRead (
+
+ cups_file_t *fp,
+ char *buf,
+ size_t bytes
+);Parameters
+
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
-+ ++ +cups_file_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];
+};