openfam::fam::fam_stat

Get the size, permissions and name of a region or data item.

Synopsis

void fam_stat(Fam_Descriptor *descriptor, Fam_Stat *famInfo);

void fam_stat(Fam_Region_Descriptor *descriptor, Fam_Stat *famInfo);

Description

These methods return the size, permissions and name associated with the data item or region descriptor.

Input Arguments

Name	Description
descriptor	Descriptor associated with the region or the data item.
famInfo	A pointer to the structure where the information is copied.

fam_stat() takes a pointer to the Fam_Stat structure as input to copy the information associated with region or data item descriptor.

typedef struct {
    uint64_t size;
    mode_t perm;
    uint32_t uid;
    uint32_t gid;
    char *name;    
    Fam_Region_Attributes region_attributes;
    int num_memservers;
    int interleaveSize;
    int *memory_servers;

} Fam_Stat;

Name	Description	Default Value
size	Size of the region or data item in bytes	none
perm	permissions associated with the region or data item	none
uid	uid associated with the region or data item	none
gid	gid associated with the region or data item	none
name	Name of the region or data item.	none
region_attributes	Region-specific attributes like redundancy level, MemoryType, InterleaveDisabled/Enabled .	0
num_memservers	Number of memory servers used for a region or data item.	none
interleaveSize	data item interleaving size used for a given region.	none
memory_servers	List of memory servers used for a given data item allocation. The list is ordered such that data item offset will be obtained as a multiple of list_element_index and interleaveSize. If the data item goes beyond available memory servers, the allocation is done again from the beginning of list. In that case data item offset calculation on any memory server can be obtained as a multiple of (list_element_index * intereleaveSize) % num_memservers, added with (num_memservers * interleaveSize), each time we rollback to the beginning of list.	none

Return Values

None. Throws Fam_Exception on error.

Fam Error Numbers

Error	Description
FAM_ERR_INVALID	API called with incorrect parameters.
FAM_ERR_NOPERM	Caller does not have access rights.
FAM_ERR_NOTFOUND	Item or region name was not found by the metadata service.
FAM_ERR_RPC	Communication error from grpc layer.
FAM_ERR_RPC_CLIENT_NOTFOUND	RPC service not available.
FAM_ERR_METADATA	Metadata service error.

Example

#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <fam/fam.h>
#include <fam/fam_exception.h>
using namespace std;
using namespace openfam;

int main(void) {
	fam *myFam = new fam();
	
	// ... initialization code here
	
	try {
		// get a region descriptor from the metadata service
		Fam_Region_Descriptor *region = myFam->fam_lookup_region("myRegion");
		
		// allocate space for Fam_Stat structure.
		Fam_Stat *info = (Fam_Stat *)calloc(1, sizeof(Fam_Stat));
		myFam->fam_stat(region, info);
		printf("Region_size: %lu\n", info->size);
		
		// Get a descriptor (created by another PE) via the metadata service
		Fam_Descriptor *arrayDescriptor = myFam->fam_lookup("myArray", "myOtherRegion");
		
		// Get data item info
		myFam->fam_stat(arrayDescriptor, info);
		printf("array_size: %lu\n", info->size);
		
	} catch (Fam_Exception &e) {
		printf("Fam API failed: %d: %s\n", e.fam_error(), e.fam_error_msg());
	}
		
	// ... continuation code here
}