shared: add NMStrBuf util

Our own implementation of a string buffer like GString.

Advantages (in decreasing relevance):

- Since we are in control, we can easily let it nm_explicit_bzero()
  the memory. The regular GString API cannot be used in such a case.
  While nm_explicit_bzero() may or may not be of questionable benefit,
  the problem is that if the underlying API counteracts the aim of
  clearing memory, it gets impossible. As API like NMStrBuf supports
  it, clearing memory is a easy as enable the right flag.
  This would for example be useful for example when we read passwords
  from a file or file descriptor (e.g. try_spawn_vpn_auth_helper()).

- We have API like

    nmp_object_to_string (const NMPObject *obj,
                          NMPObjectToStringMode to_string_mode,
                          char *buf,
                          gsize buf_size);

  which accept a fixed size output buffer. This has the problem of
  how choosing the right sized buffer. With NMStrBuf such API could
  be instead

    nmp_object_to_string (const NMPObject *obj,
                          NMPObjectToStringMode to_string_mode,
                          NMStrBuf *buf);

  which can automatically grow (using heap allocation). It would be
  easy to extend NMStrBuf to use a fixed buffer or limiting the
  maximum string length. The point is, that the to-string API wouldn't
  have to change. Depending on the NMStrBuf passed in, you can fill
  an unbounded heap allocated string, a heap allocated string up to
  a fixed length, or a static string of fixed length. NMStrBuf currently
  only implements the unbounded heap allocate string case, but it would
  be simple to extend.

  Note that we already have API like nm_utils_strbuf_*() to fill a buffer
  of fixed size. GString is not useable for that (efficiently), hence
  this API exists. NMStrBuf could be easily extended to replace this API
  without usability or performance penalty. So, while this adds one new
  API, it could replace other APIs.

- GString always requires a heap allocation for the container. In by far
  most of the cases where we use GString, we use it to simply construct
  a string dynamically. There is zero use for this overhead. If one
  really needs a heap allocated buffer, NMStrBuf can easily embedded
  in a malloc'ed memory and boxed that way.

- GString API supports inserting and removing range. We almost never
  make use of that. We only require append-only, which is simple to
  implement.

- GString needs to NUL terminate the buffer on every append. It
  has unnecessary overhead for allowing a usage of where intermediate
  buffer contents are valid strings too. That is not the case with
  NMStrBuf: the API requires the user to call nm_str_buf_get_str() or
  nm_str_buf_finalize(). In most cases, you would only access the string
  once at the end, and not while constructing it.

- GString always grows the buffer size by doubling it. I don't think
  that is optimal. I don't think there is one optimal approach for how
  to grow the buffer, it depends on the usage patterns. However, trying
  to make an optimal choice here makes a difference. QT also thinks so,
  and I adopted their approach in nm_utils_get_next_realloc_size().

3 files changed, 276 insertions, 0 deletions

diff --git a/Makefile.am b/Makefile.am
index 7580e993d5..e1b7b12abd 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -415,6 +415,7 @@ shared_nm_glib_aux_libnm_glib_aux_la_SOURCES = \
 	shared/nm-glib-aux/nm-secret-utils.h \
 	shared/nm-glib-aux/nm-shared-utils.c \
 	shared/nm-glib-aux/nm-shared-utils.h \
+	shared/nm-glib-aux/nm-str-buf.h \
 	shared/nm-glib-aux/nm-time-utils.c \
 	shared/nm-glib-aux/nm-time-utils.h \
 	shared/nm-glib-aux/nm-value-type.h \
diff --git a/shared/nm-glib-aux/nm-shared-utils.c b/shared/nm-glib-aux/nm-shared-utils.c
index 22d68be3ec..d0cc1f05a6 100644
--- a/shared/nm-glib-aux/nm-shared-utils.c
+++ b/shared/nm-glib-aux/nm-shared-utils.c
@@ -15,6 +15,7 @@
 #include <net/if.h>
 
 #include "nm-errno.h"
+#include "nm-str-buf.h"
 
 /*****************************************************************************/
 
@@ -4455,3 +4456,69 @@ nm_utils_ifname_valid (const char* name,
 
 	g_return_val_if_reached (FALSE);
 }
+
+/*****************************************************************************/
+
+void
+_nm_str_buf_ensure_size (NMStrBuf *strbuf,
+                         gsize new_size,
+                         gboolean reserve_exact)
+{
+	_nm_str_buf_assert (strbuf);
+
+	/* Currently this only supports strictly growing the buffer. */
+	nm_assert (new_size > strbuf->_allocated);
+
+	if (!reserve_exact) {
+		new_size = nm_utils_get_next_realloc_size (!strbuf->_do_bzero_mem,
+		                                           new_size);
+	}
+
+	strbuf->_str = nm_secret_mem_realloc (strbuf->_str,
+	                                      strbuf->_do_bzero_mem,
+	                                      strbuf->_allocated,
+	                                      new_size);
+	strbuf->_allocated = new_size;
+}
+
+void
+nm_str_buf_append_printf (NMStrBuf *strbuf,
+                          const char *format,
+                          ...)
+{
+	va_list args;
+	gsize available;
+	int l;
+
+	_nm_str_buf_assert (strbuf);
+
+	available = strbuf->_allocated - strbuf->_len;
+
+	va_start (args, format);
+	l = g_vsnprintf (&strbuf->_str[strbuf->_len],
+	                 available,
+	                 format,
+	                 args);
+	va_end (args);
+
+	nm_assert (l >= 0);
+	nm_assert (l < G_MAXINT);
+
+	if ((gsize) l > available) {
+		gsize l2 = ((gsize) l) + 1u;
+
+		nm_str_buf_maybe_expand (strbuf, l2, FALSE);
+
+		va_start (args, format);
+		l = g_vsnprintf (&strbuf->_str[strbuf->_len],
+		                 l2,
+		                 format,
+		                 args);
+		va_end (args);
+
+		nm_assert (l >= 0);
+		nm_assert (l == l2 - 1);
+	}
+
+	strbuf->_len += (gsize) l;
+}
diff --git a/shared/nm-glib-aux/nm-str-buf.h b/shared/nm-glib-aux/nm-str-buf.h
new file mode 100644
index 0000000000..e7f9219cd9
--- /dev/null
+++ b/shared/nm-glib-aux/nm-str-buf.h
@@ -0,0 +1,208 @@
+// SPDX-License-Identifier: LGPL-2.1+
+
+#ifndef __NM_STR_BUF_H__
+#define __NM_STR_BUF_H__
+
+#include "nm-shared-utils.h"
+#include "nm-secret-utils.h"
+
+/*****************************************************************************/
+
+/* NMStrBuf is not unlike GString. The main difference is that it can use
+ * nm_explicit_bzero() when growing the buffer. */
+typedef struct {
+	char *_str;
+	union {
+		const gsize len;
+		gsize _len;
+	};
+	gsize _allocated;
+	bool _do_bzero_mem;
+} NMStrBuf;
+
+/*****************************************************************************/
+
+static inline void
+_nm_str_buf_assert (NMStrBuf *strbuf)
+{
+	nm_assert (strbuf);
+	nm_assert (strbuf->_str);
+	nm_assert (strbuf->_allocated > 0);
+	nm_assert (strbuf->_len <= strbuf->_allocated);
+}
+
+static inline void
+nm_str_buf_init (NMStrBuf *strbuf,
+                 gsize len,
+                 bool do_bzero_mem)
+{
+	nm_assert (strbuf);
+	nm_assert (len > 0);
+
+	strbuf->_do_bzero_mem = do_bzero_mem;
+	strbuf->_allocated    = len;
+	strbuf->_str          = g_malloc (len);
+	strbuf->_len          = 0;
+
+	_nm_str_buf_assert (strbuf);
+}
+
+void _nm_str_buf_ensure_size (NMStrBuf *strbuf,
+                              gsize new_size,
+                              gboolean reserve_exact);
+
+static inline void
+nm_str_buf_maybe_expand (NMStrBuf *strbuf,
+                         gsize reserve,
+                         gboolean reserve_exact)
+{
+	_nm_str_buf_assert (strbuf);
+
+	/* currently we always require to reserve a non-zero number of bytes. */
+	nm_assert (reserve > 0);
+	nm_assert (strbuf->_len < G_MAXSIZE - reserve);
+
+	/* @reserve is the extra space that we require. */
+	if (G_UNLIKELY (reserve > strbuf->_allocated - strbuf->_len))
+		_nm_str_buf_ensure_size (strbuf, strbuf->_len + reserve, reserve_exact);
+}
+
+static inline void
+nm_str_buf_append_c (NMStrBuf *strbuf,
+                     char ch)
+{
+	nm_str_buf_maybe_expand (strbuf, 2, FALSE);
+	strbuf->_str[strbuf->_len++] = ch;
+}
+
+static inline void
+nm_str_buf_append_c2 (NMStrBuf *strbuf,
+                      char ch0,
+                      char ch1)
+{
+	nm_str_buf_maybe_expand (strbuf, 3, FALSE);
+	strbuf->_str[strbuf->_len++] = ch0;
+	strbuf->_str[strbuf->_len++] = ch1;
+}
+
+static inline void
+nm_str_buf_append_c4 (NMStrBuf *strbuf,
+                      char ch0,
+                      char ch1,
+                      char ch2,
+                      char ch3)
+{
+	nm_str_buf_maybe_expand (strbuf, 5, FALSE);
+	strbuf->_str[strbuf->_len++] = ch0;
+	strbuf->_str[strbuf->_len++] = ch1;
+	strbuf->_str[strbuf->_len++] = ch2;
+	strbuf->_str[strbuf->_len++] = ch3;
+}
+
+static inline void
+nm_str_buf_append_len (NMStrBuf *strbuf,
+                       const char *str,
+                       gsize len)
+{
+	_nm_str_buf_assert (strbuf);
+
+	if (len > 0) {
+		nm_str_buf_maybe_expand (strbuf, len + 1, FALSE);
+		memcpy (&strbuf->_str[strbuf->_len], str, len);
+		strbuf->_len += len;
+	}
+}
+
+static inline void
+nm_str_buf_append (NMStrBuf *strbuf,
+                   const char *str)
+{
+	nm_assert (str);
+
+	nm_str_buf_append_len (strbuf, str, strlen (str));
+}
+
+void nm_str_buf_append_printf (NMStrBuf *strbuf,
+                               const char *format,
+                               ...) _nm_printf (2, 3);
+
+/*****************************************************************************/
+
+/**
+ * nm_str_buf_get_str:
+ * @strbuf: the #NMStrBuf instance
+ *
+ * Returns the NUL terminated internal string.
+ *
+ * While constructing the string, the intermediate buffer
+ * is not NUL terminated (this makes it different from GString).
+ * Usually, one would build the string and retrieve it at the
+ * end with nm_str_buf_finalize(). This returns the NUL terminated
+ * buffer that was appended so far. Contrary to nm_str_buf_finalize(), you
+ * can still append more data to the buffer and this does not transfer ownership
+ * of the string.
+ *
+ * Returns: (transfer none): the internal string. The string
+ *   is of length "strbuf->len", which may be larger if the
+ *   returned string contains NUL characters (binary). The terminating
+ *   NUL character is always present after "strbuf->len" characters.
+ */
+static inline const char *
+nm_str_buf_get_str (NMStrBuf *strbuf)
+{
+	nm_str_buf_maybe_expand (strbuf, 1, FALSE);
+	strbuf->_str[strbuf->_len] = '\0';
+	return strbuf->_str;
+}
+
+/**
+ * nm_str_buf_finalize:
+ * @strbuf: an initilized #NMStrBuf
+ * @out_len: (out): (allow-none): optional output
+ *   argument with the length of the returned string.
+ *
+ * Returns: (transfer full): the string of the buffer
+ *   which must be freed by the caller. The @strbuf
+ *   is afterwards in undefined state, though it can be
+ *   reused after nm_str_buf_init(). */
+static inline char *
+nm_str_buf_finalize (NMStrBuf *strbuf,
+                     gsize *out_len)
+{
+	nm_str_buf_maybe_expand (strbuf, 1, TRUE);
+	strbuf->_str[strbuf->_len] = '\0';
+
+	NM_SET_OUT (out_len, strbuf->_len);
+
+	/* the buffer is in invalid state afterwards, however, we clear it
+	 * so far, that nm_auto_str_buf and nm_str_buf_destroy() is happy.  */
+	return g_steal_pointer (&strbuf->_str);
+}
+
+/**
+ * nm_str_buf_destroy:
+ * @strbuf: an initialized #NMStrBuf
+ *
+ * Frees the associated memory of @strbuf. The buffer
+ * afterwards is in undefined state, but can be re-initialized
+ * with nm_str_buf_init().
+ */
+static inline void
+nm_str_buf_destroy (NMStrBuf *strbuf)
+{
+	if (!strbuf->_str)
+		return;
+	_nm_str_buf_assert (strbuf);
+	if (strbuf->_do_bzero_mem)
+		nm_explicit_bzero (strbuf->_str, strbuf->_allocated);
+	g_free (strbuf->_str);
+
+	/* the buffer is in invalid state afterwards, however, we clear it
+	 * so far, that nm_auto_str_buf is happy when calling
+	 * nm_str_buf_destroy() again.  */
+	strbuf->_str = NULL;
+}
+
+#define nm_auto_str_buf    nm_auto (nm_str_buf_destroy)
+
+#endif /* __NM_STR_BUF_H__ */