loadtbl
Purpose
Installs or queries configuration information in the
kernel.
Syntax
#include <sys/dstables.h>
int loadtbl (cntl, buf, size)
struct ltable *cntl;
char *buf;
int size;
Description
The loadtbl system call installs one element of a table
into the kernel or queries information from the kernel.
If Distributed Services is installed on your system, you
can query, but not change, the kernel of another node.
To change or add an entry in the kernel table with the
loadtbl system call, a process must have an effective
user ID of superuser. Queries of table entries can be
submitted by any process.
This system call provides a general mechanism for
installing configuration information into the kernel.
The outline of the general structure supported by loadtbl
is:
o For each type, there is an array of table headers
that has a fixed size.
o Each table header contains an ID and a pointer to a
structure of information related to that ID.
o The structure of buf is unknown to the loadtbl system
call.
The loadtbl system call can be used to load a single
table entry into the kernel, to load an entire set of
table entries into the kernel, or to query one or more
entries in the kernel.
The buf parameter is a pointer to the data being loaded,
while the size parameter determines the size (in bytes)
of the data being loaded. The cntl parameter points to a
structure of type ltable. The ltable structure is
defined in the sys/dstables.h header file, and it con-
tains the following members:
char type; /* Defines the type of table being managed */
/* or queried. The type must be one of: */
/* DSNCB (Node Control Block) */
/* DSOCB (Outbound Translate) */
/* DSWCB (Wild Card Node Translate) */
/* DSIPC (IPC key table entries) */
/* USERTBL (User-defined Table) */
long id; /* Identifies which table entry is being */
/* loaded. For DSNCB this is the node ID. */
char mode; /* Type of request. */
long nid; /* For queries, the node ID whose tables are */
/* to be queried. */
long reserved[4]; /* Reserved. Contents must be zero */
The mode field of the ltable structure can contain any
one of the following values:
L_REPLACE The entry being loaded is either a new one
or a replacement for an existing one. If no
corresponding table entry exists, a new one
is created.
L_DELETE The table information for the id specified
is deleted.
L_QUERYI This mode enables the calling process to
learn which IDs of a particular type cur-
rently have information in the kernel. The
ltable.type field specifies which type is
being queried. buf is assumed to point to
an array of long integers into which
loadtabl places the requested IDs. (When
type is DSOCB, DSWCB, or DSIPC, a single
zero ID is returned in the array.) The
ltable.nid specifies which node's kernel is
to be queried. If ltable.nid is 0 or the
node ID of the local node, then the local
kernel is queried. Otherwise, the specified
remote node ID is queried.
L_QUERYT This mode enables the calling process to
learn the table values that currently reside
in the kernel for a particular table type
and id. The ltable.type field specifies
which type of table is being queried, and
ltable.id specifies which ID is being
queried. The ltable.nid field specifies
which node's kernel is to be queried. If
ltable.nid is 0 or the node ID of the local
node, then the local kernel is queried.
Otherwise, the specified remote node ID is
queried. buf is assumed to point to an
array of long integers into which loadtabl
places the requested information.
Three of the ltable.types, DSNCB, DSOCB, and DSWCB, are
associated with ID translates. The fourth type, DSIPC,
is used when an IPC key mapping table is being loaded.
The fifth type is USERTBL, which is used to load tables
for international character support into the kernel. The
following sections describe the ID translate values
first, then the key map information, and, finally, the
international character support tables.
The ID translate types are:
DSNCB An inbound user ID or group ID translate table
for a particular node.
DSOCB A translate table for outbound requests.
DSWCB A translate table for the wild card node.
In all of these cases, the memory pointed to by buf con-
tains a dsxlate structure, which contains, among other
things, the first row of translate information, followed
by the rest of the translate rows. For DSNCB, the
ltable.id specifies which node ID's table is used.
The dsxlate structure is described in the sys/dstables.h
header file, and it contains the following members:
short rlvl; /* Reserved. Must be 0 - release level. */
short gid; /* Local wildcard group ID for this node. */
short uid; /* Local wildcard user ID for this node. */
char flag; /* The 0X01 bit is set if there is a wildcard */
/* user ID for this node. */
/* The 0X02 bit is set if there is a wildcard */
/* group ID for this node. */
char pad1; /* Dummy for alignment purposes */
short numuids; /* The number of user ID translate rows */
short numgids; /* The number of group ID translate rows */
short pad2; /* Dummy for alignment purposes */
struct idrow idrow[1|; /* First row of translate information */
/* Rest of the translates follow. */
The idrow structure is described in the sys/dstables.h
header file, and it contains the following members:
long wireid; /* ID that arrived with the request */
short localid; /* Local ID resulting from a translate */
short pad; /* Dummy for alignment purposes */
Note: For ltable.type values of DSNCB and DSWCB, the
entries in the user ID and group ID table arrays must be
ordered by increasing wireid. For a type value of DSOCB
(outbound translate table), the table must be ordered by
increasing localid.
There are occasions when an application needs to load an
entire set of new translates into the kernel. In the
normal processing sequence for such a case, the applica-
tion should:
1. Call the loadtbl system call with "ltable.type=DSNCB"
and "ltable.mode=L_QUERYT" to get a list of the node
IDs that currently have translates.
2. Compare the returned list of node IDs that currently
have translates to the list of node IDs that should
have translates after the new information is loaded.
3. Use L_DELETE to remove the node IDs that now have
translates, but should not.
4. Use L_REPLACE on the translates for the other nodes
(both node IDs that have existing translates and node
IDs that are not yet in the table).
The next ltable.type loads a different type of informa-
tion into the kernel than the ID translate types listed
earlier. When ltable.type is DSIPC, an IPC key mapping
table is being loaded. The value of ltable.id is ignored
for this type, and the entire set of IPC keys is loaded
as one piece of information. The memory pointed to by
buf should be an array of dsipc structures. The dsipc
structure is defined in the sys/dstables.h file, and it
contains the following members:
long inkey; /* Input key */
long nid; /* Node ID */
long outkey; /* Result key */
A dsipc.nid with a value of 0 indicates that the inkey is
to be mapped to the outkey in the local node. Otherwise,
the specified node is used.
The array should be sorted by inkey so that the msgget
subroutine can use a binary search to locate the
requested key translate.
The final ltable.type is used to load tables of a dif-
ferent nature than described above for Distributed Ser-
vices. When ltable.type is USERTBL, the table being
loaded into the kernel is used for international char-
acter support, such as a character collation and classi-
fication table. (See "Overview of International
Character Support" in Managing the AIX Operating System
for additional information on character collation and
classification.)
Return Value
Upon successful completion, the loadtbl system call
returns:
o For L_REPLACE, a value of 0.
o For L_DELETE, a value of 0.
o For L_QUERYI, a value of 0 if no table exists for the
type specified. Otherwise, the number of IDs of the
specified type is returned.
o For L_QUERYT, the number of bytes transferred.
If the loadtbl system call fails, a value of -1 is
returned, and errno is set to indicate the error.
Diagnostics
The loadtbl system call fails and the configuration
information remains unchanged if one or more of the fol-
lowing are true:
E2BIG buf is too small to contain query data.
EINVAL Invalid input data (such as invalid
ltable.type or ltable.mode, or an ltable.nid
that specifies a remote node when ltable.mode
is L_REPLACE or L_DELETE).
EPERM The ltable.mode is either L_REPLACE or
L_DELETE and the effective user ID of the
calling process is not superuser.
If Distributed Services is installed on your system, the
loadtbl system call also fails if one or more of the fol-
lowing are true:
EDIST Outbound requests are currently blocked.
EDIST The server has a release level of Distrib-
uted Services that cannot communicate with
this node.
EAGAIN The server is too busy to accept the
request.
ENOMEM Either this node or the server does not
have enough memory available to service the
request.
ENOCONNECT An attempt to establish a new network con-
nection with a remote node failed.
EBADCONNECT An attempt to use an existing network con-
nection with a remote node failed.
Related Information
In this book: "msgget."
The dsldxprof command in AIX Operating System Commands
Reference.
"Overview of International Character Support" in Managing
the AIX Operating System.
Managing the AIX Operating System.
AIX Operating System Programming Tools and Interfaces.