keyctl(2)                                                  keyctl(2)


       NAME
             keyctl - sets and retrieves user and processor limits

       SYNOPSIS
             #include <sys/keyctl.h>
             int keyctl(int cmd, void *arg, int nskeys);

       DESCRIPTION
             The keyctl system call sets the user and processor limits
             based on its arguments and the upgrade key pair(s) passed to
             it as input, or retrieves the current processor or user limit.

             The processor limit is the maximum number of processors that
             can be online at any given time.  The user limit is the
             maximum number of users that can simultaneously log in to a
             system.

             The keyctl system call is intended for use by the software key
             mechanism.  It is executed at boot time and when doing a
             processor or user limit upgrade.  If keyctl is not executed at
             boot time or if no valid strings are passed, a system will run
             as a limited use system, with a single processor enabled.
             Appropriate administrative privilege is required to use the
             keyctl K_SETLIMIT command.

          Input
             When cmd is K_SETPROCLIMIT or K_SETUSERLIMIT, arg is a pointer
             to an array of nskeys structures of type k_skey.  A k_skey
             structure is defined as:

                   struct k_skey {
                       uchar_t   sernum[STRLEN];   /* Serial Identifier */
                       uchar_t   serkey[STRLEN];   /* Activation Key */
                   };

             nskeys is the number of elements in the array pointed to by
             arg.

             When the cmd is K_GETPROCLIMIT or K_GETUSERLIMIT, the arg and
             nskeys arguments are ignored.

             The serial identifier is a combination of product_id and
             serial_number.





                           Copyright 1994 Novell, Inc.               Page 1

      keyctl(2)                                                  keyctl(2)


         Processing
            When cmd is K_SETLIMIT, keyctl validates each element of the
            array pointed to by arg against the base key embedded in the
            kernel.  keyctl checks each serial identifier for uniqueness
            with respect to other serial identifiers in the array and sets
            the processor limit to the sum of the values of the unique and
            valid key pairs found in the array, or to 1 if no unique and
            valid key pairs were found.

            The user limit on a Application Server (AS) System is set to
            UNLIMITED if the AS key pair is valid or to 2 if it is
            invalid.  The user limit on a Personal Edition (PE) System is
            set to 2.

            When cmd is K_GETPROCLIMIT or K_GETUSERLIMIT, keyctl returns
            the appropriate limit.  This is the maximum number of
            processors that can be online simultaneously, or the maximum
            number of users that can be logged in.

         Errors
            If any of the following conditions occur, a negative value is
            returned and errno is set to the corresponding value:

            EEXIST    The array contains duplicate upgrade serial numbers.
                      The limit is set to the number of valid and unique
                      key pairs that were found, or to the default if no
                      unique and valid entries were found.

            EFAULT    arg is NULL or is an invalid address.

            EINVAL    cmd is invalid or the array contains one or more
                      invalid upgrade key pairs.

            ENOMEM    There is not enough memory to complete the
                      operation.

            EPERM     The caller does not have appropriate privilege for
                      the operation.

            ETIME     cmd is K_SETLIMIT and less than ten seconds has
                      passed since the last unsuccessful call of keyctl
                      with the same cmd.

            Note that the EEXIST and EINVAL cases do not follow standard
            function semantics: the function fails, errno is set, but a
            side effect occurs.


                          Copyright 1994 Novell, Inc.               Page 2

       keyctl(2)                                                  keyctl(2)


       REFERENCES
             keyadm(1M), licensekeys(4), sysconf(3C)














































                           Copyright 1994 Novell, Inc.               Page 3