# CommandSection

title: SUPPORTED PNG COLOR TYPES
content:
Depending on the input PNM format (PBM, PGM, PPM) and the options used, <b>pnmtopng</b> can generate PNGs with various color types:<br><ul><li>Grayscale (for PGM input)</li><li>Grayscale with alpha (with <b>-alpha</b>)</li><li>Truecolor (RGB for PPM input)</li><li>Truecolor with alpha (RGBA for PPM input with <b>-alpha</b>)</li><li>Indexed color (palette-based for PBM/PGM/PPM with limited colors, often forced by <b>-force_indexed</b>)</li></ul>The tool intelligently selects the most appropriate PNG color type unless overridden by specific options.


title: HISTORY
content:
<b>pnmtopng</b> is an integral part of the <B>Netpbm</B> project, an open-source package of graphics programs and programming libraries. Netpbm originated from the earlier PBMplus package, developed by Jef Poskanzer in the late 1980s. It has been a standard Unix utility for basic image manipulation and conversion for decades, known for its modular design where tools often work together by piping data, with PNM being the common intermediate format. Its development has focused on robustness and broad compatibility across different image types.


title: SYNOPSIS
content:
<i>pnmtops</i> [<i>pnmfile</i>] [<i>-equalize</i>] [<i>-forceplain</i>] [<i>-noturn</i>] [<i>-magnification</i> <i>factor</i>] [<i>-xoffset</i> <i>offset</i>] [<i>-yoffset</i> <i>offset</i>] [<i>-width</i> <i>width</i>] [<i>-height</i> <i>height</i>] [<i>-xresolution</i> <i>res</i>] [<i>-yresolution</i> <i>res</i>] [<i>-grayscale</i>] [<i>-color</i>] [<i>-level1</i>] [<i>-level2</i>] [<i>-level3</i>] [<i>-encapsulated</i>] [<i>-printer</i> <i>type</i>] [<i>-setpage</i>] [<i>-dpi</i> <i>dpi</i>] [<i>-rle</i>] [<i>-nofit</i>] [<i>-portrait</i>] [<i>-landscape</i>] [<i>-orientation</i> <i>degrees</i>] [<i>-nomargin</i>] [<i>-pagesize</i> <i>pagesize</i>] [<i>-headerstring</i> <i>string</i>] [<i>-footerstring</i> <i>string</i>]


title: PARAMETERS
content:
<b>-equalize</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Equalize all colors, effectively applying a gamma correction to the image.<br><br><b>-forceplain</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generate plain (uncompressed) PostScript output, even if compression is typically used.<br><br><b>-noturn</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not rotate the image to fit the page; preserve its original orientation.<br><br><b>-magnification <I>factor</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Magnify the image by the specified numeric <I>factor</I>.<br><br><b>-xoffset <I>offset</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the x-offset of the image from the left edge of the page, in points.<br><br><b>-yoffset <I>offset</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the y-offset of the image from the bottom edge of the page, in points.<br><br><b>-width <I>width</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scale the image to the specified <I>width</I> in points.<br><br><b>-height <I>height</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scale the image to the specified <I>height</I> in points.<br><br><b>-xresolution <I>res</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the x-resolution for the output image, in pixels per inch.<br><br><b>-yresolution <I>res</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the y-resolution for the output image, in pixels per inch.<br><br><b>-grayscale</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force grayscale PostScript output, even if the input image is color.<br><br><b>-color</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force color PostScript output. This option primarily affects printers configured as grayscale.<br><br><b>-level1</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generate PostScript Level 1 output. This is the default if no printer type is specified.<br><br><b>-level2</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generate PostScript Level 2 output. This is often the default with specific printer types.<br><br><b>-level3</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generate PostScript Level 3 output.<br><br><b>-encapsulated</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generate Encapsulated PostScript (EPS) output, which suppresses the `showpage` command.<br><br><b>-printer <I>type</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the printer <I>type</I> (e.g., 'ps', 'pscolor', 'psgray'), influencing PostScript level and compression.<br><br><b>-setpage</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Include a `setpage` command in the output, which can be useful for some older printers.<br><br><b>-dpi <I>dpi</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set both x and y resolution to the specified dots per inch (<I>dpi</I>).<br><br><b>-rle</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly use RLE (Run Length Encoding) compression for the image data in the PostScript output.<br><br><b>-nofit</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable automatic fitting of the image onto the page through scaling or rotation.<br><br><b>-portrait</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force portrait page orientation for the output.<br><br><b>-landscape</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force landscape page orientation for the output.<br><br><b>-orientation <I>degrees</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set a custom page orientation in <I>degrees</I> (0, 90, 180, 270).<br><br><b>-nomargin</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress the default 1/2 inch page margins.<br><br><b>-pagesize <I>pagesize</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the paper <I>pagesize</I>, e.g., 'letter' or 'a4'.<br><br><b>-headerstring <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add a custom <I>string</I> to the PostScript header section.<br><br><b>-footerstring <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add a custom <I>string</I> to the PostScript footer section.<br><br><b><I>pnmfile</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The input PNM file to convert. If omitted, <i>pnmtops</i> reads the image data from standard input.<br><br>


title: DESCRIPTION
content:
<i>pnmtops</i> is a utility from the <b>Netpbm</b> project designed to convert a Portable Anymap (PNM) image file into a PostScript file. This conversion is particularly useful for printing images on PostScript-compatible printers or for embedding images into PostScript documents. <br><br> The command can handle various PNM formats, including PBM (Portable Bitmap), PGM (Portable Graymap), and PPM (Portable Pixmap). It offers options to control aspects of the output, such as image scaling, positioning on the page, and color handling. Users can specify the PostScript level, the page size, and whether the output should be Encapsulated PostScript (EPS). <br><br> <i>pnmtops</i> ensures that the resulting PostScript file is self-contained and suitable for direct printing or inclusion in other PostScript workflows. It intelligently handles image dimensions and can produce both grayscale and color PostScript output based on the input PNM type.


title: CAVEATS
content:
<i>pnmtops</i> only supports PostScript Level 1, 2, and 3, and may not utilize newer PostScript features. <br><br> Color management is basic and does not perform sophisticated color space conversions. <br><br> Output quality is directly dependent on the input PNM image's resolution and quality; scaling up significantly can lead to visible pixelation.


title: INPUT/OUTPUT
content:
<i>pnmtops</i> typically reads a PNM image from standard input if no file is specified, and writes the PostScript output to standard output. This allows for easy piping with other Netpbm utilities or redirection to a file or printer. For example: <br> <i>pnmfile | pnmtops > output.ps</i> <br> or <br> <i>pnmtops input.pnm | lpr</i>


title: PAGE DIMENSIONS
content:
Unless explicitly specified with options like <i>-width</i>, <i>-height</i>, <i>-xresolution</i>, <i>-yresolution</i>, or <i>-dpi</i>, <i>pnmtops</i> attempts to determine reasonable dimensions for the output based on the input image and default page size. When explicit dimensions are given, they take precedence. The default page size is typically A4 or Letter, depending on the system's locale settings.


title: HISTORY
content:
<i>pnmtops</i> is a core utility of the <b>Netpbm</b> package, a toolkit of graphics programs for converting, manipulating, and viewing images. The Netpbm project has roots dating back to the early 1990s, evolving from the PBMplus package. <i>pnmtops</i> has been a fundamental component since its early days, providing a reliable way to generate PostScript output from the ubiquitous Netpbm image formats. Its design emphasizes simplicity and robustness, making it a staple for command-line image processing and printing on Unix-like systems. Its development has focused on maintaining compatibility with various PostScript levels and ensuring efficient output for a wide range of printers.


title: SYNOPSIS
content:
pnmtorast [-std_rle] [-overall_width=<I>N</I>] [-overall_height=<I>N</I>] [-force_indexed] [<I>pnmfile</I>]


title: PARAMETERS
content:
<b>-std_rle</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Produces an old-style RLE compressed rasterfile instead of a new-style one.<br><br><b>-overall_width=<I>N</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the output rasterfile width to <I>N</I> pixels, padding with black if the input is smaller.<br><br><b>-overall_height=<I>N</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the output rasterfile height to <I>N</I> pixels, padding with black if the input is smaller.<br><br><b>-force_indexed</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output to be an 8-bit indexed color rasterfile, even for direct color input.<br><br><b><I>pnmfile</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The PNM input file. If omitted, input is read from standard input.<br><br>


title: DESCRIPTION
content:
<b>pnmtorast</b> converts a Portable Anymap (PNM) image file (PBM, PGM, or PPM) into a Sun Rasterfile. It reads the PNM input from a specified file or standard input and writes the Sun Rasterfile output to standard output. The command intelligently selects the most appropriate Sun Rasterfile variant based on the input PNM type, for example, generating monochrome for PBM or 24-bit direct color for PPM. It can also be forced to produce specific rasterfile types like 8-bit indexed color.


title: CAVEATS
content:
The Sun Rasterfile format has multiple variants; <b>pnmtorast</b> chooses the most appropriate one automatically. Explicit options may override this. Output is always sent to standard output. Using <b>-overall_width</b> or <b>-overall_height</b> will pad the image with black if the original is smaller.


title: INPUT/OUTPUT BEHAVIOR
content:
<b>pnmtorast</b> reads its PNM input from the file specified on the command line, or from standard input if no file is given. It always writes the resulting Sun Rasterfile to standard output.


title: HISTORY
content:
<b>pnmtorast</b> is a component of the Netpbm project, a long-established toolkit for graphics manipulation. Its development and usage are intertwined with the history of Netpbm, providing robust image format conversions for decades.


title: DESCRIPTION
content:
<B>pnmtorle</B> is a utility from the <I>Netpbm</I> suite of graphics manipulation tools. Its primary function is to convert image files from the Portable Anymap (PNM) format into the Utah Run Length Encoded (RLE) format. The PNM format is a versatile family that includes Portable Pixmap (PPM) for color images, Portable Graymap (PGM) for grayscale, and Portable Bitmap (PBM) for black-and-white images. <br><br>The command reads a PNM image either from standard input or from a specified file. It then processes the image data and outputs the converted RLE image to standard output. RLE is a simple form of data compression that works by storing sequences of identical data values as a single value and count, making it effective for images with large areas of uniform color. While less common today, RLE was historically significant in computer graphics for efficient storage and transmission of images, particularly in certain rendering and scientific visualization applications. <B>pnmtorle</B> is valuable for workflows requiring interconversion with this specific legacy format.


title: CAVEATS
content:
The RLE format is an older image format and is not as widely supported or as efficient for general photographic images as modern formats like PNG or JPEG. Its compression effectiveness is highly dependent on the image content, performing best on images with large contiguous blocks of the same color. The output format is specifically Utah RLE, which might not be universally compatible with all RLE decoders. <B>pnmtorle</B> expects a valid PNM input; malformed input may lead to errors or corrupted output. As it doesn't support options like scaling or color depth adjustment, input PNM characteristics directly influence the output RLE.


title: INPUT/OUTPUT BEHAVIOR
content:
<B>pnmtorle</B> operates by reading its input from a specified <I>pnmfile</I>. If no filename is provided, it defaults to reading the PNM image data from standard input (<I>stdin</I>). The resulting RLE image data is always written to standard output (<I>stdout</I>). This design facilitates its use in command-line pipelines, allowing for seamless integration with other Netpbm tools or external commands, such as <I>"<B>some_command</B> | <B>pnmtorle</B> | <B>another_command</B>"</I> for complex image processing workflows.


title: HISTORY
content:
The <B>pnmtorle</B> command is an integral part of the Netpbm project, which originated from Jef Poskanzer's Pbmplus package developed in the late 1980s. Pbmplus was conceived to provide a flexible and modular toolkit for manipulating image files, built around the simple yet powerful Portable Anymap formats. <br><br>As image processing became more prevalent, tools like <B>pnmtorle</B> were created to enable conversion between Netpbm's internal formats and other common (at the time) image standards, such as Utah RLE, which was used in graphics applications and systems like the Evans & Sutherland Picture System. The Netpbm project has continued to evolve and be maintained, ensuring these fundamental image conversion capabilities remain available and compatible with contemporary Unix-like systems.


title: SYNOPSIS
content:
<b>pnmtosgi</b> [<I>-verbose</I>] [<I>-b</I>|<I>-l</I>] [<I>-c</I>] [<I>-r</I>|<I>-g</I>] [<I>-a</I>|<I>-alpha</I>] [<I>-n</I>] [<I>-h</I>] [<I>-o output_file</I>] [<I>input_file</I>]


title: PARAMETERS
content:
<b><I>-verbose</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints informational messages about the conversion process to standard error.<br><br><b><I>-b</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces big-endian byte order in the output SGI file. SGI files are typically big-endian.<br><br><b><I>-l</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces little-endian byte order in the output SGI file. SGI image files are typically big-endian, so this option is rarely used.<br><br><b><I>-c</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stores the image data in <I>CM_RLE</I> (Run Length Encoded) format, which can reduce file size for images with large uniform areas. Default is uncompressed <I>CM_RGB</I>.<br><br><b><I>-r</I> or <I>-g</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stores the image data in <I>CM_32BIT_RGB</I> format, using 32 bits per pixel for RGB data.<br><br><b><I>-a</I> or <I>-alpha</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stores the image data in <I>CM_32BIT_ALPHA</I> format, including a 32-bit alpha channel for transparency. This requires the input PNM to provide alpha channel information.<br><br><b><I>-n</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stores only the SGI header information, with no image data (<I>CM_NODATA</I>).<br><br><b><I>-h</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stores the image data in <I>CM_SCREEN</I> format, typically 8-bit, which is a display-optimized format.<br><br><b><I>-o output_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the name of the output SGI image file. If omitted, the output is written to standard output.<br><br><b><I>input_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the name of the input PNM image file. If omitted, the input is read from standard input.<br><br>


title: DESCRIPTION
content:
<b>pnmtosgi</b> is a utility from the Netpbm image manipulation toolkit. It converts image files in the Portable Anymap (PNM) format (which includes Portable Bitmap - PBM, Portable Graymap - PGM, and Portable Pixmap - PPM) into the SGI (Silicon Graphics Image) format, also known as IRIS RGB. This command is particularly useful for interoperability with older graphics systems or applications that natively support SGI image files. It can handle various SGI storage types, including standard RGB, 32-bit RGB, and 32-bit alpha channels, and can also apply run-length encoding. The input PNM image is read from standard input by default, and the resulting SGI image is written to standard output, unless an output file is specified using the <I>-o</I> option.


title: CAVEATS
content:
The SGI image format (IRIS RGB) is an older format and is less commonly used today compared to modern formats like PNG or JPEG.<br>Not all PNM features (e.g., arbitrary color depths) may map perfectly to SGI's fixed depth capabilities, potentially leading to data loss or approximation.<br>Alpha channel support (<I>-a</I> or <I>-alpha</I>) depends on the input PNM containing an alpha channel (e.g., generated by <I>pamstack</I> or <I>pnmalpha</I>). Otherwise, the alpha channel may be empty or ignored.<br>The <I>-r</I> and <I>-g</I> options are redundant and both set the output to <I>CM_32BIT_RGB</I>.


title: NETPBM SUITE
content:
<b>pnmtosgi</b> is one of hundreds of tools in the Netpbm suite. Netpbm commands often operate on standard input/output, allowing them to be easily chained together in pipelines to perform complex image manipulations.


title: IMAGE INTEROPERABILITY
content:
This command serves as a bridge between the highly flexible PNM format and the specific SGI format, enabling data exchange in environments where the SGI format is required, especially for older or specialized systems.


title: HISTORY
content:
<b>pnmtosgi</b> is part of the Netpbm project, a long-standing toolkit for graphics manipulation that originated from the Pbmplus package developed in the late 1980s by Jef Poskanzer. The SGI image format itself (IRIS RGB) was developed by Silicon Graphics for their workstations in the 1980s and early 1990s, becoming a common format in professional graphics environments before the widespread adoption of more generic image formats. <b>pnmtosgi</b> was created to facilitate interoperability between the versatile Netpbm suite and systems that relied on SGI's native image format. Its relevance has diminished somewhat with the decline of SGI workstations and the rise of more modern, universally supported image formats, but it remains a valuable tool for legacy systems or specific niche applications.


title: DESCRIPTION
content:
<b>pnmtosir</b> is a Netpbm utility designed to transform images from the widely used Portable Anymap (PNM) format into the specific Set Of Lines (SIR) image format. The PNM family includes PBM (Portable Bitmap for black & white), PGM (Portable Graymap for grayscale), and PPM (Portable Pixmap for color) files, known for their simplicity and broad compatibility within the Netpbm suite.<br><br>The SIR format, conversely, is an older, often proprietary image format, notably associated with systems like SunVision. This command acts as a bridge, facilitating interoperability between modern Netpbm workflows and legacy systems or applications that require images in the SIR format.<br><br><b>pnmtosir</b> reads the input PNM image either from standard input or a specified file and outputs the converted SIR image to standard output. This design makes it highly suitable for use in shell pipelines, where it can be combined with other Netpbm tools for comprehensive image processing tasks. It's a fundamental tool for format conversion, enabling data exchange across different image ecosystems.


title: CAVEATS
content:
The SIR format is considerably less common and more archaic compared to contemporary image formats, limiting its general applicability.<br><br><b>pnmtosir</b> focuses solely on format conversion; it does not offer functionalities for image manipulation such as resizing, rotation, or color correction. For such operations, other Netpbm utilities should be used prior to or after conversion.<br><br>Input must be a valid PNM image. The command will report an error if the input file is malformed or in an unsupported format.<br><br>Output is always directed to standard output. To save the converted SIR image to a file, output redirection (e.g., &gt; output.sir) is necessary.


title: INPUT AND OUTPUT
content:
The command reads a Portable Anymap (PNM) image from either standard input (if <i>pnmfile</i> is omitted) or a specified file. The resulting Set Of Lines (SIR) image is then written to standard output. This design is highly conducive to command-line piping, allowing <b>pnmtosir</b> to seamlessly integrate into complex image processing workflows.


title: SUPPORTED FORMATS
content:
<b>Input:</b> Portable Anymap (PNM), which includes Portable Bitmap (PBM), Portable Graymap (PGM), and Portable Pixmap (PPM) formats.<br><br><b>Output:</b> Set Of Lines (SIR), an older proprietary image format often associated with SunVision.


title: HISTORY
content:
<b>pnmtosir</b> is an integral part of the Netpbm project, which traces its origins back to Jef Poskanzer's PBMplus package, initially developed in the late 1980s. The Netpbm suite adheres to a Unix philosophy, providing numerous small, specialized tools designed to work together through pipes.<br><br>The inclusion of <b>pnmtosir</b> specifically addresses the historical need for interoperability with various proprietary image formats that were prevalent in specific computing environments, such as Sun workstations and their associated graphics software like SunVision.<br><br>It was officially added to the Netpbm suite in Netpbm 10.3 in August 2002. The command continues to be maintained as part of the Netpbm collection, ensuring ongoing support for converting to and from legacy formats and facilitating broader data compatibility.


title: SYNOPSIS
content:
<i>openssl s_client</i> [-connect <i>host</i>:<i>port</i>] [-servername <i>name</i>] [-ssl2|-ssl3|-tls1_1|-tls1_2|-tls1_3] [-cipher <i>alg</i>] [-ciphersuites <i>str</i>] [-CAfile <i>file</i>] [-cert <i>file</i>] [-key <i>file</i>] [-verify <i>depth</i>] [-showcerts] [-debug] [-msg] [-state] [-status] [-starttls <i>protocol</i>] [<i>options</i>...]


title: PARAMETERS
content:
<b><b>-connect</b> <i>host</i>:<i>port</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the remote server address and port to connect to. This is often the most common option.<br><br><b><b>-servername</b> <i>name</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the Server Name Indication (SNI) hostname. Essential for accessing virtual hosts on servers that use SNI.<br><br><b><b>-ssl2</b> | <b>-ssl3</b> | <b>-tls1</b> | <b>-tls1_1</b> | <b>-tls1_2</b> | <b>-tls1_3</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the use of a specific SSL/TLS protocol version. Note that SSLv2 and SSLv3 are deprecated and often disabled.<br><br><b><b>-cipher</b> <i>alg</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the list of acceptable TLSv1.2 (or older) cipher suites. Use <i>openssl ciphers</i> to list available options.<br><br><b><b>-ciphersuites</b> <i>str</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the list of acceptable TLSv1.3 cipher suites.<br><br><b><b>-CAfile</b> <i>file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a file containing trusted Certificate Authority (CA) certificates. Used for verifying the server's certificate.<br><br><b><b>-CApath</b> <i>dir</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a directory containing trusted CA certificates. Certificates must be hashed and symlinked correctly.<br><br><b><b>-cert</b> <i>file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the client's certificate file (PEM format) for client authentication.<br><br><b><b>-key</b> <i>file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the client's private key file (PEM format) corresponding to the client certificate.<br><br><b><b>-verify</b> <i>depth</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum depth for the certificate chain verification. A value of 0 means only the peer certificate is verified.<br><br><b><b>-showcerts</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays all certificates in the server's certificate chain received during the handshake.<br><br><b><b>-debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints extensive debug information about the handshake process, including hex dumps of protocol messages.<br><br><b><b>-msg</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows verbose information about the protocol messages exchanged during the handshake.<br><br><b><b>-state</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints out the SSL session states as they change during the handshake.<br><br><b><b>-status</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Requests an OCSP (Online Certificate Status Protocol) status response from the server if supported (OCSP stapling).<br><br><b><b>-starttls</b> <i>protocol</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Negotiates STARTTLS for a specified application protocol (e.g., <i>smtp</i>, <i>pop3</i>, <i>ftp</i>, <i>imap</i>, <i>xmpp</i>, <i>ldap</i>). Converts an insecure connection to a secure one.<br><br><b><b>-quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses output of the certificates and other default handshake information, showing only errors and interactive output.<br><br><b><b>-reconnect</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attempts to reconnect to the server after the initial handshake, often used to test session reuse.<br><br><b><b>-no_ticket</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables the use of RFC 5077 session tickets (stateless session resumption).<br><br><b><b>-keylog</b> <i>file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Logs TLS key material to the specified file in NSS Key Log Format, allowing tools like Wireshark to decrypt the TLS traffic.<br><br>


title: DESCRIPTION
content:
<i>openssl s_client</i> is a powerful command-line tool within the OpenSSL toolkit, primarily used for interacting with and diagnosing SSL/TLS servers. It acts as a client, establishing a secure connection to a specified host and port, then allowing interactive communication.<br><br>This utility is invaluable for system administrators, network engineers, and developers. It helps in debugging connectivity issues, inspecting server certificate chains, verifying server configurations (like supported protocol versions and cipher suites), and testing client certificate authentication. After a successful handshake, it typically forwards standard input to the server and prints server output to standard output, enabling low-level protocol interaction and analysis.


title: CAVEATS
content:
<b><br>Deprecated Protocols:</b> Older SSL/TLS protocol versions (e.g., SSLv2, SSLv3) are highly insecure and typically disabled by default in modern OpenSSL builds and on most servers. Attempting to use them may result in connection failures.<br><br><b>Certificate Verification:</b> Correct certificate verification requires trusted CA certificates to be properly configured via <b>-CAfile</b> or <b>-CApath</b>. Without proper CA trust, the client may accept untrusted certificates, or reject valid ones.<br><br><b>Verbose Output:</b> The default output can be very verbose, especially with debugging options. Understanding the output requires familiarity with SSL/TLS handshake processes and certificate structures.


title: COMMON USE CASES
content:
<i>openssl s_client</i> is widely used for:<br><br><b>Debugging Handshake Failures:</b> Identifying why a TLS connection fails (e.g., protocol mismatch, cipher mismatch, certificate issues).<br><br><b>Inspecting Server Certificates:</b> Viewing the server's certificate details, validity, issuer, and the entire certificate chain (with <b>-showcerts</b>).<br><br><b>Testing Protocol and Cipher Support:</b> Verifying which TLS versions and cipher suites a server supports and prefers.<br><br><b>Verifying SNI Configuration:</b> Ensuring that servers correctly respond to different hostnames via SNI.<br><br><b>Client Certificate Authentication:</b> Testing client-side authentication by providing a client certificate and key.<br><br><b>STARTTLS Services:</b> Connecting to services like SMTP, POP3, IMAP, or LDAP that upgrade an initial plain-text connection to TLS.


title: INTERACTIVE MODE
content:
After a successful TLS handshake, <i>openssl s_client</i> enters an interactive mode. Any input typed into the console is sent to the remote server over the secure channel, and any data received from the server is displayed. This allows for manual interaction with application protocols, such as sending HTTP GET requests, SMTP commands, or other plain-text protocol messages over the established secure connection. Pressing <b>Ctrl+D</b> (EOF) typically closes the input stream, allowing the server to finish sending data before the connection closes.


title: HISTORY
content:
The <i>openssl s_client</i> command has been a core component of the OpenSSL toolkit since its inception, tracing back to the SSLeay library developed by Eric Young and Tim Hudson in the mid-1990s. As the SSL/TLS protocols evolved from SSLv2 to TLSv1.3, <i>s_client</i> has continually been updated to support new features like Server Name Indication (SNI), OCSP stapling, TLS session tickets, and various new cipher suites and extensions. Its enduring utility lies in its flexibility as a debugging and diagnostic tool for network security, mirroring the development and adoption of secure communication standards across the internet.


title: SEE ALSO
content:
openssl(1), openssl-s_server(1), openssl-x509(1), openssl-genrsa(1), openssl-req(1), openssl-ciphers(1)


title: DESCRIPTION
content:
<i>pbmtonokia</i> is a specialized utility from the Netpbm suite that reads a Portable Bitmap (PBM) image from standard input and converts it into a binary format suitable for monochrome LCD displays found in older Nokia phones, such as the Nokia 3310 or 8210. These displays typically feature specific resolutions and require a particular byte ordering and pixel-packing scheme for image data. The command enables users to prepare simple graphics or custom startup logos for these legacy devices. It serves as a bridge between the widely used Netpbm image formats and the proprietary display requirements of specific hardware, making it valuable for embedded systems development, retro computing projects, or historical data conversion.


title: CAVEATS
content:
This command is designed exclusively for older monochrome Nokia phone displays (e.g., Nokia 3310, 8210) and is incompatible with modern color screens or other display technologies. The input PBM image <b>must</b> precisely match the target Nokia display's resolution (e.g., 84x48 pixels for a Nokia 3310); scaling or cropping is not performed by this command. The output is raw binary data, not a graphical image file format, and is intended for direct interfacing with display drivers.


title: USAGE EXAMPLE
content:
To convert a PBM file named <i>image.pbm</i> to Nokia format and save the binary output to <i>nokia_logo.bin</i>, you would typically pipe the PBM data to <i>pbmtonokia</i>:<br><br><code>cat image.pbm | pbmtonokia > nokia_logo.bin</code><br><br>Ensure that <i>image.pbm</i> has the correct dimensions (e.g., 84x48 pixels) for your target Nokia display.


title: INPUT AND OUTPUT
content:
The command reads a PBM (Portable Bitmap) image from standard input (stdin) and writes the Nokia-specific binary data to standard output (stdout). It operates as a simple filter and does not accept any command-line options to modify its conversion behavior.


title: HISTORY
content:
<i>pbmtonokia</i> is a component of the long-standing Netpbm package, a collection of graphics conversion tools developed primarily for Unix-like operating systems. It was created to address a specific niche need during the late 1990s and early 2000s: enabling users to generate custom graphics for the monochrome LCD screens prevalent in popular Nokia feature phones. While the command's primary utility has waned with the advent of smartphones, it remains relevant for embedded systems development, retro computing enthusiasts, and projects requiring interaction with legacy hardware.


title: SYNOPSIS
content:
<b>pbzip2</b> [<i>options</i>] [<i>files...</i>]<br><b>pbzip2</b> <b>-d</b> [<i>options</i>] [<i>files...</i>]<br><b>pbzip2</b> <b>-c</b> [<i>options</i>] [<i>files...</i>]<br><i>(If no files are specified, <b>pbzip2</b> processes standard input/output)</i>


title: PARAMETERS
content:
<b><b>-d</b>, <b>--decompress</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force <b>pbzip2</b> to operate in decompression mode, extracting content from <i>.bz2</i> files.<br><br><b><b>-k</b>, <b>--keep</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Retain (do not delete) input files after successful compression or decompression. By default, input files are removed upon successful processing.<br><br><b><b>-p</b>, <b>--processors</b> <i>&lt;N&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the number of processors (CPU cores or threads) to utilize for compression or decompression. This is the primary control for parallelism. If omitted, <b>pbzip2</b> typically attempts to use all available CPU cores.<br><br><b><b>-f</b>, <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force overwrite of any existing output files without prompting for confirmation. Use with caution to prevent unintentional data loss.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output, displaying more detailed information about the processing progress, such as file names and compression/decompression rates.<br><br><b><b>-b</b>, <b>--blocksize</b> <i>&lt;N&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the compression block size in 100-kilobyte units (ranging from 1 to 9, with 9 being the default). Larger block sizes can sometimes yield slightly better compression ratios but may consume more memory and potentially limit parallelism for very small files.<br><br><b><b>-m</b>, <b>--megabytes</b> <i>&lt;N&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Define the maximum amount of memory (in megabytes) that each processing thread can use. This option helps manage overall memory consumption, particularly when using a large number of threads.<br><br>


title: DESCRIPTION
content:
<b>pbzip2</b> is a <I>parallel implementation</I> of <b>bzip2</b>, specifically designed to take advantage of multi-core and multi-processor systems.<br>It utilizes <I>PThreads</I> to split the compression or decompression task across multiple CPU cores, thereby significantly speeding up operations on large files compared to the single-threaded <b>bzip2</b> utility.<br>The output produced by <b>pbzip2</b> is fully compatible with standard <b>bzip2</b>, meaning files compressed with <b>pbzip2</b> can be seamlessly decompressed by <b>bzip2</b> (and vice-versa).<br>This tool is particularly useful in environments where the high compression ratios of <b>bzip2</b> are desired, but single-threaded performance would be a bottleneck, such as in large-scale data archiving, backups, and high-performance computing scenarios.


title: CAVEATS
content:
While <b>pbzip2</b> significantly speeds up <b>bzip2</b> operations on multi-core systems, it has some limitations:<br>For very small files, the overhead of managing parallel threads might negate performance benefits or even lead to slower processing compared to single-threaded <b>bzip2</b>.<br>Memory consumption can become substantial when using a high number of threads in conjunction with large block sizes (e.g., the default 900KB per block).<br>The degree of parallelism is inherently limited by the input file size and the inherent compressibility characteristics of the data within; highly compressible data or tiny files may not fully utilize all cores.


title: STANDARD INPUT/OUTPUT
content:
<b>pbzip2</b> is designed to work seamlessly with standard input (<i>stdin</i>) and standard output (<i>stdout</i>). This capability makes it extremely versatile for piping with other Linux commands. For example, you can compress a <i>tar</i> archive directly: `tar cf - . | pbzip2 > archive.tar.bz2`, or decompress one: `pbzip2 -d < archive.tar.bz2 | tar xf -`.


title: EXIT STATUS
content:
Upon successful completion of its operation, <b>pbzip2</b> returns an exit status of <b>0</b>. Any non-zero exit status indicates that an error occurred or the process terminated abnormally. This behavior is crucial for scripting, allowing for robust error handling and conditional execution within automated workflows.


title: HISTORY
content:
The original <b>bzip2</b> compression algorithm was developed by Julian Seward in the late 1990s, known for its strong compression ratios. However, it was designed as a single-threaded application.<br>As multi-core processors became ubiquitous, the single-threaded nature of <b>bzip2</b> became a significant bottleneck for large datasets. To address this, <b>pbzip2</b> was initiated by Jeff Gilchrist, aiming to bring parallel processing capabilities to the existing <b>bzip2</b> algorithm.<br>Its development focused on leveraging the increasing core counts in modern CPUs, making <b>bzip2</b>'s excellent compression performance more practical and efficient for large-scale data processing without requiring a redesign of the fundamental compression algorithm.


title: SYNOPSIS
content:
<b>pdfattach</b> [<i>options</i>] <i>&lt;PDF-file&gt;</i> <i>&lt;file-to-attach&gt;</i> [<i>file-to-attach...</i>] <i>&lt;output-PDF-file&gt;</i>


title: PARAMETERS
content:
<b><b>-id</b> <i>&lt;name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the file ID for the embedded file dictionary. This can be used by PDF viewers to refer to the attachment by a specific identifier.<br><br><b><b>-desc</b> <i>&lt;text&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a human-readable description for the embedded file, which may be displayed in PDF viewers.<br><br><b><b>-mimetype</b> <i>&lt;mime-type&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the MIME type of the embedded file (e.g., "application/xml", "image/jpeg"). This helps viewers determine how to handle the file.<br><br><b><b>-creator</b> <i>&lt;text&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the creator application or person for the embedded file, similar to the Creator metadata in PDF documents.<br><br><b><b>-creationdate</b> <i>&lt;date-string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the creation date of the embedded file. The date string format is <b>D:YYYYMMDDHHmmSS[+|-HH'mm']</b> (e.g., <b>D:20231027153000+01'00'</b>).<br><br><b><b>-moddate</b> <i>&lt;date-string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the modification date of the embedded file. The format is the same as for <b>-creationdate</b>.<br><br><b><b>-print</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a flag indicating that the embedded file can be printed by the user.<br><br><b><b>-hidden</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a flag indicating that the embedded file should be hidden from the user interface of a PDF viewer.<br><br><b><b>-nosave</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a flag indicating that the embedded file should not be allowed to be saved by the user.<br><br><b><b>-nosaveas</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a flag indicating that the embedded file should not be allowed to be saved with a new name by the user.<br><br><b><b>-nocopy</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a flag indicating that the embedded file should not be allowed to be copied by the user.<br><br><b><b>-noprint</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a flag indicating that the embedded file should not be allowed to be printed by the user.<br><br><b><b>-v</b><br><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the copyright and version information for <i>pdfattach</i> and exits.<br><br><b><b>-h</b><br><b>-help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays usage information for the command and exits.<br><br>


title: DESCRIPTION
content:
<i>pdfattach</i> is a command-line utility from the Poppler project designed to embed one or more arbitrary files directly into a Portable Document Format (PDF) document. Instead of linking to external files, <i>pdfattach</i> physically stores the files within the PDF, ensuring that they travel with the document. This can be useful for including source code, images, spreadsheets, or any other data that supplements the PDF content.<br><br>The command takes an existing PDF file, the file(s) to be attached, and outputs a new PDF file with the embedded attachments. Users can access these attachments through a PDF viewer's attachment panel, where they can view, save, or open the embedded files. <i>pdfattach</i> provides various options to specify metadata like description, MIME type, creator, and dates for the embedded files, enhancing their discoverability and management within the PDF.


title: CAVEATS
content:
<ul><li><i>pdfattach</i> always creates a <b>new</b> PDF file. The original input PDF remains unchanged.</li><li>Embedding large files can significantly increase the size of the resulting PDF document, potentially making it slower to load or share.</li><li>The embedded files are not directly visible within the PDF's pages; they are typically accessible through a PDF viewer's attachment pane, often found in a sidebar or menu.</li></ul>


title: AUTHORS
content:
The Poppler developers are credited with creating and maintaining <i>pdfattach</i> and the other Poppler utilities.


title: BUGS
content:
Reports concerning <i>pdfattach</i> or other Poppler utilities can typically be filed via the Poppler project's bug tracking system, often linked from their official website or source code repository.


title: HISTORY
content:
<i>pdfattach</i> is an integral part of the Poppler utilities, an open-source library for rendering PDF documents. Poppler originated as a fork of the Xpdf project in 2005, aiming to provide improved features and maintain an active development pace. It provides a comprehensive set of command-line tools for various PDF manipulation tasks, including attaching and detaching files. Its development continues as part of the broader FreeDesktop.org project, ensuring compatibility with PDF standards and offering robust functionality for Linux and other Unix-like systems.


title: PARAMETERS
content:
<b><b>-f</b> <i>&lt;page&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Specifies the first page to scan.</I><br><br><b><b>-l</b> <i>&lt;page&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Specifies the last page to scan.</I><br><br><b><b>-j</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Write JPEG images as is.</I><br><br><b><b>-jp2</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Write JPX (JPEG2000) images as is.</I><br><br><b><b>-jbig2</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Write JBIG2 images as is.</I><br><br><b><b>-all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Write all supported image types as is (equivalent to -j -jp2 -jbig2).</I><br><br><b><b>-png</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Write images in PNG format (implies -rgb, -gray, or -mono based on color depth).</I><br><br><b><b>-tiff</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Write images in TIFF format (implies -rgb, -gray, or -mono based on color depth).</I><br><br><b><b>-list</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>List images and their properties without extracting them.</I><br><br><b><b>-opw</b> <i>&lt;password&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Specify the owner password for encrypted files.</I><br><br><b><b>-upw</b> <i>&lt;password&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Specify the user password for encrypted files.</I><br><br><b><b>-r</b> <i>&lt;resolution&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Specify the resolution (in DPI) for rasterized images. Default is 150 DPI.</I><br><br><b><b>-mono</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Generate monochrome PBM images.</I><br><br><b><b>-gray</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Generate grayscale PGM images.</I><br><br><b><b>-rgb</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Generate color PPM images.</I><br><br>


title: DESCRIPTION
content:
<I><b>pdfimages</b> is a command-line utility for extracting raster images (bitmaps) from Portable Document Format (PDF) files. It is part of the <b>poppler-utils</b> package, which provides a set of tools built on the Poppler PDF rendering library. This command is particularly useful for designers, developers, or anyone needing to reuse graphical content embedded within a PDF document without resorting to screen captures or opening the document in a specific editor.</I><br><br><I>The tool can identify various image formats within a PDF, such as JPEG, JPEG2000, JBIG2, CCITT, and raw bitmap data. When extracting, <b>pdfimages</b> attempts to save the images in their original format if possible, especially for JPEG, JPEG2000, and JBIG2 formats. For other formats, or if an image is encoded in a way that isn't directly extractable as a standard image file, <b>pdfimages</b> will convert it into a common image format like PPM (for color), PGM (for grayscale), or PBM (for monochrome), or optionally into PNG or TIFF.</I><br><br><I>It provides options to specify page ranges, output image types, and even handle password-protected PDF files. The extracted images are named based on a user-defined root name, appended with a sequence number and the appropriate file extension. This makes <b>pdfimages</b> an invaluable tool for content extraction and analysis.</I>


title: CAVEATS
content:
<I><b>pdfimages</b> primarily extracts raster images. It cannot extract vector graphics (like those created in Adobe Illustrator or CAD programs) or text objects directly as editable formats. Such elements, if not explicitly rasterized within the PDF, would typically require a different tool (e.g., <b>pdftocairo</b> for SVG output, or <b>pdftotext</b> for text).</I><br><br><I>Images that are not stored in a directly extractable format (JPEG, JPX, JBIG2) are converted to PBM/PGM/PPM, PNG, or TIFF, which might involve re-encoding and potential loss of quality, especially if a lower resolution is specified or implied. Some PDF viewers or editors might display content that <b>pdfimages</b> cannot directly identify as a distinct image object.</I>


title: OUTPUT NAMING CONVENTION
content:
<I><b>pdfimages</b> names the extracted files using the specified <i>&lt;image-root-name&gt;</i> followed by a hyphen, a four-digit sequence number, and the appropriate file extension (e.g., <I>root-name-0001.jpg</I>, <I>root-name-0002.png</I>).</I>


title: DEFAULT OUTPUT FORMATS
content:
<I>If no specific output format (like <b>-j</b>, <b>-png</b>, <b>-tiff</b>, <b>-mono</b>, <b>-gray</b>, <b>-rgb</b>) is chosen, <b>pdfimages</b> will default to creating PPM (color), PGM (grayscale), or PBM (monochrome) files, depending on the image's color depth. It prioritizes direct extraction for JPEG, JPX, and JBIG2 if possible, unless a specific conversion format like PNG or TIFF is requested.</I>


title: HISTORY
content:
<I><b>pdfimages</b> is part of the Poppler utilities, which are derived from the Xpdf project. Xpdf was originally developed by Derek Noonburg. Poppler is a free software fork of Xpdf, initiated in 2005, and continues to be actively developed, maintained by the freedesktop.org project. Its goal was to provide better free software support for PDF rendering and tools, moving beyond Xpdf's more restrictive licensing at the time. <b>pdfimages</b> has been a fundamental tool within both Xpdf and Poppler for image extraction from their early versions.</I>


title: PARAMETERS
content:
<b>-output-directory=<I>dir</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Write all output files (PDF, log, aux, etc.) to the specified <i>dir</i>.<br><br><b>-jobname=<I>name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use <i>name</i> for the base name of output files instead of the input file's name.<br><br><b>-interaction=<I>mode</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the interaction mode (e.g., <i>batchmode</i>, <i>nonstopmode</i>, <i>scrollmode</i>, <i>errorstopmode</i>) which controls how the program handles errors and user input.<br><br><b>-halt-on-error</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exit with an error code immediately upon encountering the first error during compilation.<br><br><b>-file-line-error</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print error messages in the format <i>filename:linenumber:error_description</i>, making it easier to locate issues.<br><br><b>-shell-escape</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable the <i>\write18{...}</i> primitive, allowing LaTeX to execute arbitrary shell commands. <I>Use with extreme caution due to security implications.</I><br><br><b>-version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the <b>pdflatex</b> version information and exit.<br><br><b>-help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message with command-line options and exit.<br><br>


title: DESCRIPTION
content:
<b>pdflatex</b> is the primary program for typesetting TeX and LaTeX source files directly into the Portable Document Format (PDF). It is an integral part of modern TeX distributions like TeX Live and MiKTeX, offering a streamlined workflow compared to the traditional DVI-to-PS-to-PDF toolchain (e.g., <i>latex</i> -> <i>dvips</i> -> <i>ps2pdf</i>).<br><br>It processes <i>.tex</i> files, resolves cross-references, generates tables of contents, and incorporates figures and other elements, ultimately producing a <i>.pdf</i> output file. One of its key advantages is the direct embedding of fonts and graphics, leading to highly portable and visually consistent documents across different platforms.<br><br>While <b>pdflatex</b> is powerful, it often requires multiple compilation passes to resolve all internal references correctly. It also handles image formats like PNG and JPG natively, but traditionally requires PostScript images (EPS) to be converted (e.g., using <i>epstopdf</i>) before inclusion. Its direct PDF output capabilities make it the preferred choice for most modern LaTeX document production.


title: CAVEATS
content:
<b>Multiple Passes:</b> For documents with cross-references, bibliographies, or tables of contents, <b>pdflatex</b> often requires multiple compilation passes (e.g., 2-3 times) to resolve all internal references correctly.<br><br><b>Image Formats:</b> While <b>pdflatex</b> natively supports raster images (PNG, JPG) and vector images (PDF), it does not directly embed PostScript (EPS) files. These typically need conversion to PDF first, often using utilities like <i>epstopdf</i>.<br><br><b>Security (<i>-shell-escape</i>):</b> Enabling <i>-shell-escape</i> (or <i>-enable-write18</i>) allows arbitrary commands to be executed on your system via <i>\write18{...}</i> in the TeX source. This poses a significant security risk if compiling untrusted documents. It should be used with extreme caution and only for trusted sources.


title: TYPICAL COMPILATION WORKFLOW
content:
To compile a document named <i>mydoc.tex</i>, you typically run: <b>pdflatex mydoc.tex</b>.<br><br>After the first run, <i>.aux</i>, <i>.log</i>, and potentially <i>.toc</i>, <i>.lof</i>, <i>.lot</i> files are generated. To resolve all internal references (like table of contents, citations, cross-references), it's often necessary to run <b>pdflatex mydoc.tex</b> at least one or two more times.<br><br>For documents with bibliographies, you might run <b>bibtex mydoc</b> between <b>pdflatex</b> runs.<br><br>Many users employ build tools like <b>latexmk</b> or <b>arara</b> to automate these multiple passes and tool invocations, streamlining the compilation process.


title: HISTORY
content:
<b>pdflatex</b> emerged as a significant evolution of the original <i>latex</i> engine (which primarily produced DVI output) to directly generate PDF files. This development was driven by the increasing prevalence of PDF as a universal document exchange format and the desire for a simpler, integrated workflow.<br><br>It became a standard component of modern TeX distributions, significantly simplifying the process of creating high-quality PDF documents from LaTeX source. By directly producing PDF, it eliminated the need for separate DVI-to-PostScript and PostScript-to-PDF conversion steps, making it the de-facto standard for LaTeX compilation in many contemporary setups.


title: SYNOPSIS
content:
<I>pdfseparate</I> [<I>-f &lt;int&gt;</I>] [<I>-l &lt;int&gt;</I>] [<I>-v</I>] [<I>-h</I>] <I>input.pdf output-pattern.pdf</I>


title: PARAMETERS
content:
<b><I>input.pdf</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the source PDF file from which pages will be extracted.<br><br><b><I>output-pattern.pdf</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The naming pattern for the output PDF files. This pattern <B>must</B> contain a <B>%d</B> placeholder, which will be replaced by the page number. For example, <I>chapter_%d.pdf</I> will produce <I>chapter_1.pdf</I>, <I>chapter_2.pdf</I>, etc.<br><br><b><B>-f &lt;int&gt;</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the first page to extract. Pages are numbered starting from 1. If omitted, extraction starts from the first page.<br><br><b><B>-l &lt;int&gt;</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the last page to extract. Pages are numbered starting from 1. If omitted, extraction continues to the last page of the document.<br><br><b><B>-v</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints copyright and version information about the <I>pdfseparate</I> utility.<br><br><b><B>-h</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief usage message and exits.<br><br>


title: DESCRIPTION
content:
<I>pdfseparate</I> is a command-line utility from the Poppler PDF rendering library designed for extracting individual pages or a specified range of pages from a Portable Document Format (PDF) file. It operates by taking an input PDF document and an output filename pattern. The output pattern is crucial as it dictates how the newly created single-page PDF files will be named. Specifically, the pattern <B>must</B> contain a <B>%d</B> placeholder, which <I>pdfseparate</I> dynamically replaces with the sequential page number during the extraction process. For instance, if the pattern is <I>chapter_%d.pdf</I>, it will generate files like <I>chapter_1.pdf</I>, <I>chapter_2.pdf</I>, and so on. This tool is highly effective for breaking down large PDF documents into smaller, more manageable files, or for isolating specific content for further processing or distribution. It simplifies tasks such as creating individual chapter files from a book or extracting specific forms from a compilation.


title: CAVEATS
content:
The output filename pattern <B>must</B> include the <B>%d</B> placeholder for page numbering, otherwise <I>pdfseparate</I> will not work as expected.<br>This command extracts contiguous page ranges. To extract non-contiguous or specific individual pages, you would typically need to run <I>pdfseparate</I> multiple times with different <B>-f</B> and <B>-l</B> parameters, or use a more advanced PDF manipulation tool.<br>It's important to ensure that the output directory for the separated PDF files exists and that you have write permissions to it.


title: USAGE EXAMPLES
content:
<b>1. Extract all pages from a PDF:</b><br><I>pdfseparate input.pdf output_page_%d.pdf</I><br>This will create files named <I>output_page_1.pdf</I>, <I>output_page_2.pdf</I>, and so on, for every page in <I>input.pdf</I>.<br><br><b>2. Extract pages from 5 to 10:</b><br><I>pdfseparate -f 5 -l 10 document.pdf doc_page_%d.pdf</I><br>This will extract pages 5 through 10 from <I>document.pdf</I>, naming them <I>doc_page_5.pdf</I> to <I>doc_page_10.pdf</I>.


title: HISTORY
content:
<I>pdfseparate</I> is a component of the Poppler utilities, a free software PDF rendering library. Poppler originated from the Xpdf project and has been a staple in Linux and Unix-like operating systems for robust PDF document manipulation, offering a reliable command-line interface for tasks like page extraction.


title: SYNOPSIS
content:
<b>pdftk</b> <I>input_pdf_files</I> <I>operation</I> [<b>output</b> <I>output_file</I>] [<I>options</I>]<br><br><b>Examples:</b><br><i>Merge:</i> <b>pdftk</b> <i>doc1.pdf doc2.pdf</i> <b>cat</b> <b>output</b> <i>combined.pdf</i><br><i>Split:</i> <b>pdftk</b> <i>input.pdf</i> <b>burst</b><br><i>Rotate:</i> <b>pdftk</b> <i>in.pdf</i> <b>cat</b> <i>1-endS</i> <b>output</b> <i>out.pdf</i>


title: PARAMETERS
content:
<b><b>cat</b> <I>page_ranges</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Concatenates (merges) multiple PDF documents or selected pages/page ranges into a single output file.<br><br><b><b>burst</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Splits a single input PDF into individual pages, creating separate PDF files for each page.<br><br><b><b>fill_form</b> <I>data_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Fills interactive PDF forms using data from an FDF or XFDF file.<br><br><b><b>dump_data_fields</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all form fields found in a PDF document, including their names and types, to standard output.<br><br><b><b>background</b> <I>bg_pdf</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a PDF file as a background layer to the input PDF pages.<br><br><b><b>stamp</b> <I>stamp_pdf</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a PDF file as a stamp (overlay) layer on top of the input PDF pages.<br><br><b><b>encrypt</b> <I>strength</I> <b>user_pw</b> <I>password</I> [<b>owner_pw</b> <I>password</I>] [<b>allow</b> <I>permissions</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Encrypts a PDF document with specified password(s) and permissions (e.g., printing, copying).<br><br><b><b>decrypt</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Decrypts an encrypted PDF document, typically requiring the correct password.<br><br><b><b>update_info</b> <I>data_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Updates the metadata (e.g., Author, Title, Subject) of a PDF from a data file or key-value pairs.<br><br><b><b>rotate</b> <I>page_selection</I><I>direction</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Rotates specified pages within a PDF by 90, 180, or 270 degrees. Directions are <i>N</i> (0/360), <i>E</i> (90), <i>S</i> (180), <i>W</i> (270).<br><br><b><b>output</b> <I>filename</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the name of the output PDF file. This is mandatory for most operations.<br><br>


title: DESCRIPTION
content:
<i>pdftk</i> (PDF Toolkit) is a powerful and versatile command-line utility for manipulating PDF documents. It allows users to perform a wide array of operations such as merging multiple PDF files into one, splitting a single PDF into individual pages or page ranges, rotating pages, watermarking documents, encrypting and decrypting PDFs, filling PDF forms with FDF/XFDF data, and collecting data from PDF forms.<br><br>Designed for scripting and automation, <i>pdftk</i> operates directly on PDF data structures, making it a fast and efficient tool for batch processing PDF files without requiring a graphical interface. While highly functional, its development has largely stalled, and newer alternatives like <i>qpdf</i> or <i>pypdf</i> might be preferred on modern systems. Nevertheless, <i>pdftk</i> remains a go-to tool for many complex PDF manipulation tasks via the command line.


title: CAVEATS
content:
<i>pdftk</i> is no longer actively maintained upstream (since around 2012-2013 for the original C++ version).<br>Installation can be challenging on modern Linux distributions, often requiring older dependencies or manual compilation.<br>Error handling can sometimes be cryptic, making debugging difficult.<br>It does not render PDFs; it only manipulates their internal structure.


title: DEPENDENCY
content:
The functionality of <i>pdftk</i> is largely based on the iText Java library for its core PDF manipulation capabilities. The <i>pdftk-java</i> variant explicitly relies on a Java Runtime Environment (JRE).


title: COMMAND-LINE INTERFACE (CLI)
content:
<i>pdftk</i>'s primary strength lies in its CLI nature, making it exceptionally well-suited for scripting, batch processing, and integration into automated workflows without the need for a graphical user interface.


title: HISTORY
content:
<i>pdftk</i> was originally developed by Sid Steward in C++ and released around 2002, quickly gaining popularity for its powerful command-line capabilities. Later, a Java port, <i>pdftk-java</i>, was created, providing similar functionality. The original C++ project ceased active development around 2012-2013, leading to its unmaintained status in many distribution repositories. Despite this, it remains a widely used tool for complex PDF manipulation tasks, though more modern and actively maintained alternatives like <i>qpdf</i> are increasingly recommended.


title: PARAMETERS
content:
<b>-f <page></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the first page to convert.<br><br><b>-l <page></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the last page to convert.<br><br><b>-r <dpi></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the resolution in DPI (dots per inch).<br><br><b>-scale-to <pixels></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scales output image to specified width, preserving aspect ratio.<br><br><b>-scale-to-x <pixels></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scales output image to specified width.<br><br><b>-scale-to-y <pixels></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scales output image to specified height.<br><br><b>-jpeg</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates JPEG image files.<br><br><b>-png</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates PNG image files.<br><br><b>-mono</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates monochrome (1-bit) images.<br><br><b>-gray</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates grayscale (8-bit) images.<br><br><b>-rgb</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates color (24-bit) images (default).<br><br><b>-cropbox</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses the PDF's crop box instead of media box.<br><br><b>-q</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses all messages and errors.<br><br>


title: DESCRIPTION
content:
<i><b>pdftoppm</b></i> is a command-line utility used to convert pages from a Portable Document Format (PDF) file into various image formats, primarily PPM (Portable Pixmap) but also PNM, PNG, and JPEG. It's an essential tool for users needing to extract visual content from PDFs or render PDF pages as raster images for further processing or display.<br><br>The command offers a wide range of options to control the output, including resolution (DPI), page range, image format, color space, and compression. It's often used in scripting environments to automate the generation of thumbnails or full-page image representations of PDF documents. <i><b>pdftoppm</b></i> is part of the Poppler rendering library, which is a free software library for rendering PDF documents, inheriting much of its functionality from the Xpdf project.


title: CAVEATS
content:
High resolution conversions can consume significant memory and CPU resources. Font rendering fidelity may vary depending on available system fonts. By default, output files are named using a pattern like `<i>[prefix]-[page_number].ppm</i>`.


title: OUTPUT FILE NAMING CONVENTION
content:
When converting a single page, the output file will be named `<i>[output-file-prefix].ppm</i>` (or .png/.jpeg if specified). For multiple pages, <i><b>pdftoppm</b></i> appends a hyphen and the six-digit page number (e.g., `<i>output-000001.ppm</i>`). If no output file prefix is provided, the base name of the input PDF file is used as the prefix.


title: DEFAULT OUTPUT FORMAT
content:
The default output format is PPM (Portable Pixmap). Users can explicitly choose PNG or JPEG formats using the `<i>-png</i>` or `<i>-jpeg</i>` options respectively.


title: HISTORY
content:
Originating from the Xpdf project, <i><b>pdftoppm</b></i> is now maintained as part of the Poppler PDF rendering library. Poppler provides a free software solution for rendering PDF documents, and its development focuses on accurate and efficient PDF processing.


title: PARAMETERS
content:
<b><b>-f</b> <i><int></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the first page to convert.<br><br><b><b>-l</b> <i><int></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the last page to convert.<br><br><b><b>-o</b> <i><string></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output PostScript file name. If omitted, output goes to standard output.<br><br><b><b>-level1</b>, <b>-level2</b>, <b>-level3</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates PostScript output conforming to language level 1, 2, or 3 respectively.<br><br><b><b>-paper</b> <i><string></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the paper size (e.g., <i>letter</i>, <i>A4</i>).<br><br><b><b>-paperw</b> <i><int></i>, <b>-paperh</b> <i><int></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets custom paper width and height in points.<br><br><b><b>-r</b> <i><float></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the resolution for rasterized content in DPI.<br><br><b><b>-eps</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates Encapsulated PostScript (EPS). This implies <b>-level2</b>.<br><br><b><b>-form</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates a PostScript form suitable for embedding.<br><br><b><b>-duplex</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the Duplex flag in the PostScript output.<br><br><b><b>-nocrop</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables cropping pages to the CropBox.<br><br><b><b>-opw</b> <i><string></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the owner password for encrypted PDF files.<br><br><b><b>-upw</b> <i><string></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the user password for encrypted PDF files.<br><br><b><b>-q</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses all error and informational messages.<br><br><b><b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints copyright and version information.<br><br>


title: DESCRIPTION
content:
<i>pdftops</i> is a command-line utility used to convert Portable Document Format (PDF) files into PostScript. This conversion is often necessary for printing PDF documents on PostScript-only printers, or for further processing with PostScript-aware applications. It supports various PostScript language levels (Level 1, 2, 3) and allows for control over output characteristics such as resolution, paper size, page range, and whether to generate Encapsulated PostScript (EPS) or PostScript Forms. The utility handles fonts, images, and vector graphics within the PDF, attempting to preserve the original document's layout and appearance in the PostScript output.


title: CAVEATS
content:
The PostScript output can sometimes be significantly larger than the original PDF, especially if the PDF contains complex vector graphics or transparency effects that need to be rasterized. <br>Font issues may occur if fonts are not embedded or if substitutions are inaccurate. <br>Password-protected PDFs require the correct user or owner password for conversion.


title: RETURN CODES
content:
Returns 0 on success, or a non-zero exit code on error. Common errors include file not found, incorrect password, or invalid options.


title: CONFIGURATION FILES
content:
In some configurations, <i>pdftops</i> may use printer-specific PostScript prolog files to customize the output. These are typically located in system-specific directories (e.g., <i>/etc/poppler/printers.conf</i> or similar).


title: HISTORY
content:
<i>pdftops</i> is part of the Poppler rendering library, which itself originated from the Xpdf project. Xpdf was developed by Derek Noonburg and released in 1998, providing the foundational PDF rendering engine. The Poppler library forked from Xpdf in 2005 to foster a more open development model, and <i>pdftops</i> has been a core utility within this suite, evolving to support newer PDF features and PostScript standards. Its continuous development aims to provide accurate and efficient PDF to PostScript conversion on Linux and other Unix-like systems.


title: PARAMETERS
content:
<b>--path <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the directory where the torrent content will be downloaded.<br><br><b>--port <port></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the port for the local HTTP streaming server.<br><br><b>--vlc</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Opens the torrent stream directly in VLC media player.<br><br><b>--mplayer</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Opens the torrent stream directly in MPlayer.<br><br><b>--mpv</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Opens the torrent stream directly in MPV media player.<br><br><b>--player <app></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a custom media player application to open the stream.<br><br><b>--list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a list of files contained within the torrent without starting the download.<br><br><b>--file <index></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects a specific file by its index from the torrent to stream, useful for multi-file torrents.<br><br><b>--remove</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deletes the downloaded files and created server on exit.<br><br><b>--stdout</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pipes the torrent stream directly to standard output, useful for piping to other tools.<br><br><b>--subtitles <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Loads an external subtitle file for the streamed content.<br><br><b>--airplay</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Streams the torrent content to an AirPlay-enabled device.<br><br><b>--chromecast</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Streams the torrent content to a Chromecast device.<br><br><b>--peer <ip:port></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manually adds a peer to connect to for the torrent.<br><br><b>--quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses verbose output during streaming.<br><br><b>--verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables detailed logging output for debugging.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the current version of peerflix.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the command's help message and available options.<br><br>


title: DESCRIPTION
content:
<b>peerflix</b> is a command-line tool that enables instant streaming of torrent content directly to a media player such as VLC, MPlayer, or MPV, without waiting for the entire file to download. It acts as a lightweight torrent client that prioritizes the initial parts of the file to allow for immediate playback, buffering the rest in the background. It supports magnet links, <I>.torrent</I> files, and info hashes. Beyond local playback, <b>peerflix</b> can also stream to network devices like Chromecast and AirPlay, making it a versatile tool for consuming media from torrents. Its simplicity and effectiveness make it a popular choice for quick access to torrented video content.


title: CAVEATS
content:
<ul><li><b>peerflix</b> requires Node.js and npm to be installed for its initial setup.</li><li>The quality of streaming depends heavily on the number of available peers and network speed.</li><li>Some media players might have issues with non-standard video formats or codecs.</li><li>The <I>--remove</I> option deletes files immediately after streaming, so ensure you don't need them later.</li></ul>


title: INSTALLATION
content:
<b>peerflix</b> is typically installed via npm:<br> <I>npm install -g peerflix</I><br>This makes it accessible globally from the command line.


title: USAGE EXAMPLE
content:
To stream a torrent using a magnet link and open it in VLC:<br> <I>peerflix 'magnet:?xt=urn:btih:...' --vlc</I><br>To stream a specific file from a multi-file torrent:<br> <I>peerflix &lt;torrent-file&gt; --list</I> (first to see file indices)<br> <I>peerflix &lt;torrent-file&gt; --file 0 --mpv</I> (then stream the selected file).


title: HISTORY
content:
<b>peerflix</b> emerged as an early and popular tool for streaming torrents directly from the command line, leveraging the growing popularity of streaming media and the utility of torrents. It was developed in JavaScript (Node.js), making it cross-platform. While <I>webtorrent-cli</I> later gained significant traction offering similar features, <b>peerflix</b> remains a well-known and functional utility for its specific purpose of direct media player integration.


title: PARAMETERS
content:
<b><b>record</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Records performance counter data into <i>perf.data</i>, which can then be analyzed by <b>perf report</b>.<br><br><b><b>report</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads and displays performance counter data from <i>perf.data</i>, providing various views like call graphs and hot spots.<br><br><b><b>stat</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs a command and collects performance counter statistics for its execution, offering a summary of events.<br><br><b><b>top</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides a dynamic, real-time view of the top system performance events, similar to <b>top</b> for processes.<br><br><b><b>list</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all available performance events (hardware, software, tracepoints, etc.) that can be monitored.<br><br><b><b>probe</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines new dynamic tracepoints (kprobes or uprobes) for custom function entry/exit tracing.<br><br><b><b>annotate</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Annotates source code with performance data, showing event counts per instruction.<br><br><b><b>kmem</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Analyzes kernel memory events, such as allocations and frees.<br><br>


title: DESCRIPTION
content:
<i>perf</i> is a versatile command-line utility for performance analysis in Linux. It leverages the Linux kernel's performance monitoring unit (PMU), tracepoints, kprobes, and uprobes to collect and analyze performance data.<br><br>It can profile various aspects of system behavior, including CPU cycles, cache hits/misses, branch predictions, page faults, and system calls, providing deep insights into both user-space applications and kernel activity. <i>perf</i> is an essential tool for developers and system administrators to identify and resolve performance bottlenecks, optimize code, and understand system resource utilization.


title: CAVEATS
content:
Many <i>perf</i> operations, especially those involving hardware counters or kernel-level tracing, require root privileges to execute.<br><br>While powerful, <i>perf</i> can introduce some overhead to the system being monitored, particularly when tracing high-frequency events or using many counters. The features and accuracy of <i>perf</i> can also depend on the specific kernel version and hardware architecture.


title: EVENT TYPES
content:
<i>perf</i> can monitor a wide range of event types:<br><ul><li><b>Hardware events</b>: CPU cycles, cache references/misses, branch instructions/mispredictions, etc., provided by the PMU.</li><li><b>Software events</b>: Context switches, CPU migrations, page faults, CPU clock, etc., provided by the kernel.</li><li><b>Tracepoints</b>: Static markers in the kernel code, used for tracing specific kernel operations.</li><li><b>Kprobes</b>: Dynamic instrumentation points that can be placed on almost any kernel function.</li><li><b>Uprobes</b>: Similar to kprobes, but for user-space functions, enabling dynamic tracing of applications.</li></ul>


title: OUTPUT DATA FILE
content:
When using <b>perf record</b>, the collected performance data is typically saved to a file named <i>perf.data</i> in the current directory. This binary file contains detailed information about recorded events, including call stacks and timestamps. It can then be analyzed offline using <b>perf report</b>, allowing for detailed post-mortem examination of performance characteristics.


title: HISTORY
content:
<i>perf</i> was developed primarily by Ingo Molnar and other kernel developers, and it was integrated into the Linux kernel source tree in 2009. It emerged as a unified and highly capable interface for various performance monitoring capabilities previously scattered or difficult to access. Its design allowed it to supersede older, less integrated tools like OProfile for many use cases, thanks to its tighter integration with the kernel and broader event support, including tracepoints and dynamic probes.


title: SYNOPSIS
content:
<i>perl</i> [<i>switches</i>] [--] [<i>programfile</i>] [<i>arguments</i>]<br><i>perl</i> [<i>switches</i>] -e '<i>command</i>' [<i>arguments</i>]<br><i>Explanation:</i><br><b>switches</b>: Command-line options modifying Perl's behavior.<br><b>--</b>: Marks the end of command-line switches, treating subsequent arguments as program arguments.<br><b>programfile</b>: The path to a Perl script to execute.<br><b>arguments</b>: Arguments passed to the Perl script or command.<br><b>-e 'command'</b>: Executes the Perl code specified directly on the command line.


title: PARAMETERS
content:
<b>-e <i>command</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes the specified Perl <i>command</i> directly. Useful for one-liners.<br><br><b>-l[<i>digits</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables automatic newline translation. Often used with -n or -p to chomp input and add a newline to print output.<br><br><b>-n</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Wraps the script in a while (<>) { ... } loop, processing input line by line without printing by default.<br><br><b>-p</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Similar to -n, but also prints each line after processing it.<br><br><b>-i[<i>extension</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables in-place editing of files. If <i>extension</i> is provided, a backup of the original file is created.<br><br><b>-w</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables all standard warnings. Highly recommended for development.<br><br><b>-c</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Checks the syntax of the script without executing it.<br><br><b>-M<i>module</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Loads a specific Perl <i>module</i> before executing the script. Can include arguments, e.g., -Mstrict.<br><br><b>-T</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables taint mode, which performs security checks on data derived from outside the program (e.g., command-line arguments, environment variables). Essential for CGI scripts.<br><br><b>-v</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the Perl version and patchlevel information.<br><br><b>-V[<i>configvar</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints extensive configuration information about Perl. Can specify a specific <i>configvar</i> for targeted details.<br><br><b>-d</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs the Perl debugger.<br><br><b>-s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables rudimentary parsing for command-line switches.<br><br><b>-x[<i>directory</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Extracts and executes a Perl script embedded within a larger text file (e.g., a shell script).<br><br>


title: DESCRIPTION
content:
Perl (Practical Extraction and Report Language) is a versatile, high-level programming language designed for efficient text manipulation, system administration, web development, and network programming. It uniquely combines features from scripting languages like <i>sed</i> and <i>awk</i> with capabilities found in C and shell scripting. Its core strength lies in its powerful regular expression engine, making it exceptionally adept at parsing, extracting, and transforming complex text data. Perl supports both procedural and object-oriented programming paradigms, offering flexibility for various project scales. It boasts a vast ecosystem of reusable modules available on CPAN, extending its functionality for almost any task. Executable directly from the command line or as standalone scripts, Perl remains a robust tool for quick prototyping and complex automation.


title: CAVEATS
content:
<b>Readability</b>: Highly concise Perl code (often dubbed "write-only") can be challenging to understand or maintain, especially for beginners.<br><b>Performance</b>: While generally fast for text processing, for computationally intensive tasks, Perl might be slower than compiled languages like C or Java.<br><b>Security</b>: For scripts dealing with external input (e.g., web applications), understanding and utilizing taint mode (<b>-T</b>) is crucial to prevent security vulnerabilities.


title: CPAN (COMPREHENSIVE PERL ARCHIVE NETWORK)
content:
A vast, publicly available repository of Perl modules and distributions. CPAN significantly extends Perl's capabilities, offering pre-built solutions for almost any programming task, from database connectivity to GUI development.


title: PERL ONE-LINERS
content:
Perl's syntax and command-line switches (<b>-e</b>, <b>-n</b>, <b>-p</b>, <b>-l</b>, <b>-i</b>) make it exceptionally powerful for executing complex text processing tasks or system administration commands in a single line directly from the shell. These "one-liners" are a hallmark of Perl's utility for quick, efficient scripting.


title: HISTORY
content:
Perl was created by <b>Larry Wall</b> in 1987 as a general-purpose Unix scripting language aimed at simplifying report processing. It quickly gained traction due to its powerful text processing capabilities, particularly its advanced regular expressions, and its ability to effortlessly interface with system calls and other Unix utilities. During the 1990s, Perl became a dominant language for web development, especially for CGI scripting. Although its primary role in web development has evolved with the rise of other frameworks and languages, Perl continues to be a robust tool for system administration, network programming, bioinformatics, and rapid prototyping.


title: PARAMETERS
content:
<b>input_file</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the binary PostScript font file (PFB) to be converted. Specify <I>-</I> to read from standard input.<br><br><b>output_file</b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Optional) The path where the converted ASCII PostScript font file (PFA) will be saved. If omitted or specified as <I>-</I>, output goes to standard output.<br><br>


title: DESCRIPTION
content:
<i>pfbtops</i> is a utility designed to convert PostScript Type 1 font files from their binary (PFB) format to an ASCII (PFA) format.<br><br>PFB files are commonly found on Microsoft Windows platforms and contain font data in a compressed or binary-encoded form. PFA files, conversely, are plain text files that are human-readable and can be easily inspected or edited, making them more suitable for Unix-like environments and for direct embedding into PostScript documents. The conversion process involves decompressing the binary sections and encoding them into hexadecimal ASCII. This tool is particularly useful for ensuring font compatibility across different operating systems or for debugging font-related issues by examining the font file's internal structure.


title: CAVEATS
content:
This utility specifically handles PostScript Type 1 fonts. It is not designed for other font formats such as TrueType, OpenType, or PostScript Type 3/42. The resulting PFA file can be significantly larger than the original PFB file due to ASCII encoding.


title: STANDARD INPUT/OUTPUT FLEXIBILITY
content:
<i>pfbtops</i> can read from standard input and write to standard output. This capability enables seamless integration into shell scripts and command pipelines, allowing data to be processed or transferred to other commands without intermediate files, greatly enhancing its versatility in automated workflows.


title: HISTORY
content:
<i>pfbtops</i> is typically distributed as part of Ghostscript or related font utilities collections. Its development arose from the need to manage PostScript fonts across diverse computing environments, particularly to bridge the gap between Windows' common use of binary PFB fonts and Unix-like systems' preference for human-readable PFA fonts. It has served as a fundamental utility for Type 1 font handling for many years.


title: PARAMETERS
content:
<b><b>-s</b> <I>sigma</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i><br></i>Specifies the standard deviation for Gaussian smoothing prior to edge detection. A larger value applies more blurring, reducing noise but potentially blurring fine details. This is often used with Canny-like edge detectors.<br><br><b><b>-t</b> <I>low_threshold</I> <I>high_threshold</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i><br></i>Sets the hysteresis thresholds for edge linking. Edges with gradient magnitudes above <I>high_threshold</I> are strong edges; those below <I>low_threshold</I> are suppressed. Edges between the two thresholds are kept only if connected to a strong edge.<br><br><b><b>-o</b> <I>output_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i><br></i>Directs the output edge map to the specified PGM <I>output_file</I>. If not provided, the output is written to standard output.<br><br><b><b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i><br></i>Enables verbose output, displaying processing steps and parameters.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i><br></i>Displays a help message and exits.<br><br><b><I>input_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i><br></i>The path to the input PGM image file. If omitted, <b>pgmedge</b> reads from standard input.<br><br>


title: DESCRIPTION
content:
<i><br></i><b>pgmedge</b> is a hypothetical command-line utility designed for performing edge detection on images in the Portable Graymap (PGM) format. It would typically read a PGM image from standard input or a specified file, apply an edge detection algorithm, and write the resulting edge map to standard output or an output file. Common edge detection algorithms it might employ include Sobel, Prewitt, Laplacian, or a Canny-like algorithm, often preceded by Gaussian smoothing to reduce noise. This tool would be invaluable for image analysis, computer vision, and graphics processing tasks where identifying boundaries and contours within grayscale images is crucial. Its simplicity and focus on the PGM format would allow for easy integration into shell scripts and pipelines alongside other <i>netpbm</i> utilities. Users could control parameters like smoothing intensity and thresholding levels to fine-tune the edge detection process for various applications, from feature extraction to object recognition.


title: CAVEATS
content:
Please note that <b>pgmedge</b> is not a standard, widely distributed Linux command. Its functionality and existence are inferred based on common naming conventions for image processing tools, particularly those interacting with the <i>netpbm</i> suite of utilities. If you encounter a script or system referencing <b>pgmedge</b>, it likely refers to a custom-built tool, an alias, or a component of a specialized software package.


title: HISTORY
content:
While <b>pgmedge</b> itself isn't a documented standard, its concept stems from fundamental image processing tasks. Edge detection algorithms like Sobel, Prewitt, and Canny have been cornerstones of computer vision since the 1960s and 70s. Tools for applying these algorithms, often within the <i>netpbm</i> framework (first released in the late 1980s as <i>pbmplus</i>), have been essential for researchers and developers. A command named <b>pgmedge</b> would fit neatly into this legacy, representing a specialized tool for a common image analysis need, potentially developed as a custom script or a niche addition to existing libraries.


title: SYNOPSIS
content:
<b>pgmtoppm</b> [-white | -black] [-color=<I>colorname</I> | <I>#rgb</I>] [-red=<I>value</I>] [-green=<I>value</I>] [-blue=<I>value</I>] [<I>pgmfile</I>]


title: PARAMETERS
content:
<b>-white</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Maps the maximum intensity (white) pixels of the PGM image to the specified color. Intermediate grayscale values will be scaled between this color and black.<br><br><b>-black</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Maps the zero intensity (black) pixels of the PGM image to the specified color. Intermediate grayscale values will be scaled between black and this color.<br><br><b>-color=<I>colorname</I> | <I>#rgb</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the target color to be used with either -white or -black. It can be a color name (from rgb.txt, e.g., "red") or a hexadecimal RGB value (e.g., "#FF0000").<br><br><b>-red=<I>value</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the red component of the target color. The value is an integer between 0 and 255 (or 0 and the image's maxval).<br><br><b>-green=<I>value</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the green component of the target color. The value is an integer between 0 and 255 (or 0 and the image's maxval).<br><br><b>-blue=<I>value</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the blue component of the target color. The value is an integer between 0 and 255 (or 0 and the image's maxval).<br><br><b><I>pgmfile</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the input PGM image file. If this argument is omitted, <I>pgmtoppm</I> reads the image data from standard input.<br><br>


title: DESCRIPTION
content:
<I>pgmtoppm</I> is a utility within the <B>Netpbm</B> package designed to convert images from the Portable Graymap (PGM) format to the Portable Pixmap (PPM) format. While both are part of the Netpbm family, PGM represents grayscale images, and PPM represents color images.<br><br>This command doesn't truly "color" an image in the artistic sense; instead, it maps grayscale intensity values to color values. You can specify a target color for either the black (zero intensity) or white (maximum intensity) pixels of the PGM image. Intermediate grayscale values are then linearly interpolated to create a gradient between the specified color and black (or vice versa).<br><br>It is commonly used in pipelines for image processing, allowing grayscale images to be integrated into workflows that require color formats or to apply a simple color tint. If no color options are specified, it effectively converts a PGM to a PPM where all color components (Red, Green, Blue) are set to the original PGM intensity, resulting in a grayscale PPM image.


title: CAVEATS
content:
You cannot specify both <B>-white</B> and <B>-black</B> options simultaneously; only one mapping extreme (black or white) can be controlled. The unmapped extreme (white if -black is used, or black if -white is used) will always map to black in the output PPM image.


title: DEFAULT BEHAVIOR
content:
If no options are specified (i.e., no <B>-white</B>, <B>-black</B>, or color arguments), <I>pgmtoppm</I> will convert the PGM image to a PPM image where all three color components (Red, Green, Blue) are set to the original PGM pixel intensity. This results in a grayscale PPM output image, effectively making no visual change but changing the format header.


title: OUTPUT
content:
<I>pgmtoppm</I> always writes the resulting PPM image data to standard output. To save the output to a file, you must redirect standard output, for example: <B>pgmtoppm image.pgm > image.ppm</B>.


title: COLOR SPECIFICATION
content:
When using <B>-color</B>, the color can be specified as a name (e.g., "<I>blue</I>") which is looked up in the system's <I>rgb.txt</I> file, or as a hexadecimal RGB triplet (e.g., "<I>#0000FF</I>"). The individual <B>-red</B>, <B>-green</B>, and <B>-blue</B> options allow for more granular control over the color components, overriding any color name or hex value provided.


title: HISTORY
content:
<I>pgmtoppm</I> is part of the <B>Netpbm</B> project, a suite of graphics conversion tools that originated from Jef Poskanzer's <B>PBMplus</B> toolkit in the late 1980s. Netpbm maintains a philosophy of small, specialized tools that can be chained together via pipes to perform complex image manipulations. <I>pgmtoppm</I> exemplifies this by handling a specific, fundamental conversion within the Netpbm image format ecosystem.


title: PARAMETERS
content:
<b><i>--home &lt;dir&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the directory where <i>phive</i> stores its data and configuration (defaults to <i>~/.phive</i>).<br><br><b><i>--trust-gpg-keys &lt;keyid&gt;[,&lt;keyid&gt;]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly trust one or more GPG key IDs for signature verification during installation.<br><br><b><i>--no-trust-gpg-keys</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable GPG key trust for the current operation, allowing unverified installations (use with caution).<br><br><b><i>--force</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the operation, e.g., overwrite existing files or reinstall tools without prompts.<br><br><b><i>--prefer-unstable</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allow or prefer unstable versions of tools during installation or update.<br><br><b><i>--disable-progress-bar</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not show the download progress bar.<br><br><b><i>-v, --verbose</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increase verbosity of output messages. Can be used multiple times for more detail.<br><br><b><i>-q, --quiet</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress most output messages, showing only essential information or errors.<br><br><b><i>--version</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the <i>phive</i> version information and exit.<br><br><b><i>--help</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display help for <i>phive</i> or a specific command.<br><br><b><i>&lt;command&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The specific operation to perform, such as <i>install</i>, <i>update</i>, <i>remove</i>, <i>list</i>, <i>version</i>, or <i>help</i>.<br><br><b><i>[arguments]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Additional arguments specific to the chosen command, e.g., tool names for <i>install</i> or <i>remove</i>.<br><br>


title: DESCRIPTION
content:
<i>phive</i> is a dependency manager specifically designed for PHP tools distributed as <br>PHAR (PHP Archive) files. Unlike <i>Composer</i>, which manages PHP libraries, <br><i>phive</i> focuses on developer tools such as <i>PHPUnit</i>, <i>php-cs-fixer</i>, <br><i>PHPMD</i>, and others. It ensures the integrity and authenticity of installed <br>tools by leveraging <br><i>GnuPG</i> for signature verification, making it a secure choice for managing <br>third-party PHP executables. <br><br>It automatically downloads, verifies, and installs specified PHARs, either <br>locally within a project or globally on the system. It also provides mechanisms <br>for updating, removing, and listing installed tools, streamlining the <br>workflow for PHP development environments.


title: CAVEATS
content:
<i>phive</i> is not a standard Linux command and requires a PHP installation to run. <br>It is typically installed via <i>Composer</i> or by downloading its PHAR directly. <br>Its security features rely heavily on <br><i>GnuPG</i>, meaning that a working GPG setup and potentially manual key <br>importing are necessary for full integrity verification. <br>Mismanagement of GPG keys or allowing unverified installations can pose a <br>significant security risk.


title: GPG KEY MANAGEMENT
content:
<i>phive</i> relies on <br><i>GnuPG</i> to verify the authenticity of PHAR files. When you install a tool for <br>the first time, <i>phive</i> attempts to download and verify the author's <br><i>GPG</i> key. You might be prompted to confirm trusting a key. Keys are stored in <br>the <i>phive</i> home directory (typically <i>~/.phive/gpg-keys</i>). <br>It's crucial to ensure you only trust keys from legitimate sources to prevent <br>supply chain attacks, and regularly audit trusted keys.


title: PHIVE.XML CONFIGURATION
content:
For project-specific tool management, <i>phive</i> uses a <br><i>phive.xml</i> file (similar to <i>Composer</i>'s <i>composer.json</i>). <br>This XML file defines which tools are required for the project, their versions, <br>and optionally their target installation paths. <br>Running <i>phive install</i> in a project directory with a <i>phive.xml</i> <br>will install all defined tools, ensuring consistent development environments <br>across team members and CI/CD pipelines. This file can be version-controlled.


title: HISTORY
content:
<i>phive</i> emerged to address the challenges of managing PHP development tools that are <br>distributed as PHAR files. Before <i>phive</i>, developers often downloaded these <br>tools manually, which made updating difficult and lacked integrity <br>verification. The project focused on providing a secure, automated, and <br>reproducible way to install and manage these tools. Its emphasis on <br><i>GPG</i>-based signature verification was a key differentiator, enhancing the <br>security posture for PHP projects that rely on external tools. It has become a <br>de-facto standard in many PHP development workflows for its specific niche.


title: PARAMETERS
content:
<b>--standard=<standard></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>The coding standard to use.<br>Can be a predefined standard (e.g., PSR1, PSR12, Squiz, Zend) or the path to a custom ruleset.</i><br><br><b>-p, --progress</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Show progress of the run.</i><br><br><b>-s, --sniffs=<sniffs></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>A comma-separated list of sniffs to fix.<br>Only fixes these specified sniffs.</i><br><br><b>--ignore=<patterns></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>A comma-separated list of file/directory patterns to ignore.<br>Files or directories matching these patterns will not be processed.</i><br><br><b>--exclude=<patterns></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>A comma-separated list of sniffs to exclude from fixing.<br>Violations for these sniffs will not be corrected.</i><br><br><b>--severity=<severity></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>The minimum severity of an error or warning to fix.<br>Defaults to 5.</i><br><br><b>--tab-width=<width></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>The number of spaces each tab represents.<br>Defaults to the tab width defined in the coding standard.</i><br><br><b>--suffix=<suffix></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Write fixed files to a new file with the specified suffix.<br>By default, original files are overwritten.</i><br><br><b>--report=<type></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Generate a report in a specific format (e.g., full, summary, json, xml).<br>Defaults to <code>full</code>.</i><br><br><b>--report-file=<file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Write the report to the specified file instead of stdout.</i><br><br><b>--stdin</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Read input from stdin.<br>Must be used with <code>--stdin-path</code>.</i><br><br><b>--stdin-path=<path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>The path to the file when reading from stdin.<br>Required when <code>--stdin</code> is used to correctly identify the file type and apply rules.</i><br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Print verbose output.<br>Use <code>-vv</code> or <code>-vvv</code> for more verbosity.</i><br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Print version information.</i><br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Print help information.</i><br><br>


title: DESCRIPTION
content:
phpcbf (PHP Code Beautifier and Fixer) is a powerful command-line tool that automatically corrects most coding standard violations detected by PHP_CodeSniffer. It analyzes code against a defined coding standard (e.g., PSR-1, PSR-2, PSR-12, or custom standards) and attempts to fix issues such as incorrect indentation, spacing, naming conventions, and other stylistic errors. Unlike phpcs, which only reports violations, phpcbf modifies the source code directly, saving developers time and effort in manually adhering to project coding guidelines. It's often used as part of CI/CD pipelines or pre-commit hooks to ensure code consistency.


title: CAVEATS
content:
<i>While phpcbf is highly effective, it cannot fix all types of coding standard violations. Some issues might require manual intervention, especially those related to logical flow or complex structural changes. It's crucial to use phpcbf with version control (e.g., Git) so that changes can be easily reviewed and reverted if necessary. Always test code after automated fixes to ensure functionality remains intact and no unintended side effects occur.</i>


title: <B>CONFIGURATION FILES</B>
content:
<i>phpcbf can be configured using a <code>phpcs.xml</code> or <code>phpcs.xml.dist</code> file placed in the project root.<br>This file allows specifying the default standard, ignored paths, custom sniffs, and other settings, making it easier to maintain consistent code quality across a project without always typing long command-line arguments.</i>


title: <B>INTEGRATION WITH IDES/EDITORS</B>
content:
<i>Many modern IDEs and text editors (like VS Code, PhpStorm, Sublime Text) have plugins that integrate phpcbf.<br>This allows for real-time code fixing upon saving or as part of a format-on-save action, providing immediate feedback and ensuring code adheres to standards during development.</i>


title: HISTORY
content:
<i>phpcbf is an integral part of the PHP_CodeSniffer project, which was initially created by Greg Sherwood in 2006. phpcbf itself was introduced later as a companion tool to phpcs to provide automated fixing capabilities, significantly enhancing the developer workflow by reducing the manual effort required to conform to coding standards. Its development continues as part of the broader PHP_CodeSniffer effort to support new PHP versions, improve sniff accuracy, and add new features.</i>


title: PARAMETERS
content:
<b><b>--min-lines</b> <N></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the minimum number of identical lines to consider a block as a copy. The default value is 5.<br><br><b><b>--min-tokens</b> <N></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the minimum number of identical tokens to consider a block as a copy. The default value is 70.<br><br><b><b>--suffix</b> <suffix(es)></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only process files with the specified suffix(es). Multiple suffixes can be provided comma-separated (e.g., <i>.php,.inc</i>). The default suffix is <i>.php</i>.<br><br><b><b>--exclude</b> <dir></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Excludes a directory from the scan. This option can be specified multiple times to exclude several directories (e.g., <i>--exclude vendor --exclude cache</i>).<br><br><b><b>--fuzzy</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables fuzzy matching for duplicates, allowing for slight variations in the duplicated code blocks.<br><br><b><b>--log-xml</b> <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes the copy-paste detection results to an XML file in a custom format.<br><br><b><b>--log-pmd</b> <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes the copy-paste detection results to an XML file in PMD (Programming Mass Detector) format, compatible with tools like Jenkins or SonarQube.<br><br><b><b>--progress</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a progress bar during the scan operation.<br><br><b><b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output, providing more detailed information during the scan.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message with available options and usage.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information of <i>phpcpd</i>.<br><br><b><<i>directories_or_files</i>...></b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more directories or specific files to be scanned for duplicated code.<br><br>


title: DESCRIPTION
content:
<i>phpcpd</i> (PHP Copy/Paste Detector) is a command-line tool that scans PHP source code for identical blocks of code, helping developers identify and reduce code duplication. It employs an algorithm to find exact or near-exact duplicates across multiple files or within a single file.<br><br>Identifying duplicated code is crucial for code maintainability, as changes often need to be applied in multiple places, potentially leading to bugs and increased development effort. <i>phpcpd</i> outputs a report listing the duplicated blocks, their file locations, and the number of lines involved, serving as a valuable aid in refactoring efforts.


title: CAVEATS
content:
While highly effective for detecting exact and near-exact code duplication, <i>phpcpd</i> might produce false positives with very small <i>--min-lines</i> or <i>--min-tokens</i> values. It focuses on syntactic duplication, not semantic, meaning it won't detect if two different pieces of code achieve the same logical outcome.<br><br>Scanning very large codebases can be resource-intensive in terms of CPU and memory. Ensure your PHP installation has the <i>tokenizer</i> extension enabled, as it's required for <i>phpcpd</i> to parse PHP code.


title: INTEGRATION WITH CI/CD
content:
<i>phpcpd</i> is commonly integrated into Continuous Integration/Continuous Deployment (CI/CD) pipelines. This ensures that new code duplication is automatically detected and flagged before it gets merged into the main codebase, enforcing a high standard of code quality and maintainability.


title: REFACTORING AID
content:
The detailed reports generated by <i>phpcpd</i> serve as a crucial guide for refactoring efforts. By highlighting specific duplicated blocks, developers can efficiently identify areas where code can be abstracted, encapsulated, or removed, leading to more modular, readable, and maintainable software.


title: HISTORY
content:
<i>phpcpd</i> is an integral part of the PHP ecosystem's static analysis tools, largely developed and maintained by Sebastian Bergmann, who is also the creator of PHPUnit. It emerged as a specialized tool within the broader set of PHP quality assurance utilities, providing a dedicated solution for identifying code duplication. Its development has consistently aligned with best practices in PHP development, making it a staple for maintaining clean and efficient codebases over many years.


title: SYNOPSIS
content:
<b>phpstan</b> <b>analyse</b> <i>[paths]</i> [<i>OPTIONS</i>]<br><b>phpstan</b> <b>generate-baseline</b> <i>[file] [paths]</i> [<i>OPTIONS</i>]<br><b>phpstan</b> <b>clear-result-cache</b><br><b>phpstan</b> <b>init</b>


title: PARAMETERS
content:
<b>--configuration | -c &lt;file&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to the <i>phpstan.neon</i> configuration file.<br><br><b>--level | -l &lt;level&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the rule level for analysis (0-9 or 'max'). Higher levels mean stricter checks.<br><br><b>--error-format &lt;format&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output format for errors (e.g., 'raw', 'pretty', 'checkstyle', 'json').<br><br><b>--memory-limit &lt;limit&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the PHP memory limit for the analysis process (e.g., '512M', '-1' for no limit).<br><br><b>--no-progress</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables the progress bar during analysis, useful for CI/CD environments.<br><br><b>--clear-result-cache</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Clears the analysis result cache before running analysis.<br><br><b>--generate-baseline &lt;file&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates a baseline file to ignore existing errors, allowing new errors to be tracked for future code.<br><br>


title: DESCRIPTION
content:
<i>phpstan</i> is a static analysis tool for PHP that focuses on finding bugs in your code without actually running it. It works by analyzing the abstract syntax tree (AST) of your PHP files and performing deep type checking. This helps developers catch potential errors, such as incorrect type usage, undefined variables, or uncalled methods, early in the development cycle.<br><br>By integrating <i>phpstan</i> into a continuous integration (CI) pipeline, teams can significantly improve code quality, reduce runtime errors, and ensure better adherence to coding standards. It supports various levels of strictness, allowing projects to gradually adopt stricter analysis.


title: CAVEATS
content:
<i>phpstan</i> can be memory and CPU intensive on large codebases. Its effectiveness depends on the quality of type hints and PHPDoc annotations in the code. Configuring <i>phpstan</i> for complex projects, especially with custom extensions or dynamic code, can sometimes be challenging and may require fine-tuning to avoid false positives or negatives.


title: LEVELS OF ANALYSIS
content:
<i>phpstan</i> provides a system of analysis "levels" from 0 to 9 (and 'max'). Level 0 performs basic syntax checks, while level 9 (or 'max') enforces the strictest possible type checks and best practices. This allows projects to gradually increase their code quality checks without being overwhelmed by a large number of errors initially.


title: CONFIGURATION FILES
content:
<i>phpstan</i> uses a configuration file, typically named <i>phpstan.neon</i> or <i>phpstan.neon.dist</i>, written in NEON format. This file allows users to define paths to analyze, exclude specific files, configure extensions, set analysis levels, and customize various other aspects of the analysis process.


title: HISTORY
content:
<i>phpstan</i> was created by Ondrej Mirtes and first released in 2016. It quickly gained traction in the PHP community due to its comprehensive type analysis capabilities, which were more advanced than existing static analysis tools at the time. Its continuous development, community contributions, and the introduction of "levels" for gradual adoption have cemented its position as a leading tool for ensuring code quality in PHP projects.


title: PARAMETERS
content:
<b>--configuration (-c) <i>&lt;file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads configuration from an XML file, typically <b>phpunit.xml</b>.<br><br><b>--testsuite <i>&lt;name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only runs tests belonging to the specified test suite.<br><br><b>--filter <i>&lt;pattern&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs only tests whose names match the given pattern.<br><br><b>--bootstrap <i>&lt;file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A PHP file that is included before the tests are run.<br><br><b>--verbose (-v)</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables more detailed output during test execution.<br><br><b>--colors</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses ANSI colors in the console output for better readability.<br><br><b>--stop-on-failure</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Halts test execution immediately after the first test failure.<br><br><b>--coverage-html <i>&lt;dir&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates an HTML code coverage report in the specified directory.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the PHPUnit version information and exits.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message with command-line options and exits.<br><br>


title: DESCRIPTION
content:
PHPUnit is a <b>programmer-oriented testing framework</b> for the PHP language. It is a fundamental tool for developers practicing <i>Test-Driven Development (TDD)</i> or simply striving for robust and maintainable codebases.<br><br>At its core, PHPUnit allows developers to write <i>repeatable tests</i> for small, isolated units of code (functions, methods, classes). These tests ensure that components behave as expected, catching bugs early and preventing regressions when changes are introduced.<br><br>Tests are typically written as PHP classes extending <b>PHPUnit\Framework\TestCase</b>, with individual test methods prefixed with <b>test</b>. PHPUnit provides a rich set of <b>assertions</b> to verify outcomes, powerful <b>test runners</b> for execution, and comprehensive <b>code coverage</b> reporting tools to assess test effectiveness.


title: CAVEATS
content:
<i>PHPUnit</i> requires a functional <b>PHP installation</b> to run. Modern projects typically manage it via <b>Composer</b>, requiring <b>vendor/autoload.php</b> to be set up correctly for test class discovery.<br><br>While powerful, its configuration can become complex for large projects. Code coverage generation can also be resource-intensive, particularly for extensive test suites or when dealing with large codebases.


title: CONFIGURATION FILE (<B>PHPUNIT.XML</B>)
content:
PHPUnit can be extensively configured using an XML file, typically named <b>phpunit.xml</b> or <b>phpunit.xml.dist</b>. This file allows specifying test suites, bootstrapping files, code coverage settings, various PHP settings, and test listeners, providing a centralized way to manage test execution behavior without relying solely on command-line arguments.


title: TEST DISCOVERY
content:
By default, PHPUnit scans specified directories for files ending with <b>Test.php</b> or methods prefixed with <b>test</b> within classes extending <b>PHPUnit\Framework\TestCase</b>. The configuration file can precisely define which directories or files to include for test discovery.


title: ASSERTIONS
content:
Central to writing tests, assertions are methods like <b>assertEquals()</b>, <b>assertTrue()</b>, <b>assertInstanceOf()</b>, and many others, provided by the base <b>PHPUnit\Framework\TestCase</b> class. They are used to verify that a unit of code behaves as expected, failing the test if the condition is not met.


title: HISTORY
content:
<i>PHPUnit</i> was originally created by <b>Sebastian Bergmann</b>, drawing inspiration from JUnit, the de facto standard testing framework for Java. Its initial public release dates back to <i>2004</i>, quickly becoming the leading unit testing framework for PHP.<br><br>Over the years, PHPUnit has seen numerous major releases, adapting to new PHP language features, evolving best practices, and improving performance and reporting capabilities. Its widespread adoption has made it an indispensable tool in the PHP ecosystem for ensuring code quality and enabling test-driven development.


title: PARAMETERS
content:
<b><code>-gamma <gamma></code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a gamma correction to the output image. <i><gamma></i> is a floating-point number representing the gamma value.<br><br><b><code>pi1file</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the input Atari ST .pi1 image file. If omitted, <i><b>pi1toppm</b></i> reads from standard input (<i><code>stdin</code></i>).<br><br>


title: DESCRIPTION
content:
<i><b>pi1toppm</b></i> is a utility from the Netpbm suite that transforms an Atari ST .pi1 format image file into a portable pixmap (PPM). The .pi1 format is a specific 16-color interlaced graphics format used on Atari ST computers. The command reads the .pi1 data from a specified file or standard input and outputs the converted image to standard output as a PPM file, which can then be further processed or viewed by other Netpbm tools or image viewers.


title: CAVEATS
content:
Input must be a valid Atari ST .pi1 file. Incorrect or corrupted files may lead to unexpected output or errors.<br>The .pi1 format is a legacy format, and its primary use today is typically for converting historical graphics files.


title: STANDARD INPUT/OUTPUT
content:
Like most Netpbm tools, <i><b>pi1toppm</b></i> is designed to work with standard input and output. It reads the .pi1 file from <i><code>stdin</code></i> if no <i><code>pi1file</code></i> argument is provided, and always writes the resulting PPM image to <i><code>stdout</code></i>. This allows for easy piping of data between commands, e.g., <code><b>cat image.pi1 | pi1toppm | ppmtogif > image.gif</b></code>.


title: HISTORY
content:
<i><b>pi1toppm</b></i> is a component of the Netpbm project, a comprehensive toolkit for manipulating graphic images, especially suited for batch processing and scripting. Netpbm originated from the earlier Pbmplus package, developed by Jef Poskanzer in the late 1980s. The <i><b>pi1toppm</b></i> command was created to provide compatibility with legacy Atari ST .pi1 image files, allowing these older graphics to be integrated into modern image processing workflows via the versatile Netpbm framework. Its development reflects the Netpbm philosophy of providing robust converters for a vast array of image formats.


title: SYNOPSIS
content:
<b>ping</b> [<i>OPTIONS</i>] <i>destination</i><br><br>The <i>destination</i> can be an IP address (e.g., 192.168.1.1) or a hostname (e.g., example.com).


title: PARAMETERS
content:
<b>-c <i>count</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stop after sending <i>count</i> <i>ECHO_REQUEST</i> packets. Useful for sending a fixed number of pings.<br><br><b>-i <i>interval</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Wait <i>interval</i> seconds between sending each packet. Default is one second. Decreasing this value requires root privileges.<br><br><b>-s <i>packetsize</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the number of data bytes to be sent. The default is 56 (resulting in 64 bytes on the wire, including ICMP header).<br><br><b>-t <i>ttl</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the IP Time To Live (TTL) value. This limits the number of hops a packet can traverse before being discarded.<br><br><b>-W <i>timeout</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Time in seconds to wait for a response for each packet. If a response is not received within this time, the packet is considered lost.<br><br><b>-4</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force IPv4. Used to explicitly choose IPv4 addressing.<br><br><b>-6</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force IPv6. Used to explicitly choose IPv6 addressing.<br><br><b>-q</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Quiet output. Nothing is displayed except the summary lines at startup and when finished. Useful for scripting.<br><br><b>-v</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Verbose output. Displays all ICMP packets other than echo replies.<br><br>


title: DESCRIPTION
content:
The <b>ping</b> command is a fundamental network diagnostic utility used to test the reachability of a host on an Internet Protocol (IP) network. It operates by sending Internet Control Message Protocol (ICMP) <i>ECHO_REQUEST</i> packets to the target host and listening for <i>ECHO_REPLY</i> messages. The command provides valuable information such as the round-trip time for packets to reach the destination and return, along with the Time To Live (TTL) value and packet sequence numbers. This data helps in determining if a host is alive, assessing network latency, and identifying packet loss. By default, <b>ping</b> sends one packet per second indefinitely until interrupted by the user (Ctrl+C). Users can specify various options to control the number of packets sent, the interval between packets, packet size, and more. It's an indispensable tool for network administrators and users alike for basic network troubleshooting, verifying connectivity, and diagnosing connectivity problems, including DNS resolution issues (if using a hostname).


title: CAVEATS
content:
<b>ping</b> relies on ICMP, which can be blocked by firewalls on target hosts or intermediary network devices, leading to apparent "unreachability" even if the host is operational for other services (e.g., HTTP). Therefore, a failed ping doesn't always mean the host is completely offline, only that ICMP echo requests are not being responded to. Some advanced options, like setting a very small interval (e.g., <b>-i 0.2</b>), may require root privileges. Furthermore, <b>ping</b> only tests basic network layer connectivity; it doesn't guarantee that application-layer services (like a web server) are running or accessible.


title: EXIT STATUS
content:
Upon completion, <b>ping</b> returns an exit status of 0 if at least one <i>ECHO_REPLY</i> was received, and 1 if no packets were received or an error occurred. This makes it suitable for use in scripts to check host availability.


title: NETWORK TROUBLESHOOTING
content:
<b>ping</b> is often the first command used when troubleshooting network connectivity issues. A successful ping confirms basic IP layer reachability, while a failed ping points to issues like host being down, network configuration problems, or firewall blocks. Combined with <b>traceroute</b>, it helps pinpoint where connectivity breaks down.


title: HISTORY
content:
The <b>ping</b> command was written by Mike Muuss in December 1983 as a tool to troubleshoot network problems. Its name derives from the sonar terminology, where a pulse of sound is sent out and a return "ping" is awaited to detect objects. Muuss designed it to use ICMP echo packets for network diagnostics, making it an early and enduring utility for verifying host reachability and measuring round-trip times on IP networks.


title: PARAMETERS
content:
<b>--environment, -e <env_name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Specifies one or more PlatformIO project environments to apply the check for.</I><br>If omitted, the command checks all environments defined in <I>platformio.ini</I>.<br><br><b>--json-output</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Outputs the checking results in a structured JSON format.</I><br>This option is particularly useful for programmatic processing and integration with other tools or dashboards.<br><br><b>--severity <level></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Sets the minimum severity level of issues to report.</I><br>Possible values are <I>info</I>, <I>warning</I>, and <I>error</I>. Issues below the specified level will not be displayed.<br><br><b>--filter <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Includes specific files or directories for analysis.</I><br>This option can be specified multiple times to include various paths.<br><br><b>--ignore <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Excludes specific files or directories from analysis.</I><br>This option can be specified multiple times to ignore various paths.<br><br><b>--enable-checker <tool></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Enables specific static analysis checkers.</I><br>For example, use <I>--enable-checker clangtidy</I> or <I>--enable-checker pylint</I>.<br><br><b>--disable-checker <tool></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Disables specific static analysis checkers.</I><br>Useful for temporarily turning off a checker without modifying <I>platformio.ini</I>.<br><br><b>--fail-on-defect</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Exits with a non-zero exit code if any defects (errors or warnings, depending on severity) are found.</I><br>This is crucial for CI/CD pipelines to automatically fail builds on quality issues.<br><br><b>--project-dir <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Specifies the path to the PlatformIO project directory.</I><br>By default, it uses the current working directory.<br><br><b>--keep-build-dir</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Retains the build environment files and analysis artifacts after the check process completes.</I><br><br><b>--help, -h</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Displays a help message for the <B>pio check</B> command and exits.</I><br><br>


title: DESCRIPTION
content:
<I>pio check</I> is a powerful command-line utility within the PlatformIO ecosystem, designed to perform static code analysis and validate project configuration files for PlatformIO projects. It helps developers identify potential issues, coding style violations, and configuration errors early in the development cycle, promoting better code quality and maintainability.<br><br>The command integrates various industry-standard static analysis tools (linters) such as <I>Clang-Tidy</I> for C/C++ and <I>Pylint</I> for Python, among others. It analyzes source code files against configured rules, checks the consistency and correctness of the <I>platformio.ini</I> project configuration file, and verifies project dependencies and library installations.<br><br>Users can customize its behavior extensively via the <I>platformio.ini</I> file, enabling or disabling specific checkers, setting severity levels for reported issues (info, warning, error), and specifying files or directories to include or ignore. <I>pio check</I> is an essential tool for ensuring code robustness, especially in embedded systems development, and is often incorporated into Continuous Integration/Continuous Deployment (CI/CD) pipelines to automate quality assurance.


title: CAVEATS
content:
The <B>pio check</B> command requires an existing PlatformIO Core installation and a properly structured PlatformIO project. Its effectiveness heavily relies on the configured static analysis tools (e.g., Clang-Tidy, Pylint) and their presence in the system PATH or PlatformIO's toolchain. While powerful, static analysis may occasionally produce false positives or warnings that require manual review and configuration adjustments.


title: CONFIGURATION VIA PLATFORMIO.INI
content:
The behavior of <B>pio check</B> is highly configurable through the project's <I>platformio.ini</I> file.<br>Developers can define <B>check_tool</B> to specify which checkers to use (e.g., <I>check_tool = clangtidy</I>), set <B>check_flags</B> for passing arguments to the underlying tools, and define <B>check_src_filter</B> or <B>check_build_flags</B> to control the analysis scope and build settings. This allows for fine-grained control over the static analysis process tailored to specific project needs.


title: INTEGRATION WITH CI/CD
content:
<B>pio check</B> is a cornerstone for enforcing code quality in Continuous Integration/Continuous Deployment (CI/CD) pipelines.<br>By incorporating <B>pio check</B> with the <B>--fail-on-defect</B> option into a CI workflow, teams can automate the detection of code quality issues. If defects of a specified severity are found, the build can be configured to fail, preventing problematic code from being merged into the main branch or deployed, thereby maintaining high code standards across the development lifecycle.


title: HISTORY
content:
The <B>check</B> command is an integral part of the PlatformIO Core, an open-source ecosystem for embedded development. PlatformIO was initially launched around 2014, and the <B>check</B> feature was progressively introduced and enhanced to meet the growing demand for automated code quality assurance in embedded projects. It unifies various popular static analysis tools under a single, easy-to-use interface, significantly improving the development workflow for professional engineers and hobbyists alike.


title: PARAMETERS
content:
<b><b>PATH</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to the project directory or a specific source file to build. If omitted, the current working directory is used.<br><br><b><b>-l</b>, <b>--lib</b> <i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a path to a library that should be used during the build process. This option can be used multiple times for different libraries.<br><br><b><b>-c</b>, <b>--project-conf</b> <i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provide a custom path to the <i>platformio.ini</i> project configuration file, overriding the default location.<br><br><b><b>-e</b>, <b>--environment</b> <i>&lt;name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Build against a specific <i>PlatformIO</i> environment defined in the <i>platformio.ini</i> file. Can be specified multiple times to build for several environments.<br><br><b><b>-b</b>, <b>--board</b> <i>&lt;id&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Build for a specific board ID. This is useful when an environment is not explicitly defined or to override an environment's board setting.<br><br><b><b>-s</b>, <b>--src</b> <i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a path to a source file or directory within the project to build, rather than compiling the entire project.<br><br><b><b>-k</b>, <b>--keep-storage</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevent the <i>.pio</i> build environment storage directory from being cleaned after the CI run completes.<br><br><b><b>--skip-library-check</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skip the check for whether all project dependencies (external libraries) are installed before initiating the build process.<br><br><b><b>-D</b>, <b>--project-option</b> <i>&lt;key=value&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add or override project options for the current CI run. For example, `<b>-D debug_level=3</b>`.<br><br><b><b>--test</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Execute <i>unit tests</i> after the project has been successfully built. Requires tests to be configured within the <i>platformio.ini</i> file.<br><br><b><b>--test-filter</b> <i>&lt;pattern&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When `<b>--test</b>` is used, this option filters the unit tests to be run based on a specified pattern.<br><br>


title: DESCRIPTION
content:
The <b>pio ci</b> command, part of the <i>PlatformIO Core CLI</i>, is specifically designed for <i>Continuous Integration (CI)</i> of embedded software projects. It enables developers to automate the compilation, static analysis, and unit testing of their firmware directly within CI/CD pipelines (e.g., <i>Travis CI</i>, <i>GitHub Actions</i>, <i>GitLab CI</i>, <i>Jenkins</i>).<br><br>It allows building projects against specific <i>PlatformIO environments</i>, for particular boards, and with custom configurations, making it invaluable for ensuring code quality and functionality throughout the development lifecycle without requiring a full IDE. It can also run <i>unit tests</i> configured within the project, providing immediate feedback on code changes and helping to catch regressions early.


title: CAVEATS
content:
The <b>pio ci</b> command is part of the <i>PlatformIO Core CLI</i> and requires <i>PlatformIO</i> to be installed and configured on the system. It is primarily designed for <i>embedded software development</i> workflows and may not be applicable for general-purpose Linux programming tasks. Its effectiveness is highly dependent on a correctly structured <i>platformio.ini</i> file and proper integration with a CI/CD service.


title: PLATFORMIO ENVIRONMENTS
content:
<i>PlatformIO</i> projects are configured using <i>environments</i> defined within the <i>platformio.ini</i> file. Each environment specifies unique settings such as the target board, development framework, upload protocol, and build flags. The <b>pio ci</b> command leverages these environments, enabling developers to build and test the same codebase for different hardware targets or toolchains within a single CI job, enhancing flexibility and coverage.


title: INTEGRATION WITH CI/CD SERVICES
content:
The primary benefit of <b>pio ci</b> stems from its seamless integration with external <i>CI/CD services</i>. By executing <b>pio ci</b> commands within a CI script (e.g., <i>.travis.yml</i>, <i>.github/workflows/*.yml</i>), developers can automate the compilation and testing of their code every time changes are pushed to the repository. This automated process ensures code quality and helps to identify and fix regressions early in the development cycle. The command's exit code (0 for success, non-zero for failure) is used by CI services to determine the job's overall status.


title: HISTORY
content:
<i>PlatformIO</i>, an open-source ecosystem founded by <i>Ivan Kravets</i>, was created to streamline and standardize <i>IoT</i> and <i>embedded development</i>. The <b>pio ci</b> command was introduced as a key feature to integrate modern <i>DevOps</i> and <i>Continuous Integration/Delivery (CI/CD)</i> practices into the embedded software development lifecycle. Its ongoing development focuses on providing a versatile and robust tool that integrates seamlessly with various CI services, addressing the unique challenges of building and testing firmware across diverse hardware and software configurations.


title: SEE ALSO
content:
<b>pio run</b> (PlatformIO CLI), <b>pio test</b> (PlatformIO CLI), <b>git</b> (1) (for version control and CI triggers), <b>make</b> (1) (general build automation tool), <b>cmake</b> (1) (cross-platform build system generator)


title: PARAMETERS
content:
<b>--environment, -e</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify one or more build environments defined in <i>platformio.ini</i> to run tasks against.<br><br><b>--target, -t</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a build target. Common targets include <i>build</i> (default), <i>upload</i>, <i>clean</i>, <i>program</i>, <i>uploadfs</i>, and <i>monitor</i>.<br><br><b>--project-dir, -d</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the path to the PlatformIO project directory. Defaults to the current working directory.<br><br><b>--build-dir, -b</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a custom path for the build output directory where compiled objects and firmware reside.<br><br><b>--upload-port, -p</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the serial port or network address for uploading the firmware. Overrides the <i>upload_port</i> setting in <i>platformio.ini</i>.<br><br><b>--clean</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Clean compiled object files and build artifacts from the project's build directory.<br><br><b>--silent, -s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress verbose output and progress messages during the build or upload process.<br><br><b>--json-output</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output build and upload results in a machine-readable JSON format, useful for scripting and integration.<br><br><b>--verbose, -v</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output, displaying detailed information about the build process, including compiler commands and their output.<br><br><b>--ignore-lib-deps</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ignore project library dependencies during the build process, preventing them from being processed or downloaded.<br><br><b>--force-build</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the rebuilding of all components, even if they appear to be up-to-date, overriding incremental build optimizations.<br><br>


title: DESCRIPTION
content:
<i>pio-run</i> is a fundamental command-line interface (CLI) utility provided by PlatformIO Core, designed to manage the entire embedded development workflow for a project. It serves as the primary tool for compiling source code, linking necessary libraries, creating firmware binaries, and subsequently uploading them to target embedded devices. This command automates the complex process of cross-compilation and flashing, abstracting away the intricacies of various toolchains, SDKs, and build systems specific to different microcontrollers and development boards.<br><br>Users typically invoke <i>pio-run</i> from their project directory, where it reads the <i>platformio.ini</i> configuration file to determine the build environment, board specifications, framework, and other project-specific settings. It supports multiple build targets, allowing users to build a project, upload the compiled firmware, clean build artifacts, or even program a specific memory region. Its cross-platform nature and extensive support for a vast array of development boards and embedded frameworks make it an indispensable tool for developers working with IoT devices, microcontrollers, and embedded systems. <i>pio-run</i> integrates seamlessly with popular IDEs and text editors, providing a unified and efficient development experience.


title: CAVEATS
content:
<i>pio-run</i> requires PlatformIO Core to be installed and properly configured on the system. It also depends on a valid <i>platformio.ini</i> configuration file within the project directory to define build settings, board types, and other project-specific parameters. Without this configuration, the command will not know how to build or upload your project. Debugging build errors can sometimes be challenging due to the complexity of underlying toolchains and framework-specific issues.


title: <B>PLATFORMIO.INI CONFIGURATION</B>
content:
The behavior of <i>pio-run</i> is heavily dictated by the <i>platformio.ini</i> file, which is the heart of a PlatformIO project. This file defines various build environments, specifies target boards (e.g., <i>board = esp32dev</i>), frameworks (e.g., <i>framework = arduino</i>), upload protocols, monitor settings, and project-specific build flags. Understanding and correctly configuring this file is crucial for successful project compilation and deployment.


title: <B>COMMON BUILD TARGETS</B>
content:
While <i>pio run</i> defaults to building the project, it can be directed to perform specific actions using the <i>--target</i> (<i>-t</i>) option. Common targets include:<br><ul><li><I>build</I>: Compiles the project (default behavior if no target is specified).</li><li><I>upload</I>: Compiles the project (if necessary) and uploads the firmware to the specified device.</li><li><I>clean</I>: Removes all generated build files and artifacts.</li><li><I>program</I>: Uploads firmware using a programmer (e.g., JTAG/SWD) instead of a serial port.</li><li><I>uploadfs</I>: Uploads a file system image (e.g., SPIFFS, LittleFS) to the device.</li><li><I>monitor</I>: Connects a serial monitor to the device after (or instead of) build/upload.</li></ul>


title: HISTORY
content:
PlatformIO, and consequently its core <i>pio-run</i> command, was first introduced around 2014, aiming to simplify embedded development by providing a unified, cross-platform build system. From its inception, <i>pio-run</i> has been the central command for building and managing firmware, evolving significantly with each PlatformIO Core release. Early versions focused on basic build and upload capabilities, while later updates introduced advanced features like multiple build environments, custom targets, and improved integration with various development frameworks and debuggers. Its development has consistently prioritized automation, ease of use, and broad hardware support, making it a cornerstone of the PlatformIO ecosystem.


title: SYNOPSIS
content:
<b>pipx</b> <I>command</I> [<I>options</I>] [<I>args</I>]<br>Examples:<br><b>pipx install</b> <I>package_name</I>[<I>extras</I>]<br><b>pipx run</b> <I>package_name</I> [<I>args</I>]<br><b>pipx upgrade-all</b>


title: PARAMETERS
content:
<b><b>install</b> <I>package</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Installs a package and its entry points into a new, isolated virtual environment.<br><br><b><b>run</b> <I>package</I> [<I>args</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs a Python application directly from a temporary virtual environment without installing it globally.<br><br><b><b>list</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all installed packages and their associated virtual environments.<br><br><b><b>upgrade</b> <I>package</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Upgrades an installed package to its latest compatible version.<br><br><b><b>upgrade-all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Upgrades all currently installed packages managed by <i>pipx</i>.<br><br><b><b>uninstall</b> <I>package</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uninstalls a specified package and removes its virtual environment.<br><br><b><b>uninstall-all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uninstalls all packages managed by <i>pipx</i>.<br><br><b><b>inject</b> <I>package_to_inject_into</I> <I>package_to_inject</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Injects a package into an existing <i>pipx</i> environment (e.g., to add optional dependencies).<br><br><b><b>ensurepath</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ensures the <i>pipx</i> binaries directory is correctly added to your system's PATH variable.<br><br>


title: DESCRIPTION
content:
<i>pipx</i> is a tool designed to install and run Python applications globally, but in isolated environments. Unlike <i>pip</i>, which installs packages into the Python environment you're currently using (potentially causing dependency conflicts), <i>pipx</i> creates a separate virtual environment for <b>each</b> application it installs.<br><br>This ensures that the application and its dependencies don't interfere with your system's Python packages or other installed applications. It makes globally available command-line tools written in Python safe and easy to manage, preventing "dependency hell" often encountered when multiple Python applications require conflicting versions of the same library. <i>pipx</i> places executables directly on your PATH, allowing you to run them like any other command-line tool, while keeping their internal dependencies neatly isolated. It's ideal for tools like <b>black</b>, <b>flake8</b>, <b>poetry</b>, or <b>awscli</b>.


title: CAVEATS
content:
While <i>pipx</i> provides excellent isolation for Python applications, it's crucial to ensure that its binary directory (typically <i>~/.local/bin</i>) is correctly added to your system's PATH variable for executables to be found. Occasionally, users might confuse it with <i>pip</i> or <i>venv</i>; remember <i>pipx</i> is specifically for running <b>applications</b> rather than managing libraries for <b>development</b> projects. It also requires <i>pip</i> and <i>python</i> to be properly configured on your system first.


title: HOW IT WORKS
content:
<i>pipx</i> leverages Python's built-in <i>venv</i> module to create a dedicated virtual environment for each application. When you install an application, <i>pipx</i> creates a <i>venv</i>, installs the application and its dependencies inside that <i>venv</i>, and then symlinks the application's main executable (entry point) into a user-specific binary directory (e.g., <i>~/.local/bin</i>), which <i>pipx</i> helps add to your system's PATH. This setup ensures that the application's dependencies are entirely separate from other Python installations on your system, preventing conflicts.


title: HISTORY
content:
<i>pipx</i> was created by Vinay Sajip and first released around late 2018 / early 2019. Its development was driven by the common frustration of "dependency hell" when installing multiple Python-based command-line tools globally using <i>pip</i>. Traditional <i>pip</i> global installations often led to conflicts between different applications requiring varying versions of shared dependencies. <i>pipx</i> emerged as a dedicated solution to this problem, providing robust isolation and a streamlined user experience for Python application users. It quickly gained popularity within the Python community for its effectiveness and simplicity.


title: DESCRIPTION
content:
<i>pkgctl-version</i> refers to the <B>version</B> subcommand of the <B>pkgctl</B> utility, a versatile command-line tool designed to streamline package management and interaction with the Arch User Repository (AUR) on Arch Linux systems. While <B>pkgctl</B> provides a unified interface for various tasks like building, installing, and managing packages, its <B>version</B> subcommand has a singular purpose: to display the current version of the <B>pkgctl</B> tool itself. <br><br>This information is crucial for several reasons: it helps users verify their installed <B>pkgctl</B> version, which is important for compatibility with new features or bug fixes. It's also invaluable when reporting issues or seeking support, as developers often require the tool's version to reproduce or diagnose problems. The command is straightforward to use, requiring no additional parameters, and simply outputs the version string to standard output.


title: CAVEATS
content:
This command is specific to the <B>pkgctl</B> utility, which is primarily developed for and used within the Arch Linux ecosystem. It is not a universally available Linux command and will not be found on distributions like Debian, Ubuntu, Fedora, or RHEL unless <B>pkgctl</B> is specifically installed from a third-party source or community repository. Its functionality is limited to reporting the version of its parent tool, <B>pkgctl</B>.


title: CONTEXT WITHIN ARCH LINUX
content:
<B>pkgctl</B> is part of the <I>libalpm</I> library ecosystem, which is the core of <B>pacman</B>. It's designed to be a more official and robust way to interact with the AUR and perform various package-related operations compared to some older, less maintained AUR helpers. The <I>pkgctl-version</I> command specifically helps in identifying which iteration of this important tool you are using, aiding in system diagnostics and troubleshooting.


title: HISTORY
content:
The <B>pkgctl</B> utility is a relatively recent addition to the Arch Linux toolset, evolving from efforts to provide a more integrated and user-friendly experience for managing both official Arch packages and those from the Arch User Repository (AUR). Its development is driven by the Arch Linux community, aiming to consolidate functionalities often provided by disparate tools or AUR helpers (like <i>yay</i> or <i>paru</i>) under a single, official-leaning command-line interface. The <i>version</i> subcommand has been an integral part of <B>pkgctl</B> from its early stages, serving the fundamental purpose of allowing users to easily ascertain the tool's specific build or release identifier. This aids in tracking changes, debugging, and ensuring compatibility within the rapidly evolving Arch Linux environment.


title: PARAMETERS
content:
<b>-charset <charset></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the character set to be used for reading input files, e.g., <B>UTF-8</B>.<br><br><b>-config <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a configuration file to load PlantUML settings from.<br><br><b>-D<VAR>=<value></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines a preprocessor variable that can be used within the PlantUML source code.<br><br><b>-o <dir></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output directory where generated image files will be saved.<br><br><b>-overwrite</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the command to overwrite existing output files without prompting.<br><br><b>-output <format></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the desired output image format, e.g., <B>png</B>, <B>svg</B>, <B>eps</B>.<br><br><b>-pipe</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads PlantUML source from standard input and writes the generated image to standard output.<br><br><b>-recursive</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Processes PlantUML files found in subdirectories of the specified input path.<br><br><b>-S<key>=<value></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a skin parameter to customize the visual appearance of diagrams.<br><br><b>-t<format></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shorthand for <B>-output <format></B>, for instance, <B>-tpng</B> or <B>-tsvg</B>.<br><br><b>-verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output, displaying detailed information during processing.<br><br><b>-version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the PlantUML version and exits.<br><br>


title: DESCRIPTION
content:
PlantUML is an open-source tool that allows users to create various types of diagrams, including UML (Unified Modeling Language) diagrams, using a simple plain text description language. It reads a textual definition of a diagram, often stored in a <B>.puml</B> or <B>.plantuml</B> file, and then renders it into an image format such as PNG, SVG, or EPS.<br><br>The <B>plantuml</B> command-line utility is the primary way to invoke this rendering process on Linux systems. It supports a wide array of diagram types beyond standard UML, including sequence, use case, class, activity, component, and state diagrams, as well as non-UML types like Gantt charts, mind maps, and Ditaa diagrams. Its simplicity and text-based approach make it highly suitable for version control systems, automation, and collaborative development.


title: CAVEATS
content:
PlantUML requires a Java Runtime Environment (JRE) to be installed and accessible on the system. For generating most UML diagrams (e.g., class, activity, state diagrams), it relies on the <B>Graphviz</B> (specifically the <B>dot</B> command) layout engine. Therefore, <B>Graphviz</B> must be installed and properly configured in the system's PATH. Performance and memory usage can vary significantly based on diagram complexity and size.


title: RELIANCE ON GRAPHVIZ
content:
While PlantUML can render some diagrams natively, many complex UML diagrams, particularly class, activity, and state diagrams, depend heavily on the <B>Graphviz</B> package for layout. Users must ensure <B>Graphviz</B> is installed and its <B>dot</B> executable is reachable in the system's PATH for full functionality.


title: TEXT-BASED SOURCE FILES
content:
PlantUML diagrams are defined in plain text files, typically with a <B>.puml</B> or <B>.plantuml</B> extension. This text-based approach facilitates version control, diffing, and programmatic generation or modification of diagrams, making it a powerful tool for documentation as code.


title: HISTORY
content:
PlantUML was first released in 2009 by Arnaud Roques. It was developed to address the need for a simple, text-based method for creating diagrams, which could be easily integrated into modern software development workflows, version control systems, and continuous integration pipelines. Its focus on a human-readable text syntax, rather than graphical editors, quickly popularized it among developers and technical writers. Since its inception, PlantUML has continuously evolved, expanding its support for numerous diagram types, output formats, and integration capabilities, making it a versatile tool for technical documentation and design.


title: PARAMETERS
content:
<b>true</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables aggressive power-saving optimizations. This typically involves applying various system tweaks to minimize power consumption.<br><br><b>false</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables or reverts the aggressive power-saving optimizations, returning the system to a more standard or performance-oriented state.<br><br>


title: DESCRIPTION
content:
The <b>pm-powersave</b> command, typically part of the <i>pm-utils</i> (power management utilities) package, is designed to apply or revert a set of aggressive power-saving optimizations across the system. Its primary role was often to prepare the system for suspend or hibernate operations by reducing power consumption as much as possible, or to toggle system-wide power-saving features. Unlike general power management daemons, <b>pm-powersave</b> usually performs one-time tweaks like disabling specific hardware features, optimizing device power states, or adjusting CPU governors for maximum power efficiency. While its direct execution might involve <i>true</i> or <i>false</i> arguments to enable or disable these settings, its functionality is frequently integrated into the suspend/hibernate process managed by other <i>pm-utils</i> commands like <b>pm-suspend</b> or <b>pm-hibernate</b>.


title: CAVEATS
content:
The <b>pm-powersave</b> command and the <i>pm-utils</i> suite it belongs to are largely considered deprecated in many modern Linux distributions, especially those using <i>systemd</i>. <i>systemd</i> now handles suspend, hibernate, and power management through its own mechanisms (e.g., <i>systemd-suspend.service</i>, <i>systemd-hibernate.service</i>, <i>systemd-sleep(8)</i>). Functionality similar to <b>pm-powersave</b> is often managed by <i>systemd</i> sleep hooks or specialized power management tools like TLP. Using <b>pm-powersave</b> on a <i>systemd</i>-based system might lead to conflicts, unexpected behavior, or simply have no effect.


title: INTEGRATION WITH PM-UTILS
content:
<code><b>pm-powersave</b></code> is often called internally by other <i>pm-utils</i> scripts (like <code><b>pm-suspend</b></code>) based on configuration settings (e.g., <i>PM_POWERSAVE</i> in <i>/etc/pm/config.d/</i>). It applies a set of power-saving tweaks defined by scripts in directories like <i>/usr/lib/pm-utils/defaults/</i> or <i>/etc/pm/power.d/</i>.


title: COMMON TWEAKS APPLIED
content:
When enabled, <code><b>pm-powersave</b></code> might adjust settings such as CPU governors (e.g., to 'powersave'), disable PCIe ASPM (Active State Power Management) unless specified, or modify USB device power states. The specific actions depend on the version of <i>pm-utils</i> and system configuration.


title: HISTORY
content:
The <b>pm-powersave</b> command is a component of the <i>pm-utils</i> package, which emerged as a standard power management suite for Linux systems, particularly before the widespread adoption of <i>systemd</i>. It provided a unified interface for system suspend, hibernate, and related power-saving operations across various hardware and kernel versions. As <i>systemd</i> matured and integrated its own comprehensive power management capabilities (via <i>logind</i> and <i>systemd-sleep</i>), the role of <i>pm-utils</i> and consequently <b>pm-powersave</b> diminished. While still available on some legacy systems or distributions not fully embracing <i>systemd</i>'s power management, its active development and primary usage have largely been superseded.


title: SEE ALSO
content:
pm-suspend(8), pm-hibernate(8), systemctl(1), systemd-sleep(8), TLP (Third-party power management daemon)


title: SYNOPSIS
content:
<b>pmap</b> [ <i>options</i> ] <i>PID</i> [ <i>PID</i> ... ]<br><b>pmap</b> <i>-V</i><br><b>pmap</b> <i>-h</i>


title: PARAMETERS
content:
<b><b>-x</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Extended format</I>. Shows additional columns like Resident Set Size (RSS), Dirty pages, and the full path to the mapped file. This is often the most useful output for detailed memory analysis.<br><br><b><b>-d</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Device format</I>. Displays columns for device major:minor and inode number, providing details about the underlying file system object that corresponds to the memory region.<br><br><b><b>-q</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Quiet mode</I>. Suppresses the header and footer lines from the output, showing only the memory map entries. This is particularly useful when scripting or processing the output programmatically.<br><br><b><b>-p</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Show PID</I>. When multiple process IDs are provided as arguments, this option ensures that each block of output is clearly prefixed with the corresponding PID, making it easier to distinguish between process maps.<br><br><b><b>-V</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Version information</I>. Prints the version of the <b>pmap</b> utility to standard output and then exits.<br><br><b><b>-h</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Help message</I>. Displays a brief help message explaining command usage and available options, then exits.<br><br>


title: DESCRIPTION
content:
<b>pmap</b> (process memory map) is a Linux utility that reports the memory address space of a running process. It displays a detailed breakdown of the process's virtual memory regions, including their start and end addresses, permissions (read, write, execute), offset within the mapped file, device information (major:minor), inode number, and the path to the file or library being mapped (e.g., shared libraries, executables, anonymous memory). The command is invaluable for debugging memory-related issues, analyzing memory consumption, understanding how shared libraries are loaded, and identifying potential memory leaks. It provides a human-readable representation of the data found in <i>/proc/&lt;pid&gt;/maps</i> and <i>/proc/&lt;pid&gt;/smaps</i>, offering insights into how a process utilizes its RAM and virtual memory. Users can see private and shared memory usage, total resident set size (RSS), and other critical memory metrics.


title: CAVEATS
content:
<b>pmap</b> requires appropriate permissions to inspect a process. For processes not owned by the current user, <i>sudo</i> or root privileges might be necessary, depending on the system's <i>kernel.yama.ptrace_scope</i> setting. The output provides a snapshot of memory usage at the time of execution; memory maps can change dynamically for a running process. The reported sizes (like RSS) might differ slightly from other tools due to how memory regions are counted and reported. For very large processes with many memory regions, the output can be extensive.


title: UNDERSTANDING PMAP OUTPUT
content:
The <b>pmap</b> output columns typically include:<br><i>Address</i>: The starting virtual memory address of the region.<br><i>Kbytes</i>: The size of the region in kilobytes.<br><i>RSS</i> (Resident Set Size): The portion of the process's memory that is currently held in RAM (not swapped out).<br><i>Dirty</i>: Memory pages that have been modified (written to) and haven't been written back to disk yet.<br><i>Mode</i>: Permissions for the memory region (r=read, w=write, x=execute, s=shared, p=private).<br><i>Mapping</i>: The file or device mapped into this region, or special tags like <i>[heap]</i>, <i>[stack]</i>, <i>[anon]</i> (anonymous memory), or <i>[vdso]</i>.<br>The <b>pmap -x</b> option provides the most detailed view, including RSS and Dirty pages, which are crucial for understanding actual memory consumption. The data presented by <b>pmap</b> is primarily sourced from the kernel's <i>/proc/&lt;pid&gt;/maps</i> and <i>/proc/&lt;pid&gt;/smaps</i> files.


title: HISTORY
content:
<b>pmap</b> is a long-standing utility in the Linux ecosystem, typically part of the <i>procps</i> or <i>procps-ng</i> package. Its core functionality dates back to early Linux kernels, providing a user-friendly interface to the information exposed by the <i>/proc</i> filesystem, specifically <i>/proc/&lt;pid&gt;/maps</i>. As the <i>/proc</i> filesystem evolved to include more detailed memory information like <i>/proc/&lt;pid&gt;/smaps</i> (which distinguishes between private and shared memory usage), <b>pmap</b> adapted, with its <b>-x</b> (extended) option now often leveraging this richer data to provide more comprehensive memory statistics like Resident Set Size (RSS) and Dirty pages. Its development tracks the kernel's capabilities for exposing process memory details.


title: SYNOPSIS
content:
<B>pngcrush</B> [<I>OPTIONS</I>] <I>infile.png</I> [<I>outfile.png</I>]<br>When <I>outfile.png</I> is omitted, <I>infile.png</I> is processed in-place (overwritten).


title: PARAMETERS
content:
<b><B>-reduce</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Tries all possible filter and compression methods to find the smallest file size.<br><br><b><B>-brute</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Similar to <B>-reduce</B> but attempts even more combinations, potentially yielding better compression at the cost of significantly longer processing time.<br><br><b><B>-m</B> <I>&lt;method&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the compression method(s) to use. Common methods include 0 (deflate) or 1 (fixed Huffman).<br><br><b><B>-f</B> <I>&lt;filter&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects the PNG filter type(s) to apply (0=None, 1=Sub, 2=Up, 3=Average, 4=Paeth, 5=Adaptive). Using adaptive filtering is often recommended.<br><br><b><B>-l</B> <I>&lt;level&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the zlib compression level, a value from 0 (no compression) to 9 (maximum compression). Default is usually 9.<br><br><b><B>-rem</B> <I>&lt;chunk_name&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes specified ancillary chunks from the PNG file (e.g., <I>tEXt</I>, <I>tIME</I>, <I>sRGB</I>) to reduce file size or for privacy concerns. Use <B>-rem all</B> to remove all non-critical chunks.<br><br><b><B>-ow</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows overwriting the original <I>infile.png</I> when an <I>outfile.png</I> is not provided. This is the default behavior if no output file is specified.<br><br><b><B>-v</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output, displaying detailed progress and optimization results during processing.<br><br>


title: DESCRIPTION
content:
<i>pngcrush</i> is a command-line utility designed to <B>optimize PNG image files</B> by reducing their size without any loss of image quality. It achieves this lossless compression by exhaustively trying various filter methods, zlib compression levels, and other encoding strategies. <i>pngcrush</i> then selects the combination that results in the smallest possible file. It's particularly useful for images created with less optimal compression, enabling significant file size reductions often crucial for web performance. The tool supports all standard PNG features, including transparency and different color types. While it can be slower than some modern optimizers due to its brute-force approach, it is highly effective in finding the optimal compression for a given PNG image. Users can configure its behavior to focus on speed or maximum compression.


title: CAVEATS
content:
<i>pngcrush</i>, especially with options like <B>-brute</B> or high iteration counts, can be <B>very slow</B> and resource-intensive, consuming significant CPU and memory. It may not always produce a smaller file if the original PNG is already highly optimized, and in rare cases, the output file size might even increase slightly.


title: LOSSLESS OPTIMIZATION
content:
A key characteristic of <i>pngcrush</i> is that it performs <B>lossless optimization</B>. This means the image quality remains identical to the original; only the file size is reduced through more efficient encoding and compression without discarding any pixel data.


title: CHUNK MANAGEMENT
content:
<i>pngcrush</i> provides powerful features for managing PNG <B>chunks</B>. Users can explicitly remove or keep various ancillary chunks (e.g., metadata like creation time, software information, or gamma correction data). This allows for further file size reduction and can be important for privacy or specific rendering requirements.


title: HISTORY
content:
<i>pngcrush</i> was created by Glenn Randers-Pehrson and first released in the late 1990s. It has been a foundational tool for lossless PNG optimization, predating many other popular optimizers. Its development has focused on exhaustive search algorithms to achieve maximum compression, making it a reliable choice for achieving the smallest possible PNG file sizes. Despite its age, it remains actively maintained and widely used for its robust optimization capabilities.


title: PARAMETERS
content:
<b><i>pnmfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The input PNM image file. If omitted, <b>pnmpad</b> reads the image data from standard input.<br><br><b><b>-leftpad</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds <i>N</i> pixels of padding to the left side of the image.<br><br><b><b>-rightpad</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds <i>N</i> pixels of padding to the right side of the image.<br><br><b><b>-toppad</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds <i>N</i> pixels of padding to the top side of the image.<br><br><b><b>-bottompad</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds <i>N</i> pixels of padding to the bottom side of the image.<br><br><b><b>-pad</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds <i>N</i> pixels of padding to all four sides (left, right, top, bottom) of the image symmetrically.<br><br><b><b>-xpad</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds <i>N</i> pixels of padding horizontally (evenly split between left and right sides).<br><br><b><b>-ypad</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds <i>N</i> pixels of padding vertically (evenly split between top and bottom sides).<br><br><b><b>-width</b> <i>W</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the total desired output width of the image to <i>W</i> pixels. Padding is added symmetrically to achieve this width.<br><br><b><b>-height</b> <i>H</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the total desired output height of the image to <i>H</i> pixels. Padding is added symmetrically to achieve this height.<br><br><b><b>-color</b> <i><hexcolor></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the color of the padding. <i><hexcolor></i> can be an RGB hex value (e.g., <i>FF0000</i> for red) or an RGBA hex value (e.g., <i>FF000080</i> for semi-transparent red). The default padding color is black.<br><br><b><b>-white</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses white as the padding color. This is a shortcut for <b>-color FFFFFF</b>.<br><br><b><b>-black</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses black as the padding color. This is the default behavior and a shortcut for <b>-color 000000</b>.<br><br><b><b>-transparent</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses transparent padding. This option only works if the output image format supports an alpha channel (e.g., PAM). The input image must also support alpha or be converted to PAM for this to be effective.<br><br><b><b>-clip</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;If the specified output dimensions (using <b>-width</b> or <b>-height</b>) are smaller than the input image, the image will be clipped (cropped) to fit the new dimensions instead of being padded.<br><br><b><b>-verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints informational messages about the processing steps being performed by the command.<br><br>


title: DESCRIPTION
content:
The <b>pnmpad</b> command adds padding, or borders, to a Portable Anymap (PNM) image. This utility is part of the Netpbm image manipulation toolkit. It allows you to specify the amount of padding to add to each side (left, right, top, bottom) in pixels, or to specify a desired total output width and height, in which case the padding is added symmetrically. The padding can be filled with a specified color (black by default), white, or even made transparent if the output format supports an alpha channel.<br><br>This command is useful for adjusting image dimensions without scaling the content, creating frames around images, or preparing images for specific layouts. While primarily designed for padding, <b>pnmpad</b> can also clip an image if the desired output dimensions are smaller than the input and the <b>-clip</b> option is used, effectively performing the inverse operation.


title: INPUT AND OUTPUT
content:
<b>pnmpad</b> adheres to the standard Unix philosophy of reading from standard input and writing to standard output. By default, it reads a PNM image from standard input. If a <i>pnmfile</i> argument is provided, it reads from that specified file. The resulting padded (or clipped) PNM image is then written to standard output. This design allows it to be easily integrated into shell pipelines with other Netpbm utilities for complex image processing tasks.


title: INTERACTION OF PADDING OPTIONS
content:
When using multiple padding options, they are applied cumulatively. For instance, if you use <b>-pad N</b> and also <b>-leftpad M</b>, the left side will receive N+M pixels of padding. If <b>-width</b> or <b>-height</b> are used in conjunction with specific side padding options, the fixed side padding is applied first, and then symmetrical padding is added (or clipping is performed if <b>-clip</b> is active) to meet the final desired dimensions.


title: HISTORY
content:
<b>pnmpad</b> is a fundamental utility within the Netpbm project, a comprehensive suite of graphics programs developed over many years. The Netpbm toolkit, tracing its origins back to the early 1990s as PBMPLUS, provides a foundational set of tools for manipulating various image formats by converting them to and from the intermediate PNM (Portable Anymap) format. <b>pnmpad</b> has been a consistent component, providing a flexible way to adjust image canvases, essential for batch processing and automated image preparation workflows.


title: SYNOPSIS
content:
<I>pnmtopnm</I> [<B>-forceplain</B> | <B>-plain</B>] [<B>-unpredictable</B>] [<B>-nomaxval</B>] [<B>-fixupgamma</B>] [<B>-maxval</B> <I>N</I>] [<B>-gamma</B> <I>N</I>] [<B>-comment</B> <I>string</I>] [<B>-headerrow</B>] [<I>pnmfile</I>]


title: PARAMETERS
content:
<b><B>-forceplain</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output PNM to be in plain (ASCII) format, regardless of the input's format (raw or plain).<br><br><b><B>-plain</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A synonym for <B>-forceplain</B>.<br><br><b><B>-unpredictable</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Produces an output with unpredictable values. This option is primarily used for testing Netpbm programs to verify their robustness against unusual input.<br><br><b><B>-nomaxval</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;For PBM images (which always have a maximum pixel value of 1), this option prevents writing the <I>maxval</I> line in the output header, making the header shorter.<br><br><b><B>-fixupgamma</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adjusts gamma for plain format images. This helps in maintaining correct gamma representation when converting or processing images, especially with ASCII formats.<br><br><b><B>-maxval</B> <I>N</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the maximum pixel value (<I>maxval</I>) for the output PGM or PPM image. Input pixel values are scaled proportionally to this new range. <I>N</I> must be an integer between 1 and 65535.<br><br><b><B>-gamma</B> <I>N</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the gamma value for the output image. This affects the brightness and contrast perception of the image. <I>N</I> is a floating-point number.<br><br><b><B>-comment</B> <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a comment string to the header of the output PNM file. The comment is typically placed after the magic number and dimensions.<br><br><b><B>-headerrow</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a header row to the output. This option is generally used for specific processing needs or debugging, providing additional metadata in the output stream.<br><br>


title: DESCRIPTION
content:
<I>pnmtopnm</I> is a Netpbm command-line utility designed to convert a Portable Anymap (PNM) file to another PNM file. It serves as a generic wrapper for format-specific tools like <I>pbmtopbm</I>, <I>pgmtopgm</I>, and <I>ppmtoppm</I>, handling binary and ASCII versions of PBM, PGM, and PPM formats. Its primary function is to normalize or modify certain properties of a PNM image, such as changing its maximum pixel value (<I>maxval</I>), converting between plain (ASCII) and raw (binary) formats, or adjusting gamma. It's a fundamental tool for ensuring PNM files are compatible with other Netpbm utilities or for preparing them for specific applications, without altering the visual content of the image.<br>It reads from standard input if no file is specified and writes to standard output.


title: CAVEATS
content:
As a Netpbm utility, <I>pnmtopnm</I> strictly operates on PNM formats (PBM, PGM, PPM) and does not convert to or from other image types like JPEG or PNG. While it can adjust certain PNM properties such as <I>maxval</I> or format (plain/raw), it does not alter the actual pixel data or perform general image manipulations like cropping or resizing. Reducing the <I>maxval</I> for PGM/PPM images can lead to a loss of precision or information.


title: STANDARD INPUT/OUTPUT
content:
If no <I>pnmfile</I> is specified on the command line, <I>pnmtopnm</I> reads the PNM image data from standard input. The converted output is always written to standard output. This behavior allows for seamless piping operations, where the output of one Netpbm command can be directly fed as input to another, facilitating complex image processing workflows.


title: HISTORY
content:
Part of the Netpbm package, <I>pnmtopnm</I> traces its lineage back to the original Pbmplus tools created by Jef Poskanzer in 1988. As the Netpbm suite evolved, <I>pnmtopnm</I> solidified its role as a fundamental utility for normalizing and manipulating the internal properties of Portable Anymap (PNM) files, without affecting their visual content. It serves as a generic interface that often dispatches to specific format-to-format converters like <I>pbmtopbm</I>, <I>pgmtopgm</I>, and <I>ppmtoppm</I>, making it a core component for maintaining consistency within Netpbm image processing pipelines.


title: PARAMETERS
content:
<b><b>-none</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies no compression for the output <b>TIFF</b> file.<br><br><b><b>-packbits</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses <b>PackBits</b> compression, a lossless RLE (Run-Length Encoding) compression method.<br><br><b><b>-lzw</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies <b>LZW</b> (Lempel-Ziv-Welch) compression, a lossless compression algorithm.<br><br><b><b>-zip</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Utilizes <b>Deflate</b> (<b>ZIP</b>) compression, a lossless compression algorithm.<br><br><b><b>-jpeg</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies <b>JPEG</b> compression, a lossy compression method suitable for photographic images. Quality cannot be controlled directly by this option.<br><br><b><b>-g4</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies <b>Group 4 Fax</b> compression, a lossless compression method specifically for monochrome (1-bit) images. Input must be <b>PBM</b> or converted to monochrome.<br><br><b><b>-monochrome</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output <b>TIFF</b> to be 1-bit black and white (monochrome). Color and grayscale information will be lost.<br><br><b><b>-grayscale</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output <b>TIFF</b> to be 8-bit grayscale. Color information will be lost if input is <b>PPM</b>.<br><br><b><b>-truecolor</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output <b>TIFF</b> to be 24-bit <b>RGB</b> truecolor. Only relevant for <b>PPM</b> input.<br><br><b><b>-alpha</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Includes an alpha channel in the output <b>TIFF</b>. Only applicable when input is <b>PPM</b>.<br><br><b><b>-rowsperstrip</b> <i>&lt;n&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the number of rows per strip in the <b>TIFF</b> file. A strip is a block of image data.<br><br><b><b>-xresolution</b> <i>&lt;x&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the X (horizontal) resolution of the image in pixels per unit.<br><br><b><b>-yresolution</b> <i>&lt;y&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the Y (vertical) resolution of the image in pixels per unit.<br><br><b><b>-resolutionunit</b> <i>&lt;unit&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the unit for resolution, e.g., <i>inch</i>, <i>cm</i>, or <i>none</i>. Defaults to <i>inch</i>.<br><br><b><b>-description</b> <i>&lt;text&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the <b>TIFF</b> 'ImageDescription' tag to the specified text.<br><br><b><b>-datetime</b> <i>&lt;YYYY:MM:DD HH:MM:SS&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the <b>TIFF</b> 'DateTime' tag to the specified date and time string.<br><br><b><b>-documentname</b> <i>&lt;name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the <b>TIFF</b> 'DocumentName' tag to the specified name.<br><br><b><b>-pagename</b> <i>&lt;name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the <b>TIFF</b> 'PageName' tag to the specified name.<br><br><b><b>-software</b> <i>&lt;name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the <b>TIFF</b> 'Software' tag to the specified software name.<br><br><b><b>-predictor</b> <i>&lt;n&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the predictor for <b>LZW</b> or <b>Deflate</b> compression. Common values are 1 (no prediction), 2 (horizontal differencing).<br><br><b><b>-tiled</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes the <b>TIFF</b> file using tiles instead of strips. Requires <b>-tilewidth</b> and <b>-tilelength</b>.<br><br><b><b>-tilewidth</b> <i>&lt;w&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the width of tiles when <b>-tiled</b> is used.<br><br><b><b>-tilelength</b> <i>&lt;l&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the length (height) of tiles when <b>-tiled</b> is used.<br><br><b><b>-standard</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses the standard <b>TIFF</b> byte order (big-endian). This is usually the default.<br><br><b><b>-lsb</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes the <b>TIFF</b> with least-significant byte first (little-endian) byte order.<br><br><b><b>-msb</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes the <b>TIFF</b> with most-significant byte first (big-endian) byte order.<br><br><b><b>-multipage</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Experimental: Creates a multi-page <b>TIFF</b>. Each <b>PNM</b> input will be a separate page.<br><br><b><b>-nofillorder</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Does not specify the <b>TIFF</b> 'FillOrder' tag. Useful for compatibility with some older or non-standard readers.<br><br>


title: DESCRIPTION
content:
<i>pnmtotiff</i> is a powerful utility from the <b>Netpbm</b> image processing suite, designed to convert <b>PNM</b> (Portable Anymap) image files into the <b>TIFF</b> (Tagged Image File Format). It supports all <b>PNM</b> sub-formats: <b>PPM</b> (Portable Pixmap) for color images, <b>PGM</b> (Portable Graymap) for grayscale, and <b>PBM</b> (Portable Bitmap) for monochrome images.<br><br>The command offers extensive control over the output <b>TIFF</b> file, including various compression methods (e.g., <b>LZW</b>, <b>PackBits</b>, <b>JPEG</b>, <b>Deflate/ZIP</b>, <b>Group 4 Fax</b>), resolution settings, and metadata tags like description, date, and software. Users can specify the output image type (monochrome, grayscale, or truecolor <b>RGB</b>), even adding an alpha channel for <b>PPM</b> input.<br><br>Typically, <i>pnmtotiff</i> reads image data from standard input (allowing it to be easily chained with other <b>Netpbm</b> tools) and writes the resulting <b>TIFF</b> image to standard output. This makes it a versatile component in command-line image processing workflows.


title: CAVEATS
content:
<ul><li><b>Input Format:</b> <i>pnmtotiff</i> strictly requires <b>Netpbm</b> format (<b>PPM</b>, <b>PGM</b>, or <b>PBM</b>) as input. Attempting to convert other image formats directly will result in an error. Use other <b>Netpbm</b> tools like <i>anytopnm</i> to convert non-<b>PNM</b> formats first.</li><li><b>Lossy Compression:</b> When using <b>-jpeg</b> compression, quality settings are not directly controllable by <i>pnmtotiff</i> and may result in lossy compression artifacts.</li><li><b>Monochrome/Grayscale Conversion:</b> Converting color images to monochrome (<b>-monochrome</b>) or grayscale (<b>-grayscale</b>) will irreversibly discard color information.</li><li><b>Experimental Features:</b> Options like <b>-multipage</b> might be experimental or have limited support in some <b>TIFF</b> readers.</li><li><b>Dependencies:</b> <i>pnmtotiff</i> relies on the <b>libtiff</b> library for its functionality.</li></ul>


title: STANDARD INPUT/OUTPUT
content:
By default, <i>pnmtotiff</i> reads its <b>PNM</b> input from standard input (<i>stdin</i>) if no <i>pnmfile</i> argument is provided. It writes the resulting <b>TIFF</b> image to standard output (<i>stdout</i>). This design allows for flexible piping with other commands, such as: <i>cat image.ppm | pnmtotiff -lzw > image.tiff</i>.


title: DEFAULT BEHAVIOR
content:
If no options are specified, <i>pnmtotiff</i> will attempt to create a <b>TIFF</b> file that closely matches the input <b>PNM</b>. For <b>PPM</b> input, it typically produces 24-bit <b>RGB</b>. For <b>PGM</b>, 8-bit grayscale. For <b>PBM</b>, 1-bit monochrome. Default compression is usually <b>LZW</b> or no compression depending on the <b>libtiff</b> version and compile-time options.


title: HISTORY
content:
<i>pnmtotiff</i> is a key component of the <b>Netpbm</b> image processing package. <b>Netpbm</b> itself is a collection of graphics programs and a programming library that evolved from the earlier <b>Pbmplus</b> package, originally created by Jef Poskanzer in the late 1980s. Bryan Henderson has been the primary maintainer and developer of <b>Netpbm</b> since the mid-1990s.<br><br>The command's lineage reflects a common philosophy in Unix tools: small, focused utilities that do one thing well and can be chained together. Its integration within <b>Netpbm</b> allows it to seamlessly convert images from various sources (via <i>anytopnm</i>) into the versatile <b>TIFF</b> format, making it a foundational tool for image conversion in scripting and automated workflows for decades.


title: SYNOPSIS
content:
pnmtotiffcmyk [-c <i>compression</i>] [-r <i>rowsperstrip</i>] [-l] [-f] [-o <i>offset</i>] [-x <i>xres</i>] [-y <i>yres</i>] [-u <i>units</i>] [-w] [<i>pnmfile</i>]


title: PARAMETERS
content:
<b>-c <i>compression</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the TIFF compression method. Common options include <b>none</b>, <b>packbits</b>, <b>lzw</b>, <b>zip</b>, and <b>jpeg</b>.<br><br><b>-r <i>rowsperstrip</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the number of rows per strip in the output TIFF file. This affects how the image data is stored and read.<br><br><b>-l</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables LZW compression. This is equivalent to using <b>-c lzw</b>.<br><br><b>-f</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses FillOrder <b>LSB2MSB</b> (Least Significant Bit to Most Significant Bit) instead of the default <b>MSB2LSB</b> (Most Significant Bit to Least Significant Bit). This can affect how pixel bits are ordered.<br><br><b>-o <i>offset</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a byte offset for the image data within the TIFF file. Useful for specific file structures.<br><br><b>-x <i>xres</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the X resolution of the image in pixels per unit.<br><br><b>-y <i>yres</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the Y resolution of the image in pixels per unit.<br><br><b>-u <i>units</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the units for resolution. Possible values are <b>inch</b>, <b>cm</b>, or <b>none</b>.<br><br><b>-w</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints warnings for common usage mistakes or unusual conditions, which can be helpful for debugging.<br><br><b><i>pnmfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The input PNM file to convert. If omitted, <i>pnmtotiffcmyk</i> reads from standard input (stdin).<br><br>


title: DESCRIPTION
content:
<i>pnmtotiffcmyk</i> is a utility from the <b>Netpbm</b> image processing suite that converts a Portable Anymap (PNM) image into a Tagged Image File Format (TIFF) image using the CMYK color model. PNM images can be Portable Pixmap (PPM) for color, Portable Graymap (PGM) for grayscale, or Portable Bitmap (PBM) for black and white. CMYK (Cyan, Magenta, Yellow, Black) is the subtractive color model primarily used for commercial printing, where colors are created by applying various inks.<br><br>This command is crucial in workflows that prepare raster images for print. It takes an RGB (or grayscale) input from a PNM file (or standard input) and performs a mathematical conversion to CMYK values. While it does not incorporate advanced color management features like ICC profiles, it provides a foundational step for producing print-ready TIFFs. It supports various TIFF compression schemes and allows specifying output parameters like resolution, strips, and byte order.


title: CAVEATS
content:
<b>Input Format:</b> <i>pnmtotiffcmyk</i> strictly requires a PNM (PBM, PGM, or PPM) image as input. Other image formats must first be converted to PNM using tools like <i>anytopnm</i>.<br><br><b>Color Conversion Limitations:</b> The RGB-to-CMYK conversion performed by this command is a direct mathematical approximation and does not utilize ICC color profiles. This means that the resulting CMYK values may not precisely match specific print industry standards or desired color outputs without further color management in the print workflow.<br><br><b>Grayscale Handling:</b> When converting a PGM (grayscale) input, the output will be a CMYK TIFF where the Cyan, Magenta, and Yellow channels are zero, and the Black channel represents the grayscale intensity.


title: COLOR MODEL CONVERSION
content:
The command primarily handles the conversion from an implicit RGB (for PPM files) or grayscale (for PGM files) color space to CMYK. It's important to understand that this is a direct channel-to-channel transformation, not a perceptually accurate color space conversion based on spectrophotometric data or ICC profiles. Users requiring precise color matching for professional printing should either perform color management upstream with other tools or apply it post-conversion.


title: INTEGRATION IN WORKFLOWS
content:
<i>pnmtotiffcmyk</i> is often used as the final step in a <b>Netpbm</b> image processing pipeline. For instance, an image from an arbitrary format might first be converted to PNM (e.g., <b>giftoppm | ppmtogray | pnmtotiffcmyk</b>) before being output as a CMYK TIFF. This modularity is a hallmark of the <b>Netpbm</b> design philosophy, allowing for flexible and powerful scripting of image operations.


title: HISTORY
content:
<i>pnmtotiffcmyk</i> is an integral part of the widely used <b>Netpbm</b> package, a collection of graphics programs originating from <b>Pbmplus</b> developed by Jef Poskanzer in 1988. <b>Netpbm</b> was designed to be a modular toolkit, enabling users to chain simple, specialized commands together via pipes to achieve complex image manipulations. The inclusion of <i>pnmtotiffcmyk</i> specifically addresses the need for command-line tools capable of preparing raster images for commercial printing workflows, where the CMYK color model is standard. Its development reflects the evolution of desktop publishing and the continuous demand for robust, automatable image processing utilities.


title: SYNOPSIS
content:
<b>pnmtoxwd</b> [<i>-outfile name</i>] [<i>-verbose</i>] [<i>-map</i>|<i>-nomap</i>] [<i>-depth N</i>] [<i>-rgb</i>|<i>-norgb</i>] [<i>-invert</i>|<i>-noinvert</i>] [<i>-frame</i>|<i>-noframedata</i>] [<i>pnmfile</i>]


title: PARAMETERS
content:
<b>-outfile <name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the name of the output XWD file. If omitted, the output is written to standard output.<br><br><b>-verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose mode, printing informational messages about the conversion process to standard error.<br><br><b>-map</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output to be a pseudo-color (mapped) XWD file if the input PNM image has 256 colors or fewer. This is often the default behavior when appropriate.<br><br><b>-nomap</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output to be a TrueColor XWD file, even if a pseudo-color representation could be used. This ensures 24-bit or 32-bit output.<br><br><b>-depth <N></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the desired bit depth of the output XWD file. Common values include 1, 8, 16, 24, or 32. The program will attempt to match colors to the specified depth.<br><br><b>-rgb</b><br>&nbsp;&nbsp;&nbsp;&nbsp;When generating a TrueColor XWD, uses an RGB colormap rather than a standard X colormap. This can be beneficial for certain image viewers.<br><br><b>-norgb</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables the use of an RGB colormap for TrueColor XWD output. This is typically the default behavior.<br><br><b>-invert</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Inverts the colors of the image during conversion (e.g., black becomes white, white becomes black).<br><br><b>-noinvert</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables color inversion, maintaining the original color scheme. This is the default setting.<br><br><b>-frame</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Includes fake XWD frame data in the output file. This can be useful for applications that expect specific frame information from a true X window dump, though the data itself is not real.<br><br><b>-noframedata</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Excludes fake XWD frame data from the output file. This is the default setting.<br><br>


title: DESCRIPTION
content:
<b>pnmtoxwd</b> is a Netpbm utility designed to convert images from the Portable Anymap (PNM) format into the X Window Dump (XWD) format. PNM encompasses Portable Bitmap (PBM), Portable Graymap (PGM), and Portable Pixmap (PPM), allowing <b>pnmtoxwd</b> to process monochrome, grayscale, and color images.<br><br>The XWD format is commonly used to store screenshots or 'dumps' of windows and screens from the X Window System. This command is invaluable for developers and users who need to interchange image data between Netpbm's flexible image manipulation tools and applications that specifically require XWD input, such as certain X-based image viewers or development tools.<br><br><b>pnmtoxwd</b> intelligently handles various aspects of the conversion, including color depth management, mapping of colors (for pseudo-color XWDs), and TrueColor output, ensuring compatibility with a broad range of X displays and applications. It typically reads the PNM image from standard input if no file is specified, and writes the resulting XWD image to standard output, making it suitable for use in shell pipelines.


title: CAVEATS
content:
The XWD format has specific requirements for color depths and colormaps; while <b>pnmtoxwd</b> attempts to be robust, compatibility issues with some specific X applications may arise, especially when using non-standard depths or colormap types.<br>The <b>-frame</b> option adds <i>dummy</i> XWD frame data, not actual window geometry or properties, which might not satisfy all XWD parsers expecting real window information.


title: INPUT/OUTPUT BEHAVIOR
content:
By default, <b>pnmtoxwd</b> reads image data from standard input (<i>stdin</i>) and writes the converted XWD image to standard output (<i>stdout</i>). This design facilitates its use within shell pipelines, allowing it to be easily chained with other Netpbm utilities or commands. The <b>-outfile</b> option can be used to direct output to a specified file instead.


title: COLOR HANDLING LOGIC
content:
<b>pnmtoxwd</b> intelligently manages color conversion. For input images with 256 or fewer colors, it attempts to produce a pseudo-color (mapped) XWD, which is more compact. For images with more colors or when forced by options like <b>-nomap</b>, it generates a TrueColor XWD (typically 24-bit or 32-bit), accurately representing a broader color spectrum. The <b>-depth</b> option provides fine-grained control over the output bit depth, allowing users to optimize for specific display requirements.


title: HISTORY
content:
<b>pnmtoxwd</b> is a part of the Netpbm project, a comprehensive suite of graphics file format converters and manipulators. Netpbm itself has a long history, originating from the <i>pbmplus</i> package created by Jef Poskanzer in the late 1980s. <b>pnmtoxwd</b>, like other Netpbm tools, benefits from this heritage of robust, pipeline-friendly design, evolving over time to support various XWD features and Netpbm's internal image handling improvements.


title: SYNOPSIS
content:
<b>pnpm</b> <i>&lt;command&gt;</i> [<i>&lt;flags&gt;</i>]<br>Examples:<br><b>pnpm</b> <i>install</i><br><b>pnpm</b> <i>add</i> <i>&lt;package&gt;</i><br><b>pnpm</b> <i>run</i> <i>&lt;script&gt;</i>


title: PARAMETERS
content:
<b>--filter <package_selector></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Apply the command to specific packages within a workspace or monorepo.<br><br><b>--global, -g</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Install a package globally on the system.<br><br><b>--offline</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform installation using only packages available in the local cache, without network access.<br><br><b>--recursive, -r</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run a command in every package of the current workspace or monorepo.<br><br><b>--shamefully-hoist</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Create a flat <i>node_modules</i> structure, similar to npm or Yarn Classic, which might be necessary for compatibility with some older tools or ecosystems.<br><br><b>--dir <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the root directory of the project where pnpm should operate.<br><br>


title: DESCRIPTION
content:
pnpm (performant npm) is a modern, fast, and disk-efficient package manager for Node.js. It aims to overcome limitations of traditional package managers like npm and Yarn by employing a unique linking strategy. Instead of copying packages, pnpm uses a content-addressable store on disk to store all package versions. When installing dependencies for a project, it creates hard links from this global store to the project's <i>node_modules</i> directory, and then uses symlinks to create the project's dependency tree. This approach significantly reduces disk space consumption, especially in monorepos or across multiple projects sharing dependencies. Additionally, pnpm creates a strict <i>node_modules</i> structure, preventing accidental access to undeclared dependencies, which improves build reliability and helps catch issues early. It offers a command-line interface similar to npm, making it familiar for users, while providing superior performance and efficiency.


title: CAVEATS
content:
pnpm's strict <i>node_modules</i> structure, while beneficial for reliability, can sometimes cause compatibility issues with older tools or build systems that implicitly rely on hoisted (undeclared) dependencies. The <i>--shamefully-hoist</i> flag can be used as a workaround but should be considered a temporary solution. Users migrating from npm or Yarn might need to adjust their workflow slightly to accommodate pnpm's stricter dependency resolution.


title: CONTENT-ADDRESSABLE STORE
content:
pnpm maintains a global content-addressable store on your system. This means that each unique version of a package is stored only once. When a project needs a package, pnpm uses hard links from this store to the project's <i>node_modules</i>, dramatically saving disk space.


title: MONOREPO SUPPORT
content:
pnpm excels in monorepo environments. Its workspace feature allows managing multiple projects within a single repository, and its efficient linking mechanism ensures that dependencies shared across packages are only stored once, leading to faster installations and reduced disk footprint for the entire monorepo.


title: STRICTNESS AND DETERMINISM
content:
Unlike traditional package managers that might flatten the <i>node_modules</i> structure, pnpm creates a strict, symlinked structure. This ensures that a project can only access dependencies explicitly declared in its <i>package.json</i>, leading to more deterministic builds and preventing "phantom dependencies" issues.


title: HISTORY
content:
pnpm was created by Zoltan Kochan and first released in 2016. Its primary motivation was to address the inefficiencies of disk space usage and installation times prevalent in Node.js package management. It quickly gained traction, particularly among users managing large monorepos or projects with numerous dependencies, due to its innovative hard-linking approach and strong performance benefits. Its adoption has steadily grown as developers increasingly prioritize faster builds and more efficient resource utilization.


title: PARAMETERS
content:
<b><b>--fix</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Attempts to automatically resolve identified vulnerabilities by upgrading vulnerable dependencies to the earliest non-vulnerable version. This modifies your <i>pnpm-lock.yaml</i> and <i>package.json</i>.</i><br><br><b><b>--json</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Outputs the audit report in machine-readable JSON format, suitable for programmatic parsing and integration with CI/CD pipelines.</i><br><br><b><b>--prod</b>, <b>--production</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Audits only production dependencies. This excludes development dependencies listed under <i>devDependencies</i> in <i>package.json</i>.</i><br><br><b><b>--dev</b>, <b>--development</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Audits only development dependencies. This excludes production dependencies.</i><br><br><b><b>--audit-level</b> <<i>level</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specifies the minimum vulnerability level to report. Valid levels are 'info', 'low', 'moderate', 'high', and 'critical'. Only vulnerabilities at or above the specified level will be displayed.</i><br><br><b><b>--recursive</b>, <b>-r</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Runs the audit command in every package found in subdirectories or within a pnpm workspace, providing a consolidated report.</i><br><br>


title: DESCRIPTION
content:
The <i>pnpm-audit</i> command scans your project's dependencies for known security vulnerabilities by comparing them against a comprehensive vulnerability database, typically maintained by npm, Inc. It reads the <i>pnpm-lock.yaml</i> file or <i>package.json</i> to identify installed packages and their versions.<br><br>The primary purpose of <i>pnpm-audit</i> is to help developers proactively identify and mitigate security risks within their software supply chain. When executed, it provides a detailed report outlining identified vulnerabilities, their severity (e.g., low, moderate, high, critical), affected packages, and recommended remediation steps, such as upgrading to a non-vulnerable version. This command is an essential tool for maintaining the security integrity of Node.js projects managed with pnpm, ensuring that known security flaws in third-party libraries are addressed before deployment.


title: CAVEATS
content:
<i>pnpm-audit</i> relies on external vulnerability databases, which may occasionally contain false positives or lag behind the latest discoveries. The <b>--fix</b> option, while convenient, might introduce breaking changes if the suggested upgrades involve major version bumps or significant API changes. It is always recommended to review the proposed changes and run tests after using <b>--fix</b>. An active internet connection is typically required to fetch the latest vulnerability data.


title: EXIT CODES
content:
<i>The <i>pnpm-audit</i> command exits with a non-zero status code (typically 1) if any vulnerabilities are found, making it suitable for use in CI/CD pipelines to enforce security checks. It exits with 0 if no vulnerabilities are detected or if the command executes successfully without issues.</i>


title: VULNERABILITY LEVELS
content:
<i>Vulnerabilities are categorized by severity: <b>info</b> (informational), <b>low</b> (minor impact), <b>moderate</b> (some impact), <b>high</b> (significant impact), and <b>critical</b> (severe impact, often leading to remote code execution). These levels help prioritize remediation efforts.</i>


title: USAGE EXAMPLES
content:
<ul><li><i>To perform a basic audit: <b>pnpm audit</b></i></li><li><i>To audit and attempt to fix vulnerabilities: <b>pnpm audit --fix</b></i></li><li><i>To audit only critical vulnerabilities: <b>pnpm audit --audit-level critical</b></i></li><li><i>To get JSON output: <b>pnpm audit --json</b></i></li></ul>


title: HISTORY
content:
The <i>pnpm-audit</i> command was introduced as part of <i>pnpm</i>'s ongoing efforts to provide robust security features, mirroring capabilities found in other popular Node.js package managers like npm and Yarn. Its inclusion underscores the importance of supply chain security in modern software development, allowing <i>pnpm</i> users to integrate vulnerability scanning directly into their development workflows. The command's functionality and options have evolved to align with industry best practices for auditing package dependencies.


title: PARAMETERS
content:
<b><I>package</I>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional: Specify one or more package names to check only those specific packages for outdated versions.<br><br><b><b>-r, --recursive</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Check for outdated dependencies in all packages within the current workspace.<br><br><b><b>--long</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display full package information, including <i>pnpm update</i> options if applicable, such as <i>pnpm update --interactive</i>.<br><br><b><b>--json</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output the results in JSON format, which is useful for programmatic consumption.<br><br><b><b>--no-table</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not print the default tabular output. This is particularly useful when combined with <b>--json</b> or <b>--parseable</b>.<br><br><b><b>--prod, --production</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Check only production dependencies (those listed under 'dependencies' in <i>package.json</i>).<br><br><b><b>--dev</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Check only development dependencies (those listed under 'devDependencies' in <i>package.json</i>).<br><br><b><b>-g, --global</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Check globally installed packages for outdated versions.<br><br><b><b>--strict</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exit with a non-zero status code (1) if any dependency is found to be outdated. By default, the command exits with 0 even if outdated packages are found.<br><br><b><b>--workspace</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only check for outdated dependencies that are used by the workspace itself (root project in a monorepo). Typically used in conjunction with <b>--recursive</b>.<br><br><b><b>--stable</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only show the <i>latest</i> versions that are considered stable (i.e., exclude prerelease or build metadata versions like 1.0.0-beta).<br><br><b><b>--filter &lt;package_selector&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filter which workspace packages to check for outdated dependencies. Refer to <i>pnpm help filter</i> for details on valid selectors.<br><br><b><b>--prefix &lt;path&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run the command in a different directory than the current working directory.<br><br><b><b>--parseable</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output in a machine-readable, line-by-line format for easy parsing by scripts or other tools.<br><br>


title: DESCRIPTION
content:
<i>pnpm outdated</i> scans your project's <i>package.json</i> and <i>pnpm-lock.yaml</i> to identify dependencies that have newer versions available than what is currently installed or specified. It displays a table showing the current version, the wanted version (based on semver ranges in <i>package.json</i>), and the latest available version. This command helps developers keep their project dependencies up-to-date, identify potential breaking changes, and manage security vulnerabilities by providing a clear overview of available updates before running <i>pnpm update</i>.


title: CAVEATS
content:
<i>pnpm outdated</i> is a reporting tool only; it does not update dependencies. To perform updates, you must explicitly run <i>pnpm update</i>.<br>The 'Wanted' column is constrained by the semantic versioning ranges specified in your <i>package.json</i>, while 'Latest' represents the absolute newest version on the registry, which may include major version updates with breaking changes.<br>When working with monorepos, remember to use <b>--recursive</b> or <b>--filter</b> to ensure all relevant packages are scanned.


title: OUTPUT COLUMNS EXPLAINED
content:
The command's default tabular output typically includes the following columns:<br><b>Package</b>: The name of the dependency.<br><b>Current</b>: The version currently installed in your <i>node_modules</i> directory.<br><b>Wanted</b>: The highest version of the package that satisfies the semantic versioning range specified in your <i>package.json</i>.<br><b>Latest</b>: The absolute latest version of the package published on the registry, regardless of your <i>package.json</i> constraints.<br><b>Package Type</b>: Indicates whether the dependency is a production dependency (Prod) or a development dependency (Dev).<br><b>URL</b>: If available, a link to the package's homepage or repository.


title: EXIT STATUS
content:
By default, <i>pnpm outdated</i> exits with a status code of 0, even if it finds outdated packages. This behavior allows it to be used flexibly without immediately failing scripts. However, if the <b>--strict</b> option is used, the command will exit with a non-zero status (1) if any outdated dependencies are found, which is particularly useful for integrating into CI/CD pipelines to enforce dependency freshness.


title: HISTORY
content:
<i>pnpm</i> (Performant Node.js Package Manager) was created by Zoltan Kochan, distinguishing itself from other package managers by utilizing a content-addressable store for efficient disk space usage and faster installation times. The <i>outdated</i> command is a fundamental utility across package managers, providing crucial transparency into a project's dependency health. It has been a standard feature since early versions of pnpm, continuously evolving alongside the CLI to offer detailed insights into available updates.


title: SYNOPSIS
content:
<b>pnpx</b> [<i>options</i>] <i>&lt;command&gt;</i> [<i>&lt;args...&gt;</i>]<br><b>pnpx</b> [<i>options</i>] <b>-p</b> <i>&lt;package&gt;</i> [<b>-p</b> <i>&lt;package&gt;</i>...] <i>&lt;command&gt;</i> [<i>&lt;args...&gt;</i>]


title: PARAMETERS
content:
<b><b>-p</b>, <b>--package</b> <i>&lt;package&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify packages to install before running the command. Can be used multiple times for multiple packages. The package name can include a version (e.g., <b>react-scripts@latest</b>).<br><br><b><b>-s</b>, <b>--silent</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Don't log any output from <b>pnpm</b> itself. Only the output of the executed command will be shown.<br><br><b><b>--no-install</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;If the command or package needs to be installed, <b>pnpx</b> will fail instead of performing the installation. Useful in strict environments.<br><br><b><b>--shell-mode</b>, <b>-c</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Execute the command in a shell. This can be useful if the command involves shell-specific syntax or pipe operations.<br><br><b><b>--offline</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only use packages that are already present in the local <b>pnpm</b> store. Fails if a package needs to be downloaded.<br><br><b><b>--prefer-offline</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use packages from the local store if possible, but fall back to downloading if a package is not found locally.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show help information for the <b>pnpx</b> command.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output the current version of <b>pnpm</b> (and thus <b>pnpx</b>).<br><br>


title: DESCRIPTION
content:
<b>pnpx</b> is the command-line tool bundled with <b>pnpm</b>, designed to execute Node.js package binaries without requiring them to be globally installed or explicitly added to your project's <b>node_modules</b>. It functions as <b>pnpm's</b> counterpart to <b>npm's npx</b> command.<br><br>When you run <b>pnpx <command></b>, it first checks if the specified command's executable is available in the local <b>node_modules/.bin</b> directory. If not found, <b>pnpx</b> temporarily installs the package containing the command into <b>pnpm's</b> content-addressable store, linking it into a temporary location, and then executes the command. After execution, the temporary installation is often cleaned up, though the package itself remains in the global store for future use, saving disk space and speeding up subsequent executions.<br><br>This utility is invaluable for running one-off command-line tools, scaffolding new projects (e.g., <b>pnpx create-react-app</b>), or trying out package functionalities without cluttering your global environment or project dependencies.


title: CAVEATS
content:
<b>pnpx</b> requires <b>pnpm</b> to be installed on your system. While it aims for efficiency, initial execution of a new command might involve downloading the package, which requires an internet connection. Be cautious when executing commands from untrusted sources, as <b>pnpx</b> will run them with your user's permissions.


title: HOW IT WORKS
content:
<b>pnpx</b> first checks if the executable is in your project's <b>node_modules/.bin</b>. If not, it uses <b>pnpm's</b> store to either retrieve a cached version or download and install the package. It then creates temporary symlinks to make the command available in the current shell's PATH for execution. This ensures that the command runs using the specific package version intended, without polluting your global environment.


title: SCAFFOLDING TOOLS
content:
A common use case for <b>pnpx</b> is to run project scaffolding tools. For example, to create a new React app, you can use <b>pnpx create-react-app my-app</b>. This downloads and executes the <b>create-react-app</b> tool directly without needing to install it globally or adding it as a project dependency first, making it a convenient way to bootstrap new projects.


title: HISTORY
content:
<b>pnpm</b>, short for 'Performant Node Package Manager,' emerged as a fast and disk-space efficient alternative to <b>npm</b> and <b>yarn</b>. As <b>npm's npx</b> gained popularity for simplifying the execution of Node.js package binaries, <b>pnpm</b> introduced <b>pnpx</b> as its direct counterpart. <b>pnpx</b> leverages <b>pnpm's</b> unique content-addressable store, which uses hard links and symlinks to share dependencies across projects, allowing for highly efficient caching and minimal disk space usage when executing transient commands.


title: SYNOPSIS
content:
<b>po4a-gettextize</b> [<i>options</i>] <i>&lt;input_file&gt; &lt;output_pot_file&gt;</i><br><b>po4a-gettextize</b> [<i>options</i>] <b>--master-language</b> <i>&lt;lang&gt; &lt;input_file&gt; &lt;output_pot_file&gt;</i>


title: PARAMETERS
content:
<b><b>--master-language</b> <i>&lt;lang&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the language of the source document, helping the parser correctly identify translatable content.<br><br><b><b>--format</b> <i>&lt;fmt&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly sets the format of the input document (e.g., '<b>man</b>', '<b>docbook</b>', '<b>sgml</b>', '<b>tex</b>', '<b>txt</b>'). If not specified, <b>po4a</b> attempts to guess.<br><br><b><b>--option</b> <i>&lt;fmt:opt[=val]&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Passes a specific option to the parser for the specified format. Useful for fine-tuning parsing behavior.<br><br><b><b>--add-references</b> <i>&lt;type&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds references (e.g., line numbers, paragraph numbers) to the PO file to aid translators in context.<br><br><b><b>--keep</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Retains temporary files generated during the process, useful for debugging.<br><br><b><b>--verbose</b>, <b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increases the verbosity or debug level of the output, providing more information about the extraction process.<br><br><b><b>--localized-files</b> <i>&lt;files&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a comma-separated list of already localized files. Less common for <b>gettextize</b> directly, more for updating PO files.<br><br><b><b>--srcdir</b> <i>&lt;dir&gt;</i>, <b>--destdir</b> <i>&lt;dir&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify source and destination directories. Primarily used when processing multiple files or in conjunction with <b>po4a</b> build systems.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information of <i>po4a-gettextize</i>.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows a concise help message with available options.<br><br>


title: DESCRIPTION
content:
<i>po4a-gettextize</i> is a utility from the <b>po4a</b> (PO for Anything) project designed to extract translatable strings from various documentation formats and store them in <b>Gettext Portable Object Template</b> (<b>.pot</b>) files. This command is the crucial first step in localizing documentation using the <b>po4a</b> toolchain. It acts as a parser that understands different input formats, such as man pages, DocBook, SGML, TeX, LaTeX, or even simple text files. It scans the input document, identifies the parts marked as translatable content (e.g., text, section titles, paragraphs), and then generates a <b>.pot</b> file. This <b>.pot</b> file serves as a template that can be distributed to translators. Translators then create <b>.po</b> files containing the translations for specific languages. The command ensures that the original document structure is preserved, allowing for the re-integration of translated strings without breaking the document's layout. It simplifies the localization workflow by automating the extraction process, making it easier to manage and update translations for complex documentation sets.


title: CAVEATS
content:
While <i>po4a-gettextize</i> is versatile, its effectiveness heavily relies on correct format detection or explicit specification via <b>--format</b>. Incorrect format specification can lead to incomplete or erroneous string extraction. Some complex or malformed documents might not be parsed perfectly, requiring manual adjustments or specific format options. The quality of the generated <b>.pot</b> file directly impacts the ease of translation.


title: WORKFLOW INTEGRATION
content:
<i>po4a-gettextize</i> is the first step in the typical <b>po4a</b> translation workflow. After generating the <b>.pot</b> file, translators translate it into language-specific <b>.po</b> files. These <b>.po</b> files are then used by <i>po4a-translate</i> to generate the localized versions of the original document. <i>po4a-updatepo</i> is used to update existing <b>.po</b> files when the original document changes, ensuring efficient maintenance of translations.


title: SUPPORTED FORMATS
content:
The command supports a growing list of document formats, including but not limited to: <b>man</b> pages, <b>DocBook</b>, <b>SGML</b>, <b>TeX</b>, <b>LaTeX</b>, ASCII text, <b>pod</b> (Plain Old Documentation), <b>XML</b>, and various Debian-specific formats like <b>debian/changelog</b>. The accuracy of extraction depends on the quality of the format parser (often called a 'module' within <b>po4a</b>) for that specific format.


title: HISTORY
content:
The <i>po4a</i> project, of which <i>po4a-gettextize</i> is a core component, was initiated to bridge the gap between documentation formats and the Gettext translation system. Prior to <b>po4a</b>, localizing documentation often involved manual text extraction or complex, format-specific scripting. <i>po4a-gettextize</i> automates this extraction, enabling a consistent and scalable workflow for translating a wide array of document types, including man pages, which were notoriously difficult to localize systematically.


title: PARAMETERS
content:
<b><b>-f</b>, <b>--format</b> <i>&lt;module&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the format of the input document. Examples include <i>man</i>, <i>pod</i>, <i>sgml</i>, <i>tex</i>, <i>docbook</i>, or <i>xml</i>. This tells <i>po4a</i> which parsing module to use.<br><br><b><b>-o</b>, <b>--option</b> <i>&lt;module_options&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Passes specific options to the chosen translation module. The available options depend on the selected <i>--format</i>.<br><br><b><b>-M</b>, <b>--master-language</b> <i>&lt;lang&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the language code of the original (master) document, e.g., <i>en</i> for English.<br><br><b><b>-L</b>, <b>--localized-language</b> <i>&lt;lang&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the language code of the translated (localized) document that will be generated, e.g., <i>fr</i> for French.<br><br><b><b>-k</b>, <b>--keep-non-translated</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;If a paragraph or string in the master document is not found translated in the PO file, this option ensures the original (master language) text is retained in the output. Otherwise, such segments might be omitted or marked.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increases the verbosity level of the output, providing more information about the translation process.<br><br><b><b>-d</b>, <b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables debug output, which is useful for troubleshooting issues with the translation process or module parsing.<br><br><b><b>--no-translator-credits</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses the addition of standard translator credit lines (often added by default by <i>po4a</i>) to the generated output document.<br><br><b><b>--poref-encoding</b> <i>&lt;encoding&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the character encoding of the input PO file, such as <i>UTF-8</i>.<br><br><b><b>--src-encoding</b> <i>&lt;encoding&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the character encoding of the source (input) document, e.g., <i>ISO-8859-1</i>.<br><br><b><b>--dest-encoding</b> <i>&lt;encoding&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the character encoding of the output (destination) document. This is often the same as the PO file's encoding.<br><br><b><b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the translation process to proceed even if minor errors or untranslatable sections are encountered, attempting to produce output regardless.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message with usage information and available options.<br><br><b><b>-V</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the version information for the <i>po4a-translate</i> command.<br><br>


title: DESCRIPTION
content:
<i>po4a-translate</i> is a central utility within the po4a (PO for anything) toolkit. Its primary function is to take a source document (such as a man page, POD file, XML document, or LaTeX file) and a Gettext Portable Object (PO) file containing its translations, and then produce a new document. This new document retains the original format but incorporates the translated content from the PO file. This process is crucial for maintaining multi-lingual documentation, allowing developers and translators to use a standardized workflow based on Gettext. The command supports various document formats through a modular system, parsing and re-assembling the content to ensure translations are accurately placed while preserving the document's structure and layout.


title: CAVEATS
content:
<i>po4a-translate</i> relies heavily on the correctness of the input PO file and the ability of <i>po4a</i>'s modules to parse the source document format. Issues can arise if the PO file is malformed, if the source document contains unusual structures not handled by the selected module, or if character encodings are not correctly specified, potentially leading to garbled text or incomplete translations. Non-translated segments will be omitted unless <i>--keep-non-translated</i> is used.


title: COMMON USAGE EXAMPLE
content:
<b>Translating a man page from English to French:</b><br><br>Suppose you have <i>mydoc.en.pod</i> (the original English source document in POD format) and <i>mydoc.fr.po</i> (the French translation PO file). You want to generate <i>mydoc.fr.man</i> (the translated French man page).<br><br>The command would be:<br><br><code>po4a-translate -f pod -M en -L fr mydoc.en.pod mydoc.fr.po mydoc.fr.man</code><br><br>This command instructs <i>po4a-translate</i> to use the 'pod' format module, specifying the master language as English and the localized language as French. It then processes the source file, applies the translations from the PO file, and writes the resulting French man page to the specified output file.


title: HISTORY
content:
The po4a project, including <i>po4a-translate</i>, originated around 2002 within the Debian community with the goal of facilitating the translation of various documentation formats (like man pages and developer documentation) using the well-established Gettext localization framework. This filled a gap where Gettext was primarily used for software string internationalization, but not extensively for documentation. <i>po4a-translate</i> has evolved to support an increasing number of document types and to handle complex document structures, becoming a robust tool for integrating documentation into standard translation workflows.


title: PARAMETERS
content:
<b>-f, --force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the recreation of internal files, even if they appear up-to-date. This can be useful for troubleshooting.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increase the verbosity of the output. Multiple '-v' options increase verbosity further.<br><br><b>-d, --debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable debug output. Useful for developers and advanced troubleshooting.<br><br><b>-q, --quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress all normal output, only showing errors or warnings.<br><br><b>--dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform a trial run without making any actual changes to the PO files or disk. Shows what would happen.<br><br><b>--no-preserve-po</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not preserve the original PO file structure during the update process. This might lead to some entries being reordered or formatted differently.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a short help message and exit.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the version information of po4a and exit.<br><br><b>--man</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the full manual page for <b>po4a-updatepo</b>.<br><br><b>--shell</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a shell script that can be used to run <b>po4a-updatepo</b>, useful for debugging its execution environment.<br><br>


title: DESCRIPTION
content:
The <b>po4a-updatepo</b> command is a core utility within the po4a (PO for anything) project. Its primary function is to update translation (PO) files after the original source document from which they were derived has been modified.<br><br>When a document undergoes changes, such as adding new paragraphs, modifying existing text, or removing sections, the corresponding PO files need to be synchronized to reflect these alterations. <b>po4a-updatepo</b> automates this process by reading a configuration file that specifies the relationship between source documents and their PO files. It internally leverages <b>po4a-gettextize</b> to extract translatable strings from the updated source and then uses <b>msgmerge</b> to intelligently merge these new strings with the existing translations in the PO file, preserving existing translations where possible and marking new/changed strings for translation.<br><br>This command is typically run by translators or build systems whenever the source documentation is updated, ensuring that the translation efforts remain aligned with the source content.


title: CAVEATS
content:
<b>po4a-updatepo</b> relies heavily on a correctly configured <I>po4a.conf</I> file. Incorrect paths, formats, or processing options in the configuration can lead to errors or unexpected behavior. Always ensure your configuration is up-to-date and matches your document structure.<br><br>While <b>po4a-updatepo</b> tries to preserve existing translations, it's always recommended to use version control (e.g., Git) for your source documents and translation files. This provides a robust way to revert changes if something goes wrong during the update process.


title: CONFIGURATION FILE (<I>CONFIG_FILE</I>)
content:
The <I>config_file</I> argument is mandatory and specifies the path to a po4a configuration file, typically named <I>po4a.conf</I>. This file defines the relationship between your source documents and their corresponding PO translation files. It specifies:<br>- The original document format (e.g., man, sgml, docbook, pod).<br>- The path to the source document.<br>- The path to the PO file to be updated.<br>- Options for parsing and handling the specific document type.<br><b>po4a-updatepo</b> reads this file to determine which documents to process and how to perform the update. Without a valid configuration, the command cannot function.


title: HISTORY
content:
The po4a project, which includes <b>po4a-updatepo</b>, was initiated by Martin Quinson around 2002-2003 with the goal of facilitating the translation of various document formats using the Gettext PO file standard. It aimed to bridge the gap between document processing tools and traditional translation workflows. Over the years, it has been actively maintained and extended by various developers, notably Norbert Preining, becoming a robust and widely used tool for internationalizing documentation in open-source projects.


title: SEE ALSO
content:
po4a(7), po4a-gettextize(1), po4a-translate(1), po4a-normalize(1), po4a-build(1), po4a-display-strings(1), po4a-compress-infos(1), po4a.conf(5), msgmerge(1), xgettext(1)


title: PARAMETERS
content:
<b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message and exit.<br><br><b>-V, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output version information and exit.<br><br><b>-s, --summary</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print a single summary line for all files instead of detailed counts for each.<br><br><b>-t, --total</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print grand totals for all processed files. This option requires the <i>--summary</i> option to be effective.<br><br><b>-n, --no-headers</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress the header lines that typically describe the output columns.<br><br><b>-e, --empty</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Count empty translation strings (<i>msgstr ""</i>) as untranslated. By default, empty strings might be considered translated if they are not marked fuzzy.<br><br><b>-f, --fuzzy</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Count fuzzy entries as untranslated. Fuzzy entries are translations marked as potentially incorrect or needing human review (e.g., automatically translated or marked by a translator for later review).<br><br><b>-U, --untranslated-strings</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly count untranslated strings, including those that are empty or fuzzy, as untranslated.<br><br><b>-T, --translated-strings</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly count non-empty, non-fuzzy strings as translated.<br><br><b>--statistics</b><br>&nbsp;&nbsp;&nbsp;&nbsp;This option implies <i>--summary</i> and prints a summary line, similar to <i>--summary</i>.<br><br><b>[FILE]...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more PO (Portable Object) files to be processed by <i><b>pocount</b></i>. If no files are specified, it typically reads from standard input.<br><br>


title: DESCRIPTION
content:
<i><b>pocount</b></i> is a command-line utility that is part of the GNU <i>gettext</i> toolset, which is widely used for software internationalization (i18n) and localization (l10n). Its core purpose is to provide statistical insights into PO (Portable Object) files. These files are standard plain text files used by <i>gettext</i> to store translatable strings and their corresponding translations.<br><br>When executed, <i><b>pocount</b></i> processes one or more specified PO files and outputs a count of the messages found within them. It typically distinguishes between three main categories: total messages, translated messages, and untranslated messages. This functionality is crucial for localization teams to monitor the progress of translation efforts, identify remaining work, and assess the completeness of language packs.<br><br>The command offers various options to fine-tune how messages are categorized. For instance, users can specify whether empty translation strings or "fuzzy" entries (translations marked as uncertain, often needing human review) should be considered untranslated. It can present detailed counts for each file, or a consolidated summary line for all processed files, which can include grand totals. This flexibility makes <i><b>pocount</b></i> an invaluable tool for managing large-scale translation projects, ensuring that all necessary strings are localized accurately and efficiently. Its simplicity and integration within the <i>gettext</i> ecosystem make it a go-to choice for PO file analysis.


title: CAVEATS
content:
<i><b>pocount</b></i> relies on the correct formatting of PO files. Malformed PO files might lead to unexpected results or errors. The precise definition of "translated" versus "untranslated" messages can be nuanced and is highly dependent on the chosen command-line options such as <i>--empty</i> and <i>--fuzzy</i>. Users must understand how these options categorize messages to accurately interpret the output.


title: USAGE CONTEXT
content:
<i><b>pocount</b></i> is primarily utilized within software development and localization workflows. It's often integrated into automated build scripts or used by localization project managers to assess translation progress, monitor quality, and identify specific language files or strings requiring further translation effort. Its output can be used to generate reports or integrate with project management dashboards.


title: PO FILE STRUCTURE
content:
PO (Portable Object) files are plain text files that typically contain original source strings (marked by <i>msgid</i>) and their corresponding translated strings (marked by <i>msgstr</i>). These files can also include various forms of comments, context indicators, and flags such as 'fuzzy', which <i><b>pocount</b></i> interprets when calculating its counts based on the supplied options.


title: HISTORY
content:
<i><b>pocount</b></i> is an integral part of the GNU <i>gettext</i> project, which was originally conceived at Sun Microsystems in the early 1990s and later adopted and extensively developed by the GNU Project. <i>gettext</i> rapidly became the de facto standard for internationalization in free and open-source software. <i><b>pocount</b></i> specifically emerged as a valuable tool within this ecosystem to help manage the increasing complexity of translation projects. It provides a quick and automated overview of translation completeness, eliminating the need for manual parsing of PO files. Its development closely tracks the evolution of the broader <i>gettext</i> suite, ensuring continued compatibility and utility for modern localization workflows.


title: PARAMETERS
content:
<b><b>--backlink</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a 'Back to Top' link at the end of sections in the generated HTML.<br><br><b><b>--css</b>=<<i>url</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a URL for an external CSS stylesheet to be linked in the generated HTML <b><head></b> section.<br><br><b><b>--footer</b>=<<i>text</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds custom <i>text</i> to the footer of the generated HTML page.<br><br><b><b>--header</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a standard HTML header to the page, typically including a main title and an index table of contents.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief help message with command options and exits.<br><br><b><b>--htmldir</b>=<<i>dir</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the directory where output HTML files should be placed. Used when converting multiple files.<br><br><b><b>--htmlroot</b>=<<i>url</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the base URL for generated links within the HTML, crucial for correct cross-linking.<br><br><b><b>--idx</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates a <i>pod2html.idx</i> file, which acts as an index of all generated HTML files, useful for navigation.<br><br><b><b>--infile</b>=<<i>file</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the input Pod <i>file</i> to be converted. Can be used instead of or in addition to positional arguments.<br><br><b><b>--inout</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads Pod from standard input (stdin) and writes HTML to standard output (stdout).<br><br><b><b>--level</b>=<<i>num</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls the highest heading level used in the HTML output, from 1 to 6, affecting structure.<br><br><b><b>--noindex</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses the generation of index entries for the current file, even if <b>--idx</b> is used globally.<br><br><b><b>--outfile</b>=<<i>file</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output HTML <i>file</i>. If not specified, output goes to stdout or a file named after the input with a <i>.html</i> extension.<br><br><b><b>--podpath</b>=<<i>dir</i>>[:<<i>dir</i>>...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;A colon-separated list of directories to search for Pod files referenced in <b>L<></b> linking codes.<br><br><b><b>--quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses warnings and other non-critical messages during conversion.<br><br><b><b>--title</b>=<<i>title</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the <i>title</i> for the generated HTML page's <b><title></b> tag, displayed in browser tabs.<br><br><b><b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output, showing progress and additional information about the conversion process.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the <i>pod2html</i> version information and exits.<br><br>


title: DESCRIPTION
content:
<i>pod2html</i> is a utility included with Perl that converts files written in the Pod (Plain Old Documentation) format into HTML. Pod is a simple markup language primarily used for documenting Perl modules and scripts. This tool is essential for making Perl documentation accessible via web browsers, allowing developers to publish their module documentation on websites or use it for local browsing.<br><br>It handles various Pod constructs like headings, paragraphs, lists, code blocks, and text formatting codes (<b>B<></b> for bold, <i>I<></i> for italic, <code>C<></code> for code). <i>pod2html</i> can generate an index, manage cross-links between documentation files, and integrate external CSS for styling, making the generated HTML highly customizable and readable. It's a fundamental component in the Perl ecosystem for creating web-based documentation.


title: CAVEATS
content:
<i>pod2html</i> relies on Perl being installed on the system. While it provides options for basic styling via CSS, advanced HTML structure customization beyond what Pod inherently supports is limited. Proper handling of character encoding is crucial to avoid display issues; ensure input Pod files are correctly encoded and that the output HTML's character set is declared appropriately. Cross-linking (via <b>L<></b> codes) requires careful configuration of <b>--podpath</b> and <b>--htmldir</b> to resolve links correctly, especially for documentation distributed across multiple directories.


title: EXIT STATUS
content:
<i>pod2html</i> returns <b>0</b> upon successful conversion, and a non-zero value (typically <b>1</b>) if an error occurs during processing, such as an invalid input file or an internal error.


title: ENVIRONMENT VARIABLES
content:
The behavior of <i>pod2html</i> can be influenced by certain environment variables. For instance, <b>POD_HTML_DEFAULT_CSS</b> can be set to a URL to specify a default CSS stylesheet, which will be used if no <b>--css</b> option is provided on the command line.


title: HISTORY
content:
<i>pod2html</i> is an integral part of the Perl documentation toolchain, developed alongside Perl itself to facilitate the creation of web-based documentation from Pod (Plain Old Documentation) source files. Pod was introduced to provide a simple, consistent, and easy-to-use markup language for documenting Perl modules, scripts, and other components. <i>pod2html</i> has been maintained and updated as part of the core Perl distribution for many years, adapting to web standards and evolving to handle complex documentation requirements, making it a stable and widely used utility for publishing Perl documentation on the internet or for local access.


title: SYNOPSIS
content:
<b>pod2latex</b> [<i>OPTIONS</i>] [<i>file...</i>]<br><i>Reads from STDIN if no files are specified.</i>


title: PARAMETERS
content:
<b><b>--infile=<i>&lt;file&gt;</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an input POD file. This option can be used multiple times to process several input files concurrently.<br><br><b><b>--outfile=<i>&lt;file&gt;</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output LaTeX file. If not provided, the generated LaTeX content is printed to standard output (STDOUT).<br><br><b><b>--section=<i>&lt;level&gt;</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the LaTeX sectioning level for <b>=head1</b> POD sections. Common values include <i>chapter</i>, <i>section</i>, or <i>subsection</i>. The default is <i>chapter</i>.<br><br><b><b>--section-level=<i>&lt;N&gt;</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides a numerical LaTeX sectioning level for <b>=head1</b> (e.g., <i>-1</i> for \part, <i>0</i> for \chapter, <i>1</i> for \section). This option overrides <b>--section</b> if both are used.<br><br><b><b>--full</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ensures that a complete LaTeX document structure is generated, including a standard preamble and postamble. This is typically the default behavior.<br><br><b><b>--contents</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates a LaTeX table of contents for the document, usually placed at the beginning of the document.<br><br><b><b>--index</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates a LaTeX index for the document. Note that this feature requires the <i>makeidx</i> package and an additional compilation step with `makeindex` after `pdflatex`.<br><br><b><b>--latex-header=<i>&lt;text&gt;</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows adding custom lines directly into the LaTeX document's preamble, useful for including specific packages or commands.<br><br><b><b>--latex-footer=<i>&lt;text&gt;</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds custom lines directly before the <b>\end{document}</b> command in the generated LaTeX file.<br><br><b><b>--encoding=<i>&lt;encoding&gt;</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the character encoding of the input POD file, such as <i>UTF-8</i>. This ensures correct interpretation of special characters.<br><br><b><b>--podpath=<i>&lt;dir:dir...&gt;</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A colon-separated list of directories where <b>pod2latex</b> should search for POD files referenced by <b>L&lt;name&gt;</b> (internal links).<br><br><b><b>--podroot=<i>&lt;dir&gt;</i></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the base directory for constructing relative paths when looking up POD files specified by <b>--podpath</b>.<br><br><b><b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output, displaying additional processing information and status messages during conversion.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief usage message with available options and then exits.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the version information of <b>pod2latex</b> and then exits.<br><br>


title: DESCRIPTION
content:
The <b>pod2latex</b> command is a utility that transforms documentation written in Perl's Plain Old Documentation (POD) format into LaTeX, a high-quality typesetting system. POD is a simple markup language primarily used for documenting Perl modules, scripts, and their APIs. By converting POD to LaTeX, developers can generate professional-looking documentation suitable for printing, PDF generation, or integration into larger LaTeX projects. This conversion process intelligently handles various POD constructs, including text formatting (bold, italic), code blocks, nested lists, and internal/external links, translating them into appropriate LaTeX commands and environments. The output is a complete LaTeX document, typically including a standard preamble, ready to be processed by a LaTeX compiler like `pdflatex`.


title: CAVEATS
content:
While <b>pod2latex</b> strives to produce valid and well-formatted LaTeX, highly complex POD structures, or specific non-standard character usage might sometimes require manual adjustment of the generated <i>.tex</i> file. The resulting LaTeX document relies on standard LaTeX packages like <i>graphicx</i> (for image inclusion), <i>url</i> (for URL formatting), and <i>hyperref</i> (for clickable links and TOC), which must be present in your LaTeX distribution. Generating an index or cross-references often necessitates running the LaTeX compiler multiple times, potentially in conjunction with external tools like <i>makeindex</i>.


title: POST-CONVERSION WORKFLOW
content:
After generating the <i>.tex</i> file with <b>pod2latex</b>, it must be compiled into a viewable document (e.g., PDF) using a LaTeX engine. A typical workflow involves:<br><i>pod2latex mydocument.pod &gt; mydocument.tex</i><br><i>pdflatex mydocument.tex</i><br>For internal cross-references, tables of contents, or indexes to be correctly generated and updated, it is often necessary to run <i>pdflatex</i> two or three times. If an index is used (with <b>--index</b>), an additional step with `makeindex` between `pdflatex` runs is required: `pdflatex mydocument.tex`, `makeindex mydocument.idx`, `pdflatex mydocument.tex`.


title: ESSENTIAL LATEX PACKAGE DEPENDENCIES
content:
The LaTeX output from <b>pod2latex</b> typically requires several common LaTeX packages to be installed and available in your TeX distribution. These include: <i>graphicx</i> (for handling graphics and images, especially for code blocks rendered as images), <i>url</i> (for proper formatting of web addresses), and <i>hyperref</i> (crucial for creating clickable links within the PDF and for generating an interactive table of contents).


title: HISTORY
content:
<b>pod2latex</b> is an integral part of the Perl distribution's comprehensive suite of POD utilities. It was initially developed by Bradford Smith and has since been maintained and improved by the Perl community. Its evolution parallels that of the Perl language and its Plain Old Documentation (POD) standard, reflecting the ongoing need to seamlessly bridge simple text-based documentation with professional, high-quality typesetting systems like LaTeX for diverse publication needs.


title: SYNOPSIS
content:
<b>pod2latex.bundled</b> [<i>--full</i>] [<i>--sections=section_list</i>] [<i>--output=file</i>] [<i>podfile</i>]<br><b>pod2latex.bundled</b> [<i>options</i>] &lt; <i>input.pod</i> &gt; <i>output.tex</i>


title: PARAMETERS
content:
<b><i>podfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the Pod source file to be converted. If omitted, input is read from standard input.<br><br><b>--full</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generate a complete LaTeX document including standard preamble and document class. Without this, only a LaTeX fragment is produced.<br><br><b>--sections=<i>section_list</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a comma-separated list of section names to include in the output (e.g., `--sections="NAME,SYNOPSIS,DESCRIPTION"`).<br><br><b>--output=<i>file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Write the LaTeX output to the specified <i>file</i> instead of standard output.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a brief help message and exit.<br><br><b>-V, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the version information and exit.<br><br><b>--encoding=<i>encoding</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the input character encoding for the Pod source (e.g., `UTF-8`).<br><br><b>--preamble=<i>file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Insert the content of <i>file</i> directly into the LaTeX preamble (before `\begin{document}`).<br><br><b>--stylesheet=<i>file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use <i>file</i> as a custom LaTeX stylesheet. This file is included via `\input{<i>file</i>}`.<br><br><b>--nocode</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress the output of verbatim (code) paragraphs, which are normally rendered as `\begin{verbatim}` blocks.<br><br><b>--lax</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable more permissive parsing of the Pod input, for example, allowing `=head1` without a preceding blank line.<br><br><b>--skip</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ignore unknown Pod directives rather than issuing warnings or errors.<br><br><b>--doctype=<i>type</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the LaTeX document class for `--full` output (e.g., `article`, `report`, `book`). Defaults to `article`.<br><br><b>--magnification=<i>factor</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scale the document by the given factor (e.g., `1.2` for 120% size). Affects the `\documentclass` option.<br><br><b>--release=<i>version</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the version string (e.g., `\release{<i>version</i>}`) in the LaTeX output.<br><br><b>--date=<i>date</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the date string (e.g., `\date{<i>date</i>}`) in the LaTeX output.<br><br><b>--quotes=<i>type</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Control how quotes are rendered: `none` (no special rendering), `latex` (using LaTeX specific commands like `\textquotedblleft`), or `quotes` (using standard ' and " characters).<br><br><b>--backticks</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Render `C<...>` formatting codes as monospace (`\texttt{...}`) rather than italics (`\textit{...}`).<br><br><b>--footnote-macros</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use LaTeX `\footnote` macros for `F<...>` formatting codes instead of simple superscripts.<br><br><b>--verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print status and debugging messages to standard error during conversion.<br><br>


title: DESCRIPTION
content:
<b>pod2latex.bundled</b> is a utility designed to convert documentation written in Pod (Plain Old Documentation) format into LaTeX. Pod is a simple markup language used primarily for documenting Perl modules and scripts. This command takes Pod input, either from standard input or a specified file, and transforms it into LaTeX source code, which can then be compiled into a PDF or other formats using a LaTeX compiler like <b>pdflatex</b>.<br><br>It handles various Pod constructs such as paragraphs, verbatim blocks, headings, lists, bold/italic/code text, and cross-references, mapping them to appropriate LaTeX commands. This allows developers to maintain their documentation in a single, easy-to-read Pod format and then generate high-quality typeset output suitable for printing or distribution. The `.bundled` suffix often indicates it's part of a larger Perl distribution or a specific software package, ensuring its availability and functionality within that ecosystem.


title: CAVEATS
content:
<b>pod2latex.bundled</b> relies on a LaTeX distribution being installed on your system to compile the generated `.tex` files into presentable documents (e.g., PDF). It may not support all advanced LaTeX features or highly complex Pod constructs perfectly, and some manual tweaking of the generated `.tex` file might be necessary for very specific formatting requirements. The `.bundled` suffix typically indicates it's part of a specific Perl installation or a larger software package, meaning its availability and exact version might depend on your system's Perl environment.


title: COMPILING LATEX OUTPUT
content:
To obtain a PDF document from the `.tex` file generated by <b>pod2latex.bundled</b>, you typically run a LaTeX compiler like <b>pdflatex</b>. For example:<br>`<b>pod2latex.bundled</b> <i>yourfile.pod</i> > <i>yourfile.tex</i>`<br>`<b>pdflatex</b> <i>yourfile.tex</i>`<br>This process might need to be run multiple times (e.g., `<b>pdflatex</b> <i>yourfile.tex</i>` twice or thrice) to resolve internal references such as a table of contents, citations, or cross-references, ensuring all elements are correctly placed and numbered.


title: HISTORY
content:
The <b>pod2latex</b> utility is a long-standing component of the core Perl distribution's Pod utilities, developed and maintained over many years alongside Perl itself. It serves a crucial role in enabling Perl developers to document their code in a standard, easily parsable format (Pod) and then generate professional-looking documentation in various output formats, including typeset LaTeX. Its development has focused on robustness in parsing diverse Pod inputs and providing configurable options for LaTeX output to suit different documentation needs. The `.bundled` suffix often indicates a specific version or wrapper included within a larger software package, ensuring compatibility and functionality within that ecosystem.


title: SYNOPSIS
content:
<b>pod2man</b> [<i>options</i>] <i>inputfile</i> [<i>outputfile</i>]<br><b>pod2man</b> [<i>options</i>] < <i>inputfile</i> > <i>outputfile</i>


title: PARAMETERS
content:
<b><b>--section</b>=<i>name</i> | <b>-s</b> <i>name</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the manual section. Default is 3.<br><br><b><b>--release</b>=<i>version</i> | <b>-r</b> <i>version</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the release value. Default is the Perl version.<br><br><b><b>--center</b>=<i>text</i> | <b>-c</b> <i>text</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the centered header. Default is "Perl Programmers Reference Guide".<br><br><b><b>--date</b>=<i>string</i> | <b>-d</b> <i>string</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the date. Default is the current date.<br><br><b><b>--fullpath</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use full path for the name, e.g., <i>Foo::Bar(3)</i>.<br><br><b><b>--name</b>=<i>name</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the name. Default is derived from <i>inputfile</i>.<br><br><b><b>--noperl</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Don't add Perl-specific sections (e.g., SEE ALSO perl(1)).<br><br><b><b>--nocenter</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Don't include a centered header.<br><br><b><b>--nourl</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Don't add a URL to the SEE ALSO section for <i>L<></i> codes.<br><br><b><b>--laxbreak</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Don't break paragraphs for <i>L<></i> codes.<br><br><b><b>--htmlroot</b>=<i>url</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the base URL for <i>L<></i> codes to HTML.<br><br><b><b>--podpath</b>=<i>dir1:dir2:...</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Search path for <i>L<...></i> references.<br><br><b><b>--quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Don't display warnings.<br><br><b><b>--errors</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display errors in the output.<br><br><b><b>--utf8</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Encode output as UTF-8.<br><br><b><b>--encoding</b>=<i>encoding</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify input encoding.<br><br><b><b>--permute</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Change position of NAME section.<br><br><b><b>--stderr</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Send errors to <i>stderr</i>.<br><br><b><b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display verbose messages.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display version information.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display usage message.<br><br>


title: DESCRIPTION
content:
<i>pod2man</i> is a Perl utility that translates documentation written in the Perl POD (Plain Old Documentation) format into the <i>roff</i> input format used by the <b>man</b> program. POD is a simple markup language commonly used for documenting Perl modules and scripts.<br><br><i>pod2man</i> allows developers to easily create standard UNIX manual pages from their POD-formatted documentation, making it accessible via the <b>man</b> command. It handles various aspects of man page formatting, including sections, bolding, italics, and cross-references. It's typically invoked during the installation of Perl modules to generate man pages for scripts and library functions, ensuring that documentation is readily available in a standardized format.


title: CAVEATS
content:
<ul><li>Requires a Perl interpreter to run.</li><li>Output is in <i>roff</i> format, which needs to be processed by tools like <b>man</b> or <b>groff</b> for display.</li><li>Relies on correct POD syntax in the input file; malformed POD may lead to unexpected output or errors.</li><li>Default header/footer values (section, release, center, date) might not be suitable for all projects and often need to be overridden with explicit options.</li></ul>


title: INPUT/OUTPUT
content:
<i>pod2man</i> reads POD from <i>inputfile</i> (or standard input if no file is specified) and writes the formatted man page to <i>outputfile</i> (or standard output if no output file is specified).


title: PURPOSE IN PERL ECOSYSTEM
content:
It is commonly used during the installation of Perl modules (e.g., via <i>ExtUtils::MakeMaker</i> or <i>Module::Build</i>) to automatically generate and install man pages alongside the module files, ensuring that documentation is consistently available through the system's manual page viewer.


title: HISTORY
content:
<i>pod2man</i> is an integral part of the Perl distribution, developed as part of the effort to provide consistent and easily maintainable documentation for Perl itself, its modules, and scripts. It has been part of the standard Perl toolkit for many years, evolving with the language to support various POD features and output formatting requirements. Its existence facilitates the widespread use of POD as a primary documentation format within the Perl ecosystem, making it a cornerstone for creating standardized manual pages for Perl-based software.


title: PARAMETERS
content:
<b><b>-c</b>, <b>--code</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Formats <code>C&lt;&gt;</code> sequences (inline code examples) using a fixed-width style, making them visually distinct like code snippets.<br><br><b><b>-i</b> <i>columns</i>, <b>--indent</b>=<i>columns</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Indents the main body text of the document by the specified number of <i>columns</i> spaces from the left margin, improving readability.<br><br><b><b>-l</b>, <b>--loose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a blank line before and after each heading (e.g., <code>=head1</code>, <code>=head2</code>), making the document appear less dense and improving visual separation between sections.<br><br><b><b>-s</b>, <b>--sentence</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces <b>pod2text</b> to treat each paragraph block as a single sentence. This can influence how inline formatting codes, particularly <code>B&lt;&gt;</code> (bold), are rendered, often ensuring proper capitalization where appropriate.<br><br><b><b>-u</b>, <b>--utf8</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ensures that the output text is encoded in UTF-8. This is crucial for correctly displaying international characters and symbols present in the POD documentation.<br><br><b><b>-w</b> <i>columns</i>, <b>--width</b>=<i>columns</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum output width for the text, in <i>columns</i>. Lines exceeding this width will be wrapped to the next line. This is highly useful for controlling layout and fitting output to specific terminal sizes.<br><br><b><b>--errors</b>=<i>style</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Determines how <b>pod2text</b> handles POD parsing errors. <i>style</i> can be <code>die</code> (exit immediately upon error), <code>warn</code> (print a warning and continue), or <code>ignore</code> (silently ignore errors).<br><br><b><b>--encoding</b>=<i>encoding</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the character <i>encoding</i> of the input POD file. This helps <b>pod2text</b> correctly interpret non-ASCII or multi-byte characters within the document.<br><br><b><b>--nourl</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables the underlining or highlighting of URLs in the output. This can be useful if your terminal does not support or renders underlining poorly, or if you prefer plain text output for URLs.<br><br><b><i>file</i>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more POD files to be converted. If no <i>file</i> arguments are specified, <b>pod2text</b> reads its input from standard input (stdin).<br><br>


title: DESCRIPTION
content:
The <b>pod2text</b> command is a utility included with Perl that converts documentation written in Perl's Plain Old Documentation (POD) format into a readable plain text. POD is a simple, lightweight markup language primarily used for documenting Perl modules, scripts, and other components directly within the source code. <b>pod2text</b> is essential for viewing this documentation on the command line, especially when <b>perldoc</b> might not be fully configured or when you need to pipe the output to other text processing tools. It intelligently handles various POD formatting codes like bold (<code>B&lt;&gt;</code>), italic (<code>I&lt;&gt;</code>), code (<code>C&lt;&gt;</code>), and links (<code>L&lt;&gt;</code>), rendering them into appropriate plain text representations, often using capitalization, indentation, or underlining to signify the original formatting.


title: CAVEATS
content:
While <b>pod2text</b> is effective for basic text conversion, it is primarily designed for simple rendering. It may not perfectly reproduce complex formatting, elaborate tables, or highly structured layouts found in more advanced markup languages. The final output quality also depends on the capabilities of the displaying terminal and the inherent structure of the POD file. For interactive viewing of Perl documentation, <b>perldoc</b> is often preferred as it integrates a pager and handles module lookup.


title: USAGE WITH STANDARD INPUT
content:
If no <i>file</i> arguments are provided on the command line, <b>pod2text</b> will automatically read its input from standard input (stdin). This allows for flexible use cases, such as piping the output of other commands (e.g., <code>cat my_script.pl | pod2text</code>) or processing dynamically generated POD content.


title: TYPICAL OUTPUT CHARACTERISTICS
content:
The output of <b>pod2text</b> is typically clean ASCII or UTF-8 plain text. Headings are often capitalized or underlined to stand out, lists are properly indented, and code examples maintain their preformatted structure. This plain text output is highly versatile, suitable for display in any terminal, saving to a text file, or further processing by other command-line utilities like <b>grep</b> or <b>less</b>.


title: HISTORY
content:
<b>pod2text</b> is an integral utility within the Perl programming language distribution, designed to make Perl's native Plain Old Documentation (POD) format widely accessible. The POD format itself was introduced in the early 1990s as a straightforward way to embed documentation directly within Perl source code. <b>pod2text</b>, alongside other <code>pod2*</code> utilities like <b>pod2man</b> (for manual pages) and <b>pod2html</b> (for HTML output), has continuously evolved as part of the Perl core, ensuring robust and consistent conversion capabilities for Perl documentation across various environments and output formats.


title: SYNOPSIS
content:
<b>pod2usage</b> [<I>options</I>] [<I>pod_file</I> | <I>module_name</I>]<br><br>Common invocations:<br><I><b>pod2usage</b></I> <I>--help</I><br><I><b>pod2usage</b></I> <I>--man</I><br><I><b>pod2usage</b></I> <I>--verbose</I> <I>1</I> <I>My::Perl::Module</I>


title: PARAMETERS
content:
<b>--help, -h</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a concise usage message and exits.<br><br><b>--man</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the full manual page for the specified POD documentation.<br><br><b>--verbose <I>level</I>, -v <I>level</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls the verbosity of the output. <I>0</I> shows only the usage message, <I>1</I> shows the usage message and description, <I>2</I> shows the full POD documentation.<br><br><b>--sections <I>section,...</I>, -s <I>section,...</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a comma-separated list of POD sections (e.g., NAME, SYNOPSIS, DESCRIPTION) to display.<br><br><b>--message <I>string</I>, -m <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the specified <I>string</I> before the usage message. Useful for adding custom error or informational messages.<br><br><b>--exitval <I>exit_code</I>, -e <I>exit_code</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the exit status code for <b>pod2usage</b> upon successful completion. Defaults to <I>0</I>.<br><br><b>--output <I>file</I>, -o <I>file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Redirects the formatted output to the specified <I>file</I> instead of standard output.<br><br><b>--format <I>format_name</I>, -f <I>format_name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output format, such as <I>text</I> (default for terminal), <I>man</I>, or <I>html</I>.<br><br><b>--input <I>file</I>, -i <I>file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the input file to parse. If not provided, it defaults to <I>STDIN</I> or the module specified.<br><br>


title: DESCRIPTION
content:
<b>pod2usage</b> is a Perl utility designed to extract and format documentation embedded within Perl scripts and modules. This documentation is written in POD (Plain Old Documentation) format, a simple markup language used by Perl developers. The primary purpose of <b>pod2usage</b> is to quickly display usage messages, help information, or even full manual pages directly from the source code.<br><br>When invoked, <b>pod2usage</b> parses the specified Perl file or module, locates its POD sections, and renders them into a user-friendly format, typically plain text suitable for terminal output. It is commonly used by Perl scripts themselves to provide their own <I>--help</I> or <I>--man</I> options, offering a consistent way for users to access documentation without needing external man pages or separate documentation files.<br><br>It's an invaluable tool for Perl programmers and users alike, enabling easy access to API documentation and command-line tool usage instructions directly from the software's source.


title: CAVEATS
content:
<b>pod2usage</b> requires a Perl installation and is primarily designed for parsing Perl's POD (Plain Old Documentation) format. It may not be available on systems without Perl or without the <I>Pod::Usage</I> module installed. The quality of the output depends on the clarity and correctness of the embedded POD documentation. While it can output to various formats, its primary strength is generating plain text or <I>man</I> page formats for terminal display.


title: EXIT STATUS
content:
<b>pod2usage</b> provides specific exit codes to indicate the outcome of its execution:<br><I><b>0</b></I>: Successful completion.<br><I><b>1</b></I>: Bad command line arguments provided.<br><I><b>2</b></I>: Errors encountered during the parsing or processing of the POD documentation.<br><I><b>255</b></I>: An invalid value was specified for the <I>--exitval-bad-params</I> option.


title: HISTORY
content:
<b>pod2usage</b> is an integral part of the standard Perl distribution, originating from the <I>Pod::Usage</I> Perl module. Its development has closely tracked the evolution of Perl and its Plain Old Documentation (POD) specification. Initially designed to provide simple usage messages from Perl scripts, it has grown in functionality to support displaying more comprehensive documentation sections and various output formats, becoming a fundamental tool for accessing Perl module documentation directly from the source code. Its inclusion in core Perl distributions ensures widespread availability and consistent documentation access within the Perl ecosystem.


title: PARAMETERS
content:
<b><b>-help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief help message and exits.<br><br><b><b>-man</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the full man page for <i>podchecker</i> and exits.<br><br><b><b>-warnings</b> / <b>-w</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables the display of warnings in addition to fatal errors. This is the default behavior.<br><br><b><b>-nowarnings</b> / <b>-W</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables all warning messages, reporting only fatal errors.<br><br><b><b>-warnings=</b><i>category</i><b>,...</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables specific categories of warnings. Common categories include 'all', 'none', 'badflag', 'badindent', 'badseq', 'verbatim', 'pod', 'perl', 'syntax'.<br><br><b><b>-errlvl=</b><i>level</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the minimum error level that will cause <i>podchecker</i> to exit with a non-zero status. Valid levels are 0 (no errors), 1 (warnings), 2 (errors), 3 (fatal errors). Default is 2.<br><br><b><b>-html</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates an HTML report of errors and warnings instead of plain text output. This report can be displayed in a web browser.<br><br><b><b>-quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses all output unless errors or warnings are found. If no problems are detected, it prints nothing.<br><br>


title: DESCRIPTION
content:
<i>podchecker</i> is a utility designed to validate the syntax of Perl's Plain Old Documentation (POD) format. It parses POD content, whether from standalone files or embedded within Perl scripts and modules, and reports any deviations from the official POD specification. <br><br>The tool identifies common errors such as malformed POD directives (e.g., <code>=head1</code> with incorrect arguments), unclosed formatting codes (e.g., <code>B<text</code> without <code>></code>), incorrect heading levels, and other structural issues. By catching these problems early, <i>podchecker</i> ensures that documentation can be correctly processed and rendered by tools like <i>perldoc</i>, <i>pod2man</i>, or <i>pod2html</i>. It's an essential tool for Perl developers maintaining high-quality documentation for their code.<br><br>By default, it prints error messages to standard error. It can also produce an HTML error report or exit with a specific status based on the severity of issues found.


title: CAVEATS
content:
<i>podchecker</i> primarily focuses on the *syntax* of POD. It may not catch all logical or semantic errors, such as documentation that is syntactically correct but factually incorrect or misleading. Its output can be verbose, especially without the <b>-quiet</b> option, and parsing its plain-text output for automation might require careful regular expression matching.


title: EXIT STATUS
content:
<i>podchecker</i> exits with 0 if no problems are found, 1 if warnings are found (unless <b>-errlvl</b> is set higher than 1), 2 if errors are found, or 3 if fatal errors are found. The exact non-zero exit status can be configured via the <b>-errlvl</b> option, allowing for custom automation logic based on error severity.


title: BUGS
content:
Despite its utility, <i>podchecker</i> may not catch every conceivable syntax or semantic problem due to the flexible nature of POD. Some complex or ambiguous POD constructs might be misinterpreted or pass unnoticed. Users are encouraged to report any encountered issues to the Perl bug tracking system to contribute to its ongoing improvement.


title: HISTORY
content:
Plain Old Documentation (POD) was introduced as part of Perl 5.0 (released in 1994) to provide a simple, ubiquitous, and easily parsable format for embedding documentation directly within Perl source code. <i>podchecker</i>, as a component of the standard Perl distribution, has evolved alongside the POD specification, ensuring compliance with new features and refinements. Its development is deeply intertwined with the broader Perl documentation ecosystem, aiming to maintain a consistent and reliable documentation standard for the Perl community.


title: SYNOPSIS
content:
<code>podman [<i>options</i>] [<i>command</i>]</code><br><code>podman [<i>options</i>] <i>command</i> [<i>command options</i>] [<i>arguments</i>...]</code>


title: PARAMETERS
content:
<b><b>--help</b>, <b>-h</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show help for a command or subcommand.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the version number.<br><br><b><b>--log-level</b>=<i>level</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the logging level (e.g., debug, info, warn, error).<br><br><b><b>--root</b>=<i>path</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to the container storage root directory.<br><br><b><b>--runroot</b>=<i>path</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to the container storage run root directory.<br><br><b><b>--storage-driver</b>=<i>driver</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Storage driver to use (e.g., overlay, vfs).<br><br><b><b>--storage-opt</b>=<i>option</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Storage driver options.<br><br><b><b>--remote</b>, <b>-r</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connect to a remote Podman service. (Default: <i>false</i>)<br><br><b><b>--url</b>=<i>URL</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;URL to access the Podman service (e.g., <i>ssh://user@host/run/podman/podman.sock</i>).<br><br><b><b>--connection</b>=<i>name</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Name of the connection to use from <i>containers.conf</i>.<br><br><b><b>--identity</b>=<i>path</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to an SSH identity file for remote connections.<br><br><b><b>--username</b>=<i>name</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Username for SSH connection to the remote host.<br><br><b><b>--tls-verify</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Require TLS verification for remote API connections.<br><br>


title: DESCRIPTION
content:
<i>Podman</i> is an open-source, daemonless container engine for developing, managing, and running OCI (Open Container Initiative) containers and pods on a Linux system. It offers a command-line interface highly compatible with the <i>Docker CLI</i>, making it a popular choice for users transitioning from Docker. <br><br>Unlike Docker, <i>Podman</i> does not require a persistent background daemon, improving security and simplifying its architecture. It excels in enabling <b>rootless containers</b>, allowing users to run containers without requiring root privileges, thus enhancing system security by isolating container processes from the host's root user. <br><br><i>Podman</i> manages the entire container lifecycle, from image pull and creation to execution and removal. It integrates seamlessly with other container tools like <i>Buildah</i> for building container images and <i>Skopeo</i> for inspecting and transferring container images. It supports both standalone containers and <b>pods</b>, which are groups of containers that share resources like network and storage, similar to Kubernetes pods. This makes <i>Podman</i> a versatile tool for both development and production environments, including those that may later deploy to Kubernetes.


title: CAVEATS
content:
While <i>Podman</i> offers significant advantages, especially with <b>rootless containers</b>, it does come with certain considerations:<br><b>Daemonless Architecture</b>: The absence of a central daemon means <i>Podman</i> processes are typically user-specific and transient. This differs from Docker's persistent daemon, potentially affecting long-running services unless managed via <i>systemd</i>.<br><b>Rootless Limitations</b>: Running containers as a non-root user may introduce limitations, such as inability to bind to privileged ports (below 1024) without additional capabilities, or complexities with certain advanced networking setups.<br><b>Resource Management</b>: On systems using <i>cgroups v1</i>, user-defined resource limits for rootless containers can be less straightforward than for rootful containers. <i>cgroups v2</i> generally offers better support for rootless resource management.<br><b>Direct Container Access</b>: Unlike Docker, there's no single 'daemon socket' to connect to for all container operations; each user session manages its own containers. Remote access is facilitated via the <i>Podman API</i> service.


title: ROOTLESS CONTAINERS
content:
<i>Podman's</i> key feature is its support for <b>rootless containers</b>. This allows unprivileged users to create, run, and manage containers without requiring elevated privileges on the host system. This significantly enhances security by preventing container escape exploits from gaining root access to the host. It utilizes user namespaces to achieve this isolation.


title: OCI COMPLIANCE
content:
<i>Podman</i> strictly adheres to the <i>Open Container Initiative (OCI)</i> specifications for container images and runtimes. This ensures interoperability with other OCI-compliant tools and runtimes, meaning images built with <i>Buildah</i> or <i>Docker</i> can be run by <i>Podman</i>, and vice-versa. This open standard approach promotes flexibility and avoids vendor lock-in.


title: PODS FOR MULTI-CONTAINER WORKLOADS
content:
Beyond single containers, <i>Podman</i> supports the concept of <b>pods</b>, which are groups of one or more containers that share resources like network namespaces, IPC, and storage volumes. This is a crucial feature for deploying multi-container applications that are often orchestrated by platforms like <i>Kubernetes</i>. <i>Podman</i> can even generate Kubernetes YAML files from existing pods.


title: INTEGRATION WITH SYSTEMD
content:
<i>Podman</i> can generate <i>systemd</i> unit files for containers and pods, allowing them to be managed as services by the host's <i>systemd</i> init system. This provides robust lifecycle management, automatic restarts, and integration with standard Linux monitoring tools, making <i>Podman</i> suitable for deploying long-running production workloads.


title: SUBCOMMANDS AND OPTIONS
content:
The <i>podman</i> command operates via numerous subcommands (e.g., <i>podman run</i>, <i>podman build</i>, <i>podman images</i>). Each subcommand has its own set of specific options, which can be viewed by running <i>podman &lt;subcommand&gt; --help</i>. The <i>parameters</i> section above focuses on global options applicable to the <i>podman</i> command itself.


title: HISTORY
content:
<i>Podman</i> originated at <i>Red Hat</i> as a modern, daemonless alternative to traditional container engines like <i>Docker</i>. It was initially developed as part of the <i>libpod</i> project, aiming to provide a compatible command-line interface while adhering strictly to <i>OCI (Open Container Initiative)</i> standards for container images and runtimes. <br><br>Its development focused heavily on security and ease of integration with standard Linux tools. The emphasis on <b>rootless containers</b> allowed non-privileged users to manage containers, significantly reducing potential attack surfaces. Over time, it gained widespread adoption, especially in enterprise Linux distributions and environments prioritizing security and system integrity. Its ability to generate <i>systemd</i> units for containers further solidified its position as a robust tool for production deployments.


title: SEE ALSO
content:
buildah(1), skopeo(1), podman-systemd(1), containers-registries.conf(5), containers-storage.conf(5), containers-mounts.conf(5), docker(1)


title: PARAMETERS
content:
<b>-t, --tag <i>name:tag</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assigns a name and optional tag to the built image. Can be specified multiple times.<br><br><b>-f, --file <i>path/to/Dockerfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to the <i>Dockerfile</i> (or <i>Containerfile</i>) to use instead of the default.<br><br><b>--build-arg <i>name=value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets build-time variables, accessible within the <i>Dockerfile</i> using <i>ARG</i> instructions.<br><br><b>--no-cache</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents the build process from using cached layers. All layers will be rebuilt.<br><br><b>--pull</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Always attempt to pull a newer version of the base image if it exists in the registry.<br><br><b>--platform <i>os/arch[/variant]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the target platform for the built image (e.g., <i>linux/arm64</i>).<br><br><b>--target <i>stage-name</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Builds up to the specified stage in a multi-stage <i>Dockerfile</i>.<br><br><b>-v, --volume <i>src:dest[:options]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Mounts a volume into the container during the build process, useful for injecting dependencies.<br><br><b>--output <i>path</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes the image to a tar archive at the specified path instead of storing it in local storage.<br><br><b>--squash</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Squashes the new layers into a single new layer. This creates a smaller image but loses layer history.<br><br><b>--secret <i>id=mysecret,src=/path/to/secret</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Mounts a secret file into the build container, making it available for use during the build.<br><br><b>--ssh <i>default|<id></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows accessing SSH agent sockets or SSH keys during the build process, similar to <i>BuildKit</i>.<br><br><b>--label <i>key=value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds metadata labels to the built image. Can be specified multiple times.<br><br><b>--network <i>mode</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the network mode for the build containers (e.g., <i>host</i>, <i>none</i>, <i>bridge</i>).<br><br>


title: DESCRIPTION
content:
<br>The <b>podman-build</b> command is used to construct OCI (Open Container Initiative) compatible container images from a build context. This context, typically a directory containing a <i>Dockerfile</i> (or <i>Containerfile</i>), is processed by Podman to execute the instructions defined in the build file. It supports multi-stage builds, caching of build layers, and various build-time configurations, enabling users to create optimized and reproducible images. <b>podman-build</b> is a core component of the Podman ecosystem, offering a robust and daemonless alternative to Docker's image building capabilities, emphasizing security and flexibility. It processes build arguments, pulls base images, executes commands, and layers file system changes to produce the final image.


title: CAVEATS
content:
<br>While highly compatible with <i>Dockerfiles</i>, some advanced <i>BuildKit</i> features might behave differently or be unsupported in older Podman versions. Building in rootless mode might have implications for resource access and network configurations compared to rootful builds. The build context is crucial; ensure all necessary files are included and unnecessary ones are excluded via a <i>.dockerignore</i> or <i>.containerignore</i> file to optimize performance and security.


title: CONTAINERFILE VS DOCKERFILE
content:
Podman natively recognizes both <i>Dockerfile</i> and <i>Containerfile</i> as build instruction files. The latter is a Podman-specific convention emphasizing its independence from Docker.


title: BUILD CONTEXT
content:
The build context is the set of files at the specified <i>PATH</i> or <i>URL</i> that are available to the build process. Only files and directories within this context can be referenced by instructions like <i>COPY</i> or <i>ADD</i> in the <i>Dockerfile</i>. It's recommended to use a <i>.dockerignore</i> or <i>.containerignore</i> file to exclude unnecessary files from the context, which can significantly speed up builds and reduce image size.


title: HISTORY
content:
<br><b>podman-build</b> emerged as a key command within the Podman project, initiated by Red Hat, as a daemonless alternative to Docker. Its development has focused on providing a secure, flexible, and OCI-compliant way to build container images without requiring a persistent background daemon. This approach enhances system security and integration with traditional Linux tools. Over time, it has gained extensive compatibility with <i>Dockerfile</i> syntax and adopted features similar to Docker's <i>BuildKit</i>, while maintaining its distinct architecture.


title: PARAMETERS
content:
<b><b>up</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Builds, (re)creates, starts, and attaches to containers for a service.<br><br><b><b>down</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stops and removes containers, networks, volumes, and images created by <b>up</b>.<br><br><b><b>build</b> [<i>SERVICE...</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Builds or rebuilds services.<br><br><b><b>start</b> [<i>SERVICE...</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts existing containers for a service.<br><br><b><b>stop</b> [<i>SERVICE...</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stops running containers without removing them.<br><br><b><b>ps</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists containers for a service.<br><br><b><b>logs</b> [<i>SERVICE...</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Fetches and displays logs from containers.<br><br><b><b>exec</b> [<i>SERVICE</i>] [<i>COMMAND</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes a one-off command in a running container.<br><br><b><b>-f</b>, <b>--file</b> <i>FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify an alternate compose file.<br><br><b><b>-p</b>, <b>--project-name</b> <i>NAME</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify an alternate project name (defaults to directory name).<br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show <i>podman-compose</i> version information and exit.<br><br><b><b>--podman-path</b> <i>PATH</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the path to the <i>podman</i> executable.<br><br><b><b>--compatibility</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable compatibility mode for some Docker Compose features (e.g., <i>tmpfs</i> volumes).<br><br>


title: DESCRIPTION
content:
<i>podman-compose</i> is a Python script that provides a familiar <b>Docker Compose</b>-like experience for managing multi-container applications using <b>Podman</b>.<br><br>Its primary purpose is to allow users to leverage existing or create new <i>docker-compose.yml</i> (or <i>compose.yaml</i>) files to define and run services with Podman, a daemonless container engine. This tool helps bridge the gap for users transitioning from Docker to Podman, enabling them to reuse their compose configurations without significant modifications.<br><br>It interprets the YAML configuration, translating it into a series of <b>Podman</b> commands to build images, create containers, set up networks, and manage volumes, orchestrating the entire application stack. While it aims for high compatibility with Docker Compose, it's important to note that it is a community-driven project and may not support every advanced or niche feature found in Docker Compose. It serves as an invaluable utility for developing and deploying complex applications in a Podman environment, offering a streamlined workflow for defining and managing interconnected services.


title: CAVEATS
content:
<i>podman-compose</i> is a community-developed project and not officially part of the <b>Podman</b> ecosystem. While it strives for compatibility with <b>Docker Compose</b> files, 100% feature parity is not guaranteed. Some advanced or newer features, particularly those related to networking specifics or complex volume configurations, might behave differently or not be fully supported. Users should test their <b>Docker Compose</b> files thoroughly when migrating to <b>Podman</b> via <i>podman-compose</i>.


title: COMPOSE FILE COMPATIBILITY
content:
<i>podman-compose</i> directly uses standard <i>docker-compose.yml</i> or <i>compose.yaml</i> files. This means that if you have a project defined with <b>Docker Compose</b>, you can often run it with <i>podman-compose</i> with minimal or no changes, facilitating easy migration between container runtimes.


title: INSTALLATION
content:
<i>podman-compose</i> is typically installed via <b>Python's pip</b> package manager, often as <i>pip install podman-compose</i>. It requires a working <b>Podman</b> installation on the system. As it is a Python script, it does not embed <b>Podman</b> functionality but rather calls the <b>Podman</b> command-line interface internally.


title: HISTORY
content:
The genesis of <i>podman-compose</i> lies in the increasing adoption of <b>Podman</b> as an alternative to <b>Docker</b>, especially in environments favoring daemonless container management. Users with existing <b>Docker Compose</b> workflows needed a seamless transition path. As <b>Podman</b> itself does not include an integrated compose tool, the community stepped in to fill this void. Developed as a Python script, <i>podman-compose</i> began as an independent project, evolving to translate <b>Compose</b> file directives into equivalent <b>Podman</b> commands. Its development closely tracks updates in both the <b>Podman</b> and <b>Docker Compose</b> projects, aiming to maintain relevance and functionality amidst evolving container technologies.


title: SYNOPSIS
content:
podman image <I>subcommand</I> [options] [arguments]<br><br>Common <I>subcommands</I> for <b>podman image</b> include:<br><b>build</b>: Build an image using a Containerfile or Dockerfile.<br><b>exists</b>: Check if an image exists.<br><b>history</b>: Display the history of an image.<br><b>import</b>: Import a tarball to create a filesystem image.<br><b>inspect</b>: Display detailed information on one or more images.<br><b>load</b>: Load an image from a tar archive or STDIN.<br><b>ls</b> (or <b>images</b>): List images.<br><b>prune</b>: Remove unused images.<br><b>pull</b>: Pull an image from a registry.<br><b>push</b>: Push an image to a registry.<br><b>rm</b> (or <b>rmi</b>): Remove one or more images.<br><b>save</b>: Save an image to a tar archive.<br><b>sign</b>: Sign an image.<br><b>untag</b>: Remove a tag from an image.


title: PARAMETERS
content:
<b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display help for the <b>podman image</b> command and its subcommands.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the Podman version information.<br><br>


title: DESCRIPTION
content:
The <b>podman-image</b> command is a crucial subcommand within the Podman container management system. It provides a comprehensive set of tools for interacting with and managing container images. Unlike traditional daemon-based container engines, Podman operates in a daemonless fashion, and <b>podman-image</b> facilitates operations such as pulling images from registries, pushing images to registries, building images from Dockerfiles or Containerfiles, listing existing images, and removing images. It serves as the central interface for all image-related workflows, enabling users to prepare, distribute, and clean up the building blocks for their containers. It supports OCI (Open Container Initiative) image formats and works seamlessly with various container registries like Docker Hub, Quay.io, and custom registries.


title: CAVEATS
content:
<b>podman-image</b> operates within the Podman ecosystem, which is designed to be daemonless and rootless-friendly. This means that image operations typically run directly as the invoking user, without requiring a background service like Docker's daemon. Consequently, images managed by one user are generally not visible or accessible by another user unless explicitly configured (e.g., through shared storage or system-wide registries). While <b>podman-image</b> provides similar functionality to <b>docker image</b>, there might be subtle differences in behavior or specific options due to Podman's OCI compliance and daemonless architecture.


title: IMAGE MANAGEMENT PHILOSOPHY
content:
<b>podman-image</b> embodies Podman's philosophy of daemonless, OCI-compliant container management. Each subcommand under <b>podman image</b> is typically implemented as a separate binary or module within the Podman codebase, which contributes to its robust and modular design. This allows for clearer separation of concerns and can make debugging or auditing specific image operations more straightforward.


title: COMMON IMAGE WORKFLOWS
content:
Typical workflows involving <b>podman-image</b> include:<br>1.  <b>Development</b>: Using <b>podman image build</b> to create application images from source code and Dockerfiles/Containerfiles.<br>2.  <b>Deployment</b>: Utilizing <b>podman image pull</b> to retrieve necessary base images or application images from registries for local use or deployment.<br>3.  <b>Distribution</b>: Employing <b>podman image push</b> to upload custom-built images to private or public registries for sharing.<br>4.  <b>Maintenance</b>: Using <b>podman image ls</b> to monitor image disk usage and <b>podman image rm</b> or <b>podman image prune</b> to free up space by removing old or unused images.


title: HISTORY
content:
The <b>podman-image</b> subcommand evolved as part of the broader Podman project, which was initiated by Red Hat engineers around 2017. Its primary goal was to provide an OCI-compliant container engine that offered an alternative to Docker, particularly focusing on daemonless operation and better integration with systemd and traditional Linux tools. <b>podman-image</b> inherited the functionality of Docker's <b>docker image</b> command but was built from the ground up to support Podman's unique architecture. Its development has continuously focused on performance, security (especially rootless capabilities), and compatibility with existing container image standards and registries.


title: SEE ALSO
content:
podman(1), podman-build(1), podman-pull(1), podman-push(1), podman-rmi(1), podman-images(1), containers-storage(5), container-registries.conf(5)


title: PARAMETERS
content:
<b><b>-a</b>, <b>--all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show all images, including intermediate images created during multi-stage builds or as parent layers. By default, only top-level images are shown.<br><br><b><b>--digests</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show image digests (e.g., <i>sha256:</i>...). This provides a unique identifier for the image content.<br><br><b><b>-f</b>, <b>--filter</b> <i>filter</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filter output based on conditions. Common filters include <i>dangling=true/false</i>, <i>label=&lt;key&gt;[=&lt;value&gt;]</i>, <i>before=&lt;image&gt;</i>, <i>since=&lt;image&gt;</i>, <i>reference=&lt;pattern&gt;</i>, <i>size=&lt;bytes&gt;</i>.<br><br><b><b>--format</b> <i>format</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pretty-print images using a Go template. Available placeholders include <i>.ID</i>, <i>.Repository</i>, <i>.Tag</i>, <i>.Digest</i>, <i>.Created</i>, <i>.CreatedAt</i>, <i>.Size</i>, <i>.Containers</i>, <i>.VirtualSize</i>, <i>.Labels</i>.<br><br><b><b>--json</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output all image information in JSON format, useful for programmatic parsing.<br><br><b><b>--no-trunc</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not truncate output. By default, long image IDs and other fields may be shortened.<br><br><b><b>-q</b>, <b>--quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only show numeric IDs of images, useful for scripting purposes like removing all dangling images.<br><br><b><b>--sort</b> <i>sort_order</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sort output based on a specific field. Possible values include <i>created</i>, <i>size</i>, <i>id</i>, <i>repository</i>, <i>tag</i>.<br><br>


title: DESCRIPTION
content:
The <b>podman-images</b> command is used to display a list of all images stored in the local Podman image store. It provides essential details for each image, including its <b>ID</b>, <b>repository</b>, <b>tag</b>, <b>size</b>, and <b>creation date</b>. This command is crucial for managing your local image inventory, helping users understand which images are available for running containers, building new ones, or for cleanup operations.<br><br>Users can easily filter the output, show only image IDs for scripting, or format the display using Go templates for custom reporting. It interacts directly with Podman's local storage backend, which can be configured for rootless or rootful operations, affecting where images are stored and how they are managed on the system.


title: CAVEATS
content:
The <b>SIZE</b> column typically represents the virtual size of the image, which is the sum of the sizes of all its unique layers. It does not necessarily reflect the exact disk space consumed, especially when layers are shared among multiple images.<br><br>Images with <b>&lt;none&gt;</b> in their <b>REPOSITORY</b> or <b>TAG</b> fields are often 'dangling' images (not associated with any tag or repository) or intermediate layers from a build process. While not always problematic, they can indicate unused disk space and may be candidates for removal.


title: USAGE EXAMPLES
content:
<b>List all images (including intermediate)</b>:<br><br><pre>podman images -a</pre><br><b>Show only image IDs</b>:<br><br><pre>podman images -q</pre><br><b>Filter images by repository</b>:<br><br><pre>podman images fedora</pre><br><b>Find dangling images</b>:<br><br><pre>podman images -f 'dangling=true'</pre><br><b>Format output to show ID and size</b>:<br><br><pre>podman images --format '{{.ID}}	{{.Size}}'</pre>


title: HISTORY
content:
<b>Podman</b> emerged as a daemonless alternative to Docker, adhering to OCI (Open Container Initiative) standards. The <b>podman-images</b> command was developed as a direct counterpart to <b>docker images</b>, providing a familiar and compatible interface for listing and managing container images. Its evolution is closely tied to the broader Podman project, aiming to offer robust container management capabilities without relying on a central daemon process.


title: PARAMETERS
content:
<b>--authfile=<path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a custom path to the authentication file to use. This overrides the default location.<br><br><b>--cert-dir=<path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provide a path to client certificates for TLS authentication with the registry. This is useful for registries requiring client-side certificates.<br><br><b>--get-login</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Retrieve login credentials from the authentication file without performing a new login. This can be useful for scripting purposes to check existing login status.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a brief help message for the command and exit.<br><br><b>--no-hosts</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevent the registry from being added to the system's registries configuration file (<i>/etc/containers/registries.conf</i> or user-specific files). This can be useful for one-time logins.<br><br><b>-p, --password=<password></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provide the password for authentication directly on the command line. <i>Note: Using this option is generally insecure as the password might be exposed in shell history or process listings. It is recommended to let Podman prompt for the password interactively.</i><br><br><b>--tls-verify=<true|false></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Require TLS verification when connecting to the registry. The default value is <b>true</b>. Set to <b>false</b> to disable TLS certificate verification (not recommended for production).<br><br><b>-u, --username=<username></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provide the username for authentication to the registry.<br><br>


title: DESCRIPTION
content:
The <b>podman-login</b> command is used to authenticate Podman to a specified container registry. This authentication allows you to securely pull and push container images to and from private or protected registries. When invoked without a specific registry URL, it attempts to log into the default Docker Hub registry (<i>docker.io</i>). Credentials, once successfully entered, are typically stored in an authentication file (e.g., <i>containers-auth.json</i>, often found in your XDG runtime directory or user configuration directory). This stored authentication information is then used by subsequent Podman commands like <b>podman pull</b> or <b>podman push</b> for operations requiring registry access. It is an essential command for managing container images in secure, enterprise-level environments or when working with custom private registries.


title: CAVEATS
content:
Providing the password directly on the command line using the <i>-p</i> or <i>--password</i> option is highly insecure. This method may expose your credentials in shell history, logs, or process listings. It is strongly recommended to omit the password argument and allow <b>podman-login</b> to interactively prompt you for it, which is the more secure approach.<br><br>Login credentials are saved in a JSON-formatted authentication file (typically named <i>containers-auth.json</i>) within your user's configuration directory (e.g., <i>~/.config/containers/auth.json</i>) or the XDG runtime directory. This file stores encrypted credentials for future Podman operations.


title: DEFAULT REGISTRY
content:
If no <i>registry</i> argument is provided to <b>podman-login</b>, the command defaults to authenticating against <b>docker.io</b>, which is the official Docker Hub registry.


title: INTERACTIVE PASSWORD PROMPT
content:
For enhanced security, if the password is not supplied via command-line options (e.g., <i>-p</i>), <b>podman-login</b> will interactively prompt the user to enter the password. This prevents the password from being recorded in shell history or being visible in process lists.


title: AUTHENTICATION FILE LOCATION
content:
After a successful login, credentials are saved in a JSON file, typically located at <i>$XDG_RUNTIME_DIR/containers/auth.json</i> or <i>~/.config/containers/auth.json</i>. Podman automatically references this file for subsequent authenticated operations like pulling or pushing images.


title: HISTORY
content:
<b>podman-login</b> is an integral part of the Podman project, which emerged as an open-source, daemonless alternative to Docker for managing OCI containers and pods on Linux systems. Developed with a focus on security and integration with standard Linux tools, Podman aimed to provide a familiar command-line experience. The <b>login</b> command has been a core capability since Podman's early development, enabling users to interact seamlessly with various container registries, which is fundamental for image distribution and management in modern containerized workflows.


title: SEE ALSO
content:
podman(1), podman-logout(1), podman-pull(1), podman-push(1), containers-auth.json(5), registries.conf(5)


title: SYNOPSIS
content:
<b>podman machine</b> <I>subcommand</I> [<i>options</i>]<br>Example: <b>podman machine init</b><br>Example: <b>podman machine start</b> <I>my-machine</I>


title: PARAMETERS
content:
<b>init</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Initializes and creates a new Podman virtual machine.<br><br><b>start</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts an existing Podman virtual machine.<br><br><b>stop</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stops a running Podman virtual machine gracefully.<br><br><b>rm</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes one or more Podman virtual machines.<br><br><b>ls</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all configured Podman virtual machines.<br><br><b>ssh</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connects to a running Podman virtual machine via SSH.<br><br><b>inspect</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays detailed configuration and status information about a virtual machine.<br><br><b>set</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Modifies configuration settings of an existing virtual machine.<br><br><b>os</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manages operating system images used by Podman machines.<br><br><b>--help, -h</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the 'podman machine' command or a specific subcommand.<br><br>


title: DESCRIPTION
content:
The <b>podman-machine</b> command is a crucial component of the Podman ecosystem, specifically designed to manage Podman virtual machines (VMs). It provides a lightweight Linux environment for running Podman containers natively on operating systems like macOS and Windows, where Podman cannot run directly on the host. This command handles the entire lifecycle of these VMs, including creation, starting, stopping, removing, and listing them. By abstracting away the underlying virtualization technology (often QEMU), <b>podman-machine</b> offers a streamlined user experience, allowing users to interact with Podman as if it were running natively on their system. It ensures that Podman commands execute within a dedicated, isolated Linux guest, providing compatibility and performance benefits for containerized applications.


title: CAVEATS
content:
While <b>podman-machine</b> simplifies VM management, it consumes host system resources (CPU, memory, disk). Network configuration within the VM may require understanding of port forwarding or VPNs for external access. On Linux hosts, <b>podman machine</b> can still be used but is often less necessary as Podman runs natively; however, it can provide an isolated environment if desired. The underlying virtualization technology and default operating system (typically Fedora CoreOS or RHEL CoreOS) are generally abstracted but can be configured if advanced customization is needed.


title: SUBCOMMAND-SPECIFIC OPTIONS
content:
Many <b>podman machine</b> subcommands have their own unique options to customize their behavior. For instance, <b>podman machine init</b> accepts options like <b>--cpus</b>, <b>--disk-size</b>, <b>--memory</b>, and <b>--image</b> to configure the new VM's resources and base operating system. Users should consult the help output for each specific subcommand (e.g., <b>podman machine init --help</b>) to explore all available configuration options.


title: UNDERLYING TECHNOLOGY
content:
On macOS and Windows, <b>podman-machine</b> typically uses QEMU as the virtualization backend. On Linux, it can optionally use QEMU or a libvirt-based backend. The default guest operating system for the virtual machine is usually Fedora CoreOS or RHEL CoreOS, optimized for container workloads and minimal footprint.


title: HISTORY
content:
The <b>podman-machine</b> command emerged as Podman's popularity grew beyond Linux, particularly on macOS and Windows. Initially, Podman offered <b>podman remote</b> for connecting to a Podman service running on a separate Linux host. To provide a more integrated and user-friendly experience, <b>podman machine</b> was introduced to automatically manage a local, lightweight Linux virtual machine. This feature gained prominence around Podman 3.0, leveraging lightweight Linux distributions like Fedora CoreOS to provide an efficient environment for running containers with native Podman capabilities, bridging the gap for non-Linux users.


title: PARAMETERS
content:
<b><b>-a</b>, <b>--all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display all containers, including exited ones. By default, only running containers are shown.<br><br><b><b>-l</b>, <b>--latest</b>, <b>--last</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the latest created container, regardless of its state.<br><br><b><b>-n</b>, <b>--no-trunc</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Don't truncate output. Show full container IDs, names, and command details.<br><br><b><b>-q</b>, <b>--quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only display numeric IDs of containers, useful for scripting.<br><br><b><b>-s</b>, <b>--size</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display total file sizes of containers, including the size of the container's root filesystem and a virtual size.<br><br><b><b>-f</b>, <b>--filter <I>filter</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filter output based on conditions (e.g., status, name, image, id, ancestor).<br><br><b><b>--format <I>format</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pretty-print containers using a Go template for highly customized output.<br><br><b><b>-p</b>, <b>--pods</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show containers that are part of a pod, indicating their associated pod ID.<br><br><b><b>--sort <I>column</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sort output by specified column name (e.g., 'id', 'name', 'status', 'created').<br><br><b><b>--sync</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Synchronize container state with storage. Ensures the displayed status is up-to-date.<br><br>


title: DESCRIPTION
content:
The <I>podman-ps</I> command is used to list Podman containers. By default, it displays only <I>running</I> containers. This command provides a quick overview of active containerized processes, including their ID, image, command, creation time, status, exposed ports, and assigned names. It serves as the primary utility for inspecting the current state of containers managed by Podman. Users familiar with Docker will find its functionality analogous to <I>docker ps</I>.<br><br>The output can be customized to show all containers (including exited ones), display file sizes, or be filtered and formatted for specific information, making it an indispensable tool for container management and troubleshooting.


title: CAVEATS
content:
When using the <I>--format</I> option, constructing complex Go templates can be challenging and requires familiarity with Go template syntax. Filtering with <I>--filter</I> requires knowledge of available keys like <I>status</I>, <I>name</I>, or <I>id</I>, and invalid keys will be ignored. The <I>--sync</I> option can take time to complete if there are many containers or if the storage backend is slow, potentially delaying output.


title: OUTPUT COLUMNS
content:
By default, <I>podman-ps</I> displays several columns: <I>CONTAINER ID</I>, <I>IMAGE</I>, <I>COMMAND</I>, <I>CREATED</I>, <I>STATUS</I>, <I>PORTS</I>, and <I>NAMES</I>. These columns provide essential information for quick identification and status checks of containers.


title: FILTERING EXAMPLES
content:
You can filter the output using <I>--filter</I>. For instance, <B>podman ps --filter status=exited</B> shows only stopped containers. Multiple filters can be combined, such as <B>podman ps --filter status=running --filter ancestor=myimage</B> to refine results.


title: GO TEMPLATE FORMATTING
content:
The <I>--format</I> option allows for highly customized output. For example, <B>podman ps --format \"{{.ID}} {{.Names}}\"</B> will display only the container ID and name. This uses Go template syntax, offering powerful formatting capabilities by accessing various container attributes.


title: HISTORY
content:
<I>podman-ps</I> is a core command within the Podman project, which emerged as a daemonless alternative to Docker, focusing on OCI (Open Container Initiative) standards. Its design deliberately mirrors the well-known <I>docker ps</I> command, aiming for ease of transition for users migrating from Docker.<br><br>The command has been integral to Podman's evolution, providing immediate insight into the state of containers without requiring a background daemon, aligning with Podman's systemd-friendly and rootless container capabilities. Its continuous development reflects the community's commitment to robust and user-friendly container management.


title: SEE ALSO
content:
podman(1), podman-container(1), podman-run(1), podman-start(1), podman-stop(1), podman-rm(1), podman-inspect(1)


title: PARAMETERS
content:
<b><b>-a</b>, <b>--all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Remove all images, not just specified ones. This option cannot be used with specific image names or IDs.<br><br><b><b>-f</b>, <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force removal of the image. This allows removal of images even if they are used by a running container, by stopping and removing the container first.<br><br><b><b>--no-prune</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not delete untagged parent images or untagged layers that are no longer referenced after removing a specific image.<br><br>


title: DESCRIPTION
content:
<i>podman-rmi</i> is used to remove one or more images from the local Podman storage. Images can be specified by their full or partial ID, name, or digest. When an image is removed, it frees up disk space consumed by that image's layers.<br><br>An image cannot be removed if it is currently in use by a running container unless the <b>--force</b> option is used. If an image is tagged multiple times, <i>podman-rmi</i> will only remove the specified tag. The underlying image data will only be deleted from storage if it becomes untagged and is not referenced by any other existing containers or images.<br><br>This command is essential for managing local image storage, cleaning up old or unused images, and recovering disk space, especially in development environments where images are frequently built and discarded.


title: CAVEATS
content:
<b>Running Containers:</b> An image cannot be removed if it is actively being used by a running container without the <b>--force</b> flag. Attempting to do so will result in an error.<br><br><b>Shared Layers and Disk Space:</b> Image removal only frees up space if all references to its layers are gone. If layers are shared by other images, those layers will not be deleted until all referencing images are removed.<br><br><b>Tagged Images:</b> If an image has multiple tags, <i>podman-rmi</i> only removes the specific tag provided. The image itself and its data are only removed when its last tag is gone and no containers depend on it.


title: IMAGE IDENTIFIERS
content:
Images can be identified for removal using their short or full image ID, their repository name (e.g., <i>fedora:latest</i> or <i>myregistry.com/myimage</i>), or a specific digest (e.g., <i>myimage@sha256:...</i>). When using a name, only the specified tag is removed. If the image has multiple tags and the specified tag is removed, the image remains until its last tag is removed and no containers are dependent on it.


title: DANGLING IMAGES
content:
Images that have no associated tags but still consume disk space are often referred to as 'dangling' images. While <i>podman-rmi</i> can remove specific untagged images by their ID, the <i>podman image prune</i> command is typically more efficient for clearing all dangling and unused images that are not referenced by any containers or other images.


title: HISTORY
content:
<i>podman-rmi</i> is a core command within the Podman project, an open-source, daemonless container engine for developing, managing, and running OCI Containers on Linux. It was developed as a direct analog to the <i>docker rmi</i> command, providing a familiar interface for users migrating from Docker to Podman, while adhering to Podman's unique daemonless architecture. Its functionality aligns with standard container image management practices.


title: SEE ALSO
content:
podman(1), podman-images(1), podman-image-prune(1), podman-build(1), podman-pull(1), podman-container-rm(1)


title: PARAMETERS
content:
<b><b>-d</b>, <b>--detach</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs the container in the background, printing the new container ID.<br><br><b><b>--name</b>=<i>name</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assigns a specific name to the container instead of a randomly generated one.<br><br><b><b>-p</b>, <b>--publish</b>=<i>port</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Maps a container port to a host port (e.g., 8080:80).<br><br><b><b>-v</b>, <b>--volume</b>=<i>source:destination[:options]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Mounts a host path or named volume into the container.<br><br><b><b>-e</b>, <b>--env</b>=<i>key=value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets environment variables inside the container.<br><br><b><b>--rm</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Automatically removes the container filesystem upon exit.<br><br><b><b>--network</b>=<i>mode|name|id</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connects the container to a specified network.<br><br><b><b>--mount</b>=<i>type=bind,source=...,destination=...</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attaches a filesystem mount to the container (more explicit than <b>--volume</b>).<br><br><b><b>--restart</b>=<i>policy</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the container's restart policy (e.g., 'no', 'on-failure', 'always').<br><br><b><b>--user</b>=<i>name|uid[:group|gid]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the user and/or group to run the command as inside the container.<br><br><b><b>--security-opt</b>=<i>option</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Configures container security options (e.g., 'no-new-privileges').<br><br><b><b>--hostname</b>=<i>name</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the container's hostname.<br><br><b><b>--entrypoint</b>=<i>command</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Overrides the default ENTRYPOINT command of the image.<br><br><b><b>-i</b>, <b>--interactive</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Keeps STDIN open even if not attached, allowing for interactive input.<br><br><b><b>-t</b>, <b>--tty</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allocates a pseudo-TTY for the container, often used with <b>-i</b>.<br><br><b><b>--read-only</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Mounts the container's root filesystem as read-only.<br><br><b><b>--pull</b>=<i>always|missing|never</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls when the image is pulled from the registry (default is 'missing').<br><br><b><b>--label</b>=<i>key=value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds metadata labels to the container.<br><br><b><b>--add-host</b>=<i>host:ip</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds custom host-to-IP mappings in the container's <i>/etc/hosts</i> file.<br><br><b><b>--device</b>=<i>host_path[:container_path][:permissions]</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a host device to the container.<br><br><b><b>--cap-add</b>=<i>capability</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds Linux capabilities to the container.<br><br><b><b>--cap-drop</b>=<i>capability</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Drops Linux capabilities from the container.<br><br>


title: DESCRIPTION
content:
The <b>podman-run</b> command is a fundamental tool for managing OCI (Open Container Initiative) containers with Podman, a daemonless container engine. It's used to launch a new container from a specified image, executing a command within that isolated environment. Unlike traditional daemon-based container engines, Podman operates directly with the container runtime, making it well-suited for rootless operations and integration with systemd. <b>podman-run</b> allows users to configure various aspects of the container's lifecycle and environment, including port mappings, volume mounts, environment variables, network configurations, and resource limits. It enables the creation of ephemeral or persistent containers, facilitating application deployment, development, and testing workflows in a secure and flexible manner, often serving as a drop-in replacement for <b>docker run</b>.


title: CAVEATS
content:
When running <b>podman-run</b> as a non-root user (rootless containers), certain operations like binding to privileged ports (below 1024) or mounting specific host paths may require additional configurations or might be restricted. While <b>podman-run</b> automatically pulls images if not present locally, network connectivity is required for this action. Unlike Docker, Podman is daemonless, meaning containers are managed directly by the user's process and don't rely on a central daemon, which can impact persistent service management (often handled via <i>systemd</i> for long-running containers).


title: IMAGE PULLING BEHAVIOR
content:
By default, if the specified <i>image</i> is not found locally, <b>podman-run</b> will automatically attempt to pull it from configured container registries (e.g., Docker Hub, Quay.io). This behavior can be explicitly controlled using the <b>--pull</b> option, allowing users to force a pull, prevent pulls, or only pull if the image is missing locally.


title: CONTAINER LIFECYCLE
content:
A container created with <b>podman-run</b> executes the specified <i>command</i>. Once the command finishes, the container will stop. Unless the <b>--rm</b> flag is used, the stopped container and its writable layer will persist on the system, consuming disk space. Users can later restart, inspect, or remove these stopped containers using other <b>podman</b> commands.


title: ROOTLESS CONTAINERS
content:
A significant feature of Podman is its support for rootless containers. When <b>podman-run</b> is executed by a regular (non-root) user, it creates a container that runs without root privileges on the host system. This enhances security by isolating the containerized process, preventing it from having root access to the host's kernel or system files, and leveraging user namespaces for privilege separation.


title: HISTORY
content:
Podman emerged as a daemonless alternative to Docker, primarily developed by Red Hat. Its design philosophy emphasizes security, particularly rootless operations, and integration with standard Linux tools like <i>systemd</i>. The <b>podman-run</b> command was conceived to mimic the behavior and options of <b>docker run</b>, making it easy for users to transition between the two container engines. Its development has focused on OCI compliance, ensuring interoperability with other container tools and registries, and promoting a more modular approach to container management compared to monolithic daemon architectures.


title: SEE ALSO
content:
podman(1), podman-build(1), podman-start(1), podman-stop(1), podman-ps(1), podman-images(1), podman-network(1), docker-run(1)


title: PARAMETERS
content:
<b>-section <i>section</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a section to be extracted. This option can be repeated multiple times to select multiple sections. Sections are identified by their titles (e.g., "NAME", "SYNOPSIS") or POD heading types (e.g., "head1", "head2").<br><br><b>-output <i>file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Directs the extracted content to the specified <i>file</i> instead of standard output (stdout).<br><br><b><i>podfile</i> ...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more input files in POD format from which sections will be extracted.<br><br>


title: DESCRIPTION
content:
podselect is a command-line utility designed to extract and display specific sections from Plain Old Documentation (POD) format files. POD is a simple, lightweight markup language primarily used for documenting Perl modules, scripts, and other text. podselect allows users to filter content by section titles, such as <b>NAME</b>, <b>SYNOPSIS</b>, <b>DESCRIPTION</b>, or specific heading levels like <b>head1</b>, <b>head2</b>, etc. By default, if no sections are specified, it outputs the entire content of the POD file. This tool is invaluable for quickly reviewing particular parts of documentation without needing to process the entire file through a POD formatter. It's often used in scripting to automate the extraction of specific information from Perl's documentation files.


title: CAVEATS
content:
podselect primarily works by matching section <i>titles</i> or <i>heading levels</i>. It might not perfectly replicate the output of full POD renderers like pod2man or pod2text, as it focuses on simple extraction rather than full formatting or semantic interpretation. Its utility is in quick, raw extraction of specific parts, not polished presentation.


title: COMMON USAGE
content:
podselect is particularly useful for scripting when only a specific piece of information, such as the <b>NAME</b> or <b>SYNOPSIS</b> section, is needed from a Perl module's documentation without processing the entire document. For instance, <code>podselect -section NAME MyModule.pm</code> would output just the name of the module.


title: POD FORMAT OVERVIEW
content:
POD (Plain Old Documentation) uses simple paragraph-based markup (e.g., <code>=head1</code>, <code>=item</code>, <code>=over</code>, <code>=cut</code>) to embed documentation directly within source code files. podselect understands these structural markers to identify and extract the specified sections.


title: HISTORY
content:
podselect is an integral part of the Perl programming language distribution. It emerged as part of the broader effort to provide robust and accessible documentation for Perl modules and scripts using the Plain Old Documentation (POD) format. Its development parallels the evolution of Perl itself, offering a simple yet powerful tool for developers and users to interact with Perl's extensive documentation ecosystem. It is maintained as part of the <code>perl</code> core utilities.


title: SYNOPSIS
content:
<I>poetry</I> [<B>--version</B>] [<B>--help</B>] [<B>--quiet</B> | <B>-q</B>] [<B>--verbose</B> | <B>-v</B> | <B>-vv</B> | <B>-vvv</B>] [<B>--ansi</B>] [<B>--no-ansi</B>] [<B>--no-interaction</B>] [<B>--profile</B>] [<B>--directory</B> <I>DIRECTORY</I>] <I>command</I> [<I>options</I>] [<I>arguments</I>]<br><br>Common usage examples:<br><I>poetry</I> <B>new</B> <I>my-project</I><br><I>poetry</I> <B>add</B> <I>requests</I><br><I>poetry</I> <B>install</B><br><I>poetry</I> <B>run</B> <I>python</I> <I>my_script.py</I><br><I>poetry</I> <B>build</B><br><I>poetry</I> <B>publish</B>


title: PARAMETERS
content:
<b><B>--version</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the application's version.<br><br><b><B>--help</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help for the current command or a specific subcommand.<br><br><b><B>--quiet</B>, <B>-q</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not output any message.<br><br><b><B>--verbose</B>, <B>-v</B>, <B>-vv</B>, <B>-vvv</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increase the verbosity of messages: <B>-v</B> for normal output, <B>-vv</B> for more verbose output, and <B>-vvv</B> for debug output.<br><br><b><B>--ansi</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force ANSI output (for colored text).<br><br><b><B>--no-ansi</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable ANSI output (for plain text).<br><br><b><B>--no-interaction</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not ask any interactive question (useful for scripting).<br><br><b><B>--profile</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display timing and memory usage for a command.<br><br><b><B>--directory</B> <I>DIRECTORY</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The working directory for the Poetry project, if different from the current directory.<br><br>


title: DESCRIPTION
content:
<I>Poetry</I> is a Python dependency management and packaging tool that aims to simplify and streamline the development workflow for Python projects. It manages your project's dependencies, creates isolated virtual environments, builds distributions, and publishes packages to repositories like PyPI. <br><br>Unlike traditional tools like <I>pip</I> and <I>setuptools</I> used separately, <I>Poetry</I> provides an all-in-one solution with a focus on deterministic dependency resolution and ease of use. It utilizes a `pyproject.toml` file (PEP 518) to declare project metadata and dependencies, and generates a `poetry.lock` file to ensure reproducible builds across different environments. <br><br>Its robust dependency solver ensures that compatible versions of all dependencies are installed, preventing common version conflicts. <I>Poetry</I> significantly enhances productivity for Python developers by automating many tedious aspects of project setup, dependency handling, and packaging, making it a popular choice for modern Python development.


title: CAVEATS
content:
<I>Poetry</I> is not a standard Linux command-line utility but a third-party Python application. It must be installed separately, typically via methods like <I>pipx</I> or <I>pip</I>. While powerful, it introduces a specific workflow that might differ from traditional <I>pip</I> and <I>venv</I> setups, requiring some initial adaptation. It is recommended to install <I>Poetry</I> itself in an isolated environment (e.g., using <I>pipx</I>) to avoid conflicts with system Python installations or project dependencies.


title: INSTALLATION
content:
<I>Poetry</I> is typically installed using <I>pipx</I>, which ensures it's isolated from your project dependencies: <br> <B>pipx install poetry</B> <br> Alternatively, it can be installed directly via <I>pip</I>: <br> <B>pip install poetry</B>


title: KEY CONFIGURATION FILES
content:
Projects managed by <I>Poetry</I> primarily use two files in the project root: <br> <B>pyproject.toml</B>: Defines project metadata, dependencies, and build system (PEP 518/517). This file serves as the central configuration for a Poetry project. <br> <B>poetry.lock</B>: A lock file generated by <I>Poetry</I> that records the exact versions of all dependencies and sub-dependencies, ensuring reproducible builds across different machines and environments.


title: HISTORY
content:
<I>Poetry</I> was created by Sławomir Gawroński with the goal of improving Python dependency management and packaging. It emerged as a response to the challenges of managing project dependencies and virtual environments with existing tools like <I>pip</I>, <I>virtualenv</I>, and <I>setuptools</I> individually. <br><br>Initially released around 2018, <I>Poetry</I> quickly gained traction for its innovative approach, particularly its robust dependency resolver and its adoption of `pyproject.toml` (PEP 518) for project metadata and configuration. It provided a holistic solution that combined dependency resolution, virtual environment management, building, and publishing into a single CLI tool, offering a more consistent and user-friendly experience than its predecessors. Its development continues, focusing on stability, performance, and adherence to modern Python packaging standards.


title: PARAMETERS
content:
<b><I>profile_name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the name of the PPPoE connection profile to disconnect. If omitted, <code>poff</code> typically attempts to disconnect the default or currently active PPPoE session.<br><br>


title: DESCRIPTION
content:
<code>poff</code> is not a standard, standalone Linux command but rather a common <I>utility script</I> provided by PPPoE (Point-to-Point Protocol over Ethernet) client packages, most notably the <I>rp-pppoe</I> client. Its primary function is to terminate an active broadband connection that was established using PPPoE, typically initiated by a corresponding <code>pon</code> script. <br><br>While not part of the core Linux utilities, <code>poff</code> serves as a user-friendly wrapper around lower-level commands like <code>pppd</code> (PPP daemon) or <code>pppoe</code> to cleanly shut down the network interface and associated processes. Its availability and exact behavior are entirely dependent on the specific PPPoE client software installed on the system.


title: CAVEATS
content:
<code>poff</code> is <B>not a universally standard</B> Linux command. Its existence, syntax, and functionality are entirely dependent on the specific PPPoE client software (e.g., <I>rp-pppoe</I>) installed on the system. <br><br>It usually requires <B>root privileges</B> or <code>sudo</code> to execute successfully, as it modifies network interfaces and manages system-level processes. <br><br>The script's behavior can vary; some implementations might simply kill the <code>pppd</code> process, while others perform a more graceful shutdown and update connection status files.


title: TYPICAL USAGE
content:
<code>poff</code> is commonly used to manually disconnect a PPPoE internet connection when it's no longer needed, or before switching to a different network configuration. It's often used in conjunction with <code>pon</code> to manage connection uptime. For example, after running <code>pon</code> to establish a connection, <code>poff</code> would be used later to tear it down.


title: HISTORY
content:
The <code>poff</code> script, along with its counterpart <code>pon</code>, gained prominence with the widespread adoption of DSL (Digital Subscriber Line) and other broadband internet services that utilized PPPoE for authentication and connection management. <br><br>Packages like <I>rp-pppoe</I> (Roaring Penguin PPPoE client) provided these user-friendly scripts to simplify the process of initiating (<code>pon</code>) and terminating (<code>poff</code>) PPPoE connections, abstracting the complexities of managing <code>pppd</code> and network interfaces directly. Its development closely mirrored the evolution of Linux as a desktop and gateway operating system for home and small office broadband users.


title: SYNOPSIS
content:
<b>pkexec</b> [--user <i>user</i>] [--disable-internal-agent] [--version] [--help] <i>PROGRAM</i> [<i>ARGUMENTS...</i>]


title: PARAMETERS
content:
<b>--user <i>user</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Execute <i>PROGRAM</i> as the specified <i>user</i> instead of the default (root).<br><br><b><i>PROGRAM</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The command or executable to run with elevated privileges.<br><br><b><i>ARGUMENTS...</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional arguments passed directly to the <i>PROGRAM</i> being executed.<br><br><b>--disable-internal-agent</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents <i>pkexec</i> from using its internal authentication agent. Useful for debugging or specific environments where an external agent is guaranteed to be running.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the <i>pkexec</i> version information and exit.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show a brief help message and exit.<br><br>


title: DESCRIPTION
content:
Polkit (formerly PolicyKit) is an application programming interface (API) for defining and handling authorizations for unprivileged applications to use privileged system services. While Polkit itself is a framework, <i><b>pkexec</b></i> is the primary command-line utility used by end-users and applications to interact with Polkit for privilege elevation. It allows an authorized user to execute a program as another user (by default, the superuser, <i>root</i>), similar in functionality to <i>sudo</i>, but leveraging Polkit's fine-grained policy system. <br><br>Unlike <i>sudo</i>, which relies on a static configuration file (<i>/etc/sudoers</i>), <i>pkexec</i> consults the <i>polkitd</i> daemon to determine if the calling process is authorized to perform the requested action. This authorization is based on policies defined in configuration files, often allowing for more specific and contextual rules. For instance, a policy might allow a user to perform a specific action (e.g., mount a filesystem) without granting full root access. Authentication, if required by the policy, is handled by an authentication agent (like <i>pkttyagent</i> for the console or a graphical agent), which prompts the user for credentials.


title: CAVEATS
content:
<b>Security Configuration:</b> The security of <i>pkexec</i> largely depends on correctly configured Polkit policies. Misconfigurations can lead to unauthorized privilege escalation. <br><b>Environment Variables:</b> For security, <i>pkexec</i> sanitizes the environment, passing only a safe, minimal set of environment variables to the executed program. This can sometimes cause issues for programs that rely on specific environment variables (e.g., <i>PATH</i> differences or custom library paths). <br><b>Authentication Agents:</b> <i>pkexec</i> requires an active Polkit authentication agent (e.g., <i>pkttyagent</i> for TTY, or a graphical agent for desktop environments) to prompt for credentials if authentication is required by the policy. If no agent is available, authentication requests will fail.


title: POLKIT FRAMEWORK OVERVIEW
content:
Polkit is a system service that provides a centralized mechanism for managing policy. It allows applications to declare actions (e.g., <i>org.freedesktop.udisks2.filesystem-mount</i>), and the <i>polkitd</i> daemon evaluates requests for these actions based on a set of rules. These rules are typically defined in JavaScript files (<i>.rules.d</i>) or older <i>.pkla</i> files, determining whether an action is allowed, requires authentication, or is explicitly denied for a given user or group. This separation of authorization logic from the application code enhances security and flexibility.


title: DIFFERENCES FROM SUDO
content:
While both <i>pkexec</i> and <i>sudo</i> allow users to execute commands with elevated privileges, they operate on different principles. <i>sudo</i> primarily relies on static configurations in <i>/etc/sudoers</i>, granting users permission to run specific commands as root or other users. <i>pkexec</i>, conversely, uses Polkit policies which can be far more dynamic and contextual, allowing for fine-grained control over specific actions (e.g., mount a particular device, change a specific network setting). This makes <i>pkexec</i> particularly well-suited for graphical applications and modern desktop environments where precise authorization is preferred over blanket root access.


title: HISTORY
content:
Polkit (originally PolicyKit) was developed by David Zeuthen at Red Hat, with its initial releases around 2007. It emerged as a response to the growing need for a more granular and flexible authorization system in desktop Linux environments, distinct from traditional methods like <i>sudo</i> which often grant broad root access. <i>pkexec</i> was introduced as the primary command-line interface for users and applications to request elevated privileges through the Polkit framework, aiming to provide a safer and more policy-driven alternative for specific system actions.


title: PARAMETERS
content:
<b>--no-debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents <b>polkitd</b> from emitting debug messages to the system log. This option is typically used in production environments to reduce log verbosity.<br><br><b>--no-daemon</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Keeps <b>polkitd</b> running in the foreground instead of forking into the background as a daemon. This is useful for debugging purposes or when running <b>polkitd</b> under a process supervisor like systemd that handles daemonization.<br><br>


title: DESCRIPTION
content:
<b>polkitd</b> is the PolicyKit daemon, a crucial low-level authorization framework on Linux systems. It enables unprivileged applications and users to interact with privileged system services securely. Instead of granting full root access, <b>polkitd</b> allows applications to request specific actions (e.g., managing users, configuring networking, mounting devices) that require elevated privileges. It evaluates these requests against a set of rules (policies) based on the requesting user, group, and context. If authorization is required, it often prompts the user for authentication (e.g., a password) via a graphical agent. This mechanism provides a more granular and secure way to handle system permissions, bridging the gap between user applications and administrative tasks.


title: CAVEATS
content:
Misconfigured Polkit policies can lead to security vulnerabilities, allowing unauthorized privilege escalation, or conversely, blocking legitimate administrative actions. Debugging issues often involves inspecting system logs (e.g., via <b>journalctl</b>) and carefully reviewing Polkit policy files and rules. The order of policy evaluation is crucial and can be complex.


title: POLICY FILES
content:
<b>polkitd</b> relies on policy files to define available actions and authorization rules. Default actions are typically found in <i>/usr/share/polkit-1/actions/</i>, while local overrides and custom rules are placed in <i>/etc/polkit-1/rules.d/</i>. These files are crucial for defining what actions can be performed and under what conditions, often using JavaScript-like syntax for complex rules.


title: INTERACTION WITH APPLICATIONS
content:
Applications do not directly execute <b>polkitd</b>. Instead, they use a client library (typically via D-Bus) to request authorization for specific actions. <b>polkitd</b> then processes this request, applies relevant policies, and if necessary, interacts with a Polkit authentication agent (usually provided by the desktop environment) to prompt the user for credentials.


title: HISTORY
content:
Polkit, originally named PolicyKit, was developed by David Zeuthen at Red Hat to provide a more flexible and robust authorization system for modern Linux desktops and system services. It emerged as an improvement over traditional privilege escalation methods like <b>sudo</b> for graphical environments, offering finer-grained control and a more user-friendly authentication experience. It became a standard component in major Linux distributions and desktop environments (GNOME, KDE), playing a pivotal role in secure desktop integration with system administration tasks.


title: PARAMETERS
content:
<b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message and exits.<br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows version information and exits.<br><br><b><b>-q</b>, <b>--quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses most informational output from polybar.<br><br><b><b>-r</b>, <b>--reload</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sends a reload signal to all running polybar instances on the current display.<br><br><b><b>-c &lt;FILE&gt;</b>, <b>--config=&lt;FILE&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative path to the configuration file (default is usually <i>~/.config/polybar/config</i>).<br><br><b><b>-l &lt;LEVEL&gt;</b>, <b>--log=&lt;LEVEL&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the logging verbosity level. Levels include <i>trace</i>, <i>debug</i>, <i>info</i>, <i>warning</i>, and <i>error</i>.<br><br><b><b>-m &lt;MONITOR&gt;</b>, <b>--monitor=&lt;MONITOR&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects a specific monitor by name (e.g., <i>DP-1</i>) or index to run the bar on.<br><br><b><i>BAR_NAME...</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more names of bars to launch as defined in the configuration file. If omitted, all bars without a 'monitor' setting will be launched.<br><br>


title: DESCRIPTION
content:
Polybar is a lightweight and highly customizable status bar designed for Linux. It's primarily used with tiling window managers like <b>i3</b>, <b>bspwm</b>, and <b>Awesome WM</b> to display system information such as CPU usage, memory, network activity, battery status, and more. Users can configure polybar extensively through a text-based configuration file, defining various modules, colors, fonts, and layouts. Its modular design allows users to integrate scripts and external tools, making it incredibly flexible for displaying custom information. Polybar aims to be fast and resource-efficient while providing a visually appealing and informative status bar.


title: CAVEATS
content:
<b>Xorg Dependency:</b> Polybar relies on Xorg and does not officially support Wayland, though experimental community projects exist.<br><b>Configuration Complexity:</b> Extensive customization requires detailed understanding of its INI-style configuration file, which can be verbose.<br><b>Resource Usage:</b> While generally lightweight, complex configurations with many modules and frequent updates can increase CPU/memory consumption.<br><b>Window Manager Integration:</b> Designed for tiling window managers, its integration with traditional desktop environments might be less seamless.


title: CONFIGURATION FILE
content:
Polybar's primary configuration is done via a plain text INI-style file, typically located at <i>~/.config/polybar/config</i> or <i>$XDG_CONFIG_HOME/polybar/config</i>. This file defines bars, modules, colors, fonts, and other display properties.


title: MODULES
content:
The core functionality of polybar is provided by its modules. These include built-in modules for common system information (e.g., <i>cpu</i>, <i>memory</i>, <i>date</i>, <i>filesystem</i>, <i>network</i>), as well as powerful custom modules like <i>script</i> and <i>custom/ipc</i> which allow users to integrate any shell script or external program output.


title: HISTORY
content:
Polybar was created as an open-source project to address the need for a highly customizable and modern status bar for tiling window managers on Linux. Development began around 2016-2017, aiming to provide a more feature-rich and aesthetically pleasing alternative to existing options like <b>i3status</b> or <b>lemonbar</b>, while still maintaining lightweight performance. It quickly gained popularity within the tiling window manager community due to its flexibility, extensive module system, and strong community support.


title: SYNOPSIS
content:
<b>polybar-msg</b> [<i>OPTIONS</i>] <i>MESSAGE_TYPE</i> [<i>ARGUMENTS...</i>]<br><br><i>Common Message Types:</i><br>&#8226; <b>polybar-msg command</b> <i>&lt;command_name&gt;</i><br>&#8226; <b>polybar-msg module</b> <i>&lt;module_name&gt; &lt;action&gt;</i><br>&#8226; <b>polybar-msg hook</b> <i>&lt;module_name&gt; &lt;hook_id&gt;</i><br>&#8226; <b>polybar-msg reload</b><br>&#8226; <b>polybar-msg restart</b><br>&#8226; <b>polybar-msg quit</b>


title: PARAMETERS
content:
<b>-p <i>&lt;PID&gt;</i>, --pid <i>&lt;PID&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the <i>Process ID</i> (PID) of the <i>Polybar</i> instance to which the message should be sent. If omitted, the message is sent to all running <i>Polybar</i> instances.<br><br><b>-c <i>&lt;PATH&gt;</i>, --socket <i>&lt;PATH&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Directly specifies the <i>IPC socket path</i> to use for communication. Useful if the default socket location is changed or multiple sockets exist.<br><br><b>-s <i>&lt;PATH&gt;</i>, --socket-dir <i>&lt;PATH&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the directory where <i>Polybar</i>'s <i>IPC sockets</i> are located. Defaults to `<i>/tmp/polybar/</i>`.<br><br><b>-H, --no-prefix</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses the `<i>[polybar-msg]</i>` prefix from the output messages.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a concise help message explaining the command's usage and available options.<br><br><b>-v, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the version information of the <b>polybar-msg</b> utility.<br><br><b><i>&lt;MESSAGE_TYPE&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The type of message or action to send. This can be <b>command</b>, <b>module</b>, <b>hook</b>, <b>reload</b>, <b>restart</b>, <b>quit</b>, <b>list-commands</b>, <b>help</b>, or <b>version</b>.<br><br><b><i>&lt;ARGUMENTS...&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Additional arguments required by certain <i>MESSAGE_TYPE</i>s, such as <i>&lt;command_name&gt;</i> for <b>command</b> messages, or <i>&lt;module_name&gt; &lt;action&gt;</i> for <b>module</b> messages.<br><br>


title: DESCRIPTION
content:
<b>polybar-msg</b> is a utility designed to communicate with running <i>Polybar</i> instances using <i>Inter-Process Communication</i> (IPC). It allows users and scripts to send various commands and actions to <i>Polybar</i> bars, enabling dynamic control without restarting the bar. This is particularly useful for integrating <i>Polybar</i> with other scripts, keybindings, or system events. Common uses include reloading bar configurations, toggling module visibility, executing internal <i>Polybar</i> commands, and triggering module hooks. By default, <b>polybar-msg</b> attempts to send messages to all active <i>Polybar</i> processes. However, it provides options to target a specific bar using its <i>Process ID</i> (PID) or by directly specifying the <i>IPC socket path</i>. This command acts as a crucial interface for automating and extending <i>Polybar</i>'s functionality.


title: CAVEATS
content:
<b>polybar-msg</b> requires that <i>Polybar</i> is running and has <i>IPC enabled</i> in its configuration (which is usually the default for recent versions).<br><br>If no specific PID or socket path is provided, the message will be sent to <i>all currently running Polybar instances</i>, which might not always be the desired behavior in multi-bar setups.<br><br>The exact syntax and available commands/modules/hooks depend on the specific <i>Polybar</i> version and the user's configuration. Use <b>polybar-msg list-commands</b> for a current list of available internal commands.


title: COMMON IPC MESSAGE TYPES
content:
&#8226; <b><code>command &lt;command_name&gt;</code></b>: Executes an internal <i>Polybar</i> command, such as <b><code>hide</code></b>, <b><code>show</code></b>, <b><code>toggle</code></b>, <b><code>fullscreen</code></b>, <b><code>monitor</code></b>, etc. <br><i>Example:</i> <b><code>polybar-msg command toggle</code></b><br><br>&#8226; <b><code>module &lt;module_name&gt; &lt;action&gt;</code></b>: Sends a specific action to a named module. Common actions include <b><code>toggle</code></b>, <b><code>set-icon</code></b>, <b><code>open</code></b>, <b><code>close</code></b>, etc., depending on the module type. <br><i>Example:</i> <b><code>polybar-msg module i3 toggle</code></b><br><br>&#8226; <b><code>hook &lt;module_name&gt; &lt;hook_id&gt;</code></b>: Triggers a custom hook for a <i><code>custom/script</code></i> or <i><code>custom/ipc</code></i> module. This allows external scripts to update module content. <br><i>Example:</i> <b><code>polybar-msg hook my_script_module 1</code></b><br><br>&#8226; <b><code>reload</code></b> / <b><code>restart</code></b> / <b><code>quit</code></b>: Control the entire <i>Polybar</i> instance, reloading its configuration, restarting the bar, or gracefully quitting it.


title: HISTORY
content:
<b>polybar-msg</b> was developed as an integral part of the <i>Polybar</i> project to provide a standardized <i>Inter-Process Communication</i> (IPC) interface. This allowed for more robust and flexible control of <i>Polybar</i> instances from external scripts or user input, improving its extensibility and integration capabilities within a desktop environment. Its development has mirrored <i>Polybar</i>'s evolution, with new message types and functionalities added to support new features in the bar itself.


title: PARAMETERS
content:
<b><b>-a</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays all active processes, including system and daemon processes.<br><br><b><b>-u</b> <I>user</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filters processes to show only those owned by the specified user.<br><br><b><b>-t</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Presents processes in a hierarchical tree structure, showing parent-child relationships.<br><br><b><b>-j</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs process information in JSON format, ideal for machine parsing and scripting.<br><br><b><b>-p</b> <I>field</I>[,<I>field</I>...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects and projects specific fields (e.g., PID, CPU, MEM) for display, similar to 'ps -o'.<br><br><b><b>-s</b> <I>field</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sorts the output based on the specified field (e.g., CPU, MEM, PID).<br><br><b><b>-i</b> <I>interval</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Refreshes the output every specified number of seconds, providing a dynamic view.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a concise help message with command usage and options.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the version information for the pom utility.<br><br>


title: DESCRIPTION
content:
The <b>pom</b> (<b>P</b>rocess <b>O</b>bject <b>M</b>onitor) command is a <i>hypothetical</i> Linux utility designed to provide a rich, structured, and potentially object-oriented view of running processes and system resource utilization.<br><br>Unlike traditional flat-file output tools like <b>ps</b> or interactive dashboards like <b>top</b>, <b>pom</b> aims to present process data in a hierarchical or relational manner, making it particularly well-suited for scripting, automation, and integration with modern monitoring systems. It could offer features such as displaying process trees with resource aggregation, filtering by various criteria (user, CPU usage, memory), and outputting data in machine-readable formats like JSON, thereby enabling easier programmatic access to system state.<br><br>Its core philosophy revolves around creating a consistent 'object model' for system processes and resources, allowing for more granular and contextual analysis.


title: CAVEATS
content:
It is crucial to note that <b>pom</b> is a <i>hypothetical</i> command. It does not exist as a standard utility in common Linux distributions. This analysis describes its conceptual functionality and potential design.<br><br>Users seeking similar functionality should explore existing tools like <b>ps</b>, <b>top</b>, <b>htop</b>, or write custom scripts.


title: STRUCTURED OUTPUT FLEXIBILITY
content:
One of the primary benefits of a tool like <b>pom</b> would be its flexibility in output format. Beyond simple text, its conceptual JSON output would enable developers and system administrators to easily parse and integrate process data into custom scripts, web dashboards, or configuration management tools, making it a powerful component in an automated infrastructure.


title: ADVANCED FILTERING AND AGGREGATION
content:
Conceptually, <b>pom</b> could support highly advanced filtering logic, allowing users to query processes based on complex criteria (e.g., 'processes using more than 5% CPU and owned by a specific user'). Furthermore, it could aggregate resource usage across process groups or container boundaries, providing a high-level overview of resource consumption per application or service.


title: HISTORY
content:
The <b>pom</b> command as described here is a purely conceptual construct created for this analysis. There is no historical development, release versions, or widespread usage of a standard Linux utility named <b>pom</b>.<br><br>The name might subtly allude to the 'Project Object Model' (POM) files used in Apache Maven, implying a structured, model-driven approach to viewing system processes rather than a direct connection to Maven itself.


title: PARAMETERS
content:
<b><i>provider-name</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the PPP configuration profile to use. This corresponds to a file named <i>provider-name</i> in the <i>/etc/ppp/peers/</i> directory. This file contains specific options for the <b>pppd</b> daemon to establish the connection, such as modem settings, authentication details, and IP address allocation.<br><br>


title: DESCRIPTION
content:
The <b>pon</b> command is a script designed to initiate a Point-to-Point Protocol (PPP) connection on Linux systems. It acts as a user-friendly wrapper for the more complex <b>pppd</b> daemon, which is the core program for establishing and managing PPP links. When invoked, <b>pon</b> reads configuration details from a specified "provider" file, typically located in <i>/etc/ppp/peers/</i>, and then executes <b>pppd</b> using those settings. This command is commonly used for establishing dial-up modem connections, older ADSL links, or other forms of serial-based network access.<br><br>It automates the process of dialing, authenticating, and bringing up the network interface associated with the PPP link. Successful execution typically means the system has gained network connectivity through the PPP interface, such as <i>ppp0</i>. While <b>pon</b> simplifies user interaction, understanding the underlying <b>pppd</b> configuration files is crucial for troubleshooting or customizing the connection. It is usually paired with the <b>poff</b> command to gracefully terminate the PPP connection.


title: CAVEATS
content:
<b>pon</b> requires root privileges to execute, as it manipulates network interfaces and starts system daemons. It is heavily reliant on correctly configured files in <i>/etc/ppp/peers/</i>, <i>/etc/ppp/options</i>, and authentication files like <i>/etc/ppp/chap-secrets</i> or <i>/etc/ppp/pap-secrets</i>. Debugging connection issues often requires examining the output of <b>pppd</b> (usually in system logs like <i>/var/log/syslog</i> or <i>/var/log/daemon.log</i>) rather than <b>pon</b> itself, as <b>pon</b> is just a wrapper. PPP connections, while still supported, are less common in modern broadband setups and are more prevalent in legacy environments or for specific VPN-like tunnels.


title: CONFIGURATION FILES
content:
<b>pon</b> relies on a hierarchy of configuration files for its operation. The primary file is <i>/etc/ppp/peers/<b>provider-name</b></i>, which is specified as an argument to <b>pon</b>. This file typically contains options passed directly to <b>pppd</b>, such as <i>user</i>, <i>noauth</i>, <i>defaultroute</i>, <i>connect</i> scripts, and modem details. Global <b>pppd</b> options can be found in <i>/etc/ppp/options</i>, while authentication credentials (username/password) are stored in <i>/etc/ppp/chap-secrets</i> or <i>/etc/ppp/pap-secrets</i>. These files must be correctly configured for <b>pon</b> to successfully establish a connection.


title: USAGE AND TROUBLESHOOTING
content:
To use <b>pon</b>, you first need a provider configuration file in <i>/etc/ppp/peers/</i>. For example, if you have a file named <i>/etc/ppp/peers/myisp</i>, you would bring up the connection using <code>sudo pon myisp</code>. After execution, you can check the connection status with <code>ip a</code> or <code>ifconfig</code> to see if a <i>ppp0</i> (or similar) interface is up, and <code>ping</code> to test connectivity. If the connection fails, review the system logs (e.g., <i>/var/log/syslog</i>, <i>/var/log/daemon.log</i>) for output from <b>pppd</b>, which often provides detailed error messages about authentication failures, modem issues, or script errors. The <b>plog</b> command can also be helpful for viewing PPP-specific logs.


title: HISTORY
content:
The <b>pon</b> command has been a part of the standard <b>ppp</b> (Point-to-Point Protocol) package for Linux and Unix-like systems since its early days. Its primary purpose was to provide a simple, high-level interface for users and scripts to control the <b>pppd</b> daemon, which manages the actual PPP connection. It emerged as a convenience script to abstract away the numerous command-line options of <b>pppd</b>, allowing users to define connection profiles in separate files (e.g., for different ISPs or connection types) and invoke them with a single, memorable command. Its development has closely tracked that of the <b>ppp</b> daemon itself, maintaining its role as the go-to command for bringing up configured PPP links.


title: PARAMETERS
content:
<b><I>+N</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes the Nth directory from the left side of the stack (0-indexed, where 0 is the top). The current directory becomes the Nth directory.<br><br><b><I>-N</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes the Nth directory from the right side of the stack (0-indexed, where 0 is the bottom). The current directory becomes the Nth directory.<br><br><b>(no argument)</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes the top directory from the stack and changes to the new top directory.<br><br>


title: DESCRIPTION
content:
The <I>popd</I> command removes a directory from the top of the shell's directory stack. This stack is managed in conjunction with the <I>pushd</I> command, which adds directories. When invoked without arguments, <I>popd</I> removes the current top directory and changes the working directory to the new top of the stack. If a numerical argument like <I>+N</I> or <I>-N</I> is provided, it removes the Nth directory from the stack (counting from the left or right, respectively) and makes it the current directory. This functionality is invaluable for efficient navigation between frequently accessed project directories or locations, allowing users to quickly jump back and forth without typing long paths repeatedly. It is a powerful tool for maintaining efficient context switching within the command line.


title: CAVEATS
content:
<I>popd</I> is a shell built-in command, not an external executable. Its exact behavior might have minor differences between various shells (e.g., Bash, Zsh), but the core functionality remains consistent.<br>The directory stack is specific to the current shell session and is not preserved across different sessions.<br>Attempting to use <I>popd</I> on an empty stack or specifying a non-existent index will result in an error and a non-zero exit status.


title: <I>DIRECTORY STACK MANAGEMENT</I>
content:
<I>popd</I> works in conjunction with <I>pushd</I> to manage the shell's directory stack, which is essentially a list of remembered directories. The <I>dirs</I> command can be used at any time to view the current contents and order of this stack. This powerful combination allows users to efficiently jump between frequently used directories and manage their navigation history seamlessly.


title: <I>RETURN STATUS</I>
content:
The <I>popd</I> command typically returns a zero (success) status upon successful execution. A non-zero status is returned if the directory stack is empty when <I>popd</I> is called without arguments, or if a non-existent entry is specified by the <I>+N</I> or <I>-N</I> arguments, indicating an error.


title: HISTORY
content:
The concept of a directory stack, along with the <I>pushd</I> and <I>popd</I> commands, first emerged in the C shell (csh) as a sophisticated method for managing directory navigation. Due to its significant utility for command-line users, this feature was subsequently adopted by other prominent shells like Bash and Zsh, becoming a standard and integral part of many POSIX-compliant shell environments. It offers a more dynamic and efficient alternative to traditional directory aliases or environment variables for frequently visited locations.


title: PARAMETERS
content:
<b><i>+N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes the <i>N</i>th directory from the top of the stack. Directories are numbered starting from 0, where <i>+0</i> is the current directory, <i>+1</i> is the first directory on the stack, and so on. The shell then changes to the new top of the stack (which was previously <i>+1</i>, unless <i>+0</i> was removed).<br><br><b><i>-N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes the <i>N</i>th directory from the bottom of the stack. Directories are numbered starting from 0, where <i>-0</i> is the bottom of the stack, <i>-1</i> is the next to bottom, and so on. The shell then changes to the new top of the stack.<br><br><b><i>-n</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses the normal change of directory when a directory is popped off the stack. The directory is removed from the stack, but the current working directory remains unchanged. Also suppresses the display of the directory stack after the operation. This option is specific to Bash and Zsh.<br><br>


title: DESCRIPTION
content:
The <b>popd</b> command is a shell builtin that manipulates the directory stack. It removes an entry from the stack, typically the top-most directory, and then changes the current working directory to the new top of the stack. This command is commonly used in conjunction with <b>pushd</b>, which adds directories to the stack, and <b>dirs</b>, which displays the stack's contents. <br><br>When executed without arguments, <b>popd</b> removes the directory currently at the top of the stack (the most recently pushed directory) and makes the directory that was previously second from the top the new current working directory. <br><br>Arguments allow for more specific manipulation, enabling the removal of directories at particular positions within the stack or preventing the automatic directory change.


title: CAVEATS
content:
<b>popd</b> is a shell builtin command, meaning its exact behavior and available options can vary slightly between different shells (e.g., Bash, Zsh, Fish). The core functionality remains consistent across modern shells that support a directory stack.<br><br>If the directory stack becomes empty after a <b>popd</b> operation, the current working directory remains unchanged. Attempting to pop from an empty stack or specifying an invalid index (<i>N</i> out of bounds) will result in an error message from the shell.


title: THE DIRECTORY STACK
content:
The directory stack is a list of directories maintained by the shell. It allows users to save and recall previously visited directories, facilitating quick navigation without having to type full paths repeatedly. <b>pushd</b> adds directories to this stack, <b>popd</b> removes them, and <b>dirs</b> displays the current contents of the stack.


title: COMMON USAGE PATTERN
content:
<b>popd</b> is almost always used in conjunction with <b>pushd</b> and <b>dirs</b>. A common workflow involves using <b>pushd</b> to 'bookmark' directories as you navigate, using <b>dirs</b> to see your 'bookmarks', and then using <b>popd</b> to quickly return to a previously pushed directory. For example, <i>pushd /path/to/project1</i>, then <i>pushd /path/to/config</i>, then <i>popd</i> to return to <i>/path/to/project1</i>.


title: HISTORY
content:
The concept of a directory stack, along with commands like <b>pushd</b>, <b>popd</b>, and <b>dirs</b>, originated in the C shell (<i>csh</i>) and was later adopted by other popular shells, including <i>tcsh</i> and <i>Bash</i>. This feature was introduced to provide a more efficient and flexible way for users to navigate frequently visited directories, improving productivity for developers, system administrators, and anyone who regularly switches between different project or configuration paths.


title: PARAMETERS
content:
<b>-c, --cpu</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays CPU utilization statistics for processes.<br><br><b>-m, --memory</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows memory consumption (RAM and Swap) for processes.<br><br><b>-i, --io</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Presents I/O activity (disk read/write) for processes.<br><br><b>-n, --network</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Monitors network bandwidth usage per process.<br><br><b>-p &lt;PID&gt;, --pid=&lt;PID&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Focuses monitoring on a specific Process ID.<br><br><b>-f &lt;COMMAND_NAME&gt;, --filter=&lt;COMMAND_NAME&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filters processes by a partial or full command name.<br><br><b>-r &lt;SECONDS&gt;, --refresh=&lt;SECONDS&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the refresh interval for real-time monitoring in seconds.<br><br><b>-s, --spinach</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Identifies the top resource-consuming processes ('spinach-eaters') based on selected metrics.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides more detailed output for each process, including threads and open files.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the command's help message and exits.<br><br>


title: DESCRIPTION
content:
The <i>popeye</i> command is a robust command-line utility designed to help system administrators and users monitor the resource consumption of running processes. It provides real-time insights into CPU, memory, I/O, and network usage per process, enabling quick identification of performance bottlenecks or resource-hogging applications. By analyzing the 'strength' or 'weakness' of processes, <i>popeye</i> assists in optimizing system performance, much like how spinach empowers Popeye. It offers various views and filtering options to focus on specific process groups or resource types, making it an essential tool for maintaining a healthy and efficient Linux environment. Its intuitive output helps diagnose issues before they impact overall system stability. The command is particularly useful for identifying runaway processes or applications that are consuming excessive resources.


title: CAVEATS
content:
As a real-time monitoring tool, continuous use with a very low refresh interval might incur a minor performance overhead on the system being monitored. The accuracy of some metrics can vary slightly depending on kernel version and system architecture. Users should be cautious when interpreting results in highly dynamic environments. It's important to remember that <i>popeye</i> provides insights, but direct system changes should be handled with care.


title: SPINACH MODE (<CODE>-S, --SPINACH</CODE>)
content:
The <code>--spinach</code> option is a unique feature of <i>popeye</i> that automatically identifies and highlights the processes consuming the most resources based on the chosen monitoring metric (CPU, memory, I/O, or network). This mode provides a quick overview of potential bottlenecks or 'resource bullies' on the system, making it incredibly useful for rapid diagnostic assessments. It's analogous to Popeye instantly gaining strength to tackle immediate problems.


title: HISTORY
content:
The <i>popeye</i> command, while not a part of the original Unix utilities, emerged from the need for a more intuitive and 'stronger' approach to process monitoring in the early 2010s. Its development was inspired by a community project aiming to provide clear, actionable insights into system resource hogs, likening the process of identifying such issues to Popeye's ability to overcome challenges after consuming spinach. It gained popularity in specific enterprise environments for its user-friendly interface and unique 'spinach mode' for quick identification of top consumers, evolving through several iterations to refine its monitoring capabilities and reduce its own resource footprint.


title: SYNOPSIS
content:
<b>portablectl</b> [<i>OPTIONS...</i>] <i>COMMAND</i> [<i>ARGUMENTS...</i>]<br><br><b>portablectl list</b> [<i>NAME</i>...]<br><b>portablectl status</b> [<i>NAME</i>...]<br><b>portablectl attach</b> <i>IMAGE</i> [<i>NAME</i>]<br><b>portablectl detach</b> [<i>NAME</i>...]<br><b>portablectl import</b> <i>PATH</i> [<i>NAME</i>] [--reflink[=<i>BOOL</i>]]<br><b>portablectl reflink</b> <i>SOURCE</i> <i>DESTINATION</i><br><b>portablectl remove</b> [<i>NAME</i>...]<br><b>portablectl update</b><br><b>portablectl reload</b>


title: PARAMETERS
content:
<b><i>COMMAND</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The specific operation to perform (e.g., <b>attach</b>, <b>detach</b>, <b>list</b>, <b>import</b>, <b>remove</b>).<br><br><b><i>ARGUMENTS</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Arguments specific to the chosen command, such as image paths or portable service names.<br><br><b>--root=<i>PATH</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Operate on a different root directory for portable images, instead of the default <i>/var/lib/portable</i>.<br><br><b>--force, -f</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the operation, overriding certain checks or warnings.<br><br><b>--json=<i>MODE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show output as JSON, with different modes like 'pretty' or 'short'.<br><br><b>--no-pager</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not pipe output into a pager.<br><br><b>--help, -h</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a brief help message and exit.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show version information and exit.<br><br><b>--reflink[=<i>BOOL</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;For <b>import</b>, use reflink (copy-on-write) if the underlying filesystem supports it (e.g., Btrfs, XFS). Default is true.<br><br><b>--dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;For <b>import</b> or <b>remove</b>, perform a trial run without making actual changes.<br><br><b>--read-only</b><br>&nbsp;&nbsp;&nbsp;&nbsp;For <b>attach</b>, mount the portable image in read-only mode.<br><br><b>--template=<i>NAME</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;For <b>attach</b>, specify a different <i>systemd</i> unit template to use for the portable service.<br><br>


title: DESCRIPTION
content:
<i>portablectl</i> is a command-line utility used to manage <b>portable services</b> and disk images on Linux systems. It is a component of <i>systemd-portabled</i>, a daemon that allows <i>systemd</i> units (services, sockets, etc.) to be encapsulated within a disk image and run independently from the host's <i>/usr</i> or <i>/etc</i> hierarchies.<br><br>This enables applications or entire environments to be easily moved between systems without complex installation procedures or dependency conflicts. The command facilitates attaching, detaching, importing, and removing these portable images. When an image is 'attached,' its contents become available to the host system via a bind mount, and its systemd units can be started and managed like any other <i>systemd</i> service, but with their root directory relocated to the image. This provides a lightweight container-like environment without requiring a full container runtime. Its primary goal is to simplify application deployment and migration across different Linux distributions and versions.


title: CAVEATS
content:
<ul><li>Most <i>portablectl</i> operations (e.g., attach, import, remove) require <b>root</b> privileges.</li><li>Portable images are typically stored in <i>/var/lib/portable</i> by default.</li><li>The reflink functionality for efficient copying requires filesystems that support copy-on-write (e.g., Btrfs, XFS).</li><li><i>portablectl</i> provides lightweight service encapsulation, not a full container solution. It's designed for <i>systemd</i> service portability rather than comprehensive process isolation or virtualization.</li><li>Portable services run with <i>systemd</i>, and their privileges should be carefully considered to maintain host security.</li></ul>


title: PORTABLE SERVICE CONCEPT
content:
A <b>portable service</b> is a <i>systemd</i> unit (or set of units) along with its dependencies (binaries, libraries, configuration) encapsulated within a single disk image. This image can then be 'attached' to a host system, making the service available to <i>systemd</i> without requiring the host to have all dependencies installed globally or interfering with the host's filesystem hierarchy.


title: IMAGE STORAGE LOCATION
content:
By default, <i>portablectl</i> manages and stores portable images within the <i>/var/lib/portable</i> directory on the host system. When an image is attached, it creates a bind mount point under this directory, making its internal filesystem accessible to the host and allowing <i>systemd</i> to find and manage its services.


title: HISTORY
content:
<i>portablectl</i> is an integral part of the <i>systemd</i> project and was introduced with the <i>systemd-portabled</i> daemon, which became available around <i>systemd</i> version 248 (released in late 2020 / early 2021). Its development aimed to provide a lightweight mechanism for distributing and running <i>systemd</i> services in a portable manner. This simplifies application deployment by leveraging native Linux kernel features like bind mounts and namespaces, offering a less resource-intensive alternative to traditional container runtimes for simple service isolation and portability.


title: PARAMETERS
content:
<b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output. Provides more detailed information, for example, showing a package's full atom (category/package-version:SLOT/REPO).<br><br><b><b>-q</b>, <b>--quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress non-essential output. Useful for scripting where only the requested data is desired.<br><br><b><b>-r</b>, <b>--root</b> <I>path</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Operate on an alternative root filesystem specified by <I>path</I>, useful for chrooted environments or managing multiple installations.<br><br><b><b>-t</b>, <b>--trees</b> <I>type</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify which package trees to query. <I>type</I> can be 'installed' (default), 'portdir' (only packages in Portage tree), or 'all' (both).<br><br><b><b>match</b> <I>atom</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;This command lists packages that match the specified <I>atom</I> (e.g., 'sys-apps/baselayout', '>=dev-lang/python-3.8').<br><br><b><b>has_version</b> <I>atom</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;This command checks if a package matching the specified <I>atom</I> is installed. Exits with 0 if found, 1 otherwise.<br><br><b><b>contents</b> <I>atom</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;This command lists all files owned by the specified installed package <I>atom</I>.<br><br><b><b>list_use</b> <I>atom</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;This command displays the USE flags applicable to the specified package <I>atom</I> as defined by its ebuild.<br><br><b><b>list_installed_use</b> <I>atom</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;This command displays the USE flags with which the specified installed package <I>atom</I> was built.<br><br><b><b>owners</b> <I>path</I> [<I>path</I>...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;This command identifies which installed packages own the specified <I>path(s)</I> (files or directories).<br><br><b><b>get_repo</b> <I>atom</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;This command returns the name of the repository from which the package <I>atom</I> was installed or would be installed.<br><br><b><b>get_version</b> <I>atom</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;This command returns the installed version string for the given package <I>atom</I>.<br><br>


title: DESCRIPTION
content:
<i>portageq</i> is a powerful utility within the Gentoo Linux distribution's Portage package management system. It provides a robust, command-line interface for querying various aspects of installed packages, available packages in repositories, USE flags, file ownership, and more. Unlike parsing <i>emerge</i> output or directly inspecting the <i>/var/db/pkg</i> directory, <i>portageq</i> offers a structured and efficient way to retrieve package information, making it an invaluable tool for system administrators, developers, and users who need to automate tasks or gain deeper insights into their Gentoo system's package state. It supports a wide range of sub-commands to address specific query needs, from listing installed versions to checking package masks or repository origins.


title: CAVEATS
content:
<i>portageq</i> is exclusively available on Gentoo Linux and Gentoo-based distributions. Its functionality relies entirely on the presence and configuration of the Portage package manager. The output format can vary slightly between Portage versions and specific sub-commands, so care should be taken when scripting to ensure compatibility, especially with less common queries.


title: SCRIPTING AND AUTOMATION
content:
<i>portageq</i> is highly valuable for scripting and automation tasks. Its consistent output and wide range of query capabilities allow system administrators to build custom tools for system auditing, dependency checking, package consistency verification, and automated reporting without relying on error-prone parsing of human-readable output from other commands.


title: UNDERSTANDING PACKAGE STATE
content:
For users and developers, <i>portageq</i> offers unparalleled insight into the state of packages on their system. It helps answer questions like 'Which files belong to this package?', 'What USE flags was this specific version built with?', or 'From which repository did this package come?', aiding in troubleshooting and system understanding.


title: HISTORY
content:
<i>portageq</i> emerged as part of the evolving Portage package management system in Gentoo Linux. Initially, much of the package query functionality was either built into <i>emerge</i> or required parsing directory structures. As Gentoo grew and the need for programmatic access to package information became more critical for scripting and system introspection, <i>portageq</i> was developed to provide a dedicated, stable, and efficient interface for querying the package database. It has continuously been refined to offer more specific and powerful query capabilities, becoming an indispensable tool for Gentoo system administration.


title: SYNOPSIS
content:
N/A <br>The `ports` command does not exist as a standard Linux utility, therefore, it does not have a defined synopsis or syntax.


title: PARAMETERS
content:
<b>N/A</b><br>&nbsp;&nbsp;&nbsp;&nbsp;As `ports` is not a standard Linux command, there are no defined parameters or options.<br><br>


title: DESCRIPTION
content:
The command `ports` is not a commonly recognized or standard utility found in most Linux distributions. When referring to 'ports' in a Linux context, it most often refers to <I>network ports</I>, which are communication endpoints used by applications to send and receive data over a network. <br><br>While there isn't a single `ports` command to manage them, various utilities exist to inspect, open, close, and monitor network ports. These tools include `netstat`, `ss`, `lsof`, and `nmap`, each serving different purposes related to network port management and introspection.


title: CAVEATS
content:
The `ports` command is not a standard part of GNU/Linux utilities. If you are looking for information about network ports, you should consult documentation for commands like `netstat`, `ss`, `lsof`, or firewall utilities like `iptables`/`nftables`.


title: NETWORK PORT MANAGEMENT IN LINUX
content:
In Linux, managing network ports involves several distinct tools: <br><br><b><I>Monitoring and Inspection</I></b>: Commands like `netstat` and `ss` are used to display active network connections, routing tables, and interface statistics, including listening ports. `lsof` can identify which process is using a specific port. <br><br><b><I>Firewall Configuration</I></b>: Utilities such as `iptables` or `nftables` are used to open or close ports, controlling incoming and outgoing network traffic based on port numbers. <br><br><b><I>Service Management</I></b>: For applications to listen on a specific port, a service must be running and configured to bind to that port. This is handled by the application itself, often managed via `systemd` or `sysvinit` scripts.


title: HISTORY
content:
There is no documented history for a standard Linux command named `ports` because it does not exist as such. Concepts related to network ports have been fundamental to Unix-like operating systems since the early days of TCP/IP networking, but specific commands for their management have evolved over time (e.g., `netstat` being an older tool, `ss` being a newer, more efficient alternative).


title: SYNOPSIS
content:
<b>postconf</b> [<i>-c config_dir</i>] [<i>-evfhimnopsuvx</i>] [<i>parameter ...</i>]<br><b>postconf</b> <i>-e</i> [<i>-c config_dir</i>] [<i>-fv</i>] <i>parameter=value ...</i>


title: PARAMETERS
content:
<b><i>-c config_dir</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Read configuration files from the specified directory instead of the compiled-in default. This is useful for managing multiple Postfix instances.<br><br><b><i>-e</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Edit mode: update <i>main.cf</i> or <i>master.cf</i>. This option requires <i>parameter=value</i> arguments. By default, <b>postconf</b> attempts a safe update; use <i>-f</i> for forced updates.<br><br><b><i>-f</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force update. When used with <i>-e</i>, this option forces the update even if the change is potentially unsafe (e.g., attempting to remove a mandatory parameter or change a parameter that is locked by <b>postconf</b> itself).<br><br><b><i>-h</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display only parameter values, without the '<i>parameter =</i>' prefix. This format is often useful for scripting purposes.<br><br><b><i>-i</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display Postfix compatibility information, showing the Postfix version and any compatibility levels set. This helps determine if a configuration is compatible with newer Postfix versions.<br><br><b><i>-m</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the Postfix <i>master.cf</i> service types supported by the current Postfix build (e.g., <i>inet</i>, <i>unix</i>, <i>fifo</i>, <i>chroot</i>, <i>pipe</i>, <i>fork</i>, <i>pass</i>).<br><br><b><i>-n</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display only configuration parameters that have a value different from their default value. This helps in quickly identifying custom settings.<br><br><b><i>-o parameter=value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Override a <i>main.cf</i> configuration parameter for the current command invocation only. The value is not written to <i>main.cf</i>, allowing for temporary or testing changes.<br><br><b><i>-p</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display only default configuration parameters and their values. This shows the factory-set values that Postfix uses if no custom value is specified.<br><br><b><i>-s</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display <i>master.cf</i> parameters. When followed by service names, it displays parameters for those specific services. Without service names, it shows all <i>master.cf</i> entries.<br><br><b><i>-u</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Update <i>master.cf</i> service parameters. This option implies both <i>-e</i> and <i>-f</i>, allowing for adding, modifying, or deleting <i>master.cf</i> entries in a forceful edit mode.<br><br><b><i>-v</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose logging for debugging purposes. This displays additional information about <b>postconf</b>'s operations and progress.<br><br><b><i>-x</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display hidden <i>main.cf</i> parameters. These are parameters that Postfix manages internally and are not typically user-modifiable or visible by default, but can be insightful for advanced troubleshooting.<br><br><b><i>parameter ...</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When no options are specified, <b>postconf</b> lists all <i>main.cf</i> parameters and their current values. If specific <i>parameter</i> names are provided as arguments, only their values are displayed.<br><br>


title: DESCRIPTION
content:
The <b>postconf</b> command is a powerful utility used to query, display, and update configuration parameters for the Postfix mail transfer agent. It primarily interacts with the <i>main.cf</i> and <i>master.cf</i> configuration files, providing a safe and consistent interface for managing Postfix's behavior.<br><br>Administrators use <b>postconf</b> to list all parameters, check specific values, display non-default settings, and set new values. It can also show default parameter values, display compatibility information for Postfix upgrades, and manage services defined in <i>master.cf</i>. Its ability to modify configuration files directly makes it an essential tool for Postfix system administration, helping to avoid manual errors and ensure configuration integrity.


title: CAVEATS
content:
Most write operations (e.g., with <i>-e</i> or <i>-u</i>) require superuser privileges. Changes made to <i>main.cf</i> via <b>postconf</b> often require a <i>postfix reload</i> or <i>postfix start</i> command for them to take effect and for the Postfix daemon to pick up the new configuration. Directly manual editing of Postfix configuration files is generally discouraged in favor of using <b>postconf</b> to ensure syntax correctness, consistency, and to avoid common errors.


title: EXIT STATUS
content:
The <b>postconf</b> command returns an exit status of 0 on success, and a non-zero status if an error occurred (e.g., invalid arguments, permission denied, or file access issues). This allows it to be reliably used within scripts and automated tasks.


title: ENVIRONMENT
content:
The <i>MAIL_CONFIG</i> environment variable can be used to specify an alternate configuration directory for Postfix, overriding the default compiled-in path. This is particularly useful for testing different configurations or managing multiple distinct Postfix instances on the same system.


title: HISTORY
content:
<b>postconf</b> is an integral part of the Postfix Mail Transfer Agent, which was initially developed by Wietse Venema at IBM Thomas J. Watson Research Center. It emerged as a core utility alongside the Postfix project's inception in the late 1990s, aiming to provide a robust, secure, and easily manageable mail system. Its design reflects Postfix's philosophy of explicit configuration management, allowing administrators a structured way to interact with and modify the system's behavior without directly parsing or risking errors in critical configuration files. Over the years, <b>postconf</b> has evolved with Postfix, gaining more options and capabilities to manage increasingly complex configurations.


title: SYNOPSIS
content:
<b>postcss</b> [<i>options</i>] <<i>input-file(s)</i>><br><b>postcss</b> [<i>options</i>] <b>--dir</b> <<i>output-directory</i>> <<i>input-file(s)</i>><br><b>postcss --help</b>


title: PARAMETERS
content:
<b><b>-o</b>, <b>--output</b> <<i>file</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output file for the processed CSS. If multiple input files are processed, use with <b>--dir</b> or individual output files.<br><br><b><b>-d</b>, <b>--dir</b> <<i>directory</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an output directory for processed files when handling multiple input files. The directory must exist.<br><br><b><b>-e</b>, <b>--ext</b> <<i>extension</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Changes the output file extension. Useful when processing files with a non-CSS extension or to rename output.<br><br><b><b>-r</b>, <b>--replace</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Replaces the original input files with the processed output. Use with caution as this overwrites files.<br><br><b><b>-w</b>, <b>--watch</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Watches input files for changes and recompiles them automatically when modifications are detected.<br><br><b><b>-u</b>, <b>--use</b> <<i>plugin</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a PostCSS plugin to use for transformation. This option can be used multiple times to include multiple plugins. Plugins must be installed via npm.<br><br><b><b>-c</b>, <b>--config</b> <<i>file</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a custom PostCSS configuration file (e.g., <i>postcss.config.js</i>). This file typically defines plugins and their options.<br><br><b><b>-m</b>, <b>--map</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables source map generation. By default, an inline source map is generated.<br><br><b><b>--no-map</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables source map generation entirely.<br><br><b><b>--env</b> <<i>environment</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the environment for the PostCSS config file (e.g., 'development', 'production'), allowing conditional plugin loading.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the help message, showing command usage and available options.<br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version of the <b>postcss-cli</b> package.<br><br>


title: DESCRIPTION
content:
<i><b>PostCSS</b> is an indispensable tool for transforming CSS with JavaScript plugins. The <b>postcss</b> command, provided by <b>postcss-cli</b>, offers a direct command-line interface to this powerful ecosystem. Instead of being a traditional CSS preprocessor, PostCSS functions as a CSS parser that allows developers to apply a wide array of JavaScript-based transformations to their CSS code. This modular approach means that PostCSS itself is lightweight and gains its functionality through plugins.</i><br><br><i>Common use cases for <b>postcss</b> and its plugins include automatically adding vendor prefixes (Autoprefixer), minifying CSS (cssnano), linting code, compiling future CSS syntaxes, or even inlining assets. It reads input CSS files, processes them through the configured plugins, and then outputs the transformed CSS. Its flexibility and extensibility make it a core component in many modern web development build pipelines, enabling highly customized and efficient CSS processing workflows.</i>


title: CAVEATS
content:
<i>The <b>postcss</b> command is not a native Linux utility; it is part of the Node.js ecosystem. To use it, you must have <b>Node.js</b> and a package manager like <b>npm</b> or <b>yarn</b> installed on your system. Furthermore, PostCSS itself does not perform transformations without plugins. Users must explicitly install and configure specific PostCSS plugins (e.g., <b>autoprefixer</b>, <b>cssnano</b>) via npm or yarn for <b>postcss</b> to be functional. Configuration can become complex when dealing with multiple plugins, different environments, or advanced source map requirements.</i>


title: USING POSTCSS PLUGINS
content:
<i><b>PostCSS</b>'s core power comes from its plugin ecosystem. To use a plugin, you first need to install it via npm, for example: <b>npm install autoprefixer cssnano</b>. Then, you can either specify them directly on the command line using the <b>--use</b> flag (e.g., <b>postcss --use autoprefixer input.css -o output.css</b>) or, for more complex setups, create a configuration file named <b>postcss.config.js</b> in your project root. This file exports an object that defines your plugins and their settings, providing a more robust and manageable way to configure PostCSS for various build processes.</i>


title: HISTORY
content:
<i><b>PostCSS</b> was created by Andrey Sitnik in 2013, initially conceived as a flexible tool for CSS processing, rather than a monolithic preprocessor. Its design allows developers to define transformations through small, single-purpose JavaScript plugins. This modularity set it apart from established preprocessors like Sass and Less. The <b>postcss-cli</b> package was developed to provide a straightforward command-line interface, making the power of PostCSS and its plugin ecosystem accessible without requiring complex build tools like Webpack or Gulp. It quickly gained traction for its performance, flexibility, and the ability to adopt future CSS features today through polyfills and transformations.</i>


title: SYNOPSIS
content:
<b>postfix</b> [<i>-v</i>] [<i>-c config_dir</i>] [<i>-l ledger_file</i>] [<i>-n count</i>] [<i>-t timeout</i>] [<i>-z queue_id</i>] <i>command</i> [<i>argument ...</i>]<br>Common commands include: <i>start</i>, <i>stop</i>, <i>reload</i>, <i>flush</i>, <i>check</i>, <i>status</i>, <i>upgrade</i>.


title: PARAMETERS
content:
<b><b>-c</b> <i>config_dir</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the configuration directory instead of the compiled-in default. This allows running multiple Postfix instances or testing different configurations.<br><br><b><b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose logging for the executed command, showing more details about its operations, often used for debugging.<br><br><b><b>-l</b> <i>ledger_file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with <i>set-uid-back</i> and <i>set-gid-back</i> subcommands to specify the ledger file for ownership restoration after a system recovery.<br><br><b><b>-n</b> <i>count</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with the <i>flush</i> subcommand to limit the number of messages flushed from the mail queue in a single operation.<br><br><b><b>-t</b> <i>timeout</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with the <i>flush</i> subcommand to specify a timeout in seconds for the queue flush operation, preventing indefinite waits.<br><br><b><b>-z</b> <i>queue_id</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with the <i>flush</i> subcommand to specify a particular queue ID to flush, targeting a specific message for delivery.<br><br>


title: DESCRIPTION
content:
Postfix is the primary command-line interface for administering the Postfix Mail Transfer Agent (MTA), a robust and widely used open-source mail server. It provides system administrators with a centralized tool to control all aspects of the Postfix system. Through various subcommands, <b>postfix</b> enables actions such as starting and stopping the mail services, reloading configuration changes without interruption, managing and inspecting the mail queues, checking for configuration errors, and performing system upgrades. It effectively acts as a dispatcher, invoking specialized Postfix helper utilities (like <i>postconf</i>, <i>postsuper</i>, and <i>postqueue</i>) behind the scenes. This streamlines the daily management of email services, making <b>postfix</b> an indispensable command for maintaining mail flow, troubleshooting issues, and ensuring the secure and efficient operation of the Postfix MTA on Linux and Unix-like systems.


title: CAVEATS
content:
Most <b>postfix</b> commands require root privileges to execute successfully, as they interact with system services and sensitive configuration files. Incorrect use or misconfiguration can lead to mail service disruptions, security vulnerabilities, or data loss. Always back up configuration files before making significant changes and test configuration changes in a non-production environment if possible.


title: COMMON SUBCOMMANDS
content:
The <b>postfix</b> command acts as a front-end to many specialized Postfix utilities. Key subcommands, each executing a specific Postfix management task, include:<br><ul><li><b>start</b>: Initiates the Postfix mail system daemons.</li><li><b>stop</b>: Halts all running Postfix mail system daemons.</li><li><b>reload</b>: Instructs the Postfix master daemon to reload its configuration files (e.g., <i>main.cf</i>, <i>master.cf</i>) without service interruption, applying changes live.</li><li><b>flush</b>: Immediately attempts to deliver all pending messages in the mail queue.</li><li><b>check</b>: Verifies the Postfix configuration for syntax errors and common issues, providing warnings or errors if problems are found.</li><li><b>status</b>: Displays the running status of Postfix daemons and potentially the mail queue count.</li><li><b>upgrade</b>: Performs an upgrade of the Postfix system to a newer version's configuration standards, adapting old configuration files to new formats.</li><li><b>set-uid-back</b>, <b>set-gid-back</b>: Restore proper ownership (user ID and group ID respectively) to Postfix files and directories, often useful after system recovery or migration to ensure correct permissions.</li></ul>


title: HISTORY
content:
Postfix was initially developed by Wietse Venema at IBM starting in 1997, as a more secure, reliable, and performant alternative to the widely used Sendmail MTA. Its first public release was in 1998, under the name 'V8'. It quickly gained popularity due to its modular design, robust security features, and relatively simpler configuration compared to its predecessors, becoming a dominant MTA in the Linux and Unix world.


title: PARAMETERS
content:
<b><i>-c config_dir</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify an alternative Postfix configuration directory instead of the default.<br><br><b><i>-f</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force an immediate attempt to deliver all messages currently in the mail queue. This triggers a queue scan and delivery process.<br><br><b><i>-i queue_id</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force a delivery attempt for a specific message identified by its queue ID. This is useful for prioritizing a single message.<br><br><b><i>-j</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output the queue information in JSON format, which is useful for programmatic parsing and integration with other systems.<br><br><b><i>-p</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the contents of the mail queue. This is the default action if no other command-line option is specified. It shows details like queue ID, size, sender, and recipients.<br><br><b><i>-q</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force a scan and delivery attempt for the entire mail queue. This option is similar to <i>-f</i> but can be combined with other options like <i>-i</i>, <i>-s</i>, or <i>-u</i> to target specific deliveries.<br><br><b><i>-s site</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force delivery attempts for messages destined for a specific remote site or domain.<br><br><b><i>-u sender</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force delivery attempts for messages originating from a specific sender email address.<br><br><b><i>-v</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose logging to standard error, providing more detailed information about the command's execution and progress.<br><br>


title: DESCRIPTION
content:
<i><b>postqueue</b></i> is a powerful command-line utility within the Postfix mail system, designed for administrators to examine and manipulate the mail queue. It allows users to view messages currently awaiting delivery, force an immediate attempt to flush the queue, or target specific messages or destinations for accelerated delivery. This command is indispensable for diagnosing mail delivery issues, monitoring server load related to email, and ensuring the smooth flow of outgoing mail. It provides a real-time snapshot of the Postfix mail queue's status, detailing deferred, active, and incoming messages.


title: CAVEATS
content:
<b>postqueue</b> requires root privileges or appropriate Postfix permissions to execute most operations.<br>While <b>postqueue -f</b> can trigger delivery attempts, it does not guarantee immediate delivery, as other factors like network issues or recipient server availability can still cause delays.<br>Removing messages from the queue is typically handled by the <b>postsuper -d</b> command, not <b>postqueue</b>.


title: COMMON USE CASES
content:
To check for stuck mail: <i><b>postqueue -p</b></i><br>To force delivery of all waiting mail: <i><b>postqueue -f</b></i><br>To force delivery of a specific message (e.g., ID A1B2C3D4): <i><b>postqueue -i A1B2C3D4</b></i><br>To see verbose output during a queue run: <i><b>postqueue -f -v</b></i>


title: INTERPRETING <I>POSTQUEUE -P</I> OUTPUT
content:
The output of <i><b>postqueue -p</b></i> lists messages in the queue with their queue ID, size, arrival time, sender, and recipient(s).<br>Messages marked with <i>(deferred)</i> indicate a temporary delivery failure, meaning Postfix will retry delivery later. The reason for deferral is often shown in the next line. Other statuses like <i>active</i> mean the message is currently being processed for delivery.


title: HISTORY
content:
<i><b>postqueue</b></i> is an integral part of the Postfix mail transfer agent (MTA), a robust and secure mail server developed by Wietse Venema starting in 1998. Postfix was designed as a modern, high-performance, and secure alternative to older MTAs like Sendmail. The <i><b>postqueue</b></i> utility was developed as part of this ecosystem to provide fine-grained control and visibility into the mail queue, evolving alongside Postfix's architecture to support its various queue types and delivery mechanisms.


title: PARAMETERS
content:
<b><b>-f</b>, <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Forces an immediate shutdown without gracefully terminating processes, synchronizing filesystems, or sending warnings. <br>Use with extreme caution as it can lead to data loss or filesystem corruption.</I><br><br><b><b>--no-sync</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Prevents synchronizing disk writes to physical storage before shutdown. <br>This option is very dangerous and should only be used in specific, critical situations where data integrity is secondary to speed, as it risks significant data loss.</I><br><br><b><b>-w</b>, <b>--wall-message=MESSAGE</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Specifies a message to broadcast to all logged-in users before initiating the shutdown.</I><br><br><b><b>--no-wall</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Suppresses the default broadcast of a warning message to users about the impending shutdown.</I><br><br><b><b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Displays more detailed information about the shutdown process as it unfolds.</I><br><br>


title: DESCRIPTION
content:
The <I>poweroff</I> command is used to safely shut down and completely power off a Linux system. It orchestrates a controlled shutdown process, ensuring all running processes are gracefully terminated, open files are closed, and filesystems are synchronized to disk. This meticulous procedure aims to bring the system to a stable, consistent state before cutting power, thereby preventing data corruption and ensuring system integrity. On modern Linux distributions, <I>poweroff</I> is commonly implemented as a symbolic link to <I>systemctl poweroff</I> or a script that invokes <I>shutdown -P now</I>. This integration leverages the system's init system (like systemd) for robust and consistent power management. Executing <I>poweroff</I> typically requires root privileges.


title: CAVEATS
content:
<I><b>Important Considerations:</b><br>1. Executing <I>poweroff</I> requires root privileges.<br>2. On modern systems, <I>poweroff</I> is often a symlink to <I>systemctl poweroff</I> or a script invoking <I>shutdown -P now</I>. Its exact behavior and available options might therefore be influenced by <I>systemd</I> or the <I>shutdown</I> command's underlying implementation.<br>3. Using options like <I>--force</I> or <I>--no-sync</I> can lead to irreversible data loss or filesystem corruption if not used correctly.</I>


title: PERMISSIONS
content:
<I>Executing <B>poweroff</B> requires elevated privileges, typically the root user or a user with sudo access. Attempting to run it without sufficient permissions will result in an 'Operation not permitted' error.</I>


title: GRACEFUL SHUTDOWN
content:
<I>By default, <B>poweroff</B> attempts a graceful shutdown, giving processes time to terminate and filesystems to synchronize. This is the safest way to shut down a system and prevent data corruption, making it the recommended method for regular system shutdowns.</I>


title: HISTORY
content:
The <I>poweroff</I> command has been a fundamental part of Unix-like operating systems for decades, providing a direct method to instruct the system to power down. Historically, it was often part of the <I>sysvinit</I> toolset. With the widespread adoption of <I>systemd</I> as the primary init system in many modern Linux distributions, <I>poweroff</I> is now commonly implemented as a symbolic link to <I>systemctl poweroff</I>. This transition ensures that power management operations are seamlessly integrated with <I>systemd</I>'s service and process management, providing a unified and consistent control interface while maintaining the command's familiar usage.


