Suite/P Toolkit: Posix-Style Capabilities

Last revised: 17Mar2004 GLG

Table of Contents

Introduction

This document defines the suite-names and capability-names of Posix-style capabilities. It also describes the type that each capability-name returns by convention.

A platform need not be Posix-like in order to provide these capabilities. Many different OSes of various lineage have facilities that correspond to the capabilities listed here.

Suite Names

The following suite-names are defined in the interface glguerin.suitep.posix.PosixSuites. Each is listed as the Java variable-name, followed by the String value. The Java variable-names are listed in alphabetical order.

All suite-name strings contain the trailing dot delimiter.

ENV_SUITE = "env."
This suite-name provides access to environment-variables.

FILE_SUITE = "file."
This suite-name provides access to file-system facilities.

GROUPID_SUITE = "groupid."
This suite-name provides access to Posix-style groupid capabilities, such as a process's real and effective groupid, a Lookup for mapping between names and id's, and a Mutater for changing them.

LIMIT_SUITE = "limit."
This suite-name provides access to the rlimit(2) facilities, which defines process resource limits. Soft-limits and hard-limits are supported with distinct capability-names.

PROCESS_SUITE = "process."
This suite-name provides access to a process's process-ID, parent process-ID, scheduling priority (niceness), umask, and process-signalling facilities. etc.

USERID_SUITE = "userid."
This suite-name provides access to Posix-style userid capabilities, such as a process's real and effective userid, a Lookup for mapping between names and id's, and a Mutater for changing them.

The following suite-names are based on the BSD sysctl(2) function, and may not be available on some platforms. They are available on Mac OS X, however.
HW_SUITE = "hw."
This suite-name provides access to hardware information, including cpu type and speed, bus speed, physical RAM, etc.

KERN_SUITE = "kern."
This suite-name provides access to kernel configuration information.

USER_SUITE = "user."
This suite-name provides access to some of a user's default values, notably the default command-path.

ENV_SUITE Capabilities

There are no specific capability-names in this suite. Instead, you simply prefix ENV_SUITE to the environment-variable name you want retrieved, and pass the resulting String to Suite.get().

A String or null is returned for all environment-variable values.

Depending on the platform or implementation, the environment-variable's name may be case-sensitive. Mac OS X has case-sensitive names, and it's safest to assume so elsewhere.

FILE_SUITE Capabilities

There are no capability-names yet defined in this suite.

GROUPID_SUITE Capabilities

GROUPID_REAL = "groupid.real" -- returns a Number
Represents this process's current real groupid.

GROUPID_EFFECTIVE = "groupid.effective" -- returns a Number
Represents this process's current effective groupid.

GROUPID_SAVED = "groupid.saved" -- returns a Number
Represents this process's current saved groupid.

GROUPID_LOOKUP = "groupid.lookup" -- returns a Lookup
Represents a mapping between group-names and int group-IDs, for all group-IDs and group-names known on this platform.

Since it takes a relatively long time (10's of ms) to create the returned Lookup, callers should keep the Lookup if many lookups are to be performed. While a process is running, the group name/id database may be updated, but this will only be reflected in a Lookup created after the database update. Long-running processes should determine for themselves the best balance between caching the groupid Lookup and having the freshest data available.

GROUPID_MUTATER = "groupid.mutater" -- returns a Mutater
Represents a way for this process to change its real, effective, and/or saved groupid. The process must have appropriate privileges for the Mutater methods to succeed.

LIMIT_SUITE Capabilities

The following names represent soft-limit Parameters. To obtain the corresponding hard-limit Parameter, append the name PosixSuites.HARD, which is the String ".hard", to the soft-limit name before calling Suite.get().. Any process may lower a hard-limit, but only a privileged process may raise it.
LIMIT_COREDUMP = "limit.coredump" -- returns a Parameter
Represents this process's soft-limit on the size of a coredump file, measured in bytes.

LIMIT_CPU = "limit.cpu" -- returns a Parameter
Represents this process's soft-limit on CPU-time, measured in seconds.

LIMIT_DATA = "limit.data" -- returns a Parameter
Represents this process's soft-limit on data-segment size, measured in bytes.

LIMIT_DESCRIPTORS= "limit.descriptor" -- returns a Parameter
Represents this process's soft-limit on file-descriptors (open files, pipes, or sockets), measured as a count.

LIMIT_FILESIZE = "limit.filesize" -- returns a Parameter
Represents this process's soft-limit on the length of a single written file, measured in bytes.

LIMIT_MEMLOCK = "limit.memlock" -- returns a Parameter
Represents this process's soft-limit on the amount of memory locked in core (not swapped), measured in bytes.

LIMIT_PROCESS = "limit.process" -- returns a Parameter
Represents the soft-limit on the number of processes for the current userid, measured as a count.

LIMIT_RSS = "limit.rss" -- returns a Parameter
Represents this process's soft-limit on resident-set size, measured in bytes.

LIMIT_STACK = "limit.stack" -- returns a Parameter
Represents this process's soft-limit on stack-segment size, measured in bytes.

PROCESS_SUITE Capabilities

PROCESS_ID = "process.id" -- returns a Number
Represents this process's process ID.

PROCESS_ID_PARENT = "process.id.parent" -- returns a Number
Represents this process's parent-process ID. The parent-process ID may change, if a process's parent terminates before the child process does. The orphaned process is then reassigned a new parent process, but the exact parent process is specific to a platform and implementation.

PROCESS_GROUP = "process.group" -- returns a Number
Represents this process's process group ID. The process group can be changed with a Processing imp.

PROCESS_NICE = "process.nice" -- returns a Parameter
Represents this process's native scheduling priority. Under Posix, higher numbers are less favorable, i.e. "nicer" to other processes. See 'man nice'.

PROCESS_UMASK = "process.umask" -- returns a Parameter
Represents this process's mask affecting the initial access-permissions assigned to newly created files and directories. See 'man 2 umask'.

PROCESS_PROCESSING = "process.processing" -- returns a Processing imp
Provides the way to obtain the process ID of a java.lang.Process instance, and manage the affiliation of processes into process groups.

PROCESS_SIGNALLER = "process.signaller" -- returns a Signaller
Represents the means for this process to send signals, and to obtain a related SignalReceiver.

PROCESS_SIGNALRECEIVER = "process.signalreceiver" -- returns a SignalReceiver
Represents the means for this process to manage the reception of signals, and to obtain a related Signaller.

USERID_SUITE Capabilities

USERID_REAL = "userid.real" -- returns a Number
Represents this process's current real userid.

USERID_EFFECTIVE = "userid.effective" -- returns a Number
Represents this process's current effective userid.

USERID_SAVED = "userid.saved" -- returns a Number
Represents this process's current saved userid.

USERID_SUPERPOWERS = "userid.superpowers" -- returns a Boolean
Represents whether this process currently has or can obtain root privileges (superpowers).

USERID_LOOKUP = "userid.lookup" -- returns a Lookup
Represents a mapping between user-names and int user-IDs, for all user-IDs and user-names known on this platform.

Since it takes a relatively long time (10's of ms) to create the returned Lookup, callers should keep the Lookup if many lookups are to be performed. While a process is running, the user name/id database may be updated, but this will only be reflected in a Lookup created after the database update. Long-running processes should determine for themselves the best balance between caching the userid Lookup and having the freshest data available.

USERID_MUTATER = "userid.mutater" -- returns a Mutater
Represents a way for this process to change its real, effective, and/or saved userid. The process must have appropriate privileges for the Mutater methods to succeed.

HW_SUITE Capabilities

HW_BYTEORDER = "hw.byteorder" -- returns a Number
Represents the native byte-order, where 4321 means big-endian and 1234 means little-endian.

HW_BUS_FREQ = "hw.busfrequency" -- returns a Number
Represents the frequency of the main memory bus, measured in Hertz (cycles per second). For example, a 25 MHz bus-frequency returns a Number having the value 25000000.

HW_CPU_FREQ = "hw.cpufrequency" -- returns a Number
Represents the highest frequency of the CPU, measured in Hertz (cycles per second). When the CPU frequency is variable, as in certain power-saving modes of laptops, the returned value is the highest attainable CPU frequency. For frequencies above 2 GHz, be sure to use Number.longValue() rather than intValue().

HW_MACHINE = "hw.machine" -- returns a String
Represents the kind of machine.

HW_MODEL = "hw.model" -- returns a String
Represents the model of machine.

HW_NCPU = "hw.ncpu" -- returns a Number
Represents the number of CPUs available.

HW_PHYSMEM = "hw.physmem" -- returns a Number
Represents the total amount of physical memory, measured in bytes.

HW_USERMEM = "hw.usermem" -- returns a Number
Represents the amount of physical memory available for non-kernel use, measured in bytes.

HW_VECTORUNIT = "hw.vectorunit" -- returns a Number
Represents whether the CPU has a vector-unit (1) or not (0). On Mac OS X on PowerPCs, this signifies AltiVec (Velocity Engine) presence.

KERN_SUITE Capabilities

KERN_ARGMAX = "kern.argmax" -- returns a Number
Represents the largest amount of memory that the args to a new process can consume, measured in bytes.

KERN_HOSTNAME = "kern.hostname" -- returns a String
Represents this machine's host-name at boot, which may or may not be the current host-name.

KERN_MAXFILES = "kern.maxfiles" -- returns a Number
Represents the maximum number of simultaneously open file-descriptors system-wide.

KERN_MAXPROC = "kern.maxproc" -- returns a Number
Represents the maximum number of simultaneous processes system-wide.

KERN_MAXVNODES = "kern.maxvnodes" -- returns a Number
Represents the maximum number of vnodes in the kernel.

KERN_OSRELEASE = "kern.osrelease" -- returns a String
Represents the kernel's release level, which need not correspond to the OS product-release level. For example, Mac OS X 10.2.3 returns "6.3" for this value.

KERN_OSREV = "kern.osrev" -- returns a Number
Represents the kernel's OS revision level, which may have no evident relationship to any known product version.

KERN_OSTYPE = "kern.ostype" -- returns a String
Represents the kernel's OS type-name. On Mac OS X, this returns "Darwin".

KERN_POSIX1 = "kern.posix1version" -- returns a Number
Represents the Posix-1 compliance version.

KERN_SECURELVL = "kern.securelevel" -- returns a Number
Represents the current kernel security level.

USER_SUITE Capabilities

USER_POSIX2_VERSION = "user.posix2_version" -- returns a Number
Represents the Posix-2 compliance level.

USER_CS_PATH = "user.cs_path" -- returns a String
Represents the default value for the command-path, whose current value is the "PATH" environment-variable.

To Greg's Home Page
To Greg's Software Page