1// SPDX-License-Identifier: 0BSD 2 3/////////////////////////////////////////////////////////////////////////////// 4// 5/// \file util.h 6/// \brief Miscellaneous utility functions 7// 8// Author: Lasse Collin 9// 10/////////////////////////////////////////////////////////////////////////////// 11 12/// \brief Safe malloc() that never returns NULL 13/// 14/// \note xmalloc(), xrealloc(), and xstrdup() must not be used when 15/// there are files open for writing, that should be cleaned up 16/// before exiting. 17#define xmalloc(size) xrealloc(NULL, size) 18 19 20/// \brief Safe realloc() that never returns NULL 21lzma_attr_alloc_size(2) 22extern void *xrealloc(void *ptr, size_t size); 23 24 25/// \brief Safe strdup() that never returns NULL 26extern 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/// 40extern 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. 47extern 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). 60extern const char *uint64_to_str(uint64_t value, uint32_t slot); 61 62 63enum 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/// 94extern 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. 103lzma_attribute((__format__(__printf__, 3, 4))) 104extern void my_snprintf(char **pos, size_t *left, const char *fmt, ...); 105 106 107/// \brief Test if file descriptor is a terminal 108/// 109/// For POSIX systems, this is a simple wrapper around isatty(). However on 110/// Windows, isatty() returns true for all character devices, not just 111/// terminals. 112/// 113/// \param fd File descriptor to test 114/// 115/// \return bool: 116/// - true if file descriptor is a terminal 117/// - false otherwise 118extern bool is_tty(int fd); 119 120 121/// \brief Test if stdin is a terminal 122/// 123/// If stdin is a terminal, an error message is printed and exit status set 124/// to EXIT_ERROR. 125extern bool is_tty_stdin(void); 126 127 128/// \brief Test if stdout is a terminal 129/// 130/// If stdout is a terminal, an error message is printed and exit status set 131/// to EXIT_ERROR. 132extern bool is_tty_stdout(void); 133