keyctl(2)
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 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.
The calling process must have the P_SYSOPS privilege to
use the K_SETLIMIT command.
Input
When cmd is K_SETLIMIT,
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 Number */
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.
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 number for uniqueness with respect
to other serial numbers in the array and sets the processor
and or user limit to the values indicated.
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 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 key pairs.
ENOMEM-
There is not enough memory to complete the operation.
EPERM-
The command was K_SETLIMIT, and the caller does not
have the P_SYSOPS privilege.
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.
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004