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 "Libnetbpm Utility Functions" 3 "27 August 2006" "netpbm documentation" 7 8 9.PP 10 11.PP 12.UR #toc 13Table Of Contents 14.UE 15\& 16.PP 17These library functions are part of 18.BR "Netpbm" (1)\c 19\&. 20.PP 21This page documents functions in the Netpbm subroutine library that 22are not directly related to image data. 23.PP 24For introductory and general information using \fBlibnetpbm\fP, see 25.BR "Libnetpbm User's Guide" (3)\c 26\&. 27.PP 28The most commonly used \fBlibnetpbm\fP functions are those that 29read and write and process Netpbm images. Those are documented in 30.BR "Libnetpbm Netpbm Image Processing 31Manual" (3)\c 32\& 33.PP 34To use these services, #include \fBpam.h\fP. 35 36.UN functions 37.SH Functions 38 39.UN initialization 40.SS Initialization 41 42.B Overview 43.PP 44\fBvoid pm_init(\fP 45\fBconst char * \fP\fIprogname\fP\fB,\fP 46\fBunsigned int \fP\fIflags\fP 47\fB);\fP 48.PP 49\fBvoid pm_proginit(\fP 50\fBint * \fP\fIargcP\fP\fB,\fP 51\fBchar * \fP\fIargv\fP\fB[]\fP 52\fB);\fP 53 54.B Description 55.PP 56All Netpbm programs must call \fBpm_proginit()\fP just after 57startup, before they process their arguments. \fBpm_proginit()\fP, 58among other things, processes Netpbm universal arguments and removes 59them from the argument list. 60.PP 61A program that isn't a Netpbm program, but just uses \fBlibnetpbm\fP 62services, need not invoke \fBpm_proginit\fP. But such a program 63must invoke \fBpm_init()\fP. 64.PP 65By "Netpbm program," we mean a program that is part of 66the Netpbm package or is intended to act like one. \fBpm_proginit()\fP 67does things that all Netpbm programs do by convention. For example, 68it scans the argument list for 69.UR index.html#commonoptions 70 common options 71.UE 72\&, handles them, and removes them from the argument 73list. Ergo, if you want your program to have the same common options 74as those in the Netpbm package, you might use \fBpm_proginit()\fP, 75and if you don't, you must not. 76.PP 77\fBpm_proginit()\fP is primarily intended for Netpbm developers, 78so you should not expect it to have stable function across releases, 79and you must go to the comments in the source code to see exactly what 80it does. 81.PP 82Any program that uses \fBlibnetpbm\fP but does not call 83\fBpm_proginit\fP (i.e. is not a Netpbm program) must call 84\fBpm_init()\fP. The conventional place to do this is at the very 85beginning of the program. This sets up some program-global variables 86for use by the \fBlibnetpbm\fP functions. 87.PP 88The \fIprogname\fP argument is the program name for 89\fBlibnetpbm\fP functions to use in messages they issue. Normally, 90you would use argv[0] for this. 91.PP 92\fIflags\fP is meaningless, but for forward compatibility, you 93must set it to zero. 94.PP 95\fBpm_init()\fP and \fBpm_proginit()\fP have been around at least 96since Netpbm 9.25 (March 2002). Another function named 97\fBpm_init()\fP exists in older Netpbm, but was for internal use. 98Netpbm programs of that era use \fBpbm_init()\fP, etc to do what 99\fBpm_proginit()\fP does today. Today, \fBpbm_init()\fP, etc. exist 100for backward compatibility and are identical the \fBpm_proginit()\fP. 101 102 103.UN file 104.SS File Or Image Stream Access 105 106.B Overview 107.PP 108\fBFILE *pm_openr(\fP 109\fBchar *\fP \fIname\fP 110\fB);\fP 111.PP 112\fBFILE *pm_openw(\fP 113\fBchar *\fP \fIname\fP 114\fB);\fP 115.PP 116\fBFILE *pm_openr_seekable(\fP 117\fBconst char *\fP \fIname\fP 118\fB);\fP 119.PP 120\fBFILE *pm_close(\fP 121\fBFILE *\fP \fIfp\fP 122\fB);\fP 123.PP 124\fBvoid pm_tell2(\fP 125\fBFILE * \fP \fIfileP\fP\fB,\fP 126\fBpm_filepos *\fP \fIfileposP\fP\fB,\fP 127\fBunsigned int\fP \fIfileposSize\fP 128\fB);\fP 129.PP 130\fBunsigned int pm_tell(\fP 131\fBFILE *\fP \fIfileP\fP 132\fB);\fP 133.PP 134\fBvoid pm_seek2(\fP 135\fBFILE * \fP \fIfileP\fP\fB,\fP 136\fBconst pm_filepos *\fP \fIfileposP\fP\fB,\fP 137\fBunsigned int\fP \fIfileposSize\fP 138\fB);\fP 139.PP 140\fBvoid pm_seek(\fP 141\fBFILE * \fP \fIfileP\fP\fB,\fP 142\fBunsigned long\fP \fIfilepos\fP 143\fB);\fP 144.PP 145\fBchar *pm_read_unknown_size(\fP 146\fBFILE *\fP \fIfp\fP\fB,\fP 147\fBlong *\fP \fInread\fP 148\fB);\fP 149 150 151.B Description 152.PP 153An image stream is just a file stream (represented in the standard C 154library as type \fBFILE *\fP). 155.PP 156These routines work on files > 2 GiB if the underlying system does, 157using the standard large file interface. Before Netpbm 10.15 (April 2003), 158though, they would fail to open any file that large or process any offset 159in a file that could not be represented in 32 bits. 160.PP 161\fBpm_openr()\fP opens the given file for reading, with 162appropriate error checking. A filename of \fB-\fP is taken to mean 163Standard Input. \fBpm_openw()\fP opens the given file for writing, 164with appropriate error checking. \fBpm_close()\fP closes the file 165descriptor, with appropriate error checking. 166.PP 167\fBpm_openr_seekable()\fP appears to open the file just like 168\fBpm_openr()\fP, but the file thus opened is guaranteed to be 169seekable (you can use ftell() and fseek() on it). 170\fBpm_openr_seekable()\fP pulls this off by copying the entire file 171to a temporary file and giving you the handle of the temporary file, 172if it has to. If the file you name is a regular file, it's already 173seekable so \fBpm_openr_seekable()\fP just does the same thing as 174\fBpm_openr()\fP. 175 176But if it is, say, a pipe, it isn't seekable. So 177\fBpm_openr_seekable()\fP reads the pipe until EOF into a temporary 178file, then opens that temporary file and returns the handle of the 179temporary file. The temporary file is seekable. 180.PP 181 The file 182\fBpm_openr_seekable()\fP creates is one that the operating system 183recognizes as temporary, so when you close the file, by any means, it 184gets deleted. 185.PP 186You need a seekable file if you intend to make multiple passes through 187the file. The only alternative is to read the entire image into 188memory and work from that copy. That may use too much memory. Note 189that the image takes less space in the file cache than in a buffer in 190memory. As much as 96 times less space! Each sample is an integer in 191the buffer, which is usually 96 bits. In the file, a sample may be as 192small as 1 bit and rarely more than 8 bits. 193.PP 194\fBpm_tell2()\fP returns a handle for the current position of the 195image stream (file), whether it be the header or a row of the raster. 196Use the handle as an argument to \fBpm_seek2()\fP to reposition the 197file there later. The file must be seekable (which you can ensure by 198opening it with \fBpm_openr_seekable()\fP) or this may fail. 199.PP 200The file position handle is of type \fBpm_filepos\fP, which is 201intended to be opaque, i.e. used only with these two functions. In 202practice, it is a file offset and is 32 bits or 64 bits depending upon 203the capability of the underlying system. For maximum backward and 204forward compatibility, the functions that take or return a 205\fBpm_filepos\fP have a \fIfileposSize\fP argument for the size of 206the data structure. In C, simply code \fBsizeof(pm_filepos)\fP for 207that. 208.PP 209\fBpm_seek()\fP and \fBpm_tell\fP are for backward compatibility 210only. Do not use them in new code. These functions are not capable of 211handle positions in files whose byte offset cannot be represented in 32 212bits. 213.PP 214\fBpm_tell2()\fP and \fBpm_seek2()\fP replaced \fBpm_tell()\fP and 215\fBpm_seek()\fP in Netpbm 10.15 (April 2003). 216.PP 217\fBpm_read_unknown_size()\fP reads an entire file or input stream 218of unknown size to a buffer. It allocates more memory as needed. The 219calling routine has to free the allocated buffer with \fBfree()\fP. 220.PP 221\fBpm_read_unknown_size()\fP returns a pointer to the allocated 222buffer. The \fBnread\fP argument returns the number of bytes read. 223 224 225.UN endian 226.SS Endian I/O 227 228.B Entry Points 229.PP 230\fBvoid pm_readchar(\fP 231\fBFILE *\fP \fIin\fP\fB,\fP 232\fBchar *\fP \fIsP\fP 233\fB);\fP 234.PP 235\fBvoid pm_writechar(\fP 236\fBFILE *\fP \fIout\fP\fB,\fP 237\fBchar\fP \fIs\fP 238\fB);\fP 239.PP 240\fBint pm_readbigshort(\fP 241\fBFILE *\fP \fIin\fP\fB,\fP 242\fBshort *\fP \fIsP\fP 243\fB);\fP 244.PP 245\fBint pm_writebigshort(\fP 246\fBFILE *\fP \fIout\fP\fB,\fP 247\fBshort\fP \fIs\fP 248\fB);\fP 249.PP 250\fBint pm_readbiglong(\fP 251\fBFILE *\fP \fIin\fP\fB,\fP 252\fBlong *\fP \fIlP\fP 253\fB);\fP 254.PP 255\fBint pm_writebiglong(\fP 256\fBFILE *\fP \fIout\fP\fB,\fP 257\fBlong\fP \fIl\fP 258\fB);\fP 259.PP 260\fBint pm_readlittleshort(\fP 261\fBFILE *\fP \fIin\fP\fB,\fP 262\fBshort *\fP \fIsP\fP 263\fB);\fP 264.PP 265\fBint pm_writelittleshort(\fP 266\fBFILE *\fP \fIout\fP\fB,\fP 267\fBshort\fP \fIs\fP 268\fB);\fP 269.PP 270\fBint pm_readlittlelong(\fP 271\fBFILE *\fP \fIin\fP\fB,\fP 272\fBlong *\fP \fIlP\fP 273\fB);\fP 274.PP 275\fBint pm_writelittlelong(\fP 276\fBFILE *\fP \fIout\fP\fB,\fP 277\fBlong\fP \fIl\fP 278\fB);\fP 279.PP 280\fBvoid pm_readcharu(\fP 281\fBFILE *\fP \fIin\fP\fB,\fP 282\fBchar *\fP \fIsP\fP 283\fB);\fP 284.PP 285\fBvoid pm_writecharu(\fP 286\fBFILE *\fP \fIout\fP\fB,\fP 287\fBchar\fP \fIs\fP 288\fB);\fP 289.PP 290\fBint pm_readbigshortu(\fP 291\fBFILE *\fP \fIin\fP\fB,\fP 292\fBshort *\fP \fIsP\fP 293\fB);\fP 294.PP 295\fBint pm_writebigshortu(\fP 296\fBFILE *\fP \fIout\fP\fB,\fP 297\fBshort\fP \fIs\fP 298\fB);\fP 299.PP 300\fBint pm_readbiglongu(\fP 301\fBFILE *\fP \fIin\fP\fB,\fP 302\fBlong *\fP \fIlP\fP 303\fB);\fP 304.PP 305\fBint pm_writebiglongu(\fP 306\fBFILE *\fP \fIout\fP\fB,\fP 307\fBlong\fP \fIl\fP 308\fB);\fP 309.PP 310\fBint pm_readlittleshortu(\fP 311\fBFILE *\fP \fIin\fP\fB,\fP 312\fBshort *\fP \fIsP\fP 313\fB);\fP 314.PP 315\fBint pm_writelittleshortu(\fP 316\fBFILE *\fP \fIout\fP\fB,\fP 317\fBshort\fP \fIs\fP 318\fB);\fP 319.PP 320\fBint pm_readlittlelongu(\fP 321\fBFILE *\fP \fIin\fP\fB,\fP 322\fBlong *\fP \fIlP\fP 323\fB);\fP 324.PP 325\fBint pm_writelittlelongu(\fP 326\fBFILE *\fP \fIout\fP\fB,\fP 327\fBlong\fP \fIl\fP 328\fB);\fP 329 330.B Description 331 332\fBpm_readchar()\fP, \fBpm_writechar()\fP, \fBpm_readbigshort()\fP, 333\fBpm_writebigshort()\fP, \fBpm_readbiglong()\fP, 334\fBpm_writebiglong()\fP, \fBpm_readlittleshort()\fP, 335\fBpm_writelittleshort()\fP, \fBpm_readlittlelong()\fP, and 336\fBpm_writelittlelong()\fP are routines to read and write 1-byte, 3372-byte, and 4-byte pure binary integers in either big- or 338little-endian byte order. Note that a "long int" C type might 339be wider than 4 bytes, but the "long" routines still read and 340write 4 bytes. 341.PP 342\fBpm_readbiglongu()\fP, etc. (names ending in \fBu\fP) are the same 343except they work on unsigned versions of the type. 344.PP 345The routines with declared return values always return 0. Before 346Netpbm 10.27 (March 2005), they returned -1 on failure, including EOF. 347Now, they issue an error message to Standard Error and abort the program 348if the I/O fails or encounters EOF. 349.PP 350The 1-byte routines were new in Netpbm 10.27 (March 2005). 351The unsigned versions were new somewhere around Netpbm 10.21 (2004). 352 353.UN maxval 354.SS Maxval Arithmetic 355 356.B Entry Points 357.PP 358\fBint pm_maxvaltobits(\fP 359\fBint\fP \fImaxval\fP 360\fB);\fP 361.PP 362\fBint pm_bitstomaxval(\fP 363\fBint\fP \fIbits\fP 364\fB);\fP 365.PP 366\fBunsigned int pm_lcm(\fP 367\fBunsigned int\fP \fIx\fP\fB,\fP 368\fBunsigned int\fP \fIy\fP\fB,\fP 369\fBunsigned int\fP \fIz\fP\fB,\fP 370\fBunsigned int\fP \fIlimit\fP 371\fB);\fP 372 373.B Description 374.PP 375\fBpm_maxvaltobits()\fP and \fBpm_bitstomaxval()\fP convert 376between a maxval and the minimum number of bits required to hold it. 377.PP 378\fBpm_lcm()\fP computes the least common multiple of 3 integers. 379You also specify a limit and if the LCM would be higher than that 380limit, \fBpm_lcm()\fP just returns that limit. 381 382.UN gamma 383.SS Gamma Arithmetic 384 385.B Entry Points 386.PP 387\fBfloat pm_gamma709(\fP 388\fBfloat\fP \fIintensity\fP 389\fB);\fP 390.PP 391\fBfloat pm_ungamma709(\fP 392\fBfloat\fP \fIbrightness\fP 393\fB);\fP 394 395 396.B Description 397.PP 398In graphics processing, there are two common ways of representing 399numerically the intensity of a pixel, or a component of a pixel. 400.PP 401The obvious way is with a number that is directly proportional to 402the light intensity (e.g. 10 means twice as many milliwatts per square 403centimeter as 5). There are two problems with this: 404 405 406.IP \(bu 407To the human eye, a 1 milliwatt per square centimeter difference 408 in a bright image is much less apparent than a 1 milliwatt per 409 square centimeter difference in a dark image. So if you have 410 a fixed number of bits in which to store the intensity value, 411 you're wasting resolution at the bright end and skimping on it at 412 the dark end. 413.IP \(bu 414Monitor inputs and camera outputs aren't directly proportional to 415 the light intensity they project or detect. 416 417.PP 418For these reasons, light intensities are often represented in 419graphics processing by an exponential scale. The transfer function is 420called a gamma function and the resulting numbers are called 421gamma-corrected or gamma-adjusted. There are various gamma functions. 422The Netpbm formats specify that intensities are represented by 423gamma-adjusted numbers of a particular gamma transfer function. 424.PP 425These functions let you convert back and forth between these two 426scales, using the same gamma transfer function that is specified in the 427Netpbm format specifications. 428.PP 429\fBpm_gamma709\fP converts from an intensity-proportional intensity 430value to a gamma-adjusted intensity value (roughly proportional to 431brightness, which is the human subjective perception of intensity), 432using the ITU-R Recommendation BT.709 gamma transfer function. 433.PP 434\fBpm_ungamma709\fP is the inverse of \fBpm_gamma709\fP. 435 436.UN message 437.SS Messages 438 439.B Overview 440.PP 441\fBvoid pm_message(\fP 442\fBchar *\fP \fIfmt\fP\fB,\fP 443\fB... );\fP 444.PP 445\fBvoid pm_setusermessagefn(pm_usermessagefn *\fP \fIfunction\fP\fB);\fP 446 447.B Description 448.PP 449\fBpm_message()\fP is a \fBprintf()\fP style routine to write an 450informational message to the Standard Error file stream. 451\fBpm_message()\fP suppresses the message, however, if the user 452specified the \fB-quiet\fP 453.UR index.html#commonoptions 454common option 455.UE 456\& on the command line. Note that Netpbm programs are often 457used interactively, but also often used by programs. In the 458interactive case, it is nice to issue messages about what the program 459is doing, but in the program case, such messages are usually 460undesirable. By using \fBpm_message()\fP for all your messages, you 461make your program usable in both cases. Without any effort on your 462part, program users of your program can avoid the messages by 463specifying the \fB-quiet\fP option. 464.PP 465Netpbm distinguishes between error messages and information 466messages; \fBpm_message()\fP is just for informational messages. To 467issue an error message, see 468.UR liberror.html#pm_errormsg 469\fBpm_errormsg()\fP 470.UE 471\&. 472.PP 473\fBpm_setusermessagefn\fP registers a handler for informational 474messages, called a user message routine. Any library function 475(including \fBpm_message()\fP) that wants to issue an informational 476message in the future will call that function with the message as an 477argument instead of writing the message to Standard Error. 478.PP 479The argument the user message routine gets is English text designed 480for human reading. It is just the text of the message; there is no 481attempt at formatting in it (so you won't see any newline or tab 482characters). 483.PP 484To capture error messages in addition to informational messages, 485see 486.UR liberror.html#pm_setusererrormsgfn 487\fBpm_setusererrormsgfn()\fP 488.UE 489\&. 490.PP 491You can remove the user message routine, so that the library issues 492future informational messages in its default way (write to Standard 493Error) by specifying a null pointer for \fIfunction\fP. 494 495Example: 496 497.nf 498\f(CW 499 static pm_usermessagefn logfilewrite; 500 501 static void 502 logfilewrite(const char * const msg) { 503 fprintf(mymsglog, "Netpbm message: %s", msg); 504 } 505 506 pm_setusermessagefn(&logfilewrite); 507 508 pm_message("Message for the message log"); 509\fP 510.fi 511 512 513.UN system 514.SS System Utilities 515 516 517.IP \(bu 518 519.BR "pm_system" (3)\c 520\& 521.IP \(bu 522 523.BR "pm_tmpfile" (3)\c 524\& 525 526 527.UN keyword 528.SS Keyword Matching 529 530.B Entry Points 531.PP 532\fBvoid pm_keymatch();\fP 533 534.B Description 535.PP 536This subroutine is obsolete. It used to be used for command line 537option processing. Today, you can do better option processing more 538easily with the shhopt facility. See any recent program in the Netpbm 539package for an example. 540 541\fBpm_keymatch()\fP does a case-insensitive match of \fBstr\fP 542against \fBkeyword\fP. \fBstr\fP can be a leading substring of 543\fBkeyword\fP, but at least \fBminchars\fP must be present. 544.SH DOCUMENT SOURCE 545This manual page was generated by the Netpbm tool 'makeman' from HTML 546source. The master documentation is at 547.IP 548.B http://netpbm.sourceforge.net/doc/libpm.html 549.PP