lmsgi(3) lmsgi(3)
NAME
lmsgi : license_init, license_chk_out, license_chk_in, license_timer,
license_set_attr, license_expdate, license_errstr, license_status,
license_free - 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
license_free
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.
LMLICENSEFILE
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.
Page 1
lmsgi(3) lmsgi(3)
LMLICENSEDB
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.
Page 2
lmsgi(3) lmsgi(3)
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().
Page 3
lmsgi(3) lmsgi(3)
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().
Page 4
lmsgi(3) lmsgi(3)
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.
keepconn
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().
Page 5
lmsgi(3) lmsgi(3)
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
*/
Page 6
lmsgi(3) lmsgi(3)
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:
LMSGINOSUCHFEATURE
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.
LMSGI30DAYWARNING
A pointer to a function which is called when the requested feature
will expire within 30 days.
LMSGI60DAYWARNING
A pointer to a function which is called when the requested feature
will expire within 60 days.
LMSGI90DAYWARNING
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:
Page 7
lmsgi(3) lmsgi(3)
LMSGINOSUCHFEATURE
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.
LMSGI30DAYWARNING
This attribute is set to do nothing if the license is about to
expire within 30 days.
LMSGI60DAYWARNING
This attribute is set to do nothing if the license is about to
expire within 60 days.
LMSGI90DAYWARNING
This attribute is set to do nothing if the license is about to
expire within 90 days.
LMAUSERRECONNECT
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.
LMAUSERRECONNECTDONE
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.
LMAUSEREXITCALL
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;
Page 8
lmsgi(3) lmsgi(3)
{
(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().
Page 9
lmsgi(3) lmsgi(3)
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().
Page 10
lmsgi(3) lmsgi(3)
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());
Page 11
lmsgi(3) lmsgi(3)
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());
}
Page 12
lmsgi(3) lmsgi(3)
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();
Page 13
lmsgi(3) lmsgi(3)
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).
Page 14