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 stdin is a terminal
     109  ///
     110  /// If stdin is a terminal, an error message is printed and exit status set
     111  /// to EXIT_ERROR.
     112  extern bool is_tty_stdin(void);
     113  
     114  
     115  /// \brief      Test if stdout is a terminal
     116  ///
     117  /// If stdout is a terminal, an error message is printed and exit status set
     118  /// to EXIT_ERROR.
     119  extern bool is_tty_stdout(void);