---
name: "libpgm"
section: "3"
platform: "linux"
package: "netpbm"
version: "10.86.51-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/libpgm"
---

# libpgm(3)

libnetpbm functions to read and write PGM image files

## NAME

libpgm - libnetpbm functions to read and write PGM image files

## SYNOPSIS

**#include \<netpbm/pgm.h\>**

**void pgm\_init(**  **int \****argcP***,** **char \****argv***\[\]** **);**

**gray \*\* pgm\_allocarray(** **int** *cols***,** **int** *rows* **);**

**gray \* pgm\_allocrow(** **int***cols* **);**

**void pgm\_freearray(** **gray \*\****grays***,** **int***rows* **);**

**void pgm\_freerow(** **gray \****grayrow***);**

**void pgm\_readpgminit(**  **FILE \****fp***,** **int \****colsP***,** **int \****rowsP***,** **gray \****maxvalP***,** **int \****formatP* **);**

**void pgm\_readpgmrow(**  **FILE \****fp***,** **gray \****grayrow***,** **int** *cols***,** **gray** *maxval***,** **int** *format* **);**

**gray \*\* pgm\_readpgm(**  **FILE \****fp***,** **int \****colsP***,** **int \****rowsP***,** **gray \****maxvalP* **);**

**void pgm\_writepgminit(**  **FILE \*  fp ,**  **int** *cols***,** **int** *rows***,** **gray** *maxval***,** **int** *forceplain* **);**

**void pgm\_writepgmrow(**  **FILE \****fp***,** **gray \****grayrow***,** **int cols***,* **gray** *maxval***,** **int** *forceplain* **);**

**void pgm\_writepgm(**  **FILE \****fp***,** **gray \*\*** *grays***,** **int** *cols***,** **int** *rows***,** **gray** *maxval***,** **int** *forceplain* **);**

**void pgm\_writepgm(**  **FILE \****fp***,** **gray \*\****grays***,** **int** *cols***,** **int** *rows***,** **gray** *maxval***,** **int** *forceplain* **);**

**void pgm\_nextimage(** **FILE \****file***,** **int \* const** *eofP***);**

**void pgm\_check(** **FILE \*** *file***,** **const enum pm\_check\_type** *check\_type***,** **const int** *format***,** **const int** *cols***,** **const int** *rows***,** **const int** *maxval***,** **enum pm\_check\_code \* const** *retval***);**

**typedef ... gray;**

**#define PGM\_MAXMAXVAL ...**

**#define PGM\_OVERALLMAXVAL ...**

**#define PGM\_FORMAT ...**

**#define RPGM\_FORMAT ...**

**#define PGM\_TYPE PGM\_FORMAT**

**#define**

**PGM\_FORMAT\_TYPE(***format***)** **...**

## DESCRIPTION

These library functions are part of **Netpbm**(1) .

### TYPES AND CONSTANTS

Each **gray** should contain only the values between **0** and **PGM\_OVERALLMAXVAL**.

**PGM\_OVERALLMAXVAL** is the maximum value of a maxval in a PGM file.  **PGM\_MAXMAXVAL** is the maximum value of a maxval in a PGM file that is compatible with the PGM format as it existed before April 2000.  It is also the maximum value of a maxval that results in the minimum possible raster size for a particular image.  I.e an image with a maxval higher than **PGM\_MAXMAXVAL** cannot be read or generated by old PGM processing programs and requires more file space.

**PGM\_FORMAT**  is the format code for a Plain PGM format image file.  **RPGM\_FORMAT** is the format code for a Raw PGM format image file.  **PGM\_TYPE**  is the format type code for the PGM formats.  **PGM\_FORMAT\_TYPE** is a macro that generates code to compute the format type code of a PBM or PGM format from the format code which is its argument.

### INITIALIZATION

**pgm\_init()** is obsolete (at least since Netpbm 9.25 (March 2002)). Use  **pm\_proginit()** ⟨libpm.html#initialization⟩  instead.

**pgm\_init()** is identical to **pm\_proginit**.

### MEMORY MANAGEMENT

**pgm\_allocarray()** allocates an array of grays.

**pgm\_allocrow()** allocates a row of the given number of grays.

**pgm\_freearray()** frees the array allocated with **pgm\_allocarray()** containing the given number of rows.

**pgm\_freerow()** frees a row of grays allocated with **pgm\_allocrow()**.

### READING FILES

If a function in this section is called on a PBM format file, it translates the PBM file into a PGM file on the fly and functions as if it were called on the equivalent PGM file.  The *format* value returned by **pgm\_readpgminit()** is, however, not translated.  It represents the actual format of the PBM file.

**pgm\_readpgminit()** reads the header of a PGM file, returning all the information from the header and leaving the file positioned just after the header.

**pgm\_readpgmrow()** reads a row of grays into the *grayrow*  array.  *format*, *cols*, and *maxval*  are the values returned by **pgm\_readpgminit()**.

**pgm\_readpgm()** reads an entire PGM image into memory, returning the allocated array as its return value and returning the information from the header as *rows*, *cols*, and *maxval*.  This function combines **pgm\_readpgminit()**, **pgm\_allocarray()**, and **pgm\_readpgmrow()**.

**pgm\_readpgminit()** and **pgm\_readpgm** abort the program with a message to Standard Error if the PGM image header is not syntactically valid, including if it contains a number too large to be processed using the system's normal data structures (to wit, a number that won't fit in a C 'int').

### WRITING FILES

**pgm\_writepgminit()** writes the header for a PGM file and leaves it positioned just after the header.

*forceplain* is a logical value that tells **pgm\_writepgminit()**  to write a header for a plain PGM format file, as opposed to a raw PGM format file.

**pgm\_writepgmrow()** writes the row *grayrow* to a PGM file.  For meaningful results, *cols*, *maxval*, and *forceplain* must be the same as was used with **pgm\_writepgminit()**.

**pgm\_writepgm()** write the header and all data for a PGM image.  This function combines **pgm\_writepgminit()** and **pgm\_writepgmrow()**.

### MISCELLANEOUS

**pgm\_nextimage()** positions a PGM input file to the next image in it (so that a subsequent **pgm\_readpgminit()** reads its header).

**pgm\_nextimage()** is analogous to **pbm\_nextimage()**, but works on PGM and PBM files.

**pgm\_check()**  checks for the common file integrity error where the file is the wrong size to contain all the image data.

**pgm\_check()**  is analogous to **pbm\_check()**, but works on PGM and PBM files.

## SEE ALSO

**libpbm**(1) , **libppm**(1) , **libpnm**(1)

## DOCUMENT SOURCE

This manual page was generated by the Netpbm tool 'makeman' from HTML source.  The master documentation is at

-

  **http://netpbm.sourceforge.net/doc/libpgm.html**