1\ 2.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. 3.\" Do not hand-hack it! If you have bug fixes or improvements, please find 4.\" the corresponding HTML page on the Netpbm website, generate a patch 5.\" against that, and send it to the Netpbm maintainer. 6.TH "User manual for old pbm functions" 3 "8 September 2007" "netpbm documentation" 7 8.SH NAME 9libpbm - libnetpbm functions to read and write PBM image files 10 11.UN synopsis 12.SH SYNOPSIS 13 14\fB#include <netpbm/pbm.h>\fP 15.PP 16\fBbit **pbm_allocarray(int\fP 17\fIcols\fP\fB, int \fP\fIrows\fP\fB);\fP 18.PP 19\fBbit *pbm_allocrow(int\fP 20\fIcols\fP\fB);\fP 21.PP 22\fBpbm_freearray(bit \fP 23\fB**\fP\fIbits\fP\fB, int \fP\fIrows\fP\fB);\fP 24.PP 25\fBpbm_freerow(bit\fP 26\fB*\fP\fIbitrow\fP\fB);\fP 27.PP 28\fBvoid pbm_readpbminit(FILE *\fP 29\fIfp\fP\fB, 30int *\fP\fIcolsP\fP\fB, 31int *\fP\fIrowsP\fP\fB, 32int *\fP\fIformatP\fP\fB);\fP 33.PP 34\fBvoid pbm_readpbmrow(FILE *\fP 35\fIfp\fP\fB, 36bit *\fP\fIbitrow\fP\fB, 37int \fP\fIcols\fP\fB, 38int \fP\fIformat\fP\fB);\fP 39.PP 40\fBvoid pbm_readpbmrow_packed(FILE *\fP 41\fIfp\fP\fB,\fP 42\fBunsigned char * const \fP\fIpacked_bits\fP\fB,\fP 43\fBconst int \fP\fIcols\fP\fB,\fP 44\fBconst int \fP\fIformat\fP\fB);\fP 45.PP 46\fBvoid bit** pbm_readpbm(FILE *\fP 47\fIfp\fP\fB, int *\fP\fIcolsP\fP\fB, int *\fP\fIrowsP\fP\fB);\fP 48.PP 49\fBvoid pbm_writepbminit(FILE *\fP 50\fIfp\fP\fB, 51int \fP\fIcols\fP\fB, 52int \fP\fIrows\fP\fB, 53int \fP\fIforceplain\fP\fB);\fP 54.PP 55\fBvoid pbm_writepbmrow(FILE *\fP 56\fIfp\fP\fB, 57bit *\fP\fIbitrow\fP\fB, 58int \fP\fIcols\fP\fB, 59int \fP\fIforceplain\fP\fB);\fP 60.PP 61\fBvoid pbm_writepbmrow_packed(FILE *\fP 62\fIfp\fP\fB,\fP 63\fBunsigned char * const \fP\fIpacked_bits\fP\fB,\fP 64\fBconst int \fP\fIcols\fP\fB,\fP 65\fBconst int \fP\fIforceplain\fP\fB);\fP 66.PP 67\fBvoid pbm_writepbm(FILE *\fP 68\fIfp\fP\fB, 69bit **\fP\fIbits\fP\fB, 70int \fP\fIcols\fP\fB, 71int \fP\fIrows\fP\fB, 72int \fP\fIforceplain\fP\fB);\fP 73.PP 74\fB#define pbm_packed_bytes(\fP\fIcols\fP\fB) ...\fP 75.PP 76\fBvoid pbm_nextimage(\fP 77\fBFILE *\fP\fIfile\fP\fB,\fP 78\fBint * const \fP\fIeofP\fP\fB);\fP 79.PP 80\fBvoid pbm_check(\fP 81\fBFILE * \fP\fIfile\fP\fB,\fP 82\fBconst enum pm_check_type \fP\fIcheck_type\fP\fB,\fP 83\fBconst int \fP\fIformat\fP\fB,\fP 84\fBconst int \fP\fIcols\fP\fB,\fP 85\fBconst int \fP\fIrows\fP\fB,\fP 86\fBenum pm_check_code * const \fP\fIretval\fP\fB);\fP 87 88 89.UN description 90.SH DESCRIPTION 91.PP 92These library functions are part of 93.BR "Netpbm" (1)\c 94\&. 95 96.UN types 97.SS TYPES AND CONSTANTS 98 99\fBtypedef ... bit;\fP 100.PP 101\fB#define PBM_WHITE ...\fP 102.PP 103\fB#define PBM_BLACK ...\fP 104.PP 105Each \fBbit\fP should contain only the values of \fBPBM_WHITE\fP 106or \fBPBM_BLACK\fP. 107.PP 108\fB#define PBM_FORMAT ...\fP 109.PP 110\fB#define RPBM_FORMAT ...\fP 111.PP 112\fB#define PBM_TYPE PBM_FORMAT\fP 113.PP 114\fB#define \fP 115\fBPBM_FORMAT_TYPE(\fP\fIf\fP\fB) ...\fP 116.PP 117These are for distinguishing different file formats and types. 118 119.UN initialization 120.SS INITIALIZATION 121.PP 122\fBpbm_init()\fP is obsolete (at least since Netpbm 9.25 (March 2002)). 123Use 124.UR libpm.html#initialization 125\fBpm_proginit()\fP 126.UE 127\& instead. 128.PP 129\fBpbm_init()\fP is identical to \fBpm_proginit\fP. 130 131.UN memorymanagement 132.SS MEMORY MANAGEMENT 133 134\fBpbm_allocarray()\fP allocates an array of bits. 135\fBpbm_allocrow()\fP allocates a row of the given number of bits. 136\fBpbm_freearray()\fP frees the array allocated with 137\fBpbm_allocarray()\fP containing the given number of rows. 138\fBpbm_freerow()\fP frees a row of bits. 139 140 141.UN reading 142.SS READING PBM IMAGE FILES 143.PP 144\fBpbm_readpbminit()\fP reads the header from a PBM image in a PBM 145file, filling in the rows, cols and format variables. 146\fBpbm_readpbmrow()\fP reads a row of bits into the \fIbitrow \fP 147array. Format and cols were filled in by \fBpbm_readpbminit()\fP. 148 149\fBpbm_readpbmrow_packed()\fP is like \fBpbm_readpbmrow()\fP except 150instead of returning a \fBbits\fP array, it returns an array 151\fIpacked_bits\fP of bytes with the pixels of the image row packed 152into them. The pixels are in order from left to right across the row 153and from the beginning of the array to the end. Within a byte, the 154bits are in order from the most significant bit to the least 155significant bit. If the number of pixels in the row is not a multiple 156of 8, the last byte returned is padded on the least significant bit 157side with undefined bits. White is represented by a \fBPBM_WHITE\fP 158bit; black by \fBPBM_BLACK\fP. 159.PP 160\fBpbm_readpbm()\fP reads an entire bitmap file into memory, 161returning the allocated array and filling in the rows and cols 162variables. This function combines \fBpbm_readpbminit()\fP, 163\fBpbm_allocarray()\fP and \fBpbm_readpbmrow()\fP. 164.PP 165\fBpbm_readpbminit()\fP and \fBpbm_readpbm\fP abort the program with 166a message to Standard Error if the PBM image header is not syntactically 167valid, including if it contains a number too large to be processed using 168the system's normal data structures (to wit, a number that won't fit in 169a C 'int'). 170.PP 171\fBppm_readppminit()\fP and \fBppm_readppm\fP abort the program with 172a message to Standard Error if the PPM image header is not syntactically 173valid, including if it contains a number too large to be processed using 174the system's normal data structures (to wit, a number that won't fit in 175a C 'int'). 176 177.UN writing 178.SS WRITING PBM IMAGE FILES 179 180\fBpbm_writepbminit()\fP writes the header for a PBM image in a PBM 181file. \fIforceplain\fP is a boolean value specifying that a plain 182format (text) file to be written, as opposed to a raw format (binary) 183one. \fBpbm_writepbmrow()\fP writes a row to a PBM file. 184\fBpbm_writepbmrow_packed()\fP is the same as 185\fBpbm_writepbmrow()\fP except that you supply the row to write as an 186array of bytes packed with bits instead of as a \fBbits\fP array. 187The format of \fIpacked_bits \fP is the same as that returned by 188\fBpbm_readpbmrow()\fP. 189.PP 190\fBpbm_writepbm()\fP writes the header and all data for a PBM 191image to a PBM file. This function combines \fBpbm_writepbminit()\fP 192and \fBpbm_writepbmrow()\fP. 193 194.UN miscellaneous 195.SS MISCELLANEOUS 196.PP 197\fBpbm_nextimage()\fP positions a PBM input file to the next image 198in it (so that a subsequent \fBpbm_readpbminit()\fP reads its 199header). 200.PP 201Immediately before a call to \fBpbm_nextimage()\fP, the file must 202be positioned either at its beginning (i.e. nothing has been read from 203the file yet) or just after an image (i.e. as left by a 204\fBpbm_readpbmrow() \fP of the last row in the image). 205.PP 206Note that in the raw PNM and PAM format, the next image always 207starts immediately after the previous image, so all 208\fBpbm_nextimage()\fP really does is test whether there is a next 209image or the file is positioned at end-of-file. In plain PNM, though, 210there may be white space between images. 211.PP 212If \fBpbm_nextimage() \fP successfully positions to the next 213image, it returns \fB*\fP\fIeofP\fP false (0). If there is no next 214image in the file, it returns \fB*\fP\fIeofP\fP true . If it can't 215position or determine the file status because of a file error, it 216.UR liberror.html#error 217throws an error 218.UE 219\&. 220.PP 221\fBpbm_check()\fP checks for the common file integrity error where 222the file is the wrong size to contain all the image data. 223\fBpbm_check()\fP assumes the file is positioned after an image 224header (as if \fBpbm_readpbminit() \fP was the last operation on the 225file). It checks the file size to see if the number of bytes left in 226the file are the number required to contain the image raster. If the 227file is too short, \fBpbm_check()\fP causes the program t 228.UR liberror.html#error 229throws an error 230.UE 231\&. Otherwise, it returns 232one of the following values (enumerations of the \fBenum 233pm_check_code\fP type) as \fB*\fP\fIretval\fP: 234 235 236.TP 237\fBPM_CHECK_OK\fP 238The file's size is exactly what is required to hold the image raster. 239 240.TP 241\fBPM_CHECK_UNKNOWN_TYPE\fP 242\fIformat\fP is not a format whose size \fBpbm_check()\fP can 243anticipate. The only format with which \fBpbm_check()\fP can deal is 244raw PBM format. 245 246.TP 247\fBPM_CHECK_TOO_LONG\fP 248The file is longer than it needs to be to contain the image 249raster. The extra data might be another image. 250 251.TP 252\fBPM_CHECK_UNCHECKABLE\fP 253The file is not a kind that has a predictable size, so there is no 254simple way for \fBpbm_check()\fP to know if it is the right size. 255Only a regular file has predictable size. A pipe is a common example 256of a file that does not. 257 258 259.PP 260\fIcheck_type\fP must have the value \fBPM_CHECK_BASIC \fP (an 261enumerated value of the \fBpm_check_type\fP enumerated type). 262Otherwise, the effect of \fBpbm_check()\fP is unpredictable. This 263argument exists for future backward compatible expansion of the 264function of \fBpbm_check()\fP. 265 266.UN seealso 267.SH SEE ALSO 268.BR "libpgm" (3)\c 269\&, 270.BR "libppm" (3)\c 271\&, 272.BR "libpnm" (3)\c 273\&, 274.BR "pbm" (5)\c 275\& 276 277.UN author 278.SH AUTHOR 279 280Copyright (C) 1989, 1991 by Tony Hansen and Jef Poskanzer. 281.SH DOCUMENT SOURCE 282This manual page was generated by the Netpbm tool 'makeman' from HTML 283source. The master documentation is at 284.IP 285.B http://netpbm.sourceforge.net/doc/libpbm.html 286.PP