1 Linux Standard Base Printing Specification 3.2 2 3 Copyright © 2007 Linux Foundation 4 5 Permission is granted to copy, distribute and/or modify this 6 document under the terms of the GNU Free Documentation License, 7 Version 1.1; with no Invariant Sections, with no Front-Cover 8 Texts, and with no Back-Cover Texts. A copy of the license is 9 included in the section entitled "GNU Free Documentation 10 License". 11 12 Portions of the text may be copyrighted by the following 13 parties: 14 15 * The Regents of the University of California 16 * Free Software Foundation 17 * Ian F. Darwin 18 * Paul Vixie 19 * BSDI (now Wind River) 20 * Andrew G Morgan 21 * Jean-loup Gailly and Mark Adler 22 * Massachusetts Institute of Technology 23 * Apple Inc. 24 * Easy Software Products 25 * artofcode LLC 26 * Till Kamppeter 27 * Manfred Wassman 28 * Python Software Foundation 29 30 These excerpts are being used in accordance with their 31 respective licenses. 32 33 Linux is the registered trademark of Linus Torvalds in the U.S. 34 and other countries. 35 36 UNIX is a registered trademark of The Open Group. 37 38 LSB is a trademark of the Linux Foundation in the United States 39 and other countries. 40 41 AMD is a trademark of Advanced Micro Devices, Inc. 42 43 Intel and Itanium are registered trademarks and Intel386 is a 44 trademark of Intel Corporation. 45 46 PowerPC is a registered trademark and PowerPC Architecture is a 47 trademark of the IBM Corporation. 48 49 S/390 is a registered trademark of the IBM Corporation. 50 51 OpenGL is a registered trademark of Silicon Graphics, Inc. 52 __________________________________________________________ 53 54 Table of Contents 55 Foreword 56 Introduction 57 I. Introductory Elements 58 59 1. Scope 60 2. Normative References 61 3. Requirements 62 63 3.1. Relevant Libraries 64 65 4. Definitions 66 5. Terminology 67 6. PPD Format Extensions 68 69 II. LSB Printing Libraries 70 71 7. Libraries 72 73 7.1. Interfaces for libcups 74 7.2. Data Definitions for libcups 75 7.3. Interface Definitions for libcups 76 7.4. Interfaces for libcupsimage 77 7.5. Data Definitions for libcupsimage 78 7.6. Interface Definitions for libcupsimage 79 80 III. Printing Commands 81 82 8. Printing Commands 83 84 8.1. Printing Commands 85 8.2. Command Behavior 86 87 A. GNU Free Documentation License (Informative) 88 89 A.1. PREAMBLE 90 A.2. APPLICABILITY AND DEFINITIONS 91 A.3. VERBATIM COPYING 92 A.4. COPYING IN QUANTITY 93 A.5. MODIFICATIONS 94 A.6. COMBINING DOCUMENTS 95 A.7. COLLECTIONS OF DOCUMENTS 96 A.8. AGGREGATION WITH INDEPENDENT WORKS 97 A.9. TRANSLATION 98 A.10. TERMINATION 99 A.11. FUTURE REVISIONS OF THIS LICENSE 100 A.12. How to use this License for your documents 101 102 List of Tables 103 2-1. Normative References 104 3-1. Standard Library Names 105 7-1. libcups Definition 106 7-2. libcups - CUPS Convenience ABI Function Interfaces 107 7-3. libcupsimage Definition 108 7-4. libcupsimage - CUPS Raster ABI Function Interfaces 109 8-1. Commands And Utilities 110 __________________________________________________________ 111 112 Foreword 113 114 This is version 3.2 of the LSB-Printing Module Specification. 115 116 An implementation of this version of the specification may not 117 claim to be an implementation of LSB-Printing Module unless it 118 has successfully completed the compliance process as defined by 119 the Linux Foundation. 120 __________________________________________________________ 121 122 Introduction 123 124 The LSB-Printing Module defines the multimedia components that 125 are required to be present on a conforming system. 126 127 This document should be used in conjunction with the documents 128 it references. Information referenced in this way is as much a 129 part of this document as is the information explicitly included 130 here. 131 132 I. Introductory Elements 133 134 Table of Contents 135 1. Scope 136 2. Normative References 137 3. Requirements 138 139 3.1. Relevant Libraries 140 141 4. Definitions 142 5. Terminology 143 6. PPD Format Extensions 144 __________________________________________________________ 145 146 Chapter 1. Scope 147 148 The LSB-Printing module defines the multimedia components found 149 on an LSB conforming system. 150 __________________________________________________________ 151 152 Chapter 2. Normative References 153 154 The specifications listed below are referenced in whole or in 155 part by the LSB-Printing Module Standard. Such references may 156 be normative or informative; a reference to specification shall 157 only be considered normative if it is explicitly cited as such. 158 The LSB-Printing Module may make normative references to a 159 portion of these specifications (that is, to define a specific 160 function or group of functions); in such cases, only the 161 explicitly referenced portion of the specification is to be 162 considered normative. 163 164 Table 2-1. Normative References 165 Name Title URL 166 ISO C (1999) ISO/IEC 9899: 1999, Programming Languages --C 167 PPD Specification PostScript Printer Description File Format 168 Specification version 4.3 169 http://partners.adobe.com/public/developer/en/ps/5003.PPD_Spec_ 170 v4.3.pdf 171 PPD Specification Update Update to PPD Specification Version 172 4.3 173 http://partners.adobe.com/public/developer/en/ps/5645.PPD_Updat 174 e.pdf 175 __________________________________________________________ 176 177 Chapter 3. Requirements 178 179 3.1. Relevant Libraries 180 181 The libraries listed in Table 3-1 shall be available on a Linux 182 Standard Base system, with the specified runtime names. This 183 list may be supplemented or amended by the 184 architecture-specific specification. 185 186 Table 3-1. Standard Library Names 187 Library Runtime Name 188 libcups libcups.so.2 189 libcupsimage libcupsimage.so.2 190 191 These libraries will be in an implementation-defined directory 192 which the dynamic linker shall search by default. 193 __________________________________________________________ 194 195 Chapter 4. Definitions 196 197 For the purposes of this document, the following definitions, 198 as specified in the ISO/IEC Directives, Part 2, 2001, 4th 199 Edition, apply: 200 201 can 202 203 be able to; there is a possibility of; it is possible to 204 cannot 205 206 be unable to; there is no possibility of; it is not possible to 207 may 208 209 is permitted; is allowed; is permissible 210 need not 211 212 it is not required that; no...is required 213 shall 214 215 is to; is required to; it is required that; has to; only...is 216 permitted; it is necessary 217 shall not 218 219 is not allowed [permitted] [acceptable] [permissible]; is 220 required to be not; is required that...be not; is not to be 221 should 222 223 it is recommended that; ought to 224 should not 225 226 it is not recommended that; ought not to 227 __________________________________________________________ 228 229 Chapter 5. Terminology 230 231 For the purposes of this document, the following terms apply: 232 233 implementation-defined 234 Describes a value or behavior that is not defined by 235 this document but is selected by an implementor. The 236 value or behavior may vary among implementations that 237 conform to this document. An application should not rely 238 on the existence of the value or behavior. An 239 application that relies on such a value or behavior 240 cannot be assured to be portable across conforming 241 implementations. The implementor shall document such a 242 value or behavior so that it can be used correctly by an 243 application. 244 245 Shell Script 246 A file that is read by an interpreter (e.g., awk). The 247 first line of the shell script includes a reference to 248 its interpreter binary. 249 250 undefined 251 Describes the nature of a value or behavior not defined 252 by this document which results from use of an invalid 253 program construct or invalid data input. The value or 254 behavior may vary among implementations that conform to 255 this document. An application should not rely on the 256 existence or validity of the value or behavior. An 257 application that relies on any particular value or 258 behavior cannot be assured to be portable across 259 conforming implementations. 260 261 unspecified 262 Describes the nature of a value or behavior not 263 specified by this document which results from use of a 264 valid program construct or valid data input. The value 265 or behavior may vary among implementations that conform 266 to this document. An application should not rely on the 267 existence or validity of the value or behavior. An 268 application that relies on any particular value or 269 behavior cannot be assured to be portable across 270 conforming implementations. 271 __________________________________________________________ 272 273 Chapter 6. PPD Format Extensions 274 275 The Postscript Printer Description (PPD) format is used in a 276 text file to describe device capabilities for a printing 277 device. PPD files shall conform to the format described by PPD 278 Specification and PPD Specification Update. In addition, 279 several extensions to the standard attribute list are 280 recognized, as listed below. The "cupsVersion" attribute is 281 required in a compliant PPD, while the other attributes are 282 optional. 283 284 cupsColorProfile 285 This string attribute specifies an sRGB-based color 286 profile consisting of gamma and density controls and a 287 3x3 CMY color transform matrix. 288 289 The attribute has the following parameter usage: 290 291 *cupsColorProfile Resolution/MediaType: "density gamma 292 m00 m01 m02 m10 m11 m12 m20 m21 m22" 293 294 The Resolution and MediaType values may be "-" to act as 295 a wildcard. Otherwise, they must match one of the 296 Resolution or MediaType attributes defined in the PPD 297 file. 298 299 The density and gamma values define the gamma and 300 density adjustment function such that (in terms of C 301 math): 302 303 f(x) = density * pow(x, gamma) 304 305 The m00 through m22 values define a 3x3 transformation 306 matrix for the CMY color values. The density function is 307 applied after the CMY transformation: 308 309 | m00 m01 m02 | | m10 m11 m12 | | m20 m21 m22 | 310 311 cupsFax 312 This boolean attribute specifies whether the PPD defines 313 a facsimile device. The default is false. 314 315 cupsFilter 316 The attribute has the following parameter usage: 317 318 *cupsFilter: "source/type cost program" 319 320 This string attribute provides a conversion rule from 321 the given source type to the printer's native format 322 using the filter "program". A source type is specified 323 according to the conventions of the MIME specification, 324 using "type/subtype" nomenclature, and may refer to a 325 standard MIME type or a CUPS-specific MIME type using 326 the prefix "vnd.cups-" in the subtype. If a printer 327 supports the source type directly, the special filter 328 program "-" may be specified. The cost is an arbitrary 329 positive integer, used to calculate the relative impact 330 a print job has on system load. 331 332 cupsManualCopies 333 This boolean attribute notifies the RIP filters that the 334 destination printer does not support copy generation in 335 hardware. The default value is false. 336 337 cupsModelNumber 338 This integer attribute specifies a printer-specific 339 model number. This number can be used by a filter 340 program to adjust the output for a specific model of 341 printer. 342 343 cupsVersion 344 The attribute has the following parameter usage: 345 346 *cupsVersion: "major.minor" 347 348 This required attribute describes which version of the 349 CUPS PPD file extensions was used. Currently it must be 350 the string "1.0" or "1.1". The strings "1.2" and "1.3" 351 represent newer versions of the CUPS PPD API that are 352 not covered in this version of the specification, and 353 are currently not allowed, although they may be found in 354 non-conforming PPDs which use a newer version of the 355 CUPS PPD specification. 356 357 FoomaticIDs 358 The attribute has the following parameter usage: 359 360 *FoomaticIDs printer driver 361 362 The parameters correspond to the IDs in the Foomatic 363 database for the printer and driver, respectively. 364 365 FoomaticNoPageAccounting 366 This boolean attribute tells foomatic-rip whether or not 367 to insert accounting information into the PostScript 368 data stream. By default, foomatic-rip will insert this 369 information. 370 371 FoomaticRIPCommandLine 372 The attribute has the following parameter usage: 373 374 *FoomaticRIPCommandLine "code" 375 376 This attribute defines the command line in the "code" 377 parameter for the renderer that is called by 378 foomatic-rip. The command must take PostScript on 379 standard input and provide the job data stream in the 380 printer's native language on standard output. The 381 command must exit with status 0 if the conversion was 382 successful and exit with another status if an error 383 occurs. The "code" parameter may contain option setting 384 wildcards, as described below under "FoomaticRIPOption". 385 386 FoomaticRIPDefault 387 The attribute has the following parameter usage: 388 389 *FoomaticRIPDefaultOptionName value 390 391 This attribute sets a default for a Foomatic option. The 392 name of the attribute should contain the name of the 393 option appended to "FoomaticRIPDefault", with the 394 desired default value as the only parameter. 395 396 This option is only used to provide numeric options in 397 the PPD, which are not supported by the Adobe spec, via 398 enumerated options, and should not be used except for 399 that purpose. 400 401 FoomaticRIPOption 402 The attribute has the following parameter usage: 403 404 *FoomaticRIPOption name: type style spot [order] 405 406 This attribute sets options for the command line 407 specified in the "FoomaticRIPCommandLine" attribute. The 408 "name" parameter specifies the option name, the "type" 409 parameter specifies the option type, the "style" 410 parameter specifies one of "CmdLine", "JCL", "PS", or 411 "Composite", and the "spot" parameter specifies a 412 letter, which is prepended with a "%" and used in the 413 "FoomaticRIPCommandLine" attribute to indicate where the 414 option should go in the command line. The optional 415 "order" parameter indicates an order number for 416 one-choice options. 417 418 FoomaticRIPOptionAllowedChars 419 The attribute has the following parameter usage: 420 421 *FoomaticRIPOptionAllowedChars name: "code" 422 423 This option sets a list of allowed characters in a 424 string option. The "name" parameter identifies the 425 option, while the "code" parameter is a list of allowed 426 characters. 427 428 FoomaticRIPOptionAllowedRegExp 429 The attribute has the following parameter usage: 430 431 *FoomaticRIPOptionAllowedRegExp name: "code" 432 433 This option causes the option named by "name" to be 434 validated by the Perl-style regular expression in 435 "code". 436 437 FoomaticRIPOptionMaxLength 438 The attribute has the following parameter usage: 439 440 *FoomaticRIPOptionMaxLength name: length 441 442 For string or password options, this attribute sets a 443 maximum length which can be returned. The "name" 444 parameter identifies the option, and the "length" 445 parameter is the maximum number of characters allowed. 446 447 FoomaticRIPOptionPrototype 448 The attribute has the following parameter usage: 449 450 *FoomaticRIPOptionPrototype name: "code" 451 452 For string, password, or simulated numeric options, this 453 attribute sets a code prototype to be inserted into the 454 output. This works for options where the 455 FoomaticRIPOption "style" parameter is set to CmdLine, 456 JCL, or PS. The value of the option can be represented 457 with the string "%s" in the "code" parameter. 458 459 FoomaticRIPOptionRange 460 The attribute has the following parameter usage: 461 462 *FoomaticRIPOptionRange name: min max 463 464 This attribute adds a minimux and maximum limit to 465 numeric options (that are simulated by Foomatic via 466 emumerated options). The "name" parameter identifies the 467 option, while the "min" and "max" parameters set the 468 minumum and maximum allowed values, respectively, for 469 the option. 470 471 FoomaticRIPOptionSetting 472 The attribute has the following parameter usage: 473 474 *FoomaticRIPOptionSetting name=choice: "code" 475 476 This attribute adds code to an option, identified by 477 "name", with a FoomaticRIPOption "style" parameter set 478 to Composite. It inserts options for other options that 479 are members of the Composite option "name". 480 481 FoomaticRIPPostPipe 482 The attribute has the following parameter usage: 483 484 *FoomaticRIPPostPipe "code" 485 486 This attribute defines the command line in the "code" 487 parameter for the job output command used by 488 foomatic-rip in standalone mode. The command should take 489 printer-native data on standard input. The "code" 490 parameter should include the preceding shell pipe symbol 491 ("|"). 492 493 II. LSB Printing Libraries 494 495 Table of Contents 496 7. Libraries 497 498 7.1. Interfaces for libcups 499 500 7.1.1. CUPS Convenience ABI 501 502 7.2. Data Definitions for libcups 503 504 7.2.1. cups/cups.h 505 7.2.2. cups/ppd.h 506 507 7.3. Interface Definitions for libcups 508 509 cupsAddDest -- Add a destination to the list of 510 destinations. 511 512 cupsAddOption -- Add an option to an option array. 513 cupsCancelJob -- Cancel a print job on the default 514 server. 515 516 cupsEncryption -- Get the default encryption 517 settings. 518 519 cupsFreeDests -- Free the memory used by the list of 520 destinations. 521 522 cupsFreeJobs -- Free memory used by job data. 523 cupsFreeOptions -- Free all memory used by options. 524 cupsGetDefault -- Get the default printer or class 525 for the default server. 526 527 cupsGetDest -- Get the named destination from the 528 list. 529 530 cupsGetDests -- Get the list of destinations from 531 the default server. 532 533 cupsGetJobs -- Get the jobs from the default server. 534 cupsGetOption -- Get an option value. 535 cupsGetPPD -- Get the PPD file for a printer on the 536 default server. 537 538 cupsGetPassword -- Get a password from the user. 539 cupsLangEncoding -- Return the character encoding 540 (us-ascii, etc.) 541 542 cupsLangFlush -- Flush all language data out of the 543 cache. 544 545 cupsLangFree -- Free language data. 546 cupsLangGet -- Get a language. 547 cupsLastError -- Return the last IPP status code. 548 cupsMarkOptions -- Mark command-line options in a 549 PPD file. 550 551 cupsParseOptions -- Parse options from a 552 command-line argument. 553 554 cupsPrintFile -- Print a file to a printer or class 555 on the default server. 556 557 cupsPrintFiles -- Print one or more files to a 558 printer or class on the 559 560 cupsServer -- Return the hostname/address of the 561 default server. 562 563 cupsSetDests -- Save the list of destinations for 564 the default server. 565 566 cupsSetEncryption -- Set the encryption preference. 567 cupsSetPasswordCB -- Set the password callback for 568 CUPS. 569 570 cupsSetServer -- Set the default server name. 571 cupsSetUser -- Set the default user name. 572 cupsTempFd -- Creates a temporary file. 573 cupsUser -- Return the current user's name. 574 ppdClose -- Free all memory used by the PPD file. 575 ppdCollect -- Collect all marked options that reside 576 in the specified 577 578 ppdConflicts -- Check to see if there are any 579 conflicts. 580 581 ppdEmit -- Emit code for marked options to a file. 582 ppdEmitFd -- Emit code for marked options to a file. 583 ppdEmitJCL -- Emit code for JCL options to a file. 584 ppdErrorString -- Returns the text assocated with a 585 status. 586 587 ppdFindAttr -- Find the first matching attribute... 588 ppdFindChoice -- Return a pointer to an option 589 choice. 590 591 ppdFindMarkedChoice -- Return the marked choice for 592 the specified option. 593 594 ppdFindNextAttr -- Find the next matching 595 attribute... 596 597 ppdFindOption -- Return a pointer to the specified 598 option. 599 600 ppdIsMarked -- Check to see if an option is 601 marked... 602 603 ppdLastError -- Return the status from the last 604 ppdOpen*(). 605 606 ppdMarkDefaults -- Mark all default options in the 607 PPD file. 608 609 ppdMarkOption -- Mark an option in a PPD file. 610 ppdOpen -- Read a PPD file into memory. 611 ppdOpenFd -- Read a PPD file into memory. 612 ppdOpenFile -- Read a PPD file into memory. 613 ppdPageLength -- Get the page length for the given 614 size. 615 616 ppdPageSize -- Get the page size record for the 617 given size. 618 619 ppdPageWidth -- Get the page width for the given 620 size. 621 622 ppdSetConformance -- Set the conformance level for 623 PPD files. 624 625 7.4. Interfaces for libcupsimage 626 627 7.4.1. CUPS Raster ABI 628 629 7.5. Data Definitions for libcupsimage 630 631 7.5.1. cups/raster.h 632 633 7.6. Interface Definitions for libcupsimage 634 635 cupsRasterClose -- Close a raster stream. 636 cupsRasterOpen -- Open a raster stream. 637 cupsRasterReadHeader -- Read a raster page header 638 and store it in a 639 640 cupsRasterReadPixels -- Read raster pixels. 641 cupsRasterWriteHeader -- Write a raster page header 642 from a V1 page 643 644 cupsRasterWritePixels -- Write raster pixels. 645 __________________________________________________________ 646 647 Chapter 7. Libraries 648 649 7.1. Interfaces for libcups 650 651 Table 7-1 defines the library name and shared object name for 652 the libcups library 653 654 Table 7-1. libcups Definition 655 Library: libcups 656 SONAME: libcups.so.2 657 658 The behavior of the interfaces in this library is specified by 659 the following specifications: 660 661 [LSB] This Specification 662 __________________________________________________________ 663 664 7.1.1. CUPS Convenience ABI 665 __________________________________________________________ 666 667 7.1.1.1. Interfaces for CUPS Convenience ABI 668 669 An LSB conforming implementation shall provide the generic 670 functions for CUPS Convenience ABI specified in Table 7-2, with 671 the full mandatory functionality as described in the referenced 672 underlying specification. 673 674 Table 7-2. libcups - CUPS Convenience ABI Function Interfaces 675 cupsAddDest [LSB] cupsAddOption [LSB] cupsCancelJob [LSB] 676 cupsEncryption [LSB] 677 cupsFreeDests [LSB] cupsFreeJobs [LSB] cupsFreeOptions [LSB] 678 cupsGetDefault [LSB] 679 cupsGetDest [LSB] cupsGetDests [LSB] cupsGetJobs [LSB] 680 cupsGetOption [LSB] 681 cupsGetPPD [LSB] cupsGetPassword [LSB] cupsLangEncoding [LSB] 682 cupsLangFlush [LSB] 683 cupsLangFree [LSB] cupsLangGet [LSB] cupsLastError [LSB] 684 cupsMarkOptions [LSB] 685 cupsParseOptions [LSB] cupsPrintFile [LSB] cupsPrintFiles [LSB] 686 cupsServer [LSB] 687 cupsSetDests [LSB] cupsSetEncryption [LSB] cupsSetPasswordCB 688 [LSB] cupsSetServer [LSB] 689 cupsSetUser [LSB] cupsTempFd [LSB] cupsUser [LSB] ppdClose 690 [LSB] 691 ppdCollect [LSB] ppdConflicts [LSB] ppdEmit [LSB] ppdEmitFd 692 [LSB] 693 ppdEmitJCL [LSB] ppdErrorString [LSB] ppdFindAttr [LSB] 694 ppdFindChoice [LSB] 695 ppdFindMarkedChoice [LSB] ppdFindNextAttr [LSB] ppdFindOption 696 [LSB] ppdIsMarked [LSB] 697 ppdLastError [LSB] ppdMarkDefaults [LSB] ppdMarkOption [LSB] 698 ppdOpen [LSB] 699 ppdOpenFd [LSB] ppdOpenFile [LSB] ppdPageLength [LSB] 700 ppdPageSize [LSB] 701 ppdPageWidth [LSB] ppdSetConformance [LSB] 702 __________________________________________________________ 703 704 7.2. Data Definitions for libcups 705 706 This section defines global identifiers and their values that 707 are associated with interfaces contained in libcups. These 708 definitions are organized into groups that correspond to system 709 headers. This convention is used as a convenience for the 710 reader, and does not imply the existence of these headers, or 711 their content. Where an interface is defined as requiring a 712 particular system header file all of the data definitions for 713 that system header file presented here shall be in effect. 714 715 This section gives data definitions to promote binary 716 application portability, not to repeat source interface 717 definitions available elsewhere. System providers and 718 application developers should use this ABI to supplement - not 719 to replace - source interface definition specifications. 720 721 This specification uses the ISO C (1999) C Language as the 722 reference programming language, and data definitions are 723 specified in ISO C format. The C language is used here as a 724 convenient notation. Using a C language description of these 725 data objects does not preclude their use by other programming 726 languages. 727 __________________________________________________________ 728 729 7.2.1. cups/cups.h 730 731 #define _CUPS_CUPS_H_ 732 #define CUPS_VERSION_MAJOR 1 733 #define CUPS_VERSION_MINOR 1 734 #define CUPS_VERSION 1.0123 735 #define CUPS_VERSION_PATCH 23 736 #define cupsLangDefault() cupsLangGet(NULL) 737 738 typedef enum { 739 CUPS_AUTO_ENCODING = -1, 740 CUPS_US_ASCII = 0, 741 CUPS_ISO8859_1 = 1, 742 CUPS_ISO8859_2 = 2, 743 CUPS_ISO8859_3 = 3, 744 CUPS_ISO8859_4 = 4, 745 CUPS_ISO8859_5 = 5, 746 CUPS_ISO8859_6 = 6, 747 CUPS_ISO8859_7 = 7, 748 CUPS_ISO8859_8 = 8, 749 CUPS_ISO8859_9 = 9, 750 CUPS_ISO8859_10 = 10, 751 CUPS_UTF8 = 11, 752 CUPS_ISO8859_13 = 12, 753 CUPS_ISO8859_14 = 13, 754 CUPS_ISO8859_15 = 14, 755 CUPS_WINDOWS_874 = 15, 756 CUPS_WINDOWS_1250 = 16, 757 CUPS_WINDOWS_1251 = 17, 758 CUPS_WINDOWS_1252 = 18, 759 CUPS_WINDOWS_1253 = 19, 760 CUPS_WINDOWS_1254 = 20, 761 CUPS_WINDOWS_1255 = 21, 762 CUPS_WINDOWS_1256 = 22, 763 CUPS_WINDOWS_1257 = 23, 764 CUPS_WINDOWS_1258 = 24, 765 CUPS_KOI8_R = 25, 766 CUPS_KOI8_U = 26 767 } cups_encoding_t; 768 typedef struct cups_lang_str { 769 struct cups_lang_str *next; 770 int used; 771 cups_encoding_t encoding; 772 char language[16]; 773 char *messages[506]; 774 } cups_lang_t; 775 typedef enum { 776 HTTP_ENCRYPT_IF_REQUESTED = 0, 777 HTTP_ENCRYPT_NEVER = 1, 778 HTTP_ENCRYPT_REQUIRED = 2, 779 HTTP_ENCRYPT_ALWAYS = 3 780 } http_encryption_t; 781 typedef struct { 782 char *name; 783 char *value; 784 } cups_option_t; 785 typedef struct { 786 char *name; 787 char *instance; 788 int is_default; 789 int num_options; 790 cups_option_t *options; 791 } cups_dest_t; 792 typedef enum { 793 HTTP_WAITING = 0, 794 HTTP_OPTIONS = 1, 795 HTTP_GET = 2, 796 HTTP_GET_SEND = 3, 797 HTTP_HEAD = 4, 798 HTTP_POST = 5, 799 HTTP_POST_RECV = 6, 800 HTTP_POST_SEND = 7, 801 HTTP_PUT = 8, 802 HTTP_PUT_RECV = 9, 803 HTTP_DELETE = 10, 804 HTTP_TRACE = 11, 805 HTTP_CLOSE = 12, 806 HTTP_STATUS = 13 807 } http_state_t; 808 typedef enum { 809 HTTP_ERROR = -1, 810 HTTP_CONTINUE = 100, 811 HTTP_SWITCHING_PROTOCOLS = 101, 812 HTTP_OK = 200, 813 HTTP_CREATED = 201, 814 HTTP_ACCEPTED = 202, 815 HTTP_NOT_AUTHORITATIVE = 203, 816 HTTP_NO_CONTENT = 204, 817 HTTP_RESET_CONTENT = 205, 818 HTTP_PARTIAL_CONTENT = 206, 819 HTTP_MULTIPLE_CHOICES = 300, 820 HTTP_MOVED_PERMANENTLY = 301, 821 HTTP_MOVED_TEMPORARILY = 302, 822 HTTP_SEE_OTHER = 303, 823 HTTP_NOT_MODIFIED = 304, 824 HTTP_USE_PROXY = 305, 825 HTTP_BAD_REQUEST = 400, 826 HTTP_UNAUTHORIZED = 401, 827 HTTP_PAYMENT_REQUIRED = 402, 828 HTTP_FORBIDDEN = 403, 829 HTTP_NOT_FOUND = 404, 830 HTTP_METHOD_NOT_ALLOWED = 405, 831 HTTP_NOT_ACCEPTABLE = 406, 832 HTTP_PROXY_AUTHENTICATION = 407, 833 HTTP_REQUEST_TIMEOUT = 408, 834 HTTP_CONFLICT = 409, 835 HTTP_GONE = 410, 836 HTTP_LENGTH_REQUIRED = 411, 837 HTTP_PRECONDITION = 412, 838 HTTP_REQUEST_TOO_LARGE = 413, 839 HTTP_URI_TOO_LONG = 414, 840 HTTP_UNSUPPORTED_MEDIATYPE = 415, 841 HTTP_UPGRADE_REQUIRED = 426, 842 HTTP_SERVER_ERROR = 500, 843 HTTP_NOT_IMPLEMENTED = 501, 844 HTTP_BAD_GATEWAY = 502, 845 HTTP_SERVICE_UNAVAILABLE = 503, 846 HTTP_GATEWAY_TIMEOUT = 504, 847 HTTP_NOT_SUPPORTED = 505 848 } http_status_t; 849 typedef enum { 850 HTTP_0_9 = 9, 851 HTTP_1_0 = 100, 852 HTTP_1_1 = 101 853 } http_version_t; 854 typedef enum { 855 HTTP_KEEPALIVE_OFF = 0, 856 HTTP_KEEPALIVE_ON = 1 857 } http_keepalive_t; 858 typedef enum { 859 HTTP_ENCODE_LENGTH = 0, 860 HTTP_ENCODE_CHUNKED = 1 861 } http_encoding_t; 862 typedef unsigned int md5_word_t; 863 typedef unsigned char md5_byte_t; 864 typedef struct md5_state_s { 865 md5_word_t count[2]; 866 md5_word_t abcd[4]; 867 md5_byte_t buf[64]; 868 } md5_state_t; 869 typedef enum { 870 IPP_JOB_PENDING = 3, 871 IPP_JOB_HELD = 4, 872 IPP_JOB_PROCESSING = 5, 873 IPP_JOB_STOPPED = 6, 874 IPP_JOB_CANCELLED = 7, 875 IPP_JOB_ABORTED = 8, 876 IPP_JOB_COMPLETED = 9 877 } ipp_jstate_t; 878 typedef struct { 879 int id; 880 char *dest; 881 char *title; 882 char *user; 883 char *format; 884 ipp_jstate_t state; 885 int size; 886 int priority; 887 time_t completed_time; 888 time_t creation_time; 889 time_t processing_time; 890 } cups_job_t; 891 typedef enum { 892 IPP_OK = 0, 893 IPP_OK_SUBST = 1, 894 IPP_OK_CONFLICT = 2, 895 IPP_OK_IGNORED_SUBSCRIPTIONS = 3, 896 IPP_OK_IGNORED_NOTIFICATIONS = 4, 897 IPP_OK_TOO_MANY_EVENTS = 5, 898 IPP_OK_BUT_CANCEL_SUBSCRIPTION = 6, 899 IPP_REDIRECTION_OTHER_SITE = 768, 900 IPP_BAD_REQUEST = 1024, 901 IPP_FORBIDDEN = 1025, 902 IPP_NOT_AUTHENTICATED = 1026, 903 IPP_NOT_AUTHORIZED = 1027, 904 IPP_NOT_POSSIBLE = 1028, 905 IPP_TIMEOUT = 1029, 906 IPP_NOT_FOUND = 1030, 907 IPP_GONE = 1031, 908 IPP_REQUEST_ENTITY = 1032, 909 IPP_REQUEST_VALUE = 1033, 910 IPP_DOCUMENT_FORMAT = 1034, 911 IPP_ATTRIBUTES = 1035, 912 IPP_URI_SCHEME = 1036, 913 IPP_CHARSET = 1037, 914 IPP_CONFLICT = 1038, 915 IPP_COMPRESSION_NOT_SUPPORTED = 1039, 916 IPP_COMPRESSION_ERROR = 1040, 917 IPP_DOCUMENT_FORMAT_ERROR = 1041, 918 IPP_DOCUMENT_ACCESS_ERROR = 1042, 919 IPP_ATTRIBUTES_NOT_SETTABLE = 1043, 920 IPP_IGNORED_ALL_SUBSCRIPTIONS = 1044, 921 IPP_TOO_MANY_SUBSCRIPTIONS = 1045, 922 IPP_IGNORED_ALL_NOTIFICATIONS = 1046, 923 IPP_PRINT_SUPPORT_FILE_NOT_FOUND = 1047, 924 IPP_INTERNAL_ERROR = 1280, 925 IPP_OPERATION_NOT_SUPPORTED = 1281, 926 IPP_SERVICE_UNAVAILABLE = 1282, 927 IPP_VERSION_NOT_SUPPORTED = 1283, 928 IPP_DEVICE_ERROR = 1284, 929 IPP_TEMPORARY_ERROR = 1285, 930 IPP_NOT_ACCEPTING = 1286, 931 IPP_PRINTER_BUSY = 1287, 932 IPP_ERROR_JOB_CANCELLED = 1288, 933 IPP_MULTIPLE_JOBS_NOT_SUPPORTED = 1289, 934 IPP_PRINTER_IS_DEACTIVATED = 1290 935 } ipp_status_t; 936 937 typedef struct { 938 int fd; 939 int blocking; 940 int error; 941 time_t activity; 942 http_state_t state; 943 http_status_t status; 944 http_version_t version; 945 http_keepalive_t keep_alive; 946 struct sockaddr_in hostaddr; 947 char hostname[256]; 948 char fields[27][256]; 949 char *data; 950 http_encoding_t data_encoding; 951 int data_remaining; 952 int used; 953 char buffer[2048]; 954 int auth_type; 955 md5_state_t md5_state; 956 char nonce[256]; 957 int nonce_count; 958 void *tls; 959 http_encryption_t encryption; 960 fd_set *input_set; 961 http_status_t expect; 962 char *cookie; 963 char authstring[256]; 964 char userpass[256]; 965 int digest_tries; 966 } http_t; 967 extern void cupsLangFree(cups_lang_t *); 968 extern void cupsSetEncryption(http_encryption_t); 969 extern cups_dest_t *cupsGetDest(const char *, const char *, int, 970 cups_dest_t *); 971 extern int cupsGetJobs(cups_job_t * *, const char *, int, int); 972 extern http_encryption_t cupsEncryption(void); 973 extern void cupsFreeJobs(int, cups_job_t *); 974 extern void cupsFreeOptions(int, cups_option_t *); 975 extern const char *cupsGetOption(const char *, int, cups_option_t *); 976 extern int cupsMarkOptions(ppd_file_t *, int, cups_option_t *); 977 extern int cupsAddOption(const char *, const char *, int, 978 cups_option_t * *); 979 extern int cupsGetDests(cups_dest_t * *); 980 extern void cupsSetServer(const char *); 981 extern const char *cupsGetPassword(const char *); 982 extern void cupsSetDests(int, cups_dest_t *); 983 extern int cupsParseOptions(const char *, int, cups_option_t * *); 984 extern void cupsSetPasswordCB(const char *(*digest_tries) (const char *) 985 ); 986 extern void cupsSetUser(const char *); 987 extern cups_lang_t *cupsLangGet(const char *); 988 extern void cupsLangFlush(void); 989 extern int cupsPrintFiles(const char *, int, const char **, const char *, 990 int, cups_option_t *); 991 extern int cupsCancelJob(const char *, int); 992 extern char *cupsLangEncoding(cups_lang_t *); 993 extern void cupsFreeDests(int, cups_dest_t *); 994 extern ipp_status_t cupsLastError(void); 995 extern const char *cupsGetDefault(void); 996 extern const char *cupsGetPPD(const char *); 997 extern const char *cupsServer(void); 998 extern const char *cupsUser(void); 999 extern int cupsTempFd(char *, int); 1000 extern int cupsPrintFile(const char *, const char *, const char *, int, 1001 cups_option_t *); 1002 extern int cupsAddDest(const char *, const char *, int, cups_dest_t * *); 1003 __________________________________________________________ 1004 1005 7.2.2. cups/ppd.h 1006 1007 #define _CUPS_PPD_H_ 1008 #define PPD_MAX_LINE 256 1009 #define PPD_VERSION 4.3 1010 #define PPD_MAX_NAME 41 1011 #define PPD_MAX_TEXT 81 1012 1013 typedef enum { 1014 PPD_CS_CMYK = -4, 1015 PPD_CS_CMY = -3, 1016 PPD_CS_GRAY = 1, 1017 PPD_CS_RGB = 3, 1018 PPD_CS_RGBK = 4, 1019 PPD_CS_N = 5 1020 } ppd_cs_t; 1021 typedef struct { 1022 char name[41]; 1023 char *start; 1024 char *stop; 1025 } ppd_emul_t; 1026 typedef enum { 1027 PPD_UI_BOOLEAN = 0, 1028 PPD_UI_PICKONE = 1, 1029 PPD_UI_PICKMANY = 2 1030 } ppd_ui_t; 1031 typedef enum { 1032 PPD_ORDER_ANY = 0, 1033 PPD_ORDER_DOCUMENT = 1, 1034 PPD_ORDER_EXIT = 2, 1035 PPD_ORDER_JCL = 3, 1036 PPD_ORDER_PAGE = 4, 1037 PPD_ORDER_PROLOG = 5 1038 } ppd_section_t; 1039 typedef struct { 1040 char marked; 1041 char choice[41]; 1042 char text[81]; 1043 char *code; 1044 void *option; 1045 } ppd_choice_t; 1046 typedef struct { 1047 char conflicted; 1048 char keyword[41]; 1049 char defchoice[41]; 1050 char text[81]; 1051 ppd_ui_t ui; 1052 ppd_section_t section; 1053 float order; 1054 int num_choices; 1055 ppd_choice_t *choices; 1056 } ppd_option_t; 1057 typedef struct ppd_group_str { 1058 char text[40]; 1059 char name[41]; 1060 int num_options; 1061 ppd_option_t *options; 1062 int num_subgroups; 1063 struct ppd_group_str *subgroups; 1064 } ppd_group_t; 1065 typedef struct { 1066 int marked; 1067 char name[41]; 1068 float width; 1069 float length; 1070 float left; 1071 float bottom; 1072 float right; 1073 float top; 1074 } ppd_size_t; 1075 typedef struct { 1076 char option1[41]; 1077 char choice1[41]; 1078 char option2[41]; 1079 char choice2[41]; 1080 } ppd_const_t; 1081 typedef struct { 1082 char resolution[41]; 1083 char media_type[41]; 1084 float density; 1085 float gamma; 1086 float matrix[3][3]; 1087 } ppd_profile_t; 1088 typedef struct { 1089 char name[41]; 1090 char spec[41]; 1091 char text[81]; 1092 char *value; 1093 } ppd_attr_t; 1094 typedef struct { 1095 int language_level; 1096 int color_device; 1097 int variable_sizes; 1098 int accurate_screens; 1099 int contone_only; 1100 int landscape; 1101 int model_number; 1102 int manual_copies; 1103 int throughput; 1104 ppd_cs_t colorspace; 1105 char *patches; 1106 int num_emulations; 1107 ppd_emul_t *emulations; 1108 char *jcl_begin; 1109 char *jcl_ps; 1110 char *jcl_end; 1111 char *lang_encoding; 1112 char *lang_version; 1113 char *modelname; 1114 char *ttrasterizer; 1115 char *manufacturer; 1116 char *product; 1117 char *nickname; 1118 char *shortnickname; 1119 int num_groups; 1120 ppd_group_t *groups; 1121 int num_sizes; 1122 ppd_size_t *sizes; 1123 float custom_min[2]; 1124 float custom_max[2]; 1125 float custom_margins[4]; 1126 int num_consts; 1127 ppd_const_t *consts; 1128 int num_fonts; 1129 char **fonts; 1130 int num_profiles; 1131 ppd_profile_t *profiles; 1132 int num_filters; 1133 char **filters; 1134 int flip_duplex; 1135 char *protocols; 1136 char *pcfilename; 1137 int num_attrs; 1138 int cur_attr; 1139 ppd_attr_t **attrs; 1140 } ppd_file_t; 1141 typedef enum { 1142 PPD_OK = 0, 1143 PPD_FILE_OPEN_ERROR = 1, 1144 PPD_NULL_FILE = 2, 1145 PPD_ALLOC_ERROR = 3, 1146 PPD_MISSING_PPDADOBE4 = 4, 1147 PPD_MISSING_VALUE = 5, 1148 PPD_INTERNAL_ERROR = 6, 1149 PPD_BAD_OPEN_GROUP = 7, 1150 PPD_NESTED_OPEN_GROUP = 8, 1151 PPD_BAD_OPEN_UI = 9, 1152 PPD_NESTED_OPEN_UI = 10, 1153 PPD_BAD_ORDER_DEPENDENCY = 11, 1154 PPD_BAD_UI_CONSTRAINTS = 12, 1155 PPD_MISSING_ASTERISK = 13, 1156 PPD_LINE_TOO_LONG = 14, 1157 PPD_ILLEGAL_CHARACTER = 15, 1158 PPD_ILLEGAL_MAIN_KEYWORD = 16, 1159 PPD_ILLEGAL_OPTION_KEYWORD = 17, 1160 PPD_ILLEGAL_TRANSLATION = 18, 1161 PPD_ILLEGAL_WHITESPACE = 19 1162 } ppd_status_t; 1163 typedef enum { 1164 PPD_CONFORM_RELAXED = 0, 1165 PPD_CONFORM_STRICT = 1 1166 } ppd_conform_t; 1167 extern float ppdPageLength(ppd_file_t *, const char *); 1168 extern ppd_status_t ppdLastError(int *); 1169 extern int ppdEmitFd(ppd_file_t *, int, ppd_section_t); 1170 extern int ppdMarkOption(ppd_file_t *, const char *, const char *); 1171 extern int ppdEmitJCL(ppd_file_t *, FILE *, int, const char *, 1172 const char *); 1173 extern ppd_choice_t *ppdFindChoice(ppd_option_t *, const char *); 1174 extern ppd_file_t *ppdOpenFile(const char *); 1175 extern int ppdEmit(ppd_file_t *, FILE *, ppd_section_t); 1176 extern int ppdCollect(ppd_file_t *, ppd_section_t, ppd_choice_t * **); 1177 extern ppd_option_t *ppdFindOption(ppd_file_t *, const char *); 1178 extern void ppdMarkDefaults(ppd_file_t *); 1179 extern ppd_file_t *ppdOpenFd(int); 1180 extern ppd_attr_t *ppdFindNextAttr(ppd_file_t *, const char *, 1181 const char *); 1182 extern const char *ppdErrorString(ppd_status_t); 1183 extern ppd_attr_t *ppdFindAttr(ppd_file_t *, const char *, const char *); 1184 extern ppd_size_t *ppdPageSize(ppd_file_t *, const char *); 1185 extern ppd_file_t *ppdOpen(FILE *); 1186 extern int ppdIsMarked(ppd_file_t *, const char *, const char *); 1187 extern float ppdPageWidth(ppd_file_t *, const char *); 1188 extern int ppdConflicts(ppd_file_t *); 1189 extern ppd_choice_t *ppdFindMarkedChoice(ppd_file_t *, const char *); 1190 extern void ppdClose(ppd_file_t *); 1191 extern void ppdSetConformance(ppd_conform_t); 1192 __________________________________________________________ 1193 1194 7.3. Interface Definitions for libcups 1195 1196 Table of Contents 1197 cupsAddDest -- Add a destination to the list of destinations. 1198 cupsAddOption -- Add an option to an option array. 1199 cupsCancelJob -- Cancel a print job on the default server. 1200 cupsEncryption -- Get the default encryption settings. 1201 cupsFreeDests -- Free the memory used by the list of 1202 destinations. 1203 1204 cupsFreeJobs -- Free memory used by job data. 1205 cupsFreeOptions -- Free all memory used by options. 1206 cupsGetDefault -- Get the default printer or class for the 1207 default server. 1208 1209 cupsGetDest -- Get the named destination from the list. 1210 cupsGetDests -- Get the list of destinations from the default 1211 server. 1212 1213 cupsGetJobs -- Get the jobs from the default server. 1214 cupsGetOption -- Get an option value. 1215 cupsGetPPD -- Get the PPD file for a printer on the default 1216 server. 1217 1218 cupsGetPassword -- Get a password from the user. 1219 cupsLangEncoding -- Return the character encoding (us-ascii, 1220 etc.) 1221 1222 cupsLangFlush -- Flush all language data out of the cache. 1223 cupsLangFree -- Free language data. 1224 cupsLangGet -- Get a language. 1225 cupsLastError -- Return the last IPP status code. 1226 cupsMarkOptions -- Mark command-line options in a PPD file. 1227 cupsParseOptions -- Parse options from a command-line argument. 1228 cupsPrintFile -- Print a file to a printer or class on the 1229 default server. 1230 1231 cupsPrintFiles -- Print one or more files to a printer or class 1232 on the 1233 1234 cupsServer -- Return the hostname/address of the default 1235 server. 1236 1237 cupsSetDests -- Save the list of destinations for the default 1238 server. 1239 1240 cupsSetEncryption -- Set the encryption preference. 1241 cupsSetPasswordCB -- Set the password callback for CUPS. 1242 cupsSetServer -- Set the default server name. 1243 cupsSetUser -- Set the default user name. 1244 cupsTempFd -- Creates a temporary file. 1245 cupsUser -- Return the current user's name. 1246 ppdClose -- Free all memory used by the PPD file. 1247 ppdCollect -- Collect all marked options that reside in the 1248 specified 1249 1250 ppdConflicts -- Check to see if there are any conflicts. 1251 ppdEmit -- Emit code for marked options to a file. 1252 ppdEmitFd -- Emit code for marked options to a file. 1253 ppdEmitJCL -- Emit code for JCL options to a file. 1254 ppdErrorString -- Returns the text assocated with a status. 1255 ppdFindAttr -- Find the first matching attribute... 1256 ppdFindChoice -- Return a pointer to an option choice. 1257 ppdFindMarkedChoice -- Return the marked choice for the 1258 specified option. 1259 1260 ppdFindNextAttr -- Find the next matching attribute... 1261 ppdFindOption -- Return a pointer to the specified option. 1262 ppdIsMarked -- Check to see if an option is marked... 1263 ppdLastError -- Return the status from the last ppdOpen*(). 1264 ppdMarkDefaults -- Mark all default options in the PPD file. 1265 ppdMarkOption -- Mark an option in a PPD file. 1266 ppdOpen -- Read a PPD file into memory. 1267 ppdOpenFd -- Read a PPD file into memory. 1268 ppdOpenFile -- Read a PPD file into memory. 1269 ppdPageLength -- Get the page length for the given size. 1270 ppdPageSize -- Get the page size record for the given size. 1271 ppdPageWidth -- Get the page width for the given size. 1272 ppdSetConformance -- Set the conformance level for PPD files. 1273 1274 The interfaces defined on the following pages are included in 1275 libcups and are defined by this specification. Unless otherwise 1276 noted, these interfaces shall be included in the source 1277 standard. 1278 1279 Other interfaces listed in Section 7.1 shall behave as 1280 described in the referenced base document. 1281 1282 cupsAddDest 1283 1284 Name 1285 1286 cupsAddDest -- Add a destination to the list of destinations. 1287 1288 Synopsis 1289 1290 #include 1291 1292 int cupsAddDest(const char * name, const char * instance, int 1293 num_dests, cups_dest_t ** dests); 1294 1295 Description 1296 1297 Add a destination to the list of destinations. 1298 1299 This function cannot be used to add a new class or printer 1300 queue, it only adds a new container of saved options for the 1301 named destination or instance. 1302 1303 If the named destination already exists, the destination list 1304 is returned unchanged. Adding a new instance of a destination 1305 creates a copy of that destination's options. 1306 1307 Use the cupsSaveDests() function to save the updated list of 1308 destinations to the user's lpoptions file. 1309 1310 Return Value 1311 1312 New number of destinations 1313 1314 cupsAddOption 1315 1316 Name 1317 1318 cupsAddOption -- Add an option to an option array. 1319 1320 Synopsis 1321 1322 #include 1323 1324 int cupsAddOption(const char * name, const char * value, int 1325 num_options, cups_option_t ** options); 1326 1327 Description 1328 1329 Add an option to an option array. 1330 1331 Return Value 1332 1333 Number of options 1334 1335 cupsCancelJob 1336 1337 Name 1338 1339 cupsCancelJob -- Cancel a print job on the default server. 1340 1341 Synopsis 1342 1343 #include 1344 1345 int cupsCancelJob(const char * name, int job); 1346 1347 Description 1348 1349 Cancel a print job on the default server. 1350 1351 Use the cupsLastError() and cupsLastErrorString() functions to 1352 get the cause of any failure. 1353 1354 Return Value 1355 1356 1 on success, 0 on failure 1357 1358 cupsEncryption 1359 1360 Name 1361 1362 cupsEncryption -- Get the default encryption settings. 1363 1364 Synopsis 1365 1366 #include 1367 1368 http_encryption_t cupsEncryption(void); 1369 1370 Description 1371 1372 Get the default encryption settings. 1373 1374 The default encryption setting comes from the CUPS_ENCRYPTION 1375 environment variable, then the ~/.cupsrc file, and finally the 1376 /etc/cups/client.conf file. If not set, the default is 1377 HTTP_ENCRYPT_IF_REQUESTED. 1378 1379 Return Value 1380 1381 Encryption settings 1382 1383 cupsFreeDests 1384 1385 Name 1386 1387 cupsFreeDests -- Free the memory used by the list of 1388 destinations. 1389 1390 Synopsis 1391 1392 #include 1393 1394 void cupsFreeDests(int num_dests, cups_dest_t * dests); 1395 1396 Description 1397 1398 Free the memory used by the list of destinations. 1399 1400 Return Value 1401 1402 This function does not return a value. 1403 1404 cupsFreeJobs 1405 1406 Name 1407 1408 cupsFreeJobs -- Free memory used by job data. 1409 1410 Synopsis 1411 1412 #include 1413 1414 void cupsFreeJobs(int num_jobs, cups_job_t * jobs); 1415 1416 Description 1417 1418 Free memory used by job data. 1419 1420 Return Value 1421 1422 This function does not return a value. 1423 1424 cupsFreeOptions 1425 1426 Name 1427 1428 cupsFreeOptions -- Free all memory used by options. 1429 1430 Synopsis 1431 1432 #include 1433 1434 void cupsFreeOptions(int num_options, cups_option_t * options); 1435 1436 Description 1437 1438 Free all memory used by options. 1439 1440 Return Value 1441 1442 This function does not return a value. 1443 1444 cupsGetDefault 1445 1446 Name 1447 1448 cupsGetDefault -- Get the default printer or class for the 1449 default server. 1450 1451 Synopsis 1452 1453 #include 1454 1455 const char * cupsGetDefault(void); 1456 1457 Description 1458 1459 Get the default printer or class for the default server. 1460 1461 This function returns the default printer or class as defined 1462 by the LPDEST or PRINTER environment variables. If these 1463 environment variables are not set, the server default 1464 destination is returned. Applications should use the 1465 cupsGetDests() and cupsGetDest() functions to get the 1466 user-defined default printer, as this function does not support 1467 the lpoptions-defined default printer. 1468 1469 Return Value 1470 1471 Default printer or NULL 1472 1473 cupsGetDest 1474 1475 Name 1476 1477 cupsGetDest -- Get the named destination from the list. 1478 1479 Synopsis 1480 1481 #include 1482 1483 cups_dest_t * cupsGetDest(const char * name, const char * 1484 instance, int num_dests, cups_dest_t * dests); 1485 1486 Description 1487 1488 Get the named destination from the list. 1489 1490 Use the cupsGetDests() or cupsGetDests2() functions to get a 1491 list of supported destinations for the current user. 1492 1493 Return Value 1494 1495 Destination pointer or NULL 1496 1497 cupsGetDests 1498 1499 Name 1500 1501 cupsGetDests -- Get the list of destinations from the default 1502 server. 1503 1504 Synopsis 1505 1506 #include 1507 1508 int cupsGetDests(cups_dest_t ** dests); 1509 1510 Description 1511 1512 Get the list of destinations from the default server. 1513 1514 Starting with CUPS 1.2, the returned list of destinations 1515 include the printer-info, printer-is-accepting-jobs, 1516 printer-is-shared, printer-make-and-model, printer-state, 1517 printer-state-change-time, printer-state-reasons, and 1518 printer-type attributes as options. 1519 1520 Use the cupsFreeDests() function to free the destination list 1521 and the cupsGetDest() function to find a particular 1522 destination. 1523 1524 Return Value 1525 1526 Number of destinations 1527 1528 cupsGetJobs 1529 1530 Name 1531 1532 cupsGetJobs -- Get the jobs from the default server. 1533 1534 Synopsis 1535 1536 #include 1537 1538 int cupsGetJobs(cups_job_t ** jobs, const char * mydest, int 1539 myjobs, int completed); 1540 1541 Description 1542 1543 Get the jobs from the default server. 1544 1545 Return Value 1546 1547 Number of jobs 1548 1549 cupsGetOption 1550 1551 Name 1552 1553 cupsGetOption -- Get an option value. 1554 1555 Synopsis 1556 1557 #include 1558 1559 const char * cupsGetOption(const char * name, int num_options, 1560 cups_option_t * options); 1561 1562 Description 1563 1564 Get an option value. 1565 1566 Return Value 1567 1568 Option value or NULL 1569 1570 cupsGetPPD 1571 1572 Name 1573 1574 cupsGetPPD -- Get the PPD file for a printer on the default 1575 server. 1576 1577 Synopsis 1578 1579 #include 1580 1581 const char * cupsGetPPD(const char * name); 1582 1583 Description 1584 1585 Get the PPD file for a printer on the default server. 1586 1587 For classes, cupsGetPPD() returns the PPD file for the first 1588 printer in the class. 1589 1590 Return Value 1591 1592 Filename for PPD file 1593 1594 cupsGetPassword 1595 1596 Name 1597 1598 cupsGetPassword -- Get a password from the user. 1599 1600 Synopsis 1601 1602 #include 1603 1604 const char * cupsGetPassword(const char * prompt); 1605 1606 Description 1607 1608 Get a password from the user. 1609 1610 Uses the current password callback function. Returns NULL if 1611 the user does not provide a password. 1612 1613 Return Value 1614 1615 Password 1616 1617 cupsLangEncoding 1618 1619 Name 1620 1621 cupsLangEncoding -- Return the character encoding (us-ascii, 1622 etc.) 1623 1624 Synopsis 1625 1626 #include 1627 1628 const char * cupsLangEncoding(cups_lang_t * lang); 1629 1630 Description 1631 1632 Return the character encoding (us-ascii, etc.) for the given 1633 language. 1634 1635 Return Value 1636 1637 Character encoding 1638 1639 cupsLangFlush 1640 1641 Name 1642 1643 cupsLangFlush -- Flush all language data out of the cache. 1644 1645 Synopsis 1646 1647 #include 1648 1649 void cupsLangFlush(void); 1650 1651 Description 1652 1653 Flush all language data out of the cache. 1654 1655 Return Value 1656 1657 This function does not return a value. 1658 1659 cupsLangFree 1660 1661 Name 1662 1663 cupsLangFree -- Free language data. 1664 1665 Synopsis 1666 1667 #include 1668 1669 void cupsLangFree(cups_lang_t * lang); 1670 1671 Description 1672 1673 Free language data. 1674 1675 This does not actually free anything; use cupsLangFlush() for 1676 that. 1677 1678 Return Value 1679 1680 This function does not return a value. 1681 1682 cupsLangGet 1683 1684 Name 1685 1686 cupsLangGet -- Get a language. 1687 1688 Synopsis 1689 1690 #include 1691 1692 cups_lang_t * cupsLangGet(const char * language); 1693 1694 Description 1695 1696 Get a language. 1697 1698 Return Value 1699 1700 Language data 1701 1702 cupsLastError 1703 1704 Name 1705 1706 cupsLastError -- Return the last IPP status code. 1707 1708 Synopsis 1709 1710 #include 1711 1712 ipp_status_t cupsLastError(void); 1713 1714 Description 1715 1716 Return the last IPP status code. 1717 1718 Return Value 1719 1720 IPP status code from last request 1721 1722 cupsMarkOptions 1723 1724 Name 1725 1726 cupsMarkOptions -- Mark command-line options in a PPD file. 1727 1728 Synopsis 1729 1730 #include 1731 1732 int cupsMarkOptions(ppd_file_t * ppd, int num_options, 1733 cups_option_t * options); 1734 1735 Description 1736 1737 Mark command-line options in a PPD file. 1738 1739 Return Value 1740 1741 1 if conflicting 1742 1743 cupsParseOptions 1744 1745 Name 1746 1747 cupsParseOptions -- Parse options from a command-line argument. 1748 1749 Synopsis 1750 1751 #include 1752 1753 int cupsParseOptions(const char * arg, int num_options, 1754 cups_option_t ** options); 1755 1756 Description 1757 1758 Parse options from a command-line argument. 1759 1760 This function converts space-delimited name/value pairs 1761 according to the PAPI text option ABNF specification. 1762 Collection values ("name={a=... b=... c=...}") are stored with 1763 the curley brackets intact - use cupsParseOptions() on the 1764 value to extract the collection attributes. 1765 1766 Return Value 1767 1768 Number of options found 1769 1770 cupsPrintFile 1771 1772 Name 1773 1774 cupsPrintFile -- Print a file to a printer or class on the 1775 default server. 1776 1777 Synopsis 1778 1779 #include 1780 1781 int cupsPrintFile(const char * name, const char * filename, 1782 const char * title, int num_options, cups_option_t * options); 1783 1784 Description 1785 1786 Print a file to a printer or class on the default server. 1787 1788 Return Value 1789 1790 Job ID 1791 1792 cupsPrintFiles 1793 1794 Name 1795 1796 cupsPrintFiles -- Print one or more files to a printer or class 1797 on the 1798 1799 Synopsis 1800 1801 #include 1802 1803 int cupsPrintFiles(const char * name, int num_files, const char 1804 ** files, const char * title, int num_options, cups_option_t * 1805 options); 1806 1807 Description 1808 1809 Print one or more files to a printer or class on the default 1810 server. 1811 1812 Return Value 1813 1814 Job ID 1815 1816 cupsServer 1817 1818 Name 1819 1820 cupsServer -- Return the hostname/address of the default 1821 server. 1822 1823 Synopsis 1824 1825 #include 1826 1827 const char * cupsServer(void); 1828 1829 Description 1830 1831 Return the hostname/address of the default server. 1832 1833 The returned value can be a fully-qualified hostname, a numeric 1834 IPv4 or IPv6 address, or a domain socket pathname. 1835 1836 Return Value 1837 1838 Server name 1839 1840 cupsSetDests 1841 1842 Name 1843 1844 cupsSetDests -- Save the list of destinations for the default 1845 server. 1846 1847 Synopsis 1848 1849 #include 1850 1851 void cupsSetDests(int num_dests, cups_dest_t * dests); 1852 1853 Description 1854 1855 Save the list of destinations for the default server. 1856 1857 This function saves the destinations to /etc/cups/lpoptions 1858 when run as root and ~/.cups/lpoptions when run as a normal 1859 user. 1860 1861 Return Value 1862 1863 This function does not return a value. 1864 1865 cupsSetEncryption 1866 1867 Name 1868 1869 cupsSetEncryption -- Set the encryption preference. 1870 1871 Synopsis 1872 1873 #include 1874 1875 void cupsSetEncryption(http_encryption_t e); 1876 1877 Description 1878 1879 Set the encryption preference. 1880 1881 Return Value 1882 1883 This function does not return a value. 1884 1885 cupsSetPasswordCB 1886 1887 Name 1888 1889 cupsSetPasswordCB -- Set the password callback for CUPS. 1890 1891 Synopsis 1892 1893 #include 1894 1895 void cupsSetPasswordCB(cups_password_cb_t cb); 1896 1897 Description 1898 1899 Set the password callback for CUPS. 1900 1901 Pass NULL to restore the default (console) password callback. 1902 1903 Return Value 1904 1905 This function does not return a value. 1906 1907 cupsSetServer 1908 1909 Name 1910 1911 cupsSetServer -- Set the default server name. 1912 1913 Synopsis 1914 1915 #include 1916 1917 void cupsSetServer(const char * server); 1918 1919 Description 1920 1921 Set the default server name. 1922 1923 The "server" string can be a fully-qualified hostname, a 1924 numeric IPv4 or IPv6 address, or a domain socket pathname. Pass 1925 NULL to restore the default server name. 1926 1927 Return Value 1928 1929 This function does not return a value. 1930 1931 cupsSetUser 1932 1933 Name 1934 1935 cupsSetUser -- Set the default user name. 1936 1937 Synopsis 1938 1939 #include 1940 1941 void cupsSetUser(const char * user); 1942 1943 Description 1944 1945 Set the default user name. 1946 1947 Pass NULL to restore the default user name. 1948 1949 Return Value 1950 1951 This function does not return a value. 1952 1953 cupsTempFd 1954 1955 Name 1956 1957 cupsTempFd -- Creates a temporary file. 1958 1959 Synopsis 1960 1961 #include 1962 1963 int cupsTempFd(char * filename, int len); 1964 1965 Description 1966 1967 Creates a temporary file. 1968 1969 The temporary filename is returned in the filename buffer. The 1970 temporary file is opened for reading and writing. 1971 1972 Return Value 1973 1974 New file descriptor or -1 on error 1975 1976 cupsUser 1977 1978 Name 1979 1980 cupsUser -- Return the current user's name. 1981 1982 Synopsis 1983 1984 #include 1985 1986 const char * cupsUser(void); 1987 1988 Description 1989 1990 Return the current user's name. 1991 1992 Return Value 1993 1994 User name 1995 1996 ppdClose 1997 1998 Name 1999 2000 ppdClose -- Free all memory used by the PPD file. 2001 2002 Synopsis 2003 2004 #include 2005 2006 void ppdClose(ppd_file_t * ppd); 2007 2008 Description 2009 2010 Free all memory used by the PPD file. 2011 2012 Return Value 2013 2014 This function does not return a value. 2015 2016 ppdCollect 2017 2018 Name 2019 2020 ppdCollect -- Collect all marked options that reside in the 2021 specified 2022 2023 Synopsis 2024 2025 #include 2026 2027 int ppdCollect(ppd_file_t * ppd, ppd_section_t section, 2028 ppd_choice_t *** choices); 2029 2030 Description 2031 2032 Collect all marked options that reside in the specified 2033 section. 2034 2035 Return Value 2036 2037 Number of options marked 2038 2039 ppdConflicts 2040 2041 Name 2042 2043 ppdConflicts -- Check to see if there are any conflicts. 2044 2045 Synopsis 2046 2047 #include 2048 2049 int ppdConflicts(ppd_file_t * ppd); 2050 2051 Description 2052 2053 Check to see if there are any conflicts. 2054 2055 Return Value 2056 2057 Number of conflicts found 2058 2059 ppdEmit 2060 2061 Name 2062 2063 ppdEmit -- Emit code for marked options to a file. 2064 2065 Synopsis 2066 2067 #include 2068 2069 int ppdEmit(ppd_file_t * ppd, FILE * fp, ppd_section_t 2070 section); 2071 2072 Description 2073 2074 Emit code for marked options to a file. 2075 2076 Return Value 2077 2078 0 on success, -1 on failure 2079 2080 ppdEmitFd 2081 2082 Name 2083 2084 ppdEmitFd -- Emit code for marked options to a file. 2085 2086 Synopsis 2087 2088 #include 2089 2090 int ppdEmitFd(ppd_file_t * ppd, int fd, ppd_section_t section); 2091 2092 Description 2093 2094 Emit code for marked options to a file. 2095 2096 Return Value 2097 2098 0 on success, -1 on failure 2099 2100 ppdEmitJCL 2101 2102 Name 2103 2104 ppdEmitJCL -- Emit code for JCL options to a file. 2105 2106 Synopsis 2107 2108 #include 2109 2110 int ppdEmitJCL(ppd_file_t * ppd, FILE * fp, int job_id, const 2111 char * user, const char * title); 2112 2113 Description 2114 2115 Emit code for JCL options to a file. 2116 2117 Return Value 2118 2119 0 on success, -1 on failure 2120 2121 ppdErrorString 2122 2123 Name 2124 2125 ppdErrorString -- Returns the text assocated with a status. 2126 2127 Synopsis 2128 2129 #include 2130 2131 const char * ppdErrorString(ppd_status_t status); 2132 2133 Description 2134 2135 Returns the text assocated with a status. 2136 2137 Return Value 2138 2139 Status string 2140 2141 ppdFindAttr 2142 2143 Name 2144 2145 ppdFindAttr -- Find the first matching attribute... 2146 2147 Synopsis 2148 2149 #include 2150 2151 ppd_attr_t * ppdFindAttr(ppd_file_t * ppd, const char * name, 2152 const char * spec); 2153 2154 Description 2155 2156 Find the first matching attribute... 2157 2158 Return Value 2159 2160 Attribute or NULL if not found 2161 2162 ppdFindChoice 2163 2164 Name 2165 2166 ppdFindChoice -- Return a pointer to an option choice. 2167 2168 Synopsis 2169 2170 #include 2171 2172 ppd_choice_t * ppdFindChoice(ppd_option_t * o, const char * 2173 choice); 2174 2175 Description 2176 2177 Return a pointer to an option choice. 2178 2179 Return Value 2180 2181 Choice pointer or NULL 2182 2183 ppdFindMarkedChoice 2184 2185 Name 2186 2187 ppdFindMarkedChoice -- Return the marked choice for the 2188 specified option. 2189 2190 Synopsis 2191 2192 #include 2193 2194 ppd_choice_t * ppdFindMarkedChoice(ppd_file_t * ppd, const char 2195 * option); 2196 2197 Description 2198 2199 Return the marked choice for the specified option. 2200 2201 Return Value 2202 2203 Pointer to choice or NULL 2204 2205 ppdFindNextAttr 2206 2207 Name 2208 2209 ppdFindNextAttr -- Find the next matching attribute... 2210 2211 Synopsis 2212 2213 #include 2214 2215 ppd_attr_t * ppdFindNextAttr(ppd_file_t * ppd, const char * 2216 name, const char * spec); 2217 2218 Description 2219 2220 Find the next matching attribute... 2221 2222 Return Value 2223 2224 Attribute or NULL if not found 2225 2226 ppdFindOption 2227 2228 Name 2229 2230 ppdFindOption -- Return a pointer to the specified option. 2231 2232 Synopsis 2233 2234 #include 2235 2236 ppd_option_t * ppdFindOption(ppd_file_t * ppd, const char * 2237 option); 2238 2239 Description 2240 2241 Return a pointer to the specified option. 2242 2243 Return Value 2244 2245 Pointer to option or NULL 2246 2247 ppdIsMarked 2248 2249 Name 2250 2251 ppdIsMarked -- Check to see if an option is marked... 2252 2253 Synopsis 2254 2255 #include 2256 2257 int ppdIsMarked(ppd_file_t * ppd, const char * option, const 2258 char * choice); 2259 2260 Description 2261 2262 Check to see if an option is marked... 2263 2264 Return Value 2265 2266 Non-zero if option is marked 2267 2268 ppdLastError 2269 2270 Name 2271 2272 ppdLastError -- Return the status from the last ppdOpen*(). 2273 2274 Synopsis 2275 2276 #include 2277 2278 ppd_status_t ppdLastError(int * line); 2279 2280 Description 2281 2282 Return the status from the last ppdOpen*(). 2283 2284 Return Value 2285 2286 Status code 2287 2288 ppdMarkDefaults 2289 2290 Name 2291 2292 ppdMarkDefaults -- Mark all default options in the PPD file. 2293 2294 Synopsis 2295 2296 #include 2297 2298 void ppdMarkDefaults(ppd_file_t * ppd); 2299 2300 Description 2301 2302 Mark all default options in the PPD file. 2303 2304 Return Value 2305 2306 This function does not return a value. 2307 2308 ppdMarkOption 2309 2310 Name 2311 2312 ppdMarkOption -- Mark an option in a PPD file. 2313 2314 Synopsis 2315 2316 #include 2317 2318 int ppdMarkOption(ppd_file_t * ppd, const char * option, const 2319 char * choice); 2320 2321 Description 2322 2323 Mark an option in a PPD file. 2324 2325 Notes: 2326 2327 -1 is returned if the given option would conflict with any 2328 currently selected option. 2329 2330 Return Value 2331 2332 Number of conflicts 2333 2334 ppdOpen 2335 2336 Name 2337 2338 ppdOpen -- Read a PPD file into memory. 2339 2340 Synopsis 2341 2342 #include 2343 2344 ppd_file_t * ppdOpen(FILE * fp); 2345 2346 Description 2347 2348 Read a PPD file into memory. 2349 2350 Return Value 2351 2352 PPD file record 2353 2354 ppdOpenFd 2355 2356 Name 2357 2358 ppdOpenFd -- Read a PPD file into memory. 2359 2360 Synopsis 2361 2362 #include 2363 2364 ppd_file_t * ppdOpenFd(int fd); 2365 2366 Description 2367 2368 Read a PPD file into memory. 2369 2370 Return Value 2371 2372 PPD file record 2373 2374 ppdOpenFile 2375 2376 Name 2377 2378 ppdOpenFile -- Read a PPD file into memory. 2379 2380 Synopsis 2381 2382 #include 2383 2384 ppd_file_t * ppdOpenFile(const char * filename); 2385 2386 Description 2387 2388 Read a PPD file into memory. 2389 2390 Return Value 2391 2392 PPD file record 2393 2394 ppdPageLength 2395 2396 Name 2397 2398 ppdPageLength -- Get the page length for the given size. 2399 2400 Synopsis 2401 2402 #include 2403 2404 float ppdPageLength(ppd_file_t * ppd, const char * name); 2405 2406 Description 2407 2408 Get the page length for the given size. 2409 2410 Return Value 2411 2412 Length of page in points or 0.0 2413 2414 ppdPageSize 2415 2416 Name 2417 2418 ppdPageSize -- Get the page size record for the given size. 2419 2420 Synopsis 2421 2422 #include 2423 2424 ppd_size_t * ppdPageSize(ppd_file_t * ppd, const char * name); 2425 2426 Description 2427 2428 Get the page size record for the given size. 2429 2430 Return Value 2431 2432 Size record for page or NULL 2433 2434 ppdPageWidth 2435 2436 Name 2437 2438 ppdPageWidth -- Get the page width for the given size. 2439 2440 Synopsis 2441 2442 #include 2443 2444 float ppdPageWidth(ppd_file_t * ppd, const char * name); 2445 2446 Description 2447 2448 Get the page width for the given size. 2449 2450 Return Value 2451 2452 Width of page in points or 0.0 2453 2454 ppdSetConformance 2455 2456 Name 2457 2458 ppdSetConformance -- Set the conformance level for PPD files. 2459 2460 Synopsis 2461 2462 #include 2463 2464 void ppdSetConformance(ppd_conform_t c); 2465 2466 Description 2467 2468 Set the conformance level for PPD files. 2469 2470 Return Value 2471 2472 This function does not return a value. 2473 __________________________________________________________ 2474 2475 7.4. Interfaces for libcupsimage 2476 2477 Table 7-3 defines the library name and shared object name for 2478 the libcupsimage library 2479 2480 Table 7-3. libcupsimage Definition 2481 Library: libcupsimage 2482 SONAME: libcupsimage.so.2 2483 2484 The behavior of the interfaces in this library is specified by 2485 the following specifications: 2486 2487 [LSB] This Specification 2488 __________________________________________________________ 2489 2490 7.4.1. CUPS Raster ABI 2491 __________________________________________________________ 2492 2493 7.4.1.1. Interfaces for CUPS Raster ABI 2494 2495 An LSB conforming implementation shall provide the generic 2496 functions for CUPS Raster ABI specified in Table 7-4, with the 2497 full mandatory functionality as described in the referenced 2498 underlying specification. 2499 2500 Table 7-4. libcupsimage - CUPS Raster ABI Function Interfaces 2501 cupsRasterClose [LSB] cupsRasterOpen [LSB] cupsRasterReadHeader 2502 [LSB] cupsRasterReadPixels [LSB] 2503 cupsRasterWriteHeader [LSB] cupsRasterWritePixels [LSB] 2504 __________________________________________________________ 2505 2506 7.5. Data Definitions for libcupsimage 2507 2508 This section defines global identifiers and their values that 2509 are associated with interfaces contained in libcupsimage. These 2510 definitions are organized into groups that correspond to system 2511 headers. This convention is used as a convenience for the 2512 reader, and does not imply the existence of these headers, or 2513 their content. Where an interface is defined as requiring a 2514 particular system header file all of the data definitions for 2515 that system header file presented here shall be in effect. 2516 2517 This section gives data definitions to promote binary 2518 application portability, not to repeat source interface 2519 definitions available elsewhere. System providers and 2520 application developers should use this ABI to supplement - not 2521 to replace - source interface definition specifications. 2522 2523 This specification uses the ISO C (1999) C Language as the 2524 reference programming language, and data definitions are 2525 specified in ISO C format. The C language is used here as a 2526 convenient notation. Using a C language description of these 2527 data objects does not preclude their use by other programming 2528 languages. 2529 __________________________________________________________ 2530 2531 7.5.1. cups/raster.h 2532 2533 #define _CUPS_RASTER_H_ 2534 #define CUPS_RASTER_SYNC 0x52615374 2535 #define CUPS_RASTER_REVSYNC 0x74536152 2536 #define CUPS_RASTER_HAVE_COLORIMETRIC 1 2537 2538 typedef enum { 2539 CUPS_RASTER_READ = 0, 2540 CUPS_RASTER_WRITE = 1 2541 } cups_mode_t; 2542 typedef struct { 2543 unsigned int sync; 2544 int fd; 2545 cups_mode_t mode; 2546 } cups_raster_t; 2547 typedef enum { 2548 CUPS_ADVANCE_NONE = 0, 2549 CUPS_ADVANCE_FILE = 1, 2550 CUPS_ADVANCE_JOB = 2, 2551 CUPS_ADVANCE_SET = 3, 2552 CUPS_ADVANCE_PAGE = 4 2553 } cups_adv_t; 2554 typedef enum { 2555 CUPS_FALSE = 0, 2556 CUPS_TRUE = 1 2557 } cups_bool_t; 2558 typedef enum { 2559 CUPS_CUT_NONE = 0, 2560 CUPS_CUT_FILE = 1, 2561 CUPS_CUT_JOB = 2, 2562 CUPS_CUT_SET = 3, 2563 CUPS_CUT_PAGE = 4 2564 } cups_cut_t; 2565 typedef enum { 2566 CUPS_JOG_NONE = 0, 2567 CUPS_JOG_FILE = 1, 2568 CUPS_JOG_JOB = 2, 2569 CUPS_JOG_SET = 3 2570 } cups_jog_t; 2571 typedef enum { 2572 CUPS_EDGE_TOP = 0, 2573 CUPS_EDGE_RIGHT = 1, 2574 CUPS_EDGE_BOTTOM = 2, 2575 CUPS_EDGE_LEFT = 3 2576 } cups_edge_t; 2577 typedef enum { 2578 CUPS_ORIENT_0 = 0, 2579 CUPS_ORIENT_90 = 1, 2580 CUPS_ORIENT_180 = 2, 2581 CUPS_ORIENT_270 = 3 2582 } cups_orient_t; 2583 typedef enum { 2584 CUPS_ORDER_CHUNKED = 0, 2585 CUPS_ORDER_BANDED = 1, 2586 CUPS_ORDER_PLANAR = 2 2587 } cups_order_t; 2588 typedef enum { 2589 CUPS_CSPACE_W = 0, 2590 CUPS_CSPACE_RGB = 1, 2591 CUPS_CSPACE_RGBA = 2, 2592 CUPS_CSPACE_K = 3, 2593 CUPS_CSPACE_CMY = 4, 2594 CUPS_CSPACE_YMC = 5, 2595 CUPS_CSPACE_CMYK = 6, 2596 CUPS_CSPACE_YMCK = 7, 2597 CUPS_CSPACE_KCMY = 8, 2598 CUPS_CSPACE_KCMYcm = 9, 2599 CUPS_CSPACE_GMCK = 10, 2600 CUPS_CSPACE_GMCS = 11, 2601 CUPS_CSPACE_WHITE = 12, 2602 CUPS_CSPACE_GOLD = 13, 2603 CUPS_CSPACE_SILVER = 14, 2604 CUPS_CSPACE_CIEXYZ = 15, 2605 CUPS_CSPACE_CIELab = 16, 2606 CUPS_CSPACE_ICC1 = 32, 2607 CUPS_CSPACE_ICC2 = 33, 2608 CUPS_CSPACE_ICC3 = 34, 2609 CUPS_CSPACE_ICC4 = 35, 2610 CUPS_CSPACE_ICC5 = 36, 2611 CUPS_CSPACE_ICC6 = 37, 2612 CUPS_CSPACE_ICC7 = 38, 2613 CUPS_CSPACE_ICC8 = 39, 2614 CUPS_CSPACE_ICC9 = 40, 2615 CUPS_CSPACE_ICCA = 41, 2616 CUPS_CSPACE_ICCB = 42, 2617 CUPS_CSPACE_ICCC = 43, 2618 CUPS_CSPACE_ICCD = 44, 2619 CUPS_CSPACE_ICCE = 45, 2620 CUPS_CSPACE_ICCF = 46 2621 } cups_cspace_t; 2622 typedef struct { 2623 char MediaClass[64]; 2624 char MediaColor[64]; 2625 char MediaType[64]; 2626 char OutputType[64]; 2627 unsigned int AdvanceDistance; 2628 cups_adv_t AdvanceMedia; 2629 cups_bool_t Collate; 2630 cups_cut_t CutMedia; 2631 cups_bool_t Duplex; 2632 unsigned int HWResolution[2]; 2633 unsigned int ImagingBoundingBox[4]; 2634 cups_bool_t InsertSheet; 2635 cups_jog_t Jog; 2636 cups_edge_t LeadingEdge; 2637 unsigned int Margins[2]; 2638 cups_bool_t ManualFeed; 2639 unsigned int MediaPosition; 2640 unsigned int MediaWeight; 2641 cups_bool_t MirrorPrint; 2642 cups_bool_t NegativePrint; 2643 unsigned int NumCopies; 2644 cups_orient_t Orientation; 2645 cups_bool_t OutputFaceUp; 2646 unsigned int PageSize[2]; 2647 cups_bool_t Separations; 2648 cups_bool_t TraySwitch; 2649 cups_bool_t Tumble; 2650 unsigned int cupsWidth; 2651 unsigned int cupsHeight; 2652 unsigned int cupsMediaType; 2653 unsigned int cupsBitsPerColor; 2654 unsigned int cupsBitsPerPixel; 2655 unsigned int cupsBytesPerLine; 2656 cups_order_t cupsColorOrder; 2657 cups_cspace_t cupsColorSpace; 2658 unsigned int cupsCompression; 2659 unsigned int cupsRowCount; 2660 unsigned int cupsRowFeed; 2661 unsigned int cupsRowStep; 2662 } cups_page_header_t; 2663 extern void cupsRasterClose(cups_raster_t *); 2664 extern unsigned int cupsRasterWritePixels(cups_raster_t *, unsigned char *, 2665 unsigned int); 2666 extern unsigned int cupsRasterReadHeader(cups_raster_t *, 2667 cups_page_header_t *); 2668 extern unsigned int cupsRasterReadPixels(cups_raster_t *, unsigned char*, 2669 unsigned int); 2670 extern cups_raster_t *cupsRasterOpen(int, cups_mode_t); 2671 extern unsigned int cupsRasterWriteHeader(cups_raster_t *, 2672 cups_page_header_t *); 2673 __________________________________________________________ 2674 2675 7.6. Interface Definitions for libcupsimage 2676 2677 Table of Contents 2678 cupsRasterClose -- Close a raster stream. 2679 cupsRasterOpen -- Open a raster stream. 2680 cupsRasterReadHeader -- Read a raster page header and store it 2681 in a 2682 2683 cupsRasterReadPixels -- Read raster pixels. 2684 cupsRasterWriteHeader -- Write a raster page header from a V1 2685 page 2686 2687 cupsRasterWritePixels -- Write raster pixels. 2688 2689 The interfaces defined on the following pages are included in 2690 libcupsimage and are defined by this specification. Unless 2691 otherwise noted, these interfaces shall be included in the 2692 source standard. 2693 2694 Other interfaces listed in Section 7.4 shall behave as 2695 described in the referenced base document. 2696 2697 cupsRasterClose 2698 2699 Name 2700 2701 cupsRasterClose -- Close a raster stream. 2702 2703 Synopsis 2704 2705 #include 2706 2707 void cupsRasterClose(cups_raster_t * r); 2708 2709 Description 2710 2711 Close a raster stream. 2712 2713 Return Value 2714 2715 This function does not return a value. 2716 2717 cupsRasterOpen 2718 2719 Name 2720 2721 cupsRasterOpen -- Open a raster stream. 2722 2723 Synopsis 2724 2725 #include 2726 2727 cups_raster_t * cupsRasterOpen(int fd, cups_mode_t mode); 2728 2729 Description 2730 2731 Open a raster stream. 2732 2733 Return Value 2734 2735 New stream 2736 2737 cupsRasterReadHeader 2738 2739 Name 2740 2741 cupsRasterReadHeader -- Read a raster page header and store it 2742 in a 2743 2744 Synopsis 2745 2746 #include 2747 2748 unsigned cupsRasterReadHeader(cups_raster_t * r, 2749 cups_page_header_t * h); 2750 2751 Description 2752 2753 Read a raster page header and store it in a V1 page header 2754 structure. 2755 2756 Return Value 2757 2758 1 on success, 0 on fail 2759 2760 cupsRasterReadPixels 2761 2762 Name 2763 2764 cupsRasterReadPixels -- Read raster pixels. 2765 2766 Synopsis 2767 2768 #include 2769 2770 unsigned cupsRasterReadPixels(cups_raster_t * r, unsigned char 2771 * p, unsigned len); 2772 2773 Description 2774 2775 Read raster pixels. 2776 2777 Return Value 2778 2779 Number of bytes read 2780 2781 cupsRasterWriteHeader 2782 2783 Name 2784 2785 cupsRasterWriteHeader -- Write a raster page header from a V1 2786 page 2787 2788 Synopsis 2789 2790 #include 2791 2792 unsigned cupsRasterWriteHeader(cups_raster_t * r, 2793 cups_page_header_t * h); 2794 2795 Description 2796 2797 Write a raster page header from a V1 page header structure. 2798 2799 Return Value 2800 2801 1 on success, 0 on failure 2802 2803 cupsRasterWritePixels 2804 2805 Name 2806 2807 cupsRasterWritePixels -- Write raster pixels. 2808 2809 Synopsis 2810 2811 #include 2812 2813 unsigned cupsRasterWritePixels(cups_raster_t * r, unsigned char 2814 * p, unsigned len); 2815 2816 Description 2817 2818 Write raster pixels. 2819 2820 Return Value 2821 2822 Number of bytes written 2823 2824 III. Printing Commands 2825 2826 Table of Contents 2827 8. Printing Commands 2828 2829 8.1. Printing Commands 2830 8.2. Command Behavior 2831 2832 FOOMATIC-RIP -- Universal print filter/RIP wrapper 2833 GS -- GhostScript (PostScript and PDF language 2834 interpreter) 2835 __________________________________________________________ 2836 2837 Chapter 8. Printing Commands 2838 2839 8.1. Printing Commands 2840 2841 An LSB conforming implementation shall provide the commands and 2842 utilities as described in Table 8-1, with at least the behavior 2843 described as mandatory in the referenced underlying 2844 specification, with the following exceptions: 2845 2846 1. If any operand (except one which follows --) starts with a 2847 hyphen, the behavior is unspecified. 2848 2849 Rationale (Informative): Applications should place options 2850 before operands, or use --, as needed. This text is needed 2851 because, by default, GNU option parsing differs from POSIX, 2852 unless the environment variable POSIXLY_CORRECT is set. For 2853 example, ls . -a in GNU ls means to list the current 2854 directory, showing all files (that is, "." is an operand and 2855 -a is an option). In POSIX, "." and -a are both operands, 2856 and the command means to list the current directory, and 2857 also the file named -a. Suggesting that applications rely on 2858 the setting of the POSIXLY_CORRECT environment variable, or 2859 try to set it, seems worse than just asking the applications 2860 to invoke commands in ways which work with either the POSIX 2861 or GNU behaviors. 2862 2863 Table 8-1. Commands And Utilities 2864 foomatic-rip [1] gs [1] 2865 2866 Referenced Specification(s) 2867 2868 [1]. This Specification 2869 __________________________________________________________ 2870 2871 8.2. Command Behavior 2872 2873 Table of Contents 2874 FOOMATIC-RIP -- Universal print filter/RIP wrapper 2875 GS -- GhostScript (PostScript and PDF language interpreter) 2876 2877 This section contains descriptions for commands and utilities 2878 whose specified behavior in the LSB contradicts or extends the 2879 standards referenced. It also contains commands and utilities 2880 only required by the LSB and not specified by other standards. 2881 2882 FOOMATIC-RIP 2883 2884 Name 2885 2886 foomatic-rip -- Universal print filter/RIP wrapper 2887 2888 SYNOPSIS 2889 2890 Standalone Mode 2891 2892 foomatic-rip [-v] [-q] [-d] [ --ppd ppdfile ] [ -J jobtitle ] [ 2893 -o option=value [...] ] [ files ] 2894 2895 CUPS Mode 2896 2897 foomatic-rip jobid user jobtitle numcopies options [file] 2898 2899 DESCRIPTION 2900 2901 foomatic-rip is a universal print filter which works with every 2902 known free software printer spooler. 2903 2904 This page describes the facilities of foomatic-rip when used as 2905 a CUPS filter and when used outside of a print system. While 2906 implementations of foomatic-rip may support other print 2907 systems, such use is not documented here. 2908 2909 When run as a CUPS filter, foomatic-rip reads the job from the 2910 specified file, or from standard input if no file is specified. 2911 It renders the file into a printer-specific format, and writes 2912 the result to standard output. 2913 2914 When run standalone, foomatic-rip will read the job from the 2915 specified files, or from standard input if no files are given. 2916 The files are rendered into a printer-specific format, which is 2917 then output according to the PPD option "FoomaticRIPPostPipe", 2918 documented in the LSB. 2919 2920 Printer capabilities are described to foomatic-rip via PPD 2921 files, as described (with extensions used by foomatic-rip) in 2922 the LSB. The method foomatic-rip uses to determine the proper 2923 PPD file for the printer in question is defined by the 2924 implementation of both the spooler and foomatic-rip. 2925 2926 CUPS OPTIONS 2927 2928 Unless otherwise noted, all parameters are required when 2929 running foomatic-rip as a CUPS filter. 2930 2931 jobid 2932 2933 The internal Job ID from CUPS. 2934 username 2935 2936 The username of the user who submitted the job. 2937 jobtitle 2938 2939 The job's title, as submitted by the user. 2940 numcopies 2941 2942 The number of copies of the job requested. 2943 options 2944 2945 A series of printer options, separated by spaces, each of which 2946 take the form name or name=value. The specific list of options 2947 supported is dependent on the printer and spooler, and is 2948 usually documented in the PPD file for the printer. 2949 2950 An option may be preceded by a page specification, describing 2951 the pages to which the option should apply. A page 2952 specification consists of one or more items, separated by 2953 commas, and separated from the option name by a colon. Valid 2954 items include the words "even" and "odd", a single page number, 2955 and a page range. Page ranges are described with a starting 2956 page, a dash ("-"), and an ending page. If omitted, the 2957 starting and ending pages are the first and last page, 2958 respectively, but only one of the ends of the range may be 2959 omitted. 2960 file 2961 2962 The full path to the file containing the job. This parameter is 2963 optional; if it is not supplied, the job is read from standard 2964 input. 2965 2966 SPOOLER-LESS OPTIONS 2967 2968 -v 2969 2970 Verbose mode. Intended for debugging and testing purposes only. 2971 -q 2972 2973 Quiet mode - minimal information output. 2974 -d 2975 2976 Identical to the 'opts' option, but option information is left 2977 in text format. The PPD file will need to be specified using 2978 the --ppd option. 2979 --ppd ppdfile 2980 2981 The PPD file ppdfile should be applied for processing this job. 2982 -J jobtitle 2983 2984 Print the given job title in the header of every page of a 2985 plain text job. 2986 -o option=value 2987 2988 Set an option setting for this job. 2989 2990 EXIT STATUS 2991 2992 foomatic-rip returns 0 unless something unexpected happens. 2993 2994 AUTHOR 2995 2996 Till Kamppeter with parts of Manfred 2997 Wassmanns's man pages for the 2998 Foomatic 2.0.x filters. 2999 3000 Jeff Licquia adapted the 3001 original man page for the LSB. 3002 3003 GS 3004 3005 Name 3006 3007 gs -- GhostScript (PostScript and PDF language interpreter) 3008 3009 SYNOPSIS 3010 3011 gs -h | --help 3012 3013 gs [ options ] ps-file [ [ options ] ps-file2 ] ... 3014 3015 DESCRIPTION 3016 3017 The gs command invokes Ghostscript, an interpreter of Adobe 3018 Systems' PostScript(tm) and Portable Document Format (PDF) 3019 languages. gs reads the files named by ps-file in sequence and 3020 executes them as Ghostscript programs. After doing this, it 3021 reads further input from the standard input stream (normally 3022 the keyboard), interpreting each line separately. The 3023 interpreter exits gracefully when it encounters the "quit" 3024 command (either in a file or from the keyboard), at 3025 end-of-file, or at an interrupt signal (such as Control-C at 3026 the keyboard). 3027 3028 Some of GhostScript's options are set via command-line options; 3029 others are set as processing parameters, each of which consists 3030 of a name and a value. 3031 3032 OPTIONS 3033 3034 -h --help 3035 3036 Show GhostScript's help, as well as lists of the supported 3037 input formats, supported devices, and the search path for gs 3038 components. 3039 -q 3040 3041 Suppress normal startup messages, and also set the processing 3042 parameter QUIET. 3043 -c 3044 3045 Begin interpreting arguments as PostScript code. All following 3046 arguments are sent to the interpreter up to the next argument 3047 beginning with "-" followed by a non-digit, or with "@". This 3048 code is interpolated with the file list, so files specified 3049 before -c are interpreted beforehand, and files after -c are 3050 interpreted afterwards. 3051 -f 3052 3053 Specifies a PostScript file to run as its argument. This is 3054 equivalent to the ps-file arguments, but is useful for 3055 terminating PostScript code as passed via -c. 3056 -d -D 3057 3058 Set a processing parameter. The "name=value" pair follows 3059 immediately after the option, as in "-Dfoo=bar". The values 3060 here must be integers or the values "true" or "false". The 3061 equals sign and value may be omitted; this is assumed to set 3062 the name to "true". 3063 -s -S 3064 3065 Set a processing parameter to a string value. The "name=value" 3066 pair follows immediately after the option, as in "-Sfoo=bar". 3067 -u 3068 3069 Unset a processing parameter. The name to be unset follows 3070 immediately after the option, as in "-ufoo". 3071 -o 3072 3073 Write rendered output to the named file, and also inhibit 3074 pauses and the interactive shell. This is equivalent to setting 3075 the processing parameters BATCH and NOPAUSE to true, and 3076 OutputFile to the parameter after -o. 3077 -r 3078 3079 Set the device resolution. The resolution is specified as two 3080 numbers separated with an "x", as in "300x150", corresponding 3081 to the X and Y axis resolutions, respectively. If a single 3082 number is given without an "x", it is treated as the value for 3083 both resolutions. 3084 3085 This is equivalent to setting DEVICEXRESOLUTION and 3086 DEVICEYRESOLUTION in systemdict. 3087 -g 3088 3089 Set the device size, in pixels. The size is specified as two 3090 numbers separated with an "x", as in "640x480", corresponding 3091 to the width and height, respectively. 3092 3093 This is equivalent to setting DEVICEWIDTH and DEVICEHEIGHT in 3094 systemdict. 3095 3096 RECOGNIZED PROCESSING PARAMETERS 3097 3098 Processing parameters may have arbitrary names; no limits are 3099 placed on the settings that may be made. However, certain 3100 settings have meaning to the gs interpreter, and drivers may 3101 use other settings. Below is a list of recognized settings that 3102 the gs interpreter must respect. 3103 3104 BATCH 3105 3106 If set to true, do not enter an interactive shell after 3107 processing all command-line files. 3108 DEVICE 3109 3110 Contains the name of the device used to render the page, as a 3111 string. 3112 3113 The list of available devices can be discovered with the -h 3114 parameter, as described above. At least the following devices 3115 must be present: cups (CUPS Raster), ijs, pxlmono, pxlcolor, 3116 and opvp (OpenPrinting Vector). 3117 DEVICEHEIGHT 3118 3119 Contains the height, in pixels, of the output device. 3120 3121 The effect of this setting when the current driver is a vector 3122 driver is undefined. 3123 DEVICEHEIGHTPOINTS 3124 3125 Sets the initial page height, in units of 1/72 of an inch. 3126 DEVICEWIDTH 3127 3128 Contains the width, in pixels, of the output device. 3129 3130 The effect of this setting when the current driver is a vector 3131 driver is undefined. 3132 DEVICEWIDTHPOINTS 3133 3134 Sets the initial page width, in units of 1/72 of an inch. 3135 DEVICEXRESOLUTION 3136 3137 Contains the resolution, in pixels per inch, of the X dimension 3138 (horizontal) of the output device. 3139 DEVICEYRESOLUTION 3140 3141 Contains the resolution, in pixels per inch, of the Y dimension 3142 (vertical) of the output device. 3143 NOPAUSE 3144 3145 If set to true, disable the prompt and pause normally displayed 3146 after rendering a page. 3147 OutputFile 3148 3149 Contains the path to the file to which gs should write its 3150 output, as a string. This parameter may be set to '-', in which 3151 case gs's output is sent to standard output. 3152 PAPERSIZE 3153 3154 Contains the string representation of the paper size. The ISO 3155 paper sizes a0-a10 (plus a4small), isob0-isob6, and c0-c6 are 3156 recognized, as are jisb0-jisb6 (JIS standard sizes) and the US 3157 paper sizes 11x17, ledger, legal, letter, lettersmall, and 3158 archA-archE. 3159 QUIET 3160 3161 If set to true, suppress routine information comments on 3162 standard output. 3163 SAFER 3164 3165 If set to true, disable several unsafe PostScript features: the 3166 deletefile and renamefile operators, piped commands, reading or 3167 writing to general files, and changing of certain system 3168 settings. 3169 STRICT 3170 3171 If set to true, disable as many extensions to the Adobe 3172 PostScript specification as possible. 3173 3174 EXIT STATUS 3175 3176 gs returns 0 on successful execution. Any other return value 3177 indicates an error. 3178 3179 AUTHOR 3180 3181 Jeff Licquia (licquia@linux-foundation.org) wrote this man page 3182 for the LSB specification. 3183 3184 Portions of this page were taken from the GhostScript 3185 documentation. The maintainer and rights holder for GhostScript 3186 is Artifex Software, Inc. 3187 __________________________________________________________ 3188 3189 Appendix A. GNU Free Documentation License (Informative) 3190 3191 This specification is published under the terms of the GNU Free 3192 Documentation License, Version 1.1, March 2000 3193 3194 Copyright (C) 2000 Free Software Foundation, Inc. 59 Temple 3195 Place, Suite 330, Boston, MA 02111-1307 USA Everyone is 3196 permitted to copy and distribute verbatim copies of this 3197 license document, but changing it is not allowed. 3198 __________________________________________________________ 3199 3200 A.1. PREAMBLE 3201 3202 The purpose of this License is to make a manual, textbook, or 3203 other written document "free" in the sense of freedom: to 3204 assure everyone the effective freedom to copy and redistribute 3205 it, with or without modifying it, either commercially or 3206 noncommercially. Secondarily, this License preserves for the 3207 author and publisher a way to get credit for their work, while 3208 not being considered responsible for modifications made by 3209 others. 3210 3211 This License is a kind of "copyleft", which means that 3212 derivative works of the document must themselves be free in the 3213 same sense. It complements the GNU General Public License, 3214 which is a copyleft license designed for free software. 3215 3216 We have designed this License in order to use it for manuals 3217 for free software, because free software needs free 3218 documentation: a free program should come with manuals 3219 providing the same freedoms that the software does. But this 3220 License is not limited to software manuals; it can be used for 3221 any textual work, regardless of subject matter or whether it is 3222 published as a printed book. We recommend this License 3223 principally for works whose purpose is instruction or 3224 reference. 3225 __________________________________________________________ 3226 3227 A.2. APPLICABILITY AND DEFINITIONS 3228 3229 This License applies to any manual or other work that contains 3230 a notice placed by the copyright holder saying it can be 3231 distributed under the terms of this License. The "Document", 3232 below, refers to any such manual or work. Any member of the 3233 public is a licensee, and is addressed as "you". 3234 3235 A "Modified Version" of the Document means any work containing 3236 the Document or a portion of it, either copied verbatim, or 3237 with modifications and/or translated into another language. 3238 3239 A "Secondary Section" is a named appendix or a front-matter 3240 section of the Document that deals exclusively with the 3241 relationship of the publishers or authors of the Document to 3242 the Document's overall subject (or to related matters) and 3243 contains nothing that could fall directly within that overall 3244 subject. (For example, if the Document is in part a textbook of 3245 mathematics, a Secondary Section may not explain any 3246 mathematics.) The relationship could be a matter of historical 3247 connection with the subject or with related matters, or of 3248 legal, commercial, philosophical, ethical or political position 3249 regarding them. 3250 3251 The "Invariant Sections" are certain Secondary Sections whose 3252 titles are designated, as being those of Invariant Sections, in 3253 the notice that says that the Document is released under this 3254 License. 3255 3256 The "Cover Texts" are certain short passages of text that are 3257 listed, as Front-Cover Texts or Back-Cover Texts, in the notice 3258 that says that the Document is released under this License. 3259 3260 A "Transparent" copy of the Document means a machine-readable 3261 copy, represented in a format whose specification is available 3262 to the general public, whose contents can be viewed and edited 3263 directly and straightforwardly with generic text editors or 3264 (for images composed of pixels) generic paint programs or (for 3265 drawings) some widely available drawing editor, and that is 3266 suitable for input to text formatters or for automatic 3267 translation to a variety of formats suitable for input to text 3268 formatters. A copy made in an otherwise Transparent file format 3269 whose markup has been designed to thwart or discourage 3270 subsequent modification by readers is not Transparent. A copy 3271 that is not "Transparent" is called "Opaque". 3272 3273 Examples of suitable formats for Transparent copies include 3274 plain ASCII without markup, Texinfo input format, LaTeX input 3275 format, SGML or XML using a publicly available DTD, and 3276 standard-conforming simple HTML designed for human 3277 modification. Opaque formats include PostScript, PDF, 3278 proprietary formats that can be read and edited only by 3279 proprietary word processors, SGML or XML for which the DTD 3280 and/or processing tools are not generally available, and the 3281 machine-generated HTML produced by some word processors for 3282 output purposes only. 3283 3284 The "Title Page" means, for a printed book, the title page 3285 itself, plus such following pages as are needed to hold, 3286 legibly, the material this License requires to appear in the 3287 title page. For works in formats which do not have any title 3288 page as such, "Title Page" means the text near the most 3289 prominent appearance of the work's title, preceding the 3290 beginning of the body of the text. 3291 __________________________________________________________ 3292 3293 A.3. VERBATIM COPYING 3294 3295 You may copy and distribute the Document in any medium, either 3296 commercially or noncommercially, provided that this License, 3297 the copyright notices, and the license notice saying this 3298 License applies to the Document are reproduced in all copies, 3299 and that you add no other conditions whatsoever to those of 3300 this License. You may not use technical measures to obstruct or 3301 control the reading or further copying of the copies you make 3302 or distribute. However, you may accept compensation in exchange 3303 for copies. If you distribute a large enough number of copies 3304 you must also follow the conditions in section 3. 3305 3306 You may also lend copies, under the same conditions stated 3307 above, and you may publicly display copies. 3308 __________________________________________________________ 3309 3310 A.4. COPYING IN QUANTITY 3311 3312 If you publish printed copies of the Document numbering more 3313 than 100, and the Document's license notice requires Cover 3314 Texts, you must enclose the copies in covers that carry, 3315 clearly and legibly, all these Cover Texts: Front-Cover Texts 3316 on the front cover, and Back-Cover Texts on the back cover. 3317 Both covers must also clearly and legibly identify you as the 3318 publisher of these copies. The front cover must present the 3319 full title with all words of the title equally prominent and 3320 visible. You may add other material on the covers in addition. 3321 Copying with changes limited to the covers, as long as they 3322 preserve the title of the Document and satisfy these 3323 conditions, can be treated as verbatim copying in other 3324 respects. 3325 3326 If the required texts for either cover are too voluminous to 3327 fit legibly, you should put the first ones listed (as many as 3328 fit reasonably) on the actual cover, and continue the rest onto 3329 adjacent pages. 3330 3331 If you publish or distribute Opaque copies of the Document 3332 numbering more than 100, you must either include a 3333 machine-readable Transparent copy along with each Opaque copy, 3334 or state in or with each Opaque copy a publicly-accessible 3335 computer-network location containing a complete Transparent 3336 copy of the Document, free of added material, which the general 3337 network-using public has access to download anonymously at no 3338 charge using public-standard network protocols. If you use the 3339 latter option, you must take reasonably prudent steps, when you 3340 begin distribution of Opaque copies in quantity, to ensure that 3341 this Transparent copy will remain thus accessible at the stated 3342 location until at least one year after the last time you 3343 distribute an Opaque copy (directly or through your agents or 3344 retailers) of that edition to the public. 3345 3346 It is requested, but not required, that you contact the authors 3347 of the Document well before redistributing any large number of 3348 copies, to give them a chance to provide you with an updated 3349 version of the Document. 3350 __________________________________________________________ 3351 3352 A.5. MODIFICATIONS 3353 3354 You may copy and distribute a Modified Version of the Document 3355 under the conditions of sections 2 and 3 above, provided that 3356 you release the Modified Version under precisely this License, 3357 with the Modified Version filling the role of the Document, 3358 thus licensing distribution and modification of the Modified 3359 Version to whoever possesses a copy of it. In addition, you 3360 must do these things in the Modified Version: 3361 3362 A. Use in the Title Page (and on the covers, if any) a title 3363 distinct from that of the Document, and from those of 3364 previous versions (which should, if there were any, be 3365 listed in the History section of the Document). You may use 3366 the same title as a previous version if the original 3367 publisher of that version gives permission. 3368 B. List on the Title Page, as authors, one or more persons or 3369 entities responsible for authorship of the modifications in 3370 the Modified Version, together with at least five of the 3371 principal authors of the Document (all of its principal 3372 authors, if it has less than five). 3373 C. State on the Title page the name of the publisher of the 3374 Modified Version, as the publisher. 3375 D. Preserve all the copyright notices of the Document. 3376 E. Add an appropriate copyright notice for your modifications 3377 adjacent to the other copyright notices. 3378 F. Include, immediately after the copyright notices, a license 3379 notice giving the public permission to use the Modified 3380 Version under the terms of this License, in the form shown 3381 in the Addendum below. 3382 G. Preserve in that license notice the full lists of Invariant 3383 Sections and required Cover Texts given in the Document's 3384 license notice. 3385 H. Include an unaltered copy of this License. 3386 I. Preserve the section entitled "History", and its title, and 3387 add to it an item stating at least the title, year, new 3388 authors, and publisher of the Modified Version as given on 3389 the Title Page. If there is no section entitled "History" 3390 in the Document, create one stating the title, year, 3391 authors, and publisher of the Document as given on its 3392 Title Page, then add an item describing the Modified 3393 Version as stated in the previous sentence. 3394 J. Preserve the network location, if any, given in the 3395 Document for public access to a Transparent copy of the 3396 Document, and likewise the network locations given in the 3397 Document for previous versions it was based on. These may 3398 be placed in the "History" section. You may omit a network 3399 location for a work that was published at least four years 3400 before the Document itself, or if the original publisher of 3401 the version it refers to gives permission. 3402 K. In any section entitled "Acknowledgements" or 3403 "Dedications", preserve the section's title, and preserve 3404 in the section all the substance and tone of each of the 3405 contributor acknowledgements and/or dedications given 3406 therein. 3407 L. Preserve all the Invariant Sections of the Document, 3408 unaltered in their text and in their titles. Section 3409 numbers or the equivalent are not considered part of the 3410 section titles. 3411 M. Delete any section entitled "Endorsements". Such a section 3412 may not be included in the Modified Version. 3413 N. Do not retitle any existing section as "Endorsements" or to 3414 conflict in title with any Invariant Section. 3415 3416 If the Modified Version includes new front-matter sections or 3417 appendices that qualify as Secondary Sections and contain no 3418 material copied from the Document, you may at your option 3419 designate some or all of these sections as invariant. To do 3420 this, add their titles to the list of Invariant Sections in the 3421 Modified Version's license notice. These titles must be 3422 distinct from any other section titles. 3423 3424 You may add a section entitled "Endorsements", provided it 3425 contains nothing but endorsements of your Modified Version by 3426 various parties--for example, statements of peer review or that 3427 the text has been approved by an organization as the 3428 authoritative definition of a standard. 3429 3430 You may add a passage of up to five words as a Front-Cover 3431 Text, and a passage of up to 25 words as a Back-Cover Text, to 3432 the end of the list of Cover Texts in the Modified Version. 3433 Only one passage of Front-Cover Text and one of Back-Cover Text 3434 may be added by (or through arrangements made by) any one 3435 entity. If the Document already includes a cover text for the 3436 same cover, previously added by you or by arrangement made by 3437 the same entity you are acting on behalf of, you may not add 3438 another; but you may replace the old one, on explicit 3439 permission from the previous publisher that added the old one. 3440 3441 The author(s) and publisher(s) of the Document do not by this 3442 License give permission to use their names for publicity for or 3443 to assert or imply endorsement of any Modified Version. 3444 __________________________________________________________ 3445 3446 A.6. COMBINING DOCUMENTS 3447 3448 You may combine the Document with other documents released 3449 under this License, under the terms defined in section 4 above 3450 for modified versions, provided that you include in the 3451 combination all of the Invariant Sections of all of the 3452 original documents, unmodified, and list them all as Invariant 3453 Sections of your combined work in its license notice. 3454 3455 The combined work need only contain one copy of this License, 3456 and multiple identical Invariant Sections may be replaced with 3457 a single copy. If there are multiple Invariant Sections with 3458 the same name but different contents, make the title of each 3459 such section unique by adding at the end of it, in parentheses, 3460 the name of the original author or publisher of that section if 3461 known, or else a unique number. Make the same adjustment to the 3462 section titles in the list of Invariant Sections in the license 3463 notice of the combined work. 3464 3465 In the combination, you must combine any sections entitled 3466 "History" in the various original documents, forming one 3467 section entitled "History"; likewise combine any sections 3468 entitled "Acknowledgements", and any sections entitled 3469 "Dedications". You must delete all sections entitled 3470 "Endorsements." 3471 __________________________________________________________ 3472 3473 A.7. COLLECTIONS OF DOCUMENTS 3474 3475 You may make a collection consisting of the Document and other 3476 documents released under this License, and replace the 3477 individual copies of this License in the various documents with 3478 a single copy that is included in the collection, provided that 3479 you follow the rules of this License for verbatim copying of 3480 each of the documents in all other respects. 3481 3482 You may extract a single document from such a collection, and 3483 distribute it individually under this License, provided you 3484 insert a copy of this License into the extracted document, and 3485 follow this License in all other respects regarding verbatim 3486 copying of that document. 3487 __________________________________________________________ 3488 3489 A.8. AGGREGATION WITH INDEPENDENT WORKS 3490 3491 A compilation of the Document or its derivatives with other 3492 separate and independent documents or works, in or on a volume 3493 of a storage or distribution medium, does not as a whole count 3494 as a Modified Version of the Document, provided no compilation 3495 copyright is claimed for the compilation. Such a compilation is 3496 called an "aggregate", and this License does not apply to the 3497 other self-contained works thus compiled with the Document, on 3498 account of their being thus compiled, if they are not 3499 themselves derivative works of the Document. 3500 3501 If the Cover Text requirement of section 3 is applicable to 3502 these copies of the Document, then if the Document is less than 3503 one quarter of the entire aggregate, the Document's Cover Texts 3504 may be placed on covers that surround only the Document within 3505 the aggregate. Otherwise they must appear on covers around the 3506 whole aggregate. 3507 __________________________________________________________ 3508 3509 A.9. TRANSLATION 3510 3511 Translation is considered a kind of modification, so you may 3512 distribute translations of the Document under the terms of 3513 section 4. Replacing Invariant Sections with translations 3514 requires special permission from their copyright holders, but 3515 you may include translations of some or all Invariant Sections 3516 in addition to the original versions of these Invariant 3517 Sections. You may include a translation of this License 3518 provided that you also include the original English version of 3519 this License. In case of a disagreement between the translation 3520 and the original English version of this License, the original 3521 English version will prevail. 3522 __________________________________________________________ 3523 3524 A.10. TERMINATION 3525 3526 You may not copy, modify, sublicense, or distribute the 3527 Document except as expressly provided for under this License. 3528 Any other attempt to copy, modify, sublicense or distribute the 3529 Document is void, and will automatically terminate your rights 3530 under this License. However, parties who have received copies, 3531 or rights, from you under this License will not have their 3532 licenses terminated so long as such parties remain in full 3533 compliance. 3534 __________________________________________________________ 3535 3536 A.11. FUTURE REVISIONS OF THIS LICENSE 3537 3538 The Free Software Foundation may publish new, revised versions 3539 of the GNU Free Documentation License from time to time. Such 3540 new versions will be similar in spirit to the present version, 3541 but may differ in detail to address new problems or concerns. 3542 See http://www.gnu.org/copyleft/. 3543 3544 Each version of the License is given a distinguishing version 3545 number. If the Document specifies that a particular numbered 3546 version of this License "or any later version" applies to it, 3547 you have the option of following the terms and conditions 3548 either of that specified version or of any later version that 3549 has been published (not as a draft) by the Free Software 3550 Foundation. If the Document does not specify a version number 3551 of this License, you may choose any version ever published (not 3552 as a draft) by the Free Software Foundation. 3553 __________________________________________________________ 3554 3555 A.12. How to use this License for your documents 3556 3557 To use this License in a document you have written, include a 3558 copy of the License in the document and put the following 3559 copyright and license notices just after the title page: 3560 3561 Copyright (c) YEAR YOUR NAME. Permission is granted to copy, 3562 distribute and/or modify this document under the terms of 3563 the GNU Free Documentation License, Version 1.1 or any later 3564 version published by the Free Software Foundation; with the 3565 Invariant Sections being LIST THEIR TITLES, with the 3566 Front-Cover Texts being LIST, and with the Back-Cover Texts 3567 being LIST. A copy of the license is included in the section 3568 entitled "GNU Free Documentation License". 3569 3570 If you have no Invariant Sections, write "with no Invariant 3571 Sections" instead of saying which ones are invariant. If you 3572 have no Front-Cover Texts, write "no Front-Cover Texts" instead 3573 of "Front-Cover Texts being LIST"; likewise for Back-Cover 3574 Texts. 3575 3576 If your document contains nontrivial examples of program code, 3577 we recommend releasing these examples in parallel under your 3578 choice of free software license, such as the GNU General Public 3579 License, to permit their use in free software.