meminfo(2)

NAME

     meminfo - provide information about memory

SYNOPSIS

     #include <sys/types.h>
     #include <sys/mman.h>

     int meminfo(const uint64_t inaddr[], int  addr_count,  const
     uint_t   info_req[],  int  info_count,  uint64_t  outdata[],
     uint_t validity[]);

PARAMETERS

     inaddr
           array  of  input  addresses;  the  maximum  number  of
           addresses  that  can  be  processed  for  each call is
           MAX_MEMINFO_CNT

     addr_count
           number of addresses

     info_req
           array of types of information requested

     info_count
           number of pieces of  information  requested  for  each
           address in inaddr

     outdata
           array into which results are placed; array  size  must
           be the product of info_count and addr_count

     validity
           array of size  addr_count  containing  bitwise  result
           codes;  0th  bit  evaluates  validity of corresponding
           input address, 1st bit validity of response  to  first
           member of info_req, and so on

DESCRIPTION

     The meminfo() function provides  information  about  virtual
     and  physical memory particular to the calling process.  The
     user or developer of  performance  utilities  can  use  this
     information to analyze system memory allocations and develop
     a better understanding of the factors affecting  application
     performance.

     The caller of meminfo() can obtain the  following  types  of
     information about both virtual and physical memory.

     MEMINFO_VPHYSICAL
           physical address corresponding to virtual address

     MEMINFO_VLGRP
           locality group of physical page corresponding to  vir-
           tual address

     MEMINFO_VPAGESIZE
           size of physical page corresponding to virtual address

     MEMINFO_VREPLCNT
           number of replicated physical pages  corresponding  to
           specified virtual address

     MEMINFO_VREPL | n
           nth physical replica of specified virtual address

     MEMINFO_VREPL_LGRP | n
           lgrp of nth  physical  replica  of  specified  virtual
           address

     MEMINFO_PLGRP
           locality group of specified physical address

RETURN VALUES

     Upon successful completion meminfo() returns 0. Otherwise -1
     is returned and errno is set to indicate the error.

ERRORS

     The meminfo() function will fail if:

     EFAULT
           The area pointed to by outdata or validity  could  not
           be  written,  or  the  data  pointed to by info_req or
           inaddr could not be read.

     EINVAL
           The value of info_count is greater  than  31  or  less
           than 1, or the value of addr_count is less than 1.

EXAMPLES

     Example 1: Print physical pages and page sizes corresponding
     to a set of virtual addresses.

     The following example prints the  physical  pages  and  page
     sizes corresponding to a set of virtual addresses.

     void
     print_info(void **addrvec, int how_many)
     {
         static const uint_t info[] = {
             MEMINFO_VPHYSICAL,
             MEMINFO_VPAGESIZE
         };

         int info_num = sizeof (info) / sizeof (info[0]);
         int i;

         uint64_t *inaddr = alloca(sizeof (uint64_t) * how_many);
         uint64_t *outdata = alloca(sizeof (uint64_t) * how_many * info_num);
         uint_t *validity = alloca(sizeof (uint_t) * how_many);

         for (i = 0; i < how_many; i++)
             inaddr[i] = (uint64_t)addrvec[i];

         if (meminfo(inaddr, how_many, info, info_num, outdata, validity) < 0) {
             perror("meminfo");
             return;
         }

         for (i = 0; i < how_many; i++) {
             if ((validity[i] & 1) == 0)
                 printf("address 0x%llx not part of address space\n",
                     inaddr[i]);

             else if ((validity[i] & 2) == 0)
                 printf("address 0x%llx has no physical page "
                     "associated with it\n", inaddr[i]);

             else {
                 char buff[80];
                 if ((validity[i] & 4) == 0)
                     strcpy(buff, "<Unknown>");
                 else
                     sprintf(buff, "%lld",
                         outdata[i * info_num + 1]);

                 printf("address 0x%llx is backed by physical "
                     "page 0x%llx of size %s\n",
                     inaddr[i], outdata[i * info_num], buff);
             }
         }
     }

ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Stable                      |
    |_____________________________|_____________________________|
    | MT-Level                    | Async-Signal-Safe           |
    |_____________________________|_____________________________|

SEE ALSO

     memcntl(2),  mmap(2),  gethomelgroup(3C),   getpagesize(3C),
     madvise(3C), sysconf(3C), attributes(5)