# backend

## NAME



           backend - cups backend transmission interfaces
    


## SYNOPSIS



           **backend**
           **backend** _job user title num-copies options_ [ _filename_ ]
    
           **#include <cups/cups.h>**
    
           **const char *cupsBackendDeviceURI**(**char ****_argv_);
    
           **void cupsBackendReport**(**const char ***_device_scheme_ ,
                                  **const char ***_device_uri_ ,
                                  **const char ***_device_make_and_model_ ,
                                  **const char ***_device_info_ ,
                                  **const char ***_device_id_ ,
                                  **const char ***_device_location_);
    
           **ssize_t cupsBackChannelWrite**(**const char ***_buffer_ ,
                                        **size_t** _bytes_ , **double** _timeout_);
    
           **int cupsSideChannelRead**(**cups_sc_command_t ***_command_ ,
                                   **cups_sc_status_t ***_status_ , **char ***_data_ ,
                                   **int ***_datalen_ , **double** _timeout_);
    
           **int cupsSideChannelWrite**(**cups_sc_command_t** _command_ ,
                                    **cups_sc_status_t** _status_ , **const char ***_data_ ,
                                    **int** _datalen_ , **double** _timeout_);
    


## DESCRIPTION



           Backends are a special type of filter(7) which is used to send
           print data to and discover different devices on the system.
    
           Like filters, backends must be capable of reading from a filename
           on the command-line or from the standard input, copying the
           standard input to a temporary file as required by the physical
           interface.
    
           The command name (_argv[0]_) is set to the device URI of the
           destination printer.  Authentication information in _argv[0]_ is
           removed, so backend developers are urged to use the **DEVICE_URI**
           environment variable whenever authentication information is
           required. The **cupsBackendDeviceURI**() function may be used to
           retrieve the correct device URI.
    
           Back-channel data from the device should be relayed to the job
           filters using the _cupsBackChannelWrite_ function.
    
           Backends are responsible for reading side-channel requests using
           the **cupsSideChannelRead**() function and responding with the
           **cupsSideChannelWrite**() function. The **CUPS_SC_FD** constant defines
           the file descriptor that should be monitored for incoming
           requests.
    
       **DEVICE DISCOVERY**
           When run with no arguments, the backend should list the devices
           and schemes it supports or is advertising to the standard output.
           The output consists of zero or more lines consisting of any of the
           following forms:
    
               device-class scheme "Unknown" "device-info"
               device-class device-uri "device-make-and-model" "device-info"
               device-class device-uri "device-make-and-model" "device-info" "device-id"
               device-class device-uri "device-make-and-model" "device-info" "device-id" "device-location"
    
           The **cupsBackendReport**() function can be used to generate these
           lines and handle any necessary escaping of characters in the
           various strings.
    
           The _device-class_ field is one of the following values:
    
           **direct**
                The device-uri refers to a specific direct-access device with
                no options, such as a parallel, USB, or SCSI device.
    
           **file** The device-uri refers to a file on disk.
    
           **network**
                The device-uri refers to a networked device and conforms to
                the general form for network URIs.
    
           **serial**
                The device-uri refers to a serial device with configurable
                baud rate and other options.  If the device-uri contains a
                baud value, it represents the maximum baud rate supported by
                the device.
    
           The _scheme_ field provides the URI scheme that is supported by the
           backend.  Backends should use this form only when the backend
           supports any URI using that scheme.  The _device-uri_ field
           specifies the full URI to use when communicating with the device.
    
           The _device-make-and-model_ field specifies the make and model of
           the device, e.g. "Example Foojet 2000".  If the make and model is
           not known, you must report "Unknown".
    
           The _device-info_ field specifies additional information about the
           device.  Typically this includes the make and model along with the
           port number or network address, e.g. "Example Foojet 2000 USB #1".
    
           The optional _device-id_ field specifies the IEEE-1284 device ID
           string for the device, which is used to select a matching driver.
    
           The optional _device-location_ field specifies the physical location
           of the device, which is often used to pre-populate the printer-
           location attribute when adding a printer.
    
       **PERMISSIONS**
           Backends without world read and execute permissions are run as the
           root user.  Otherwise, the backend is run using an unprivileged
           user account, typically "lp".
    


## EXIT STATUS



           The following exit codes are defined for backends:
    
           **CUPS_BACKEND_OK**
                The print file was successfully transmitted to the device or
                remote server.
    
           **CUPS_BACKEND_FAILED**
                The print file was not successfully transmitted to the device
                or remote server.  The scheduler will respond to this by
                canceling the job, retrying the job, or stopping the queue
                depending on the state of the _printer-error-policy_ attribute.
    
           **CUPS_BACKEND_AUTH_REQUIRED**
                The print file was not successfully transmitted because valid
                authentication information is required.  The scheduler will
                respond to this by holding the job and adding the 'cups-held-
                for-authentication' keyword to the "job-reasons" Job
                Description attribute.
    
           **CUPS_BACKEND_HOLD**
                The print file was not successfully transmitted because it
                cannot be printed at this time.  The scheduler will respond
                to this by holding the job.
    
           **CUPS_BACKEND_STOP**
                The print file was not successfully transmitted because it
                cannot be printed at this time.  The scheduler will respond
                to this by stopping the queue.
    
           **CUPS_BACKEND_CANCEL**
                The print file was not successfully transmitted because one
                or more attributes are not supported or the job was canceled
                at the printer.  The scheduler will respond to this by
                canceling the job.
    
           **CUPS_BACKEND_RETRY**
                The print file was not successfully transmitted because of a
                temporary issue.  The scheduler will retry the job at a
                future time - other jobs may print before this one.
    
           **CUPS_BACKEND_RETRY_CURRENT**
                The print file was not successfully transmitted because of a
                temporary issue.  The scheduler will retry the job
                immediately without allowing intervening jobs.
    
           All other exit code values are reserved.
    


## ENVIRONMENT



           In addition to the environment variables listed in cups(1) and
           filter(7), CUPS backends can expect the following environment
           variable:
    
           **DEVICE_URI**
                The device URI associated with the printer.
    


## FILES



           _/etc/cups/cups-files.conf_
    


## NOTES



           CUPS backends are not generally designed to be run directly by the
           user.  Aside from the device URI issue ( _argv[0]_ and **DEVICE_URI**
           environment variable contain the device URI), CUPS backends also
           expect specific environment variables and file descriptors, and
           typically run in a user session that (on macOS) has additional
           restrictions that affect how it runs.  Backends can also be
           installed with restricted permissions (0500 or 0700) that tell the
           scheduler to run them as the "root" user instead of an
           unprivileged user (typically "lp") on the system.
    
           Unless you are a developer and know what you are doing, please do
           not run backends directly.  Instead, use the lp(1) or lpr(1)
           programs to send print jobs or lpinfo(8) to query for available
           printers using the backend.  The one exception is the SNMP backend
           - see cups-snmp(8) for more information.
    


## NOTES



           CUPS printer drivers and backends are deprecated and will no
           longer be supported in a future feature release of CUPS.  Printers
           that do not support IPP can be supported using applications such
           as ippeveprinter(1).
    


* * *