doc/README.modules

   1 Writing Userinfo Modules
   2 ------------------------
   3
   4 This document describes how to write your own modules for use with the
   5 userinfo utility.
   6
   7 Here are the available functions for modules:
   8
   9     void (ui_module_init)(int *chainable);
  10         Setup any defaults or anything that needs to be initialized for your
  11         module here. The only parameter is a pointer to an integer which
  12         should be set to 1 if the module is chainable and 0 if not. Chainable
  13         means the previous module was passed the -x or -X option and this
  14         module is at the middle or end of the module chain.
  15
  16     void (ui_module_exit)(void);
  17         Your module should free any resources allocated and close any files
  18         here. This is called just before the main program exits.
  19
  20     void *(ui_module_help)(void);
  21         This displays help on the command line. Put a bunch of printf()'s in
  22         here to show available command-line options for your module. Try to
  23         keep the help output consistant with other modules (see -h).
  24
  25     char *(ui_module_options_init)(char **defaults);
  26         This function should return an option string which is compatible with
  27         getopt(3) for any options your module may take. The "defaults"
  28         argument should be the default options you'd want specified (only
  29         options without option arguments are supported) if none are specified
  30         for this module on the command line or in the configuration file. If
  31         your module takes no options then return NULL; this will bypass any
  32         ui_module_options() calls (see below). If you do not want to set any
  33         default options, then set "defaults" to NULL.
  34
  35     int (ui_module_options)(int argc, char **argv);
  36         This function should parse your module command-line options via
  37         getopt(3). It takes two arguments which are the argument count and
  38         argument list as if passed to the main() function.
  39
  40     int (ui_module_exec)(char ***, const struct passwd *, const int, const int,
  41             char *);
  42         This is the main module function. Each module has this function called
  43         in sequence of other modules and not directly after the option
  44         parsing. This should be taken into consideration when loading a module
  45         more than once. It takes a few arguments:
  46             1 - A pointer to an array of character pointers holding strings
  47                 which will be output in the order they have been added. If
  48                 this parameter is initialized (not NULL), then chaining has
  49                 been requested for this module (either -x or -X from the
  50                 command-line, or '>' or '-' from the configuration file).
  51
  52             2 - A password structure for the current username.
  53
  54             3 - A character which separates multi-string values. This can be
  55                 specified on the command line (-m). For example, the password
  56                 module can output all groups a user belongs to. These groups
  57                 are separated by a comma (by default) rather than the field
  58                 deliminator (-F).
  59
  60             4 - Whether the -v option was passed on the command line
  61                 (verbose). Useful if you want to limit the display unless
  62                 otherwise needed.
  63
  64             5 - The strftime() time format. This is either the default or the
  65                 value of the -t command line option. If you have any values
  66                 that contain seconds-from-epoch, you should pass this format
  67                 string to strftime() to maintain output consistency.
  68
  69         This function should return an integer 0 on success or 1 on general
  70         failure. Note that this affects the program exit status.
  71
  72         The output for fields which contain static information should be
  73         consistant with the hardcoded values in the main userinfo utility.
  74         Type 'ui -h' and look for "Output Key" and assign values for the
  75         static fields from this key.
  76
  77 Note that the order of output is dependent on the order of module loading and
  78 the order of module options.
  79
  80 There are three other functions that are built into the userinfo utility which
  81 can be used in your module. The first is a function to add a character string
  82 to an array of character pointers:
  83
  84     void add_string(char ***dest, const char *string);
  85
  86 The first argument is the destination buffer and the second is the string to
  87 add.
  88
  89 The second function is a time format conversion function. It looks like this:
  90
  91     char *stamp(time_t epoch, const char *format);
  92
  93 If you have any information arguments that are time strings, you should try
  94 and convert them to seconds-since-epoch then run them through the above
  95 function. This keeps the time format consistant with other modules (-t command
  96 line option).
  97
  98 Finally, a safer version of strncat(3) that will always nul-terminate the
  99 destination buffer by treating the size N as N-1. Both the dst and src strings
 100 must be nul terminated:
 101
 102     char *safe_strncat(char *dst, const char *src, size_t n);
 103
 104 If you have any questions, feel free to send them to the address below.
 105
 106 Ben Kibbey <bjk@luxsci.net>