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