chiark - git - mdw - fwd/blob - fwd.h

   1 /* -*-c-*-
   2  *
   3  * Main header file for port forwarder
   4  *
   5  * (c) 1999 Straylight/Edgeware
   6  */
   7
   8 /*----- Licensing notice --------------------------------------------------*
   9  *
  10  * This file is part of the `fwd' port forwarder.
  11  *
  12  * `fwd' is free software; you can redistribute it and/or modify
  13  * it under the terms of the GNU General Public License as published by
  14  * the Free Software Foundation; either version 2 of the License, or
  15  * (at your option) any later version.
  16  *
  17  * `fwd' is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  * GNU General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU General Public License
  23  * along with `fwd'; if not, write to the Free Software Foundation,
  24  * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  25  */
  26
  27 #ifndef FW_H
  28 #define FW_H
  29
  30 #ifdef __cplusplus
  31   extern "C" {
  32 #endif
  33
  34 /*----- Header files ------------------------------------------------------*/
  35
  36 /* --- Configuration --- */
  37
  38 #include "config.h"
  39 #define _GNU_SOURCE
  40
  41 /* --- ANSI C --- */
  42
  43 #include <assert.h>
  44 #include <ctype.h>
  45 #include <errno.h>
  46 #include <float.h>
  47 #include <limits.h>
  48 #include <math.h>
  49 #include <signal.h>
  50 #include <stdarg.h>
  51 #include <stddef.h>
  52 #include <stdio.h>
  53 #include <stdlib.h>
  54 #include <string.h>
  55 #include <time.h>
  56
  57 /* --- Unix --- */
  58
  59 #include <fcntl.h>
  60 #include <unistd.h>
  61
  62 #include <sys/types.h>
  63 #include <sys/stat.h>
  64 #include <sys/time.h>
  65 #include <sys/resource.h>
  66 #include <sys/uio.h>
  67 #include <sys/wait.h>
  68
  69 #include <sys/socket.h>
  70 #include <sys/un.h>
  71 #include <netinet/in.h>
  72 #include <arpa/inet.h>
  73 #include <netdb.h>
  74
  75 #include <pwd.h>
  76 #include <grp.h>
  77
  78 #include <syslog.h>
  79
  80 /* --- mLib --- */
  81
  82 #include <mLib/alloc.h>
  83 #include <mLib/bres.h>
  84 #include <mLib/conn.h>
  85 #include <mLib/darray.h>
  86 #include <mLib/dstr.h>
  87 #include <mLib/env.h>
  88 #include <mLib/fdflags.h>
  89 #include <mLib/fdpass.h>
  90 #include <mLib/ident.h>
  91 #include <mLib/macros.h>
  92 #include <mLib/mdup.h>
  93 #include <mLib/mdwopt.h>
  94 #include <mLib/quis.h>
  95 #include <mLib/report.h>
  96 #include <mLib/sel.h>
  97 #include <mLib/selbuf.h>
  98 #include <mLib/sig.h>
  99 #include <mLib/str.h>
 100 #include <mLib/sub.h>
 101 #include <mLib/sym.h>
 102 #include <mLib/tv.h>
 103
 104 /*----- Other subtleties --------------------------------------------------*/
 105
 106 #if defined(HAVE_DECL_ENVIRON) && !HAVE_DECL_ENVIRON
 107   extern char **environ;
 108 #endif
 109
 110 /*----- Resource limit names ----------------------------------------------*/
 111
 112 #if defined(RLIMIT_OFILE) && !defined(RLIMIT_NOFILE)
 113 #  define RLIMIT_NOFILE RLIMIT_OFILE
 114 #endif
 115
 116 /*
 117    ;;; The resource-limit name table is very boring to type and less fun to
 118    ;;; maintain.  To make life less awful, put the names in this list and
 119    ;;; evaluate the code to get Emacs to regenerate it.
 120
 121    (let ((limits '(as core cpu data fsize locks memlock msgqueue
 122                    nice nofile nproc rss rtprio sigpending stack
 123                    vmem)))
 124      (save-excursion
 125        (goto-char
 126         (point-min))
 127        (search-forward (concat "***" "BEGIN rlimitlist" "***"))
 128        (beginning-of-line 2)
 129        (delete-region (point)
 130                       (progn
 131                         (search-forward "***END***")
 132                         (beginning-of-line)
 133                         (point)))
 134        (let ((avail (make-marker))
 135              (list (make-marker)))
 136          (set-marker avail (point))
 137          (insert "#define RLIMITS(_)")
 138          (set-marker list (point))
 139          (dolist (limit (sort (copy-list limits) #'string<))
 140            (let* ((name (symbol-name limit))
 141                   (constant (concat "RLIMIT_" (upcase name)))
 142                   (have (concat "HAVE_" constant "_P")))
 143              (goto-char avail)
 144              (insert-before-markers (format (concat "#ifdef %s\n"
 145                                                     "#  define %s t\n"
 146                                                     "#else\n"
 147                                                     "#  define %s nil\n"
 148                                                     "#endif\n")
 149                                             constant have have))
 150              (goto-char list)
 151              (insert-before-markers
 152               (format " \\\n  MAYBE_ITEM(_, %s, (%s, %s))"
 153                       have name constant))))
 154          (goto-char list)
 155          (insert "\n"))))
 156 */
 157
 158 /***BEGIN rlimitlist***/
 159 #ifdef RLIMIT_AS
 160 #  define HAVE_RLIMIT_AS_P t
 161 #else
 162 #  define HAVE_RLIMIT_AS_P nil
 163 #endif
 164 #ifdef RLIMIT_CORE
 165 #  define HAVE_RLIMIT_CORE_P t
 166 #else
 167 #  define HAVE_RLIMIT_CORE_P nil
 168 #endif
 169 #ifdef RLIMIT_CPU
 170 #  define HAVE_RLIMIT_CPU_P t
 171 #else
 172 #  define HAVE_RLIMIT_CPU_P nil
 173 #endif
 174 #ifdef RLIMIT_DATA
 175 #  define HAVE_RLIMIT_DATA_P t
 176 #else
 177 #  define HAVE_RLIMIT_DATA_P nil
 178 #endif
 179 #ifdef RLIMIT_FSIZE
 180 #  define HAVE_RLIMIT_FSIZE_P t
 181 #else
 182 #  define HAVE_RLIMIT_FSIZE_P nil
 183 #endif
 184 #ifdef RLIMIT_LOCKS
 185 #  define HAVE_RLIMIT_LOCKS_P t
 186 #else
 187 #  define HAVE_RLIMIT_LOCKS_P nil
 188 #endif
 189 #ifdef RLIMIT_MEMLOCK
 190 #  define HAVE_RLIMIT_MEMLOCK_P t
 191 #else
 192 #  define HAVE_RLIMIT_MEMLOCK_P nil
 193 #endif
 194 #ifdef RLIMIT_MSGQUEUE
 195 #  define HAVE_RLIMIT_MSGQUEUE_P t
 196 #else
 197 #  define HAVE_RLIMIT_MSGQUEUE_P nil
 198 #endif
 199 #ifdef RLIMIT_NICE
 200 #  define HAVE_RLIMIT_NICE_P t
 201 #else
 202 #  define HAVE_RLIMIT_NICE_P nil
 203 #endif
 204 #ifdef RLIMIT_NOFILE
 205 #  define HAVE_RLIMIT_NOFILE_P t
 206 #else
 207 #  define HAVE_RLIMIT_NOFILE_P nil
 208 #endif
 209 #ifdef RLIMIT_NPROC
 210 #  define HAVE_RLIMIT_NPROC_P t
 211 #else
 212 #  define HAVE_RLIMIT_NPROC_P nil
 213 #endif
 214 #ifdef RLIMIT_RSS
 215 #  define HAVE_RLIMIT_RSS_P t
 216 #else
 217 #  define HAVE_RLIMIT_RSS_P nil
 218 #endif
 219 #ifdef RLIMIT_RTPRIO
 220 #  define HAVE_RLIMIT_RTPRIO_P t
 221 #else
 222 #  define HAVE_RLIMIT_RTPRIO_P nil
 223 #endif
 224 #ifdef RLIMIT_SIGPENDING
 225 #  define HAVE_RLIMIT_SIGPENDING_P t
 226 #else
 227 #  define HAVE_RLIMIT_SIGPENDING_P nil
 228 #endif
 229 #ifdef RLIMIT_STACK
 230 #  define HAVE_RLIMIT_STACK_P t
 231 #else
 232 #  define HAVE_RLIMIT_STACK_P nil
 233 #endif
 234 #ifdef RLIMIT_VMEM
 235 #  define HAVE_RLIMIT_VMEM_P t
 236 #else
 237 #  define HAVE_RLIMIT_VMEM_P nil
 238 #endif
 239 #define RLIMITS(_) \
 240   MAYBE_ITEM(_, HAVE_RLIMIT_AS_P, (as, RLIMIT_AS)) \
 241   MAYBE_ITEM(_, HAVE_RLIMIT_CORE_P, (core, RLIMIT_CORE)) \
 242   MAYBE_ITEM(_, HAVE_RLIMIT_CPU_P, (cpu, RLIMIT_CPU)) \
 243   MAYBE_ITEM(_, HAVE_RLIMIT_DATA_P, (data, RLIMIT_DATA)) \
 244   MAYBE_ITEM(_, HAVE_RLIMIT_FSIZE_P, (fsize, RLIMIT_FSIZE)) \
 245   MAYBE_ITEM(_, HAVE_RLIMIT_LOCKS_P, (locks, RLIMIT_LOCKS)) \
 246   MAYBE_ITEM(_, HAVE_RLIMIT_MEMLOCK_P, (memlock, RLIMIT_MEMLOCK)) \
 247   MAYBE_ITEM(_, HAVE_RLIMIT_MSGQUEUE_P, (msgqueue, RLIMIT_MSGQUEUE)) \
 248   MAYBE_ITEM(_, HAVE_RLIMIT_NICE_P, (nice, RLIMIT_NICE)) \
 249   MAYBE_ITEM(_, HAVE_RLIMIT_NOFILE_P, (nofile, RLIMIT_NOFILE)) \
 250   MAYBE_ITEM(_, HAVE_RLIMIT_NPROC_P, (nproc, RLIMIT_NPROC)) \
 251   MAYBE_ITEM(_, HAVE_RLIMIT_RSS_P, (rss, RLIMIT_RSS)) \
 252   MAYBE_ITEM(_, HAVE_RLIMIT_RTPRIO_P, (rtprio, RLIMIT_RTPRIO)) \
 253   MAYBE_ITEM(_, HAVE_RLIMIT_SIGPENDING_P, (sigpending, RLIMIT_SIGPENDING)) \
 254   MAYBE_ITEM(_, HAVE_RLIMIT_STACK_P, (stack, RLIMIT_STACK)) \
 255   MAYBE_ITEM(_, HAVE_RLIMIT_VMEM_P, (vmem, RLIMIT_VMEM))
 256 /***END***/
 257
 258 /* --- The unpleasant conditional-output machinery --- */
 259
 260 #define MAYBE_ITEM(_, emitp, args) GLUE(MAYBE_ITEM_, emitp)(_, args)
 261 #define MAYBE_ITEM_t(_, args) _ args
 262 #define MAYBE_ITEM_nil(_, args)
 263
 264 /*----- Main program ------------------------------------------------------*/
 265
 266 /* --- The global select state --- */
 267
 268 extern sel_state *sel;
 269
 270 /* --- Global state flags --- */
 271
 272 extern unsigned flags;
 273
 274 #define FW_SYSLOG 1u
 275 #define FW_QUIET 2u
 276 #define FW_SET 4u
 277
 278 /* --- Help text --- */
 279
 280 extern const char grammar_text[];
 281 extern const char option_text[];
 282
 283 /* --- Generally useful magic constants --- */
 284
 285 #define NOW ((time_t)-1)
 286
 287 /* --- @fw_log@ --- *
 288  *
 289  * Arguments:   @time_t t@ = when the connection occurred or (@NOW@)
 290  *              @const char *fmt@ = format string to fill in
 291  *              @...@ = other arguments
 292  *
 293  * Returns:     ---
 294  *
 295  * Use:         Logs a connection.
 296  */
 297
 298 extern void PRINTF_LIKE(2, 3)
 299   fw_log(time_t /*t*/, const char */*fmt*/, ...);
 300
 301 /* --- @fw_inc@, @fw_dec@ --- *
 302  *
 303  * Arguments:   ---
 304  *
 305  * Returns:     ---
 306  *
 307  * Use:         Increments or decrements the active thing count.  `fwd' won't
 308  *              quit while there are active things.
 309  */
 310
 311 extern void fw_inc(void);
 312 extern void fw_dec(void);
 313
 314 /*----- Channel management ------------------------------------------------*/
 315
 316 /* --- Magic numbers --- */
 317
 318 #define CHAN_BUFSZ 4096
 319
 320 /* --- Channel structure --- */
 321
 322 typedef struct chan {
 323   unsigned base, len;                   /* Base and length of data */
 324   unsigned f;                           /* Various interesting flags */
 325   void (*func)(void */*p*/);            /* Function to call on closure */
 326   int err;                              /* What's wrong with the channel */
 327   void *p;                              /* Argument to pass function */
 328   sel_file r, w;                        /* Reader and writer selectors */
 329   char buf[CHAN_BUFSZ];                 /* The actual data buffer */
 330 } chan;
 331
 332 #define CHANF_CLOSE 1u                  /* Close channel when buffer empty */
 333 #define CHANF_READY 2u                  /* The channel destination exists */
 334
 335 /* --- @chan_close@ --- *
 336  *
 337  * Arguments:   @chan *c@ = pointer to channel
 338  *
 339  * Returns:     ---
 340  *
 341  * Use:         Closes down a channel prematurely.
 342  */
 343
 344 extern void chan_close(chan */*c*/);
 345
 346 /* --- @chan_dest@ --- *
 347  *
 348  * Arguments:   @chan *c@ = pointer to channel
 349  *              @int fd@ = destination file descriptor for channel
 350  *
 351  * Returns:     ---
 352  *
 353  * Use:         Sets the channel's destination so it knows where to put
 354  *              data.
 355  */
 356
 357 extern void chan_dest(chan */*c*/, int /*fd*/);
 358
 359 /* --- @chan_open@ --- *
 360  *
 361  * Arguments:   @chan *c@ = pointer to channel to open
 362  *              @int from, to@ = source and destination file descriptors
 363  *              @void (*func)(void *p)@ = function to call on closure
 364  *              @void *p@ = argument to pass to function
 365  *
 366  * Returns:     ---
 367  *
 368  * Use:         Opens a channel.  Data is copied from the source to the
 369  *              destination.  The @to@ argument may be @-1@ if the file
 370  *              descriptor isn't known yet.
 371  */
 372
 373 extern void chan_open(chan */*c*/, int /*from*/, int /*to*/,
 374                       void (*/*func*/)(void */*p*/), void */*p*/);
 375
 376 /*----- Character scanners ------------------------------------------------*/
 377
 378 /* --- A low-level scanner source --- */
 379
 380 typedef struct scansrc {
 381   struct scansrc *next;                 /* Next one in the list */
 382   struct scansrc_ops *ops;              /* Pointer to operations table */
 383   char *src;                            /* Name of this source */
 384   int line;                             /* Current line number */
 385   dstr pushback;                        /* Pushback characters */
 386   char *tok;                            /* Token pushback */
 387   unsigned t;                           /* Token type pushback */
 388 } scansrc;
 389
 390 /* --- Scanner source operations --- */
 391
 392 typedef struct scansrc_ops {
 393   int (*scan)(scansrc */*ss*/);         /* Read another character */
 394   void (*destroy)(scansrc */*ss*/);     /* Destroy an unwanted source */
 395 } scansrc_ops;
 396
 397 /* --- A character scanner --- */
 398
 399 typedef struct scanner {
 400   scansrc *head, **tail;                /* Scanner list head and tail */
 401   int t;                                /* Token type */
 402   dstr d;                               /* Current token value */
 403   const char *wbegin, *wcont;           /* Parsing exception strings */
 404 } scanner;
 405
 406 /* --- @scan_file@ --- *
 407  *
 408  * Arguments:   @FILE *fp@ = pointer to file descriptor
 409  *              @const char *name@ = pointer to source file name
 410  *              @unsigned f@ = flags
 411  *
 412  * Returns:     A scanner source.
 413  *
 414  * Use:         Creates a new scanner source for reading from a file.
 415  */
 416
 417 #define SCF_NOCLOSE 1u                  /* Don't close @fp@ when finished */
 418
 419 extern scansrc *scan_file(FILE */*fp*/, const char */*name*/,
 420                           unsigned /*f*/);
 421
 422 /* --- @scan_argv@ --- *
 423  *
 424  * Arguments:   @char **av@ = pointer to argument array (null terminated)
 425  *
 426  * Returns:     A scanner source.
 427  *
 428  * Use:         Creates a new scanner source for reading from an @argv@
 429  *              array.
 430  */
 431
 432 extern scansrc *scan_argv(char **/*av*/);
 433
 434 /* --- @scan@ --- *
 435  *
 436  * Arguments:   @scanner *sc@ = pointer to main scanner context
 437  *
 438  * Returns:     Character read, or end-of-file.
 439  *
 440  * Use:         Scans a character from a source of characters.
 441  */
 442
 443 extern int scan(scanner */*sc*/);
 444
 445 /* --- @unscan@ --- *
 446  *
 447  * Arguments:   @scanner *sc@ = pointer to main scanner context
 448  *              @int ch@ = character to unscan
 449  *
 450  * Returns:     ---
 451  *
 452  * Use:         Scans a character from a source of characters.
 453  */
 454
 455 extern void unscan(scanner */*sc*/, int /*ch*/);
 456
 457 /* --- @scan_push@ --- *
 458  *
 459  * Arguments:   @scanner *sc@ = pointer to main scanner context
 460  *              @scansrc *ss@ = souorce to push
 461  *
 462  * Returns:     ---
 463  *
 464  * Use:         Pushes a scanner source onto the front of the queue.
 465  */
 466
 467 extern void scan_push(scanner */*sc*/, scansrc */*ss*/);
 468
 469 /* --- @scan_add@ --- *
 470  *
 471  * Arguments:   @scanner *sc@ = pointer to main scanner context
 472  *              @scansrc *ss@ = souorce to push
 473  *
 474  * Returns:     ---
 475  *
 476  * Use:         Adds a scanner source onto the end of the queue.
 477  */
 478
 479 extern void scan_add(scanner */*sc*/, scansrc */*ss*/);
 480
 481 /* --- @scan_create@ --- *
 482  *
 483  * Arguments:   @scanner *sc@ = scanner context to initialize
 484  *
 485  * Returns:     ---
 486  *
 487  * Use:         Initializes a scanner block ready for use.
 488  */
 489
 490 extern void scan_create(scanner */*sc*/);
 491
 492 /* --- @scan_destroy@ --- *
 493  *
 494  * Arguments:   @scanner *sc@ = pointer to scanner context
 495  *
 496  * Returns:     ---
 497  *
 498  * Use:         Destroys a scanner and all the sources attached to it.
 499  */
 500
 501 extern void scan_destroy(scanner */*sc*/);
 502
 503 /*----- Configuration parsing ---------------------------------------------*/
 504
 505 /* --- Magical constants --- */
 506
 507 #define CTOK_EOF (-1)
 508 #define CTOK_WORD 256
 509
 510 /* --- @conf_undelim@ --- *
 511  *
 512  * Arguments:   @scanner *sc@ = pointer to scanner definition
 513  *              @const char *d, *dd@ = pointer to characters to escape
 514  *
 515  * Returns:     ---
 516  *
 517  * Use:         Modifies the tokenizer.  Characters in the first list will
 518  *              always be considered to begin a word.  Characters in the
 519  *              second list will always be allowed to continue a word.
 520  */
 521
 522 extern void conf_undelim(scanner */*sc*/,
 523                          const char */*d*/, const char */*dd*/);
 524
 525 /* --- @token@ --- *
 526  *
 527  * Arguments:   @scanner *sc@ = pointer to scanner definition
 528  *
 529  * Returns:     Type of token scanned.
 530  *
 531  * Use:         Reads the next token from the character scanner.
 532  */
 533
 534 extern int token(scanner */*sc*/);
 535
 536 /* --- @error@ --- *
 537  *
 538  * Arguments:   @scanner *sc@ = pointer to scanner definition
 539  *              @const char *msg@ = message skeleton string
 540  *              @...@ = extra arguments for the skeleton
 541  *
 542  * Returns:     Doesn't
 543  *
 544  * Use:         Reports an error at the current scanner location.
 545  */
 546
 547 extern void PRINTF_LIKE(2, 3) NORETURN
 548   error(scanner */*sc*/, const char */*msg*/, ...);
 549
 550 /* --- @pushback@ --- *
 551  *
 552  * Arguments:   @scanner *sc@ = pointer to scanner definition
 553  *
 554  * Returns:     ---
 555  *
 556  * Use:         Pushes the current token back.  This is normally a precursor
 557  *              to pushing a new scanner source.
 558  */
 559
 560 extern void pushback(scanner */*sc*/);
 561
 562 /* --- @conf_enum@ --- *
 563  *
 564  * Arguments:   @scanner *sc@ = pointer to a scanner object
 565  *              @const char *list@ = comma-separated things to allow
 566  *              @unsigned @f = flags for the search
 567  *              @const char *err@ = error message if not found
 568  *
 569  * Returns:     Index into list, zero-based, or @-1@.
 570  *
 571  * Use:         Checks whether the current token is a string which matches
 572  *              one of the comma-separated items given.  The return value is
 573  *              the index (zero-based) of the matched string in the list.
 574  *
 575  *              The flags control the behaviour if no exact match is found.
 576  *              If @ENUM_ABBREV@ is set, and the current token is a left
 577  *              substring of exactly one of the possibilities, then that one
 578  *              is chosen.  If @ENUM_NONE@ is set, the value @-1@ is
 579  *              returned; otherwise an error is reported and the program is
 580  *              terminated.
 581  */
 582
 583 #define ENUM_ABBREV 1u
 584 #define ENUM_NONE 2u
 585
 586 extern int conf_enum(scanner */*sc*/, const char */*list*/,
 587                      unsigned /*flags*/, const char */*err*/);
 588
 589 /* --- @conf_prefix@ --- *
 590  *
 591  * Arguments:   @scanner *sc@ = pointer to a scanner object
 592  *              @const char *p@ = pointer to prefix string to check
 593  *
 594  * Returns:     Nonzero if the prefix matches.
 595  *
 596  * Use:         If the current token is a word matching the given prefix
 597  *              string, then it and an optional `.' character are removed and
 598  *              a nonzero result is returned.  Otherwise the current token is
 599  *              left as it is, and zero is returned.
 600  *
 601  *              Typical options parsing code would remove an expected prefix,
 602  *              scan an option anyway (since qualifying prefixes are
 603  *              optional) and if a match is found, claim the option.  If no
 604  *              match is found, and a prefix was stripped, then an error
 605  *              should be reported.
 606  */
 607
 608 extern int conf_prefix(scanner */*sc*/, const char */*p*/);
 609
 610 /* --- @CONF_BEGIN@, @CONF_END@ --- *
 611  *
 612  * Arguments:   @sc@ = scanner to read from
 613  *              @prefix@ = prefix to scan for
 614  *              @desc@ = description of what we're parsing
 615  *
 616  * Use:         Bracket an options parsing routine.  The current token is
 617  *              checked to see whether it matches the prefix.  If so, it is
 618  *              removed and the following token examined.  If that's a `.'
 619  *              then it's removed.  If it's a `{' then the enclosed
 620  *              option-parsing code is executed in a loop until a matching
 621  *              '}' is found.  If the options parser doesn't accept an
 622  *              option, the behaviour is dependent on whether a prefix was
 623  *              seen: if so, an error is reported; otherwse a zero return is
 624  *              made.
 625  */
 626
 627 #define CS_PLAIN 0
 628 #define CS_PREFIX 1
 629 #define CS_BRACE 2
 630 #define CS_UNKNOWN 3
 631
 632 #define CONF_BEGIN(sc, prefix, desc) do {                               \
 633   scanner *_conf_sc = (sc);                                             \
 634   const char *_conf_desc = (desc);                                      \
 635   int _conf_state = CS_PLAIN;                                           \
 636                                                                         \
 637   /* --- Read the initial prefix --- */                                 \
 638                                                                         \
 639   if (_conf_sc->t == CTOK_WORD &&                                       \
 640       strcmp(_conf_sc->d.buf, (prefix)) == 0) {                         \
 641     token(_conf_sc);                                                    \
 642     _conf_state = CS_PREFIX;                                            \
 643     if (_conf_sc->t == '.')                                             \
 644       token(_conf_sc);                                                  \
 645     else if (_conf_sc->t == '{') {                                      \
 646       token(_conf_sc);                                                  \
 647       _conf_state = CS_BRACE;                                           \
 648     }                                                                   \
 649   }                                                                     \
 650                                                                         \
 651   /* --- Ensure the next token is a word --- */                         \
 652                                                                         \
 653   if (_conf_sc->t != CTOK_WORD)                                         \
 654     error(_conf_sc, "parse error, expected option keyword");            \
 655   do {
 656
 657 #define CONF_END                                                        \
 658                                                                         \
 659     /* --- Reject an option --- *                                       \
 660      *                                                                  \
 661      * We could get here as a result of an explicit @CONF_REJECT@ or    \
 662      * because the option wasn't accepted.                              \
 663      */                                                                 \
 664                                                                         \
 665     goto _conf_reject;                                                  \
 666   _conf_reject:                                                         \
 667     if (_conf_state == CS_PLAIN)                                        \
 668       _conf_state = CS_UNKNOWN;                                         \
 669     else {                                                              \
 670       error(_conf_sc, "unknown %s option `%s'",                         \
 671             _conf_desc, _conf_sc->d.buf);                               \
 672     }                                                                   \
 673                                                                         \
 674     /* --- Accept an option --- *                                       \
 675      *                                                                  \
 676      * It's safe to drop through from above.  Either an error will have \
 677      * been reported, or the state is not @CS_BRACE@.                   \
 678      */                                                                 \
 679                                                                         \
 680   _conf_accept:                                                         \
 681     if (_conf_state == CS_BRACE && _conf_sc->t == ';')                  \
 682       token(_conf_sc);                                                  \
 683   } while (_conf_state == CS_BRACE && _conf_sc->t == CTOK_WORD);        \
 684                                                                         \
 685   /* --- Check for a closing brace --- */                               \
 686                                                                         \
 687   if (_conf_state == CS_BRACE) {                                        \
 688     if (_conf_sc->t == '}')                                             \
 689       token(_conf_sc);                                                  \
 690     else                                                                \
 691       error(_conf_sc, "parse error, expected `}'");                     \
 692   }                                                                     \
 693                                                                         \
 694   /* --- Return an appropriate value --- */                             \
 695                                                                         \
 696   return (_conf_state != CS_UNKNOWN);                                   \
 697 } while (0)
 698
 699 /* --- @CONF_ACCEPT@, @CONF_REJECT@ --- *
 700  *
 701  * Arguments:   ---
 702  *
 703  * Use:         Within an options parser (between @CONF_BEGIN@ and
 704  *              @CONF_END@), accept or reject an option.
 705  */
 706
 707 #define CONF_ACCEPT goto _conf_accept
 708 #define CONF_REJECT goto _conf_reject
 709
 710 /* --- @CONF_QUAL@ --- *
 711  *
 712  * Arguments:   ---
 713  *
 714  * Use:         Evaluates to a nonzero value if the current option is
 715  *              qualified.  This can be used to decide whether abbreviations
 716  *              for options should be accepted.
 717  */
 718
 719 #define CONF_QUAL (_conf_state != CS_PLAIN)
 720
 721 /* --- @conf_name@ --- *
 722  *
 723  * Arguments:   @scanner *sc@ = pointer to scanner
 724  *              @char delim@ = delimiter character to look for
 725  *              @dstr *d@ = pointer to dynamic string for output
 726  *
 727  * Returns:     ---
 728  *
 729  * Use:         Reads in a compound name consisting of words separated by
 730  *              delimiters.  Leading and trailing delimiters are permitted,
 731  *              although they'll probably cause confusion if used.  The name
 732  *              may be enclosed in square brackets if that helps at all.
 733  *
 734  *              Examples of compound names are filenames (delimited by `/')
 735  *              and IP addresses (delimited by `.').
 736  */
 737
 738 extern void conf_name(scanner */*sc*/, char /*delim*/, dstr */*d*/);
 739
 740 /* --- @conf_fname@ --- *
 741  *
 742  * Arguments:   @scanner *sc@ = pointer to scanner
 743  *              @dstr *d@ = pointer to dynamic string for output
 744  *
 745  * Returns:     ---
 746  *
 747  * Use:         Reads a file name from the input and stores it in @d@.
 748  */
 749
 750 extern void conf_fname(scanner */*sc*/, dstr */*d*/);
 751
 752 /*----- Reference-counted file descriptors --------------------------------*/
 753
 754 typedef struct reffd {
 755   int fd;
 756   unsigned ref;
 757   void (*proc)(void */*p*/);
 758   void *p;
 759 } reffd;
 760
 761 /* --- @reffd_init@ --- *
 762  *
 763  * Arguments:   @int fd@ = file descriptor
 764  *
 765  * Returns:     Reference-counted file descriptor object.
 766  *
 767  * Use:         Creates a refcounted file descriptor.
 768  */
 769
 770 extern reffd *reffd_init(int /*fd*/);
 771
 772 /* --- @reffd_handler@ --- *
 773  *
 774  * Arguments:   @reffd *r@ = pointer to reference counted filehandle
 775  *              @void (*proc)(void *p)@ = procedure to call
 776  *              @void *p@
 777  *
 778  * Returns:     ---
 779  *
 780  * Use:         Sets the reference counted file descriptor to call @proc@
 781  *              when it is no longer required.
 782  */
 783
 784 extern void reffd_handler(reffd */*r*/, void (*/*proc*/)(void */*p*/),
 785                           void */*p*/);
 786
 787 /* --- @reffd_inc@ --- *
 788  *
 789  * Arguments:   @reffd *r@ = pointer to reference counted filehandle
 790  *
 791  * Returns:     ---
 792  *
 793  * Use:         Increments the reference count for a file descriptor.
 794  */
 795
 796 #define REFFD_INC(r) do { (r)->ref++; } while (0)
 797
 798 extern void reffd_inc(reffd */*r*/);
 799
 800 /* --- @reffd_dec@ --- *
 801  *
 802  * Arguments:   @reffd *r@ = pointer to reference counted filehandle
 803  *
 804  * Returns:     ---
 805  *
 806  * Use:         Decrements the reference count for a file descriptor.
 807  */
 808
 809 #define REFFD_DEC(r) do {                                               \
 810   reffd *_r = (r);                                                      \
 811   _r->ref--;                                                            \
 812   if (_r->ref == 0) {                                                   \
 813     close(_r->fd);                                                      \
 814     if (_r->proc)                                                       \
 815       _r->proc(_r->p);                                                  \
 816     DESTROY(_r);                                                        \
 817   }                                                                     \
 818 } while (0)
 819
 820 extern void reffd_dec(reffd */*r*/);
 821
 822 /*----- Sources, targets and endpoints ------------------------------------*/
 823
 824 /* --- Basic endpoint structure --- */
 825
 826 typedef struct endpt {
 827   struct endpt_ops *ops;                /* Pointer to operations table */
 828   struct endpt *other;                  /* Pointer to sibling endpoint */
 829   unsigned f;                           /* Various flags */
 830   struct tango *t;                      /* Private data structure */
 831   reffd *in, *out;                      /* File descriptors */
 832 } endpt;
 833
 834 /* --- Endpoint flags --- */
 835
 836 #define EPF_PENDING 1u                  /* Endpoint creation in progress */
 837 #define EPF_FILE 2u                     /* Endpoint smells like a file */
 838
 839 /* --- Endpoint operations table --- */
 840
 841 typedef struct endpt_ops {
 842
 843   /* --- @attach@ --- *
 844    *
 845    * Arguments: @endpt *e@ = pointer to endpoint to be attached
 846    *            @reffd *in, *out@ = input and output file descriptors
 847    *
 848    * Returns:   ---
 849    *
 850    * Use:       Instructs a non-file endpoint to attach itself to a pair of
 851    *            files.
 852    */
 853
 854   void (*attach)(endpt */*e*/, reffd */*in*/, reffd */*out*/);
 855
 856   /* --- @file@ --- *
 857    *
 858    * Arguments: @endpt *e@ = pointer to endpoint in question
 859    *            @endpt *f@ = pointer to a file endpoint
 860    *
 861    * Returns:   ---
 862    *
 863    * Use:       Informs a non-file endpoint of a file endpoint which will
 864    *            want to be closed when it's finished with.  At that time, the
 865    *            endpoint should arrange to have both itself and its partner
 866    *            closed.  If no file is registered, the endpoint manager will
 867    *            close both endpoints itself.
 868    */
 869
 870   void (*file)(endpt */*e*/, endpt */*f*/);
 871
 872   /* --- @wclose@ --- *
 873    *
 874    * Arguments: @endpt *e@ = endpoint to be partially closed
 875    *
 876    * Returns:   ---
 877    *
 878    * Use:       Announces that the endpoint will not be written to any more.
 879    */
 880
 881   void (*wclose)(endpt */*e*/);
 882
 883   /* --- @close@ --- *
 884    *
 885    * Arguments: @endpt *e@ = endpoint to be closed
 886    *
 887    * Returns:   ---
 888    *
 889    * Use:       Completely closes an endpoint.  The endpoint's data may be
 890    *            freed, although some endpoints may wish to delay freeing for
 891    *            some reason.
 892    */
 893
 894   void (*close)(endpt */*e*/);
 895
 896 } endpt_ops;
 897
 898 /* --- A basic target object --- */
 899
 900 typedef struct target {
 901   struct target_ops *ops;
 902   unsigned ref;
 903   char *desc;
 904 } target;
 905
 906 /* --- Forwarding target operations --- */
 907
 908 typedef struct target_ops {
 909   const char *name;                     /* Name of this target */
 910
 911   /* --- @option@ --- *
 912    *
 913    * Arguments: @target *t@ = pointer to target object, or zero if global
 914    *            @scanner *sc@ = scanner to read from
 915    *
 916    * Returns:   Nonzero to claim the option.
 917    *
 918    * Use:       Handles an option string from the configuration file.
 919    */
 920
 921   int (*option)(target */*t*/, scanner */*sc*/);
 922
 923   /* --- @read@ --- *
 924    *
 925    * Arguments: @scanner *sc@ = pointer to scanner to read from
 926    *
 927    * Returns:   Pointer to a target object to claim, null to reject.
 928    *
 929    * Use:       Parses a target description from the configuration file.
 930    *            Only the socket target is allowed to omit the prefix on a
 931    *            target specification.
 932    */
 933
 934   target *(*read)(scanner */*sc*/);
 935
 936   /* --- @confirm@ --- *
 937    *
 938    * Arguments: @target *t@ = pointer to target
 939    *
 940    * Returns:   ---
 941    *
 942    * Use:       Confirms configuration of a target.
 943    */
 944
 945   void (*confirm)(target */*t*/);
 946
 947   /* --- @create@ --- *
 948    *
 949    * Arguments: @target *t@ = pointer to target
 950    *            @const char *desc@ = description of connection
 951    *
 952    * Returns:   Pointer to a created endpoint.
 953    *
 954    * Use:       Generates a target endpoint for communication.
 955    */
 956
 957   endpt *(*create)(target */*t*/, const char */*desc*/);
 958
 959   /* --- @destroy@ --- *
 960    *
 961    * Arguments: @target *t@ = pointer to target
 962    *
 963    * Returns:   ---
 964    *
 965    * Use:       Destroys a target.
 966    */
 967
 968   void (*destroy)(target */*t*/);
 969
 970 } target_ops;
 971
 972 /* --- A basic source object --- */
 973
 974 typedef struct source {
 975   struct source *next, *prev;
 976   struct source_ops *ops;
 977   unsigned ref;
 978   unsigned f;
 979 #define SF_ACTIVE 1u
 980   char *desc;
 981 } source;
 982
 983
 984 /* --- Forwarding source operations --- */
 985
 986 typedef struct source_ops {
 987   const char *name;                     /* Name of this source */
 988
 989   /* --- @option@ --- *
 990    *
 991    * Arguments: @scanner *sc@ = scanner to read from
 992    *            @source *s@ = pointer to source object, or zero if global
 993    *
 994    * Returns:   Nonzero to claim the option.
 995    *
 996    * Use:       Handles an option string from the configuration file.
 997    */
 998
 999   int (*option)(source */*s*/, scanner */*sc*/);
1000
1001   /* --- @read@ --- *
1002    *
1003    * Arguments: @scanner *sc@ = pointer to scanner to read from
1004    *
1005    * Returns:   Pointer to a source object to claim, null to reject.
1006    *
1007    * Use:       Parses a source description from the configuration file.
1008    *            Only the socket source is allowed to omit the prefix on a
1009    *            source specification.
1010    */
1011
1012   source *(*read)(scanner */*sc*/);
1013
1014   /* --- @attach@ --- *
1015    *
1016    * Arguments: @source *s@ = pointer to source
1017    *            @scanner *sc@ = scanner (for error reporting)
1018    *            @target *t@ = pointer to target to attach
1019    *
1020    * Returns:   ---
1021    *
1022    * Use:       Attaches a target to a source.
1023    */
1024
1025   void (*attach)(source */*s*/, scanner */*sc*/, target */*t*/);
1026
1027   /* --- @shutdown@ --- *
1028    *
1029    * Arguments: @source *s@ = pointer to source
1030    *
1031    * Returns:   ---
1032    *
1033    * Use:       Deactivates the source so that it won't produce any more
1034    *            endpoints.
1035    */
1036
1037   void (*shutdown)(source */*s*/);
1038
1039   /* --- @destroy@ --- *
1040    *
1041    * Arguments: @source *s@ = pointer to source
1042    *
1043    * Returns:   ---
1044    *
1045    * Use:       Destroys a source.  Used when closing the system down, for
1046    *            example as a result of a signal.
1047    */
1048
1049   void (*destroy)(source */*s*/);
1050
1051 } source_ops;
1052
1053 /* --- @endpt_kill@ --- *
1054  *
1055  * Arguments:   @endpt *a@ = an endpoint
1056  *
1057  * Returns:     ---
1058  *
1059  * Use:         Kills an endpoint.  If the endpoint is joined to another, the
1060  *              other endpoint is also killed, as is the connection between
1061  *              them (and that's the tricky bit).
1062  */
1063
1064 extern void endpt_kill(endpt */*a*/);
1065
1066 /* --- @endpt_killall@ --- *
1067  *
1068  * Arguments:   ---
1069  *
1070  * Returns:     ---
1071  *
1072  * Use:         Destroys all current endpoint connections.  Used when
1073  *              shutting down.
1074  */
1075
1076 extern void endpt_killall(void);
1077
1078 /* --- @endpt_join@ --- *
1079  *
1080  * Arguments:   @endpt *a@ = pointer to first endpoint
1081  *              @endpt *b@ = pointer to second endpoint
1082  *              @const char *desc@ = description of connection
1083  *
1084  * Returns:     ---
1085  *
1086  * Use:         Joins two endpoints together.  It's OK to join endpoints
1087  *              which are already joined; in fact, the the right thing to do
1088  *              when your endpoint decides that it's not pending any more is
1089  *              to join it to its partner again.
1090  *
1091  *              If the endpoints are already connected then the description
1092  *              string is ignored.  The endpoint manager takes a copy of
1093  *              the string, so you don't need to keep it around.
1094  */
1095
1096 extern void endpt_join(endpt */*a*/, endpt */*b*/, const char */*desc*/);
1097
1098 /* --- @target_inc@ --- *
1099  *
1100  * Arguments:   @target *t@ = pointer to a source
1101  *
1102  * Returns:     ---
1103  *
1104  * Use:         Increments a target's refcount.
1105  */
1106
1107 extern void target_inc(target */*t*/);
1108
1109 /* --- @target_dec@ --- *
1110  *
1111  * Arguments:   @target *t@ = pointer to a target
1112  *
1113  * Returns:     ---
1114  *
1115  * Use:         Decrements a target's refcount, destroying it if necessary.
1116  */
1117
1118 extern void target_dec(target */*t*/);
1119
1120 /* --- @source_add@ --- *
1121  *
1122  * Arguments:   @source *s@ = pointer to a source
1123  *
1124  * Returns:     ---
1125  *
1126  * Use:         Adds a source to the master list.  Only do this for passive
1127  *              sources (e.g., listening sockets), not active sources (e.g.,
1128  *              executable programs).
1129  */
1130
1131 extern void source_add(source */*s*/);
1132
1133 /* --- @source_remove@ --- *
1134  *
1135  * Arguments:   @source *s@ = pointer to a source
1136  *
1137  * Returns:     ---
1138  *
1139  * Use:         Removes a source from the master list.
1140  */
1141
1142 extern void source_remove(source */*s*/);
1143
1144 /* --- @source_inc@ --- *
1145  *
1146  * Arguments:   @source *s@ = pointer to a source
1147  *
1148  * Returns:     ---
1149  *
1150  * Use:         Increments a source's refcount.
1151  */
1152
1153 extern void source_inc(source */*s*/);
1154
1155 /* --- @source_dec@ --- *
1156  *
1157  * Arguments:   @source *s@ = pointer to a source
1158  *
1159  * Returns:     ---
1160  *
1161  * Use:         Decrements a source's refcount, destroying it if necessary.
1162  */
1163
1164 extern void source_dec(source */*s*/);
1165
1166 /* --- @source_killall@ --- *
1167  *
1168  * Arguments:   ---
1169  *
1170  * Returns:     ---
1171  *
1172  * Use:         Frees all sources.
1173  */
1174
1175 extern void source_killall(void);
1176
1177 /*----- The exec source and target ----------------------------------------*/
1178
1179 extern source_ops xsource_ops;
1180 extern target_ops xtarget_ops;
1181
1182 /* --- @exec_init@ --- *
1183  *
1184  * Arguments:   ---
1185  *
1186  * Returns:     ---
1187  *
1188  * Use:         Initializes the executable problem source and target.
1189  */
1190
1191 extern void exec_init(void);
1192
1193 /*----- The file source and target ----------------------------------------*/
1194
1195 extern source_ops fsource_ops;
1196 extern target_ops ftarget_ops;
1197
1198 /*----- The socket source and target --------------------------------------*/
1199
1200 extern source_ops ssource_ops;
1201 extern target_ops starget_ops;
1202
1203 /* --- @starget_connected@ --- *
1204  *
1205  * Arguments:   @int fd@ = file descriptor now ready for use
1206  *              @void *p@ = pointer to an endpoint structure
1207  *
1208  * Returns:     ---
1209  *
1210  * Use:         Handles successful connection of the target endpoint.
1211  */
1212
1213 extern void starget_connected(int /*fd*/, void */*p*/);
1214
1215 /*----- Handling of file attributes ---------------------------------------*/
1216
1217 /* --- File attribute options structure --- */
1218
1219 typedef struct fattr {
1220   unsigned mode;
1221   uid_t uid;
1222   gid_t gid;
1223 } fattr;
1224
1225 /* --- Shared global options --- */
1226
1227 extern fattr fattr_global;
1228
1229 /* --- @fattr_init@ --- *
1230  *
1231  * Arguments:   @fattr *f@ = pointer to file attributes
1232  *
1233  * Returns:     ---
1234  *
1235  * Use:         Initializes a set of file attributes to default values.
1236  */
1237
1238 extern void fattr_init(fattr */*f*/);
1239
1240 /* --- @fattr_option@ --- *
1241  *
1242  * Arguments:   @scanner *sc@ = pointer to scanner to read
1243  *              @fattr *f@ = pointer to file attributes to set
1244  *
1245  * Returns:     Whether the option was clamed.
1246  *
1247  * Use:         Reads file attributes from a scanner.
1248  */
1249
1250 extern int fattr_option(scanner */*sc*/, fattr */*f*/);
1251
1252 /* --- @fattr_apply@ --- *
1253  *
1254  * Arguments:   @const char *file@ = pointer to filename
1255  *              @fattr *f@ = pointer to attribute set
1256  *
1257  * Returns:     @-1@ if it failed.
1258  *
1259  * Use:         Applies file attributes to a file.  For best results, try to
1260  *              create the file with the right permissions and so on.  This
1261  *              call will fix everything up, but there are potential races
1262  *              which might catch you out if you're not careful.
1263  */
1264
1265 extern int fattr_apply(const char */*file*/, fattr */*f*/);
1266
1267 /*----- Making privileged connections -------------------------------------*/
1268
1269 /* --- @privconn_split@ --- *
1270  *
1271  * Arguments:   @sel_state *s@ = select state
1272  *
1273  * Returns:     ---
1274  *
1275  * Use:         Splits off the privileged binding code into a separate
1276  *              process.
1277  */
1278
1279 extern void privconn_split(sel_state */*s*/);
1280
1281 /* --- @privconn_adddest@ --- *
1282  *
1283  * Arguments:   @struct in_addr peer@ = address to connect to
1284  *              @unsigned port@ = port to connect to
1285  *
1286  * Returns:     Index for this destination address, or @-1@ if not
1287  *              available.
1288  *
1289  * Use:         Adds a valid destination for a privileged connection.
1290  */
1291
1292 extern int privconn_adddest(struct in_addr /*peer*/, unsigned /*port*/);
1293
1294 /* --- @privconn_connect@ --- *
1295  *
1296  * Arguments:   @conn *c@ = connection structure to fill in
1297  *              @sel_state *s@ = pointer to select state to attach to
1298  *              @int i@ = address index to connect to
1299  *              @struct in_addr bind@ = address to bind to
1300  *              @void (*func)(int, void *)@ = function to call on connect
1301  *              @void *p@ = argument for the function
1302  *
1303  * Returns:     Zero on success, @-1@ on failure.
1304  *
1305  * Use:         Sets up a privileged connection job.
1306  */
1307
1308 extern int privconn_connect(conn */*c*/, sel_state */*s*/,
1309                             int /*i*/, struct in_addr /*bind*/,
1310                             void (*/*func*/)(int, void *), void */*p*/);
1311
1312 /*----- Identifying remote clients ----------------------------------------*/
1313
1314 typedef struct id_req {
1315   struct sockaddr_in lsin;              /* Local address of connection */
1316   struct sockaddr_in rsin;              /* Remote address of connection */
1317   const char *desc;                     /* Description of connection */
1318   const char *act;                      /* Action taken by server */
1319   reffd *r;                             /* Pointer to file descriptor */
1320 } id_req;
1321
1322 /* --- @identify@ --- *
1323  *
1324  * Arguments:   @const id_req *q@ = pointer to request block
1325  *
1326  * Returns:     ---
1327  *
1328  * Use:         Starts a background ident lookup and reverse-resolve job
1329  *              which will, eventually, report a message to the system log.
1330  */
1331
1332 extern void identify(const id_req */*q*/);
1333
1334 /*----- Host-based access control -----------------------------------------*/
1335
1336 /* --- An access control entry --- */
1337
1338 typedef struct acl_entry {
1339   struct acl_entry *next;               /* Next entry in the list */
1340   const struct acl_ops *ops;            /* Operations for the ACL entry */
1341   unsigned act;                         /* What to do with matching hosts */
1342 } acl_entry;
1343
1344 #define ACL_DENY 0                      /* Deny access to matching conns */
1345 #define ACL_ALLOW 1                     /* Allow access to matching conns */
1346 #define ACL_PERM 1u                     /* Bit mask for permission bit */
1347
1348 /* --- Host-based access control --- */
1349
1350 typedef struct acl_host {
1351   acl_entry a;                          /* Base structure */
1352   struct in_addr addr, mask;            /* Address and netmask */
1353 } acl_host;
1354
1355 /* --- ACL methods --- */
1356
1357 typedef struct acl_ops {
1358   int (*check)(void */*a*/, struct in_addr /*addr*/, unsigned /*port*/);
1359   void (*dump)(void */*a*/, FILE */*fp*/);
1360   void (*free)(void */*a*/);
1361 } acl_ops;
1362
1363 /* --- @acl_check@ --- *
1364  *
1365  * Arguments:   @acl_entry *a@ = pointer to ACL to check against
1366  *              @struct in_addr addr@ = address to check
1367  *              @unsigned port@ = port number to check
1368  *              @int *act@ = verdict (should initially be @ACT_ALLOW@)
1369  *
1370  * Returns:     Zero if undecided, nonzero if a rule matched.
1371  *
1372  * Use:         Checks an address against an ACL.
1373  */
1374
1375 extern int acl_check(acl_entry */*a*/,
1376                      struct in_addr /*addr*/, unsigned /*port*/,
1377                      int */*act*/);
1378
1379 /* --- @acl_dump@ --- *
1380  *
1381  * Arguments:   @acl_entry *a@ = pointer to ACL to dump
1382  *              @FILE *fp@ = pointer to stream to dump on
1383  *
1384  * Returns:     ---
1385  *
1386  * Use:         Dumps an access control list to an output stream.
1387  */
1388
1389 extern void acl_dump(acl_entry */*a*/, FILE */*fp*/);
1390
1391 /* --- @acl_free@ --- *
1392  *
1393  * Arguments:   @acl_entry *a@ = pointer to a list of ACLs
1394  *
1395  * Returns:     ---
1396  *
1397  * Use:         Frees all of the memory used by an ACL.
1398  */
1399
1400 extern void acl_free(acl_entry */*a*/);
1401
1402 /* --- @acl_addhost@ --- *
1403  *
1404  * Arguments:   @acl_entry ***a@ = address of pointer to list tail
1405  *              @unsigned act@ = what to do with matching addresses
1406  *              @struct in_addr addr, mask@ = address and mask to match
1407  *
1408  * Returns:     ---
1409  *
1410  * Use:         Adds a host-authentication entry to the end of an access
1411  *              control list.
1412  */
1413
1414 extern void acl_addhost(acl_entry ***/*a*/, unsigned /*act*/,
1415                         struct in_addr /*addr*/, struct in_addr /*mask*/);
1416
1417 /* --- @acl_addpriv@ --- *
1418  *
1419  * Arguments:   @acl_entry ***a@ = address of pointer to list tail
1420  *              @unsigned act@ = what to do with matching addresses
1421  *
1422  * Returns:     ---
1423  *
1424  * Use:         Adds a privileged-port check to the end of an access control
1425  *              list.
1426  */
1427
1428 extern void acl_addpriv(acl_entry ***/*a*/, unsigned /*act*/);
1429
1430 /*----- Network addresses -------------------------------------------------*/
1431
1432 /* --- A generic socket address --- *
1433  *
1434  * Not all systems understand @sa_len@ fields.  (In particular, Linux
1435  * doesn't.)  Some fairly ugly hacking is then performed on particular
1436  * address types.
1437  */
1438
1439 typedef struct addr {
1440   struct addr_ops *ops;
1441   size_t sz;
1442 } addr;
1443
1444 #define ADDRSZ(sz) (sizeof(addr) + (sz))
1445
1446 /* --- Address configuration --- *
1447  *
1448  * An address family will want to extend this.
1449  */
1450
1451 typedef struct addr_opts {
1452   unsigned f;
1453 } addr_opts;
1454
1455 #define ADDRF_NOLOG 1u
1456
1457 /* --- Address types --- *
1458  *
1459  * For things like Internet addresses, source and destinations look
1460  * different.
1461  */
1462
1463 enum {
1464   ADDR_SRC,
1465   ADDR_DEST,
1466   ADDR_GLOBAL
1467 };
1468
1469 /* --- Description of an address type handler --- */
1470
1471 typedef struct addr_ops {
1472   const char *name;                     /* Protocol's internal name */
1473
1474   /* --- @read@ --- *
1475    *
1476    * Arguments: @scanner *sc@ = pointer to scanner to read from
1477    *            @unsigned type@ = type of address to be read
1478    *
1479    * Returns:   A filled-in socket address.
1480    *
1481    * Use:       Parses a textual representation of a socket address.
1482    */
1483
1484   addr *(*read)(scanner */*sc*/, unsigned /*type*/);
1485
1486   /* --- @destroy@ --- *
1487    *
1488    * Arguments: @addr *a@ = pointer to an address block
1489    *
1490    * Returns:   ---
1491    *
1492    * Use:       Disposes of an address block in some suitable fashion.
1493    */
1494
1495   void (*destroy)(addr */*a*/);
1496
1497   /* --- @print@ --- *
1498    *
1499    * Arguments: @addr *a@ = pointer to socket address to read
1500    *            @unsigned type@ = type of address to be written
1501    *            @dstr *d@ = string on which to write the description
1502    *
1503    * Returns:   ---
1504    *
1505    * Use:       Writes a textual representation of a socket address to
1506    *            a string.
1507    */
1508
1509   void (*print)(addr */*a*/, unsigned /*type*/, dstr */*d*/);
1510
1511   /* --- @initsrcopts@ --- *
1512    *
1513    * Arguments: ---
1514    *
1515    * Returns:   A pointer to a protocol-specific data block for a listener
1516    *
1517    * Use:       Creates a data block for a listener.  This is attached to the
1518    *            listener data structure.  Options can then be requested, and
1519    *            are added to the block when necessary.
1520    */
1521
1522   addr_opts *(*initsrcopts)(void);
1523
1524   /* --- @option@ --- *
1525    *
1526    * Arguments: @scanner *sc@ = pointer to a scanner to read from
1527    *            @unsigned type@ = kind of option this is
1528    *            @addr_opts *ao@ = data block to modify (from @init@), or null
1529    *
1530    * Returns:   Nonzero to claim the option.
1531    *
1532    * Use:       Parses a source option, either global or listener-specific.
1533    */
1534
1535   int (*option)(scanner */*sc*/, addr_opts */*ao*/, unsigned /*type*/);
1536
1537   /* --- @confirm@ --- *
1538    *
1539    * Arguments: @addr *a@ = pointer to an address structure
1540    *            @unsigned type@ = kind of address this is
1541    *            @addr_opts *ao@ = address options
1542    *
1543    * Returns:   ---
1544    *
1545    * Use:       Called during initialization when an address is fully
1546    *            configured.
1547    */
1548
1549   void (*confirm)(addr */*a*/, unsigned /*type*/, addr_opts */*ao*/);
1550
1551   /* --- @freesrcopts@ --- *
1552    *
1553    * Arguments: @addr_opts *ao@ = data block to remove
1554    *
1555    * Returns:   ---
1556    *
1557    * Use:       Throws away all the configuration data for an address type.
1558    */
1559
1560   void (*freesrcopts)(addr_opts */*ao*/);
1561
1562   /* --- @bind@ --- *
1563    *
1564    * Arguments: @addr *a@ = the address to bind to
1565    *            @addr_opts *ao@ = the address options
1566    *
1567    * Returns:   File descriptor of bound socket if OK, or @-1@ on error.
1568    *
1569    * Use:       Binds a listening socket.  The tedious stuff with @listen@
1570    *            isn't necessary.
1571    */
1572
1573   int (*bind)(addr */*a*/, addr_opts */*ao*/);
1574
1575   /* --- @unbind@ --- *
1576    *
1577    * Arguments: @addr *a@ = pointer to an address
1578    *
1579    * Returns:   ---
1580    *
1581    * Use:       Unbinds an address.  This is used when tidying up.  The main
1582    *            purpose is to let the Unix-domain handler remove its socket
1583    *            node from the filesystem.
1584    */
1585
1586   void (*unbind)(addr */*a*/);
1587
1588   /* --- @accept@ --- *
1589    *
1590    * Arguments: @int fd@ = listening file descriptor
1591    *            @addr_opts *ao@ = data block to get configuration from
1592    *            @const char *desc@ = description of the listener
1593    *
1594    * Returns:   Pointer to a reference counted file descriptor.
1595    *
1596    * Use:       Accepts, verifies and logs an incoming connection.
1597    */
1598
1599   reffd *(*accept)(int /*fd*/, addr_opts */*ao*/, const char */*desc*/);
1600
1601   /* --- @inittargopts@ --- *
1602    *
1603    * Arguments: ---
1604    *
1605    * Returns:   A pointer to a protocol-specific data block for a connecter
1606    *
1607    * Use:       Creates a data block for a target.  This is attached to the
1608    *            target data structure.  Options can then be requested, and
1609    *            are added to the block when necessary.
1610    */
1611
1612   addr_opts *(*inittargopts)(void);
1613
1614   /* --- @freetargopts@ --- *
1615    *
1616    * Arguments: @addr_opts *ao@ = data block to remove
1617    *
1618    * Returns:   ---
1619    *
1620    * Use:       Throws away all the configuration data for an address type.
1621    */
1622
1623   void (*freetargopts)(addr_opts */*ao*/);
1624
1625   /* --- @connect@ --- *
1626    *
1627    * Arguments: @addr *a@ = destination address
1628    *            @addr_opts *ao@ = target address options
1629    *            @conn *c@ = connection structure
1630    *            @endpt *e@ = endpoint structure
1631    *
1632    * Returns:   Zero if OK, @-1@ on some error.
1633    *
1634    * Use:       Requests that a connection be made, or at least set in
1635    *            motion.  An address may do one of these things:
1636    *
1637    *              * Return @-1@.
1638    *
1639    *              * Call @starget_connected@ with @-1@ or a connected file
1640    *                descriptor and the pointer @e@.
1641    *
1642    *              * Call @conn_init@ or @conn_fd@, giving @starget_connected@
1643    *                and @e@ as the function to call.
1644    */
1645
1646   int (*connect)(addr */*a*/, addr_opts */*ao*/, conn */*c*/, endpt */*e*/);
1647
1648 } addr_ops;
1649
1650 /* --- Address types --- */
1651
1652 extern addr_ops un_ops;
1653 extern addr_ops inet_ops;
1654
1655 /*----- That's all, folks -------------------------------------------------*/
1656
1657 #ifdef __cplusplus
1658   }
1659 #endif
1660
1661 #endif