This file contains the guidelines for the procedures that are added to libfs.
These guidelines are not requirements, but if they are followed, it will
make the procedures in the library easier to share and more supportable over
the long term.

 1. The procedures in libfs should not call exit().  Only the calling program
    should make the determination as to whether to recover or terminate the
    program.

 2. The procedures in libfs should not print error messages.  They should save
    a descriptive error message by calling set_fserror(), and they should have
    a method of communicating that there was an error to the calling code.  For
    example, you could call set_fserror() with a system error message as
    follows:

	set_fserror( strerror( errno ) );
    
    The caller can determine whether or not to print the error message.  The
    caller can retrieve the error message by calling the procedure fserror().

    The procedures fserror() and set_fserror() are both included in libfs.

 3. The procedures in libfs can return static values that are good until the
    next call, but these procedures should not be called by other procedures
    in libfs.  It is too easy to break existing code that has not copied the
    return value, by adding another call to the same procedure.

 4. When a procedure in libfs allocates a resource that needs to be released
    by the caller (such as malloc'ed memory), that fact should be clearly
    stated in the comments describing the procedure.

 5. Whenever possible, procedures should be in individual object files so that
    only the procedures that are referenced are extracted from the library
    when a command is linked with the library.  This will allow command files
    to have private copies of some procedure in the library while using the
    shared copy of other procedures.  The command owner is free to migrate to
    the shared copy of procedures on a case by case basis.

 6. Some of the modules in libfs include a procedure named main() that is
    conditionally compiled when the variable TESTING is defined.  These
    procedures should not be confused with a test package.  They are only
    intended to create programs that provides command line access to the
    procedures inside the files.  Thus, these programs facilitate testing the
    procedures in libfs; they are not test programs in themselves.

    There is no scaffold test for libfs.  The procedures in libfs are only
    tested by testing the commands that are linked to libfs.

 7. The header for libfs is libfs.h, which is located in $hsh/head/libfs.h
    (/hpux/shared/supp/usr/src/head/libfs.h).  This contains macro definition
    and extern declarations for libfs.  As you add or modify routines, please
    update the header file.  

    A C program can include the header file via the following statement:
		#include <sys/libfs.h>
    Not that this header file is only in the build environment.

