lmsgi(3)
lmsgi : license_init, license_chk_out, license_chk_in, license_timer, license_set_attr, license_expdate, license_errstr, license_status - SGI FLEXlm library
As shipped in IRIX 6.5. First release of IRIX 6.5.
NAME lmsgi : license_init, license_chk_out, license_chk_in, license_timer, license_set_attr, license_expdate, license_errstr, license_status - SGI FLEXlm library HEADER FILE #include <lmsgi.h> DESCRIPTION This manual page describes the SGI interface to liblmsgi.a, the SGI extension to Globetrotter Software's FLEXlm library. This library supports the interfaces provided by FLEXlm as well as the functions described here. The SGI interface defines a small set of functions for licensing your software using the FLEXlm, and consists of the following calls: license_init license_chk_out license_chk_in license_timer license_set_attr license_expdate license_errstr license_status get_job When using any of the liblmsgi library functions you must include the following header and macro in your source file: #include <lmsgi.h> LM_CODE(code, ENCRYPTION_CODE_1, ENCRYPTION_CODE_2, VENDOR_KEY1, VENDOR_KEY2, VENDOR_KEY3, VENDOR_KEY4, VENDOR_KEY5); The -llmsgi flag must be given to the C compiler to link programs which contain calls to FLEXlm functions. cc file.o -llmsgi ENVIRONMENT The following environment variables will modify the behavior of applications licensed with this library. LM_LICENSE_FILE If set, specifies the name of one or more FLEXlm license files. Multiple files can be specified by separating them with a colon (:). The specified files are checked first for FLEXlm licenses. LM_LICENSE_DB If set, specifies the name of a license file database. A license file database is a file which contains a list of one or more FLEXlm license files and/or directories containing FLEXlm license files. If LM_LICENSE_DB is not defined the default license file database, /var/flexlm/licensefile.db, is used. The format of a license file database is one file or directory per line. Comments are indicated by a pound sign '#' in the first column of the line. Blank lines are ignored. Trailing and/or leading whitespace is not allowed on a line. Any directory listed in the file is searched for filenames matching "*.dat". Any subdirectory is also searched (recursively). All file names must also end with the "*.dat" extension. If no license files have been defined by either the LM_LICENSE_FILE or LM_LICENSE_DB environment variables, the default FLEXlm license file is /var/flexlm/license.dat. NAME license_init - Initializes the FLEXlm library. SYNOPSIS #include <lmsgi.h> int license_init (VENDORCODE* code, char *vendorname, boolean_t heartbeat); DESCRIPTION license_init() initializes the FLEXlm library and creates a license job. All subsequent calls to license_init() create new license jobs. Each license is independent. code Use the global variable "code" which was defined by the LM_CODE macro (see above). vendorname The name of the vendor daemon to use. heartbeat This is B_FALSE or B_TRUE. If B_FALSE, then a default heartbeat protocol is implemented. FLEXlm will generate a SIGALRM at every LM_A_CHECK_INTERVAL. This will make a call to license_timer(). If B_TRUE, then the SIGALRM is not generated, and it is up the application to call license_timer() periodically. EXAMPLE /* * The following code initializes the FLEXlm library and * uses sgifd as the vendor daemon. If any errors are detected, * then display them. */ if ( license_init (&code, "sgifd", B_FALSE) < 0 ) { printf ("Initialization error: %s\n", license_errstr()); } DIAGNOSTICS license_init() returns a 0 upon success or a value less than 0 if an error is detected. The error string can viewed via license_errstr(). NAME license_chk_out - Attempts to check out a license. SYNOPSIS #include <lmsgi.h> int license_chk_out(VENDORCODE *code, char *feature, char *version); DESCRIPTION license_chk_out() checks out one (or more) license(s) for the specified feature and, for counted licenses, keeps the daemon up to date on the status of the process using the license(s). code Use the global variable "code" which was defined by the LM_CODE macro (see above). feature The ASCII feature name desired. version The version of the feature desired in floating point format, 3 decimal places max. This value must be less than or equal to the version number in the license file for the check out to succeed. The default behavior of this library when a license request fails is to print the standard SGI feature not found message and exit. To override this behavior, applications should set the attribute LMSGI_NO_SUCH_FEATURE using license_set_attr to register their own callback before calling license_chk_out. DIAGNOSTICS license_chk_out() returns a 0 upon success or a value less than 0 if an error is detected. The error string can viewed via license_errstr(). NAME license_chk_in - Return a checked out license. SYNOPSIS #include <lmsgi.h> int license_chk_in(char *feature, int keep_conn); DESCRIPTION license_chk_in() checks in the license of the specified feature that had been previously checked out with license_chk_out(). feature The feature (license) name to be checked in. keep_conn A non-zero means "Keep connection to server"; a 0 means drop TCP connection. A zero should always be used as the default. Unused for UDP. Consult the FLEXlm Programmer's Guide for more details. EXAMPLE /* * The following code returns the license, dummy, back to the * server. If any errors are detected, then display them. */ if ( license_chk_in ("dummy", 0) ) { printf ("Check in error: %s\n", license_errstr()); } DIAGNOSTICS license_chk_in() returns a 0 upon success or a value less than 0 if an error is detected. The error string can viewed via license_errstr(). NAME license_timer - Verifies the connection to the license server. SYNOPSIS #include <lmsgi.h> void license_timer(); DESCRIPTION Periodic calls to license_timer() should be throughout the user's application. These calls are important because they verify that the license currently checked out to your application remains valid. The user may want to call license_timer() before important steps in the program (for example, before writing a file to disk). EXAMPLE /* * application code */ license_timer(); /* * some more application code and then * verify connection before writing to disk */ license_timer(); /* * some more application code */ NAME license_set_attr - Used to set different FLEXlm attributes. SYNOPSIS #include <lmsgi.h> int license_set_attr(int key, LM_A_VAL_TYPE value); DESCRIPTION license_set_attr() set a FLEXlm attribute. The key describes which attribute to set and value describes the value for that attribute. A description of the attributes can be found in the FLEXlm Programmer's Guide or the header file lm_attr.h. key The FLEXlm attribute to set. value Value to set the key to. Values should be of the appropriate type for the particular attribute, but should be cast to LM_A_VAL_TYPE. NOTES Four additional attributes have been defined in lmsgi: LMSGI_NO_SUCH_FEATURE A pointer to a function which is called when the requested feature cannot be checked out. This function is only called if license_chk_out() fails with an LM_NOFEATURE error. LMSGI_30_DAY_WARNING A pointer to a function which is called when the requested feature will expire within 30 days. LMSGI_60_DAY_WARNING A pointer to a function which is called when the requested feature will expire within 60 days. LMSGI_90_DAY_WARNING A pointer to a function which is called when the requested feature will expire within 90 days. The lmsgi library sets default values for attributes in order to provide standardized error handling and error messages for SGI software. To disable a pre-set attribute, either use license_set_attr() to register a new callback that provides your desired behavior, or register a NULL callback to turn off the default behavior. The pre-set attributes are as follows: LMSGI_NO_SUCH_FEATURE This attribute is set to a function which displays information on how to get a license for an SGI product. This function also calls exit(), thus the application exits when the requested feature cannot be checked out. LMSGI_30_DAY_WARNING This attribute is set to do nothing if the license is about to expire within 30 days. LMSGI_60_DAY_WARNING This attribute is set to do nothing if the license is about to expire within 60 days. LMSGI_90_DAY_WARNING This attribute is set to do nothing if the license is about to expire within 90 days. LM_A_USER_RECONNECT This attribute is set to a function which displays a message noting that the connection to the license server was lost, and an attempt is being made to reconnect to the server. LM_A_USER_RECONNECT_DONE This attribute is set to a function which displays a message noting that the connection to the license server was lost, and the attempt to reconnect to the server was successful. LM_A_USER_EXITCALL This attribute is set to a function which displays a message noting that the connection to the license server was lost, and the attempt to reconnect to the server has failed. This function also calls exit(), thus the application exits when the reconnect fails. EXAMPLE /* * The following code sets the LM_A_RETRY_COUNT to 5. * If any errors are detected, then display them. */ if ( license_set_attr(LM_A_RETRY_COUNT, (LM_A_VAL_TYPE) 5) ) { printf("Set attribute error: %s\n", license_errstr()); } /* * The following code displays a message when a license will expire * within 90 days. */ int expire_soon(daysLeft) int daysLeft; { (void) fprintf(stderr, "Your software license will expire in %d days.\n", daysLeft); return 0; } /* * The following code registers a callback for a license which * will expire soon. */ if ( license_set_attr(LMSGI_30_DAY_WARNING, (LM_A_VAL_TYPE) expire_soon) ) { printf("Set attribute error: %s\n", license_errstr()); } DIAGNOSTICS license_set_attr() returns a 0 upon success or a value less than 0 if an error is detected. The error string can viewed via license_errstr(). NAME license_expdate - Returns the expiration date of the feature checked out. SYNOPSIS #include <lmsgi.h> time_t license_expdate(char *feature); DESCRIPTION license_expdate() returns the expiration date of a feature (license). feature The name of the feature (license). EXAMPLE /* * The following code returns the expiration date of the * feature, dummy. * If any errors are detected, then display them. */ time_t feature_expdate; if ( ( feature_expdate = license_expdate("dummy") ) == -1 ) printf ("Expiration date error: %s\n", license_errstr()); DIAGNOSTICS license_expdate() returns the expiration date of the given feature in seconds since 00:00:00 UTC, January 1, 1970. If the given feature is a permanent feature (no expiration date) then license_expdate() returns 0. If an error occurs, a value of (time_t)-1 is returned. Any error string can viewed via license_errstr(). NAME license_errstr - Returns license server or system errors. SYNOPSIS #include <lmsgi.h> char* license_errstr(); DESCRIPTION license_errstr() returns the FLEXlm error string for the most recent FLEXlm error along with the major and minor number. If a UNIX error is involved, the UNIX error description will also be included in the message, along with the UNIX errno. EXAMPLE /* * The following code prints out the error * * Cannot find license file (-1, 73:2), No such file or directory * * when the license file cannot be accessed. * */ printf ("%s\n", license_errstr()); NAME license_status - Returns the latest status of the checked out feature. SYNOPSIS #include <lmsgi.h> int license_status(char *feature); DESCRIPTION license_status() returns the status of the requested feature (license). A return value of 0 indicates a successful return from the most recent call to the FLEXlm library for that feature. A return value value less than 0 indicates an error from most recent call to the FLEXlm library. feature The name of the feature. EXAMPLE /* * The following code checks the status of the most recent FLEXlm * library call. If any errors occurred, then display them. */ license_chk_out (&code, "dummy", "2.000"); if ( license_status ("dummy") < 0 ) { printf ("error: %s\n", license_errstr()); } NAME get_job - Returns the FLEXlm job ID. SYNOPSIS #include <lmsgi.h> LM_HANDLE *get_job(void); DESCRIPTION Returns the FLEXlm job ID so that applications can use the standard FLEXlm functions along with the SGI interface. A return value of NULL indicates that there is currently no FLEXlm job ID. EXAMPLE LM_HANDLE *job; job = get_job(); RESTRICTIONS The FlexLM licensing code uses the stdio functions (fopen(), fgets(), etc). In some circumstances, a process may have more open file descriptors than will fit in a FILE structure (field _file; see /usr/include/stdio.h for details). If this happens before the licensing calls, acquiring the license will fail with the message: Cannot find license file (-1,212:2) No such file or directory The only solution is to reduce the number of file descriptors in use when licensing calls are made. In practice this is only a problem with the O32 (5.3 compatible) ABI, which uses an unsigned char to hold the file descriptor (fd<=255).