Welcome to little lamb

Code » limb » master » tree

[master] / src / doc / output.h / die.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
% limb manual
% die(3)
% limb 0.1.0
% 2023-07-24

# NAME

die, dief, diefu, diesys, diefsys, diefusys - write a message to stderr and terminate

# SYNOPSIS

    #include <limb/output.h>
    extern const char *PROG;

```pre hl
void die(<em>exit</em>, ...)
void dief(<em>exit</em>, ...)
void diefu(<em>exit</em>, ...)
void diesys(<em>exit</em>, ...)
void diefsys(<em>exit</em>, ...)
void diefusys(<em>exit</em>, ...)

void dieusage(<em>exit</em>, <em>usage</em>)
void diehelp(<em>exit</em>, <em>usage</em>, <em>help</em>)

void errhelp(<em>exit</em>, <em>usage</em>, <em>help</em>)

void diecmdusage(<em>exit</em>, <em>usage</em>, <em>command</em>)
void diecmdhelp(<em>exit</em>, <em>usage</em>, <em>command</em>)

void dieversion(<em>version</em>, <em>year1</em>, <em>year2</em>, <em>author</em>, <em>url</em>, <em>license</em>)
```

# DESCRIPTION

All of those are implemented as macros (to [err_putmsgdie](3) or
[out_putmsgdie](3) for `dieversion`()) and will write the specified strings to
*stderr* (or *stdout* for `dieversion`()), with a new line added at the end,
then terminate the calling process via [\_exit](3) using `exit` as return/status
code.

One exception is `errhelp`() which is the same as `diehelp`() only based on
[err_putmsg](3), so it will /not/ end program execution. It is mainly intended
for internal use through [dienocommand](3).

<inc obuffers.md>

All messages will be prefixed by the program's name (i.e. value of `PROG`), a
colon and a space.

`dief`() will add "fatal: " after the prefix and before the given strings.

`diefu`() will also add "unable to " before the specified strings.

The `diesys`(), `diefsys`() and `diefusys`() macros are similar, only the
specified strings will be followed by a colon, a space and the error description
provided by [strerror](3) according to `errno`.

! HINT:
! Some special features are supported, to e.g. easily include a number or
! perform escaping of some strings. Refer to [out](3), or directly
! [buffer_putmsg](3), for more.

The `dieusage`() macro writes the word "usage: " followed by the program's name
and a space as prefix, then the `usage` string.

The `diehelp`() macro is similar to `dieusage`(), only adding two new lines
followed by the string `help`.

The `diecmdusage`() macro is similar to `dieusage`() but will add the command's
name and usage line. The command must be a *struct command* as defined in
[command.h](0).

The `diecmdhelp`() macro is similar to `diehelp`() bit will add the command's
name and usage, and show its own help screen. As with `diecmdusage`() the
command must be a *struct command* as defined in [command.h](0).

The `dieversion`() macro writes the program's name (i.e. value of `PROG`), the
string " version " then the specified `version` and a new line.
On a second line is written "Copyright (C) " then `year1`, followed by a dash
and `year2` if it differs from `year1`, then ' - ' followed by `url`
Lastly, if `license` is not `NULL` it is written, else on a new line a line for
"License GPL-2.0" is written.