summaryrefslogtreecommitdiffstats
path: root/lib/param/README
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-05 17:47:29 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-05 17:47:29 +0000
commit4f5791ebd03eaec1c7da0865a383175b05102712 (patch)
tree8ce7b00f7a76baa386372422adebbe64510812d4 /lib/param/README
parentInitial commit. (diff)
downloadsamba-4f5791ebd03eaec1c7da0865a383175b05102712.tar.xz
samba-4f5791ebd03eaec1c7da0865a383175b05102712.zip
Adding upstream version 2:4.17.12+dfsg.upstream/2%4.17.12+dfsgupstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'lib/param/README')
-rw-r--r--lib/param/README86
1 files changed, 86 insertions, 0 deletions
diff --git a/lib/param/README b/lib/param/README
new file mode 100644
index 0000000..d83fe9a
--- /dev/null
+++ b/lib/param/README
@@ -0,0 +1,86 @@
+libsamba-hostconfig
+-------------------
+
+This directory contains "libsamba-hostconfig".
+
+The libsamba-hostconfig library provides access to all host-wide configuration
+such as the configured shares, default parameter values and host secret keys.
+
+
+Adding a parameter
+------------------
+
+To add or change an smb.conf option, in general you only have to add
+the documentation to docs-xml/smbdotconf, or change it.
+In addition to that, if special defaults are needed, the functions
+loadparm_init() in lib/param/loadparm.c and/or init_globals() in
+source3/param/loadparm.c need to be adapted accordingly.
+The rest is generated for you.
+
+It is important to get the attributes right in the <samba:parameter ...>
+tag of the xml files. These determine the details of the generated code.
+
+- Supported attributes are name, context, type, constant, function,
+ generated_function, synonym, parm, enumlist, handler, and deprecated.
+- Supported contexts are 'G' (for global) and 'S' (for share).
+- Supported types are boolean, boolean-rev, boolean-auto, list,
+ cmdlist, string, ustring, char, integer, bytes, octal, and enum.
+
+
+
+Using smb.conf parameters in the code
+-------------------------------------
+
+Call the lpcfg_*() function. To get the lp_ctx, have the caller pass
+it to you. To get a lp_ctx for the source3/param loadparm system, use:
+
+struct loadparm_context *lp_ctx = loadparm_init_s3(tmp_ctx, loadparm_s3_helpers());
+
+Remember to talloc_unlink(tmp_ctx, lp_ctx) the result when you are done!
+
+To get a lp_ctx for the lib/param loadparm system, typically the
+pointer is already set up by popt at startup, and is passed down from
+cmdline_lp_ctx.
+
+In pure source3/ code, you may use lp_*() functions, but are
+encouraged to use the lpcfg_*() functions so that code can be made
+common.
+
+
+How does loadparm_init_s3() work?
+---------------------------------
+
+loadparm_s3_helpers() returns a initialised table of function
+pointers, pointing at all global lp_*() functions, except for those
+that return substituted strings (% macros). The lpcfg_*() function
+then calls this plugged in function, allowing the one function and
+pattern to use either loadparm system.
+
+
+There is a lot of generated code, here, what generates what?
+------------------------------------------------------------
+
+The regular format of the CPP macros in param_functions.c is used to
+generate up the prototypes (mkproto.pl, mks3param_proto.pl), the service
+and globals table (mkparamdefs.pl), the glue table (mmks3param.pl) and
+the initilisation of the glue table (mks3param_ctx_table.pl).
+
+I have tried combining some of these, but it just makes the scripts more
+complex.
+
+The CPP macros are defined in and expand in lib/param/loadparm.c and
+source3/param/loadparm.c to read the values from the generated
+stuctures. They are CPP #included into these files so that the same
+macro has two definitions, depending on the system it is loading into.
+
+
+Why was this done, rather than a 'proper' fix, or just using one system or the other?
+-------------------------------------------------------------------------------------
+
+This was done to allow merging from both ends - merging more parts of
+the loadparm handling, and merging code that needs to read the
+smb.conf, without having to do it all at once. Ideally
+param_functions.c would be generated from param_table.c or (even
+better) our XML manpage source, and the CPP macros would instead be
+generated expanded as generated C files, but this is a task nobody has
+taken on yet.