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
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
|
.TH LC_SYNC 3 2025-06-09 "LIBRECAST" "Librecast Programmer's Manual"
.SH NAME
lc_sync, lc_syncfile \- synchronize memory or files over multicast
.SH LIBRARY
Librecast library
.RI ( liblibrecast ", " \-llibrecast )
.SH SYNOPSIS
.nf
.B #include <librecast/sync.h>
.PP
.BI "ssize_t lc_sync(lc_ctx_t " *lctx ", unsigned char " *hash ", void " *data ", const size_t " len ",
.BI " q_t " *q ", lc_stat_t " *stats ", lc_sync_options_t " *opt ", int " flags ");"
.BI "ssize_t lc_syncfile(lc_ctx_t " *lctx ", unsigned char " *hash ", const char " *pathname ",
.BI " q_t " *q ", lc_stat_t " *stats ", lc_sync_options_t " *opt ", int " flags ");"
.BI "ssize_t lc_syncfilehash(lc_ctx_t " *lctx ", unsigned char " *hash ", const char " *dst ",
.BI " q_t " *q ", lc_stat_t " *stats ", lc_sync_options_t " *opt ", int " flags ");"
.fi
.PP
Compile and link with \fI\-llibrecast\fP.
.SH DESCRIPTION
The
.BR lc_sync ()
function synchronizes the memory area pointed to by
.IR data
of length
.IR len
with data fetched from the network.
.PP
The
.BR lc_syncfile ()
function synchronizes the file at
.IR pathname
with with data fetched from the network. The file will be created if it does not
exist.
.PP
The
.BR lc_syncfile_hash ()
function synchronizes the file at
.IR pathname
with with data fetched from the network. The file will be created if it does not
exist. If a trailing slash is present it is parsed and removed before calling
.BR lc_syncfile (3).
Similar to
.BR rsync (3),
the presence of a trailing slash on the source directory indicates that the
directories synced are at the same level. The absence of a trailing slash on the
source will cause the directory to be created as a subdirectory on the
destination.
.PP
.IR hash
is used to create the multicast address from which to fetch the merkle tree of
the source data. This tree is compared to the merkle tree of the memory at
.IR data
to find which chunks differ, and these chunks are fetched from the network using
their hashes to create the multicast source addresses.
.PP
.IR lctx
is a Librecast context, created with
.BR lc_ctx_new (3).
.PP
If
.IR q
is not NULL, it must point to a queue
.IR q_t
structure previously initialized with
.BR q_init (3).
This queue will have jobs enqueued to build the tree. This is normally used in
conjunction with a threadpool created with
.BR q_pool_create (3)
with threads all calling
.BR q_job_seek (3).
.PP
If
.IR q
is NULL, the creation and destruction of a queue and threadpool will be handled automatically.
.PP
If
.IR stats
is not NULL, transfer statistics will be returned in this structure.
.PP
.IR opt
is not used, at present, and must be NULL for compatibility with future versions.
.PP
.IR flags
is not used, at present, and must be zero for compatibility with future versions.
.PP
.SH RETURN VALUE
These calls return the number of bytes received, or -1 if an error occurred.
On error, NULL is returned, and
.I errno
is set to indicate the error.
.PP
.SH ERRORS
.TP
.BR EINVAL
Invalid argument.
.PP
.BR ENOMEM
Not enough space/cannot allocate memory (POSIX.1-2001).
.PP
.BR EACCES
Permission to create a socket of the specified type and/or protocol is denied.
.PP
.BR lc_syncfile ()
can also fail with any of the errors for
.BR lc_mmapfile (3).
.PP
.SH NOTES
To restrict syncing to a particular network interface, call
.BR lc_ctx_ifx (3)
to set the default interface for the Librecast context before calling the
appropriate sync function.
.PP
.SH SEE ALSO
.BR lc_ctx_new (3),
.BR lc_ctx_ifx (3),
.BR lc_mmapfile (3),
.BR lc_share (3),
.BR mdex_init (3),
.BR mdex_free (3),
.BR mdex_add (3),
.BR mdex_addfile (3),
.BR mdex_alias (3),
.BR mdex_get (3),
.BR mdex_put (3),
.BR mdex_del (3),
.BR lcrq (7)
|
