libproccpuinfo Guide

This guide is intended to demonstrate the use of libproccpuinfo through examples and explaination.

The most recent version can always be found at http://download.savannah.nongnu.org/releases/proccpuinfo/

The library uses autotools, just use the standard commands.

$ ./configure --prefix=/usr
$ make
$ make check
$ sudo make install

Below is an example program which makes use of libproccpuinfo. This program prints out the information that it has gathered from /proc/cpuinfo.

#include <proccpuinfo.h>

int main() {
        proccpuinfo *info = proccpuinfo_read();

        if (!info)
                return 1;

        printf("architecture\t\t: %s\n",info->architecture);
        printf("hardware_platform\t: %s\n",info->hardware_platform);
        printf("frequency\t\t: %lf MHz\n", info->frequency);
        printf("cache\t\t\t: %d KB\n", info->cache);
        printf("cpus\t\t\t: %d processor%c\n",info->cpus, (info->cpus == 1 ? ' ' : 's'));
        printf("bogomips\t\t: %lf\n",info->bogomips);

        proccpuinfo_free(info);
        return 0;
}

Compiling a program that makes use of this library is fairly straight forward. Simply add -lproccpuinfo to link it against the libproccpuinfo library.

gcc proccpuinfo.c -lproccpuinfo -o proccpuinfo

proccpuinfo is a structure that contains all of the information collected from /proc/cpuinfo. This is what it looks like

typedef struct proccpuinfo {
        char *architecture;
        char *hardware_platform;
        double frequency;
        double bogomips;
        unsigned int cache;
        unsigned int cpus;
} proccpuinfo;

The architecture and hardware_platform fields contain strings. It should be noted that architecture refers to CPU architecture, not system architecture. If the /proc/cpuinfo file does not list these values or if the library fails to recognize the architecture or hardware platform, then the value will be set to the null byte. frequency holds the CPU clock speed in MHz. If the /proc/cpuinfo file doesn't list the clock speed or if the library fails to recognize the clock speed, then this value defaults to zero. bogomips also defaults to zero if the /proc/cpuinfo file doesn't list the BogoMips or if the library fails to recognize the BogoMips. cache holds the amount of L2 cache in kilobytes. If the /proc/cpuinfo file does not list the amount of L2 cache or if the library fails to recognize the amount of L2 cache, then the value defaults to zero. cpus holds the total number of processors detected. On systems that list the number of detected processors and the number of active/enabled processors, the number of detected processors is used. If the /proc/cpuinfo file does not list the number of processors or if the library fails to determine the number of processors, then the value defaults to 1 since all running computers have at least 1 processor.

Calling the proccpuinfo_read() function is all that is required. The library does the rest of the work for you.

proccpuinfo *info = proccpuinfo_read();

In the event of a catastrophic error (i.e. cannot allocate memory or /proc isn't mounted), proccpuinfo_read() will return the null byte.

The library provides a utility function to free the proccpuinfo and any fields that were allocated during its use.

proccpuinfo_free(info);

If you want to read files from a location other than /proc/cpuinfo, you need to set the path to the file with proccpuinfo_set_filename(char*).

proccpuinfo_set_filename("/path/to/file");

This function is useful for testing and for batch processing of cpuinfo files. This function is used by make check to test the library with many different cpuinfo files.

Since the format of cpuinfo files changes from architecture to architecture, the library has different rule sets for each one. To determine the rule set identifier, use proccpuinfo_decode_arch(char*). To set the rule set use proccpuinfo_set_arch(int).

proccpuinfo_set_arch(proccpuinfo_decode_arch("alpha"));

Valid architecture values are: alpha, arm, cris, frv, hppa, i386, ia64, m32r, m68k, mips, powerpc, powerpc64, s390, s390x, sh, sparc, vax, and x86_64. DO NOT HARDCODE RULE SET IDENTIFIERS INTO YOUR PROGRAM. The rule set identifier is an internal number which is subject to change without notice. Always use proccpuinfo_decode_arch(char*) to obtain the value. If you do not call proccpuinfo_set_arch(int), then the library will default to reading cpuinfo files using the rule set of the architecture that it was built on.