NAME
table - examine/update element(s) from system table

SYNOPSIS
#include <sys/table.h>

cel = table(id, index, addr, nel, lel)
int cel, id, index;
void *addr;
int nel;
size_t lel;

DESCRIPTION
The table call is used to examine and/or update selected elements
from certain system tables. The desired table is identified by id
and a particular element within that table is selected by index.

The value of each element is copied to/from the specified addr. The
magnitude of nel specifies the number of elements to copy while its
sign indicates the transfer direction. When the number of elements
to transfer is positive, the direction is from the kernel to addr,
in effect a "read" operation. When the number of elements to
transfer is negative, the direction is from addr into the kernel,
in effect a "write" operation.

The expected size of a single element is specified by lel and
successive transfer addresses are calculated from addr by
incrementing it by this size for each element copied. If the
actual element size is larger, then excess data is truncated from
the end of each element returned to addr during an examine and only
the expected size is stored from addr during an update. If the
actual element size is smaller, then holes are left between
elements returned to addr during an examine and excess data is
truncated from the end of each each element stored from addr during
an update.

All changes to system table elements are guaranteed to be made in
such a way that each field within the element structure remains at
a constant offset and size, and that new fields are added only at
the end of an element.

The count of elements examined or updated is returned as cel. A
call with an element length of 0 and number of elements set to the
maximum positive integer can be used to determine the length of a
table (in elements) before actually requesting any of the data.
The id parameter specifies one of the following tables.

TBL_TTYLOC - terminal location information table.

The index is by device number which is incremented by one for
successive elements. Each element is a ttyloc structure as
described in tty(4).

The terminal location information cannot be updated by this
call.

TBL_U_TTYD - controlling terminal device number table.

The index is by process ID and exactly one element may be
requested. If the process ID is zero, then the current
process is indexed (only zero or the current process ID are
supported for now). Each element is of type dev_t as defined
in <sys/types.h>.

The controlling terminal device number cannot be updated by
this call.

TBL_UAREA - U-area table.

The index is by process ID which is incremented by one for
successive elements.

Additional details to be supplied.

The contents of the U-area cannot be updated by this call.

TBL_LOADAVG - system load average vector (pseudo-)table.

The index must be zero and exactly one element may be
requested. This element has the following structure:

struct tbl_loadavg {
union {
long l[3];
double d[3];
} tl_avenrun;
int tl_lscale;
};

If the scale is zero, then the load average vector is the
floating point variant. If the scale is non-zero, then the
load average vector has been scaled by the indicated factor
(typically 1000) to produce the long integer variant.

The load average vector cannot be updated by this call.

TBL_INCLUDE_VERSION - system include file version number
(pseudo-)table.

The index must be zero and exactly one element may be
requested. The include version is an integer which serves as
a unique identifer associated with the layout of kernel data
stuctures which are imported by certain kernel dependent
programs such as ps(1).

The include version number cannot be updated by this call.

TBL_FSPARAM - file system parameters (pseudo-)table.

To be supplied.

TBL_ARGUMENTS - process command argument table.

To be supplied.

TBL_MAXUPRC - maximum process count per user-ID table.

The index is by process ID and exactly one element may be
requested. If the process ID is zero, then the current
process is indexed (only zero or the current process ID are
supported for now). The element is a short integer.

The maximum count includes all processes running under the
current user-ID even though the limit affects only the current
process and any children created with that limit in effect.

The limit may only be changed by the super-user.

TBL_AID - account ID table.

The index is by process ID and exactly one element may be
requested. If the process ID is zero, then the current
process is indexed (only zero or the current process ID are
supported for now). The element is of type u_short. as
defined in <sys/types.h>.

The account ID is stored in the accounting record recorded by
the system at process exit time as described in acct(5)*.

The account ID may only be changed by the super-user.

TBL_MODES - process modes table.

The index is by process ID and exactly one element may be
requested. If the process ID is zero, then the current
process is indexed (only zero or the current process ID are
supported for now). The element is an integer with bits
defined in <sys/syscalls.h> as:

UMODE_P_GID
Use the standard 4.3BSD semantics of assigning the group
ID of the parent directory to newly created i-nodes. At
CMU-CS, the default is to assign the current group ID of
the running process as was the case in 4.1BSD.

UMODE_NOFOLLOW
Do not follow remote or symbolic links when they are
encountered as the last comonent of a pathname. When
this mode bit is set for a process, all references to such
links access the link itself rather than interpreting its
contents as would normally be the case.

UMODE_NONICE
Do not automatically lower the scheduling priority of
long-running processes when they exceed the CPU time
threshhold (typically 10 minutes).

This is the default for workstation configurations.

TBL_PROCINFO - process status information table.

The index is by process slot which is incremented by one for
successive elements. An element is a tbl_procinfo structure
defined as:

#define PI_COMLEN 19 /* length of command name */
struct tbl_procinfo {
int pi_uid; /* user ID */
int pi_pid; /* proc ID */
int pi_ppid; /* parent proc ID */
int pi_pgrp; /* proc group ID */
int pi_ttyd; /* controlling terminal number */
int pi_status; /* process status: */
#define PI_EMPTY 0 /* - no process */
#define PI_ACTIVE 1 /* - active process */
#define PI_EXITING 2 /* - exiting */
#define PI_ZOMBIE 3 /* - zombie */
int pi_flag; /* other random flags */
char pi_comm[PI_COMLEN+1]; /* short command name */
};

The process status information cannot be updated by this call.

The table system call is unique to the Mach environment and is not
part of a standard BSD system.

RETURN VALUE
A positive return value indicates that the call succeeded for that
count of elements. A return value of -1 indicates that an error
occurred, and an error code is stored in the global location errno.

ERRORS
The possible errors are:

[EFAULT] The address specified for addr is invalid.

[EINVAL] The table specified by id is not defined.

[EINVAL] The index specified by index does not exist in the
specified table.

[EINVAL] The specified table admits only an index of the
current process ID with exactly one element and some
other index or element number was specified.

[EINVAL] An element length of zero was supplied for the
TBL_ARGUMENTS table.

[EINVAL] An attempt is made to update an element which cannot
be changed by the table call.

[EPERM] An attempt is made to change the maximum number of
processes or account ID, and the caller is not the
super-user.

[ESRCH] The process given by a process ID index cannot be
found.

SEE ALSO
setmodes(1)*, acct(2)*, tty(4), acct(5)*

BUGS
The restrictions on referencing only the current process should be
lifted.

__________
* Not currently supported under MachTen