1libsamba-hostconfig
2-------------------
3
4This directory contains "libsamba-hostconfig".
5
6The libsamba-hostconfig library provides access to all host-wide configuration
7such as the configured shares, default parameter values and host secret keys.
8
9
10Adding a parameter
11------------------
12
13To add or change an smb.conf option, in general you only have to add
14the documentation to docs-xml/smbdotconf, or change it.
15In addition to that, if special defaults are needed, the functions
16loadparm_init() in lib/param/loadparm.c and/or init_globals() in
17source3/param/loadparm.c need to be adapted accordingly.
18The rest is generated for you.
19
20It is important to get the attributes right in the <samba:parameter ...>
21tag of the xml files.  These determine the details of the generated code.
22
23- Supported attributes are name, context, type, constant, function,
24  generated_function, synonym, parm, enumlist, handler, and deprecated.
25- Supported contexts are 'G' (for global) and 'S' (for share).
26- Supported types are boolean, boolean-rev, boolean-auto, list,
27  cmdlist, string, ustring, char, integer, bytes, octal, and enum.
28
29
30
31Using smb.conf parameters in the code
32-------------------------------------
33
34Call the lpcfg_*() function.  To get the lp_ctx, have the caller pass
35it to you.  To get a lp_ctx for the source3/param loadparm system, use:
36
37struct loadparm_context *lp_ctx = loadparm_init_s3(tmp_ctx, loadparm_s3_helpers());
38
39Remember to talloc_unlink(tmp_ctx, lp_ctx) the result when you are done!
40
41To get a lp_ctx for the lib/param loadparm system, typically the
42pointer is already set up by popt at startup, and is passed down from
43cmdline_lp_ctx.
44
45In pure source3/ code, you may use lp_*() functions, but are
46encouraged to use the lpcfg_*() functions so that code can be made
47common.
48
49
50How does loadparm_init_s3() work?
51---------------------------------
52
53loadparm_s3_helpers() returns a initialised table of function
54pointers, pointing at all global lp_*() functions, except for those
55that return substituted strings (% macros).  The lpcfg_*() function
56then calls this plugged in function, allowing the one function and
57pattern to use either loadparm system.
58
59
60There is a lot of generated code, here, what generates what?
61------------------------------------------------------------
62
63The regular format of the CPP macros in param_functions.c is used to
64generate up the prototypes (mkproto.pl, mks3param_proto.pl), the service
65and globals table (mkparamdefs.pl), the glue table (mmks3param.pl) and
66the initilisation of the glue table (mks3param_ctx_table.pl).
67
68I have tried combining some of these, but it just makes the scripts more
69complex.
70
71The CPP macros are defined in and expand in lib/param/loadparm.c and
72source3/param/loadparm.c to read the values from the generated
73stuctures.  They are CPP #included into these files so that the same
74macro has two definitions, depending on the system it is loading into.
75
76
77Why was this done, rather than a 'proper' fix, or just using one system or the other?
78-------------------------------------------------------------------------------------
79
80This was done to allow merging from both ends - merging more parts of
81the loadparm handling, and merging code that needs to read the
82smb.conf, without having to do it all at once.  Ideally
83param_functions.c would be generated from param_table.c or (even
84better) our XML manpage source, and the CPP macros would instead be
85generated expanded as generated C files, but this is a task nobody has
86taken on yet.
87