# File and Directory APIs

Headers | cups/file.h cups/dir.h
--- | ---
Library | -lcups
See Also | Programming: Introduction to CUPS Programming Programming: CUPS API

## Contents

- Overview
- Functions
  - cupsDirClose
  - cupsDirOpen
  - cupsDirRead
  - cupsDirRewind
  - cupsFileClose
  - cupsFileCompression
  - cupsFileEOF
  - cupsFileFind
  - cupsFileFlush
  - cupsFileGetChar
  - cupsFileGetConf
  - cupsFileGetLine
  - cupsFileGets
  - cupsFileLock
  - cupsFileNumber
  - cupsFileOpen
  - cupsFileOpenFd
  - cupsFilePeekChar
  - cupsFilePrintf
  - cupsFilePutChar
  - cupsFilePutConf
  - cupsFilePuts
  - cupsFileRead
  - cupsFileRewind
  - cupsFileSeek
  - cupsFileStderr
  - cupsFileStdin
  - cupsFileStdout
  - cupsFileTell
  - cupsFileUnlock
  - cupsFileWrite
- Data Types
  - cups_dentry_t
  - cups_dir_t
  - cups_file_t
- Structures
  - cups_dentry_s

## Overview

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.

## Functions

### CUPS 1.2/macOS 10.5 cupsDirClose

Close a directory.

void cupsDirClose (
cups_dir_t *dp
);

#### Parameters

dp
  Directory pointer

### CUPS 1.2/macOS 10.5 cupsDirOpen

Open a directory.

cups_dir_t *cupsDirOpen (
const char *directory
);

#### Parameters

directory
  Directory name

#### Return Value

Directory pointer or `NULL` if the directory could not be opened.

### CUPS 1.2/macOS 10.5 cupsDirRead

Read the next directory entry.

cups_dentry_t *cupsDirRead (
cups_dir_t *dp
);

#### Parameters

dp
  Directory pointer

#### Return Value

Directory entry or `NULL` when there are no more

### CUPS 1.2/macOS 10.5 cupsDirRewind

Rewind to the start of the directory.

void cupsDirRewind (
cups_dir_t *dp
);

#### Parameters

dp
  Directory pointer

### CUPS 1.2/macOS 10.5 cupsFileClose

Close a CUPS file.

int cupsFileClose (
cups_file_t *fp
);

#### Parameters

fp
  CUPS file

#### Return Value

0 on success, -1 on error

### CUPS 1.2/macOS 10.5 cupsFileCompression

Return whether a file is compressed.

int cupsFileCompression (
cups_file_t *fp
);

#### Parameters

fp
  CUPS file

#### Return Value

`CUPS_FILE_NONE` or `CUPS_FILE_GZIP`

### CUPS 1.2/macOS 10.5 cupsFileEOF

Return the end-of-file status.

int cupsFileEOF (
cups_file_t *fp
);

#### Parameters

fp
  CUPS file

#### Return Value

1 on end of file, 0 otherwise

### CUPS 1.2/macOS 10.5 cupsFileFind

Find a file using the specified path.

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

#### Parameters

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

#### Return Value

Full path to file or `NULL` if not found

#### Discussion

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.

### CUPS 1.2/macOS 10.5 cupsFileFlush

Flush pending output.

int cupsFileFlush (
cups_file_t *fp
);

#### Parameters

fp
  CUPS file

#### Return Value

0 on success, -1 on error

### CUPS 1.2/macOS 10.5 cupsFileGetChar

Get a single character from a file.

int cupsFileGetChar (
cups_file_t *fp
);

#### Parameters

fp
  CUPS file

#### Return Value

Character or -1 on end of file

### CUPS 1.2/macOS 10.5 cupsFileGetConf

Get a line from a configuration file.

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

#### Parameters

fp
  CUPS file
buf
  String buffer
buflen
  Size of string buffer
value
  Pointer to value
linenum
  Current line number

#### Return Value

Line read or `NULL` on end of file or error

### CUPS 1.2/macOS 10.5 cupsFileGetLine

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
);

#### Parameters

fp
  File to read from
buf
  Buffer
buflen
  Size of buffer

#### Return Value

Number of bytes on line or 0 on end of file

#### Discussion

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.

### CUPS 1.2/macOS 10.5 cupsFileGets

Get a CR and/or LF-terminated line.

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

#### Parameters

fp
  CUPS file
buf
  String buffer
buflen
  Size of string buffer

#### Return Value

Line read or `NULL` on end of file or error

### CUPS 1.2/macOS 10.5 cupsFileLock

Temporarily lock access to a file.

int cupsFileLock (
cups_file_t *fp,
int block
);

#### Parameters

fp
  CUPS file
block
  1 to wait for the lock, 0 to fail right away

#### Return Value

0 on success, -1 on error

### CUPS 1.2/macOS 10.5 cupsFileNumber

Return the file descriptor associated with a CUPS file.

int cupsFileNumber (
cups_file_t *fp
);

#### Parameters

fp
  CUPS file

#### Return Value

File descriptor

### CUPS 1.2/macOS 10.5 cupsFileOpen

Open a CUPS file.

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

#### Parameters

filename
  Name of file
mode
  Open mode

#### Return Value

CUPS file or `NULL` if the file or socket cannot be opened

#### Discussion

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.

### CUPS 1.2/macOS 10.5 cupsFileOpenFd

Open a CUPS file using a file descriptor.

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

#### Parameters

fd
  File descriptor
mode
  Open mode

#### Return Value

CUPS file or `NULL` if the file could not be opened

#### Discussion

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.

### CUPS 1.2/macOS 10.5 cupsFilePeekChar

Peek at the next character from a file.

int cupsFilePeekChar (
cups_file_t *fp
);

#### Parameters

fp
  CUPS file

#### Return Value

Character or -1 on end of file

### CUPS 1.2/macOS 10.5 cupsFilePrintf

Write a formatted string.

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

#### Parameters

fp
  CUPS file
format
  Printf-style format string
...
  Additional args as necessary

#### Return Value

Number of bytes written or -1 on error

### CUPS 1.2/macOS 10.5 cupsFilePutChar

Write a character.

int cupsFilePutChar (
cups_file_t *fp,
int c
);

#### Parameters

fp
  CUPS file
c
  Character to write

#### Return Value

0 on success, -1 on error

### CUPS 1.4/macOS 10.6 cupsFilePutConf

Write a configuration line.

ssize_t cupsFilePutConf (
cups_file_t *fp,
const char *directive,
const char *value
);

#### Parameters

fp
  CUPS file
directive
  Directive
value
  Value

#### Return Value

Number of bytes written or -1 on error

#### Discussion

This function handles any comment escaping of the value.

### CUPS 1.2/macOS 10.5 cupsFilePuts

Write a string.

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

#### Parameters

fp
  CUPS file
s
  String to write

#### Return Value

Number of bytes written or -1 on error

#### Discussion

Like the `fputs` function, no newline is appended to the string.

### CUPS 1.2/macOS 10.5 cupsFileRead

Read from a file.

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

#### Parameters

fp
  CUPS file
buf
  Buffer
bytes
  Number of bytes to read

#### Return Value

Number of bytes read or -1 on error

### CUPS 1.2/macOS 10.5 cupsFileRewind

Set the current file position to the beginning of the file.

off_t cupsFileRewind (
cups_file_t *fp
);

#### Parameters

fp
  CUPS file

#### Return Value

New file position or -1 on error

### CUPS 1.2/macOS 10.5 cupsFileSeek

Seek in a file.

off_t cupsFileSeek (
cups_file_t *fp,
off_t pos
);

#### Parameters

fp
  CUPS file
pos
  Position in file

#### Return Value

New file position or -1 on error

### CUPS 1.2/macOS 10.5 cupsFileStderr

Return a CUPS file associated with stderr.

cups_file_t *cupsFileStderr (void);

#### Return Value

CUPS file

### CUPS 1.2/macOS 10.5 cupsFileStdin

Return a CUPS file associated with stdin.

cups_file_t *cupsFileStdin (void);

#### Return Value

CUPS file

### CUPS 1.2/macOS 10.5 cupsFileStdout

Return a CUPS file associated with stdout.

cups_file_t *cupsFileStdout (void);

#### Return Value

CUPS file

### CUPS 1.2/macOS 10.5 cupsFileTell

Return the current file position.

off_t cupsFileTell (
cups_file_t *fp
);

#### Parameters

fp
  CUPS file

#### Return Value

File position

### CUPS 1.2/macOS 10.5 cupsFileUnlock

Unlock access to a file.

int cupsFileUnlock (
cups_file_t *fp
);

#### Parameters

fp
  CUPS file

#### Return Value

0 on success, -1 on error

### CUPS 1.2/macOS 10.5 cupsFileWrite

Write to a file.

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

#### Parameters

fp
  CUPS file
buf
  Buffer
bytes
  Number of bytes to write

#### Return Value

Number of bytes written or -1 on error

## Data Types

### cups_dentry_t

Directory entry type

typedef struct cups_dentry_s cups_dentry_t;

### cups_dir_t

Directory type

typedef struct _cups_dir_s cups_dir_t;

### cups_file_t

CUPS file type

typedef struct _cups_file_s cups_file_t;

## Structures

### cups_dentry_s

Directory entry type

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

#### Members

fileinfo
  File information
filename[260]
  File name