# CommandSection

title: DESCRIPTION
content:
pkeyutl is a versatile OpenSSL command-line utility designed for performing generic public key cryptographic operations. It supports a wide range of algorithms, including RSA, DSA, and EC (Elliptic Curve), allowing users to encrypt, decrypt, sign, and verify data. Unlike higher-level OpenSSL commands that might wrap these operations with X.509 certificates or specific file formats, pkeyutl works directly with raw public or private keys and data. It's commonly used for low-level cryptographic tasks, such as generating signatures, verifying them, performing raw RSA encryption/decryption (often used for data exchange or key encapsulation), and testing cryptographic primitives. The command takes input data, a private or public key, and performs the specified operation, outputting the result. While the prompt references 'pkeyutl.1s', this utility is widely available as part of the OpenSSL suite, typically documented as 'pkeyutl(1SSL)'.


title: CAVEATS
content:
pkeyutl works with raw data. For RSA encryption/decryption, it performs 'raw' RSA operations. Without proper padding schemes (like PKCS#1 v1.5 or OAEP) explicitly specified via -pkeyopt, RSA is insecure for direct data encryption. When using 'sign' or 'verify', the input data is typically the *hash* of the actual message, not the message itself. The hash algorithm used and padding options are critical for security and interoperability. It's a low-level utility; misuse can lead to cryptographic vulnerabilities, requiring a good understanding of the underlying algorithms and padding schemes.


title: COMMON USAGE: RSA ENCRYPTION/DECRYPTION WITH PADDING
content:
To encrypt data using RSA with OAEP padding (recommended for encryption):<br><code>openssl pkeyutl -encrypt -in <I>plaintext.bin</I> -out <I>ciphertext.bin</I> -pubin -inkey <I>public.pem</I> -pkeyopt <I>rsa_padding_mode:oaep</I></code><br><br>To decrypt data using RSA with OAEP padding:<br><code>openssl pkeyutl -decrypt -in <I>ciphertext.bin</I> -out <I>recovered_plaintext.bin</I> -inkey <I>private.pem</I> -pkeyopt <I>rsa_padding_mode:oaep</I></code>


title: SIGNING AND VERIFYING A HASH
content:
To sign a SHA256 hash of a file using an RSA private key with PSS padding:<br><code>openssl dgst -sha256 -binary <I>file.txt</I> > <I>file.hash</I></code><br><code>openssl pkeyutl -sign -in <I>file.hash</I> -out <I>signature.bin</I> -inkey <I>private.pem</I> -pkeyopt <I>rsa_padding_mode:pss</I> -pkeyopt <I>digest:sha256</I></code><br><br>To verify the signature using the public key:<br><code>openssl dgst -sha256 -binary <I>file.txt</I> > <I>file.hash</I></code><br><code>openssl pkeyutl -verify -in <I>file.hash</I> -sigfile <I>signature.bin</I> -pubin -inkey <I>public.pem</I> -pkeyopt <I>rsa_padding_mode:pss</I> -pkeyopt <I>digest:sha256</I></code><br>Note: For signing/verifying, 'rsa_padding_mode:pss' is often preferred for RSA. The 'digest' option tells pkeyutl which digest algorithm was used to produce the input, allowing it to correctly apply padding.


title: HISTORY
content:
The pkeyutl command was introduced in OpenSSL to provide a generic, algorithm-independent interface for various public key operations. Prior to its introduction or widespread use, specific utilities like 'rsa', 'dsa', 'ec' were often used for operations tied to their respective algorithms. pkeyutl simplifies scripting and allows for more flexible handling of different key types without needing to invoke distinct commands. Its development reflects OpenSSL's move towards a more unified and extensible cryptographic architecture, making it a powerful tool for advanced cryptographic tasks.


title: PARAMETERS
content:
<b><b>-y</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assume 'yes' to all queries without prompting. Useful for non-interactive scripts.<br><br><b><b>-f</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the requested operation, overriding checks or existing conditions where appropriate.<br><br><b><b>-q</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Operate quietly, suppressing most informational output messages.<br><br><b><b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Operate verbosely, showing more detailed output about the ongoing operation.<br><br><b><b>-r</b> <i>&lt;repo&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the repository from which to fetch packages. Overrides default repository configuration for the command.<br><br><b><b>-C</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not use the local package cache; forces a re-download of metadata from remote repositories.<br><br><b><b>-o</b> <i>&lt;option=value&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set a specific configuration option for the command. Can be used multiple times.<br><br><b><b>-R</b> <i>&lt;rootdir&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use <i>&lt;rootdir&gt;</i> as the root directory for all operations (similar to a chroot environment).<br><br><b><b>-s</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform operations in a 'sandbox' or simulated mode (dry run) without making actual changes.<br><br><b><b>-U</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not update the repository metadata from the remote source before executing the command.<br><br>


title: DESCRIPTION
content:
<i>pkg</i> is the official binary package management utility for FreeBSD and other BSD-based operating systems. It provides a robust, dependency-aware framework for installing, upgrading, and removing pre-compiled software packages. It handles complex dependency chains, ensures consistent system state, and allows for safe upgrades and easy rollbacks. <i>pkg</i> interacts with remote repositories to fetch and manage packages, offering features like package auditing for known vulnerabilities, automatic removal of orphaned dependencies, and query capabilities for installed software. <br><br><b>Important Note:</b> While the prompt asks for a 'Linux command', <i>pkg</i> is primarily known and used as the package manager for FreeBSD. Linux distributions use different package managers like <i>apt</i> (Debian/Ubuntu), <i>yum</i>/<i>dnf</i> (Red Hat/Fedora), or <i>pacman</i> (Arch Linux). A standalone <i>pkg</i> command is not natively available or commonly used on most Linux systems.


title: CAVEATS
content:
<i>pkg</i> is the primary package management tool for FreeBSD and other BSD derivatives, not for standard Linux distributions. While some Linux environments might contain a tool named 'pkg' (e.g., specific development tools or custom setups), it is not part of the core Linux utility set. Users on Linux systems should typically use their distribution's native package manager (e.g., <i>apt</i>, <i>dnf</i>, <i>pacman</i>, <i>zypper</i>) to manage software packages.


title: COMMON COMMANDS
content:
<i>pkg</i> operates through a series of subcommands that define the action to be performed. Here are some of the most frequently used:<br><b>install</b> <i>&lt;pkg_name&gt;</i>: Installs one or more specified packages.<br><b>remove</b> <i>&lt;pkg_name&gt;</i>: Removes one or more specified packages.<br><b>update</b>: Fetches the latest package catalog (metadata) from configured repositories.<br><b>upgrade</b>: Upgrades all installed packages to their latest available versions based on the updated catalog.<br><b>search</b> <i>&lt;term&gt;</i>: Searches for packages matching a specified term in the repository catalogs.<br><b>info</b> <i>&lt;pkg_name&gt;</i>: Displays detailed information about an installed or available package.<br><b>autoremove</b>: Removes packages that were installed as dependencies and are no longer required by any other installed software.<br><b>clean</b>: Clears the local package cache of downloaded package files to free up disk space.


title: CONFIGURATION
content:
<i>pkg</i>'s behavior and repository settings are controlled by configuration files. The primary configuration file is typically <i>/usr/local/etc/pkg.conf</i>. Repository definitions are managed in files within the <i>/usr/local/etc/pkg/repos/</i> directory. These files define repository URLs, package signing keys, and other system-wide preferences, allowing for flexible management of package sources.


title: HISTORY
content:
The <i>pkg</i> utility for FreeBSD was developed to modernize and replace the older <i>pkg_install</i> tools. It was designed to provide a more robust, transactional, and user-friendly experience for managing binary packages. It became the official package manager starting with FreeBSD 10.0-RELEASE. Its development aimed to address limitations of previous systems, offering improved dependency resolution, integrity checking, and repository management.


title: PARAMETERS
content:
<b><b>--cflags</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output pre-processor and compiler flags for the specified libraries.<br><br><b><b>--libs</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output linker flags for the specified libraries.<br><br><b><b>--modversion</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output the version string of the specified module.<br><br><b><b>--list-all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;List all modules that <b>pkg-config</b> knows about.<br><br><b><b>--exists</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Check if the specified modules exist; returns 0 if all exist, non-zero otherwise.<br><br><b><b>--atleast-version=<i>VERSION</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Check if the module's version is at least the specified <i>VERSION</i>.<br><br><b><b>--variable=<i>NAME</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output the value of a specific variable defined within the module's <b>.pc</b> file.<br><br><b><b>--static</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output flags suitable for static linking, often including full dependency closure.<br><br><b><b>--uninstalled</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Look for uninstalled modules, useful during library development.<br><br><b><b>--with-path=<i>PATH</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add <i>PATH</i> to the search path for <b>.pc</b> files, overriding <b>PKG_CONFIG_PATH</b> for this command.<br><br><b><b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose debug output to assist with troubleshooting.<br><br><b><b>--silence-errors</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress all error messages, useful when only the exit status is needed.<br><br>


title: DESCRIPTION
content:
<i><b>pkg-config</b> is a command-line utility that simplifies the process of compiling and linking applications against installed libraries. It queries metadata files, typically with a <b>.pc</b> extension, which libraries install in standard locations like <b>/usr/lib/pkgconfig</b>. These <b>.pc</b> files contain crucial information such as header file locations (<b>-I</b> flags), library paths (<b>-L</b> flags), library names (<b>-l</b> flags), version numbers, and dependencies. By automating the retrieval of these compilation and linking flags, <b>pkg-config</b> eliminates the need for developers to hardcode paths or options. This makes build systems more robust, portable, and easier to manage across different operating systems or environments, significantly reducing potential errors when library versions or locations change. It is widely adopted in open-source projects, serving as a critical component in many modern build workflows.</i>


title: CAVEATS
content:
<i><b>pkg-config</b>'s functionality is dependent on libraries providing correct and complete <b>.pc</b> files, which is not universally guaranteed. For non-standard installations or cross-compilation environments, proper configuration of environment variables such as <b>PKG_CONFIG_PATH</b> and <b>PKG_CONFIG_SYSROOT_DIR</b> is crucial. While effective for direct dependencies, complex or deeply nested transitive dependencies might occasionally require manual intervention or deeper understanding of the specific library's build requirements.</i>


title: <B>PKG_CONFIG_PATH ENVIRONMENT VARIABLE</B>
content:
<i>This crucial environment variable specifies a colon-separated list of directories where <b>pkg-config</b> searches for <b>.pc</b> files. It is essential for locating libraries installed in non-standard or custom prefix locations (e.g., <b>/usr/local/lib/pkgconfig</b>, <b>~/my_libs/lib/pkgconfig</b>), ensuring that <b>pkg-config</b> can find all necessary module definitions.</i>


title: <B>.PC FILES</B>
content:
<i>These plain-text metadata files are fundamental to <b>pkg-config</b>'s operation. Each <b>.pc</b> file provides details about a specific library, including its version, installation prefix, required compiler flags (<b>Cflags</b>), linker flags (<b>Libs</b>), and direct dependencies (<b>Requires</b>, <b>Conflicts</b>). Libraries typically install their corresponding <b>.pc</b> file into a <b>pkgconfig</b> subdirectory within their <b>libdir</b> (e.g., <b>/usr/lib/x86_64-linux-gnu/pkgconfig/gtk+-3.0.pc</b>), making their build information discoverable.</i>


title: <B>CROSS-COMPILATION SUPPORT</B>
content:
<i><b>pkg-config</b> includes robust support for cross-compilation. This is achieved by setting environment variables such as <b>PKG_CONFIG_SYSROOT_DIR</b>, which points to the sysroot of the target architecture, and <b>PKG_CONFIG_LIBDIR</b>, which specifies the path to the <b>pkgconfig</b> directory within that sysroot. This setup allows build systems to accurately query libraries intended for a different architecture than the host system, ensuring correct compilation and linking for diverse targets.</i>


title: HISTORY
content:
<i><b>pkg-config</b> originated within the GNOME project to standardize and simplify the process of finding and using library dependencies, replacing less flexible predecessors like <b>gnome-config</b> and <b>kde-config</b>. Its core innovation was the introduction of standardized <b>.pc</b> metadata files. This design offered a consistent and portable method for libraries to expose their build-time information. Due to its simplicity, efficiency, and the portability benefits it offered, <b>pkg-config</b> quickly became a de facto standard in Linux and Unix-like build environments, extending its usage far beyond its initial GNOME-centric scope to become a widely adopted tool across various open-source projects.</i>


title: SYNOPSIS
content:
<I>pkgadd</I> <B>[-d <I>device</I>]</B> <B>[-R <I>root_path</I>]</B> <B>[-s <I>spool_dir</I>]</B> <B>[-a <I>admin_file</I>]</B> <B>[-r <I>response_file</I>]</B> <B>[-n]</B> <B>[-q]</B> <B>[-G]</B> <B>[-x]</B> <B>[-V <I>version</I>]</B> <I>pkg_id</I> [<I>pkg_id</I>...]<br><I>pkgadd</I> <B>-s <I>spool_dir</I></B> <B>-d <I>device</I></B> [<I>pkg_id</I>]


title: PARAMETERS
content:
<b>-d <I>device</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the source device or directory for the package (e.g., tape, CD-ROM, local path).<br><br><b>-R <I>root_path</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternate root path (chroot environment) where the package should be installed instead of the default '/'. Used for non-global zones or system imaging.<br><br><b>-s <I>spool_dir</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Spools the package to a specified directory on the local system before installation. This allows for package storage and later installation without the original media.<br><br><b>-a <I>admin_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an administrative file to override default installation behaviors, such as prompting for package information or handling of file conflicts.<br><br><b>-r <I>response_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides a response file containing answers to questions that <I>pkgadd</I> might pose during installation, enabling unattended installations.<br><br><b>-n</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Non-interactive mode. Assumes 'no' to any questions that would typically require user input, often leading to installation abortion if input is mandatory.<br><br><b>-q</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Quiet mode. Suppresses most output during the installation process, useful for scripting or automated deployments.<br><br><b>-G</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not install package group dependencies. Only the specified package will be installed, ignoring any declared dependencies on other packages within the same group.<br><br><b>-x</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes pre-installation and post-installation scripts in a non-trusted shell environment, providing additional security by limiting their capabilities.<br><br><b>-V <I>version</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the SVR4 version of the package format. Rarely used explicitly as <I>pkgadd</I> typically detects it.<br><br><b><I>pkg_id</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more unique identifiers of the package(s) to be added. This is the primary argument to specify which package to install.<br><br>


title: DESCRIPTION
content:
<I>pkgadd</I> is a command used to <B>install software packages</B> onto a System V Release 4 (SVR4) compliant Unix system. Unlike Linux, which predominantly uses package managers like <I>APT</I> (Debian/Ubuntu), <I>RPM</I> (Red Hat/CentOS/Fedora), or <I>pacman</I> (Arch Linux), <B>pkgadd is not a standard command found on most Linux distributions</B>. Its primary home is on systems such as <I>Solaris</I>, <I>HP-UX</I>, and older versions of <I>AIX</I>, which adhere to the SVR4 packaging standard.<br><br>The packages managed by <I>pkgadd</I> are typically found in a specific directory structure containing metadata files (<B>pkginfo</B>) and scripts (<B>preinstall</B>, <B>postinstall</B>, <B>preremove</B>, <B>postremove</B>) that automate the installation and configuration process. When executed, <I>pkgadd</I> prompts the user for information where necessary, verifies package integrity, and executes any associated installation scripts. It handles the placement of files, creation of symbolic links, and updates system records to track installed components.<br><br><I>pkgadd</I> can install packages from various media, including tape drives, CD-ROMs, network file systems, or local directories. It also supports "spooling" packages, which involves copying the package to a local disk area before installation, allowing for offline installation or easier management of multiple installations. Its design reflects a time when software distribution was more standardized across different Unix vendors under the SVR4 initiative. Understanding <I>pkgadd</I> is crucial when working with legacy System V Unix environments, or when porting applications from such systems.


title: CAVEATS
content:
<B>Not a native Linux command:</B> <I>pkgadd</I> is primarily found on System V Release 4 (SVR4) Unix systems such as Solaris, HP-UX, and older AIX versions. It is <B>not part of standard Linux distributions</B> (which use <I>APT</I>, <I>RPM</I>, <I>dnf</I>, <I>zypper</I>, etc.) and will not be available unless specifically ported or if you are on a very specialized Linux variant aiming for SVR4 compatibility.<br><B>Package Format Dependency:</B> It only works with packages formatted according to the SVR4 packaging standard, which differs significantly from common Linux package formats (.deb, .rpm).<br><B>Security Implications:</B> Packages can contain pre-install and post-install scripts that run with elevated privileges. Always ensure the package source is trusted.


title: USAGE CONTEXT
content:
You would typically encounter <I>pkgadd</I> when working with legacy System V Unix systems (e.g., Solaris 10 and earlier, some HP-UX or AIX environments), or in very specific cross-platform scenarios where SVR4 package formats are still used. It is <B>not relevant for most modern Linux administrative tasks</B>.


title: SVR4 PACKAGE STRUCTURE
content:
An SVR4 package is essentially a directory structure, or a file stream, containing various components:<br> - <B>pkginfo</B>: A mandatory file containing package metadata (name, version, architecture, dependencies).<br> - <B>install</B> scripts: Optional scripts like <I>preinstall</I>, <I>postinstall</I>, <I>preremove</I>, <I>postremove</I> that automate setup or teardown tasks.<br> - <B>reloc</B>: A directory for relocatable files.<br> - <B>root</B>: A directory for absolute path files.<br> - Other control files.


title: HISTORY
content:
The <I>pkgadd</I> command is a core component of the <B>System V Release 4 (SVR4) packaging system</B>, which was developed in the late 1980s by AT&T and Sun Microsystems as an attempt to standardize Unix operating systems and their software management practices. It was designed to provide a robust and portable method for installing and managing software across diverse SVR4-compliant Unix platforms. While it was widely adopted on systems like Solaris, HP-UX, and older AIX versions, its influence on Linux was indirect. Linux distributions later developed their own, more advanced package management systems (<I>RPM</I>, <I>APT</I>) that drew on some concepts but diverged significantly in implementation and package formats. Therefore, <I>pkgadd</I>'s history is tied to the evolution of Unix rather than Linux directly.


title: SYNOPSIS
content:
<b>pkgctl</b> &lt;<i>subcommand</i>&gt; [<i>options</i>] [<i>arguments</i>]<br><br><i>Common Subcommands:</i><br><b>pkgctl install</b> &lt;<i>package</i>&gt;...<br><b>pkgctl update</b><br><b>pkgctl search</b> &lt;<i>pattern</i>&gt;<br><b>pkgctl remove</b> &lt;<i>package</i>&gt;...<br><b>pkgctl sync</b>


title: PARAMETERS
content:
<b><b>--pretend</b>, <b>-p</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs a dry run, showing what changes would be made without actually executing them.<br><br><b><b>--ask</b>, <b>-a</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prompts the user for confirmation before proceeding with the operation.<br><br><b><b>--verbose</b>, <b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increases the verbosity of the output, providing more detailed information.<br><br><b><b>--quiet</b>, <b>-q</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses non-essential output, showing only critical messages.<br><br><b><b>--help</b>, <b>-h</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the <i>pkgctl</i> command or a specific subcommand (e.g., <i>pkgctl install --help</i>).<br><br>


title: DESCRIPTION
content:
<i>pkgctl</i> is a modern, user-friendly command-line interface for the Gentoo/Funtoo Linux distributions' <i>Portage</i> package management system. It aims to simplify common package operations that traditionally require more complex <i>emerge</i> commands. Inspired by <i>git</i>'s subcommand structure, <i>pkgctl</i> provides intuitive subcommands like <b>install</b>, <b>remove</b>, <b>update</b>, <b>search</b>, and <b>sync</b>, making package management more accessible for both new and experienced users.<br><br>It abstracts away some of the intricacies of <i>Portage</i> while still leveraging its powerful features like USE flags, slots, and profiles. <i>pkgctl</i> helps streamline workflows for installing new software, keeping the system updated, and managing installed packages efficiently. It serves as a more direct and convenient alternative for daily tasks, while advanced or specific <i>Portage</i> operations might still be performed with <i>emerge</i>.


title: CAVEATS
content:
<i>pkgctl</i> is specific to Gentoo/Funtoo Linux distributions and requires <i>Portage</i> as its backend; it is not a standalone package manager for other systems. While designed for daily use, some highly advanced or niche <i>Portage</i> operations may still require direct use of the <i>emerge</i> command.


title: SUBCOMMAND STRUCTURE
content:
<i>pkgctl</i> employs a subcommand architecture (similar to <i>git</i>), where different operations are handled by distinct subcommands (e.g., <b>install</b>, <b>remove</b>, <b>update</b>). This design makes the command set more organized, intuitive, and easier to remember for users.


title: INTEGRATION WITH PORTAGE
content:
While <i>pkgctl</i> provides a new interface, it fully leverages the underlying <i>Portage</i> system. This means it respects and interacts with existing <i>Portage</i> configurations, such as USE flags, package masks, and overlays, ensuring seamless integration with the Gentoo system.


title: HISTORY
content:
<i>pkgctl</i> was developed relatively recently within the Gentoo ecosystem as a modern frontend for <i>Portage</i>. Its development was driven by the desire to provide a more intuitive and <i>git</i>-like command structure, simplifying daily package management tasks compared to the more verbose <i>emerge</i> syntax. It gained traction as a more user-friendly alternative, making Gentoo more approachable. Its design aims to abstract away some of the complexities while still providing access to <i>Portage</i>'s powerful features.


title: SYNOPSIS
content:
<i>pkgctl</i> <b>auth</b> <i>subcommand</i> [<b>options</b>]<br><i>pkgctl</i> <b>auth login</b> [<b>--username</b> <i>user</i>] [<b>--password-file</b> <i>file</i>]<br><i>pkgctl</i> <b>auth logout</b><br><i>pkgctl</i> <b>auth status</b>


title: PARAMETERS
content:
<b>login</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>subcommand</i>. Authenticates the user with configured services or repositories. This typically prompts for credentials interactively if not provided via options or environment variables, then securely stores authentication tokens.<br><br><b>--username <user></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>option for login</i>. Specifies the username for non-interactive authentication. Should be used with <b>--password-file</b> or in an environment where the password can be provided.<br><br><b>--password-file <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>option for login</i>. Provides the password from a specified file for non-interactive authentication. The file should contain only the password and have restrictive permissions (e.g., 0600).<br><br><b>logout</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>subcommand</i>. Deauthenticates the user by removing stored credentials or tokens for all configured services, requiring re-login for future authenticated operations.<br><br><b>status</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>subcommand</i>. Displays the current authentication status for all configured services, indicating whether the user is logged in and, in some cases, the expiry of tokens.<br><br>


title: DESCRIPTION
content:
<i>pkgctl-auth</i> refers to the authentication capabilities within the <i>pkgctl</i> package management utility, primarily accessed via the <i>pkgctl auth</i> subcommand. This functionality allows users to securely log in, log out, and check their authentication status with various package repositories and services that require credentials, such as Red Hat Subscription Management or private enterprise repositories.<br><br>It handles the secure storage and retrieval of authentication tokens or credentials, ensuring that <i>pkgctl</i> can access authorized resources. Unlike many traditional Linux commands, <i>pkgctl-auth</i> is not a standalone executable but an integral part of the <i>pkgctl</i> command suite, focusing on providing a streamlined and secure authentication workflow for package operations. It integrates with system credential stores where available, enhancing security and user convenience.


title: CAVEATS
content:
<b>Security</b>: When using <b>--password-file</b>, ensure the file has restrictive permissions (e.g., 0600) to prevent unauthorized access to credentials. Avoid using this option in shared environments if possible.<br><b>Integration</b>: <i>pkgctl-auth</i> relies on the proper configuration of <i>pkgctl</i> services and repositories. If services are not correctly set up, authentication attempts may fail.<br><b>Non-Standalone</b>: This command refers to a sub-component of <i>pkgctl</i>. There is no direct <i>pkgctl-auth</i> executable; functionality is accessed via <i>pkgctl auth</i>.


title: CREDENTIAL STORAGE
content:
<i>pkgctl-auth</i> attempts to integrate with secure system credential stores (e.g., keyring services) where available, to store authentication tokens and sensitive data more securely than plain text files. This enhances overall system security.


title: SERVICE SPECIFICS
content:
The exact authentication flow and requirements can vary depending on the service being authenticated against. For instance, authenticating with Red Hat Subscription Management uses different mechanisms than a simple username/password for an HTTP basic authentication protected repository.


title: HISTORY
content:
<i>pkgctl</i> is part of the DNF5 project, intended as a modern, high-level command-line interface for RPM-based package management. Its development aims to unify and simplify package operations. The <i>auth</i> subcommand, which <i>pkgctl-auth</i> refers to, was introduced as an essential component to handle authentication for commercial or private repositories, a common requirement in enterprise environments. It provides a more structured and secure way to manage credentials compared to ad-hoc methods.


title: SYNOPSIS
content:
<b>pkgctl build</b> [<br>&nbsp;&nbsp;&nbsp;&nbsp;<b>--chroot</b> | <b>-c</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>--force</b> | <b>-f</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>--install</b> | <b>-i</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>--syncdeps</b> | <b>-s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>--rmdeps</b> | <b>-r</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>--skipinteg</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>--noextract</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>--nodeps</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>--noconfirm</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>--clean</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>--log</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>--log-level</b> <<i>level</i>><br>&nbsp;&nbsp;&nbsp;&nbsp;...<br>][<<i>package-path</i>>]


title: PARAMETERS
content:
<b><b>[</b><i>package-path</i><b>]</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to the directory containing the PKGBUILD file, or the PKGBUILD file itself. Defaults to the current working directory.<br><br><b><b>-c</b>, <b>--chroot</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Build the package in a clean chroot environment. This ensures a pristine build free from system-specific dependencies.<br><br><b><b>-f</b>, <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the build process, even if a package with the same version already exists or is considered up-to-date.<br><br><b><b>-i</b>, <b>--install</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Install the built package(s) using <i>pacman</i> after a successful build.<br><br><b><b>-s</b>, <b>--syncdeps</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sync and install any missing build dependencies from the official repositories before building.<br><br><b><b>-r</b>, <b>--rmdeps</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Remove build dependencies after the package has been successfully built and/or installed.<br><br><b><b>--skipinteg</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skip integrity checks (MD5, SHA256, etc.) for source files. Use with caution.<br><br><b><b>--noextract</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not extract the source files. Useful if sources are already extracted in the build directory.<br><br><b><b>--nodeps</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not check for or install any dependencies. Assumes all necessary dependencies are already satisfied.<br><br><b><b>--noconfirm</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not prompt for any user confirmation during the build or installation process.<br><br><b><b>--clean</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Clean up the build directory before and after the build process.<br><br><b><b>--log</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Log the build output to a file for later review.<br><br><b><b>--log-level</b> <<i>level</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the verbosity level for logging output (e.g., info, debug, warn).<br><br>


title: DESCRIPTION
content:
<i>pkgctl-build</i> is a powerful subcommand of the <i>pkgctl</i> utility, specifically designed to streamline the process of building Arch Linux packages. It acts as an intelligent wrapper around <i>makepkg</i>, automating crucial steps such as resolving and installing build dependencies, fetching source files, and executing the build process. This command is particularly valuable for users who frequently interact with the Arch User Repository (AUR) or manage custom local packages. It aims to simplify the common workflow, often reducing it to a single command, making package creation and maintenance more efficient and less prone to manual errors. Features like optional chroot builds ensure clean environments, while integration with <i>pkgctl</i>'s broader capabilities offers a cohesive package management experience on Arch-based systems. It handles various build scenarios, providing a more integrated and user-friendly interface compared to manual <i>makepkg</i> invocations.


title: CAVEATS
content:
<i>pkgctl-build</i> relies heavily on the underlying <i>makepkg</i> utility and its configuration found in <i>/etc/makepkg.conf</i>.<br>Using the <b>--chroot</b> option requires <i>arch-install-scripts</i> and a properly set up chroot environment (e.g., via <i>mkarchroot</i>).<br>Building packages from the Arch User Repository (AUR) carries inherent risks as these packages are user-contributed and not officially supported.<br>This command is primarily designed for Arch Linux and its derivatives.


title: PKGBUILD FILES
content:
<i>pkgctl-build</i> operates on <i>PKGBUILD</i> files, which are essential shell scripts in Arch Linux. These files contain all the metadata and instructions necessary for <i>makepkg</i> (and by extension, <i>pkgctl-build</i>) to download sources, resolve dependencies, compile software, and package it into an Arch Linux package (.pkg.tar.zst).


title: CHROOT BUILDS EXPLAINED
content:
Building in a chroot (change root) environment, enabled by the <b>--chroot</b> option, involves creating a minimal, isolated Arch Linux installation. This ensures that the package is built against a clean, consistent set of dependencies, preventing 'polluted' builds where a package might inadvertently link against libraries or files present only on the host system. This is crucial for reproducible builds and for ensuring the package works correctly on other Arch systems.


title: HISTORY
content:
<i>pkgctl</i> is a relatively modern addition to the Arch Linux ecosystem, developed to provide a more unified and user-friendly command-line interface for various package management tasks. <i>pkgctl-build</i> specifically emerged to streamline the often complex process of building local or AUR packages, offering a more automated approach than direct <i>makepkg</i> commands. Its development reflects a trend towards consolidating and improving the user experience for Arch Linux package maintainers and users.


title: PARAMETERS
content:
<b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message and exits, showing general usage and available options for the command.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increases the verbosity of the output, providing more detailed information about the database update process.<br><br><b><b>-q</b>, <b>--quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Decreases the verbosity of the output, suppressing most non-essential messages during the update.<br><br><b><b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables debugging output, useful for troubleshooting issues with the database update process.<br><br><b><b>--json</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the results or status of the update operation in a JSON format, suitable for machine parsing.<br><br>


title: DESCRIPTION
content:
<i>pkgctl-db-update</i> refers to the essential operation of synchronizing and updating the local package database within the <i>pkgctl</i> package management system, primarily developed for Gentoo Linux. This command, typically invoked as <b>pkgctl db update</b>, plays a crucial role in ensuring that <i>pkgctl</i> has the most current metadata about available software packages, their versions, dependencies, and ebuilds (Gentoo's package definition scripts).<br><br>When executed, <b>pkgctl db update</b> connects to configured remote repositories (such as the Gentoo Portage tree and specified overlays) to fetch the latest package information. This process involves downloading new ebuilds, updating checksums, and refreshing the local index that <i>pkgctl</i> uses for all subsequent operations. Without an up-to-date database, <i>pkgctl</i> cannot accurately search for, install, upgrade, or remove packages, as it would be operating on stale information.<br><br>The function of <b>pkgctl db update</b> is analogous to <b>emerge --sync</b> in traditional Gentoo environments or <b>apt update</b> in Debian-based distributions. It is generally the first command a user runs after system installation or periodically to prepare for any package management tasks, guaranteeing that dependency resolution is correct and that the latest security patches and features are discoverable and available for installation. It is a fundamental step in maintaining a healthy and current Gentoo system using <i>pkgctl</i>.


title: CAVEATS
content:
<i>pkgctl</i> is a relatively new and actively developed package manager for Gentoo. As such, its features, options, and behavior, including the database update mechanism, may evolve rapidly and are not yet considered stable for production use. It requires network connectivity to synchronize with remote repositories and typically needs root privileges or appropriate permissions to modify system-wide package database files.


title: PURPOSE OF THE DATABASE
content:
The local <i>pkgctl</i> database stores crucial information about available ebuilds, package versions, repository configurations, and mirrors. Maintaining this local copy enables fast searching, accurate dependency resolution, and ensures that <i>pkgctl</i> operates with the most current and correct data.


title: NETWORK REQUIREMENTS
content:
Successful execution of <b>pkgctl db update</b> requires active internet connectivity to reach configured package repositories and download the latest metadata. Without a network connection, the command will not be able to fetch updates.


title: PRIVILEGES
content:
Typically, updating the system-wide package database requires root privileges or equivalent permissions, as it involves writing to system directories where package metadata is stored. Running the command without sufficient privileges will likely result in permission denied errors.


title: HISTORY
content:
<i>pkgctl</i> is part of a modern initiative within the Gentoo Linux project to create a more consistent and user-friendly command-line interface for package management, addressing some complexities of the traditional <i>emerge</i> utility. The <i>db update</i> command is a fundamental component of <i>pkgctl</i> from its early development, essential for maintaining the local package index necessary for all package operations. Its development reflects the ongoing efforts to innovate Gentoo's package management ecosystem.


title: SYNOPSIS
content:
<b>pkgctl diff</b> [<i>options</i>] <i><package_or_file_reference></i> [<i><additional_reference></i>]<br><br>Common usage patterns:<br><b>pkgctl diff</b> <i><pkgname></i><br><b>pkgctl diff</b> <b>--git-diff</b> <i><file1></i> <i><file2></i><br><b>pkgctl diff</b> <b>--repo</b> <i><repository></i> <i><pkgname></i><br><b>pkgctl diff</b> <b>--version</b> <i><version></i> <i><pkgname></i><br><b>pkgctl diff</b> <i><pkgname></i> <i><old_path></i> <i><new_path></i>


title: PARAMETERS
content:
<b><b>--color[=</b><I>when</I><b>]</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables or disables colored output. The <I>when</I> argument can be 'always', 'never', or 'auto'.<br><br><b><b>--diff-cmd</b> <I>command</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an external command to use for generating the diff output instead of the default.<br><br><b><b>--git-diff</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces <i>pkgctl-diff</i> to use <i>git diff</i> for comparing arbitrary file arguments, bypassing package-specific logic.<br><br><b><b>--no-color</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables colored output, overriding any default color settings.<br><br><b><b>--plain</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs a plain diff, without additional context lines or special formatting.<br><br><b><b>--repo</b> <I>repository</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Compares the package against the version found in the specified repository.<br><br><b><b>--version</b> <I>version</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Compares the package against a specific version string, typically used for historical comparisons.<br><br><b><b>--pkgbuild</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly compares the local <i>PKGBUILD</i> file with its upstream version. This is often the default behavior when only a package name is provided.<br><br><b><b>--config-file</b> <I>path</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative configuration file to use for <i>pkgctl</i> operations.<br><br>


title: DESCRIPTION
content:
<i>pkgctl-diff</i> is a subcommand of the <i>pkgctl</i> utility, a modern command-line interface tool designed for package management tasks in Arch Linux. While <i>pkgctl</i> offers a unified front-end for various operations like building, publishing, and testing packages, <i>pkgctl-diff</i> specifically focuses on showing differences.<br><br>It can compare a local <i>PKGBUILD</i> file with its upstream repository version, allowing package maintainers to quickly see changes. It can also be used to compare two specific files, leveraging <i>git</i>'s diff capabilities. Furthermore, <i>pkgctl-diff</i> facilitates comparisons between different package versions or between a package as it exists in a repository versus a local build or installed state.<br><br>This command is invaluable for developers maintaining packages, as it helps in tracking upstream changes, verifying modifications, and ensuring consistency. For advanced users, it provides a powerful way to inspect proposed package updates or to debug issues by examining differences in package content or build instructions.


title: CAVEATS
content:
<i>pkgctl-diff</i> is primarily designed for the Arch Linux ecosystem and relies on the <i>pkgctl</i> tool's infrastructure. Its functionality is heavily dependent on the availability of package metadata in configured repositories. While it can perform generic file diffs using <b>--git-diff</b>, its core strength lies in package-related comparisons. Network access is required for comparisons involving remote repositories.


title: PRIMARY USE CASE
content:
<i>pkgctl-diff</i> is most commonly used by Arch Linux package maintainers and developers to monitor changes in upstream <i>PKGBUILD</i> files, compare source code versions, or verify the integrity of their local package builds against official repositories. It's a critical tool for maintaining the quality and security of packages within the Arch ecosystem.


title: GIT INTEGRATION
content:
A significant aspect of <i>pkgctl-diff</i>'s design is its deep integration with <i>Git</i>. Many of its comparison functionalities internally leverage <i>git diff</i>, providing rich, colored, and contextual diff output, which is familiar to developers accustomed to version control systems.


title: HISTORY
content:
<i>pkgctl</i>, and by extension <i>pkgctl-diff</i>, emerged as part of the Arch Linux project's efforts to modernize and streamline its package management tooling. Developed by the Arch Linux team, it aims to provide a more consistent and user-friendly interface for various tasks that traditionally involved separate tools like <i>pacman</i> and <i>makepkg</i>. Its development gained momentum in the late 2010s and early 2020s, reflecting a desire for more integrated and efficient workflows, especially for package maintainers and developers.


title: PARAMETERS
content:
<b><I>--branch &lt;branch&gt;</I>, <I>-b &lt;branch&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the target Fedora branch (e.g., <i>f38</i>, <i>rawhide</i>) for the release.<br><br><b><I>--stable</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Proposes the update as a <i>stable</i> release in Bodhi, requiring karma.<br><br><b><I>--unstable</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Proposes the update as an <i>unstable</i> release in Bodhi, typically for testing.<br><br><b><I>--message &lt;message&gt;</I>, <I>-m &lt;message&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the detailed message for the Bodhi update.<br><br><b><I>--type &lt;type&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the type of Bodhi update (e.g., <i>bugfix</i>, <i>enhancement</i>, <i>security</i>).<br><br><b><I>--commit</I>, <I>-c</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Commits the changes to the local dist-git repository.<br><br><b><I>--push</I>, <I>-p</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pushes the committed changes to the remote dist-git repository.<br><br><b><I>--update</I>, <I>-u</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a new update in the Bodhi update system.<br><br><b><I>--from-tag &lt;tag&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a particular git tag from which the release should be based.<br><br><b><I>--dry-run</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs a simulated run without making any actual changes or pushing to remote.<br><br><b><I>--force</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the release operation, potentially overriding existing checks.<br><br><b><I>--wait-on-update</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Waits for the Bodhi update to be successfully created and returned.<br><br><b><I>--notes &lt;notes&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds additional release notes to the Bodhi update, displayed in Bodhi.<br><br>


title: DESCRIPTION
content:
<b>pkgctl-release</b> is a subcommand of the <b>pkgctl</b> utility, which streamlines the process of preparing and submitting package updates within the Fedora Project's dist-git infrastructure. It automates several steps traditionally performed manually by package maintainers, including creating new branches, committing changes, pushing them to dist-git, and proposing updates to the Bodhi update system. <br><br>This command aims to simplify the release workflow, ensuring consistency and reducing the potential for errors during the package update process. It's primarily used for pushing new upstream releases or important bug fixes to various Fedora branches, making the update process more efficient and less prone to manual mistakes.


title: CAVEATS
content:
<ul><li>Requires a properly configured <b>dist-git</b> environment and authenticated access to the Fedora infrastructure (e.g., Kerberos tickets).</li><li>Incorrect usage, especially with <b>--force</b>, can lead to unintended package updates or conflicts.</li><li>Assumes the user is in a <b>dist-git</b> repository clone for a specific package.</li><li>Network connectivity is essential for interacting with <b>dist-git</b> and <b>Bodhi</b>.</li></ul>


title: WORKFLOW INTEGRATION
content:
The <b>pkgctl-release</b> command is typically used as part of a larger package update workflow. It is often preceded by local development, testing, and building the package, and followed by monitoring the Bodhi update system for karma and eventual stable release.


title: IDEMPOTENCY AND SAFETY
content:
While designed to be robust, it's crucial to understand that repeated calls might not always be idempotent, especially if the state of the dist-git repository or Bodhi has changed externally. Using <b>--dry-run</b> is highly recommended for complex or new release scenarios to preview actions without committing them.


title: HISTORY
content:
The <b>pkgctl</b> suite, including <b>pkgctl-release</b>, was developed as a modern replacement and improvement over the older <b>fedpkg</b> tool for interacting with Fedora's dist-git. It aims to provide a more intuitive and consistent command-line interface, leveraging Python and focusing on simplifying common packaging workflows. Its introduction reflects Fedora's continuous efforts to streamline contributor tools and improve developer experience.


title: PARAMETERS
content:
<b><b>add</b> <i>--name NAME</i> <i>--baseurl URL</i> [<i>OPTIONS</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a new RPM repository definition. Requires a unique name and either a base URL, mirror list, or metalink. Other options can define its properties like GPG keys, priority, and initial enabled state.<br><br><b><b>remove</b> <i>--name NAME</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes an existing RPM repository definition by its unique name.<br><br><b><b>list</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all currently configured RPM repositories managed by <i>pkgctl-repo</i>, along with their key properties.<br><br><b><b>enable</b> <i>--name NAME</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables a previously added or disabled repository, making it available for <i>rpm-ostree</i> operations.<br><br><b><b>disable</b> <i>--name NAME</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables an active repository, preventing <i>rpm-ostree</i> from using it for package layering.<br><br><b><i>--name NAME</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the unique name for the repository. This name is used to identify the repository in subsequent commands like <b>remove</b>, <b>enable</b>, or <b>disable</b>.<br><br><b><i>--baseurl URL</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the base URL for the repository. This option is mutually exclusive with <i>--mirrorlist</i> and <i>--metalink</i>.<br><br><b><i>--gpgkey PATH|URL</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path or URL to the GPG public key used for verifying package signatures from this repository. Essential for secure package layering.<br><br><b><i>--priority PRIORITY</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the priority for the repository (an integer from 1 to 99). Lower numbers indicate higher priority, influencing package resolution by <i>rpm-ostree</i>/DNF.<br><br><b><i>--cost COST</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the cost for the repository, influencing package selection when multiple repositories provide the same package.<br><br><b><i>--description DESCRIPTION</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides a human-readable description for the repository, useful for documentation and clarity.<br><br><b><i>--enabled {true|false}</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the initial enabled state of the repository when adding it. Defaults to <i>true</i> if not specified for <b>add</b>.<br><br><b><i>--disable-gpg-check</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables GPG signature checking for the repository. Use with extreme caution as it compromises security by allowing installation of unsigned packages.<br><br><b><i>--mirrorlist URL</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a URL to a mirror list file for the repository. Mutually exclusive with <i>--baseurl</i> and <i>--metalink</i>.<br><br><b><i>--metalink URL</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a URL to a metalink file for the repository. Mutually exclusive with <i>--baseurl</i> and <i>--mirrorlist</i>.<br><br>


title: DESCRIPTION
content:
<i>pkgctl-repo</i> is a subcommand of the <i>pkgctl</i> utility, designed for managing custom DNF/RPM repositories on systems that leverage <i>rpm-ostree</i>, such as Fedora CoreOS or CentOS Stream CoreOS. It provides a streamlined interface for administrators to add, remove, enable, disable, and list repositories.<br><br>These repositories are then utilized by <i>rpm-ostree</i> for layering additional RPM packages on top of the immutable base operating system image. This capability is vital for environments that require specific software or dependencies not included in the default CoreOS image, offering flexibility without compromising the atomic update model of <i>rpm-ostree</i>. The command handles the underlying creation and management of the necessary <i>.repo</i> files.


title: CAVEATS
content:
<i>pkgctl-repo</i> is primarily designed for immutable operating systems like Fedora CoreOS and CentOS Stream CoreOS, which utilize <i>rpm-ostree</i> for package management. Changes made via <i>pkgctl-repo</i> define repositories that <i>rpm-ostree</i> will use for layering. For these changes to take full effect (e.g., after adding new packages from a new repo), an <i>rpm-ostree</i> rebase or apply operation followed by a system reboot is typically required.<br><br>Direct use of <i>dnf</i> commands on the host might not always leverage these configured repositories for base system package operations, as <i>rpm-ostree</i> manages the overall system image atomically.


title: INTEGRATION WITH <I>RPM-OSTREE</I>
content:
The repositories configured with <i>pkgctl-repo</i> are consumed by <i>rpm-ostree</i> when performing operations like <i>rpm-ostree install</i> or <i>rpm-ostree override replace</i>. They enable <i>rpm-ostree</i> to resolve and layer packages from custom sources on top of the base OS image. This process ensures that layered packages are part of the atomic updates, maintaining system consistency and rollback capabilities.


title: PERSISTENCE OF REPOSITORY DEFINITIONS
content:
Unlike temporary DNF configurations, the repository definitions created by <i>pkgctl-repo</i> are persistent across system reboots and updates. They are stored in a manner that <i>rpm-ostree</i> can consistently access them, ensuring that the custom software environment remains stable across OS lifecycle events.


title: HISTORY
content:
<i>pkgctl-repo</i> emerged as a crucial component of the <i>pkgctl</i> utility, developed to streamline the process of managing external RPM repositories within the unique architectural constraints of <i>rpm-ostree</i>-based systems. Before <i>pkgctl</i>, adding custom repositories often involved manual manipulation of <i>.repo</i> files, which could be cumbersome and error-prone in an immutable OS environment. Its development directly addresses the need for a user-friendly and persistent mechanism to integrate custom software sources into CoreOS distributions, facilitating package layering while adhering to the atomic update model.


title: SYNOPSIS
content:
<b><code>pkgdelta</code></b> [<i>options</i>] <i>&lt;old_package_or_file&gt;</i> <i>&lt;new_package_or_file&gt;</i> [<i>&lt;output_delta_file&gt;</i>]<br><br><i><code>&lt;old_package_or_file&gt;</code></i>: Can be an installed package name or the path to an old <code>.deb</code> file.<br><i><code>&lt;new_package_or_file&gt;</code></i>: Can be an installed package name or the path to a new <code>.deb</code> file.<br><i><code>&lt;output_delta_file&gt;</code></i>: Optional. The path to save the generated delta. If omitted, the delta is usually written to standard output.


title: PARAMETERS
content:
<b>-o, --output-file <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path for the output delta file.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output, showing more details during delta generation.<br><br><b>-q, --quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses most output, showing only critical errors or warnings.<br><br><b>-f, --force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces delta generation even if conditions are not optimal (e.g., packages are identical).<br><br><b>--strict</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exits with an error if the generated delta is not smaller than the new package.<br><br><b>--diff-cmd <cmd></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative binary diff utility to use (e.g., bsdiff, xdelta).<br><br>


title: DESCRIPTION
content:
pkgdelta is a command-line utility used to generate a <i>binary delta</i> between two versions of a software package, typically in the .deb format. It creates a small difference file (the delta) that, when applied to the older package, reconstructs the newer package. This mechanism significantly reduces the amount of data that needs to be transferred during package updates, making it highly beneficial for users with limited bandwidth or slow internet connections. pkgdelta can operate on installed packages by name or on specified .deb package files. It leverages sophisticated binary diffing algorithms to achieve high compression ratios for the difference.


title: CAVEATS
content:
<b>Requires both versions:</b> To generate a delta, pkgdelta needs access to both the <i>exact old and new versions</i> of the package.<br><b>Resource intensive:</b> Delta generation can be <i>CPU and I/O intensive</i>, especially for large packages, which might impact system performance during the process.<br><b>Delta size variability:</b> While generally small, the delta file can be substantial if the old and new packages differ drastically (e.g., a major version upgrade with extensive changes).<br><b>Debian/Ubuntu specific:</b> pkgdelta is primarily part of the <code>debdelta</code> suite and is most commonly used within Debian-based Linux distributions.


title: HOW IT WORKS
content:
At its core, pkgdelta uses advanced <i>binary diffing algorithms</i> (like <code>bsdiff</code> or <code>xdelta</code>) to compare the raw binary content of the old and new package files. It identifies common blocks and generates instructions to transform the old file into the new one, resulting in a delta file much smaller than the new package itself. This delta is then used by tools like <code>applydelta</code> to reconstruct the updated package.


title: TYPICAL USE CASE
content:
The primary use case for pkgdelta (or the <code>debdelta</code> system it's part of) is for <i>efficient package updates</i>. Instead of downloading a 50MB new package, a user might only download a 500KB delta file. This is especially valuable in environments with slow internet connections, metered bandwidth, or frequent updates to large packages.


title: HISTORY
content:
pkgdelta is an integral component of the <i>debdelta</i> project, which was initiated to revolutionize how Debian package updates are distributed. Its development aimed at drastically reducing bandwidth consumption for users by replacing full package downloads with small, efficient delta updates. The project has been a significant contributor to network efficiency in Debian-based ecosystems since its inception.


title: PARAMETERS
content:
<b>-u, --update</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Updates the local <b>pkgfile</b> database from the configured repositories.<br><br><b>-s, --search</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Searches for files matching the provided pattern (this is the default action if no other action is specified).<br><br><b>-l, --list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists the contents of specified packages. This option requires package names as arguments instead of file patterns.<br><br><b>-g, --glob</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Interprets the file pattern as a glob expression (e.g., <i>*.conf</i>).<br><br><b>-r, --regex</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Interprets the file pattern as a regular expression.<br><br><b>-i, --ignore-case</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs a case-insensitive search.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output, showing more details about the search process.<br><br><b>-q, --quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses error messages.<br><br><b>-d <path>, --database <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative path for the <b>pkgfile</b> database.<br><br><b>-z <repo>, --repo <repo></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Searches only within files belonging to the specified repository. Can be used multiple times.<br><br><b>-e, --uninstalled</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Also searches for files provided by packages that are not currently installed on the system.<br><br><b>-m <pattern>, --match <pattern></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Further filters results by package name matching the given pattern (glob or regex depending on <i>-g</i> or <i>-r</i>).<br><br><b>-p, --package-name</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only prints the name of the package that owns the file, without the file path.<br><br><b>-c, --color</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces colored output.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message and exits.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays version information and exits.<br><br>


title: DESCRIPTION
content:
<b>pkgfile</b> is a command-line utility used to quickly determine which Arch Linux package provides a specified file or matches a given pattern. It works by querying a local database that contains a listing of all files shipped by packages in your configured repositories. This tool is invaluable for troubleshooting missing commands, identifying the source of configuration files, or simply discovering which package to install to get a particular file. It can search for exact filenames, glob patterns, or regular expressions, and its database can be updated to reflect the latest package changes in the repositories.


title: CAVEATS
content:
<b>pkgfile</b> relies on a local database of package file lists. If this database is not regularly updated using <b>pkgfile -u</b>, search results may be outdated or incomplete, leading to inaccurate information about file ownership. This command is primarily designed for Arch Linux and other Pacman-based distributions; it is not available by default on Debian/Ubuntu or Fedora/RHEL systems, which have their own equivalent utilities (e.g., <b>apt-file</b>, <b>dnf provides</b>). The database can consume significant disk space.


title: DATABASE MANAGEMENT
content:
The <b>pkgfile</b> database must be updated regularly to ensure accurate results. This is done using the command <b>pkgfile -u</b>. It's often recommended to run this command after a system update or new repository synchronization. The database is typically stored in <i>/var/cache/pkgfile/</i>.


title: COMMON USAGE EXAMPLES
content:
- To find which package provides the <i>ls</i> command: <b>pkgfile /usr/bin/ls</b><br>- To find all packages that contain files ending with <i>.so</i>: <b>pkgfile -r '.*\.so$'</b><br>- To list all files within the <i>bash</i> package: <b>pkgfile -l bash</b><br>- To search for files matching a glob pattern, e.g., all <i>.conf</i> files: <b>pkgfile -g '*.conf'</b>


title: HISTORY
content:
<b>pkgfile</b> was developed specifically for the Arch Linux ecosystem to fill a gap in <b>pacman</b>'s functionality: the ability to quickly determine which package provides a given file without having to download or install packages. It became a crucial tool for system administrators and users for troubleshooting and package management. It is often distributed as part of the <i>pacman-contrib</i> package, highlighting its supplementary role to the core <b>pacman</b> system. Its development has focused on efficiency and providing up-to-date file mappings.


title: SYNOPSIS
content:
<b>pkginfo</b> [ -d <i>device</i> ] [ -q ] [ -l | -x ] { -r | <i>pkginst</i> }<br><b>pkginfo</b> [ -i ] [ -d <i>device</i> ] [ -q ] [ -l | -x ] <i>pkginst</i><br><b>pkginfo</b> [ -c <i>category</i> ] [ -a <i>arch</i> ] [ -v <i>version</i> ] [ -q ] [ -l | -x ] [ <i>pkginst</i> ]<br><b>pkginfo</b> [ -p ] [ -q ] [ -l | -x ] <i>pkginst</i>


title: PARAMETERS
content:
<b>-d <i>device</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the device or directory where packages are stored, e.g., a CD-ROM or a download directory. Useful for querying packages on an installation medium.<br><br><b>-q</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Quiet mode. Suppresses the output of all messages except for error messages. This is particularly useful for scripting when only the exit status is needed.<br><br><b>-l</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a long format listing of package information, including more detailed attributes like category, vendor, installation date, and full description.<br><br><b>-x</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays an extracted format listing of package information. This is a concise, colon-separated list of basic package attributes (e.g., abbreviation, full name, architecture, version, category).<br><br><b>-r</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays information about relocatable packages that are installed in a non-default root path. This option must be used with a specified <i>pkginst</i> or the <b>-d</b> option.<br><br><b>-i</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays information about the package on the installation medium (device) rather than an already installed package on the system. Requires a <i>pkginst</i>.<br><br><b>-c <i>category</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filters packages by a specific category, e.g., 'system', 'application', or 'utility'. This allows narrowing down the search to specific types of software.<br><br><b>-a <i>arch</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filters packages by a specific architecture, e.g., 'sparc', 'i386', 'x86_64'. This is useful in multi-architecture environments.<br><br><b>-v <i>version</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filters packages by a specific version string. This helps in locating specific package releases.<br><br><b>-p</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows <i>pkginst</i> to be a partial match, displaying information for all packages whose abbreviation matches the given pattern. Wildcards are often supported.<br><br><b><i>pkginst</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the package instance(s) to query. Can be a specific package abbreviation (e.g., 'SUNWbash'), the keyword 'all' for all installed packages, or '<i>category</i>.all' for all packages within a specific category.<br><br>


title: DESCRIPTION
content:
<br><i>pkginfo</i> is a command-line utility used to display information about installed software packages. It is part of the System V Release 4 (SVR4) package management system, commonly found on Unix-like operating systems such as Solaris, HP-UX, and some older Linux distributions that utilize this packaging standard.<br><br>The command allows users to query the package database for details like package name, architecture, version, category, vendor, description, installation date, and status. It supports various output formats, including a concise "extracted" view and a verbose "long" listing, providing comprehensive details about a package's attributes.<br><br><i>pkginfo</i> is essential for system administrators and users to verify installed software, troubleshoot package issues, or simply gain insights into the system's software inventory.


title: CAVEATS
content:
<i>pkginfo</i> is <b>not</b> a standard command on most modern Linux distributions (e.g., Debian, Ubuntu, Fedora, RHEL, CentOS, Arch Linux). These distributions primarily use different package management systems like <i>dpkg</i>/<i>apt</i> (Debian-based) or <i>rpm</i>/<i>yum</i>/<i>dnf</i> (Red Hat-based).<br><br>It is primarily associated with System V Release 4 (SVR4) package management, historically found on systems like Solaris, HP-UX, and specific older or specialized Linux environments (e.g., SCO OpenServer).<br><br>To use <i>pkginfo</i>, packages must have been installed using the <i>pkgadd</i> utility, which adheres to the SVR4 packaging standard.


title: OUTPUT FORMATS
content:
<i>pkginfo</i> offers various output formats. The <b>long (-l)</b> format provides a comprehensive list of attributes for each package, including detailed descriptions, installation paths, and dependencies. The <b>extracted (-x)</b> format offers a more concise, colon-separated output, useful for scripting or quick overviews. The default output provides basic information like package abbreviation and full name.


title: PACKAGE INSTANCE SPECIFICATION
content:
You can specify packages using their unique <i>abbreviation</i> (e.g., 'SUNWcs'). Using the keyword 'all' retrieves information for all installed packages. You can also query for packages belonging to a specific <i>category</i> (e.g., 'system.all') or use partial matching with the <b>-p</b> option to find packages that match a pattern.


title: HISTORY
content:
The <i>pkginfo</i> command, along with the entire System V Release 4 (SVR4) package management framework (including <i>pkgadd</i>, <i>pkgrm</i>, <i>pkgchk</i>), was developed as part of AT&T's UNIX System V Release 4 in the late 1980s. It provided a standardized approach to software packaging, installation, and management across different SVR4-compliant UNIX systems.<br><br>While widely adopted on systems like Solaris, HP-UX, and SCO OpenServer, its direct usage on mainstream Linux distributions became less common as <i>rpm</i> (Red Hat Package Manager) and <i>dpkg</i> (Debian Package Manager) emerged and became the dominant packaging standards for the open-source Linux ecosystem. However, its design principles influenced subsequent package management systems.


title: SYNOPSIS
content:
pkgmk [-o] [-d device] [-f prototype] [-l limit] [-p pstamp] [-r rootpath] [-v version] [-a arch] [-b base] [-i pkginst] [pkgid]


title: PARAMETERS
content:
<b>-o</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Overwrite existing</i>. Specifies that if a package instance with the same package ID and instance already exists on the output device, it should be overwritten.<br><br><b>-d device</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Output device/directory</i>. Defines the output device or directory where the package instance will be created. Default is <i>/var/spool/pkg</i>.<br><br><b>-f prototype</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Prototype file</i>. Specifies the path to the prototype file which defines the package's contents and structure. This is a mandatory component for building a package.<br><br><b>-l limit</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Size limit</i>. Sets a maximum size (in 512-byte blocks) for the package. If the package exceeds this limit, <b>pkgmk</b> will exit with an error.<br><br><b>-p pstamp</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Package stamp</i>. Assigns a unique stamp to the package, often used for identifying specific builds or versions.<br><br><b>-r rootpath</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Root path</i>. Specifies a base directory to prepend to all relative pathnames found in the prototype file. Useful for creating packages from a staging area.<br><br><b>-v version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Package version</i>. Defines a specific version string for the package, overriding any version specified in the prototype file's <b>pkginfo</b> entry.<br><br><b>-a arch</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Architecture</i>. Defines the architecture string for the package, overriding any architecture specified in the prototype file.<br><br><b>-b base</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Base directory</i>. Specifies a base directory for relocatable package contents, often used with the <i>relocatable</i> package class.<br><br><b>-i pkginst</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Package instance</i>. Specifies a unique instance identifier for the package being created.<br><br><b>pkgid</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Package Identifier</i>. The specific package identifier to build if the prototype file describes multiple packages. If omitted, <b>pkgmk</b> attempts to build the first package found.<br><br>


title: DESCRIPTION
content:
pkgmk is a command-line utility used to create an installable software package from a defined set of files and scripts. It operates according to the <b>System V Release 4 (SVr4)</b> packaging standard. The core input for pkgmk is a <i>prototype file</i>, which acts as a manifest. This file specifies every component of the package: files, directories, symbolic links, devices, and package-specific installation scripts (e.g., preinstall, postinstall, request scripts). <br><br>The command collects the specified files from the source directory, applies attributes like permissions and ownership defined in the prototype, and bundles them into a package instance. This package instance is typically stored in a spool directory (like <i>/var/spool/pkg</i>) and is then ready for installation using the <b>pkgadd</b> command. <br><br>While central to older <b>System V Unix</b> systems like <i>Solaris</i> and <i>HP-UX</i>, pkgmk is less common on modern Linux distributions, which predominantly use <i>RPM</i> or <i>Deb</i> packages. However, understanding pkgmk is crucial for environments maintaining legacy SVr4 package management.


title: CAVEATS
content:
Primarily found and used on <b>System V Release 4 (SVr4)</b> based Unix systems such as <i>Solaris</i>, <i>HP-UX</i>, and <i>AIX</i>. It is not standard on most mainstream Linux distributions, which use <i>RPM</i> or <i>Deb</i> package formats. <br><br>Requires a meticulously prepared <i>prototype file</i>; errors in this file can lead to incorrect or failed package builds. <br><br>Building packages might require appropriate write permissions to the designated output device or directory.


title: THE PROTOTYPE FILE
content:
The <i>prototype file</i> is the blueprint for the package. It defines the type of each entry (file, directory, link, device), its source path, target path within the package, permissions, owner, group, and any associated install scripts. <b>pkgmk</b> parses this file to understand what to include and how to package it.


title: PACKAGE SPOOL
content:
<b>pkgmk</b> typically creates the package instance in a designated spool area (e.g., <i>/var/spool/pkg</i>). This location serves as a repository for pre-built packages, making them readily available for installation by <b>pkgadd</b>.


title: HISTORY
content:
<b>pkgmk</b> is an integral part of the <i>System V Release 4 (SVr4) Package Management System</i>, originally developed by AT&T and Unix System Laboratories (USL). This packaging standard was a significant advancement in software distribution for Unix systems during the late 1980s and early 1990s. <br><br>While SVr4 packaging tools, including <b>pkgmk</b>, remain crucial for systems like <i>Solaris</i>, <i>HP-UX</i>, and <i>AIX</i>, their direct usage on Linux became less prevalent with the rise of the <i>Red Hat Package Manager (RPM)</i> and <i>Debian packages (.deb)</i> which offered different approaches to software management. Despite this, the underlying concepts of package manifests and lifecycle scripts have influenced modern packaging systems.


title: SYNOPSIS
content:
<pre><b>pkgrm</b> [<i>-n</i>] [<i>-a <I>admin</I></i>] [<i>-R <I>root_path</I></i>] [<i><I>pkginst</I>...</i>]</pre><br>Where:<br><i><I>pkginst</I></i> refers to the package instance name (e.g., <i>SUNWcadap</i>). Multiple instances can be specified. If no <i><I>pkginst</I></i> is provided, <b>pkgrm</b> will list all installed packages and prompt for which ones to remove.


title: PARAMETERS
content:
<b><i>-n</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;No execution. Displays what would be removed without actually performing the removal. Useful for testing.<br><br><b><i>-a <I>admin</I></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an administrative file. This file contains parameters that define how <b>pkgrm</b> should behave, such as suppressing prompts or handling conflicts.<br><br><b><i>-R <I>root_path</I></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternate root path. Useful for removing packages from an unmounted system or alternate root environment.<br><br><b><i><I>pkginst</I></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique instance name(s) of the package(s) to be removed. If omitted, an interactive list of installed packages is presented.<br><br>


title: DESCRIPTION
content:
<b>pkgrm</b> is a command-line utility used to remove or uninstall software packages from a system that utilizes the System V Release 4 (SVR4) package management format. It is the counterpart to <b>pkgadd</b> (package add) and manages the process of deleting installed software, including associated files, directories, and configuration settings. When executed, <b>pkgrm</b> can perform pre-removal and post-removal scripts defined within the package, ensuring a clean uninstallation. It updates the system's package database to reflect the removal, making the package no longer visible via <b>pkginfo</b>. This command is crucial for maintaining system integrity and managing installed software on traditional Unix-like operating systems such as Solaris, HP-UX, and older Linux distributions that adhered to SVR4 packaging standards. It often requires superuser privileges to execute successfully.


title: CAVEATS
content:
<b>pkgrm</b> is primarily associated with System V Release 4 (SVR4) package management. It is not commonly used on most modern Linux distributions (e.g., Debian, Ubuntu, Fedora, CentOS), which utilize different packaging systems like APT (Debian/Ubuntu), RPM (Fedora/CentOS), or DNF/YUM. Users on these systems should typically use their respective package managers (e.g., <b>apt remove</b>, <b>yum remove</b>, <b>dnf remove</b>, <b>rpm -e</b>, <b>dpkg -r</b>). Executing <b>pkgrm</b> generally requires superuser (root) privileges.


title: INTERACTIVE MODE
content:
If no <i><I>pkginst</I></i> is specified on the command line, <b>pkgrm</b> will enter an interactive mode. It will list all currently installed packages and prompt the user to select which packages to remove, requiring confirmation for each removal. This mode is useful when you are unsure of the exact package name or want to browse available uninstall options.


title: ADMINISTRATIVE FILES
content:
Administrative files, specified with the <i>-a</i> option, provide a non-interactive way to control <b>pkgrm</b>'s behavior. They can define responses to prompts (e.g., 'yes' or 'no' for confirmations) and control error handling, making them useful for automated script-based package removals.


title: HISTORY
content:
The <b>pkgrm</b> command is an integral part of the System V Release 4 (SVR4) package management system, which was developed by AT&T in the late 1980s and early 1990s. This system was designed to standardize software installation and removal across various Unix platforms. While its influence can be seen in later package management systems, <b>pkgrm</b> itself is now primarily found on traditional Unix-like operating systems such as Oracle Solaris, HP-UX, and older versions of SCO Unixware, rather than mainstream Linux distributions that have adopted their own, more modern packaging formats.


title: SYNOPSIS
content:
<b>pkill</b> [<i>options</i>] <i>pattern</i><br><b>pkill</b> [<i>-signal</i>] [<i>options</i>] <i>pattern</i>


title: PARAMETERS
content:
<b><i>pattern</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An extended regular expression that is matched against the process names or full command lines (if <b>-f</b> is used). This is the primary way to identify processes.<br><br><b><b>-signal</b>, <b>--signal</b> <i>signal</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the signal to send to the matching processes. <i>signal</i> can be a numeric value (e.g., 9 for SIGKILL) or a symbolic name (e.g., KILL, TERM, HUP). The default is SIGTERM.<br><br><b><b>-c</b>, <b>--count</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses normal output; instead, print the number of matching processes. When no processes match, the exit code is 1.<br><br><b><b>-e</b>, <b>--exact</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Select only processes whose name or command line exactly matches the <i>pattern</i>.<br><br><b><b>-f</b>, <b>--full</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The <i>pattern</i> is matched against the full command line, not just the process name.<br><br><b><b>-g</b>, <b>--group</b> <i>group</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Select processes belonging to the specified effective group(s) (IDs or names). Multiple groups can be specified with a comma-separated list.<br><br><b><b>-G</b>, <b>--real-group</b> <i>group</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Select processes belonging to the specified real group(s) (IDs or names). Multiple groups can be specified with a comma-separated list.<br><br><b><b>-l</b>, <b>--list-name</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists the process name of all matching processes instead of killing them. Useful for testing a <i>pattern</i> before execution.<br><br><b><b>-n</b>, <b>--newest</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Select only the newest (most recently started) of the matching processes.<br><br><b><b>-o</b>, <b>--oldest</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Select only the oldest (least recently started) of the matching processes.<br><br><b><b>-P</b>, <b>--parent</b> <i>ppid</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Select processes whose parent process ID is one of the specified <i>ppid</i>s. Multiple parent PIDs can be specified with a comma-separated list.<br><br><b><b>-t</b>, <b>--terminal</b> <i>term</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Select processes attached to the specified terminal(s) (tty, pts/0, etc.). Multiple terminals can be specified with a comma-separated list.<br><br><b><b>-u</b>, <b>--euid</b> <i>user</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Select processes whose effective user ID is one of the specified user(s) (IDs or names). Multiple users can be specified with a comma-separated list.<br><br><b><b>-U</b>, <b>--ruid</b> <i>user</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Select processes whose real user ID is one of the specified user(s) (IDs or names). Multiple users can be specified with a comma-separated list.<br><br><b><b>-v</b>, <b>--inverse</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Invert the match, i.e., select all processes EXCEPT those that match the criteria.<br><br><b><b>-x</b>, <b>--exact</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;This option is often an alias for <b>-e</b>, indicating an exact match against the process name or command line.<br><br>


title: DESCRIPTION
content:
<i>pkill</i> is a command-line utility used to send signals to processes based on their name or other attributes. It is part of the <i>procps-ng</i> suite of tools, which also includes <i>pgrep</i>. While <i>kill</i> requires a Process ID (PID) and <i>killall</i> typically kills all processes matching a name, <i>pkill</i> offers more granular control by allowing users to select processes based on various criteria such as user, group, parent process, terminal, or even the full command line. The default signal sent is <i>SIGTERM</i> (signal 15), which gracefully requests a process to terminate. However, any signal can be specified by name or number. This flexibility makes <i>pkill</i> a powerful tool for system administrators and users alike for managing running processes.


title: CAVEATS
content:
Using <i>pkill</i> without careful consideration of the <i>pattern</i> and options can lead to unintended termination of critical processes. Always verify the processes that would be affected by first using <i><b>pgrep</b></i> with the same options, or by using <i><b>pkill -l</b></i> to list the names of matching processes before sending a signal. The <i><b>-f</b></i> (full command line) option can be powerful but also prone to matching too broadly if the command line arguments vary significantly.


title: REGULAR EXPRESSIONS
content:
The <i>pattern</i> argument supports extended regular expressions (ERE). This allows for complex matching rules, such as <code>^httpd$</code> to match only processes named "httpd" and not "httpd-worker", or <code>(firefox|chrome)</code> to match either Firefox or Chrome processes. Understanding ERE syntax is crucial for effective use of <i>pkill</i>.


title: SIGNALS
content:
Signals are a form of inter-process communication used by the operating system to notify a process of an event or to request it to perform a specific action, such as terminating. Common signals include <i>SIGTERM</i> (15, graceful termination), <i>SIGKILL</i> (9, immediate termination, cannot be caught or ignored), and <i>SIGHUP</i> (1, typically used to reload configuration files).


title: HISTORY
content:
<i>pkill</i> was developed as part of the <i>procps-ng</i> utility suite, which provides essential system monitoring and management tools. It emerged as a more flexible and robust alternative to older commands like <i>killall</i> for situations requiring process selection based on criteria beyond just the process name. Its development was closely tied to that of <i>pgrep</i>, sharing much of its underlying logic for process identification.


title: PARAMETERS
content:
<b><b>help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message, listing available commands and their basic usage.<br><br><b><b>query</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Queries the current authorization rules for a specific action or identity.<br><i>Options:</i><br><b>--action-id</b> <i>ACTION_ID</i>: Specifies the unique identifier of the action to query (e.g., <i>org.freedesktop.policykit.exec</i>).<br><b>--identity</b> <i>IDENTITY</i>: Specifies the identity (e.g., <i>unix-user:root</i>, <i>unix-group:sudo</i>) for which to query the rule.<br><br><b><b>set-rule</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a new authorization rule or modifies an existing one. This command typically requires root privileges.<br><i>Options:</i><br><b>--action-id</b> <i>ACTION_ID</i>: The action ID to apply the rule to.<br><b>--identity</b> <i>IDENTITY</i>: The identity for which the rule applies.<br><b>--rule</b> <i>RULE_TYPE</i>: Defines the authorization behavior (e.g., <i>allow</i>, <i>auth_self</i>, <i>auth_admin</i>, <i>no</i>).<br><b>--priority</b> <i>PRIORITY</i>: An integer determining the rule's precedence (higher values take precedence).<br><b>--scope</b> <i>SCOPE</i>: Defines the scope of the rule (e.g., <i>session</i>, <i>system</i>).<br><br><b><b>remove-rule</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes an existing authorization rule. This command typically requires root privileges.<br><i>Options:</i><br><b>--action-id</b> <i>ACTION_ID</i>: The action ID of the rule to remove.<br><b>--identity</b> <i>IDENTITY</i>: The identity associated with the rule to remove.<br><b>--priority</b> <i>PRIORITY</i>: The priority of the rule to remove (if multiple rules exist for the same action/identity).<br><b>--scope</b> <i>SCOPE</i>: The scope of the rule to remove.<br><br><b><b>reload</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reloads the Polkit authorization policy database from disk, applying any changes made to policy files. This command typically requires root privileges.<br><br><b><b>version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information of the <i>pklocalauthority</i> utility.<br><br>


title: DESCRIPTION
content:
<i>pklocalauthority</i> is a low-level command-line tool for managing the local authorization policy database used by <b>Polkit</b> (formerly PolicyKit). Polkit is an authorization framework that controls system-wide privileges for unprivileged processes interacting with privileged ones. While not typically used by end-users, <i>pklocalauthority</i> is invaluable for system administrators and scripts to programmatically query, set, or remove authorization rules. It interacts directly with Polkit's local authority backend, allowing fine-grained control over how actions are authorized on the system. Operations like setting or removing rules usually require superuser privileges.


title: CAVEATS
content:
Most operations, particularly <i>set-rule</i>, <i>remove-rule</i>, and <i>reload</i>, require superuser privileges. Direct manipulation of Polkit policies can lead to unintended security implications or system instability if not performed with care. It's generally recommended to understand Polkit's rule evaluation logic thoroughly before making changes. For most common use cases, higher-level tools or D-Bus APIs are preferred over direct <i>pklocalauthority</i> usage.


title: AUTHORIZATION RULE TYPES
content:
The <b>--rule</b> option for <b>set-rule</b> accepts several values to define authorization behavior:<br><b>allow</b>: The action is always authorized without authentication.<br><b>auth_self</b>: Authentication is required, and the user performing the action must authenticate themselves.<br><b>auth_admin</b>: Authentication is required, and an administrator must authenticate.<br><b>auth_self_keep</b>: Same as <i>auth_self</i>, but authentication is cached.<br><b>auth_admin_keep</b>: Same as <i>auth_admin</i>, but authentication is cached.<br><b>no</b>: The action is never authorized.


title: IDENTITY FORMAT
content:
Identities are typically specified in the format <i>type:value</i>.<br>Common types include:<br><b>unix-user:</b><i>username</i> (e.g., <i>unix-user:john</i>)<br><b>unix-group:</b><i>groupname</i> (e.g., <i>unix-group:wheel</i>, <i>unix-group:sudo</i>)<br><b>session:</b><i>session_id</i> (refers to a specific login session)


title: RULE PRIORITY AND SCOPE
content:
Rules with a higher numerical <b>--priority</b> take precedence over rules with lower priority. This allows for more specific rules to override general ones. The <b>--scope</b> option defines the context in which the rule applies, such as <i>session</i> (for rules effective only during a user's session) or <i>system</i> (for rules affecting the entire system).


title: HISTORY
content:
<i>pklocalauthority</i> is an integral part of the <b>Polkit</b> project, which began its life as PolicyKit, developed primarily by David Zeuthen. It emerged as a crucial authorization framework to provide a structured way for unprivileged applications to perform privileged operations, becoming a standard component in modern Linux distributions for system-wide privilege management and desktop environments.


title: PARAMETERS
content:
<b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display version information and exit.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message and exit.<br><br>


title: DESCRIPTION
content:
<i>pkttyagent</i> is a Polkit authentication agent designed for text-based environments (TTY/console). It registers itself with the system's D-Bus message bus to handle authorization requests from applications that use Polkit.<br><br>When a program requires administrative privileges or a specific authorization from the user (e.g., installing software, changing system settings, or performing actions requiring root access), and no graphical authentication agent is running, <i>pkttyagent</i> steps in. It provides a simple password prompt in the terminal where the user can enter their credentials to authorize the requested action. This allows Polkit-managed operations to be performed securely in environments without a graphical user interface, such as SSH sessions or virtual consoles.


title: CAVEATS
content:
<b>Caveats and Limitations:</b><br>Requires a D-Bus session to be active for communication.<br>Only prompts on the TTY from which it was launched or the one associated with the process requesting authorization.<br>If a graphical Polkit agent is running (e.g., from a desktop environment), <i>pkttyagent</i> might not be used, as graphical agents typically take precedence.


title: D-BUS INTERACTION
content:
<i>pkttyagent</i> relies heavily on D-Bus for communication. It registers itself as an authentication agent on the system bus. When a D-Bus client requests an action that requires authorization, the <i>polkitd</i> daemon checks if an agent is registered. If <i>pkttyagent</i> is the active agent, it receives the request and displays a password prompt to the user in the terminal.


title: SESSION SCOPE
content:
Typically, <i>pkttyagent</i> is started as part of a user's session (e.g., by a display manager or shell startup script) to handle authorizations within that specific session. It runs in the background, waiting for authorization requests and acting only when needed.


title: HISTORY
content:
Polkit (formerly PolicyKit) was developed by David Zeuthen at Red Hat. <i>pkttyagent</i> is an integral part of the Polkit framework, providing a necessary text-based authentication mechanism. Its development tracks with Polkit's evolution, becoming a standard component for privilege escalation and system policy management in Linux distributions, especially for server and command-line environments where graphical agents are not present. It fills the critical role of allowing privileged operations to be performed securely and with user consent in non-graphical environments.


title: PARAMETERS
content:
<b><i>file.pl</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the Perl 4 library file to be converted. If omitted, <b>pl2pm</b> reads from standard input (<i>STDIN</i>) and writes the converted module to standard output (<i>STDOUT</i>).<br><br>


title: DESCRIPTION
content:
The <i>pl2pm</i> command is a utility designed to assist in the migration of Perl 4 library files (typically with a <i>.pl</i> extension) into Perl 5 modules (with a <i>.pm</i> extension). Prior to Perl 5, code reusability often involved simple <i>require</i> statements that loaded code into the global namespace. Perl 5 introduced a more robust and organized module system, utilizing the <i>package</i> keyword for defining namespaces and the <i>Exporter</i> module for explicitly declaring subroutines or variables that can be used by other scripts.<br><br><i>pl2pm</i> automates the basic steps of this conversion: it wraps the existing Perl 4 code within a <i>package</i> declaration, ensures a true value is returned at the end of the file (a requirement for Perl 5 modules), and can optionally set up basic <i>Exporter</i> functionality. This tool is particularly useful for modernizing legacy Perl codebases, providing a starting point for converting old procedural libraries into well-structured Perl 5 modules. However, it's a best-effort tool and almost always requires manual review and further adjustments to ensure full compatibility and optimal Perl 5 practices.


title: CAVEATS
content:
<i>pl2pm</i> provides a rudimentary conversion and does not handle complex Perl 4 idioms, advanced module concepts, or ensure complete compatibility without manual intervention. It's a starting point, not a full migration solution. Users must review the generated <i>.pm</i> file for correctness, add `use strict; use warnings;` if not automatically included, and implement proper exporting or object-oriented structures as needed. It may not be installed by default on all systems, typically being part of the `perl-doc` or `perl-tools` package within Perl distributions.


title: USAGE WITH OUTPUT REDIRECTION
content:
Since <b>pl2pm</b> often writes its output to standard output (<i>STDOUT</i>) by default, you typically redirect its output to a new <i>.pm</i> file:<br><br><b>pl2pm</b> <i>my_old_script.pl</i> > <i>MyNewModule.pm</i><br><br>This allows you to then inspect and modify <i>MyNewModule.pm</i>. It is crucial to remember that the generated <i>.pm</i> file will almost certainly require manual editing to ensure proper functionality and adhere to modern Perl coding standards.


title: PERL 4 VS. PERL 5 MODULE SYSTEM
content:
In Perl 4, a 'library' was often just a file that could be `require`d, and its subroutines and variables would implicitly be in the global namespace. Perl 5 introduced explicit <i>packages</i> to create distinct namespaces and the <i>Exporter</i> module to explicitly declare which subroutines or variables are made available to users of the module. <i>pl2pm</i> attempts to bridge this by wrapping the code in a <i>package</i> and adding basic <i>Exporter</i> setup, but sophisticated conversions require a deeper understanding of Perl 5 module best practices for proper encapsulation and API design.


title: HISTORY
content:
With the significant evolution from Perl 4 to Perl 5 in the mid-1990s, the way Perl code was organized and reused underwent a major change. Perl 5 introduced true modules, `package` declarations, and the `Exporter` mechanism, offering much cleaner namespaces and better encapsulation than Perl 4's simpler `require` system. <i>pl2pm</i> was developed as part of the Perl distribution to help developers bridge this gap, offering a utility to automate the most straightforward aspects of converting older Perl 4 library scripts into the new Perl 5 module format. Its primary utility was during this transition period, making it a less frequently used but historically significant tool for maintaining backward compatibility and aiding modernization.


title: PARAMETERS
content:
<b><i>&lt;colorscheme_name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The exact name of the color scheme to apply. This name corresponds to the `.colors` or `.colorscheme` file (e.g., 'Breeze Dark', 'Breeze', 'Adwaita'). The available names can typically be found in the Plasma System Settings or in the `~/.local/share/color-schemes/` and system-wide `/usr/share/color-schemes/` directories.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief help message with command usage and available options.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows version information for the `plasma-apply-colorscheme` utility.<br><br>


title: DESCRIPTION
content:
The `plasma-apply-colorscheme` command provides a powerful command-line interface for dynamically changing the color scheme of the KDE Plasma desktop environment. It allows users and scripts to apply a named color scheme to the currently running Plasma session without needing to navigate through graphical settings.<br><br>This utility is particularly useful for scripting, automation, and quick theming adjustments. For instance, it can be integrated into custom scripts that switch themes based on time of day, external conditions, or user preference, offering a flexible way to manage the look and feel of the Plasma desktop.<br><br>When executed, the command instantly updates the colors of windows, widgets, and other Plasma elements to match the specified scheme, providing immediate visual feedback.


title: CAVEATS
content:
<ul><li>This command requires a running KDE Plasma desktop session to function correctly.</li><li>It only affects the current user's active Plasma session.</li><li>The provided color scheme name must exactly match an available scheme, often case-sensitively.</li><li>While the color scheme is applied immediately, the command itself does not provide an option to permanently save the setting for future sessions. However, the Plasma desktop typically saves the last applied scheme automatically upon logout or shutdown.</li></ul>


title: FINDING AVAILABLE COLOR SCHEME NAMES
content:
To find the exact names of color schemes available on your system, you can either:<br>1. Open KDE Plasma System Settings and navigate to <b>Appearance</b> -> <b>Colors</b>. The names listed there are the ones you can use.<br>2. List the contents of the color scheme directories: `ls ~/.local/share/color-schemes/` or `ls /usr/share/color-schemes/`. The file names (without the `.colors` or `.colorscheme` extension) are usually the correct names.


title: SCRIPTING AND AUTOMATION
content:
This command is exceptionally useful in shell scripts. For example, you could create a cron job or a custom shortcut that switches between a light and dark theme based on the time of day, or integrate it into a larger setup script for new Plasma installations to apply a consistent look.


title: HISTORY
content:
The `plasma-apply-colorscheme` command is an integral part of the KDE Plasma desktop environment, evolving with KDE's modularization and the Plasma 5 series. It was developed to provide finer-grained control over desktop settings through the command line, aligning with KDE's philosophy of offering both powerful graphical and command-line configuration options. Its inclusion reflects the growing demand for scripting and automation capabilities within modern desktop environments.


title: SYNOPSIS
content:
<b>plasma-apply-cursortheme</b> [OPTIONS] &lt;theme_name&gt;<br><br>The <i>&lt;theme_name&gt;</i> is a mandatory argument specifying the exact name of the cursor theme to be applied.


title: PARAMETERS
content:
<b><b>-h, --help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information about the command's usage and available options.<br><br><b><b>-v, --version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information of the <i>plasma-apply-cursortheme</i> utility.<br><br>


title: DESCRIPTION
content:
<i>plasma-apply-cursortheme</i> is a utility part of the KDE Plasma desktop environment, specifically from the <b>kde-cli-tools</b> package. Its primary function is to quickly apply a designated cursor theme to the active Plasma session.<br><br>When executed with a valid theme name, it configures the X Window System's cursor theme setting and updates KDE's internal configuration (often via <i>kwriteconfig5</i> or similar mechanisms) to ensure the chosen theme is persistent across sessions and correctly rendered by applications. This command is typically used by scripts or advanced users who wish to automate cursor theme changes without navigating through graphical system settings. It relies on the specified cursor theme being installed and available in standard X cursor theme locations (e.g., <i>/usr/share/icons/</i> or <i>~/.icons/</i>).


title: CAVEATS
content:
<b>Caveats and Limitations:</b><br><i>Requires a running KDE Plasma session:</i> This command requires an active KDE Plasma session for immediate effect and to persist the configuration change.<br><i>Theme availability:</i> The specified <i>theme_name</i> must correspond to an installed and accessible cursor theme on the system. If the theme is not found, the command may fail or revert to a default.<br><i>KDE Plasma specific:</i> This is not a universal Linux command; it is exclusive to systems running the KDE Plasma desktop environment.<br><i>Application restart may be needed:</i> While the command applies the change, some older applications or specific contexts might require a restart of the application or the entire X session to fully adopt the new cursor theme consistently.


title: CURSOR THEME LOCATIONS
content:
Cursor themes are typically stored in <i>/usr/share/icons/</i> for system-wide themes or <i>~/.icons/</i> for user-specific themes. Each theme is represented by a directory containing the actual cursor files (e.g., PNGs or Xcursors) and an <i>index.theme</i> file that describes the theme's properties and mapping.


title: APPLYING CHANGES AND PERSISTENCE
content:
The command applies the change to the current session and writes the configuration to make it persistent across reboots. However, for changes to take full effect across all applications and contexts, especially in long-running applications or those that don't dynamically reload X settings, a restart of the application or the X session might be necessary.


title: HISTORY
content:
<i>plasma-apply-cursortheme</i> emerged as a component of the <b>kde-cli-tools</b> suite, which provides command-line utilities for managing various aspects of the KDE Plasma desktop environment. Its development aligns with the broader KDE project's goal of offering both graphical and command-line interfaces for configuration, allowing for greater automation and scripting capabilities within the Plasma ecosystem. It serves as a simplified frontend to underlying configuration mechanisms that evolved with KDE Plasma 5, replacing or supplementing older methods from KDE 4 and earlier, aiming for a more streamlined user and developer experience.


title: PARAMETERS
content:
<b><I>theme_name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The <b>case-sensitive</b> name of the installed KDE Plasma desktop theme to be applied. For example, 'Breeze' or 'Oxygen'.<br><br>


title: DESCRIPTION
content:
The <b>plasma-apply-desktoptheme</b> command is a utility provided by the KDE Plasma desktop environment designed to programmatically change the active global Plasma desktop theme. It acts as a convenient command-line wrapper for underlying D-Bus calls, specifically interacting with the <i>org.kde.Plasma.Desktop</i> service to instruct the Plasma shell to load and apply a new theme. When invoked with a valid theme name, this command changes the visual appearance of various Plasma components, including the desktop background, panels, widgets, and other core Plasma elements. It is particularly useful for scripting, automation, or users who prefer command-line interaction over graphical configuration tools like System Settings. While it primarily affects the Plasma shell's visual style, it does not typically change separate theme categories such as KWin window decorations, icon themes, or GTK application themes, which are managed independently. For a complete look and feel change, related commands like <i>plasma-apply-lookandfeel</i> might be more appropriate.


title: CAVEATS
content:
This command requires the KDE Plasma desktop environment to be running for it to function correctly, as it relies on the Plasma D-Bus service. The specified theme must be already installed and available on the system. Although theme changes usually take effect immediately for the Plasma shell, some applications or components might require a restart or a full logout/login to fully adopt the new theme's appearance.


title: HISTORY
content:
The <b>plasma-apply-desktoptheme</b> utility is a part of the KDE Plasma 5 series and later, representing an evolution from earlier theme management approaches in KDE 4. Its introduction simplified the command-line application of Plasma themes, leveraging the D-Bus communication framework for robust interaction with the Plasma shell. It reflects KDE's ongoing commitment to providing both graphical and programmatic interfaces for desktop configuration.


title: SEE ALSO
content:
qdbus(1), systemsettings5(1), kcmshell5(1), kwriteconfig5(1), plasma-apply-colorscheme(1), plasma-apply-lookandfeel(1)


title: PARAMETERS
content:
<b><i>&lt;theme_name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique identifier or directory name of the 'Look and Feel' theme to be applied. This name corresponds to the directory where the theme is installed (e.g., 'Breeze', 'Lightly', 'Oxygen').<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a short help message showing usage information and exits.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the application's version information and exits.<br><br>


title: DESCRIPTION
content:
The <i>plasma-apply-lookandfeel</i> command is a command-line utility used to apply a complete 'Look and Feel' theme to the KDE Plasma desktop environment.<br><br>A Plasma Look and Feel theme is a bundled collection of various visual elements, including the Plasma style, application style (for both Qt and GTK applications), color scheme, window decorations, icon set, fonts, cursor theme, splash screen, and desktop layout.<br><br>This command provides a programmatic way to switch between these comprehensive themes, making it useful for scripting, automating desktop setup, or quickly changing the entire visual appearance of a Plasma session without using the graphical settings interface.


title: CAVEATS
content:
<i>Requires an active KDE Plasma desktop session to function correctly.</i><br><i>The specified &lt;theme_name&gt; must exactly match an installed 'Look and Feel' theme. If the theme is not found, the command will fail or revert to a default.</i><br><i>Applying a new theme might override individual user customizations to specific components (e.g., custom icon sets or fonts) if the new theme defines its own for those components.</i><br><i>While most changes are applied immediately, some elements (like the splash screen) might only take full effect after a user logs out and logs back into the Plasma session.</i>


title: THEME LOCATIONS
content:
KDE Plasma 'Look and Feel' themes are typically stored in the following directories:<br><i>- System-wide themes: /usr/share/plasma/look-and-feel/</i><br><i>- User-installed themes: ~/.local/share/plasma/look-and-feel/</i><br>Each theme is usually represented by a subdirectory containing its configuration files and assets.


title: LISTING AVAILABLE THEMES
content:
To list the names of currently installed 'Look and Feel' themes, you can either inspect the directories mentioned above or use the graphical 'System Settings' application by navigating to 'Appearance' -> 'Global Theme'. For command-line users, launching the relevant KCM module with <i>kcmshell5 kcm_lookandfeel</i> can display the available themes.


title: HISTORY
content:
The 'Look and Feel' theming concept, along with the <i>plasma-apply-lookandfeel</i> command, was introduced as a significant feature within the KDE Plasma 5 series. It was designed to simplify and unify the management of various desktop visual elements into cohesive bundles, offering a more streamlined approach to desktop customization compared to the separate configuration of individual components in earlier KDE versions. The command provides a direct, non-GUI method to leverage this unified theming system.


title: PARAMETERS
content:
<b><i>&lt;FILE&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to the image file to be used as wallpaper. This is a mandatory argument.<br><br><b><b>--screen</b> <i>&lt;N&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies the wallpaper to a specific screen, identified by its numerical index (e.g., 0 for the primary screen, 1 for a secondary screen).<br><br><b><b>--activity</b> <i>&lt;UUID&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies the wallpaper to a specific Plasma activity, identified by its unique UUID. Activity UUIDs can be discovered using D-Bus commands like <b>qdbus org.kde.ActivityManager /ActivityManager Activities</b>.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message and exits.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays version information about the command and exits.<br><br>


title: DESCRIPTION
content:
The <b>plasma-apply-wallpaperimage</b> command provides a convenient command-line interface for changing the wallpaper image on a KDE Plasma desktop environment. It allows users to programmatically set a background image for specific screens or Plasma activities. This utility is particularly useful for scripting, automation, or quickly cycling through wallpapers without interacting with the graphical user interface. By leveraging Plasma's internal D-Bus mechanisms, it integrates seamlessly with the desktop, offering precise control over wallpaper settings. It's an essential tool for users looking to customize their Plasma experience through scripts or external applications.


title: CAVEATS
content:
This command is designed exclusively for the KDE Plasma desktop environment and requires a running Plasma session to function correctly.<br>It only supports image files as wallpapers and cannot directly set slideshows, animated wallpapers, or solid colors. For more complex wallpaper types, direct D-Bus calls might be necessary.


title: USAGE EXAMPLES
content:
Here are common ways to use the <b>plasma-apply-wallpaperimage</b> command:<br><br><b>1. Set wallpaper for the current desktop/activity:</b><br><i>plasma-apply-wallpaperimage /home/user/Pictures/my_cool_wallpaper.jpg</i><br><br><b>2. Set wallpaper for a specific screen (e.g., screen 1):</b><br><i>plasma-apply-wallpaperimage --screen 1 /home/user/Pictures/secondary_monitor_bg.png</i><br><br><b>3. Set wallpaper for a specific Plasma activity:</b><br>First, find the activity UUIDs:<br><i>qdbus org.kde.ActivityManager /ActivityManager Activities</i><br>Then, use the obtained UUID:<br><i>plasma-apply-wallpaperimage --activity &lt;YOUR_ACTIVITY_UUID&gt; /home/user/Pictures/work_activity_bg.webp</i>


title: HISTORY
content:
<b>plasma-apply-wallpaperimage</b> is part of the <b>plasma-workspace</b> package, which comprises core components of the KDE Plasma desktop environment. It was introduced to provide a command-line interface for managing certain desktop settings, specifically wallpaper, complementing the graphical configuration modules. This allows for greater automation and integration into shell scripts or custom applications, reflecting KDE's commitment to flexibility and user control over the desktop environment.


title: SYNOPSIS
content:
plasmapkg <B>command</B> [options] [arguments]<br><br>Common commands include:<br><B>install</B> <I>&lt;path_to_package_file_or_id&gt;</I> [--type <I>&lt;type&gt;</I>] [--force] [--global]<br><B>remove</B> <I>&lt;package_id&gt;</I> [--type <I>&lt;type&gt;</I>] [--global]<br><B>update</B> <I>&lt;package_id&gt;</I> [--type <I>&lt;type&gt;</I>] [--force] [--global]<br><B>list</B> [--type <I>&lt;type&gt;</I>] [--global]<br><B>query</B> <I>&lt;package_id&gt;</I> [--type <I>&lt;type&gt;</I>] [--global]


title: PARAMETERS
content:
<b>--type <I>&lt;type&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the type of Plasma package to manage (e.g., `plasmoid`, `wallpaper`, `look-and-feel`, `kwinscript`). This is crucial as `plasmapkg` handles various package types.<br><br><b>--install <I>&lt;path_or_id&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Installs a Plasma package from a local file path or a store ID. This option should be used as a command argument.<br><br><b>--remove <I>&lt;id&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes an installed package by its unique ID. This option should be used as a command argument.<br><br><b>--update <I>&lt;id&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Updates an installed package by its ID. This option should be used as a command argument.<br><br><b>--list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all installed packages or packages of a specific type if `--type` is also provided. This option should be used as a command argument.<br><br><b>--query <I>&lt;id&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays detailed information about a specific package by its ID. This option should be used as a command argument.<br><br><b>--force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the operation, often used to overwrite existing packages during installation or update, or to ignore warnings.<br><br><b>--global</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Installs or manages packages globally (for all users) instead of locally (for the current user). Requires appropriate permissions (e.g., `sudo`).<br><br><b>--non-interactive</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents prompts and confirmation questions, useful for scripting automated tasks.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information of the `plasmapkg` utility.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message with command usage and available options.<br><br>


title: DESCRIPTION
content:
The `plasmapkg` command-line utility is used for managing Plasma packages. These packages can include widgets (plasmoids), themes, scripts, KWin scripts, data engines, wallpaper plugins, and more, which extend the functionality and appearance of the KDE Plasma desktop. It allows users and developers to install new packages from local files or online stores, remove existing ones, update installed packages, list available or installed packages, and query details about specific packages. It acts as a backend tool for Plasma's package management, often utilized by graphical tools like Plasma Discover or for scripting automated installations.


title: CAVEATS
content:
<ul><li><b>Package Types:</b> It's critical to specify the correct <I>--type</I> for most operations, as `plasmapkg` manages different kinds of Plasma components, and operations are type-specific.</li><li><b>Permissions:</b> Using the <I>--global</I> option requires root or sudo privileges, as it installs packages system-wide. Without it, packages are installed in the user's local configuration directory (e.g., <I>~/.local/share/plasma/plasmoids/</I>).</li><li><b>Dependencies:</b> `plasmapkg` does not automatically resolve external software dependencies. If a plasmoid requires a specific library, you must install it separately through your distribution's package manager.</li><li><b>Source:</b> Packages downloaded from stores (like store.kde.org) or discovered locally must be valid Plasma packages. Incorrectly formatted or malicious packages could cause issues.</li></ul>


title: LOCAL VS. GLOBAL INSTALLATION
content:
By default, `plasmapkg` installs packages into the current user's local Plasma data directories (e.g., <I>~/.local/share/plasma/plasmoids</I>). To install packages for all users on the system, the <I>--global</I> option must be used, typically with <B>sudo</B>. This distinction is important for multi-user systems, affecting where the package files are placed and who can access them.


title: PACKAGE IDS
content:
When using the <B>remove</B>, <B>update</B>, or <B>query</B> commands, `plasmapkg` requires a unique package ID. This ID is often derived from the package's name or its unique identifier within the package's metadata (e.g., <I>metadata.desktop</I> file). The <B>list</B> command can help in identifying these IDs for currently installed packages.


title: HISTORY
content:
The `plasmapkg` command evolved from its predecessors, `kpackagetool` (for KDE4) and `kpackagetool5` (for early Plasma 5). As the KDE Plasma desktop matured, the `plasmapkg` name became standard for managing Plasma-specific components, reflecting its direct integration with the Plasma framework. It serves as the primary command-line interface for Plasma's package management capabilities, handling the lifecycle of various Plasma extensions.


title: PARAMETERS
content:
<b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information of the <i>plasmashell</i> executable and exits.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a short help message, including available options, and exits.<br><br><b><b>--replace</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Replaces a currently running instance of <i>plasmashell</i> with a new one. Useful for restarting the shell without logging out.<br><br><b><b>--shut-down</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attempts to gracefully shut down the running <i>plasmashell</i> instance.<br><br><b><b>--test-mode</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts <i>plasmashell</i> in a special test mode, often used by developers for debugging or testing new features. Not for general use.<br><br><b><b>--no-x-errors</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Internal/developer) Suppresses X error messages. Rarely used by end-users.<br><br><b><b>--prefetch</b> <i>&lt;id&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Internal) Used for prefetching resources, typically managed by the system. Not for direct user invocation.<br><br>


title: DESCRIPTION
content:
<i><b>plasmashell</b></i> is the core component of the KDE Plasma desktop environment. It manages the graphical shell, including the desktop, panels, widgets (Plasmoids), and overall user interaction.<br><br>It's responsible for drawing the desktop background, handling window management (in conjunction with KWin), displaying system notifications, and providing access to applications via launchers and menus. It acts as the primary interface for users to interact with the Plasma workspace. <i><b>plasmashell</b></i> is highly customizable, allowing users to modify its appearance and behavior through various settings and add-ons. It runs continuously as long as the Plasma desktop is active, providing the visual and interactive elements of the user session. Its stability and performance are crucial for a smooth user experience in KDE Plasma.


title: CAVEATS
content:
Users typically do not need to run <i><b>plasmashell</b></i> directly; it's automatically launched as part of the KDE Plasma session.<br><br>Running <b>--replace</b> can sometimes lead to temporary glitches if the previous session isn't fully prepared for replacement.<br><br>Killing <i><b>plasmashell</b></i> abruptly (e.g., via <i>killall plasmashell</i>) will terminate the Plasma desktop environment, potentially leaving the user with a blank screen or a basic window manager, requiring a restart of the session or logging out/in.<br><br>The <b>--test-mode</b> and <b>--prefetch</b> options are primarily for development and internal use and generally not recommended for regular users.


title: CONFIGURATION FILES
content:
<i><b>plasmashell</b></i>'s behavior and appearance are largely configured through KConfig files, typically located in <i>~/.config/</i>. Key files include <i>~/.config/plasmashellrc</i> and <i>~/.config/plasma-org.kde.plasma.desktop-appletsrc</i>, which store settings for panels, widgets, desktop layout, and other shell-specific configurations.


title: CUSTOMIZATION
content:
The <i><b>plasmashell</b></i> environment is highly customizable through Plasma widgets (Plasmoids), themes, and desktop settings accessible via KDE's System Settings. Users can add, remove, and configure panels, change themes, manage virtual desktops/activities, and more, directly influencing the shell's presentation and functionality.


title: HISTORY
content:
The concept of a modular desktop shell within KDE evolved significantly over versions. <i><b>plasmashell</b></i>, as a distinct executable, became the core component responsible for the desktop shell functionality with the release of KDE Plasma 5. This marked a key design decision to separate the shell from the window manager (KWin) and other underlying KDE Frameworks, focusing on greater modularity, customizability, and performance for the Plasma desktop environment.


title: SYNOPSIS
content:
<b>platformio</b> [<i>GLOBAL_OPTIONS</i>] <i>COMMAND</i> [<i>COMMAND_OPTIONS</i>] [<i>ARGUMENTS</i>]...


title: PARAMETERS
content:
<b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays PlatformIO version information.<br><br><b><b>--help</b>, <b>-h</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows help message and exits. Can be used globally or for specific subcommands (e.g., <b>platformio run --help</b>).<br><br><b><b>--verbosity</b>, <b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increases verbosity level for command output (can be used multiple times for more details).<br><br><b><b>--disable-color</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables colored output in the terminal.<br><br><b><b>init</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Initializes a new PlatformIO project or updates an existing one, setting up the necessary project structure and configuration files.<br><br><b><b>run</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Builds project firmware and uploads it to the target board. This is one of the most frequently used commands.<br><br><b><b>lib</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manages project and global libraries. This subcommand has its own actions like <b>install</b>, <b>update</b>, <b>list</b>, and <b>search</b>.<br><br><b><b>monitor</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts a serial port monitor to communicate with a connected board, useful for debugging and logging output.<br><br><b><b>board</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manages development boards, allowing listing available boards and viewing their detailed information.<br><br><b><b>home</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts the PlatformIO Home graphical user interface in a web browser, providing an easy way to manage projects, libraries, and boards.<br><br><b><b>update</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Updates PlatformIO core components, installed platforms, and tools to their latest versions.<br><br><b><b>debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts a debugging session for a project on a supported board with a compatible debugger setup.<br><br>


title: DESCRIPTION
content:
PlatformIO is a powerful, cross-platform, and open-source ecosystem designed for professional embedded development and Internet of Things (IoT) applications. It provides a unified command-line interface (CLI) to manage projects, build firmware, upload code to devices, and monitor serial communication. PlatformIO abstracts away the complexities of different toolchains, SDKs, and board-specific configurations, offering a consistent development experience across a vast array of development boards (e.g., ESP32, STM32, Arduino) and frameworks (e.g., Arduino, ESP-IDF, Mbed OS, Zephyr). Its CLI component, accessible via the <b>platformio</b> command, is the backbone for automation, continuous integration, and seamless integration with various IDEs, most notably through its popular VS Code extension. It simplifies the entire embedded software development lifecycle.


title: CAVEATS
content:
PlatformIO requires a Python interpreter to be installed on the system. Initial setup and subsequent operations like installing new platforms or libraries often require an active internet connection to download necessary toolchains and dependencies, which can consume significant disk space. While simplifying development, users still need to understand the underlying embedded concepts and the <b>platformio.ini</b> configuration file for advanced customization.


title: <I>PROJECT CONFIGURATION (<BR>PLATFORMIO.INI)</I>
content:
Every PlatformIO project contains a <b>platformio.ini</b> file in its root directory. This critical configuration file defines project-specific settings such as the target board, development framework, build flags, upload protocols, monitor settings, and library dependencies. It allows for highly customized build environments and is central to PlatformIO's flexibility and reproducibility.


title: <I>CROSS-PLATFORM & CROSS-ARCHITECTURE SUPPORT</I>
content:
One of PlatformIO's core strengths is its ability to provide a consistent development experience across various operating systems (Windows, macOS, Linux) and for diverse microcontroller architectures (ARM, ESP8266/ESP32, AVR, etc.). It manages the complexity of different toolchains, compilers, and upload tools, making it easy to switch between projects and hardware without reconfiguring the entire development environment.


title: HISTORY
content:
PlatformIO was founded by Ivan Kuten around 2014 with the vision to create a universal and accessible development ecosystem for embedded systems. Initially gaining traction among Arduino users, it rapidly expanded its support for a vast array of microcontrollers, development boards, and frameworks. Its modular design and strong emphasis on a command-line interface made it adaptable for automation and continuous integration workflows. Over the years, it has evolved into a comprehensive platform, complemented by powerful IDE integrations (most notably the VS Code extension), becoming a staple tool for both hobbyists and professional embedded developers worldwide.


title: SYNOPSIS
content:
<I>play</I> [<I>options</I>] <I>audiofile</I> [<I>effects</I>]<br><br>Examples:<br><I>play</I> <I>myfile.mp3</I><br><I>play</I> -r 48k <I>podcast.ogg</I> <I>vol</I> 0.5<br><I>play</I> <I>sound.wav</I> <I>speed</I> 1.2 <I>reverb</I>


title: PARAMETERS
content:
<b>-d or --device</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the audio output device to use (e.g., <I>alsa</I>, <I>pulseaudio</I>, or a specific device name).<br><br><b>-q or --quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses all progress and informational output to the console.<br><br><b>-v or --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increases the verbosity level, showing more detailed information about the audio processing.<br><br><b>-r or --rate <I>rate</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the sample rate in Hz for the input or output audio.<br><br><b>-c or --channels <I>count</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the number of audio channels (e.g., 1 for mono, 2 for stereo).<br><br><b>-t or --type <I>type</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the file type of the input audio (e.g., <I>wav</I>, <I>mp3</I>, <I>flac</I>). Useful when the file extension is missing or incorrect.<br><br><b>--no-show-progress</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables the progress bar display during playback.<br><br>


title: DESCRIPTION
content:
The <I>play</I> command is a versatile utility used for playing audio files directly from the command line. It is part of the SoX (Sound eXchange) suite of tools, often referred to as "the Swiss Army knife of sound processing programs." <I>play</I> leverages SoX's powerful audio processing capabilities, allowing users not only to play various audio formats (e.g., WAV, MP3, FLAC, Ogg Vorbis) but also to apply real-time audio effects during playback. This makes it more than just a simple player; it can be used for quick audio checks, testing audio setups, or even for rudimentary sound analysis and manipulation on the fly. Its command-line nature makes it ideal for scripting and integration into automated workflows, as well as for users who prefer a minimalist interface without graphical overhead.


title: CAVEATS
content:
The <I>play</I> command is typically a symbolic link or wrapper for the <B>sox</B> command; thus, <B>sox</B> must be installed on your system. Its functionality heavily relies on the underlying audio system (e.g., ALSA, PulseAudio, OSS). Issues with these audio backends or device configurations can prevent <I>play</I> from functioning correctly. While it supports many formats, some proprietary or less common formats might require additional libraries. Applying complex audio effects in real-time can be CPU-intensive.


title: SUPPORTED AUDIO FORMATS
content:
<I>play</I> supports a vast array of audio file formats, including but not limited to WAV, MP3, FLAC, Ogg Vorbis, AIFF, AU, and raw audio data. The specific formats supported depend on the SoX compilation and installed libraries.


title: REAL-TIME AUDIO EFFECTS
content:
One of <I>play</I>'s powerful features is its ability to apply various audio effects in real-time during playback. These effects include volume adjustment (<B>vol</B>), speed change (<B>speed</B>), trimming (<B>trim</B>), reversing (<B>reverse</B>), normalization (<B>norm</B>), equalization (<B>equalizer</B>), and many more, making it a flexible tool for audio manipulation and analysis.


title: HISTORY
content:
The <I>play</I> command is an integral part of the SoX (Sound eXchange) project, which originated in 1991 by Lance Norskog. SoX was designed to be a cross-platform command-line utility for manipulating various audio file formats. <I>play</I> specifically emerged as a convenient wrapper or direct invocation of SoX with the default output device, simplifying the common task of playing audio files without needing to explicitly specify conversion or output destinations. Over decades, SoX and consequently <I>play</I> have undergone continuous development, adapting to new audio formats, output devices, and incorporating a vast array of audio effects and processing capabilities, solidifying its position as a robust and essential tool in the Linux audio ecosystem.


title: SYNOPSIS
content:
<b>playerctl</b> [<i>OPTIONS</i>] [<i>COMMAND</i>] [<i>ARGUMENTS</i>]<br><br>Examples:<br><b>playerctl</b> play<br><b>playerctl</b> -p spotify next<br><b>playerctl</b> metadata --format '<i>{{artist}} - {{title}}</i>'


title: PARAMETERS
content:
<b>--player=&lt;player&gt;, -p &lt;player&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects a specific media player instance by its name (e.g., 'spotify', 'vlc').<br><br><b>--all-players, -a</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies the specified command to all currently detected and running media players.<br><br><b>--list-all, -l</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists the names of all currently available and MPRIS-compliant media players.<br><br><b>--follow, -s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;For commands like <i>status</i> or <i>metadata</i>, keeps printing updates as changes occur.<br><br><b>--format &lt;format&gt;, -f &lt;format&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a Go-like template string for formatting output from <i>metadata</i> or <i>status</i> commands.<br><br><b>play</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts or resumes playback of the current media. If already playing, it does nothing.<br><br><b>pause</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pauses the playback of the current media. If already paused, it does nothing.<br><br><b>play-pause</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Toggles the playback state between playing and paused.<br><br><b>stop</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Completely stops playback. This may reset the playback position.<br><br><b>next</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skips to the next track or item in the current playlist.<br><br><b>previous</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skips to the previous track or item in the current playlist.<br><br><b>status</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the current playback status (e.g., 'Playing', 'Paused', 'Stopped').<br><br><b>metadata</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints detailed metadata for the current track, such as artist, title, album, and duration.<br><br><b>volume [level]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Gets the current volume level, or sets it if a value (0.0 to 1.0) is provided.<br><br><b>position [seconds]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Gets the current playback position in seconds, or sets it if a value is provided.<br><br><b>loop [status]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Gets the current loop status, or sets it ('None', 'Track', 'Playlist').<br><br><b>shuffle [status]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Gets the current shuffle status, or sets it ('On', 'Off').<br><br>


title: DESCRIPTION
content:
<i>playerctl</i> is a command-line utility for controlling media players that support the Media Player Remote Interfacing Specification (MPRIS) over D-Bus. This makes it a universal tool for managing playback, volume, and track information for most modern Linux media applications like Spotify, VLC, Rhythmbox, and many others. It allows users to pause, play, skip tracks, query metadata, and adjust volume directly from the terminal or via custom keybindings and scripts.<br><br>By abstracting away the specifics of each media player, <i>playerctl</i> provides a consistent interface, making it invaluable for automation, desktop environment integration, and building custom media control solutions. Its reliance on D-Bus ensures seamless communication within the Linux desktop environment, providing a robust and flexible way to interact with your audio and video playback. Whether for simple one-off commands or complex scripting, <i>playerctl</i> empowers users with comprehensive control over their media experience.


title: CAVEATS
content:
<i>playerctl</i> relies entirely on the <I>MPRIS D-Bus interface</I>. If a media player does not implement this standard, or if the D-Bus service is not running correctly, <i>playerctl</i> will not be able to control it. <br><br>Furthermore, <i>playerctl</i> can only control players that are currently running and broadcasting their MPRIS interface. It does not launch players or manage their lifecycle beyond what the MPRIS specification allows. Ensure your player is compatible and active for <i>playerctl</i> to function as expected.


title: SCRIPTING AND AUTOMATION
content:
<i>playerctl</i> is ideal for custom keyboard shortcuts (e.g., assigning media keys) or integrating media control into shell scripts, status bars (like polybar, i3status), or desktop widgets.


title: MPRIS INTEGRATION
content:
The command's functionality is entirely dependent on the media player's MPRIS implementation. While most major players support it, some niche or older players might not.


title: FORMAT STRINGS
content:
The <i>--format</i> option, especially with <i>metadata</i>, allows for powerful customization of output using Go-like template syntax (e.g., <i>{{artist}} - {{title}} ({{album}})</i>), enabling precise data extraction for display or logging.


title: HISTORY
content:
<i>playerctl</i> emerged to address the need for a standardized, command-line interface to control media players on Linux, bridging the gap left by more ad-hoc or player-specific control mechanisms. Leveraging the <I>MPRIS (Media Player Remote Interfacing Specification)</I>, which became a de-facto standard for media player integration into desktop environments, <i>playerctl</i> provides a robust and universal solution. Its development reflects the growing desire for seamless media control in scripting, keyboard shortcuts, and custom desktop widgets, becoming an essential utility for many Linux users and developers seeking consistent media playback management.


title: PARAMETERS
content:
<b><i>&lt;pid&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The process ID of the target process whose loaded dynamic libraries are to be listed. This is a mandatory argument.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief usage message and exits.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the version information of the <b>pldd</b> utility and exits.<br><br>


title: DESCRIPTION
content:
<b>pldd</b> (Print Loaded Dynamic Libraries) is a utility that displays the shared libraries currently loaded by a specified running process. It takes a process ID (PID) as an argument and outputs a list of the dynamic libraries, along with their memory addresses, that the process is actively using.<br><br>This command is particularly useful for debugging, understanding application dependencies, and analyzing which libraries a running application is linked against without the need to stop or restart the application. It provides a quick snapshot of a process's live library landscape, making it invaluable for diagnosing linking issues or resource consumption.


title: CAVEATS
content:
<ul><li><b>Permissions:</b> To use <b>pldd</b>, you must have sufficient permissions to read the <code>/proc/&lt;pid&gt;/maps</code> file for the target process. This typically means you must be the owner of the process or have root privileges.</li><li><b>No Dependency Tree:</b> Unlike <b>ldd</b>, <b>pldd</b> does not show the dependency tree of libraries (i.e., which libraries are loaded by other libraries). It only lists the libraries directly mapped by the process.</li></ul>


title: HOW IT WORKS
content:
<b>pldd</b> functions by parsing the <code>/proc/&lt;pid&gt;/maps</code> pseudo-file for the specified process ID. This file contains a comprehensive list of memory regions mapped by the process, including executable code, data, stack, heap, and shared libraries. <b>pldd</b> specifically extracts entries that correspond to shared object files (typically ending in <code>.so</code>) and, in some cases, the executable itself, presenting them in a user-friendly format, showing the library's path and its loaded memory address within the process's virtual address space.


title: HISTORY
content:
<b>pldd</b> is typically distributed as part of the <b>procps-ng</b> suite of utilities, which provides a wide range of tools for monitoring and interacting with processes on Linux systems. Its development parallels the evolution of the <code>/proc</code> filesystem as a rich source of process information. While not as historically prominent as commands like <b>ps</b> or <b>top</b>, <b>pldd</b> emerged as a specialized and convenient way to inspect live process library usage without resorting to manual parsing of <code>/proc</code> files or using more general-purpose tools like <b>lsof</b>.


title: PARAMETERS
content:
<b>install <version></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Installs a specific Perl <i>version</i> (requires the `perl-build` plugin).<br><br><b>versions</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all Perl versions installed by `plenv`, indicating the currently active one.<br><br><b>global <version></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the global default Perl <i>version</i> across all shell sessions.<br><br><b>local <version></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the Perl <i>version</i> for the current directory and its subdirectories by creating a `.perl-version` file.<br><br><b>shell <version></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the Perl <i>version</i> for the current shell session only. This setting takes precedence over local and global settings.<br><br><b>rehash</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Rebuilds the `plenv` shim executables. This command is essential after installing new Perl versions or any Perl modules via `cpan` or `cpanm`.<br><br><b>uninstall <version></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uninstalls a specific Perl <i>version</i> from your `plenv` environment.<br><br><b>exec <command> [args]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes a <i>command</i> using the currently selected Perl environment, bypassing shims.<br><br><b>which <command></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the full path to the executable that the `plenv` shim will invoke for the given <i>command</i>.<br><br><b>sh-init</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the necessary shell initialization script for `plenv`. This output should be `eval`uated in your shell's startup file (e.g., `~/.bashrc`).<br><br><b>sh-update</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Updates the `plenv` installation itself to the latest version available in its Git repository.<br><br>


title: DESCRIPTION
content:
<i>plenv</i> is a lightweight command-line tool designed to simplify the management of multiple Perl versions on a single system. Inspired by `rbenv`, it provides a convenient way for developers to switch between different Perl interpreters for various projects without conflicts. Instead of modifying the system's Perl installation, `plenv` works by inserting a directory of "shims" at the front of your <b>PATH</b>. When you run a command like `perl` or `cpan`, your shell finds the `plenv` shim first, which then delegates the command to the correct Perl version based on your project's configuration (via `.perl-version` files) or global settings. This approach ensures that different projects can use their specific Perl versions and associated modules, providing isolation and reproducibility for development environments. It's particularly useful for testing applications against multiple Perl releases or managing dependencies for various legacy and modern projects.


title: CAVEATS
content:
To enable `plenv` functionality, you must initialize it in your shell by adding `eval "$(plenv init -)"` to your shell's configuration file (e.g., `~/.bashrc` or `~/.zshrc`). After installing new Perl versions or Perl modules (e.g., with `cpan` or `cpanm`), you <b>must</b> run `plenv rehash` to update the shim executables; otherwise, newly installed commands or modules may not be found. `plenv` manages user-specific Perl installations and does not interfere with, or manage, the system's pre-installed Perl.


title: HOW `PLENV` WORKS WITH SHIMS
content:
<i>plenv</i> operates by placing "shim" executables (small scripts) in `~/.plenv/shims` and ensuring this directory is at the front of your <b>PATH</b> environment variable. When you type a command like `perl` or `cpan`, your shell finds the `plenv` shim first. This shim then consults your `plenv` configuration (global, local, or shell settings) to determine which specific Perl version to use, and then transparently delegates the command to the actual Perl binary located in the corresponding `~/.plenv/versions/<version>/bin` directory. This transparent delegation means you don't need to manually manage your <b>PATH</b> for each Perl version you use.


title: THE `PERL-BUILD` PLUGIN
content:
While `plenv` provides the framework for managing Perl versions, the actual process of compiling and installing Perl from source code is handled by a separate, external plugin called `perl-build`. This plugin needs to be installed separately (typically by cloning its repository into `~/.plenv/plugins/`) for the `plenv install` command to function correctly. `perl-build` offers various options for customizing the Perl build process, such as configuring installation paths or enabling specific features.


title: HISTORY
content:
<i>plenv</i> was developed as an open-source project, largely inspired by the successful `rbenv` tool for Ruby version management. It emerged to address the need for a similar lightweight, shim-based approach to managing multiple Perl installations, offering an alternative to more comprehensive and potentially heavier tools like `perlbrew`. Its development reflects a broader trend in developer tooling towards isolated, project-specific environments for language runtimes, making it easier to manage dependencies and test against various Perl versions.


title: PARAMETERS
content:
<b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the <I>plesk</I> command or a specific subcommand.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the installed Plesk version.<br><br><b><I>subcommand</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The specific action to perform. Examples include <I>domain</I>, <I>customer</I>, <I>db</I>, <I>service</I>, <I>installer</I>, <I>repair</I>, <I>bin</I>, <I>ext</I>, etc.<br>Each subcommand has its own set of unique options and arguments.<br><br>


title: DESCRIPTION
content:
The <I>plesk</I> command is the main entry point for managing Plesk Panel installations from the command line.<br>It provides a robust set of subcommands and options to automate and script various administrative tasks, including domain creation, customer management, database operations, service control, and system updates.<br>It's essential for administrators who prefer shell access or need to perform bulk operations and integrate Plesk management into existing automation workflows.<br>It interacts directly with the Plesk internal API and database, offering a powerful alternative to the web-based GUI for advanced management.


title: CAVEATS
content:
Most operations executed via the <I>plesk</I> command require root or <I>sudo</I> privileges.<br>Incorrect usage, especially with powerful subcommands like <I>db</I> or <I>repair</I>, can lead to data loss or service disruption.<br>The command is only available on servers with a Plesk Panel installation.<br>Syntax and available subcommands may vary slightly between different Plesk versions.


title: AUTOMATION AND SCRIPTING
content:
The <I>plesk</I> command is extensively used for automating administrative tasks, such as provisioning new domains, managing customer accounts, migrating data, and integrating Plesk functionalities into custom scripts and external systems.


title: OUTPUT FORMATS
content:
Many <I>plesk</I> subcommands support various output formats, including XML, JSON, and CSV, which facilitates parsing and processing command output in scripts for automated workflows and data analysis.


title: HISTORY
content:
Plesk Panel has been a prominent web hosting control panel since the early 2000s, evolving from its roots as Confixx.<br>The command-line utility has developed in parallel with the graphical user interface, providing administrators with a powerful tool for server management, automation, and scripting.<br>Its modular design allows for a flexible structure, enabling new functionalities to be seamlessly integrated as subcommands, reflecting the panel's expanding capabilities.


title: SYNOPSIS
content:
<b>plipconfig</b> [<i>interface</i>]<br><b>plipconfig</b> [<i>interface</i>] [<b>irq</b> <i>irq</i>] [<b>base</b> <i>address</i>] [<b>full</b>] [<b>fast</b>] [<b>nibble</b>] [<b>trigger</b>] [<b>auto</b>] [<b>mode</b> <i>mode</i>] [<b>noprobe</b>]<br><b>plipconfig</b> <b>-V</b>


title: PARAMETERS
content:
<b><i>interface</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the PLIP network device to configure (e.g., <i>plip0</i>, <i>plip1</i>).<br><br><b><b>irq</b> <i>irq</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the Interrupt Request (IRQ) line used by the parallel port. Common IRQs are 7 and 5.<br><br><b><b>base</b> <i>address</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the I/O base address of the parallel port hardware (e.g., <i>0x378</i>, <i>0x278</i>, <i>0x3BC</i>).<br><br><b><b>full</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables full-duplex operation for bidirectional data transfer.<br><br><b><b>fast</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Activates the fast transfer mode, often using EPP/ECP (Enhanced Parallel Port/Extended Capabilities Port) if supported by the hardware and driver.<br><br><b><b>nibble</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Configures the device to use nibble mode, a slower 4-bit data transfer method.<br><br><b><b>trigger</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the parallel port to trigger mode, using the strobe line for data transfer control.<br><br><b><b>auto</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows the driver to automatically negotiate the best transfer mode.<br><br><b><b>mode</b> <i>mode</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a specific PLIP operating mode (0-3), with mode 0 typically being the fastest and mode 3 the slowest.<br><br><b><b>noprobe</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents the command from probing for the parallel port hardware, useful if the hardware is known to exist but probing causes issues.<br><br><b><b>-V</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information for the <b>plipconfig</b> utility.<br><br>


title: DESCRIPTION
content:
The <b>plipconfig</b> command is a specialized Linux utility used for configuring parameters of the Parallel Line Internet Protocol (PLIP) network devices. PLIP is an older, hardware-based networking protocol that allows two computers to communicate directly over their parallel (printer) ports using a special null-modem cable. While largely superseded by modern networking technologies like Ethernet, USB, and Wi-Fi, <b>plipconfig</b> provided the means to set crucial operational parameters for these devices, such as the I/O base address of the parallel port, its interrupt request (IRQ) line, and various data transfer modes (e.g., full-duplex, fast, nibble). It was essential for establishing and troubleshooting these direct parallel port connections in early Linux environments. Today, its usage is primarily historical or for very specific legacy systems.


title: CAVEATS
content:
The <b>plipconfig</b> command and PLIP networking are largely obsolete in modern computing environments. Parallel ports are rarely found on new hardware, and more robust and faster networking options are universally available. Use of PLIP requires specific parallel port null-modem cables and kernel modules (like <i>parport_pc</i> and <i>plip</i>) to be loaded and configured. Modern Linux distributions may not include PLIP support by default in their kernels, or the necessary utilities might be absent. It offers no security features inherent in modern network protocols.


title: PLIP PROTOCOL OVERVIEW
content:
The Parallel Line Internet Protocol (PLIP) was a basic networking protocol that reused the existing parallel printer port hardware for network communication. It operated by bit-banging data over the parallel port's data and control lines, using a specialized 'null-modem' parallel cable to cross-connect the necessary pins between two computers. Due to the nature of parallel port hardware, PLIP connections were inherently slow, typically achieving speeds in the range of 10-20 KB/s, significantly less than early Ethernet (10 Mb/s).


title: HISTORY
content:
The PLIP protocol and consequently the <b>plipconfig</b> utility emerged in the early days of Linux (and other Unix-like systems) as a simple and inexpensive way to network two computers directly, particularly in environments without Ethernet hardware. It was commonly used for file transfers or playing early network games between two machines. Its importance waned rapidly with the widespread adoption and cost reduction of Ethernet cards in the late 1990s and early 2000s, followed by USB and wireless technologies. Today, <b>plipconfig</b> remains primarily as a historical artifact or for maintaining very old, specialized systems.


title: PARAMETERS
content:
<b><b>-b</b>, <b>--basename</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Search only the base name of files, ignoring the directory path.<br><br><b><b>-c</b>, <b>--count</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instead of printing filenames, print only the total number of matches found.<br><br><b><b>-d</b> DATABASE, <b>--database</b>=DATABASE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a custom database file to search instead of the default system-wide database.<br><br><b><b>-i</b>, <b>--ignore-case</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform a case-insensitive search, matching both uppercase and lowercase characters.<br><br><b><b>-l</b> LIMIT, <b>--limit</b>=LIMIT</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limit the number of results to display to the specified numeric limit.<br><br><b><b>-r</b>, <b>--regex</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Interpret the provided PATTERN as a regular expression for more flexible matching.<br><br><b><b>-w</b>, <b>--wholename</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Match the entire path (this is the default behavior), not just the basename.<br><br><b><b>-0</b>, <b>--null</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print entries separated by a NUL character instead of a newline, useful for scripting.<br><br><b><b>-q</b>, <b>--quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not report errors about database problems or other minor issues.<br><br><b><b>-V</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display version information about <i>plocate</i> and exit.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message summarizing command usage and options, then exit.<br><br>


title: DESCRIPTION
content:
<i>plocate</i> is a significantly faster alternative to the traditional <i>locate</i> command, designed for quickly finding files by name on a Linux system. It achieves its speed by querying a pre-built database of filenames, typically generated by the <i>updatedb</i> command. Unlike <i>find</i>, which scans the filesystem in real-time, <i>plocate</i>'s lookup is almost instantaneous because it simply reads from an indexed file.<br><br>This makes it ideal for systems with vast numbers of files where real-time searches would be prohibitively slow. It's often used as a drop-in replacement for <i>mlocate</i>, offering superior performance, especially with very large databases, due to its efficient database handling and parallel processing capabilities.


title: CAVEATS
content:
The primary limitation of <i>plocate</i>, like other <i>locate</i> implementations, is that its database is not updated in real-time. Files created, deleted, or renamed since the last <i>updatedb</i> run will not be accurately reflected in search results.<br><br>The accuracy of results depends entirely on the frequency of database updates. If <i>updatedb</i> is not run regularly, search results can become stale.<br><br><i>plocate</i> respects filesystem permissions recorded in the database; it will only show files that the user running <i>plocate</i> would ordinarily have access to view, based on the permissions at the time the database was built.


title: DATABASE UPDATES
content:
<i>plocate</i> relies on a database generated by the <i>updatedb</i> command, which is typically run daily via a cron job. To ensure the most up-to-date results, ensure your system is configured to run <i>updatedb</i> regularly.<br><br>Example: <code>sudo updatedb</code>


title: PERFORMANCE ADVANTAGE
content:
<i>plocate</i> achieves its superior speed by memory-mapping the database file, allowing for very fast disk I/O. It also employs highly optimized search algorithms and can utilize multiple CPU cores for parallel processing, making it exceptionally efficient for searching through millions of filenames.


title: HISTORY
content:
<i>plocate</i> was developed as a modern, high-performance alternative to existing <i>locate</i> implementations, notably <i>mlocate</i>. Written in Rust, it leverages memory-mapping and highly optimized search algorithms to deliver significantly faster results, especially on systems with very large <i>locate</i> databases.<br><br>Its development aimed to provide a drop-in replacement that could handle gigabyte-sized databases with near-instantaneous query times, addressing the performance bottlenecks of older tools.


title: SYNOPSIS
content:
<b>plot</b> [<I>OPTIONS</I>] [<I>FILE</I>...]<br><I>Reads plotting commands from FILEs (or standard input) and generates graphical output.</I>


title: PARAMETERS
content:
<b>-T <I>device</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the plotting device or output format (e.g., '<I>x</I>' for X Window, '<I>ps</I>' for PostScript, '<I>dumb</I>' for ASCII).<br><br><b>-o <I>file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes the generated graphical output to the specified <I>file</I> instead of standard output.<br><br><b>-P</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sends the generated graphical output directly to the default printer.<br><br><b>-C</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables color rendering for devices that support it, rather than monochrome output.<br><br><b>--list_devices</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints a comprehensive list of all supported output devices and their descriptions, then exits.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief usage message and a list of common options, then exits.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the version information for the `<b>plot</b>` utility and exits.<br><br>


title: DESCRIPTION
content:
The `<b>plot</b>` command is a classic utility from the `plotutils` package, designed for generating graphical output from text-based plotting instructions. It acts as a filter, reading a specific, line-oriented plotting language from standard input (or specified files) and translating it into a graphical representation. This output can be directed to various devices or file formats, ranging from simple ASCII art (via the `dumbplot` device) to PostScript, HP-GL, or interactive X Window System displays. <br><br>Historically, `<b>plot</b>` served as a universal interface to diverse plotting hardware. While it doesn't offer the advanced data analysis or visualization features of modern graphing tools like <I>Gnuplot</I>, it remains valuable for simple, programmatic drawing, particularly in shell scripting where its input format can be easily generated or processed.


title: CAVEATS
content:
The `<b>plot</b>` command, typically part of the `plotutils` package, might not be universally installed by default on all Linux distributions. Its input format uses a specific, simple plotting language, which is distinct from and less expressive than those used by modern graphing tools like <I>Gnuplot</I> or programming libraries like <I>Matplotlib</I>. Output capabilities and appearance heavily depend on the selected device and the availability of appropriate rendering backends.


title: INPUT PLOTTING LANGUAGE
content:
The `<b>plot</b>` command interprets a stream of single-character commands, often followed by integer or floating-point arguments. Common commands include: <br><i>'m x y'</i> (move pen to x,y), <br><i>'d x y'</i> (draw line to x,y), <br><i>'c x y r'</i> (draw circle centered at x,y with radius r), <br><i>'s'</i> (set pen size), <br><i>'e'</i> (end of plot). <br>This minimalistic language facilitates drawing basic geometric shapes and figures programmatically.


title: TYPICAL USAGE SCENARIOS
content:
A frequent use case for `<b>plot</b>` involves piping the output of another command or a shell script directly to it. For example, a script might generate a series of `<b>plot</b>` commands based on some data, and then this output is piped to `<b>plot</b> -Tps > output.ps` to create a PostScript file, or to `<b>plot</b> -Tx` to display the graphics interactively in an X Window. This makes it a useful tool for integrating simple graphical output into automated workflows.


title: HISTORY
content:
The `<b>plot</b>` command and the broader `plotutils` suite trace their origins back to early Unix systems, representing some of the first efforts to provide programmatic graphical output from the command line. They were instrumental in interfacing with various physical plotting devices prevalent in scientific and engineering environments. While contemporary graphics software offers far greater sophistication, `plotutils` persists as a testament to the Unix philosophy of small, specialized tools and remains useful for tasks amenable to its particular plotting language.


title: PARAMETERS
content:
<b>--new-window</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Opens a new empty window.<br><br><b>--new-document</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a new empty document in a new window.<br><br><b>--print</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the specified file(s).<br><br><b>--encoding=<I>ENCODING</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the character encoding to use when opening files specified on the command line.<br><br><b>-s, --select=<I>LINE</I>:<I>COLUMN</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects a range of text starting at the specified line and column. Useful for scripting.<br><br><b>--list-encodings</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a list of all supported character encodings.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the Pluma version information and exits.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief help message with common command-line options.<br><br>


title: DESCRIPTION
content:
<b>Pluma</b> is the official text editor for the <I>MATE</I> desktop environment, serving as a modern, easy-to-use graphical editor for general purpose text editing. It is a direct fork of the <I>gedit</I> editor from the <I>GNOME 2</I> codebase, maintaining a similar interface and feature set that emphasizes simplicity and user-friendliness while offering powerful capabilities. <br><br>Designed primarily for plain text files, <b>Pluma</b> supports syntax highlighting for various programming languages, making it suitable for developers and programmers. Its tabbed interface allows for managing multiple documents efficiently within a single window. Key features include support for international character encodings, a flexible plugin system to extend functionality (e.g., spell checking, file browser pane, snippets), printing capabilities, and drag-and-drop support. It integrates seamlessly with the <I>MATE</I> desktop, providing a fast and reliable solution for editing notes, configuration files, source code, and more.


title: CAVEATS
content:
While <b>Pluma</b> is excellent for general-purpose text editing, it is not designed as a full-fledged IDE or for handling extremely large files (gigabytes). For very large files, specialized tools or command-line editors might offer better performance.<br><br>Its functionality is heavily integrated with the <I>MATE</I> desktop environment, meaning some features or integrations might not be fully functional or aesthetically consistent in other desktop environments.


title: PLUGIN SYSTEM
content:
<b>Pluma</b> features a robust plugin system that allows users to extend its functionality. This includes plugins for features like a file browser sidebar, snippets, document statistics, spell checking, and more. Plugins can be enabled or disabled via the 'Edit -> Preferences -> Plugins' menu within the editor.


title: SYNTAX HIGHLIGHTING
content:
One of <b>Pluma's</b> core features is its extensive syntax highlighting support. It automatically detects and highlights syntax for a wide array of programming languages and markup formats, significantly improving readability for code and configuration files. Users can also manually set the highlighting mode.


title: HISTORY
content:
<b>Pluma</b> emerged from the <I>GNOME 2</I> desktop environment's text editor, <I>gedit</I>. When <I>GNOME 3</I> was released with its new <I>GNOME Shell</I> interface, a group of users and developers decided to fork the <I>GNOME 2</I> codebase to create the <I>MATE</I> desktop environment, aiming to preserve the traditional desktop paradigm. As part of this effort, <I>gedit</I> was forked and renamed to <b>Pluma</b> to serve as the default text editor for <I>MATE</I>. <br><br>Since its inception, <b>Pluma</b> has continued to be actively developed, maintaining compatibility with modern Linux systems while retaining the familiar interface and feature set of its <I>gedit</I> predecessor, ensuring a stable and user-friendly experience for <I>MATE</I> users.


title: PARAMETERS
content:
<b><i>&lt;action&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the power management event that triggered the action:<br><ul><li><b>suspend</b>: System is suspending to RAM or resuming from it.</li><li><b>hibernate</b>: System is hibernating to disk or resuming from it.</li><li><b>resume</b>: Specific for actions taken after resuming from suspend.</li><li><b>thaw</b>: Specific for actions taken after resuming from hibernate.</li><li><b>reboot</b>: Indicates a system reboot event.</li><li><b>force-suspend</b>: Internal variant for forcing suspend.</li><li><b>force-hibernate</b>: Internal variant for forcing hibernate.</li><li><b>force-resume</b>: Internal variant for forcing resume.</li><li><b>force-thaw</b>: Internal variant for forcing thaw.</li><li><b>suspend-hybrid</b>: Indicates a hybrid suspend (suspend-to-RAM and disk).</li></ul><br><br><b><i>&lt;hook_type&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies when the scripts are executed relative to the action:<br><ul><li><b>pre</b>: Run scripts <i>before</i> the system enters the sleep state.</li><li><b>post</b>: Run scripts <i>after</i> the system resumes from the sleep state.</li><li><b>true</b>: Internal signal indicating the preceding sleep action was successful.</li><li><b>false</b>: Internal signal indicating the preceding sleep action failed.</li></ul><br><br>


title: DESCRIPTION
content:
<b>pm-action</b> is a foundational utility script within the <b>pm-utils</b> package, designed to facilitate custom script execution during system power state transitions. It serves as a hook mechanism, primarily invoked by higher-level power management commands such as <b>pm-suspend</b> and <b>pm-hibernate</b>.<br><br>Its core function is to run user-defined scripts located in directories like <i>/etc/pm/sleep.d/</i> and <i>/usr/lib/pm-utils/sleep.d/</i>. These scripts are executed either <i>before</i> the system enters a low-power state (like suspend or hibernate) or <i>after</i> it resumes. This capability allows system administrators to automate critical tasks, such as unmounting network drives, synchronizing data, or adjusting hardware settings prior to sleep, and re-establishing connections or reloading services upon waking.<br><br>While still present in many Linux environments, <b>pm-action</b> and the broader <b>pm-utils</b> framework have largely been superseded by <b>systemd</b>'s integrated power management features in modern distributions (e.g., <b>systemctl suspend</b>, <b>systemctl hibernate</b>).


title: CAVEATS
content:
<b>pm-action</b> is typically called by other <b>pm-utils</b> commands and is not usually invoked directly by users. In modern Linux distributions, power management is primarily handled by <b>systemd</b>, making <b>pm-action</b> less relevant for new configurations. Custom scripts must be executable and placed in the designated sleep directories (<i>/etc/pm/sleep.d/</i> or <i>/usr/lib/pm-utils/sleep.d/</i>).


title: SCRIPT EXECUTION ORDER
content:
Scripts within the <i>/etc/pm/sleep.d/</i> and <i>/usr/lib/pm-utils/sleep.d/</i> directories are executed in lexical (alphanumeric) order. Each script receives the <i>&lt;action&gt;</i> and <i>&lt;hook_type&gt;</i> as command-line arguments, allowing for conditional logic within the scripts.


title: IMPACT OF SCRIPT EXIT STATUS
content:
For 'pre' hooks, if any script exits with a non-zero status, <b>pm-action</b> may abort the suspend or hibernate operation, preventing the system from entering the low-power state. This provides a mechanism for scripts to signal critical failures that should halt the sleep process.


title: HISTORY
content:
<b>pm-action</b> is a component of the <b>pm-utils</b> collection, which emerged as a common framework for managing power states (suspend-to-RAM, suspend-to-disk) on Linux systems. It provided a standardized way for system administrators to integrate custom scripts into the suspend/resume process before <b>systemd</b> became the dominant init system. While its direct usage has declined with <b>systemd</b>'s widespread adoption, it remains available on systems where <b>pm-utils</b> is installed, often supporting legacy configurations or environments not utilizing <b>systemd</b> for power management.


title: PARAMETERS
content:
<b>suspend</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Checks if suspend-to-RAM (system sleep to memory) is supported.<br><br><b>hibernate</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Checks if suspend-to-disk (hibernation) is supported.<br><br><b>hybrid-sleep</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Checks if hybrid sleep (suspend to RAM, then hibernate, then power off) is supported.<br><br><b>suspend-hybrid</b><br>&nbsp;&nbsp;&nbsp;&nbsp;An alias for <I>hybrid-sleep</I>.<br><br>


title: DESCRIPTION
content:
<i>pm-is-supported</i> is a utility designed to determine if specific power management operations, such as system suspend (to RAM), system hibernate (to disk), or hybrid sleep, are supported by the current Linux system. It typically verifies kernel support for these features by examining interfaces like <I>/sys/power/state</I> and other ACPI-related kernel files.<br><br>The command returns an exit status of <b>0</b> if the requested operation is supported, and a non-zero status if it is not. This makes it particularly useful for scripting power management actions reliably, allowing scripts to adapt to the system's capabilities and prevent attempting unsupported power states that could lead to errors or instability.


title: CAVEATS
content:
This command primarily checks kernel-level and ACPI support. It might not account for all factors, such as specific hardware quirks, driver issues, or ongoing processes that could prevent successful power state transitions.<br><br>On modern Linux distributions, its functionality is often provided by <I>systemd</I>, and <I>systemctl</I> commands (e.g., <I>systemctl suspend</I>) are generally preferred for managing power states. <I>pm-is-supported</I> often exists as a compatibility layer.


title: EXIT STATUS
content:
The command communicates support primarily through its exit status:<br><b>0</b>: The requested power management action is supported.<br><b>1</b>: The requested power management action is <b>not</b> supported.<br><b>2</b>: An invalid argument or action was provided.<br><b>3</b>: An internal error occurred.


title: HOW IT DETERMINES SUPPORT
content:
The command typically checks the contents of <I>/sys/power/state</I> (for available sleep states like <i>freeze</i>, <i>mem</i>, <i>disk</i>) and <I>/sys/power/disk</I> (for hibernation configuration). It may also examine kernel command line parameters and other system capabilities to determine support.


title: HISTORY
content:
The <I>pm-is-supported</I> command originated as part of the <I>pm-utils</I> package, a collection of utilities for power management on Linux systems. It provided a straightforward way for scripts and users to query hardware and kernel support for various suspend and hibernate states.<br><br>With the widespread adoption of <I>systemd</I> as the primary init system, much of <I>pm-utils</I>' functionality, including power management, has been absorbed and re-implemented within <I>systemd</I>. <I>pm-is-supported</I> now often exists as a compatibility symlink or script that leverages <I>systemd-sleep</I> to perform its checks, ensuring backward compatibility for older scripts that rely on its presence and behavior.


title: SYNOPSIS
content:
<b>pm2</b> <I>command</I> [options] <I>arguments</I><br>Examples:<br><b>pm2</b> start <I>app|script</I> [options]<br><b>pm2</b> list<br><b>pm2</b> restart <I>app|id</I><br><b>pm2</b> stop <I>app|id</I><br><b>pm2</b> delete <I>app|id</I><br><b>pm2</b> monit<br><b>pm2</b> save


title: PARAMETERS
content:
<b>--name <name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assign a custom name to the process.<br><br><b>-i <number|max>, --instances <number|max></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Launch multiple instances (cluster mode) of the application. 'max' uses all CPU cores.<br><br><b>--watch</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Watch application folder and restart on file changes.<br><br><b>--ignore-watch <paths></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevent specified paths/patterns from being watched when --watch is enabled.<br><br><b>--output <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify output log file path.<br><br><b>--error <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify error log file path.<br><br><b>--log-date-format <format></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the date format for logs (e.g., 'YYYY-MM-DD HH:mm:ss').<br><br><b>--max-memory-restart <size></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Restart the application if its memory usage exceeds the specified threshold (e.g., '200M', '1G').<br><br><b>--env <environment></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify an environment name to load variables from ecosystem file (e.g., --env production).<br><br><b>--no-daemon</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not daemonize PM2; run it in the foreground (useful for Docker).<br><br><b>--silent, -s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not output any logs from PM2 itself (only application logs).<br><br><b>--force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force an action, for example, start an app even if it's already declared.<br><br>


title: DESCRIPTION
content:
<b>pm2</b> is a <I>production process manager</I> for Node.js applications with a built-in <I>load balancer</I>. It allows you to keep applications <I>alive forever</I>, to <I>reload them without downtime</I>, and to facilitate common <I>system administration tasks</I>. Beyond Node.js, it supports any language or framework (Python, PHP, Go, .NET, etc.). It monitors applications, manages logs, and provides a clustering mode to distribute load across CPU cores. It simplifies deployment, offers a comprehensive CLI, and integrates with advanced monitoring solutions. It's designed for reliability, scalability, and ease of use in production environments.


title: CAVEATS
content:
<b>pm2</b> can sometimes consume significant memory if managing a very large number of processes or if log rotation is not adequately configured for high-volume logs. It's not a full-fledged deployment tool but rather a process manager, often used in conjunction with other deployment automation tools like Ansible or Capistrano. While it can manage applications written in any language, <b>pm2</b> itself requires a Node.js runtime environment to operate.


title: ECOSYSTEM FILE
content:
An <B>ecosystem file</B> (<I>ecosystem.config.js/json/yml</I>) is a declarative configuration that allows you to define one or more applications, their environment variables, logging paths, and other <b>pm2</b> options. It's the recommended way to manage complex deployments, enabling version control of application configurations and simplifying deployment processes.


title: ZERO-DOWNTIME RELOADS
content:
Achieved via the <b>pm2 reload</b> <I>app|id</I> command. <b>pm2</b> starts new instances of your application, waits for them to be ready, and only then gracefully kills the old instances. This ensures continuous service availability during application updates, making it ideal for critical production systems.


title: CLUSTERING MODE
content:
Using <b>pm2 start</b> <I>app.js</I> <B>-i max</B> (or a specific number), <b>pm2</b> launches as many instances of your application as there are CPU cores (or the specified number). <b>pm2</b> automatically load-balances incoming requests across these instances, significantly improving performance and reliability for CPU-bound applications.


title: HISTORY
content:
<b>pm2</b> was created by Alexandre Strzelewicz and initially released around 2013. It rapidly gained popularity within the Node.js community as a robust and feature-rich solution for managing applications in production environments. Its continuous development has expanded its capabilities to support applications written in virtually any language, solidifying its position as a widely adopted process manager.


title: SYNOPSIS
content:
<b>pmount</b> [<i>options</i>] <i>device</i> [<i>mountpoint</i>]<br><b>pmount</b> [<i>options</i>] {<b>-u</b>|<b>--umount</b>} <i>mountpoint</i><br><b>pmount</b> {<b>-s</b>|<b>--show</b>}


title: PARAMETERS
content:
<b><i>device</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the device special file (e.g., <i>/dev/sdb1</i>), or a label/UUID if configured.<br><br><b><i>mountpoint</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The directory where the device should be mounted. This directory must usually exist and be empty.<br><br><b><b>-u</b>, <b>--umount</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Unmounts the specified <i>mountpoint</i>. The <i>device</i> argument is not used when unmounting.<br><br><b><b>-s</b>, <b>--show</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all devices currently mounted via <b>pmount</b>.<br><br><b><b>-r</b>, <b>--read-only</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Mounts the device in read-only mode.<br><br><b><b>-w</b>, <b>--writeable</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Mounts the device in writeable mode. This is often the default behavior.<br><br><b><b>-o</b> <i>options</i>, <b>--options=</b><i>options</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify comma-separated mount options (e.g., <i>uid=1000,gid=1000</i>). These options are subject to restrictions defined in <i>/etc/pmount.allow</i>.<br><br><b><b>-i</b>, <b>--iso9660</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Hint to mount the device as an ISO9660 filesystem (commonly used for CD/DVD images). The filesystem type is usually auto-detected.<br><br><b><b>-l</b>, <b>--loop</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Treat the <i>device</i> argument as a file, and mount it as a loop device. Useful for mounting disk images.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output, providing more details about the mounting process.<br><br><b><b>-d</b>, <b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables debug output, useful for troubleshooting.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief help message and exits.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information and exits.<br><br>


title: DESCRIPTION
content:
The <b>pmount</b> command provides a secure and straightforward way for unprivileged users to mount and unmount removable devices such as USB drives, CDs, and DVDs. Unlike the standard <b>mount(8)</b> command, which typically requires root privileges, <b>pmount</b> is a <i>setuid</i> root program. This allows it to perform privileged operations on behalf of a regular user, but only under strict control.<br><br>Its functionality is governed by configuration files like <i>/etc/pmount.allow</i> or <i>udev</i> rules, which define which devices can be mounted, by whom, and with what options. This design enhances system security by preventing arbitrary mounts while still offering user convenience. <b>pmount</b> is particularly useful in desktop environments where users frequently interact with removable media, and also in server contexts where a minimal, secure user-mounting solution is preferred over full root access.


title: CAVEATS
content:
<b>pmount</b> relies heavily on proper system configuration. If <i>/etc/pmount.allow</i> or <i>udev</i> rules are misconfigured, it could lead to security vulnerabilities or prevent users from mounting devices.<br>Mount points usually need to be pre-created and empty. The default mount location is often under <i>/media</i> or <i>/mnt</i>, but this can vary by system configuration.<br>In modern Linux desktop environments, higher-level abstractions like <i>udisks</i> or <i>gvfs</i> often handle automatic mounting of removable media, reducing the direct need for <b>pmount</b> for typical users.


title: CONFIGURATION FILES
content:
The primary configuration file for <b>pmount</b> is <i>/etc/pmount.allow</i>. This file specifies which users are allowed to mount which devices, and with what options. It uses a simple syntax to define permissions. Some distributions might also use <i>/etc/pmount.deny</i>, though it's less common, or rely entirely on <i>udev</i> rules for device permissions.


title: PERMISSIONS
content:
<b>pmount</b> is typically installed as a <i>setuid root</i> binary. This means that when a non-root user executes <b>pmount</b>, it temporarily gains root privileges to perform the necessary actions (like interacting with kernel mount syscalls). However, these privileges are strictly confined by the policies defined in its configuration files, ensuring that users cannot perform arbitrary system modifications.


title: DEFAULT MOUNT LOCATIONS
content:
By default, <b>pmount</b> often attempts to mount devices into a user-specific subdirectory within <i>/media</i> (e.g., <i>/media/user/device_label</i> or <i>/media/user/uuid</i>) or <i>/mnt</i>. The exact default location and naming convention can be configured system-wide and may vary between Linux distributions.


title: HISTORY
content:
<b>pmount</b> emerged as a solution to the long-standing challenge of allowing non-root users to mount removable devices without compromising system security. Before tools like <b>pmount</b>, users either needed root access (which was insecure) or relied on complex <i>fstab</i> entries with the `user` or `users` option (which could be rigid and less flexible for hot-plug devices). <br><br>It provided a simpler, policy-driven approach, often integrating with desktop environments to enable clickable mounting of USB drives and optical media. While its direct command-line usage has become less common in typical desktop use cases due to the rise of automated mounting services (like those provided by <i>udev</i>, <i>udisks</i>, and desktop environments themselves), <b>pmount</b> remains a robust and valuable utility for specific scenarios, especially in command-line-centric or embedded systems.


title: PARAMETERS
content:
<b><i>file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to one or more PNG files to be checked.<br><br><b><b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output, showing more details about chunks and data.<br><br><b><b>-p</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print all chunk names found in the file.<br><br><b><b>-c</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print names of critical chunks (IHDR, PLTE, IDAT, IEND) only.<br><br><b><b>-t</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print contents of text chunks (tEXt, zTXt, iTXt).<br><br><b><b>-f</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Report only the first error encountered and then exit.<br><br><b><b>-e</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print extended information, such as chunk length and CRC values.<br><br><b><b>-o</b> <i>offset</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Start checking the file from the specified byte <i>offset</i>. Useful for embedded PNGs.<br><br><b><b>-l</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;List all known PNG chunk types supported by <i><b>pngcheck</b></i> and exit. This option does not take file arguments.<br><br><b><b>-q</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable quiet mode; suppress all output except for error messages or exit status.<br><br><b><b>-s</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print statistics about the PNG file, including dimensions, color depth, interlace type, etc.<br><br><b><b>-S</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print short statistics (a subset of <b>-s</b> information).<br><br><b><b>-T</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not check CRCs for IDAT (image data) chunks. This can speed up checks but is less thorough.<br><br><b><b>-C</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Check all CRCs, including for non-critical chunks and IDAT chunks (default behavior unless <b>-T</b> is used).<br><br><b><b>-V</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the version information of <i><b>pngcheck</b></i> and exit.<br><br>


title: DESCRIPTION
content:
<i><b>pngcheck</b></i> is a command-line utility designed to check the integrity and validity of Portable Network Graphics (PNG) files. It thoroughly examines the internal structure of PNG images, verifying chunk integrity, CRC (Cyclic Redundancy Check) values, and adherence to the PNG specification. This tool is invaluable for detecting corrupted or malformed PNG files, identifying files that do not conform to the standard, or debugging issues related to PNG image processing.<br><br>Beyond simple error detection, <i><b>pngcheck</b></i> can also print detailed information about the PNG file's chunks, dimensions, color depth, and other attributes. It's widely used by developers, system administrators, and anyone who needs to ensure the reliability and interoperability of PNG images in their workflows.


title: CAVEATS
content:
While <i><b>pngcheck</b></i> excels at validating the structural integrity and specification compliance of PNG files, it does <b>not</b> perform visual rendering tests. Therefore, a file deemed 'valid' by <i><b>pngcheck</b></i> might still display incorrectly in certain applications if it contains valid but visually problematic data (e.g., incorrect color profiles not violating PNG spec but causing display issues). Its primary focus is on byte-level adherence to the PNG standard.


title: EXIT STATUS
content:
<i><b>pngcheck</b></i> returns an exit status of <b>0</b> if all specified PNG files are valid and no errors are found. A non-zero exit status indicates that one or more files are invalid or that an internal error occurred, making it suitable for use in shell scripts and automated validation workflows.


title: PNG CHUNKS
content:
PNG files are composed of a series of <b>chunks</b>, each containing specific data (e.g., image header, palette, image data, text information). <i><b>pngcheck</b></i> meticulously examines these chunks, verifying their length, type, CRC, and order, ensuring the file's adherence to the PNG specification.


title: HISTORY
content:
<i><b>pngcheck</b></i> was developed by Glenn Randers-Pehrson, a significant contributor to the PNG (Portable Network Graphics) specification. It emerged as a vital tool within the <i>libpng</i> ecosystem, designed to help ensure the robustness and interoperability of PNG images across various platforms and applications. Its development was driven by the need for a reliable command-line utility to validate PNG files against the official standard, aiding developers in identifying and rectifying issues that could lead to malformed or non-compliant image files.


title: SYNOPSIS
content:
<B>pngquant</B> [<I>options</I>] [<I>file</I> ...] <br> <B>pngquant</B> [<I>options</I>] - < <I>input.png</I> > <I>output.png</I>


title: PARAMETERS
content:
<b><I>file</I> ...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more input PNG files to process. If none specified, reads from standard input.<br><br><b>-</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads image data from standard input (stdin) and writes to standard output (stdout).<br><br><b>-o <I><file></I>, --output <I><file></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output file name. If omitted, <B>pngquant</B> appends `-fs8.png` or `-or8.png` to the input filename.<br><br><b>--quality <I>min-max</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the quality range for compression, e.g., `0-100`. `min` is the minimum acceptable quality, `max` is the target.<br><br><b>--speed <I>N</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls the tradeoff between compression speed and quality (1-11). Higher speeds (e.g., 11) result in faster compression but potentially larger files; lower speeds (e.g., 1) are slower but yield better quality/smaller files.<br><br><b>--ext <I><suffix></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the output file extension (e.g., `.png`). Useful with `--output` for custom naming conventions.<br><br><b>--force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Overwrites existing output files without prompting.<br><br><b>--skip-if-larger</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only saves the output file if it's smaller than the original input file.<br><br><b>--strip</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Strips all optional metadata (e.g., text chunks, EXIF, color profiles) from the output PNG.<br><br><b>--verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints detailed information about the compression process to stderr.<br><br><b>--nofs</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables Floyd-Steinberg dithering. Can sometimes reduce file size further but may introduce visible banding.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the <B>pngquant</B> version information.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the help message and available options.<br><br>


title: DESCRIPTION
content:
<B>pngquant</B> is a powerful command-line utility designed for <B>lossy compression</B> of PNG images. It achieves significant file size reductions by converting 24-bit or 32-bit full-color PNGs into more efficient 8-bit paletted PNGs. The tool employs a sophisticated <I>perceptual quantization</I> algorithm that intelligently selects the optimal color palette for each image. This process aims to maintain high visual quality, even with a reduced color count, by prioritizing colors important to human perception. Its primary application is optimizing images for web delivery, resulting in faster loading times, reduced bandwidth consumption, and improved user experience. It's also widely used for preparing graphics for mobile applications and games where file size efficiency is critical. <B>pngquant</B> offers a robust balance between image quality and extreme file size reduction.


title: CAVEATS
content:
<B>Lossy Compression:</B> <B>pngquant</B> performs lossy compression, meaning some original image data is permanently discarded. While designed to minimize visual impact, a degree of quality reduction is inherent, especially noticeable on images with a wide range of unique colors or subtle gradients.<br><B>Palette Limitation:</B> The output is an 8-bit paletted PNG, limited to a maximum of 256 unique colors. Images with more than 256 distinct colors will have their color count reduced, which might lead to color shifts or banding.<br><B>Unsupported Features:</B> Certain advanced PNG features like APNG (animated PNGs) are not supported and will result in a static image. Embedded ICC profiles are also typically stripped unless specific measures are taken.


title: INPUT AND OUTPUT HANDLING
content:
<B>pngquant</B> can process individual files, multiple files, or integrate into pipelines using standard input/output. When processing multiple files, it typically creates a new file for each input, appending a suffix like `-fs8.png` unless an output name or extension is explicitly specified. Using `-` for standard input/output allows seamless integration with other command-line tools in a pipe.


title: BATCH PROCESSING
content:
For optimizing a large number of images, <B>pngquant</B> is commonly used in conjunction with shell utilities like `find` and `xargs` to automate optimization tasks across entire directories. This makes it highly suitable for integration into automated build processes, content management systems, and other deployment workflows requiring optimized image assets.


title: HISTORY
content:
<B>pngquant</B> was originally developed by <I>Kornel Lesiński</I>. Since its inception, it has grown to become a widely adopted and essential tool for image optimization in web development and other media pipelines. Its development has consistently focused on pioneering efficient algorithms for <I>perceptual quantization</I>, allowing for impressive file size reductions without severely compromising visual fidelity. This continuous improvement in balancing speed, output quality, and compression effectiveness has solidified its position as a go-to utility for handling static PNG assets.


title: SYNOPSIS
content:
<b>pngtopam</b> [<i>-verbose</i>] [<i>-alphaout={filename|-}</i>] [<i>-alphapam</i>] [<i>-gamma={float}</i>] [<i>-background={color}</i>] [<i>-text={string}</i>] [<i>-time</i>] [<i>-timeislocal</i>] [<i>-transparent={color}</i>] [<i>-usetrans</i>] [<i>pngfile</i>]


title: PARAMETERS
content:
<b><i>-verbose</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints detailed debugging information to standard error during processing.<br><br><b><i>-alphaout={filename|-}</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Extracts the PNG's alpha channel into a separate PGM (Portable Graymap) file. If '-' is specified as the filename, the PGM output goes to standard output, causing the main PAM output to be redirected to standard error.<br><br><b><i>-alphapam</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Extracts the alpha channel as a PAM image instead of the default PGM format.<br><br><b><i>-gamma={float}</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Overrides any gamma value specified in the PNG file, allowing for custom gamma correction. A value of 0.0 disables gamma correction.<br><br><b><i>-background={color}</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Composites the image against a specified background color. The color can be an RGB hex string (e.g., #RRGGBB) or a recognized color name.<br><br><b><i>-text={string}</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs any textual chunks embedded within the PNG file as messages to standard error.<br><br><b><i>-time</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints time-related information (e.g., last modification time) from the PNG file to standard error.<br><br><b><i>-timeislocal</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Interprets any time information found in the PNG file as local time, rather than Coordinated Universal Time (UTC).<br><br><b><i>-transparent={color}</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Treats the specified color as transparent, applying transparency to pixels matching this color.<br><br><b><i>-usetrans</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses the transparent color defined within the PNG file itself (if present) for transparency processing.<br><br><b><i>pngfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the input PNG image file. If omitted, <i>pngtopam</i> reads from standard input.<br><br>


title: DESCRIPTION
content:
<i>pngtopam</i> is a command-line utility from the Netpbm suite designed to convert Portable Network Graphics (PNG) image files into the Portable Arbitrary Map (PAM) format.<br><br>PAM is Netpbm's most general image format, capable of representing images with any number of samples per pixel, including color, grayscale, and alpha channels. This tool effectively handles all PNG color types and bit depths, making it a versatile converter. By default, it reads a PNG file from standard input if no filename is provided and writes the resulting PAM image to standard output.<br><br>For PNGs without an alpha channel, <i>pngtopam</i> outputs a PGM (grayscale) or PPM (color) image, which are simpler Netpbm formats. The command leverages the <i>libpng</i> library for PNG decoding.


title: CAVEATS
content:
When using the <i>-alphaout -</i> option to send the alpha channel to standard output, the primary PAM image output is unexpectedly redirected to standard error. This behavior can be confusing and requires careful handling in scripts.<br><br>The <i>pngtopam</i> command primarily focuses on converting the raw pixel data and alpha information. While it uses <i>libpng</i>, which may process sRGB or iCCP color profiles, <i>pngtopam</i> itself does not offer explicit options to control or manipulate these color management aspects directly, beyond gamma correction.


title: OUTPUT FORMAT DETAIL
content:
<i>pngtopam</i>'s default output is the PAM format, which is the most general Netpbm format. If the input PNG does not have an alpha channel, the output PAM image will effectively be a PGM (for grayscale) or PPM (for color) image, which are simpler, more specialized Netpbm formats. The output format is always written to standard output unless specified otherwise (e.g., with <i>-alphaout -</i>).


title: STANDARD INPUT/OUTPUT USAGE
content:
The command is designed to work seamlessly within Unix pipelines. If no <i>pngfile</i> argument is provided, <i>pngtopam</i> reads the PNG image data from standard input (<i>stdin</i>). The resulting PAM image is then written to standard output (<i>stdout</i>), making it easy to chain with other Netpbm utilities or external commands.


title: HISTORY
content:
<i>pngtopam</i> is an integral part of the Netpbm image processing toolkit, which itself has a long and rich history. The Netpbm project is a direct descendant of the original PBMplus package developed by Jef Poskanzer in the late 1980s. PBMplus aimed to provide a set of simple, composable tools for image manipulation based on the Portable BitMap (PBM), Portable GrayMap (PGM), and Portable PixMap (PPM) formats.<br><br>As image formats evolved, Netpbm adapted by incorporating support for newer formats like PNG and introducing more generalized formats like PAM. <i>pngtopam</i> was developed to bridge PNG images with the Netpbm ecosystem, allowing PNGs to be processed and transformed using the vast array of Netpbm utilities by first converting them into a Netpbm format. Its development closely tracks the evolution and adoption of the PNG standard and the ongoing maintenance of the Netpbm project.


title: SYNOPSIS
content:
<b>pngtopnm</b> [<i>options</i>] [<i>pngfile</i>]<br><br>If <i>pngfile</i> is omitted, <b>pngtopnm</b> reads the PNG data from standard input. The converted PNM image is written to standard output.


title: PARAMETERS
content:
<b><b>-alpha</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs an additional Portable Graymap (PGM) file representing the alpha channel of the PNG image. This allows the transparency information to be processed separately.<br><br><b><b>-mix</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Mixes the alpha channel into the image colors. Transparent pixels are blended with a background color, either specified by the <b>-background</b> option or a default black background, creating a non-transparent output.<br><br><b><b>-verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints informative messages to standard error about the conversion process, such as PNG header information and detected features.<br><br><b><b>-gamma=<i>N</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a gamma correction of <i>N</i> to the image. This can be used to adjust the brightness and contrast of the output image, compensating for display or image characteristics.<br><br><b><b>-text=<i>N</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls how text chunks (e.g., <i>tEXt</i>, <i>zTXt</i>) embedded in the PNG file are handled. <i>N</i> can be 0 (ignore), 1 (pass to standard error), or 2 (strip from the output).<br><br><b><b>-transparent=<i>color</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a color to be considered transparent if the PNG file doesn't have an alpha channel, or if <b>-alpha</b>/<b>-mix</b> are not used. <i>color</i> can be a color name (e.g., 'red'), a hexadecimal RGB value (e.g., '#FF0000'), or a comma-separated RGB tuple (e.g., '255,0,0').<br><br><b><b>-background=<i>color</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the background color used when mixing transparent pixels with the <b>-mix</b> option. This color is used for areas where the PNG image is transparent. The format for <i>color</i> is the same as for <b>-transparent</b>.<br><br>


title: DESCRIPTION
content:
<i>pngtopnm</i> is a utility within the Netpbm suite of graphics programs, designed to convert Portable Network Graphics (PNG) image files into the Portable Anymap (PNM) family of formats. The PNM format includes Portable Pixmap (PPM) for color images, Portable Graymap (PGM) for grayscale images, and Portable Bitmap (PBM) for black and white images.<br><br>This conversion is crucial for interoperability within the Unix/Linux environment, as the Netpbm tools are known for their simplicity and ability to be easily chained together in pipelines. <i>pngtopnm</i> allows users to take a PNG image and convert it into a format that can then be processed, edited, or converted further by hundreds of other Netpbm programs or standard Unix utilities. It handles various PNG features like alpha channels and gamma correction during conversion.


title: CAVEATS
content:
While <i>pngtopnm</i> is highly effective for image data conversion, it strips many PNG-specific features such as animations (APNG), embedded profiles (ICC), and extensive metadata beyond basic text chunks. Complex transparency, if not handled by the <b>-alpha</b> or <b>-mix</b> options, will be lost as PNM formats typically do not natively support alpha channels. Therefore, only the raw pixel data and basic color information are preserved.


title: HISTORY
content:
<i>pngtopnm</i> is a key component of the Netpbm project, which originated from the <i>pbmplus</i> package in the early 1990s. The Netpbm tools were developed to provide a flexible and robust set of command-line utilities for image manipulation, emphasizing a simple 'pipeline' design where programs could feed their output to another program's input. <i>pngtopnm</i> was added as support for the then-emerging PNG format became necessary, fitting seamlessly into the Netpbm philosophy of converting various image formats into and out of the common PNM intermediate representation for further processing.


title: PARAMETERS
content:
<b><i>pnmfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The input PNM image file. If omitted, <i>pnm2ppa</i> reads from standard input.<br><br><b><b>-o</b> <i>outfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output file for the PPA data. If omitted, output is sent to standard output.<br><br><b><b>-c</b> <i>color_mode</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the color mode: <b>0</b> for black & white, <b>1</b> for color (default: <b>1</b>).<br><br><b><b>-d</b> <i>density</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls print density: <b>0</b> for normal, <b>1</b> for high (default: <b>1</b>).<br><br><b><b>-q</b> <i>quality</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets print quality: <b>0</b> for draft, <b>1</b> for normal, <b>2</b> for best (default: <b>2</b>).<br><br><b><b>-g</b> <i>gamma</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adjusts the gamma correction value (default: <b>1.5</b>).<br><br><b><b>-f</b> <i>feed</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Determines whether to send a form feed character at the end of the job (default: <b>1</b> for true).<br><br><b><b>-l</b> <i>left_margin</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the left margin in 600dpi dots (default: <b>0</b>).<br><br><b><b>-h</b> <i>high_margin</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the upper-right margin in 600dpi dots (default: <b>0</b>).<br><br><b><b>-r</b> <i>right_margin</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the right margin in 600dpi dots (default: <b>0</b>).<br><br><b><b>-s</b> <i>scan_mode</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the scan mode: <b>0</b> for unidirectional, <b>1</b> for bidirectional (default: <b>0</b>).<br><br><b><b>-t</b> <i>top_margin</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the top margin in 600dpi dots (default: <b>0</b>).<br><br><b><b>-x</b> <i>x_res</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the horizontal resolution in dots per inch (default: <b>600</b>).<br><br><b><b>-y</b> <i>y_res</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the vertical resolution in dots per inch (default: <b>600</b>).<br><br><b><b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output, showing progress and additional information.<br><br>


title: DESCRIPTION
content:
<i>pnm2ppa</i> is a utility from the Netpbm package that transforms Portable Anymap (PNM) image files into a proprietary HP PPA (PhotoREt Printer Access) format. This specific format was primarily used by older HP DeskJet series inkjet printers, such as the DeskJet 710C, 720C, 810C, 820C, 1000C, and 1100C, which utilized HP's PhotoREt color layering technology for enhanced photo quality.<br><br>The command takes a PNM image (which can be PBM, PGM, or PPM) as input, either from a specified file or standard input, and outputs the PPA data to standard output or a designated file. This output can then be directly sent to a compatible HP printer. While modern printers often use standardized protocols like IPP or universal drivers, <i>pnm2ppa</i> remains useful for supporting legacy hardware or for specific embedded systems where precise control over the printer's native format is required.


title: CAVEATS
content:
<i>pnm2ppa</i> is designed for specific older HP DeskJet printers that utilize the HP PhotoREt PPA format. It does not support all HP printer models or modern printer protocols (like PCL, PostScript, or IPP). Its functionality is largely superseded by generic printer drivers (e.g., CUPS) in modern Linux distributions, which handle proprietary formats transparently.<br><br>The output is raw printer data and should typically be sent directly to a printer device or spooled via a printing system configured for direct raw printing.


title: USAGE EXAMPLE
content:
To convert a PPM image to PPA format and send it to an HP printer connected via USB, you might use:<br><code><b><I>ppmtoppm</I></b> <I>myimage.ppm</I> | <b><I>pnm2ppa</I></b> -q 2 -c 1 > /dev/usb/lp0</code><br>Or, to a file for later spooling:<br><code><b><I>pnm2ppa</I></b> <I>input.pnm</I> -o <I>output.ppa</I></code>


title: HISTORY
content:
<i>pnm2ppa</i> is a component of the Netpbm project, a long-standing and widely used suite of graphics conversion tools for Unix-like systems. Netpbm originated in the late 1980s/early 1990s as a collection of `pbmplus` tools by Jef Poskanzer. Over time, it evolved into the `netpbm` package, maintaining its philosophy of simple, pipe-able tools for image manipulation.<br><br><i>pnm2ppa</i> was developed to address the need for Linux and Unix users to print to specific HP DeskJet printers that required their proprietary PPA format, a common challenge before the widespread adoption of universal printer drivers and standardized printing systems like CUPS. Its inclusion reflects Netpbm's goal to provide comprehensive image conversion capabilities, even for niche or proprietary formats prevalent at the time.


title: SYNOPSIS
content:
<b>pnmalias</b> [<I>-a alias program arguments</I>] [<I>-d alias</I>] [<I>-f aliasfile</I>] [<I>-l</I>] [<I>-v</I>]


title: PARAMETERS
content:
<b>-a <I>alias program arguments</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds or changes an <I>alias</I>. <I>alias</I> is the new command name, <I>program</I> is the Netpbm utility (e.g., <b>anytoppm</b>), and <I>arguments</I> are the default parameters for that program.<br><br><b>-d <I>alias</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deletes the specified <I>alias</I> from the configuration file.<br><br><b>-f <I>aliasfile</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative configuration file to use instead of the default <b>.pnmalias</b>.<br><br><b>-l</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all currently defined <I>aliases</I> and their corresponding commands.<br><br><b>-v</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables <I>verbose</I> output, showing more details about the operations being performed by <code>pnmalias</code>.<br><br>


title: DESCRIPTION
content:
<code>pnmalias</code> is a utility from the Netpbm suite designed to manage <I>aliases</I> for programs that convert to and from the Portable Anymap (PNM) format. It allows users to define custom, more descriptive command names (e.g., "giftoppm", "jpegtopnm") that map to the generic <b>anytoppm</b> or <b>ppmtoany</b> commands with specific format arguments. This simplifies command-line usage by abstracting away the need to remember the exact syntax for each conversion.<br><br>The tool can <I>add</I>, <I>delete</I>, or <I>list</I> these aliases, typically by modifying a configuration file (often <b>.pnmalias</b> in the user's home directory). When a program like <b>anytoppm</b> is invoked with an alias, it interprets the alias to determine the desired input format. This makes the Netpbm toolkit more user-friendly for common image format conversions, allowing users to invoke specific conversions with intuitive command names without remembering the underlying generic command arguments.


title: CAVEATS
content:
Aliases defined by <b>pnmalias</b> are only recognized by specific Netpbm programs like <b>anytoppm</b> and <b>ppmtoany</b>; they are not shell aliases.<br>Changes made by <b>pnmalias</b> are persistent, modifying the specified alias file, which can affect all subsequent Netpbm operations relying on those aliases.<br>Ensure the aliased <I>program</I> (e.g., <b>anytoppm</b>) is correctly installed and accessible via the system's PATH for the aliases to function as intended when invoked.


title: DEFAULT ALIAS FILE
content:
By default, <b>pnmalias</b> looks for and modifies an alias file named <b>.pnmalias</b> in the user's home directory (<b>$HOME/.pnmalias</b>). If this file doesn't exist, <b>pnmalias</b> will create it upon adding the first alias, ensuring user-specific alias configurations are maintained.


title: ALIAS FILE FORMAT
content:
The <b>.pnmalias</b> file is a plain text file where each line defines an alias. The format is typically: <I>alias_name program_name arguments</I>. For example, a line like <b>giftoppm anytoppm gif</b> defines an alias named 'giftoppm' that calls 'anytoppm' with the argument 'gif'.


title: HOW ALIASES ARE USED
content:
The aliases themselves are not executable commands. Instead, when you attempt to run a command like <b>giftoppm</b>, if it's not found as a direct executable, the Netpbm <code>anytoppm</code> or <code>ppmtoany</code> programs are designed to check if the invoked command name (e.g., <b>giftoppm</b>) matches an alias defined in the <b>.pnmalias</b> file. If a match is found, they then execute themselves with the corresponding arguments specified by the alias (e.g., <b>anytoppm gif</b>), effectively performing the desired conversion.


title: HISTORY
content:
<b>pnmalias</b> is an integral part of the Netpbm project, which evolved from the Pbmplus package in the early 1990s. Its development was driven by the need to simplify the command-line interface for the vast array of image format converters within the Netpbm suite. Instead of requiring users to always specify input/output formats explicitly with generic tools like <b>anytoppm</b>, <b>pnmalias</b> enabled the creation of user-friendly wrappers (e.g., <b>giftoppm</b>) that automatically passed the correct format arguments, significantly improving usability and reducing typing for common conversions. It reflects a design philosophy aimed at making powerful command-line tools more accessible.


title: SYNOPSIS
content:
<b>pnmarith</b> <i>operation</i> <i>pnmfile1</i> <i>pnmfile2</i><br><b>pnmarith</b> <i>blend</i> <i>factor</i> <i>pnmfile1</i> <i>pnmfile2</i>


title: PARAMETERS
content:
<b><i>add</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds the pixel values of the two input images. The result is clamped to the maximum pixel value.<br><br><b><i>subtract</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Subtracts the pixel values of <i>pnmfile2</i> from <i>pnmfile1</i>. Results are clamped at zero for negative values.<br><br><b><i>multiply</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Multiplies the pixel values of the two input images. The result is scaled down to fit the valid pixel range.<br><br><b><i>divide</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Divides the pixel values of <i>pnmfile1</i> by <i>pnmfile2</i>. Division by zero results in a pixel value of zero.<br><br><b><i>min</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects the minimum pixel value between corresponding pixels of the two input images. Also known as <i>darken</i>.<br><br><b><i>max</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects the maximum pixel value between corresponding pixels of the two input images. Also known as <i>lighten</i>.<br><br><b><i>difference</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Calculates the absolute difference between corresponding pixel values. Also known as <i>absdiff</i>.<br><br><b><i>average</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Computes the arithmetic average of the corresponding pixel values from the two images.<br><br><b><i>blend factor</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Blends the two images. <i>factor</i> is a floating-point number between 0.0 and 1.0. A factor of 0.0 means 100% of <i>pnmfile1</i>, 1.0 means 100% of <i>pnmfile2</i>.<br><br>


title: DESCRIPTION
content:
<i>pnmarith</i> is a command-line utility from the Netpbm suite that applies various arithmetic operations to corresponding pixels of two input Portable Anymap (PNM) images. This includes bitmap (PBM), grayscale (PGM), and pixmap (PPM) formats. It's an essential tool for combining images, creating overlays, performing pixel-level analysis, or adjusting image brightness/contrast based on another image's data. Operations are performed channel-by-channel for color images. The command intelligently handles differences in image dimensions (requiring them to be the same), color depths, and maximum pixel values to produce a valid output PNM image.


title: CAVEATS
content:
Images must have identical dimensions (width and height). If input images have different maximum pixel values (maxval), <i>pnmarith</i> automatically scales the lower maxval image to match the higher before computation. The output image will adopt the higher maxval. All arithmetic results are clamped to be within the valid pixel range (0 to maxval).


title: INPUT AND OUTPUT
content:
<i>pnmarith</i> reads its two input images from the filenames specified on the command line. A hyphen (<b>-</b>) can be used in place of a filename to indicate reading from standard input. The resulting image is always written to standard output.


title: COLOR AND MAXVAL HANDLING
content:
For color images (PPM), operations are performed independently on each of the Red, Green, and Blue color components. For grayscale (PGM) or bitmap (PBM) images, the operation applies to the single pixel value. If input images have different maximum pixel values (e.g., 255 vs 65535), the image with the lower maxval is internally scaled up to match the higher maxval before calculations, ensuring consistent arithmetic results. The output image will have the higher maxval.


title: HISTORY
content:
<i>pnmarith</i> is a long-standing component of the Netpbm package, which originated from Jef Poskanzer's <i>pbmplus</i> suite in the late 1980s. It embodies the Unix philosophy of doing one thing well, providing a simple yet powerful command-line interface for fundamental image arithmetic. While more modern and flexible tools like <i>pamarith</i> have been introduced within Netpbm to handle arbitrary tuple types, <i>pnmarith</i> remains a standard and widely used utility for its direct approach to PNM image manipulation.


title: SYNOPSIS
content:
<b>pnmcat</b> [<i>-left</i> | <i>-right</i> | <i>-top</i> | <i>-bottom</i>] [<i>-spacing=N</i>] [<i>-border=N</i>] [<i>-background=color</i>] [<i>pnmfiles...</i>]


title: PARAMETERS
content:
<b><i>-left</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Concatenates images horizontally, aligning them to the left edge of the composite image.<br><br><b><i>-right</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Concatenates images horizontally, aligning them to the right edge of the composite image.<br><br><b><i>-top</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Concatenates images vertically, aligning them to the top edge of the composite image (this is the default behavior if no direction is specified).<br><br><b><i>-bottom</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Concatenates images vertically, aligning them to the bottom edge of the composite image.<br><br><b><i>-force</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces concatenation even if image dimensions do not perfectly match, potentially truncating or clipping larger images.<br><br><b><i>-spacing=N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies <i>N</i> pixels of transparent space to be added between concatenated images.<br><br><b><i>-border=N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a border of <i>N</i> pixels around each individual image before concatenation.<br><br><b><i>-background=color</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the background color for spaces, borders, and margins. The color can be a name (e.g., 'red') or a hexadecimal RGB value (e.g., '#FF0000').<br><br><b><i>-margin=N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a margin of <i>N</i> pixels around the entire final output image.<br><br><b><i>-jigsaw</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables a specialized 'jigsaw' mode to arrange images into a mosaic, attempting to fill a specified area. This option requires other <i>-jigsaw_...</i> parameters to control its behavior.<br><br><b><i>-jigsaw_width_max=N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum width for individual cells in 'jigsaw' mode.<br><br><b><i>-jigsaw_height_max=N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum height for individual cells in 'jigsaw' mode.<br><br><b><i>-jigsaw_width_min=N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the minimum width for individual cells in 'jigsaw' mode.<br><br><b><i>-jigsaw_height_min=N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the minimum height for individual cells in 'jigsaw' mode.<br><br><b><i>-jigsaw_average_pixels=N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the target average number of pixels for each cell in 'jigsaw' mode.<br><br><b><i>-jigsaw_random_order</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Arranges the images in a random order when using 'jigsaw' mode.<br><br><b><i>-jigsaw_vertical_first</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prioritizes vertical arrangement before horizontal when placing images in 'jigsaw' mode.<br><br><b><i>-jigsaw_force_width=N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the total output width of the 'jigsaw' mosaic to be <i>N</i> pixels.<br><br><b><i>-jigsaw_force_height=N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the total output height of the 'jigsaw' mosaic to be <i>N</i> pixels.<br><br>


title: DESCRIPTION
content:
<i>pnmcat</i> is a utility from the Netpbm suite used to concatenate multiple Portable Anymap (PNM) image files into a single output image. PNM refers to the PBM (Portable BitMap), PGM (Portable GrayMap), and PPM (Portable PixMap) formats. By default, <i>pnmcat</i> concatenates images vertically, stacking them one above the other. Users can specify horizontal concatenation (side-by-side) or control alignment. It offers options for adding spacing, borders, and margins, and even a specialized 'jigsaw' mode for creating mosaics. This command is particularly useful for creating simple image montages or combining a series of images into a single strip.


title: CAVEATS
content:
Input images are generally expected to be of compatible Netpbm types (PBM, PGM, PPM) and have compatible maxval settings, though <i>pnmcat</i> attempts some conversions. Using the <i>-force</i> option can result in images being truncated or clipped if their dimensions do not align with the concatenation direction. The specialized 'jigsaw' mode requires careful tuning of its associated parameters for optimal results.


title: INPUT AND OUTPUT
content:
<i>pnmcat</i> reads PNM image data from files specified as arguments on the command line. If no filenames are provided, it reads image data from standard input. The concatenated PNM image is always written to standard output. Users commonly redirect this output to a file using shell redirection (e.g., <code>pnmcat img1.pnm img2.pnm > output.pnm</code>).


title: DEFAULT CONCATENATION
content:
When no specific direction option (like <i>-left</i> or <i>-right</i>) is used, <i>pnmcat</i> defaults to concatenating images vertically. This means images are stacked one above the other, starting from the top and progressing downwards.


title: HISTORY
content:
<i>pnmcat</i> is an integral part of the Netpbm project, a widely used and venerable toolkit for manipulating graphic images. The origins of Netpbm lie in a collection of separate utilities for PBM, PGM, and PPM formats (Pbmplus, Pgmplus, Ppmplus) created by Jef Poskanzer. These tools were designed following the Unix philosophy of small, specialized utilities that can be chained together. Over time, these distinct projects were merged and expanded into the unified Netpbm package, with <i>pnmcat</i> serving as a foundational component for basic image assembly.


title: SYNOPSIS
content:
<b>pnmcolormap</b> [<b>-colors</b> <i>N</i>] [<b>-transparent</b>] [<b>-transparent-color</b> <i>color</i>] [<b>-transparent-max</b> <i>value</i>] [<b>-transparent-luminance</b> <i>value</i>] [<b>-transparent-threshold</b> <i>value</i>] [<b>-mapfile</b> <i>filename</i>] [<b>-exact</b>] [<b>-verbose</b>] [<i>pnmfile</i>]


title: PARAMETERS
content:
<b><b>-colors</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the maximum number of colors (<i>N</i>) to include in the output colormap. The default value is 256.<br><br><b><b>-transparent</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instructs <i>pnmcolormap</i> to consider transparent pixels. It attempts to make the most common transparent color one of the chosen colormap colors, but excludes transparent pixels from the color quantization process itself.<br><br><b><b>-transparent-color</b> <i>color</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the exact color to be treated as transparent. This is useful when the image has transparent pixels, and you want to ensure a specific color is handled as the transparent one. If not specified, <i>pnmcolormap</i> tries to deduce it.<br><br><b><b>-transparent-max</b> <i>value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum value an alpha channel sample can have for a pixel to be considered transparent. The default is 0.<br><br><b><b>-transparent-luminance</b> <i>value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the minimum luminance a pixel must have to be considered transparent.<br><br><b><b>-transparent-threshold</b> <i>value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the maximum alpha channel threshold for considering a pixel transparent.<br><br><b><b>-mapfile</b> <i>filename</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides an external colormap file to use. Instead of analyzing the input image for colors, <i>pnmcolormap</i> will select a colormap from this specified file.<br><br><b><b>-exact</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When used with <b>-mapfile</b>, this option forces <i>pnmcolormap</i> to use all colors from the provided mapfile, even if some of them are not present in the input image. Without <b>-exact</b>, only colors from the mapfile that are actually present in the input image are used.<br><br><b><b>-verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output, printing more information about the colormap generation process to standard error.<br><br><b><i>pnmfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The input PNM image file. If omitted, <i>pnmcolormap</i> reads the image data from standard input.<br><br>


title: DESCRIPTION
content:
<i>pnmcolormap</i> is a utility from the Netpbm image processing toolkit. It reads a PNM (Portable Anymap) image from standard input or a specified file and outputs a colormap. This colormap is itself a PNM image, typically consisting of a single row of pixels representing the chosen colors.<br><br>The primary purpose of <i>pnmcolormap</i> is to determine a reduced set of colors that best represents the original image, often used for color quantization. It employs an algorithm to select the optimal <i>N</i> colors from the input image, minimizing the perceived color distance between the original and quantized image.<br><br>This command is frequently used in conjunction with <i>pnmquant</i> or <i>ppmquant</i>. <i>pnmcolormap</i> generates the palette, and then <i>pnmquant</i> applies that palette to the image, converting it to an indexed color format. It also offers options for handling transparent pixels, allowing the generated colormap to account for transparency.<br><br>By generating a specific colormap, <i>pnmcolormap</i> provides fine-grained control over color reduction, which is crucial for optimizing images for formats that support limited color palettes, such as GIF or indexed PNG.


title: CAVEATS
content:
The algorithm employed by <i>pnmcolormap</i> aims to minimize color distance, but the resulting colormap may not always be perceptually optimal for all types of images or specific visual preferences. Processing very large images with a vast number of unique colors can be computationally intensive and may require significant memory resources. The transparent options, while powerful, can sometimes be complex and may require experimentation to achieve the desired effect.


title: ALGORITHM
content:
The core algorithm used by <i>pnmcolormap</i> for selecting colors is a variation of the median cut algorithm, a popular technique for color quantization that recursively subdivides color space to find the most representative colors.


title: OUTPUT FORMAT
content:
The output of <i>pnmcolormap</i> is a PNM image (PBM, PGM, or PPM depending on the input image's type), specifically structured as a list of colors. Typically, this output image will have only one row of pixels, with each pixel representing one color in the generated colormap.


title: HISTORY
content:
<i>pnmcolormap</i> is an integral part of the Netpbm suite, a collection of graphics utilities with a rich history rooted in the Unix environment. Netpbm evolved from Jef Poskanzer's <i>pbmplus</i> package, first released in the late 1980s. As image formats and processing needs became more sophisticated, tools like <i>pnmcolormap</i> were developed to provide more generalized and advanced capabilities for tasks such as color reduction and palette optimization, moving beyond simpler quantization methods to offer more control over the generated colormaps, particularly for indexed color formats like GIF or PNG.


title: SYNOPSIS
content:
<b>pnmcomp</b> [<i>-left=C</i>] [<i>-top=R</i>] [<i>-bottom=R</i>] [<i>-right=C</i>] [<i>-xleft=C</i>] [<i>-xtop=R</i>] [<i>-xbottom=R</i>] [<i>-xright=C</i>] [<i>-align=X</i>] [<i>-valign=Y</i>] [<i>-opacity=PERCENT</i>] [<i>-alpha</i>] [<i>-mask=MASKFILE</i>] [<i>-background=BGFILE</i>] [<i>-blend=PERCENT</i>] [<i>-operator={add|subtract|average|difference|multiply|mask-add|mask-subtract}</i>] [<i>mainimage</i> [<i>compositeimage</i>]]


title: PARAMETERS
content:
<b>mainimage</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The base image onto which the composite image will be placed. If omitted, it is read from standard input.<br><br><b>compositeimage</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The image to be overlaid on the main image. If omitted, it is read from standard input after the main image (if mainimage is also stdin).<br><br><b><i>-left=C</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the column (C) for the left edge of the composite image on the main image.<br><br><b><i>-top=R</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the row (R) for the top edge of the composite image on the main image.<br><br><b><i>-right=C</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the column (C) for the right edge of the composite image on the main image.<br><br><b><i>-bottom=R</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the row (R) for the bottom edge of the composite image on the main image.<br><br><b><i>-xleft=C</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a relative horizontal offset (C) from the left edge of the main image.<br><br><b><i>-xtop=R</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a relative vertical offset (R) from the top edge of the main image.<br><br><b><i>-xright=C</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a relative horizontal offset (C) from the right edge of the main image.<br><br><b><i>-xbottom=R</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a relative vertical offset (R) from the bottom edge of the main image.<br><br><b><i>-align=X</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Horizontal alignment for the composite image (<i>left</i>, <i>center</i>, or <i>right</i>). Overrides explicit column positioning.<br><br><b><i>-valign=Y</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Vertical alignment for the composite image (<i>top</i>, <i>middle</i>, or <i>bottom</i>). Overrides explicit row positioning.<br><br><b><i>-opacity=PERCENT</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the opacity of the composite image, as a percentage (0-100). 0 means fully transparent, 100 means fully opaque. Uses 'over' operator.<br><br><b><i>-alpha</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Treats the composite image as having an alpha channel if it's a PAM file. Not fully supported for all operations compared to <i>pamcomp</i>.<br><br><b><i>-mask=MASKFILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses a PBM mask file to determine transparency. Black pixels in the mask mean transparent, white pixels mean opaque.<br><br><b><i>-background=BGFILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses the specified image file as a background, filling areas where the main image is smaller than the composite image.<br><br><b><i>-blend=PERCENT</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Legacy option for blending the composite image with the main image, equivalent to <i>-opacity</i> with a simpler 'over' blend.<br><br><b><i>-operator={add|subtract|average|difference|multiply|mask-add|mask-subtract}</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the compositing operator to use. Determines how pixel values from the two images are combined arithmetically.<br><br>


title: DESCRIPTION
content:
<i>pnmcomp</i> is a versatile Netpbm command-line tool used to overlay or composite one Netpbm image onto another. It takes a 'main image' and a 'composite image' and places the composite image on top of the main image, producing a new combined image. The command offers extensive control over the positioning of the composite image, allowing for absolute coordinates, relative offsets, and various alignment options. Beyond simple overlay, <i>pnmcomp</i> supports transparency through several mechanisms: implicit transparency (where black pixels in a PBM composite image are treated as transparent), an external mask file, or an alpha channel if present in the composite image. It also provides different blending modes and arithmetic operators (e.g., add, subtract, multiply, average) to determine how the pixel values of the two images are combined. This makes it a powerful utility for tasks like watermarking, superimposing graphics, or combining different visual elements programmatically within image processing pipelines.


title: CAVEATS
content:
<i>pnmcomp</i> is part of the Netpbm suite, which primarily handles PBM, PGM, and PPM formats. While it has an <i>-alpha</i> option, its alpha channel handling is not as robust or comprehensive as the more modern <i>pamcomp(1)</i> command, especially for complex alpha blending scenarios. For true alpha blending with arbitrary transparency, <i>pamcomp</i> is generally preferred. Furthermore, the behavior of some operators (e.g., <i>mask-add</i>, <i>mask-subtract</i>) can be specific to the Netpbm color space and may not behave as expected with all image types or pixel ranges.


title: INPUT/OUTPUT
content:
<i>pnmcomp</i> reads its input images (main and composite) from files specified as arguments or from standard input (`-`). The resulting composite image is always written to standard output. This behavior allows it to be easily integrated into shell pipelines with other Netpbm utilities.


title: TRANSPARENCY AND MASKS
content:
By default, for PBM input, black pixels in the composite image are transparent. For PGM/PPM, black pixels or pixels with the same color as the first pixel of the main image can be treated as transparent. The <i>-mask</i> option provides a more explicit and flexible way to define transparent areas using a separate PBM file, where black represents transparency and white represents opacity. The <i>-alpha</i> option attempts to use an actual alpha channel if the composite image is in PAM format, but this is less robust than <i>pamcomp</i>.


title: HISTORY
content:
<i>pnmcomp</i> is a long-standing utility within the Netpbm project, a comprehensive toolkit for manipulating graphic images. Netpbm originated from the `pbmplus` package created by Jef Poskanzer in the late 1980s. <i>pnmcomp</i> was developed to provide basic image overlay and blending capabilities, a fundamental operation in graphics processing. Its design reflects the era before widespread true alpha channel support, hence its emphasis on explicit mask files and simple pixel-wise arithmetic operations. While newer tools like <i>pamcomp</i> have emerged to handle modern alpha blending more efficiently, <i>pnmcomp</i> remains a valuable tool for simpler compositing tasks, particularly within scripts leveraging the Netpbm format's stream-based processing.


title: SYNOPSIS
content:
<b>pnmconvol</b> [<i>-normalize</i>] [<i>-offset float</i>] [<i>-scale float</i>] <i>kernel_width kernel_height</i> [<i>pnmfile</i>]


title: PARAMETERS
content:
<b><i>kernel_width</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The width (number of columns) of the convolution kernel matrix. This is a required integer argument.<br><br><b><i>kernel_height</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The height (number of rows) of the convolution kernel matrix. This is a required integer argument.<br><br><b><i>pnmfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional. The path to the input PNM image file. If omitted, <b>pnmconvol</b> reads the image from standard input.<br><br><b><i>-normalize</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An optional flag. If specified, the command normalizes the kernel elements so that their sum equals 1. This is particularly useful for blur filters to prevent image brightness changes.<br><br><b><i>-offset float</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An optional argument. Adds the specified floating-point value to each pixel's result after convolution. Useful for adjusting brightness or black levels.<br><br><b><i>-scale float</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An optional argument. Multiplies each pixel's result by the specified floating-point value after convolution. Useful for adjusting contrast or intensity.<br><br>


title: DESCRIPTION
content:
<b>pnmconvol</b> is a command-line utility from the Netpbm toolkit designed to apply a convolution filter to a Portable Anymap (PNM) image. It reads an image either from a specified file or standard input and writes the processed image to standard output.<br><br>A convolution operation involves sliding a kernel (a small matrix of numbers) over each pixel of the image. For each pixel, the kernel's values are multiplied by the corresponding pixel values in the image region covered by the kernel, and the results are summed to determine the new pixel value. This process is fundamental for various image processing effects such as blurring (e.g., Gaussian blur), sharpening, edge detection (e.g., Sobel, Laplace filters), and embossing.<br><br>The user defines the kernel's dimensions and its floating-point values, which are read from standard input. <b>pnmconvol</b> provides options to normalize the kernel, apply an offset, or scale the resulting pixel values, offering flexibility in achieving desired visual outcomes.


title: CAVEATS
content:
<b>pnmconvol</b> expects the convolution kernel matrix to be supplied via standard input immediately after the command line arguments. Each row of the kernel must contain <i>kernel_width</i> space-separated floating-point numbers.<br>The command only processes <I>PNM (Portable Anymap)</I> image formats (PBM, PGM, PPM). Other image formats must first be converted using appropriate Netpbm utilities (e.g., <I>jpegtopnm</I>, <I>pngtopnm</I>).<br>Output pixel values are clamped to the maximum value of the PNM format if they exceed it, potentially leading to saturation for extreme convolution results.


title: KERNEL EXAMPLES
content:
Convolution kernels define the transformation applied to the image. Here are common examples:<br><br>A simple 3x3 blurring kernel, often used with the <i>-normalize</i> option:<br>0.111 0.111 0.111<br>0.111 0.111 0.111<br>0.111 0.111 0.111<br><br>A basic 3x3 sharpening kernel:<br>0 -1 0<br>-1 5 -1<br>0 -1 0<br><br>To apply these, the kernel values are typically piped to <b>pnmconvol</b>'s standard input. For example, to sharpen an image, you might use: echo "0 -1 0\n-1 5 -1\n0 -1 0" | pnmconvol 3 3 image.pnm > sharpened.pnm


title: HISTORY
content:
<b>pnmconvol</b> is a core utility within the Netpbm image processing toolkit. The Netpbm project itself originated from the PBMPLUS package created by Jef Poskanzer in the late 1980s. Over the years, Netpbm has evolved as a robust and comprehensive suite of command-line tools for converting and manipulating various image formats, primarily using the Portable Anymap (PNM) family as an intermediate format. <b>pnmconvol</b> exemplifies the Unix philosophy of small, focused tools that can be chained together (via pipes) to perform complex tasks. Its stable functionality for convolution has been a fundamental component for image filtering operations within the Netpbm ecosystem for decades, serving as a building block for many advanced image processing workflows.


title: PARAMETERS
content:
<b>-white</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assumes the border color is white for automatic cropping.<br><br><b>-black</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assumes the border color is black for automatic cropping.<br><br><b>-top</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Crops only from the top edge of the image.<br><br><b>-bottom</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Crops only from the bottom edge of the image.<br><br><b>-left</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Crops only from the left edge of the image.<br><br><b>-right</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Crops only from the right edge of the image.<br><br><b>-sides</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Crops from both the left and right edges.<br><br><b>-margins</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Crops from all four margins (top, bottom, left, and right).<br><br><b>-margin N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Crops a fixed N pixels from all four margins of the image.<br><br><b>-margin-top N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Crops a fixed N pixels from the top margin.<br><br><b>-margin-bottom N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Crops a fixed N pixels from the bottom margin.<br><br><b>-margin-left N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Crops a fixed N pixels from the left margin.<br><br><b>-margin-right N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Crops a fixed N pixels from the right margin.<br><br>


title: DESCRIPTION
content:
<I>pnmcrop</I> is a fundamental utility within the Netpbm suite, designed to crop <I>PNM</I> (Portable Anymap) images. Its primary function is to remove uniform-colored borders automatically. By default, it intelligently detects the border color by analyzing the four corner pixels of the image. If these corners do not exhibit a consistent color, <I>pnmcrop</I> defaults to assuming the border color is white. Users have granular control, being able to explicitly specify the border color (either <B>-white</B> or <B>-black</B>) or direct the cropping operation to specific sides only, such as <B>-top</B>, <B>-bottom</B>, <B>-left</B>, <B>-right</B>, or all four <B>-margins</B>. Beyond automatic border detection, <I>pnmcrop</I> also supports cropping a precise, fixed number of pixels from any or all edges, offering exact control over the output image dimensions. This command adheres to the Unix philosophy, reading image data from standard input (or a specified file) and writing the resulting cropped image to standard output, making it ideal for integration into shell pipelines.


title: CAVEATS
content:
The automatic border detection relies on the color of the four corner pixels. If the border is non-uniform, transparent, or its color doesn't match the corners, the cropping result might not be as expected. <I>pnmcrop</I> is designed primarily for uniform-colored borders and works exclusively with <I>PNM</I> format images.


title: INPUT AND OUTPUT
content:
<I>pnmcrop</I> reads the image data from a specified <I>PNMFILE</I> argument. If no file is provided, it defaults to reading from standard input. The resulting cropped image is always written to standard output. This design makes it highly versatile and efficient for use within shell scripts and pipelines, allowing it to easily chain with other Netpbm utilities or standard Unix commands.


title: DEFAULT CROPPING LOGIC
content:
When no specific cropping options are provided, <I>pnmcrop</I> employs an intelligent default behavior. It attempts to automatically detect and crop away a uniform-colored border. To determine this border color, it samples the colors of the image's four corner pixels. If these sampled corner colors are not identical, indicating a non-uniform or ambiguous border, <I>pnmcrop</I> falls back to assuming the border is white, and then proceeds to crop based on this assumption.


title: HISTORY
content:
<I>pnmcrop</I> is an integral part of the Netpbm project, a comprehensive suite of utilities for converting and manipulating graphic files. The Netpbm toolkit evolved from Jef Poskanzer's original PBM (Portable BitMap) utilities, which began in the late 1980s. Over time, it expanded to include PGM (Portable GreyMap) and PPM (Portable PixMap), collectively known as PNM. Bryan Henderson is credited as the author for <I>pnmcrop</I>. Netpbm tools are renowned for their adherence to the Unix philosophy – doing one thing well – and their long-standing presence and utility in the Linux/Unix ecosystem, often used in command-line pipelines for image processing.


title: SYNOPSIS
content:
<b>pnmcut</b> [<b>-left=</b><i>N</i>] [<b>-top=</b><i>N</i>] [<b>-width=</b><i>N</i>] [<b>-height=</b><i>N</i>] [<i>pnmfile</i>]<br>


title: PARAMETERS
content:
<b>-left=N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the 0-indexed column number for the leftmost edge of the output rectangle. If omitted, defaults to 0 (the leftmost column of the input image).<br><br><b>-top=N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the 0-indexed row number for the topmost edge of the output rectangle. If omitted, defaults to 0 (the topmost row of the input image).<br><br><b>-width=N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the desired width of the output rectangle. If omitted, defaults to the width of the input image, effectively cutting to its right edge.<br><br><b>-height=N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the desired height of the output rectangle. If omitted, defaults to the height of the input image, effectively cutting to its bottom edge.<br><br><b>pnmfile</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional path to the input PNM image file. If not provided, <i>pnmcut</i> reads the image data from standard input.<br><br>


title: DESCRIPTION
content:
<i>pnmcut</i> is a specialized command-line utility from the comprehensive <i>Netpbm</i> toolkit, designed for precise manipulation of portable anymap (PNM) images. It reads a PNM image (PBM, PGM, or PPM format) from standard input or a specified file and extracts a rectangular portion of it. The output is the cropped image, written to standard output.<br><br>Users define the desired rectangular region by specifying its top-left corner (x, y coordinates) and its width and height. If any of these parameters are omitted, <i>pnmcut</i> defaults to values that effectively extend the cut region to the image boundaries; for instance, a missing width implies the output should extend to the right edge of the input image. This tool is invaluable for tasks such as isolating specific elements from an image, preparing sub-sections for further processing, or creating image sprites, all within a scriptable and non-interactive environment.


title: CAVEATS
content:
If the specified cut region extends beyond the input image's boundaries, the output image will be smaller than specified, cutting only up to the actual image edges. If the specified rectangle does not overlap the input image at all, the output will be an empty image (zero width or zero height). All coordinates are 0-indexed; the top-left pixel is at (0,0).


title: STANDARD INPUT/OUTPUT
content:
<i>pnmcut</i> is designed to work seamlessly within shell pipelines. It reads the PNM image from standard input if no <i>pnmfile</i> argument is provided, and it always writes the resulting cropped PNM image to standard output.


title: COORDINATE SYSTEM
content:
The coordinate system used by <i>pnmcut</i> (and generally by <i>Netpbm</i> tools) places the origin (0,0) at the top-left corner of the image. Column numbers increase to the right, and row numbers increase downwards.


title: HISTORY
content:
<i>pnmcut</i> is an integral part of the <i>Netpbm</i> project, a suite of graphics programs that originated from the <i>pbmplus</i> package. Developed to provide fundamental command-line image manipulation capabilities, <i>Netpbm</i> tools, including <i>pnmcut</i>, have been a staple in Unix-like environments for decades, enabling powerful scripting and automation of image processing tasks long before the advent of sophisticated GUI image editors.


title: DESCRIPTION
content:
<i>pnmdepth</i> is a specialized utility within the <b>Netpbm</b> image processing suite. Its primary function is to change the 'maxval' (maximum pixel value) of a PNM image. This 'maxval' determines the pixel depth, indicating the range of intensity values or colors available for each pixel.<br><br>For grayscale images (PGM) and color images (PPM), a higher maxval allows for more distinct shades or colors, providing finer gradation. For example, a maxval of 255 means 256 possible values (0-255), while 65535 allows for 65536 values. When you use <i>pnmdepth</i> to decrease the maxval, it scales down the existing pixel values, which can lead to a loss of detail and potentially introduce banding or quantization artifacts. Conversely, increasing the maxval simply scales up the existing values, without adding new information or detail to the image; it merely expands the range.<br><br><i>pnmdepth</i> reads a PNM image (PBM, PGM, or PPM) from standard input and writes the modified image to standard output, making it suitable for use in pipelines with other Netpbm tools.


title: CAVEATS
content:
When decreasing the <i>maxval</i>, <i>pnmdepth</i> performs a simple linear scaling of pixel values. This means that if the original image has a wide range of distinct colors or shades, reducing the <i>maxval</i> will irreversibly quantize these values, potentially leading to a loss of detail, color banding, or posterization effects.<br><br>Increasing the <i>maxval</i> does not add any new information or detail to the image; it merely stretches the existing pixel values across a larger range, which can sometimes make existing imperfections more apparent. The input <i>maxval</i> must not exceed 65535.


title: USAGE AND ARGUMENTS
content:
<i>pnmdepth</i> does not accept any command-line options (flags). Instead, it requires a single mandatory argument: <i>newmaxval</i>. This argument is an integer that specifies the desired maximum pixel value for the output image. It must be a positive integer, typically between 1 and 65535.<br><br>The command reads the input PNM image from standard input if no <i>pnmfile</i> is specified. If an optional <i>pnmfile</i> is provided, it reads the image from that file. The transformed image is always written to standard output. This behavior makes <i>pnmdepth</i> highly compatible with Unix pipelines.<br><br><b>Example:</b> To convert an image to a maxval of 255 (standard 8-bit depth for many applications):<br><code>cat input.ppm | pnmdepth 255 > output.ppm</code>


title: HISTORY
content:
<i>pnmdepth</i> is an integral part of the <b>Netpbm</b> project, a venerable toolkit for graphics manipulation that originated from Jef Poskanzer's <b>PBMPlus</b> package in the late 1980s. The <b>Netpbm</b> suite, including <i>pnmdepth</i>, was designed to be highly modular, allowing users to chain simple, single-purpose commands together via pipes to perform complex image transformations. This design philosophy emphasizes simplicity, efficiency, and interoperability within the Unix-like environment. <i>pnmdepth</i> continues to be a fundamental tool for managing pixel depth in image processing workflows, particularly when interfacing with systems or applications that require specific maximum pixel values.


title: PARAMETERS
content:
<b>-x bits</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the horizontal enlargement factor as 2<sup>bits</sup>. Each pixel is replicated horizontally 2<sup>bits</sup> times. The default value for 'bits' is 1, resulting in a 2x horizontal enlargement.<br><br><b>-y bits</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the vertical enlargement factor as 2<sup>bits</sup>. Each pixel is replicated vertically 2<sup>bits</sup> times. The default value for 'bits' is 1, resulting in a 2x vertical enlargement.<br><br><b>pnmfile</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to the input portable anymap (PBM, PGM, or PPM) file. If this argument is omitted, <i>pnmenlarge</i> reads the image data from standard input.<br><br>


title: DESCRIPTION
content:
<i>pnmenlarge</i> is a command-line utility from the <b>Netpbm</b> suite designed to enlarge portable anymap (PBM, PGM, PPM) images. It achieves enlargement by a simple method of pixel replication: each pixel in the original image is duplicated a specified number of times, both horizontally and vertically, to create a larger block of identical pixels in the output.<br><br>The enlargement factor is determined by powers of two; specifically, 2<sup>bits</sup> for both horizontal and vertical dimensions. For instance, if 'bits' is 1, each pixel becomes a 2x2 block, effectively doubling the image's dimensions. By default, <i>pnmenlarge</i> enlarges images by a factor of 2 (i.e., bits=1) in both directions. While functional for basic integer scaling, this method of enlargement can result in a 'blocky' or 'pixelated' appearance, especially when scaling up significantly. This tool reads input from a specified file or standard input and always outputs a Portable Graymap (PGM) file, converting color or monochrome inputs to grayscale. Due to its limitations and the availability of more sophisticated scaling algorithms, <i>pnmenlarge</i> is considered <b>obsolete</b>, with <b>pamscale(1)</b> being the recommended alternative for most image scaling tasks.


title: CAVEATS
content:
This command is considered <i>obsolete</i>. Users are advised to use <b>pamscale(1)</b> for image scaling, which offers more flexibility and better algorithms. <i>pnmenlarge</i> performs simple pixel replication, which can result in a blocky and unsmooth appearance, particularly for large scaling factors. The output is <i>always</i> a Portable Graymap (PGM) file, regardless of the input type (PBM, PGM, or PPM).


title: INPUT/OUTPUT
content:
<i>pnmenlarge</i> reads the input image from standard input if no <i>pnmfile</i> is specified. The enlarged image is then written to standard output.


title: OUTPUT FORMAT
content:
The output of <i>pnmenlarge</i> is exclusively a Portable Graymap (PGM) file. If the input was a PBM (monochrome) file, the output PGM will represent black as 0 and white as 255. If the input was a PPM (color) file, it will be converted to grayscale before enlargement.


title: HISTORY
content:
Part of the Netpbm suite, <i>pnmenlarge</i> is one of the older utilities designed for basic image manipulation. Its functionality for simple integer scaling has largely been superseded by more advanced and general-purpose tools like <b>pamscale(1)</b>, leading to its current classification as obsolete within the Netpbm project.


title: SYNOPSIS
content:
<b>pnmfile</b> [<i>-byname</i>|<i>-byvalue</i>|<i>-bywidth</i>|<i>-byheight</i>|<i>-width</i>|<i>-height</i>|<i>-maxval</i>|<i>-format</i>|<i>-type</i>|<i>-color</i>|<i>-pixels</i>|<i>-verbose</i>|<i>-long</i>|<i>-all</i>|<i>-rows</i>|<i>-columns</i>] [<i>filename ...</i>]


title: PARAMETERS
content:
<b><i>-byname</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sorts and prints information about files by their names.<br><br><b><i>-byvalue</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sorts and prints information about files by their content value (e.g., a checksum or perceptual hash).<br><br><b><i>-bywidth</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sorts and prints information about files by their image width.<br><br><b><i>-byheight</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sorts and prints information about files by their image height.<br><br><b><i>-width</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints only the width of the image in pixels.<br><br><b><i>-height</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints only the height of the image in pixels.<br><br><b><i>-maxval</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints only the maximum pixel value (maxval) for the image.<br><br><b><i>-format</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints only the precise Netpbm format name (e.g., PBM, PGM, PPM, PAM).<br><br><b><i>-type</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints a simplified type of the image (e.g., PBM, PGM, PPM, PAM).<br><br><b><i>-color</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints 'color' if the image is color, or 'grayscale' otherwise.<br><br><b><i>-pixels</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the total number of pixels in the image (width * height).<br><br><b><i>-verbose</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints a detailed summary of all common information for each file, including format, dimensions, maxval, and type.<br><br><b><i>-long</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Equivalent to <i>-verbose</i>; prints a detailed summary for each file.<br><br><b><i>-all</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints all known information about the image file, including checksums and more obscure details.<br><br><b><i>-rows</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the height of the image. This option is considered obsolete.<br><br><b><i>-columns</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the width of the image. This option is considered obsolete.<br><br><b><i>-version</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the Netpbm package version number.<br><br>


title: DESCRIPTION
content:
<I>pnmfile</I> (also known as <I>pnminfo</I>) is a command-line utility from the Netpbm suite designed to report various characteristics of Netpbm image files. It can identify the image format (PBM, PGM, PPM, or PAM), its dimensions (width and height), the maximum pixel value (maxval), and whether the image is color or grayscale. This command is invaluable for scripting image processing workflows, for quickly verifying image attributes, or for simply inspecting file metadata without needing to display the image content. You can request specific pieces of information or a comprehensive summary for one or multiple image files. <I>pnmfile</I> processes files from standard input if no filenames are provided, making it flexible for pipeline use.


title: CAVEATS
content:
<i>pnmfile</i> is part of the Netpbm suite and primarily works with Netpbm formats (PBM, PGM, PPM, PAM). While it can often infer properties from other image types that Netpbm can implicitly convert (via <I>anytopnm</I>), its core functionality is optimized for its native formats.<br>If an input file is not a valid Netpbm image, <I>pnmfile</I> will typically report an error and exit with a non-zero status, which is useful for error checking in scripts.<br>Some options, such as <I>-rows</I> and <I>-columns</I>, are deprecated and their use is discouraged; they may be removed in future Netpbm releases.


title: DEFAULT OUTPUT
content:
When invoked without specific property options, <I>pnmfile</I> provides a concise default output for each file, typically in the format: <I>filename: &lt;width&gt; x &lt;height&gt; &lt;format&gt; &lt;maxval&gt;.</I> For example, <I>image.ppm: 640 x 480 PPM 255</I>.


title: EXIT STATUS
content:
<I>pnmfile</I> returns an exit status of 0 if all specified image files are valid Netpbm formats and their information was successfully reported. A non-zero exit status (typically 1) indicates an error, such as an invalid input file, making it suitable for use in shell scripts to check for successful image processing.


title: HISTORY
content:
<I>pnmfile</I> is a fundamental utility within the Netpbm package, a comprehensive collection of graphics tools for converting and manipulating images. The Netpbm project originated from Jef Poskanzer's Pbmplus toolkit, first released in the late 1980s. As a core component, <I>pnmfile</I> (and its alias <I>pnminfo</I>) has been instrumental from the early days for quickly inspecting the properties of PBM, PGM, and PPM images. The suite has undergone continuous development and maintenance over several decades, evolving into a widely used and reliable command-line tool for basic image processing tasks in Unix-like environments. Its design reflects the Unix philosophy of small, specialized tools that can be chained together.


title: PARAMETERS
content:
<b><b>-lr</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Flips the image left-to-right (horizontally mirrors it).<br><br><b><b>-tb</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Flips the image top-to-bottom (vertically mirrors it).<br><br><b><b>-r90</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Rotates the image 90 degrees clockwise.<br><br><b><b>-r180</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Rotates the image 180 degrees.<br><br><b><b>-r270</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Rotates the image 270 degrees clockwise (equivalent to 90 degrees counter-clockwise).<br><br><b><I>pnmfile</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the input PNM image file. If omitted, pnmflip reads the image data from standard input.<br><br>


title: DESCRIPTION
content:
pnmflip is a versatile command-line utility from the <I>Netpbm</I> suite, designed for fundamental transformations of Portable Anymap (PNM) images. It allows users to easily flip images horizontally or vertically, and rotate them by 90, 180, or 270 degrees clockwise. This tool operates as a filter, typically reading a PNM image from standard input and writing the modified image to standard output, making it highly suitable for use in shell pipelines. For instance, you can pipe the output of an image conversion tool directly into pnmflip and then pipe its output to another Netpbm utility or a display program. Its simplicity and robust integration within the Netpbm ecosystem make it an essential utility for basic image orientation adjustments in scripting and batch processing workflows. While pnmflip handles common transformations, it strictly works with PBM, PGM, and PPM formats, upholding the modular design philosophy of the Netpbm toolkit.


title: CAVEATS
content:
pnmflip only works with <I>Portable Anymap</I> (PBM, PGM, PPM) formats. <br>Rotation options (<b>-r90</b>, <b>-r180</b>, <b>-r270</b>) are mutually exclusive; you can only specify one at a time. <br>If both flip (<b>-lr</b> or <b>-tb</b>) and rotate options are specified, the flips are applied <I>before</I> the rotations.


title: STANDARD INPUT/OUTPUT
content:
pnmflip is designed to operate as a filter. By default, it reads image data from standard input (stdin) and writes the processed image to standard output (stdout). This makes it highly flexible for use in pipelines, allowing it to be chained with other Netpbm utilities or command-line tools without needing intermediate files. For example: `convert input.jpg pnm:- | pnmflip -r90 | pnmtojpeg > output_rotated.jpg`.


title: FORMAT SUPPORT
content:
The command specifically supports the Portable Anymap formats: PBM (Portable Bitmap for monochrome images), PGM (Portable Graymap for grayscale images), and PPM (Portable Pixmap for color images). It cannot directly process other image formats like JPEG, PNG, or GIF; these must first be converted to a PNM format using other Netpbm tools (e.g., `jpegtopnm`, `pngtopnm`) before being processed by pnmflip.


title: HISTORY
content:
`pnmflip` is a long-standing utility within the <I>Netpbm</I> suite, which evolved from the <I>Pbmplus</I> package created by Jef Poskanzer. It has been a core component for basic image manipulation on Unix-like systems since the early days of graphical computing. Its design philosophy aligns with the Unix principle of small, focused tools that do one thing well and can be combined via pipes. While newer, more generalized tools like <I>pamflip</I> exist within Netpbm, <I>pnmflip</I> remains widely used for its specific PNM-centric functionality and backward compatibility.


title: PARAMETERS
content:
<b><b>-gamma=<i>G</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the gamma value to apply. The input pixel values are transformed by raising them to the power of <i>1/G</i>. A typical value for <i>G</i> is 2.2, which is also the default if neither <i>-gamma</i> nor <i>-ungamma</i> is specified. Setting <i>G=1.0</i> results in no change to the image.<br><br><b><b>-ungamma</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies the inverse gamma correction. Input pixel values are transformed by raising them to the power of <i>G</i>. If <i>-gamma=G</i> is also specified, that <i>G</i> value is used; otherwise, the default <i>G</i> of 2.2 is applied. This mode is useful for linearizing an image before other processing, after which normal gamma correction can be reapplied.<br><br><b><i>pnmfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the input PNM image file. If omitted, <i>pnmgamma</i> reads the image data from standard input (stdin).<br><br>


title: DESCRIPTION
content:
<i>pnmgamma</i> is a utility from the Netpbm image processing toolkit designed to apply gamma correction to PNM (Portable Anymap) image files. Gamma correction is a non-linear operation that maps pixel values to new values using a power law, typically expressed as <i>V_out = V_in^(1/G)</i>, where <i>G</i> is the gamma value. This process is crucial for compensating for the non-linear response of display devices (like CRT monitors or modern LCDs) which tend to display an input value <i>V_in</i> as <i>V_in^G</i>. By applying gamma correction with a specific <i>G</i>, <i>pnmgamma</i> ensures that the image appears perceptually correct on a standard display.<br><br>The command reads a PNM image from standard input or a specified file and writes the modified image to standard output. It's often used to adjust the brightness and contrast of the midtones without significantly affecting the highlights or shadows. The default gamma value assumed by <i>pnmgamma</i> (if not specified) is typically 2.2, a common gamma value for many display devices.


title: CAVEATS
content:
Gamma correction is a lossy operation, especially for images with low bit depths, due to floating-point calculations and subsequent rounding of pixel values. Repeated applications of gamma correction can degrade image quality. It's generally best to apply it once at the end of a processing chain, or to linearize the image first if complex manipulations are needed.<br><br>The term 'gamma' itself can be confusing; <i>pnmgamma</i> implements the display-compensation gamma (raising pixel values to 1/G), meaning a higher G brightens the image to compensate for a darker display. If you intend to make an image inherently darker for other reasons, you might need a different approach or a gamma value less than 1 (which would also brighten the image).


title: UNDERSTANDING GAMMA CORRECTION
content:
Gamma correction is essential because human vision perceives brightness logarithmically, and display devices output light non-linearly. Most displays have a native gamma response (power law) of approximately 2.2 to 2.4. To ensure an image appears as intended, an inverse gamma correction (often called 'gamma encoding' or 'gamma compression') is applied to the image data before it's displayed. <i>pnmgamma</i> with <i>-gamma=2.2</i> performs the appropriate operation (<i>V_out = V_in^(1/2.2)</i>) to make an image look correct on such a display.<br><br>Conversely, if you're trying to process an image that has already been 'gamma-encoded' (e.g., from a digital camera), you might want to linearize it first using <i>-ungamma</i> before performing operations like resizing, blending, or color space conversions. This prevents incorrect results due to non-linear averaging of pixel values. After processing, you'd re-apply standard gamma correction.


title: EXAMPLE USAGE
content:
To apply a standard gamma correction of 2.2 to an image named <i>input.ppm</i> and save it as <i>output.ppm</i>:<br><code>pnmgamma -gamma=2.2 input.ppm > output.ppm</code><br><br>To linearize an image before processing it with another Netpbm tool, and then re-apply gamma:<br><code>cat input.ppm | pnmgamma -ungamma | pnmflip -lr | pnmgamma -gamma=2.2 > output.ppm</code><br>(This example linearizes, flips left-right, then re-applies gamma)


title: HISTORY
content:
<i>pnmgamma</i> is a part of the Netpbm project, a comprehensive suite of graphics file format converters and image processing tools. Netpbm originated from Jef Poskanzer's PBMplus package in the early 1990s, evolving into the robust toolkit used today. The commands in the Netpbm suite, including <i>pnmgamma</i>, are known for their simplicity, adherence to the Unix philosophy (do one thing well), and their ability to be chained together using pipes. While specific development milestones for <i>pnmgamma</i> are not widely documented, it has been a foundational utility for basic image gamma adjustment within the Netpbm ecosystem for decades.


title: SYNOPSIS
content:
<b>pnmhisteq</b> [-intensity | -value | -saturation] [-gamma <i>G</i>] [-uniform <i>N</i> | -linear <i>N</i> | -exponential <i>N</i> | -sqrt <i>N</i> | -cube <i>N</i>] [-verbose] [<i>pnmfile</i>]<br>


title: PARAMETERS
content:
<b><b>-intensity</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Default.</i> Equalizes the intensity (luminance) component of the image. For color images, it equalizes based on luminance and reapplies to RGB.<br><br><b><b>-value</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Equalizes the 'value' component (brightness) in the HSV color space.<br><br><b><b>-saturation</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Equalizes the 'saturation' component in the HSV color space.<br><br><b><b>-gamma</b> <i>G</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a gamma correction of <i>G</i> before equalization. Values greater than 1 brighten, less than 1 darken the image.<br><br><b><b>-uniform</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Equalizes to a uniform distribution across <i>N</i> gray levels. <i>N</i> specifies the number of output gray levels.<br><br><b><b>-linear</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Equalizes to a linear distribution across <i>N</i> gray levels, concentrating values towards higher intensities.<br><br><b><b>-exponential</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Equalizes to an exponential distribution across <i>N</i> gray levels, concentrating values towards lower intensities.<br><br><b><b>-sqrt</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Equalizes to a square root distribution across <i>N</i> gray levels.<br><br><b><b>-cube</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Equalizes to a cubic distribution across <i>N</i> gray levels.<br><br><b><b>-verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays diagnostic information and progress messages during execution.<br><br><b><i>pnmfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The input PNM image file. If omitted, <i>pnmhisteq</i> reads from standard input.<br><br>


title: DESCRIPTION
content:
<i>pnmhisteq</i> transforms the intensity values of an image such that its histogram (the distribution of pixel intensities) becomes more uniform or follows a specified distribution. This often enhances the contrast of images, especially those that are either too dark or too bright, by spreading out the most frequent intensity values across the entire available range. It works primarily on grayscale (PGM) and color (PPM) images, internally converting color images to grayscale for equalization based on the chosen channel (intensity, value, or saturation) and then remapping the color components. It's a powerful tool for image enhancement within the <b>Netpbm</b> suite.


title: CAVEATS
content:
<i>pnmhisteq</i> does not work directly with <b>PBM</b> (bitmap) files; it requires <b>PGM</b> (grayscale) or <b>PPM</b> (color) input.<br>Aggressive equalization or a small number of output gray levels (<i>N</i>) can lead to <i>posterization</i> or <i>banding</i> artifacts in the output image.<br>While it enhances contrast, it might sometimes produce an unnatural appearance, especially on images that already have good contrast.


title: UNDERSTANDING DISTRIBUTIONS
content:
The <i>-uniform</i>, <i>-linear</i>, <i>-exponential</i>, <i>-sqrt</i>, and <i>-cube</i> options allow users to specify the target distribution for the equalized histogram, rather than just a purely uniform one. This provides finer control over the resulting contrast and brightness characteristics, making it possible to achieve different visual effects depending on the image content and desired outcome. For instance, <i>-linear</i> can help brighten images, while <i>-exponential</i> might darken them while still enhancing contrast.


title: HISTORY
content:
<i>pnmhisteq</i> is part of the <b>Netpbm</b> package, a venerable suite of graphics utilities for converting, creating, and manipulating image files.<br>Netpbm originated from <b>PBMplus</b>, developed by Jef Poskanzer in the late 1980s. Its design philosophy emphasizes small, simple command-line tools that can be piped together to perform complex tasks.<br>Histogram equalization, as an image processing technique, has been a fundamental method for contrast enhancement for decades. <i>pnmhisteq</i> provides a robust, highly configurable implementation within the Netpbm framework, making it a staple for command-line image manipulation.


title: SYNOPSIS
content:
<b>pnmhistmap</b> [<I>-maxval=<I>value</I></I>] [<I>-xsize=<I>pixels</I></I>] [<I>-ysize=<I>pixels</I></I>] [<I>-greyscale</I>] [<I>-nofill</I>] [<I>-noheader</I>] [<I>pnmfile</I>]


title: PARAMETERS
content:
<b><I>pnmfile</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the input PNM image file. If omitted, <b>pnmhistmap</b> reads the image data from standard input.<br><br><b><I>-maxval=<I>value</I></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the maximum pixel value (maxval) for the output histogram image. This affects the brightness range of the generated map. Defaults to 255.<br><br><b><I>-xsize=<I>pixels</I></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the width of the output histogram image in pixels. The default width is typically 256 or a multiple of 256 to align with the 256 bins.<br><br><b><I>-ysize=<I>pixels</I></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the height of the output histogram image in pixels. The default height is typically 256.<br><br><b><I>-greyscale</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output histogram to be a grayscale (PGM) image, even if the input is a color (PPM) image. This displays the luminance histogram.<br><br><b><I>-nofill</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;By default, the area below the histogram line is filled. This option prevents filling, showing only the line itself.<br><br><b><I>-noheader</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses the drawing of the descriptive header text at the top of the output histogram image.<br><br>


title: DESCRIPTION
content:
<b>pnmhistmap</b> is a utility from the Netpbm suite that generates a visual histogram of a PNM (Portable Anymap) image. It reads an input image and computes the frequency of pixel values across its intensity or color range. The output is a new PNM image (PGM for grayscale, PPM for color) that graphically represents this histogram. <br><br>For grayscale images, it plots the distribution of intensity values. For color images, it typically plots the distribution for each color component (red, green, blue) separately or can be forced to grayscale to show overall luminance. The X-axis of the output histogram represents the pixel value range (from 0 to the image's maxval), divided into 256 bins by default, while the Y-axis indicates the frequency or count of pixels falling into each bin. <br><br>This command is invaluable for analyzing image characteristics such as contrast, exposure, and color balance. It's designed to be used in shell pipelines, allowing seamless integration with other Netpbm tools for comprehensive image manipulation and analysis.


title: CAVEATS
content:
While <b>pnmhistmap</b> can process color images, it typically generates separate histograms for each color component (red, green, and blue) unless the <i>-greyscale</i> option is used. It does not produce a true 3D color histogram. The default binning is 256, which covers the typical 0-255 range for 8-bit images, but images with higher maxval will still be mapped to these bins, potentially losing fine detail if not scaled appropriately.


title: EXAMPLE USAGE
content:
To generate a grayscale histogram map of an image named <I>input.pnm</I> and save it to <I>histogram.pgm</I>:<br><br><b>pnmhistmap</b> <I>-greyscale</I> input.pnm > histogram.pgm<br><br>To pipe output from another Netpbm command, for example, creating a histogram from a converted JPEG:<br><br><b>jpegtopnm</b> myimage.jpg | <b>pnmhistmap</b> <I>-xsize=512</I> <I>-ysize=300</I> > hist_output.ppm


title: HISTOGRAM CALCULATION
content:
By default, <b>pnmhistmap</b> divides the input image's pixel value range (from 0 to its maxval) into 256 bins. It then counts how many pixels fall into each bin. The output image's Y-axis (height) is scaled such that the highest frequency bin reaches the top of the graph, making the distribution clearly visible. For color images, this process is applied to each of the red, green, and blue components individually before drawing them on the same map.


title: HISTORY
content:
<b>pnmhistmap</b> is an integral part of the <I>Netpbm</I> package, which evolved from the original <I>PBMplus</I> toolkit developed by Jef Poskanzer. The Netpbm suite, designed around a philosophy of small, specialized tools that can be chained together via pipes, has been a staple in Unix-like environments for image processing since the late 1980s. <br><br>The inclusion of histogram generation tools like <b>pnmhistmap</b> reflects the early recognition of the importance of statistical image analysis for tasks ranging from print preparation to scientific visualization. Its development focused on being robust, efficient, and compatible with the broader Netpbm ecosystem's pipe-based workflow, allowing users to easily analyze and then manipulate image properties based on their histogram distribution.


title: PARAMETERS
content:
<b><b>-width</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the width of the thumbnail images to <i>N</i> pixels.<br><br><b><b>-height</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the height of the thumbnail images to <i>N</i> pixels.<br><br><b><b>-cols</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the number of columns in the HTML table.<br><br><b><b>-rows</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the maximum number of rows per page in the HTML table. If more images exist, multiple pages are generated.<br><br><b><b>-output</b> <i>filename</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Names the main HTML output file. Defaults to <i>index.html</i> or outputs to standard output if <I>-</I> is specified.<br><br><b><b>-ext</b> <i>ext</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the file extension for generated thumbnails (e.g., <I>jpg</I>, <I>png</I>). Requires the corresponding <I>Netpbm</I> converter.<br><br><b><b>-relative</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses relative paths for image links in the HTML, suitable for local browsing or deployment to a web server in the same structure.<br><br><b><b>-title</b> <i>string</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the title of the HTML page, displayed in the browser's title bar.<br><br><b><b>-desc</b> <i>string</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a description for the HTML page, displayed below the title on the page.<br><br><b><b>-verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints progress messages to standard error during execution, useful for debugging or monitoring long processes.<br><br><b><b>-jpeg</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates JPEG format thumbnails. This is often the default if <I>cjpeg</I> is available.<br><br><b><b>-text</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates a text-only index without any thumbnail images, listing filenames and possibly other details.<br><br><b><b>-light</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses a light background color scheme for the HTML page.<br><br><b><b>-dark</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses a dark background color scheme for the HTML page.<br><br><b><b>-link</b> <i>url</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Links thumbnails to the specified <i>url</i> or the original image file by default. Can be used for external links.<br><br><b><b>-sort</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sorts images by filename alphabetically before processing.<br><br><b><b>-sortsize</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sorts images by their file size.<br><br><b><b>-sortdate</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sorts images by their modification date, from oldest to newest.<br><br><b><b>-rsort</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reverses the sort order specified by <b>-sort</b>, <b>-sortsize</b>, or <b>-sortdate</b>.<br><br><b><b>-page-size</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum number of thumbnails to include per HTML page.<br><br><b><b>-page-prefix</b> <i>prefix</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the filename prefix for additional HTML pages generated when <b>-page-size</b> is used.<br><br><b><b>-thumbnails-only</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates only the thumbnail files, skipping the HTML index page generation.<br><br><b><b>-url-prefix</b> <i>prefix</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a <i>prefix</i> to the URLs for original images in the HTML, useful for hosting images in a specific directory.<br><br>


title: DESCRIPTION
content:
<i>pnmindex</i> is a utility from the <I>Netpbm</I> package designed to generate HTML index pages from a collection of <I>PNM</I> (Portable Anymap) image files. It automatically creates thumbnail images for each input image and embeds them into an HTML table, with links to the original images. This command is particularly useful for quickly generating a web-based gallery of images without manual HTML coding.<br><br>Users can customize various aspects of the output, including the dimensions of the thumbnails, the number of columns and rows in the HTML layout, page title, description, and the color scheme. It supports generating multiple HTML pages if the number of images exceeds a specified limit per page. While <i>pnmindex</i> primarily works with <I>PNM</I> files, it can be integrated with other <I>Netpbm</I> tools to process images in different formats by converting them to <I>PNM</I> first.


title: CAVEATS
content:
<i>pnmindex</i> expects its input to be in one of the <I>PNM</I> formats (<I>PBM</I>, <I>PGM</I>, or <I>PPM</I>). If your images are in other formats (like <I>JPEG</I>, <I>PNG</I>, or <I>GIF</I>), you will need to convert them to <I>PNM</I> first using other <I>Netpbm</I> utilities such as <I>djpeg</I> (for <I>JPEG</I> to <I>PPM</I>) or <I>pngtopnm</I> (for <I>PNG</I> to <I>PPM</I>).<br><br>Generating thumbnails, especially for a large number of high-resolution images, can be CPU and disk I/O intensive. The generated HTML is functional but basic, suitable for quick indexing rather than complex web design. The command may create temporary files in the current directory or <I>/tmp</I> during processing.


title: TYPICAL USAGE WORKFLOW
content:
To use <i>pnmindex</i> effectively with common image formats, you often need to pipe the output of a conversion utility to <i>pnmindex</i>, or convert images to <I>PNM</I> first. <br><br>A common approach for <I>JPEG</I> files would be to convert them to <I>PNM</I> and then pass the <I>PNM</I> filenames to <i>pnmindex</i>:<br><code><b>mkdir</b> pnm_tmp<br><b>for</b> f <b>in</b> *.jpg; <b>do</b> <b>djpeg</b> "$f" > pnm_tmp/"${f%.jpg}.pnm"; <b>done</b><br><b>pnmindex</b> -width 150 -height 100 -cols 4 -output <b>gallery.html</b> pnm_tmp/*.pnm<br><b>rm</b> -r pnm_tmp</code><br><br>A simpler example for already existing <I>PNM</I> files:<br><code><b>pnmindex</b> -width 150 -height 100 -cols 4 -output <b>gallery.html</b> *.ppm *.pgm</code><br>This command generates an <I>HTML</I> file named <I>gallery.html</I> with thumbnails of 150x100 pixels, arranged in 4 columns, for all <I>PPM</I> and <I>PGM</I> files in the current directory.


title: OUTPUT THUMBNAIL FORMATS
content:
By default, <i>pnmindex</i> generates <I>JPEG</I> thumbnails if the <I>cjpeg</I> utility is available. You can specify a different output format using the <b>-ext</b> option (e.g., <code><b>-ext png</b></code>), provided the corresponding <I>Netpbm</I> converter (like <I>pnmtopng</I>) is installed and accessible in your system's PATH. If the specified extension's converter is not found, <i>pnmindex</i> may fall back to its default or report an error.


title: HISTORY
content:
<i>pnmindex</i> is an integral part of the <I>Netpbm</I> project, a suite of graphics utilities that originated from the <I>Pbmplus</I> package developed by Jef Poskanzer in the late 1980s. <I>Netpbm</I> tools are known for their simplicity, pipeline-friendliness, and ability to convert and manipulate a wide array of image formats using the <I>PNM</I> (Portable Anymap) intermediate format. <i>pnmindex</i> has evolved within this ecosystem, adapting to various system environments and image processing needs over decades, maintaining its core functionality of creating simple, navigable image indexes.


title: SEE ALSO
content:
<I>netpbm</I>(1), <I>pnmscale</I>(1), <I>anytopnm</I>(1), <I>djpeg</I>(1), <I>pngtopnm</I>(1), <I>cjpeg</I>(1), <I>pnmtopng</I>(1)


title: PARAMETERS
content:
<b><i>-x_mult=N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the horizontal (width) multiplication factor. The output image will have a width that is N times the input width. The default value is 2.<br><br><b><i>-y_mult=N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the vertical (height) multiplication factor. The output image will have a height that is N times the input height. The default value is 2.<br><br><b><i>pnmfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the input PGM file. If this argument is omitted, <b>pnminterp</b> reads the PGM image from standard input.<br><br>


title: DESCRIPTION
content:
The <b>pnminterp</b> command is a utility from the Netpbm suite designed to increase the resolution of a grayscale (PGM) image. It achieves this by applying a bilinear interpolation algorithm, which calculates new pixel values based on the weighted average of surrounding pixels. This process smooths out the image, making it appear less blocky when scaled up, especially useful for photographic images. <br><br>It takes a PGM image as input, either from a specified file or from standard input, and outputs the higher-resolution PGM image to standard output. Users can specify the horizontal and vertical multiplication factors to control the degree of resolution increase.


title: CAVEATS
content:
<b>pnminterp</b> is specifically designed for grayscale (PGM) images. While Netpbm tools can often convert other formats to PGM (e.g., using <b>pnmtopgm</b>), the interpolation itself operates only on the PGM data. It uses bilinear interpolation, which is a common but not the most advanced interpolation method; for very high-quality upscaling, other algorithms (e.g., bicubic, Lanczos) might be preferred by specialized image processing software.


title: USAGE NOTES
content:
<b>pnminterp</b> is typically used in a pipeline with other Netpbm commands. For instance, to interpolate a JPEG image, one would first convert it to PGM (e.g., <b>djpeg | pnmtopgm</b>), then pipe it to <b>pnminterp</b>, and finally convert the output back to a desired format (e.g., <b>pnmtojpeg</b>).<br><br>Example: <br><i>djpeg image.jpg | pnmtopgm | pnminterp -x_mult=4 -y_mult=4 | pnmtojpeg > interpolated_image.jpg</i><br><br>This command chain converts 'image.jpg' to a PGM, interpolates its resolution by a factor of 4 in both dimensions, and then converts the result back to a JPEG file named 'interpolated_image.jpg'.


title: HISTORY
content:
<b>pnminterp</b> is part of the Netpbm project, a toolkit for manipulating graphic images. Netpbm has a long history, originating from the PBM (Portable BitMap) utilities created by Jef Poskanzer in 1988. Over time, it expanded to include PGM (Portable GrayscaleMap) and PPM (Portable PixMap) formats, evolving into the comprehensive Netpbm suite. <b>pnminterp</b> was developed to provide a standard way to scale images up while attempting to preserve image quality, a common requirement in image processing workflows.


title: DESCRIPTION
content:
<i>pnminvert</i> is a Netpbm tool designed to perform a color inversion on a Portable Anymap (PNM) image.<br>It operates by reading a PNM image from standard input (or a specified filename if provided as an argument) and then writes the inverted image to standard output.<br>For grayscale images (PGM), it flips the intensity values, meaning black becomes white, white becomes black, and intermediate gray shades are similarly inverted.<br>For color images (PPM), <i>pnminvert</i> processes each of the red, green, and blue color components independently, transforming the image into its photographic negative.<br>This utility is a fundamental component of the Netpbm toolkit, frequently used in command-line pipelines with other Netpbm commands for more complex image manipulation tasks.


title: CAVEATS
content:
<i>pnminvert</i> strictly processes Portable Anymap (PNM) images (PBM, PGM, PPM). The input image must be in one of these formats.<br>If your source image is in a different format (e.g., JPEG, PNG, TIFF), you must first convert it to PNM using a suitable Netpbm converter (such as <i>jpegtopnm</i> or <i>pngtopnm</i>) before piping it to <i>pnminvert</i>.<br>As it works with standard input and output, it's highly efficient for piping, but requires proper redirection for file-based operations.


title: USAGE EXAMPLE
content:
To invert an image file named <i>original.pnm</i> and save the resulting negative to <i>negative.pnm</i>:<br><code>pnminvert original.pnm > negative.pnm</code><br><br>To integrate <i>pnminvert</i> into a command pipeline (e.g., convert a JPEG to PNM, invert it, then convert to PNG):<br><code>jpegtopnm input.jpg | pnminvert | pnmtopng > output_inverted.png</code>


title: HOW INVERSION WORKS
content:
The inversion process for each individual pixel's color component (or grayscale value) is calculated using a simple formula: <b><code>new_value = maxval - old_value</code></b>.<br>In this formula, <code>maxval</code> represents the maximum pixel value defined for the image type (e.g., 255 for a typical 8-bit image, or 1 for a PBM (monochrome) image). This calculation ensures that a pixel value of 0 (e.g., black) becomes <code>maxval</code> (e.g., white), and <code>maxval</code> becomes 0, with all intermediate values being proportionally inverted.


title: HISTORY
content:
<i>pnminvert</i> is a long-standing utility that forms part of the comprehensive Netpbm suite. The Netpbm project itself evolved from the PBMplus package, initially developed by Jef Poskanzer in the late 1980s. PBMplus established a foundational set of command-line tools for manipulating portable bitmaps, graymaps, and pixmaps.<br>Netpbm continued and expanded upon this legacy, becoming a widely adopted standard for command-line image processing on Unix-like operating systems. <i>pnminvert</i> has been a core component for basic image transformations since these early developments, underscoring its fundamental utility in image manipulation workflows.


title: SYNOPSIS
content:
<b>pnmmargin</b> [<i>-left</i>=<i>pixels</i>] [<i>-right</i>=<i>pixels</i>] [<i>-top</i>=<i>pixels</i>] [<i>-bottom</i>=<i>pixels</i>] [<i>-margincolor</i>=<i>color</i>] [<i>-verbose</i>] [<i>-pgm</i> | <i>-ppm</i>]


title: PARAMETERS
content:
<b><i>-left</i>=<i>pixels</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the width of the margin on the left side of the image, specified in pixels.<br><br><b><i>-right</i>=<i>pixels</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the width of the margin on the right side of the image, specified in pixels.<br><br><b><i>-top</i>=<i>pixels</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the width of the margin on the top side of the image, specified in pixels.<br><br><b><i>-bottom</i>=<i>pixels</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the width of the margin on the bottom side of the image, specified in pixels.<br><br><b><i>-margincolor</i>=<i>color</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the color to use for the margins. The <i>color</i> can be an X color name (e.g., "red"), an RGB hexadecimal value (e.g., "#FF0000"), or simple names like "black" or "white".<br><br><b><i>-verbose</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Causes <b>pnmmargin</b> to print informational messages about its processing to standard error.<br><br><b><i>-pgm</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output image format to be PGM (Portable Graymap). If the input is PPM, it will be converted to grayscale.<br><br><b><i>-ppm</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output image format to be PPM (Portable Pixmap). If the input is PGM or PBM, it will be promoted to color.<br><br>


title: DESCRIPTION
content:
The <b>pnmmargin</b> command is a utility from the Netpbm image manipulation suite. It reads a Portable Anymap (PNM) format image (which includes PBM for bitmaps, PGM for graymaps, and PPM for pixmaps) from standard input, adds specified margins around the image, and then writes the modified image to standard output.<br><br>Users can specify the width of margins independently for the left, right, top, and bottom sides of the image in pixels. Additionally, the color of these margins can be customized. If no margin color is explicitly provided, the margins will default to black. This tool is particularly useful for preparing images for layout, printing, or when consistent padding is required around visual content. Its standard input/output behavior allows for easy integration into shell scripts and pipelines with other Netpbm tools.


title: CAVEATS
content:
If no margin options are specified, <b>pnmmargin</b> effectively acts as a no-operation, simply copying the input image to the output without modification. <br><br>When adding margins to PBM (Portable Bitmap) images, specifying a margin color that is neither black nor white will cause the image to be promoted to PGM (Portable Graymap) to accommodate the color. Similarly, adding a non-grayscale margin to a PGM image will promote it to PPM (Portable Pixmap). This automatic promotion might alter the intended output format if not explicitly handled with <i>-pgm</i> or <i>-ppm</i> options.


title: STANDARD INPUT/OUTPUT
content:
<b>pnmmargin</b> reads the input PNM image from standard input and writes the resulting image to standard output. This design makes it highly suitable for use in Unix pipelines, allowing it to easily chain with other Netpbm utilities or commands. For example, an image can be piped from a file using <code>cat</code> or directly from another image processing command.


title: HISTORY
content:
<b>pnmmargin</b> is part of the Netpbm project, a comprehensive suite of graphics file format converters and image processing tools. Netpbm originated from the pbmplus package, which was first released in 1988 by Jef Poskanzer. The project has undergone continuous development and maintenance, with <b>pnmmargin</b> being developed by Bryan Henderson as part of the Netpbm suite. Its long history reflects the enduring utility of its minimalist, pipeline-friendly design philosophy for image manipulation on Unix-like systems.


title: SYNOPSIS
content:
pnmmercator [-lon0 longitude] [-lat0 latitude] [-scale scale] [-width width] [-height height] [-north] [-south] [<I>pnmfile</I>]


title: PARAMETERS
content:
<b>-lon0 <I>longitude</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the longitude (in degrees) that maps to the horizontal center of the output image. Default is 0.<br><br><b>-lat0 <I>latitude</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the latitude (in degrees) that maps to the vertical center of the output image. Default is 0.<br><br><b>-scale <I>scale</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the scale factor for the output image. Default is 1. The scale is the ratio of output pixels per degree at the equator.<br><br><b>-width <I>width</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the width of the output image in pixels. Default is the input image's width.<br><br><b>-height <I>height</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the height of the output image in pixels. Default is calculated to show the maximum possible vertical range without distortion for the given width and scale.<br><br><b>-north</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limits the output to the Northern Hemisphere only (0 to 90 degrees latitude). This option overrides both <b>-lat0</b> and <b>-height</b>.<br><br><b>-south</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limits the output to the Southern Hemisphere only (-90 to 0 degrees latitude). This option also overrides <b>-lat0</b> and <b>-height</b>.<br><br><b><I>pnmfile</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional. The input <b>PNM</b> file to process. If omitted, <i><code>pnmmercator</code></i> reads from standard input.<br><br>


title: DESCRIPTION
content:
<i><code>pnmmercator</code></i> reads a <b>PNM</b> image, interpreting it as a cylindrical projection (a standard latitude/longitude map). It then applies the Mercator projection to this image. The input is assumed to cover the full Earth, from -180 to +180 degrees longitude and -90 to +90 degrees latitude. The command allows for centering the projection at specific longitudes and latitudes, scaling the output, and defining its dimensions. Due to the nature of the Mercator projection, which extends infinitely towards the poles, the output image is practically limited to a latitude range of approximately -85.05 to +85.05 degrees. This tool is particularly useful for reprojecting geographic imagery into a common web mapping projection.


title: CAVEATS
content:
The input image is strictly assumed to be in a cylindrical projection (equirectangular).<br>The Mercator projection mathematically extends infinitely towards the poles; therefore, the output image is cropped to a practical latitude range (approximately -85.05 to +85.05 degrees).<br><b>Important:</b> <i><code>pnmmercator</code></i> is considered <b>deprecated</b> in the Netpbm suite. Users are encouraged to use the more general and powerful <i><code>pnmremap</code></i> command for image remapping and projection tasks.


title: HISTORY
content:
<i><code>pnmmercator</code></i> is part of the extensive <b>Netpbm</b> suite of graphics utilities, which provides a comprehensive set of tools for manipulating graphic images in various formats. It was developed to address the specific need for reprojecting cylindrical maps into the Mercator projection.<br>Over time, with the introduction of more flexible and generic image remapping tools, <i><code>pnmmercator</code></i> has been superseded. Its functionality is now largely absorbed and improved upon by the <i><code>pnmremap</code></i> command, making <i><code>pnmmercator</code></i> a legacy tool within the Netpbm collection.


title: SYNOPSIS
content:
<b>pnmmontage</b> [<I>options</I>] [<I>pnmfile...</I>]<br><i>Common options include</i>: <br><b>pnmmontage</b> [<b>-background</b> <I>color</I>] [<b>-borderwidth</b> <I>width</I>] [<b>-bordercolor</b> <I>color</I>] [<b>-grid</b> <I>rowsxcols</I>] [<b>-equal</b>] [<b>-novertical</b>] [<b>-verbose</b>] [<I>pnmfile...</I>]


title: PARAMETERS
content:
<b>-background color</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the background <I>color</I> for empty cells in the grid or for the overall image if parts are not filled. Default is white. Colors can be specified using HTML color names, hexadecimal RGB codes (e.g., `#RRGGBB`), or the `rgb:RR/GG/BB` format.<br><br><b>-borderwidth width</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the <I>width</I> (in pixels) of the border to be drawn around each individual image within the montage. The default is 0 (no border).<br><br><b>-bordercolor color</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the <I>color</I> of the borders drawn around each image. The default border color is black. Color specification follows the same rules as <b>-background</b>.<br><br><b>-grid rowsxcols</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly sets the dimensions of the grid as <I>rows</I> by <I>columns</I> (e.g., `3x4` for 3 rows and 4 columns). If omitted, <i>pnmmontage</i> attempts to create a squarish grid.<br><br><b>-equal</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces all input images to be scaled to the same size within their grid cells. Without this option, each image is scaled independently to fit its allocated cell.<br><br><b>-novertical</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents images from being scaled vertically. Images are scaled horizontally to fit their cell width, and their cell height is adjusted to maintain the original aspect ratio. This is useful for preserving image proportions.<br><br><b>-verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output, causing <i>pnmmontage</i> to print informational messages about its progress and actions to standard error.<br><br><b>pnmfile...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more input <i>Netpbm</i> image files (PBM, PGM, or PPM) to be included in the montage. If no files are specified, <i>pnmmontage</i> reads a concatenated stream of <i>Netpbm</i> images from standard input.<br><br>


title: DESCRIPTION
content:
<i>pnmmontage</i> is a command-line utility from the <i>Netpbm</i> suite designed for creating image montages or contact sheets. It takes multiple <i>Netpbm</i> format images (PBM, PGM, or PPM) as input and arranges them into a single, larger image, typically in a grid layout. This tool is invaluable for tasks such as creating visual overviews of image collections, comparing multiple images side-by-side, or simply combining related graphics into a single displayable unit. <i>pnmmontage</i> automatically scales input images to fit within their respective grid cells, ensuring all images are visible. Users can customize the grid dimensions, add borders around individual images, specify border and background colors, and control scaling behavior to suit specific needs. The output is always a new <i>Netpbm</i> image, usually in PPM format if any input images are color, or PGM/PBM otherwise.


title: CAVEATS
content:
<i>pnmmontage</i> is designed exclusively for <i>Netpbm</i> image formats (PBM, PGM, PPM). It does not support other image formats directly; external tools like <i>anytopnm</i> would be needed for conversion. The output is always a single <i>Netpbm</i> image written to standard output, which requires redirection to a file for saving. While it handles scaling, precise control over individual image positioning or complex layering is not available. For very large numbers of high-resolution images, memory consumption can be significant.


title: OUTPUT FORMAT
content:
The output of <i>pnmmontage</i> is always a single <i>Netpbm</i> image written to standard output. If any of the input images are color (PPM), the output will be a PPM image. If all input images are grayscale (PGM) or black & white (PBM), the output will be PGM or PBM respectively, preserving the highest common denominator format. This output typically needs to be redirected to a file, for example: `pnmmontage image1.pnm image2.pnm > montage.pnm`.


title: COLOR SPECIFICATION
content:
Colors for options like <b>-background</b> and <b>-bordercolor</b> can be specified in several ways: <br>1. Named colors (e.g., "white", "black", "red").<br>2. Hexadecimal RGB codes (e.g., `"#FFFFFF"` for white).<br>3. The `rgb:RR/GG/BB` format (e.g., `rgb:FF/FF/FF`).


title: HISTORY
content:
<i>pnmmontage</i> is an integral part of the <i>Netpbm</i> project, a suite of graphics manipulation programs that evolved from the earlier <i>PBMplus</i> package. The Netpbm philosophy emphasizes small, simple, and specialized tools that can be chained together using pipes to perform complex image processing tasks. <i>pnmmontage</i> adheres to this design principle by focusing solely on arranging <i>Netpbm</i> images into a grid, leveraging the strengths of the <i>Netpbm</i> ecosystem for input and output. Its development has mirrored the Netpbm project's ongoing efforts to maintain compatibility and efficiency across various Unix-like systems.


title: SYNOPSIS
content:
<i><b>pnmnlfilt</b></i> [<I>-width W</I>] [<I>-height H</I>] [<I>-weight W</I>] [<I>-all</I>] [<I>-percent P</I>] [<I>-median</I> | <I>-mode</I> | <I>-hilow</I> | <I>-average</I> | <I>-min</I> | <I>-max</I> | <I>-range</I> | <I>-sdev</I> | <I>-total</I> | <I>-gauss</I> | <I>-user filterfile</I>] [<I>pnmfile</I>]


title: PARAMETERS
content:
<b><i><b>-width</b></i> <I>W</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the width of the filter window to <I>W</I> pixels. The default width is 1.<br><br><b><i><b>-height</b></i> <I>H</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the height of the filter window to <I>H</I> pixels. The default height is 1.<br><br><b><i><b>-weight</b></i> <I>W</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assigns a weight to the center pixel within the filter window. The default weight is 1. A higher weight makes the center pixel's original value more influential in the resulting calculation.<br><br><b><i><b>-all</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;If the input is a PPM (color) image, this option causes <i><b>pnmnlfilt</b></i> to apply the filter to each of the three color components (Red, Green, Blue) separately. The output will also be a PPM image. Without this option, for a PPM input, <i><b>pnmnlfilt</b></i> extracts the grayscale equivalent of the image, processes it, and outputs a PGM (grayscale) image.<br><br><b><i><b>-percent</b></i> <I>P</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the percentile to use for filtering. <I>P</I> is a floating-point number between 0 and 100. This is typically used with percentile-based operations like median filtering (which is 50%).<br><br><b><i><b>-median</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs a median filter. Each pixel is replaced by the median value of all pixels within its defined window. This is the default operation if no other filter type is specified.<br><br><b><i><b>-mode</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs a mode filter. Each pixel is replaced by the most frequently occurring value among the pixels within its window.<br><br><b><i><b>-hilow</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Replaces the pixel value with the average of the lowest and highest pixel values found within its window.<br><br><b><i><b>-average</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Replaces the pixel value with the arithmetic mean (average) of all pixel values within its window.<br><br><b><i><b>-min</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs an erosion operation; each pixel is replaced by the minimum value found within its window.<br><br><b><i><b>-max</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs a dilation operation; each pixel is replaced by the maximum value found within its window.<br><br><b><i><b>-range</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Replaces the pixel value with the range (maximum - minimum) of pixel values within its window.<br><br><b><i><b>-sdev</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Replaces the pixel value with the standard deviation of the pixel values within its window.<br><br><b><i><b>-total</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Replaces the pixel value with the sum of all pixel values within its window.<br><br><b><i><b>-gauss</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Replaces the pixel value with a Gaussian-weighted average of the pixel values within its window, providing a smoothing effect.<br><br><b><i><b>-user</b></i> <I>filterfile</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows the user to define a custom filter. The filter characteristics, including type, window dimensions, and optional pixel weights, are specified in the provided <I>filterfile</I>.<br><br>


title: DESCRIPTION
content:
<i><b>pnmnlfilt</b></i> applies a non-linear filter to a Portable Anymap (PNM) image, which includes PGM (Portable Graymap) and PPM (Portable Pixmap) formats. This command is highly effective for noise reduction, particularly useful for preserving image edges while removing speckle or salt-and-pepper noise, a task where linear filters often fall short by blurring features. It operates by evaluating a defined neighborhood (or 'window') of pixels around each target pixel. The target pixel's value is then replaced with a value derived from this neighborhood using a non-linear function.<br><br>Common non-linear operations supported include median filtering (default), where the pixel value is replaced by the median of its neighbors, or mode filtering, which replaces it with the most frequent value. Users can control the filter's behavior by specifying the width and height of the neighborhood window, and by choosing from various filtering algorithms. The input image can be PGM or PPM; if a PPM image is processed without the <i><b>-all</b></i> option, it will be converted to grayscale and output as a PGM. This tool is a fundamental component of the Netpbm suite for versatile image manipulation and processing.


title: CAVEATS
content:
Processing large images or using wide filter windows can be computationally intensive and consume significant memory, potentially leading to slow execution times. Users should be aware that if a PPM (color) image is provided as input and the <i><b>-all</b></i> option is not specified, <i><b>pnmnlfilt</b></i> will convert the image to grayscale, apply the filter, and output a PGM (grayscale) image. This might lead to unexpected color loss if not anticipated.


title: EXAMPLES
content:
To apply a 5x5 median filter to a grayscale image:<br><br><code><i><b>pnmnlfilt</b></i> <I>-width</I> 5 <I>-height</I> 5 <I>input.pgm</I> > <I>output.pgm</I></code><br><br>To apply a 3x3 mode filter to a color image while preserving its colors:<br><br><code><i><b>pnmnlfilt</b></i> <I>-width</I> 3 <I>-height</I> 3 <I>-mode</I> <I>-all</I> <I>color_input.ppm</I> > <I>color_output.ppm</I></code><br><br>To apply a 7x7 minimum filter (erosion) to reduce noise in a binary-like image:<br><br><code><i><b>pnmnlfilt</b></i> <I>-width</I> 7 <I>-height</I> 7 <I>-min</I> <I>binary.pbm</I> > <I>eroded.pbm</I></code>


title: HISTORY
content:
Part of the Netpbm suite, <i><b>pnmnlfilt</b></i> descends from Jef Poskanzer's Pbmplus package, which was originally developed in the late 1980s. It provides fundamental non-linear filtering capabilities, a core technique in image processing for noise reduction and edge preservation, integrating seamlessly into the comprehensive Netpbm toolkit. Its continued development as part of Netpbm reflects the ongoing need for robust, low-level image manipulation tools in a Unix-like environment.


title: SYNOPSIS
content:
<b>pnmnorm</b> [<i>-b blackval</i>] [<i>-w whiteval</i>] [<i>-S saturate</i>] [<i>-l minlumin</i>] [<i>-L maxlumin</i>] [<i>-m maxsamples</i>] [<i>pnmfile</i>]


title: PARAMETERS
content:
<b><b>-b</b> <i>blackval</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the target value for the darkest pixel found in the image.<br>Instead of mapping the darkest pixel to 0, it will be mapped to <i>blackval</i> (0 to maxval). Defaults to 0.<br><br><b><b>-w</b> <i>whiteval</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the target value for the brightest pixel found in the image.<br>Instead of mapping the brightest pixel to maxval, it will be mapped to <i>whiteval</i> (0 to maxval). Defaults to maxval.<br><br><b><b>-S</b> <i>saturate</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A percentage (0.0 to 100.0) indicating how much of the darkest and lightest pixels should be "clipped".<br>For example, if <i>saturate</i> is 1.0, the darkest 1% of pixels will be mapped to the blackval and the brightest 1% to the whiteval, preventing outliers from excessively stretching the contrast.<br><br><b><b>-l</b> <i>minlumin</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a minimum luminance value to map to blackval.<br>If the actual darkest pixel in the image is brighter than <i>minlumin</i>, then <i>minlumin</i> is used as the mapping point for black.<br>This ensures a certain level of darkness is always rendered as black.<br><br><b><b>-L</b> <i>maxlumin</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a maximum luminance value to map to whiteval.<br>If the actual brightest pixel in the image is darker than <i>maxlumin</i>, then <i>maxlumin</i> is used as the mapping point for white.<br>This ensures a certain level of brightness is always rendered as white.<br><br><b><b>-m</b> <i>maxsamples</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limits the number of pixels sampled to determine the darkest and brightest values.<br>This is useful for very large images to speed up processing. The default is 100000 samples.<br><br>


title: DESCRIPTION
content:
<b>pnmnorm</b> is a Netpbm utility that enhances the contrast of a PNM image (PBM, PGM, or PPM). It achieves this by "normalizing" the pixel values, meaning it scales the darkest pixel value in the image to black (0) and the lightest pixel value to white (the image's maxval), with all intermediate values linearly adjusted. This process effectively expands the image's dynamic range to fill the entire available color space, making "washed out" or low-contrast images appear more vibrant and defined.<br><br>For color (PPM) images, <b>pnmnorm</b> operates on the luminance component of the colors, based on the NTSC standard, and then converts the colors back. For grayscale (PGM) images, it works directly on the gray values. While it does process PBM (bitmap) images, their binary nature often means normalization has little or no visible effect unless specific options are used. The command can read from a specified file or standard input and writes the normalized image to standard output.


title: CAVEATS
content:
<b>pnmnorm</b> primarily operates on the luminance component for color (PPM) images, which might not always produce the desired perceptual effect on individual color channels.<br>For PBM (bitmap) images, the effect of <b>pnmnorm</b> is usually negligible or non-existent, as they only contain black and white pixels.<br>Using the <b>-S</b> option (saturation) can lead to loss of detail in the darkest and brightest regions if the percentage is set too high, as these pixels will be clipped to pure black or pure white.<br>If the image has a maxval less than 255, <b>pnmnorm</b> will scale the image to a maxval of 255 after normalization, which might change the image's overall range.


title: INPUT/OUTPUT
content:
<b>pnmnorm</b> reads a PNM image from <i>pnmfile</i> or standard input if no file is specified. The resulting normalized PNM image is written to standard output. This allows for easy piping with other Netpbm commands.


title: INTERNAL PRECISION
content:
The calculations within <b>pnmnorm</b> are performed using floating-point arithmetic to maintain precision during scaling, ensuring accurate luminance mapping.


title: HISTORY
content:
<b>pnmnorm</b> is part of the Netpbm project, a widely used open-source graphics toolkit. The Netpbm package evolved from earlier tools like Pbmplus, which was created by Jef Poskanzer in the late 1980s. <b>pnmnorm</b> itself likely appeared early in the development of these tools, as contrast normalization is a fundamental image processing operation. The Netpbm project continues to be actively maintained, providing a robust set of command-line utilities for manipulating image files.


title: PARAMETERS
content:
<b><B>-r</B> <I>row</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the top row coordinate (Y-axis) for pasting the image. Default is 0.<br><br><b><B>-c</B> <I>col</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the left column coordinate (X-axis) for pasting the image. Default is 0.<br><br><b><B>-mix</B> <I>level</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Blends the foreground with the background. <I>level</I> is a float from 0.0 (background only) to 1.0 (foreground only).<br><br><b><B>-transparent</B> <I>color_spec</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines a specific color in the foreground image to be treated as transparent.<br><br><b><B>-alpha</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses the foreground image's inherent alpha channel for transparency, if available.<br><br><b><B>-alphafile</B> <I>file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads an external PGM or PBM <I>file</I> to use as an alpha mask for the foreground image.<br><br><b><B>-clip</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Clips the pasted foreground image to the dimensions of the background. This is the default.<br><br><b><B>-no-clip</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents clipping, allowing the output image to expand if the foreground goes beyond the background's boundaries.<br><br><b><B>-width</B> <I>pixels</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the output image's width. The canvas expands or contracts as needed.<br><br><b><B>-height</B> <I>pixels</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the output image's height. The canvas expands or contracts as needed.<br><br><b><B>-verbose</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays informational messages about the processing.<br><br>


title: DESCRIPTION
content:
<I>pnmpaste</I> is a fundamental command within the <I>Netpbm</I> suite, designed for image composition. It allows users to overlay one or more Portable Anymap (PNM) format images (PBM, PGM, PPM) onto a specified background PNM image. This tool excels at positioning foreground images using coordinates, applying various forms of transparency, and blending them with the background.<br><br>Its core strength lies in its ability to be integrated seamlessly into shell scripts and automated workflows, leveraging the simple, uncompressed nature of the PNM formats as a universal intermediate. Whether combining logos, watermarks, or creating composite scenes, <I>pnmpaste</I> provides a robust and flexible solution for programmatic image layering, adhering to the modular Unix philosophy of chaining simple utilities for complex tasks.


title: CAVEATS
content:
<I>pnmpaste</I> exclusively processes <I>Netpbm</I> (PBM, PGM, PPM) image formats. Any other image type must first be converted using appropriate <I>Netpbm</I> conversion tools (e.g., <I>jpegtopnm</I>, <I>pngtopnm</I>). While versatile, achieving precise transparency or blending effects may require a clear understanding of color spaces and alpha channel handling within the <I>Netpbm</I> framework. When pasting multiple foregrounds, their application order significantly affects the final composite image.


title: INPUT AND OUTPUT FLEXIBILITY
content:
<I>pnmpaste</I> is designed for seamless integration into shell pipelines. The background image can be read from standard input by default, specified as the first positional argument, or explicitly with the <I>-background</I> option. All resulting composite images are written to standard output, facilitating direct piping to other <I>Netpbm</I> tools or image format converters.


title: COLOR FORMAT HANDLING
content:
While <I>pnmpaste</I> supports PBM (monochrome), PGM (grayscale), and PPM (color) images, mixing them typically results in an automatic conversion to the highest common format (e.g., PGM or PBM converting to PPM). Transparency and blending operations are intelligently applied across these various <I>Netpbm</I> color formats.


title: HISTORY
content:
<I>pnmpaste</I> is an integral part of the widely recognized <I>Netpbm</I> graphics utilities package. This suite evolved from the earlier <I>Pbmplus</I> package, released in 1991, which itself built upon the original Portable BitMap (PBM) utilities created by Jef Poskanzer in 1988. The development philosophy behind these tools emphasizes modularity and pipe-friendliness, enabling complex image manipulations through the chaining of simple commands. <I>pnmpaste</I> perfectly embodies this principle, providing a foundational image composition operation that is both flexible and highly scriptable, making it a long-standing staple in Unix and Linux environments for automated image processing tasks.


title: PARAMETERS
content:
<b><b>-plain</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output just the PSNR or MSE value, without any descriptive text.<br><br><b><b>-raw</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Equivalent to <b>-plain</b>.<br><br><b><b>-mse</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output the Mean Squared Error (MSE) instead of PSNR.<br><br><b><b>-absolute</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use absolute differences for MSE calculation instead of squared differences. This results in Mean Absolute Difference (MAD) or Peak Absolute Difference (PAD), not standard MSE/PSNR. This is a legacy feature for historical comparisons.<br><br><b><b>-maxval</b> <I>value</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the maximum possible pixel value to use in PSNR calculation. By default, it uses the <b>maxval</b> from the images. This option is useful if the actual pixel range for comparison is different from the image's encoded <b>maxval</b>.<br><br>


title: DESCRIPTION
content:
<I>pnmpsnr</I> is a Netpbm program that computes the Peak Signal-to-Noise Ratio (PSNR) between two portable anymap (PNM) images. PSNR is a widely used metric for measuring the quality of reconstruction of lossy compressed images. It compares a compressed or processed image to its original uncompressed version.<br><br>The command reads two image files, which must have identical dimensions and format (PBM, PGM, or PPM). It calculates the Mean Squared Error (MSE) between the two images and then derives the PSNR value from it. A higher PSNR value indicates a better quality image, meaning less distortion or noise introduced. The result is printed to standard output. This tool is essential for evaluating image compression algorithms and assessing image degradation.


title: CAVEATS
content:
Both input images must have identical dimensions and be of the same PNM type (PBM, PGM, or PPM).<br>The calculations are performed on the raw numeric pixel values; no gamma correction or color space transformations are applied.<br>Using the <b>-absolute</b> option deviates from the standard PSNR/MSE definition.


title: PSNR FORMULA
content:
PSNR (Peak Signal-to-Noise Ratio) is typically defined as:<br><br><b>PSNR = 10 * log10((MAX_I^2) / MSE)</b><br><br>Where:<br>- <b>MAX_I</b> is the maximum possible pixel value of the image (e.g., 255 for 8-bit images).<br>- <b>MSE</b> is the Mean Squared Error between the two images.


title: MSE FORMULA
content:
MSE (Mean Squared Error) is calculated as:<br><br><b>MSE = (1 / (M * N)) * sum((I1(i,j) - I2(i,j))^2)</b><br><br>Where:<br>- <b>M</b> and <b>N</b> are the image dimensions (width and height).<br>- <b>I1(i,j)</b> and <b>I2(i,j)</b> are the pixel values of the two images at coordinate (i,j).


title: HISTORY
content:
<I>pnmpsnr</I> is part of the Netpbm project, a long-standing collection of graphics utilities for manipulating image files. Netpbm originated from the PBMPLUS package developed by Jef Poskanzer in the late 1980s. It provides a foundational set of tools for converting, processing, and analyzing images in the simple and versatile PNM (Portable Anymap) formats. <I>pnmpsnr</I> specifically addresses the need for quantitative image quality assessment, which became increasingly important with the rise of image compression technologies.


title: SEE ALSO
content:
pnm(5), pgm(5), ppm(5), netpbm(1), pnmhisteq(1), identify(1) (ImageMagick), compare(1) (ImageMagick)


title: SYNOPSIS
content:
<b>pnmquant</b> [<b>-nofs</b>] [<b>-floyd</b>] [<b>-fs</b>] [<b>-meangray</b>] [<b>-mapfile</b> <i>mapfile</i>] {<i>N</i> | <b>-colors=</b><i>N</i>} [<i>pnmfile</i>]


title: PARAMETERS
content:
<b><b>-nofs</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables Floyd-Steinberg error diffusion. Each pixel is mapped directly to the closest color in the target palette, which can result in banding or posterization.<br><br><b><b>-floyd</b> or <b>-fs</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables Floyd-Steinberg error diffusion (dithering). This is the default behavior. It spreads quantization errors to neighboring pixels, creating the illusion of more colors and reducing banding.<br><br><b><b>-meangray</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Converts the image to grayscale by averaging the R, G, and B components for each pixel before quantization. This is not typical color quantization but a specific grayscale conversion method.<br><br><b><b>-mapfile</b> <i>mapfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses the colors from the specified <i>mapfile</i> as the target palette for quantization. The <i>mapfile</i> must be a PNM image. The number of colors in the map file implicitly defines the target number of colors.<br><br><b><i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the maximum number of colors (<i>N</i>) to reduce the image to. This is a required argument and can be provided as a number directly or using the <b>-colors=</b> option.<br><br><b><b>-colors=</b><i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An alternative way to specify the maximum number of colors (<i>N</i>) to reduce the image to, identical in function to providing <i>N</i> directly.<br><br><b><i>pnmfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The input PNM image file. If not specified, <i>pnmquant</i> reads the image from standard input.<br><br>


title: DESCRIPTION
content:
<i>pnmquant</i> is a Netpbm command-line utility used to reduce the number of colors in a PNM (Portable Anymap) image. This process, known as color quantization, is essential for converting high-color images (e.g., 24-bit truecolor) into images with a limited palette (e.g., 8-bit, 256 colors).<br><br>The primary use cases include preparing images for display on hardware with limited color capabilities, reducing file sizes for web or embedded systems, or converting images to formats like GIF or PNG-8 that support indexed color. <i>pnmquant</i> employs various algorithms, most notably error diffusion (dithering) like Floyd-Steinberg, to minimize visual artifacts when mapping original colors to a smaller palette. Without dithering, colors are simply mapped to the nearest available color, which can lead to banding or posterization effects.


title: CAVEATS
content:
The quality of the quantized image is highly dependent on the chosen number of colors (<i>N</i>) and whether dithering is used. Too few colors without dithering can lead to significant loss of detail and color banding. Dithering can introduce noise but generally improves perceived image quality at low color depths. The <b>-meangray</b> option performs a simple average for grayscale, which might not be perceptually optimal for all images.


title: INPUT AND OUTPUT
content:
<i>pnmquant</i> reads a PNM image from standard input if no <i>pnmfile</i> is specified. The quantized image is written to standard output in PNM format. This allows for easy piping with other Netpbm utilities.


title: COLOR PALETTE GENERATION
content:
When a map file is not provided, <i>pnmquant</i> intelligently selects the <i>N</i> most representative colors from the input image to form the new palette. This process is optimized to retain as much visual information as possible given the color constraint.


title: HISTORY
content:
<i>pnmquant</i> is part of the Netpbm project, a toolkit for manipulating graphic images. Netpbm originated from the PBMPLUS package by Jef Poskanzer in the late 1980s, which became a foundational suite for image processing on Unix-like systems. <i>pnmquant</i> has been a core utility for color reduction since the early days of the toolkit.


title: SYNOPSIS
content:
<i>pnmquantall</i> [<i>-colors=N</i>] [<i>-mapfile=filename</i>] <br>[<i>-outfile=format_string</i>] [<i>-verbose</i>] <br>[<i>-nofloyd</i> | <i>-floyd</i>] [<i>-wu</i> | <i>-mean</i>] <br>[<i>-extracolors=N</i>] [<i>-posterize=N</i>] <br>[<i>pnmfile ...</i>]


title: PARAMETERS
content:
<b><i>-colors=N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Target number of colors.</b> <br>Specifies the maximum number of colors (up to 256) to be <br>in the output images' colormap. The actual number may be less.<br><br><b><i>-mapfile=filename</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Output colormap file.</b> <br>Writes the computed common colormap to the specified file in <br>PNM format. This can be useful for debugging or reuse.<br><br><b><i>-outfile=format_string</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Output file naming pattern.</b> <br>A string containing '<i>%s</i>' (for the input filename) and/or <br>'<i>%i</i>' (for the sequence number) to specify output filenames. <br>If omitted, output goes to standard output.<br><br><b><i>-verbose</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Display progress information.</b> <br>Prints messages to standard error about the processing <br>steps and statistics.<br><br><b><i>-floyd</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Enable Floyd-Steinberg dithering.</b> <br>This is the default. Uses the Floyd-Steinberg algorithm to <br>distribute color quantization errors, reducing banding.<br><br><b><i>-nofloyd</i> | <i>-nodither</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Disable dithering.</b> <br>Prevents <i>pnmquantall</i> from applying any dithering to <br>the output images, which can result in sharper but potentially <br>more banded images.<br><br><b><i>-wu</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Use Wu's color quantization algorithm.</b> <br>Selects Wu's algorithm for generating the colormap, which is <br>generally considered high quality. This is the default.<br><br><b><i>-mean</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Use mean color quantization algorithm.</b> <br>Selects a simpler mean-cut algorithm for colormap generation. <br>Can be faster but potentially lower quality than Wu's.<br><br><b><i>-extracolors=N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Add extra colors during quantization.</b> <br>Adds a specified number of extra colors beyond the <i>-colors</i> <br>limit for an internal quantization step. This can sometimes <br>improve quality, though it adds computation.<br><br><b><i>-posterize=N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Reduce color levels to N.</b> <br>Before quantization, reduces the number of distinct intensity <br>levels for each primary color component to <i>N</i>. Useful for <br>creating a posterized effect.<br><br><b><i>pnmfile ...</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Input PNM files.</b> <br>One or more PNM image files to be processed. If no files <br>are specified, <i>pnmquantall</i> reads from standard input.<br><br>


title: DESCRIPTION
content:
<i>pnmquantall</i> is a Netpbm command-line utility designed for <br>color quantization of <i>multiple</i> Portable Anymap (PNM) <br>images simultaneously. Unlike <i>pnmquant</i>, which quantizes <br>each image individually, <i>pnmquantall</i> analyzes all input <br>images to compute a <i>single, optimal, common colormap</i> that <br>represents the colors across the entire set. This is crucial for <br>applications requiring color consistency, such as creating <br>animated GIFs or a series of images that need to share a <br>unified palette. It then converts each input image to use this <br>generated colormap, effectively reducing the total number of <br>colors in the sequence while preserving visual fidelity as much <br>as possible. The default dithering method is Floyd-Steinberg, <br>which helps to minimize banding artifacts. This tool is <br>indispensable for preparing image series for constrained color <br>environments, like older display hardware or specific image <br>formats.


title: CAVEATS
content:
<i>pnmquantall</i> can consume significant memory and CPU <br>time, especially when processing a large number of high-resolution <br>images. This is due to the need to load all images into memory <br>(or access them frequently) to build the global colormap. <br>Care must be taken with the <i>-outfile</i> option to ensure unique <br>and correctly named output files, particularly when processing <br>images with similar filenames or complex paths.


title: INPUT/OUTPUT BEHAVIOR
content:
If no <i>pnmfile</i> arguments are given, <br><i>pnmquantall</i> reads a single PNM image from standard input. <br>If no <i>-outfile</i> is specified, the quantized output images <br>are written sequentially to standard output. When <i>-outfile</i> <br>is used, each input image corresponds to a uniquely named <br>output file. All output images are typically in PPM format.


title: HISTORY
content:
<i>pnmquantall</i> is an integral part of the Netpbm graphics <br>conversion toolkit, which evolved from the Pbmplus package <br>originally developed by Jef Poskanzer in the late 1980s. <br>It was specifically added to address the challenge of <br>creating animated GIFs and other sequential image formats <br>that require a common, consistent color palette across <br>all frames. Its development allowed for more efficient <br>and higher-quality batch processing of image sequences <br>compared to quantizing each image independently.


title: SYNOPSIS
content:
<b>pnmremap</b> [<b>-map=</b><i>&lt;mapfile&gt;</i>] [<b>-optimize</b>] [<b>-nofind</b>] [<b>-quiet</b>] [<i>&lt;pnmfile&gt;</i>]


title: PARAMETERS
content:
<b><b>-map=</b><i>&lt;mapfile&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the PNM image file to be used as the color map. All colors in the input image will be remapped to the closest colors found in this map file. If this option is omitted, a default 12-color CGA palette is used.<br><br><b><b>-optimize</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Causes <i>pnmremap</i> to generate a color map based on the input image itself, rather than using a specified <i>&lt;mapfile&gt;</i>. The generated map will contain all the colors present in the input image, up to a maximal color depth of 8 bits (256 colors). This is useful for color quantization where you want to reduce colors but keep the most important ones from the original image.<br><br><b><b>-nofind</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables the 'find closest color' functionality. When this option is used, <i>pnmremap</i> will only remap colors if they exactly match a color in the map file. If any color in the input image does not have an exact match in the map, an error will be generated and the command will fail.<br><br><b><b>-quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses any verbose output or informational messages that <i>pnmremap</i> might otherwise print to standard error.<br><br>


title: DESCRIPTION
content:
<i>pnmremap</i> is a Netpbm command-line utility designed to remap the colors of a PNM (Portable Anymap) image. It takes an input image and transforms its colors to a predefined set of colors found in a 'map' image. For each color in the input image, <i>pnmremap</i> finds the closest matching color in the map image (typically using Euclidean distance in RGB color space) and replaces it. This process is useful for reducing the number of colors in an image, converting an image to a specific color palette (e.g., for older displays or file formats), or preparing an image for dithering. The input image must be in PPM format, and the map image is typically also a PPM. If no map file is specified, <i>pnmremap</i> defaults to a standard 12-color CGA palette.


title: CAVEATS
content:
<i>pnmremap</i> internally converts non-PPM input to PPM if necessary. The map file, if specified, is also expected to be in PNM format, though it can automatically convert GIF to PPM if a GIF is provided.<br><br>When using <b>-optimize</b>, <i>pnmremap</i> essentially performs a color quantization, limiting the output palette to 256 colors. Without <b>-nofind</b>, the 'closest' color matching is based on Euclidean distance in RGB color space, which may not always correspond to perceptual similarity.


title: HISTORY
content:
<i>pnmremap</i> is part of the Netpbm project, a toolkit of graphic file format converters and image processing utilities. Netpbm has a long history, evolving from the original PBMPLUS package created by Jef Poskanzer in the late 1980s. The modular design of Netpbm tools, including <i>pnmremap</i>, allows them to be easily chained together using pipes for complex image manipulations. Its development reflects the ongoing need for robust, open-source image manipulation tools on Unix-like systems.


title: SYNOPSIS
content:
pnmrotate <I>[-angle degrees]</I> <I>[-background color]</I> <I>[-bilinear | -point | -bicubic]</I> <I>[-c corner]</I> <I>[-exact]</I> <I>[-noantialias]</I> <I>[pnmfile]</I>


title: PARAMETERS
content:
<b>-angle degrees</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The angle in degrees by which to rotate the image. Positive values rotate clockwise. The default is 0 degrees (no rotation).<br><br><b>-background color</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the color to fill in any newly exposed areas of the image after rotation. The color can be specified using <I>pnm_parsecolor()</I> format (e.g., "red", "#FF0000"). The default is black.<br><br><b>-bilinear</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects bilinear interpolation. This is the default method for arbitrary angle rotations, offering a good balance between speed and quality.<br><br><b>-point</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects point sampling (nearest neighbor) interpolation. This is the fastest method but can result in a blocky or pixelated appearance, especially for small angles.<br><br><b>-bicubic</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects bicubic interpolation. This method generally produces the highest quality results but is the slowest to process.<br><br><b>-c corner</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the corner or center point around which the image is rotated. Options include <I>topleft</I>, <I>topright</I>, <I>bottomleft</I>, <I>bottomright</I>, and <I>center</I>. The default is <I>center</I>.<br><br><b>-exact</b><br>&nbsp;&nbsp;&nbsp;&nbsp;If specified, the output image dimensions are chosen precisely to contain the entire rotated image without cropping. This may result in larger dimensions with more background compared to the default behavior.<br><br><b>-noantialias</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables antialiasing for arbitrary angle rotations. This option is primarily useful when <I>pnmrotate</I> would use <I>pnmgamma</I> for antialiasing, potentially speeding up processing but reducing image smoothness.<br><br><b>pnmfile</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The input Netpbm image file. If not specified, <I>pnmrotate</I> reads the image data from standard input.<br><br>


title: DESCRIPTION
content:
<I>pnmrotate</I> is a versatile utility from the Netpbm image processing toolkit, designed to rotate Portable Anymap (PNM) format images. It reads an image from standard input (or a specified file) and outputs the rotated image to standard output. The command supports rotation by any specified angle, not just multiples of 90 degrees.<br><br>For rotations that are exact multiples of 90, 180, or 270 degrees, <I>pnmrotate</I> performs a lossless operation without interpolation, resulting in perfectly sharp output. However, for arbitrary angles, the tool employs various interpolation algorithms—bilinear by default, but also point sampling (nearest neighbor) or bicubic interpolation—to calculate the new pixel values. While interpolation allows for smooth rotation at any angle, it can introduce some degree of blurring or artifacts, depending on the chosen method. Newly exposed areas of the image, which were outside the original bounds but become visible after rotation, can be filled with a specified background color. <I>pnmrotate</I> is an essential tool for precise image orientation adjustments within workflows utilizing the Netpbm suite.


title: CAVEATS
content:
<I>pnmrotate</I>'s behavior for arbitrary angles relies on interpolation, which inherently involves approximation. This can lead to a slight loss of image sharpness or the introduction of artifacts, especially when rotating by non-integral angles or when using the faster but lower-quality point sampling method. Choosing the appropriate interpolation method (<I>bilinear</I> or <I>bicubic</I>) is crucial for visual quality but impacts processing time.<br><br>Additionally, the output image dimensions for arbitrary rotations are generally a bounding box that encapsulates the rotated image, which can be larger than the original, unless specific angles (multiples of 90 degrees) are used without the <I>-exact</I> option.


title: INTERPOLATION QUALITY TRADE-OFFS
content:
When rotating images by arbitrary angles, <I>pnmrotate</I> relies on interpolation to calculate the new pixel values.<br><b>Point sampling</b> (<I>-point</I>) is the fastest but can result in a blocky or jagged appearance, as it simply picks the nearest original pixel.<br><b>Bilinear interpolation</b> (<I>-bilinear</I>, the default) provides a smoother result by averaging the four nearest pixels, balancing speed and quality.<br><b>Bicubic interpolation</b> (<I>-bicubic</I>) offers the highest quality by considering 16 nearest pixels, resulting in the smoothest output, but is significantly slower.<br>The choice depends on the desired balance between processing time and visual fidelity.


title: OUTPUT IMAGE DIMENSIONS
content:
By default, when rotating by multiples of 90 degrees, <I>pnmrotate</I> attempts to maintain the original image dimensions where sensible. For arbitrary angle rotations, the output image size will be a bounding box that perfectly encloses the rotated image, which will typically be larger than the original image dimensions.<br>Using the <I>-exact</I> option forces the output dimensions to be precisely the minimal size to contain the rotated image, which can further increase the image's dimensions if the rotated image's bounding box is larger. This ensures no cropping occurs but may add more background space.


title: HISTORY
content:
<I>pnmrotate</I> is a core component of the Netpbm package, a suite of graphics utilities that originated from Jef Poskanzer's PBMplus toolkit in the late 1980s. Netpbm maintains a Unix philosophy of small, specialized tools that can be chained together. <I>pnmrotate</I> was developed to complement simpler rotation tools like <I>pnmflip</I> (which handles only 90-degree increment rotations), providing the capability for precise, arbitrary angle rotations. Its long-standing presence in the Netpbm suite underscores its utility and the stability of the PNM format for command-line image manipulation.


title: PARAMETERS
content:
<b>-xysize <width> <height></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scales the image to the exact specified <width> and <height> in pixels. This may alter the image's aspect ratio.<br><br><b>-xsize <width></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scales the image to the specified <width> in pixels, automatically calculating the height to preserve the aspect ratio.<br><br><b>-ysize <height></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scales the image to the specified <height> in pixels, automatically calculating the width to preserve the aspect ratio.<br><br><b>-scale <factor></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scales the image by the given numerical <factor>. For example, a factor of <i>2.0</i> doubles the size, while <i>0.5</i> halves it.<br><br><b>-filter <type></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the interpolation algorithm used for scaling. Common types include <i>nearest</i> (fastest, lowest quality), <i>bilinear</i> (smoother), and <i>bicubic</i> (smoother, higher quality for enlargements). Many other filter types are available.<br><br><b>-maxrgb</b><br>&nbsp;&nbsp;&nbsp;&nbsp;When reducing image size, this option uses the maximum of the input pixels' color components instead of the average. This can help preserve color vibrancy in certain scenarios.<br><br><b>-verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints diagnostic information and details about the scaling process to standard error.<br><br>


title: DESCRIPTION
content:
<b>pnmscale</b> is a utility from the Netpbm package designed for scaling graphic images. It reads an image in the PNM (Portable Anymap) format, which includes PBM (Portable Bitmap), PGM (Portable Graymap), or PPM (Portable Pixmap), and outputs a resized version. The command offers flexibility in how images are scaled:<br><br>Users can specify an exact output width and/or height, scale by a proportional factor, or fit the image within defined dimensions while preserving its aspect ratio. A key feature of <b>pnmscale</b> is its support for various interpolation algorithms, also known as filters. These range from the fast but lower-quality <i>nearest neighbor</i>, to smoother options like <i>bilinear</i> and <i>bicubic</i>, which are crucial for maintaining image quality during enlargement or significant reduction. <br><br>As part of the Netpbm suite, <b>pnmscale</b> is typically used in shell scripts and command-line pipelines, allowing for efficient batch processing and integration with other image manipulation tools.


title: CAVEATS
content:
<b>pnmscale</b> primarily works with the Netpbm (PNM) image formats. To process other image types (like JPEG, PNG, TIFF), they must first be converted to PNM using other Netpbm tools (e.g., <i>jpegtopnm</i>, <i>pngtopnm</i>) and then converted back if desired. <br><br>Higher quality filters (e.g., bicubic) require more computational resources and can be significantly slower, especially for large images. Memory usage can also increase with certain filters and very large images.


title: PIPELINING AND STANDARD I/O
content:
<b>pnmscale</b> is designed for efficient use in shell pipelines. By default, it reads image data from standard input if no input file is specified, and writes the scaled image to standard output. This facilitates seamless integration with other command-line tools. For example, to resize a JPEG image: <br><code>jpegtopnm input.jpg | pnmscale -xsize 200 | pnmtojpeg > thumbnail.jpg</code>


title: PNM FORMATS
content:
The PNM format is a family of simple, ASCII or binary image file formats that includes:<br><ul><li><i>PBM</i> (Portable Bitmap): Monochrome (black and white) images.</li><li><i>PGM</i> (Portable Graymap): Grayscale images.</li><li><i>PPM</i> (Portable Pixmap): Color images.</li></ul>While <b>pnmscale</b> specifically refers to these, modern implementations often leverage <i>pamscale</i>, which also supports the PAM format, extending compatibility and functionality.


title: HISTORY
content:
<b>pnmscale</b> is a core component of the Netpbm suite of graphics utilities, which originated from the Pbmplus package developed by Jef Poskanzer in the late 1980s. Pbmplus was designed around the Unix philosophy of small, single-purpose programs that can be chained together in pipelines. <b>pnmscale</b> perfectly embodies this, focusing solely on image scaling. Over the years, it has been enhanced with a wider array of interpolation algorithms to improve scaling quality. In modern Netpbm distributions, <b>pnmscale</b> is often implemented as a symbolic link to the more general <i>pamscale</i> command, which supports the newer PAM (Portable Anymap Map) format, a superset of PNM, demonstrating its continued relevance and evolution within the Netpbm framework.


title: PARAMETERS
content:
<b><I>factor</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The mandatory floating-point number representing the scaling factor. For example, <I>2.0</I> will double the image size, while <I>0.5</I> will halve it. A factor of <I>1.0</I> results in no change.<br><br><b><I>pnmfile</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An optional argument specifying the path to the <I>PNM</I> image file to be scaled. If omitted, <b>pnmscalefixed</b> reads the image data from standard input (stdin).<br><br>


title: DESCRIPTION
content:
<b>pnmscalefixed</b> is a command-line utility from the <I>Netpbm</I> package used to resize (scale) <I>Portable Anymap (PNM)</I> images by a fixed, specified factor. Unlike its more general counterpart, <I>pnmscale</I>, <b>pnmscalefixed</b> <B>always</B> employs cubic convolution interpolation to achieve smoother, higher-quality results, particularly when enlarging images. This makes it ideal for situations where image fidelity is paramount. It processes an image from standard input and outputs the scaled image to standard output, making it suitable for use in shell pipelines. The scaling factor is provided as a floating-point number, enabling precise control over the resizing operation. It's a specialized tool focusing on quality-oriented, exact ratio scaling.


title: CAVEATS
content:
<b>pnmscalefixed</b> exclusively uses cubic convolution interpolation, which can be computationally intensive and slow for very large images or extreme scaling factors.<br>Output dimensions are rounded to the nearest integer, which might lead to minor discrepancies from exact proportionality in certain edge cases.<br>It only supports the <I>PNM</I> image formats (PBM, PGM, PPM).


title: INTERPOLATION METHOD
content:
This command's key characteristic is its exclusive use of <I>cubic convolution</I> for image interpolation. This method calculates new pixel values based on a weighted average of a 4x4 neighborhood of surrounding pixels, resulting in smoother transitions, reduced aliasing, and generally higher visual quality, especially when enlarging images, compared to simpler methods like nearest-neighbor or bilinear interpolation.


title: INPUT/OUTPUT
content:
<b>pnmscalefixed</b> operates as a filter program: it reads image data from standard input (stdin) and writes the processed, scaled image to standard output (stdout). This design makes it highly flexible and suitable for chaining with other Netpbm utilities or commands in Unix-like shell pipelines.


title: HISTORY
content:
<b>pnmscalefixed</b> is an integral part of the <I>Netpbm</I> graphics toolkit, which originated as <I>pbmplus</I> by Jef Poskanzer in the late 1980s. It was specifically developed to provide a dedicated tool for high-quality image scaling using cubic convolution interpolation, a method known for superior results compared to simpler algorithms. Its purpose was to offer a specialized, fixed-interpolation scaling option alongside the more versatile <I>pnmscale</I>.


title: PARAMETERS
content:
<b>-x <I>Xshear</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the amount of X-shearing. This is a floating-point number representing the horizontal shift for every unit change in the Y-coordinate. For example, a value of 0.5 means that for every pixel row, the horizontal position is shifted by half a pixel relative to the row above it.<br><br><b>-y <I>Yshear</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the amount of Y-shearing. This is a floating-point number representing the vertical shift for every unit change in the X-coordinate. For example, a value of 0.5 means that for every pixel column, the vertical position is shifted by half a pixel relative to the column to its left.<br><br><b><I>pnmfile</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the Portable Anymap (PNM) image file to be sheared. If not specified, <i>pnmshear</i> reads the image data from standard input.<br><br>


title: DESCRIPTION
content:
<i>pnmshear</i> is a Netpbm command-line utility for applying a shearing transformation to a Portable Anymap (PNM) image. Shearing skews an image along one axis, proportional to its position on the other axis.<br><br>For example, X-shearing shifts pixels horizontally based on their Y-coordinate, making the image appear to tilt. Similarly, Y-shearing shifts pixels vertically based on their X-coordinate. The command allows specifying the shear amount for both X and Y axes using floating-point numbers. The output image may be larger to accommodate the skewed shape, with newly exposed areas filled with black pixels.


title: CAVEATS
content:
<ul><li>Shearing can significantly increase the dimensions of the output image, especially with large shear amounts, as the entire skewed shape must be contained.</li><li>Newly exposed areas outside the original image boundaries after shearing are filled with black pixels.</li><li>The transformation is pixel-based and may introduce jagged edges or loss of detail, particularly when the shear amount is not an integer multiple of pixel shifts.</li></ul>


title: INPUT/OUTPUT FORMATS
content:
<i>pnmshear</i> exclusively operates on Portable Anymap (PNM) images, which include Portable Bitmap (PBM), Portable Graymap (PGM), and Portable Pixmap (PPM) formats. It reads PNM data from <i>pnmfile</i> or standard input and always outputs the resulting sheared image in PNM format to standard output. This design makes it suitable for use in pipelines with other Netpbm tools.


title: MATHEMATICAL CONCEPT OF SHEARING
content:
A shear transformation shifts points in a direction parallel to a specific axis, with the amount of shift being proportional to the coordinate perpendicular to that axis. For an X-shear with factor <i>s_x</i>, a point (x, y) transforms to (x + <i>s_x</i> * y, y). For a Y-shear with factor <i>s_y</i>, (x, y) transforms to (x, y + <i>s_y</i> * x). <i>pnmshear</i> applies these transformations to the pixel coordinates of the image.


title: HISTORY
content:
<i>pnmshear</i> is a component of the Netpbm project, a widely used suite of graphics manipulation tools for Unix-like systems. Netpbm originated from the pbmplus package developed by Jef Poskanzer in the late 1980s, which itself was based on earlier pbm utilities. Over decades, Netpbm has evolved as a collection of converters and filters for various graphics formats, with <i>pnmshear</i> being one of the specialized filters added to perform geometric transformations on the intermediary PNM formats (PBM, PGM, PPM). Its development aligns with the Netpbm philosophy of providing small, single-purpose tools that can be chained together using pipes.


title: PARAMETERS
content:
<b>-filter=<i>width</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the width of the square boxcar filter. The default width is 3. A width of 1 means no smoothing is performed.<br><br><b>-passes=<i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Determines how many times the smoothing filter is applied. The default is 1 pass. <i>N</i> must be at least 1.<br><br>


title: DESCRIPTION
content:
The <b>pnmsmooth</b> command is a utility within the Netpbm suite designed to smooth PNM (Portable Anymap) images. It reads a PNM image from standard input or a specified file and outputs a smoothed version to standard output. The smoothing process involves replacing each pixel with the average value of itself and its surrounding neighbors. This operation is <i>effectively a convolution</i> with a square boxcar filter, which helps to reduce noise and blur the image. Users can control the extent of smoothing by adjusting the filter's width and specifying multiple application passes. For instance, several passes with a small filter can achieve similar results to a single pass with a larger filter, often with better computational efficiency.


title: INPUT AND OUTPUT
content:
If no <i>pnmfile</i> is specified, <b>pnmsmooth</b> reads the PNM image from standard input. The smoothed PNM image is always written to standard output.


title: PERFORMANCE CONSIDERATION
content:
Applying multiple passes with a smaller filter (e.g., three passes with a filter width of 3) can often achieve a smoothing effect comparable to a single pass with a larger filter (e.g., width of 7), but with significantly improved computational performance and reduced processing time.


title: HISTORY
content:
Originating from the PBMPLUS package, <b>pnmsmooth</b> was integrated into the Netpbm suite in 1992. Significant enhancements were made in 1995 by Bryan Henderson, who added the <b>-passes</b> option and made the filter width configurable, significantly improving its flexibility and efficiency.


title: SYNOPSIS
content:
<B>pnmsplit</B> [<I>-basefile basename</I>] [<I>-digits N</I>] [<I>-ext extension</I>] [<I>-outfilepattern pattern</I>]


title: PARAMETERS
content:
<b><I>-basefile basename</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the base string for output filenames. For example, with <I>-basefile frame</I>, files will be named <I>frame00000.pnm</I>, <I>frame00001.pnm</I>, etc. The default is <I>image</I>.<br><br><b><I>-digits N</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the number of digits <I>N</I> to use for the sequential part of the filename. For instance, <I>-digits 3</I> would result in names like <I>image000.pnm</I>, <I>image001.pnm</I>, etc. The default is 5.<br><br><b><I>-ext extension</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the filename extension for the output files. For example, <I>-ext .png</I> would use <I>.png</I> instead of <I>.pnm</I>. The default is <I>.pnm</I>.<br><br><b><I>-outfilepattern pattern</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides a <I>printf</I>-style format string for generating output filenames. This option overrides <I>-basefile</I>, <I>-digits</I>, and <I>-ext</I>. The pattern <B>must</B> contain a <I>%d</I> (or similar integer specifier like <I>%05d</I>) for the sequence number. Example: <I>-outfilepattern "series_%03d.pgm"</I>.<br><br>


title: DESCRIPTION
content:
<B>pnmsplit</B> is a utility that reads a stream of one or more portable anymap images (PBM, PGM, or PPM) from standard input and writes each individual image to a separate file. This command is particularly useful for extracting frames from animations, multi-page documents, or any concatenated PNM stream. By default, it generates output filenames sequentially, such as <I>image00000.pnm</I>, <I>image00001.pnm</I>, and so on, using 5 digits for the sequence number and the <I>.pnm</I> extension. Users can customize the base filename prefix, the number of digits for sequencing, and the file extension. For advanced control, a <I>printf</I>-style output filename pattern can be specified, overriding the default naming conventions. It consistently uses the Portable Anymap formats for output files, which can be any of PBM, PGM, or PPM depending on the input image content.


title: CAVEATS
content:
When using <I>-digits N</I>, ensure <I>N</I> is sufficient to accommodate the expected number of images; an insufficient number of digits could lead to non-unique filenames if the sequence number overflows the specified digit count.<br><br>The default output extension is <I>.pnm</I>, even if the internal image format is specifically PBM, PGM, or PPM. Consider using <I>-ext</I> or <I>-outfilepattern</I> for more specific extensions if desired.


title: INPUT AND OUTPUT
content:
<B>pnmsplit</B> reads image data from standard input (<I>stdin</I>). The output images are written to individual files in the current working directory, or to paths specified within the <I>-outfilepattern</I>.


title: USAGE EXAMPLE
content:
To split a multi-image GIF animation (after converting it to PNM) into separate PPM files named <I>frame_000.ppm</I>, <I>frame_001.ppm</I>, etc.:<br><br><I>giftoppm &lt; animation.gif | pnmsplit -outfilepattern "frame_%03d.ppm"</I><br><br>This demonstrates its common use in a pipeline with other Netpbm tools.


title: HISTORY
content:
<B>pnmsplit</B> is a core utility within the <B>Netpbm</B> package, a long-established open-source toolkit for graphics manipulation. Its design reflects the Unix philosophy of small, specialized tools that can be chained together. It has been a stable part of the Netpbm suite for many years, providing a fundamental capability for image stream processing.


title: SYNOPSIS
content:
<b>pnmtile</b> [<i>-width=<cols></i>] [<i>-height=<rows></i>] [<i>input_image</i> [<i>canvas_image</i>]]


title: PARAMETERS
content:
<b><b>-width=</b><i>cols</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the width of the output image in pixels. If not provided, and no <i>canvas_image</i> is given, the output width cannot be determined. If a <i>canvas_image</i> is provided, this defaults to the width of the <i>canvas_image</i>.<br><br><b><b>-height=</b><i>rows</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the height of the output image in pixels. Similar to <i>-width</i>, if not provided and no <i>canvas_image</i> is given, the output height cannot be determined. If a <i>canvas_image</i> is provided, this defaults to the height of the <i>canvas_image</i>.<br><br><b><i>input_image</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the image file that will be tiled. If omitted, <i>pnmtile</i> reads the image from standard input.<br><br><b><i>canvas_image</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Optional) The path to a background image file onto which the <i>input_image</i> will be tiled. If specified, the output image will have the same dimensions as this <i>canvas_image</i>. If omitted, and <i>-width</i> and <i>-height</i> are not specified, <i>pnmtile</i> will not know the output dimensions and will produce an error.<br><br>


title: DESCRIPTION
content:
<i>pnmtile</i> is a utility from the Netpbm suite of graphics manipulation tools. It takes an input image and repeatedly copies it (tiles it) to fill a specified output size, or to fill the size of a second input image. This is particularly useful for creating background patterns, wallpapers, or repeating textures from a smaller source image. The tiling can be done without gaps, creating a seamless repetition of the source image. It reads PGM, PPM, or PBM format images as input and produces an image in the same format. If no output dimensions are specified via options or a canvas image, the command will fail.


title: CAVEATS
content:
The command requires a way to determine the output dimensions (either via <i>-width</i>/<i>-height</i> options or by providing a <i>canvas_image</i>). Without this, it will fail. It expects Netpbm formats (PBM, PGM, PPM) as input; other formats need prior conversion. <i>pnmtile</i> performs simple tiling and does not offer options for spacing between tiles or starting offsets.


title: EXAMPLES
content:
Here are some common ways to use <i>pnmtile</i>:<br><br><b>1. Tile an image to a specific size:</b><br><i>pnmtile -width=800 -height=600 small_tile.pnm > tiled_image.pnm</i><br>This command tiles 'small_tile.pnm' to create an 800x600 pixel image named 'tiled_image.pnm'.<br><br><b>2. Tile an image onto an existing background:</b><br><i>pnmtile tile.pnm background.pnm > patterned_background.pnm</i><br>Here, 'tile.pnm' is repeatedly placed over 'background.pnm'. The output image will have the same dimensions as 'background.pnm'.<br><br><b>3. Pipe input from another command:</b><br><i>jpegtopnm input.jpg | pnmtile -width=1024 -height=768 > tiled_output.pnm</i><br>This example converts a JPEG image to PNM format and then tiles it to a 1024x768 resolution.


title: HISTORY
content:
<i>pnmtile</i> is part of the Netpbm package, which has a long history dating back to the <i>pbmplus</i> package created by Jef Poskanzer in 1988. Netpbm provides a fundamental set of tools for processing graphic images in various formats, emphasizing a pipeline approach where smaller, specialized tools are chained together. <i>pnmtile</i> serves its specific purpose within this philosophy, handling a common image manipulation task efficiently.


title: SYNOPSIS
content:
<b>pnmtoddif</b> [<i>options</i>] [<i>pnmfile</i>]<br><i>Example:</i> <b>pnmtoppm</b> <i>myimage.pbm</i> | <b>pnmtoddif</b> <b>-color</b> <b>-comment</b> <i>"Converted image"</i> > <i>myimage.ddif</i>


title: PARAMETERS
content:
<b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information and exits.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays version information and exits.<br><br><b><b>-color</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces output to be a color DDIF image. Only applicable if the input PNM is PPM.<br><br><b><b>-mono</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces output to be a monochrome (black and white) DDIF image.<br><br><b><b>-grayscale</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces output to be a grayscale DDIF image.<br><br><b><b>-ddiftype</b> <i>&lt;type&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the internal DDIF image representation type (e.g., RGB_DDIF, CIELab_DDIF).<br><br><b><b>-comment</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds the specified <i>string</i> as a comment in the DDIF header.<br><br><b><b>-compress</b> <i>&lt;type&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the compression method for the DDIF image. Accepted types are <i>none</i> or <i>runlength</i>.<br><br><b><b>-map</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;If applicable, uses a colormap for the output DDIF image.<br><br><b><b>-nomap</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents the use of a colormap in the output DDIF image, even if one could be used.<br><br><b><b>-alpha</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates an alpha channel (transparency) in the output DDIF image.<br><br><b><b>-noalpha</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ensures no alpha channel is included in the output DDIF image.<br><br><b><b>-pelsperinch</b> <i>&lt;value&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the horizontal and vertical resolution of the image in pixels per inch.<br><br><b><b>-title</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the document title metadata in the DDIF header.<br><br><b><b>-author</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the author metadata in the DDIF header.<br><br><b><b>-subject</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the subject metadata in the DDIF header.<br><br><b><b>-keywords</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets keywords metadata in the DDIF header, typically comma-separated.<br><br><b><b>-creator</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the creator application metadata in the DDIF header.<br><br><b><b>-date</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the creation date metadata in the DDIF header.<br><br>


title: DESCRIPTION
content:
<b>pnmtoddif</b> is a utility from the Netpbm toolkit, designed to convert images from the flexible Netpbm formats (PBM, PGM, PPM) into the Digital Document Interchange Format (DDIF). DDIF is a structured document and image interchange format primarily associated with Digital Equipment Corporation (DEC) systems and applications. This command is crucial for environments needing to interoperate with legacy DEC systems that rely on DDIF for image data.<br><br>The tool supports various image types, including monochrome, grayscale, and color, and allows for control over output characteristics such as compression (none, runlength) and resolution. It can also embed metadata like comments, titles, authors, and keywords directly into the DDIF header, ensuring robust document information preservation. By default, <b>pnmtoddif</b> reads a PNM image from standard input and writes the resulting DDIF image to standard output, making it suitable for piping in shell scripts.


title: CAVEATS
content:
DDIF is a proprietary and less commonly used format today, primarily relevant for interoperability with older Digital Equipment Corporation (DEC) systems. Conversion may result in loss of specific image properties if the DDIF format or chosen options do not support the full fidelity of the input PNM. Compression options are limited to basic <i>none</i> and <i>runlength</i>.


title: DDIF FORMAT CONTEXT
content:
The Digital Document Interchange Format (DDIF) is a proprietary format developed by Digital Equipment Corporation (DEC) for structured documents and images. It was often used in DEC's imaging and document management systems. While not widely used in modern contexts, <b>pnmtoddif</b> provides a bridge for working with legacy DDIF files.


title: STANDARD INPUT/OUTPUT
content:
Like many Netpbm utilities, <b>pnmtoddif</b> is designed to work as part of a pipeline. It reads the PNM image from standard input (stdin) if no <i>pnmfile</i> is specified and writes the resulting DDIF image to standard output (stdout). This allows easy chaining with other commands.


title: HISTORY
content:
<b>pnmtoddif</b> is a component of the comprehensive Netpbm suite, which originated from Jef Poskanzer's PBMPlus package developed in the late 1980s. The inclusion of <b>pnmtoddif</b> reflects a historical need for interoperability, particularly with Digital Equipment Corporation (DEC) systems that extensively utilized the DDIF format for image and document exchange. Its development ensured that images processed by the widely adopted Netpbm tools could be integrated into DEC's proprietary document workflows, maintaining its utility for specific legacy environments.


title: PARAMETERS
content:
<b><b>-debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable debugging output, providing more detailed information about the conversion process.<br><br><b><b>-verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output, displaying progress and additional messages during encoding.<br><br><b><b>-quality</b> <i>&lt;quality&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the compression quality from 0 to 100 (default is 75). Higher values result in better image quality but larger file sizes, and vice-versa.<br><br><b><b>-frames</b> <i>&lt;n&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limit the number of frames to encode, processing only the first <i>n</i> frames from the input stream.<br><br><b><b>-fps</b> <i>&lt;n&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the target frame rate for the output Fiasco stream in frames per second.<br><br><b><b>-start</b> <i>&lt;n&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Begin encoding from frame number <i>n</i>, skipping earlier frames.<br><br><b><b>-end</b> <i>&lt;n&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;End encoding at frame number <i>n</i>, stopping before subsequent frames.<br><br><b><b>-no_interlace</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable interlaced encoding, producing a progressive scan output.<br><br><b><b>-gray</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force grayscale output, converting color images to grayscale before encoding.<br><br><b><b>-rgray</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Convert to grayscale by averaging only the red and green color components, specific to Fiasco's internal grayscale conversion.<br><br><b><b>-no_quant</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable quantization, which can result in larger files but potentially higher fidelity.<br><br><b><b>-no_dither</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable dithering, which can affect color representation, especially for limited palettes.<br><br><b><b>-palette</b> <i>&lt;file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use a predefined color palette loaded from the specified <i>file</i> for encoding.<br><br><b><b>-dump_palette</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Dump the generated or used color palette to standard output.<br><br><b><b>-dump_quant</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Dump the quantization tables used during the encoding process.<br><br><b><b>-dump_dither</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Dump the dithering tables used.<br><br><b><b>-dump_frames</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Dump raw frame data to standard output, bypassing Fiasco encoding.<br><br><b><b>-dump_stats</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Dump encoding statistics, such as compression ratio and frame information.<br><br><b><b>-dump_raw</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Dump raw output data from the encoder.<br><br><b><b>-dump_fiasco</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Dump the Fiasco stream data directly to standard output, useful for debugging the format.<br><br><b><b>-dump_huff</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Dump Huffman tables used for entropy coding.<br><br><b><b>-dump_g721</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Dump G.721 audio data, though <b>pnmtofiasco</b> primarily handles video.<br><br><b><b>-dump_jpeg</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Dump JPEG-like internal representation data of frames.<br><br><b><b>-dump_motion</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Dump motion vector data used for inter-frame compression.<br><br><b><b>-dump_key</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Dump key frame (intra-coded) information.<br><br><b><b>-dump_delta</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Dump delta frame (inter-coded) information.<br><br><b><b>-version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display version information for the <b>pnmtofiasco</b> command.<br><br><b><i>pnmfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional input PNM file. If not specified, <b>pnmtofiasco</b> reads a sequence of PNM images from standard input.<br><br>


title: DESCRIPTION
content:
<b>pnmtofiasco</b> is a command-line utility that reads a sequence of Portable Anymap (PNM) images from standard input (or a specified file) and converts them into a Fiasco video stream. The Fiasco codec is a low-bandwidth, high-compression video codec developed by Bell Labs, optimized for network transmission. This tool enables users to encode image sequences into the Fiasco format, which can then be played by a Fiasco player or integrated into other applications requiring this specific video format. It offers various options to control compression quality, frame rate, frame range, and internal encoding processes like quantization and dithering, providing granular control over the encoding process.


title: CAVEATS
content:
While the man page states 'No known bugs,' <b>pnmtofiasco</b> converts to the Fiasco codec, which is a specialized and historically significant format developed by Bell Labs. As such, its output might not be directly compatible with modern, widely used video players or streaming platforms without further conversion. Its primary utility lies in contexts where the Fiasco format is specifically required or for historical analysis of early network video technologies.


title: INPUT/OUTPUT
content:
The command reads a sequence of PNM images from standard input by default, enabling it to be easily chained with other Netpbm tools or image processing pipelines. Alternatively, a specific <i>pnmfile</i> can be provided as an argument. The resulting Fiasco stream is written to standard output, allowing for direct piping to a Fiasco player or redirection to a file.


title: HISTORY
content:
The <b>pnmtofiasco</b> command is intrinsically linked to the Fiasco codec, a low-bandwidth, high-compression video codec developed by Bell Labs. This codec was designed for efficient video transmission over networks, reflecting early efforts in digital video streaming during the 1990s. The command likely emerged as part of a suite of tools for processing and converting media streams for this specific ecosystem, demonstrating an important phase in the evolution of video compression technology. It is often found as part of the Netpbm suite of graphics utilities, known for its extensive support for various image formats and conversions.


title: SYNOPSIS
content:
<b>pnmtofits</b> [<i>-type</i>] [<i>-input <pnmfile></i>] [<i>-output <fitsfile></i>] [<i>-header <headerstring></i>] [<i>-comment <comment_string></i>] [<i>-history <history_string></i>] [<i>-bzero <value></i>] [<i>-bscale <value></i>] [<i>-bitpix <value></i>] [<i>-naxis <value></i>] [<i>-naxis1 <value></i>] [<i>-naxis2 <value></i>] [<i><pnmfile></i>]


title: PARAMETERS
content:
<b><i>-type</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the desired output FITS data type. Options include <i>-int8</i>, <i>-int16</i>, <i>-int32</i> for integer data, and <i>-float32</i>, <i>-float64</i> for floating-point data. This option overrides the default <i>BITPIX</i> calculation.<br><br><b><i>-input <pnmfile></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Designates the path to the input PNM file. If this option is omitted, <b>pnmtofits</b> reads the PNM data from standard input (stdin).<br><br><b><i>-output <fitsfile></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path for the output FITS file. If not provided, the resulting FITS data is written to standard output (stdout).<br><br><b><i>-header <headerstring></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a raw FITS header card directly into the output FITS file. The <i><headerstring></i> should be a valid FITS header line, e.g., '<i>KEYWORD = VALUE / Comment text</i>'.<br><br><b><i>-comment <comment_string></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Inserts a <i>COMMENT</i> keyword entry into the FITS header with the provided string. This is useful for general descriptive text.<br><br><b><i>-history <history_string></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a <i>HISTORY</i> keyword entry to the FITS header with the specified string. Typically used to log processing steps or significant events related to the data.<br><br><b><i>-bzero <value></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the <i>BZERO</i> keyword in the FITS header. This value acts as an offset when converting scaled FITS pixel values to their true physical values (<i>true_value = BZERO + BSCALE * pixel_value</i>).<br><br><b><i>-bscale <value></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the <i>BSCALE</i> keyword in the FITS header. This value acts as a scaling factor when converting scaled FITS pixel values to their true physical values (<i>true_value = BZERO + BSCALE * pixel_value</i>).<br><br><b><i>-bitpix <value></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly sets the <i>BITPIX</i> keyword in the FITS header, which indicates the number of bits per data pixel (e.g., 8, 16, 32 for signed integers; -32, -64 for floating point). This overrides the command's default detection.<br><br><b><i>-naxis <value></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the <i>NAXIS</i> keyword, specifying the number of axes (dimensions) in the data array. For 2D images, this value is typically 2.<br><br><b><i>-naxis1 <value></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the <i>NAXIS1</i> keyword, representing the length or size of the first axis of the image data (e.g., the width in pixels).<br><br><b><i>-naxis2 <value></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the <i>NAXIS2</i> keyword, representing the length or size of the second axis of the image data (e.g., the height in pixels).<br><br><b><i><pnmfile></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A positional argument for the input PNM file. This serves as an alternative to using the <i>-input</i> option.<br><br>


title: DESCRIPTION
content:
The <b>pnmtofits</b> command is a specialized utility from the Netpbm suite designed to convert image files in the Portable Anymap (PNM) format (which includes PBM for bitmaps, PGM for graymaps, and PPM for pixmaps) into the Flexible Image Transport System (FITS) format. FITS is a widely adopted standard for data exchange in astronomy, astrophysics, and other scientific fields, primarily used for storing images, tables, and multidimensional data.<br><br>This command acts as a bridge between general-purpose image manipulation (offered by Netpbm) and scientific data processing. It reads a 2D PNM image from standard input or a specified file and outputs a FITS file to standard output or a specified file. <b>pnmtofits</b> intelligently determines an appropriate FITS data type (<i>BITPIX</i>) based on the input PNM's maximum value, but it also allows users to explicitly override this for specific FITS encoding requirements. Furthermore, it provides options to embed crucial metadata such as custom header keywords, comments, and history entries, which are essential for documenting scientific datasets and their provenance.


title: CAVEATS
content:
<b>pnmtofits</b> is designed specifically for converting 2-dimensional images. It does not support multi-extension FITS (MEF) files, FITS tables (binary or ASCII), or multi-dimensional data beyond two axes directly from PNM. While it attempts to choose an appropriate <i>BITPIX</i> value by default, explicit setting via <i>-bitpix</i> or <i>-type</i> might be necessary to avoid data precision loss during conversion, especially with higher bit-depth PNM inputs, or to meet specific FITS standard requirements for certain datasets.


title: FITS HEADER INFORMATION
content:
FITS files are unique in that they store not only the primary image or data array but also extensive descriptive metadata within a structured header section. Key header keywords, many of which <b>pnmtofits</b> can manage, include:<br><i>BITPIX</i>: Defines the data type and bit depth of the individual pixels (e.g., 8, 16, 32 for integers; -32, -64 for floats).<br><i>NAXIS</i>: The number of dimensions in the data array.<br><i>NAXIS1</i>, <i>NAXIS2</i>, ...: The size or length of each respective dimension.<br><i>BZERO</i>, <i>BSCALE</i>: Used for linear scaling of pixel values to their true physical units using the formula: <i>true_value = BZERO + BSCALE * pixel_value</i>.<br><b>pnmtofits</b> automatically generates a basic FITS header containing essential information from the PNM input, but users can add custom information vital for scientific analysis, data provenance, and inter-instrument compatibility.


title: DEFAULT BITPIX SELECTION LOGIC
content:
When the <i>-bitpix</i> option is not explicitly specified, <b>pnmtofits</b> applies a default logic to determine the most appropriate <i>BITPIX</i> value for the output FITS file, based on the characteristics of the input PNM image:<br>- For PBM (Portable Bitmap) input, where pixel values are binary (0 or 1), <i>BITPIX</i> typically defaults to 8.<br>- For PGM (Portable Graymap) or PPM (Portable Pixmap) input:<br>  - If the maximum pixel value (maxval) within the PNM header is 255 or less, <i>BITPIX</i> defaults to 16.<br>  - If the maximum pixel value (maxval) is greater than 255 (indicating a wider dynamic range), <i>BITPIX</i> defaults to -32 (representing single-precision floating-point numbers) to preserve higher precision values and avoid truncation.


title: HISTORY
content:
The <b>pnmtofits</b> command is an integral part of the Netpbm project, which originated from the `pbmplus` package created by Jef Poskanzer in the late 1980s. Netpbm rapidly evolved into a versatile toolkit for converting and manipulating a wide array of image formats. Concurrently, the FITS (Flexible Image Transport System) standard was developed in the late 1970s and early 1980s, specifically to facilitate the reliable exchange of astronomical data between disparate institutions and software systems. The inclusion of <b>pnmtofits</b> within the Netpbm suite allowed users to seamlessly integrate general image processing workflows with the specialized FITS data format, bridging common image utilities with the critical data archiving and analysis needs of the scientific community.


title: PARAMETERS
content:
<b>-quality N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the desired output quality level for the JPEG image. <I>N</I> is an integer between 0 (lowest quality, highest compression) and 100 (highest quality, lowest compression). The default is usually 75.<br><br><b>-optimize</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs optimization of the entropy encoding parameters. This can result in a smaller file size for the same image quality but may take longer to encode.<br><br><b>-progressive</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a progressive JPEG file. Progressive JPEGs display in a series of passes, gradually refining the image quality, which can be beneficial for web viewing.<br><br><b>-grayscale</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output JPEG image to be grayscale, even if the input PNM image is color (PPM). This is useful for reducing file size when color information is not needed.<br><br><b>-rgb</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output JPEG image to be color (RGB), even if the input PNM image is grayscale (PGM) or monochrome (PBM). Note that a PGM input will result in a color JPEG with identical R, G, B channels.<br><br><b>-smooth N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a smoothing filter to the input image before JPEG compression. <I>N</I> is an integer between 1 and 100, controlling the degree of smoothing. Higher values result in more smoothing.<br><br><b>-outfile filename</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output file for the JPEG image. If this option is not used, the JPEG image is written to standard output.<br><br><b>pnmfile</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the input PNM image file. If no file is specified, <I>pnmtojpeg</I> reads the PNM image from standard input.<br><br>


title: DESCRIPTION
content:
The <I>pnmtojpeg</I> command, part of the Netpbm suite of graphics utilities, transforms images in the Portable Anymap (PNM) format into the widely used JPEG format. It can accept any of the PNM sub-formats: PBM (Portable Bitmap), PGM (Portable Graymap), or PPM (Portable Pixmap). By default, <I>pnmtojpeg</I> reads the PNM image from standard input and writes the resulting JPEG image to standard output, allowing it to be easily integrated into shell pipelines. Users can control the JPEG compression quality, create progressive JPEGs for faster web display, and apply various other encoding options to fine-tune the output.


title: CAVEATS
content:
JPEG is a lossy compression format, meaning some image data is discarded during compression. The quality setting directly impacts the amount of data loss. Repeated re-saving of a JPEG image can lead to cumulative degradation. The <I>-arithmetic</I> option (not listed above as it's less common) produces files that may not be universally supported by older or less common JPEG decoders.


title: HISTORY
content:
<I>pnmtojpeg</I> is part of the extensive Netpbm package, a collection of utilities for manipulating graphic images. Its core functionality often relies on the widely used independent JPEG Group (IJG) library (or its successor, libjpeg-turbo), which provides the actual JPEG encoding algorithms. This connection ensures compatibility and adherence to JPEG standards. It serves as a user-friendly wrapper for <I>cjpeg</I> in many Netpbm installations, streamlining the conversion process from Netpbm's native formats to JPEG.


title: PARAMETERS
content:
<b><b>-compress</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables Palm's RLE compression for the output image. This is the default behavior.<br><br><b><b>-nocompress</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables Palm's RLE compression, potentially resulting in larger file sizes but faster decompression on the device.<br><br><b><b>-dither</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables dithering when converting to lower bit depths (e.g., from 24-bit color to 8-bit color or grayscale). This is the default.<br><br><b><b>-nodither</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables dithering. This can lead to banding or loss of detail in gradients when reducing color depth.<br><br><b><b>-color</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output to be an 8-bit color image. This is the default if the input PNM is color.<br><br><b><b>-nocolor</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output to be a grayscale image, even if the input PNM is color. This is the default if the input PNM is grayscale or monochrome.<br><br><b><b>-2gray</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output to be a 2-bit (4-level) grayscale image.<br><br><b><b>-4gray</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output to be a 4-bit (16-level) grayscale image.<br><br><b><b>-8gray</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output to be an 8-bit (256-level) grayscale image.<br><br><b><b>-idb</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs an <i>iDB</i> format image, which is a specific structure used by Palm's Image library.<br><br><b><b>-name</b> <i>&lt;db_name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the database name for the output .pdb file. Default is 'Netpbm Image'.<br><br><b><b>-creator</b> <i>&lt;creator_id&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the 4-character creator ID for the database. Default is 'PbIm'.<br><br><b><b>-type</b> <i>&lt;type_id&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the 4-character type ID for the database. Default is 'IMAG'.<br><br><b><b>-comments</b> <i>&lt;comment_string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a comment string to the image record within the database.<br><br>


title: DESCRIPTION
content:
<i>pnmtopalm</i> is a Netpbm utility that converts a Portable Anymap (PNM) image into a PalmPilot image database (.pdb) file. It supports various Palm image formats, including 1-bit monochrome, 2-bit grayscale, 4-bit grayscale, 8-bit grayscale, and 8-bit color. The command can optionally apply Palm's RLE compression to reduce file size and performs dithering for conversions to lower bit depths to maintain visual quality. The generated .pdb file is structured to be directly installable and viewable on PalmPilot devices, making it a crucial tool for preparing images for these handheld organizers.


title: CAVEATS
content:
Given the widespread obsolescence of PalmPilot devices, <i>pnmtopalm</i> is primarily a historical tool or useful for enthusiasts and emulation purposes. The .pdb format created is specific to these older platforms and not generally compatible with modern image viewers or mobile devices.<br><br>The quality of conversion, especially for color images, is limited by the capabilities of the original Palm devices, which often had restricted color palettes.


title: INPUT AND OUTPUT
content:
By default, <i>pnmtopalm</i> reads the PNM image data from standard input (stdin) and writes the resulting PalmPilot .pdb file to standard output (stdout).<br><br>Alternatively, an input file path (<i>pnmfile</i>) can be specified as the last argument, in which case the command reads from that file instead of stdin.


title: SUPPORTED PALM IMAGE FORMATS
content:
<i>pnmtopalm</i> can generate images in several Palm-compatible formats:<br>1-bit monochrome (black and white)<br>2-bit grayscale (4 levels)<br>4-bit grayscale (16 levels)<br>8-bit grayscale (256 levels)<br>8-bit color (256 colors, typically from a fixed palette)<br><br>The command attempts to select the best format based on the input PNM and specified options, or can be forced to a specific grayscale depth.


title: HISTORY
content:
<i>pnmtopalm</i> is an integral part of the Netpbm graphics toolkit, a venerable suite of image processing utilities that has been in continuous development since the early days of Unix. Its inclusion highlights Netpbm's commitment to supporting a wide array of image formats and devices, even niche or historical ones like the PalmPilot. The command was developed to bridge the gap between standard image formats (PNM) and the proprietary image formats required by Palm OS devices, allowing users to transfer and view their images on early handheld organizers.


title: SYNOPSIS
content:
<b>pnmtopam</b> [<I>pnmfile</I>]<br><br><i>Input is read from standard input if <I>pnmfile</I> is not specified. Output is written to standard output.</i>


title: PARAMETERS
content:
<b>-tupletype=<name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i><br>Specifies the tuple type name for the output PAM header. This can describe the semantic meaning of the channels, e.g., RGB, GRAYSCALE, etc.</i><br><br><b>-alpha</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i><br>Adds an opaque alpha channel to the output PAM image. The alpha value will be the maximum possible value for the deepness.</i><br><br><b>-alphaval=<value></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i><br>Adds an alpha channel to the output PAM image, setting all alpha values to the specified <I>value</I>. This allows for a uniform transparency.</i><br><br><b>-verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i><br>Prints informative messages about the input and output formats, including the maximum value and dimensions.</i><br><br><b>-forceplain</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i><br>Forces the output PAM to be in plain (ASCII) format, even if the input was raw (binary). By default, <b>pnmtopam</b> produces raw PAM output.</i><br><br>


title: DESCRIPTION
content:
<i>pnmtopam</i> is a Netpbm utility that converts an image in the Portable Anymap (PNM) format (which includes Portable Bitmap PBM, Portable Graymap PGM, and Portable Pixmap PPM) into the Portable Arbitrary Map (PAM) format. The PAM format is a more general and flexible Netpbm format that can handle an arbitrary number of planes (channels) and arbitrary tuple types.<br><br>This command essentially upgrades a classic PNM file to the more modern PAM structure, preserving the image data. It's particularly useful when you need to process images with tools that exclusively work with PAM, or when you intend to add an alpha channel to an existing PNM image, as PAM inherently supports multiple channels beyond the basic RGB.


title: CAVEATS
content:
<i><b>pnmtopam</b> primarily performs a format conversion. It does not perform image manipulation or color space conversions beyond what's implied by adding an alpha channel. The output PAM file will have the same dimensions and basic pixel data as the input PNM file.</i>


title: <I>STANDARD INPUT/OUTPUT</I>
content:
<i><br>Like most Netpbm commands, <b>pnmtopam</b> is designed to work as a filter in a pipeline. If no input file is specified, it reads from standard input. The converted PAM output is always written to standard output, making it easy to chain with other Netpbm utilities or redirect to a file.</i>


title: HISTORY
content:
<i><b>pnmtopam</b> is part of the Netpbm project, a toolkit for graphic file conversion and manipulation. Netpbm originated from Jef Poskanzer's Pbmplus package in the late 1980s. The PAM format was introduced later as a more flexible evolution of the original PNM formats, allowing for arbitrary numbers of image channels and more descriptive headers. <b>pnmtopam</b> was developed to bridge the gap, enabling older PNM files to be integrated into workflows that utilize the more powerful PAM format.</i>


title: PARAMETERS
content:
<b><b>-width=</b><I>width</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scales the image to the specified <I>width</I> in inches.<br><br><b><b>-height=</b><I>height</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scales the image to the specified <I>height</I> in inches.<br><br><b><b>-xscale=</b><I>xscale</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scales the image horizontally by the factor <I>xscale</I>.<br><br><b><b>-yscale=</b><I>yscale</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scales the image vertically by the factor <I>yscale</I>.<br><br><b><b>-scale=</b><I>scale</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scales the image uniformly by the factor <I>scale</I> in both X and Y directions.<br><br><b><b>-gray</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the PCL XL data in grayscale. If the input PNM is color, it will be converted to grayscale.<br><br><b><b>-rgb</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the PCL XL data using the RGB color space. This is the default for color images.<br><br><b><b>-cmyk</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the PCL XL data using the CMYK color space.<br><br><b><b>-compress=</b>{<I>none</I>|<I>rle</I>|<I>jpeg</I>|<I>delta</I>}</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the compression method for the image data: <I>none</I> (no compression), <I>rle</I> (Run-Length Encoding), <I>jpeg</I> (JPEG compression), or <I>delta</I>.<br><br><b><b>-landscape</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the page orientation to landscape.<br><br><b><b>-resolution=</b><I>dpi</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the output resolution in dots per inch (<I>dpi</I>).<br><br><b><b>-pagesize=</b>{<I>A3</I>|<I>A4</I>|<I>A5</I>|<I>B4</I>|<I>B5</I>|<I>executive</I>|<I>folio</I>|<I>jisb4</I>|<I>jisb5</I>|<I>ledger</I>|<I>legal</I>|<I>letter</I>|<I>monarch</I>|<I>number10</I>|<I>tabloid</I>}</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the standard page size for the output document.<br><br><b><b>-pageleft=</b><I>left</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the left margin of the image on the page in inches.<br><br><b><b>-pagetop=</b><I>top</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the top margin of the image on the page in inches.<br><br><b><b>-multipagemode</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables a mode where <I>pnmtopclxl</I> does not close the PCL XL page after processing an image, allowing multiple concatenated <I>pnmtopclxl</I> outputs to form a single PCL XL document with multiple images on one or more pages.<br><br><b><I>pnmfile</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The input PNM image file. If omitted, <I>pnmtopclxl</I> reads from standard input.<br><br>


title: DESCRIPTION
content:
The <b>pnmtopclxl</b> command is a utility from the Netpbm project designed to convert <I>PNM (Portable Anymap)</I> image files into <I>PCL XL (Printer Command Language XL)</I> format. PCL XL is a page description language primarily used by modern <I>Hewlett-Packard (HP)</I> printers. This command takes a PNM image (which can be PBM, PGM, or PPM) as input, either from a specified file or standard input, and outputs the corresponding PCL XL data to standard output.<br><br>It supports various options for scaling, setting output resolution, defining page sizes and margins, selecting color spaces (grayscale, RGB, CMYK), and choosing compression methods. This makes it a versatile tool for preparing images for direct printing on PCL XL compatible printers, especially when precise control over image rendering on the page is required for automated workflows or custom print solutions.


title: CAVEATS
content:
This command implements a subset of the complex PCL XL specification. While it is suitable for converting image data for printing, it is not designed for general document generation. Compatibility with all PCL XL printers may vary, especially with older or non-HP models that might not fully support the PCL XL standard.


title: STANDARD INPUT/OUTPUT
content:
Like most Netpbm tools, <b>pnmtopclxl</b> typically reads the PNM image from standard input if no <I>pnmfile</I> argument is provided, and writes the PCL XL output to standard output. This design facilitates piping commands together, for example, <I>convert input.jpg pnm:- | pnmtopclxl - &gt; output.pclxl</I>.


title: PCL XL BACKGROUND
content:
<I>PCL XL</I> (also known as <I>PCL 6 Enhanced</I>) is a binary, object-oriented printer language introduced by HP to provide improved performance and features over older PCL versions. It is designed to be more efficient for graphics and text rendering, often used for direct print streams to laser printers.


title: HISTORY
content:
<b>pnmtopclxl</b> is a component of the <I>Netpbm</I> graphics toolkit, a widely used suite of command-line tools for image manipulation. Netpbm itself originated from the <I>PBMPLUS</I> package created by Jef Poskanzer in the late 1980s. Over the years, Netpbm has grown to include hundreds of utilities, with <b>pnmtopclxl</b> being added to support the PCL XL format, which became prevalent with newer HP printers. It continues to be maintained as part of the Netpbm project, providing essential image format conversion capabilities in Unix-like environments.


title: DESCRIPTION
content:
<i>pnmtoplainpnm</i> reads a PNM (Portable Anymap) image from standard input or a specified file and converts it to its plain (ASCII) format. The input can be a PBM (Portable Bitmap), PGM (Portable Graymap), or PPM (Portable Pixmap) file. The output will correspond to the input type (e.g., PBM to plain PBM, PGM to plain PGM, PPM to plain PPM).<br><br>Plain PNM files are represented using human-readable ASCII characters, making them suitable for inspection, debugging, or use with tools that expect text-based input. In contrast, "raw" PNM files are binary, generally smaller, and faster for machine processing. This command effectively transforms the binary raw format into its text-based equivalent, or ensures a text-based format if the input was already plain.


title: PARAMETERS
content:
<b><b>-interlace</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates an interlaced PNG file using the Adam7 algorithm, which allows a rough image to be displayed quickly and refined over time in web browsers.<br><br><b><b>-transparent</b> <i>color</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines a specific <i>color</i> (e.g., 'red', '#RRGGBB', or a pixel value like '0 0 0' for black) in the input image to be transparent in the output PNG. Only one color can be specified.<br><br><b><b>-alpha</b> <i>alpha_file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a separate PGM or PBM file to be used as the alpha channel for the output PNG, allowing for per-pixel transparency.<br><br><b><b>-gamma</b> <i>value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the gamma value for the output PNG image. This can be used for display calibration or to correct image brightness, typically a floating-point number (e.g., 2.2).<br><br><b><b>-compression</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the compression level for the PNG output. <i>N</i> is an integer from 0 (no compression, fastest) to 9 (maximum compression, slowest). The default is typically 6.<br><br><b><b>-text</b> "<i>key=value</i>"</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a text chunk to the PNG metadata. Multiple <b>-text</b> options can be used to add multiple key-value pairs (e.g., 'Author=John Doe').<br><br><b><b>-time</b> <i>time_spec</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the modification time of the image in the PNG metadata. <i>time_spec</i> can be 'now' or a specific date/time string format (e.g., 'YYYY-MM-DD HH:MM:SS').<br><br><b><b>-comment</b> "<i>text</i>"</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a comment chunk to the PNG metadata, which is typically a short descriptive string.<br><br><b><b>-force_rgb</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output PNG to be RGB (24-bit) even if the image could otherwise be represented as an indexed color (palette) image.<br><br><b><b>-force_indexed</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output PNG to be an indexed color image if possible, potentially reducing file size for images with 256 or fewer unique colors.<br><br><b><b>-verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints informative messages about the conversion process, such as input/output format detection and compression details, to standard error.<br><br>


title: DESCRIPTION
content:
<i>pnmtopng</i> is a versatile command-line utility from the Netpbm suite, designed to convert Portable Anymap (PNM) images into the Portable Network Graphics (PNG) format. PNM encompasses PBM (Portable Bitmap), PGM (Portable Graymap), and PPM (Portable Pixmap) formats. This tool is essential for preparing Netpbm-generated or processed images for web use or other applications that require the widely supported and lossless PNG format. It supports various PNG features like interlacing, transparency, gamma correction, and adjustable compression levels, making it a flexible choice for image conversion tasks. It typically reads PNM data from standard input or a specified file and writes the PNG output to standard output.


title: CAVEATS
content:
<b>pnmtopng</b> strictly expects a valid PNM (PBM, PGM, or PPM) stream as input; invalid input will result in errors and premature exit. It does not support creating animated PNGs (APNG). When using <b>-transparent</b>, only a single specified color is made transparent, unless an alpha channel file is provided with <b>-alpha</b> for per-pixel transparency.


title: INPUT/OUTPUT STREAM PROCESSING
content:
By default, <b>pnmtopng</b> reads PNM data from standard input (stdin) and writes the resulting PNG data to standard output (stdout). This design principle is common in Netpbm utilities, enabling powerful command chaining via pipes. For example: <br><code><B>anytoppm</B> <i>image.jpg</i> | <B>pnmtopng</B> > <i>image.png</i></code><br>This command converts a JPEG image to PNM, then pipes the PNM data to <b>pnmtopng</b> to convert it to PNG.


