Store the period internaly and get rid of the sarg-period file.

[thirdparty/sarg.git] / documentation / util.txt

diff --git a/documentation/util.txt b/documentation/util.txt
index 1f1c242ca473d2b5ab01b99b3a27f511983f4552..23daaa96b9e1575b29422e52455d822682d5dfd8 100644 (file)
--- a/documentation/util.txt
+++ b/documentation/util.txt
@@ -198,19 +198,15 @@ number is less than this length, it is padded with zeros.
 
 
 
-/*! \fn void builddia(char *dia, const char *mes, const char *ano, const char *df, char *wdata)
+/*! \fn int builddia(int day, int month, int year)
 
-Format a date into a YYYYMMDD string and into a DD/MM/YYYY or MM/DD/YYYY string depending on the value
-of the \a df parameter.
+Return a numerical value made of the date.
 
-\param dia The day of the date on input. It is replaced by the date in the human readable format.
-\param mes The name of the month as spelled in ::mtab1. If the month is invalid the output dates are
-set to month 13.
-\param ano The year.
-\param df The format for the human readable date. If the string start with a 'u', it is formatted as
-MM/DD/YYYY. Any other character format it as DD/MM/YYYY.
-\param wdata A buffer to store the machine formatted date YYYYMMDD.
+\param day The day of the date.
+\param month The number of the month starting from 1.
+\param year The year.
 
+\return The date in an integer format computed as year*10000+month*100+day.
 */
 
 
@@ -231,22 +227,28 @@ is set to month 13.
 
 
 
-/*! \fn void conv_month(char *month)
+/*! \fn int conv_month(int char *month)
 Convert the month's name into its two digits numerical equivalent.
 
-\param month The name of the month as spelled in ::mtab1. It is replaced by the month number on
-two digits with a padding zero. If the month name is not in ::mtab1, the string is not replaced.
+\param month The name of the month as spelled in ::mtab1.
+
+\return The month number on starting from one. If the month name is not in ::mtab1,
+13 is returned.
 */
 
 
 
 
 
-/*! \fn void conv_month_name(char *month)
+/*! \fn const char *conv_month_name(int month)
 Convert a month number into a name.
 
-\param month The number of the month. It is replaced by the name of the month from ::mtab1 unless
-the month number is not between 1 and 12.
+\param month The number of the month in the range 1 to 12.
+
+\return The name of the month from ::mtab1 unless the month number is not between 1 and 12
+in which case, the number is returned encoded on 3 characters. If the number is
+invalid, the returned string is static and will be reused by any subsequent call to this
+function with an invalid month number.
 */
 
 
@@ -266,21 +268,6 @@ Get the name of the month according to the language file selected by the user.
 
 
 
-/*! \fn void fixper(char *tbuf, char *period, const char *duntil)
-Given a date in the form YYYYMMDD, the function format it as DD/mmm/YYYY
-or mmm/DD/YYYY according to the value of the ::df global variable and append
-it to \a period.
-
-\param tbuf Unused.
-\param period The string to which the formated date is appended.
-\param duntil The date to format.
-
-*/
-
-
-
-
-
 /*! \fn void debuga(const char *msg,...)
 Write a debug message to stderr. The message is prefixed by "SARG:" to identify its origin.
 
@@ -402,14 +389,13 @@ Format a date to display it in the report.
 
 
 
-/*! \fn time_t computedate(const char *year,const char *month,const char *day);
-Compute a unix timestamp from a date.
+/*! \fn void computedate(int year,int month,int day,struct tm *t);
+Fill a tm structure with the data of the date.
 
 \param year The full year with century.
-\param month The name of the month in English as defined by ::mtab1.
+\param month The number of the month starting from one.
 \param day The day of the date.
-
-\return A unix timestamp.
+\param t The buffer to fill with the date.
 */
 
 
@@ -444,18 +430,19 @@ per entry.
 
 
 
+/*! \fn int getperiod_buildtext(struct periodstruct *period)
+Build the text to display as the date range of the report.
 
-/*! \fn void gperiod(const char *dirname, const char *period)
-Write the current period for the connection directory in a file named <tt>sarg-period</tt>
-in the connection directory.
+\param period The object whose text must be contructed.
 
-\param dirname The connection directory to which the period must be written.
-\param period The period to write in the file.
+\retval 0 No error.
+\retval -1 Resulting text too long for buffer.
 */
 
 
 
 
+
 /*! \fn static void copy_images(void)
 Copy the images (in fact all the files) from the directory ::IMAGEDIR into the output directory
 whose name is in ::outdir.
@@ -567,8 +554,7 @@ Convert a string to all uppercases.
 
 
 /*! \fn void removetmp(const char *outdir)
-Remove the file <tt>sarg-period</tt> from the output directory and purge the file <tt>sarg-general</tt> from
-all the lines but the total.
+Purge the file <tt>sarg-general</tt> from all the lines but the total.
 
 \param outdir The output directory to purge.
 */
@@ -790,7 +776,7 @@ Mangle an URL to produce a part that can be included in a file.
 
 
 
-/*! \fn void write_html_trailer(FILE *fp_ou)
+/*! \fn int write_html_trailer(FILE *fp_ou)
 End the HTML file by closing the centered table that was opened by write_html_header(), writting
 the informations of show_info() and closing the body and html tag. After this function returns, the
 HTML file is complete and nothing should be written to it.
@@ -798,6 +784,8 @@ HTML file is complete and nothing should be written to it.
 \param fp_ou The HTML file to close. The file handle is not closed but you should not write anything
 to the file after this function returns.
 
+\retval 0 No error.
+\retval -1 Write error.
 */