wlm_classify Subroutine

Purpose

Determines which classes a process is assigned to.

Library

Workload Manager Library (libwlm.a)

Syntax

#include <sys/wlm.h>

int wlm_classify ( config,  attributes,  class,  len)

char *config;

char *attributes;

char *class;

int *len;

Description

The wlm_classify subroutine must be passed the name of a valid configuration and a set of process attributes in a format identical to the format of the rules file (assignment rules). The names of the classes are copied into the area pointed to by class. The integer pointed to by len contains the size of the class names area on input and the number of matches on output. If the area pointed to by class is not big enough to contain the names of all the potential matches, an error is returned.

The normal use of the wlm_classify routine is to explicitly provide all the process classification attributes: user name, group name, application pathname, type, and tag when applicable. This gives a match to a single class. To implement "what if" scenarios, the interface allows you to leave some of the attributes unspecified by using a hyphen ('-') instead. This may lead to multiple classes the process could be assigned to, depending on the values of the unspecified attributes. If all the attributes are left unspecified, an error is returned.

The attributes string is provided in a format identical to the format of the attributes in the rules file: a list of attribute values separated by spaces. The order of the attributes in the assignment rules is:

  1. reserved: must be a hyphen ('-')
  2. user name
  3. group name
  4. application pathname
  5. type of application
  6. tag

Each field can have at most one value. Exclusion (!), attribute value groupings ($), comma separated lists and wild cards are not allowed. For the type field, the AND operator "+" is allowed, since a process can have several of the possible values for the type attribute at the same time. For instance a process can be a 32 bit process and call plock, or be a 64 bit fixed priority process.

Here are examples of valid attributes strings:

"- bob staff /usr/bin/emacs - -"

"- - - /usr/sbin/dbserv - _DB1"

"- - devlt - 32bit+fixed"

"- sally"

The class name(s) returned by the function in the class buffer is fully-qualified, null-terminated class names of the form supername.subname.

This function does not require any special privileges and can be called by all users.

Parameters

Item Description
config Specifies a pointer to a string containing the name of a valid Workload Manager (WLM) configuration (the name of a subdirectory of /etc/wlm). If a null string ('\0') is given, the wlm_classify subroutine uses current as the default configuration.

If the configuration is a set of time-based configurations, either because config or current is a configuration set, the subroutine will apply to the currently applicable configurations of the set.
attributes Specifies the address of a string, with the format described above, containing a list of values for the process attributes used for automatic classification of processes.
class Specifies a pointer to a buffer where the name of the class the process could be assigned to is returned as consecutive null-terminated character strings.
len Specifies a pointer to an integer containing the length in bytes of the buffer pointed to by class when calling wlm_classify and the actual number of class names copied into the class buffer upon successful return.

Return Values

Upon successful completion, the wlm_classify subroutine returns a value of 0. In case of error, a non-0 value is returned.

When a non-0 value is returned, the content of the class buffer and the value of the integer pointed to by len are unspecified.

Error Codes

For a list of the possible error codes returned by the WLM API functions, see the description of the wlm.h header file.