nloc(3) — Subroutines

NAME

nloc − Queries the NUMA Topology or Resource Affinity Domains (libnuma library)

SYNOPSIS

#include <numa.h>
int nloc(
numa_attr_t ∗numa_attr,
radset_t radset );

PARAMETERS

numa_attr
Points to a structure that specifies the criteria for selecting a set of resource Affinity Domains (RADs). This structure contains the following elements:

nattr_type
The type of resource for which the set of “nearby” RADs is requested.

nattr_descr
The resource descriptor for which the RAD set is requested.

nattr_distance
The distance criteria for selecting resources. RADs in the caller’s partition that have a distance <= this value will be included in the radset returned by nloc(). See DESCRIPTION for more information about nattr_distance.

nattr_flags
Flags that influence the selection of RADs. See DESCRIPTION for details.

radset
Specifies a buffer to contain the set of RADs in the caller’s partition that satisfy the criteria specified by numa_attr.

DESCRIPTION

The nloc() function will return in radset the set of RADs that have a distance <= the nattr_distance value from the specified resource. The returned radset value may be used as an argument to explicit process or thread placement APIs or in the mattr_radset member of a memory allocation policy structure for explicit memory placement.

The following symbolic values for nattr_distance are defined:

RAD_DIST_LOCAL
Represents the distance value for resources that are directly connected to the specified resource.

RAD_DIST_REMOTE
Represents the maximum distance value for the system. Generally, all RADs in the partition will be <= this distance.

For NUMA topologies in which RADs are variable distances from one another, RAD_DIST_LOCAL can be incremented to specify a specific distance. In other words, RAD_DIST_LOCAL + 1 represents the distance to the closest RADs, RAD_DIST_LOCAL + 2 represents the distance to the next closest RADs, and so forth. For example, when nattr_distance is set to RAD_DIST_LOCAL + 2, nloc() returns in radset the set of RADs that have a distance <= (RAD_DIST_LOCAL + 2) from the specified resource. For NUMA topologies where all RADs are equidistant from one another, <= (RAD_DIST_LOCAL + n), where n is a positive integer, is equivalent to <= RAD_DIST_REMOTE.

The following symbolic values are defined for the nattr_flags field:

RAD_BOUND
When specified, only RADs that have processes bound to them will be returned in radset.

RAD_NOBOUND
When specified, only RADs that do not have processes bound to them will be returned in radset.

RETURN VALUES

0Success.

−1Failure. In this case, errno is set to indicate the error.

ERRORS

If the nloc() function fails, it sets errno to one of the following values for the reason specified:

[EFAULT]
The numa_attr argument (or its nattr_descr field) or the radset argument point to an invalid address.

[EINVAL]
One or more of the following conditions are true:

•The numa_attr argument contains an undefined type value.

•The nattr_descr field contains an invalid resource value for the specified type.

•The nattr_distance or nattr_flags fields contain an invalid or undefined value.

[ESRCH]
The process specified by rd_pid does not exist.

[ELOOP]
There are too many symbolic links in rd_pathname.

[ENAMETOOLONG]
The rd_pathname length exceeds MAXPATHLEN, or a component of rd_pathname exceeds MAXNAMELEN.

[ENOENT]
The file named by rd_pathname does not exist.

[ENOTDIR]
A component of rd_pathname is not a directory.

Museum

Related Articles