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