[PREVIOUS CHAPTER]
[NEXT CHAPTER]
7 FML internal data structures
Here we describe FML internal data structures. When you hacks FML,
this knowledge is required. However you do not need to read this
chapter if you toggle variables only on/off.
7.1 Naming convention of variables
* ^[A-Z0-9_]+$ name variable is USER DEFINED VARIABLE for customize.
It is a global variable. Fundamentally these variables are defined in
config.ph, sitedef.ph and site_init.ph.
Example: $MAIL_LIST
* Capitals are global not for USERS but for systems. In principle
users should not touch them. If you hacks, it must require to handle
these variable.
$MailBody $Reply_to
%Envelope *_cf
%Envelope is the most important variable. We should not increase
the number of global variables. Several variables e.g. @Fld
are capital but historically left not as global.
ATTENTION: historically $debug is global for convenience.
* Lower case word is local variable.
[Appendix]
Directory variables consists of two types
$*_DIR relative path to $DIR
$FP_*_DIR obsolete path
$FP_*_DIR is automatically defined based on directory variables.
In a lot cases absolute path is used.
$FP_TMP_DIR
$FP_VARDB_DIR
$FP_VARLOG_DIR
$FP_VARRUN_DIR
$FP_VAR_DIR
$FP_SPOOL_DIR
7.2 Naming convention of functions
Except for a few cases, a function name is capitalized. The word after
"_" is also capitalized. It is similar to X11 style:D
* Some exceptions remains after fml 1.5.
File operation functions are defined as
f_function_name conversion interface
Cnstr_function_name constructor for this mode
Destr_function_name destructor for this mode
These are exceptional. In that age I should replace these naming
convention but still remains ;D
7.3 %Envelope (hash)
%Envelope is most important variable(hash). %Envelope contains header,
each field of the header, body as a hash table. This hash is passed in
a lot of function calls. It is similar to sendmail's struct ENVELOPE
e;
In the age of FML 1.5, perl 5 does not run. Hence we cannot use
e.g. the following style
$Envelope->$Header->$From = "uja@domain";
It is represented by
$Envelope{"h:From:"} = "uja@domain";
":" is a separator. From: is a special syntax to identify this key is
a field.
Keys of %Envelope:
KEY beginning with "h:" is a field of a header.
h:Capital: adjusted field data to use in delivery e.g. h:Subject:
h:lower-case: original field data e.g. h:subject:
h:field: header field
lower case name is original
Capital is after changed.
fh:field: enforce a field to use this value
oh:field: enforce fml.pl to use original field value
for this field
GH:field: enforce some value for field of command mail results
and so on. used in GenerateHeader().
reply-to: > From:
Addr2Reply: address to send a command result and so on
[mode or method configurations]
macro:x corresponds to $x of sendmail
mode:x mode x is enabled.
mci:mailer Mail Connection Information
mci:mailer is ipc or prog.
[Internal Data]
Header original header
Body original mail body
Hdr header of sending mails out in distribute phase
message message to send back to a sender
for command results and others
error error message to send back to a sender
MIME ISO-2022-JP is detected (toggle Flag)
UnixFrom Unix From
MIME ISO-2022-JP is detected (toggle Flag)
UnixFrom Unix From
Hdr2add buffer when $SUPERFLUOUS_HEADER is set.
nclines number of lines for "# command" style lines
nlines lines of mail body
preamble preamble to put on mail body
trailer trailer to put on mail body
tmp:x temporary used
Example: Subject:
$Envelope{'h:subject:'} is
an in-coming mail's original Subject: field value.
$Envelope{'h:Subject:'} is after cutting Re:'s and tags e.g. [Elena 100].
Example: In a header of distribution, used key of %Envelop is as follow:
Field key in %Envelope
---------------------------------------
Date: h:Date:
From: h:From:
To: h:To:
Subject: h:Subject:
7.4 Initialize data structures
Initialization of fml.pl is as follows:
initialize $DIR $LIBDIR @INC and so on
&InitConfig
&SetDefaults
%Envelope
DNS, @HdrFieldsOrder, and others
&LoadConfig
$DIR/config.ph
sitedef.ph
&SetOpts
command line options
COMPATIBILITY CODE
&Parse
&Parse
reset %Envelope
&GetFieldsFromHeader
&GetFieldsFromHeader
analyze %Envelope and set h:field: and h:Field: up.
&FixHeaderFields
&FixHeaderFields
adjust h:Field:
&CheckCurrentProc
&CheckCurrentProc
adjust fields, check loops, modes and so on
After this fml.pl sets in the main routine,
hooks are evaluated in several locations.
Example:
$START_HOOK
$SMTP_OPEN_HOOK
$FML_EXIT_HOOK
After this, the critical section begins.
7.5 Directory variables
[Directory variable list]
$DIR @INC(original) $LIBDIR ...
$DIR
$DIR
config.ph location. ML's HOME directory.
The argument of @INC.
$LIBDIR
library paths. @LIBDIR is a list of $LIBDIR's.
fml pushes $LIBDIR to @LIBDIR.
fml searches @LIBDIR for executable and libraries
$SPOOL_DIR $DIR/spool
$SPOOL_DIR $DIR/spool
spool of articles of ML
[Relative path from $DIR]
$TMP_DIR tmp (temporary)
$VARDB_DIR var/db (database, 4.4BSD like)
$VARLOG_DIR var/log (log, 4.4BSD like)
$DIR/log is exceptional for backward
compatibility.
($VARLOG_DIR/log is preferable)
$VARRUN_DIR var/run (4.4BSD like)
pid's file and several caches
$VAR_DIR var (4.4BSD like)
[Corresponding fully pathed directory variables]
$FP_TMP_DIR $DIR/$TMP_DIR
$FP_VARDB_DIR $DIR/$VARDB_DIR
$FP_VARLOG_DIR $DIR/$VARLOG_DIR
$FP_VARRUN_DIR $DIR/$VARRUN_DIR
$FP_VAR_DIR $DIR/$VAR_DIR
$FP_SPOOL_DIR $DIR/$SPOOL_DIR
7.6 On temporary directory ($TMP_DIR)
$DIR/tmp is temporary working area. It is defined as $TMP_DIR. We
should not use the system's /tmp or /var/tmp if the file is left when
OS crashes.
7.7 Configuration files
[Member Lists]
$MEMBER_LIST $DIR/members
the ML member list for authentication. If a given address is
not in this list, fml.pl does not authenticate the
address. This is not a delivery list in non automatically
registration mode. In automatic registration mode, this file
is both a member and delivery list.
$ACTIVE_LIST $DIR/actives
list of distribution in non automatically registration mode.
$REJECT_ADDR_LIST $DIR/spamlist
list to reject as a spammer.
[files of guides and so on]
$OBJECTIVE_FILE $DIR/objective
objective of ML
$GUIDE_FILE $DIR/guide
guide for general people (for not member)
$HELP_FILE $DIR/help
help file of ML (for only member)
$DENY_FILE $DIR/deny
file to send back when fml.pl rejects mail from a non member.
This is not used in auto registration mode.
$WELCOME_FILE $DIR/guide
file to send back in auto-registration mode when
a user is automatically registered.
$CONFIRMATION_FILE $DIR/confirm
confirmation file in auto-registration mode.
Please see confirmation (../how_to_subscribe 5.9).
[Logfiles]
$LOGFILE $DIR/log
log file
$MGET_LOGFILE $DIR/log
mget log. In default $MGET_LOGFILE == $LOGFILE.
$SMTPLOG $VARLOG_DIR/_smtplog
Log of SMTP (for debug).
$SUMMARY_FILE $DIR/summary
summary of ML
$SEQUENCE_FILE $DIR/seq
ML's sequence number
$MSEND_RC $VARLOG_DIR/msendrc
digest control file.
$LOCK_FILE $VARRUN_DIR/lockfile.v7
lock file when not flock(2) lock but link(2) based.
$LOG_MESSAGE_ID $VARRUN_DIR/msgidcache
Message-Id cache file to prevent loops.
$MESSAGE_ID_CACHE_BUFSIZE
Message-ID cache file size
$INDEX_FILE $DIR/index
Fml.pl works without this file. If exists, "index" commands
sends back this file. If not, FML scans $SPOOL_DIR,
@ARCHIVE_DIR and sends back the summary.
7.8 Other useful variables
$DO_NOTHING
Special flag to declare "do nothing".
$NULL
dummy:D like "#define null (char *)0".
$FML
process table name
$FACE_MARK
e.g. P(^^)
Be seeing you P(^^)
appended in the reply message, e.g. command results.
$INCLUDE_SIM_PATH
Please ignore this. This is used in simulation.
$UNISTD
Declare "Unix Standard" flag. undefined on Windows NT4
$LOCKFILE
lock file variable in some libraries. It may be uncontrolled
by a user.
%MAKE_FML
Please not touch %MAKE_FML in config.ph which variable "makefml" uses
though it is not used today.
* obsolete variables (renamed to)
$GUIDE_REQUEST -> $GuideRequest
$RPG_ML_FORM_FLAG -> $COMMAND_SYNTAX_EXTENSION
* obsolete
$NON_PORTABILITY
7.9 Listing variables list
To dump variable used in fml.pl (by dumpvar.pl), sets
$DUMPVAR = 1;
FYI: fmlserv.pl uses the same technique to switch name spaces.
[PREVIOUS CHAPTER]
[NEXT CHAPTER]