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
22extern void *xrealloc(void *ptr, size_t size)
23		lzma_attribute((__malloc__)) lzma_attr_alloc_size(2);
24
25
26/// \brief      Safe strdup() that never returns NULL
27extern char *xstrdup(const char *src) lzma_attribute((__malloc__));
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///
41extern 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.
48extern 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).
61extern const char *uint64_to_str(uint64_t value, uint32_t slot);
62
63
64enum 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///
95extern 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.
104extern void my_snprintf(char **pos, size_t *left, const char *fmt, ...)
105		lzma_attribute((__format__(__printf__, 3, 4)));
106
107
108/// \brief      Check if filename is empty and print an error message
109extern bool is_empty_filename(const char *filename);
110
111
112/// \brief      Test if stdin is a terminal
113///
114/// If stdin is a terminal, an error message is printed and exit status set
115/// to EXIT_ERROR.
116extern bool is_tty_stdin(void);
117
118
119/// \brief      Test if stdout is a terminal
120///
121/// If stdout is a terminal, an error message is printed and exit status set
122/// to EXIT_ERROR.
123extern bool is_tty_stdout(void);
124