SLGetPrinterSettings(3) Impressario SLGetPrinterSettings(3)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
Page 1
SLGetPrinterSettings(3) Impressario SLGetPrinterSettings(3)
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
Page 2
SLGetPrinterSettings(3) Impressario SLGetPrinterSettings(3)
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;
Page 3
SLGetPrinterSettings(3) Impressario SLGetPrinterSettings(3)
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.
Page 4
SLGetPrinterSettings(3) Impressario SLGetPrinterSettings(3)
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 ALSOglp(1), lp(1), SLPerror(3), libspool(3)
Page 5
