Technical Reference: Base Operating System and Extensions, Volume 2

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.

Notes:

Registering a resource set definition can only be done by a process that has root authority or CAP_NUMA_ATTACH attachment privilege.
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

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:

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.

Related Information

rs_getnameattr Subroutine, rs_discardname Subroutine, and rs_getnamedrset Subroutine.