LIBPGM(3)

💖 NAME 💖

libpgm — bestie, these are the libnetpbm functions that read and write PGM image files. That's it. That's the whole vibe. 🎀

(Oh also, hi, you're reading the User manua...m functions(3) page from the Library Functions Manual — section 3, library functions, we love her. 💅)

---

✨ SYNOPSIS ✨

#include <netpbm/pgm.h>

void pgm_init( int *argcP, char *argv[] );

gray ** pgm_allocarray( int cols, int rows );

gray * pgm_allocrow( intcols );

void pgm_freearray( gray **grays, introws );

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 🌸

Okay so, real talk: these library functions are part of Netpbm(1). 🫶

🦋 TYPES AND CONSTANTS 🦋

Every single gray should hold only values between 0 and PGM_OVERALLMAXVAL. No rogue numbers, bestie, we don't do that here.

• PGM_OVERALLMAXVAL — this is the absolute ceiling for a maxval in a PGM file. The big one. 👑
• PGM_MAXMAXVAL — this is the maximum value of a maxval in a PGM file that's compatible with the PGM format as it existed before April 2000. It's also the maximum maxval that gives you the minimum possible raster size for a particular image. Translating that for the group chat: an image with a maxval higher than PGM_MAXMAXVAL cannot be read or generated by old PGM processing programs and it needs more file space. So like… old-head energy vs. extra disk space, pick your struggle. 💀
• PGM_FORMAT — the format code for a Plain PGM format image file.
• RPGM_FORMAT — the format code for a Raw PGM format image file.
• PGM_TYPE — the format type code for the PGM formats.
• PGM_FORMAT_TYPE — 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. She's a code generator, she's a girlboss. ✨

🎀 INITIALIZATION 🎀

pgm_init() is obsolete — at least since Netpbm 9.25 (March 2002). Use pm_proginit() instead, periodt. 🙈

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. Clean up after yourself, it's giving responsible. 🧚
• pgm_freerow() — frees a row of grays allocated with pgm_allocrow().

🔥 READING FILES 🔥

Big note first, no cap: 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. But — and this is the plot twist — the format value returned by pgm_readpgminit() is not translated. It represents the actual format of the PBM file. Iconic behaviour honestly.

• pgm_readpgminit() — reads the header of a PGM file, hands you back all the info from the header, and leaves the file positioned just after the header. 📍
• pgm_readpgmrow() — reads a row of grays into the grayrow array. The 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 info from the header as rows, cols, and maxval. This function combines pgm_readpgminit(), pgm_allocarray(), and pgm_readpgmrow(). She's the whole friend group in one function. 👑

🚨 Okay important: 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'). So don't feed her chaos and expect a gentle little error return. She will end it. 💀

🌈 WRITING FILES 🌈

• pgm_writepgminit() — writes the header for a PGM file and leaves it positioned just after the header.
• forceplain — 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(). Matching values = main character energy, mismatched values = chaos. ⭐
• pgm_writepgm() — writes 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). She's the "next slide please" of file parsing. 💅
• 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. A vibe check, but for file sizes. 🦋
• 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

---

okay that's the whole page, you ate that, go read some PGMs bestie 💖✨🎀

netpbm documentation — 08 September 2007 — and yes, the page title really is "User manua...m functions(3)", she's a little mysterious like that, iykyk 🫶💜