2 \brief Various useful functions.
9 /*! \var static char mtab1[12][4];
10 The list of the months.
16 /*! \fn void getword_start(struct getwordstruct *gwarea, char *line)
17 Initialize the getword buffer with the given text line.
19 \param gwarea The getword buffer to initialize.
20 \param line The text line to use in the getword buffer.
27 /*! \fn void getword_restart(struct getwordstruct *gwarea)
28 Restart the getword buffer from the beginning.
30 \param gwarea The getword buffer to reset.
37 /*! \fn int getword(char *word, int limit, struct getwordstruct *gwarea, char stop)
39 Extract one "word" from the text line and remove it from the text line. The word's boundary is defined
40 by the \a stop character. If multiple stop characters are found after the word, only the first one is
41 removed. Therfore, passing the line buffer again to the function will remove the next word in a column
44 \param word The buffer to store the extracted word.
45 \param limit The size of the buffer. If the stop character isn't found before that limit is reached,
46 the function displays an error message and returns an error code.
47 \param gwarea The getword buffer initialized by getword_start().
48 \param stop The character indicating the end of the word.
50 \retval 0 The word is extracted.
51 \retval -1 The stop character was not found before the limit is reached.
59 /*! \fn int getword_limit(char *word, int limit, struct getwordstruct *gwarea, char stop)
60 Extract one word with a maximum size and skip any supernumerary bytes until the stop bytes is
63 \param word The buffer to store the extracted word.
64 \param limit The size of the buffer.
65 \param gwarea The getword buffer initialized by getword_start().
66 \param stop The character indicating the end of the word.
68 \retval 0 The word is extracted.
75 /*! \fn int getword_multisep(char *word, int limit, struct getwordstruct *gwarea, char stop)
77 Extract one "word" from the text line and remove it from the text line. The word's boundary is defined
78 by the \a stop character. All the stop characters following the word are removed too. Therefore, passing
79 the line buffer again to the function will remove words even if they are separated by multiple stop
82 \param word The buffer to store the extracted word.
83 \param limit The size of the buffer. If the stop character isn't found before that limit is reached,
84 the function displays an error message and returns an error code.
85 \param gwarea The getword buffer initialized by getword_start().
86 \param stop The character indicating the end of the word.
88 \retval 0 The word is extracted.
89 \retval -1 The stop character was not found before the limit is reached.
96 /*! \fn int getword_skip(int limit, struct getwordstruct *gwarea, char stop)
97 Skip one "word" from the text line and remove it from the text line. The word's boundary is defined
98 by the \a stop character.
100 \param limit The maximum number of characters to skip. If the stop character isn't found before that limit is reached,
101 the function displays an error message and returns an error code.
102 \param gwarea The getword buffer initialized by getword_start().
103 \param stop The character indicating the end of the word.
105 \retval 0 The word is skipped.
106 \retval -1 The stop character was not found before the limit is reached.
113 /*! \fn int getword_atoll(long long int *number, struct getwordstruct *gwarea, char stop)
114 Extract one number from the text line.
116 \param number Where the store the extracted number.
117 \param gwarea The getword buffer initialized by getword_start().
118 \param stop The character indicating the end of the word.
120 \retval 0 The number is extracted.
121 \retval -1 The stop character was not found after the number.
127 /*! \fn int getword_ptr(char *orig_line,char **word, struct getwordstruct *gwarea, char stop)
128 Return a pointer to a null terminated string starting at the current position and ending
129 and the stop character.
131 \param orig_line The line that is being parsed.
132 \param word A pointer to set to the beginning of the string.
133 \param gwarea The getword buffer initialized by getword_start().
134 \param stop The character indicating the end of the word.
136 \retval 0 The word is skipped.
137 \retval -1 Invalid \a orig_line passed to the function.
143 /*! \fn long long int my_atoll (const char *nptr)
145 Convert a string into a long long.
147 \param nptr The string containing the number to convert.
149 \return The number found in the string or zero if no number was found.
157 /*! \fn static int is_absolute(const char *path)
159 Tell if the path is absolute. On Unix, a path is absolute if it starts with a /.
161 On Windows, we also check if the path starts with "x:" where x can be any letter.
163 \param path The path to check.
165 \retval 1 The path is absolute.
166 \retval 0 The path is relative.
173 /*! \fn void my_mkdir(const char *name)
175 Create the directory and all the non existing parent directories.
177 \param name The absolute directory to create.
185 /*! \fn void my_lltoa(unsigned long long int n, char *s, int ssize, int len)
187 Format a long long into a string.
189 \param n The number to format.
190 \param s The buffer to write the number.
191 \param ssize The size of the output buffer.
192 \param len The minimum number of digits to format in the output. If the formatted
193 number is less than this length, it is padded with zeros.
201 /*! \fn int builddia(int day, int month, int year)
203 Return a numerical value made of the date.
205 \param day The day of the date.
206 \param month The number of the month starting from 1.
207 \param year The year.
209 \return The date in an integer format computed as year*10000+month*100+day.
216 /*! \fn void buildymd(const char *dia, const char *mes, const char *ano, char *wdata)
217 Convert the date into a machine format YYYYMMDD.
220 \param mes The name of the month as spelled in ::mtab1. If the month is invalid, the output date
223 \param wdata The buffer to format the date.
230 /*! \fn int conv_month(int char *month)
231 Convert the month's name into its two digits numerical equivalent.
233 \param month The name of the month as spelled in ::mtab1.
235 \return The month number on starting from one. If the month name is not in ::mtab1,
243 /*! \fn const char *conv_month_name(int month)
244 Convert a month number into a name.
246 \param month The number of the month in the range 1 to 12.
248 \return The name of the month from ::mtab1 unless the month number is not between 1 and 12
249 in which case, the number is returned encoded on 3 characters. If the number is
250 invalid, the returned string is static and will be reused by any subsequent call to this
251 function with an invalid month number.
258 /*! \fn void name_month(char *month,int month_len)
259 Get the name of the month according to the language file selected by the user.
261 \param month The number of the month. It is replaced by the month's name if the number is between
262 1 and 12 or by the name of December if the number is invalid.
263 \param month_len The size of the \a month buffer.
271 /*! \fn char *fixnum(long long int value, int n)
272 Rewrite a number to make it more readable. The number may be written
273 with the suffix K, M, G or T depending on its magnitude or the digits
274 are grouped by three and separated by a dot or a comma.
276 \param value The number to format.
277 \param n If the number is abreviated and this parameter is true then append
278 the suffix K, M, G or T if necessary. If it is zero, the number is shortened
279 but no suffix is written.
281 \return A static buffer containing the formatted number. It is overwritten on the next
282 call of this function.
290 /*! \def MAXLEN_FIXNUM
291 The size of the buffer to format a number in fixnum().
298 /*! \fn char *fixnum2(long long int value, int n)
299 Format a number by grouping the digits by three and separating the groups by
306 /*! \def MAXLEN_FIXNUM2
307 The size of the buffer to format a number in fixnum2().
314 /*! \fn void buildhref(char * href)
315 Replace the path given as argument by the first part of a HTML tag to link to the given
316 directory (the A tag). More precisely, the argument is replaced by <a href=" followed by the given \a href.
318 \param href The directory to replace by a HTML A tag with the open HREF to it.
326 /*! \fn char *buildtime(long long int elap)
327 Write the elapsed time given in milliseconds as a string in the format HH:MM:SS.
329 \param elap The elapsed time in milliseconds.
331 \return A static buffer with the formatted time. It is valid until the function is called again.
338 /*! \fn void formatdate(char *date,int date_size,int year,int month,int day,int hour,int minute,int second,int dst)
339 Format a date to display it in the report.
341 \param date The buffer to write the formatted date into.
342 \param date_size The size of the buffer.
343 \param year The absolute year to format. It must be greater than 1900.
344 \param month The month to format. It must be between 1 and 12.
345 \param day The day to format starting from 1.
346 \param hour The hour to format.
347 \param minute The minute to format.
348 \param second The second to format.
349 \param dst A positive number if the daylight saving is active, zero if it is not active and a negative number if it is unknown.
356 /*! \fn void computedate(int year,int month,int day,struct tm *t);
357 Fill a tm structure with the data of the date.
359 \param year The full year with century.
360 \param month The number of the month starting from one.
361 \param day The day of the date.
362 \param t The buffer to fill with the date.
369 /*! \fn int obtuser(const char *dirname, const char *name)
370 Get the number of entries stored in a report data directory. The number is read from
371 the <tt>sarg-users</tt> file of the report data's directory.
373 \param dirname The directory containing the reports.
374 \param name The name of the report directory whose <tt>sarg-users</tt> file must be read.
376 \return The number of entries in the report or zero if the file doesn't exists.
383 /*! \fn void obttotal(const char *dirname, const char *name, int nuser, long long int *tbytes, long long int *media)
384 Count the total size transfered in a report directory and compute the average number of bytes
387 \param dirname The directory containing the reports.
388 \param name The name of the report directory whose <tt>sarg-general</tt> file must be read.
389 \param nuser The number of entries in the report directory.
390 \param tbytes A variable to store the total number of bytes from this report.
391 \param media A variable to store the average number of bytes per entry.
398 /*! \fn int getperiod_fromsarglog(const char *arqtt,struct periodstruct *period)
399 Initialize the period with the content of the first line of a sarg log.
401 \param arqtt The text at the first line of a sarg log file.
402 \param period The period to initialize.
409 /*! \fn void getperiod_fromrange(struct periodstruct *period,int dfrom,int duntil)
410 Fill the period with the specified range.
412 \param period The period to change.
413 \param dfrom The start date in the form year*10000+month*100+day.
414 \param duntil The end date in the form year*10000+month*100+day.
421 /*! \fn int getperiod_buildtext(struct periodstruct *period)
422 Build the text to display as the date range of the report.
424 \param period The object whose text must be contructed.
427 \retval -1 Resulting text too long for buffer.
434 /*! \fn static void copy_images(void)
435 Copy the images (in fact all the files) from the directory ::IMAGEDIR into the output directory
436 whose name is in ::outdir.
443 /*! \fn void vrfydir(const char *per1, const char *addr, const char *site, const char *us, const char *form)
444 Create a directory to generate a report for the specified connection data and populate it with the a <tt>sarg-date</tt> file
445 containing the current date.
447 The function also create an <tt>images</tt> directory in \a dir and copy all the files from the <tt>SYSCONFDIR/images</tt> into
450 \param per1 The date range in the form: YYYYMMMDD-YYYYMMMDD or DDMMMYYYY-DDMMMYYYY depending on the value of
452 \param addr The ip address or host name to which the report is limited. If the string is empty, all the addresses are accepted.
453 \param site The destination site to which the report is limited. If the string is empty, all the sites are accepted.
454 \param us The user to whom the report is limited. It is an empty string if all the users are accepted.
455 \param form The email address to which the report is sent. It is currently unused.
463 /*! \fn void strip_latin(char *line)
464 Remove any HTML entity from the line. A HTML entity starts with an ampersand and end at the next
467 \param line The text whose html entities are to be removed.
474 /*! \fn void zdate(char *ftime,int ftimesize, const char *DateFormat)
475 Format the current date and time according to the date format.
477 \param ftime The buffer to format the date.
478 \param ftimesize The size of the buffer to store the date
479 \param DateFormat The format of the date. It can be:
480 \arg u to format as mmm/dd/YYYY HH:MM
481 \arg e to format as dd/mmm/YYYY HH:MM
482 \arg w to format as WW-HH-MM where WW is the week number in the range 00 to 53.
489 /*! \fn char *fixtime(long int elap)
490 Format a "time" into a size or a time formatted as HH:MM:SS.
492 \param elap The "time" to format in milliseconds if it is a time and into bytes if it is a size.
494 \return The formatted time.
496 \bug If the elapsed time is less than 1000ms, the time is formated with the milliseconds as the seconds.
498 \todo Review this function and documentation based on the calls made to it and the arguments passed by the callers.
505 /*! \fn void date_from(char *date, int *dfrom, int *duntil)
506 Split a date range into a date from and a date until. If the date range
507 is not a range but just a single date, it is duplicated to make a range out
510 \param date The date range to split in the form <tt>from-until</tt>. If it is a single date,
511 it is transformed into a range like <tt>date-date</tt>. Each date is in the form DD/MM/YYYY.
512 \param dfrom A variable to write the start date in the form YYYY*10000+MM*100+DD.
513 \param duntil A variable to write the end date in the form YYYY*10000+MM*100+DD.
520 /*! \fn char *strlow(char *string)
521 Convert a string to all lowercases.
523 \param string The string to convert.
525 \return A pointer to the string passed as argument.
532 /*! \fn char *strup(char *string)
533 Convert a string to all uppercases.
535 \param string The string to convert.
537 \return A pointer to the string passed as argument.
544 /*! \fn void removetmp(const char *outdir)
545 Purge the file <tt>sarg-general</tt> from all the lines but the total.
547 \param outdir The output directory to purge.
554 /*! \fn void load_excludecodes(const char *ExcludeCodes)
555 Load the list of the HTTP codes to exclude from the report. There must be one code per line.
556 Any trailing space is removed and there is no provision for comments.
558 \param ExcludeCodes The name of the file to load.
560 This function allocate the memory to store the codes and it must be freed by a call to
568 /*! \fn void free_excludecodes(void)
569 Free the memory allocated by load_excludecodes().
575 /*! \fn int vercode(const char *code)
576 Check if the code is contained in the exclusion list loaded by load_excludecodes().
578 \param code The HTTP code to test.
580 \retval 1 The code is excluded.
581 \retval 0 The code is not excluded.
588 /*! \fn void fixnone(char *str)
589 Find if the string is the word none and clear the string if it matches. The function
590 tolerates the trailing spaces and tabulations.
592 \param str The text to test for the word "none".
599 /*! \fn void fixendofline(char *str)
600 Remove the control codes and spaces at the end of the line. That is, it remove any ASCII
601 code less than or equal to 0x20.
603 \param str The string to truncate.
609 /*! \fn int testvaliduserchar(const char *user)
610 Tell if the user string contains any invalid character in a user name. The list
611 of the invalid characters is defined by ::UserInvalidChar.
613 \param user The user name to test.
615 \retval 1 The string contains at least one invalid character.
616 \retval 0 The string is valid.
623 /*! \fn int compar( const void *a, const void *b )
624 Compare two integers for bsearch.
626 \param a A pointer to the first integer.
627 \param b A pointer to the second integer.
638 /*! \fn int getnumlist( char *buf, numlist *list, const int len, const int maxvalue )
639 Get a comma separated list of numbers and split them into separate values taking into account
640 that no value may be greater than a maximum. If a value is in fact a range, it is expended.
642 Any duplicate value is removed.
644 \param buf The string with the list of numbers.
645 \param list Where to store the numbers.
646 \param len The size of the list.
647 \param maxvalue The maximum value allowed in the list.
650 \retval -1 Error detected.
657 /*! \fn void show_info(FILE *fp_ou)
658 Write the HTML formatted message to indicate the version of sarg that produced
659 the report and when the report was generated.
661 \param fp_ou The HTML file to which the identification block must be appended.
668 /*! \fn void show_sarg(FILE *fp_ou, int depth)
669 Write the header of the report to tell that it was generated by sarg.
671 \param fp_ou The handle of the HTML file.
672 \param depth How deep is the page in the directory tree. It is used to prepend the images directory name
673 with as many .. as necessary. If the page is at the same level as the image directory, the depth is zero.
680 /*! \fn char *get_size(const char *path, const char *file)
681 Get the size, in human readable form and kibibytes, of the content of a directory.
683 \param path The path containing the directory to scan.
684 \param file The last part of the path to the directory to scan.
686 \return The size of the path.
692 /*! \fn void write_html_head(FILE *fp_ou,int depth, const char *page_title,int javascript)
693 Write the header of the HTML document. The DTD corresponds to a
694 transitional HTML version 4.01. The title of the document is taken from
695 the global variable ::Title.
697 \param fp_ou The file to which the HTML header is written.
698 \param depth How deep is the page in the directory tree. The path of the relative javascripts is adjusted accordingly.
699 \param title The title of the page.
700 \param javascript Which javascript to include in the page. Is a combination of the following bits:
701 \arg HTML_JS_SORTTABLE
708 /*! \fn void write_html_header(FILE *fp_ou, int depth, const char *title)
709 Write the HTML header of a HTML report file including the sarg logo and
710 the beginning of the header of the report.
712 The header of the report must be closed by a call to close_html_header().
714 \param fp_ou The file to which the HTML header is written.
715 \param depth How deep is the page in the directory tree. The depth is passed to show_sarg().
716 \param title The title of the page.
717 \param javascript Which javascript to include in the page. Is a combination of bits.
718 See \see write_html_header() for the possible values.
725 /*! \fn void close_html_header(FILE *fp_ou)
726 Close the header opened by write_html_header().
728 \param fp_ou The file to which the HTML header is written.
735 /*! \fn void url_module(const char *url, char *w2)
736 Copy at most 254 bytes from the end of the URL or stops at the first /.
738 \param url The URL to parse.
739 \param w2 A buffer to store the copied portion of the URL. The buffer must
740 be at least 255 characters long.
747 /*! \fn void url_to_file(const char *url,char *file,int filesize)
748 Mangle an URL to produce a part that can be included in a file.
750 \param url The URL to mangle.
751 \param file The buffer to write the mangled URL.
752 \param filesize The size of the buffer.
759 /*! \fn int write_html_trailer(FILE *fp_ou)
760 End the HTML file by closing the centered table that was opened by write_html_header(), writting
761 the informations of show_info() and closing the body and html tag. After this function returns, the
762 HTML file is complete and nothing should be written to it.
764 \param fp_ou The HTML file to close. The file handle is not closed but you should not write anything
765 to the file after this function returns.
768 \retval -1 Write error.
775 /*! \fn void version(void)
776 Display the current version of sarg and terminate the program.
783 /*! \fn char *get_param_value(const char *param,char *line)
784 Get the value of a parameter formatted in the string as "param value"
787 If the parameter name matches \a param, then the value following the parameter
788 is returned. If it doesn't match, the function return NULL.
790 The function is suitable to parse configuration files because it will ignore
791 comments (anything but spaces and tabulations put before the parameter will make
792 it unrecognized by this function)
794 \param param The parameter name that must be found at the beginning of the line
795 with possible spaces or tabulations before.
796 \param line The text line to search for the parameter and it's value.
798 \return The beginning of the value after the equal sign and with the possible
799 spaces or tabulations removed. If the line doesn't start with the parameter name,
800 the function returns NULL.
808 /*! \fn void write_logo_image(FILE *fp_ou)
809 Write a link of the logo of the organisation that generate the report in the HTML file. The logo
810 is written in a centered table.
812 \param fp_ou The handle of the HTML file being written.
819 /*! \fn void output_html_string(FILE *fp_ou,const char *str,int maxlen)
820 Write a string in a file and replace the problematic ASCII characters by their equivalent HTML entities.
822 \param fp_ou The handle of the output file.
823 \param str The string to output.
824 \param maxlen The maximum number of bytes to write from the string. Set to zero to have no limit.
826 If the string is longer than the requested length, only the requested number of bytes are output and
827 the string is truncated and ended by ….
834 /*! \fn void output_html_url(FILE *fp_ou,const char *url)
835 Write an URL into the file and replace any & by &.
837 \param fp_ou The handle of the output file.
838 \param url The URL to output.
845 /*! \fn void unlinkdir(const char *dir,int contentonly)
846 Delete a directory and its content.
848 \param dir The name of the directory to delete.
849 \param contentonly \c True to delete only the content of the directory and leave the directory
850 itself in place. If set to \c zero, the directory is removed too.