1User manual for old pbm funcLtiibornasr(y3)FunctionUsseMranmuaanlual for old pbm functions(3)
2
3
4

NAME

6       libpbm - libnetpbm functions to read and write PBM image files
7
8

SYNOPSIS

10       #include <netpbm/pbm.h>
11
12       bit **pbm_allocarray(int cols,  int rows);
13
14       bit *pbm_allocrow(int cols);
15
16       pbm_freearray(bit **bits, int rows);
17
18       pbm_freerow(bit *bitrow);
19
20       void pbm_readpbminit(FILE * fp, int *colsP, int *rowsP, int *formatP);
21
22       void pbm_readpbmrow(FILE * fp, bit *bitrow, int cols, int format);
23
24       void   pbm_readpbmrow_packed(FILE   *   fp,   unsigned   char  *  const
25       packed_bits, const int cols, const int format);
26
27       void bit** pbm_readpbm(FILE * fp, int *colsP, int *rowsP);
28
29       void pbm_writepbminit(FILE * fp, int cols, int rows, int forceplain);
30
31       void pbm_writepbmrow(FILE * fp, bit *bitrow, int cols, int forceplain);
32
33       void  pbm_writepbmrow_packed(FILE  *  fp,   unsigned   char   *   const
34       packed_bits, const int cols, const int forceplain);
35
36       void pbm_writepbm(FILE * fp, bit **bits, int cols, int rows, int force‐
37       plain);
38
39       #define pbm_packed_bytes(cols) ...
40
41       void pbm_nextimage( FILE *file, int * const eofP);
42
43       void pbm_check( FILE * file, const enum pm_check_type check_type, const
44       int  format, const int cols, const int rows, enum pm_check_code * const
45       retval);
46
47
48

DESCRIPTION

50       These library functions are part of Netpbm(1).
51
52
53   TYPES AND CONSTANTS
54       typedef ... bit;
55
56       #define PBM_WHITE ...
57
58       #define PBM_BLACK ...
59
60       Each bit should contain only the values of PBM_WHITE or PBM_BLACK.
61
62       #define PBM_FORMAT ...
63
64       #define RPBM_FORMAT ...
65
66       #define PBM_TYPE PBM_FORMAT
67
68       #define PBM_FORMAT_TYPE(f) ...
69
70       These are for distinguishing different file formats and types.
71
72
73   INITIALIZATION
74       pbm_init() is obsolete (at least since Netpbm 9.25 (March 2002)).   Use
75       pm_proginit() ⟨libpm.html#initialization⟩  instead.
76
77       pbm_init() is identical to pm_proginit.
78
79
80   MEMORY MANAGEMENT
81       pbm_allocarray()  allocates an array of bits.  pbm_allocrow() allocates
82       a row of the given number of bits.   pbm_freearray()  frees  the  array
83       allocated  with  pbm_allocarray()  containing the given number of rows.
84       pbm_freerow() frees a row of bits.
85
86
87
88   READING PBM IMAGE FILES
89       pbm_readpbminit() reads the header from a PBM  image  in  a  PBM  file,
90       filling in the rows, cols and format variables.  pbm_readpbmrow() reads
91       a row of bits into the bitrow array.  Format and cols were filled in by
92       pbm_readpbminit().
93
94       pbm_readpbmrow_packed()  is  like  pbm_readpbmrow()  except  instead of
95       returning a bits array, it returns an array packed_bits of  bytes  with
96       the  pixels of the image row packed into them.  The pixels are in order
97       from left to right across the row and from the beginning of  the  array
98       to the end.  Within a byte, the bits are in order from the most signif‐
99       icant bit to the least significant bit.  If the number of pixels in the
100       row  is  not  a  multiple of 8, the last byte returned is padded on the
101       least significant bit side with undefined bits.  White  is  represented
102       by a PBM_WHITE bit; black by PBM_BLACK.
103
104       pbm_readpbm()  reads  an  entire bitmap file into memory, returning the
105       allocated array and filling in the rows and cols variables.  This func‐
106       tion combines pbm_readpbminit(), pbm_allocarray() and pbm_readpbmrow().
107
108       pbm_readpbminit()  and  pbm_readpbm abort the program with a message to
109       Standard Error if the PBM image  header  is  not  syntactically  valid,
110       including  if  it contains a number too large to be processed using the
111       system's normal data structures (to wit, a number that won't fit in a C
112       'int').
113
114       ppm_readppminit()  and  ppm_readppm abort the program with a message to
115       Standard Error if the PPM image  header  is  not  syntactically  valid,
116       including  if  it contains a number too large to be processed using the
117       system's normal data structures (to wit, a number that won't fit in a C
118       'int').
119
120
121   WRITING PBM IMAGE FILES
122       pbm_writepbminit()  writes  the  header  for a PBM image in a PBM file.
123       forceplain is a boolean value specifying that  a  plain  format  (text)
124       file  to  be  written,  as  opposed  to  a  raw  format  (binary)  one.
125       pbm_writepbmrow() writes a row to a PBM file.  pbm_writepbmrow_packed()
126       is  the  same  as  pbm_writepbmrow()  except that you supply the row to
127       write as an array of bytes packed with bits instead of as a bits array.
128       The format of packed_bits  is the same as that returned by pbm_readpbm‐
129       row().
130
131       pbm_writepbm() writes the header and all data for a PBM image to a  PBM
132       file.  This function combines pbm_writepbminit() and pbm_writepbmrow().
133
134
135   MISCELLANEOUS
136       pbm_nextimage()  positions a PBM input file to the next image in it (so
137       that a subsequent pbm_readpbminit() reads its header).
138
139       Immediately before a call to pbm_nextimage(), the file  must  be  posi‐
140       tioned  either  at  its  beginning (i.e. nothing has been read from the
141       file yet) or just after an image (i.e. as left  by  a  pbm_readpbmrow()
142       of the last row in the image).
143
144       Note  that  in the raw PNM and PAM format, the next image always starts
145       immediately after the previous image,  so  all  pbm_nextimage()  really
146       does is test whether there is a next image or the file is positioned at
147       end-of-file.  In plain PNM, though, there may be  white  space  between
148       images.
149
150       If  pbm_nextimage()   successfully  positions  to  the  next  image, it
151       returns *eofP false (0).  If there is no next image  in  the  file,  it
152       returns *eofP true .  If it can't position or determine the file status
153       because of a file error, it throws an error ⟨liberror.html#error⟩ .
154
155       pbm_check() checks for the common file integrity error where  the  file
156       is  the  wrong size to contain all the image data.  pbm_check() assumes
157       the file is positioned after an image header (as  if  pbm_readpbminit()
158       was the last operation on the file).  It checks the file size to see if
159       the number of bytes left in the file are the number required to contain
160       the  image  raster.   If  the file is too short, pbm_check() causes the
161       program t  throws  an  error  ⟨liberror.html#error⟩  .   Otherwise,  it
162       returns   one  of  the  following  values  (enumerations  of  the  enum
163       pm_check_code type) as *retval:
164
165
166
167       PM_CHECK_OK
168              The file's size is exactly what is required to  hold  the  image
169              raster.
170
171
172       PM_CHECK_UNKNOWN_TYPE
173              format  is  not  a format whose size pbm_check() can anticipate.
174              The only format with which pbm_check() can deal is raw PBM  for‐
175              mat.
176
177
178       PM_CHECK_TOO_LONG
179              The  file  is  longer  than  it needs to be to contain the image
180              raster.  The extra data might be another image.
181
182
183       PM_CHECK_UNCHECKABLE
184              The file is not a kind that has a predictable size, so there  is
185              no  simple  way for pbm_check() to know if it is the right size.
186              Only a regular file has predictable size.  A pipe  is  a  common
187              example of a file that does not.
188
189
190
191       check_type  must have the value PM_CHECK_BASIC  (an enumerated value of
192       the  pm_check_type  enumerated  type).   Otherwise,   the   effect   of
193       pbm_check() is unpredictable.  This argument exists for future backward
194       compatible expansion of the function of pbm_check().
195
196

SEE ALSO

198       libpgm(1), libppm(1), libpnm(1), pbm(1)
199
200

AUTHOR

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

DOCUMENT SOURCE

205       This manual page was generated by the Netpbm tool 'makeman'  from  HTML
206       source.  The master documentation is at
207
208              http://netpbm.sourceforge.net/doc/libpbm.html
209
210netpbm documentation           08 SeptemberUs2e0r07manual for old pbm functions(3)
Impressum