#CONTENTSCUPS Software Programmers ManualCUPS Software Programmers Manual
CUPS-SPM-1.1.23
Easy Software Products
Copyright 1997-2005, All Rights Reserved
Table of Contents 
#1Preface #1_1System Overview #1_2Document Overview #1_3Notation Conventions #1_4Abbreviations #1_5Other References #OVERVIEW1 - Printing System Overview #2_1The Printing Problem #2_2The Technology #2_3Jobs #2_4Classes #2_5Filters #2_6Backends #2_7Printer Drivers #2_8Networking #CUPS_API2 - The CUPS API #3_1The CUPS API Library #3_1_1Detecting the CUPS API Library in GNU Autoconf #3_2Printing Services #3_2_1Include Files #3_2_2Printing a File #3_2_3Printing Multiple Files #3_2_4Cancelling Jobs #3_2_5Getting the Available Printers and Classes #3_2_6Printing with Options #3_2_7Setting Printer Options #3_2_8Getting Errors #3_2_9Passwords and Authentication #3_3PPD Services #3_3_1Include Files #3_3_2Getting a PPD File for a Printer #3_3_3Loading a PPD File #3_3_4Freeing PPD File Information #3_3_5The PPD File Structure #3_3_6Marking Options #3_3_7Checking for Conflicts #WRITING_FILTERS3 - Writing Filters #4_1Overview #4_1_1Security Considerations #4_1_2Users and Groups #4_1_3Temporary Files #4_1_4Sending Messages to the User #4_1_5Page Accounting #4_1_6Command-Line Arguments #4_1_7Copy Generation #4_1_8Environment Variables #4_2Dissecting the HP-GL/2 Filter #4_2_1Initializing the Filter #4_3PostScript Output #WRITING_DRIVERS4 - Writing Printer Drivers #5_1Overview #5_1_1CUPS Raster Data #5_1_2Page Accounting #5_1_3Color Management #5_1_4Device and Bitmap Variables #5_2Dissecting the HP-PCL Driver #5_2_1PPD Files #5_2_2Reading Raster Data #WRITING_BACKENDS5 - Writing Backends #6_1Overview #6_1_1Security Considerations #6_1_2Command-Line Arguments #6_1_3Copy Generation #6_1_4Page Accounting #6_1_5Exclusive Access #6_1_6Retries #6_2Dissecting the Serial Port Backend #6_2_1Supporting Device Discovery #6_2_2Opening the Serial Port #6_2_3Writing Data to the Port #6_2_4Finishing Up #LICENSEA - Software License Agreement #7_1Common UNIX Printing System License Agreement #7_1_1Introduction #7_1_2License Exceptions #7_1_3Trademarks #7_1_4Binary Distribution Rights #7_1_5Support #7_2GNU GENERAL PUBLIC LICENSE #7_2_1Preamble #7_3GNU LIBRARY GENERAL PUBLIC LICENSE #7_3_1Preamble #CONSTANTSB - Constants #8_1CUPS Constants #8_1_1Version Number #8_1_2Printer Capabilities #8_1_3Encodings #8_2HTTP Constants #8_2_1Limits #8_2_2Status Codes #8_2_3Fields #8_3IPP Constants #8_3_1Limits #8_3_2Tags #8_3_3Resolution Units #8_3_4Finishings #8_3_5Orientations #8_3_6Qualities #8_3_7Job States #8_3_8Printer States #8_3_9Operations #8_3_10Status Codes #8_4PPD Constants #8_4_1PPD Format Version #8_4_2PPD User-Interface Types #8_4_3PPD Sections #8_4_4PPD Colorspaces #8_5Raster Constants #8_5_1Raster Sync Words #8_5_2Raster Stream Modes #8_5_3Raster Boolean Constants #8_5_4Raster Jog Values #8_5_5Raster Orientation Values #8_5_6Raster CutMedia Values #8_5_7Raster AdvanceMedia Values #8_5_8Raster LeadingEdge Values #8_5_9Raster Color Order Values #8_5_10Raster Colorspace Values #STRUCTURESC - Structures #9_1CUPS Structures #cups_dest_tCUPS Destinations #cups_job_tCUPS Jobs #cups_lang_tCUPS Messages #cups_option_tCUPS Options #9_2Networking Structures #http_tHTTP State #ipp_tIPP State #ipp_attribute_tIPP Attribute #9_3PPD Structures #ppd_file_tPPD File #ppd_choice_tPPD Choice #9_4Raster Structures #cups_raster_tRaster Stream #cups_raster_header_tRaster Page Header #FUNCTIONSD - Functions #cupsAddDestcupsAddDest() #10_1_1Usage #10_1_2Arguments #10_1_3Returns #10_1_4Description #10_1_5Example #10_1_6See Also #cupsAddOptioncupsAddOption() #10_2_1Usage #10_2_2Arguments #10_2_3Returns #10_2_4Description #10_2_5Example #10_2_6See Also #cupsCancelJobcupsCancelJob() #10_3_1Usage #10_3_2Arguments #10_3_3Returns #10_3_4Description #10_3_5Example #10_3_6See Also #cupsDoAuthenticationcupsDoAuthentication() #10_4_1Usage #10_4_2Arguments #10_4_3Returns #10_4_4Description #10_4_5Example #10_4_6See Also #cupsDoFileRequestcupsDoFileRequest() #10_5_1Usage #10_5_2Arguments #10_5_3Returns #10_5_4Description #10_5_5Example #10_5_6See Also #cupsDoRequestcupsDoRequest() #10_6_1Usage #10_6_2Arguments #10_6_3Returns #10_6_4Description #10_6_5Example #10_6_6See Also #cupsEncodeOptionscupsEncodeOptions() #10_7_1Usage #10_7_2Arguments #10_7_3Description #10_7_4Example #10_7_5See Also #cupsEncryptioncupsEncryption() #10_8_1Usage #10_8_2Returns #10_8_3Description #10_8_4Example #10_8_5See Also #cupsFreeDestscupsFreeDests() #10_9_1Usage #10_9_2Arguments #10_9_3Description #10_9_4Example #10_9_5See Also #cupsFreeJobscupsFreeJobs() #10_10_1Usage #10_10_2Arguments #10_10_3Description #10_10_4Example #10_10_5See Also #cupsFreeOptionscupsFreeOptions() #10_11_1Usage #10_11_2Arguments #10_11_3Description #10_11_4Example #10_11_5See Also #cupsGetClassescupsGetClasses() #10_12_1Usage #10_12_2Arguments #10_12_3Returns #10_12_4Description #10_12_5Example #10_12_6See Also #cupsGetDefaultcupsGetDefault() #10_13_1Usage #10_13_2Returns #10_13_3Description #10_13_4Example #10_13_5See Also #cupsGetDestcupsGetDest() #10_14_1Usage #10_14_2Arguments #10_14_3Returns #10_14_4Description #10_14_5Example #10_14_6See Also #cupsGetDestscupsGetDests() #10_15_1Usage #10_15_2Arguments #10_15_3Returns #10_15_4Description #10_15_5Example #10_15_6See Also #cupsGetFdcupsGetFd() #10_16_1Usage #10_16_2Arguments #10_16_3Returns #10_16_4Description #10_16_5Example #10_16_6See Also #cupsGetFilecupsGetFile() #10_17_1Usage #10_17_2Arguments #10_17_3Returns #10_17_4Description #10_17_5Example #10_17_6See Also #cupsGetJobscupsGetJobs() #10_18_1Usage #10_18_2Arguments #10_18_3Returns #10_18_4Description #10_18_5Example #10_18_6See Also #cupsGetOptioncupsGetOption() #10_19_1Usage #10_19_2Arguments #10_19_3Returns #10_19_4Description #10_19_5See Also #cupsGetPasswordcupsGetPassword() #10_20_1Usage #10_20_2Arguments #10_20_3Returns #10_20_4Description #10_20_5Example #10_20_6See Also #cupsGetPPDcupsGetPPD() #10_21_1Usage #10_21_2Arguments #10_21_3Returns #10_21_4Description #10_21_5Example #cupsGetPrinterscupsGetPrinters() #10_22_1Usage #10_22_2Arguments #10_22_3Returns #10_22_4Description #10_22_5Example #10_22_6See Also #cupsLangDefaultcupsLangDefault() #10_23_1Usage #10_23_2Returns #10_23_3Description #10_23_4Example #10_23_5See Also #cupsLangEncodingcupsLangEncoding() #10_24_1Usage #10_24_2Arguments #10_24_3Returns #10_24_4Description #10_24_5Example #10_24_6See Also #cupsLangFlushcupsLangFlush() #10_25_1Usage #10_25_2Description #10_25_3Example #10_25_4See Also #cupsLangFreecupsLangFree() #10_26_1Usage #10_26_2Arguments #10_26_3Description #10_26_4Example #10_26_5See Also #cupsLangGetcupsLangGet() #10_27_1Usage #10_27_2Arguments #10_27_3Returns #10_27_4Description #10_27_5Example #10_27_6See Also #cupsLangStringcupsLangString() #10_28_1Usage #10_28_2Arguments #10_28_3Returns #10_28_4Description #10_28_5Example #10_28_6See Also #cupsLastErrorcupsLastError() #10_29_1Usage #10_29_2Returns #10_29_3Description #10_29_4Example #10_29_5See Also #cupsMarkOptionscupsMarkOptions() #10_30_1Usage #10_30_2Arguments #10_30_3Returns #10_30_4Description #10_30_5Example #10_30_6See Also #cupsParseOptionscupsParseOptions() #10_31_1Usage #10_31_2Arguments #10_31_3Returns #10_31_4Description #10_31_5Example #10_31_6See Also #cupsPrintFilecupsPrintFile() #10_32_1Usage #10_32_2Arguments #10_32_3Returns #10_32_4Description #10_32_5Example #10_32_6See Also #cupsPrintFilescupsPrintFiles() #10_33_1Usage #10_33_2Arguments #10_33_3Returns #10_33_4Description #10_33_5Example #10_33_6See Also #cupsPutFdcupsPutFd() #10_34_1Usage #10_34_2Arguments #10_34_3Returns #10_34_4Description #10_34_5Example #10_34_6See Also #cupsPutFilecupsPutFile() #10_35_1Usage #10_35_2Arguments #10_35_3Returns #10_35_4Description #10_35_5Example #10_35_6See Also #cupsRasterClosecupsRasterClose() #10_36_1Usage #10_36_2Arguments #10_36_3Description #10_36_4Example #10_36_5See Also #cupsRasterOpencupsRasterOpen() #10_37_1Usage #10_37_2Arguments #10_37_3Returns #10_37_4Description #10_37_5Example #10_37_6See Also #cupsRasterReadHeadercupsRasterReadHeader() #10_38_1Usage #10_38_2Arguments #10_38_3Returns #10_38_4Description #10_38_5Example #10_38_6See Also #cupsRasterReadPixelscupsRasterReadPixels() #10_39_1Usage #10_39_2Arguments #10_39_3Returns #10_39_4Description #10_39_5Example #10_39_6See Also #cupsRasterWriteHeadercupsRasterWriteHeader() #10_40_1Usage #10_40_2Arguments #10_40_3Returns #10_40_4Description #10_40_5Example #10_40_6See Also #cupsRasterWritePixelscupsRasterWritePixels() #10_41_1Usage #10_41_2Arguments #10_41_3Returns #10_41_4Description #10_41_5Example #10_41_6See Also #cupsServercupsServer() #10_42_1Usage #10_42_2Returns #10_42_3Description #10_42_4Example #10_42_5See Also #cupsSetDestscupsSetDests() #10_43_1Usage #10_43_2Arguments #10_43_3Description #10_43_4Example #10_43_5See Also #cupsSetEncryptioncupsSetEncryption() #10_44_1Usage #10_44_2Arguments #10_44_3Description #10_44_4Example #10_44_5See Also #cupsSetPasswordCBcupsSetPasswordCB() #10_45_1Usage #10_45_2Arguments #10_45_3Description #10_45_4Example #10_45_5See Also #cupsSetServercupsSetServer() #10_46_1Usage #10_46_2Arguments #10_46_3Description #10_46_4Example #10_46_5See Also #cupsSetUsercupsSetUser() #10_47_1Usage #10_47_2Arguments #10_47_3Description #10_47_4Example #10_47_5See Also #cupsTempFdcupsTempFd() #10_48_1Usage #10_48_2Arguments #10_48_3Returns #10_48_4Description #10_48_5Example #10_48_6See Also #cupsTempFilecupsTempFile() #10_49_1Usage #10_49_2Arguments #10_49_3Returns #10_49_4Description #10_49_5Example #10_49_6See Also #cupsUsercupsUser() #10_50_1Usage #10_50_2Returns #10_50_3Description #10_50_4Example #10_50_5See Also #httpBlockinghttpBlocking() #10_51_1Usage #10_51_2Arguments #10_51_3Description #10_51_4Example #10_51_5See Also #httpCheckhttpCheck() #10_52_1Usage #10_52_2Arguments #10_52_3Returns #10_52_4Description #10_52_5Example #10_52_6See Also #httpClearFieldshttpClearFields() #10_53_1Usage #10_53_2Arguments #10_53_3Description #10_53_4Example #10_53_5See Also #httpClosehttpClose() #10_54_1Usage #10_54_2Arguments #10_54_3Description #10_54_4Example #10_54_5See Also #httpConnecthttpConnect() #10_55_1Usage #10_55_2Arguments #10_55_3Returns #10_55_4Description #10_55_5Example #10_55_6See Also #httpConnectEncrypthttpConnectEncrypt() #10_56_1Usage #10_56_2Arguments #10_56_3Returns #10_56_4Description #10_56_5Example #10_56_6See Also #httpDecode64httpDecode64() #10_57_1Usage #10_57_2Arguments #10_57_3Returns #10_57_4Description #10_57_5Example #10_57_6See Also #httpDeletehttpDelete() #10_58_1Usage #10_58_2Arguments #10_58_3Returns #10_58_4Description #10_58_5Example #10_58_6See Also #httpEncode64httpEncode64() #10_59_1Usage #10_59_2Arguments #10_59_3Returns #10_59_4Description #10_59_5Example #10_59_6See Also #httpEncryptionhttpEncryption() #10_60_1Usage #10_60_2Arguments #10_60_3Returns #10_60_4Description #10_60_5Example #10_60_6See Also #httpErrorhttpError() #10_61_1Usage #10_61_2Arguments #10_61_3Returns #10_61_4Description #10_61_5Example #10_61_6See Also #httpFlushhttpFlush() #10_62_1Usage #10_62_2Arguments #10_62_3Description #10_62_4Example #10_62_5See Also #httpGethttpGet() #10_63_1Usage #10_63_2Arguments #10_63_3Returns #10_63_4Description #10_63_5Example #10_63_6See Also #httpGetshttpGets() #10_64_1Usage #10_64_2Arguments #10_64_3Returns #10_64_4Description #10_64_5Example #10_64_6See Also #httpGetDateStringhttpGetDateString() #10_65_1Usage #10_65_2Arguments #10_65_3Returns #10_65_4Description #10_65_5Example #10_65_6See Also #httpGetDateTimehttpGetDateTime() #10_66_1Usage #10_66_2Arguments #10_66_3Returns #10_66_4Description #10_66_5Example #10_66_6See Also #httpGetFieldhttpGetField() #10_67_1Usage #10_67_2Arguments #10_67_3Returns #10_67_4Description #10_67_5Example #10_67_6See Also #httpGetHostByNamehttpGetHostByName() #10_68_1Usage #10_68_2Arguments #10_68_3Returns #10_68_4Description #10_68_5Example #httpGetLengthhttpGetLength() #10_69_1Usage #10_69_2Arguments #10_69_3Returns #10_69_4Description #10_69_5Example #10_69_6See Also #httpGetSubFieldhttpGetSubField() #10_70_1Usage #10_70_2Arguments #10_70_3Returns #10_70_4Description #10_70_5Example #10_70_6See Also #httpHeadhttpHead() #10_71_1Usage #10_71_2Arguments #10_71_3Returns #10_71_4Description #10_71_5Example #10_71_6See Also #httpInitializehttpInitialize() #10_72_1Usage #10_72_2Description #10_72_3Example #10_72_4See Also #httpMD5httpMD5() #10_73_1Usage #10_73_2Arguments #10_73_3Returns #10_73_4Description #10_73_5Example #10_73_6See Also #httpMD5FinalhttpMD5Final() #10_74_1Usage #10_74_2Arguments #10_74_3Returns #10_74_4Description #10_74_5Example #10_74_6See Also #httpMD5StringhttpMD5String() #10_75_1Usage #10_75_2Arguments #10_75_3Returns #10_75_4Description #10_75_5Example #10_75_6See Also #httpOptionshttpOptions() #10_76_1Usage #10_76_2Arguments #10_76_3Returns #10_76_4Description #10_76_5Example #10_76_6See Also #httpPosthttpPost() #10_77_1Usage #10_77_2Arguments #10_77_3Returns #10_77_4Description #10_77_5Example #10_77_6See Also #httpPrintfhttpPrintf() #10_78_1Usage #10_78_2Arguments #10_78_3Returns #10_78_4Description #10_78_5Example #10_78_6See Also #httpPuthttpPut() #10_79_1Usage #10_79_2Arguments #10_79_3Returns #10_79_4Description #10_79_5Example #10_79_6See Also #httpReadhttpRead() #10_80_1Usage #10_80_2Arguments #10_80_3Returns #10_80_4Description #10_80_5Example #10_80_6See Also #httpReconnecthttpReconnect() #10_81_1Usage #10_81_2Arguments #10_81_3Returns #10_81_4Description #10_81_5Example #10_81_6See Also #httpSeparatehttpSeparate() #10_82_1Usage #10_82_2Arguments #10_82_3Description #10_82_4Example #10_82_5See Also #httpSetFieldhttpSetField() #10_83_1Usage #10_83_2Arguments #10_83_3Description #10_83_4Example #10_83_5See Also #httpStatushttpStatus() #10_84_1Usage #10_84_2Arguments #10_84_3Returns #10_84_4Description #10_84_5Example #httpTracehttpTrace() #10_85_1Usage #10_85_2Arguments #10_85_3Returns #10_85_4Description #10_85_5Example #10_85_6See Also #httpUpdatehttpUpdate() #10_86_1Usage #10_86_2Arguments #10_86_3Returns #10_86_4Description #10_86_5Example #10_86_6See Also #httpWritehttpWrite() #10_87_1Usage #10_87_2Arguments #10_87_3Returns #10_87_4Description #10_87_5Example #10_87_6See Also #ippAddBooleanippAddBoolean() #10_88_1Usage #10_88_2Arguments #10_88_3Returns #10_88_4Description #10_88_5Example #10_88_6See Also #ippAddBooleansippAddBooleans() #10_89_1Usage #10_89_2Arguments #10_89_3Returns #10_89_4Description #10_89_5Example #10_89_6See Also #ippAddDateippAddDate() #10_90_1Usage #10_90_2Arguments #10_90_3Returns #10_90_4Description #10_90_5Example #10_90_6See Also #ippAddIntegerippAddInteger() #10_91_1Usage #10_91_2Arguments #10_91_3Returns #10_91_4Description #10_91_5Example #10_91_6See Also #ippAddIntegersippAddIntegers() #10_92_1Usage #10_92_2Arguments #10_92_3Returns #10_92_4Description #10_92_5Example #10_92_6See Also #ippAddRangeippAddRange() #10_93_1Usage #10_93_2Arguments #10_93_3Returns #10_93_4Description #10_93_5Example #10_93_6See Also #ippAddRangesippAddRanges() #10_94_1Usage #10_94_2Arguments #10_94_3Returns #10_94_4Description #10_94_5Example #10_94_6See Also #ippAddResolutionippAddResolution() #10_95_1Usage #10_95_2Arguments #10_95_3Returns #10_95_4Description #10_95_5Example #10_95_6See Also #ippAddResolutionsippAddResolutions() #10_96_1Usage #10_96_2Arguments #10_96_3Returns #10_96_4Description #10_96_5Example #10_96_6See Also #ippAddSeparatorippAddSeparator() #10_97_1Usage #10_97_2Arguments #10_97_3Returns #10_97_4Description #10_97_5Example #10_97_6See Also #ippAddStringippAddString() #10_98_1Usage #10_98_2Arguments #10_98_3Returns #10_98_4Description #10_98_5Example #10_98_6See Also #ippAddStringsippAddStrings() #10_99_1Usage #10_99_2Arguments #10_99_3Returns #10_99_4Description #10_99_5Example #10_99_6See Also #ippDateToTimeippDateToTime() #10_100_1Usage #10_100_2Arguments #10_100_3Returns #10_100_4Description #10_100_5Example #10_100_6See Also #ippDeleteippDelete() #10_101_1Usage #10_101_2Arguments #10_101_3Description #10_101_4Example #10_101_5See Also #ippErrorStringippErrorString() #10_102_1Usage #10_102_2Arguments #10_102_3Returns #10_102_4Description #10_102_5Example #10_102_6See Also #ippFindAttributeippFindAttribute() #10_103_1Usage #10_103_2Arguments #10_103_3Returns #10_103_4Description #10_103_5Example #10_103_6See Also #ippFindNextAttributeippFindNextAttribute() #10_104_1Usage #10_104_2Arguments #10_104_3Returns #10_104_4Description #10_104_5Example #10_104_6See Also #ippLengthippLength() #10_105_1Usage #10_105_2Arguments #10_105_3Returns #10_105_4Description #10_105_5Example #10_105_6See Also #ippNewippNew() #10_106_1Usage #10_106_2Returns #10_106_3Description #10_106_4Example #10_106_5See Also #ippPortippPort() #10_107_1Usage #10_107_2Returns #10_107_3Description #10_107_4Example #10_107_5See Also #ippReadippRead() #10_108_1Usage #10_108_2Arguments #10_108_3Returns #10_108_4Description #10_108_5Example #10_108_6See Also #ippSetPortippSetPort() #10_109_1Usage #10_109_2Arguments #10_109_3Description #10_109_4Example #10_109_5See Also #ippTimeToDateippTimeToDate() #10_110_1Usage #10_110_2Arguments #10_110_3Returns #10_110_4Description #10_110_5Example #10_110_6See Also #ippWriteippWrite() #10_111_1Usage #10_111_2Arguments #10_111_3Returns #10_111_4Description #10_111_5Example #10_111_6See Also #ppdCloseppdClose() #10_112_1Usage #10_112_2Arguments #10_112_3Description #10_112_4Example #10_112_5See Also #ppdCollectppdCollect() #10_113_1Usage #10_113_2Arguments #10_113_3Returns #10_113_4Description #10_113_5Example #10_113_6See Also #ppdConflictsppdConflicts() #10_114_1Usage #10_114_2Arguments #10_114_3Returns #10_114_4Description #10_114_5Example #10_114_6See Also #ppdEmitppdEmit() #10_115_1Usage #10_115_2Arguments #10_115_3Returns #10_115_4Description #10_115_5Example #10_115_6See Also #ppdEmitFdppdEmitFd() #10_116_1Usage #10_116_2Arguments #10_116_3Returns #10_116_4Description #10_116_5Example #10_116_6See Also #ppdEmitJCLppdEmitJCL() #10_117_1Usage #10_117_2Arguments #10_117_3Returns #10_117_4Description #10_117_5Example #10_117_6See Also #ppdFindAttrppdFindAttr() #10_118_1Usage #10_118_2Arguments #10_118_3Returns #10_118_4Description #10_118_5Example #10_118_6See Also #ppdFindChoiceppdFindChoice() #10_119_1Usage #10_119_2Arguments #10_119_3Returns #10_119_4Description #10_119_5Example #10_119_6See Also #ppdFindMarkedChoiceppdFindMarkedChoice() #10_120_1Usage #10_120_2Arguments #10_120_3Returns #10_120_4Description #10_120_5Example #10_120_6See Also #ppdFindNextAttrppdFindNextAttr() #10_121_1Usage #10_121_2Arguments #10_121_3Returns #10_121_4Description #10_121_5Example #10_121_6See Also #ppdFindOptionppdFindOption() #10_122_1Usage #10_122_2Arguments #10_122_3Returns #10_122_4Description #10_122_5Example #10_122_6See Also #ppdIsMarkedppdIsMarked() #10_123_1Usage #10_123_2Arguments #10_123_3Returns #10_123_4Description #10_123_5Example #10_123_6See Also #ppdMarkDefaultsppdMarkDefaults() #10_124_1Usage #10_124_2Arguments #10_124_3Description #10_124_4Example #10_124_5See Also #ppdMarkOptionppdMarkOption() #10_125_1Usage #10_125_2Arguments #10_125_3Returns #10_125_4Description #10_125_5Example #10_125_6See Also #ppdOpenppdOpen() #10_126_1Usage #10_126_2Arguments #10_126_3Returns #10_126_4Description #10_126_5Example #10_126_6See Also #ppdOpenFdppdOpenFd() #10_127_1Usage #10_127_2Arguments #10_127_3Returns #10_127_4Description #10_127_5Example #10_127_6See Also #ppdOpenFileppdOpenFile() #10_128_1Usage #10_128_2Arguments #10_128_3Returns #10_128_4Description #10_128_5Example #10_128_6See Also #ppdPageLengthppdPageLength() #10_129_1Usage #10_129_2Arguments #10_129_3Returns #10_129_4Description #10_129_5Example #10_129_6See Also #ppdPageSizeppdPageSize() #10_130_1Usage #10_130_2Arguments #10_130_3Returns #10_130_4Description #10_130_5Example #10_130_6See Also #ppdPageWidthppdPageWidth() #10_131_1Usage #10_131_2Arguments #10_131_3Returns #10_131_4Description #10_131_5Example #10_131_6See Also Preface 
This software programmers manual provides software programming
 information for the Common UNIX Printing System ("CUPS") Version
 1.1.23.
System Overview 
CUPS provides a portable printing layer for UNIX®-based operating
 systems. It has been developed by 
http://www.easysw.comEasy
 Software Products
 to promote a standard printing solution for all
 UNIX vendors and users. CUPS provides the System V and Berkeley
 command-line interfaces.
CUPS uses the Internet Printing Protocol ("IPP") as the basis for
 managing print jobs and queues. The Line Printer Daemon ("LPD") Server
 Message Block ("SMB"), and AppSocket (a.k.a. JetDirect) protocols are
 also supported with reduced functionality. CUPS adds network printer
 browsing and PostScript Printer Description ("PPD") based printing
 options to support real-world printing under UNIX.
CUPS includes an image file RIP that supports printing of image files
 to non-PostScript printers. A customized version of GNU Ghostscript
 7.05 for CUPS called ESP Ghostscript is available separately to support
 printing of PostScript files within the CUPS driver framework. Sample
 drivers for Dymo, EPSON, HP, and OKIDATA printers are included that use
 these filters.
Drivers for thousands of printers are provided with our ESP Print Pro
 software, available at:
    
http://www.easysw.com/printpro/http://www.easysw.com/printpro/ CUPS is licensed under the GNU General Public License and GNU Library
 General Public License. Please contact Easy Software Products for
 commercial support and "binary distribution" rights.
Document Overview 
This software programmers manual is organized into the following
 sections:
#OVERVIEW1 - Printing System Overview #CUPS_API2 - The CUPS API #WRITING_FILTERS3 - Writing Filters #WRITING_DRIVERS4 - Writing Printer Drivers #WRITING_BACKENDS5 - Writing Backends #LICENSEA - Software License Agreement #CONSTANTSB - Constants #STRUCTURESC - Structures #FUNCTIONSD - Functions Notation Conventions 
Various font and syntax conventions are used in this guide. Examples
 and their meanings and uses are explained below:
Example    Description  lpstat lpstat(1)    The names of commands;
 the first mention of a command or function in a chapter is followed by
 a manual page section number.
 /var /usr/share/cups/data/testprint.ps    File and directory names.
 Request ID is Printer-123    
Screen output.  lp -d printer filename ENTER    
Literal user input; special keys like ENTER are
 in ALL CAPS.
 12.3    Numbers in the text are
 written using the period (.) to indicate the decimal point.
Abbreviations 
 The following abbreviations are used throughout this manual:
kbKilobytes, or 1024 bytes
 MbMegabytes, or 1048576 bytes
 GbGigabytes, or 1073741824 bytes
 Other References 
CUPS Software Administrators ManualAn administration guide for the CUPS software.
 CUPS Software Users ManualAn end-user guide for using the CUPS software.
 1 - Printing System Overview 
This chapter provides an overview of how the Common UNIX Printing
 System works.
The Printing Problem 
For years the printing problem has plagued UNIX. Unlike
 Microsoft® Windows® or Mac OS, UNIX has no standard interface or system
 in place for supporting printers. Among the solutions currently
 available, the Berkeley and System V printing systems are the most
 prevalent.
These printing systems support line printers (text only) or
 PostScript printers (text and graphics), and with some coaxing they can
 be made to support a full range of printers and file formats. However,
 because each varient of the UNIX operating system uses a different
 printing system than the next developing printer drivers for a wide
 range of printers and operating systems is extremely difficult. That
 combined with the limited volume of customers for each UNIX varient has
 forced most printer vendors to give up supporting UNIX entirely.
CUPS is designed to eliminate the printing problem. One common
 printing system can be used by all UNIX varients to support the
 printing needs of users. Printer vendors can use its modular filter
 interface to develop a single driver program that supports a wide range
 of file formats with little or no effort. Since CUPS provides both the
 System V and Berkeley printing commands, users (and applications) can
 reap the benefits of this new technology with no changes.
The Technology 
CUPS is based upon an emerging Internet standard called the Internet
 Printing Protocol. IPP has been embraced by dozens of printer and
 printer server manufacturers and is supported by Microsoft Windows
 2000.
IPP defines a standard protocol for printing as well as managing
 print jobs and printer options like media size, resolution, and so
 forth. Like all IP-based protocols, IPP can be used locally or over the
 Internet to printers hundreds or thousands of miles away. Unlike other
 protocols, however, IPP also supports access control, authentication,
 and encryption, making it a much more capable and secure printing
 solution than older ones.
IPP is layered on top of the Hyper-Text Transport Protocol ("HTTP")
 which is the basis of web servers on the Internet. This allows users to
 view documentation, check status information on a printer or server,
 and manage their printers, classes, and jobs using their web browser.
CUPS provides a complete IPP/1.1 based printing system that provides
 Basic, Digest, and local certificate authentication and user, domain,
 or IP-based access control. TLS encryption will be available in future
 versions of CUPS.
Jobs 
Each file or set of files that is submitted for printing is called a job
. Jobs are identified by a unique number starting at 1 and are
 assigned to a particular destination, usually a printer. Jobs can also
 have options associated with them such as media size, number of copies,
 and priority.
Classes 
CUPS supports collections of printers known as classes. Jobs
 sent to a class are forwarded to the first available printer in the
 class.
Filters 
Filters allow a user or application to print many types of files
 without extra effort. Print jobs sent to a CUPS server are filtered
 before sending them to a printer. Some filters convert job files to
 different formats that the printer can understand. Others perform page
 selection and ordering tasks.
CUPS provides filters for printing many types of image files, HP-GL/2
 files, PDF files, and text files. CUPS also supplies PostScript and
 image file Raster Image Processor ("RIP") filters that convert
 PostScript or image files into bitmaps that can be sent to a raster
 printer.
Backends 
Backends perform the most important task of all - they send the
 filtered print data to the printer.
CUPS provides backends for printing over parallel, serial, and USB
 ports, and over the network via the IPP, JetDirect (AppSocket), and
 Line Printer Daemon ("LPD") protocols. Additional backends are
 available in network service packages such as the SMB backend included
 with the popular SAMBA software.
Backends are also used to determine the available devices. On startup
 each backend is asked for a list of devices it supports, and any
 information that is available. This allows the parallel backend to tell
 CUPS that an EPSON Stylus Color 600 printer is attached to parallel
 port 1, for example.
Printer Drivers 
Printer drivers in CUPS consist of one of more filters specific to a
 printer. CUPS includes sample printer drivers for Hewlett-Packard
 LaserJet and DeskJet printers and EPSON 9-pin, 24-pin, Stylus Color,
 and Stylus Photo printers. While these drivers do not generate optimal
 output for the different printer models, they do provide basic printing
 and demonstrate how you can write your own printer drivers and
 incorporate them into CUPS.
Networking 
Printers and classes on the local system are automatically shared
 with other systems on the network. This allows you to setup one system
 to print to a printer and use this system as a printer server or spool
 host for all of the others. Users may then select a local printer by
 name or a remote printer using "name@server".
CUPS also provides implicit classes, which are collections of
 printers and/or classes with the same name. This allows you to setup
 multiple servers pointing to the same physical network printer, for
 example, so that you aren't relying on a single system for printing.
 Because this also works with printer classes, you can setup multiple
 servers and printers and never worry about a single point of failure
 unless all of the printers and servers go down!
2 - The CUPS API 
This chapter describes the CUPS Application Programmers Interface
 ("API").
The CUPS API Library 
The CUPS library provides a whole collection of interfaces needed to
 support the internal needs of the CUPS software as well as the needs of
 applications, filters, printer drivers, and backends.
Unlike the rest of CUPS, the CUPS API library is provided under the
 GNU Library General Public License. This means that you can use the
 CUPS API library in both proprietary and open-source programs.
Programs that use the CUPS API library typically will include the <cups/cups.h>
 header file:
#include <cups/cups.h>
...
jobid = cupsPrintFile("myprinter", "filename.ps", "title",
                      num_options, options);
Use the -lcups compiler option when linking to the CUPS
 API library:
cc -o program program.c -lcups ENTERAdditional options and libraries may be required depending on the
 operating system and the location of the CUPS API library.
Detecting the CUPS API Library in GNU Autoconf 
GNU autoconf is a popular configuration tool used by many programs.
 Add the following lines to your
 configure.in file to check
 for the CUPS API library in your configuration script:
AC_CHECK_LIB(socket,socket,
if test "$uname" != "IRIX"; then
	LIBS="-lsocket $LIBS"
else
	echo "Not using -lsocket since you are running IRIX."
fi)
AC_CHECK_LIB(nsl,gethostbyaddr,
if test "$uname" != "IRIX"; then
	LIBS="-lnsl $LIBS"
else
	echo "Not using -lnsl since you are running IRIX."
fi)
AC_CHECK_LIB(cups,httpConnect)
Printing Services 
The CUPS API library provides some basic printing services for
 applications that need to print files.
Include Files 
The include file used by all of these functions is <cups/cups.h>
:
#include <cups/cups.h>
Printing a File 
The CUPS API provides two functions for printing files. The first is cupsPrintFile
 which prints a single named file:
#include <cups/cups.h>
...
int jobid;
...
jobid = cupsPrintFile("
name", "filename", "title", 0, NULL);
The name string is the name of the printer or class to
 print to. The 
filename string is the name of the file to
 print. The 
title string is the name of the print job, e.g.
 "Acme Word Document".
The return value is a unique ID number for the print job or 0 if
 there was an error.
Printing Multiple Files 
The second printing function is cupsPrintFiles:
#include <cups/cups.h>
...
int        jobid;
int        num_files;
const char *files[100];
...
jobid = cupsPrintFiles("name", 
num_files, files, "title", 0, NULL);
Instead of passing a filename string as with cupsPrintFile() you pass a file count (
num_files) and filename pointer
 array (
files) for each file that you want to print.
As with cupsPrintFile() the return value is a unique ID
 for the print job.
Cancelling Jobs 
The cupsCancelJob() function cancels a queued print job:
#include <cups/cups.h>
...
int jobid;
int status;
...
status = cupsCancelJob("
name", jobid);
The name string specifies the destination and is used to
 determine the server to send the request to. The 
jobid value is the integer returned from a previous 
cupsPrintFile() or 
cupsPrintFiles() call.
cupsCancelJob() returns 1 if the job was
 successfully cancelled and 
0 if there was an error.
Getting the Available Printers and Classes 
The cupsGetDests() function can be used to get a list of
 the available printers, classes, and instances that a user has defined:
#include <cups/cups.h>
...
int         num_dests;
cups_dest_t *dests;
...
num_dests = cupsGetDests(&dests);
Each destination is stored in a cups_dest_t structure
 which defines the printer or class name, the instance name (if any), if
 it is the default destination, and the default options the user has
 defined for the destination:
typedef struct               /**** Destination ****/
{
  char          *name,       /* Printer or class name */
                *instance;   /* Local instance name or NULL */
  int           is_default;  /* Is this printer the default? */
  int           num_options; /* Number of options */
  cups_option_t *options;    /* Options */
} cups_dest_t;
The destinations are sorted by name and instance for your
 convenience. Once you have the list of available destinations, you can
 lookup a specific destination using the 
cupsGetDest() function:
#include <cups/cups.h>
...
int         num_dests;
cups_dest_t *dests;
cups_dest_t *mydest;
...
mydest = cupsGetDest("
name", "instance", num_dests, dests);
The name string is the printer or class name. You can
 pass a value of 
NULL to get the default destination.
The instance string is the user-defined instance name.
 Pass 
NULL to select the default instance, e.g. "name"
 instead of "name/instance".
Printing with Options 
All of the previous printing examples have passed 0 and NULL
 for the last two arguments to the cupsPrintFile() and 
cupsPrintFiles() functions. These last two arguments
 are the number of options and a pointer to the option array:
int cupsPrintFile(const char *name, const char *filename, const char *title,
                  int num_options, cups_option_t *options);
int cupsPrintFiles(const char *name, int num_files, const char **files,
                   const char *title, int num_options,
		   cups_option_t *options);
The cups_option_t structure holds each option and its
 value. These are converted as needed and passed to the CUPS server when
 printing a file.
The simplest way of handling options is to use the num_options and 
options members of the cups_dest_t structure described earlier:
#include <cups/cups.h>
...
int         jobid;
int         num_dests;
cups_dest_t *dests;
cups_dest_t *mydest;
...
mydest = cupsGetDest("
name", "instance", num_dests, dests);
jobid  = cupsPrintFile(mydest->name, "filename", "title",
                       mydest->num_options, mydest->options);
This effectively uses the options a user has previous selected
 without a lot of code.
Setting Printer Options 
Options can also be set by your program using the cupsAddOption()
 function:
#include <cups/cups.h>
...
int           num_options;
cups_option_t *options;
...
num_options = 0;
options     = NULL;
...
num_options = cupsAddOption("
name", "value", num_options, &options);
num_options = cupsAddOption("
name", "value", num_options, &options);
num_options = cupsAddOption("
name", "value", num_options, &options);
num_options = cupsAddOption("
name", "value", num_options, &options);
The name string is the name of the option, and the value
 string is the value for that option.
Each call to cupsAddOption() returns the new number of
 options. Since adding two options with the same name overwrites the
 first value with the second, do not assume that calling 
cupsAddOptions()
 20 times will result in 20 options.
Call cupsFreeOptions once you are done using the
 options:
#include <cups/cups.h>
...
int           num_options;
cups_option_t *options;
...
cupsFreeOptions(num_options, options);
Getting Errors 
If any of the CUPS API printing functions returns an error, the
 reason for that error can be found by calling 
cupsLastError() and 
ippErrorString(). cupsLastError() returns
 the last IPP error code that was encountered. 
ippErrorString() converts the error code to a localized message string suitable for
 presentation to the user:
#include <cups/cups.h>
...
int jobid;
...
if (jobid == 0)
  puts(ippErrorString(cupsLastError()));
Passwords and Authentication 
CUPS supports authentication of any request, including submission of
 print jobs. The default mechanism for getting the username and password
 is to use the login user and a password from the console.
To support other types of applications, in particular Graphical User
 Interfaces ("GUIs"), the CUPS API provides functions to set the default
 username and to register a callback function that returns a password
 string.
The #cupsSetPasswordCBcupsSetPasswordCB()  function is used to set a password callback in your program. Only one
 function can be used at any time.
The #cupsSetUsercupsSetUser()  function
 sets the current username for authentication. This function can be
 called by your password callback function to change the current
 username as needed.
The following example shows a simple password callback that gets a
 username and password from the user:
#include <cups/cups.h>
const char *
my_password_cb(const char *prompt)
{
  char	user[65];
  puts(prompt);
 /* Get a username from the user */
  printf("Username: ");
  if (fgets(user, sizeof(user), stdin) == NULL)
    return (NULL);
 /* Strip the newline from the string and set the user */
  user[strlen(user) - 1] = '\0';
  cupsSetUser(user);
 /* Use getpass() to ask for the password... */
  return (getpass("Password: "));
}
...
cupsSetPasswordCB(my_password_cb);
Similarly, a GUI interface could display the prompt string in a
 window with input fields for the username and password. The username
 should probably default to the value of 
#cupsUsercupsUser()
 to make things easier on the user.
PPD Services 
CUPS includes functions to access and manipulate PostScript Printer
 Description ("PPD") files that are used with the printer drivers in
 CUPS.
Each PPD file enumerates the available features provided by a
 printer, including conflict information for specific options (e.g.
 can't duplex output on envelopes.)
Include Files 
Include the <cups/ppd.h> header file to use the PPD
 functions:
#include <cups/ppd.h>
This header file is also included by the <cups/cups.h> header file.
Getting a PPD File for a Printer 
The cupsGetPPD() function retrieves the PPD file for the
 named printer or class:
#include <cups/cups.h>
...
const char *filename;
filename = cupsGetPPD("
name");
The name string is the name of the printer or class,
 including the remote server name as appropriate (e.g.
 "printer@server".)
The return value is a pointer to a filename in static storage; this
 value is overwritten with each call to 
cupsGetPPD(). If
 the printer or class does not exist, a 
NULL pointer will
 be returned.
Loading a PPD File 
The ppdOpenFile() function "opens" a PPD file and loads
 it into memory:
#include <cups/ppd.h>
...
ppd_file_t *ppd;
ppd = ppdOpenFile("
filename");
The filename string is the name of the file to load,
 such as the value returned by the 
cupsGetPPD() function.
The return value is a pointer to a structure describing the contents
 of the PPD file or NULL if the PPD file could not be read.
Freeing PPD File Information 
Once you are done using a PPD file, call the ppdClose() function to free all memory that has been used:
#include <cups/ppd.h>
...
ppd_file_t *ppd;
...
ppdClose(ppd);
The PPD File Structure 
Each PPD file contains a number of capability attributes, printer
 options, and conflict definitions. The page size options also include
 the physical margins for the printer and the minimum and maximum sizes
 for the printer. All of this information is stored in the 
ppd_file_t
 structure.
Capabilities
Each PPD file contains a number of informational attributes that
 describe the capabilities of the printer. These are provided in the 
ppd_file_t
 structure in the following members:
MemberTypeDescription accurate_screens int 1
 = supports accurate screens
color_device int 1 =
 color device
colorspace ppd_cs_t Default colorspace: PPD_CS_CMYK, PPD_CS_CMY, PPD_CS_GRAY, PPD_CS_RGB,
 PPD_CS_RGBK, PPD_CS_N
contone_only int 1 =
 printer is continuous tone only
num_emulations
 emulations int
 ppd_emul_t * Emulations supported by the printer flip_duplex int 1 =
 need to flip odd pages when duplexing
num_fonts
 fonts int
 char ** The fonts available on the printer. jcl_begin
 jcl_ps
 jcl_end char * Job Control
 Language commands for PostScript output
landscape int Landscape orientation, -90 or 90 degrees
lang_encoding char * The character used for the option strings
lang_version char * The language used for the options strings (English, French, etc.)
language_level int PostScript language level, 1 to 3
manual_copies int 1 =
 Copies are done manually
model_number int Driver-specific model number.
patches char * Patch
 commands to send to the printer
manufacturer char * The Manufacturer attribute from the PPD file, if any
modelname char * The
 ModelName attribute from the PPD file
nickname char * The
 NickName attribute from the PPD file, if any
product char * The
 Product attribute from the PPD file, if any
shortnickname char * The ShortNickName attribute from the PPD file, if any
throughput int Number
 of pages per minute
ttrasterizer char * The TruType font rasterizer (Type42)
variable_sizes int 1 =
 supports variable sizes
Options and Groups
PPD files support multiple options, which are stored in ppd_option_t
 and ppd_choice_t structures by the PPD
 functions.
Each option in turn is associated with a group stored in the ppd_group_t
 structure. Groups can be specified in the PPD file;
 if an option is not associated with a group then it is put in a
 "General" or "Extra" group depending on the option.
Groups can also have sub-groups; CUPS currently limits the depth of
 sub-groups to 1 level to reduce programming complexity.
Conflicts
PPD files support specification of conflict conditions between
 different options. Conflicts are stored in 
ppd_conflict_t structures which specify the options that conflict with each other.
Page Sizes
PPD files specify all of the available pages sizes and the physical
 margins associated with them. These sizes are stored in 
ppd_size_t
 structures and are available in the num_sizes and 
sizes members of the ppd_file_t structure. You can lookup a particular page size with the 
ppdPageWidth()
, ppdPageLength(), and ppdPageSize()
 functions:
#include <cups/ppd.h>
...
ppd_file_t *ppd;
ppd_size_t *size;
float      width;
float      length;
...
size   = ppdPageSize(ppd, "
size");
width  = ppdPageWidth(ppd, "
size");
length = ppdPageLength(ppd, "
size");
The size string is the named page size option. The width
 and length are in points; there are 72 points per inch. The 
ppd_size_t
 structure contains the width, length, and margin
 information:
typedef struct    /**** Page Sizes ****/
{
  int   marked;   /* Page size selected? */
  char  name[41]; /* Media size option */
  float width,    /* Width of media in points */
        length,   /* Length of media in points */
        left,     /* Left printable margin in points */
        bottom,   /* Bottom printable margin in points */
        right,    /* Right printable margin in points */
        top;      /* Top printable margin in points */
} ppd_size_t;
Custom Page Sizes
Besides the standard page sizes listed in a PPD file, some printers
 support variable or custom page sizes. If 
variables_sizes is non-zero, the 
custom_min, custom_max, and custom_margins
 members of the ppd_file_t structure
 define the limits of the variable sizes.
To get the resulting media size, use a page size string of Custom.
widthxlength, where width and length
 are integer values in points:
Custom.612x792   [8.5 inches wide, 11 inches long]
Custom.1224x792  [17 inches wide, 11 inches long]
Marking Options 
Before marking any user-defined options, call the ppdMarkDefaults()
 function to mark the default options from the
 PPD file:
#include <cups/ppd.h>
...
ppd_file_t *ppd;
...
ppdMarkDefaults(ppd);
Then call the ppdMarkOption() function to mark
 individual options:
#include <cups/ppd.h>
...
ppd_file_t *ppd;
int        conflicts;
...
conflicts = ppdMarkOption(ppd, "
name", "value");
The name and value strings choose a
 particular option and choice, respectively. The return value is 0 if
 there are not conflicts created by the selection.
CUPS also provides a convenience function for marking all options in
 the 
cups_option_t structure:
#include <cups/cups.h>
...
ppd_file_t    *ppd;
int           num_options;
cups_option_t *options;
int           conflicts;
...
conflicts = cupsMarkOptions(ppd, num_options, options);
The cupsMarkOptions() function also handles mapping the
 IPP job template attributes to PPD options. The return value is the
 number of conflicts present.
Checking for Conflicts 
The ppdMarkOption() and cupsMarkOptions() functions return the number of conflicts with the currently marked
 options.
Call the ppdConflicts() function to get the number of
 conflicts after you have marked all of the options:
#include <cups/cups.h>
...
ppd_file_t *ppd;
int        conflicts;
...
conflicts = ppdConflicts(ppd);
The return value is the number of conflicting options, or 0 if there
 are no conflicts.
3 - Writing Filters 
This chapter describes how to write a file filter for CUPS.
Overview 
File filters are programs that convert from one or more MIME types to
 another type. Filters use a common command-line and environment
 interface that allows them to be joined as needed to print files to any
 type of printer.
Security Considerations 
Filters are normally run as a non-priviledged user, so the major
 security consideration is resource utilization - filters should not
 depend on unlimited amounts of memory and disk space.
Users and Groups 
The default CUPS configuration runs filters as user "lp" and group
 "other".
Temporary Files 
Temporary files should be created in the directory specified by the
 "TMPDIR" environment variable. The 
#cupsTempFilecupsTempFile()
 function can be used to safely choose
 temporary files in this directory.
Sending Messages to the User 
The CUPS scheduler collects messages sent to the standard error file
 by the filter. These messages are relayed to the user based upon the
 scheduler 
LogLevel directive.
The type of message is determined by an initial prefix sent on each
 line:
DEBUG: - a debug messageINFO: - an informational messageWARNING: - a warning messageERROR: - an error messagePAGE: - a page accounting messageIf the line of text does not begin with any of the above prefixes, it
 is treated as a debug message. Text following the prefix is copied to
 the 
printer-state-message attribute for the printer, and
 also added to the
 error_log unless it is an informational or
 page accounting message.
Page Accounting 
Page accounting messages are used to inform the server when one or
 more pages are printed. Each line has the form:
PAGE: page-number copy-count
The page-number field is the current page number, starting at
 1. The
 copy-count field specifies the number of copies of that
 page that was produced.
Page account messages are added to the page_log file and
 cause the 
job-sheets-completed attribute to be updated for
 the job.
Command-Line Arguments 
Every filter accepts exactly 6 or 7 command-line arguments:
printer job user title copies options [filename]
printer - The name of the printer queue (normally this
 is the name of the program being run)
job - The numeric job ID for the job being printeduser - The string from the originating-user-name attribute
title - The string from the job-name attribute
copies - The numeric value from the number-copies attribute
options - String representations of the job template
 attributes, separated by spaces. Boolean attributes are provided as
 "name" for true values and "noname" for false values. All other
 attributes are provided as "name=value" for single-valued attributes
 and "name=value1,value2,...,valueN" for set attributes
filename - The request fileThe filename argument is only provided to the first filter in
 the chain; all filters
 must be prepared to read the print file
 from the standard input if the
 filename argument is omitted.
Copy Generation 
The copies argument specifies the number of copies to produce
 of the input file. In general, you should only generate copies if the
 filename
 argument is supplied. The only exception to this are
 filters that produce device-independent PostScript output (without any
 printer commands from the printer's PPD file), since the PostScript
 filter 
pstops is responsible for copy generation.
Environment Variables 
Every filter receives a fixed set of environment variables that can
 be used by the filter:
CHARSET - The character set used by the client for this
 print file
CONTENT_TYPE - The original document type, such as
 "application/postscript"
CUPS_DATADIR - The location of CUPS data filesCUPS_SERVERROOT - The location of CUPS configuration
 files
DEVICE_URI - The output device URILANG - The language used by the client for this print
 file
PATH - The execution path exported to the filterPPD - The full filename of the printer's PPD filePRINTER - The name of the printer queueRIP_CACHE - The maximum amount of memory each filter
 should use
SOFTWARE - The name of the CUPS software, typically
 "CUPS/1.1"
TZ - The local timezoneUSER - The name of the current user Dissecting the HP-GL/2 Filter 
The HP-GL/2 filter (hpgltops) provided with CUPS is a
 complex program that converts HP-GL/2 files into device-independent
 PostScript output. Since it produces device-independent PostScript
 output, it does not need to handle copy generation or writing printer
 options from the printer's PPD file.
Initializing the Filter 
The first task of any filter is to ensure that the correct number of
 command-line arguments are present:
if (argc < 6 || argc > 7)
{
  fputs("ERROR: hpgltops job-id user title copies options [file]\n", stderr);
  return (1);
}
After this you open the print file or read from the standard input as
 needed:
FILE *fp;
/*
 * If we have 7 arguments, print the file named on the command-line.
 * Otherwise, send stdin instead...
 */
if (argc == 6)
  fp = stdin;
else
{
 /*
  * Try to open the print file...
  */
  if ((fp = fopen(argv[6], "rb")) == NULL)
  {
    perror("ERROR: unable to open print file - ");
    return (1);
  }
}
Once the print file has been opened, options can be processed using
 the 
#cupsParseOptionscupsParseOptions()  and
 
#cupsGetOptioncupsGetOption()  functions:
int           num_options;
cups_option_t *options;
const char    *val;
/*
 * Process command-line options and write the prolog...
 */
options     = NULL;
num_options = cupsParseOptions(argv[5], 0, &options);
if ((val = cupsGetOption("blackplot", num_options, options)) != NULL)
  shading = 0;
if ((val = cupsGetOption("fitplot", num_options, options)) != NULL)
  FitPlot = 1;
if ((val = cupsGetOption("penwidth", num_options, options)) != NULL)
  PenWidth = (float)atoi(val) * 0.001f;
After the options have been processed, the filter writes PostScript
 code to the standard output based on the print file, closes the print
 file (as needed), and returns 0 to the scheduler.
PostScript Output 
Filters that produce PostScript output must generate output
 conforming to the Adobe Document Structuring Conventions, 3.0. In
 general this means the beginning of each file must begin with:
%!PS-Adobe-3.0
%%BoundingBox: left bottom right top
%%Pages: (atend)
%%EndComments
The left, bottom, right, and top values
 are integers in points from the lower-lefthand corner of the page.
Pages must be surrounded by:
%%Page: number number
gsave
...
grestore
showpage
And the end of each file must contain:
%%Trailer
%%Pages: number-pages
%%EOF
These comments allow the PostScript filter to correctly perform page
 accounting, copy generation, N-up printing, and so forth.
4 - Writing Printer Drivers 
This chapter discusses how to write a printer driver, which is a
 special filter program that converts CUPS raster data into the
 appropriate commands and data required for a printer.
Overview 
Raster printers utilitize PPD files that specify one or more
 device-specific filters that handle converting print files for the
 printer. The simplest raster printer drivers provide a single filter
 that converts CUPS raster data to the printer's native format.
CUPS Raster Data 
CUPS raster data (application/vnd.cups-raster) consists
 of a stream of raster page descriptions produced by one of the RIP
 filters, such as 
pstoraster or imagetoraster.
Each page of data begins with a page dictionary structure called #cups_raster_header_tcups_raster_header_t . This structure contains the
 colorspace, bits per color, media size, media type, hardware
 resolution, and so forth.
After the page dictionary comes the page data which is a
 full-resolution, uncompressed bitmap representing the page in the
 printer's output colorspace.
Page Accounting 
Printer drivers must handle all page accounting. This means they must
 send "PAGE:" messages to the standard error file for each page (and in
 many cases, copy) sent to the printer.
Color Management 
Printer drivers can implement their color management via the cupsColorProfile
 attributes in the PPD file or internally in the
 driver from a device-independent colorspace. In general, color
 management performed by the RIP filters is more efficient than that
 performed inside printer drivers.
For example, the pstoraster filter often only has to
 perform a color conversion once each time the color is used for
 multiple output pixels, while the raster filter must convert every
 pixel on the page.
Device and Bitmap Variables 
Besides the standard PostScript page device dictionary variables
 defined in the Adobe PostScript Level 3 reference manual, the CUPS
 filters support additional variables that are passed in the page device
 dictionary header for the page and in some cases control the type of
 raster data that is generated:
VariableTypeDescription cupsWidth read-only integer Width of bitmap in
 pixels
cupsHeight read-only integer Height of bitmap in
 pixels
cupsMediaType read-write integer Device-specific
 media type code
cupsBitsPerColor read-write integer Number of
 bits per color; 1, 2, 4, and 8 are currently supported
cupsBitsPerPixel read-only integer Number of
 bits per pixel; 1 to 32
cupsBytesPerLine read-only integer Number of
 bytes per line of raster graphics
cupsColorOrder read-write enum The order of
 color values in the bitmap:
CUPS_ORDER_CHUNKED - CMYK CMYK CMYKCUPS_ORDER_BANDED - CCC MMM YYY KKKCUPS_ORDER_PLANAR - CCC ... MMM ... YYY ... KKK ... cupsColorSpace read-write enum The colorspace of
 the bitmap:
CUPS_CSPACE_W - White (luminance)CUPS_CSPACE_RGB - Red, green, blueCUPS_CSPACE_RGBA - Red, green, blue, alphaCUPS_CSPACE_K - BlackCUPS_CSPACE_CMY - Cyan, magenta, yellowCUPS_CSPACE_YMC - Yellow, magenta, cyanCUPS_CSPACE_CMYK - Cyan, magenta, yellow, blackCUPS_CSPACE_YMCK - Yellow, magenta, cyan, blackCUPS_CSPACE_KCMY - Black, cyan, magenta, yellowCUPS_CSPACE_KCMYcm - Black, cyan, magenta, yellow,
 light cyan, light magenta
CUPS_CSPACE_GMCK - Metallic yellow (gold), metallic
 magenta, metallic cyan, black
CUPS_CSPACE_GMCS - Metallic yellow (gold), metallic
 magenta, metallic cyan, metallic grey (silver)
CUPS_CSPACE_WHITE - White pigment (black as white
 pigment)
CUPS_CSPACE_GOLD - Gold foil (black as gold foil)CUPS_CSPACE_SILVER - Silver foil (black as silver foil) cupsCompression read-write integer Device-specific compression type code
cupsRowCount read-write integer Device-specific
 row count value
cupsRowFeed read-write integer Device-specific
 row feed value
cupsRowStep read-write integer Device-specific
 row step value
Bitmaps with a colorspace of CUPS_CSPACE_KCMYcm and more than 1 bit
 per color are transmitted to the raster driver in KCMY colorspace; the
 driver is responsible for producing the correct separation of normal
 and light cyan and magenta inks.
Dissecting the HP-PCL Driver 
The HP-PCL driver provided with CUPS (rastertohp)
 converts bitmap data from the raster filters into HP-PCL commands for
 most PCL-compatible printers. The actual format of the raster data is
 controlled by the PPD file being used -
 deskjet.ppd or laserjet.ppd
.
PPD Files 
PPD files play an important part of all raster printer drivers.
 Options defined in the PPD file contain PostScript commands that
 control the raster data that is sent to the printer driver.
A typical CUPS printer driver will include ColorModel, InputSlot
, PageSize, PageRegion, and Resolution
 options. Each option is shown using the standard PPD
 format:
*OpenUI *PageSize/Media Size: PickOne
*OrderDependency: 10 AnySetup *PageSize
*DefaultPageSize: Letter
*PageSize Letter/US Letter: "<<
/PageSize [612 792]
/ImagingBBox null
>> setpagedevice"
*End
*PageSize Legal/US Legal: "<<
/PageSize [612 1008]
/ImagingBBox null
>> setpagedevice"
*End
*PageSize A4/A4: "<<
/PageSize [595 842]
/ImagingBBox null
>> setpagedevice"
*End
*CloseUI: *PageSize
The OpenUI keyword specifies the new option. The first
 name is the option with an asterisk (*) in front of it. The first name
 is usually followed by a slash (/) and a human-readable version of the
 option name.
Every option must have a default value, specified using the Default
Option keyword.
Each option begins with the option name followed by the computer and
 human-readable values. The PostScript commands follow these inside
 double quotes. PostScript commands can be provided on a single line:
*PageSize A4/A4: "<</PageSize[595 842]/ImagingBBox null>> setpagedevice"
or broken down on separate lines using the End keyword
 to terminate them:
*PageSize A4/A4: "<<
/PageSize [595 842]
/ImagingBBox null
>> setpagedevice"
*End
The choice of the two formats is usually esthetic. However, each line
 in a PPD file must not exceed 255 characters, so if your PostScript
 commands are long you may need to break them up on separate lines.
Reading Raster Data 
As with any filter, your printer driver should handle raster data
 from a filename specified on the command-line or from the standard
 input. The 
#cupsRasterOpencupsRasterOpen()  function opens a raster stream for printing:
int           fd;   /* File descriptor */
cups_raster_t *ras; /* Raster stream for printing */
/*
 * Check for valid arguments...
 */
if (argc < 6 || argc > 7)
{
 /*
  * We don't have the correct number of arguments; write an error message
  * and return.
  */
  fputs("ERROR: rastertopcl job-id user title copies options [file]\n", stderr);
  return (1);
}
/*
 * Open the page stream...
 */
if (argc == 7)
{
  if ((fd = open(argv[6], O_RDONLY)) == -1)
  {
    perror("ERROR: Unable to open raster file - ");
    sleep(1);
    return (1);
  }
}
else
  fd = 0;
ras = cupsRasterOpen(fd, CUPS_RASTER_READ);
Once you have opened the raster stream you just need to read each
 page and print it:
cups_raster_header_t header;
int                  y;
unsigned char        data[8192];
while (cupsRasterReadHeader(ras, &header))
{
  ... initialize the printer ...
  for (y = header.cupsHeight; y > 0; y ++)
  {
    cupsRasterReadPixels(ras, data, header.cupsBytesPerLine);
    ... send raster line to printer ...
  }
}
After you have processed all pages, close the raster stream and
 return:
cupsRasterClose(ras);
return (0);
5 - Writing Backends 
This chapter describes how to write a backend for CUPS. Backends
 communicate directly with printers and allow printer drivers and
 filters to send data using any type of connection transparently.
Overview 
Backends are special filters that communicate with printers directly.
 They are treated slightly differently than filters, however, and have
 some unique requirements.
Security Considerations 
Backends are run as the root user, so special care must be taken to
 avoid potential security violations. In particular, remember that a
 backend will be able to manipulate disk files, devices, and other
 resources that potentially could damage a system or printer.
Command-Line Arguments 
Besides the standard filter arguments, backends are also run with no
 arguments to get a list of available devices. This discovery process is
 described later in this chapter.
Copy Generation 
Like filters, backends should send multiple copies of the print file
 only if a filename is supplied on the command-line. Otherwise the
 backend should assume that the upstream filter has already added the
 necessary commands or data to produce the multiple copies.
Page Accounting 
Backend filters generally do not do page accounting, however they
 should at a minimum produce a single page message for each copy that is
 produced when a filename is present on the command-line. This is
 because the user selected "raw" printing and no other accounting
 information is possible.
Exclusive Access 
Backends that talk to local character or block devices should open
 the device file in exclusive mode (
O_EXCL) to cooperate
 with other printers defined for the same device.
Retries 
All backends must retry connections to the device. This
 includes backends that talk to local character or block devices, as the
 user may define more than one printer queue pointing at the same
 physical device.
To prevent excess CPU utilitization, the backend should go to sleep
 for an amount of time between retries; the CUPS-supplied backends retry
 once every 30 seconds.
Dissecting the Serial Port Backend 
The serial port backend provides support for serial printers. Since
 it does everything a good backend needs to do, it provides an excellent
 example of what to do.
Supporting Device Discovery 
As previously noted, backends are special filter programs that talk
 to printer devices. Another task a backend must perform is to list the
 available devices it supports. The backend lists the available devices
 when no additioanl arguments are supplied on the command-line (i.e.
 just the command name...)
The serial backend lists devices by looking at serial port files in
 the
 /dev directory, by consulting a hardware inventory
 (IRIX), and in some cases by trying to open the ports to see if they
 actually exist.
Once it finds a serial port it writes a single line for each port to
 the standard output file. Each line looks like this:
serial serial:/dev/ttyS0?baud=115200 "Unknown" "Serial Port 1"
The first word "serial" is the device class; this identifies
 the class of device which can be used to categorize it in user
 interfaces. CUPS currently recognizes the following classes:
"file" - a disk file."direct" - a parallel or fixed-rate serial data port, currently used
 for Centronics, IEEE-1284, and USB printer ports.
"serial" - a variable-rate serial port."network" - a network connection, typically via AppSocket, HTTP,
 IPP, LPD, or SMB/CIFS protocols.
After the device class is the device URI, in this case
 "serial:/dev/ttyS0?baud=115200". This is the URI that should be used by
 the user to select this port. For serial ports, the "baud=115200"
 specifies the maximum baud rate supported by the port - the actual
 value will vary based on the speed the user selects for the printer.
The last two strings are the model and description for the port. The
 "Unknown" string means that the printer model is unknown - some devices
 are able to provide a make and model such as "HP DeskJet" that allows
 users and software to choose an appropriate printer driver more easily.
 Both the model and description must be enclosed inside double quotes.
Opening the Serial Port 
As noted previously, all backends should open device files in
 exclusive mode, and retry as needed until the port is available. The
 serial port does this using a 
do-while loop:
do
{
  if ((fd = open(resource, O_WRONLY | O_NOCTTY | O_EXCL)) == -1)
  {
    if (errno == EBUSY)
    {
      fputs("INFO: Serial port busy; will retry in 30 seconds...\n", stderr);
      sleep(30);
    }
    else
    {
      perror("ERROR: Unable to open serial port device file");
      return (1);
    }
  }
}
while (fd < 0);
If the port is busy or in use by another process, the backend will go
 to sleep for 30 seconds and try again. If another error is detected a
 message is sent to the user and the backend aborts the print job until
 the problem can be corrected.
Writing Data to the Port 
Network and character devices pose an interesting problem when
 writing data to the port - they may not be able to write all of the
 bytes in your buffer before returning. To work around this problem you
 must loop until all bytes have been written:
while (nbytes > 0)
{
  if ((wbytes = write(fd, bufptr, nbytes)) < 0)
    if (errno == ENOTTY)
      wbytes = write(fd, bufptr, nbytes);
  if (wbytes < 0)
  {
    perror("ERROR: Unable to send print file to printer");
    break;
  }
  nbytes -= wbytes;
  bufptr += wbytes;
}
The check for the ENOTTY error is needed on some
 platforms to clear an error from a previous 
ioctl() call.
Finishing Up 
Once you have sent the print file, return 0 if the file printed
 successfully or 1 if it did not. This will allow the scheduler to stop
 the print job if there is a device error, preserving the print job for
 later printing once the problem has been corrected.
A - Software License Agreement 
Common UNIX Printing System License
 Agreement
Copyright 1997-2005 by Easy Software Products
 44141 AIRPORT VIEW DR STE 204
 HOLLYWOOD, MARYLAND 20636 USA
 Voice: +1.301.373.9600
 Email: mailto:cups-info@cups.orgcups-info@cups.org  WWW: http://www.cups.orghttp://www.cups.org 
Introduction 
The Common UNIX Printing SystemTM, ("CUPSTM"),
 is provided under the GNU General Public License ("GPL") and GNU
 Library General Public License ("LGPL"), Version 2, with exceptions for
 Apple operating systems and the OpenSSL toolkit. A copy of the
 exceptions and licenses follow this introduction.
The GNU LGPL applies to the CUPS API library, located in the "cups"
 subdirectory of the CUPS source distribution and in the "cups" include
 directory and library files in the binary distributions. The GNU GPL
 applies to the remainder of the CUPS distribution, including the
 "pdftops" filter which is based upon Xpdf and the CUPS imaging library.
For those not familiar with the GNU GPL, the license basically allows
 you to:
Use the CUPS software at no charge.Distribute verbatim copies of the software in source or binary form.Sell verbatim copies of the software for a media fee, or sell
 support for the software.
Distribute or sell printer drivers and filters that use CUPS so long
 as source code is made available under the GPL.
What this license does not allow you to do is make changes or
 add features to CUPS and then sell a binary distribution without source
 code. You must provide source for any new drivers, changes, or
 additions to the software, and all code must be provided under the GPL
 or LGPL as appropriate. The only exceptions to this are the portions of
 the CUPS software covered by the Apple operating system license
 exceptions outlined later in this license agreement.
The GNU LGPL relaxes the "link-to" restriction, allowing you to
 develop applications that use the CUPS API library under other licenses
 and/or conditions as appropriate for your application.
License Exceptions 
In addition, as the copyright holder of CUPS, Easy Software Products
 grants the following special exceptions:
Apple Operating System Development License Exception;
Software that is developed by any person or entity for an Apple
 Operating System ("Apple OS-Developed Software"), including but not
 limited to Apple and third party printer drivers, filters, and backends
 for an Apple Operating System, that is linked to the CUPS imaging
 library or based on any sample filters or backends provided with CUPS
 shall not be considered to be a derivative work or collective work
 based on the CUPS program and is exempt from the mandatory source code
 release clauses of the GNU GPL. You may therefore distribute linked
 combinations of the CUPS imaging library with Apple OS-Developed
 Software without releasing the source code of the Apple OS-Developed
 Software. You may also use sample filters and backends provided with
 CUPS to develop Apple OS-Developed Software without releasing the
 source code of the Apple OS-Developed Software.
An Apple Operating System means any operating system software
 developed and/or marketed by Apple Computer, Inc., including but not
 limited to all existing releases and versions of Apple's Darwin, Mac OS
 X, and Mac OS X Server products and all follow-on releases and future
 versions thereof.
This exception is only available for Apple OS-Developed Software and
 does not apply to software that is distributed for use on other
 operating systems.
All CUPS software that falls under this license exception have the
 following text at the top of each source file:
This file is
 subject to the Apple OS-Developed Software exception.
OpenSSL Toolkit License Exception;
Easy Software Products explicitly allows the compilation and
 distribution of the CUPS software with the OpenSSL Toolkit.
No developer is required to provide these exceptions in a derived
 work.
Trademarks 
Easy Software Products has trademarked the Common UNIX Printing
 System, CUPS, and CUPS logo. You may use these names and logos in any
 direct port or binary distribution of CUPS. Please contact Easy
 Software Products for written permission to use them in derivative
 products. Our intention is to protect the value of these trademarks and
 ensure that any derivative product meets the same high-quality
 standards as the original.
Binary Distribution Rights 
Easy Software Products also sells rights to the CUPS source code
 under a binary distribution license for vendors that are unable to
 release source code for their drivers, additions, and modifications to
 CUPS under the GNU GPL and LGPL. For information please contact us at
 the address shown above.
The Common UNIX Printing System provides a "pdftops" filter that is
 based on the Xpdf software. For binary distribution licensing of this
 software, please contact:
 Derek B. Noonburg
 Email: mailto:derekn@foolabs.comderekn@foolabs.com  WWW: http://www.foolabs.com/xpdf/http://www.foolabs.com/xpdf/
Support 
Easy Software Products sells software support for CUPS as well as a
 commercial printing product based on CUPS called ESP Print Pro. You can
 find out more at our web site:
http://www.easysw.com/http://www.easysw.com/ GNU GENERAL PUBLIC LICENSE 
Version 2, June 1991
Copyright 1989, 1991 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Everyone is permitted to copy and distribute verbatim
copies of this license document, but changing it is not allowed.
Preamble 
The licenses for most software are designed to take away your freedom
 to share and change it. By contrast, the GNU General Public License is
 intended to guarantee your freedom to share and change free
 software--to make sure the software is free for all its users. This
 General Public License applies to most of the Free Software
 Foundation's software and to any other program whose authors commit to
 using it. (Some other Free Software Foundation software is covered by
 the GNU Library General Public License instead.) You can apply it to
 your programs, too.
When we speak of free software, we are referring to freedom, not
 price. Our General Public Licenses are designed to make sure that you
 have the freedom to distribute copies of free software (and charge for
 this service if you wish), that you receive source code or can get it
 if you want it, that you can change the software or use pieces of it in
 new free programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid
 anyone to deny you these rights or to ask you to surrender the rights.
 These restrictions translate to certain responsibilities for you if you
 distribute copies of the software, or if you modify it.
For example, if you distribute copies of such a program, whether
 gratis or for a fee, you must give the recipients all the rights that
 you have. You must make sure that they, too, receive or can get the
 source code. And you must show them these terms so they know their
 rights.
We protect your rights with two steps: (1) copyright the software,
 and (2) offer you this license which gives you legal permission to
 copy, distribute and/or modify the software.
Also, for each author's protection and ours, we want to make certain
 that everyone understands that there is no warranty for this free
 software. If the software is modified by someone else and passed on, we
 want its recipients to know that what they have is not the original, so
 that any problems introduced by others will not reflect on the original
 authors' reputations.
Finally, any free program is threatened constantly by software
 patents. We wish to avoid the danger that redistributors of a free
 program will individually obtain patent licenses, in effect making the
 program proprietary. To prevent this, we have made it clear that any
 patent must be licensed for everyone's free use or not licensed at all.
The precise terms and conditions for copying, distribution and
 modification follow.
GNU GENERAL PUBLIC LICENSE
 TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
This License applies to any program or other work which contains a
 notice placed by the copyright holder saying it may be distributed
 under the terms of this General Public License. The "Program", below,
 refers to any such program or work, and a "work based on the Program"
 means either the Program or any derivative work under copyright law:
 that is to say, a work containing the Program or a portion of it,
 either verbatim or with modifications and/or translated into another
 language. (Hereinafter, translation is included without limitation in
 the term "modification".) Each licensee is addressed as "you".
Activities other than copying, distribution and modification are not
 covered by this License; they are outside its scope. The act of running
 the Program is not restricted, and the output from the Program is
 covered only if its contents constitute a work based on the Program
 (independent of having been made by running the Program). Whether that
 is true depends on what the Program does.
You may copy and distribute verbatim copies of the Program's source
 code as you receive it, in any medium, provided that you conspicuously
 and appropriately publish on each copy an appropriate copyright notice
 and disclaimer of warranty; keep intact all the notices that refer to
 this License and to the absence of any warranty; and give any other
 recipients of the Program a copy of this License along with the
 Program.
You may charge a fee for the physical act of transferring a copy, and
 you may at your option offer warranty protection in exchange for a fee.
You may modify your copy or copies of the Program or any portion of
 it, thus forming a work based on the Program, and copy and distribute
 such modifications or work under the terms of Section 1 above, provided
 that you also meet all of these conditions:
You must cause the modified files to carry prominent notices stating
 that you changed the files and the date of any change.
You must cause any work that you distribute or publish, that in
 whole or in part contains or is derived from the Program or any part
 thereof, to be licensed as a whole at no charge to all third parties
 under the terms of this License.
if the modified program normally reads commands interactively when
 run, you must cause it, when started running for such interactive use
 in the most ordinary way, to print or display an announcement including
 an appropriate copyright notice and a notice that there is no warranty
 (or else, saying that you provide a warranty) and that users may
 redistribute the program under these conditions, and telling the user
 how to view a copy of this License. (Exception: if the Program itself
 is interactive but does not normally print such an announcement, your
 work based on the Program is not required to print an announcement.)
These requirements apply to the modified work as a whole. If
 identifiable sections of that work are not derived from the Program,
 and can be reasonably considered independent and separate works in
 themselves, then this License, and its terms, do not apply to those
 sections when you distribute them as separate works. But when you
 distribute the same sections as part of a whole which is a work based
 on the Program, the distribution of the whole must be on the terms of
 this License, whose permissions for other licensees extend to the
 entire whole, and thus to each and every part regardless of who wrote
 it.
Thus, it is not the intent of this section to claim rights or contest
 your rights to work written entirely by you; rather, the intent is to
 exercise the right to control the distribution of derivative or
 collective works based on the Program.
In addition, mere aggregation of another work not based on the
 Program with the Program (or with a work based on the Program) on a
 volume of a storage or distribution medium does not bring the other
 work under the scope of this License.
You may copy and distribute the Program (or a work based on it,
 under Section 2) in object code or executable form under the terms of
 Sections 1 and 2 above provided that you also do one of the following:
Accompany it with the complete corresponding machine-readable source
 code, which must be distributed under the terms of Sections 1 and 2
 above on a medium customarily used for software interchange; or,
Accompany it with a written offer, valid for at least three years,
 to give any third party, for a charge no more than your cost of
 physically performing source distribution, a complete machine-readable
 copy of the corresponding source code, to be distributed under the
 terms of Sections 1 and 2 above on a medium customarily used for
 software interchange; or,
Accompany it with the information you received as to the offer to
 distribute corresponding source code. (This alternative is allowed only
 for noncommercial distribution and only if you received the program in
 object code or executable form with such an offer, in accord with
 Subsection b above.)
The source code for a work means the preferred form of the work for
 making modifications to it. For an executable work, complete source
 code means all the source code for all modules it contains, plus any
 associated interface definition files, plus the scripts used to control
 compilation and installation of the executable. However, as a special
 exception, the source code distributed need not include anything that
 is normally distributed (in either source or binary form) with the
 major components (compiler, kernel, and so on) of the operating system
 on which the executable runs, unless that component itself accompanies
 the executable.
If distribution of executable or object code is made by offering
 access to copy from a designated place, then offering equivalent access
 to copy the source code from the same place counts as distribution of
 the source code, even though third parties are not compelled to copy
 the source along with the object code.
You may not copy, modify, sublicense, or distribute the Program
 except as expressly provided under this License. Any attempt otherwise
 to copy, modify, sublicense or distribute the Program is void, and will
 automatically terminate your rights under this License. However,
 parties who have received copies, or rights, from you under this
 License will not have their licenses terminated so long as such parties
 remain in full compliance.
You are not required to accept this License, since you have not
 signed it. However, nothing else grants you permission to modify or
 distribute the Program or its derivative works. These actions are
 prohibited by law if you do not accept this License. Therefore, by
 modifying or distributing the Program (or any work based on the
 Program), you indicate your acceptance of this License to do so, and
 all its terms and conditions for copying, distributing or modifying the
 Program or works based on it.
Each time you redistribute the Program (or any work based on the
 Program), the recipient automatically receives a license from the
 original licensor to copy, distribute or modify the Program subject to
 these terms and conditions. You may not impose any further restrictions
 on the recipients' exercise of the rights granted herein. You are not
 responsible for enforcing compliance by third parties to this License.
If, as a consequence of a court judgment or allegation of patent
 infringement or for any other reason (not limited to patent issues),
 conditions are imposed on you (whether by court order, agreement or
 otherwise) that contradict the conditions of this License, they do not
 excuse you from the conditions of this License. If you cannot
 distribute so as to satisfy simultaneously your obligations under this
 License and any other pertinent obligations, then as a consequence you
 may not distribute the Program at all. For example, if a patent license
 would not permit royalty-free redistribution of the Program by all
 those who receive copies directly or indirectly through you, then the
 only way you could satisfy both it and this License would be to refrain
 entirely from distribution of the Program.
If any portion of this section is held invalid or unenforceable under
 any particular circumstance, the balance of the section is intended to
 apply and the section as a whole is intended to apply in other
 circumstances.
It is not the purpose of this section to induce you to infringe any
 patents or other property right claims or to contest validity of any
 such claims; this section has the sole purpose of protecting the
 integrity of the free software distribution system, which is
 implemented by public license practices. Many people have made generous
 contributions to the wide range of software distributed through that
 system in reliance on consistent application of that system; it is up
 to the author/donor to decide if he or she is willing to distribute
 software through any other system and a licensee cannot impose that
 choice.
This section is intended to make thoroughly clear what is believed to
 be a consequence of the rest of this License.
If the distribution and/or use of the Program is restricted in
 certain countries either by patents or by copyrighted interfaces, the
 original copyright holder who places the Program under this License may
 add an explicit geographical distribution limitation excluding those
 countries, so that distribution is permitted only in or among countries
 not thus excluded. In such case, this License incorporates the
 limitation as if written in the body of this License.
The Free Software Foundation may publish revised and/or new versions
 of the General Public License from time to time. Such new versions will
 be similar in spirit to the present version, but may differ in detail
 to address new problems or concerns.
Each version is given a distinguishing version number. If the Program
 specifies a version number of this License which applies to it and "any
 later version", you have the option of following the terms and
 conditions either of that version or of any later version published by
 the Free Software Foundation. If the Program does not specify a version
 number of this License, you may choose any version ever published by
 the Free Software Foundation.
If you wish to incorporate parts of the Program into other free
 programs whose distribution conditions are different, write to the
 author to ask for permission. For software which is copyrighted by the
 Free Software Foundation, write to the Free Software Foundation; we
 sometimes make exceptions for this. Our decision will be guided by the
 two goals of preserving the free status of all derivatives of our free
 software and of promoting the sharing and reuse of software generally.
NO WARRANTY
BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
 PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
 EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
 ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH
 YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
 NECESSARY SERVICING, REPAIR OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
 AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU
 FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
 PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
 RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
 FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF
 SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
 DAMAGES.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest
 possible use to the public, the best way to achieve this is to make it
 free software which everyone can redistribute and change under these
 terms.
To do so, attach the following notices to the program. It is safest
 to attach them to the start of each source file to most effectively
 convey the exclusion of warranty; and each file should have at least
 the "copyright" line and a pointer to where the full notice is found.
one line to give the program's name and an idea of what it does.Copyright (C) 
yyyy  name of authorThis program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
Also add information on how to contact you by electronic and paper
 mail.
If the program is interactive, make it output a short notice like
 this when it starts in an interactive mode:
Gnomovision version 69, Copyright (C) 
year name of authorGnomovision comes with ABSOLUTELY NO WARRANTY; for details
type `show w'.  This is free software, and you are welcome
to redistribute it under certain conditions; type `show c' 
for details.
The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of
 course, the commands you use may be called something other than 
`show w'
 and `show c'; they could even be
 mouse-clicks or menu items--whatever suits your program.
You should also get your employer (if you work as a programmer) or
 your school, if any, to sign a "copyright disclaimer" for the program,
 if necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright
interest in the program `Gnomovision'
(which makes passes at compilers) written 
by James Hacker.
signature of Ty Coon, 1 April 1989
Ty Coon, President of Vice
GNU LIBRARY GENERAL PUBLIC LICENSE 
Version 2, June 1991
Copyright (C) 1991 Free Software Foundation, Inc.
59 Temple Place - Suite 330, Boston, MA  02111-1307, USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
[This is the first released version of the library GPL.  It is
 numbered 2 because it goes with version 2 of the ordinary GPL.]
Preamble 
The licenses for most software are designed to take away your freedom
 to share and change it. By contrast, the GNU General Public Licenses
 are intended to guarantee your freedom to share and change free
 software--to make sure the software is free for all its users.
This license, the Library General Public License, applies to some
 specially designated Free Software Foundation software, and to any
 other libraries whose authors decide to use it. You can use it for your
 libraries, too.
When we speak of free software, we are referring to freedom, not
 price. Our General Public Licenses are designed to make sure that you
 have the freedom to distribute copies of free software (and charge for
 this service if you wish), that you receive source code or can get it
 if you want it, that you can change the software or use pieces of it in
 new free programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid
 anyone to deny you these rights or to ask you to surrender the rights.
 These restrictions translate to certain responsibilities for you if you
 distribute copies of the library, or if you modify it.
For example, if you distribute copies of the library, whether gratis
 or for a fee, you must give the recipients all the rights that we gave
 you. You must make sure that they, too, receive or can get the source
 code. If you link a program with the library, you must provide complete
 object files to the recipients so that they can relink them with the
 library, after making changes to the library and recompiling it. And
 you must show them these terms so they know their rights.
Our method of protecting your rights has two steps: (1) copyright the
 library, and (2) offer you this license which gives you legal
 permission to copy, distribute and/or modify the library.
Also, for each distributor's protection, we want to make certain that
 everyone understands that there is no warranty for this free library.
 If the library is modified by someone else and passed on, we want its
 recipients to know that what they have is not the original version, so
 that any problems introduced by others will not reflect on the original
 authors' reputations.
Finally, any free program is threatened constantly by software
 patents. We wish to avoid the danger that companies distributing free
 software will individually obtain patent licenses, thus in effect
 transforming the program into proprietary software. To prevent this, we
 have made it clear that any patent must be licensed for everyone's free
 use or not licensed at all.
Most GNU software, including some libraries, is covered by the
 ordinary GNU General Public License, which was designed for utility
 programs. This license, the GNU Library General Public License, applies
 to certain designated libraries. This license is quite different from
 the ordinary one; be sure to read it in full, and don't assume that
 anything in it is the same as in the ordinary license.
The reason we have a separate public license for some libraries is
 that they blur the distinction we usually make between modifying or
 adding to a program and simply using it. Linking a program with a
 library, without changing the library, is in some sense simply using
 the library, and is analogous to running a utility program or
 application program. However, in a textual and legal sense, the linked
 executable is a combined work, a derivative of the original library,
 and the ordinary General Public License treats it as such.
Because of this blurred distinction, using the ordinary General
 Public License for libraries did not effectively promote software
 sharing, because most developers did not use the libraries. We
 concluded that weaker conditions might promote sharing better.
However, unrestricted linking of non-free programs would deprive the
 users of those programs of all benefit from the free status of the
 libraries themselves. This Library General Public License is intended
 to permit developers of non-free programs to use free libraries, while
 preserving your freedom as a user of such programs to change the free
 libraries that are incorporated in them. (We have not seen how to
 achieve this as regards changes in header files, but we have achieved
 it as regards changes in the actual functions of the Library.) The hope
 is that this will lead to faster development of free libraries.
The precise terms and conditions for copying, distribution and
 modification follow. Pay close attention to the difference between a
 "work based on the library" and a "work that uses the library". The
 former contains code derived from the library, while the latter only
 works together with the library.
Note that it is possible for a library to be covered by the ordinary
 General Public License rather than by this special one.
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
0. This License Agreement applies to any software
 library which contains a notice placed by the copyright holder or other
 authorized party saying it may be distributed under the terms of this
 Library General Public License (also called "this License"). Each
 licensee is addressed as "you".
A "library" means a collection of software functions and/or data
 prepared so as to be conveniently linked with application programs
 (which use some of those functions and data) to form executables.
The "Library", below, refers to any such software library or work
 which has been distributed under these terms. A "work based on the
 Library" means either the Library or any derivative work under
 copyright law: that is to say, a work containing the Library or a
 portion of it, either verbatim or with modifications and/or translated
 straightforwardly into another language. (Hereinafter, translation is
 included without limitation in the term "modification".)
"Source code" for a work means the preferred form of the work for
 making modifications to it. For a library, complete source code means
 all the source code for all modules it contains, plus any associated
 interface definition files, plus the scripts used to control
 compilation and installation of the library.
Activities other than copying, distribution and modification are not
 covered by this License; they are outside its scope. The act of running
 a program using the Library is not restricted, and output from such a
 program is covered only if its contents constitute a work based on the
 Library (independent of the use of the Library in a tool for writing
 it). Whether that is true depends on what the Library does and what the
 program that uses the Library does.
1. You may copy and distribute verbatim copies of
 the Library's complete source code as you receive it, in any medium,
 provided that you conspicuously and appropriately publish on each copy
 an appropriate copyright notice and disclaimer of warranty; keep intact
 all the notices that refer to this License and to the absence of any
 warranty; and distribute a copy of this License along with the Library.
You may charge a fee for the physical act of transferring a copy, and
 you may at your option offer warranty protection in exchange for a fee.
2. You may modify your copy or copies of the Library
 or any portion of it, thus forming a work based on the Library, and
 copy and distribute such modifications or work under the terms of
 Section 1 above, provided that you also meet all of these conditions:
The modified work must itself be a software library.
You must cause the files modified to carry prominent notices stating
 that you changed the files and the date of any change.
You must cause the whole of the work to be licensed at no charge to
 all third parties under the terms of this License.
If a facility in the modified Library refers to a function or a
 table of data to be supplied by an application program that uses the
 facility, other than as an argument passed when the facility is
 invoked, then you must make a good faith effort to ensure that, in the
 event an application does not supply such function or table, the
 facility still operates, and performs whatever part of its purpose
 remains meaningful.
(For example, a function in a library to compute square roots has a
 purpose that is entirely well-defined independent of the application.
 Therefore, Subsection 2d requires that any application-supplied
 function or table used by this function must be optional: if the
 application does not supply it, the square root function must still
 compute square roots.)
These requirements apply to the modified work as a whole. If
 identifiable sections of that work are not derived from the Library,
 and can be reasonably considered independent and separate works in
 themselves, then this License, and its terms, do not apply to those
 sections when you distribute them as separate works. But when you
 distribute the same sections as part of a whole which is a work based
 on the Library, the distribution of the whole must be on the terms of
 this License, whose permissions for other licensees extend to the
 entire whole, and thus to each and every part regardless of who wrote
 it.
Thus, it is not the intent of this section to claim rights or contest
 your rights to work written entirely by you; rather, the intent is to
 exercise the right to control the distribution of derivative or
 collective works based on the Library.
In addition, mere aggregation of another work not based on the
 Library with the Library (or with a work based on the Library) on a
 volume of a storage or distribution medium does not bring the other
 work under the scope of this License.
3. You may opt to apply the terms of the ordinary
 GNU General Public License instead of this License to a given copy of
 the Library. To do this, you must alter all the notices that refer to
 this License, so that they refer to the ordinary GNU General Public
 License, version 2, instead of to this License. (If a newer version
 than version 2 of the ordinary GNU General Public License has appeared,
 then you can specify that version instead if you wish.) Do not make any
 other change in these notices.
Once this change is made in a given copy, it is irreversible for that
 copy, so the ordinary GNU General Public License applies to all
 subsequent copies and derivative works made from that copy.
This option is useful when you wish to copy part of the code of the
 Library into a program that is not a library.
4. You may copy and distribute the Library (or a
 portion or derivative of it, under Section 2) in object code or
 executable form under the terms of Sections 1 and 2 above provided that
 you accompany it with the complete corresponding machine-readable
 source code, which must be distributed under the terms of Sections 1
 and 2 above on a medium customarily used for software interchange.
If distribution of object code is made by offering access to copy
 from a designated place, then offering equivalent access to copy the
 source code from the same place satisfies the requirement to distribute
 the source code, even though third parties are not compelled to copy
 the source along with the object code.
5. A program that contains no derivative of any
 portion of the Library, but is designed to work with the Library by
 being compiled or linked with it, is called a "work that uses the
 Library". Such a work, in isolation, is not a derivative work of the
 Library, and therefore falls outside the scope of this License.
However, linking a "work that uses the Library" with the Library
 creates an executable that is a derivative of the Library (because it
 contains portions of the Library), rather than a "work that uses the
 library". The executable is therefore covered by this License. Section
 6 states terms for distribution of such executables.
When a "work that uses the Library" uses material from a header file
 that is part of the Library, the object code for the work may be a
 derivative work of the Library even though the source code is not.
 Whether this is true is especially significant if the work can be
 linked without the Library, or if the work is itself a library. The
 threshold for this to be true is not precisely defined by law.
If such an object file uses only numerical parameters, data structure
 layouts and accessors, and small macros and small inline functions (ten
 lines or less in length), then the use of the object file is
 unrestricted, regardless of whether it is legally a derivative work.
 (Executables containing this object code plus portions of the Library
 will still fall under Section 6.)
Otherwise, if the work is a derivative of the Library, you may
 distribute the object code for the work under the terms of Section 6.
 Any executables containing that work also fall under Section 6, whether
 or not they are linked directly with the Library itself.
6. As an exception to the Sections above, you may
 also compile or link a "work that uses the Library" with the Library to
 produce a work containing portions of the Library, and distribute that
 work under terms of your choice, provided that the terms permit
 modification of the work for the customer's own use and reverse
 engineering for debugging such modifications.
You must give prominent notice with each copy of the work that the
 Library is used in it and that the Library and its use are covered by
 this License. You must supply a copy of this License. If the work
 during execution displays copyright notices, you must include the
 copyright notice for the Library among them, as well as a reference
 directing the user to the copy of this License. Also, you must do one
 of these things:
Accompany the work with the complete corresponding machine-readable
 source code for the Library including whatever changes were used in the
 work (which must be distributed under Sections 1 and 2 above); and, if
 the work is an executable linked with the Library, with the complete
 machine-readable "work that uses the Library", as object code and/or
 source code, so that the user can modify the Library and then relink to
 produce a modified executable containing the modified Library. (It is
 understood that the user who changes the contents of definitions files
 in the Library will not necessarily be able to recompile the
 application to use the modified definitions.)
Accompany the work with a written offer, valid for at least three
 years, to give the same user the materials specified in Subsection 6a,
 above, for a charge no more than the cost of performing this
 distribution.
If distribution of the work is made by offering access to copy from
 a designated place, offer equivalent access to copy the above specified
 materials from the same place.
Verify that the user has already received a copy of these materials
 or that you have already sent this user a copy.
For an executable, the required form of the "work that uses the
 Library" must include any data and utility programs needed for
 reproducing the executable from it. However, as a special exception,
 the source code distributed need not include anything that is normally
 distributed (in either source or binary form) with the major components
 (compiler, kernel, and so on) of the operating system on which the
 executable runs, unless that component itself accompanies the
 executable.
It may happen that this requirement contradicts the license
 restrictions of other proprietary libraries that do not normally
 accompany the operating system. Such a contradiction means you cannot
 use both them and the Library together in an executable that you
 distribute.
7. You may place library facilities that are a work
 based on the Library side-by-side in a single library together with
 other library facilities not covered by this License, and distribute
 such a combined library, provided that the separate distribution of the
 work based on the Library and of the other library facilities is
 otherwise permitted, and provided that you do these two things:
Accompany the combined library with a copy of the same work based on
 the Library, uncombined with any other library facilities. This must be
 distributed under the terms of the Sections above.
Give prominent notice with the combined library of the fact that
 part of it is a work based on the Library, and explaining where to find
 the accompanying uncombined form of the same work.
8. You may not copy, modify, sublicense, link with,
 or distribute the Library except as expressly provided under this
 License. Any attempt otherwise to copy, modify, sublicense, link with,
 or distribute the Library is void, and will automatically terminate
 your rights under this License. However, parties who have received
 copies, or rights, from you under this License will not have their
 licenses terminated so long as such parties remain in full compliance.
9. You are not required to accept this License,
 since you have not signed it. However, nothing else grants you
 permission to modify or distribute the Library or its derivative works.
 These actions are prohibited by law if you do not accept this License.
 Therefore, by modifying or distributing the Library (or any work based
 on the Library), you indicate your acceptance of this License to do so,
 and all its terms and conditions for copying, distributing or modifying
 the Library or works based on it.
10. Each time you redistribute the Library (or any
 work based on the Library), the recipient automatically receives a
 license from the original licensor to copy, distribute, link with or
 modify the Library subject to these terms and conditions. You may not
 impose any further restrictions on the recipients' exercise of the
 rights granted herein. You are not responsible for enforcing compliance
 by third parties to this License.
11. If, as a consequence of a court judgment or
 allegation of patent infringement or for any other reason (not limited
 to patent issues), conditions are imposed on you (whether by court
 order, agreement or otherwise) that contradict the conditions of this
 License, they do not excuse you from the conditions of this License. If
 you cannot distribute so as to satisfy simultaneously your obligations
 under this License and any other pertinent obligations, then as a
 consequence you may not distribute the Library at all. For example, if
 a patent license would not permit royalty-free redistribution of the
 Library by all those who receive copies directly or indirectly through
 you, then the only way you could satisfy both it and this License would
 be to refrain entirely from distribution of the Library.
If any portion of this section is held invalid or unenforceable under
 any particular circumstance, the balance of the section is intended to
 apply, and the section as a whole is intended to apply in other
 circumstances.
It is not the purpose of this section to induce you to infringe any
 patents or other property right claims or to contest validity of any
 such claims; this section has the sole purpose of protecting the
 integrity of the free software distribution system which is implemented
 by public license practices. Many people have made generous
 contributions to the wide range of software distributed through that
 system in reliance on consistent application of that system; it is up
 to the author/donor to decide if he or she is willing to distribute
 software through any other system and a licensee cannot impose that
 choice.
This section is intended to make thoroughly clear what is believed to
 be a consequence of the rest of this License.
12. If the distribution and/or use of the Library is
 restricted in certain countries either by patents or by copyrighted
 interfaces, the original copyright holder who places the Library under
 this License may add an explicit geographical distribution limitation
 excluding those countries, so that distribution is permitted only in or
 among countries not thus excluded. In such case, this License
 incorporates the limitation as if written in the body of this License.
13. The Free Software Foundation may publish revised
 and/or new versions of the Library General Public License from time to
 time. Such new versions will be similar in spirit to the present
 version, but may differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Library
 specifies a version number of this License which applies to it and "any
 later version", you have the option of following the terms and
 conditions either of that version or of any later version published by
 the Free Software Foundation. If the Library does not specify a license
 version number, you may choose any version ever published by the Free
 Software Foundation.
14. If you wish to incorporate parts of the Library
 into other free programs whose distribution conditions are incompatible
 with these, write to the author to ask for permission. For software
 which is copyrighted by the Free Software Foundation, write to the Free
 Software Foundation; we sometimes make exceptions for this. Our
 decision will be guided by the two goals of preserving the free status
 of all derivatives of our free software and of promoting the sharing
 and reuse of software generally.
NO WARRANTY
15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE,
 THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY
 APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
 HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT
 WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
 PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE
 OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU
 ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR
 AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO
 MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE
 LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL
 OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
 LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
 RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
 FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
 SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
 DAMAGES.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Libraries
If you develop a new library, and you want it to be of the greatest
 possible use to the public, we recommend making it free software that
 everyone can redistribute and change. You can do so by permitting
 redistribution under these terms (or, alternatively, under the terms of
 the ordinary General Public License).
To apply these terms, attach the following notices to the library. It
 is safest to attach them to the start of each source file to most
 effectively convey the exclusion of warranty; and each file should have
 at least the "copyright" line and a pointer to where the full notice is
 found.
one line to give the library's name and an idea of what it does.Copyright (C) 
year  name of authorThis library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
Also add information on how to contact you by electronic and paper
 mail.
You should also get your employer (if you work as a programmer) or
 your school, if any, to sign a "copyright disclaimer" for the library,
 if necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright interest in
the library `Frob' (a library for tweaking knobs) written
by James Random Hacker.
signature of Ty Coon, 1 April 1990
Ty Coon, President of Vice
That's all there is to it!
B - Constants 
This appendix lists all of the constants that are defined by the CUPS
 API.
CUPS Constants 
Version Number 
The CUPS_VERSION constant is a floating-point number
 representing the API version number. The current version number is
 1.0100 which represents CUPS version 1.1.0.
Printer Capabilities 
The CUPS_PRINTER constants represent capability bits for
 printers and classes:
CUPS_PRINTER_LOCAL - Is a local printer or class.CUPS_PRINTER_REMOTE - Is a remote printer or class.CUPS_PRINTER_CLASS - Is a class.CUPS_PRINTER_BW - Printer prints in black and white.CUPS_PRINTER_COLOR - Printer prints in color.CUPS_PRINTER_DUPLEX - Printer can print double-sided.CUPS_PRINTER_STAPLE - Printer can staple output.CUPS_PRINTER_COPIES - Printer can produce multiple
 copies on its own.
CUPS_PRINTER_COLLATE - Printer can collate copies.CUPS_PRINTER_PUNCH - Printer can punch holes in output.CUPS_PRINTER_COVER - Printer can put covers on output.CUPS_PRINTER_BIND - Printer can bind output.CUPS_PRINTER_SORT - Printer can sort output.CUPS_PRINTER_SMALL - Printer can print on media up to
 9x14 inches.
CUPS_PRINTER_MEDIUM - Printer can print on media from
 9x14 to 18x24 inches.
CUPS_PRINTER_LARGE - Printer can print on media larger
 than 18x24 inches.
CUPS_PRINTER_VARIABLE - Printer can print on variable
 or custom media sizes.
CUPS_PRINTER_IMPLICIT - Is an implicit class.CUPS_PRINTER_OPTIONS - All of the printer capability
 and option bits.
Encodings 
CUPS defines the following character set encoding constants:
CUPS_US_ASCII - US ASCII character set.CUPS_UTF_8 - UTF-8 encoding of Unicode.CUPS_ISO8859_1 - ISO-8859-1 character set.CUPS_ISO8859_2 - ISO-8859-2 character set.CUPS_ISO8859_3 - ISO-8859-3 character set.CUPS_ISO8859_4 - ISO-8859-4 character set.CUPS_ISO8859_5 - ISO-8859-5 character set.CUPS_ISO8859_6 - ISO-8859-6 character set.CUPS_ISO8859_7 - ISO-8859-7 character set.CUPS_ISO8859_8 - ISO-8859-8 character set.CUPS_ISO8859_9 - ISO-8859-9 character set.CUPS_ISO8859_10 - ISO-8859-10 character set.CUPS_ISO8859_13 - ISO-8859-13 character set.CUPS_ISO8859_14 - ISO-8859-14 character set.CUPS_ISO8859_15 - ISO-8859-15 character set.CUPS_WINDOWS_874 - Windows code page 874.CUPS_WINDOWS_1250 - Windows code page 1250.CUPS_WINDOWS_1251 - Windows code page 1251.CUPS_WINDOWS_1252 - Windows code page 1252.CUPS_WINDOWS_1253 - Windows code page 1253.CUPS_WINDOWS_1254 - Windows code page 1254.CUPS_WINDOWS_1255 - Windows code page 1255.CUPS_WINDOWS_1256 - Windows code page 1256.CUPS_WINDOWS_1257 - Windows code page 1257.CUPS_WINDOWS_1258 - Windows code page 1258.CUPS_KOI8_R - Russian code page koi8-r.CUPS_KOI8_U - Ukrainian code page koi8-r. HTTP Constants 
Limits 
The following constants define the limits for strings:
HTTP_MAX_BUFFER - Size of socket buffer.HTTP_MAX_HOST - Maximum length of hostname.HTTP_MAX_URI - Maximum length of URI.HTTP_MAX_VALUE - Maximum length of field values. Status Codes 
The following status codes can be returned by httpUpdate():
HTTP_ERROR - A network error occurredHTTP_CONTINUE - Continue response from HTTP proxyHTTP_OK - OPTIONS/GET/HEAD/POST/TRACE command was
 successful
HTTP_CREATED - PUT command was successfulHTTP_ACCEPTED - DELETE command was successfulHTTP_NOT_AUTHORITATIVE - Information isn't
 authoritative
HTTP_NO_CONTENT - Successful commandHTTP_RESET_CONTENT - Content was reset/recreatedHTTP_PARTIAL_CONTENT - Only a partial file was
 recieved/sent
HTTP_MULTIPLE_CHOICES - Multiple files match requestHTTP_MOVED_PERMANENTLY - Document has moved permanentlyHTTP_MOVED_TEMPORARILY - Document has moved temporarilyHTTP_SEE_OTHER - See this other link...HTTP_NOT_MODIFIED - File not modifiedHTTP_USE_PROXY - Must use a proxy to access this URIHTTP_BAD_REQUEST - Bad requestHTTP_UNAUTHORIZED - Unauthorized to access hostHTTP_PAYMENT_REQUIRED - Payment requiredHTTP_FORBIDDEN - Forbidden to access this URIHTTP_NOT_FOUND - URI was not foundHTTP_METHOD_NOT_ALLOWED - Method is not allowedHTTP_NOT_ACCEPTABLE - Not AcceptableHTTP_PROXY_AUTHENTICATION - Proxy Authentication is
 Required
HTTP_REQUEST_TIMEOUT - Request timed outHTTP_CONFLICT - Request is self-conflictingHTTP_GONE - Server has gone awayHTTP_LENGTH_REQUIRED - A content length or encoding is
 required
HTTP_PRECONDITION - Precondition failedHTTP_REQUEST_TOO_LARGE - Request entity too largeHTTP_URI_TOO_LONG - URI too longHTTP_UNSUPPORTED_MEDIATYPE - The requested media type
 is unsupported
HTTP_SERVER_ERROR - Internal server errorHTTP_NOT_IMPLEMENTED - Feature not implementedHTTP_BAD_GATEWAY - Bad gatewayHTTP_SERVICE_UNAVAILABLE - Service is unavailableHTTP_GATEWAY_TIMEOUT - Gateway connection timed outHTTP_NOT_SUPPORTED - HTTP version not supported Fields 
The following fields are indices for each of the standard HTTP fields
 in HTTP 1/1:
HTTP_FIELD_ACCEPT_LANGUAGE - Accept-LanguageHTTP_FIELD_ACCEPT_RANGES - Accept-RangesHTTP_FIELD_AUTHORIZATION - AuthorizationHTTP_FIELD_CONNECTION - ConnectionHTTP_FIELD_CONTENT_ENCODING - Content-EncodingHTTP_FIELD_CONTENT_LANGUAGE - Content-LanguageHTTP_FIELD_CONTENT_LENGTH - Content-LengthHTTP_FIELD_CONTENT_LOCATION - Content-LocationHTTP_FIELD_CONTENT_MD5 - Content-MD5HTTP_FIELD_CONTENT_RANGE - Content-RangeHTTP_FIELD_CONTENT_TYPE - Content-TypeHTTP_FIELD_CONTENT_VERSION - Content-VersionHTTP_FIELD_DATE - DateHTTP_FIELD_HOST - HostHTTP_FIELD_IF_MODIFIED_SINCE - If-Modified-SinceHTTP_FIELD_IF_UNMODIFIED_SINCE - If-Unmodified-SinceHTTP_FIELD_KEEP_ALIVE - Keep-AliveHTTP_FIELD_LAST_MODIFIED - Last-ModifiedHTTP_FIELD_LINK - LinkHTTP_FIELD_LOCATION - LocationHTTP_FIELD_RANGE - RangeHTTP_FIELD_REFERER - RefererHTTP_FIELD_RETRY_AFTER - Retry-AfterHTTP_FIELD_TRANSFER_ENCODING - Transfer-EncodingHTTP_FIELD_UPGRADE - UpgradeHTTP_FIELD_USER_AGENT - User-AgentHTTP_FIELD_WWW_AUTHENTICATE - WWW-Authenticate IPP Constants 
Limits 
The following constants define array limits for IPP data:
IPP_MAX_NAME - Maximum length of an attribute nameIPP_MAX_VALUES - Maximum number of set-of values that
 can be read in a request.
Tags 
IPP_TAG_ZERO - Wildcard tag value for searches; also
 used to separate groups of attributes
IPP_TAG_OPERATION - Tag for values of type operationIPP_TAG_JOB - Tag for values of type jobIPP_TAG_END - Tag for values of type endIPP_TAG_PRINTER - Tag for values of type printerIPP_TAG_UNSUPPORTED_GROUP - Tag for values of type
 unsupported_group
IPP_TAG_UNSUPPORTED_VALUE - Tag for values of type
 unsupported_value
IPP_TAG_DEFAULT - Tag for values of type defaultIPP_TAG_UNKNOWN - Tag for values of type unknownIPP_TAG_NOVALUE - Tag for values of type novalueIPP_TAG_NOTSETTABLE - Tag for values of type
 notsettable
IPP_TAG_DELETEATTR - Tag for values of type deleteattrIPP_TAG_ANYVALUE - Tag for values of type anyvalueIPP_TAG_INTEGER - Tag for values of type integerIPP_TAG_BOOLEAN - Tag for values of type booleanIPP_TAG_ENUM - Tag for values of type enumIPP_TAG_STRING - Tag for values of type stringIPP_TAG_DATE - Tag for values of type dateIPP_TAG_RESOLUTION - Tag for values of type resolutionIPP_TAG_RANGE - Tag for values of type rangeIPP_TAG_COLLECTION - Tag for values of type collectionIPP_TAG_TEXTLANG - Tag for values of type textlangIPP_TAG_NAMELANG - Tag for values of type namelangIPP_TAG_TEXT - Tag for values of type textIPP_TAG_NAME - Tag for values of type nameIPP_TAG_KEYWORD - Tag for values of type keywordIPP_TAG_URI - Tag for values of type uriIPP_TAG_URISCHEME - Tag for values of type urischemeIPP_TAG_CHARSET - Tag for values of type charsetIPP_TAG_LANGUAGE - Tag for values of type languageIPP_TAG_MIMETYPE - Tag for values of type mimetype Resolution Units 
The IPP_RES_PER_INCH and IPP_RES_PER_CM constants specify dots per inch and dots per centimeter, respectively.
Finishings 
The finishing values specify special finishing operations to be
 performed on the job.
IPP_FINISH_NONE - Do no finishingIPP_FINISH_STAPLE - Staple the jobIPP_FINISH_PUNCH - Punch the jobIPP_FINISH_COVER - Cover the jobIPP_FINISH_BIND - Bind the job Orientations 
The orientation values specify the orientation of the job.
IPP_PORTRAIT - No rotationIPP_LANDSCAPE - 90 degrees counter-clockwiseIPP_REVERSE_LANDSCAPE - 90 degrees clockwiseIPP_REVERSE_PORTRAIT - 180 degrees Qualities 
The quality values specify the desired quality of the print.
IPP_QUALITY_DRAFT - Draft qualityIPP_QUALITY_NORMAL - Normal qualityIPP_QUALITY_HIGH - High quality Job States 
The job state values are used to represent the current job state.
IPP_JOB_PENDING - Job is pendingIPP_JOB_HELD - Job is heldIPP_JOB_PROCESSING - Job is processingIPP_JOB_STOPPED - Job is stoppedIPP_JOB_CANCELLED - Job is cancelledIPP_JOB_ABORTED - Job is abortedIPP_JOB_COMPLETED - Job is completed Printer States 
The printer state values are used to represent the current printer
 state.
IPP_PRINTER_IDLE - Printer is idleIPP_PRINTER_PROCESSING - Printer is processingIPP_PRINTER_STOPPED - Printer is stopped Operations 
The operation values represent the available IPP operations.
IPP_PRINT_JOB - Print a fileIPP_PRINT_URI - Print a URIIPP_VALIDATE_JOB - Validate job attributesIPP_CREATE_JOB - Create a new jobIPP_SEND_DOCUMENT - Send a document to a jobIPP_SEND_URI - Send a URI to a jobIPP_CANCEL_JOB - Cancel a jobIPP_GET_JOB_ATTRIBUTES - Get job attributesIPP_GET_JOBS - Get a list of all jobsIPP_GET_PRINTER_ATTRIBUTES - Get printer attributesIPP_HOLD_JOB - Hold a pending jobIPP_RELEASE_JOB - Release a held jobIPP_RESTART_JOB - Restart a completed jobIPP_PAUSE_PRINTER - Pause a printerIPP_RESUME_PRINTER - Restart a paused printerIPP_PURGE_JOBS - Purge jobs from the queueIPP_SET_PRINTER_ATTRIBUTES - Set printer attributesIPP_SET_JOB_ATTRIBUTES - Set job attributesIPP_GET_PRINTER_SUPPORTED_VALUES - Get printer
 supported values
CUPS_GET_DEFAULT - Get the default destinationCUPS_GET_PRINTERS - Get a list of all printersCUPS_ADD_PRINTER - Add or modify a printerCUPS_DELETE_PRINTER - Delete a printerCUPS_GET_CLASSES - Get a list of all classesCUPS_ADD_CLASS - Add or modify a classCUPS_DELETE_CLASS - Delete a classCUPS_ACCEPT_JOBS - Accept jobs on a printer or classCUPS_REJECT_JOBS - Reject jobs on a printer or classCUPS_SET_DEFAULT - Set the default destinationCUPS_GET_DEVICES - Get a list of all devicesCUPS_GET_PPDS - Get a list of all PPDsCUPS_MOVE_JOB - Move a job to a new destination Status Codes 
Status codes are returned by all IPP requests.
IPP_OK - Request completed with no errorsIPP_OK_SUBST - Request completed but some attribute
 values were substituted
IPP_OK_CONFLICT - Request completed but some attributes
 conflicted
IPP_BAD_REQUEST - The request was badIPP_FORBIDDEN - You don't have access to the resourceIPP_NOT_AUTHENTICATED - You are not authenticated for
 the resource
IPP_NOT_AUTHORIZED - You not authorized to access the
 resource
IPP_NOT_POSSIBLE - The requested operation cannot be
 completed
IPP_TIMEOUT - A timeout occurredIPP_NOT_FOUND - The resource was not foundIPP_GONE - The resource has gone awayIPP_REQUEST_ENTITY - The request was too largeIPP_REQUEST_VALUE - The request contained a value that
 was unknown to the server
IPP_DOCUMENT_FORMAT - The document format is not
 supported by the server
IPP_ATTRIBUTES - Required attributes are missingIPP_URI_SCHEME - The URI scheme is not supportedIPP_CHARSET - The charset is not supportedIPP_CONFLICT - One or more attributes conflictIPP_COMPRESSION_NOT_SUPPORTED - The specified
 compression is not supported
IPP_COMPRESSION_ERROR - The compressed data contained
 an error
IPP_DOCUMENT_FORMAT_ERROR - The document data contained
 an error in it
IPP_DOCUMENT_ACCESS_ERROR - The remote document could
 not be accessed
IPP_INTERNAL_ERROR - The server encountered an internal
 error
IPP_OPERATION_NOT_SUPPORTED - The requested operation
 is not supported
IPP_SERVICE_UNAVAILABLE - The requested service is
 unavailable
IPP_VERSION_NOT_SUPPORTED - The IPP request version is
 not supported
IPP_DEVICE_ERROR - The output device encountered an
 error
IPP_TEMPORARY_ERROR - A temporary error occurredIPP_NOT_ACCEPTING - The destination is not accepting
 jobs
IPP_PRINTER_BUSY - The destination is busyIPP_ERROR_JOB_CANCELLED - The requested job has been
 cancelled
IPP_MULTIPLE_JOBS_NOT_SUPPORTED - The server does not
 support multiple jobs
PPD Constants 
PPD Format Version 
The PPD_VERSION constant defines a floating point number
 representing the newest format version that is supported by CUPS,
 currently 4.3.
PPD User-Interface Types 
Each printer option has a type associated with it:
PPD_UI_BOOLEAN - The user can turn this option on or
 off
PPD_UI_PICKONE - The user can choose one option value
 to use.
PPD_UI_PICKMANY - The user can choose zero or more
 option values.
PPD Sections 
Some options must be output before others, or in different sections
 of the output document. The 
ppd_section_t enumeration
 defines which section the option must be output in:
PPD_ORDER_ANY - The option can be output in any of the
 document, page, or prolog sections of the document
PPD_ORDER_DOCUMENT - The option must be output in the
 DocumentSetup section of the document
PPD_ORDER_EXIT - The option must be output before the
 document
PPD_ORDER_JCL - The option must be output in the job
 control section of the document
PPD_ORDER_PAGE - The option must be output in the
 PageSetup section of the document
PPD_ORDER_PROLOG - The option must be output in the
 Prolog section of the document
PPD Colorspaces 
Each printer has a default colorspace:
PPD_CS_CMYK - The printer uses CMYK colors by defaultPPD_CS_CMY - The printer uses CMY colors by defaultPPD_CS_GRAY - The printer uses grayscale by defaultPPD_CS_RGB - The printer uses RGB colors by defaultPPD_CS_RGBK - The printer uses RGBK colors by defaultPPD_CS_N - The printer uses a DeviceN colorspace by
 default
Raster Constants 
Raster Sync Words 
The CUPS_RASTER_SYNC and CUPS_RASTER_REVSYNC constants define the standard sync words at the beginning of each CUPS
 raster file.
Raster Stream Modes 
The CUPS_RASTER_READ and CUPS_RASTER_WRITE constants are used with the 
#cupsRasterOpencupsRasterOpen()
 function to specify a stream for reading or
 writing.
Raster Boolean Constants 
The CUPS_FALSE and CUPS_TRUE constants
 represent boolean values in the page header.
Raster Jog Values 
The cups_jog_t enumeration defines constants for the Jog
 page device dictionary variable:
CUPS_JOG_NONE - Do no joggingCUPS_JOG_FILE - Jog pages after each fileCUPS_JOG_JOB - Jog pages after each jobCUPS_JOG_SET - Jog pages after each set of jobs Raster Orientation Values 
The cups_orient_t enumeration defines constants for the
 Orientation page device dictionary variable:
CUPS_ORIENT_0 - Portrait orientationCUPS_ORIENT_90 - Landscape orientationCUPS_ORIENT_180 - Reverse-portrait orientationCUPS_ORIENT_270 - Reverse-landscape orientation Raster CutMedia Values 
The cups_cut_t enumeration defines constants for the
 CutMedia page device dictionary variable:
CUPS_CUT_NONE - Do no joggingCUPS_CUT_FILE - Cut pages after each fileCUPS_CUT_JOB - Cut pages after each jobCUPS_CUT_SET - Cut pages after each set of jobsCUPS_CUT_PAGE - Cut each page Raster AdvanceMedia Values 
The cups_advance_t enumeration defines constants for the
 AdvanceMedia page device dictionary variable:
CUPS_ADVANCE_NONE - Do no joggingCUPS_ADVANCE_FILE - Advance media after each fileCUPS_ADVANCE_JOB - Advance media after each jobCUPS_ADVANCE_SET - Advance media after each set of jobsCUPS_ADVANCE_PAGE - Advance media for each page Raster LeadingEdge Values 
The cups_edge_t enumeration defines constants for the
 LeadingEdge page device dictionary variable:
CUPS_EDGE_TOP - The top of the media is the leading
 edge
CUPS_EDGE_RIGHT - The right of the media is the leading
 edge
CUPS_EDGE_BOTTOM - The bottom of the media is the
 leading edge
CUPS_EDGE_LEFT - The left of the media is the leading
 edge
Raster Color Order Values 
The cups_order_t enumeration defines the possible color
 value orderings:
CUPS_ORDER_CHUNKED - CMYK CMYK CMYKCUPS_ORDER_BANDED - CCC MMM YYY KKKCUPS_ORDER_PLANAR - CCC ... MMM ... YYY ... KKK ... Raster Colorspace Values 
The cups_cspace_t enumeration defines the possible
 colorspaces:
CUPS_CSPACE_W - White (luminance)CUPS_CSPACE_RGB - Red, green, blueCUPS_CSPACE_RGBA - Red, green, blue, alphaCUPS_CSPACE_K - BlackCUPS_CSPACE_CMY - Cyan, magenta, yellowCUPS_CSPACE_YMC - Yellow, magenta, cyanCUPS_CSPACE_CMYK - Cyan, magenta, yellow, blackCUPS_CSPACE_YMCK - Yellow, magenta, cyan, blackCUPS_CSPACE_KCMY - Black, cyan, magenta, yellowCUPS_CSPACE_KCMYcm - Black, cyan, magenta, yellow,
 light cyan, light magenta
CUPS_CSPACE_GMCK - Metallic yellow (gold), metallic
 magenta, metallic cyan, black
CUPS_CSPACE_GMCS - Metallic yellow (gold), metallic
 magenta, metallic cyan, metallic grey (silver)
CUPS_CSPACE_WHITE - White pigment (black as white
 pigment)
CUPS_CSPACE_GOLD - Gold foil (black as gold foil)CUPS_CSPACE_SILVER - Silver foil (black as silver foil) C - Structures 
This appendix describes all of the structures that are defined by the
 CUPS API.
CUPS Structures 
CUPS Destinations 
The CUPS destination structure (cups_dest_t) contains
 information on a specific destination or instance:
MemberTypeDescription name char * The name of the printer or class. instance char * The instance of the printer or
 class; NULL for the primary instance.
is_default int 1 if the destination is set as
 the default, 0 otherwise.
num_options int The number of options associated
 with this destination.
options #cups_option_tcups_option_t * The options associated with this destination.
CUPS Jobs 
The CUPS job structure (cups_job_t) contains information
 on a specific job:
MemberTypeDescription id int The job ID for this job. dest char * The destination for this job
 (printer or class name).
title char * The job-name for this job (title). user char * The job-originating-user-name for
 this job (username).
format char * The document-format for this job
 (MIME type string).
state ipp_jstate The current state of the job. size int The size of this job in kilobytes. priority int The priority of this job from 1 to
 100 (50 is normal).
completed_time time_t The time the job was
 completed, or 0 if not yet completed.
creation_time time_t The time the job was
 queued.
processing_time time_t The time the job started
 printing.
CUPS Messages 
The CUPS messages structure (cups_lang_t) contains the
 character set, locale name, and messages array:
MemberTypeDescription next cups_lang_t * Pointer to the next messages
 structure in memory.
used int The number of active users of this
 messages structure.
encoding cups_encoding_t The character encoding
 of the message strings.
language char [16] The language/locale name. messages char *[] The array of message strings. 
CUPS Options 
The CUPS option structure (cups_option_t) contains the
 option name and string value:
MemberTypeDescription name char * The name of the option. value char * The string value of the option. 
Networking Structures 
HTTP State 
The HTTP state structure (http_t) contains the current
 state of a HTTP request or response:
MemberTypeDescription fd int The socket for the HTTP connection. blocking int 1 if the HTTP functions should
 block, 0 if not.
error int The last OS error that occurred on the
 socket.
activity time_t The last time the HTTP
 connection was used.
state http_state_t The current HTTP
 request/response state.
status int The last HTTP status seen. version http_version_t The HTTP protocol version
 in use.
keep_alive http_keep_alive_t Whether or not to
 use Keep-Alive
hostaddr struct sockaddr_in The IPv4 address of
 the HTTP server.
hostname char [] The hostname of the HTTP
 server.
fields char [][] The string values of all HTTP
 request/response fields.
data char * Current byte in data buffer. data_encoding http_encoding_t The transfer
 encoding for the request/response.
data_remaining int The number of bytes remaining
 in the current request, response, or chunk.
used int The number of bytes that are used in
 the buffer.
buffer char [] The read/write buffer. auth_type int The type of authentication in use. md5_state md5_state_t The current MD5 digest
 state.
nonce char [] The nonce value for Digest
 authentication.
nonce_count int The nonce count value. tls void * A pointer to private encryption data. encryption http_encryption_t The current
 encryption mode.
IPP State 
The IPP state structure (ipp_t) contains the current
 state of a IPP request or response:
MemberTypeDescription 
IPP Attribute 
TODO
PPD Structures 
PPD File 
TODO
PPD Choice 
TODO
Raster Structures 
Raster Stream 
TODO
Raster Page Header 
The raster page header (cups_raster_header_t) consists
 of the PostScript page device dictionary for the page:
MemberTypeDescription MediaClass char[64] The media class name MediaColor char[64] The media color name MediaType char[64] The media type name OutputType char[64] The output type name AdvanceDistance unsigned The distance to advance
 the media in points
AdvanceMedia cups_adv_t When to advance the
 media
Collate cups_bool_t Whether or not to produce
 collated copies
CutMedia cups_cut_t When to cut the media Duplex cups_bool_t Whether or not to print on
 both sides of the paper
HWResolution unsigned[2] The resolution of the
 page image in pixels per inch; the HWResolution[0] represents the
 horizontal resolution and HWResolution[1] represents the vertical
 resolution
ImagingBoundingBox unsigned[4] The bounding box
 for the page in points; the elements represent the left, bottom, right,
 and top coordinates of the imaged area (if 0 then the whole page is
 imaged)
InsertSheet cups_bool_t Whether or not to insert
 a sheet before this page
Jog cups_jog_t When to jog copies of the page LeadingEdge cups_edge_t The leading edge of the
 page
Margins unsigned[2] The lower-lefthand margin of
 the page in points
ManualFeed cups_bool_t Whether or not to
 manually feed the page
MediaPosition unsigned The input slot number to
 use
MediaWeight unsigned The weight of the output
 media in grams/m
2 MirrorPrint cups_bool_t Whether or not to mirror
 the print
NegativePrint cups_bool_t Whether or not to
 invert the print
NumCopies unsigned The number of copies to
 produce
Orientation cups_orient_t The orientation of the
 page image
OutputFaceUp cups_bool_t Whether or not to
 output the page face up
PageSize unsigned[2] The width and height of the
 page in points
Separations cups_bool_t Whether or not to output
 separations
TraySwitch cups_bool_t Whether or not to
 automatically switch trays for the requested media size/type
Tumble cups_bool_t Whether or not to rotate the
 back side of the page
cupsWidth unsigned The width of the page image
 in pixels
cupsHeight unsigned The height of the page image
 in pixels
cupsMediaType unsigned The device-specific media
 type code
cupsBitsPerColor unsigned The number of bits per
 color
cupsBitsPerPixel unsigned The number of bits per
 pixel
cupsBytesPerLine unsigned The number of bytes
 per line of image data
cupsColorOrder cups_order_t The order of color
 values
cupsColorSpace cups_cspace_t The type of color
 values
cupsCompression unsigned The device-specific
 compression code
cupsRowCount unsigned The device-specific row
 count
cupsRowFeed unsigned The device-specific row
 feed
cupsRowStep unsigned The device-specific row
 step
D - Functions 
This appendix provides a reference for all of the CUPS API functions.
cupsAddDest() 
Usage 
int
cupsAddDest(const char  *name,
            const char  *instance,
            int         num_dests,
	    cups_dest_t **dests);
Arguments 
ArgumentDescription name The name of the destination. instance The instance of the destination, or NULL for
 the primary instance.
num_dests The number of destinations in the array. dest A pointer to the destination array pointer. Returns 
The new number of destinations in the array.
Description 
cupsAddDest() adds the named destination to the
 destination array if it does not already exist.
Example 
#include <cups/cups.h>
int         num_dests;
#cups_dest_tcups_dest_t  *dests;
num_dests = cupsAddDests("foo", "bar", num_dests, &dests);
See Also 
 #cupsFreeDestscupsFreeDests() , #cupsGetDestcupsGetDest() , #cupsGetDestscupsGetDests()
cupsAddOption() 
Usage 
int
cupsAddOption(const char    *name,
              const char    *value,
              int           num_options,
	      cups_option_t **options);
Arguments 
ArgumentDescription name The name of the option. value The value of the option. num_options Number of options currently in the array. options Pointer to the options array. Returns 
The new number of options.
Description 
cupsAddOption() adds an option to the specified array.
Example 
#include <cups.h>
...
/* Declare the options array */
int           num_options;
#cups_option_tcups_option_t  *options;
/* Initialize the options array */
num_options = 0;
options     = (cups_option_t *)0;
/* Add options using cupsAddOption() */
num_options = cupsAddOption("media", "letter", num_options, &options);
num_options = cupsAddOption("resolution", "300dpi", num_options, &options);
See Also 
 
#cupsEncodeOptionscupsEncodeOptions() , #cupsFreeOptionscupsFreeOptions() , #cupsGetOptioncupsGetOption()
, #cupsParseOptionscupsParseOptions()
cupsCancelJob() 
Usage 
int
cupsCancelJob(const char *dest,
              int        job);
Arguments 
ArgumentDescription dest Printer or class name job Job ID Returns 
1 on success, 0 on failure. On failure the error can be found by
 calling 
#cupsLastErrorcupsLastError() .
Description 
cupsCancelJob() cancels the specifies job.
Example 
#include <cups.h>
cupsCancelJob("LaserJet", 1);
See Also 
 #cupsLastErrorcupsLastError() , #cupsPrintFilecupsPrintFile() , #cupsPrintFilescupsPrintFiles()
cupsDoAuthentication() 
Usage 
int
cupsDoAuthentication(http_t     *http,
                     const char *method,
                     const char *resource);
Arguments 
ArgumentDescription http HTTP connection to server. method HTTP method name ("GET", "POST", "PUT", etc.) resource HTTP resource name. Returns 
0 if the authentication string was successfully generated, -1
 otherwise.
Description 
cupsDoAuthentication() generates an authentication
 string for the given method and request. It supports Basic, Digest, and
 CUPS local certificate authentication methods and uses the current user
 and password callback to collect authentication information as needed.
Applications using this function should set the HTTP_FIELD_AUTHORIZATION
 field to the authstring value in the 
http_t structure prior to issuing a new
 request.
Example 
#include <cups.h>
http_t        *http;
char          resource[HTTP_MAX_URI];
http_status_t status;
...
do
{
  httpClearFields(http);
  httpSetField(http, HTTP_FIELD_AUTHORIZATION, http->authstring);
  if (httpGet(http, resource))
  {
    if (httpReconnect(http))
    {
      status = HTTP_ERROR;
      break;
    }
    continue;
  }
  while ((status = httpUpdate(http)) == HTTP_CONTINUE);
  if (status == HTTP_UNAUTHORIZED)
  {
    httpFlush(http);
    if (cupsDoAuthentication(http, "GET", resource))
      break;
    httpReconnect(http);
    continue;
  }
}
while (status == HTTP_UNAUTHORIZED);
See Also 
 #cupsDoAuthenticationcupsDoAuthentication() , 
#cupsGetPasswordcupsGetPassword() , #cupsSetPasswordCBcupsSetPasswordCB() , #cupsSetUsercupsSetUser()
, #cupsUsercupsUser() 
cupsDoFileRequest() 
Usage 
ipp_t *
cupsDoFileRequest(http_t     *http,
                  ipp_t      *request,
                  const char *resource,
		  const char *filename);
Arguments 
ArgumentDescription http HTTP connection to server. request IPP request data. resource HTTP resource name for POST. filename File to send with POST request (NULL pointer if none.)
Returns 
IPP response data or NULL if the request fails. On
 failure the error can be found by calling 
#cupsLastErrorcupsLastError()
.
Description 
cupsDoFileRequest() does a HTTP POST request and
 provides the IPP request and optionally the contents of a file to the
 IPP server. It also handles resubmitting the request and performing
 password authentication as needed.
Example 
#include <cups.h>
#http_thttp_t       *http;
#cups_lang_tcups_lang_t  *language;
#ipp_tipp_t        *request;
ipp_t       *response;
...
/* Get the default language */
language = 
#cupsLangDefaultcupsLangDefault() ;
/* Create a new IPP request */
request  = 
#ippNewippNew() ;
request->request.op.operation_id = IPP_PRINT_FILE;
request->request.op.request_id   = 1;
/* Add required attributes */
#ippAddStringippAddString (request, IPP_TAG_OPERATION, IPP_TAG_CHARSET,
             "attributes-charset", NULL, 
#cupsLangEncodingcupsLangEncoding (language));
ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_LANGUAGE,
             "attributes-natural-language", NULL,
             language != NULL ? language->language : "C");
ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri",
             NULL, "ipp://hostname/resource");
ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name",
             NULL, 
#cupsUsercupsUser() );
/* Do the request... */
response = cupsDoFileRequest(http, request, "/resource", "filename.txt");
See Also 
 #cupsLangDefaultcupsLangDefault() , #cupsLangEncodingcupsLangEncoding() , #cupsUsercupsUser()
, #httpConnecthttpConnect() , 
#ippAddStringippAddString() , #ippNewippNew() 
cupsDoRequest() 
Usage 
ipp_t *
cupsDoRequest(http_t *http,
              ipp_t *request,
              const char *resource);
Arguments 
ArgumentDescription http HTTP connection to server. request IPP request data. resource HTTP resource name for POST. Returns 
IPP response data or NULL if the request fails. On
 failure the error can be found by calling 
#cupsLastErrorcupsLastError()
.
Description 
cupsDoRequest() does a HTTP POST request and provides
 the IPP request to the IPP server. It also handles resubmitting the
 request and performing password authentication as needed.
Example 
#include <cups.h>
#http_thttp_t       *http;
#cups_lang_tcups_lang_t  *language;
#ipp_tipp_t        *request;
ipp_t       *response;
...
/* Get the default language */
language = 
#cupsLangDefaultcupsLangDefault() ;
/* Create a new IPP request */
request  = 
#ippNewippNew() ;
request->request.op.operation_id = IPP_GET_PRINTER_ATTRIBUTES;
request->request.op.request_id   = 1;
/* Add required attributes */
#ippAddStringippAddString (request, IPP_TAG_OPERATION, IPP_TAG_CHARSET,
             "attributes-charset", NULL, 
#cupsLangEncodingcupsLangEncoding (language));
ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_LANGUAGE,
             "attributes-natural-language", NULL,
             language != NULL ? language->language : "C");
ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri",
             NULL, "ipp://hostname/resource");
/* Do the request... */
response = cupsDoRequest(http, request, "/resource");
See Also 
 #cupsLangDefaultcupsLangDefault() , #cupsLangEncodingcupsLangEncoding() , #cupsUsercupsUser()
, #httpConnecthttpConnect() , 
#ippAddStringippAddString() , #ippNewippNew() 
cupsEncodeOptions() 
Usage 
void
cupsEncodeOptions(ipp_t         *ipp,
                  int           num_options,
		  cups_option_t *options);
Arguments 
ArgumentDescription ipp The IPP request. num_options The number of options. options The options. Description 
cupsEncodeOptions() encodes all of the options in the
 specified array as IPP attributes and adds them to the IPP request.
Example 
#include <cups/cups.h>
#ipp_tipp_t          *ipp;
int           num_options;
#cups_option_tcups_option_t  *options;
cupsEncodeOptions(ipp, num_options, options);
See Also 
 #cupsAddOptioncupsAddOption() , #cupsParseOptionscupsParseOptions() , #ippNewippNew() 
cupsEncryption() 
Usage 
http_encryption_t
cupsEncryption(void);
Returns 
The current encryption setting.
Description 
cupsEncryption() returns the current encryption setting
 for IPP requests such as printing.
Example 
#include <cups/cups.h>
#http_thttp_t  *http;
printf("The current encryption setting is %d.\n", cupsEncryption());
http = httpConnectEncrypt(cupsServer(), ippPort(), cupsEncryption());
See Also 
 #cupsServercupsServer() , #httpConnectEncrypthttpConnectEncrypt() , #ippPortippPort()
cupsFreeDests() 
Usage 
void
cupsFreeDests(int         num_dests,
              cups_dest_t *dests);
Arguments 
ArgumentDescription num_dests The number of destinations in the array. dests The destination array. Description 
cupsFreeDests() frees a destination array that was
 created using 
cupsGetDests().
Example 
#include <cups/cups.h>
int         num_dests;
#cups_dest_tcups_dest_t  *dests;
cups_dest_t *dest;
num_dests = cupsGetDests(&dests);
dest      = cupsGetDest(NULL, NULL, num_dests, dests);
if (dest)
  printf("The default destination is %s\n", dest->name);
else
  puts("No default destination.");
cupsFreeDests(num_dests, dests);
See Also 
 #cupsGetDestcupsGetDest() , #cupsGetDestscupsGetDests() 
cupsFreeJobs() 
Usage 
void
cupsFreeJobs(int        num_jobs,
             cups_job_t *jobs);
Arguments 
ArgumentDescription num_jobs The number of jobs. jobs The job array. Description 
cupsFreeJobs() frees an array of print jobs created by
 the 
cupsGetJobs() function.
Example 
#include <cups/cups.h>
int        i;
int        num_jobs;
#cups_job_tcups_job_t  *jobs;
num_jobs = cupsGetJobs(&jobs, NULL, 0, 0);
printf("%d active job(s):\n", num_jobs);
for (i = 0; i < num_jobs; i ++)
  printf("%-16.16s %-6d %-12.12s %s (%s)\n", jobs[i].dest, jobs[i].id,
         jobs[i].user, jobs[i].title,
	 jobs[i].state != IPP_JOB_PENDING ? "printing" : "pending");
cupsFreeJobs(num_jobs, jobs);
See Also 
 #cupsGetJobscupsGetJobs() , #cupsGetDestscupsGetDests() 
cupsFreeOptions() 
Usage 
void
cupsFreeOptions(int           num_options,
                cups_option_t *options);
Arguments 
ArgumentDescription num_options Number of options in array. options Pointer to options array. Description 
cupsFreeOptions() frees all memory associated with the
 option array specified.
Example 
#include <cups/cups.h>
int           num_options;
#cups_option_tcups_option_t  *options;
...
cupsFreeOptions(num_options, options);
See Also 
 #cupsAddOptioncupsAddOption() , #cupsEncodeOptionscupsEncodeOptions() , #cupsGetOptioncupsGetOption()
, #cupsMarkOptionscupsMarkOptions()
, #cupsParseOptionscupsParseOptions()
cupsGetClasses() 
Usage 
int
cupsGetClasses(char ***classes);
Arguments 
ArgumentDescription classes Pointer to character pointer array. Returns 
The number of printer classes available.
Description 
cupsGetClasses() gets a list of the available printer
 classes. The returned array should be freed using the 
free() when it is no longer needed.
Example 
#include <cups/cups.h>
int  i;
int  num_classes;
char **classes;
...
num_classes = cupsGetClasses(&classes);
...
if (num_classes > 0)
{
  for (i = 0; i < num_classes; i ++)
    free(classes[i]);
  free(classes);
}
See Also 
 #cupsGetDefaultcupsGetDefault() , #cupsGetPrinterscupsGetPrinters() 
cupsGetDefault() 
Usage 
const char *
cupsGetDefault(void);
Returns 
A pointer to the default destination.
Description 
cupsGetDefault() gets the default destination printer or
 class. The default destination is stored in a static string and will be
 overwritten (usually with the same value) after each call.
Example 
#include <cups/cups.h>
printf("The default destination is %s\n", cupsGetDefault());
See Also 
 #cupsGetClassescupsGetClasses() , #cupsGetPrinterscupsGetPrinters() 
cupsGetDest() 
Usage 
cups_dest_t *
cupsGetDest(const char  *name,
            const char  *instance,
            int         num_dests,
            cups_dest_t *dests);
Arguments 
ArgumentDescription name The name of the destination, or NULL for the
 default destination.
instance The instance of the destination, or NULL for
 the primary instance.
num_dests The number of destinations. dests The destination array. Returns 
A pointer to the specified destination, or NULL if none exists.
Description 
cupsGetDest() finds the specified destination in the
 array of destinations created by the 
cupsGetDests() function.
Example 
#include <cups/cups.h>
int         num_dests;
#cups_dest_tcups_dest_t  *dests;
cups_dest_t *dest;
num_dests = cupsGetDests(&dests);
dest      = cupsGetDest(NULL, NULL, num_dests, dests);
if (dest)
  printf("The default destination is %s\n", dest->name);
else
  puts("No default destination.");
cupsFreeDests(num_dests, dests);
See Also 
 #cupsGetDestscupsGetDests() , #cupsGetJobscupsGetJobs() 
cupsGetDests() 
Usage 
int
cupsGetDests(cups_dest_t **dests);
Arguments 
ArgumentDescription dests A pointer to a destination array pointer. Returns 
The number of available destinations.
Description 
cupsGetDests() creates an array of available
 destinations that the user can print to. The array should be freed
 using the 
cupsFreeDests() function.
Example 
#include <cups/cups.h>
int         num_dests;
#cups_dest_tcups_dest_t  *dests;
cups_dest_t *dest;
num_dests = cupsGetDests(&dests);
dest      = cupsGetDest(NULL, NULL, num_dests, dests);
if (dest)
  printf("The default destination is %s\n", dest->name);
else
  puts("No default destination.");
cupsFreeDests(num_dests, dests);
See Also 
 #cupsFreeDestscupsFreeDests() , #cupsGetDestcupsGetDest() , #cupsGetJobscupsGetJobs()
cupsGetFd() 
Usage 
http_status_t
cupsGetFd(http_t     *http,
          const char *resource,
	  int        fd);
Arguments 
ArgumentDescription http The HTTP connection to the server. resource The resource name on the server. fd The file descriptor to write to. Returns 
The HTTP status code associated with the request.
Description 
cupsGetFd() gets a file from the given HTTP server and
 writes it to the specified file descriptor, performing any
 authentication or encryption as required.
Example 
#include <cups/cups.h>
http_t        *http;
int           fd;
char          filename[1024];
http_status_t status;
...
http   = httpConnectEncrypt(cupsServer(), ippPort(), cupsEncryption());
fd     = cupsTempFd(filename, sizeof(filename));
status = cupsGetFd(http, "/admin/cupsd.conf", fd);
...
close(fd);
unlink(filename);
httpClose(http);
See Also 
 #cupsGetFilecupsGetFile() , #cupsPutFdcupsPutFd() , #cupsPutFilecupsPutFile() 
cupsGetFile() 
Usage 
http_status_t
cupsGetFile(http_t     *http,
            const char *resource,
	    const char *filename);
Arguments 
ArgumentDescription http The HTTP connection to the server. resource The resource name on the server. filename The filename to write to. Returns 
The HTTP status code associated with the request.
Description 
cupsGetFile() gets a file from the given HTTP server and
 writes it to the specified filename, performing any authentication or
 encryption as required.
Example 
#include <cups/cups.h>
http_t        *http;
char          filename[1024];
http_status_t status;
...
http = httpConnectEncrypt(cupsServer(), ippPort(), cupsEncryption());
cupsTempFile(filename, sizeof(filename));
status = cupsGetFile(http, "/admin/cupsd.conf", filename);
...
unlink(filename);
httpClose(http);
See Also 
 #cupsGetFdcupsGetFd() , #cupsPutFdcupsPutFd() , #cupsPutFilecupsPutFile() 
cupsGetJobs() 
Usage 
int
cupsGetJobs(cups_job_t **jobs,
            const char *dest,
            int        myjobs,
            int        completed);
Arguments 
ArgumentDescription jobs A pointer to the job array pointer. dest The destination name, or NULL if jobs for all
 destinations are requested.
myjobs 1 if only those jobs submitted by the current cupsUser()
 should be returned, 0 for jobs submitted by all users. completed 1 if only completed jobs should be returned, 0
 if only pending/processing jobs should be returned.
Returns 
The number of jobs.
Description 
cupsGetJobs() creates an array of print jobs based on
 the arguments supplied in the function call. The returned array should
 be freed using the 
cupsFreeJobs() function.
Example 
#include <cups/cups.h>
int        i;
int        num_jobs;
#cups_job_tcups_job_t  *jobs;
num_jobs = cupsGetJobs(&jobs, NULL, 0, 0);
printf("%d active job(s):\n", num_jobs);
for (i = 0; i < num_jobs; i ++)
  printf("%-16.16s %-6d %-12.12s %s (%s)\n", jobs[i].dest, jobs[i].id,
         jobs[i].user, jobs[i].title,
	 jobs[i].state != IPP_JOB_PENDING ? "printing" : "pending");
cupsFreeJobs(num_jobs, jobs);
See Also 
 #cupsFreeJobscupsFreeJobs() , #cupsGetDestscupsGetDests() 
cupsGetOption() 
Usage 
const char *
cupsGetOption(const char    *name,
              int           num_options,
              cups_option_t *options);
Arguments 
ArgumentDescription name The name of the option. num_options The number of options in the array. options The options array. Returns 
A pointer to the option values or NULL if the option is
 not defined.
Description 
cupsGetOption() returns the first occurrence of the
 named option. If the option is not included in the options array then a
 
NULL pointer is returned.
#include <cups/cups.h>
int           num_options;
cups_option_t *options;
const char    *media;
...
media = cupsGetOption("media", num_options, options);
See Also 
 #cupsAddOptioncupsAddOption() , #cupsEncodeOptionscupsEncodeOptions() , #cupsFreeOptionscupsFreeOptions()
, #cupsMarkOptionscupsMarkOptions()
, #cupsParseOptionscupsParseOptions()
cupsGetPassword() 
Usage 
const char *
cupsGetPassword(const char *prompt);
Arguments 
ArgumentDescription prompt The prompt to display to the user. Returns 
A pointer to the password that was entered or NULL if no
 password was entered.
Description 
cupsGetPassword() displays the prompt string and asks
 the user for a password. The password text is not echoed to the user.
Example 
#include <cups/cups.h>
char *password;
...
password = cupsGetPassword("Please enter a password:");
See Also 
 #cupsDoAuthenticationcupsDoAuthentication() , 
#cupsServercupsServer() , #cupsSetPasswordCBcupsSetPasswordCB() , #cupsSetServercupsSetServer()
, #cupsSetUsercupsSetUser() , #cupsUsercupsUser() 
cupsGetPPD() 
Usage 
const char *
cupsGetPPD(const char *printer);
Arguments 
ArgumentDescription printer The name of the printer. Returns 
The name of a temporary file containing the PPD file or NULL if the printer cannot be located or does not have a PPD file.
Description 
cupsGetPPD() gets a copy of the PPD file for the named
 printer. The printer name can be of the form "printer" or
 "printer@hostname".
You should remove (unlink) the PPD file after you are done using it.
 The filename is stored in a static buffer and will be overwritten with
 each call to 
cupsGetPPD().
Example 
#include <cups/cups.h>
char *ppd;
...
ppd = cupsGetPPD("printer@hostname");
...
unlink(ppd);
cupsGetPrinters() 
Usage 
int
cupsGetPrinters(char ***printers);
Arguments 
ArgumentDescription printers Pointer to character pointer array. Returns 
The number of printer printers available.
Description 
cupsGetPrinters() gets a list of the available printers.
 The returned array should be freed using the 
free() when
 it is no longer needed.
Example 
#include <cups/cups.h>
int  i;
int  num_printers;
char **printers;
...
num_printers = cupsGetPrinters(&printers);
...
if (num_printers > 0)
{
  for (i = 0; i < num_printers; i ++)
    free(printers[i]);
  free(printers);
}
See Also 
 #cupsGetClassescupsGetClasses()  #cupsGetDefaultcupsGetDefault() 
cupsLangDefault() 
Usage 
const char *
cupsLangDefault(void);
Returns 
A pointer to the default language structure.
Description 
cupsLangDefault() returns a language structure for the
 default language. The default language is defined by the 
LANG environment variable. If the specified language cannot be located then
 the POSIX (English) locale is used.
Call cupsLangFree() to free any memory associated with
 the language structure when you are done.
Example 
#include <cups/language.h>
#cups_lang_tcups_lang_t  *language;
...
language = cupsLangDefault();
...
cupsLangFree(language);
See Also 
 #cupsLangEncodingcupsLangEncoding() , #cupsLangFlushcupsLangFlush() , #cupsLangFreecupsLangFree()
, #cupsLangGetcupsLangGet() , #cupsLangStringcupsLangString() 
cupsLangEncoding() 
Usage 
char *
cupsLangEncoding(cups_lang_t *language);
Arguments 
ArgumentDescription language The language structure. Returns 
A pointer to the encoding string.
Description 
cupsLangEncoding() returns the language encoding used
 for the specified language, e.g. "iso-8859-1", "utf-8", etc.
Example 
#include <cups/language.h>
#cups_lang_tcups_lang_t  *language;
char        *encoding;
...
language = cupsLangDefault();
encoding = cupsLangEncoding(language);
...
cupsLangFree(language);
See Also 
 #cupsLangDefaultcupsLangDefault() , #cupsLangFlushcupsLangFlush() , #cupsLangFreecupsLangFree()
, #cupsLangGetcupsLangGet() , #cupsLangStringcupsLangString() 
cupsLangFlush() 
Usage 
void
cupsLangFlush(void);
Description 
cupsLangFlush() frees all language structures that have
 been allocated.
Example 
#include <cups/language.h>
...
cupsLangFlush();
See Also 
 #cupsLangDefaultcupsLangDefault() , #cupsLangEncodingcupsLangEncoding() , #cupsLangFreecupsLangFree()
, #cupsLangGetcupsLangGet() , #cupsLangStringcupsLangString() 
cupsLangFree() 
Usage 
void
cupsLangFree(cups_lang_t *language);
Arguments 
ArgumentDescription language The language structure to free. Description 
cupsLangFree() frees the specified language structure.
Example 
#include <cups/language.h>
#cups_lang_tcups_lang_t  *language;
...
cupsLangFree(language);
See Also 
 #cupsLangDefaultcupsLangDefault() , #cupsLangEncodingcupsLangEncoding() , #cupsLangFlushcupsLangFlush()
, #cupsLangGetcupsLangGet() , #cupsLangStringcupsLangString() 
cupsLangGet() 
Usage 
cups_lang_t *
cupsLangGet(const char *name);
Arguments 
ArgumentDescription name The name of the locale. Returns 
A pointer to a language structure.
Description 
cupsLangGet() returns a language structure for the
 specified locale. If the locale is not defined then the POSIX (English)
 locale is substituted.
Example 
#include <cups/language.h>
#cups_lang_tcups_lang_t  *language;
...
language = cupsLangGet("fr");
...
cupsLangFree(language);
See Also 
 #cupsLangDefaultcupsLangDefault() , #cupsLangEncodingcupsLangEncoding() , #cupsLangFlushcupsLangFlush()
, #cupsLangFreecupsLangFree() , #cupsLangStringcupsLangString() 
cupsLangString() 
Usage 
char *
cupsLangString(cups_lang_t *language,
               int         message);
Arguments 
ArgumentDescription language The language to query. message The message number. Returns 
A pointer to the message string or NULL if the message
 is not defined.
Description 
cupsLangString() returns a pointer to the specified
 message string in the specified language.
Example 
#include <cups/language.h>
#cups_lang_tcups_lang_t  *language;
char        *s;
...
language = cupsLangGet("fr");
s = cupsLangString(language, CUPS_MSG_YES);
...
cupsLangFree(language);
See Also 
 #cupsLangDefaultcupsLangDefault() , #cupsLangEncodingcupsLangEncoding() , #cupsLangFlushcupsLangFlush()
, #cupsLangFreecupsLangFree() , #cupsLangGetcupsLangGet() 
cupsLastError() 
Usage 
ipp_status_t
cupsLastError(void);
Returns 
An enumeration containing the last IPP error.
Description 
cupsLastError() returns the last IPP error that
 occurred. If no error occurred then it will return 
IPP_OK or 
IPP_OK_CONFLICT.
Example 
#include <cups/cups.h>
ipp_status_t status;
...
status = cupsLastError();
See Also 
 #cupsCancelJobcupsCancelJob() , #cupsPrintFilecupsPrintFile() 
cupsMarkOptions() 
Usage 
int
cupsMarkOptions(ppd_file_t    *ppd,
                int           num_options,
                cups_option_t *options);
Arguments 
ArgumentDescription ppd The PPD file to mark. num_options The number of options in the options array. options A pointer to the options array. Returns 
The number of conflicts found.
Description 
cupsMarkOptions() marks options in the PPD file. It also
 handles mapping of IPP option names and values to PPD option names.
Example 
#include <cups/cups.h>
int           num_options;
#cups_option_tcups_option_t  *options;
#ppd_file_tppd_file_t     *ppd;
...
cupsMarkOptions(ppd, num_options, options);
See Also 
 #cupsAddOptioncupsAddOption() , #cupsFreeOptionscupsFreeOptions() , #cupsGetOptioncupsGetOption()
, #cupsParseOptionscupsParseOptions()
cupsParseOptions() 
Usage 
int
cupsParseOptions(const char    *arg,
                 int           num_options,
                 cups_option_t **options);
Arguments 
ArgumentDescription arg The string containing one or more options. num_options The number of options in the options array. options A pointer to the options array pointer. Returns 
The new number of options in the array.
Description 
cupsParseOptions() parses the specifies string for one
 or more options of the form "name=value", "name", or "noname". It can
 be called multiple times to combine the options from several strings.
Example 
#include <cups/cups.h>
int           num_options;
#cups_option_tcups_option_t  *options;
...
num_options = 0;
options     = (cups_option_t *)0;
num_options = cupsParseOptions(argv[5], num_options, &options);
See Also 
 #cupsAddOptioncupsAddOption() , #cupsFreeOptionscupsFreeOptions() , #cupsGetOptioncupsGetOption()
, #cupsMarkOptionscupsMarkOptions()
cupsPrintFile() 
Usage 
int
cupsPrintFile(const char    *printer,
              const char    *filename,
              const char    *title,
	      int           num_options,
	      cups_option_t *options);
Arguments 
ArgumentDescription printer The printer or class to print to. filename The file to print. title The job title. num_options The number of options in the options array. options A pointer to the options array. Returns 
The new job ID number or 0 on error.
Description 
cupsPrintFile() sends a file to the specified printer or
 class for printing. If the job cannot be printed the error code can be
 found by calling 
cupsLastError().
Example 
#include <cups/cups.h>
int           num_options;
#cups_option_tcups_option_t  *options;
int           jobid;
...
jobid = cupsPrintFile("printer@hostname", "filename.ps", "Job Title",
                      num_options, options);
See Also 
 #cupsCancelJobcupsCancelJob() , #cupsLastErrorcupsLastError() , #cupsPrintFilescupsPrintFiles()
cupsPrintFiles() 
Usage 
int
cupsPrintFiles(const char    *printer,
               int           num_files,
               const char    **files,
               const char    *title,
	       int           num_options,
	       cups_option_t *options);
Arguments 
ArgumentDescription printer The printer or class to print to. num_files The number of files to print. files The files to print. title The job title. num_options The number of options in the options array. options A pointer to the options array. Returns 
The new job ID number or 0 on error.
Description 
cupsPrintFiles() sends multiple files to the specified
 printer or class for printing. If the job cannot be printed the error
 code can be found by calling 
cupsLastError().
Example 
#include <cups/cups.h>
int           num_files;
const char    *files[100];
int           num_options;
#cups_option_tcups_option_t  *options;
int           jobid;
...
jobid = cupsPrintFiles("printer@hostname", num_files, files,
                       "Job Title", num_options, options);
See Also 
 #cupsCancelJobcupsCancelJob() , #cupsLastErrorcupsLastError() , #cupsPrintFilecupsPrintFile()
cupsPutFd() 
Usage 
http_status_t
cupsPutFd(http_t     *http,
          const char *resource,
	  int        fd);
Arguments 
ArgumentDescription http The HTTP connection to the server. resource The resource name on the server. fd The file descriptor to read from. Returns 
The HTTP status code associated with the request.
Description 
cupsPutFd() puts a file to the given HTTP server,
 reading it from the specified file descriptor and performing any
 authentication or encryption as required.
Example 
#include <cups/cups.h>
http_t        *http;
int           fd;
http_status_t status;
...
http   = httpConnectEncrypt(cupsServer(), ippPort(), cupsEncryption());
status = cupsPutFd(http, "/admin/cupsd.conf", fd);
httpClose(http);
See Also 
 #cupsGetFdcupsGetFd() , #cupsGetFilecupsGetFile() , #cupsPutFilecupsPutFile()
cupsPutFile() 
Usage 
http_status_t
cupsPutFile(http_t     *http,
            const char *resource,
	    const char *filename);
Arguments 
ArgumentDescription http The HTTP connection to the server. resource The resource name on the server. filename The filename to read from. Returns 
The HTTP status code associated with the request.
Description 
cupsPutFile() puts a file on the given HTTP server,
 reading it from the specified filename and performing any
 authentication or encryption as required.
Example 
#include <cups/cups.h>
http_t        *http;
char          filename[1024];
http_status_t status;
...
http   = httpConnectEncrypt(cupsServer(), ippPort(), cupsEncryption());
status = cupsPutFile(http, "/admin/cupsd.conf", filename);
httpClose(http);
See Also 
 #cupsGetFdcupsGetFd() , #cupsGetFilecupsGetFile() , #cupsPutFdcupsPutFd() 
cupsRasterClose() 
Usage 
void
cupsRasterClose(cups_raster_t *ras);
Arguments 
ArgumentDescription ras The raster stream to close. Description 
cupsRasterClose() closes the specified raster stream.
Example 
#include <cups/raster.h>
#cups_raster_tcups_raster_t  *ras;
...
cupsRasterClose(ras);
See Also 
 #cupsRasterOpencupsRasterOpen() , #cupsRasterReadHeadercupsRasterReadHeader() , #cupsRasterReadPixelscupsRasterReadPixels() , #cupsRasterWriteHeadercupsRasterWriteHeader() , #cupsRasterWritePixelscupsRasterWritePixels() 
cupsRasterOpen() 
Usage 
cups_raster_t *
cupsRasterOpen(int         fd,
               cups_mode_t mode);
Arguments 
ArgumentDescription fd The file descriptor to use. mode The mode to use; CUPS_RASTER_READ or CUPS_RASTER_WRITE
. Returns 
A pointer to a raster stream or NULL if there was an
 error.
Description 
cupsRasterOpen() opens a raster stream for reading or
 writing.
Example 
#include <cups/raster.h>
#cups_raster_tcups_raster_t  *ras;
...
ras = cupsRasterOpen(0, CUPS_RASTER_READ);
See Also 
 #cupsRasterClosecupsRasterClose() , #cupsRasterReadHeadercupsRasterReadHeader() , #cupsRasterReadPixelscupsRasterReadPixels() , #cupsRasterWriteHeadercupsRasterWriteHeader() , #cupsRasterWritePixelscupsRasterWritePixels() 
cupsRasterReadHeader() 
Usage 
unsigned
cupsRasterReadHeader(cups_raster_t      *ras,
                     cups_page_header_t *header);
Arguments 
ArgumentDescription ras The raster stream to read from. header A pointer to a page header structure to read
 into.
Returns 
1 on success, 0 on EOF or error.
Description 
cupsRasterReadHeader() reads a page header from the
 specified raster stream.
Example 
#include <cups/raster.h>
int                  line;
#cups_raster_tcups_raster_t         *ras;
#cups_raster_header_tcups_raster_header_t  header;
unsigned char        pixels[8192];
...
while (cupsRasterReadHeader(ras, &header))
{
  ...
  for (line = 0; line < header.cupsHeight; line ++)
  {
    cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine);
    ...
  }
}
See Also 
 #cupsRasterClosecupsRasterClose() , #cupsRasterOpencupsRasterOpen() , #cupsRasterReadPixelscupsRasterReadPixels()
, #cupsRasterWriteHeadercupsRasterWriteHeader()
, #cupsRasterWritePixelscupsRasterWritePixels()
cupsRasterReadPixels() 
Usage 
unsigned
cupsRasterReadPixels(cups_raster_t *ras,
                     unsigned char *pixels,
		     unsigned      length);
Arguments 
ArgumentDescription ras The raster stream to read from. pixels The pointer to a pixel buffer. length The number of bytes of pixel data to read. Returns 
The number of bytes read or 0 on EOF or error.
Description 
cupsRasterReadPixels() reads pixel data from the
 specified raster stream.
Example 
#include <cups/raster.h>
int                  line;
#cups_raster_tcups_raster_t         *ras;
#cups_raster_header_tcups_raster_header_t  header;
unsigned char        pixels[8192];
...
while (cupsRasterReadHeader(ras, &header))
{
  ...
  for (line = 0; line < header.cupsHeight; line ++)
  {
    cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine);
    ...
  }
}
See Also 
 #cupsRasterClosecupsRasterClose() , #cupsRasterOpencupsRasterOpen() , #cupsRasterReadHeadercupsRasterReadHeader()
, #cupsRasterWriteHeadercupsRasterWriteHeader()
, #cupsRasterWritePixelscupsRasterWritePixels()
cupsRasterWriteHeader() 
Usage 
unsigned
cupsRasterWriteHeader(cups_raster_t      *ras,
                      cups_page_header_t *header);
Arguments 
ArgumentDescription ras The raster stream to write to. header A pointer to the page header to write. Returns 
1 on success, 0 on error.
Description 
cupsRasterWriteHeader() writes the specified page header
 to a raster stream.
Example 
#include <cups/raster.h>
int                  line;
#cups_raster_tcups_raster_t         *ras;
#cups_raster_header_tcups_raster_header_t  header;
unsigned char        pixels[8192];
...
cupsRasterWriteHeader(ras, &header);
for (line = 0; line < header.cupsHeight; line ++)
{
  ...
  cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine);
}
See Also 
 #cupsRasterClosecupsRasterClose() , #cupsRasterOpencupsRasterOpen() , #cupsRasterReadHeadercupsRasterReadHeader()
, #cupsRasterReadPixelscupsRasterReadPixels()
, #cupsRasterWritePixelscupsRasterWritePixels()
cupsRasterWritePixels() 
Usage 
unsigned
cupsRasterWritePixels(cups_raster_t *ras,
                      unsigned char *pixels,
		      unsigned      length);
Arguments 
ArgumentDescription ras The raster stream to write to. pixels The pixel data to write. length The number of bytes to write. Returns 
The number of bytes written.
Description 
cupsRasterWritePixels() writes the specified pixel data
 to a raster stream.
Example 
#include <cups/raster.h>
int                  line;
#cups_raster_tcups_raster_t         *ras;
#cups_raster_header_tcups_raster_header_t  header;
unsigned char        pixels[8192];
...
cupsRasterWriteHeader(ras, &header);
for (line = 0; line < header.cupsHeight; line ++)
{
  ...
  cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine);
}
See Also 
 #cupsRasterClosecupsRasterClose() , #cupsRasterOpencupsRasterOpen() , #cupsRasterReadHeadercupsRasterReadHeader()
, #cupsRasterReadPixelscupsRasterReadPixels()
, #cupsRasterWriteHeadercupsRasterWriteHeader()
cupsServer() 
Usage 
const char *
cupsServer(void);
Returns 
A pointer to the default server name.
Description 
cupsServer() returns a pointer to the default server
 name. The server name is stored in a static location and will be
 overwritten with every call to 
cupsServer().
The default server is determined from the following locations:
The CUPS_SERVER environment variable,The ServerName directive in the client.conf file,
The default host, "localhost". Example 
#include <cups/cups.h>
const char *server;
server = cupsServer();
See Also 
 #cupsGetPasswordcupsGetPassword() , #cupsSetPasswordCBcupsSetPasswordCB() , #cupsSetServercupsSetServer()
, #cupsSetUsercupsSetUser() , #cupsUsercupsUser() 
cupsSetDests() 
Usage 
void
cupsSetDests(int         num_dests,
             cups_dest_t *dests);
Arguments 
ArgumentDescription num_dests Number of destinations. dests Array of destinations. Description 
cupsSetDests() saves the destination array to disk. If
 the current UID is 0, the destinations are saved in the
 /etc/cups/lpoptions
 file, otherwise they are saved in the ~/.lpoptions
 file. This function is typically used to save the
 default options and instances that are set by the user.
Example 
#include <cups/cups.h>
int         num_dests;
#cups_dest_tcups_dest_t  *dests;
...
cupsSetDests(num_dests, dests);
See Also 
 #cupsGetDestscupsGetDests() 
cupsSetEncryption() 
Usage 
void
cupsSetEncryption(http_encryption_t encryption);
Arguments 
ArgumentDescription encryption The type of encryption to use. Description 
cupsSetEncryption() sets the default type of encryption
 to use when connecting with the print server.
Example 
#include <cups/cups.h>
cupsSetEncryption(HTTP_ENCRYPT_REQUIRED);
See Also 
 #cupsEncryptioncupsEncryption() 
cupsSetPasswordCB() 
Usage 
void
cupsSetPasswordCB(const char *(*cb)(const char *prompt));
Arguments 
ArgumentDescription cb The password callback function. Description 
cupsSetPasswordCB() sets the callback function to use
 when asking the user for a password. The callback function must accept
 a single character string pointer (the prompt string) and return 
NULL
 if the user did not enter a password string or a pointer to
 the password string otherwise.
Example 
#include <cups/cups.h>
const char *
my_password_cb(const char *prompt)
{
  return (getpass(prompt));
}
...
char *password;
...
cupsSetPasswordCB(my_password_cb);
password = cupsGetPassword("Please enter a password:");
See Also 
 #cupsDoAuthenticationcupsDoAuthentication() , 
#cupsServercupsServer() , #cupsSetServercupsSetServer() , #cupsSetUsercupsSetUser()
, #cupsUsercupsUser() 
cupsSetServer() 
Usage 
void
cupsSetServer(const char *server);
Arguments 
ArgumentDescription server The default server to use. Description 
cupsSetServer() sets the default server to use for the
 CUPS API. If the 
server argument is NULL, the
 default server is used.
Example 
#include <cups/cups.h>
cupsSetServer("foo.bar.com");
See Also 
 #cupsServercupsServer() , #cupsSetPasswordCBcupsSetPasswordCB() , #cupsSetUsercupsSetUser()
, #cupsUsercupsUser() 
cupsSetUser() 
Usage 
void
cupsSetUser(const char *user);
Arguments 
ArgumentDescription user The user name string to use. Description 
cupsSetUser() sets the default user name for
 authentication. If the 
user argument is NULL then the current login user is used.
Example 
#include <cups/cups.h>
...
cupsSetUser("root");
See Also 
 #cupsDoAuthenticationcupsDoAuthentication() , 
#cupsServercupsServer() , #cupsSetPasswordCBcupsSetPasswordCB() , #cupsSetServercupsSetServer()
, #cupsUsercupsUser() 
cupsTempFd() 
Usage 
int
cupsTempFd(char *filename,
           int  length);
Arguments 
ArgumentDescription filename The character string to hold the temporary
 filename.
length The size of the filename string in bytes. Returns 
A file descriptor open for reading and writing.
Description 
cupsTempFd() create a temporary filename in the /var/tmp
 directory or the directory specified by the TMPDIR environment variable.
Example 
#include <cups/cups.h>
int  fd;
char filename[256];
fd = cupsTempFd(filename, sizeof(filename));
See Also 
 #cupsTempFilecupsTempFile() 
cupsTempFile() 
Usage 
char *
cupsTempFile(char *filename,
             int  length);
Arguments 
ArgumentDescription filename The character string to hold the temporary
 filename.
length The size of the filename string in bytes. Returns 
A pointer to filename.
Description 
cupsTempFile() creates a temporary filename in the /var/tmp
 directory or the directory specified by the TMPDIR environment variable.
Example 
#include <cups/cups.h>
char filename[256];
cupsTempFile(filename, sizeof(filename));
See Also 
 #cupsTempFdcupsTempFd() 
cupsUser() 
Usage 
const char *
cupsUser(void);
Returns 
A pointer to the current username or NULL if the user ID
 is undefined.
Description 
cupsUser() returns the name associated with the current
 user ID as reported by the 
getuid() system call.
Example 
#include <cups/cups.h>
const char *user;
user = cupsUser();
See Also 
 #cupsDoAuthenticationcupsDoAuthentication() , 
#cupsGetPasswordcupsGetPassword() , #cupsServercupsServer() , #cupsSetServercupsSetServer()
, #cupsSetUsercupsSetUser() 
httpBlocking() 
Usage 
void
httpBlocking(http_t *http,
             int    blocking)
Arguments 
ArgumentDescription http The HTTP connection blocking 0 if the connection should be non-blocking, 1
 if it should be blocking
Description 
The httpBlocking() function sets the blocking mode for
 the HTTP connection. By default HTTP connections will block (stop) the
 client program until data is available or can be sent to the server.
Example 
#include <cups/http.h>
http_t *http;
http = httpConnect("server", port);
httpBlocking(http, 0);
See Also 
 
#httpCheckhttpCheck() , #httpConnecthttpConnect() httpCheck() 
Usage 
int
httpCheck(http_t *http);
Arguments 
ArgumentDescription http The HTTP connection Returns 
0 if there is no data pending, 1 otherwise.
Description 
The httpCheck() function checks to see if there is any
 data pending on an HTTP connection.
Example 
#include <cups/http.h>
http_t *http;
if (httpCheck(http))
{
  ... do something ...
}
See Also 
 
#httpBlockinghttpBlocking() , #httpConnecthttpConnect() , #httpGetshttpGets() , #httpReadhttpRead() httpClearFields() 
Usage 
void
httpClearFields(http_t *http)
Arguments 
ArgumentDescription http The HTTP connection Description 
The httpClearFields() function clears all HTTP request
 fields for the HTTP connection.
Example 
#include <cups/http.h>
http_t *http;
httpClearFields(http);
See Also 
 
#httpConnecthttpConnect() , #httpGetFieldhttpGetField() , #httpSetFieldhttpSetField()
httpClose() 
Usage 
void
httpClose(http_t *http);
Arguments 
ArgumentDescription http The HTTP connection Description 
The httpClose() function closes an active HTTP
 connection.
Example 
#include <cups/http.h>
http_t *http;
httpClose(http);
See Also 
 
#httpConnecthttpConnect() httpConnect() 
Usage 
http_t *
httpConnect(const char *hostname,
            int        port);
Arguments 
ArgumentDescription hostname The name or IP address of the server to connect
 to
port The port number to use Returns 
A pointer to a HTTP connection structure or NULL if the connection
 could not be made.
Description 
The httpConnect() function opens a HTTP connection to
 the specified server and port.
Example 
#include <cups/http.h>
#http_thttp_t  *http;
http = httpConnect(cupsServer(), ippPort());
See Also 
 
#httpClosehttpClose() , #httpConnectEncrypthttpConnectEncrypt() , #httpGethttpGet()
, #httpGetshttpGets() , #httpPosthttpPost() , #httpReadhttpRead()
, #httpWritehttpWrite() httpConnectEncrypt() 
Usage 
http_t *
httpConnectEncrypt(const char        *hostname,
                   int               port,
                   http_encryption_t encryption);
Arguments 
ArgumentDescription hostname The name or IP address of the server to connect
 to
port The port number to use encryption The level of encryption to use Returns 
A pointer to a HTTP connection structure or NULL if the connection
 could not be made.
Description 
The httpConnectEncrypt() function opens a HTTP
 connection to the specified server, port, and encryption.
Example 
#include <cups/http.h>
#http_thttp_t  *http;
http = httpConnectEncrypt(cupsServer(), ippPort(), cupsEncryption());
See Also 
 
#httpClosehttpClose() , #httpConnecthttpConnect() , #httpGethttpGet() , #httpGetshttpGets() , #httpPosthttpPost() , #httpReadhttpRead() , 
#httpWritehttpWrite() httpDecode64() 
Usage 
char *
httpDecode64(char       *out,
             const char *in);
Arguments 
ArgumentDescription out The output string in The input string Returns 
A pointer to the decoded string.
Description 
The httpDecode64() function decodes a base-64 encoded
 string to the original string.
Example 
#include <cups/http.h>
char encoded_string[255];
char original_string[255];
httpDecode64(original_string, encoded_string);
See Also 
 
#httpEncode64httpEncode64() httpDelete() 
Usage 
int
httpDelete(http_t     *http,
           const char *uri);
Arguments 
ArgumentDescription http The HTTP connection uri The URI to delete Returns 
0 on success, non-zero on failure.
Description 
The httpDelete() function sends a HTTP DELETE request to
 the server.
Example 
#include <cups/http.h>
http_t *http;
httpDelete(http, "/some/uri");
See Also 
 
#httpConnecthttpConnect() , #httpSetFieldhttpSetField() , #httpUpdatehttpUpdate()
httpEncode64() 
Usage 
char *
httpEncode64(char       *out,
             const char *in);
Arguments 
ArgumentDescription out The output string in The input string Returns 
A pointer to the encoded string.
Description 
The httpEncode64() function decodes a base-64 encoded
 string to the original string.
Example 
#include <cups/http.h>
char encoded_string[255];
char original_string[255];
httpEncode64(encoded_string, original_string);
See Also 
 
#httpDecode64httpDecode64() httpEncryption() 
Usage 
int
httpEncryption(http_t            *http,
               http_encryption_t encryption);
Arguments 
ArgumentDescription http The HTTP connection. encryption The desired level of encryption. Returns 
0 on success, -1 on error.
Description 
httpEncryption() sets the encryption level for the HTTP
 connection.
Example 
#include <cups/http.h>
#http_thttp_t  *http;
...
httpEncryption(http, HTTP_ENCRYPT_REQUIRED);
See Also 
 #httpConnectEncrypthttpConnectEncrypt() 
httpError() 
Usage 
int
httpError(http_t *http);
Arguments 
ArgumentDescription http The HTTP connection Returns 
The last error that occurred or 0 if no error has occurred.
Description 
The httpError() function returns the last error that
 occurred on the HTTP connection.
Example 
#include <cups/http.h>
http_t *http;
if (httpError(http))
{
  ... show an error message ...
}
See Also 
 
#httpConnecthttpConnect() httpFlush() 
Usage 
void
httpFlush(http_t *http);
Arguments 
ArgumentDescription http The HTTP connection Description 
The httpFlush() function flushes any remaining data left
 from a GET or POST operation.
Example 
#include <cups/http.h>
http_t *http;
httpFlush(http);
See Also 
 
#httpConnecthttpConnect() ,
httpGet() 
Usage 
int
httpGet(http_t     *http,
        const char *uri);
Arguments 
ArgumentDescription http The HTTP connection uri The URI to get Returns 
0 on success, non-zero on failure.
Description 
The httpGet() function sends a HTTP GET request to the
 server.
Example 
#include <cups/http.h>
#http_thttp_t  *http;
httpGet(http, "/some/uri");
See Also 
 
#httpConnecthttpConnect() , #httpSetFieldhttpSetField() , #httpUpdatehttpUpdate()
httpGets() 
Usage 
char *
httpGets(char   *line,
         int    length,
         http_t *http)
Arguments 
ArgumentDescription line The string to fill with a line from the HTTP
 connection
length The maximum length of the string http The HTTP connection Returns 
A pointer to the string or NULL if no line could be retrieved.
Description 
The httpGets() function is used to read a request line
 from the HTTP connection. It is not normally used by a client program.
Example 
#include <cups/http.h>
#http_thttp_t  *http;
char   line[1024];
if (httpGets(line, sizeof(line), http))
{
  ... process the line ...
}
See Also 
 
#httpConnecthttpConnect() , #httpUpdatehttpUpdate() httpGetDateString() 
Usage 
const char *
httpGetDateString(time_t time)
Arguments 
ArgumentDescription time The UNIX date/time value Returns 
A pointer to a static string containing the HTTP date/time string for
 the specified UNIX time value.
Description 
The httpGetDateString() function generates a date/time
 string suitable for HTTP requests from a UNIX time value.
Example 
#include <cups/http.h>
puts(httpGetDateString(time(NULL)));
See Also 
 
#httpGetDateTimehttpGetDateTime() httpGetDateTime() 
Usage 
time_t
httpGetDateTime(const char *date)
Arguments 
ArgumentDescription date The HTTP date/time string Returns 
A UNIX time value.
Description 
The httpGetDateTime() function converts a HTTP date/time
 string to a UNIX time value.
Example 
#include <cups/http.h>
printf("%d\n", httpGetDateTime("Fri, 30 June 2000 12:34:56 GMT"));
See Also 
 
#httpGetDateStringhttpGetDateString() httpGetField() 
Usage 
const char *
httpGetField(http_t       *http,
             http_field_t field);
Arguments 
ArgumentDescription http The HTTP connection field The HTTP field Returns 
A pointer to the field value string.
Description 
The httpGetField() function returns the current value
 for the specified HTTP field.
Example 
#include <cups/http.h>
#http_thttp_t  *http;
httpGet(http, "/some/uri");
while (httpUpdate(http) == HTTP_CONTINUE);
puts(httpGetField(http, HTTP_FIELD_CONTENT_TYPE));
See Also 
 
#httpConnecthttpConnect() , #httpGetSubFieldhttpGetSubField() , #httpSetFieldhttpSetField()
httpGetHostByName() 
Usage 
struct hostent	*
httpGetHostByName(const char *name);
Arguments 
ArgumentDescription name Name or IP address to lookup. Returns 
NULL if the host could not be found or a pointer to a host entry
 containing one or more addresses.
Description 
httpGetHostByName() is a portable wrapper around the gethostbyname()
 function which handles both hostnames and IP
 addresses.
Example 
#include <cups/http.h>
struct hostent *hostaddr;
hostaddr = httpGetHostByName("foo.bar.com");
httpGetLength() 
Usage 
int
httpGetLength(http_t *http);
Arguments 
ArgumentDescription http The HTTP connection. Returns 
The content length of the response or MAX_INT if chunking is used.
Description 
httpGetLength() returns the content length of a
 response.
Example 
#include <cups/http.h>
#http_thttp_t  *http;
...
printf("The length of the response is %d bytes.\n", httpGetLength(http));
See Also 
 #httpGethttpGet() , #httpPosthttpPost()
httpGetSubField() 
Usage 
const char *
httpGetSubField(http_t       *http,
                http_field_t field,
		const char   *name,
		char         *value);
Arguments 
ArgumentDescription http The HTTP connection. field The HTTP field. name The name of the subfield. value The string to hold the subfield value. Returns 
A pointer to the subfield value string or NULL if it does not exist.
Description 
The httpGetSubField() function returns a subfield value
 from the specified HTTP field. The destination string buffer must be at
 least 
HTTP_MAX_VALUE bytes in length.
Example 
#include <cups/http.h>
#http_thttp_t  *http;
char   value[HTTP_MAX_VALUE];
httpGet(http, "/some/uri");
while (httpUpdate(http) == HTTP_CONTINUE);
puts(httpGetSubField(http, HTTP_FIELD_CONTENT_TYPE, "charset", value));
See Also 
 
#httpConnecthttpConnect() , #httpGetFieldhttpGetField() , #httpSetFieldhttpSetField()
httpHead() 
Usage 
int
httpHead(http_t     *http,
         const char *uri);
Arguments 
ArgumentDescription http The HTTP connection uri The URI to head Returns 
0 on success, non-zero on failure.
Description 
The httpHead() function sends a HTTP HEAD request to the
 server.
Example 
#include <cups/http.h>
http_t *http;
httpHead(http, "/some/uri");
See Also 
 
#httpConnecthttpConnect() , #httpSetFieldhttpSetField() , #httpUpdatehttpUpdate()
httpInitialize() 
Usage 
void httpInitialize(void);
Description 
The httpInitialize() function initializes the networking
 code as needed by the underlying platform. It is called automatically
 by the 
httpConnect() function.
Example 
#include <cups/http.h>
httpInitialize();
See Also 
 
#httpConnecthttpConnect() httpMD5() 
Usage 
char *
httpMD5(const char *username,
        const char *realm,
        const char *passwd,
        char       md5[33]);
Arguments 
ArgumentDescription username The authenticating user name. realm The authenticating realm name. passwd The authenticating password. md5 The MD5 sum string. Returns 
A pointer to the MD5 sum string.
Description 
httpMD5() computes the MD5 hash of the username, realm,
 and password as required by the HTTP Digest specification.
Example 
#include <cups/http.h>
char md5[33];
...
httpMD5("user", "realm", "password", md5);
See Also 
 #httpMD5FinalhttpMD5Final() , #httpMD5StringhttpMD5String() 
httpMD5Final() 
Usage 
char *
httpMD5Final(const char *nonce,
             const char *method,
             const char *resource,
             char       md5[33]);
Arguments 
ArgumentDescription nonce The server nonce value. method The HTTP method (GET, POST, etc.) resource The resource path. md5 The MD5 sum string. Returns 
The MD5 sum string.
Description 
httpMD5Final() appends the nonce, method, and resource
 to the specified MD5 sum.
Example 
#include <cups/http.h>
char md5[33];
...
httpMD5Final("nonce", "GET", "/jobs", md5);
See Also 
 #httpMD5httpMD5() , #httpMD5StringhttpMD5String() 
httpMD5String() 
Usage 
char *
httpMD5String(const md5_byte_t *sum,
              char             md5[33]);
Arguments 
ArgumentDescription sum The raw MD5 sum data. md5 The MD5 sum string. Returns 
The MD5 sum string.
Description 
httpMD5String() converts the raw MD5 sum value to a
 string.
Example 
#include <cups/http.h>
md5_byte_t sum[16];
char       md5[33];
...
httpMD5String(sum, md5);
See Also 
 #httpMD5httpMD5() , #httpMD5FinalhttpMD5Final() 
httpOptions() 
Usage 
int
httpOptions(http_t     *http,
            const char *uri);
Arguments 
ArgumentDescription http The HTTP connection uri The URI to check for options Returns 
0 on success, non-zero on failure.
Description 
The httpOptions() function sends a HTTP OPTIONS request
 to the server.
Example 
#include <cups/http.h>
http_t *http;
httpOptions(http, "/some/uri");
See Also 
 
#httpConnecthttpConnect() , #httpSetFieldhttpSetField() , #httpUpdatehttpUpdate()
httpPost() 
Usage 
int
httpPost(http_t     *http,
         const char *uri);
Arguments 
ArgumentDescription http The HTTP connection uri The URI to post to Returns 
0 on success, non-zero on failure.
Description 
The httpPost() function sends a HTTP POST request to the
 server.
Example 
#include <cups/http.h>
http_t *http;
httpPost(http, "/some/uri");
See Also 
 
#httpConnecthttpConnect() , #httpSetFieldhttpSetField() , #httpUpdatehttpUpdate()
httpPrintf() 
Usage 
int
httpPrintf(http_t     *http,
           const char *format,
           ...);
Arguments 
ArgumentDescription http The HTTP connection format A printf-style format string Returns 
The number of bytes written.
Description 
The httpPrintf() function sends a formatted string to
 the HTTP connection. It is normally only used by the CUPS API and
 scheduler.
Example 
#include <cups/http.h>
http_t *http;
httpPrintf(http, "GET / HTTP/1.1 \r\n");
See Also 
 
#httpConnecthttpConnect() httpPut() 
Usage 
int
httpPut(http_t     *http,
        const char *uri);
Arguments 
ArgumentDescription http The HTTP connection uri The URI to put Returns 
0 on success, non-zero on failure.
Description 
The httpPut() function sends a HTTP PUT request to the
 server.
Example 
#include <cups/http.h>
http_t *http;
httpDelete(http, "/some/uri");
See Also 
 
#httpConnecthttpConnect() , #httpSetFieldhttpSetField() , #httpUpdatehttpUpdate()
httpRead() 
Usage 
int
httpRead(http_t *http,
         char   *buffer,
         int    length);
Arguments 
ArgumentDescription http The HTTP connection buffer The buffer to read into length The number of bytes to read Returns 
The number of bytes read or -1 on error.
Description 
The httpRead() function reads data from the HTTP
 connection, possibly the result of a GET or POST request.
Example 
#include <cups/http.h>
http_t *http;
char buffer[1024];
int  bytes;
httpGet(http, "/");
while (httpUpdate(http) != HTTP_CONTINUE);
while ((bytes = httpRead(http, buffer, sizeof(buffer) - 1)) > 0)
{
  buffer[bytes] = '\0';
  fputs(buffer, stdout);
}
See Also 
 
#httpConnecthttpConnect() , #httpWritehttpWrite() httpReconnect() 
Usage 
int
httpReconnect(http_t *http);
Arguments 
ArgumentDescription http The HTTP connection Returns 
0 on success, non-zero on failure.
Description 
The httpReconnect() function reconnects to the HTTP
 server. This is usually done automatically if the HTTP functions detect
 that the server connection has terminated.
Example 
#include <cups/http.h>
http_t *http;
httpReconnect(http);
See Also 
 
#httpConnecthttpConnect() httpSeparate() 
Usage 
void
httpSeparate(const char *uri,
             char       *method,
             char       *username,
             char       *host,
             int        *port,
             char       *resource);
Arguments 
ArgumentDescription uri The URI to separate method The method (scheme) of the URI username The username (and password) portion of the URI,
 if any
host The hostname portion of the URI, if any port The port number for the URI, either as specified or
 as default for the method/scheme
resource The resource string, usually a filename on the
 server
Description 
The httpSeparate() function separates the specified URI
 into its component parts. The method, username, hostname, and resource
 strings should be at least 
HTTP_MAX_URI characters long to
 avoid potential buffer overflow problems.
Example 
char uri[HTTP_MAX_URI];
char method[HTTP_MAX_URI];
char username[HTTP_MAX_URI];
char host[HTTP_MAX_URI];
char resource[HTTP_MAX_URI];
int  port;
...
httpSeparate(uri, method, username, host, &port, resource);
See Also 
 
#httpConnecthttpConnect() httpSetField() 
Usage 
void
httpSetField(http_t       *http,
             http_field_t field,
             const char   *value);
Arguments 
ArgumentDescription http The HTTP connection field The HTTP field value The string value for the field Description 
The httpSetField() function sets the current value for
 the specified HTTP field.
Example 
#include <cups/http.h>
http_t *http;
httpSetField(http, HTTP_FIELD_AUTHORIZATION, "Basic dfdr34453454325"));
httpGet(http, "/some/uri");
while (httpUpdate(http) == HTTP_CONTINUE);
See Also 
 
#httpConnecthttpConnect() , #httpGetFieldhttpGetField() httpStatus() 
Usage 
const char *
httpStatus(http_status_t status);
Arguments 
ArgumentDescription status The HTTP status code from the server. Returns 
The standard HTTP status text associated with the status code.
Description 
httpStatus() returns the standard HTTP status text
 associated with the status code.
Example 
#include <cups/http.h>
#http_thttp_t  *http;
...
puts(httpStatus(http->status));
httpTrace() 
Usage 
int
httpTrace(http_t     *http,
          const char *uri);
Arguments 
ArgumentDescription http The HTTP connection uri The URI to trace Returns 
0 on success, non-zero on failure.
Description 
The httpTrace() function sends a HTTP TRACE request to
 the server.
Example 
#include <cups/http.h>
http_t *http;
httpTrace(http, "/some/uri");
See Also 
 
#httpConnecthttpConnect() , #httpSetFieldhttpSetField() , #httpUpdatehttpUpdate()
httpUpdate() 
Usage 
http_status_t
httpUpdate(http_t *http);
Arguments 
ArgumentDescription http The HTTP connection Returns 
The HTTP status of the current request.
Description 
The httpUpdate() function updates the current request
 status. It is used after any DELETE, GET, HEAD, OPTIONS, POST, PUT, or
 TRACE request to finalize the HTTP request and retrieve the request
 status.
Since proxies and the current blocking mode can cause the request to
 take longer, programs should continue calling 
httpUpdate() until the return status is not the constant value 
HTTP_CONTINUE.
Example 
#include <cups/http.h>
http_t *http;
http_status_t status;
httpGet(http, "/some/uri");
while ((status = httpUpdate(http)) == HTTP_CONTINUE);
printf("Request status is %d\n", status);
See Also 
 
#httpConnecthttpConnect() , #httpDeletehttpDelete() , #httpGethttpGet() , 
#httpHeadhttpHead() , #httpOptionshttpOptions() , #httpPosthttpPost() , #httpPuthttpPut() , #httpTracehttpTrace() httpWrite() 
Usage 
int
httpWrite(http_t *http,
          char   *buffer,
          int    length);
Arguments 
ArgumentDescription http The HTTP connection buffer The buffer to read into length The number of bytes to read Returns 
The number of bytes read or -1 on error.
Description 
The httpWrite() function reads data from the HTTP
 connection, possibly the result of a GET or POST request.
Example 
#include <cups/http.h>
http_t *http;
FILE *fp;
char buffer[1024];
int  bytes;
httpPost(http, "/");
while ((bytes = fread(buffer, 1, sizeof(buffer), fp)) > 0)
  httpWrite(http, buffer, bytes);
while (httpUpdate(http) != HTTP_CONTINUE);
while ((bytes = httpRead(http, buffer, sizeof(buffer) - 1)) > 0)
{
  buffer[bytes] = '\0';
  fputs(buffer, stdout);
}
See Also 
 
#httpConnecthttpConnect() , #httpReadhttpRead() ippAddBoolean() 
Usage 
ipp_attribute_t *
ippAddBoolean(ipp_t      *ipp,
              ipp_tag_t  group,
              const char *name,
	      char       value);
Arguments 
ArgumentDescription ipp The IPP request group The IPP group name The name of attribute value The boolean value Returns 
A pointer to the new attribute or NULL if the attribute could not be
 created.
Description 
The ippAddBoolean() function adds a single boolean
 attribute value to the specified IPP request.
Example 
#include <cups/ipp.h>
ipp_t *ipp;
ippAddBoolean(ipp, IPP_TAG_OPERATION, "my-jobs", 1);
See Also 
 
#ippAddBooleansippAddBooleans() , #ippAddDateippAddDate() , #ippAddIntegerippAddInteger()
, #ippAddIntegersippAddIntegers()
, #ippAddRangeippAddRange() , #ippAddRangesippAddRanges() , #ippAddResolutionippAddResolution() , #ippAddResolutionsippAddResolutions()
, #ippAddSeparatorippAddSeparator()
, #ippAddStringippAddString()
, #ippAddStringsippAddStrings()
ippAddBooleans() 
Usage 
ipp_attribute_t *
ippAddBooleans(ipp_t      *ipp,
               ipp_tag_t  group,
               const char *name,
               int        num_values,
               const char *values);
Arguments 
ArgumentDescription ipp The IPP request group The IPP group name The name of attribute num_values The number of values values The boolean values Returns 
A pointer to the new attribute or NULL if the attribute could not be
 created.
Description 
The ippAddBooleans() function adds one or more boolean
 attribute values to the specified IPP request. If the 
values pointer is 
NULL then an array of num_values false values is created.
Example 
#include <cups/ipp.h>
ipp_t *ipp;
char values[10];
ippAddBooleans(ipp, IPP_TAG_OPERATION, "some-attribute", 10, values);
See Also 
 
#ippAddBooleanippAddBoolean() , #ippAddDateippAddDate() , #ippAddIntegerippAddInteger()
, #ippAddIntegersippAddIntegers()
, #ippAddRangeippAddRange() , #ippAddRangesippAddRanges() , #ippAddResolutionippAddResolution() , #ippAddResolutionsippAddResolutions()
, #ippAddSeparatorippAddSeparator()
, #ippAddStringippAddString()
, #ippAddStringsippAddStrings()
ippAddDate() 
Usage 
ipp_attribute_t *
ippAddDate(ipp_t       *ipp,
           ipp_tag_t   group,
           const char  *name,
           ipp_uchar_t *value);
Arguments 
ArgumentDescription ipp The IPP request group The IPP group name The name of attribute value The date value Returns 
A pointer to the new attribute or NULL if the attribute could not be
 created.
Description 
The ippAddDate() function adds a single date-time
 attribute value to the specified IPP request.
Example 
#include <cups/ipp.h>
ipp_t *ipp;
ippAddDate(ipp, IPP_TAG_OPERATION, "some-attribute", 
           ippTimeToDate(time(NULL));
See Also 
 
#ippAddBooleanippAddBoolean() , #ippAddBooleansippAddBooleans() , #ippAddIntegerippAddInteger()
, #ippAddIntegersippAddIntegers()
, #ippAddRangeippAddRange() , #ippAddRangesippAddRanges() , #ippAddResolutionippAddResolution() , #ippAddResolutionsippAddResolutions()
, #ippAddSeparatorippAddSeparator()
, #ippAddStringippAddString()
, #ippAddStringsippAddStrings()
, #ippTimeToDateippTimeToDate()
ippAddInteger() 
Usage 
ipp_attribute_t *
ippAddInteger(ipp_t      *ipp,
              ipp_tag_t  group,
              ipp_tag_t  tag,
              const char *name,
              int        value);
Arguments 
ArgumentDescription ipp The IPP request group The IPP group tag The type of integer value (IPP_TAG_INTEGER or
 IPP_TAG_ENUM)
name The name of attribute value The integer value Returns 
A pointer to the new attribute or NULL if the attribute could not be
 created.
Description 
The ippAddInteger() function adds a single integer
 attribute value to the specified IPP request.
Example 
#include <cups/ipp.h>
ipp_t *ipp;
ippAddInteger(ipp, IPP_TAG_OPERATION, "limit", 100);
See Also 
 
#ippAddBooleanippAddBoolean() , #ippAddBooleansippAddBooleans() , #ippAddDateippAddDate()
, #ippAddIntegersippAddIntegers()
, #ippAddRangeippAddRange() , #ippAddRangesippAddRanges() , #ippAddResolutionippAddResolution() , #ippAddResolutionsippAddResolutions()
, #ippAddSeparatorippAddSeparator()
, #ippAddStringippAddString()
, #ippAddStringsippAddStrings()
ippAddIntegers() 
Usage 
ipp_attribute_t *
ippAddIntegers(ipp_t      *ipp,
               ipp_tag_t  group,
               ipp_tag_t  tag,
               const char *name,
               int        num_values,
               const int  *values);
Arguments 
ArgumentDescription ipp The IPP request group The IPP group tag The type of integer value (IPP_TAG_INTEGER or
 IPP_TAG_ENUM)
name The name of attribute num_values The number of values values The integer values Returns 
A pointer to the new attribute or NULL if the attribute could not be
 created.
Description 
The ippAddIntegers() function adds one or more integer
 attribute values to the specified IPP request. If the 
values pointer is 
NULL then an array of num_values 0
 values is created.
Example 
#include <cups/ipp.h>
ipp_t *ipp;
int values[100];
ippAddIntegers(ipp, IPP_TAG_OPERATION, "some-attribute", 100, values);
See Also 
 
#ippAddBooleanippAddBoolean() , #ippAddBooleansippAddBooleans() , #ippAddDateippAddDate()
, #ippAddIntegerippAddInteger() , #ippAddRangeippAddRange() , #ippAddRangesippAddRanges() , #ippAddResolutionippAddResolution()
, #ippAddResolutionsippAddResolutions()
, #ippAddSeparatorippAddSeparator()
, #ippAddStringippAddString()
, #ippAddStringsippAddStrings()
ippAddRange() 
Usage 
ipp_attribute_t *
ippAddRange(ipp_t      *ipp,
            ipp_tag_t  group,
            const char *name,
            int        low,
            int        high);
Arguments 
ArgumentDescription ipp The IPP request group The IPP group name The name of attribute low The lower value high The higher value Returns 
A pointer to the new attribute or NULL if the attribute could not be
 created.
Description 
The ippAddRange() function adds a single range attribute
 value to the specified IPP request.
Example 
#include <cups/ipp.h>
ipp_t *ipp;
ippAddRange(ipp, IPP_TAG_OPERATION, "page-ranges", 1, 10);
See Also 
 
#ippAddBooleanippAddBoolean() , #ippAddBooleansippAddBooleans() , #ippAddDateippAddDate()
, #ippAddIntegerippAddInteger() , #ippAddIntegersippAddIntegers() , #ippAddRangesippAddRanges() , #ippAddResolutionippAddResolution()
, #ippAddResolutionsippAddResolutions()
, #ippAddSeparatorippAddSeparator()
, #ippAddStringippAddString()
, #ippAddStringsippAddStrings()
ippAddRanges() 
Usage 
ipp_attribute_t *
ippAddRanges(ipp_t      *ipp,
             ipp_tag_t  group,
             const char *name,
             int        num_values,
             const int  *lows,
             const int  *highs);
Arguments 
ArgumentDescription ipp The IPP request group The IPP group name The name of attribute num_values The number of range values lows The lower values highs The higher values Returns 
A pointer to the new attribute or NULL if the attribute could not be
 created.
Description 
The ippAddRanges() function adds one or more range
 attribute values to the specified IPP request. If the 
values pointer is 
NULL then an array of num_values 0,0 ranges is created.
Example 
#include <cups/ipp.h>
ipp_t *ipp;
int lows[2];
int highs[2];
ippAddRanges(ipp, IPP_TAG_OPERATION, "page-ranges", 2, lows, highs);
See Also 
 
#ippAddBooleanippAddBoolean() , #ippAddBooleansippAddBooleans() , #ippAddDateippAddDate()
, #ippAddIntegerippAddInteger() , #ippAddIntegersippAddIntegers() , #ippAddRangeippAddRange() , #ippAddResolutionippAddResolution()
, #ippAddResolutionsippAddResolutions()
, #ippAddSeparatorippAddSeparator()
, #ippAddStringippAddString()
, #ippAddStringsippAddStrings()
ippAddResolution() 
Usage 
ipp_attribute_t *
ippAddResolution(ipp_t      *ipp,
                 ipp_tag_t  group,
                 const char *name,
                 int        xres,
                 int        yres,
                 ipp_res_t  units);
Arguments 
ArgumentDescription ipp The IPP request group The IPP group name The name of attribute xres The horizontal resolution yres The vertical resolution units The resolution units Returns 
A pointer to the new attribute or NULL if the attribute could not be
 created.
Description 
The ippAddResolution() function adds a single resolution
 attribute value to the specified IPP request.
Example 
#include <cups/ipp.h>
ipp_t *ipp;
ippAddBoolean(ipp, IPP_TAG_OPERATION, "printer-resolution",
              720, 720, IPP_RES_PER_INCH);
See Also 
 
#ippAddBooleanippAddBoolean() , #ippAddBooleansippAddBooleans() , #ippAddDateippAddDate()
, #ippAddIntegerippAddInteger() , #ippAddIntegersippAddIntegers() , #ippAddRangeippAddRange() , #ippAddRangesippAddRanges()
, #ippAddResolutionsippAddResolutions()
, #ippAddSeparatorippAddSeparator()
, #ippAddStringippAddString()
, #ippAddStringsippAddStrings()
ippAddResolutions() 
Usage 
ipp_attribute_t *
ippAddResolutions(ipp_t           *ipp,
                  ipp_tag_t       group,
                  const char      *name,
                  int             num_values,
                  const int       *xres,
                  const int       *yres,
                  const ipp_res_t *units);
Arguments 
ArgumentDescription ipp The IPP request group The IPP group name The name of attribute num_values The number of resolution values xres The horizontal resolutions yres The vertical resolutions units The resolution units Returns 
A pointer to the new attribute or NULL if the attribute could not be
 created.
Description 
The ippAddResolutions() function adds one or more
 resolution attribute values to the specified IPP request. If the 
values
 pointer is NULL then an array of num_values
 0,0 resolutions is created.
Example 
#include <cups/ipp.h>
ipp_t *ipp;
int xres[5];
int yres[5];
ipp_res_t units[5];
ippAddBoolean(ipp, IPP_TAG_OPERATION, "printer-resolutions-supported",
              5, xres, yres, units);
See Also 
 
#ippAddBooleanippAddBoolean() , #ippAddBooleansippAddBooleans() , #ippAddDateippAddDate()
, #ippAddIntegerippAddInteger() , #ippAddIntegersippAddIntegers() , #ippAddRangeippAddRange() , #ippAddRangesippAddRanges()
, #ippAddResolutionippAddResolution()
, #ippAddSeparatorippAddSeparator()
, #ippAddStringippAddString()
, #ippAddStringsippAddStrings()
ippAddSeparator() 
Usage 
ipp_attribute_t *
ippAddSeparator(ipp_t *ipp);
Arguments 
ArgumentDescription ipp The IPP request Returns 
A pointer to the new separator or NULL if the separator could not be
 created.
Description 
The ippAddSeparator() function adds a group separator to
 the specified IPP request.
Example 
#include <cups/ipp.h>
ipp_t *ipp;
ippAddSeparator(ipp);
See Also 
 
#ippAddBooleanippAddBoolean() , #ippAddBooleansippAddBooleans() , #ippAddDateippAddDate()
, #ippAddIntegerippAddInteger() , #ippAddIntegersippAddIntegers() , #ippAddRangeippAddRange() , #ippAddRangesippAddRanges()
, #ippAddResolutionippAddResolution()
, #ippAddResolutionsippAddResolutions()
, #ippAddStringippAddString()
, #ippAddStringsippAddStrings()
ippAddString() 
Usage 
ipp_attribute_t *
ippAddString(ipp_t      *ipp,
             ipp_tag_t  group,
             ipp_tag_t  tag,
             const char *name,
             const char *charset,
             const char *value);
Arguments 
ArgumentDescription ipp The IPP request group The IPP group tag The type of string value name The name of attribute charset The character set for the string value The string value Returns 
A pointer to the new attribute or NULL if the attribute could not be
 created.
Description 
The ippAddString() function adds a single string
 attribute value to the specified IPP request. For 
IPP_TAG_NAMELANG
 and IPP_TAG_TEXTLANG strings, the
 charset value is provided with the string to identify the string
 encoding used. Otherwise the charset value is ignored.
Example 
#include <cups/ipp.h>
ipp_t *ipp;
ippAddString(ipp, IPP_TAG_OPERATION, IPP_TAG_NAME, "job-name",
             NULL, "abc123");
See Also 
 
#ippAddBooleanippAddBoolean() , #ippAddBooleansippAddBooleans() , #ippAddDateippAddDate()
, #ippAddIntegerippAddInteger() , #ippAddIntegersippAddIntegers() , #ippAddRangeippAddRange() , #ippAddRangesippAddRanges()
, #ippAddResolutionippAddResolution()
, #ippAddResolutionsippAddResolutions()
, #ippAddSeparatorippAddSeparator()
, #ippAddStringsippAddStrings()
ippAddStrings() 
Usage 
ipp_attribute_t *
ippAddStrings(ipp_t      *ipp,
              ipp_tag_t  group,
              ipp_tag_t  tag,
              const char *name,
              int        num_values,
              const char *charset,
              const char **values);
Arguments 
ArgumentDescription ipp The IPP request group The IPP group tag The type of string value name The name of attribute num_values The number of strings charset The character set for the strings values The string values Returns 
A pointer to the new attribute or NULL if the attribute could not be
 created.
Description 
The ippAddStrings() function adds one or more string
 attribute values to the specified IPP request. For 
IPP_TAG_NAMELANG
 and IPP_TAG_TEXTLANG strings, the
 charset value is provided with the strings to identify the string
 encoding used. Otherwise the charset value is ignored. If the 
values
 pointer is NULL then an array of num_values
 NULL strings is created.
Example 
#include <cups/ipp.h>
ipp_t *ipp;
char *values[2] = { "one", "two" };
ippAddStrings(ipp, IPP_TAG_OPERATION, IPP_TAG_KEYWORD, "attr-name",
              2, NULL, values);
See Also 
 
#ippAddBooleanippAddBoolean() , #ippAddBooleansippAddBooleans() , #ippAddDateippAddDate()
, #ippAddIntegerippAddInteger() , #ippAddIntegersippAddIntegers() , #ippAddRangeippAddRange() , #ippAddRangesippAddRanges()
, #ippAddResolutionippAddResolution()
, #ippAddResolutionsippAddResolutions()
, #ippAddSeparatorippAddSeparator()
, #ippAddStringippAddString()
ippDateToTime() 
Usage 
time_t
ippDateToTime(const ipp_uchar_t date[11]);
Arguments 
ArgumentDescription date The IPP date-time value Returns 
A UNIX time value.
Description 
The ippDateToTime() function converts an IPP date-time
 value to a UNIX time value.
Example 
#include <cups/ipp.h>
ipp_uchar_t date[11];
printf("UNIX time is %d\n", ippDateToTime(date));
See Also 
 
#ippTimeToDateippTimeToDate() ippDelete() 
Usage 
void
ippDelete(ipp_t *ipp);
Arguments 
ArgumentDescription ipp The IPP request or response Description 
The ippDelete() function deletes all memory used by an
 IPP request or response.
Example 
#include <cups/ipp.h>
ipp_t *ipp;
ippDelete(ipp);
See Also 
 
#ippNewippNew() ippErrorString() 
Usage 
const char *
ippErrorString(ipp_status_t error);
Arguments 
ArgumentDescription error IPP error code. Returns 
The standard text representation of the IPP error code.
Description 
ippErrorString() returns the standard text
 representation of the IPP error code.
Example 
#include <cups/ipp.h>
puts(ippErrorString(IPP_OK));
See Also 
 #cupsLastErrorcupsLastError() 
ippFindAttribute() 
Usage 
ipp_attribute_t *
ippFindAttribute(ipp_t      *ipp,
                 const char *name,
                 ipp_tag_t  tag);
Arguments 
ArgumentDescription ipp The IPP request or response name The name of the attribute tag The required value tag for the attribute or IPP_TAG_ZERO
 for any type of value. Returns 
A pointer to the first occurrence of the requested attribute, or NULL
 if it was not found.
Description 
ippFindAttribute() finds the first occurrence of the
 named attribute. The 
tag parameter restricts the search to
 a specific value type - use 
IPP_TAG_ZERO to find any value
 with the name.
The value tags IPP_TAG_NAME and IPP_TAG_TEXT match the name/text values with or without the language code.
Example 
#ipp_attribute_tipp_attribute_t  *attr;
attr = ippFindAttribute(response, "printer-state-message", IPP_TAG_TEXT);
while (attr != NULL)
{
  puts(attr->values[0].string.text);
  attr = ippFindNextAttribute(response, "printer-state-message", IPP_TAG_TEXT);
}
See Also 
 
#cupsDoFileRequestcupsDoFileRequest() , #cupsDoRequestcupsDoRequest() , #ippDeleteippDelete() , #ippFindNextAttributeippFindNextAttribute() , #ippNewippNew() ippFindNextAttribute() 
Usage 
ipp_attribute_t *
ippFindNextAttribute(ipp_t      *ipp,
                     const char *name,
                     ipp_tag_t  tag);
Arguments 
ArgumentDescription ipp The IPP request or response name The name of the attribute tag The required value tag for the attribute or IPP_TAG_ZERO
 for any type of value. Returns 
A pointer to the next occurrence of the requested attribute, or NULL
 if it was not found.
Description 
ippFindNextAttribute() finds the next occurrence of the
 named attribute. The 
tag parameter restricts the search to
 a specific value type - use 
IPP_TAG_ZERO to find any value
 with the name.
The value tags IPP_TAG_NAME and IPP_TAG_TEXT match the name/text values with or without the language code.
Example 
#ipp_attribute_tipp_attribute_t  *attr;
attr = ippFindAttribute(response, "printer-state-message", IPP_TAG_TEXT);
while (attr != NULL)
{
  puts(attr->values[0].string.text);
  attr = ippFindNextAttribute(response, "printer-state-message", IPP_TAG_TEXT);
}
See Also 
 
#cupsDoFileRequestcupsDoFileRequest() , #cupsDoRequestcupsDoRequest() , #ippDeleteippDelete() , #ippFindNextAttributeippFindNextAttribute() , #ippNewippNew() ippLength() 
Usage 
int
ippLength(ipp_t *ipp);
Arguments 
ArgumentDescription ipp The IPP request or response Returns 
The total encoded length of the IPP request or response in bytes.
Description 
ippLength() returns the length of the IPP request or
 response in bytes.
Example 
printf("The length of the response is %d bytes.\n", ippLength(response));
See Also 
 
#ippDeleteippDelete() , #ippNewippNew()
ippNew() 
Usage 
ipp_t *
ippNew(void);
Returns 
A pointer to a new IPP request or response.
Description 
The ippNew() function creates a new IPP request or
 response.
Example 
#include <cups/ipp.h>
ipp_t *ipp;
ipp = ippNew();
See Also 
 
#ippDeleteippDelete() ippPort() 
Usage 
int
ippPort(void);
Returns 
The default TCP/IP port number for IPP requests.
Description 
The ippPort() function returns the default IPP port
 number for requests.
Example 
#include <cups/http.h>
#include <cups/ipp.h>
http_t *http;
http = httpConnect(cupsServer(), ippPort());
See Also 
 
#cupsServercupsServer() , #ippSetPortippSetPort() ippRead() 
Usage 
ipp_state_t
ippRead(http_t *http,
        ipp_t  *ipp);
Arguments 
ArgumentDescription http The HTTP connection ipp The IPP request or response Returns 
The current read state.
Description 
The ippRead() function reads IPP attributes from the
 specified HTTP connection. Programs should continue calling 
ippRead()
 until IPP_ERROR or IPP_DATA is returned.
Example 
#include <cups/http.h>
#include <cups/ipp.h>
http_t *http;
ipp_t *ipp;
ipp_state_t status;
ipp = ippNew();
while ((status = ippRead(http, ipp)) != IPP_ERROR)
  if (status == IPP_DATA)
    break;
if (status == IPP_DATA)
{
  ... read additional non-IPP data using httpRead() ...
}
See Also 
 
#ippWriteippWrite() ippSetPort() 
Usage 
void
ippSetPort(int port);
Arguments 
ArgumentDescription port The port number to use Description 
The ippSetPort() function sets the default IPP port
 number for requests.
Example 
#include <cups/http.h>
#include <cups/ipp.h>
...
ippSetPort(8631);
See Also 
 
#ippPortippPort() ippTimeToDate() 
Usage 
ipp_uchar_t *
ippTimeToDate(time_t time);
Arguments 
ArgumentDescription time The UNIX time value Returns 
A static pointer to an IPP date-time value.
Description 
The ippTimeToDate() function converts a UNIX time to an
 IPP date-time value.
Example 
#include <cups/ipp.h>
ipp_uchar_t *date;
date = ippTimeToDate(time(NULL));
See Also 
 
#ippDateToTimeippDateToTime() ippWrite() 
Usage 
ipp_state_t
ippWrite(http_t *http,
         ipp_t  *ipp);
Arguments 
ArgumentDescription http The HTTP connection ipp The IPP request or response Returns 
The current write state.
Description 
The ippWrite() function writes IPP attributes to the
 specified HTTP connection. Programs should continue calling 
ippWrite()
 until IPP_ERROR or IPP_DATA is returned.
Example 
#include <cups/http.h>
#include <cups/ipp.h>
http_t *http;
ipp_t *ipp;
ipp_state_t status;
ipp = ippNew();
... add attributes ...
while ((status = ippWrite(http, ipp)) != IPP_ERROR)
  if (status == IPP_DATA)
    break;
if (status == IPP_DATA)
{
  ... read additional non-IPP data using httpWrite() ...
}
See Also 
 
#ippReadippRead() ppdClose() 
Usage 
void
ppdClose(ppd_file_t *ppd);
Arguments 
ArgumentDescription ppd The PPD file Description 
The ppdClose() function frees all memory associated with
 the PPD file.
Example 
#include <cups/ppd.h>
ppd_file_t *ppd;
ppdClose(ppd);
See Also 
 
#ppdOpenppdOpen() , #ppdOpenFdppdOpenFd()
, #ppdOpenFileppdOpenFile() ppdCollect() 
Usage 
int
ppdCollect(ppd_file_t    *ppd,
           ppd_section_t section,
           ppd_choice_t  ***choices);
Arguments 
ArgumentDescription ppd The PPD file. section The document section to collect. choices The array of option choices that are marked. Returns 
The number of options collected.
Description 
ppdCollect() collects all of the marked options in the
 specified section, sorts them by their order dependency values, and
 returns an array that can be used to emit option commands in the proper
 order. It is normally used by the 
ppdEmit*() functions.
Example 
#include <cups/ppd.h>
#ppd_file_tppd_file_t    *ppd;
int          num_choices;
#ppd_choice_tppd_choice_t  **choices;
...
num_choices = ppdCollect(ppd, PPD_ORDER_JCL, &choices);
See Also 
 #ppdEmitppdEmit() , #ppdEmitFdppdEmitFd()
, #ppdEmitJCLppdEmitJCL() 
ppdConflicts() 
Usage 
int
ppdConflicts(ppd_file_t *ppd);
Arguments 
ArgumentDescription ppd The PPD file Returns 
The number of option conflicts in the file.
Description 
The ppdConflicts() function returns the number of
 conflicts with the currently selected options.
Example 
#include <cups/ppd.h>
ppd_file_t *ppd;
printf("%d conflicts\n", ppdConflicts(ppd));
See Also 
 
#cupsMarkOptionscupsMarkOptions() , #ppdIsMarkedppdIsMarked() , #ppdMarkDefaultsppdMarkDefaults()
, #ppdMarkOptionppdMarkOption()
ppdEmit() 
Usage 
int
ppdEmit(ppd_file_t    *ppd,
        FILE          *file,
        ppd_section_t section);
Arguments 
ArgumentDescription ppd The PPD file file The file to write to section The option section to write Returns 
0 on success, -1 on error.
Description 
The ppdEmit() function sends printer-specific option
 commands to the specified file.
Example 
#include <cups/ppd.h>
ppd_file_t *ppd;
ppdEmit(ppd, stdout, PPD_ORDER_PAGE);
See Also 
 
#ppdEmitFdppdEmitFd() ppdEmitFd() 
Usage 
int
ppdEmitFd(ppd_file_t    *ppd,
          int           fd,
          ppd_section_t section);
Arguments 
ArgumentDescription ppd The PPD file fd The file descriptor to write to section The option section to write Returns 
0 on success, -1 on error.
Description 
The ppdEmitFd() function sends printer-specific option
 commands to the specified file descriptor.
Example 
#include <cups/ppd.h>
ppd_file_t *ppd;
ppdEmitFd(ppd, 1, PPD_ORDER_PAGE);
See Also 
 
#ppdEmitppdEmit() , #ppdEmitJCLppdEmitJCL()
ppdEmitJCL() 
Usage 
int
ppdEmitJCL(ppd_file_t    *ppd,
           FILE          *file,
	   int           job_id,
           const char    *user,
	   const char    *title);
Arguments 
ArgumentDescription ppd The PPD file file The file to write to job_id The job ID number user The job user title The job name Returns 
0 on success, -1 on error.
Description 
The ppdEmitJCL() function sends printer-specific job
 control commands to the specified file. For printers that support the
 HP Printer Job Language (PJL) job control language, the output also
 contains a display string that usually appears on the printer's LCD.
Example 
#include <cups/ppd.h>
ppd_file_t *ppd;
ppdEmitJCL(ppd, stdout, job_id, user, title);
See Also 
 
#ppdEmitppdEmit() , #ppdEmitFdppdEmitFd()
ppdFindAttr() 
Usage 
ppd_attr_t *
ppdFindAttr(ppd_file_t *ppd,
            const char *keyword,
	    const char *spec);
Arguments 
ArgumentDescription ppd The PPD file keyword The name of the attribute spec The option keyword associated with the attribute or
 NULL if you don't care.
Returns 
A pointer to the attribute data or NULL if the attribute does not
 exist.
Description 
The ppdFindAttr() function returns a pointer to the
 first occurrence of the attribute in the PPD file.
Example 
#include <cups/ppd.h>
ppd_file_t *ppd;
ppd_attr_t *attr;
attr = ppdFindAttr(ppd, "RequiresPageRegion", "Upper");
See Also 
 
#ppdFindNextAttrppdFindNextAttr() ppdFindChoice() 
Usage 
ppd_choice_t *
ppdFindChoice(ppd_option_t *option,
              const char   *choice);
Arguments 
ArgumentDescription option A pointer to the option choice The name of the choice Returns 
A pointer to the choice data or NULL if the choice does not exist.
Description 
The ppdFindChoice() function returns a pointer to the
 choice data for the specified option.
Example 
#include <cups/ppd.h>
ppd_file_t *ppd;
ppd_option_t *option;
ppd_choice_t *choice;
option = ppdFindOption(ppd, "PageSize");
choice = ppdFindChoice(option, "Letter");
See Also 
 
#ppdFindMarkedChoiceppdFindMarkedChoice() , #ppdFindOptionppdFindOption() ppdFindMarkedChoice() 
Usage 
ppd_choice_t *
ppdFindMarkedChoice(ppd_file_t *ppd,
                    const char *keyword);
Arguments 
ArgumentDescription ppd The PPD file keyword The name of the option Returns 
A pointer to the choice data or NULL if the choice does not exist or
 is not marked.
Description 
The ppdFindMarkedChoice() function returns a pointer to
 the marked choice data for the specified option.
Example 
#include <cups/ppd.h>
ppd_file_t *ppd;
ppd_choice_t *choice;
choice = ppdFindMarkedChoice(ppd, "PageSize");
See Also 
 
#ppdFindChoiceppdFindChoice() , #ppdFindOptionppdFindOption() ppdFindNextAttr() 
Usage 
ppd_attr_t *
ppdFindNextAttr(ppd_file_t *ppd,
        	const char *keyword,
		const char *spec);
Arguments 
ArgumentDescription ppd A pointer to the PPD file keyword The name of the attribute spec The option keyword associated with the attribute or
 NULL if you don't care.
Returns 
A pointer to the attribute data or NULL if the attribute does not
 exist.
Description 
The ppdFindNextAttr() function returns a pointer to the
 next occurrence of the attribute in the PPD file.
Example 
#include <cups/ppd.h>
ppd_file_t *ppd;
ppd_attr_t *attr;
for (attr = ppdFindAttr(ppd, "cupsICCProfile", NULL);
     attr != NULL;
     attr = ppdFindNextAttr(ppd, "cupsICCProfile", NULL))
{
  printf("*%s %s/%s: \"%s\"\n",
         attr->name, attr->spec, attr->text,
	 attr->value ? attr->value : "(none)");
}
See Also 
 
#ppdFindAttrppdFindAttr() ppdFindOption() 
Usage 
ppd_option_t *
ppdFindOption(ppd_file_t *ppd,
              const char *keyword);
Arguments 
ArgumentDescription ppd The PPD file keyword The name of the option Returns 
A pointer to the option data or NULL if the option does not exist.
Description 
The ppdFindOption() function returns a pointer to the
 option data for the specified option.
Example 
#include <cups/ppd.h>
ppd_file_t *ppd;
ppd_option_t *option;
option = ppdFindOption(ppd, "PageSize");
See Also 
 
#ppdFindChoiceppdFindChoice() , #ppdFindMarkedChoiceppdFindMarkedChoice() ppdIsMarked() 
Usage 
int
ppdIsMarked(ppd_file_t *ppd,
            const char *keyword,
            const char *choice);
Arguments 
ArgumentDescription ppd The PPD file keyword The name of the option choice The name of the option choice Returns 
1 if the choice is marked, 0 otherwise.
Description 
The ppdIsMarked() function returns whether or not the
 specified option choice is marked.
Example 
#include <cups/ppd.h>
ppd_file_t *ppd;
printf("Letter size %s selected.\n",
       ppdIsMarked(ppd, "PageSize", "Letter") ? "is" : "is not");
See Also 
 
#cupsMarkOptionscupsMarkOptions() , #ppdConflictsppdConflicts() , #ppdIsMarkedppdIsMarked()
, #ppdMarkDefaultsppdMarkDefaults()
, #ppdMarkOptionppdMarkOption()
ppdMarkDefaults() 
Usage 
void
ppdMarkDefaults(ppd_file_t *ppd);
Arguments 
ArgumentDescription ppd The PPD file Description 
The ppdMarkDefaults() function marks all of the default
 choices in the PPD file.
Example 
#include <cups/ppd.h>
ppd_file_t *ppd;
ppdMarkDefaults(ppd);
See Also 
 
#cupsMarkOptionscupsMarkOptions() , #ppdConflictsppdConflicts() , #ppdIsMarkedppdIsMarked()
, #ppdMarkDefaultsppdMarkDefaults()
, #ppdMarkOptionppdMarkOption()
ppdMarkOption() 
Usage 
int
ppdMarkOption(ppd_file_t *ppd,
              const char *keyword,
              const char *choice);
Arguments 
ArgumentDescription ppd The PPD file keyword The name of the option choice The name of the choice Returns 
The number of conflicts in the PPD file.
Description 
The ppdMarkOption() function marks the specified option
 choice.
Example 
#include <cups/ppd.h>
ppd_file_t *ppd;
ppdMarkOption(ppd, "PageSize", "Letter");
See Also 
 
#cupsMarkOptionscupsMarkOptions() , #ppdConflictsppdConflicts() , #ppdIsMarkedppdIsMarked()
, #ppdMarkDefaultsppdMarkDefaults()
, #ppdMarkOptionppdMarkOption()
ppdOpen() 
Usage 
ppd_file_t *
ppdOpen(FILE *file);
Arguments 
ArgumentDescription file The file to read from Returns 
A pointer to a PPD file structure or NULL if the PPD file could not
 be read.
Description 
The ppdOpen() function reads a PPD file from the
 specified file into memory.
Example 
#include <cups/ppd.h>
ppd_file_t *ppd;
FILE *file;
file = fopen("filename.ppd", "rb");
ppd = ppdOpen(file);
fclose(file);
See Also 
 
#ppdCloseppdClose() , #ppdOpenFdppdOpenFd()
, #ppdOpenFileppdOpenFile() ppdOpenFd() 
Usage 
ppd_file_t *
ppdOpenFd(int fd);
Arguments 
ArgumentDescription fd The file descriptor to read from Returns 
A pointer to a PPD file structure or NULL if the PPD file could not
 be read.
Description 
The ppdOpenFd() function reads a PPD file from the
 specified file descriptor into memory.
Example 
#include <cups/ppd.h>
ppd_file_t *ppd;
int        fd;
fd = open("filename.ppd", O_RDONLY);
ppd = ppdOpenFd(fd);
close(fd);
See Also 
 
#ppdCloseppdClose() , #ppdOpenppdOpen()
, #ppdOpenFileppdOpenFile() ppdOpenFile() 
Usage 
ppd_file_t *
ppdOpenFile(const char *filename);
Arguments 
ArgumentDescription filename The name of the file to read from Returns 
A pointer to a PPD file structure or NULL if the PPD file could not
 be read.
Description 
The ppdOpenFile() function reads a PPD file from the
 named file into memory.
Example 
#include <cups/ppd.h>
ppd_file_t *ppd;
ppd = ppdOpenFile("filename.ppd");
See Also 
 
#ppdCloseppdClose() , #ppdOpenppdOpen()
, #ppdOpenFdppdOpenFd() ppdPageLength() 
Usage 
float
ppdPageLength(ppd_file_t *ppd,
              const char *name);
Arguments 
ArgumentDescription ppd The PPD file name The name of the page size Returns 
The length of the specified page size in points or 0 if the page size
 does not exist.
Description 
The ppdPageLength() function returns the page length of
 the specified page size.
Example 
#include <cups/ppd.h>
ppd_file_t *ppd;
printf("Length = %.0f\n", ppdPageLength(ppd, "Letter"));
See Also 
 
#ppdPageLengthppdPageLength() , #ppdPageSizeppdPageSize() , #ppdPageWidthppdPageWidth()
ppdPageSize() 
Usage 
ppd_size_t *
ppdPageSize(ppd_file_t *ppd,
            const char *name);
Arguments 
ArgumentDescription ppd The PPD file name The name of the page size Returns 
A pointer to the page size record of the specified page size in
 points or NULL if the page size does not exist.
Description 
The ppdPageSize() function returns the page size record
 for the specified page size.
Example 
#include <cups/ppd.h>
ppd_file_t *ppd;
ppd_size_t *size;
size = ppdPageSize(ppd, "Letter");
if (size != NULL)
{
  printf(" Width = %.0f\n", size->width);
  printf("Length = %.0f\n", size->length);
  printf("  Left = %.0f\n", size->left);
  printf(" Right = %.0f\n", size->right);
  printf("Bottom = %.0f\n", size->bottom);
  printf("   Top = %.0f\n", size->top);
}
See Also 
 
#ppdPageLengthppdPageLength() , #ppdPageWidthppdPageWidth() ppdPageWidth() 
Usage 
float
ppdPageWidth(ppd_file_t *ppd,
             const char *name);
Arguments 
ArgumentDescription ppd The PPD file name The name of the page size Returns 
The width of the specified page size in points or 0 if the page size
 does not exist.
Description 
The ppdPageWidth() function returns the page width of
 the specified page size.
Example 
#include <cups/ppd.h>
ppd_file_t *ppd;
printf("Width = %.0f\n", ppdPageWidth(ppd, "Letter"));
See Also 
 
#ppdPageLengthppdPageLength() , #ppdPageSizeppdPageSize() 