wlm.h File

Purpose

Defines the constants, data structures and function prototypes used by the Workload Manager (WLM) Application Programming Interface (API) subroutines.

Description

The wlm.h file defines the wlm_args, wlm_assign, wlm_info, wlm_bio_class_info_t, and wlm_bio_dev_info_t, and wlm_proc_info structures. These structures are used by the WLM API functions in the libwlm.a library.

The wlm_args Structure

The wlm_args structure is used to pass class information to WLM when using the API functions to create, modify or delete a class. The wlm_args structure contains the following fields:

versflags

Specifies the 4 high-order bits that contain a version number used by the API to maintain binary compatibility if the data structures are ever modified. The rest of the integer is used to pass flags to the subroutines when needed.

This field should be initialized with a logical OR operation between the version number WLM_VERSION and whatever flags are needed by the target subroutine. One flag common to all the API calls is WLM_MUTE, which is used to suppress the output of error messages from the WLM library to STDERR.

confdir

Specifies a null-terminated string. This field must be initialized with the name of the WLM configuration to which the target subroutine applies (when applicable, depending on the particular one).

Alternatively, this field can be set to a null string (\0). The null string indicates that the class addition or modification is to be applied only to the WLM kernel data, not to the class description files.

class

This field is a structure of type struct class_definition that contains all the information pertaining to the superclass or subclass that is needed by the target subroutine. The fields in this structure can be initialized by a call to the wlm_init_class_definition subroutine so that you only need to initialize the fields you wish to modify.

The main structure in the wlm_init_class_definition subroutine is the class description, struct class_descr, with the following fields:

res

Specifies an array of type struct wlm_bounds that contains the following fields for each resource type and for each total limit:

iopriority

Specifies the priority for I/O requests that are issued by the threads that are classified to the class. This priority is used to prioritize I/O buffers at the device level. Valid I/O priorities range from 0 through 15.

min

Specifies the minimum value, which is between 0 (the default) and 100 (unused for total limits).

shares

Specifies the shares number, which is a value between 1 and 65535. The value -1 (default) indicates that the given resource is not managed by WLM for the class (unused for total limits).

wlmu

The union which contains the softmax (for all resources but total limits) and unit (for total limits only) fields:

softmax: Specifies the soft maximum limit, which is a value between 0 and 100 (default). The value must be greater than or equal to the value of the min field.
unit: A string (3 characters maximum) that specifies the units that apply to the hardmax value for total limits. To let the units remain undefined, set the softmax field to WLM_UNIT_UNDEF. For WLM_RES_TOTALCONNECT and WLM_RES_TOTALCPU, the default unit is "s" (seconds) and other values are "m" (minutes), "h" (hours), "d" (days), and "w" (weeks). For WLM_RES_TOTALDISKIO, the default unit is "KB" (kilobytes) and other values are "MB" (megabytes), "GB" (gigabytes), "TB" (terabytes), "PB" (petabytes), "EB" (exabytes). The other total limits do not have units. For WLM_RES_TOTALVMEM and WLM_RES_PROCVMEM, set the unit to "MB", "GB", and "TB".

hardmax

For all resources but total limits. Specifies the hard maximum limit, which is a value between 0 and 100 (default). The value must be greater than or equal to each of the values of the min and softmax fields. For total limits, this parameter specifies their value, possibly along with the unit field. If the user does not specify a units value, the default units value is used. However, the user can specify a units value other than the default. The default (total limit unspecified) is WLM_HARDMAX_UNDEF.

The resource types are defined as WLM_RES_CPU, WLM_RES_MEM, WLM_RES_BIO, and total limits are defined as WLM_RES_TOTALCPU (total CPU time for a process), WLM_RES_TOTALDISKIO (total disk IOs for a process), WLM_RES_TOTALCONNECT (total Connection time), WLM_RES_TOTALPROC (total number of processes), WLM_RES_TOTALTHRD (total number of Threads), WLM_RES_TOTALLOGIN (total number of login sessions), WLM_RES_TOTALVMEM (total virtual memory usage for a class) and WLM_RES_PROCVMEM (total virtual memory usage for a process). Each value represents the index in the array of the element, corresponding to the type of resource or total limit.

tier

Specifies the tier number for the class, which is a value between 0 (default) and 9

inheritance

Specifies how a new process is classified. A value of 0 (the default) indicates that a new process should be classified using the class assignment rules when calling the exec subroutine. A value of 1 indicates that the process inherits the class assignment from its parent process.

localshm

Indicates whether memory segments in this class remain local to the class (value 1) or if they go to the Shared class (value 0, the default), when accessed by a process belonging to another class.

assign_uid

Specifies the user ID of the user allowed to manually assign processes to the class. The value must be a valid user ID.

The default when this attribute is not specified is that no user is authorized (WLM_NOGUID).

assign_gid

Specifies the group ID of the users allowed to manually assign processes to the class. The value must be a valid group ID. The value must be a valid group ID. The default when this attribute is not specified is that no group is authorized (WLM_NOGUID).

If both the assign_uid and assign_gid fields are the default value, only the root user can assign processes to the class.

admin_uid

Specifies the user ID of the user allowed to administer the subclasses of the superclass (this attribute is valid only for superclasses)

admin_gid

Specifies the group ID of the users allowed to administer the subclasses of the superclass (this attribute is valid only for superclasses)

If both the admin_uid and admin_gid fields are left to their default value (WLM_NOGUID), only the root user can administer the subclasses of this superclass.

name

Specifies the null-terminated full name of the class. The value must be in the format super_name for a superclass and super_name.sub_name for a subclass. The superclass name and subclass name are limited to 16 characters each. This field has no default value.

In addition to the class description fields, the class_definition structure adds two more fields:

rset_name: Specifies a null-terminated character string containing the name of the resource set (partition) that the class is restricted to, when applicable. The default is that the class can access all the resources on the system.
descr_field: Specifies a null-terminated character string containing the description text of the class. This field is optional and has no default.
delshm: Specifies whether to delete shared memory segments if the last process referencing the segment was killed due to a virtual memory limit. Valid values are "yes" and "no" (default).
vmenforce: Specifies whether the faulting process (value "proc", default) or all processes in a class (value "class") are killed when a virtual memory limit is reached.

The wlm_assign Structure

The wlm_assign structure is used to manually assign processes or groups of processes to a specified superclass or subclass using the wlm_assign subroutine. The wlm_assign structure contains the following fields:

Item	Description
wa_versflags	Specifies the 4 high-order bits containing a version number. This version number is used by the API to maintain binary compatibility if the data structures are ever modified. The rest of the integer is used to pass flags to the subroutines when needed. This field should be initialized with the version number WLM_VERSION. The flag WLM_MUTE can be used to suppress the output of error messages from the WLM library on stderr.
wa_pids	Specifies the address of an array containing the process identifiers (PIDs) of the processes to be manually assigned
wa_pid_count	Specifies the number of PIDs in the array above
wa_pgids	Specifies the address of an array containing the process group IDs (PGIDs) of the process groups to be manually assigned
wa_pgid_count	Specifies the number of PGIDs in the array above
wa_classname	Specifies the full name of the superclass or the subclass of the class to which you want to manually assign processes

The wlm_info Structure

The wlm_info structure is used to extract information about the current configuration parameters and current resource utilization of the active classes using the wlm_get_info subroutine. The wlm_info structure contains the following fields:

Item	Description
i_descr	Specifies the class description of type struct class_descr
i_regul	Specifies the per-resource-type array of structures, which are of the type struct wlm_regul, containing the following fields: consum Specifies the resource consumption of the class. This value is expressed as a percentage of the total resource available. total Specifies the 64-bit number that represents the total amount of the resource consumed by the class since its creation (or since WLM was started). The value can be the number of milliseconds for CPU or the total number of 512-byte blocks for disk I/O. This field is left null (not significant) for memory. The indexes into the array of the various resources are defined as WLM_RES_CPU, WLM_RES_MEM and WLM_RES_BIO.
i_class_id	Specifies the class identifier (index of the class in the kernel class_control_block (ccb) table)
i_cl_pri	Specifies the priority delta applied to the threads in the class for CPU regulation
i_cl_inuse	Specifies the current number of processes in the class
i_cl_nblogins	Specifies the current number of logins in the class.
i_cl_nbthreads	Specifies the current number of threads in the class.
i_cl_npages	Specifies the number of memory pages currently allocated to the class
i_cl_nvpages	Specifies the total virtual memory usage for the class.
i_cl_nvpagehi	Specifies the virtual memory usage high water mark.
i_cl_mem_hwm	Specifies the maximum number of resident memory pages this class had since its creation (memory high water mark)
i_cl_change_level	Specifies the number of increments each time a change in the current WLM configuration occurs. This field is used by the WLM monitoring tools.

The wlm_bio_class_info_t and wlm_bio_dev_info_t Structures

Two structures can be used to get the I/O statistics using the wlm_get_bio_stats subroutine, depending on whether the application wants per-class or per-device statistics.

The wlm_bio_class_info_t structure is used to gather I/O statistics per class and per device. The wlm_bio_class_info_t structure contains the following fields:

Item	Description
wbc_dev	Specifies the device identifier (dev_t)
wbc_cid	Specifies the class identifier (index of the class in the kernel class_control_block table). Connecting the class ID and the class name can be performed by using the wlm_get_info subroutine. This subroutine returns the class name (in the i_descr field) and the class ID (in the i_class_id field) in the wlm_info structure.
wbc_regul	Specifies a structure of type struct wlm_regul, which contains for the given class and device the following disk I/O statistics: Resource utilization, which is expressed as a percentage of the total available throughput of the device (consum) Total number of 512-byte blocks read/written from and to the device by processes in the class since it was created, or since WLM started, whichever happened most recently
wbc_delay	Specifies in milliseconds the delay imposed on the I/Os of the processes in the class to the device. This delay is intended to limit utilization by class when it is consuming more than its entitled share.

The wlm_bio_dev_info_t structure is used to gather the global statistics for a given device, taking into account all I/Os to and from the device by all the classes accessing the device. This structure contains the following fields:

Item	Description
wbd_dev	Specifies the device identifier (dev_t)
wbd_active_cntrl	Specifies the number of classes actively accessing the device
wbd_in_queue	Specifies the number of requests in the device queue
wbd_last	Specifies the device statistics for IOs that occurred during the last second. This field is an array of integer values. The following symbolic values defined in the wlm.h file describe each index in the array: Index Description WBS_OUT_RTHRPUT Specifies the number of blocks actually read from the device (I/O completed) WBS_OUT_WTHRPUT Specifies the number of blocks actually written to the device (I/O completed) WBS_IN_RTHRPUT Specifies the requested number of blocks to be read from the device WBS_IN_WTHRPUT Specifies the requested number of blocks to write to the device WBS_REQUESTS Specifies the number of read/write requests WBS_QUEUED Specifies the number of requests queued WBS_STARVED Specifies the number of requests starved (not serviced during the time interval)
wbd_max	Contains the maximum values observed since the device was first used (after WLM was started) for all the entries of the array being described. For instance, the wbd_max field could contain the maximum number of blocks actually read from the device in one second since the device was first accessed.
wbd_av	Contains the average values for all the entries in the array, such as the average number of requests in the device queue
wbd_total	Specifies an array of 64-bit integers. This array is parallel to the arrays that, for every entry, contain the total of all the values measured every second since the device was first accessed. For instance, the value could represent the total number of blocks written to the device since the device was first accessed.

The wlm_proc_info Structure

The wlm_proc_info structure is used to extract Workload Manager information about a process using the wlm_get_procinfo subroutine. The totalconnecttime, termtime, totalcputime, totaldiskio fields are only meaningful when the total process limits are enabled. The wlm_proc_info structure contains the following fields:

version: This field should be initialized with WLM_VERSION.
wlmflags: Specifies some Workload Manager properties of the process, such as process with a rset SWLMRSET or as tag inheritance on fork SWLMTAGINHERITFORK or on exec SWLMTAGINHERITEXEC.
totalconnecttime: Specifies the 64-bit number that represents the amount of time (in seconds) for which the login session has been active.
totalvmem: Specifies the total amount of virtual memory used by the process in MBs.
termtime: Specifies the 64-bit number that represents the time (in seconds from 1970) when the process has been requested to terminate.
totalcputime: Specifies the 64-bit number that represents the amount of the CPU consumption (in microseconds) of the process.
totaldiskio: Specifies the 64-bit number that represents the amount of IO (in 512 bytes blocks) the process has run.
classname: Specifies the full name of the superclass or the subclass in which the process is classified.
tag: Specifies the character string associated with the process, if any ( see wlm_set_tag subroutine).

Error Codes

The various WLM API subroutines may return one or several of the following error codes:

Item	Description
WLM_ALREADYINIT	A call to the wlm_initialize subroutine has already been made
WLM_ATTERR	Attribute format error
WLM_ATTGPATTR	Attribute Value Grouping not allowed in attributes
WLM_ATTGPMISS	Cannot find Attribute Value Grouping definition
WLM_ATTGPTOOLNG	Attribute Value Grouping too long
WLM_BADATTAPP	Could not access file (application field of attributes)
WLM_BADATTGP	Bad format for Attribute Value Grouping
WLM_BADATTGRP	Unknown group in attributes
WLM_BADATTTAG	Invalid tag in attributes
WLM_BADATTTYP	Invalid process type in attributes
WLM_BADATTUSR	Unknown user in attributes
WLM_BADCLNAME	Bad class name
WLM_BADCNAME	Class names must be alphanumeric
WLM_BADCONFIG	Invalid configuration name
WLM_BADDEFLIM	Default limits value that is specified in the limits file is invalid
WLM_BADDEFSHR	Default shares value that is specified in the shares file is invalid
WLM_BADFLAGS	Invalid flags value
WLM_BADGID	The specified group ID is not valid on the system
WLM_BADGRP	The specified group ID is not valid on the system
WLM_BADINHER	The value specified for the class inheritance attribute is invalid
WLM_BADHARDTOTALLIMIT	Invalid total limit (under minimum)
WLM_BADHMAX	The hard maximum limit values must be between 1 and 100
WLM_BADLIMFMT	Value specified for minimum or maximum resource limit is invalid
WLM_BADLISATT	Invalid list in attributes
WLM_BADLIST	The process attribute list of an assignment rules is invalid
WLM_BADLOCALSHM	Bad localshm value
WLM_BADMIN	Minimum resource limits values must be between 0 and 100
WLM_BADRANGEF	Invalid format for a time range
WLM_BADRGRP	A group name specified in the rules file is invalid on the system
WLM_BADRSET	Bad Rset attribute for a class
WLM_BADRUSR	A user name specified in the rules file is invalid on the system
WLM_BADSHARES	Shares values must be between 1 and 65535
WLM_BADSMAX	The soft maximum limit values must be between 1 and 100

Item	Description
WLM_BADSHRFMT	Value specified for resource shares is invalid
WLM_BADSUBLIMIT	A subclass total limit exceeds its superclass limit: The superclass limit will be used (warning)
WLM_BADSUPER	Bad superclass for subclass assignment
WLM_BADTIER	Tier values must be between 0 and 9
WLM_BADTAG	An invalid tag is specified in a rule
WLM_BADTYP	Invalid process type in rules
WLM_BADUID	The specified user ID is not valid on the system
WLM_BADUSR	The specified user ID is not valid on the system
WLM_BADVERS	Bad version number passed in the versflags field
WLM_CANTASSIGN	Could not make assignment (Internal error)
WLM_CANTCHECK	Unable to check the configuration
WLM_CANTSETTAG	Could not set tag (Internal error)
WLM_CHOWNERR	Cannot change file ownership
WLM_CLASSLIMIT	A class total (process, thread, or login) limit has been reached
WLM_CLASSMIS	No class description found
WLM_CONFNOTFND	No configuration found for this time
WLM_CONFNOTINSET	Configuration not found in the set
WLM_CREATERR	A file could not be created
WLM_DAEMONCMD	Invalid WLM daemon command
WLM_DAEMONFAIL	WLM daemon failed to update configuration
WLM_DUPKEY	2 classes have the same key (warning)
WLM_EFAULT	Bad parameter address
WLM_EMPTYATTR	No valid process attributes found
WLM_EMPTYRULE	None of the file names specified in the application field of an assignment rule could be accessed. The rule is ignored (warning).
WLM_EPERM	Permission denied
WLM_ESRCH	No such processes
WLM_EXCLATTR	Exclusions not allowed in attributes
WLM_EXISTS	The specified class already exists
WLM_HASSUBS	The target superclass has subclasses
WLM_IGNRULE	This rule is likely to be ignored (warning)
WLM_ISCONFSET	This operation cannot apply to a configuration set
WLM_INVRANGE	Invalid time range
WLM_ISLOCKED	WLM configuration is locked: retry the operation later
WLM_LOADERR	A class cannot be loaded into the kernel

Item	Description
WLM_LOCKERR	Cannot lock file
WLM_MANYRULES	Too many assignment rules
WLM_MANYITEMS	Too many items in an assignment rule
WLM_MAXCLASSES	The maximum number of classes has been reached
WLM_MINSMAX	The minimum limit cannot be greater than the soft maximum limit
WLM_MKDIRERR	A directory could not be created
WLM_MULTATTGP	Attribute Value Grouping already defined
WLM_MULTATTR	Multiple specifications not allowed in attributes
WLM_NOADMINSUB	Admin attributes not applicable to subclasses
WLM_NOCLASS	The specified class does not exist
WLM_NOCONFIG	Missing configuration name
WLM_NOCONFINSET	No configuration in the set
WLM_NOCONNECT	Failure to connect to WLM daemon
WLM_NODAEMON	Failure to start WLM daemon
WLM_NOMEM	Not enough memory
WLM_NOSHRLIM	Cannot specify a total memory limit for Shared class
WLM_NOSHRRULE	Cannot specify rule for Shared class
WLM_NOSUBS	The target superclass has no subclasses
WLM_NOSYSLIM	Cannot specify a total memory limit for System class
WLM_NOSYSMAX	Hardmax not allowed on memory for System class
WLM_NOTASSGND	Process is not assigned
WLM_NOTCOMPLETE	Could not assign all processes (warning)
WLM_NOTCURRENT	Superclass update only applies to current configuration
WLM_NOTINITED	No prior call to the wlm_initialize subroutine
WLM_NOTRUNNING	WLM is not running
WLM_NOWILDCRD	Wildcards not allowed in this field
WLM_ONEDEFAULT	Only one default time range allowed in a set
WLM_OPENERR	A file could not be opened
WLM_QUERYERR	Cannot query WLM state
WLM_READERR	Cannot read file
WLM_REFRULE	A class is still referred to by rules
WLM_REMERR	An attempt to remove a file did not succeed
WLM_RENAMERR	An attempt to rename a file did not succeed
WLM_RMPREDEF	Predefined classes (such as Default and System) cannot be removed
WLM_RNOCLASS	A class specified in the rules file does not exist

Item	Description
WLM_RSVDNAME	Predefined classes cannot be redefined
WLM_RULERR	An assignment rule has an invalid format
WLM_RULESERR	The assignment rules table cannot be loaded into the kernel
WLM_RULTOOLNG	Rule too long
WLM_RUNERR	The WLM library was not able to execute a command needed for the specific function. This is not an application error, but most likely a system administration problem. The commands used by the library are basic operating system commands such as the lsuser, lsgroup, echo, and grep commands.
WLM_RUNERRATT	Cannot expand attribute
WLM_SETERR	The WLM state transition requested is illegal
WLM_SHAREDLIM	Shared class can have shares and limits set only for memory
WLM_SHAREDSUB	Shared superclass cannot have subclasses
WLM_SMAXHMAX	The soft maximum limit cannot be greater than the hard maximum limit
WLM_STATERR	One or more file name(s) specified in the application field of an assignment rule could not be accessed. The corresponding name(s) are ignored (warning)
WLM_SUBINVALID	No subclass specification allowed for this operation
WLM_SUMMINS	The sum that the minimum limits for a given resource and a given tier cannot exceed 100%
WLM_SYMLERR	An attempt to create a symbolic link did not succeed
WLM_TAGTOOLONG	Tag is too long
WLM_TOOLONG	The specified class name is too long
WLM_TOOLONGATT	Attribute list too long
WLM_TOOMANYATT	Too many items in attributes
WLM_TOOMANYPID	Process ID list too long
WLM_TOOSMALL	Output buffer too small
WLM_TOTALLIMITOUTOFRANGE	Invalid total limit (outside allowed range)
WLM_TRGAPS	Gaps between time ranges in a configuration set
WLM_TRINDEFAULT	Time range not allowed in default stanza
WLM_TROVERLAP	Time ranges overlap in a configuration set
WLM_UNLOADERR	Cannot unload class
WLM_UNSUPP	Operation or flags value not supported
WLM_WILDCRDATT	Wildcards not allowed in this attribute field
WLM_WRITERR	An attempt to write to a file did not succeed