|
An option summary appears below. Please see the documentation for details. If @filename appears anywhere in the command-line, each line of filename will be interpreted as an argument. No interpolation is done. Line terminators are stripped. @- can be specified to read from standard input. The output file can be - to indicate writing to standard output, or it can be --replace-input to cause qpdf to replace the input file with the output. Note that when contradictory options are provided, whichever options are provided last take precedence. Basic Options ------------- --version show version of qpdf --help show command-line argument help --show-crypto show supported crypto providers; default is first --completion-bash output a bash complete command you can eval --completion-zsh output a zsh complete command you can eval --password=password specify a password for accessing encrypted files --is-encrypted silently exit 0 if the file is encrypted or 2 if not; useful for shell scripts --requires-password silently exit 0 if a password (other than as supplied) is required, 2 if the file is not encrypted, or 3 if the file is encrypted but requires no password or the supplied password is correct; useful for shell scripts --verbose provide additional informational output --progress give progress indicators while writing output --no-warn suppress warnings --warning-exit-0 exit with code 0 instead of 3 if there are warnings --linearize generated a linearized (web optimized) file --replace-input use in place of specifying an output file; qpdf will replace the input file with the output --copy-encryption=file copy encryption parameters from specified file --encryption-file-password=password password used to open the file from which encryption parameters are being copied --encrypt options -- generate an encrypted file --decrypt remove any encryption on the file --password-is-hex-key treat primary password option as a hex-encoded key --suppress-password-recovery do not attempt recovering from password string encoding errors --pages options -- select specific pages from one or more files --collate causes files specified in --pages to be collated rather than concatenated --rotate=[+|-]angle[:page-range] rotate each specified page 90, 180, or 270 degrees; rotate all pages if no page range is given --split-pages=[n] write each output page to a separate file --overlay options -- overlay pages from another file --underlay options -- underlay pages from another file Note that you can use the @filename or @- syntax for any argument at any point in the command. This provides a good way to specify a password without having to explicitly put it on the command line. If none of --copy-encryption, --encrypt or --decrypt are given, qpdf will preserve any encryption data associated with a file. Note that when copying encryption parameters from another file, all parameters will be copied, including both user and owner passwords, even if the user password is used to open the other file. This works even if the owner password is not known. The --password-is-hex-key option overrides the normal computation of encryption keys. It only applies to the password used to open the main file. This option is not ordinarily useful but can be helpful for forensic or investigatory purposes. See manual for further discussion. The --rotate flag can be used to specify pages to rotate pages either 90, 180, or 270 degrees. The page range is specified in the same format as with the --pages option, described below. Repeat the option to rotate multiple groups of pages. If the angle is preceded by + or -, it is added to or subtracted from the original rotation. Otherwise, the rotation angle is set explicitly to the given value. You almost always want to use + or - unless you are certain about the internals of the PDF you are working with. If --split-pages is specified, each page is written to a separate output file. File names are generated as follows: * If the string %d appears in the output file name, it is replaced with a zero-padded page range starting from 1 * Otherwise, if the output file name ends in .pdf (case insensitive), a zero-padded page range, preceded by a dash, is inserted before the file extension * Otherwise, the file name is appended with a zero-padded page range preceded by a dash. Page ranges are single page numbers for single-page groups or first-last for multipage groups. Encryption Options ------------------ --encrypt user-password owner-password key-length flags -- Note that -- terminates parsing of encryption flags. Either or both of the user password and the owner password may be empty strings. key-length may be 40, 128, or 256 Additional flags are dependent upon key length. If 40: --print=[yn] allow printing --modify=[yn] allow document modification --extract=[yn] allow text/graphic extraction --annotate=[yn] allow comments and form fill-in and signing If 128: --accessibility=[yn] allow accessibility to visually impaired --extract=[yn] allow other text/graphic extraction --print=print-opt control printing access --assemble=[yn] allow document assembly --annotate=[yn] allow commenting/filling form fields --form=[yn] allow filling form fields --modify-other=[yn] allow other modifications --modify=modify-opt control modify access (old way) --cleartext-metadata prevents encryption of metadata --use-aes=[yn] indicates whether to use AES encryption --force-V4 forces use of V=4 encryption handler If 256, options are the same as 128 with these exceptions: --force-V4 this option is not available with 256-bit keys --use-aes this option is always on with 256-bit keys --force-R5 forces use of deprecated R=5 encryption print-opt may be: full allow full printing low allow only low-resolution printing none disallow printing modify-opt may be: all allow full document modification annotate allow comment authoring and form operations form allow form field fill-in and signing assembly allow document assembly only none allow no modifications The default for each permission option is to be fully permissive. Please refer to the manual for more details on the modify options. Specifying cleartext-metadata forces the PDF version to at least 1.5. Specifying use of AES forces the PDF version to at least 1.6. These options are both off by default. The --force-V4 flag forces the V=4 encryption handler introduced in PDF 1.5 to be used even if not otherwise needed. This option is primarily useful for testing qpdf and has no other practical use. Password Modes ---------------------- The --password-mode controls how qpdf interprets passwords supplied cases, but you can fine-tune with this option. bytes: use the password literally as supplied hex-bytes: interpret the password as a hex-encoded byte string unicode: interpret the password as a UTF-8 encoded string auto: attempt to infer the encoding and adjust as needed This is a complex topic. See the manual for a complete discussion. Page Selection Options ---------------------- These options allow pages to be selected from one or more PDF files. Whatever file is given as the primary input file is used as the starting point, but its pages are replaced with pages as specified. --keep-files-open=[yn] --keep-files-open-threshold=count --pages file [ --password=password ] [ page-range ] ... -- For each file that pages should be taken from, specify the file, a password needed to open the file (if any), and a page range. The password needs to be given only once per file. If any of the input files are the same as the primary input file or the file used to copy encryption parameters (if specified), you do not need to repeat the password here. The same file can be repeated multiple times. The filename "." may be used to refer to the current input file. All non-page data (info, outlines, page numbers, etc. are taken from the primary input file. To discard this, use --empty as the primary input. By default, when more than 200 distinct files are specified, qpdf will close each file when not being referenced. With 200 files or fewer, all files will be kept open at the same time. This behavior can be overridden by specifying --keep-files-open=[yn]. Closing and opening files can have very high overhead on certain file systems, especially networked file systems. The threshold of 200 can be modified with --keep-files-open-threshold The page range is a set of numbers separated by commas, ranges of numbers separated dashes, or combinations of those. The character "z" represents the last page. A number preceded by an "r" indicates to count from the end, so "r3-r1" would be the last three pages of the document. Pages can appear in any order. Ranges can appear with a high number followed by a low number, which causes the pages to appear in reverse. Numbers may be repeated. A page range may be appended with :odd to indicate odd pages in the selected range or :even to indicate even pages. If the page range is omitted, the range of 1-z is assumed. qpdf decides that the page range is omitted if the range argument is either -- or a valid file name and not a valid range. The usual behavior of --pages is to add all pages from the first file, then all pages from the second file, and so on. If the --collate option is specified, then pages are collated instead. In other words, qpdf takes the first page from the first file, the first page from the second file, and so on until it runs out of files; then it takes the second page from each file, etc. When a file runs out of pages, it is skipped until all specified pages are taken from all files. See the manual for examples and a discussion of additional subtleties. Overlay and Underlay Options ------------------------------- These options allow pages from another file to be overlaid or underlaid on the primary output. Overlaid pages are drawn on top of the destination page and may obscure the page. Underlaid pages are drawn below the destination page. {--overlay | --underlay } file [ --password=password ] [ --to=page-range ] [ --from=[page-range] ] [ --repeat=page-range ] -- For overlay and underlay, a file and optional password are specified, along with a series of optional page ranges. The default behavior is that each page of the overlay or underlay file is imposed on the corresponding page of the primary output until it runs out of pages, and any extra pages are ignored. The page range options all take page ranges in the same form as the --pages option. They have the following meanings: --to: the pages in the primary output to which overlay/underlay is applied --from: the pages from the overlay/underlay file that are used --repeat: pages from the overlay/underlay that are repeated after any "from" pages have been exhausted Advanced Parsing Options ------------------------------- These options control aspects of how qpdf reads PDF files. Mostly these are of use to people who are working with damaged files. There is little reason to use these options unless you are trying to solve specific problems. --suppress-recovery prevents qpdf from attempting to recover damaged files --ignore-xref-streams tells qpdf to ignore any cross-reference streams Advanced Transformation Options ------------------------------- These transformation options control fine points of how qpdf creates the output file. Mostly these are of use only to people who are very familiar with the PDF file format or who are PDF developers. --stream-data=option controls transformation of stream data (below) --compress-streams=[yn] controls whether to compress streams on output --decode-level=option controls how to filter streams from the input --recompress-flate recompress streams already compressed with Flate --compression-level=n set zlib compression level; most effective with --recompress-flate --object-streams=generate --normalize-content=[yn] enables or disables normalization of content streams --object-streams=mode controls handing of object streams --preserve-unreferenced preserve unreferenced objects --remove-unreferenced-resources={auto,yes,no} whether to remove unreferenced page resources --preserve-unreferenced-resources synonym for --remove-unreferenced-resources=no --newline-before-endstream always put a newline before endstream --flatten-annotations=option incorporate rendering of annotations into page contents including those for interactive form fields; may also want --generate-appearances --generate-appearances generate appearance streams for form fields --optimize-images compress images with DCT (JPEG) when advantageous --oi-min-width=w do not optimize images whose width is below w; default is 128. Use 0 to mean no minimum --oi-min-height=h do not optimize images whose height is below h default is 128. Use 0 to mean no minimum --oi-min-area=a do not optimize images whose pixel count is below a default is 16,384. Use 0 to mean no minimum --externalize-inline-images convert inline images to regular images; by default, images of at least 1,024 bytes are externalized --ii-min-bytes=bytes specify minimum size of inline images to be converted to regular images --keep-inline-images exclude inline images from image optimization --remove-page-labels remove any page labels present in the output file --qdf turns on "QDF mode" (below) --linearize-pass1=file write intermediate pass of linearized file for debugging --min-version=version sets the minimum PDF version of the output file --force-version=version forces this to be the PDF version of the output file Options for --flatten-annotations are all, print, or screen. If the option is print, only annotations marked as print are included. If the option is screen, options marked as "no view" are excluded. Otherwise, annotations are flattened regardless of the presence of print or NoView flags. It is common for PDF files to have a flag set that appearance streams need to be regenerated. This happens when someone changes a form value with software that does not know how to render the new value. qpdf will not flatten form fields in files like this. If you get this warning, you have two choices: regenerate appearances, or use some other tool to generate the appearances. qpdf does a pretty good job with most forms when only ASCII and "Windows ANSI" characters are used in form field values, but if your form fields contain other characters, rich text, or are other than left justified, you will get better results first saving with other software. Version numbers may be expressed as major.minor.extension-level, so 1.7.3 means PDF version 1.7 at extension level 3. Values for stream data options: compress recompress stream data when possible (default) preserve leave all stream data as is uncompress uncompress stream data when possible Values for object stream mode: preserve preserve original object streams (default) generate use object streams wherever possible When --compress-streams=n is specified, this overrides the default behavior of qpdf, which is to attempt compress uncompressed streams. Setting stream data mode to uncompress or preserve has the same effect. The --decode-level parameter may be set to one of the following values: none do not decode streams generalized decode streams compressed with generalized filters including LZW, Flate, and the ASCII encoding filters. specialized additionally decode streams with non-lossy specialized filters including RunLength all additionally decode streams with lossy filters including DCT (JPEG) In qdf mode, by default, content normalization is turned on, and the stream data mode is set to uncompress. QDF mode does not support linearized files. The --linearize flag disables qdf mode. Setting the minimum PDF version of the output file may raise the version but will never lower it. Forcing the PDF version of the output file may contents. You should only do this if you have no other possible way to features not supported later versions. Testing, Inspection, and Debugging Options ------------------------------------------ These options can be useful for digging into PDF files or for use in automated test suites for software that uses the qpdf library. --deterministic-id generate deterministic /ID --static-id generate static /ID: FOR TESTING ONLY! --static-aes-iv use a static initialization vector for AES-CBC This is option is not secure! FOR TESTING ONLY! --no-original-object-ids suppress original object ID comments in qdf mode --show-encryption quickly show encryption parameters --show-encryption-key when showing encryption, reveal the actual key --check-linearization check file integrity and linearization status --show-linearization check and show all linearization data --show-xref show the contents of the cross-reference table --show-object=trailer|obj[,gen] show the contents of the given object --raw-stream-data show raw stream data instead of object contents --filtered-stream-data show filtered stream data instead of object contents --show-npages print the number of pages in the file --show-pages shows the object/generation number for each page --with-images also shows the object IDs for images on each page --check check file structure + encryption, linearization --json generate a json representation of the file --json-help describe the format of the json representation --json-key=key repeatable; prune json structure to include only specified keys. If absent, all keys are shown --json-object=trailer|[obj,gen] repeatable; include only specified objects in the "objects" section of the json. If absent, all objects are shown The json representation generated by qpdf is designed to facilitate processing of qpdf from other programming languages that have a hard time calling C++ APIs. Run qpdf --json-help for details on the format. The manual has more in-depth information about the json representation and certain compatibility guarantees that qpdf provides. The --raw-stream-data and --filtered-stream-data options are ignored unless --show-object is given. Either of these options will cause the stream data to be written to standard output. If --filtered-stream-data is given and --normalize-content=y is also given, qpdf will attempt to normalize the stream data as if it is a page content stream. This attempt will be made even if it is not a page content stream, in which case it will produce unusable results. Ordinarily, qpdf exits with a status of 0 on success or a status of 2 if any errors occurred. If there were warnings but not errors, qpdf exits with a status of 3. If warnings would have been issued but --no-warn was given, an exit status of 3 is still used. If you want qpdf to exit with status 0 when there are warnings, use the --warning-exit-0 flag. When --no-warn and --warning-exit-0 are used together, the effect is for qpdf to completely ignore warnings. qpdf does not use exit status 1, |
|
|
