1 Basic Usage

The Coherent PDF tools provide a wide range of facilities for modifying PDF files created by other means. There is a single command-line program cpdf (cpdf.exe under Microsoft Windows). The rest of this manual describes the options that may be given to this program.

1.1 Documentation

The operation -help / --help prints each operation and option together with a short description. The operation -version prints the cpdf version string.

1.2 Input and Output Files

Files on the command line are distinguished from other input by their containing a period. If an input file does not contain a period, it should be preceded by -i. For example:

To restrict cpdf to files ending in .pdf (in upper or lower or mixed case) add the option -idir-only-pdfs before -idir:

1.3 Input Ranges

An input range may be specified after each input file. This is treated differently by each operation. For instance

1.4 Working with Encrypted Documents

In order to perform many operations, encrypted input PDF files must be decrypted. Some require the owner password, some either the user or owner passwords. Either password is supplied by writing user=<password> or owner=<password> following each input file requiring it (before or after any range). The document will not be re-encrypted upon writing. For example:

To re-encrypt the file with its existing encryption upon writing, which is required if only the user password was supplied, but allowed in any case, add the -recrypt option:

The password required (owner or user) depends upon the operation being performed. Separate facilities are provided to decrypt and encrypt files (See Section 4).

When appropriate passwords are not available, the option -decrypt-force may be added to the command line to process the file regardless.

1.5 Standard Input and Standard Output

Thus far, we have assumed that the input PDF will be read from a file on disk, and the output written similarly. Often it’s useful to be able to read input from stdin (Standard Input) or write output to stdout (Standard Output) instead. The typical use is to join several programs together into a pipe, passing data from one to the next without the use of intermediate files. Use -stdin to read from standard input, and -stdout to write to standard input, either to pipe data between multiple programs, or multiple invocations of the same program. For example, this sequence of commands (all typed on one line)

extracts the last five pages of in.pdf in the correct order, writing them to out.pdf. It does this by reversing the input, taking the first five pages and then reversing the result.

To supply passwords for a file from -stdin, use -stdin-owner <password> and/or -stdin-user <password>.

Using -stdout on the final command in the pipeline to output the PDF to screen is not recommended, since PDF files often contain compressed sections which are not screen-readable.

Several cpdf operations write to standard output by default (for example, listing fonts). A useful feature of the command line (not specific to cpdf) is the ability to redirect this output to a file. This is achieved with the > operator:

1.6 Doing Several Things at Once with AND

The keyword AND can be used to string together several commands in one. The advantage compared with using pipes is that the file need not be repeatedly parsed and written out, saving time.

To use AND, simply leave off the output specifier (e.g -o) of one command, and the input specifier (e.g filename) of the next. For instance:

1.7 Units

When measurements are given to cpdf, they are in points (1 point = 1/72 inch). They may optionally be followed by some letters to change the measurement. The following are supported:

For example, one may write 14mm or 21.6in. In addition, the following letters stand, in some operations (-scale-page, -scale-to-fit, -scale-contents, -shift, -mediabox,
-crop) for various page dimensions:

For example, we may write PMINXPMINY to stand for the coordinate of the lower left corner of the page.

Simple arithmetic may be performed using the words add, sub, mul and div to stand for addition, subtraction, multiplication and division. For example, one may write 14in sub 30pt or PMINX mul 2

1.8 Setting the Producer and Creator

The -producer and -creator options may be added to any cpdf command line to set the producer and/or creator of the PDF file. If the file was converted from another format, the creator is the program producing the original, the producer the program converting it to PDF.

1.9 PDF Version Numbers

When an operation which uses a part of the PDF standard which was introduced in a later version than that of the input file, the PDF version in the output file is set to the later version (most PDF viewers will try to load any PDF file, even if it is marked with a later version number). However, this automatic version changing may be suppressed with the -keep-version option. If you wish to manually alter the PDF version of a file, use the -set-version operation described in Section 18.5.

1.10 File IDs

PDF files contain an ID (consisting of two parts), used by some workflow systems to uniquely identify a file. To change the ID, behavior, use the -change-id operation. This will create a new ID for the output file.

1.11 Linearization

Linearized PDF is a version of the PDF format in which the data is held in a special manner to allow content to be fetched only when needed. This means viewing a multipage PDF over a slow connection is more responsive. By default, cpdf does not linearize output files. To make it do so, add the -l option to the command line, in addition to any other command being used. For example:

This requires the existence of the external program cpdflin which is provided with commercial versions of cpdf. This must be installed as described in the installation documentation provided with your copy of cpdf. If you are unable to install cpdflin, you must use -cpdflin to let cpdf know where to find it:

In extremis, you may place cpdflin and its resources in the current working directory, though this is not recommended. For further help, refer to the installation instructions for your copy of cpdf.

To keep the existing linearization status of a file (produce linearized output if the input is linearized and the reverse), use -keep-l instead of -l.

1.12 Object Streams

PDF 1.5 introduced a new mechanism for storing objects to save space: object streams. by default, cpdf will preserve object streams in input files, creating no more. To prevent the retention of existing object streams, use -no-preserve-objstm:

To create new object streams if none exist, or augment the existing ones, use -create-objstm:

Files written with object streams will be set to PDF 1.5 or higher, unless -keep-version is used (see above).

1.13 Malformed Files

There are many malformed PDF files in existence, including many produced by otherwise-reputable applications. cpdf attempts to correct these problems silently.

Grossly malformed files will be reconstructed. The reconstruction progress is shown on stderr (Standard Error):

If cpdf cannot reconstruct a malformed file, it is able to use the gs program to try to reconstruct the PDF file, if you have it installed. For example, if gs is installed and in your path, we might try:

If the malformity lies inside an individual page of the PDF, rather than in its gross structure, cpdf may appear to succeed in reconstruction, only to fail when processing a page (e.g when adding text). To force the use of gs to pre-process such files so cpdf cannot fail on them, use -gs-malformed-force:

The command line for -gs-malformed-force must be of precisely this form. Sometimes, on the other hand, we might wish cpdf to fail immediately on any malformed file, rather than try its own reconstruction process. The option -error-on-malformed achieves this.

Sometimes (old, pre-ISO standardisation) files can be technically well-formed but use inefficient PDF constructs. If you are sure the input files you are using are well formed, the -fast option may be added to the command line (or, if using AND, to each section of the command line). This will use certain shortcuts which speed up processing, but would fail on badly-produced files. The -fast option may be used with:

1.14 Error Handling

When cpdf encounters an error, it exits with code 2. An error message is displayed on stderr (Standard Error). In normal usage, this means it’s displayed on the screen. When a bad or inappropriate password is given, the exit code is 1.

1.15 Control Files

Some operating systems have a limit on the length of a command line. To circumvent this, or simply for reasons of flexibility, a control file may be specified from which arguments are drawn. This file does not support the full syntax of the command line. Commands are separated by whitespace, quotation marks may be used if an argument contains a space, and the sequence ' " may be used to introduce a genuine quotation mark in such an argument.

Several -control arguments may be specified, and may be mixed in with conventional command-line arguments. The commands in each control file are considered in the order in which they are given, after all conventional arguments have been processed. It is recommended to use -args in all new applications. However, -control will be supported for legacy applications.

To avoid interference between -control and AND, a new mechanism has been added. Using -args in place of -control will perform direct textual substitution of the file into the command line, prior to any other processing.

1.16 String Arguments

Command lines are handled differently on each operating system. Some characters are reserved with special meanings, even when they occur inside quoted string arguments. To avoid this problem, cpdf performs processing on string arguments as they are read.

A backslash is used to indicate that a character which would otherwise be treated specially by the command line interpreter is to be treated literally. For example, Unix-like systems attribute a special meaning to the exclamation mark, so the command line

1.17 Text Encodings

Some cpdf commands write text to standard output, or read text from the command line or configuration files. These are:

Add -utf8 to use Unicode UTF8, -stripped to convert to 7 bit ASCII by dropping any high characters, or -raw to perform no processing. The default unless specified in the documentation for an individual operation is -stripped.

1.18 Font Embedding

Use the -no-embed-font to avoid embedding the Standard 14 Font metrics when adding text with -add-text.

JavaScript Interface

cpdf.js: JavaScript interface to the cpdf PDF tools
===================================================

// CHAPTER -1: Introduction

/**
Use
---

coherentpdf.js can be used from both node and the browser.

The file `cpdflibtest.js` uses every function in coherentpdf.js. Call `./run`
to run it in node.

For development server-side with node: `coherentpdf.js` (minified version
`coherentpdf.min.js`). Load with `const coherentpdf = require(coherentpdf)`
if installed in npm, or `const coherentpdf = require(./coherentpdf.js)` to
load from current directory.

For development client-side with the browser : `coherentpdf.browser.js`
(minified version for deployment : `coherentpdf.browser.min.js`). Load with
`<script src="coherentpdf.browser.js"></script>` or similar.

Data types
----------

Arguments are numbers, strings, or arrays (of type UInt8Array for data). Page
ranges are represented by arrays of numbers.

Memory Management
-----------------

A PDF p must be explicitly deallocated with deletePdf(p).

Errors
------

Any function may raise an exception, containing a string describing the problem.

Concurrency
-----------

coherentpdf.js is synchronous and non-re-entrant. In the browser, best used in a worker.
**/

// CHAPTER 0. Preliminaries

/** Returns a string giving the version number of the CPDF library.
@returns {string} version */
function version() {}

/** Some operations have a fast mode. The default is slow mode, which works
even on old-fashioned files. For more details, see section 1.13 of the CPDF
manual. This function sets the mode to fast globally. */
function setFast() {}

/** Some operations have a fast mode. The default is slow mode, which works
even on old-fashioned files. For more details, see section 1.13 of the CPDF
manual. This function sets the mode to slow globally. */
function setSlow() {}

/** Delete a PDF so the memory representing it may be recovered.
@arg {pdf} pdf PDF document to delete */
function deletePdf(pdf) {}

/* A debug function which prints some information about resource usage. This
can be used to detect if PDFs or ranges are being deallocated properly.
Contrary to its name, it may be run at any time. */
function onexit() {}

// CHAPTER 1. Basics

/** Loads a PDF file from a given file. Supply a user password (possibly blank)
in case the file is encrypted. It wont be decrypted, but sometimes the
password is needed just to load the file.
@arg {string} filename File name
@arg {string} userpw User password, or blank if none */
function fromFile(filename, userpw) {}

/** Loads a PDF from a file, doing only minimal parsing. The objects will be
read and parsed when they are actually needed. Use this when the whole file
wont be required. Also supply a user password (possibly blank) in case the
file is encrypted. It wont be decrypted, but sometimes the password is needed
just to load the file.
@arg {string} filename File name
@arg {string} userpw User password, or blank if none */
function fromFileLazy(filename, userpw) {}

/** Loads a file from memory given any user password.
@arg {Uint8Array} data PDF document as an array of bytes
@arg {string} userpw User password, or blank if none */
function fromMemory(data, userpw) {}

/** Loads a file from memory, given a pointer and a length, and the user
password, but lazily like fromFileLazy.
@arg {Uint8Array} data PDF document as an array of bytes
@arg {string} userpw User password, or blank if none */
function fromMemoryLazy(data, userpw) {}

/** To enumerate the list of currently allocated PDFs, call startEnumeratePDFs
which gives the number, n, of PDFs allocated, then enumeratePDFsInfo and
enumeratePDFsKey with index numbers from 0...(n - 1). Call endEnumeratePDFs to
clean up.
@return {number} number of PDFs */
function startEnumeratePDFs() {}

/** To enumerate the list of currently allocated PDFs, call startEnumeratePDFs
which gives the number, n, of PDFs allocated, then enumeratePDFsInfo and
enumeratePDFsKey with index numbers from 0...(n - 1). Call endEnumeratePDFs to
clean up.
@arg {n} index number
@return {number} PDF key */
function enumeratePDFsKey(n) {}

/** To enumerate the list of currently allocated PDFs, call startEnumeratePDFs
which gives the number, n, of PDFs allocated, then enumeratePDFsInfo and
enumeratePDFsKey with index numbers from 0...(n - 1). Call endEnumeratePDFs to
clean up.
@arg {n} index number
@return {number} PDF information */
function enumeratePDFsInfo(n) {}

/** To enumerate the list of currently allocated PDFs, call startEnumeratePDFs
which gives the number, n, of PDFs allocated, then enumeratePDFsInfo and
enumeratePDFsKey with index numbers from 0...(n - 1). Call endEnumeratePDFs to
clean up. */
function endEnumeratePDFs() {}

/** Converts a figure in centimetres to points (72 points to 1 inch)
@arg {number} i figure in centimetres
@return {number} figure in points */
function ptOfCm(i) {}

/** Converts a figure in millimetres to points (72 points to 1 inch)
@arg {number} i figure in millimetres
@return {number} figure in points */
function ptOfMm(i) {}

/** Converts a figure in inches to points (72 points to 1 inch)
@arg {number} i figure in inches
@return {number} figure in points */
function ptOfIn(i) {}

/** Converts a figure in points to centimetres (72 points to 1 inch)
@arg {number} i figure in points
@return {number} figure in centimetres */
function cmOfPt(i) {}

/** Converts a figure in points to millimetres (72 points to 1 inch)
@arg {number} i figure in points
@return {number} figure in millimetres */
function mmOfPt(i) {}

/** Converts a figure in points to inches (72 points to 1 inch)
@arg {number} i figure in points
@return {number} figure in inches */
function inOfPt(i) {}

/** Parses a page specification with reference to a given PDF (the PDF is
supplied so that page ranges which reference pages which do not exist are
rejected).
@arg {pdf} pdf PDF document
@arg {string} pagespec Page specification
@return {array} page range */
function parsePagespec(pdf, pagespec) {}

/** Validates a page specification so far as is possible in the absence of
the actual document. Result is true if valid.
@arg {string} pagespec Page specification
@return {boolean} validity or otherwise of page specification */
function validatePagespec(pagespec) {}

/** Builds a page specification from a page range. For example, the range
containing 1,2,3,6,7,8 in a document of 8 pages might yield "1-3,6-end"
@arg {pdf} pdf PDF document
@arg {array} r Page range
@return {string} Page specifcation */
function stringOfPagespec(pdf, r) {}

/** Creates a range with no pages in.
@return {array} Page range */
function blankRange() {}

/** Builds a range from one page to another inclusive. For example, range(3,7)
gives the range 3,4,5,6,7
@arg {number} f begining of page range
@arg {number} t end of page range
@return {array} page range */
function range(f, t) {}

/** The range containing all the pages in a given document.
@arg {pdf} pdf PDF document
@return {array} page range */
function all(pdf) {}

/** Makes a range which contains just the even pages of another range.
@arg {array} r_in page range
@return {array} page range */
function even(r_in) {}

/** Makes a range which contains just the odd pages of another range.
@arg {array} r_in page range
@return {array} page range */
function odd(r_in) {}

/** Makes the union of two ranges giving a range containing the pages in range
a and range b.
@arg {array} a page range
@arg {array} b page range
@return {array} page range */
function rangeUnion(a, b) {}

/** Makes the difference of two ranges, giving a range containing all the
pages in a except for those which are also in b.
@arg {array} a page range
@arg {array} b page range
@return {array} page range */
function difference(a, b) {}

/** Deduplicates a range, making a new one.
@arg {array} a page range
@return {array} page range */
function removeDuplicates(a) {}

/** Gives the number of pages in a range.
@arg {array} r page range
@return {number} length */
function rangeLength(r) {}

/** Gets the page number at position n in a range, where n runs from 0 to
rangeLength - 1.
@arg {array} r page range
@arg {number} n position
@return {number} page at given position */
function rangeGet(r, n) {}

/** Adds the page to a range, if it is not already there.
@arg {array} r page range
@arg {number} page page number */
function rangeAdd(r, page) {}

/** Returns true if the page is in the range, false otherwise.
@arg {array} r page range
@arg {number} page page number
@return {boolean} true if page in range, false otherwise */
function isInRange(r, page) {}

/** Returns the number of pages in a PDF.
@arg {pdf} pdf PDF document
@return {number} number of pages */
function pages(pdf) {}

/** Returns the number of pages in a given PDF, with given user password. It
tries to do this as fast as possible, without loading the whole file.
@arg {string} password user password
@arg {string} filename file name
@return {number} number of pages */
function pagesFast(password, filename) {}

/** Returns the number of pages in a given PDF, with given user password. It
tries to do this as fast as possible, without loading the whole file.
@arg {string} password user password
@arg {Uint8Array} data PDF file as a byte array
@return {number} number of pages */
function pagesFastMemory(password, data) {}

/** Writes the file to a given filename. If linearize is true, it will be
linearized if a linearizer is available. If make_id is true, it will be
given a new ID.
@arg {pdf} pdf PDF document
@arg {string} filename file name
@arg {boolean} linearize linearize if a linearizer is available
@arg {boolean} make_id make a new /ID */
function toFile(pdf, filename, linearize, make_id) {}

/** Writes the file to a given filename. If make_id is true, it will be given
a new ID. If preserve_objstm is true, existing object streams will be
preserved. If generate_objstm is true, object streams will be generated even if
not originally present. If compress_objstm is true, object streams will be
compressed (what we usually want). WARNING: the pdf argument will be invalid
after this call, and should be not be used again.
@arg {pdf} pdf PDF document
@arg {string} filename file name
@arg {boolean} linearize linearize if a linearizer is available
@arg {boolean} preserve_objstm preserve existing object streams
@arg {boolean} generate_objstm create new object streams
@arg {boolean} compress_objstm compress new object streams */
function toFileExt(pdf, filename, linearize, make_id, preserve_objstm, generate_objstm, compress_objstm) {}

/** Writes a PDF file and returns as an array of bytes.
@arg {pdf} pdf PDF document
@arg {boolean} linearize linearize if a linearizer is available
@arg {boolean} make_id make a new /ID
@result {Uint8Array} PDF document as an array of bytes */
function toMemory(pdf, linearize, make_id) {}

/** Writes the file to memory. If make_id is true, it will be given
a new ID. If preserve_objstm is true, existing object streams will be
preserved. If generate_objstm is true, object streams will be generated even if
not originally present. If compress_objstm is true, object streams will be
compressed (what we usually want). WARNING: the pdf argument will be invalid
after this call, and should be not be used again.
@arg {pdf} pdf PDF document
@arg {boolean} linearize linearize if a linearizer is available
@arg {boolean} preserve_objstm preserve existing object streams
@arg {boolean} generate_objstm create new object streams
@arg {boolean} compress_objstm compress new object streams
@result {Uint8Array} PDF file as a byte array */
function toMemoryExt(pdf, linearize, make_id, preserve_objstm, generate_objstm, compress_objstm) {}

/** Returns true if a document is encrypted, false otherwise.
@arg {pdf} pdf PDF document
@return {boolean} true if document encrypted, false otherwise */
function isEncrypted(pdf) {}

/** Attempts to decrypt a PDF using the given user password. An exception is
raised if the decryption fails.
@arg {pdf} pdf PDF document
@arg {string} userpw user password, or empty if none */
function decryptPdf(pdf, userpw) {}

/** Attempts to decrypt a PDF using the given owner password. Raises an
exception if the decryption fails.
@arg {pdf} pdf PDF document
@arg {string} ownerpw owner password, or empty if none */
function decryptPdfOwner(pdf, ownerpw) {}

/** Cannot edit the document */
var noEdit = 0;

/** Cannot print the document */
var noPrint = 1;

/** Cannot copy the document */
var noCopy = 2;

/** Cannot annotate the document */
var noAnnot = 3;

/** Cannot edit forms in the document */
var noForms = 4;

/** Cannot extract information */
var noExtract = 5;

/** Cannot assemble into a bigger document */
var noAssemble = 6;

/** Cannot print high quality */
var noHqPrint = 7;

/** 40 bit RC4 encryption */
var pdf40bit = 0;

/** 128 bit RC4 encryption */
var pdf128bit = 1;

/** 128 bit AES encryption, do not encrypt metadata */
var aes128bitfalse = 2;

/** 128 bit AES encryption, encrypt metadata */
var aes128bittrue = 3;

/** Deprecated. Do not use for new files */
var aes256bitfalse = 4;

/** Deprecated. Do not use for new files */
var aes256bittrue = 5;

/** 256 bit AES encryption, do not encrypt metadata */
var aes256bitisofalse = 6;

/** 256 bit AES encryption, encrypt metadata */
var aes256bitisotrue = 7;

/** Writes a file as encrypted.
@arg {pdf} pdf PDF document
@arg {"encryption method"} encryption_method encryption method
@arg {"permission array"} array of permissions
@arg {string} ownerpw owner password
@arg {string} userpw user password
@arg {boolean} linearize linearize if a linearizer is available
@arg {boolean} makeid make a new /ID
@arg {string} filename file name */
function toFileEncrypted(pdf, encryption_method, permissions, ownerpw, userpw, linearize, makeid, filename) {}

/** Writes to memory as encrypted.
@arg {pdf} pdf PDF document
@arg {"encryption method"} encryption_method encryption method
@arg {"permission array"} array of permissions
@arg {string} ownerpw owner password
@arg {string} userpw user password
@arg {boolean} linearize linearize if a linearizer is available
@arg {boolean} makeid make a new /ID
@return {Uint8Array} PDF file as a byte array */
function toMemoryEncrypted(pdf, encryption_method, permissions, ownerpw, userpw, linearize, makeid) {}

/** Writes a file as encrypted with extra parameters. WARNING: the pdf argument
will be invalid after this call, and should not be used again.
@arg {pdf} pdf PDF document
@arg {"encryption method"} encryption_method encryption method
@arg {"permission array"} array of permissions
@arg {string} ownerpw owner password
@arg {string} userpw user password
@arg {boolean} linearize linearize if a linearizer is available
@arg {boolean} makeid make a new /ID
@arg {boolean} preserve_objstm preserve existing object streams
@arg {boolean} generate_objstm generate new object streams
@arg {boolean} compress_objstm compress object streams
@arg {string} filename file name */
function toFileEncryptedExt(pdf, encryption_method, permissions, ownerpw, userpw, linearize, makeid, preserve_objstm, generate_objstm, compress_objstm, filename) {}

/** Writes a file as encrypted with extra parameters. WARNING: the pdf argument
will be invalid after this call, and should not be used again.
@arg {pdf} pdf PDF document
@arg {"encryption method"} encryption_method encryption method
@arg {"permission array"} array of permissions
@arg {string} ownerpw owner password
@arg {string} userpw user password
@arg {boolean} linearize linearize if a linearizer is available
@arg {boolean} makeid make a new /ID
@arg {boolean} preserve_objstm preserve existing object streams
@arg {boolean} generate_objstm generate new object streams
@arg {boolean} compress_objstm compress object streams
@return {Uint8Array} PDF file as a byte array */
function toMemoryEncryptedExt(pdf, encryption_method, permissions, ownerpw, userpw, linearize, makeid, preserve_objstm, generate_objstm, compress_objstm) {}

/** Returns true if the given permission (restriction) is present.
@arg {pdf} pdf PDF document
@arg {permission} permission permission
@return {boolean} true if permission present */
function hasPermission(pdf, permission) {}

/** Returns the encryption method currently in use on a document.
@arg {pdf} pdf PDF document
@return {"encryption method"} encryption method */
function encryptionKind(pdf) {}

Chapter 1Basic Usage