contrib/xz/src/xz/util.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 //
   3 /// \file       util.h
   4 /// \brief      Miscellaneous utility functions
   5 //
   6 //  Author:     Lasse Collin
   7 //
   8 //  This file has been put into the public domain.
   9 //  You can do whatever you want with this file.
  10 //
  11 ///////////////////////////////////////////////////////////////////////////////
  12
  13 /// \brief      Safe malloc() that never returns NULL
  14 ///
  15 /// \note       xmalloc(), xrealloc(), and xstrdup() must not be used when
  16 ///             there are files open for writing, that should be cleaned up
  17 ///             before exiting.
  18 #define xmalloc(size) xrealloc(NULL, size)
  19
  20
  21 /// \brief      Safe realloc() that never returns NULL
  22 extern void *xrealloc(void *ptr, size_t size);
  23
  24
  25 /// \brief      Safe strdup() that never returns NULL
  26 extern char *xstrdup(const char *src);
  27
  28
  29 /// \brief      Fancy version of strtoull()
  30 ///
  31 /// \param      name    Name of the option to show in case of an error
  32 /// \param      value   String containing the number to be parsed; may
  33 ///                     contain suffixes "k", "M", "G", "Ki", "Mi", or "Gi"
  34 /// \param      min     Minimum valid value
  35 /// \param      max     Maximum valid value
  36 ///
  37 /// \return     Parsed value that is in the range [min, max]. Does not return
  38 ///             if an error occurs.
  39 ///
  40 extern uint64_t str_to_uint64(const char *name, const char *value,
  41                 uint64_t min, uint64_t max);
  42
  43
  44 /// \brief      Round an integer up to the next full MiB and convert to MiB
  45 ///
  46 /// This is used when printing memory usage and limit.
  47 extern uint64_t round_up_to_mib(uint64_t n);
  48
  49
  50 /// \brief      Convert uint64_t to a string
  51 ///
  52 /// Convert the given value to a string with locale-specific thousand
  53 /// separators, if supported by the snprintf() implementation. The string
  54 /// is stored into an internal static buffer indicated by the slot argument.
  55 /// A pointer to the selected buffer is returned.
  56 ///
  57 /// This function exists, because non-POSIX systems don't support thousand
  58 /// separator in format strings. Solving the problem in a simple way doesn't
  59 /// work, because it breaks gettext (specifically, the xgettext tool).
  60 extern const char *uint64_to_str(uint64_t value, uint32_t slot);
  61
  62
  63 enum nicestr_unit {
  64         NICESTR_B,
  65         NICESTR_KIB,
  66         NICESTR_MIB,
  67         NICESTR_GIB,
  68         NICESTR_TIB,
  69 };
  70
  71
  72 /// \brief      Convert uint64_t to a nice human readable string
  73 ///
  74 /// This is like uint64_to_str() but uses B, KiB, MiB, GiB, or TiB suffix
  75 /// and optionally includes the exact size in parenthesis.
  76 ///
  77 /// \param      value     Value to be printed
  78 /// \param      unit_min  Smallest unit to use. This and unit_max are used
  79 ///                       e.g. when showing the progress indicator to force
  80 ///                       the unit to MiB.
  81 /// \param      unit_max  Biggest unit to use. assert(unit_min <= unit_max).
  82 /// \param      always_also_bytes
  83 ///                       Show also the exact byte value in parenthesis
  84 ///                       if the nicely formatted string uses bigger unit
  85 ///                       than bytes.
  86 /// \param      slot      Which static buffer to use to hold the string.
  87 ///                       This is shared with uint64_to_str().
  88 ///
  89 /// \return     Pointer to statically allocated buffer containing the string.
  90 ///
  91 /// \note       This uses double_to_str() internally so the static buffer
  92 ///             in double_to_str() will be overwritten.
  93 ///
  94 extern const char *uint64_to_nicestr(uint64_t value,
  95                 enum nicestr_unit unit_min, enum nicestr_unit unit_max,
  96                 bool always_also_bytes, uint32_t slot);
  97
  98
  99 /// \brief      Wrapper for snprintf() to help constructing a string in pieces
 100 ///
 101 /// A maximum of *left bytes is written starting from *pos. *pos and *left
 102 /// are updated accordingly.
 103 extern void my_snprintf(char **pos, size_t *left, const char *fmt, ...)
 104                 lzma_attribute((format(printf, 3, 4)));
 105
 106
 107 /// \brief      Check if filename is empty and print an error message
 108 extern bool is_empty_filename(const char *filename);
 109
 110
 111 /// \brief      Test if stdin is a terminal
 112 ///
 113 /// If stdin is a terminal, an error message is printed and exit status set
 114 /// to EXIT_ERROR.
 115 extern bool is_tty_stdin(void);
 116
 117
 118 /// \brief      Test if stdout is a terminal
 119 ///
 120 /// If stdout is a terminal, an error message is printed and exit status set
 121 /// to EXIT_ERROR.
 122 extern bool is_tty_stdout(void);