-/*
-Purpose
-=======
-Reads an Internet message (RFC 5322), or one or more messages stored in a
-maildrop in mbox (RFC 4155) or MMDF format, from a file stream. Each call
-to m_getfld() reads one header field, or a portion of the body, in sequence.
-
-Inputs
-======
-state: message parse state
-bufsz: maximum number of characters to load into buf
-iob: input file stream
-
-Outputs
-=======
-name: header field name (array of size NAMESZ=999)
-buf: either a header field body or message body
-(return value): message parse state on return from function
-(global) int msg_count: number of characters loaded into buf
-
-Functions (part of Inputs, really)
-=========
-void m_unknown(FILE *iob): Determines the message delimiter string for the
- maildrop. Called by inc, scan, and msh when reading from a maildrop file.
-
-void m_eomsbr (int (*action)(int)): Sets the hook to check for end of
- message in a maildrop. Called only by msh.
-
-Those functions save state in the State variables listed below.
-
-Definitions
-===========
-state is one of:
- FLD // Field returned
- FLDPLUS // Field returned with more to come
- FLDEOF // Field returned ending at eom
- BODY // Body returned with more to come
- BODYEOF // Body returned ending at eom
- FILEEOF // Reached end of input file
- FMTERR // Message Format error
- LENERR // Name too long error from getfld
-
-msg_style is maildrop style, one of:
- MS_UNKNOWN // type not known yet
- MS_DEFAULT // default (one msg per file)
- MS_MBOX // Unix-style "from" lines
- MS_MMDF // string mmdlm2
- MS_MSH // whacko msh
-
-State variables (part of Outputs)
-===============
-m_getfld() retains state internally between calls in some state variables.
-
-These two variables are global, but only used internally by m_getfld.c:
-int msg_style
-char *msg_delim
-
-These are used for the end-of-message matcher when reading maildrops:
-static unsigned char **pat_map
-static unsigned char *fdelim
-static unsigned char *delimend
-static int fdelimlen
-static unsigned char *edelim
-static int edelimlen
-
-Restriction
-===========
-m_getfld() is restricted to operate on one file stream at a time because of
-the retained state (see "State variables" above).
-
-Current usage
-=============
-The first call to m_getfld() on a file stream is with a state of FLD.
-Subsequent calls provide the state returned by the previous call.
-
-Along the way, I thought of these possible interface changes that we
-might want to consider before rototilling the internals:
-
-1) To remove a global:
- Change bufsz to be in-out instead of in, and therefore int * instead of
- int, and use that instead of global msg_count. There are only 3 call
- sites that use msg_count so it wouldn't take much effort to remove use of
- it. Of course, all call sites would have to change to provide an int *
- instead of an int. Some now pass constants.
-
-2) To remove the state argument from the signature:
- Given the Current usage and Restriction above, the state variable could
- be removed from the signature and just retained internally.
-
-3) To remove the Restriction above:
- One approach would be for m_getfld() to retain multiple copies of that
- state, one per iob that it sees. Another approach would be for the
- caller to store it in an opaque struct, the address of which is passed
- through the interface.
-*/
-