api: add function "asprintf"

1 files changed, 54 insertions, 0 deletions

diff --git a/doc/it/weechat_plugin_api.it.adoc b/doc/it/weechat_plugin_api.it.adoc
index 7ee9cc055..a3fcab585 100644
--- a/doc/it/weechat_plugin_api.it.adoc
+++ b/doc/it/weechat_plugin_api.it.adoc
@@ -568,6 +568,60 @@ num_files = 2
 str = weechat.ngettext("file", "files", num_files)
 ----
 
+==== asprintf
+
+_WeeChat ≥ 4.3.0._
+
+// TRANSLATION MISSING
+Format a message in a string allocated by the function.
+
+// TRANSLATION MISSING
+[NOTE]
+This function is defined for systems where the GNU function `asprintf()`
+is not available. +
+The behavior is almost the same except that `*result` is set to NULL on error.
+
+Prototipo:
+
+[source,c]
+----
+int weechat_asprintf (char **result, const char *fmt, ...);
+----
+
+Argomenti:
+
+// TRANSLATION MISSING
+* _result_: pointer to a string pointer
+// TRANSLATION MISSING
+* _fmt_: format string
+
+Valore restituito:
+
+// TRANSLATION MISSING
+* number of bytes written in `*result` (excluding the final null byte),
+  a negative value in case of error.
+
+Esempio in C:
+
+[source,c]
+----
+char *str;
+
+if (weechat_asprintf (&str, "%s, %d", "test", 42) >= 0)
+{
+    /* *str == "test, 42" */
+    /* ... */
+    free (str);
+}
+else
+{
+    /* error: *str == NULL */
+}
+----
+
+[NOTE]
+Questa funzione non è disponibile nelle API per lo scripting.
+
 ==== strndup
 
 // TRANSLATION MISSING