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 pro
vided 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 behav
ior 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.
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.
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_INTER
VAL. 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() peri
odically.
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().
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, appli
cations 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().
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().
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
*/
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.
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 recon
nect 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());
}
/*
* 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().
license_expdate - Returns the expiration date of the fea
ture 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().
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());
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 fea
ture (license). A return value of 0 indicates a success
ful return from the most recent call to the FLEXlm library
for that feature. A return value value less than 0 indi
cates 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());
}
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();
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 direc
tory
The only solution is to reduce the number of file descrip
tors 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).
Man(1) output converted with
man2html