diplodocus.org Git - nmh/blob - h/mh.h

   1 /* mh.h -- main header file for all of nmh
   2  */
   3
   4 #include <h/nmh.h>
   5
   6 /* It's undefined behaviour in C99 to convert from a function pointer to
   7  * a data-object pointer, e.g. void pointer.  gcc's -pedantic warns of
   8  * this and can stop compilation.  POSIX requires the operation however,
   9  * e.g. for dlsym(3), and so we know it's safe on POSIX platforms, e.g.
  10  * the pointers are of the same size.  Thus use a union to subvert gcc's
  11  * check.  The function-pointer equivalent of a void pointer is any
  12  * function-pointer type as all function pointers are defined to be
  13  * convertible from one another;  use the simplest available. */
  14 typedef union {
  15     void *v;
  16     void (*f)(void);
  17 } generic_pointer;
  18
  19 /*
  20  * Well-used constants
  21  */
  22 #define NOTOK        (-1)       /* syscall()s return this on error */
  23 #define OK             0        /*  ditto on success               */
  24 #define DONE           1        /* ternary logic                   */
  25 #define ALL           ""
  26
  27 #define MAXARGS     1000        /* max arguments to exec                */
  28 #define NFOLDERS    1000        /* max folder arguments on command line */
  29 #define DMAXFOLDER     4        /* typical number of digits             */
  30 #define MAXFOLDER   1000        /* message increment                    */
  31
  32 /*
  33  * This macro is for use by scan, for example, so that platforms with
  34  * a small BUFSIZ can easily allocate larger buffers.
  35  */
  36 #define NMH_BUFSIZ  max(BUFSIZ, 8192)
  37
  38 /* If we're using gcc then tell it extra information so it can do more
  39  * compile-time checks. */
  40 #if __GNUC__ > 2
  41 #define NORETURN __attribute__((__noreturn__))
  42 #define CONST __attribute__((const))
  43 #define MALLOC __attribute__((malloc))
  44 #define NONNULL(...) __attribute__((nonnull(__VA_ARGS__)))
  45 #define PURE __attribute__((pure))
  46 #define ENDNULL __attribute__((sentinel))
  47 #else
  48 #define NORETURN
  49 #define CHECK_PRINTF(fmt, arg)
  50 #define ALLOC_SIZE(...)
  51 #define CONST
  52 #define MALLOC
  53 #define NONNULL(...)
  54 #define PURE
  55 #define ENDNULL
  56 #endif
  57
  58 #if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 3)
  59 #define ALLOC_SIZE(...) __attribute__((alloc_size(__VA_ARGS__)))
  60 #define CHECK_PRINTF(fmt, arg) __attribute__((format(printf, fmt, arg)))
  61 #else
  62 #define ALLOC_SIZE(...)
  63 #define CHECK_PRINTF(fmt, arg)
  64 #endif
  65
  66 /* Silence the compiler's "unused variable" warning. */
  67 #define NMH_UNUSED(i) (void)i
  68
  69 /* DIM gives the number of elements in the one-dimensional array a. */
  70 #define DIM(a) (sizeof (a) / sizeof (*(a)))
  71
  72 /* LEN gives the strlen() of string constant s, excluding the
  73  * terminating NUL. */
  74 #define LEN(s) (sizeof (s) - 1)
  75
  76 /* FENDNULL fends off NULL by giving an empty string instead. */
  77 #define FENDNULL(s) ((s) ? (s) : "")
  78
  79 /* If not specified in a file and PAGER is NULL or empty. */
  80 #define DEFAULT_PAGER "more"
  81
  82 /*
  83  * char array that keeps track of size in both bytes and characters
  84  * Usage note:
  85  *    Don't store return value of charstring_buffer() and use later
  86  *    after intervening push_back's; use charstring_buffer_copy()
  87  *    instead.
  88  */
  89 typedef struct charstring *charstring_t;
  90
  91 charstring_t charstring_create (size_t);
  92 charstring_t charstring_copy (const charstring_t) NONNULL(1);
  93 void charstring_free (charstring_t);
  94 /* Append a single-byte character: */
  95 void charstring_push_back (charstring_t, const char) NONNULL(1);
  96 /* Append possibly multi-byte character(s): */
  97 void charstring_push_back_chars (charstring_t, const char [], size_t, size_t) NONNULL(1);
  98 void charstring_append (charstring_t, const charstring_t) NONNULL(2);
  99 void charstring_append_cstring (charstring_t, const char []) NONNULL(2);
 100 void charstring_clear (charstring_t) NONNULL(1);
 101 /* Don't store return value of charstring_buffer() and use later after
 102    intervening push_back's; use charstring_buffer_copy() instead. */
 103 const char *charstring_buffer (const charstring_t) NONNULL(1);
 104 /* User is responsible for free'ing result of buffer copy. */
 105 char *charstring_buffer_copy (const charstring_t) NONNULL(1);
 106 size_t charstring_bytes (const charstring_t) NONNULL(1) PURE;
 107 size_t charstring_chars (const charstring_t) NONNULL(1) PURE;
 108 /* Length of the last character in the charstring. */
 109 int charstring_last_char_len (const charstring_t) NONNULL(1);
 110
 111 /*
 112  * user context/profile structure
 113  */
 114 struct node {
 115     char *n_name;               /* key                  */
 116     char *n_field;              /* value                */
 117     char  n_context;            /* context, not profile */
 118     struct node *n_next;        /* next entry           */
 119 };
 120
 121 /*
 122  * switches structure
 123  */
 124 #define AMBIGSW  (-2)   /* from smatch() on ambiguous switch */
 125 #define UNKWNSW  (-1)   /* from smatch() on unknown switch   */
 126
 127 struct swit {
 128
 129     /*
 130      * Switch name
 131      */
 132
 133     char *sw;
 134
 135     /*
 136      * The previous comments here about minchars was incorrect; this is
 137      * (AFAIK) the correct information.
 138      *
 139      * A minchars of "0" means this switch can be abbreviated to any number
 140      * of characters (assuming the abbreviation does not match any other
 141      * switches).
 142      *
 143      * A positive value for minchars means that when the user specifies
 144      * the switch on the command line, it MUST be at least that many
 145      * characters.
 146      *
 147      * A negative value for minchars means that the user-given switch must
 148      * be that many characters, but will NOT be shown in -help output.
 149      *
 150      * So what should I use?  Well, for nearly all switches you want to specify
 151      * a minchars of 0.  smatch will report an error if the switch given
 152      * matches more than one entry.  Let's say you have the following
 153      * two switches: -append and -apply.  -app will return AMBIGSW from
 154      * smatch. -appe and -appl will work fine.  So 0 is the correct choice
 155      * here.
 156      *
 157      * The only time you want to specify a minimum length is if you have
 158      * a switch who's name is a substring of a longer switch.  The example
 159      * you see sometimes in the code is -form and -format.  If you gave a
 160      * minchars of 0 for both, -form would match both -form AND -format,
 161      * and you'd always get AMBIGSW.  The solution is to specify a minchars
 162      * of 5 for -format; that way just -form will just match -form.  When
 163      * a minchars is given, the -help output will specify the minimum
 164      * switch length, like this:
 165      *
 166      * -(forma)t string
 167      *
 168      * A negative value works the same way, except the switch isn't printed
 169      * in -help.  Why would you do that?  Well, there are a few instances
 170      * of internal switches and some switches which only appear if a particular
 171      * feature is enabled (such as SASL or TLS).  Lately I've been of the
 172      * opinion that all switches should be specified, even if they are
 173      * internal or use non-available features, but currently the smatch
 174      * code still supports this.
 175      *
 176      * This isn't the appropriate place to make this note, but since I was
 177      * here ... when creating switches, you should make a negation switch
 178      * right after the enabling switch.  E.g. you should have:
 179      *
 180      * X("sasl", 0, SASLSW) \
 181      * X("nosasl", 0, NOSASLSW) \
 182      *
 183      * in the switch array, because when you run -help, print_sw will detect
 184      * this and output:
 185      *
 186      * -[no]sasl
 187      */
 188
 189     int minchars;
 190
 191     /*
 192      * If we pick this switch, return this value from smatch
 193      */
 194
 195     int swret;
 196 };
 197
 198 /*
 199  * Macros to use when declaring struct swit arrays.
 200  *
 201  * These macros use a technique known as X-Macros.  In your source code you
 202  * use them like this:
 203  *
 204  * #define FOO_SWITCHES \
 205  *    X("switch1", 0, SWITCHSW) \
 206  *    X("switch2", 0, SWITCH2SW) \
 207  *    X("thirdswitch", 2, SWITCH3SW) \
 208  *
 209  * The argument to each entry in FOO_SWITCHES are the switch name (sw),
 210  * the minchars field (see above) and the return value for this switch.
 211  * Note that the last entry in the above definition must either omit the
 212  * continuation backslash, or be followed by a blank line.  In the nmh
 213  * code the style is to have every line include a backslash and follow
 214  * the SWITCHES macro definition by a blank line.
 215  *
 216  * After you define FOO_SWITCHES, you instantiate it as follows:
 217  *
 218  * #define X(sw, minchars, id) id,
 219  * DEFINE_SWITCH_ENUM(FOO);
 220  * #undef X
 221  *
 222  * #define X(sw, minchars, id) { sw, minchars, id },
 223  * DEFINE_SWITCH_ARRAY(FOO);
 224  * #undef X
 225  *
 226  * DEFINE_SWITCH_ENUM defines an extra enum at the end of the list called
 227  * LEN_FOO.
 228  */
 229
 230 #define DEFINE_SWITCH_ENUM(name) \
 231     enum { \
 232         name ## _SWITCHES \
 233         LEN_ ## name \
 234     }
 235
 236 #define DEFINE_SWITCH_ARRAY(name, array) \
 237     static struct swit array[] = { \
 238         name ## _SWITCHES \
 239         { NULL, 0, 0 } \
 240     }
 241
 242 extern struct swit anoyes[];    /* standard yes/no switches */
 243
 244 /*
 245  * general folder attributes
 246  */
 247 #define READONLY   (1<<0)       /* No write access to folder    */
 248 #define SEQMOD     (1<<1)       /* folder's sequences modified   */
 249 #define ALLOW_NEW  (1<<2)       /* allow the "new" sequence     */
 250 #define OTHERS     (1<<3)       /* folder has other files       */
 251
 252 #define FBITS "\020\01READONLY\02SEQMOD\03ALLOW_NEW\04OTHERS"
 253
 254 /*
 255  * first free slot for user defined sequences
 256  * and attributes
 257  */
 258 #define FFATTRSLOT  4
 259
 260 /*
 261  * internal messages attributes (sequences)
 262  */
 263 #define EXISTS        (0)       /* exists            */
 264 #define SELECTED      (1)       /* selected for use  */
 265 #define SELECT_EMPTY  (2)       /* "new" message     */
 266 #define SELECT_UNSEEN (3)       /* inc/show "unseen" */
 267
 268 #define MBITS "\020\01EXISTS\02SELECTED\03NEW\04UNSEEN"
 269
 270 /* A vector of bits for tracking the sequence membership of a single
 271  * message.  Do not access the struct members; use vector.c.
 272  * Do not move or copy this struct as it may contain a pointer to
 273  * itself;  use bvector_copy(). */
 274 struct bvector {
 275     unsigned long *bits;
 276     size_t maxsize;
 277     unsigned long tiny[2];   /* Default fixed-size storage for bits. */
 278 };
 279 typedef struct bvector *bvector_t;
 280
 281 bvector_t bvector_create (void);
 282 void bvector_init(struct bvector *bv) NONNULL(1);
 283 void bvector_copy (bvector_t, bvector_t) NONNULL(1, 2);
 284 void bvector_free (bvector_t) NONNULL(1);
 285 void bvector_fini(struct bvector *bv) NONNULL(1);
 286 void bvector_clear (bvector_t, size_t) NONNULL(1);
 287 void bvector_clear_all (bvector_t) NONNULL(1);
 288 void bvector_set (bvector_t, size_t) NONNULL(1);
 289 unsigned int bvector_at (bvector_t, size_t) NONNULL(1) PURE;
 290 unsigned long bvector_first_bits (bvector_t) NONNULL(1) PURE;
 291
 292 typedef struct svector *svector_t;
 293
 294 svector_t svector_create (size_t);
 295 void svector_free (svector_t) NONNULL(1);
 296 char *svector_push_back (svector_t, char *) NONNULL(1);
 297 char *svector_at (svector_t, size_t) NONNULL(1);
 298 char **svector_find(svector_t, const char *) NONNULL(1) PURE;
 299 char **svector_strs (svector_t) NONNULL(1) PURE;
 300 size_t svector_size (svector_t) NONNULL(1) PURE;
 301
 302 typedef struct ivector *ivector_t;
 303
 304 ivector_t ivector_create (size_t);
 305 void ivector_free (ivector_t) NONNULL(1);
 306 int ivector_push_back (ivector_t, int) NONNULL(1);
 307 int ivector_at (ivector_t, size_t) NONNULL(1);
 308 int *ivector_atp (ivector_t, size_t) NONNULL(1);
 309
 310 /*
 311  * Primary structure of folder/message information
 312  */
 313 struct msgs {
 314     int lowmsg;         /* Lowest msg number                 */
 315     int hghmsg;         /* Highest msg number                */
 316     int nummsg;         /* Actual Number of msgs             */
 317
 318     int lowsel;         /* Lowest selected msg number        */
 319     int hghsel;         /* Highest selected msg number       */
 320     int numsel;         /* Number of msgs selected           */
 321
 322     int curmsg;         /* Number of current msg if any      */
 323
 324     int msgflags;       /* Folder attributes (READONLY, etc) */
 325     char *foldpath;     /* Pathname of folder                */
 326
 327     /*
 328      * Name of sequences in this folder.
 329      */
 330     svector_t msgattrs;
 331
 332     /*
 333      * bit flags for whether sequence
 334      * is public (0), or private (1)
 335      */
 336     bvector_t attrstats;
 337
 338     /*
 339      * These represent the lowest and highest possible
 340      * message numbers we can put in the message status
 341      * area, without calling folder_realloc().
 342      */
 343     int lowoff;
 344     int hghoff;
 345
 346     /*
 347      * This is an array of bvector_t which we allocate dynamically.
 348      * Each bvector_t is a set of bits flags for a particular message.
 349      * These bit flags represent general attributes such as
 350      * EXISTS, SELECTED, etc. as well as track if message is
 351      * in a particular sequence.
 352      */
 353     size_t num_msgstats;
 354     struct bvector *msgstats;   /* msg status */
 355
 356     /*
 357      * A FILE handle containing an open filehandle for the sequence file
 358      * for this folder.  If non-NULL, use it when the sequence file is
 359      * written.
 360      */
 361     FILE *seqhandle;
 362
 363     /*
 364      * The name of the public sequence file; required by lkfclose()
 365      */
 366     char *seqname;
 367 };
 368
 369 /*
 370  * Amount of space to allocate for msgstats.  Allocate
 371  * the array to have space for messages numbered lo to hi.
 372  * Use MSGSTATNUM to load mp->num_msgstats first.
 373  */
 374 #define MSGSTATNUM(lo, hi) ((size_t) ((hi) - (lo) + 1))
 375 #define MSGSTATSIZE(mp) ((mp)->num_msgstats * sizeof *(mp)->msgstats)
 376
 377 /*
 378  * macros for message and sequence manipulation
 379  */
 380 #define msgstat(mp,n) ((mp)->msgstats + (n) - mp->lowoff)
 381 #define clear_msg_flags(mp,msgnum)   bvector_clear_all (msgstat(mp, msgnum))
 382 #define copy_msg_flags(mp,i,j)       bvector_copy (msgstat(mp,i), msgstat(mp,j))
 383 #define get_msg_flags(mp,ptr,msgnum) bvector_copy (ptr, msgstat(mp, msgnum))
 384 #define set_msg_flags(mp,ptr,msgnum) bvector_copy (msgstat(mp, msgnum), ptr)
 385
 386 #define does_exist(mp,msgnum)     bvector_at (msgstat(mp, msgnum), EXISTS)
 387 #define unset_exists(mp,msgnum)   bvector_clear (msgstat(mp, msgnum), EXISTS)
 388 #define set_exists(mp,msgnum)     bvector_set (msgstat(mp, msgnum), EXISTS)
 389
 390 #define is_selected(mp,msgnum)    bvector_at (msgstat(mp, msgnum), SELECTED)
 391 #define unset_selected(mp,msgnum) bvector_clear (msgstat(mp, msgnum), SELECTED)
 392 #define set_selected(mp,msgnum)   bvector_set (msgstat(mp, msgnum), SELECTED)
 393
 394 #define is_select_empty(mp,msgnum)  \
 395         bvector_at (msgstat(mp, msgnum), SELECT_EMPTY)
 396 #define set_select_empty(mp,msgnum) \
 397         bvector_set (msgstat(mp, msgnum), SELECT_EMPTY)
 398
 399 #define is_unseen(mp,msgnum) \
 400         bvector_at (msgstat(mp, msgnum), SELECT_UNSEEN)
 401 #define unset_unseen(mp,msgnum) \
 402         bvector_clear (msgstat(mp, msgnum), SELECT_UNSEEN)
 403 #define set_unseen(mp,msgnum) \
 404         bvector_set (msgstat(mp, msgnum), SELECT_UNSEEN)
 405
 406 #define in_sequence(mp,seqnum,msgnum) \
 407         bvector_at (msgstat(mp, msgnum), FFATTRSLOT + seqnum)
 408 #define clear_sequence(mp,seqnum,msgnum) \
 409         bvector_clear (msgstat(mp, msgnum), FFATTRSLOT + seqnum)
 410 #define add_sequence(mp,seqnum,msgnum) \
 411         bvector_set (msgstat(mp, msgnum), FFATTRSLOT + seqnum)
 412
 413 #define is_seq_private(mp,seqnum) \
 414         bvector_at (mp->attrstats, FFATTRSLOT + seqnum)
 415 #define make_seq_public(mp,seqnum) \
 416         bvector_clear (mp->attrstats, FFATTRSLOT + seqnum)
 417 #define make_seq_private(mp,seqnum) \
 418         bvector_set (mp->attrstats, FFATTRSLOT + seqnum)
 419 #define make_all_public(mp) \
 420         mp->attrstats = bvector_create(); bvector_clear_all (mp->attrstats)
 421
 422 /*
 423  * macros for folder attributes
 424  */
 425 #define clear_folder_flags(mp) ((mp)->msgflags = 0)
 426
 427 #define is_readonly(mp)     ((mp)->msgflags & READONLY)
 428 #define set_readonly(mp)    ((mp)->msgflags |= READONLY)
 429
 430 #define other_files(mp)     ((mp)->msgflags & OTHERS)
 431 #define set_other_files(mp) ((mp)->msgflags |= OTHERS)
 432
 433 /*
 434  * m_getfld() message parsing
 435  */
 436
 437 #define NAMESZ  999             /* Limit on component name size.
 438                                    RFC 2822 limits line lengths to
 439                                    998 characters, so a header name
 440                                    can be at most that long.
 441                                    m_getfld limits header names to 2
 442                                    less than NAMESZ, which is fine,
 443                                    because header names must be
 444                                    followed by a colon.  Add one for
 445                                    terminating NULL. */
 446
 447 /* Token type or error returned from m_getfld(), and its internal state
 448  * for the next call. */
 449 /* FLD detects the header's name is too long to fit in the fixed size
 450  * array. */
 451 #define LENERR  (-2)
 452 /* FLD reaches EOF after the header's name, or the name is followed by
 453  * a linefeed rather than a colon and the body buffer isn't large enough
 454  * to pretend this header line starts the body. */
 455 #define FMTERR  (-3)
 456 /* The initial state, looking for headers.  Returned when the header's
 457  * value finishes. */
 458 #define FLD      0
 459 /* Another chunk of the header's value has been returned, but there's
 460  * more to come. */
 461 #define FLDPLUS  1
 462 /* A chunk of the email's body has been returned. */
 463 #define BODY     3
 464 /* Either the end of the input file has been reached, or the delimiter
 465  * between emails has been found and the caller should
 466  * m_getfld_state_reset() to reset the state to FLD for continuing
 467  * through the file. */
 468 #define FILEEOF  5
 469
 470 typedef struct m_getfld_state *m_getfld_state_t;
 471
 472 #define NOUSE   0               /* draft being re-used */
 473
 474 #define TFOLDER 0               /* path() given a +folder */
 475 #define TFILE   1               /* path() given a file    */
 476 #define TSUBCWF 2               /* path() given a @folder */
 477
 478 #define OUTPUTLINELEN   72      /* default line length for headers */
 479
 480 #define LINK    "@"             /* Name of link to file to which you are */
 481                                 /* replying. */
 482
 483 /*
 484  * credentials management
 485  */
 486 typedef struct nmh_creds *nmh_creds_t;
 487
 488 /*
 489  * miscellaneous macros
 490  */
 491 #define pidXwait(pid,cp) pidstatus (pidwait (pid, NOTOK), stdout, cp)
 492
 493 #ifndef max
 494 # define max(a,b) ((a) > (b) ? (a) : (b))
 495 #endif
 496
 497 #ifndef min
 498 # define min(a,b) ((a) < (b) ? (a) : (b))
 499 #endif
 500
 501 #ifndef abs
 502 # define abs(a) ((a) > 0 ? (a) : -(a))
 503 #endif
 504
 505 /*
 506  * GLOBAL VARIABLES
 507  */
 508 #define CTXMOD  0x01            /* context information modified */
 509 #define DBITS   "\020\01CTXMOD"
 510 extern char ctxflags;
 511
 512 extern char *invo_name;         /* command invocation name         */
 513 extern char *mypath;            /* user's $HOME                    */
 514 extern char *defpath;           /* pathname of user's profile      */
 515 extern char *ctxpath;           /* pathname of user's context      */
 516 extern struct node *m_defs;     /* list of profile/context entries */
 517
 518 /*
 519  * These standard strings are defined in config.c.  They are the
 520  * only system-dependent parameters in nmh, and thus by redefining
 521  * their values and reloading the various modules, nmh will run
 522  * on any system.
 523  */
 524 extern char *buildmimeproc;
 525 extern char *catproc;
 526 extern char *components;
 527 extern char *context;
 528 extern char *current;
 529 extern char *credentials_file;
 530 extern int credentials_no_perm_check;
 531 extern char *defaultfolder;
 532 extern char *digestcomps;
 533 extern char *distcomps;
 534 extern char *draft;
 535 extern char *fileproc;
 536 extern char *foldprot;
 537 extern char *formatproc;
 538 extern char *forwcomps;
 539 extern char *inbox;
 540 extern char *incproc;
 541 extern char *lproc;
 542 extern char *mailproc;
 543 extern char *mh_defaults;
 544 extern char *mh_profile;
 545 extern char *mh_seq;
 546 extern char *mhlformat;
 547 extern char *mhlforward;
 548 extern char *mhlproc;
 549 extern char *mhlreply;
 550 extern char *moreproc;
 551 extern char *msgprot;
 552 extern char *nmhaccessftp;
 553 extern char *nmhaccessurl;
 554 extern char *nmhstorage;
 555 extern char *nmhcache;
 556 extern char *nmhprivcache;
 557 extern char *nsequence;
 558 extern char *packproc;
 559 extern char *postproc;
 560 extern char *pfolder;
 561 extern char *psequence;
 562 extern char *rcvdistcomps;
 563 extern char *rcvstoreproc;
 564 extern char *replcomps;
 565 extern char *replgroupcomps;
 566 extern char *rmmproc;
 567 extern char *sendproc;
 568 extern char *showmimeproc;
 569 extern char *showproc;
 570 extern char *usequence;
 571 extern char *user_agent;
 572 extern char *version_num;
 573 extern char *version_str;
 574 extern char *whatnowproc;
 575 extern char *whomproc;
 576
 577 #include <h/prototypes.h>