cmpt_getbynum(3)

NAME

cmpt_getbynum(), cmpt_endent(), cmpt_getbyname(), cmpt_getent(), cmpt_setent() — map compartment name to number or number to name

SYNOPSIS

#include <sys/cmpt.h>

void cmpt_endent(struct cmpt_state **state);

cmpt_t cmpt_getbyname(const char *cmpt_name);

char *cmpt_getbynum(cmpt_t cmpt_num);

int cmpt_setent(struct cmpt_state **state);

const struct cmpt_pair *cmpt_getent(struct cmpt_state **state);

Parameters

cmpt_name: Pointer to a string containing a compartment name.
cmpt_num: Compartment number.
state: Pointer to internal state.

Structure Members

The cmpt_state structure is defined in <sys/cmpt.h>. It contains at least the following fields:

const char   *cmpt_name;  /* compartment name */ 
int           cmpt_num;   /* compartment number */ 

DESCRIPTION

Compartments are referenced by strings in configuration files under /etc/cmpt, but are maintained as numbers internally. The functions cmpt_getbyname(), cmpt_getbynum(), cmpt_setent(), cmpt_getent(), and cmpt_setent() query and iterate over this database.

cmpt_getbyname(): Returns the compartment number corresponding to the string specified by cmpt_name.
cmpt_getbynum(): Returns the compartment name corresponding to cmpt_num. If the return value is not NULL, it is the responsibility of the caller to free the returned value using free(). See free(3C).
cmpt_setent(): Opens the database connection to allow an iterative search.
cmpt_getent(): Returns a pointer to the next compartment name/number pair from the database. The user must not call free() to release the memory pointed to by the return value.
cmpt_endent(): Closes the database connection.

Notes

Every call to cmpt_setent() must be matched with a corresponding call to cmpt_endent().

RETURN VALUE

cmpt_getbyname() returns the following values:

n>0: Successful completion. The function returns a valid compartment number.
-1: Function failed. errno is set to indicate the error.

cmpt_getbynum() returns the following values:

pointer: Successful completions. Returns a non-null pointer to a string containing the compartment name.
NULL pointer: Function failed. Returns a null pointer and sets errno to indicate the error .

The caller is responsible for freeing the result.

cmpt_setent() returns the following values:

0: Successful completion.
-1: Function failed. errno is set to indicate the error.

cmpt_getent() returns the following values:

pointer: Succesaful completions. Returns a non-null pointer to a cmpt_pair structure.
NULL pointer: Function failed or entries are exhausted. In case of an error, errno is set to indicate the error.

cmpt_getent() sets errno to 0 and returns a null pointer when all entries have been exhausted.

ERRORS

If any of the following conditions occur, the functions fail and set errno.

ENOENT: Compartment name or number does not exist.
ENOSYS: Compartmentalization is not enabled on this system.
ENOMEM: The function failed to allocate sufficient memory for its operation.

EXAMPLES

Example 1

Get the compartment number associated with a name.

#include <sys/cmpt.h>

void main(int argc, char **argv) {
    cmpt_t cmptid;

    cmptid = cmpt_getbyname("INIT");
    if (cmptid != -1) {
        printf("\nCompartment id : %d\n", cmptid);
    } else {
        printf("\nError getting compartment number\n");
    }
}

Example 2

Get the compartment name associated with a number.

#include <sys/cmpt.h>

void main(int argc, char **argv) {
    char *name;

    name = cmpt_getbynum((cmpt_t)2);
    if (name) {
        printf("\nCompartment name : %s\n", name);
        free(name);
    } else {
        printf("\nError getting compartment name\n");
    }
}

Example 3

Iterate through compartment mapping entries.

#include <errno.h>
#include <sys/cmpt.h>

void main(int argc, char **argv) {
    struct cmpt_pair *pair;
    struct cmpt_state *state

    if (cmpt_setent(&state) != 0) {
       perror("cmpt_setent failed");
       exit(1);
    }

    /* get entries until a NULL returned */
    while ( pair = cmpt_getent(&state) )
    {
        printf("\nCompartment Nnumber : %d  Name : %s\n",
                pair->cmpt_num, pair->cmpt_name);
    }

    if (errno == 0)
    {
        printf("\nAll Entries printed\n");
    } else {
        printf("\nError getting compartment entry\n");
    }

    cmpt_endent();
}

DEPENDENCIES

These functions are a part of the libsec library, which can be linked with your executable with the -lsec option.