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 lzma_attr_alloc_size(2)
  23 extern void *xrealloc(void *ptr, size_t size);
  24
  25
  26 /// \brief      Safe strdup() that never returns NULL
  27 extern char *xstrdup(const char *src);
  28
  29
  30 /// \brief      Fancy version of strtoull()
  31 ///
  32 /// \param      name    Name of the option to show in case of an error
  33 /// \param      value   String containing the number to be parsed; may
  34 ///                     contain suffixes "k", "M", "G", "Ki", "Mi", or "Gi"
  35 /// \param      min     Minimum valid value
  36 /// \param      max     Maximum valid value
  37 ///
  38 /// \return     Parsed value that is in the range [min, max]. Does not return
  39 ///             if an error occurs.
  40 ///
  41 extern uint64_t str_to_uint64(const char *name, const char *value,
  42                 uint64_t min, uint64_t max);
  43
  44
  45 /// \brief      Round an integer up to the next full MiB and convert to MiB
  46 ///
  47 /// This is used when printing memory usage and limit.
  48 extern uint64_t round_up_to_mib(uint64_t n);
  49
  50
  51 /// \brief      Convert uint64_t to a string
  52 ///
  53 /// Convert the given value to a string with locale-specific thousand
  54 /// separators, if supported by the snprintf() implementation. The string
  55 /// is stored into an internal static buffer indicated by the slot argument.
  56 /// A pointer to the selected buffer is returned.
  57 ///
  58 /// This function exists, because non-POSIX systems don't support thousand
  59 /// separator in format strings. Solving the problem in a simple way doesn't
  60 /// work, because it breaks gettext (specifically, the xgettext tool).
  61 extern const char *uint64_to_str(uint64_t value, uint32_t slot);
  62
  63
  64 enum nicestr_unit {
  65         NICESTR_B,
  66         NICESTR_KIB,
  67         NICESTR_MIB,
  68         NICESTR_GIB,
  69         NICESTR_TIB,
  70 };
  71
  72
  73 /// \brief      Convert uint64_t to a nice human readable string
  74 ///
  75 /// This is like uint64_to_str() but uses B, KiB, MiB, GiB, or TiB suffix
  76 /// and optionally includes the exact size in parenthesis.
  77 ///
  78 /// \param      value     Value to be printed
  79 /// \param      unit_min  Smallest unit to use. This and unit_max are used
  80 ///                       e.g. when showing the progress indicator to force
  81 ///                       the unit to MiB.
  82 /// \param      unit_max  Biggest unit to use. assert(unit_min <= unit_max).
  83 /// \param      always_also_bytes
  84 ///                       Show also the exact byte value in parenthesis
  85 ///                       if the nicely formatted string uses bigger unit
  86 ///                       than bytes.
  87 /// \param      slot      Which static buffer to use to hold the string.
  88 ///                       This is shared with uint64_to_str().
  89 ///
  90 /// \return     Pointer to statically allocated buffer containing the string.
  91 ///
  92 /// \note       This uses double_to_str() internally so the static buffer
  93 ///             in double_to_str() will be overwritten.
  94 ///
  95 extern const char *uint64_to_nicestr(uint64_t value,
  96                 enum nicestr_unit unit_min, enum nicestr_unit unit_max,
  97                 bool always_also_bytes, uint32_t slot);
  98
  99
 100 /// \brief      Wrapper for snprintf() to help constructing a string in pieces
 101 ///
 102 /// A maximum of *left bytes is written starting from *pos. *pos and *left
 103 /// are updated accordingly.
 104 lzma_attribute((__format__(__printf__, 3, 4)))
 105 extern void my_snprintf(char **pos, size_t *left, const char *fmt, ...);
 106
 107
 108 /// \brief      Test if file descriptor is a terminal
 109 ///
 110 /// For POSIX systems, this is a simple wrapper around isatty(). However on
 111 /// Windows, isatty() returns true for all character devices, not just
 112 /// terminals.
 113 ///
 114 /// \param      fd    File descriptor to test
 115 ///
 116 /// \return     bool:
 117 ///             - true if file descriptor is a terminal
 118 ///             - false otherwise
 119 extern bool is_tty(int fd);
 120
 121
 122 /// \brief      Test if stdin is a terminal
 123 ///
 124 /// If stdin is a terminal, an error message is printed and exit status set
 125 /// to EXIT_ERROR.
 126 extern bool is_tty_stdin(void);
 127
 128
 129 /// \brief      Test if stdout is a terminal
 130 ///
 131 /// If stdout is a terminal, an error message is printed and exit status set
 132 /// to EXIT_ERROR.
 133 extern bool is_tty_stdout(void);