File and Directory APIs
Keywords: Programming

## Introduction

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.

## General Usage

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

## Compatibility

All of these functions require CUPS 1.2 or higher.

## Contents

- Functions
- Structures
- Types

## Functions

- `cupsDirClose()`
- `cupsDirOpen()`
- `cupsDirRead()`
- `cupsDirRewind()`
- `cupsFileClose()`
- `cupsFileCompression()`
- `cupsFileEOF()`
- `cupsFileFind()`
- `cupsFileFlush()`
- `cupsFileGetChar()`
- `cupsFileGetConf()`
- `cupsFileGetLine()`
- `cupsFileGets()`
- `cupsFileLock()`
- `cupsFileNumber()`
- `cupsFileOpen()`
- `cupsFileOpenFd()`
- `cupsFilePeekChar()`
- `cupsFilePrintf()`
- `cupsFilePutChar()`
- `cupsFilePuts()`
- `cupsFileRead()`
- `cupsFileRewind()`
- `cupsFileSeek()`
- `cupsFileStderr()`
- `cupsFileStdin()`
- `cupsFileStdout()`
- `cupsFileTell()`
- `cupsFileUnlock()`
- `cupsFileWrite()`

### cupsDirClose()

#### Description

Close a directory.

#### Syntax

`void
cupsDirClose( cups_dir_t * dp);`

#### Arguments

Name | Description
--- | ---
`dp` | Directory

#### Returns

Nothing.

### cupsDirOpen()

#### Description

Open a directory.

#### Syntax

`cups_dir_t *
cupsDirOpen( const char * directory);`

#### Arguments

Name | Description
--- | ---
`directory` | Directory name

#### Returns

Directory

### cupsDirRead()

#### Description

Read the next directory entry.

#### Syntax

`cups_dentry_t *
cupsDirRead( cups_dir_t * dp);`

#### Arguments

Name | Description
--- | ---
`dp` | Directory

#### Returns

Directory entry

### cupsDirRewind()

#### Description

Rewind to the start of the directory.

#### Syntax

`void
cupsDirRewind( cups_dir_t * dp);`

#### Arguments

Name | Description
--- | ---
`dp` | Directory

#### Returns

Nothing.

### cupsFileClose()

#### Description

Close a CUPS file.

#### Syntax

`int
cupsFileClose( cups_file_t * fp);`

#### Arguments

Name | Description
--- | ---
`fp` | CUPS file

#### Returns

0 on success, -1 on error

### cupsFileCompression()

#### Description

Return whether a file is compressed.

#### Syntax

`int
cupsFileCompression( cups_file_t * fp);`

#### Arguments

Name | Description
--- | ---
`fp` | CUPS file

#### Returns

CUPS_FILE_NONE or CUPS_FILE_GZIP

### cupsFileEOF()

#### Description

Return the end-of-file status.

#### Syntax

`int
cupsFileEOF( cups_file_t * fp);`

#### Arguments

Name | Description
--- | ---
`fp` | CUPS file

#### Returns

1 on EOF, 0 otherwise

### cupsFileFind()

#### Description

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.

#### Syntax

`const char *
cupsFileFind( const char * filename, const char * path, int executable, char * buffer, int bufsize);`

#### Arguments

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

#### Returns

Full path to file or NULL

### cupsFileFlush()

#### Description

Flush pending output.

#### Syntax

`int
cupsFileFlush( cups_file_t * fp);`

#### Arguments

Name | Description
--- | ---
`fp` | CUPS file

#### Returns

0 on success, -1 on error

### cupsFileGetChar()

#### Description

Get a single character from a file.

#### Syntax

`int
cupsFileGetChar( cups_file_t * fp);`

#### Arguments

Name | Description
--- | ---
`fp` | CUPS file

#### Returns

Character or -1 on EOF

### cupsFileGetConf()

#### Description

Get a line from a configuration file...

#### Syntax

`char *
cupsFileGetConf( cups_file_t * fp, char * buf, size_t buflen, char ** value, int * linenum);`

#### Arguments

Name | Description
--- | ---
`fp` | CUPS file
`buf` | String buffer
`buflen` | Size of string buffer
`value` | Pointer to value
`linenum` | Current line number

#### Returns

Line read or NULL on eof/error

### cupsFileGetLine()

#### Description

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.

#### Syntax

`size_t
cupsFileGetLine( cups_file_t * fp, char * buf, size_t buflen);`

#### Arguments

Name | Description
--- | ---
`fp` | File to read from
`buf` | Buffer
`buflen` | Size of buffer

#### Returns

Number of bytes on line or 0 on EOF

### cupsFileGets()

#### Description

Get a CR and/or LF-terminated line.

#### Syntax

`char *
cupsFileGets( cups_file_t * fp, char * buf, size_t buflen);`

#### Arguments

Name | Description
--- | ---
`fp` | CUPS file
`buf` | String buffer
`buflen` | Size of string buffer

#### Returns

Line read or NULL on eof/error

### cupsFileLock()

#### Description

Temporarily lock access to a file.

#### Syntax

`int
cupsFileLock( cups_file_t * fp, int block);`

#### Arguments

Name | Description
--- | ---
`fp` | File to lock
`block` | 1 to wait for the lock, 0 to fail right away

#### Returns

0 on success, -1 on error

### cupsFileNumber()

#### Description

Return the file descriptor associated with a CUPS file.

#### Syntax

`int
cupsFileNumber( cups_file_t * fp);`

#### Arguments

Name | Description
--- | ---
`fp` | CUPS file

#### Returns

File descriptor

### cupsFileOpen()

#### Description

Open a CUPS file.

#### Syntax

`cups_file_t *
cupsFileOpen( const char * filename, const char * mode);`

#### Arguments

Name | Description
--- | ---
`filename` | Name of file
`mode` | Open mode

#### Returns

CUPS file or NULL

### cupsFileOpenFd()

#### Description

Open a CUPS file using a file descriptor.

#### Syntax

`cups_file_t *
cupsFileOpenFd( int fd, const char * mode);`

#### Arguments

Name | Description
--- | ---
`fd` | File descriptor
`mode` | Open mode

#### Returns

CUPS file or NULL

### cupsFilePeekChar()

#### Description

Peek at the next character from a file.

#### Syntax

`int
cupsFilePeekChar( cups_file_t * fp);`

#### Arguments

Name | Description
--- | ---
`fp` | CUPS file

#### Returns

Character or -1 on EOF

### cupsFilePrintf()

#### Description

Write a formatted string.

#### Syntax

`int
cupsFilePrintf( cups_file_t * fp, const char * format, ...);`

#### Arguments

Name | Description
--- | ---
`fp` | CUPS file
`format` | Printf-style format string
`...` | Additional args as necessary

#### Returns

Number of bytes written or -1

### cupsFilePutChar()

#### Description

Write a character.

#### Syntax

`int
cupsFilePutChar( cups_file_t * fp, int c);`

#### Arguments

Name | Description
--- | ---
`fp` | CUPS file
`c` | Character to write

#### Returns

0 on success, -1 on error

### cupsFilePuts()

#### Description

Write a string.

#### Syntax

`int
cupsFilePuts( cups_file_t * fp, const char * s);`

#### Arguments

Name | Description
--- | ---
`fp` | CUPS file
`s` | String to write

#### Returns

Number of bytes written or -1

### cupsFileRead()

#### Description

Read from a file.

#### Syntax

`ssize_t
cupsFileRead( cups_file_t * fp, char * buf, size_t bytes);`

#### Arguments

Name | Description
--- | ---
`fp` | CUPS file
`buf` | Buffer
`bytes` | Number of bytes to read

#### Returns

Number of bytes read or -1

### cupsFileRewind()

#### Description

Rewind a file.

#### Syntax

`off_t
cupsFileRewind( cups_file_t * fp);`

#### Arguments

Name | Description
--- | ---
`fp` | CUPS file

#### Returns

New file position or -1

### cupsFileSeek()

#### Description

Seek in a file.

#### Syntax

`off_t
cupsFileSeek( cups_file_t * fp, off_t pos);`

#### Arguments

Name | Description
--- | ---
`fp` | CUPS file
`pos` | Position in file

#### Returns

New file position or -1

### cupsFileStderr()

#### Description

Just reposition the current pointer, since we have the right range...

#### Syntax

`cups_file_t *
cupsFileStderr(void);`

#### Arguments

None.

#### Returns

Return a CUPS file associated with stderr.

### cupsFileStdin()

#### Description

Open file descriptor 2...

#### Syntax

`cups_file_t *
cupsFileStdin(void);`

#### Arguments

None.

#### Returns

Return a CUPS file associated with stdin.

### cupsFileStdout()

#### Description

Open file descriptor 0...

#### Syntax

`cups_file_t *
cupsFileStdout(void);`

#### Arguments

None.

#### Returns

Return a CUPS file associated with stdout.

### cupsFileTell()

#### Description

Return the current file position.

#### Syntax

`off_t
cupsFileTell( cups_file_t * fp);`

#### Arguments

Name | Description
--- | ---
`fp` | CUPS file

#### Returns

File position

### cupsFileUnlock()

#### Description

Unlock access to a file.

#### Syntax

`int
cupsFileUnlock( cups_file_t * fp);`

#### Arguments

Name | Description
--- | ---
`fp` | File to lock

#### Returns

0 on success, -1 on error

### cupsFileWrite()

#### Description

Write to a file.

#### Syntax

`ssize_t
cupsFileWrite( cups_file_t * fp, const char * buf, size_t bytes);`

#### Arguments

Name | Description
--- | ---
`fp` | CUPS file
`buf` | Buffer
`bytes` | Number of bytes to write

#### Returns

Number of bytes written

## Structures

- `cups_dentry_s`

### cups_dentry_s

#### Description

Directory entry type

#### Definition

`struct cups_dentry_s
{
struct stat fileinfo;
char filename[260];
};`

#### Members

Name | Description
--- | ---
`fileinfo` | File information
`filename[260]` | File name

## Types

- `cups_dentry_t`
- `cups_dir_t`
- `cups_file_t`

### cups_dentry_t

#### Description

Directory entry type

#### Definition

`typedef struct cups_dentry_s cups_dentry_t;`

### cups_dir_t

#### Description

Directory type

#### Definition

`typedef struct _cups_dir_s cups_dir_t;`

### cups_file_t

#### Description

CUPS file type

#### Definition

`typedef struct _cups_file_s cups_file_t;`