1Libnetbpm Utility Functions(L3i)brary Functions ManuLailbnetbpm Utility Functions(3)
2
3
4
5       Table Of Contents ⟨#toc⟩
6
7       These library functions are part of Netpbm(1).
8
9       This page documents functions in the Netpbm subroutine library that are
10       not directly related to image data.
11
12       For introductory and general information using libnetpbm, see Libnetpb‐
13       mUser'sGuide(1).
14
15       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
19       To use these services, #include pam.h.
20
21

Functions

23   Initialization
24       Overview
25
26       void pm_init( const char * progname, unsigned int flags[] );
27
28       void pm_proginit( int * argcP, char * argv[] );
29
30       Description
31
32       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
37       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
41       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
50       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
54       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
59       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
62       flags is meaningless, but for forward compatibility, you must set it to
63       zero.
64
65       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
71
72
73   File Or Image Stream Access
74       Overview
75
76       FILE *pm_openr( char * name );
77
78       FILE *pm_openw( char * name );
79
80       FILE *pm_openr_seekable( const char * name );
81
82       FILE *pm_close( FILE * fp );
83
84       void pm_tell2( FILE *  fileP, pm_filepos * fileposP, unsigned int file‐
85       posSize );
86
87       unsigned int pm_tell( FILE * fileP );
88
89       void pm_seek2( FILE *  fileP, const pm_filepos * fileposP, unsigned int
90       fileposSize );
91
92       void pm_seek( FILE *  fileP, unsigned long filepos );
93
94       char *pm_read_unknown_size( FILE * fp, long * nread );
95
96
97       Description
98
99       An  image  stream  is just a file stream (represented in the standard C
100       library as type FILE *).
101
102       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
107       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
112       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
120       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
125        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
129       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
137       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
143       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
151       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
155       pm_tell2()  and  pm_seek2()  replaced pm_tell() and pm_seek() in Netpbm
156       10.15 (April 2003).
157
158       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
162       pm_read_unknown_size() returns a pointer to the allocated buffer.   The
163       nread argument returns the number of bytes read.
164
165
166
167   Endian I/O
168       Entry Points
169
170       void pm_readchar( FILE * in, char * sP );
171
172       void pm_writechar( FILE * out, char s );
173
174       int pm_readbigshort( FILE * in, short * sP );
175
176       int pm_writebigshort( FILE * out, short s );
177
178       int pm_readbiglong( FILE * in, long * lP );
179
180       int pm_writebiglong( FILE * out, long l );
181
182       int pm_readlittleshort( FILE * in, short * sP );
183
184       int pm_writelittleshort( FILE * out, short s );
185
186       int pm_readlittlelong( FILE * in, long * lP );
187
188       int pm_writelittlelong( FILE * out, long l );
189
190       void pm_readcharu( FILE * in, char * sP );
191
192       void pm_writecharu( FILE * out, char s );
193
194       int pm_readbigshortu( FILE * in, short * sP );
195
196       int pm_writebigshortu( FILE * out, short s );
197
198       int pm_readbiglongu( FILE * in, long * lP );
199
200       int pm_writebiglongu( FILE * out, long l );
201
202       int pm_readlittleshortu( FILE * in, short * sP );
203
204       int pm_writelittleshortu( FILE * out, short s );
205
206       int pm_readlittlelongu( FILE * in, long * lP );
207
208       int pm_writelittlelongu( FILE * out, long l );
209
210       Description
211
212       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
220       pm_readbiglongu(),  etc.  (names  ending in u) are the same except they
221       work on unsigned versions of the type.
222
223       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
228       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
231
232   Maxval Arithmetic
233       Entry Points
234
235       int pm_maxvaltobits( int maxval );
236
237       int pm_bitstomaxval( int bits );
238
239       unsigned int pm_lcm( unsigned int x, unsigned int y,  unsigned  int  z,
240       unsigned int limit );
241
242       Description
243
244       pm_maxvaltobits()  and  pm_bitstomaxval()  convert between a maxval and
245       the minimum number of bits required to hold it.
246
247       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
251
252   Gamma Arithmetic
253       Entry Points
254
255       float pm_gamma709( float intensity );
256
257       float pm_ungamma709( float brightness );
258
259
260       Description
261
262       In graphics processing, there  are  two  common  ways  of  representing
263       numerically the intensity of a pixel, or a component of a pixel.
264
265       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
269
270
271       ·      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
282       ·      Monitor  inputs  and camera outputs aren't directly proportional
283              to
284                     the light intensity they project or detect.
285
286
287       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
294       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
298       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
303       pm_ungamma709 is the inverse of pm_gamma709.
304
305
306   Messages
307       Overview
308
309       void pm_message( char * fmt, ... );
310
311       void pm_setusermessagefn(pm_usermessagefn * function);
312
313       Description
314
315       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
327       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
331       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
337       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
341       To capture error messages in addition to  informational  messages,  see
342       pm_setusererrormsgfn() ⟨liberror.html#pm_setusererrormsgfn⟩ .
343
344       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
348       Example:
349
350           static pm_usermessagefn logfilewrite;
351
352           static void
353           logfilewrite(const char * const msg) {
354               fprintf(mymsglog, 'Netpbm message: %s', msg);
355           }
356
357           pm_setusermessagefn(&logfilewrite);
358
359           pm_message('Message for the message log');
360
361
362
363   System Utilities
364       ·
365
366              pm_system(1)
367
368       ·
369
370              pm_tmpfile(1)
371
372
373
374   Keyword Matching
375       Entry Points
376
377       void pm_keymatch();
378
379       Description
380
381       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
386       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.
389
390
391
392netpbm documentation            27 August 2006  Libnetbpm Utility Functions(3)
Impressum