pappl-job(3)

📦

version 1.4.12 · 5 versions

1.4.12 · arch rolling, fedora 43, fedora 44, nixpkgs unstable (latest)
1.4.7 · opensuse-leap 16.0
1.0.3 · ubuntu jammy
1.4.9 · fedora 43, fedora 44, nixos 26.05, ubuntu questing, ubuntu resolute, ubuntu stonking
1.3.1 · debian bookworm, debian trixie, ubuntu noble

, in arch rolling, fedora 43, fedora 44, nixpkgs unstable

✨ NAME ✨

pappl-job — pappl job functions 💖

okay so this is the pappl-job(3) page, aka the pappl job functions, and bestie we are about to get so cozy with the job object. this is part 1 of 2 so buckle up 🎀

📚 LIBRARY 📚

Printer Application Framework (libpappl, pkg-config --cflags --libs pappl) 🫶

🌈 SYNOPSIS 🌈

#include <pappl/pappl.h>

typedef struct _pappl_job_s pappl_job_t;

void
papplJobCancel(pappl_job_t *job);

bool
papplJobFilterImage(pappl_job_t *job, pappl_device_t *device,
pappl_joptions_t *options, const unsigned char *pixels, unsigned width,
unsigned height, unsigned depth, bool smoothing);

ipp_attribute_t     *
papplJobGetAttribute(pappl_job_t *job, const char *name);

void      *
papplJobGetData(pappl_job_t *job);

const char     *
papplJobGetFilename(pappl_job_t *job);

const char     *
papplJobGetFormat(pappl_job_t *job);

int
papplJobGetID(pappl_job_t *job);

int
papplJobGetImpressions(pappl_job_t *job);

int
papplJobGetImpressionsCompleted(pappl_job_t *job);

const char     *
papplJobGetMessage(pappl_job_t *job);

const char     *
papplJobGetName(pappl_job_t *job);

pappl_joptions_t    *
papplJobGetOptions(pappl_job_t *job, pappl_joptions_t *options, unsigned
num_pages, bool color);

pappl_printer_t     *
papplJobGetPrinter(pappl_job_t *job);

pappl_jreason_t
papplJobGetReasons(pappl_job_t *job);

ipp_jstate_t
papplJobGetState(pappl_job_t *job);

time_t
papplJobGetTimeCompleted(pappl_job_t *job);

time_t
papplJobGetTimeCreated(pappl_job_t *job);

time_t
papplJobGetTimeProcessed(pappl_job_t *job);

const char     *
papplJobGetUsername(pappl_job_t *job);

bool
papplJobIsCanceled(pappl_job_t *job);

int
papplJobOpenFile(pappl_job_t *job, char *fname, size_t fnamesize, const
char *directory, const char *ext, const char *mode);

void
papplJobSetData(pappl_job_t *job, void *data);

void
papplJobSetImpressions(pappl_job_t *job, int impressions);

void
papplJobSetImpressionsCompleted(pappl_job_t *job, int add);

void
papplJobSetMessage(pappl_job_t *job, const char *message, ...);

void
papplJobSetReasons(pappl_job_t *job, pappl_jreason_t add,
pappl_jreason_t remove);

💅 heads up bestie: the SYNOPSIS up there and the FUNCTIONS list further down do not agree on every signature — they're both reproduced here exactly as the page has them, so trust the one you're actually calling. no editing, no "fixing", that's the vibe. ✨

💖 DESCRIPTION 💖

The PAPPL job functions give you access to the job object 🫶. Jobs, and the whole entire life cycle of the pappl_job_t objects, are managed automatically by the system object for the printer application. so like, you're not the one raising them, the system is the parent here, no cap 👑

The papplJobGet functions get the current values associated with a job, while the papplJobSet functions set the current values associated with a job. get and set. iconic pairing, honestly 🌸

The papplJobCancel function cancels processing of a job, while the papplJobIsCanceled function returns whether a job is in the canceled state (IPP_JSTATE_CANCELED) or is in the process of being canceled (IPP_JSTATE_PROCESSING and PAPPL_JREASON_PROCESSING_TO_STOP_POINT). so yes, there's a whole process of canceling, it's giving ✨main character exit✨ 😭

The papplJobOpenFile function opens a file associated with the job.

🚨 the file descriptor must be closed by the caller using the close(2) system call. not optional, not a suggestion, close your fds bestie, leaking them is not the slay you think it is 💀

The papplJobFilterImage function converts raw image data to raster data suitable for the printer. glow-up, but for pixels 💅

🔥 ENUMERATIONS 🔥

`pappl_jreason_e`

IPP "job-state-reasons" bit values 🌈

PAPPL_JREASON_ABORTED_BY_SYSTEM — 'aborted-by-system'
PAPPL_JREASON_COMPRESSION_ERROR — 'compression-error'
PAPPL_JREASON_DOCUMENT_FORMAT_ERROR — 'document-format-error'
PAPPL_JREASON_DOCUMENT_PASSWORD_ERROR — 'document-password-error'
PAPPL_JREASON_DOCUMENT_PERMISSION_ERROR — 'document-permission-error'
PAPPL_JREASON_DOCUMENT_UNPRINTABLE_ERROR — 'document-unprintable-error'
PAPPL_JREASON_ERRORS_DETECTED — 'errors-detected'
PAPPL_JREASON_JOB_CANCELED_AFTER_TIMEOUT — 'job-canceled-after-timeout'
PAPPL_JREASON_JOB_CANCELED_AT_DEVICE — 'job-canceled-at-device'
PAPPL_JREASON_JOB_CANCELED_BY_USER — 'job-canceled-by-user'
PAPPL_JREASON_JOB_COMPLETED_SUCCESSFULLY — 'job-completed-successfully'
PAPPL_JREASON_JOB_COMPLETED_WITH_ERRORS — 'job-completed-with-errors'
PAPPL_JREASON_JOB_COMPLETED_WITH_WARNINGS — 'job-completed-with-warnings'
PAPPL_JREASON_JOB_DATA_INSUFFICIENT — 'job-data-insufficient'
PAPPL_JREASON_JOB_FETCHABLE — 'job-fetchable'
PAPPL_JREASON_JOB_HOLD_UNTIL_SPECIFIED — 'job-hold-until-specified'
PAPPL_JREASON_JOB_INCOMING — 'job-incoming'
PAPPL_JREASON_JOB_PRINTING — 'job-printing'
PAPPL_JREASON_JOB_QUEUED — 'job-queued'
PAPPL_JREASON_JOB_SPOOLING — 'job-spooling'
PAPPL_JREASON_JOB_SUSPENDED_FOR_APPROVAL — 'job-suspended-for-approval'
PAPPL_JREASON_NONE — 'none'
PAPPL_JREASON_PRINTER_STOPPED — 'printer-stopped'
PAPPL_JREASON_PRINTER_STOPPED_PARTLY — 'printer-stopped-partly'
PAPPL_JREASON_PROCESSING_TO_STOP_POINT — 'processing-to-stop-point'
PAPPL_JREASON_QUEUED_IN_DEVICE — 'queued-in-device'
PAPPL_JREASON_WARNINGS_DETECTED — 'warnings-detected'

🌸 FUNCTIONS 🌸

🎀 `papplJobCancel`

Cancel a job.

void papplJobCancel (
    pappl_job_t *job
);

This function cancels the specified job 💅. If the job is currently being printed, it will be stopped at a convenient time (usually the end of a page) so that the printer will be left in a known state. so like, no ripping the paper out mid-page, we do a graceful exit bestie 🦋

🎀 `papplJobCreatePrintOptions`

Create the printer options for a job.

pappl_pr_options_t * papplJobCreatePrintOptions (
    pappl_job_t *job,
    unsigned num_pages,
    bool color
);

This function allocates a printer options structure and computes the print options for a job based upon the Job Template attributes submitted in the print request and the default values set in the printer driver data. it's giving ✨bespoke✨, tailored to your job specifically 💖

The "num_pages" and "color" arguments specify the number of pages and whether the document contains non-grayscale colors — this information typically comes from parsing the job file. so you gotta actually read the file first, no skipping steps 📖

🎀 `papplJobCreateWithFile`

Create a job with a local file.

pappl_job_t * papplJobCreateWithFile (
    pappl_printer_t *printer,
    const char *username,
    const char *format,
    const char *job_name,
    int num_options,
    cups_option_t *options,
    const char *filename
);

This function creates a new print job with a local file 🫶. The "num_options" and "options" parameters specify additional print options, as needed. and the file specified by "filename" is removed automatically if it resides in the spool directory. it cleans up after itself, we love a low-maintenance icon ✨

🎀 `papplJobDeletePrintOptions`

Delete a job options structure.

void papplJobDeletePrintOptions (
    pappl_pr_options_t *options
);

This function frees the memory used for a job options structure. bye bestie, thanks for the options 👋💜

🎀 `papplJobFilterImage`

Filter an image in memory.

bool  papplJobFilterImage (
    pappl_job_t *job,
    pappl_device_t *device,
    pappl_pr_options_t *options,
    const unsigned char *pixels,
    int width,
    int height,
    int depth,
    int ppi,
    bool smoothing
);

This function will print a grayscale or sRGB image using the printer's raster driver interface, scaling and positioning the image as necessary based on the job options, and printing as many copies as requested. it handles the whole glow-up AND the placement AND the copies, absolutely carrying the team 💅🔥

The image data is an array of grayscale ("depth" = 1) or sRGB ("depth" = 3) pixels starting at the top-left corner of the image. top-left origin, as nature intended 🎀

The image resolution ("ppi") is expressed in pixels per inch and is used for some "print-scaling" modes. Pass 0 if the image has no explicit resolution information. no vibes-based guessing, just pass 0 bestie 🫶

🎀 `papplJobGetAttribute`

Get an attribute from a job.

ipp_attribute_t * papplJobGetAttribute (
    pappl_job_t *job,
    const char *name
);

This function gets the named IPP attribute from a job. The returned attribute can be examined using the ippGetXxx functions. go forth and interrogate it 🔍

🎀 `papplJobGetCopies`

Get the number of copies in the job.

int  papplJobGetCopies (
    pappl_job_t *job
);

This function returns the number of copies to produce of the job's document data. yes, that many. all of them. 🖨️

🎀 `papplJobGetCopiesCompleted`

Get the number of completed copies.

int  papplJobGetCopiesCompleted (
    pappl_job_t *job
);

This function returns the number of copies that have been completed. progress check, we love to see it 📈✨

🎀 `papplJobGetData`

Get per-job driver data.

void * papplJobGetData (
    pappl_job_t *job
);

This function returns the driver data associated with the job. It is normally only called from drivers to maintain state for the processing of the job, for example to store bitmap compression information. driver-only zone, iykyk 🤫

🎀 `papplJobGetFilename`

Get the job's filename.

const char * papplJobGetFilename (
    pappl_job_t *job
);

This function returns the filename for the job's document data. the document's whole government name 🫶

🎀 `papplJobGetFormat`

Get the MIME media type for the job's file.

const char * papplJobGetFormat (
    pappl_job_t *job
);

This function returns the MIME media type for the job's document data. it's giving application/pdf energy but like, whatever it actually is 🌈

🎀 `papplJobGetID`

Get the job ID value.

int  papplJobGetID (
    pappl_job_t *job
);

This function returns the job's unique integer identifier. every job has a number and it is theirs, nobody else's, main character energy 👑

🎀 `papplJobGetImpressions`

Get the number of impressions (sides) in the job.

int  papplJobGetImpressions (
    pappl_job_t *job
);

This function returns the number of impressions in the job's document data. An impression is one side of an output page. one side of one page = one impression, that's the whole definition, memorize it bestie 💅

🎀 `papplJobGetImpressionsCompleted`

Get the number of completed impressions (sides) in the job.

int  papplJobGetImpressionsCompleted (
    pappl_job_t *job
);

This function returns the number of impressions that have been printed. An impression is one side of an output page. same definition, still one side of one page 🦋

🎀 `papplJobGetMessage`

Get the current job message string, if any.

const char * papplJobGetMessage (
    pappl_job_t *job
);

This function returns the current job message string, if any. if any — sometimes there's no message and that's fine, don't force it 🎀

🎀 `papplJobGetName`

Get the job name/title.

const char * papplJobGetName (
    pappl_job_t *job
);

This function returns the name or title of the job. whatever the job is calling itself today ✨

🎀 `papplJobGetPrinter`

Get the printer for the job.

pappl_printer_t * papplJobGetPrinter (
    pappl_job_t *job
);

This function returns the printer containing the job. finding the job's home printer, we love a reunion 🫶

🎀 `papplJobGetReasons`

Get the current job state reasons.

pappl_jreason_t  papplJobGetReasons (
    pappl_job_t *job
);

This function returns the current job state reasons bitfield. it's a bitfield, so go read it with the pappl_jreason_e values up top 🔥

🎀 `papplJobGetState`

Get the current job state.

ipp_jstate_t  papplJobGetState (
    pappl_job_t *job
);

This function returns the current job processing state, which is represented as an enumeration:

IPP_JSTATE_ABORTED: Job has been aborted by the system due to an error. 💀

…and that's where part 1 stops, bestie — the enumeration list is still going, so stay tuned for the rest 🦋💖

IPP_JSTATE_CANCELED — bestie a user canceled it 💀 job's over, no more printing.
IPP_JSTATE_COMPLETED — the job finished printing, ate and left no crumbs ✨
IPP_JSTATE_HELD — the job is being held for some reason, usually because the document data is still being received 👀 like it's waiting at the door fr.
IPP_JSTATE_PENDING — queued up and waiting to be printed. main character in line, just vibing 🎀
IPP_JSTATE_PROCESSING — it's printing right now, actively slaying 🔥
IPP_JSTATE_STOPPED — paused, typically when the printer isn't ready 😭 it's giving "give me a sec".

papplJobGetTimeCompleted

Get the job completion time, if any ⏰

time_t papplJobGetTimeCompleted (
    pappl_job_t *job
);

This one hands you the date and time when the job hit the completed, canceled, or aborted states. If the job hasn't reached any of those yet? You get 0 back. no cap. 🫶

papplJobGetTimeCreated

Get the job creation time 🐣

time_t papplJobGetTimeCreated (
    pappl_job_t *job
);

Returns the date and time when the job was created — its literal birthday, iconic. 🎂

papplJobGetTimeProcessed

Get the job processing time 🖨️

time_t papplJobGetTimeProcessed (
    pappl_job_t *job
);

Returns the date and time when the job started processing (printing). The moment it stopped being a lurker and became the main event. ✨

papplJobGetUsername

Get the name of the user that submitted the job 🙋‍♀️

const char * papplJobGetUsername (
    pappl_job_t *job
);

Returns the name of the user that submitted the job. credit where credit is due bestie. 💅

papplJobHold

Hold a job for printing ✋

bool papplJobHold (
    pappl_job_t *job,
    const char *username,
    const char *until,
    time_t until_time
);

This function holds a pending job for printing at a later time. it's not cancelled, it's just taking a lil nap 😴

papplJobIsCanceled

Return whether the job is canceled 🚫

bool papplJobIsCanceled (
    pappl_job_t *job
);

Returns true if the job has been canceled or aborted. fr fr, it's done-done.

papplJobOpenFile

Create or open a file for the document in a job 📂

int papplJobOpenFile (
    pappl_job_t *job,
    char *fname,
    size_t fnamesize,
    const char *directory,
    const char *ext,
    const char *mode
);

This function creates or opens a file for a job. The fname and fnamesize arguments specify the location and size of a buffer to store the job filename, which incorporates the directory, printer ID, job ID, job name (title), and ext values. The job name gets "sanitized" so it only contains alphanumeric characters — no sketchy characters sneaking in 🧼

The mode argument is "r" to read an existing job file or "w" to write a new job file. New files are created with restricted permissions for security purposes 🔒

ngl the restricted permissions thing is not a vibe killer, it's a glow-up for your security. don't fight it.

papplJobRelease

Release a job for printing 🕊️

bool papplJobRelease (
    pappl_job_t *job,
    const char *username
);

This function releases a held job for printing. un-napping it, letting it cook 🔥

papplJobResume

Resume processing of a job ▶️

void papplJobResume (
    pappl_job_t *job,
    pappl_jreason_t remove
);

papplJobRetain

Retain a completed job until the specified time 🗓️

bool papplJobRetain (
    pappl_job_t *job,
    const char *username,
    const char *until,
    int until_interval,
    time_t until_time
);

papplJobSetCopiesCompleted

Add completed copies to the job 📄

void papplJobSetCopiesCompleted (
    pappl_job_t *job,
    int add
);

This function updates the number of completed impressions in a job. An impression is one side of an output page — so yes, double-sided pages count as two, bestie. math is math. 🧮

papplJobSetData

Set the per-job driver data pointer 🔌

void papplJobSetData (
    pappl_job_t *job,
    void *data
);

This function sets the driver data for the specified job. It's normally only called from drivers to maintain state for the processing of the job — for example, to store bitmap compression information. it's giving backstage pass, drivers only 🎟️

papplJobSetImpressions

Set the number of impressions (sides) in a job 📑

void papplJobSetImpressions (
    pappl_job_t *job,
    int impressions
);

This function sets the number of impressions in a job. An impression is one side of an output page. same deal as before — sides, not sheets 💅

papplJobSetImpressionsCompleted

Add completed impressions (sides) to the job ✅

void papplJobSetImpressionsCompleted (
    pappl_job_t *job,
    int add
);

This function updates the number of completed impressions in a job. An impression is one side of an output page. we love a consistent definition 🫶

papplJobSetMessage

Set the job message string 💬

void papplJobSetMessage (
    pappl_job_t *job,
    const char *message,
    ...
);

This function sets the job message string using a printf-style format string. yes, it's a variadic function, she's flexible like that 😌

Note: The maximum length of the job message string is 1023 bytes. so don't write a whole novel in there, bestie, it will get cut off ✂️

papplJobSetReasons

Set the job state reasons bit values 🧩

void papplJobSetReasons (
    pappl_job_t *job,
    pappl_jreason_t add,
    pappl_jreason_t remove
);

This function updates the job state reasons bitfield. The remove bits are cleared first, then the add bits are set. order matters, no skipping steps 🎯

papplJobSuspend

Temporarily stop processing of a job ⏸️

void papplJobSuspend (
    pappl_job_t *job,
    pappl_jreason_t add
);

papplPrinterFindJob

Find a job 🔍

pappl_job_t * papplPrinterFindJob (
    pappl_printer_t *printer,
    int job_id
);

This function finds a job submitted to a printer using its integer ID value. integer ID, not the name — don't get it twisted 💅

papplSystemCleanJobs

Clean out old (completed) jobs 🧹

void papplSystemCleanJobs (
    pappl_system_t *system
);

This function deletes all old (completed) jobs above the limit set by the papplPrinterSetMaxCompletedJobs function. The level may temporarily exceed this limit if the jobs were completed within the last 60 seconds. it's a grace period, be nice 🌸

Note: This function is normally called automatically from the papplSystemRun function. so you usually don't have to lift a finger, she does it herself 👑

🦋 TYPES 🦋

pappl_jreason_t

Bitfield for IPP "job-state-reasons" values 🧠

typedef unsigned int pappl_jreason_t;

💖 SEE ALSO 💖

like go read the whole family, they're all iconic 🫶

👑 COPYRIGHT 👑

PAPPL is licensed under the Apache License Version 2.0 with an (optional) exception to allow linking against GPL2/LGPL2 software (like older versions of CUPS), so it can be used freely in any project you'd like. See the files "LICENSE" and "NOTICE" in the source distribution for more information.

okay bestie that's the whole thing, you made it to the end, so proud of you 🥹 this was pappl job functions from pappl-job(3), dated 2026-08-11. now go forth and print things, mwah 💋✨

📦 where this page comes from

arch rolling: pappl 1.4.12-1 · Apache-2.0 WITH LLVM-exception
fedora 43: pappl-devel 1.4.12-1.fc43 · Apache-2.0 WITH LLVM-exception
fedora 43: pappl-devel 1.4.12-1.fc43 · Apache-2.0 WITH LLVM-exception
fedora 44: pappl-devel 1.4.12-1.fc44 · Apache-2.0 WITH LLVM-exception
fedora 44: pappl-devel 1.4.12-1.fc44 · Apache-2.0 WITH LLVM-exception
nixpkgs unstable: pappl 1.4.12
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-19: a language model's rewrite of the original, under its terms