Welcome to little lamb

Code » limb » master » tree

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

# NAME

patrim\_put, patrim\_get, patrim\_isblob, patrim\_isint, patrim\_isshldata -
encode/decode data in PATRIM format

# SYNOPSIS

    #include <limb/patrim.h>

```pre hl
int patrim_put(char *<em>dst</em>, size_t <em>dlen</em>, size_t <em>offset</em>, u64 <em>id</em>, u64 <em>u</em>)
int patrim_get(u64 *<em>id</em>, u64 *<em>u</em>, const char *<em>data</em>, size_t <em>dlen</em>, size_t <em>offset</em>)

int patrim_isblob(u64 <em>id</em>)
int patrim_isint(u64 <em>id</em>)
int patrim_isshldata(u64 <em>id</em>)
```

# DESCRIPTION

The `patrim_put`() function will encode into the memory pointed by `dst` of
length `dlen`, starting at byte `offset`, the data for the given `id` and its
associated value or length, `u`.

So `u` must be either the value if `id` represents an integer, or the length of
the blob if `id` represents a blob. The actual data/blob content should
obviously be added afterwards.

The `patrim_get`() function will read the memory pointed by `data`, starting at
byte `offset` and not going past `dlen` bytes, decoding PATRIM-encoded data and
placing the ID in the memory pointed by `id` and either the value of data
length, depending whether the ID of that of an integer or a blob respectively,
into the memory pointed by `u`.

The `patrim_isblob`() macro returns 1 if the `id` if that of a blob, zero
otherwise.

The `patrim_isint`() macro returns 1 if the `id` if that of an integer, zero
otherwise.

The `patrim_isshldata`() macro returns 1 if the `id` is one that belongs to the
"shielded data" protocol - as described in [shldata](5). Note that this /only
applies/ when e.g. reading a shielded data file.

# RETURN VALUE

On success the `patrim_put`() and `patrim_get`() functions return the number of
bytes written into `dst` or read from `data`, respectively. Otherwise - meaning
not enough bytes could be written or read - they return -1.

The `patrim_isblob`() and `patrim_isint`() macros return 1 id `id` represents a
blob or an integer, respectively, otherwise they return 0.

The `patrim_isshldata`() macro returns 1 if `id` belongs to the shielded data
protocol, 0 otherwise. Note that this is only applicable when e.g. reading a
shielded data file.