Use the correct format for off_t on amd64.

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

/*! \file util.c
\brief Various useful functions.
*/





/*! \var static char mtab1[12][4];
The list of the months.
*/





/*! \fn int getword(char *word, int limit, char *line, int stop)

Extract one "word" from the text line and remove it from the text line. The word's boundary is defined
by the \a stop character. If multiple stop characters are found after the word, only the first one is
removed. Therfore, passing the line buffer again to the function will remove the next word in a column
like manner.

\param word The buffer to store the extracted word.
\param limit The size of the buffer. If the stop character isn't found before that limit is reached,
the function displays an error message and returns an error code.
\param line The text line from which the word must be extracted.
\param stop The character indicating the end of the word.

\retval 0 The word is extracted.
\retval -1 The stop character was not found before the limit or the end of the string is reached.

*/





/*! \fn int getword_multisep(char *word, int limit, char *line, int stop)

Extract one "word" from the text line and remove it from the text line. The word's boundary is defined
by the \a stop character. All the stop characters following the word are removed too. Therefore, passing
the line buffer again to the function will remove words even if they are separated by multiple stop
characters.

\param word The buffer to store the extracted word.
\param limit The size of the buffer. If the stop character isn't found before that limit is reached,
the function displays an error message and returns an error code.
\param line The text line from which the word must be extracted.
\param stop The character indicating the end of the word.

\retval 0 The word is extracted.
\retval -1 The stop character was not found before the limit or the end of the string is reached.

*/





/*! \fn int getword3(char *word, int limit, char *line, int stop)

This function is now identical to getword().

\param word The buffer to store the extracted word.
\param limit The size of the buffer. If the stop character isn't found before that limit is reached,
the function displays an error message and returns an error code.
\param line The text line from which the word must be extracted.
\param stop The character indicating the end of the word.

\retval 0 The word is extracted.
\retval -1 The stop character was not found before the limit or the end of the string is reached.

*/




/*! \fn long long int my_atoll (const char *nptr)

Convert a string into a long long.

\param nptr The string containing the number to convert.

\return The number found in the string or zero if no number was found.

*/





/*! \fn void my_mkdir(const char *name)

Create the directory and all the non existing parent directories.

\param name The absolute directory to create.

*/





/*! \fn void my_lltoa(unsigned long long int n, char s[], int len)

Format a long long into a string.

\param n The number to format.
\param s The buffer to write the number.
\param len The minimum number of digits to format in the output. If the formatted
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)

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.

\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.

*/





/*! \fn void buildymd(const char *dia, const char *mes, const char *ano, char *wdata)
Convert the date into a machine format YYYYMMDD.

\param dia The day.
\param mes The name of the month as spelled in ::mtab1. If the month is invalid, the output date
is set to month 13.
\param ano The year.
\param wdata The buffer to format the date.
*/





/*! \fn void conv_month(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.
*/





/*! \fn void conv_month_name(char *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.
*/





/*! \fn void name_month(char *month,int month_len)
Get the name of the month according to the language file selected by the user.

\param month The number of the month. It is replaced by the month's name if the number is between
1 and 12 or by the name of December if the number is invalid.
\param month_len The size of the \a month buffer.

*/





/*! \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.

\param msg The printf like message to format.
\param ... The arguments to format in the message.

*/





/*! \fn void debugaz(const char *head, const char *msg)
Write a debug message to stderr with the value of a parameter. The message is prefixed by "SARG: (util)".

\param head The name of the parameter.
\param msg The value of the parameter.
*/





/*! \fn void fixip(char *ip)
Toggle the IP address format from nnn.nnn.nnn.nnn to nnn_nnn_nnn_nnn. Only the first three
occurences of the . or _ are replaced. That limitation is imposed by a will to mimic as close
as possible the previous code based on strings copying.

\param ip The IP address to change. It is replaced in place.

*/





/*! \fn char *fixnum(long long int value, int n)
Rewrite a number to make it more readable. The number may be written
with the suffix K, M, G or T depending on its magnitude or the digits
are grouped by three and separated by a dot or a comma.

\param value The number to format.
\param n If the number is abreviated and this parameter is true then append
the suffix K, M, G or T if necessary. If it is zero, the number is shortened
but no suffix is written.

\return A static buffer containing the formatted number. It is overwritten on the next
call of this function.

*/





/*! \def MAXLEN_FIXNUM
The size of the buffer to format a number in fixnum().
*/





/*! \fn char *fixnum2(long long int value, int n)
Format a number by grouping the digits by three and separating the groups by
a dot or a comma.
*/




/*! \def MAXLEN_FIXNUM2
The size of the buffer to format a number in fixnum2().
*/





/*! \fn void buildhref(char * href)
Replace the path given as argument by the first part of a HTML tag to link to the given
directory (the A tag). More precisely, the argument is replaced by <a href=" followed by the given \a href.

\param href The directory to replace by a HTML A tag with the open HREF to it.

*/





/*! \fn char *buildtime(long long int elap)
Write the elapsed time given in milliseconds as a string in the format HH:MM:SS.

\param elap The elapsed time in milliseconds.

\return A static buffer with the formatted time. It is valid until the function is called again.
*/





/*! \fn void obtdate(const char *dirname, const char *name, char *data)
Get the date stored in the <tt>sarg-date</tt> file of a directory with the connection data.

\param dirname The directory to look for the connection directory.
\param name The name of the directory whose <tt>sarg-date</tt> file must be read.
\param data The buffer to store the content of the file. It must be more than 80
bytes long.
*/





/*! \fn void obtuser(const char *dirname, const char *name, char *tuser)
Get the number of entries stored in a connection data directory. The number is read from
the <tt>sarg-users</tt> file of the connection data's directory.

\param dirname The directory to look for the connection directory.
\param name The name of the connection directory whose <tt>sarg-users</tt> file must be read.
\param tuser The buffer to store the content of the file. It must be more than 20
bytes long.
*/





/*! \fn void obttotal(const char *dirname, const char *name, char *tbytes, char *tuser, char *media)
Count the total size transfered in a connection directory and compute the average number of bytes
per entry.

\param dirname The directory to look for the connection directory.
\param name The name of the connection directory whose <tt>sarg-general</tt> file must be read.
\param tbytes A buffer to store the total number of bytes from this connection.
\param tuser The number of entries in the connection directory.
\param media A buffer to store the average number of bytes per entry.
*/





/*! \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 dirname The connection directory to which the period must be written.
\param period The period to write in the file.
*/




/*! \fn void vrfydir(const char *dir, const char *per1, const char *addr, const char *site, const char *us, const char *form)
Create a directory to generate a report for the specified connection data and populate it with the a <tt>sarg-date</tt> file
containing the current date.

The function also create an <tt>images</tt> directory in \a dir and copy all the files from the <tt>SYSCONFDIR/images</tt> into
that directory.

\param dir The output directory to fill.
\param per1 The date range in the form: YYYYMMMDD-YYYYMMMDD or DDMMMYYYY-DDMMMYYYY depending on the value of
::IndexTree.
\param addr The ip address or host name to which the report is limited. If the string is empty, all the addresses are accepted.
\param site The destination site to which the report is limited. If the string is empty, all the sites are accepted.
\param us The user to whom the report is limited. It is an empty string if all the users are accepted.
\param form The email address to which the report is sent. It is currently unused.

*/





/*! \fn void strip_latin(char *line)
Remove any HTML entity from the line. A HTML entity starts with an ampersand and end at the next
semicolon.

\param line The text whose html entities are to be removed.
*/





/*! \fn void zdate(char *ftime, const char *DateFormat)
Format the current date and time according to the date format.

\param ftime The buffer to format the date. It must be at least 127 bytes long.
\param DateFormat The format of the date. It can be:
  \arg u to format as mmm/dd/YYYY HH:MM
  \arg e to format as dd/mmm/YYYY HH:MM
  \arg w to format as WW-HH-MM where WW is the week number in the range 00 to 53.
*/





/*! \fn char *fixtime(long int elap)
Format a "time" into a size or a time formatted as HH:MM:SS.

\param elap The "time" to format in milliseconds if it is a time and into bytes if it is a size.

\return The formatted time.

\bug If the elapsed time is less than 1000ms, the time is formated with the milliseconds as the seconds.

\todo Review this function and documentation based on the calls made to it and the arguments passed by the callers.
*/





/*! \fn void date_from(char *date, char *dfrom, char *duntil)
Split a date range into a date from and a date until. If the date range
is not a range but just a single date, it is duplicated to make a range out
of it.

\param date The date range to split in the form <tt>from-until</tt>. If it is a single date,
it is transformed into a range like <tt>date-date</tt>. Each date is in the form DD/MM/YYYY.
\param dfrom A buffer to write the start date in the form YYYYMMDD.
\param duntil A buffer to write the end date in the form YYYYMMDD.
*/





/*! \fn char *strlow(char *string)
Convert a string to all lowercases.

\param string The string to convert.

\return A pointer to the string passed as argument.
*/





/*! \fn char *strup(char *string)
Convert a string to all uppercases.

\param string The string to convert.

\return A pointer to the string passed as argument.
*/





/*! \fn void subs(char *str, int size, char *from, char *to)
Replace one occurence of the string \a from by \a to in the string \a str.

\param str The string in which to replace the text.
\param size The size of the string buffer to detect a buffer overflow if \a to is longer than \a from.
\param from The fragment of text to replace.
\param to The text to replace instead of \a from.
*/





/*! \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.

\param outdir The output directory to purge.
*/





/*! \fn void load_excludecodes(const char *ExcludeCodes)
Load the list of the HTTP codes to exclude from the report. There must be one code per line.
Any trailing space is removed and there is no provision for comments.

\param ExcludeCodes The name of the file to load.

This function allocate the memory to store the codes and it must be freed by a call to 
free_excludecodes().
*/





/*! \fn void free_excludecodes(void)
Free the memory allocated by load_excludecodes().
*/




/*! \fn int vercode(const char *code)
Check if the code is contained in the exclusion list loaded by load_excludecodes().

\param code The HTTP code to test.

\retval 1 The code is excluded.
\retval 0 The code is not excluded.
*/





/*! \fn void fixnone(char *str)
Find if the string is the word none and clear the string if it matches. The function
tolerates the trailing spaces and tabulations.

\param str The text to test for the word "none".
*/





/*! \fn void fixendofline(char *str)
Remove the control codes and spaces at the end of the line. That is, it remove any ASCII
code less than or equal to 0x20.

\param str The string to truncate.
*/




/*! \fn int testvaliduserchar(const char *user)
Tell if the user string contains any invalid character in a user name. The list
of the invalid characters is defined by ::UserInvalidChar.

\param user The user name to test.

\retval 1 The string contains at least one invalid character.
\retval 0 The string is valid.
*/





/*! \fn int compar( const void *a, const void *b )
Compare two integers for bsearch.

\param a A pointer to the first integer.
\param b A pointer to the second integer.

\retval 1 If a > b.
\retval 0 If a == b.
\retval -1 If a < b.
*/





/*! \fn int getnumlist( char *buf, numlist *list, const int len, const int maxvalue )
Get a comma separated list of numbers and split them into separate values taking into account
that no value may be greater than a maximum. If a value is in fact a range, it is expended.

Any duplicate value is removed.

\param buf The string with the list of numbers.
\param list Where to store the numbers.
\param len The size of the list.
\param maxvalue The maximum value allowed in the list.

\retval 0 No error.
\retval -1 Error detected.
*/





/*! \fn void show_info(FILE *fp_ou)
Write the HTML formatted message to indicate the version of sarg that produced
the report and when the report was generated.

\param fp_ou The HTML file to which the identification block must be appended.
*/





/*! \fn void show_sarg(FILE *fp_ou, const char *ind)
Write the header of the report to tell that it was generated by sarg.

\param fp_ou The handle of the HTML file.
\param ind The path to use to have access to the images directory with the sarg logo. It is a succession of ..
to move up until the root of the reports with the images directory.
*/





/*! \fn char *get_size(const char *path, const char *file)
Get the size, in human readable form and kibibytes, of the content of a directory.

\param path The path containing the directory to scan.
\param file The last part of the path to the directory to scan.

\return The size of the path.
*/





/*! \fn void write_html_header(FILE *fp_ou, const char * ind)
Write the HTML header of a HTML report file. The DTD correspond to a
transitional HTML version 4.01. The title of the document is taken from
the global variable ::Title.

\param fp_ou The file to which the HTML header is written.
\param ind The path to pass to show_arg() to find the root directory where the
images directory is.
*/





/*! \fn void baddata(void)
Display an error message telling that sarg suspects an attempt to execute arbitrary code and terminate sarg.

Any temporary file created by sarg is deleted.
*/





/*! \fn void url_module(const char *url, char *w2)
Copy at most 254 bytes from the end of the URL or stops at the first /.

\param url The URL to parse.
\param w2 A buffer to store the copied portion of the URL. The buffer must
be at least 255 characters long.
*/





/*! \fn void 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.

\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.

*/





/*! \fn void version(void)
Display the current version of sarg and terminate the program.
*/





/*! \fn char *get_param_value(const char *param,char *line)
Get the value of a parameter formatted in the string as "param value"
without the quotes.

If the parameter name matches \a param, then the value following the parameter
is returned. If it doesn't match, the function return NULL.

The function is suitable to parse configuration files because it will ignore
comments (anything but spaces and tabulations put before the parameter will make
it unrecognized by this function)

\param param The parameter name that must be found at the beginning of the line
with possible spaces or tabulations before.
\param line The text line to search for the parameter and it's value.

\return The beginning of the value after the equal sign and with the possible
spaces or tabulations removed. If the line doesn't start with the parameter name,
the function returns NULL.

*/





/*! \fn void read_usertab(const char *UserTabFile)
Read the content of the \a UserTabFile and store it for further use with get_usertab_name().

The file contains the IP address or ID of the user then some spaces and the real name of the user.

Any trailing space or tabulation is removed from the real name. The user ID or IP cannot contain
a space or a tabulation but it may contain any other character, including the colon that was
forbidden in the past. That change was made to allow IPv6 addresses.

The file may contain comments if the line starts with a #.

\param UserTabFile The name of the file to read. If it is empty, the function does nothing.
*/





/*! \fn void get_usertab_name(const char *user,char *name,int namelen)
Find the real name of the user with the ID or IP address in \a user. The name is fetched
from the usertab file.

The usertab file must have been read by read_usertab().

\param user The ID or IP address of the user.
\param name A buffer to write the real name of the user.
\param namelen The size of the buffer.
*/





/*! \fn int is_download_suffix(const char *url)
Tell if the URL correspond to a downloaded file. The function takes the extension at the end of the
URL with a maximum of 9 characters and compare it to the list of the download suffix in
::DownloadSuffix. If the suffix is found in the list, the function reports the URL as the download
of a file.

\param url The URL to test.

\retval 1 The URL matches a suffix of a download.
\retval 0 The URL is not a known download.

\note A downloaded file cannot be detected if the file name is embedded in a GET or POST request. Only requests
that ends with the file name can be detected.

\note A URL embedding another web site's address ending by .com at the end of the URL will match the download
extension com if it is defined in the ::DownloadSuffix.
*/




/*! \fn void write_logo_image(FILE *fp_ou)
Write a link of the logo of the organisation that generate the report in the HTML file. The logo
is written in a centered table.

\param fp_ou The handle of the HTML file being written.
*/




/*! \fn void output_html_string(FILE *fp_ou,const char *str)
Write a string in a file and replace the problematic ASCII characters by their equivalent HTML entities.

\param fp_ou The handle of the output file.
\param str The string to output.
*/