More Doxygen documentation.

diff --git a/documentation/log.txt b/documentation/log.txt
index 03869433db6e1339c9f0a3ce4a57e5125f312f31..fd0732f991008b981f3639863dbe8fd050b9ecb1 100644 (file)
--- a/documentation/log.txt
+++ b/documentation/log.txt
@@ -12,6 +12,66 @@ This function parse and process the program's options.
 
 It also parse and read the log file to analyse.
 
+\section ReadAccessLog Reading of the access log file
+
+Sarg detects the type of log that is provided. Although sarg can process multiple
+log files in one pass, they must be all of the same type. You cannot mix logs from
+different applications in one single run.
+
+\subsection SquidAccessLog Reading the squid access.log file
+
+Sarg only understand the format of the default squid log file.
+
+\subsection IisAccessLog Reading the IIS log file
+
+Sarg recognize this type of log by the first line. It starts with
+the string "#Software: Mic" without the quotes. Then sarg searches for a line
+indicating the columns found in the file. It extracts the column number of the
+columns it needs to produce the report.
+
+\section UserUnsortLog Output files
+
+The data are written in files with the \c unsort extension and named after the
+user whose access line is processed. It contains the following columns separated
+by one space:
+
+\arg The day of the access.
+\arg The time of the access.
+\arg The user ID.
+\arg The IP address of the user.
+\arg The number of bytes transfered.
+\arg The HTTP code of the server to the request.
+\arg The time spent in that request.
+\arg The smart filter information (?).
+
+Moreover, any URL classified as a download is written in the \c download.unsort file
+with the following columns:
+
+\arg The day of the download.
+\arg The time of the download.
+\arg The user ID.
+\arg The IP address of the user.
+\arg The full URL of the downloaded file.
+
+Any URL returning the HTTP code 403 (forbidden access) is reported in the file
+\c denied.log.unsort with the following columns:
+
+\arg The day of the access.
+\arg The time of the access.
+\arg The user ID.
+\arg The IP address of the user.
+\arg The URL that was rejected.
+
+Any URL returning the HTTP code 401 (unauthorized) or 407 (?) is reported in the file
+\c authfail.log.unsort with the following columns:
+
+\arg The day of the access.
+\arg The time of the access.
+\arg The user ID.
+\arg The IP address of the user.
+\arg The URL that was rejected.
+
+
 */
 
 
@@ -33,7 +93,7 @@ but the names are not stored in a way that is usable by that function.
 
 
 
-/*!\fn static void gethexclude(char *hexfile, int debug)
+/*!\fn static void gethexclude(const char *hexfile, int debug)
 Get the list of the hosts to exclude from the report.
 
 \param hexfile The name of the file to read. There is one host per line. Any line

diff --git a/documentation/report.txt b/documentation/report.txt
new file mode 100644 (file)
index 0000000..0f39583
--- /dev/null
+++ b/documentation/report.txt
@@ -0,0 +1,174 @@
+/*! \file report.c
+\brief Generate the reports.
+*/
+
+/*! \fn void gerarel(void)
+Generate the reports from the files created by main() in the temporary directory and sorted
+by sort_users_log().
+
+The function outputs several files:
+
+\arg \c user.utmp: The URL accessed by the user.
+\arg \c user.htmp: The date and time of usage of the web.
+
+The files are then organized in reports.
+
+*/
+
+
+
+
+
+/*! \fn static void maketmp(const char *user, const char *dirname, int debug, int indexonly)
+Create a temporary file with the extension \c utmp to store the sites accessed by the user.
+
+\param user The name of the user.
+\param dirname The directory where to create the file.
+\param debug \c True to run in debug mode.
+\param indexonly \c True if only an index is created and not the actual files.
+
+The content of the file is created one line at a time by gravatmp().
+*/
+
+
+
+
+
+
+/*! \fn static void maketmp_hour(const char *user, const char *dirname, int indexonly)
+Create a temporary file with the extension \c htmp to store the times the user surfed the web.
+
+\param user The name of the user.
+\param dirname The directory where to create the file.
+\param indexonly \c True if only an index is created and not the actual files.
+
+The content of the file is created one line at a time by gravatmp_hora().
+
+*/
+
+
+
+
+
+/*! \fn void gravatmp(const char *oldaccuser, const char *dirname, const char *oldurl, long long int nacc, long long int nbytes, const char *oldmsg, long long int nelap, int indexonly, long long int incache, long long int oucache)
+Append one line into the \c utmp temporary file of the user.
+
+\param oldaccuser The user.
+\param dirname The directory with the temporary file.
+\param oldurl The URL being accessed.
+\param nacc The number of access to the site.
+\param nbytes The number of bytes transfered.
+\param oldmsg The status of the connection.
+\param nelap The time spent downloading the data.
+\param indexonly \c True if only an index is created and not the actual files.
+\param incache The number of bytes fetched from the cache of squid.
+\param oucache The number of bytes not fetched from the cache of squid.
+
+The file contains one line per entry with the following informations in that order:
+\arg the number of access;
+\arg the number of bytes transfered;
+\arg the URL access by the user;
+\arg the status of the connection;
+\arg the time spent downloading that URL;
+\arg the number of bytes comming from the cache of squid;
+\arg the number of bytes not found in the cache of squid.
+*/
+
+
+
+
+
+/*! \fn static void gravatmp_hora(const char *dirname, const char *user, const char *data, const char *hora, const char *elap, const char *bytes, int indexonly)
+Append one line into the \c htmp temporary file of the user.
+
+\param dirname The directory with the temporary file.
+\param user The user.
+\param data The date of the access.
+\param hora The time of the access.
+\param elap The time spent.
+\param bytes The number of bytes transfered.
+\param indexonly \c True if only an index is created and not the actual files.
+
+The file contains one line per entry with the following informations in that order:
+\arg the date;
+\arg the time;
+\arg the number of bytes transfered or the time spent downloading them.
+
+*/
+
+
+
+
+
+/*! \fn static void gravaporuser(const char *user, const char *dirname, const char *url, const char *ip, const char *data, const char *hora, const char *tam, const char *elap, int indexonly)
+Append one line into the \c ip temporary file of the user.
+
+\param user The user.
+\param dirname The directory with the temporary file.
+\param url The URL accessed by the user.
+\param ip The IP from which the user is accessing the web.
+\param data The date of the access.
+\param hora The time of the access.
+\param tam The number of bytes transfered.
+\param elap The time spent.
+\param indexonly \c True if only an index is created and not the actual files.
+*/
+
+
+
+
+
+/*! \fn static void gravatmpf(const char *oldaccuser, const char *dirname, const char *oldurl, long long int nacc, long long int nbytes, const char *oldmsg, long long int nelap, int indexonly, long long int incache, long long int oucache)
+Looks suspiciously identical to gravatmp() except that it reset ::ind2 to zero.
+
+\param oldaccuser The user.
+\param dirname The directory with the temporary file.
+\param oldurl The URL being accessed.
+\param nacc The number of access to the site.
+\param nbytes The number of bytes transfered.
+\param oldmsg Unused.
+\param nelap The time spent downloading the data.
+\param indexonly \c True if only an index is created and not the actual files.
+\param incache The number of bytes fetched from the cache of squid.
+\param oucache The number of bytes not fetched from the cache of squid.
+*/
+
+
+
+
+
+/*! \fn static void gravager(char *dirname, const char *user, long long int nacc, const char *url, long long int nbytes, const char *ip, const char *hora, const char *dia, long long int nelap, long long int incache, long long int oucache)
+Append a record to the sarg-general file.
+
+\param dirname The directory where the sarg-general file is. The string is modified when the function returns.
+\param user The user making the connection.
+\param nacc The number of access to the site.
+\param url The accessed URL.
+\param nbytes the number of bytes transfered.
+\param ip The IP address of the user.
+\param hora The time of the access.
+\param dia The date of the access.
+\param nelap The time spent on that site.
+\param incache Number of bytes fetched from the cache of squid.
+\param oucache Number of bytes not found in the cache of squid.
+*/
+
+
+
+
+
+/*! \fn static void grava_SmartFilter(const char *dirname, const char *user, const char *ip, const char *data, const char *hora, const char *url, const char *smart)
+Append a record into the \c smartfilter.unsort file of the specified directory.
+
+\param dirname The directory where to create the file.
+\param user The user to store in the record.
+\param ip The IP used by the user.
+\param data The date of the access.
+\param hora The time of the access.
+\param url The accessed URL.
+\param smart The last entry of the log file.
+
+\bug The function suspiciously appends the HTML tags to end the HTML file of the user but it doesn't flag the file
+as closed so other HTML data may end up after the closing of the HTML and be invisible to the user.
+
+*/

diff --git a/documentation/sort.txt b/documentation/sort.txt
new file mode 100644 (file)
index 0000000..8da855e
--- /dev/null
+++ b/documentation/sort.txt
@@ -0,0 +1,34 @@
+/*! \file sort.c
+\brief Sort the temporary log files.
+*/
+
+
+
+
+/*! \fn void tmpsort(void)
+Sort all the \c utmp files form the temporary directory. The sort can be made according to the
+number of connections, the accessed sites or the time of the access depending on the value of
+::UserSortField. The sorting is either made in increasing or decreasing order as specified by
+the value of ::UserSortOrder.
+*/
+
+
+
+
+
+/*! \fn void sort_users_log(const char *tmp, int debug)
+The function sorts all the \c unsort files in the temporary directory. These files correspond
+to the format described in \ref UserUnsortLog.
+
+\param tmp The temorary directory of the sarg files.
+\param debug \c True to output debug information.
+
+The user's files are sorted by columns 5, 1 and 2 that are the columns of the number of bytes transfered,
+the date of the access and the time of the access.
+
+The file with the downloads is sorted by columns 3, 1, 2 and 5 that are the columns of the user's ID, the
+date, the time and the URL.
+
+In both cases, the sorted files are written in files with the extension \c log and the name of the unsorted
+file without the \c unsort extension. The unsorted file is deleted just after the sorting.
+*/

diff --git a/documentation/totger.txt b/documentation/totger.txt
new file mode 100644 (file)
index 0000000..d4023c6
--- /dev/null
+++ b/documentation/totger.txt
@@ -0,0 +1,14 @@
+/*! \file totger.c
+\brief Compute the total of the general report.
+*/
+
+
+/*! \fn int totalger(const char *dirname, int debug, const char *outdir)
+Append a TOTAL line into the \c sarg-general file containing the total of the numerical
+columns of that file.
+
+\param dirname The directory containing the \c sarg-general file.
+\param debug \c True to output the debug informations.
+\param outdir Unused.
+
+*/