Welcome to little lamb

Code » limb » release » tree

[release] / src / doc / autoopt.h / autoopt_quiet.3.md 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
% limb manual
% autoopt_quiet(3)
% limb 0.1.0
% 2023-07-24

# NAME

autoopt\_quiet, autoopt\_verbose, autoopt\_log, autoopt\_debug - automatic
handling of some options

# SYNOPSIS

    #include <limb/autoopt.h>

```pre hl
AUTOOPT_QUIET(<em>shortopt</em>, <em>longopt</em>, <em>flags</em>, <em>id</em>)
AUTOOPT_VERBOSE(<em>shortopt</em>, <em>longopt</em>, <em>flags</em>, <em>id</em>)
AUTOOPT_LOG(<em>shortopt</em>, <em>longopt</em>, <em>flags</em>, <em>id</em>)
AUTOOPT_DEBUG(<em>shortopt</em>, <em>longopt</em>, <em>flags</em>, <em>id</em>)

int autoopt_quiet(const struct option *<em>option</em>, const char *<em>arg</em>)
int autoopt_verbose(const struct option *<em>option</em>, const char *<em>arg</em>)
int autoopt_log(const struct option *<em>option</em>, const char *<em>arg</em>)
int autoopt_debug(const struct option *<em>option</em>, const char *<em>arg</em>)
```

# DESCRIPTION

All of those functions share the same signature, even though they may not be
used. They are intended to be used during parsing of command-line options via
[parseopt](3) (or [loadopt](3)).

As such, the `option` argument is expected to point to the option that is being
parsed/processed. It is used in case of an error (e.g. invalid argument) in
order to mention the option's name in the emitted warning.

All the functions also expected to have been defined through their corresponding
macros, notably if they take a required argument, their argument `arg` is
expected to point to a NUL-terminated string without checking (unlike with an
optional argument).

The *AUTOOPT_QUIET*(), *AUTOOPT_VERBOSE*(), *AUTOOPT_LOG*() and
*AUTOOPT_DEBUG*() macros can be used when defining an array of *struct option*
to be passed to [parseopt](3) or [loadopt](3).

The `autoopt_quiet`() function will bump the output level (of `obuffer_1`, for
*stdout*) down by one level. If already at *OLVL_SILENT* then nothing is done.

The `autoopt_verbose`() function will raise the output level (of `obuffer_1`,
for *stdout*) up by one level. If already at *OLVL_MAXIMUM* then nothing is
done.

! INFO:
! The `obuffer_1` output buffer is used by many of the [output.h](0) macros.

The `autoopt_log`() function parses `arg` as the destination to set up a log
buffer, which will get all messages sent to either `obuffer_1` or `obuffer_2`.
Said parsing is done through [autoopt_parse_buffer_dest](3).

The `autoopt_debug`() function raises the output level (of `obuffer_1`) to
*OLVL_DEBUG* if no argument was specified. Else, it parses `arg` as the
destination to set up a debug buffer, which will get all messages sent to either
`obuffer_1`or `obuffer_2`.
Said parsing is done through [autoopt_parse_buffer_dest](3).

! INFO:
! Duplicating the output is done by creating 2 output buffers backed by the same
! buffer/file descriptor. One is attached to `obuffer_1` whilst the other is
! attached to `obuffer_2`.

# RETURN VALUE

The `autoopt_quiet`() and `autoopt_verbose`() functions always returns 1.

The `autoopt_log`() and `autoopt_debug`() functions return 1 on success.
Otherwise they return 0 and set `errno` to indicate the error. A warning may be
emitted in case of parsing error, see [autoopt_parse_buffer_dest](3) for more.

# ERRORS

The `autoopt_log`() and `autoopt_debug`() functions may fail if :

: *EADDRINUSE*
:: A buffer was already set up using the same function.

The `autoopt_log`() and `autoopt_debug`() functions may also fail for the errors
described for [autoopt_parse_buffer_dest](3).