April 18, 2004

FreeBSD 4.9

PMGRrMakeDescribe(3) i386/PRM


NAME

PMGRrMakeDescribe


LIBRARY

portManager's general routines library /usr/local/lib/libPMGR.so.0 ( -lPMGR )


SYNOPSIS

#include    <PMGRrMakeDescribe.h>

char*   PMGRrMakeDescribe( char* );
       

DESCRIPTION

The purpose of PMGRrMakeDescribe is to retrieve the name and version of an available port from FreeBSD's port tree. PMGRrMakeDescribe retrieves the name from either a cache it maintains or by running ( "make describe" ) in the port that is being looked up's directory.

Because the way some ports are assigned their name and version numbers in FreeBSD's port system are quite convoluted ( a real mess, huge can of worms! ), it is nearly impossible to extract the correct name of these ports directly from their Makefiles. Shame really because if it were possible, portManager's pmStatus routine would certainly be simpler and faster.

As a compromise between simplicity and speed, PMGRrMakeDescribe is used to run the port system's "make describe" command ( simple, but slow ) when a port's name and version needs to be looked up. Once a port is looked up this routine stores its name in a cache ( /var/db/portCache.db ) along with the size and last time updated of the port's makefile. Only when the port's Makefile changes (indicating it was updated by CVSUP) does "make describe" need to be run after the port's name is cached ( speedy, but not completely simple in violation of my KISS ( Keep It Simple, Stupid ) programming principles <sigh> ). -Mike

While a cache keeps things speedy, it is always possible they may be corrupted after extensive use, compromising program reliability. The tendency will be towards deleting this cache at any sign of possible corruption in later releases of portManager, forcing the program pmStatus to be slowed down by refilling the cache over and over if need be. Reliability before speed is nearly as important as KISS IMHO ( I use too many acronyms maybe?). -Mike


RETURN VALUES

Give PMGRrMakeDescribe a makefile cat_dir/port_dir to look up in a string and it will either return a pointer to a string containing the name and version of the port in that make file or NULL if something goes wrong.


FILES

PMGRrMakeDescribe sources
PMGRrMakeDescribe.c PMGRrMakeDescribe.h

EXAMPLES

char* {available_port_name} = PMGRrMakeDescribe( char* {installed port's Makefile dir in the form category_dir/port_dir ie. "x11/XFree86" } )


DIAGNOSTICS

If pmStatus or pmUpgrade ever receive a seg fault, try deleting /var/db/portCache.db to solve the problem, and please, submit a bug report.


COMPATIBILITY

portManager and it's library routines are intended for FreeBSD-STABLE, it may also work on CURRENT. Probably portManager will compile on other UNIX type systems but what would be the point?


ERRORS

see diagnostics


SEE ALSO

pmStatus (1)


STANDARDS


HISTORY


AUTHORS

Mojave Green Software Co.
Landers Ca
Michael C. Shultz
April 2004
       

BUGS