"Fossies" - the Fresh Open Source Software Archive

Member "sarg-2.4.0/documentation/util.txt" (26 Apr 2017, 20446 Bytes) of package /linux/privat/sarg-2.4.0.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. For more information about "util.txt" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 2.3.11_vs_2.4.0.

    1 /*! \file util.c
    2 \brief Various useful functions.
    3 */
    4 
    5 
    6 
    7 
    8 
    9 /*! \var static char mtab1[12][4];
   10 The list of the months.
   11 */
   12 
   13 
   14 
   15 
   16 /*! \fn void getword_start(struct getwordstruct *gwarea, char *line)
   17 Initialize the getword buffer with the given text line.
   18 
   19 \param gwarea The getword buffer to initialize.
   20 \param line The text line to use in the getword buffer.
   21 */
   22 
   23 
   24 
   25 
   26 
   27 /*! \fn void getword_restart(struct getwordstruct *gwarea)
   28 Restart the getword buffer from the beginning.
   29 
   30 \param gwarea The getword buffer to reset.
   31 */
   32 
   33 
   34 
   35 
   36 
   37 /*! \fn int getword(char *word, int limit, struct getwordstruct *gwarea, char stop)
   38 
   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
   42 like manner.
   43 
   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.
   49 
   50 \retval 0 The word is extracted.
   51 \retval -1 The stop character was not found before the limit is reached.
   52 
   53 */
   54 
   55 
   56 
   57 
   58 
   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
   61 found.
   62 
   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.
   67 
   68 \retval 0 The word is extracted.
   69 */
   70 
   71 
   72 
   73 
   74 
   75 /*! \fn int getword_multisep(char *word, int limit, struct getwordstruct *gwarea, char stop)
   76 
   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
   80 characters.
   81 
   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.
   87 
   88 \retval 0 The word is extracted.
   89 \retval -1 The stop character was not found before the limit is reached.
   90 
   91 */
   92 
   93 
   94 
   95 
   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.
   99 
  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.
  104 
  105 \retval 0 The word is skipped.
  106 \retval -1 The stop character was not found before the limit is reached.
  107 */
  108 
  109 
  110 
  111 
  112 
  113 /*! \fn int getword_atoll(long long int *number, struct getwordstruct *gwarea, char stop)
  114 Extract one number from the text line.
  115 
  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.
  119 
  120 \retval 0 The number is extracted.
  121 \retval -1 The stop character was not found after the number.
  122 */
  123 
  124 
  125 
  126 
  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.
  130 
  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.
  135 
  136 \retval 0 The word is skipped.
  137 \retval -1 Invalid \a orig_line passed to the function.
  138 */
  139 
  140 
  141 
  142 
  143 /*! \fn long long int my_atoll (const char *nptr)
  144 
  145 Convert a string into a long long.
  146 
  147 \param nptr The string containing the number to convert.
  148 
  149 \return The number found in the string or zero if no number was found.
  150 
  151 */
  152 
  153 
  154 
  155 
  156 
  157 /*! \fn static int is_absolute(const char *path)
  158 
  159 Tell if the path is absolute. On Unix, a path is absolute if it starts with a /.
  160 
  161 On Windows, we also check if the path starts with "x:" where x can be any letter.
  162 
  163 \param path The path to check.
  164 
  165 \retval 1 The path is absolute.
  166 \retval 0 The path is relative.
  167 */
  168 
  169 
  170 
  171 
  172 
  173 /*! \fn void my_mkdir(const char *name)
  174 
  175 Create the directory and all the non existing parent directories.
  176 
  177 \param name The absolute directory to create.
  178 
  179 */
  180 
  181 
  182 
  183 
  184 
  185 /*! \fn void my_lltoa(unsigned long long int n, char *s, int ssize, int len)
  186 
  187 Format a long long into a string.
  188 
  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.
  194 
  195 */
  196 
  197 
  198 
  199 
  200 
  201 /*! \fn int builddia(int day, int month, int year)
  202 
  203 Return a numerical value made of the date.
  204 
  205 \param day The day of the date.
  206 \param month The number of the month starting from 1.
  207 \param year The year.
  208 
  209 \return The date in an integer format computed as year*10000+month*100+day.
  210 */
  211 
  212 
  213 
  214 
  215 
  216 /*! \fn void buildymd(const char *dia, const char *mes, const char *ano, char *wdata)
  217 Convert the date into a machine format YYYYMMDD.
  218 
  219 \param dia The day.
  220 \param mes The name of the month as spelled in ::mtab1. If the month is invalid, the output date
  221 is set to month 13.
  222 \param ano The year.
  223 \param wdata The buffer to format the date.
  224 */
  225 
  226 
  227 
  228 
  229 
  230 /*! \fn int conv_month(int char *month)
  231 Convert the month's name into its two digits numerical equivalent.
  232 
  233 \param month The name of the month as spelled in ::mtab1.
  234 
  235 \return The month number on starting from one. If the month name is not in ::mtab1,
  236 13 is returned.
  237 */
  238 
  239 
  240 
  241 
  242 
  243 /*! \fn const char *conv_month_name(int month)
  244 Convert a month number into a name.
  245 
  246 \param month The number of the month in the range 1 to 12.
  247 
  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.
  252 */
  253 
  254 
  255 
  256 
  257 
  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.
  260 
  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.
  264 
  265 */
  266 
  267 
  268 
  269 
  270 
  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.
  275 
  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.
  280 
  281 \return A static buffer containing the formatted number. It is overwritten on the next
  282 call of this function.
  283 
  284 */
  285 
  286 
  287 
  288 
  289 
  290 /*! \def MAXLEN_FIXNUM
  291 The size of the buffer to format a number in fixnum().
  292 */
  293 
  294 
  295 
  296 
  297 
  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
  300 a dot or a comma.
  301 */
  302 
  303 
  304 
  305 
  306 /*! \def MAXLEN_FIXNUM2
  307 The size of the buffer to format a number in fixnum2().
  308 */
  309 
  310 
  311 
  312 
  313 
  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.
  317 
  318 \param href The directory to replace by a HTML A tag with the open HREF to it.
  319 
  320 */
  321 
  322 
  323 
  324 
  325 
  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.
  328 
  329 \param elap The elapsed time in milliseconds.
  330 
  331 \return A static buffer with the formatted time. It is valid until the function is called again.
  332 */
  333 
  334 
  335 
  336 
  337 
  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.
  340 
  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.
  350 */
  351 
  352 
  353 
  354 
  355 
  356 /*! \fn void computedate(int year,int month,int day,struct tm *t);
  357 Fill a tm structure with the data of the date.
  358 
  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.
  363 */
  364 
  365 
  366 
  367 
  368 
  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.
  372 
  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.
  375 
  376 \return The number of entries in the report or zero if the file doesn't exists.
  377 */
  378 
  379 
  380 
  381 
  382 
  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
  385 per entry.
  386 
  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.
  392 */
  393 
  394 
  395 
  396 
  397 
  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.
  400 
  401 \param arqtt The text at the first line of a sarg log file.
  402 \param period The period to initialize.
  403 */
  404 
  405 
  406 
  407 
  408 
  409 /*! \fn int getperiod_buildtext(struct periodstruct *period)
  410 Build the text to display as the date range of the report.
  411 
  412 \param period The object whose text must be contructed.
  413 
  414 \retval 0 No error.
  415 \retval -1 Resulting text too long for buffer.
  416 */
  417 
  418 
  419 
  420 
  421 
  422 /*! \fn static void copy_images(void)
  423 Copy the images (in fact all the files) from the directory ::IMAGEDIR into the output directory
  424 whose name is in ::outdir.
  425 */
  426 
  427 
  428 
  429 
  430 
  431 /*! \fn void strip_latin(char *line)
  432 Remove any HTML entity from the line. A HTML entity starts with an ampersand and end at the next
  433 semicolon.
  434 
  435 \param line The text whose html entities are to be removed.
  436 */
  437 
  438 
  439 
  440 
  441 
  442 /*! \fn void zdate(char *ftime,int ftimesize, const char *DateFormat)
  443 Format the current date and time according to the date format.
  444 
  445 \param ftime The buffer to format the date.
  446 \param ftimesize The size of the buffer to store the date
  447 \param DateFormat The format of the date. It can be:
  448   \arg u to format as mmm/dd/YYYY HH:MM
  449   \arg e to format as dd/mmm/YYYY HH:MM
  450   \arg w to format as WW-HH-MM where WW is the week number in the range 00 to 53.
  451 */
  452 
  453 
  454 
  455 
  456 
  457 /*! \fn char *fixtime(long int elap)
  458 Format a "time" into a size or a time formatted as HH:MM:SS.
  459 
  460 \param elap The "time" to format in milliseconds if it is a time and into bytes if it is a size.
  461 
  462 \return The formatted time.
  463 
  464 \bug If the elapsed time is less than 1000ms, the time is formated with the milliseconds as the seconds.
  465 
  466 \todo Review this function and documentation based on the calls made to it and the arguments passed by the callers.
  467 */
  468 
  469 
  470 
  471 
  472 
  473 /*! \fn void date_from(char *date, int *dfrom, int *duntil)
  474 Split a date range into a date from and a date until. If the date range
  475 is not a range but just a single date, it is duplicated to make a range out
  476 of it.
  477 
  478 \param date The date range to split in the form <tt>from-until</tt>. If it is a single date,
  479 it is transformed into a range like <tt>date-date</tt>. Each date is in the form DD/MM/YYYY.
  480 \param dfrom A variable to write the start date in the form YYYY*10000+MM*100+DD.
  481 \param duntil A variable to write the end date in the form YYYY*10000+MM*100+DD.
  482 */
  483 
  484 
  485 
  486 
  487 
  488 /*! \fn char *strlow(char *string)
  489 Convert a string to all lowercases.
  490 
  491 \param string The string to convert.
  492 
  493 \return A pointer to the string passed as argument.
  494 */
  495 
  496 
  497 
  498 
  499 
  500 /*! \fn char *strup(char *string)
  501 Convert a string to all uppercases.
  502 
  503 \param string The string to convert.
  504 
  505 \return A pointer to the string passed as argument.
  506 */
  507 
  508 
  509 
  510 
  511 
  512 /*! \fn void removetmp(const char *outdir)
  513 Purge the file <tt>sarg-general</tt> from all the lines but the total.
  514 
  515 \param outdir The output directory to purge.
  516 */
  517 
  518 
  519 
  520 
  521 
  522 /*! \fn void load_excludecodes(const char *ExcludeCodes)
  523 Load the list of the HTTP codes to exclude from the report. There must be one code per line.
  524 Any trailing space is removed and there is no provision for comments.
  525 
  526 \param ExcludeCodes The name of the file to load.
  527 
  528 This function allocate the memory to store the codes and it must be freed by a call to
  529 free_excludecodes().
  530 */
  531 
  532 
  533 
  534 
  535 
  536 /*! \fn void free_excludecodes(void)
  537 Free the memory allocated by load_excludecodes().
  538 */
  539 
  540 
  541 
  542 
  543 /*! \fn int vercode(const char *code)
  544 Check if the code is contained in the exclusion list loaded by load_excludecodes().
  545 
  546 \param code The HTTP code to test.
  547 
  548 \retval 1 The code is excluded.
  549 \retval 0 The code is not excluded.
  550 */
  551 
  552 
  553 
  554 
  555 
  556 /*! \fn void fixnone(char *str)
  557 Find if the string is the word none and clear the string if it matches. The function
  558 tolerates the trailing spaces and tabulations.
  559 
  560 \param str The text to test for the word "none".
  561 */
  562 
  563 
  564 
  565 
  566 
  567 /*! \fn void fixendofline(char *str)
  568 Remove the control codes and spaces at the end of the line. That is, it remove any ASCII
  569 code less than or equal to 0x20.
  570 
  571 \param str The string to truncate.
  572 */
  573 
  574 
  575 
  576 
  577 /*! \fn int testvaliduserchar(const char *user)
  578 Tell if the user string contains any invalid character in a user name. The list
  579 of the invalid characters is defined by ::UserInvalidChar.
  580 
  581 \param user The user name to test.
  582 
  583 \retval 1 The string contains at least one invalid character.
  584 \retval 0 The string is valid.
  585 */
  586 
  587 
  588 
  589 
  590 
  591 /*! \fn int compar( const void *a, const void *b )
  592 Compare two integers for bsearch.
  593 
  594 \param a A pointer to the first integer.
  595 \param b A pointer to the second integer.
  596 
  597 \retval 1 If a > b.
  598 \retval 0 If a == b.
  599 \retval -1 If a < b.
  600 */
  601 
  602 
  603 
  604 
  605 
  606 /*! \fn void show_info(FILE *fp_ou)
  607 Write the HTML formatted message to indicate the version of sarg that produced
  608 the report and when the report was generated.
  609 
  610 \param fp_ou The HTML file to which the identification block must be appended.
  611 */
  612 
  613 
  614 
  615 
  616 
  617 /*! \fn void show_sarg(FILE *fp_ou, int depth)
  618 Write the header of the report to tell that it was generated by sarg.
  619 
  620 \param fp_ou The handle of the HTML file.
  621 \param depth How deep is the page in the directory tree. It is used to prepend the images directory name
  622 with as many .. as necessary. If the page is at the same level as the image directory, the depth is zero.
  623 */
  624 
  625 
  626 
  627 
  628 
  629 /*! \fn char *get_size(const char *path, const char *file)
  630 Get the size, in human readable form and kibibytes, of the content of a directory.
  631 
  632 \param path The path containing the directory to scan.
  633 \param file The last part of the path to the directory to scan.
  634 
  635 \return The size of the path.
  636 */
  637 
  638 
  639 
  640 
  641 /*! \fn void write_html_head(FILE *fp_ou,int depth, const char *page_title,int javascript)
  642 Write the header of the HTML document. The DTD corresponds to a
  643 transitional HTML version 4.01. The title of the document is taken from
  644 the global variable ::Title.
  645 
  646 \param fp_ou The file to which the HTML header is written.
  647 \param depth How deep is the page in the directory tree. The path of the relative javascripts is adjusted accordingly.
  648 \param title The title of the page.
  649 \param javascript Which javascript to include in the page. Is a combination of the following bits:
  650   \arg HTML_JS_SORTTABLE
  651 */
  652 
  653 
  654 
  655 
  656 
  657 /*! \fn void write_html_header(FILE *fp_ou, int depth, const char *title)
  658 Write the HTML header of a HTML report file including the sarg logo and
  659 the beginning of the header of the report.
  660 
  661 The header of the report must be closed by a call to close_html_header().
  662 
  663 \param fp_ou The file to which the HTML header is written.
  664 \param depth How deep is the page in the directory tree. The depth is passed to show_sarg().
  665 \param title The title of the page.
  666 \param javascript Which javascript to include in the page. Is a combination of bits.
  667 See \see write_html_header() for the possible values.
  668 */
  669 
  670 
  671 
  672 
  673 
  674 /*! \fn void close_html_header(FILE *fp_ou)
  675 Close the header opened by write_html_header().
  676 
  677 \param fp_ou The file to which the HTML header is written.
  678 */
  679 
  680 
  681 
  682 
  683 
  684 /*! \fn void url_module(const char *url, char *w2)
  685 Copy at most 254 bytes from the end of the URL or stops at the first /.
  686 
  687 \param url The URL to parse.
  688 \param w2 A buffer to store the copied portion of the URL. The buffer must
  689 be at least 255 characters long.
  690 */
  691 
  692 
  693 
  694 
  695 
  696 /*! \fn int write_html_trailer(FILE *fp_ou)
  697 End the HTML file by closing the centered table that was opened by write_html_header(), writting
  698 the informations of show_info() and closing the body and html tag. After this function returns, the
  699 HTML file is complete and nothing should be written to it.
  700 
  701 \param fp_ou The HTML file to close. The file handle is not closed but you should not write anything
  702 to the file after this function returns.
  703 
  704 \retval 0 No error.
  705 \retval -1 Write error.
  706 */
  707 
  708 
  709 
  710 
  711 
  712 /*! \fn void version(void)
  713 Display the current version of sarg and terminate the program.
  714 */
  715 
  716 
  717 
  718 
  719 
  720 /*! \fn char *get_param_value(const char *param,char *line)
  721 Get the value of a parameter formatted in the string as "param value"
  722 without the quotes.
  723 
  724 If the parameter name matches \a param, then the value following the parameter
  725 is returned. If it doesn't match, the function return NULL.
  726 
  727 The function is suitable to parse configuration files because it will ignore
  728 comments (anything but spaces and tabulations put before the parameter will make
  729 it unrecognized by this function)
  730 
  731 \param param The parameter name that must be found at the beginning of the line
  732 with possible spaces or tabulations before.
  733 \param line The text line to search for the parameter and it's value.
  734 
  735 \return The beginning of the value after the equal sign and with the possible
  736 spaces or tabulations removed. If the line doesn't start with the parameter name,
  737 the function returns NULL.
  738 
  739 */
  740 
  741 
  742 
  743 
  744 
  745 /*! \fn void write_logo_image(FILE *fp_ou)
  746 Write a link of the logo of the organisation that generate the report in the HTML file. The logo
  747 is written in a centered table.
  748 
  749 \param fp_ou The handle of the HTML file being written.
  750 */
  751 
  752 
  753 
  754 
  755 
  756 /*! \fn void output_html_string(FILE *fp_ou,const char *str,int maxlen)
  757 Write a string in a file and replace the problematic ASCII characters by their equivalent HTML entities.
  758 
  759 \param fp_ou The handle of the output file.
  760 \param str The string to output.
  761 \param maxlen The maximum number of bytes to write from the string. Set to zero to have no limit.
  762 
  763 If the string is longer than the requested length, only the requested number of bytes are output and
  764 the string is truncated and ended by &hellip;.
  765 */
  766 
  767 
  768 
  769 
  770 
  771 /*! \fn void output_html_url(FILE *fp_ou,const char *url)
  772 Write an URL into the file and replace any & by &amp;.
  773 
  774 \param fp_ou The handle of the output file.
  775 \param url The URL to output.
  776 */
  777 
  778 
  779 
  780 
  781 
  782 /*! \fn void unlinkdir(const char *dir,int contentonly)
  783 Delete a directory and its content.
  784 
  785 \param dir The name of the directory to delete.
  786 \param contentonly \c True to delete only the content of the directory and leave the directory
  787 itself in place. If set to \c zero, the directory is removed too.
  788 */
  789