Welcome to little lamb

Code » limb » master » tree

[master] / src / doc / output.h / out.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
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
% limb manual
% out(3)
% limb 0.1.0
% 2023-07-24

# NAME

out, quiet, verb, err, errverb, sys, sysverb, add, adde, outdie, quietdie,
verbdie, errdie, errverbdie, sysdie, sysverbdie - write text to standard
output/error (and terminate process)

# SYNOPSIS

    #include <limb/output.h>

```pre hl
void quiet(...)
void out(...)
void verb(...)
void err(...)
void errverb(...)
void sys(...)
void sysverb(...)
void dbg(...)
void dbgverb(...)

void add(...)
void adde(...)

void quietdie(<em>exit</em>, ...)
void outdie(<em>exit</em>, ...)
void verbdie(<em>exit</em>, ...)
void errdie(<em>exit</em>, ...)
void errverbdie(<em>exit</em>, ...)
void sysdie(<em>exit</em>, ...)
void sysverbdie(<em>exit</em>, ...)
```

# DESCRIPTION

All of those are implemented as macros and will write to either standard output
or standard error, then maybe terminate the calling process or return.

<inc obuffers.md>

The macro `out`() writes given strings to *stdout* buffers with level
*OLVL_NORMAL* or more, adding a newline and flushing out the buffer.

The macros `quiet`() and `verb`() are similar to `out`(), only with *OLVL_QUIET*
and *OLVL_VERBOSE* levels respectively.

The macro `err`() writes given strings to *stderr* buffers with level
*OLVL_NORMAL* or more, adding a newline and flushing out the buffer.

The macro `errverb`() is similar only with *OLVL_VERSOSE* level.

The macro `add`() writes given strings to *stdout* buffers with *OLVL_NORMAL*.

The macro `adde`() writes given strings to *stderr* buffers with *OLVL_NORMAL*.

The macro `sys`() is similar to `err`() but will add a colon, a space and the
error description from [strerror](3) on `errno` after the given strings.

The macro `sysverb`() is similar only with *OLVL_VERSOSE* level.

The macro `dbg`() is similar to `out`() but with level *OLVL_DEBUG*, and
prefixing with function name, file name and line number (see [dbg_putmsg](3) for
more).

Macros `quietdie`(), `outdie`(), `verbdie`(), `errdie`(), `errverbdie`(),
`sysdie`() and `sysverbdie`() are similar to `quiet`(), `out`(), `verb`(),
`err`(), `errverb`(), `sys`() and `sysverb`() respectively but will terminate
the calling process (via [\_exit](3) using `exit` as status code).

## Escaping

It is possible to use *PUTMSG_ESC* (or simply *ESC*) as one of the strings in
order to toggle escaping. See to [buffer_putmsg](3) for more.

## Numbers

It is possible to add a numbers into a message, to have its value written into
the buffer into decimal form, through the use of macros :

: *PUTMSG_UINT(`n`)*
:: To have the value of unsigned number `n` written out

: *PUTMSG_INT(`n`)*
:: Same as *PUTMSG_UINT(`n`)* but for signed number

Refer to [buffer_putmsg](3) for more.

## Hexadecimal dump

It is possible to specify a byte-array whose content shall be written out as
hexadecimal dump, through the use of macro *PUTMSG_HEX* (or simply *HEX*),
taking two arguments : a pointer to the byte array, and its length.

For more, refer to [buffer_putmsg](3).

# SEE ALSO

[out_putmsg](3), [buffer_putmsg](3)