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.