1Libnetbpm Utility Functions(L3i)brary Functions ManuLailbnetbpm Utility Functions(3)
2 Table Of Contents ⟨#toc⟩
6 These library functions are part of Netpbm(1).
8 This page documents functions in the Netpbm subroutine library that are
10 not directly related to image data.
11 For introductory and general information using libnetpbm, see Libnetpb‐
13 mUser'sGuide(1).
14 The most commonly used libnetpbm functions are those that read and
16 write and process Netpbm images. Those are documented in Libnetpbm‐
17 NetpbmImageProcessing Manual (1)
18 To use these services, #include pam.h.
20
23 Initialization
24 Overview
25 void pm_init( const char * progname, unsigned int flags[] );
27 void pm_proginit( int * argcP, char * argv[] );
29 Description
31 All Netpbm programs must call pm_proginit() just after startup, before
33 they process their arguments. pm_proginit(), among other things, pro‐
34 cesses Netpbm universal arguments and removes them from the argument
35 list.
36 A program that isn't a Netpbm program, but just uses libnetpbm ser‐
38 vices, need not invoke pm_proginit. But such a program must invoke
39 pm_init().
40 By 'Netpbm program,' we mean a program that is part of the Netpbm pack‐
42 age or is intended to act like one. pm_proginit() does things that all
43 Netpbm programs do by convention. For example, it scans the argument
44 list for
45 common options ⟨index.html#commonoptions⟩ , handles them, and removes
46 them from the argument list. Ergo, if you want your program to have
47 the same common options as those in the Netpbm package, you might use
48 pm_proginit(), and if you don't, you must not.
49 pm_proginit() is primarily intended for Netpbm developers, so you
51 should not expect it to have stable function across releases, and you
52 must go to the comments in the source code to see exactly what it does.
53 Any program that uses libnetpbm but does not call pm_proginit (i.e. is
55 not a Netpbm program) must call pm_init(). The conventional place to
56 do this is at the very beginning of the program. This sets up some
57 program-global variables for use by the libnetpbm functions.
58 The progname argument is the program name for libnetpbm functions to
60 use in messages they issue. Normally, you would use argv[0] for this.
61 flags is meaningless, but for forward compatibility, you must set it to
63 zero.
64 pm_init() and pm_proginit() have been around at least since Netpbm 9.25
66 (March 2002). Another function named pm_init() exists in older Netpbm,
67 but was for internal use. Netpbm programs of that era use pbm_init(),
68 etc to do what pm_proginit() does today. Today, pbm_init(), etc. exist
69 for backward compatibility and are identical the pm_proginit().
70 File Or Image Stream Access
74 Overview
75 FILE *pm_openr( char * name );
77 FILE *pm_openw( char * name );
79 FILE *pm_openr_seekable( const char * name );
81 FILE *pm_close( FILE * fp );
83 void pm_tell2( FILE * fileP, pm_filepos * fileposP, unsigned int file‐
85 posSize );
86 unsigned int pm_tell( FILE * fileP );
88 void pm_seek2( FILE * fileP, const pm_filepos * fileposP, unsigned int
90 fileposSize );
91 void pm_seek( FILE * fileP, unsigned long filepos );
93 char *pm_read_unknown_size( FILE * fp, long * nread );
95 Description
98 An image stream is just a file stream (represented in the standard C
100 library as type FILE *).
101 These routines work on files > 2 GiB if the underlying system does,
103 using the standard large file interface. Before Netpbm 10.15 (April
104 2003), though, they would fail to open any file that large or process
105 any offset in a file that could not be represented in 32 bits.
106 pm_openr() opens the given file for reading, with appropriate error
108 checking. A filename of - is taken to mean Standard Input. pm_openw()
109 opens the given file for writing, with appropriate error checking.
110 pm_close() closes the file descriptor, with appropriate error checking.
111 pm_openr_seekable() appears to open the file just like pm_openr(), but
113 the file thus opened is guaranteed to be seekable (you can use ftell()
114 and fseek() on it). pm_openr_seekable() pulls this off by copying the
115 entire file to a temporary file and giving you the handle of the tempo‐
116 rary file, if it has to. If the file you name is a regular file, it's
117 already seekable so pm_openr_seekable() just does the same thing as
118 pm_openr().
119 But if it is, say, a pipe, it isn't seekable. So pm_openr_seekable()
121 reads the pipe until EOF into a temporary file, then opens that tempo‐
122 rary file and returns the handle of the temporary file. The temporary
123 file is seekable.
124 The file pm_openr_seekable() creates is one that the operating system
126 recognizes as temporary, so when you close the file, by any means, it
127 gets deleted.
128 You need a seekable file if you intend to make multiple passes through
130 the file. The only alternative is to read the entire image into memory
131 and work from that copy. That may use too much memory. Note that the
132 image takes less space in the file cache than in a buffer in memory.
133 As much as 96 times less space! Each sample is an integer in the buf‐
134 fer, which is usually 96 bits. In the file, a sample may be as small
135 as 1 bit and rarely more than 8 bits.
136 pm_tell2() returns a handle for the current position of the image
138 stream (file), whether it be the header or a row of the raster. Use
139 the handle as an argument to pm_seek2() to reposition the file there
140 later. The file must be seekable (which you can ensure by opening it
141 with pm_openr_seekable()) or this may fail.
142 The file position handle is of type pm_filepos, which is intended to be
144 opaque, i.e. used only with these two functions. In practice, it is a
145 file offset and is 32 bits or 64 bits depending upon the capability of
146 the underlying system. For maximum backward and forward compatibility,
147 the functions that take or return a pm_filepos have a fileposSize argu‐
148 ment for the size of the data structure. In C, simply code
149 sizeof(pm_filepos) for that.
150 pm_seek() and pm_tell are for backward compatibility only. Do not use
152 them in new code. These functions are not capable of handle positions
153 in files whose byte offset cannot be represented in 32 bits.
154 pm_tell2() and pm_seek2() replaced pm_tell() and pm_seek() in Netpbm
156 10.15 (April 2003).
157 pm_read_unknown_size() reads an entire file or input stream of unknown
159 size to a buffer. It allocates more memory as needed. The calling
160 routine has to free the allocated buffer with free().
161 pm_read_unknown_size() returns a pointer to the allocated buffer. The
163 nread argument returns the number of bytes read.
164 Endian I/O
168 Entry Points
169 void pm_readchar( FILE * in, char * sP );
171 void pm_writechar( FILE * out, char s );
173 int pm_readbigshort( FILE * in, short * sP );
175 int pm_writebigshort( FILE * out, short s );
177 int pm_readbiglong( FILE * in, long * lP );
179 int pm_writebiglong( FILE * out, long l );
181 int pm_readlittleshort( FILE * in, short * sP );
183 int pm_writelittleshort( FILE * out, short s );
185 int pm_readlittlelong( FILE * in, long * lP );
187 int pm_writelittlelong( FILE * out, long l );
189 void pm_readcharu( FILE * in, char * sP );
191 void pm_writecharu( FILE * out, char s );
193 int pm_readbigshortu( FILE * in, short * sP );
195 int pm_writebigshortu( FILE * out, short s );
197 int pm_readbiglongu( FILE * in, long * lP );
199 int pm_writebiglongu( FILE * out, long l );
201 int pm_readlittleshortu( FILE * in, short * sP );
203 int pm_writelittleshortu( FILE * out, short s );
205 int pm_readlittlelongu( FILE * in, long * lP );
207 int pm_writelittlelongu( FILE * out, long l );
209 Description
211 pm_readchar(), pm_writechar(), pm_readbigshort(), pm_writebigshort(),
213 pm_readbiglong(), pm_writebiglong(), pm_readlittleshort(), pm_writelit‐
214 tleshort(), pm_readlittlelong(), and pm_writelittlelong() are routines
215 to read and write 1-byte, 2-byte, and 4-byte pure binary integers in
216 either big- or little-endian byte order. Note that a 'long int' C type
217 might be wider than 4 bytes, but the 'long' routines still read and
218 write 4 bytes.
219 pm_readbiglongu(), etc. (names ending in u) are the same except they
221 work on unsigned versions of the type.
222 The routines with declared return values always return 0. Before
224 Netpbm 10.27 (March 2005), they returned -1 on failure, including EOF.
225 Now, they issue an error message to Standard Error and abort the pro‐
226 gram if the I/O fails or encounters EOF.
227 The 1-byte routines were new in Netpbm 10.27 (March 2005). The
229 unsigned versions were new somewhere around Netpbm 10.21 (2004).
230 Maxval Arithmetic
233 Entry Points
234 int pm_maxvaltobits( int maxval );
236 int pm_bitstomaxval( int bits );
238 unsigned int pm_lcm( unsigned int x, unsigned int y, unsigned int z,
240 unsigned int limit );
241 Description
243 pm_maxvaltobits() and pm_bitstomaxval() convert between a maxval and
245 the minimum number of bits required to hold it.
246 pm_lcm() computes the least common multiple of 3 integers. You also
248 specify a limit and if the LCM would be higher than that limit,
249 pm_lcm() just returns that limit.
250 Gamma Arithmetic
253 Entry Points
254 float pm_gamma709( float intensity );
256 float pm_ungamma709( float brightness );
258 Description
261 In graphics processing, there are two common ways of representing
263 numerically the intensity of a pixel, or a component of a pixel.
264 The obvious way is with a number that is directly proportional to the
266 light intensity (e.g. 10 means twice as many milliwatts per square cen‐
267 timeter as 5). There are two problems with this:
268 · To the human eye, a 1 milliwatt per square centimeter difference
272 in a bright image is much less apparent than a 1 milli‐
273 watt per
274 square centimeter difference in a dark image. So if you
275 have
276 a fixed number of bits in which to store the intensity
277 value,
278 you're wasting resolution at the bright end and skimping
279 on it at
280 the dark end.
281 · Monitor inputs and camera outputs aren't directly proportional
283 to
284 the light intensity they project or detect.
285 For these reasons, light intensities are often represented in graphics
288 processing by an exponential scale. The transfer function is called a
289 gamma function and the resulting numbers are called gamma-corrected or
290 gamma-adjusted. There are various gamma functions. The Netpbm formats
291 specify that intensities are represented by gamma-adjusted numbers of a
292 particular gamma transfer function.
293 These functions let you convert back and forth between these two
295 scales, using the same gamma transfer function that is specified in the
296 Netpbm format specifications.
297 pm_gamma709 converts from an intensity-proportional intensity value to
299 a gamma-adjusted intensity value (roughly proportional to brightness,
300 which is the human subjective perception of intensity), using the ITU-R
301 Recommendation BT.709 gamma transfer function.
302 pm_ungamma709 is the inverse of pm_gamma709.
304 Messages
307 Overview
308 void pm_message( char * fmt, ... );
310 void pm_setusermessagefn(pm_usermessagefn * function);
312 Description
314 pm_message() is a printf() style routine to write an informational mes‐
316 sage to the Standard Error file stream. pm_message() suppresses the
317 message, however, if the user specified the -quiet common option
318 ⟨index.html#commonoptions⟩ on the command line. Note that Netpbm pro‐
319 grams are often used interactively, but also often used by programs.
320 In the interactive case, it is nice to issue messages about what the
321 program is doing, but in the program case, such messages are usually
322 undesirable. By using pm_message() for all your messages, you make
323 your program usable in both cases. Without any effort on your part,
324 program users of your program can avoid the messages by specifying the
325 -quiet option.
326 Netpbm distinguishes between error messages and information messages;
328 pm_message() is just for informational messages. To issue an error
329 message, see pm_errormsg() ⟨liberror.html#pm_errormsg⟩ .
330 pm_setusermessagefn registers a handler for informational messages,
332 called a user message routine. Any library function (including pm_mes‐
333 sage()) that wants to issue an informational message in the future will
334 call that function with the message as an argument instead of writing
335 the message to Standard Error.
336 The argument the user message routine gets is English text designed for
338 human reading. It is just the text of the message; there is no attempt
339 at formatting in it (so you won't see any newline or tab characters).
340 To capture error messages in addition to informational messages, see
342 pm_setusererrormsgfn() ⟨liberror.html#pm_setusererrormsgfn⟩ .
343 You can remove the user message routine, so that the library issues
345 future informational messages in its default way (write to Standard
346 Error) by specifying a null pointer for function.
347 Example:
349 static pm_usermessagefn logfilewrite;
351 static void
353 logfilewrite(const char * const msg) {
354 fprintf(mymsglog, 'Netpbm message: %s', msg);
355 }
356 pm_setusermessagefn(&logfilewrite);
358 pm_message('Message for the message log');
360 System Utilities
364 ·
365 pm_system(1)
367 ·
369 pm_tmpfile(1)
371 Keyword Matching
375 Entry Points
376 void pm_keymatch();
378 Description
380 This subroutine is obsolete. It used to be used for command line
382 option processing. Today, you can do better option processing more
383 easily with the shhopt facility. See any recent program in the Netpbm
384 package for an example.
385 pm_keymatch() does a case-insensitive match of str against keyword.
387 str can be a leading substring of keyword, but at least minchars must
388 be present.
389netpbm documentation 27 August 2006 Libnetbpm Utility Functions(3)