# CUPS API

Header | cups/cups.h
--- | ---
Library | -lcups
See Also | Programming: Introduction to CUPS Programming Programming: Array API Programming: File and Directory APIs Programming: Filter and Backend Programming Programming: HTTP and IPP APIs Programming: PPD API Programming: Raster API

## Contents

- Overview
  - Clients and Servers
  - Printers and Classes
  - Options
  - Print Jobs
  - Error Handling
  - Passwords and Authentication
- Functions
  - cupsAddDest
  - cupsAddOption
  - cupsAdminCreateWindowsPPD
  - cupsAdminExportSamba
  - cupsAdminGetServerSettings
  - cupsAdminSetServerSettings
  - cupsCancelJob
  - cupsCancelJob2
  - cupsCreateJob
  - cupsEncryption
  - cupsFinishDocument
  - cupsFreeDests
  - cupsFreeJobs
  - cupsFreeOptions
  - cupsGetClasses
  - cupsGetDefault
  - cupsGetDefault2
  - cupsGetDest
  - cupsGetDests
  - cupsGetDests2
  - cupsGetJobs
  - cupsGetJobs2
  - cupsGetNamedDest
  - cupsGetOption
  - cupsGetPPD
  - cupsGetPPD2
  - cupsGetPPD3
  - cupsGetPassword
  - cupsGetPassword2
  - cupsGetPrinters
  - cupsGetServerPPD
  - cupsLangDefault
  - cupsLangEncoding
  - cupsLangFlush
  - cupsLangFree
  - cupsLangGet
  - cupsLastError
  - cupsLastErrorString
  - cupsNotifySubject
  - cupsNotifyText
  - cupsParseOptions
  - cupsPrintFile
  - cupsPrintFile2
  - cupsPrintFiles
  - cupsPrintFiles2
  - cupsRemoveDest
  - cupsRemoveOption
  - cupsServer
  - cupsSetDefaultDest
  - cupsSetDests
  - cupsSetDests2
  - cupsSetEncryption
  - cupsSetPasswordCB
  - cupsSetPasswordCB2
  - cupsSetServer
  - cupsSetUser
  - cupsStartDocument
  - cupsTempFd
  - cupsTempFile
  - cupsTempFile2
  - cupsUser
- Data Types
  - cups_dest_t
  - cups_device_cb_t
  - cups_job_t
  - cups_option_t
  - cups_password_cb2_t
  - cups_password_cb_t
  - cups_ptype_t
- Structures
  - cups_dest_s
  - cups_job_s
  - cups_option_s
- Constants
  - cups_ptype_e

## Overview

The CUPS API provides the convenience functions needed to support applications, filters, printer drivers, and backends that need to interface with the CUPS scheduler.

### Clients and Servers

CUPS is based on the Internet Printing Protocol ("IPP"), which allows clients (applications) to communicate with a server (the scheduler) to get a list of printers, send print jobs, and so forth. You identify which server you want to communicate with using a pointer to the opaque structure `http_t`. All of the examples in this document use the `CUPS_HTTP_DEFAULT` constant, referring to the default connection to the scheduler. The HTTP and IPP APIs document provides more information on server connections.

### Printers and Classes

Printers and classes (collections of printers) are accessed through the `cups_dest_t` structure which includes the name (`name`), instance (`instance` - a way of selecting certain saved options/settings), and the options and attributes associated with that destination (`num_options` and `options`). Destinations are created using the `cupsGetDests` function and freed using the `cupsFreeDests` function. The `cupsGetDest` function finds a specific destination for printing:

    #include <cups/cups.h>

    cups_dest_t *dests;
    int num_dests = cupsGetDests(&dests);
    cups_dest_t *dest = cupsGetDest("name", NULL, num_dests, dests);

    /* do something wiith dest */

    cupsFreeDests(num_dests, dests);

Passing `NULL` to `cupsGetDest` for the destination name will return the default destination. Similarly, passing a `NULL` instance will return the default instance for that destination.

Table 1: Printer Attributes
Attribute Name | Description
--- | ---
"auth-info-required" | The type of authentication required for printing to this destination: "none", "username,password", "domain,username,password", or "negotiate" (Kerberos)
"printer-info" | The human-readable description of the destination such as "My Laser Printer".
"printer-is-accepting-jobs" | "true" if the destination is accepting new jobs, "false" if not.
"printer-is-shared" | "true" if the destination is being shared with other computers, "false" if not.
"printer-location" | The human-readable location of the destination such as "Lab 4".
"printer-make-and-model" | The human-readable make and model of the destination such as "HP LaserJet 4000 Series".
"printer-state" | "3" if the destination is idle, "4" if the destination is printing a job, and "5" if the destination is stopped.
"printer-state-change-time" | The UNIX time when the destination entered the current state.
"printer-state-reasons" | Additional comma-delimited state keywords for the destination such as "media-tray-empty-error" and "toner-low-warning".
"printer-type" | The `cups_printer_t` value associated with the destination.

### Options

Options are stored in arrays of `cups_option_t` structures. Each option has a name (`name`) and value (`value`) associated with it. The `cups_dest_t` `num_options` and `options` members contain the default options for a particular destination, along with several informational attributes about the destination as shown in Table 1. The `cupsGetOption` function gets the value for the named option. For example, the following code lists the available destinations and their human-readable descriptions:

    #include <cups/cups.h>

    cups_dest_t *dests;
    int num_dests = cupsGetDests(&dests);
    cups_dest_t *dest;
    int i;
    const char *value;

    for (i = num_dests, dest = dests; i > 0; i --, dest ++)
      if (dest->instance == NULL)
      {
        value = cupsGetOption("printer-info", dest->num_options, dest->options);
        printf("%s (%s)\n", dest->name, value ? value : "no description");
      }

    cupsFreeDests(num_dests, dests);

You can create your own option arrays using the `cupsAddOption` function, which adds a single named option to an array:

    #include <cups/cups.h>

    int num_options = 0;
    cups_option_t *options = NULL;

    /* The returned num_options value is updated as needed */
    num_options = cupsAddOption("first", "value", num_options, &options);

    /* This adds a second option value */
    num_options = cupsAddOption("second", "value", num_options, &options);

    /* This replaces the first option we added */
    num_options = cupsAddOption("first", "new value", num_options, &options);

Use a `for` loop to copy the options from a destination:

    #include <cups/cups.h>

    int i;
    int num_options = 0;
    cups_option_t *options = NULL;
    cups_dest_t *dest;

    for (i = 0; i < dest->num_options; i ++)
      num_options = cupsAddOption(dest->options[i].name, dest->options[i].value,
                                  num_options, &options);

Use the `cupsFreeOptions` function to free the options array when you are done using it:

    cupsFreeOptions(num_options, options);

### Print Jobs

Print jobs are identified by a locally-unique job ID number from 1 to 231-1 and have options and one or more files for printing to a single destination. The `cupsPrintFile` function creates a new job with one file. The following code prints the CUPS test page file:

    #include <cups/cups.h>

    cups_dest_t *dest;
    int num_options;
    cups_option_t *options;
    int job_id;

    /* Print a single file */
    job_id = cupsPrintFile(dest->name, "/usr/share/cups/data/testprint.ps",
                            "Test Print", num_options, options);

The `cupsPrintFiles` function creates a job with multiple files. The files are provided in a `char *` array:

    #include <cups/cups.h>

    cups_dest_t *dest;
    int num_options;
    cups_option_t *options;
    int job_id;
    char *files[3] = { "file1.pdf", "file2.pdf", "file3.pdf" };

    /* Print three files */
    job_id = cupsPrintFiles(dest->name, 3, files, "Test Print", num_options, options);

Finally, the `cupsCreateJob` function creates a new job with no files in it. Files are added using the `cupsStartDocument`, `cupsWriteRequestData`, and `cupsFinishDocument` functions. The following example creates a job with 10 text files for printing:

    #include <cups/cups.h>

    cups_dest_t *dest;
    int num_options;
    cups_option_t *options;
    int job_id;
    int i;
    char buffer[1024];

    /* Create the job */
    job_id = cupsCreateJob(CUPS_HTTP_DEFAULT, dest->name, "10 Text Files",
                           num_options, options);

    /* If the job is created, add 10 files */
    if (job_id > 0)
    {
      for (i = 1; i <= 10; i ++)
      {
        snprintf(buffer, sizeof(buffer), "file%d.txt", i);

        cupsStartDocument(CUPS_HTTP_DEFAULT, dest->name, job_id, buffer,
                          CUPS_FORMAT_TEXT, i == 10);

        snprintf(buffer, sizeof(buffer),
                 "File %d\n"
                 "\n"
                 "One fish,\n"
                 "Two fish,\n
                 "Red fish,\n
                 "Blue fish\n", i);

        /* cupsWriteRequestData can be called as many times as needed */
        cupsWriteRequestData(CUPS_HTTP_DEFAULT, buffer, strlen(buffer));

        cupsFinishDocument(CUPS_HTTP_DEFAULT, dest->name);
      }
    }

Once you have created a job, you can monitor its status using the `cupsGetJobs` function, which returns an array of `cups_job_t` structures. Each contains the job ID (`id`), destination name (`dest`), title (`title`), and other information associated with the job. The job array is freed using the `cupsFreeJobs` function. The following example monitors a specific job ID, showing the current job state once every 5 seconds until the job is completed:

    #include <cups/cups.h>

    cups_dest_t *dest;
    int job_id;
    int num_jobs;
    cups_job_t *jobs;
    int i;
    ipp_jstate_t job_state = IPP_JOB_PENDING;

    while (job_state < IPP_JOB_STOPPED)
    {
      /* Get my jobs (1) with any state (-1) */
      num_jobs = cupsGetJobs(&jobs, dest->name, 1, -1);

      /* Loop to find my job */
      job_state = IPP_JOB_COMPLETED;

      for (i = 0; i < num_jobs; i ++)
        if (jobs[i].id == job_id)
        {
          job_state = jobs[i].state;
          break;
        }

      /* Free the job array */
      cupsFreeJobs(num_jobs, jobs);

      /* Show the current state */
      switch (job_state)
      {
        case IPP_JOB_PENDING :
            printf("Job %d is pending.\n", job_id);
            break;
        case IPP_JOB_HELD :
            printf("Job %d is held.\n", job_id);
            break;
        case IPP_JOB_PROCESSING :
            printf("Job %d is processing.\n", job_id);
            break;
        case IPP_JOB_STOPPED :
            printf("Job %d is stopped.\n", job_id);
            break;
        case IPP_JOB_CANCELED :
            printf("Job %d is canceled.\n", job_id);
            break;
        case IPP_JOB_ABORTED :
            printf("Job %d is aborted.\n", job_id);
            break;
        case IPP_JOB_COMPLETED :
            printf("Job %d is completed.\n", job_id);
            break;
      }

      /* Sleep if the job is not finished */
      if (job_state < IPP_JOB_STOPPED)
        sleep(5);
    }

To cancel a job, use the `cupsCancelJob` function with the job ID:

    #include <cups/cups.h>

    cups_dest_t *dest;
    int job_id;

    cupsCancelJob(dest->name, job_id);

### Error Handling

If any of the CUPS API printing functions returns an error, the reason for that error can be found by calling the `cupsLastError` and `cupsLastErrorString` functions. `cupsLastError` returns the last IPP error code (`ipp_status_t`) that was encountered, while `cupsLastErrorString` returns a (localized) human-readable string that can be shown to the user. For example, if any of the job creation functions returns a job ID of 0, you can use `cupsLastErrorString` to show the reason why the job could not be created:

    #include <cups/cups.h>

    int job_id;

    if (job_id == 0)
      puts(cupsLastErrorString());

### Passwords and Authentication

CUPS supports authentication of any request, including submission of print jobs. The default mechanism for getting the username and password is to use the login user and a password from the console.

To support other types of applications, in particular Graphical User Interfaces ("GUIs"), the CUPS API provides functions to set the default username and to register a callback function that returns a password string.

The `cupsSetPasswordCB` function is used to set a password callback in your program. Only one function can be used at any time.

The `cupsSetUser` function sets the current username for authentication. This function can be called by your password callback function to change the current username as needed.

The following example shows a simple password callback that gets a username and password from the user:

    #include <cups/cups.h>

    const char *
    my_password_cb(const char *prompt)
    {
      char	user[65];

      puts(prompt);

      /* Get a username from the user */
      printf("Username: ");
      if (fgets(user, sizeof(user), stdin) == NULL)
        return (NULL);

      /* Strip the newline from the string and set the user */
      user[strlen(user) - 1] = '\0';

      cupsSetUser(user);

      /* Use getpass() to ask for the password... */
      return (getpass("Password: "));
    }

    cupsSetPasswordCB(my_password_cb);

Similarly, a GUI could display the prompt string in a window with input fields for the username and password. The username should default to the string returned by the `cupsUser` function.

## Functions

### cupsAddDest

Add a destination to the list of destinations.

int cupsAddDest (
const char *name,
const char *instance,
int num_dests,
cups_dest_t **dests
);

#### Parameters

name
  Destination name
instance
  Instance name or `NULL` for none/primary
num_dests
  Number of destinations
dests
  Destinations

#### Return Value

New number of destinations

#### Discussion

This function cannot be used to add a new class or printer queue, it only adds a new container of saved options for the named destination or instance.
If the named destination already exists, the destination list is returned unchanged. Adding a new instance of a destination creates a copy of that destination's options.
Use the `cupsSaveDests` function to save the updated list of destinations to the user's lpoptions file.

### cupsAddOption

Add an option to an option array.

int cupsAddOption (
const char *name,
const char *value,
int num_options,
cups_option_t **options
);

#### Parameters

name
  Name of option
value
  Value of option
num_options
  Number of options
options
  Pointer to options

#### Return Value

Number of options

#### Discussion

New option arrays can be initialized simply by passing 0 for the "num_options" parameter.

### CUPS 1.2/Mac OS X 10.5 cupsAdminCreateWindowsPPD

Create the Windows PPD file for a printer.

char *cupsAdminCreateWindowsPPD (
http_t *http,
const char *dest,
char *buffer,
int bufsize
);

#### Parameters

http
  Connection to server or `CUPS_HTTP_DEFAULT`
dest
  Printer or class
buffer
  Filename buffer
bufsize
  Size of filename buffer

#### Return Value

PPD file or NULL

### CUPS 1.2/Mac OS X 10.5 cupsAdminExportSamba

Export a printer to Samba.

int cupsAdminExportSamba (
const char *dest,
const char *ppd,
const char *samba_server,
const char *samba_user,
const char *samba_password,
FILE *logfile
);

#### Parameters

dest
  Destination to export
ppd
  PPD file
samba_server
  Samba server
samba_user
  Samba username
samba_password
  Samba password
logfile
  Log file, if any

#### Return Value

1 on success, 0 on failure

### CUPS 1.3/Mac OS X 10.5 cupsAdminGetServerSettings

Get settings from the server.

int cupsAdminGetServerSettings (
http_t *http,
int *num_settings,
cups_option_t **settings
);

#### Parameters

http
  Connection to server or `CUPS_HTTP_DEFAULT`
num_settings
  Number of settings
settings
  Settings

#### Return Value

1 on success, 0 on failure

#### Discussion

The returned settings should be freed with cupsFreeOptions() when you are done with them.

### CUPS 1.3/Mac OS X 10.5 cupsAdminSetServerSettings

Set settings on the server.

int cupsAdminSetServerSettings (
http_t *http,
int num_settings,
cups_option_t *settings
);

#### Parameters

http
  Connection to server or `CUPS_HTTP_DEFAULT`
num_settings
  Number of settings
settings
  Settings

#### Return Value

1 on success, 0 on failure

### cupsCancelJob

Cancel a print job on the default server.

int cupsCancelJob (
const char *name,
int job_id
);

#### Parameters

name
  Name of printer or class
job_id
  Job ID, `CUPS_JOBID_CURRENT` for the current job, or `CUPS_JOBID_ALL` for all jobs

#### Return Value

1 on success, 0 on failure

#### Discussion

Pass `CUPS_JOBID_ALL` to cancel all jobs or `CUPS_JOBID_CURRENT` to cancel the current job on the named destination.
Use the `cupsLastError` and `cupsLastErrorString` functions to get the cause of any failure.

### CUPS 1.4/Mac OS X 10.6 cupsCancelJob2

Cancel or purge a print job.

ipp_status_t cupsCancelJob2 (
http_t *http,
const char *name,
int job_id,
int purge
);

#### Parameters

http
  Connection to server or `CUPS_HTTP_DEFAULT`
name
  Name of printer or class
job_id
  Job ID, `CUPS_JOBID_CURRENT` for the current job, or `CUPS_JOBID_ALL` for all jobs
purge
  1 to purge, 0 to cancel

#### Return Value

IPP status

#### Discussion

Canceled jobs remain in the job history while purged jobs are removed from the job history.
Pass `CUPS_JOBID_ALL` to cancel all jobs or `CUPS_JOBID_CURRENT` to cancel the current job on the named destination.
Use the `cupsLastError` and `cupsLastErrorString` functions to get the cause of any failure.

### CUPS 1.4/Mac OS X 10.6 cupsCreateJob

Create an empty job for streaming.

int cupsCreateJob (
http_t *http,
const char *name,
const char *title,
int num_options,
cups_option_t *options
);

#### Parameters

http
  Connection to server or `CUPS_HTTP_DEFAULT`
name
  Destination name
title
  Title of job
num_options
  Number of options
options
  Options

#### Return Value

Job ID or 0 on error

#### Discussion

Use this function when you want to stream print data using the `cupsStartDocument`, `cupsWriteRequestData`, and `cupsFinishDocument` functions. If you have one or more files to print, use the `cupsPrintFile2` or `cupsPrintFiles2` function instead.

### cupsEncryption

Get the current encryption settings.

http_encryption_t cupsEncryption (void);

#### Return Value

Encryption settings

#### Discussion

The default encryption setting comes from the CUPS_ENCRYPTION environment variable, then the ~/.cups/client.conf file, and finally the /etc/cups/client.conf file. If not set, the default is `HTTP_ENCRYPT_IF_REQUESTED`.
Note: The current encryption setting is tracked separately for each thread in a program. Multi-threaded programs that override the setting via the `cupsSetEncryption` function need to do so in each thread for the same setting to be used.

### CUPS 1.4/Mac OS X 10.6 cupsFinishDocument

Finish sending a document.

ipp_status_t cupsFinishDocument (
http_t *http,
const char *name
);

#### Parameters

http
  Connection to server or `CUPS_HTTP_DEFAULT`
name
  Destination name

#### Return Value

Status of document submission

#### Discussion

The document must have been started using `cupsStartDocument`.

### cupsFreeDests

Free the memory used by the list of destinations.

void cupsFreeDests (
int num_dests,
cups_dest_t *dests
);

#### Parameters

num_dests
  Number of destinations
dests
  Destinations

### cupsFreeJobs

Free memory used by job data.

void cupsFreeJobs (
int num_jobs,
cups_job_t *jobs
);

#### Parameters

num_jobs
  Number of jobs
jobs
  Jobs

### cupsFreeOptions

Free all memory used by options.

void cupsFreeOptions (
int num_options,
cups_option_t *options
);

#### Parameters

num_options
  Number of options
options
  Pointer to options

### DEPRECATED cupsGetClasses

Get a list of printer classes from the default server.

int cupsGetClasses (
char ***classes
);

#### Parameters

classes
  Classes

#### Return Value

Number of classes

#### Discussion

This function is deprecated - use `cupsGetDests` instead.

### cupsGetDefault

Get the default printer or class for the default server.

const char *cupsGetDefault (void);

#### Return Value

Default printer or `NULL`

#### Discussion

This function returns the default printer or class as defined by the LPDEST or PRINTER environment variables. If these environment variables are not set, the server default destination is returned. Applications should use the `cupsGetDests` and `cupsGetDest` functions to get the user-defined default printer, as this function does not support the lpoptions-defined default printer.

### CUPS 1.1.21/Mac OS X 10.4 cupsGetDefault2

Get the default printer or class for the specified server.

const char *cupsGetDefault2 (
http_t *http
);

#### Parameters

http
  Connection to server or `CUPS_HTTP_DEFAULT`

#### Return Value

Default printer or `NULL`

#### Discussion

This function returns the default printer or class as defined by the LPDEST or PRINTER environment variables. If these environment variables are not set, the server default destination is returned. Applications should use the `cupsGetDests` and `cupsGetDest` functions to get the user-defined default printer, as this function does not support the lpoptions-defined default printer.

### cupsGetDest

Get the named destination from the list.

cups_dest_t *cupsGetDest (
const char *name,
const char *instance,
int num_dests,
cups_dest_t *dests
);

#### Parameters

name
  Destination name or `NULL` for the default destination
instance
  Instance name or `NULL`
num_dests
  Number of destinations
dests
  Destinations

#### Return Value

Destination pointer or `NULL`

#### Discussion

Use the `cupsGetDests` or `cupsGetDests2` functions to get a list of supported destinations for the current user.

### cupsGetDests

Get the list of destinations from the default server.

int cupsGetDests (
cups_dest_t **dests
);

#### Parameters

dests
  Destinations

#### Return Value

Number of destinations

#### Discussion

Starting with CUPS 1.2, the returned list of destinations include the printer-info, printer-is-accepting-jobs, printer-is-shared, printer-make-and-model, printer-state, printer-state-change-time, printer-state-reasons, and printer-type attributes as options. CUPS 1.4 adds the marker-change-time, marker-colors, marker-high-levels, marker-levels, marker-low-levels, marker-message, marker-names, marker-types, and printer-commands attributes as well.
Use the `cupsFreeDests` function to free the destination list and the `cupsGetDest` function to find a particular destination.

### CUPS 1.1.21/Mac OS X 10.4 cupsGetDests2

Get the list of destinations from the specified server.

int cupsGetDests2 (
http_t *http,
cups_dest_t **dests
);

#### Parameters

http
  Connection to server or `CUPS_HTTP_DEFAULT`
dests
  Destinations

#### Return Value

Number of destinations

#### Discussion

Starting with CUPS 1.2, the returned list of destinations include the printer-info, printer-is-accepting-jobs, printer-is-shared, printer-make-and-model, printer-state, printer-state-change-time, printer-state-reasons, and printer-type attributes as options. CUPS 1.4 adds the marker-change-time, marker-colors, marker-high-levels, marker-levels, marker-low-levels, marker-message, marker-names, marker-types, and printer-commands attributes as well.
Use the `cupsFreeDests` function to free the destination list and the `cupsGetDest` function to find a particular destination.

### cupsGetJobs

Get the jobs from the default server.

int cupsGetJobs (
cups_job_t **jobs,
const char *name,
int myjobs,
int whichjobs
);

#### Parameters

jobs
  Job data
name
  `NULL` = all destinations, otherwise show jobs for named destination
myjobs
  0 = all users, 1 = mine
whichjobs
  `CUPS_WHICHJOBS_ALL`, `CUPS_WHICHJOBS_ACTIVE`, or `CUPS_WHICHJOBS_COMPLETED`

#### Return Value

Number of jobs

#### Discussion

A "whichjobs" value of `CUPS_WHICHJOBS_ALL` returns all jobs regardless of state, while `CUPS_WHICHJOBS_ACTIVE` returns jobs that are pending, processing, or held and `CUPS_WHICHJOBS_COMPLETED` returns jobs that are stopped, canceled, aborted, or completed.

### CUPS 1.1.21/Mac OS X 10.4 cupsGetJobs2

Get the jobs from the specified server.

int cupsGetJobs2 (
http_t *http,
cups_job_t **jobs,
const char *name,
int myjobs,
int whichjobs
);

#### Parameters

http
  Connection to server or `CUPS_HTTP_DEFAULT`
jobs
  Job data
name
  `NULL` = all destinations, otherwise show jobs for named destination
myjobs
  0 = all users, 1 = mine
whichjobs
  `CUPS_WHICHJOBS_ALL`, `CUPS_WHICHJOBS_ACTIVE`, or `CUPS_WHICHJOBS_COMPLETED`

#### Return Value

Number of jobs

#### Discussion

A "whichjobs" value of `CUPS_WHICHJOBS_ALL` returns all jobs regardless of state, while `CUPS_WHICHJOBS_ACTIVE` returns jobs that are pending, processing, or held and `CUPS_WHICHJOBS_COMPLETED` returns jobs that are stopped, canceled, aborted, or completed.

### CUPS 1.4/Mac OS X 10.6 cupsGetNamedDest

Get options for the named destination.

cups_dest_t *cupsGetNamedDest (
http_t *http,
const char *name,
const char *instance
);

#### Parameters

http
  Connection to server or `CUPS_HTTP_DEFAULT`
name
  Destination name or `NULL` for the default destination
instance
  Instance name or `NULL`

#### Return Value

Destination or `NULL`

#### Discussion

This function is optimized for retrieving a single destination and should be used instead of `cupsGetDests` and `cupsGetDest` when you either know the name of the destination or want to print to the default destination. If `NULL` is returned, the destination does not exist or there is no default destination.
If "http" is `CUPS_HTTP_DEFAULT`, the connection to the default print server will be used.
If "name" is `NULL`, the default printer for the current user will be returned.
The returned destination must be freed using `cupsFreeDests` with a "num_dests" value of 1.

### cupsGetOption

Get an option value.

const char *cupsGetOption (
const char *name,
int num_options,
cups_option_t *options
);

#### Parameters

name
  Name of option
num_options
  Number of options
options
  Options

#### Return Value

Option value or `NULL`

### 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/Mac OS X 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/Mac OS X 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_OK` is returned for a new PPD file and `HTTP_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.

### cupsGetPassword

Get a password from the user.

const char *cupsGetPassword (
const char *prompt
);

#### Parameters

prompt
  Prompt string

#### Return Value

Password

#### Discussion

Uses the current password callback function. Returns `NULL` if the user does not provide a password.
Note: The current password callback function is tracked separately for each thread in a program. Multi-threaded programs that override the setting via the `cupsSetPasswordCB` or `cupsSetPasswordCB2` functions need to do so in each thread for the same function to be used.

### CUPS 1.4/Mac OS X 10.6 cupsGetPassword2

Get a password from the user using the advanced password callback.

const char *cupsGetPassword2 (
const char *prompt,
http_t *http,
const char *method,
const char *resource
);

#### Parameters

prompt
  Prompt string
http
  Connection to server or `CUPS_HTTP_DEFAULT`
method
  Request method ("GET", "POST", "PUT")
resource
  Resource path

#### Return Value

Password

#### Discussion

Uses the current password callback function. Returns `NULL` if the user does not provide a password.
Note: The current password callback function is tracked separately for each thread in a program. Multi-threaded programs that override the setting via the `cupsSetPasswordCB` or `cupsSetPasswordCB2` functions need to do so in each thread for the same function to be used.

### DEPRECATED cupsGetPrinters

Get a list of printers from the default server.

int cupsGetPrinters (
char ***printers
);

#### Parameters

printers
  Printers

#### Return Value

Number of printers

#### Discussion

This function is deprecated - use `cupsGetDests` instead.

### CUPS 1.3/Mac OS X 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`.

### cupsLangDefault

Return the default language.

cups_lang_t *cupsLangDefault (void);

#### Return Value

Language data

### cupsLangEncoding

Return the character encoding (us-ascii, etc.) for the given language.

const char *cupsLangEncoding (
cups_lang_t *lang
);

#### Parameters

lang
  Language data

#### Return Value

Character encoding

### cupsLangFlush

Flush all language data out of the cache.

void cupsLangFlush (void);

### cupsLangFree

Free language data.

void cupsLangFree (
cups_lang_t *lang
);

#### Parameters

lang
  Language to free

#### Discussion

This does not actually free anything; use `cupsLangFlush` for that.

### cupsLangGet

Get a language.

cups_lang_t *cupsLangGet (
const char *language
);

#### Parameters

language
  Language or locale

#### Return Value

Language data

### cupsLastError

Return the last IPP status code.

ipp_status_t cupsLastError (void);

#### Return Value

IPP status code from last request

### CUPS 1.2/Mac OS X 10.5 cupsLastErrorString

Return the last IPP status-message.

const char *cupsLastErrorString (void);

#### Return Value

status-message text from last request

### CUPS 1.2/Mac OS X 10.5 cupsNotifySubject

Return the subject for the given notification message.

char *cupsNotifySubject (
cups_lang_t *lang,
ipp_t *event
);

#### Parameters

lang
  Language data
event
  Event data

#### Return Value

Subject string or `NULL`

#### Discussion

The returned string must be freed by the caller using `free`.

### CUPS 1.2/Mac OS X 10.5 cupsNotifyText

Return the text for the given notification message.

char *cupsNotifyText (
cups_lang_t *lang,
ipp_t *event
);

#### Parameters

lang
  Language data
event
  Event data

#### Return Value

Message text or `NULL`

#### Discussion

The returned string must be freed by the caller using `free`.

### cupsParseOptions

Parse options from a command-line argument.

int cupsParseOptions (
const char *arg,
int num_options,
cups_option_t **options
);

#### Parameters

arg
  Argument to parse
num_options
  Number of options
options
  Options found

#### Return Value

Number of options found

#### Discussion

This function converts space-delimited name/value pairs according to the PAPI text option ABNF specification. Collection values ("name={a=... b=... c=...}") are stored with the curley brackets intact - use `cupsParseOptions` on the value to extract the collection attributes.

### cupsPrintFile

Print a file to a printer or class on the default server.

int cupsPrintFile (
const char *name,
const char *filename,
const char *title,
int num_options,
cups_option_t *options
);

#### Parameters

name
  Destination name
filename
  File to print
title
  Title of job
num_options
  Number of options
options
  Options

#### Return Value

Job ID or 0 on error

### CUPS 1.1.21/Mac OS X 10.4 cupsPrintFile2

Print a file to a printer or class on the specified server.

int cupsPrintFile2 (
http_t *http,
const char *name,
const char *filename,
const char *title,
int num_options,
cups_option_t *options
);

#### Parameters

http
  Connection to server
name
  Destination name
filename
  File to print
title
  Title of job
num_options
  Number of options
options
  Options

#### Return Value

Job ID or 0 on error

### cupsPrintFiles

Print one or more files to a printer or class on the default server.

int cupsPrintFiles (
const char *name,
int num_files,
const char **files,
const char *title,
int num_options,
cups_option_t *options
);

#### Parameters

name
  Destination name
num_files
  Number of files
files
  File(s) to print
title
  Title of job
num_options
  Number of options
options
  Options

#### Return Value

Job ID or 0 on error

### CUPS 1.1.21/Mac OS X 10.4 cupsPrintFiles2

Print one or more files to a printer or class on the specified server.

int cupsPrintFiles2 (
http_t *http,
const char *name,
int num_files,
const char **files,
const char *title,
int num_options,
cups_option_t *options
);

#### Parameters

http
  Connection to server or `CUPS_HTTP_DEFAULT`
name
  Destination name
num_files
  Number of files
files
  File(s) to print
title
  Title of job
num_options
  Number of options
options
  Options

#### Return Value

Job ID or 0 on error

### CUPS 1.3/Mac OS X 10.5 cupsRemoveDest

Remove a destination from the destination list.

int cupsRemoveDest (
const char *name,
const char *instance,
int num_dests,
cups_dest_t **dests
);

#### Parameters

name
  Destination name
instance
  Instance name or `NULL`
num_dests
  Number of destinations
dests
  Destinations

#### Return Value

New number of destinations

#### Discussion

Removing a destination/instance does not delete the class or printer queue, merely the lpoptions for that destination/instance. Use the `cupsSetDests` or `cupsSetDests2` functions to save the new options for the user.

### CUPS 1.2/Mac OS X 10.5 cupsRemoveOption

Remove an option from an option array.

int cupsRemoveOption (
const char *name,
int num_options,
cups_option_t **options
);

#### Parameters

name
  Option name
num_options
  Current number of options
options
  Options

#### Return Value

New number of options

### cupsServer

Return the hostname/address of the current server.

const char *cupsServer (void);

#### Return Value

Server name

#### Discussion

The default server comes from the CUPS_SERVER environment variable, then the ~/.cups/client.conf file, and finally the /etc/cups/client.conf file. If not set, the default is the local system - either "localhost" or a domain socket path.
The returned value can be a fully-qualified hostname, a numeric IPv4 or IPv6 address, or a domain socket pathname.
Note: The current server is tracked separately for each thread in a program. Multi-threaded programs that override the server via the `cupsSetServer` function need to do so in each thread for the same server to be used.

### CUPS 1.3/Mac OS X 10.5 cupsSetDefaultDest

Set the default destination.

void cupsSetDefaultDest (
const char *name,
const char *instance,
int num_dests,
cups_dest_t *dests
);

#### Parameters

name
  Destination name
instance
  Instance name or `NULL`
num_dests
  Number of destinations
dests
  Destinations

### cupsSetDests

Save the list of destinations for the default server.

void cupsSetDests (
int num_dests,
cups_dest_t *dests
);

#### Parameters

num_dests
  Number of destinations
dests
  Destinations

#### Discussion

This function saves the destinations to /etc/cups/lpoptions when run as root and ~/.cups/lpoptions when run as a normal user.

### CUPS 1.1.21/Mac OS X 10.4 cupsSetDests2

Save the list of destinations for the specified server.

int cupsSetDests2 (
http_t *http,
int num_dests,
cups_dest_t *dests
);

#### Parameters

http
  Connection to server or `CUPS_HTTP_DEFAULT`
num_dests
  Number of destinations
dests
  Destinations

#### Return Value

0 on success, -1 on error

#### Discussion

This function saves the destinations to /etc/cups/lpoptions when run as root and ~/.cups/lpoptions when run as a normal user.

### cupsSetEncryption

Set the encryption preference.

void cupsSetEncryption (
http_encryption_t e
);

#### Parameters

e
  New encryption preference

#### Discussion

The default encryption setting comes from the CUPS_ENCRYPTION environment variable, then the ~/.cups/client.conf file, and finally the /etc/cups/client.conf file. If not set, the default is `HTTP_ENCRYPT_IF_REQUESTED`.
Note: The current encryption setting is tracked separately for each thread in a program. Multi-threaded programs that override the setting need to do so in each thread for the same setting to be used.

### cupsSetPasswordCB

Set the password callback for CUPS.

void cupsSetPasswordCB (
cups_password_cb_t cb
);

#### Parameters

cb
  Callback function

#### Discussion

Pass `NULL` to restore the default (console) password callback, which reads the password from the console. Programs should call either this function or `cupsSetPasswordCB2`, as only one callback can be registered by a program per thread.
Note: The current password callback is tracked separately for each thread in a program. Multi-threaded programs that override the callback need to do so in each thread for the same callback to be used.

### CUPS 1.4/Mac OS X 10.6 cupsSetPasswordCB2

Set the advanced password callback for CUPS.

void cupsSetPasswordCB2 (
cups_password_cb2_t cb,
void *user_data
);

#### Parameters

cb
  Callback function
user_data
  User data pointer

#### Discussion

Pass `NULL` to restore the default (console) password callback, which reads the password from the console. Programs should call either this function or `cupsSetPasswordCB2`, as only one callback can be registered by a program per thread.
Note: The current password callback is tracked separately for each thread in a program. Multi-threaded programs that override the callback need to do so in each thread for the same callback to be used.

### cupsSetServer

Set the default server name and port.

void cupsSetServer (
const char *server
);

#### Parameters

server
  Server name

#### Discussion

The "server" string can be a fully-qualified hostname, a numeric IPv4 or IPv6 address, or a domain socket pathname. Hostnames and numeric IP addresses can be optionally followed by a colon and port number to override the default port 631, e.g. "hostname:8631". Pass `NULL` to restore the default server name and port.
Note: The current server is tracked separately for each thread in a program. Multi-threaded programs that override the server need to do so in each thread for the same server to be used.

### cupsSetUser

Set the default user name.

void cupsSetUser (
const char *user
);

#### Parameters

user
  User name

#### Discussion

Pass `NULL` to restore the default user name.
Note: The current user name is tracked separately for each thread in a program. Multi-threaded programs that override the user name need to do so in each thread for the same user name to be used.

### CUPS 1.4/Mac OS X 10.6 cupsStartDocument

Add a document to a job created with cupsCreateJob().

http_status_t cupsStartDocument (
http_t *http,
const char *name,
int job_id,
const char *docname,
const char *format,
int last_document
);

#### Parameters

http
  Connection to server or `CUPS_HTTP_DEFAULT`
name
  Destination name
job_id
  Job ID from `cupsCreateJob`
docname
  Name of document
format
  MIME type or `CUPS_FORMAT_foo`
last_document
  1 for last document in job, 0 otherwise

#### Return Value

HTTP status of request

#### Discussion

Use `cupsWriteRequestData` to write data for the document and `cupsFinishDocument` to finish the document and get the submission status.
The MIME type constants `CUPS_FORMAT_AUTO`, `CUPS_FORMAT_PDF`, `CUPS_FORMAT_POSTSCRIPT`, `CUPS_FORMAT_RAW`, and `CUPS_FORMAT_TEXT` are provided for the "format" argument, although any supported MIME type string can be supplied.

### cupsTempFd

Creates a temporary file.

int cupsTempFd (
char *filename,
int len
);

#### Parameters

filename
  Pointer to buffer
len
  Size of buffer

#### Return Value

New file descriptor or -1 on error

#### Discussion

The temporary filename is returned in the filename buffer. The temporary file is opened for reading and writing.

### DEPRECATED cupsTempFile

Generates a temporary filename.

char *cupsTempFile (
char *filename,
int len
);

#### Parameters

filename
  Pointer to buffer
len
  Size of buffer

#### Return Value

Filename or `NULL` on error

#### Discussion

The temporary filename is returned in the filename buffer. This function is deprecated - use `cupsTempFd` or `cupsTempFile2` instead.

### CUPS 1.2/Mac OS X 10.5 cupsTempFile2

Creates a temporary CUPS file.

cups_file_t *cupsTempFile2 (
char *filename,
int len
);

#### Parameters

filename
  Pointer to buffer
len
  Size of buffer

#### Return Value

CUPS file or `NULL` on error

#### Discussion

The temporary filename is returned in the filename buffer. The temporary file is opened for writing.

### cupsUser

Return the current user's name.

const char *cupsUser (void);

#### Return Value

User name

#### Discussion

Note: The current user name is tracked separately for each thread in a program. Multi-threaded programs that override the user name with the `cupsSetUser` function need to do so in each thread for the same user name to be used.

## Data Types

### cups_dest_t

Destination

typedef struct cups_dest_s cups_dest_t;

### CUPS 1.4/Mac OS X 10.6 cups_device_cb_t

Device callback

typedef void (*cups_device_cb_t)(const char *device_class, const char *device_id, const char *device_info, const char *device_make_and_model, const char *device_uri, const char *device_location, void *user_data);

### cups_job_t

Job

typedef struct cups_job_s cups_job_t;

### cups_option_t

Printer Options

typedef struct cups_option_s cups_option_t;

### CUPS 1.4/Mac OS X 10.6 cups_password_cb2_t

New password callback

typedef const char *(*cups_password_cb2_t)(const char *prompt, http_t *http, const char *method, const char *resource, void *user_data);

### cups_password_cb_t

Password callback

typedef const char *(*cups_password_cb_t)(const char *prompt);

### cups_ptype_t

Printer type/capability bits

typedef unsigned cups_ptype_t;

## Structures

### cups_dest_s

Destination

struct cups_dest_s {
char *name, *instance;
int is_default;
int num_options;
cups_option_t *options;
};

#### Members

instance
  Local instance name or NULL
is_default
  Is this printer the default?
num_options
  Number of options
options
  Options

### cups_job_s

Job

struct cups_job_s {
time_t completed_time;
time_t creation_time;
char *dest;
char *format;
int id;
int priority;
time_t processing_time;
int size;
ipp_jstate_t state;
char *title;
char *user;
};

#### Members

completed_time
  Time the job was completed
creation_time
  Time the job was created
dest
  Printer or class name
format
  Document format
id
  The job ID
priority
  Priority (1-100)
processing_time
  Time the job was processed
size
  Size in kilobytes
state
  Job state
title
  Title/job name
user
  User the submitted the job

### cups_option_s

Printer Options

struct cups_option_s {
char *name;
char *value;
};

#### Members

name
  Name of option
value
  Value of option

## Constants

### cups_ptype_e

Printer type/capability bit constants

#### Constants

CUPS_PRINTER_AUTHENTICATED CUPS 1.2/Mac OS X 10.5
  Printer requires authentication
CUPS_PRINTER_BIND
  Can bind output
CUPS_PRINTER_BW
  Can do B&W printing
CUPS_PRINTER_CLASS
  Printer class
CUPS_PRINTER_COLLATE
  Can collage copies
CUPS_PRINTER_COLOR
  Can do color printing
CUPS_PRINTER_COMMANDS CUPS 1.2/Mac OS X 10.5
  Printer supports maintenance commands
CUPS_PRINTER_COPIES
  Can do copies
CUPS_PRINTER_COVER
  Can cover output
CUPS_PRINTER_DEFAULT
  Default printer on network
CUPS_PRINTER_DELETE CUPS 1.2/Mac OS X 10.5
  Delete printer
CUPS_PRINTER_DISCOVERED CUPS 1.3/Mac OS X 10.5
  Printer was automatically discovered and added
CUPS_PRINTER_DUPLEX
  Can do duplexing
CUPS_PRINTER_FAX
  Fax queue
CUPS_PRINTER_IMPLICIT
  Implicit class
CUPS_PRINTER_LARGE
  Can do D/E/A1/A0
CUPS_PRINTER_LOCAL
  Local printer or class
CUPS_PRINTER_MEDIUM
  Can do Tabloid/B/C/A3/A2
CUPS_PRINTER_MFP CUPS 1.4/Mac OS X 10.6
  Printer with scanning capabilities
CUPS_PRINTER_NOT_SHARED CUPS 1.2/Mac OS X 10.5
  Printer is not shared
CUPS_PRINTER_PUNCH
  Can punch output
CUPS_PRINTER_REJECTING
  Printer is rejecting jobs
CUPS_PRINTER_REMOTE
  Remote printer or class
CUPS_PRINTER_SCANNER CUPS 1.4/Mac OS X 10.6
  Scanner-only device
CUPS_PRINTER_SMALL
  Can do Letter/Legal/A4
CUPS_PRINTER_SORT
  Can sort output
CUPS_PRINTER_STAPLE
  Can staple output
CUPS_PRINTER_VARIABLE
  Can do variable sizes