libproccpuinfo Guide ==================== Abstract -------- This guide is intended to demonstrate the use of libproccpuinfo through examples and explaination. Getting the most recent Version ------------------------------- The most recent version can always be found at http://download.savannah.nongnu.org/releases/proccpuinfo/[http://download.savannah.nongnu.org/releases/proccpuinfo/] Compiling the Library --------------------- The library uses autotools, just use the standard commands. --------------------------------------------------------------------- $ ./configure --prefix=/usr $ make $ make check $ sudo make install --------------------------------------------------------------------- The Example Program ------------------- Below is an example program which makes use of libproccpuinfo. This program prints out the information that it has gathered from /proc/cpuinfo. --------------------------------------------------------------------- #include 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 the Program --------------------- 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 --------------------------------------------------------------------- The proccpuinfo Type -------------------- `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. Gathering information from /proc/cpuinfo ---------------------------------------- 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. Cleaning up ----------- The library provides a utility function to free the proccpuinfo and any fields that were allocated during its use. --------------------------------------------------------------------- proccpuinfo_free(info); --------------------------------------------------------------------- Reading cpuinfo files from alternate Locations ---------------------------------------------- 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. Reading cpuinfo files from other Architectures ---------------------------------------------- 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.