libpbm(3)                                               libpbm(3)

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  min-
       chars 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  check-
       ing.

   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
       allocated  array  and  filling  in the rows and cols vari-
       ables.    This   function   combines    pbm_readpbminit(),
       pbm_allocarray() and pbm_readpbmrow().

       char* pm_read_unknown_size( FILE* fp, long* nread )

       Read  an  entire file or input stream of unknown size to a
       buffer.  Allocate memory more memory as needed. The  call-
       ing  routine has to free the allocated buffer with free().
       pm_read_unknown_size() returns a pointer to the  allocated
       buffer.  The  nread  argument  returns the number of bytes
       read.

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

       Write the header for a portable bitmap file.   The  force-
       plain  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_writepbm-
       row().

SEE ALSO
       libpgm(3), libppm(3), libpnm(3)

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

                                                                1