## NAME

         libpbm - functions to support portable bitmap programs

## SYNOPSIS

         #include <pbm.h>
         cc ... libpbm.a

## DESCRIPTION - PACKAGE-WIDE ROUTINES

      KEYWORD MATCHING
         int pm_keymatch( char* str, char* keyword, int minchars )

         Does a case-insensitive match of str against  keyword.   str
         can be a leading sunstring of keyword, but at least minchars
         must be present.

      LOG BASE TWO
         int pm_maxvaltobits( int maxval )
         int pm_bitstomaxval( int bits )

         Convert between a maxval and  the  minimum  number  of  bits
         required to hold it.

      MESSAGES AND ERRORS
         void pm_message( char* fmt, ... )

         printf() style routine to write an informational message.

         void pm_error( char* fmt, ... )

         printf() style routine to write an error message and abort.

         void pm_usage( char* usage )

         Write a usage message.   The  string  should  indicate  what
         arguments are to be provided to the program.

      GENERIC FILE MANAGEMENT
         FILE* pm_openr( char* name )

         Open the given file  for  reading,  with  appropriate  error
         checking.   A  filename  of  "-"  is  taken as equivalent to
         stdin.

         FILE* pm_openw( char* name )

         Open the given file  for  writing,  with  appropriate  error
         checking.

         void pm_close( FILE* fp )

         Close the file descriptor, with appropriate error checking.

      ENDIAN I/O
         int pm_readbigshort( FILE* in, short* sP )
         int pm_writebigshort( FILE* out, short s )
         int pm_readbiglong( FILE* in, long* lP )
         int pm_writebiglong( FILE* out, long l )
         int pm_readlittleshort( FILE* in, short* sP )
         int pm_writelittleshort( FILE* out, short s )
         int pm_readlittlelong( FILE* in, long* lP )
         int pm_writelittlelong( FILE* out, long l )

         Routines to read and write short and  long  ints  in  either
         big- or little-endian byte order.

## DESCRIPTION - PBM-SPECIFIC ROUTINES

      TYPES AND CONSTANTS
         typedef ... bit;
         #define PBM_WHITE ...
         #define PBM_BLACK ...

         each bit should contain only  the  values  of  PBM_WHITE  or
         PBM_BLACK.

         #define PBM_FORMAT ...
         #define RPBM_FORMAT ...
         #define PBM_TYPE PBM_FORMAT
         #define PBM_FORMAT_TYPE(f) ...

         For distinguishing different file formats and types.

      INITIALIZATION
         void pbm_init( int* argcP, char* argv[] )

         All PBM programs must call this routine.

      MEMORY MANAGEMENT
         bit** pbm_allocarray( int cols, int rows )

         Allocate an array of bits.

         bit* pbm_allocrow( int cols )

         Allocate a row of the given number of bits.

         void pbm_freearray( bit** bits, int rows )

         Free the array allocated  with  pbm_allocarray()  containing
         the given number of rows.

         void pbm_freerow( bit* bitrow )

         Free a row of bits.

      READING FILES
         void pbm_readpbminit( FILE* fp, int* colsP, int* rowsP, int* formatP )

         Read the header from a PBM file, filling in the  rows,  cols
         and format variables.

         void pbm_readpbmrow( FILE* fp, bit* bitrow, int cols, int format )

         Read a row of bits into the bitrow array.  Format  and  cols
         were filled in by pbm_readpbminit().

         bit** pbm_readpbm( FILE* fp, int* colsP, int* rowsP )

         Read an entire bitmap file into memory, returning the  allo-
         cated  array  and  filling  in  the rows and cols variables.
         This function combines  pbm_readpbminit(),  pbm_allocarray()
         and pbm_readpbmrow().

      WRITING FILES
         void pbm_writepbminit( FILE* fp, int cols, int rows, int forceplain )

         Write the header for a portable bitmap file.  The forceplain
         flag forces a plain-format file to be written, as opposed to
         a raw-format one.

         void pbm_writepbmrow( FILE* fp, bit* bitrow, int cols, int forceplain )

         Write a row from a portable bitmap.

         void pbm_writepbm( FILE* fp, bit** bits, int cols, int rows, int forceplain )

         Write the header and all data for a portable  bitmap.   This
         function combines pbm_writepbminit() and pbm_writepbmrow().

## SEE ALSO

         libpgm(3), libppm(3), libpnm(3)

## AUTHOR

         Copyright (C) 1989, 1991 by Tony Hansen and Jef Poskanzer.