Merge pull request #328 from npmccallum/master

Helper functions for network IO

1 files changed, 69 insertions, 1 deletions

diff --git a/doc/apiref.rst b/doc/apiref.rst
index ca38bbf..f104ad5 100644
--- a/doc/apiref.rst
+++ b/doc/apiref.rst
@@ -948,6 +948,28 @@ These functions output UTF-8:
    error. *flags* is described above. The return value must be freed
    by the caller using :func:`free()`.
 
+.. function:: size_t json_dumpb(const json_t *json, char *buffer, size_t size, size_t flags)
+
+   Writes the JSON representation of *json* to the *buffer* of
+   *size* bytes. Returns the number of bytes that would be written
+   or 0 on error. *flags* is described above. *buffer* is not
+   null-terminated.
+
+   This function never writes more than *size* bytes. If the return
+   value is greater than *size*, the contents of the *buffer* are
+   undefined. This behavior enables you to specify a NULL *buffer*
+   to determine the length of the encoding. For example::
+
+       size_t size = json_dumpb(json, NULL, 0, 0);
+       if (size == 0)
+           return -1;
+
+       char *buf = alloca(size);
+
+       size = json_dumpb(json, buf, size, 0);
+
+   .. versionadded:: 2.10
+
 .. function:: int json_dumpf(const json_t *json, FILE *output, size_t flags)
 
    Write the JSON representation of *json* to the stream *output*.
@@ -956,6 +978,23 @@ These functions output UTF-8:
    *output*. In this case, the output is undefined and most likely not
    valid JSON.
 
+.. function:: int json_dumpfd(const json_t *json, int output, size_t flags)
+
+   Write the JSON representation of *json* to the stream *output*.
+   *flags* is described above. Returns 0 on success and -1 on error.
+   If an error occurs, something may have already been written to
+   *output*. In this case, the output is undefined and most likely not
+   valid JSON.
+
+   It is important to note that this function can only succeed on stream
+   file descriptors (such as SOCK_STREAM). Using this function on a
+   non-stream file descriptor will result in undefined behavior. For
+   non-stream file descriptors, see instead :func:`json_dumpb()`.
+
+   This function requires POSIX and fails on all non-POSIX systems.
+
+   .. versionadded:: 2.10
+
 .. function:: int json_dump_file(const json_t *json, const char *path, size_t flags)
 
    Write the JSON representation of *json* to the file *path*. If
@@ -1111,7 +1150,7 @@ If no error or position information is needed, you can pass *NULL*.
    above.
 
    This function will start reading the input from whatever position
-   the input file was, without attempting to seek first. If an error
+   the input file was in, without attempting to seek first. If an error
    occurs, the file position will be left indeterminate. On success,
    the file position will be at EOF, unless ``JSON_DISABLE_EOF_CHECK``
    flag was used. In this case, the file position will be at the first
@@ -1120,6 +1159,35 @@ If no error or position information is needed, you can pass *NULL*.
    multiple times, if the input consists of consecutive JSON texts,
    possibly separated by whitespace.
 
+.. function:: json_t *json_loadfd(int input, size_t flags, json_error_t *error)
+
+   .. refcounting:: new
+
+   Decodes the JSON text in stream *input* and returns the array or
+   object it contains, or *NULL* on error, in which case *error* is
+   filled with information about the error. *flags* is described
+   above.
+
+   This function will start reading the input from whatever position
+   the input file descriptor was in, without attempting to seek first.
+   If an error occurs, the file position will be left indeterminate.
+   On success, the file position will be at EOF, unless
+   ``JSON_DISABLE_EOF_CHECK`` flag was used. In this case, the file
+   descriptor's position will be at the first character after the last
+   ``]`` or ``}`` in the JSON input. This allows calling
+   :func:`json_loadfd()` on the same file descriptor multiple times,
+   if the input consists of consecutive JSON texts, possibly separated
+   by whitespace.
+
+   It is important to note that this function can only succeed on stream
+   file descriptors (such as SOCK_STREAM). Using this function on a
+   non-stream file descriptor will result in undefined behavior. For
+   non-stream file descriptors, see instead :func:`json_loadb()`.
+
+   This function requires POSIX and fails on all non-POSIX systems.
+
+   .. versionadded:: 2.10
+
 .. function:: json_t *json_load_file(const char *path, size_t flags, json_error_t *error)
 
    .. refcounting:: new