File and Directory APIs

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/Mac OS X 10.5 cupsDirClose

Close a directory.

void cupsDirClose (
    cups_dir_t *dp
);

Parameters

dp

Directory pointer

 CUPS 1.2/Mac OS X 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/Mac OS X 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/Mac OS X 10.5 cupsDirRewind

Rewind to the start of the directory.

void cupsDirRewind (
    cups_dir_t *dp
);

Parameters

dp

Directory pointer

 CUPS 1.2/Mac OS X 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/Mac OS X 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/Mac OS X 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/Mac OS X 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/Mac OS X 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/Mac OS X 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/Mac OS X 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/Mac OS X 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/Mac OS X 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/Mac OS X 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/Mac OS X 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/Mac OS X 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/Mac OS X 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/Mac OS X 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/Mac OS X 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/Mac OS X 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/Mac OS X 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/Mac OS X 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/Mac OS X 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/Mac OS X 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/Mac OS X 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/Mac OS X 10.5 cupsFileStderr

Return a CUPS file associated with stderr.

cups_file_t *cupsFileStderr (void);

Return Value

CUPS file

 CUPS 1.2/Mac OS X 10.5 cupsFileStdin

Return a CUPS file associated with stdin.

cups_file_t *cupsFileStdin (void);

Return Value

CUPS file

 CUPS 1.2/Mac OS X 10.5 cupsFileStdout

Return a CUPS file associated with stdout.

cups_file_t *cupsFileStdout (void);

Return Value

CUPS file

 CUPS 1.2/Mac OS X 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/Mac OS X 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/Mac OS X 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