SLGetPrinterSettings(3)
SLGetPrinterSettings, SLSysVGetSpoolerOptions, SLSysVGetPrinterOptions, SLSysVSaveSpoolerOptions, SLSysVSavePrinterOptions - option management
As shipped in IRIX 6.5.22. Unchanged since IRIX 6.5.
NAME SLGetPrinterSettings, SLSysVGetSpoolerOptions, SLSysVGetPrinterOptions, SLSysVSaveSpoolerOptions, SLSysVSavePrinterOptions - option management SYNOPSIS #include <spool.h> int SLGetPrinterSettings(const char *printer, SLSettingsStruct **settingsp); int SLSysVGetSpoolerOptions(SLSysVSpoolerOptionsStruct **spooler_optsp); int SLSysVGetPrinterOptions(const char *printer, char **printer_optsp); int SLSysVSaveSpoolerOptions(SLSysVSpoolerOptionsStruct *spooler_opts); int SLSysVSavePrinterOptions(const char *printer, char *printer_opts, int location); DESCRIPTION The spooling system and the printer provide many options to customize their behavior to the needs of the user. The Silicon Graphics printing environment permits applications to save and retrieve these printing options. For example, a user can select duplex printing for a particular printer and save this setting. From then on, whenever a print job is sent to that printer it will be printed in duplex mode. This option management is provided by the libspool functions SLGetPrinterSettings, SLSysVGetSpoolerOptions, SLSysVGetPrinterOptions, SLSysVSaveSpoolerOptions and SLSysVSavePrinterOptions. Currently, option management is supported only under the System V spooling system. Under the System V spooler the spooler options are the lp(1) command switches -c, -m, -w, -s and -t. Refer to the lp man page for an explanation of these switches. Spooler options are maintained on a per user basis. For example, a banner page title (-t) is saved for a single user. That title will be used for all print jobs submitted by that user to any printer. Printer specific options are considered to be those that would be specified using the lp command line switch -o. Though there are often numerous printer specific options, the libspool option management functions treat them together as a single whitespace separated string of options. Printer options are maintained on a per user, per printer basis. This means that a user can save the option to suppress the printing of the banner for a specific printer without that settings affecting any other user or printer. Note that an application must utilize the libspool functions detailed here to participate in spooler and printer option management. For example, if an application submits a print job using SLSubmitJob, it is the application's responsibility to use the option management functions to determine what option settings should be specified for the print job. The PrintPanel and lp programs utilize the libspool option management facilities. In order to provide a consistent printing environment, it is strongly suggested that application developers utilize the libspool option management functions. The goal is to remember user printing preferences across applications. While spooler and printer options are typically handled in a spooling system dependent manner, the SLGetPrinterSettings reads these settings into the spooling system independent option structure SLSettingsStruct. This function reads both the spooler and printer options. As contained in the SLSettingsStruct, the settings can be passed as parameters to the libspool print job submittal functions (e.g. SLSubmitJob). By using the SLGetPrinterSettings function, an application can submit a print job using options that the submitter has previously saved using SGI's printing tools. Thus, the print job will be customized to match the preferences of the user. The SLSysVGetSpoolerOptions and SLSysVSaveSpoolerOptions functions read and write System V spooling system options, respectively. These are System V spooling system specific functions and an error indication will be returned if these functions are called when the System V spooler is not the current spooling system. Spooling system specific options are saved in the caller's home directory under the name .glprc. This file contains a single line of spooler specific option switches. The switches are the same as the spooler specific command line switches used by the lp program with the exception that the -d, and -n switches are never saved. These functions pass the spooler options in the SLSysVSpoolerOptionsStruct structure. The SLSysVGetPrinterOptions and SLSysVSavePrinterOptions functions read and write System V printer specific options, respectively. These are System V spooling system specific functions and an error indication will be returned if these functions are called when the System V spooler is not the current spooling system. Printer specific options are saved in the directory /var/spool/lp/settings/<printer name>. Each user's option file will be named by username. A default option file named defaultSettings may be found in the printer settings directory and, if it exists, will be used if no user option file is found. The printer specific options file consists of a single line of options. The contents are all the options specified using the -o command line switch to the lp command. Printer specific options cannot be saved for printer classes. printer specifies the name of the printer for which options are to be read or written. If NULL, the default printer will be used. settingsp is set by the SLGetPrinterSettings function to point to an SLSettingsStruct structure containing the job and printer settings information. The contents of this structure must be copied to caller storage if they are to be preserved across subsequent calls to the SLGetPrinterSettings function. If spooler or printer options cannot be found or the specified printer does not exist, the default values specified below will be assigned to the SLSettingsStruct structure fields. spooler_optsp is set by the SLSysVGetSpoolerOptions function to point to an SLSysVSpoolerOptionsStruct. This structure contains the System V spooler options. The contents of this structure must be copied to caller storage if they are to be preserved across subsequent calls to the SLSysVGetSpoolerOptions function. If spooler options cannot be found, the default values specified below will be assigned to the SLSysVSpoolerOptionsStruct structure fields. spooler_opts specifies to the SLSysVSaveSpoolerOptions function the values of the spooler options to be saved. These values are passed in the SLSysVSpoolerOptionsStruct structure. printer_optsp is set by the SLSysVGetPrinterOptions function to point to a string containing the printer specific options. The options within the string are separated by whitespace. If no options are found for the specified printer or the printer does not exist, this pointer is set to NULL. printer_opts specifies to the SLSysVSavePrinterOptions function the string of printer specific options to be saved. location specifies to the SLSysVSavePrinterOptions function whether the options to be saved are only for the caller (SL_SAVE_USER) or are for all users of the specified printer (SL_SAVE_DEFAULT). Note that to save options for all users the caller must have the username root or lp as determined from the effective user ID. The SLSettingsStruct is defined as: typedef struct _slSettingsStruct { int copy; /* 1 == copy to spooling dir, 0 == link */ int mail; /* 1 == send mail on completion */ char *title; /* Print job banner page title. If NULL */ /* the system default banner title */ /* is to be used. */ char *options; /* Spooling system specific options */ /* (e.g. -w and -o under System V */ /* and -h under BSD) */ } SLSettingsStruct; The default values for the fields of the SLSettingsStruct are spooling system dependent and are listed in the following table. Field Sys V Default BSD Default _____________________________________ copy 0 1 mail 0 0 title NULL NULL options NULL NULL The SLSysVSpoolerOptionsStruct is defined as: typedef struct _slSysVSpoolerOptionsStruct { int copy; /* 1 == copy to spooling dir, 0 == link */ int mail; /* 1 == send mail on completion */ int message; /* 1 == send message on completion */ int suppress_id; /* 1 == suppress job ID message */ char *title; /* Print job banner page title. If NULL */ /* the system default banner title */ /* is to be used. */ } SLSysVSpoolerOptionsStruct; The default values for the fields of the SLSysVSpoolerOptionsStruct are listed in the following table. Field Sys V Default ___________________________ copy 0 mail 0 message 0 suppress_id 0 title NULL RETURN VALUE All functions return 0 if execution was successful. -1 is returned and SLerrno is set if an execution error has occurred. EXECUTION ERROR CODES All functions will fail under the following circumstances. SL_ERR_FIND_SPOOLER An error occurred while attempting to determine the available printer spooling systems. SL_ERR_NO_SPOOLERS There are no printer spooling systems available. SL_ERR_NO_DEF_PRINTER There is no default printer registered with the printer spooling system. SL_ERR_BAD_PRINTER_NAME The printer name specified is either an empty string (""), or a string consisting entirely of whitespace. In addition, the SLSysV... functions will fail under the following circumstances. SL_ERR_NO_SYSV This function requires that the System V spooler be the current spooling system. And the SLSysVSave... functions can fail for the following reason. SL_ERR_SAVE_OPTIONS The options file could not be saved. Check the value of errno. WARNING The pointers to settingsp, spooler_optsp, and printer_optsp are invalid across subsequent calls to their functions. The data pointed to must be copied to be preserved. Note that the character string fields of the structures must be duplicated in any copy operation since these pointers also become invalid. SEE ALSO glp(1), lp(1), SLPerror(3), libspool(3)