rad_get_num(3)						     Library Functions Manual						    rad_get_num(3)

NAME

       rad_get_num,  rad_get_cpus,  rad_get_freemem,  rad_get_info,  rad_get_max, rad_get_physmem, rad_get_state - Query resource complements of a
       Resource Affinity Domain (libnuma)

SYNOPSIS

       #include <numa.h>

       int rad_get_cpus(
	       radid_t rad,
	       cpuset_t cpuset ); ssize_t rad_get_freemem(
	       radid_t rad ); int rad_get_info(
	       radid_t rad,
	       rad_info_t *into ); int rad_get_max( ); int rad_get_num( ); ssize_t rad_get_physmem(
	       radid_t rad ); ssize_t rad_get_state(
	       radid_t rad );

PARAMETERS

       Specifies a buffer to receive the CPU set assigned to the specified Resource Affinity Domain (RAD) in the caller's partition  Points  to  a
       buffer to receive information about the specified RAD.  Identifies the RAD for which the resource complement is being requested.

DESCRIPTION

       A  Resource  Affinity Domain (RAD) is a collection of resources that are related by the platform hardware topology.  The collection of pro-
       cessors and I/O busses connected to a local memory of a NUMA platform, plus the local memory itself, comprise a RAD.  More generally, a RAD
       may be characterized as a set of resources that are within some "distance" of each other.

       The  rad_get_info() function stores in the buffer pointed to by info, a rad_info_t structure containing information about the RAD specified
       by the radid argument.  This information includes the state of the RAD, the amount of memory in the RAD, and the  CPUs  it  contains.   The
       remaining functions on this reference page return individual members of the rad_info_t structure.

       The rad_get_cpus() function stores in the buffer specified by cpuset the set of CPUs in the specified RAD that are assigned to the caller's
       partition.

       The rad_get_freemem() function returns a snapshot of the amount of free memory (pages) in the specified RAD in the caller's partition.

       The rad_get_max() function returns the maximum number of RADs on the system.

       The rad_get_num() function returns the number of RADs in the caller's partition.

       The rad_get_physmem() function returns the amount of physical memory (pages) assigned to the specified RAD in the caller's partition.

       The rad_get_state() function returns the current state of the RAD specified by the radid argument. The possible RAD state values  are:  The
       specified RAD exists and is on line. Processes and threads may be assigned to the RAD and memory may be allocated there.  The specified RAD
       exists but is not currently on line.  Neither processes nor threads may be assigned to this RAD, and no memory may be allocated there. How-
       ever, the RAD's resource complement may be queried.

       Note  that  prior to calling any of the rad_get_*() functions, the application must set the rinfo_version field in the rad_info_t structure
       to RAD_INFO_VERSION.  The CPU set (cpuset) stored in this structure must have been created by the application prior to the call. If zero is
       specified for cpuset, the function does not fill in data for the CPU set.

RESTRICTIONS

       As  for	many queries of system information, the data returned by these functions may be stale by the time is is returned to or used by the
       calling application.

RETURN VALUES

       The rad_get_info() and rad_get_cpus() functions return the following values: Success. In this case, the integer value is the number of CPUs
       in the specified RAD.  Failure. In this case, errno is set to indicate the error.

       The rad_get_freemem() and rad_get_physmem() functions return the following: Success. Depending on the function, this value is the amount of
       free memory for the specified RAD or the amount of physical memory assigned to the RAD.	Failure. In this case, errno is  set  to  indicate
       the error.

       The  rad_get_num() and rad_get_max() functions return the number of RADs in the caller's partition or on the system, respectively. There is
       no value defined to indicate failure for these functions.

       The rad_get_state() function returns either RAD_OFFLINE or RAD_ONLINE values. There is no value defined to indicate failure for this  func-
       tion.

ERRORS

       The  rad_get_cpus(),  rad_get_info(),  rad_get_freemem(),  and rad_get_physmem() functions set errno to one of the following values for the
       specified condition: The cpuset argument indirectly points to an invalid address, or the specified CPU set does not exist, possibly because
       it  was	not  created by a call to cpusetcreate().  The rad argument specifies a RAD that does not exist.  The version number specified for
       the rinfo_version field in the info argument is not recognized by the system.

EXAMPLES

       The following example prints data returned by a call to rad_get_info():

       #include <sys/errno.h> #include <sys/numa.h>

       int print_rad_info(radid_t rad) {
	       rad_info_t radinfo;

	       /* Create a cpuset for the radinfo struct. */
	       cpusetcreate(&radinfo.rinfo_cpuset);

	       radinfo.rinfo_version = RAD_INFO_VERSION;

	       /* Fetch the data */
	       if (rad_get_info(rad, &radinfo) == -1) {
		       perror("rad_get_info");
		       return -1;
	       }

	       /* Simple datatypes can be printed directly. */
	       printf("rinfo_radid = %d
", radinfo.rinfo_radid);
	       printf("rinfo_state = %d
", radinfo.rinfo_state);
	       printf("rinfo_physmem = 0x%lx pages
", radinfo.rinfo_physmem);
	       printf("rinfo_freemem = 0x%lx pages
", radinfo.rinfo_freemem);
	       printf("
cpuset members: ");

	       /* Complex datatypes (cpuset) need to be enumerated. */
	       while (1) {
		       cpuid_t id;
		       int flags = SET_CURSOR_CONSUME;
		       cpu_cursor_t cpu_cursor = SET_CURSOR_INIT;

		       id = cpu_foreach(radinfo.rinfo_cpuset, flags, &cpu_cursor);

		       if (id == CPU_NONE) {
			       printf("
");
			       break;
		       } else {
			       printf("%3d ", id);
		       }
	       }

	       /* Destroy cpuset */
	       cpusetdestroy(&radinfo.rinfo_cpuset);

	       return 0; }

SEE ALSO

       Functions: cpu_foreach(3), cpusetcreate(3), nloc(3), numa_intro(3),

       Files: numa_types(4)

																    rad_get_num(3)