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 add the documentation to docs-xml/smbdotconf.
  15 If special defaults are needed, the functions loadparm_int() in
  16 lib/param/loadparm.c and/or init_globals() in source3/param/loadparm.c
  17 need to be adapted accordingly.
  18 The rest is generated for you.
  19
  20
  21 Using smb.conf parameters in the code
  22 -------------------------------------
  23
  24 Call the lpcfg_*() function.  To get the lp_ctx, have the caller pass
  25 it to you.  To get a lp_ctx for the source3/param loadparm system, use:
  26
  27 struct loadparm_context *lp_ctx = loadparm_init_s3(tmp_ctx, loadparm_s3_helpers());
  28
  29 Remember to talloc_unlink(tmp_ctx, lp_ctx) the result when you are done!
  30
  31 To get a lp_ctx for the lib/param loadparm system, typically the
  32 pointer is already set up by popt at startup, and is passed down from
  33 cmdline_lp_ctx.
  34
  35 In pure source3/ code, you may use lp_*() functions, but are
  36 encouraged to use the lpcfg_*() functions so that code can be made
  37 common.
  38
  39
  40 How does loadparm_init_s3() work?
  41 ---------------------------------
  42
  43 loadparm_s3_helpers() returns a initialised table of function
  44 pointers, pointing at all global lp_*() functions, except for those
  45 that return substituted strings (% macros).  The lpcfg_*() function
  46 then calls this plugged in function, allowing the one function and
  47 pattern to use either loadparm system.
  48
  49
  50 There is a lot of generated code, here, what generates what?
  51 ------------------------------------------------------------
  52
  53 The regular format of the CPP macros in param_functions.c is used to
  54 generate up the prototypes (mkproto.pl, mks3param_proto.pl), the service
  55 and globals table (mkparamdefs.pl), the glue table (mmks3param.pl) and
  56 the initilisation of the glue table (mks3param_ctx_table.pl).
  57
  58 I have tried combining some of these, but it just makes the scripts more
  59 complex.
  60
  61 The CPP macros are defined in and expand in lib/param/loadparm.c and
  62 source3/param/loadparm.c to read the values from the generated
  63 stuctures.  They are CPP #included into these files so that the same
  64 macro has two definitions, depending on the system it is loading into.
  65
  66
  67 Why was this done, rather than a 'proper' fix, or just using one system or the other?
  68 -------------------------------------------------------------------------------------
  69
  70 This was done to allow merging from both ends - merging more parts of
  71 the loadparm handling, and merging code that needs to read the
  72 smb.conf, without having to do it all at once.  Ideally
  73 param_functions.c would be generated from param_table.c or (even
  74 better) our XML manpage source, and the CPP macros would instead be
  75 generated expanded as generated C files, but this is a task nobody has
  76 taken on yet.