Skip to content

Commit 9f9596e

Browse files
garlickgarlick
committed
doc: pull in flux_conf_t man pages
Problem: there are no man pages for flux_conf_t. Pull them in from flux-core. Also pull in json_pack/json_unpack descriptions they reference. Update dictionary.
1 parent 766a466 commit 9f9596e

File tree

6 files changed

+270
-2
lines changed

6 files changed

+270
-2
lines changed

‎doc/Makefile.am‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,8 @@ MAN3_FILES_PRIMARY = \
1212
man3/idset_encode.3 \
1313
man3/idset_decode.3 \
1414
man3/idset_add.3 \
15-
man3/idset_alloc.3
15+
man3/idset_alloc.3 \
16+
man3/flux_conf_create.3
1617

1718
MAN3_FILES_SECONDARY = \
1819
man3/hostlist_destroy.3 \
@@ -59,7 +60,13 @@ MAN3_FILES_SECONDARY = \
5960
man3/idset_has_intersection.3 \
6061
man3/idset_clear_all.3 \
6162
man3/idset_free.3 \
62-
man3/idset_free_check.3
63+
man3/idset_free_check.3 \
64+
man3/flux_conf_incref.3 \
65+
man3/flux_conf_decref.3 \
66+
man3/flux_conf_copy.3 \
67+
man3/flux_conf_unpack.3 \
68+
man3/flux_conf_pack.3 \
69+
man3/flux_conf_parse.3
6370

6471
RST_FILES = \
6572
$(MAN3_FILES_PRIMARY:.3=.rst)

‎doc/man3/common/json_pack.rst‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
Flux API functions that are based on Jansson's :func:`json_pack`
2+
accept the following tokens in their format string.
3+
The type in parenthesis denotes the resulting JSON type, and
4+
the type in brackets (if any) denotes the C type that is expected as
5+
the corresponding argument or arguments.
6+
7+
**s** (string)['const char \*']
8+
Convert a null terminated UTF-8 string to a JSON string.
9+
10+
**s?** (string)['const char \*']
11+
Like **s**, but if the argument is NULL, outputs a JSON null value.
12+
13+
**s#** (string)['const char \*', 'int']
14+
Convert a UTF-8 buffer of a given length to a JSON string.
15+
16+
**s%** (string)['const char \*', 'size_t']
17+
Like **s#** but the length argument is of type size_t.
18+
19+
**+** ['const char \*']
20+
Like **s**, but concatenate to the previous string.
21+
Only valid after a string.
22+
23+
**+#** ['const char \*', 'int']
24+
Like **s#**, but concatenate to the previous string.
25+
Only valid after a string.
26+
27+
**+%** ['const char \*', 'size_t']
28+
Like **+#**, but the length argument is of type size_t.
29+
30+
**n** (null)
31+
Output a JSON null value. No argument is consumed.
32+
33+
**b** (boolean)['int']
34+
Convert a C int to JSON boolean value. Zero is converted to
35+
*false* and non-zero to *true*.
36+
37+
**i** (integer)['int']
38+
Convert a C int to JSON integer.
39+
40+
**I** (integer)['int64_t']
41+
Convert a C int64_t to JSON integer.
42+
Note: Jansson expects a json_int_t here without committing to a size,
43+
but Flux guarantees that this is a 64-bit integer.
44+
45+
**f** (real)['double']
46+
Convert a C double to JSON real.
47+
48+
**o** (any value)['json_t \*']
49+
Output any given JSON value as-is. If the value is added to an array
50+
or object, the reference to the value passed to **o** is stolen by the
51+
container.
52+
53+
**O** (any value)['json_t \*']
54+
Like **o**, but the argument's reference count is incremented. This
55+
is useful if you pack into an array or object and want to keep the reference
56+
for the JSON value consumed by **O** to yourself.
57+
58+
**o?**, **O?** (any value)['json_t \*']
59+
Like **o** and **O**, respectively, but if the argument is NULL,
60+
output a JSON null value.
61+
62+
**[fmt]** (array)
63+
Build an array with contents from the inner format string. **fmt** may
64+
contain objects and arrays, i.e. recursive value building is supported.
65+
66+
**{fmt}** (object)
67+
Build an object with contents from the inner format string **fmt**.
68+
The first, third, etc. format specifier represent a key, and must be a
69+
string as object keys are always strings. The second, fourth, etc.
70+
format specifier represent a value. Any value may be an object or array,
71+
i.e. recursive value building is supported.
72+
73+
Whitespace, **:** (colon) and **,** (comma) are ignored.
74+
75+
These descriptions came from the Jansson 2.9 manual.
76+
77+
See also: Jansson API: Building Values: http://jansson.readthedocs.io/en/2.9/apiref.html#building-values

‎doc/man3/common/json_unpack.rst‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
Flux API functions that are based on Jansson's :func:`json_unpack`
2+
accept the following tokens in their format string.
3+
The type in parenthesis denotes the resulting JSON type, and
4+
the type in brackets (if any) denotes the C type that is expected as
5+
the corresponding argument or arguments.
6+
7+
**s** (string)['const char \*']
8+
Convert a JSON string to a pointer to a null terminated UTF-8 string.
9+
The resulting string is extracted by using 'json_string_value()'
10+
internally, so it exists as long as there are still references to the
11+
corresponding JSON string.
12+
13+
**s%** (string)['const char \*', 'size_t']
14+
Convert a JSON string to a pointer to a null terminated UTF-8
15+
string and its length.
16+
17+
**n** (null)
18+
Expect a JSON null value. Nothing is extracted.
19+
20+
**b** (boolean)['int']
21+
Convert a JSON boolean value to a C int, so that *true* is converted to 1
22+
and *false* to 0.
23+
24+
**i** (integer)['int']
25+
Convert a JSON integer to a C int.
26+
27+
**I** (integer)['int64_t']
28+
Convert a JSON integer to a C int64_t.
29+
Note: Jansson expects a json_int_t here without committing to a size,
30+
but Flux guarantees that this is a 64-bit integer.
31+
32+
**f** (real)['double']
33+
Convert JSON real to a C double.
34+
35+
**F** (real)['double']
36+
Convert JSON number (integer or real) to a C double.
37+
38+
**o** (any value)['json_t \*']
39+
Store a JSON value, with no conversion, to a json_t pointer.
40+
41+
**O** (any value)['json_t \*']
42+
Like **o**, but the JSON value's reference count is incremented.
43+
44+
**[fmt]** (array)
45+
Convert each item in the JSON array according to the inner format
46+
string. **fmt** may contain objects and arrays, i.e. recursive value
47+
extraction is supported.
48+
49+
**{fmt}** (object)
50+
Convert each item in the JSON object according to the inner format
51+
string **fmt**. The first, third, etc. format specifier represent a
52+
key, and must by **s**. The corresponding argument to unpack functions
53+
is read as the object key. The second, fourth, etc. format specifier
54+
represent a value and is written to the address given as the corresponding
55+
argument. Note that every other argument is read from and every other
56+
is written to. **fmt** may contain objects and arrays as values, i.e.
57+
recursive value extraction is supported. Any **s** representing a key
58+
may be suffixed with **?** to make the key optional. If the key is not
59+
found, nothing is extracted.
60+
61+
**!**
62+
This special format specifier is used to enable the check that all
63+
object and array items are accessed, on a per-value basis. It must
64+
appear inside an array or object as the last format specifier before
65+
the closing bracket or brace.
66+
67+
Whitespace, **:** (colon) and **,** (comma) are ignored.
68+
69+
These descriptions came from the Jansson 2.9 manual.
70+
71+
See also: Jansson API: Parsing and Validating Values: http://jansson.readthedocs.io/en/2.9/apiref.html#parsing-and-validating-values

‎doc/man3/flux_conf_create.rst‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
===================
2+
flux_conf_create(3)
3+
===================
4+
5+
.. default-domain:: c
6+
7+
SYNOPSIS
8+
========
9+
10+
.. code-block:: c
11+
12+
#include <flux/conf.h>
13+
14+
flux_conf_t *flux_conf_create (void);
15+
16+
const flux_conf_t *flux_conf_incref (const flux_conf_t *conf);
17+
18+
void flux_conf_decref (const flux_conf_t *conf);
19+
20+
flux_conf_t *flux_conf_copy (const flux_conf_t *conf);
21+
22+
int flux_conf_unpack (const flux_conf_t *conf,
23+
flux_error_t *error,
24+
const char *fmt,
25+
...);
26+
27+
flux_conf_t *flux_conf_pack (const char *fmt, ...);
28+
29+
flux_conf_t *flux_conf_parse (const char *path, flux_error_t *error);
30+
31+
Link with :command:`-lflux-conf`.
32+
33+
DESCRIPTION
34+
===========
35+
36+
Flux configuration is represented by a :type:`flux_conf_t` object.
37+
38+
:func:`flux_conf_create` creates an empty object with a reference
39+
count of one.
40+
41+
:func:`flux_conf_incref` increments the object reference count.
42+
:func:`flux_conf_decref` decrements the object reference count
43+
and destroys it when the count reaches zero.
44+
45+
:func:`flux_conf_copy` duplicates an object.
46+
47+
:func:`flux_conf_unpack` unpacks an object using Jansson
48+
:func:`json_unpack` style arguments.
49+
50+
:func:`flux_conf_pack` creates an object using Jansson
51+
:func:`json_pack` style arguments.
52+
53+
:func:`flux_conf_parse` parse a TOML configuration file at :var:`path`
54+
and creates a config object that contains the result.
55+
56+
ENCODING JSON PAYLOADS
57+
======================
58+
59+
.. include:: common/json_pack.rst
60+
61+
DECODING JSON PAYLOADS
62+
======================
63+
64+
.. include:: common/json_unpack.rst
65+
66+
RETURN VALUE
67+
============
68+
69+
:func:`flux_conf_create`, :func:`flux_conf_copy`, :func:`flux_conf_pack`,
70+
and :func:`flux_conf_incref` return a :type:`flux_conf_t` object on success.
71+
On error, NULL is returned, and :var:`errno` is set.
72+
73+
:func:`flux_conf_unpack` returns 0 on success, or -1 on failure with
74+
:var:`errno` set.
75+
76+
:func:`flux_conf_parse` returns 0 on success. On error, it returns -1,
77+
:var:`errno` set, and if :var:`error` is non-NULL, it is filled with
78+
a human readable error message.
79+
80+
ERRORS
81+
======
82+
83+
EINVAL
84+
Invalid argument.
85+
86+
ENOMEM
87+
Out of memory.
88+
89+
RESOURCES
90+
=========
91+
92+
.. include:: common/resources.rst
93+
94+
TOML: Tom's Oblivious, Minimal Language https://github.com/toml-lang/toml

‎doc/manpages.py‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,4 +69,11 @@
6969
('man3/idset_alloc','idset_alloc', 'Allocate an id from an idset', [author], 3),
7070
('man3/idset_alloc','idset_free', 'Allocate an id from an idset', [author], 3),
7171
('man3/idset_alloc','idset_free_check', 'Allocate an id from an idset', [author], 3),
72+
('man3/flux_conf_create','flux_conf_create', 'create a config object', [author], 3),
73+
('man3/flux_conf_create','flux_conf_incref', 'take reference on config object', [author], 3),
74+
('man3/flux_conf_create','flux_conf_decref', 'drop reference on config object', [author], 3),
75+
('man3/flux_conf_create','flux_conf_copy', 'copy config object', [author], 3),
76+
('man3/flux_conf_create','flux_conf_unpack', 'parse config object', [author], 3),
77+
('man3/flux_conf_create','flux_conf_pack', 'build config object', [author], 3),
78+
('man3/flux_conf_create','flux_conf_parse', 'parse TOML config', [author], 3),
7279
]

‎doc/test/spell.en.pws‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,3 +40,15 @@ maxid
4040
NUL
4141
ssize
4242
typedef
43+
conf
44+
config
45+
decref
46+
fmt
47+
incref
48+
jansson
49+
jansson's
50+
json
51+
TOML
52+
github
53+
UTF
54+
whitespace

0 commit comments

Comments
 (0)