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;