Merge branch 'master' of ctdb into 'master' of samba
[sfrench/samba-autobuild/.git] / lib / param / README
1 libsamba-hostconfig
2 -------------------
3
4 This directory contains "libsamba-hostconfig". 
5
6 The libsamba-hostconfig library provides access to all host-wide configuration
7 such as the configured shares, default parameter values and host secret keys.
8
9
10 Adding a parameter
11 ------------------
12
13 To add or change an smb.conf option, you only have to modify
14 lib/param/param_table.c and lib/param/param_functions.c.  The rest is
15 generated for you.
16
17
18 Using smb.conf parameters in the code
19 -------------------------------------
20
21 Call the lpcfg_*() function.  To get the lp_ctx, have the caller pass
22 it to you.  To get a lp_ctx for the source3/param loadparm system, use:
23
24 struct loadparm_context *lp_ctx = loadparm_init_s3(tmp_ctx, loadparm_s3_helpers());
25
26 Remember to talloc_unlink(tmp_ctx, lp_ctx) the result when you are done!
27
28 To get a lp_ctx for the lib/param loadparm system, typically the
29 pointer is already set up by popt at startup, and is passed down from
30 cmdline_lp_ctx.
31
32 In pure source3/ code, you may use lp_*() functions, but are
33 encouraged to use the lpcfg_*() functions so that code can be made
34 common.
35
36
37 How does loadparm_init_s3() work?
38 ---------------------------------
39
40 loadparm_s3_helpers() returns a initialised table of function
41 pointers, pointing at all global lp_*() functions, except for those
42 that return substituted strings (% macros).  The lpcfg_*() function
43 then calls this plugged in function, allowing the one function and
44 pattern to use either loadparm system.
45
46
47 There is a lot of generated code, here, what generates what?
48 ------------------------------------------------------------
49
50 The regular format of the CPP macros in param_functions.c is used to
51 generate up the prototypes (mkproto.pl, mks3param_proto.pl), the service
52 and globals table (mkparamdefs.pl), the glue table (mmks3param.pl) and
53 the initilisation of the glue table (mks3param_ctx_table.pl).
54
55 I have tried combining some of these, but it just makes the scripts more
56 complex.
57
58 The CPP macros are defined in and expand in lib/param/loadparm.c and
59 source3/param/loadparm.c to read the values from the generated
60 stuctures.  They are CPP #included into these files so that the same
61 macro has two definitions, depending on the system it is loading into.
62
63
64 Why was this done, rather than a 'proper' fix, or just using one system or the other?
65 -------------------------------------------------------------------------------------
66
67 This was done to allow merging from both ends - merging more parts of
68 the loadparm handling, and merging code that needs to read the
69 smb.conf, without having to do it all at once.  Ideally
70 param_functions.c would be generated from param_table.c or (even
71 better) our XML manpage source, and the CPP macros would instead be
72 generated expanded as generated C files, but this is a task nobody has
73 taken on yet.