utils/strbuf: Added SDB_STRBUF_STR.

[sysdb.git] / src / include / utils / strbuf.h

diff --git a/src/include/utils/strbuf.h b/src/include/utils/strbuf.h
index 302cfdde4bb71839b94d86b47c57fe194b9647f2..a9e915537c9d97c03fd94310cfb58b66a3041c34 100644 (file)
--- a/src/include/utils/strbuf.h
+++ b/src/include/utils/strbuf.h
@@ -37,6 +37,7 @@
 
 #include <stdarg.h>
 #include <stdio.h>
+#include <unistd.h>
 
 #ifdef __cplusplus
 extern "C" {
@@ -44,6 +45,13 @@ extern "C" {
 
 typedef struct sdb_strbuf sdb_strbuf_t;
 
+/*
+ * SDB_STRBUF_STR:
+ * Return a tuple of a character array and its length representing the content
+ * of the string buffer.
+ */
+#define SDB_STRBUF_STR(buf) sdb_strbuf_string(buf), sdb_strbuf_len(buf)
+
 /*
  * sdb_strbuf_create, sdb_strbuf_destroy:
  * Allocate / deallocate string buffer objects. The initial size of a newly
@@ -73,9 +81,11 @@ sdb_strbuf_destroy(sdb_strbuf_t *strbuf);
  *  - a negative value on error
  */
 ssize_t
-sdb_strbuf_vappend(sdb_strbuf_t *strbuf, const char *fmt, va_list ap);
+sdb_strbuf_vappend(sdb_strbuf_t *strbuf, const char *fmt, va_list ap)
+               __attribute__((format(printf, 2, 0)));
 ssize_t
-sdb_strbuf_append(sdb_strbuf_t *strbuf, const char *fmt, ...);
+sdb_strbuf_append(sdb_strbuf_t *strbuf, const char *fmt, ...)
+               __attribute__((format(printf, 2, 3)));
 
 /*
  * sdb_strbuf_vsprintf, sdb_strbuf_sprintf:
@@ -89,9 +99,42 @@ sdb_strbuf_append(sdb_strbuf_t *strbuf, const char *fmt, ...);
  *  - a negative value on error
  */
 ssize_t
-sdb_strbuf_vsprintf(sdb_strbuf_t *strbuf, const char *fmt, va_list ap);
+sdb_strbuf_vsprintf(sdb_strbuf_t *strbuf, const char *fmt, va_list ap)
+               __attribute__((format(printf, 2, 0)));
+ssize_t
+sdb_strbuf_sprintf(sdb_strbuf_t *strbuf, const char *fmt, ...)
+               __attribute__((format(printf, 2, 3)));
+
+/*
+ * sdb_strbuf_memcpy, sdb_strbuf_memappend:
+ * Copy or a append a memory area to the buffer. These functions do not
+ * interpret any information in the data pointer (including \0 bytes).
+ *
+ * These functions may be used to handle arbitrary byte arrays. Mixing these
+ * function calls with any of the printf-style function works fine but the
+ * entire buffer content should then be treated as arbitrary bytes.
+ *
+ * Returns:
+ *  - the number of bytes written
+ *  - a negative value on error
+ */
+ssize_t
+sdb_strbuf_memcpy(sdb_strbuf_t *strbuf, const void *data, size_t n);
+ssize_t
+sdb_strbuf_memappend(sdb_strbuf_t *strbuf, const void *data, size_t n);
+
+/*
+ * sdb_strbuf_read:
+ * Read from an open file-descriptor and append the data to the buffer. The
+ * function does not handle *any* read errors. This allows for more
+ * flexibility for the caller regarding the handling of EAGAIN or EWOULDBLOCK.
+ *
+ * Returns:
+ *  - the number of bytes read (zero on EOF)
+ *  - a negative value on error
+ */
 ssize_t
-sdb_strbuf_sprintf(sdb_strbuf_t *strbuf, const char *fmt, ...);
+sdb_strbuf_read(sdb_strbuf_t *strbuf, int fd, size_t n);
 
 /*
  * sdb_strbuf_chomp:
@@ -105,6 +148,20 @@ sdb_strbuf_sprintf(sdb_strbuf_t *strbuf, const char *fmt, ...);
 ssize_t
 sdb_strbuf_chomp(sdb_strbuf_t *strbuf);
 
+/*
+ * sdb_strbuf_skip:
+ * Removes 'n' bytes from the buffer starting at offset 'offset'.
+ */
+void
+sdb_strbuf_skip(sdb_strbuf_t *strbuf, size_t offset, size_t n);
+
+/*
+ * sdb_strbuf_clear:
+ * Clear the buffer but do not deallocate memory.
+ */
+void
+sdb_strbuf_clear(sdb_strbuf_t *strbuf);
+
 /*
  * sdb_strbuf_string:
  * Returns the content of the string buffer. The caller may not modify the
@@ -120,6 +177,15 @@ sdb_strbuf_string(sdb_strbuf_t *strbuf);
 size_t
 sdb_strbuf_len(sdb_strbuf_t *strbuf);
 
+/*
+ * sdb_strbuf_cap:
+ * Returns the current capacity of the string buffer. It describes the max
+ * length of the buffer's content (including terminating nul byte) that may be
+ * stored in the buffer without resizing it.
+ */
+size_t
+sdb_strbuf_cap(sdb_strbuf_t *strbuf);
+
 #ifdef __cplusplus
 } /* extern "C" */
 #endif