Keywords: Programming

# PPD API (DEPRECATED)

> The PPD API is deprecated starting in CUPS 1.6/macOS 10.8. Please use the new Job Ticket APIs in the CUPS API documentation. These functions will be removed in a future release of CUPS.

Header | cups/ppd.h
--- | ---
Library | -lcups
See Also | Programming: Introduction to CUPS Programming Programming: CUPS API Specifications: CUPS PPD Extensions

## Contents

- Overview
  - Loading a PPD File
  - Options and Groups
  - Constraints
  - Page Sizes
  - Attributes
- Functions
  - cupsGetConflicts
  - cupsGetPPD
  - cupsGetPPD2
  - cupsGetPPD3
  - cupsGetServerPPD
  - cupsMarkOptions
  - cupsResolveConflicts
  - ppdCollect
  - ppdCollect2
  - ppdConflicts
  - ppdEmit
  - ppdEmitAfterOrder
  - ppdEmitFd
  - ppdEmitJCL
  - ppdEmitJCLEnd
  - ppdEmitString
  - ppdFindAttr
  - ppdFindChoice
  - ppdFindCustomOption
  - ppdFindCustomParam
  - ppdFindMarkedChoice
  - ppdFindNextAttr
  - ppdFindOption
  - ppdFirstCustomParam
  - ppdFirstOption
  - ppdInstallableConflict
  - ppdIsMarked
  - ppdLocalize
  - ppdLocalizeAttr
  - ppdLocalizeIPPReason
  - ppdLocalizeMarkerName
  - ppdMarkDefaults
  - ppdMarkOption
  - ppdNextCustomParam
  - ppdNextOption
  - ppdPageLength
  - ppdPageSize
  - ppdPageSizeLimits
  - ppdPageWidth
- Data Types
  - ppd_attr_t
  - ppd_choice_t
  - ppd_conform_t
  - ppd_const_t
  - ppd_coption_t
  - ppd_cparam_t
  - ppd_cplimit_t
  - ppd_cptype_t
  - ppd_cpvalue_t
  - ppd_cs_t
  - ppd_emul_t
  - ppd_file_t
  - ppd_group_t
  - ppd_option_t
  - ppd_profile_t
  - ppd_section_t
  - ppd_size_t
  - ppd_status_t
  - ppd_ui_t
- Structures
  - ppd_attr_s
  - ppd_choice_s
  - ppd_const_s
  - ppd_coption_s
  - ppd_cparam_s
  - ppd_emul_s
  - ppd_file_s
  - ppd_group_s
  - ppd_option_s
  - ppd_profile_s
  - ppd_size_s
- Unions
  - ppd_cplimit_u
  - ppd_cpvalue_u
- Constants
  - ppd_conform_e
  - ppd_cs_e
  - ppd_section_e
  - ppd_status_e
  - ppd_ui_e

## Overview

> The PPD API is deprecated starting in CUPS 1.6/macOS 10.8. Please use the new Job Ticket APIs in the CUPS API documentation. These functions will be removed in a future release of CUPS.

The CUPS PPD API provides read-only access the data in PostScript Printer Description ("PPD") files which are used for all printers with a driver. With it you can obtain the data necessary to display printer options to users, mark option choices and check for conflicting choices, and output marked choices in PostScript output. The `ppd_file_t` structure contains all of the information in a PPD file.

> Note:

> The CUPS PPD API uses the terms "option" and "choice" instead of the Adobe terms "MainKeyword" and "OptionKeyword" to refer to specific printer options and features. CUPS also treats option ("MainKeyword") and choice ("OptionKeyword") values as case-insensitive strings, so option "InputSlot" and choice "Upper" are equivalent to "inputslot" and "upper", respectively.

### Loading a PPD File

The `ppdOpenFile` function "opens" a PPD file and loads it into memory. For example, the following code opens the current printer's PPD file in a CUPS filter:

    #include <cups/ppd.h>

    ppd_file_t *ppd = ppdOpenFile(getenv("PPD"));

The return value is a pointer to a new `ppd_file_t` structure or `NULL` if the PPD file does not exist or cannot be loaded. The `ppdClose` function frees the memory used by the structure:

    #include <cups/ppd.h>

    ppd_file_t *ppd;

    ppdClose(ppd);

Once closed, pointers to the `ppd_file_t` structure and any data in it will no longer be valid.

### Options and Groups

PPD files support multiple options, which are stored in arrays of `ppd_option_t` and `ppd_choice_t` structures.

Each option in turn is associated with a group stored in a `ppd_group_t` structure. Groups can be specified in the PPD file; if an option is not associated with a group then it is put in an automatically-generated "General" group. Groups can also have sub-groups, however CUPS currently ignores sub-groups because of past abuses of this functionality.

Option choices are selected by marking them using one of three functions. The first is `ppdMarkDefaults` which selects all of the default options in the PPD file:

    #include <cups/ppd.h>

    ppd_file_t *ppd;

    ppdMarkDefaults(ppd);

The second is `ppdMarkOption` which selects a single option choice in the PPD file. For example, the following code selects the upper paper tray:

    #include <cups/ppd.h>

    ppd_file_t *ppd;

    ppdMarkOption(ppd, "InputSlot", "Upper");

The last function is `cupsMarkOptions` which selects multiple option choices in the PPD file from an array of CUPS options, mapping IPP attributes like "media" and "sides" to their corresponding PPD options. You typically use this function in a print filter with `cupsParseOptions` and `ppdMarkDefaults` to select all of the option choices needed for the job, for example:

    #include <cups/ppd.h>

    ppd_file_t *ppd = ppdOpenFile(getenv("PPD"));
    cups_option_t *options = NULL;
    int num_options = cupsParseOptions(argv[5], 0, &options);

    ppdMarkDefaults(ppd);
    cupsMarkOptions(ppd, num_options, options);
    cupsFreeOptions(num_options, options);

### Constraints

PPD files support specification of conflict conditions, called constraints, between different options. Constraints are stored in an array of `ppd_const_t` structures which specify the options and choices that conflict with each other. The `ppdConflicts` function tells you how many of the selected options are incompatible. Since constraints are normally specified in pairs, the returned value is typically an even number.

### Page Sizes

Page sizes are special options which have physical dimensions and margins associated with them. The size information is stored in `ppd_size_t` structures and is available by looking up the named size with the `ppdPageSize` function. The page size and margins are returned in units called points; there are 72 points per inch. If you pass `NULL` for the size, the currently selected size is returned:

    #include <cups/ppd.h>

    ppd_file_t *ppd;
    ppd_size_t *size = ppdPageSize(ppd, NULL);

Besides the standard page sizes listed in a PPD file, some printers support variable or custom page sizes. Custom page sizes are supported if the `variables_sizes` member of the `ppd_file_t` structure is non-zero. The `custom_min`, `custom_max`, and `custom_margins` members of the `ppd_file_t` structure define the limits of the printable area. To get the resulting media size, use a page size string of the form "Custom.widthxlength", where "width" and "length" are in points. Custom page size names can also be specified in inches ("Custom.widthxheightin"), centimeters ("Custom.widthxheightcm"), or millimeters ("Custom.widthxheightmm"):

    #include <cups/ppd.h>

    ppd_file_t *ppd;

    /* Get an 576x720 point custom page size */
    ppd_size_t *size = ppdPageSize(ppd, "Custom.576x720");

    /* Get an 8x10 inch custom page size */
    ppd_size_t *size = ppdPageSize(ppd, "Custom.8x10in");

    /* Get a 100x200 millimeter custom page size */
    ppd_size_t *size = ppdPageSize(ppd, "Custom.100x200mm");

    /* Get a 12.7x34.5 centimeter custom page size */
    ppd_size_t *size = ppdPageSize(ppd, "Custom.12.7x34.5cm");

If the PPD does not support variable page sizes, the `ppdPageSize` function will return `NULL`.

### Attributes

Every PPD file is composed of one or more attributes. Most of these attributes are used to define groups, options, choices, and page sizes, however several informational attributes may be present which you can access in your program or filter. Attributes normally look like one of the following examples in a PPD file:

    *name: "value"
    *name spec: "value"
    *name spec/text: "value"

The `ppdFindAttr` and `ppdFindNextAttr` functions find the first and next instances, respectively, of the named attribute with the given "spec" string and return a `ppd_attr_t` structure. If you provide a NULL specifier string, all attributes with the given name will be returned. For example, the following code lists all of the `Product` attributes in a PPD file:

    #include <cups/ppd.h>

    ppd_file_t *ppd;
    ppd_attr_t *attr;

    for (attr = ppdFindAttr(ppd, "Product", NULL);
         attr != NULL;
         attr = ppdFindNextAttr(ppd, "Product", NULL))
      puts(attr->value);

## Functions

### CUPS 1.4/macOS 10.6 cupsGetConflicts

Get a list of conflicting options in a marked PPD.

int cupsGetConflicts (
ppd_file_t *ppd,
const char *option,
const char *choice,
cups_option_t **options
);

#### Parameters

ppd
  PPD file
option
  Option to test
choice
  Choice to test
options
  Conflicting options

#### Return Value

Number of conflicting options

#### Discussion

This function gets a list of options that would conflict if "option" and "choice" were marked in the PPD. You would typically call this function after marking the currently selected options in the PPD in order to determine whether a new option selection would cause a conflict.
The number of conflicting options are returned with "options" pointing to the conflicting options. The returned option array must be freed using `cupsFreeOptions`.

### cupsGetPPD

Get the PPD file for a printer on the default server.

const char *cupsGetPPD (
const char *name
);

#### Parameters

name
  Destination name

#### Return Value

Filename for PPD file

#### Discussion

For classes, `cupsGetPPD` returns the PPD file for the first printer in the class.
The returned filename is stored in a static buffer and is overwritten with each call to `cupsGetPPD` or `cupsGetPPD2`. The caller "owns" the file that is created and must `unlink` the returned filename.

### CUPS 1.1.21/macOS 10.4 cupsGetPPD2

Get the PPD file for a printer from the specified server.

const char *cupsGetPPD2 (
http_t *http,
const char *name
);

#### Parameters

http
  Connection to server or `CUPS_HTTP_DEFAULT`
name
  Destination name

#### Return Value

Filename for PPD file

#### Discussion

For classes, `cupsGetPPD2` returns the PPD file for the first printer in the class.
The returned filename is stored in a static buffer and is overwritten with each call to `cupsGetPPD` or `cupsGetPPD2`. The caller "owns" the file that is created and must `unlink` the returned filename.

### CUPS 1.4/macOS 10.6 cupsGetPPD3

Get the PPD file for a printer on the specified server if it has changed.

http_status_t cupsGetPPD3 (
http_t *http,
const char *name,
time_t *modtime,
char *buffer,
size_t bufsize
);

#### Parameters

http
  HTTP connection or `CUPS_HTTP_DEFAULT`
name
  Destination name
modtime
  Modification time
buffer
  Filename buffer
bufsize
  Size of filename buffer

#### Return Value

HTTP status

#### Discussion

The "modtime" parameter contains the modification time of any locally-cached content and is updated with the time from the PPD file on the server.
The "buffer" parameter contains the local PPD filename. If it contains the empty string, a new temporary file is created, otherwise the existing file will be overwritten as needed. The caller "owns" the file that is created and must `unlink` the returned filename.
On success, `HTTP_STATUS_OK` is returned for a new PPD file and `HTTP_STATUS_NOT_MODIFIED` if the existing PPD file is up-to-date. Any other status is an error.
For classes, `cupsGetPPD3` returns the PPD file for the first printer in the class.

### CUPS 1.3/macOS 10.5 cupsGetServerPPD

Get an available PPD file from the server.

char *cupsGetServerPPD (
http_t *http,
const char *name
);

#### Parameters

http
  Connection to server or `CUPS_HTTP_DEFAULT`
name
  Name of PPD file ("ppd-name")

#### Return Value

Name of PPD file or `NULL` on error

#### Discussion

This function returns the named PPD file from the server. The list of available PPDs is provided by the IPP `CUPS_GET_PPDS` operation.
You must remove (unlink) the PPD file when you are finished with it. The PPD filename is stored in a static location that will be overwritten on the next call to `cupsGetPPD`, `cupsGetPPD2`, or `cupsGetServerPPD`.

### cupsMarkOptions

Mark command-line options in a PPD file.

int cupsMarkOptions (
ppd_file_t *ppd,
int num_options,
cups_option_t *options
);

#### Parameters

ppd
  PPD file
num_options
  Number of options
options
  Options

#### Return Value

1 if conflicts exist, 0 otherwise

#### Discussion

This function maps the IPP "finishings", "media", "mirror", "multiple-document-handling", "output-bin", "print-color-mode", "print-quality", "printer-resolution", and "sides" attributes to their corresponding PPD options and choices.

### CUPS 1.4/macOS 10.6 cupsResolveConflicts

Resolve conflicts in a marked PPD.

int cupsResolveConflicts (
ppd_file_t *ppd,
const char *option,
const char *choice,
int *num_options,
cups_option_t **options
);

#### Parameters

ppd
  PPD file
option
  Newly selected option or `NULL` for none
choice
  Newly selected choice or `NULL` for none
num_options
  Number of additional selected options
options
  Additional selected options

#### Return Value

1 on success, 0 on failure

#### Discussion

This function attempts to resolve any conflicts in a marked PPD, returning a list of option changes that are required to resolve them. On input, "num_options" and "options" contain any pending option changes that have not yet been marked, while "option" and "choice" contain the most recent selection which may or may not be in "num_options" or "options".
On successful return, "num_options" and "options" are updated to contain "option" and "choice" along with any changes required to resolve conflicts specified in the PPD file and 1 is returned.
If option conflicts cannot be resolved, "num_options" and "options" are not changed and 0 is returned.
When resolving conflicts, `cupsResolveConflicts` does not consider changes to the current page size (`media`, `PageSize`, and `PageRegion`) or to the most recent option specified in "option". Thus, if the only way to resolve a conflict is to change the page size or the option the user most recently changed, `cupsResolveConflicts` will return 0 to indicate it was unable to resolve the conflicts.
The `cupsResolveConflicts` function uses one of two sources of option constraint information. The preferred constraint information is defined by `cupsUIConstraints` and `cupsUIResolver` attributes - in this case, the PPD file provides constraint resolution actions.
The backup constraint information is defined by the `UIConstraints` and `NonUIConstraints` attributes. These constraints are resolved algorithmically by first selecting the default choice for the conflicting option, then iterating over all possible choices until a non-conflicting option choice is found.

### ppdCollect

Collect all marked options that reside in the specified section.

int ppdCollect (
ppd_file_t *ppd,
ppd_section_t section,
ppd_choice_t ***choices
);

#### Parameters

ppd
  PPD file data
section
  Section to collect
choices
  Pointers to choices

#### Return Value

Number of options marked

#### Discussion

The choices array should be freed using `free` when you are finished with it.

### CUPS 1.2/macOS 10.5 ppdCollect2

Collect all marked options that reside in the specified section and minimum order.

int ppdCollect2 (
ppd_file_t *ppd,
ppd_section_t section,
float min_order,
ppd_choice_t ***choices
);

#### Parameters

ppd
  PPD file data
section
  Section to collect
min_order
  Minimum OrderDependency value
choices
  Pointers to choices

#### Return Value

Number of options marked

#### Discussion

The choices array should be freed using `free` when you are finished with it.

### ppdConflicts

Check to see if there are any conflicts among the marked option choices.

int ppdConflicts (
ppd_file_t *ppd
);

#### Parameters

ppd
  PPD to check

#### Return Value

Number of conflicts found

#### Discussion

The returned value is the same as returned by `ppdMarkOption`.

### ppdEmit

Emit code for marked options to a file.

int ppdEmit (
ppd_file_t *ppd,
FILE *fp,
ppd_section_t section
);

#### Parameters

ppd
  PPD file record
fp
  File to write to
section
  Section to write

#### Return Value

0 on success, -1 on failure

### CUPS 1.2/macOS 10.5 ppdEmitAfterOrder

Emit a subset of the code for marked options to a file.

int ppdEmitAfterOrder (
ppd_file_t *ppd,
FILE *fp,
ppd_section_t section,
int limit,
float min_order
);

#### Parameters

ppd
  PPD file record
fp
  File to write to
section
  Section to write
limit
  Non-zero to use min_order
min_order
  Lowest OrderDependency

#### Return Value

0 on success, -1 on failure

#### Discussion

When "limit" is non-zero, this function only emits options whose OrderDependency value is greater than or equal to "min_order".
When "limit" is zero, this function is identical to ppdEmit().

### ppdEmitFd

Emit code for marked options to a file.

int ppdEmitFd (
ppd_file_t *ppd,
int fd,
ppd_section_t section
);

#### Parameters

ppd
  PPD file record
fd
  File to write to
section
  Section to write

#### Return Value

0 on success, -1 on failure

### ppdEmitJCL

Emit code for JCL options to a file.

int ppdEmitJCL (
ppd_file_t *ppd,
FILE *fp,
int job_id,
const char *user,
const char *title
);

#### Parameters

ppd
  PPD file record
fp
  File to write to
job_id
  Job ID
user
  Username
title
  Title

#### Return Value

0 on success, -1 on failure

### CUPS 1.2/macOS 10.5 ppdEmitJCLEnd

Emit JCLEnd code to a file.

int ppdEmitJCLEnd (
ppd_file_t *ppd,
FILE *fp
);

#### Parameters

ppd
  PPD file record
fp
  File to write to

#### Return Value

0 on success, -1 on failure

### CUPS 1.2/macOS 10.5 ppdEmitString

Get a string containing the code for marked options.

char *ppdEmitString (
ppd_file_t *ppd,
ppd_section_t section,
float min_order
);

#### Parameters

ppd
  PPD file record
section
  Section to write
min_order
  Lowest OrderDependency

#### Return Value

String containing option code or `NULL` if there is no option code

#### Discussion

When "min_order" is greater than zero, this function only includes options whose OrderDependency value is greater than or equal to "min_order". Otherwise, all options in the specified section are included in the returned string.
The return string is allocated on the heap and should be freed using `free` when you are done with it.

### CUPS 1.1.19/macOS 10.3 ppdFindAttr

Find the first matching attribute.

ppd_attr_t *ppdFindAttr (
ppd_file_t *ppd,
const char *name,
const char *spec
);

#### Parameters

ppd
  PPD file data
name
  Attribute name
spec
  Specifier string or `NULL`

#### Return Value

Attribute or `NULL` if not found

### ppdFindChoice

Return a pointer to an option choice.

ppd_choice_t *ppdFindChoice (
ppd_option_t *o,
const char *choice
);

#### Parameters

o
  Pointer to option
choice
  Name of choice

#### Return Value

Choice pointer or `NULL`

### CUPS 1.2/macOS 10.5 ppdFindCustomOption

Find a custom option.

ppd_coption_t *ppdFindCustomOption (
ppd_file_t *ppd,
const char *keyword
);

#### Parameters

ppd
  PPD file
keyword
  Custom option name

#### Return Value

Custom option or NULL

### CUPS 1.2/macOS 10.5 ppdFindCustomParam

Find a parameter for a custom option.

ppd_cparam_t *ppdFindCustomParam (
ppd_coption_t *opt,
const char *name
);

#### Parameters

opt
  Custom option
name
  Parameter name

#### Return Value

Custom parameter or NULL

### ppdFindMarkedChoice

Return the marked choice for the specified option.

ppd_choice_t *ppdFindMarkedChoice (
ppd_file_t *ppd,
const char *option
);

#### Parameters

ppd
  PPD file
option
  Keyword/option name

#### Return Value

Pointer to choice or `NULL`

### CUPS 1.1.19/macOS 10.3 ppdFindNextAttr

Find the next matching attribute.

ppd_attr_t *ppdFindNextAttr (
ppd_file_t *ppd,
const char *name,
const char *spec
);

#### Parameters

ppd
  PPD file data
name
  Attribute name
spec
  Specifier string or `NULL`

#### Return Value

Attribute or `NULL` if not found

### ppdFindOption

Return a pointer to the specified option.

ppd_option_t *ppdFindOption (
ppd_file_t *ppd,
const char *option
);

#### Parameters

ppd
  PPD file data
option
  Option/Keyword name

#### Return Value

Pointer to option or `NULL`

### CUPS 1.2/macOS 10.5 ppdFirstCustomParam

Return the first parameter for a custom option.

ppd_cparam_t *ppdFirstCustomParam (
ppd_coption_t *opt
);

#### Parameters

opt
  Custom option

#### Return Value

Custom parameter or NULL

### CUPS 1.2/macOS 10.5 ppdFirstOption

Return the first option in the PPD file.

ppd_option_t *ppdFirstOption (
ppd_file_t *ppd
);

#### Parameters

ppd
  PPD file

#### Return Value

First option or `NULL`

#### Discussion

Options are returned from all groups in ascending alphanumeric order.

### CUPS 1.4/macOS 10.6 ppdInstallableConflict

Test whether an option choice conflicts with an installable option.

int ppdInstallableConflict (
ppd_file_t *ppd,
const char *option,
const char *choice
);

#### Parameters

ppd
  PPD file
option
  Option
choice
  Choice

#### Return Value

1 if conflicting, 0 if not conflicting

#### Discussion

This function tests whether a particular option choice is available based on constraints against options in the "InstallableOptions" group.

### ppdIsMarked

Check to see if an option is marked.

int ppdIsMarked (
ppd_file_t *ppd,
const char *option,
const char *choice
);

#### Parameters

ppd
  PPD file data
option
  Option/Keyword name
choice
  Choice name

#### Return Value

Non-zero if option is marked

### CUPS 1.2/macOS 10.5 ppdLocalize

Localize the PPD file to the current locale.

int ppdLocalize (
ppd_file_t *ppd
);

#### Parameters

ppd
  PPD file

#### Return Value

0 on success, -1 on error

#### Discussion

All groups, options, and choices are localized, as are ICC profile descriptions, printer presets, and custom option parameters. Each localized string uses the UTF-8 character encoding.

### ppdLocalizeAttr

Localize an attribute.

ppd_attr_t *ppdLocalizeAttr (
ppd_file_t *ppd,
const char *keyword,
const char *spec
);

#### Parameters

ppd
  PPD file
keyword
  Main keyword
spec
  Option keyword or `NULL` for none

#### Return Value

Localized attribute or `NULL` if none exists

#### Discussion

This function uses the current locale to find the localized attribute for the given main and option keywords. If no localized version of the attribute exists for the current locale, the unlocalized version is returned.

### CUPS 1.3/macOS 10.5 ppdLocalizeIPPReason

Get the localized version of a cupsIPPReason attribute.

const char *ppdLocalizeIPPReason (
ppd_file_t *ppd,
const char *reason,
const char *scheme,
char *buffer,
size_t bufsize
);

#### Parameters

ppd
  PPD file
reason
  IPP reason keyword to look up
scheme
  URI scheme or NULL for text
buffer
  Value buffer
bufsize
  Size of value buffer

#### Return Value

Value or NULL if not found

#### Discussion

This function uses the current locale to find the corresponding reason text or URI from the attribute value. If "scheme" is NULL or "text", the returned value contains human-readable (UTF-8) text from the translation string or attribute value. Otherwise the corresponding URI is returned.
If no value of the requested scheme can be found, NULL is returned.

### CUPS 1.4/macOS 10.6 ppdLocalizeMarkerName

Get the localized version of a marker-names attribute value.

const char *ppdLocalizeMarkerName (
ppd_file_t *ppd,
const char *name
);

#### Parameters

ppd
  PPD file
name
  Marker name to look up

#### Return Value

Value or `NULL` if not found

#### Discussion

This function uses the current locale to find the corresponding name text from the attribute value. If no localized text for the requested name can be found, `NULL` is returned.

### ppdMarkDefaults

Mark all default options in the PPD file.

void ppdMarkDefaults (
ppd_file_t *ppd
);

#### Parameters

ppd
  PPD file record

### ppdMarkOption

Mark an option in a PPD file and return the number of conflicts.

int ppdMarkOption (
ppd_file_t *ppd,
const char *option,
const char *choice
);

#### Parameters

ppd
  PPD file record
option
  Keyword
choice
  Option name

#### Return Value

Number of conflicts

### CUPS 1.2/macOS 10.5 ppdNextCustomParam

Return the next parameter for a custom option.

ppd_cparam_t *ppdNextCustomParam (
ppd_coption_t *opt
);

#### Parameters

opt
  Custom option

#### Return Value

Custom parameter or NULL

### CUPS 1.2/macOS 10.5 ppdNextOption

Return the next option in the PPD file.

ppd_option_t *ppdNextOption (
ppd_file_t *ppd
);

#### Parameters

ppd
  PPD file

#### Return Value

Next option or `NULL`

#### Discussion

Options are returned from all groups in ascending alphanumeric order.

### ppdPageLength

Get the page length for the given size.

float ppdPageLength (
ppd_file_t *ppd,
const char *name
);

#### Parameters

ppd
  PPD file
name
  Size name

#### Return Value

Length of page in points or 0.0

### ppdPageSize

Get the page size record for the named size.

ppd_size_t *ppdPageSize (
ppd_file_t *ppd,
const char *name
);

#### Parameters

ppd
  PPD file record
name
  Size name

#### Return Value

Size record for page or NULL

### CUPS 1.4/macOS 10.6 ppdPageSizeLimits

Return the custom page size limits.

int ppdPageSizeLimits (
ppd_file_t *ppd,
ppd_size_t *minimum,
ppd_size_t *maximum
);

#### Parameters

ppd
  PPD file record
minimum
  Minimum custom size
maximum
  Maximum custom size

#### Return Value

1 if custom sizes are supported, 0 otherwise

#### Discussion

This function returns the minimum and maximum custom page sizes and printable areas based on the currently-marked (selected) options.
If the specified PPD file does not support custom page sizes, both "minimum" and "maximum" are filled with zeroes.

### ppdPageWidth

Get the page width for the given size.

float ppdPageWidth (
ppd_file_t *ppd,
const char *name
);

#### Parameters

ppd
  PPD file record
name
  Size name

#### Return Value

Width of page in points or 0.0

## Data Types

### CUPS 1.1.19/macOS 10.3 ppd_attr_t

PPD Attribute Structure

typedef struct ppd_attr_s ppd_attr_t;

### ppd_choice_t

Option choices

typedef struct ppd_choice_s ppd_choice_t;

### CUPS 1.1.19/macOS 10.3 ppd_conform_t

Conformance Levels

typedef enum ppd_conform_e ppd_conform_t;

### ppd_const_t

Constraints

typedef struct ppd_const_s ppd_const_t;

### CUPS 1.2/macOS 10.5 ppd_coption_t

Custom Option

typedef struct ppd_coption_s ppd_coption_t;

### CUPS 1.2/macOS 10.5 ppd_cparam_t

Custom Parameter

typedef struct ppd_cparam_s ppd_cparam_t;

### CUPS 1.2/macOS 10.5 ppd_cplimit_t

Custom Parameter Limit

typedef union ppd_cplimit_u ppd_cplimit_t;

### CUPS 1.2/macOS 10.5 ppd_cptype_t

Custom Parameter Type

typedef enum ppd_cptype_e ppd_cptype_t;

### CUPS 1.2/macOS 10.5 ppd_cpvalue_t

Custom Parameter Value

typedef union ppd_cpvalue_u ppd_cpvalue_t;

### ppd_cs_t

Colorspaces

typedef enum ppd_cs_e ppd_cs_t;

### ppd_emul_t

Emulators

typedef struct ppd_emul_s ppd_emul_t;

### ppd_file_t

PPD File

typedef struct ppd_file_s ppd_file_t;

### ppd_group_t

Groups

typedef struct ppd_group_s ppd_group_t;

### ppd_option_t

Options

typedef struct ppd_option_s ppd_option_t;

### ppd_profile_t

sRGB Color Profiles

typedef struct ppd_profile_s ppd_profile_t;

### ppd_section_t

Order dependency sections

typedef enum ppd_section_e ppd_section_t;

### ppd_size_t

Page Sizes

typedef struct ppd_size_s ppd_size_t;

### CUPS 1.1.19/macOS 10.3 ppd_status_t

Status Codes

typedef enum ppd_status_e ppd_status_t;

### ppd_ui_t

UI Types

typedef enum ppd_ui_e ppd_ui_t;

## Structures

### CUPS 1.1.19/macOS 10.3 ppd_attr_s

PPD Attribute Structure

struct ppd_attr_s {
char name[PPD_MAX_NAME];
char spec[PPD_MAX_NAME];
char text[PPD_MAX_TEXT];
char *value;
};

#### Members

name[PPD_MAX_NAME]
  Name of attribute (cupsXYZ)
spec[PPD_MAX_NAME]
  Specifier string, if any
text[PPD_MAX_TEXT]
  Human-readable text, if any
value
  Value string

### ppd_choice_s

Option choices

struct ppd_choice_s {
char choice[PPD_MAX_NAME];
char *code;
char marked;
ppd_option_t *option;
char text[PPD_MAX_TEXT];
};

#### Members

choice[PPD_MAX_NAME]
  Computer-readable option name
code
  Code to send for this option
marked
  0 if not selected, 1 otherwise
option
  Pointer to parent option structure
text[PPD_MAX_TEXT]
  Human-readable option name

### ppd_const_s

Constraints

struct ppd_const_s {
char choice1[PPD_MAX_NAME];
char choice2[PPD_MAX_NAME];
char option1[PPD_MAX_NAME];
char option2[PPD_MAX_NAME];
};

#### Members

choice1[PPD_MAX_NAME]
  First option/choice (blank for all)
choice2[PPD_MAX_NAME]
  Second option/choice (blank for all)
option1[PPD_MAX_NAME]
  First keyword
option2[PPD_MAX_NAME]
  Second keyword

### CUPS 1.2/macOS 10.5 ppd_coption_s

Custom Option

struct ppd_coption_s {
char keyword[PPD_MAX_NAME];
int marked;
ppd_option_t *option;
cups_array_t *params;
};

#### Members

keyword[PPD_MAX_NAME]
  Name of option that is being extended...
marked
  Extended option is marked
option
  Option that is being extended...
params
  Parameters

### CUPS 1.2/macOS 10.5 ppd_cparam_s

Custom Parameter

struct ppd_cparam_s {
ppd_cpvalue_t current;
ppd_cplimit_t minimum, maximum;
char name[PPD_MAX_NAME];
int order;
char text[PPD_MAX_TEXT];
ppd_cptype_t type;
};

#### Members

current
  Current value
maximum
  Maximum value
name[PPD_MAX_NAME]
  Parameter name
order
  Order (0 to N)
text[PPD_MAX_TEXT]
  Human-readable text
type
  Parameter type

### ppd_emul_s

Emulators

struct ppd_emul_s {
char name[PPD_MAX_NAME];
char *start;
char *stop;
};

#### Members

name[PPD_MAX_NAME]
  Emulator name
start
  Code to switch to this emulation
stop
  Code to stop this emulation

### ppd_file_s

PPD File

struct ppd_file_s {
int accurate_screens;
int color_device;
ppd_cs_t colorspace;
ppd_const_t *consts;
int contone_only;
float custom_margins[4];
float custom_max[2];
float custom_min[2];
ppd_emul_t *emulations;
char **filters;
int flip_duplex;
char **fonts;
ppd_group_t *groups;
char *jcl_begin;
char *jcl_end;
char *jcl_ps;
int landscape;
char *lang_encoding;
char *lang_version;
int language_level;
int manual_copies;
char *manufacturer;
int model_number;
char *modelname;
char *nickname;
int num_consts;
int num_emulations;
int num_filters;
int num_fonts;
int num_groups;
int num_profiles;
int num_sizes;
char *patches;
char *pcfilename;
char *product;
ppd_profile_t *profiles;
char *protocols;
char *shortnickname;
ppd_size_t *sizes;
int throughput;
char *ttrasterizer;
int variable_sizes;
};

#### Members

accurate_screens
  1 = supports accurate screens, 0 = not
color_device
  1 = color device, 0 = grayscale
colorspace
  Default colorspace
consts
  UI/Non-UI constraints
contone_only
  1 = continuous tone only, 0 = not
custom_margins[4]
  Margins around page
custom_max[2]
  Maximum variable page size
custom_min[2]
  Minimum variable page size
emulations
  Emulations and the code to invoke them
filters
  Filter strings...
flip_duplex DEPRECATED
  1 = Flip page for back sides
fonts
  Pre-loaded fonts
groups
  UI groups
jcl_begin
  Start JCL commands
jcl_end
  End JCL commands
jcl_ps
  Enter PostScript interpreter
landscape
  -90 or 90
lang_encoding
  Language encoding
lang_version
  Language version (English, Spanish, etc.)
language_level
  Language level of device
manual_copies
  1 = Copies done manually, 0 = hardware
manufacturer
  Manufacturer name
model_number
  Device-specific model number
modelname
  Model name (general)
nickname
  Nickname (specific)
num_consts
  Number of UI/Non-UI constraints
num_emulations
  Number of emulations supported
num_filters
  Number of filters
num_fonts
  Number of pre-loaded fonts
num_groups
  Number of UI groups
num_profiles DEPRECATED
  Number of sRGB color profiles
num_sizes
  Number of page sizes
patches
  Patch commands to be sent to printer
pcfilename CUPS 1.1.19/macOS 10.3
  PCFileName string
product
  Product name (from PS RIP/interpreter)
profiles DEPRECATED
  sRGB color profiles
protocols CUPS 1.1.19/macOS 10.3
  Protocols (BCP, TBCP) string
shortnickname
  Short version of nickname
sizes
  Page sizes
throughput
  Pages per minute
ttrasterizer
  Truetype rasterizer
variable_sizes
  1 = supports variable sizes, 0 = doesn't

### ppd_group_s

Groups

struct ppd_group_s {
char text[PPD_MAX_TEXT - PPD_MAX_NAME];
char name[PPD_MAX_NAME];
int num_options;
int num_subgroups;
ppd_option_t *options;
struct ppd_group_s *subgroups;
};

#### Members

PPD_MAX_NAME]
  Human-readable group name
name[PPD_MAX_NAME] CUPS 1.1.18/macOS 10.3
  Group name
num_options
  Number of options
num_subgroups
  Number of sub-groups
options
  Options
subgroups
  Sub-groups (max depth = 1)

### ppd_option_s

Options

struct ppd_option_s {
ppd_choice_t *choices;
char conflicted;
char defchoice[PPD_MAX_NAME];
char keyword[PPD_MAX_NAME];
int num_choices;
float order;
ppd_section_t section;
char text[PPD_MAX_TEXT];
ppd_ui_t ui;
};

#### Members

choices
  Option choices
conflicted
  0 if no conflicts exist, 1 otherwise
defchoice[PPD_MAX_NAME]
  Default option choice
keyword[PPD_MAX_NAME]
  Option keyword name ("PageSize", etc.)
num_choices
  Number of option choices
order
  Order number
section
  Section for command
text[PPD_MAX_TEXT]
  Human-readable text
ui
  Type of UI option

### ppd_profile_s

sRGB Color Profiles

struct ppd_profile_s {
float density;
float gamma;
float matrix[3][3];
char media_type[PPD_MAX_NAME];
char resolution[PPD_MAX_NAME];
};

#### Members

density
  Ink density to use
gamma
  Gamma correction to use
matrix[3][3]
  Transform matrix
media_type[PPD_MAX_NAME]
  Media type or "-"
resolution[PPD_MAX_NAME]
  Resolution or "-"

### ppd_size_s

Page Sizes

struct ppd_size_s {
float bottom;
float left;
float length;
int marked;
char name[PPD_MAX_NAME];
float right;
float top;
float width;
};

#### Members

bottom
  Bottom printable margin in points
left
  Left printable margin in points
length
  Length of media in points
marked
  Page size selected?
name[PPD_MAX_NAME]
  Media size option
right
  Right printable margin in points
top
  Top printable margin in points
width
  Width of media in points

## Unions

### CUPS 1.2/macOS 10.5 ppd_cplimit_u

Custom Parameter Limit

union ppd_cplimit_u {
float custom_curve;
int custom_int;
float custom_invcurve;
int custom_passcode;
int custom_password;
float custom_points;
float custom_real;
int custom_string;
};

#### Members

custom_curve
  Gamma value
custom_int
  Integer value
custom_invcurve
  Gamma value
custom_passcode
  Passcode length
custom_password
  Password length
custom_points
  Measurement value
custom_real
  Real value
custom_string
  String length

### CUPS 1.2/macOS 10.5 ppd_cpvalue_u

Custom Parameter Value

union ppd_cpvalue_u {
float custom_curve;
int custom_int;
float custom_invcurve;
char *custom_passcode;
char *custom_password;
float custom_points;
float custom_real;
char *custom_string;
};

#### Members

custom_curve
  Gamma value
custom_int
  Integer value
custom_invcurve
  Gamma value
custom_passcode
  Passcode value
custom_password
  Password value
custom_points
  Measurement value
custom_real
  Real value
custom_string
  String value

## Constants

### CUPS 1.1.19/macOS 10.3 ppd_conform_e

Conformance Levels

#### Constants

PPD_CONFORM_RELAXED
  Relax whitespace and control char
PPD_CONFORM_STRICT
  Require strict conformance

### ppd_cs_e

Colorspaces

#### Constants

PPD_CS_CMY
  CMY colorspace
PPD_CS_CMYK
  CMYK colorspace
PPD_CS_GRAY
  Grayscale colorspace
PPD_CS_N
  DeviceN colorspace
PPD_CS_RGB
  RGB colorspace
PPD_CS_RGBK
  RGBK (K = gray) colorspace

### ppd_section_e

Order dependency sections

#### Constants

PPD_ORDER_ANY
  Option code can be anywhere in the file
PPD_ORDER_DOCUMENT
  ... must be in the DocumentSetup section
PPD_ORDER_EXIT
  ... must be sent prior to the document
PPD_ORDER_JCL
  ... must be sent as a JCL command
PPD_ORDER_PAGE
  ... must be in the PageSetup section
PPD_ORDER_PROLOG
  ... must be in the Prolog section

### CUPS 1.1.19/macOS 10.3 ppd_status_e

Status Codes

#### Constants

PPD_ALLOC_ERROR
  Memory allocation error
PPD_BAD_CUSTOM_PARAM
  Bad custom parameter
PPD_BAD_OPEN_GROUP
  Bad OpenGroup
PPD_BAD_OPEN_UI
  Bad OpenUI/JCLOpenUI
PPD_BAD_ORDER_DEPENDENCY
  Bad OrderDependency
PPD_BAD_UI_CONSTRAINTS
  Bad UIConstraints
PPD_BAD_VALUE
  Bad value string
PPD_FILE_OPEN_ERROR
  Unable to open PPD file
PPD_ILLEGAL_CHARACTER
  Illegal control character
PPD_ILLEGAL_MAIN_KEYWORD
  Illegal main keyword string
PPD_ILLEGAL_OPTION_KEYWORD
  Illegal option keyword string
PPD_ILLEGAL_TRANSLATION
  Illegal translation string
PPD_ILLEGAL_WHITESPACE
  Illegal whitespace character
PPD_INTERNAL_ERROR
  Internal error
PPD_LINE_TOO_LONG
  Line longer than 255 chars
PPD_MISSING_ASTERISK
  Missing asterisk in column 0
PPD_MISSING_CLOSE_GROUP
  Missing CloseGroup
PPD_MISSING_OPTION_KEYWORD
  Missing option keyword
PPD_MISSING_PPDADOBE4
  Missing PPD-Adobe-4.x header
PPD_MISSING_VALUE
  Missing value string
PPD_NESTED_OPEN_GROUP
  OpenGroup without a CloseGroup first
PPD_NESTED_OPEN_UI
  OpenUI/JCLOpenUI without a CloseUI/JCLCloseUI first
PPD_NULL_FILE
  NULL PPD file pointer
PPD_OK
  OK

### ppd_ui_e

UI Types

#### Constants

PPD_UI_BOOLEAN
  True or False option
PPD_UI_PICKMANY
  Pick zero or more from a list
PPD_UI_PICKONE
  Pick one from a list