rs_registername Subroutine

Purpose

Registers a resource set definition in the system resource set registry.

Library

Standard C library (libc.a)

Syntax

#include <sys/rset.h>
int rs_registername(rset, namespace, rsname, mode, command)
rsethandle_t rset;
char *namespace, *rsname;
unsigned int mode, command;

Description

The rs_registername subroutine registers in the system resource registry (within the name space identified by namespace) the definition of the resource set identified by the rset handle. The rs_registername subroutine does this by associating with it the name specified by the null terminated string structure pointed to by rsname.

If rsname does not exist, the owner and group IDs of rsname are set to the caller's owner and group IDs, and the access control information for rsname is set according to the mode parameter.

If rsname already exists, its owner and group IDs and its access control information are left unchanged, and the mode parameter is ignored. This name can be shared with any applications to identify a dedicated resource set.

Using the command parameter, you can ask to overwrite or not to overwrite the rsname parameter's registration if it already exists in the global repository within the name space identified by namespace. If rsname already exists within the specified name space and the command parameter is set to not overwrite, an error is reported to the calling process.

The namespace sysxrset is reserved for exclusive rsets. When an exclusive rset is created, the state of CPUs in the rset is modified so that those CPUs only run work that is directed to them. See Exclusive use processor resource sets in AIX® Version 7.1 Operating system and device management and the mkrset command for more information. Root privilege or CAP_NUMA_ATTACH capability is required to create or remove an exclusive rset. An exclusive rset cannot be overwritten.

Note:
  1. Registering a resource set definition can only be done by a process that has root authority or CAP_NUMA_ATTACH capability. CAP_NUMA_ATTACH allows non-root users to create or remove an exclusive rset.
  2. Overwriting an existing name's registration can be done only by a process that has root authority or write access to this name.

An application registered resource set definition is non-persistent. It does not persist over a system boot.

Both the namespace and rsname parameters may contain up to 255 characters. They must begin with an ASCII alphanumeric character. Only the period (.), minus (-), and underscore (_) characters can be mixed with ASCII alphanumeric characters within these strings. Moreover, the names are case-sensitive, which means there is a difference between uppercase and lowercase letters in resource set names and name spaces.

Parameters

Item Description
rset Specifies a resource set handle of a resource set a name should be registered for.
namespace Points to a null terminated string corresponding to the name space within which rsname will be registered.
rsname Points to a null terminated string corresponding to the name registered with the setting of the resource set specified by rset.
mode Specifies the bit pattern that determines the created name access permissions. It is constructed by logically ORing one or more of the following values, defined in rset.h:
  • RS_IRUSR: Gives read rights to the name's owner
  • RS_IWUSR: Gives write rights to the name's owner
  • RS_IRGRP: Gives read rights to users of the same group as the name's owner
  • RS_IWGRP: Gives write rights to users of the same group as the name's owner
  • RS_IROTH: Gives read rights to others
  • RS_IWOTH: Gives write rights to others

Read privilege for a user means that the user can retrieve a resource set definition (by issuing a call to the rs_getnamedrset subroutine). Write privilege for a user means that the user can redefine a name (by issuing another call to the rs_getnamedrset subroutine).
command Specifies whether the rsname parameter's registration should be overwritten if it already exists in the global repository. This parameter takes one of the following values, defined in rset.h:
  • RS_REDEFINE: The rsname parameter should be redefined if it already exists in the name space identified by namespace. In such a case, the calling process must have write access to rsname.
  • RS_DEFINE: The rsname parameter should not be redefined if it already exists in the name space identified by namespace. If this happens, an error is reported to the calling process

Return Values

If successful, a value of 0 is returned. If unsuccessful, a value of -1 is returned and the errno global variable is set to indicate the error.

Error Codes

The rs_registername subroutine is unsuccessful if one or more of the following are true:

Item Description
EINVAL If one of the following is true:
  • rsname is a null pointer.
  • namespace is a null pointer.
  • rsname or namespace points to an invalid name. The name length is 0 or greater than the RSET_NAME_SIZE constant (defined in rset.h), or the name contains invalid characters.
  • mode identifies an invalid access rights value.
  • command identifies an invalid command value.
EEXIST The command parameter is set to RS_DEFINE and rsname already exists in the global repository within the name space identified by namespace.
ENOMEM There is not enough space to create the data structures related to the registry of this resource set.
EPERM If one of the following is true:
  • The command parameter is set to RS_REDEFINE and the calling process has neither write access to rsname nor root authority .
  • The calling process has neither the attachment privilege nor root authority.
  • The namespace parameter starts with sys. This name space is reserved for system use.
EFAULT Invalid address, and/or exceptions outside errno range.