==Specific PVFS issues==

===Copyright information=== \label{sec:pvfs-copyright} Copyright information at the top of source code in PVFS should include the University of Chicago. (The University of Chicago is affiliated with Argonne Nationa l Lab, where several key PVFS developers are located).

/*
 * (C) 2001 Clemson University and The University of Chicago. *
 * See COPYING in top-level directory.
 */
}}}===Function commenting===\label{sec:pvfs-comments}
''Figure out what standard should be to match up with autodocument tools.  This is on hold until we settle on such a tool, so use standard put forth in section \ref{sec:comments} for now.}
===Function naming===\label{sec:pvfs-naming}Interface functions and global variables in PVFS should use a standard naming co
nvention for clarity.  Here are a few guidelines:

* The letters ``PVFS'' should only be prepended to functions and global variable
s that exist as part of an application level interface.  Some examples would be 
{{{ PVFS_open} and {{{ PVFS_read}.  For clarity, do not use this naming scheme f
or interfaces internal to PVFS.* Well defined internal PVFS interfaces should use the prefix ``PINT'' (this is 
short for ``PVFS interface'').  This should then be followed by an identifier fo
r the interface, and then a description of what the particular function does.  Some examples are {{{ PINT_flow_alloc}, {{{ PINT_flow_free}, and {{{ PINT_flow_post}.* There are exceptions to the above rule.  For example, well defined interfaces that exist within a very distinct module of PVFS may use a different prefix.  Examples include the method functions within the BMI layer of PVFS communications have names such as {{{ METH_tcp_send} and {{{ METH_tcp_recv}.
* Any variables that are globally visible should follow the rules listed above a
s well.  This naming convention is for both functions and global variables.



== Specific PVFS issues ==

=== Copyright information ===
\label{sec:pvfs-copyright}

Copyright information at the top of source code in PVFS should include the University of Chicago.  (The University of Chicago is affiliated with Argonne Nationa
l Lab, where several key PVFS developers are located).

{{{
/*
 * (C) 2001 Clemson University and The University of Chicago. *
 * See COPYING in top-level directory.
 */
}}}

=== Function commenting ===
\label{sec:pvfs-comments}

See the section on Doxygen comment formatting  All program entities such as functions, structs, global variables, typedefs, etc. should have a special comment just before them in the code starting with a double asterisk as shown:

{{{
/** Brief description
 *
 *  Detailed description.
 */
struct foo {
};
}}}

Files should have a comment block that using the same format and the command {{{\

=== Function naming ===
\label{sec:pvfs-naming}

Interface functions and global variables in PVFS should use a standard naming convention for clarity.  Here are a few guidelines:

   * The letters "PVFS" should only be prepended to functions and global variables that exist as part of an application level interface.  Some examples would be 
{{{PVFS_open}}} and {{{PVFS_read}}}.  For clarity, do not use this naming scheme for interfaces internal to PVFS.
   * Well defined internal PVFS interfaces should use the prefix ``PINT'' (this is short for "PVFS interface").  This should then be followed by an identifier for the interface, and then a description of what the particular function does.  Some examples are {{{PINT_flow_alloc}}}, {{{PINT_flow_free}}}, and {{{PINT_flow_post}}}.
   * There are exceptions to the above rule.  For example, well defined interfaces that exist within a very distinct module of PVFS may use a different prefix.  Examples include the method functions within the BMI layer of PVFS communications have names such as {{{METH_tcp_send}}} and {{{METH_tcp_recv}}}.
   * Any variables that are globally visible should follow the rules listed above as well.  This naming convention is for both functions and global variables.

=== Error logging with Gossip ===

Gossip is a simple library for logging both errors and debugging messages.  It allows you to send logging messages to either stderr, syslog, or a text file.Gossip uses a {{{ debug mask} to determine which messages get logged.  You may specify a mask level with each debugging call.  These messages can then be toggled on or off depending on what the global mask value is.  This allows you to turn debugging on or off just for specific parts of your software at run time.  The global mask may be made up of several individual mask values logially or'd together in order to enable logging for multiple parts of your software simultaneously.  Gossip also allows you to send error messages.  These are similar to debugging messages, except that they get logged regardless of the mask value and whether debugging is turned on or off.  These error messages should only be used in situations in which a critical error should be recorded.

The following is a list of functions provided in the Gossip library:

   * '''gossip_enable_stderr()''':  Directs logging messages to stderr.
   * '''gossip_enable_file(filename, mode)''': Directs logging messages to a speci
fied file.  The arguments are the same as those taken by the {{{fopen()}}} function.
   * '''gossip_enable_syslog(priority)''': Directs logging to syslog.  The priority argument is the same as that given to the {{{syslog()}}} function.
   * '''gossip_set_debug_mask(debug_on, mask)''': Turns debugging messages on or off and specifies the mask value to use if turned on.
   * '''gossip_disable()''': Gracefully shuts down the Gossip logging facilities.
   * '''gossip_debug(mask, format, ...)''': Logs a debugging message.  Uses the same format syntax as the {{{printf()}}} function call.  It will only print if debugging is turned on and the mask value matches the global mask specified with gossip_set_debug_mask().
   * '''gossip_ldebug(mask, format, ...)''': Same as above, except that it prepends each message with the file name and line number of the source code that invoked it.
   * '''gossip_err(format, ...)''': Logs error messages.  These will print regardless of the mask and whether debugging is turned on or off.
   * '''gossip_lerr(format, ...)''': Same as above, except that it prepends each message with the file name and line number of the source code that invoked it.

Examples of how to use Gossip can be found in the {{{gossip/examples}}} directory of the Gossip source code.  This code can be found in the {{{pvfs2/src/common/gossip}}} directory within the PVFS 2 source tree.

=== Suggested error handling ===

==== Traditional application error handling with errno ====

Most unix system calls set a global variable called {{{errno}}} when an error condition occurs.  Since this is a global variable, it is overwritten everytime a system call is made.  This means that it must be checked immediately following the failure of the system call in question.  The errno values correspond to to various error conditions, wuch as ``bad file descriptor'' or ``permission denied.''  One can print out a textual description of these error values using the {{{perror()}}} or {{{strerror()}}} functions.  More information about the use of {{{errno}}} can be found in the man pages for {{{errno}}}, {{{perror}}}, and and {{{strerror}}}.

The use of errno in this manner is fine for small applications, but becomes more tedious when building larger software projects.  The problem is that you must store the error value somewhere when passing the error back through multiple abstraction layers.  This tends to cause confusion in large projects.