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