# libcups(3)

## Name

libcups - cups api library

## Library

pkg-config --cflags cups3
pkg-config --libs cups3

## Synopsis

#include <cups/cups.h>

## Description

CUPS 3.0 provides the "cups3" library to talk to the different parts of CUPS and with Internet Printing Protocol (IPP) printers. The "cups" library functions are accessed by including the <cups/cups.h> header.

CUPS is based on the Internet Printing Protocol ("IPP"), which allows clients (applications) to communicate with a server (the scheduler, printers, etc.) to get a list of destinations, send print jobs, and so forth. You identify which server you want to communicate with using a pointer to the opaque structure http_t. The CUPS_HTTP_DEFAULT constant can be used when you want to talk to the default CUPS spooler.

Printers are represented as destinations using the cups_dest_t structure which defines the local name as well as status and identification information such as the printer's Univeral Resource Identifier (URI), location, and model. The cupsEnumDests and cupsGetDests functions can be used to get a list of available destinations while the cupsGetNamedDest function can be used to get a single named destination.

Capability and localization information for a destination is separately contained in the cups_dinfo_t structure and is queried using the cupsCopyDestInfo function. The cupsCreateDestJob function creates a print job on a destination and the cupsStartDestDocument, cupsWriteRequestData, and cupsFinishDestDocument functions add a document to the print job.

## Example

The following simple program lists the available destinations:

    #include <stdio.h>
    #include <cups/cups.h>

    bool print_dest(void *cb_data, unsigned flags, cups_dest_t *dest)
    {
      if (dest->instance)
        printf("%s/%s\n", dest->name, dest->instance);
      else
        puts(dest->name);

      return (true);
    }

    int main(void)
    {
      cupsEnumDests(CUPS_DEST_FLAGS_NONE, 1000, NULL, 0, 0, print_dest, NULL);

      return (0);
    }

## See Also

cups(1), CUPS 3.0 Programming Manual

## Copyright

Copyright © 2025 by OpenPrinting.