external/ibm-public/postfix/dist/src/master/master.h

   1 /*      $NetBSD$        */
   2
   3 /*++
   4 /* NAME
   5 /*      master 3h
   6 /* SUMMARY
   7 /*      Postfix master - data structures and prototypes
   8 /* SYNOPSIS
   9 /*      #include "master.h"
  10 /* DESCRIPTION
  11 /* .nf
  12
  13  /*
  14   * Server processes that provide the same service share a common "listen"
  15   * socket to accept connection requests, and share a common pipe to the
  16   * master process to send status reports. Server processes die voluntarily
  17   * when idle for a configurable amount of time, or after servicing a
  18   * configurable number of requests; the master process spawns new processes
  19   * on demand up to a configurable concurrency limit and/or periodically.
  20   *
  21   * The canonical service name is what we use internally, so that we correctly
  22   * handle a request to "reload" after someone changes "smtp" into "25".
  23   *
  24   * We use the external service name from master.cf when reporting problems, so
  25   * that the user can figure out what we are talking about. Of course we also
  26   * include the canonical service name so that the UNIX-domain smtp service
  27   * can be distinguished from the Internet smtp service.
  28   */
  29 typedef struct MASTER_SERV {
  30     int     flags;                      /* status, features, etc. */
  31     char   *ext_name;                   /* service endpoint name (master.cf) */
  32     char   *name;                       /* service endpoint name (canonical) */
  33     int     type;                       /* UNIX-domain, INET, etc. */
  34     time_t  busy_warn_time;             /* limit "all servers busy" warning */
  35     int     wakeup_time;                /* wakeup interval */
  36     int    *listen_fd;                  /* incoming requests */
  37     int     listen_fd_count;            /* nr of descriptors */
  38     union {
  39         struct {
  40             char   *port;               /* inet listen port */
  41             struct INET_ADDR_LIST *addr;/* inet listen address */
  42         }       inet_ep;
  43 #define MASTER_INET_ADDRLIST(s) ((s)->endpoint.inet_ep.addr)
  44 #define MASTER_INET_PORT(s)     ((s)->endpoint.inet_ep.port)
  45     }       endpoint;
  46     int     max_proc;                   /* upper bound on # processes */
  47     char   *path;                       /* command pathname */
  48     struct ARGV *args;                  /* argument vector */
  49     char   *stress_param_val;           /* stress value: "yes" or empty */
  50     time_t  stress_expire_time;         /* stress pulse stretcher */
  51     int     avail_proc;                 /* idle processes */
  52     int     total_proc;                 /* number of processes */
  53     int     throttle_delay;             /* failure recovery parameter */
  54     int     status_fd[2];               /* child status reports */
  55     struct BINHASH *children;           /* linkage */
  56     struct MASTER_SERV *next;           /* linkage */
  57 } MASTER_SERV;
  58
  59  /*
  60   * Per-service flag bits. We assume trouble when a child process terminates
  61   * before completing its first request: either the program is defective,
  62   * some configuration is wrong, or the system is out of resources.
  63   */
  64 #define MASTER_FLAG_THROTTLE    (1<<0)  /* we're having trouble */
  65 #define MASTER_FLAG_MARK        (1<<1)  /* garbage collection support */
  66 #define MASTER_FLAG_CONDWAKE    (1<<2)  /* wake up if actually used */
  67 #define MASTER_FLAG_INETHOST    (1<<3)  /* endpoint name specifies host */
  68 #define MASTER_FLAG_LOCAL_ONLY  (1<<4)  /* no remote clients */
  69
  70 #define MASTER_THROTTLED(f)     ((f)->flags & MASTER_FLAG_THROTTLE)
  71
  72 #define MASTER_LIMIT_OK(limit, count) ((limit) == 0 || ((count) < (limit)))
  73
  74  /*
  75   * Service types.
  76   */
  77 #define MASTER_SERV_TYPE_UNIX   1       /* AF_UNIX domain socket */
  78 #define MASTER_SERV_TYPE_INET   2       /* AF_INET domain socket */
  79 #define MASTER_SERV_TYPE_FIFO   3       /* fifo (named pipe) */
  80 #define MASTER_SERV_TYPE_PASS   4       /* AF_UNIX domain socket */
  81
  82  /*
  83   * Default process management policy values. This is only the bare minimum.
  84   * Most policy management is delegated to child processes. The process
  85   * manager runs at high privilege level and has to be kept simple.
  86   */
  87 #define MASTER_DEF_MIN_IDLE     1       /* preferred # of idle processes */
  88
  89  /*
  90   * Structure of child process.
  91   */
  92 typedef int MASTER_PID;                 /* pid is key into binhash table */
  93
  94 typedef struct MASTER_PROC {
  95     MASTER_PID pid;                     /* child process id */
  96     unsigned gen;                       /* child generation number */
  97     int     avail;                      /* availability */
  98     MASTER_SERV *serv;                  /* parent linkage */
  99     int     use_count;                  /* number of service requests */
 100 } MASTER_PROC;
 101
 102  /*
 103   * Other manifest constants.
 104   */
 105 #define MASTER_BUF_LEN  2048            /* logical config line length */
 106
 107  /*
 108   * master.c
 109   */
 110 extern int master_detach;
 111
 112  /*
 113   * master_ent.c
 114   */
 115 extern void fset_master_ent(char *);
 116 extern void set_master_ent(void);
 117 extern void end_master_ent(void);
 118 extern void print_master_ent(MASTER_SERV *);
 119 extern MASTER_SERV *get_master_ent(void);
 120 extern void free_master_ent(MASTER_SERV *);
 121
 122  /*
 123   * master_conf.c
 124   */
 125 extern void master_config(void);
 126 extern void master_refresh(void);
 127
 128  /*
 129   * master_vars.c
 130   */
 131 extern void master_vars_init(void);
 132
 133  /*
 134   * master_service.c
 135   */
 136 extern MASTER_SERV *master_head;
 137 extern void master_start_service(MASTER_SERV *);
 138 extern void master_stop_service(MASTER_SERV *);
 139 extern void master_restart_service(MASTER_SERV *);
 140
 141  /*
 142   * master_events.c
 143   */
 144 extern int master_gotsighup;
 145 extern int master_gotsigchld;
 146 extern void master_sigsetup(void);
 147
 148  /*
 149   * master_status.c
 150   */
 151 extern void master_status_init(MASTER_SERV *);
 152 extern void master_status_cleanup(MASTER_SERV *);
 153
 154  /*
 155   * master_wakeup.c
 156   */
 157 extern void master_wakeup_init(MASTER_SERV *);
 158 extern void master_wakeup_cleanup(MASTER_SERV *);
 159
 160
 161  /*
 162   * master_listen.c
 163   */
 164 extern void master_listen_init(MASTER_SERV *);
 165 extern void master_listen_cleanup(MASTER_SERV *);
 166
 167  /*
 168   * master_avail.c
 169   */
 170 extern void master_avail_listen(MASTER_SERV *);
 171 extern void master_avail_cleanup(MASTER_SERV *);
 172 extern void master_avail_more(MASTER_SERV *, MASTER_PROC *);
 173 extern void master_avail_less(MASTER_SERV *, MASTER_PROC *);
 174
 175  /*
 176   * master_spawn.c
 177   */
 178 extern struct BINHASH *master_child_table;
 179 extern void master_spawn(MASTER_SERV *);
 180 extern void master_reap_child(void);
 181 extern void master_delete_children(MASTER_SERV *);
 182
 183  /*
 184   * master_flow.c
 185   */
 186 extern void master_flow_init(void);
 187 extern int master_flow_pipe[2];
 188
 189  /*
 190   * master_watch.c
 191   *
 192   * Support to warn about main.cf parameters that can only be initialized but
 193   * not updated, and to initialize or update data structures that derive
 194   * values from main.cf parameters.
 195   */
 196 typedef struct {
 197     const char *name;                   /* parameter name */
 198     char  **value;                      /* current main.cf value */
 199     char  **backup;                     /* actual value that is being used */
 200     int     flags;                      /* see below */
 201     void    (*notify) (void);           /* init or update data structure */
 202 } MASTER_STR_WATCH;
 203
 204 typedef struct {
 205     const char *name;                   /* parameter name */
 206     int    *value;                      /* current main.cf value */
 207     int     backup;                     /* actual value that is being used */
 208     int     flags;                      /* see below */
 209     void    (*notify) (void);           /* init or update data structure */
 210 } MASTER_INT_WATCH;
 211
 212 #define MASTER_WATCH_FLAG_UPDATABLE (1<<0)      /* support update after init */
 213 #define MASTER_WATCH_FLAG_ISSET    (1<<1)       /* backup is initialized */
 214
 215 extern void master_str_watch(const MASTER_STR_WATCH *);
 216 extern void master_int_watch(MASTER_INT_WATCH *);
 217
 218 /* DIAGNOSTICS
 219 /* BUGS
 220 /* SEE ALSO
 221 /* LICENSE
 222 /* .ad
 223 /* .fi
 224 /*      The Secure Mailer license must be distributed with this software.
 225 /* AUTHOR(S)
 226 /*      Wietse Venema
 227 /*      IBM T.J. Watson Research
 228 /*      P.O. Box 704
 229 /*      Yorktown Heights, NY 10598, USA
 230 /*--*/