"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "doc/functions.texi" between
mailfromd-8.11.tar.xz and mailfromd-8.12.tar.xz

About: Mailfromd is a general-purpose mail filtering daemon for Sendmail, Postfix and MeTA1 (interfaces with the MTA using Milter or PMilter protocols).

functions.texi  (mailfromd-8.11.tar.xz):functions.texi  (mailfromd-8.12.tar.xz)
skipping to change at line 19 skipping to change at line 19
the word @samp{boolean} to indicate variables of numeric type that are the word @samp{boolean} to indicate variables of numeric type that are
used as boolean values. For such variables, the term @samp{False} used as boolean values. For such variables, the term @samp{False}
stands for the numeric 0, and @samp{True} for any non-zero value. stands for the numeric 0, and @samp{True} for any non-zero value.
@menu @menu
* Macro access:: * Macro access::
* String transformation:: * String transformation::
* String manipulation:: * String manipulation::
* String formatting:: * String formatting::
* Character Type:: * Character Type::
* I/O functions::
* Filtering functions::
* Email processing functions:: * Email processing functions::
* Envelope modification functions:: * Envelope modification functions::
* Header modification functions:: * Header modification functions::
* Body Modification Functions:: * Body Modification Functions::
* Message modification queue:: * Message modification queue::
* Mail header functions:: * Mail header functions::
* Mail body functions:: * Mail body functions::
* EOM Functions:: * EOM Functions::
* Current Message Functions:: * Current Message Functions::
* Mailbox functions:: * Mailbox functions::
* Message functions:: * Message functions::
* Quarantine functions:: * Quarantine functions::
* SMTP Callout functions:: * SMTP Callout functions::
* Compatibility Callout functions:: * Compatibility Callout functions::
* Internet address manipulation functions:: * Internet address manipulation functions::
* DNS functions:: * DNS functions::
* Geolocation functions:: * Geolocation functions::
* Database functions:: * Database functions::
* I/O functions::
* System functions:: * System functions::
* Passwd functions:: * Passwd functions::
* Sieve Interface:: * Sieve Interface::
* Interfaces to Third-Party Programs:: * Interfaces to Third-Party Programs::
* Rate limiting functions:: * Rate limiting functions::
* Greylisting functions:: * Greylisting functions::
* Special test functions:: * Special test functions::
* Mail Sending Functions:: * Mail Sending Functions::
* Blacklisting Functions:: * Blacklisting Functions::
* SPF Functions:: * SPF Functions::
skipping to change at line 844 skipping to change at line 845
Checks for uppercase letters. Checks for uppercase letters.
@end deftypefn @end deftypefn
@deftypefn {Built-in Function} boolean isxdigit (string @var{str}) @deftypefn {Built-in Function} boolean isxdigit (string @var{str})
Checks for hexadecimal digits, i.e. one of @samp{0}, @samp{1}, Checks for hexadecimal digits, i.e. one of @samp{0}, @samp{1},
@samp{2}, @samp{3}, @samp{4}, @samp{5}, @samp{6}, @samp{7}, @samp{8}, @samp{2}, @samp{3}, @samp{4}, @samp{5}, @samp{6}, @samp{7}, @samp{8},
@samp{9}, @samp{a}, @samp{b}, @samp{c}, @samp{d}, @samp{e}, @samp{f}, @samp{9}, @samp{a}, @samp{b}, @samp{c}, @samp{d}, @samp{e}, @samp{f},
@samp{A}, @samp{B}, @samp{C}, @samp{D}, @samp{E}, @samp{F}. @samp{A}, @samp{B}, @samp{C}, @samp{D}, @samp{E}, @samp{F}.
@end deftypefn @end deftypefn
@node I/O functions
@section I/O functions
@acronym{MFL} provides a set of functions for writing to disk files,
pipes or sockets and reading from them. The idea behind them is the
same as in most other programming languages: first you open the
resource with a call to @code{open} which returns a @dfn{descriptor}
i.e. an integer number uniquely identifying the resource. Then you
can write or read from it using this descriptor. Finally, when the
resource is no longer needed, you can close it with a call to
@code{close}.
The number of available resource descriptors is limited. The
default limit is @value{MAX_IOSTREAMS}. You can tailor it to your needs
using the @code{max-streams} runtime configuration statement.
@xref{conf-runtime, max-streams}, for a detailed description.
@anchor{open}
@deftypefn {Built-in Function} number open (string @var{name})
The @var{name} argument specifies the name of a resource to open and
the access rights you need to have on it. The function returns a
descriptor of the opened stream, which can subsequently be used
as an argument to other @acronym{I/O} operations.
First symbols of @var{name} determine the type of the resource to be
opened and the access mode:
@table @samp
@item >
The rest of @var{name} is a name of a file. Open the file for
read-write access. If the file exists, truncate it to zero length,
otherwise create the file.
@item >>
The rest of @var{name} is a name of a file. Open the file for
appending (writing at end of file). The file is created if it does
not exist.
@item |
Treat the rest of @var{name} as the command name and its arguments.
Run this command and open its standard input for writing. The standard
error is closed before launching the program. This can be altered by
using the following versions of this construct:
@table @asis
@item |2>null: @var{command}
Standard error is redirected to @file{/dev/null}.
@item |2>file:@var{name} @var{command}
Execute @var{command} with its standard error redirected to the file
@var{name}. If the file exists, it will be truncated.
@item |2>>file:@var{name} @var{command}
Standard error of the @var{command} is appended to the file
@var{name}. If file does not exist, it will be created.
The @samp{|2>null:} construct described above is a shortcut for
@example
|2>>file:/dev/null @var{command}
@end example
@item |2>syslog:@var{facility}[.@var{priority}] @var{command}
Standard error is redirected to the given syslog @var{facility} and,
optionally, @var{priority}. If the latter is omitted, @samp{LOG_ERR}
is assumed.
Valid values for @var{facility} are: @samp{user}, @samp{daemon},
@samp{auth}, @samp{authpriv}, @samp{mail}, and @samp{local0}
through @samp{local7}. Valid values for @var{priority} are:
@samp{emerg}, @samp{alert}, @samp{crit}, @samp{err}, @samp{warning},
@samp{notice}, @samp{info}, @samp{debug}. Both @var{facility} and
@var{priority} may be given in upper, lower or
mixed cases.
@end table
Notice, that no whitespace characters are allowed between @samp{|} and
@samp{2>}.
@item |<
Treat the rest of @var{name} as the command name and its arguments.
Run this command with its stdin closed and stdout open for reading.
The standard error is treated as described above (see @samp{|}).
@item |&
Treat the rest of @var{name} as the command name and its arguments.
Run this command and set up for two-way communication with it, i.e
writes to the descriptor returned by @code{open} will send data to the
program's standard input, reads from the descriptor will get data from
the program's standard output.
The standard error is treated as described above (see
@samp{|}). For example, the following redirects it to
syslog @samp{mail.debug}:
@example
|&2>syslog:mail.debug @var{command}
@end example
@item @@
Treat the rest of @var{name} as the @acronym{URL} of a socket to
connect to. Valid @acronym{URL} forms are described in @ref{milter
port specification}.
@end table
If none of these prefixes is used, @var{name} is treated as a name
of an existing file and @code{open} will attempt to open this file for
reading.
The @code{open} function will signal exception @code{e_failure} if it
is unable to open the resource or get the required access to it.
@end deftypefn
@deftypefn {Built-in Function} number spawn (string @var{cmd} [, @
number @var{in}, number @var{out}, number @var{err}])
Runs the supplied command @var{cmd}. The syntax of the @var{cmd} is
the same as for the @var{name} argument to @code{open} (see above),
which begins with @samp{|}, excepting that the @samp{|} sign is
optional. That is:
@example
spawn("/bin/cat")
@end example
@noindent
has exactly the same effect as
@example
open("|/bin/cat")
@end example
Optional arguments specify file stream descriptors to be used for the
program standard input, output and error streams, correspondingly.
If supplied, these should be the values returned by a previous call to
@code{open} or @code{tempfile}. The value @samp{-1} means no
redirection.
The example below starts the @code{awk} program with a simple
expression as its argument and redirects the content of the
file @file{/etc/passwd} to its standard input. The returned
stream descriptor is bound to the command's standard output
(see the description of @samp{|<} prefix above). The standard
error is closed:
@example
number fd spawn("<awk -F: '@{print $1@}'", open("/etc/passwd"))
@end example
@end deftypefn
@deftypefn {Built-in Function} void close (number @var{rd})
The argument @var{rd} is a resource descriptor returned by a
previous call to @code{open}. The function @code{close} closes the
resource and deallocates any memory associated with it.
@code{close} will signal @code{e_range} exception if @var{rd} lies
outside of allowed range of resource descriptors. @xref{conf-runtime,
max-streams}.
@end deftypefn
Notice that you are not required to close resources opened by @code{open}.
Any unclosed resource will be closed automatically upon the
termination of the filtering program.
@deftypefn {Built-in Function} void shutdown (number @var{rd}, number @var{how})
This function causes all or part of a full-duplex connection to be
closed. The @var{rd} must be either a socket descriptor (returned by
@code{open(@@...)}) or a two-way pipe socket descriptor (returned by
@code{open(|&...)}), otherwise the call to @code{shutdown} is
completely equivalent to @code{close}.
The @code{how} argument identifies which part of the connection to
shut down:
@table @asis
@kwindex SHUT_RD
@item SHUT_RD
Read connection. All further receptions will be disallowed.
@kwindex SHUT_WR
@item SHUT_WR
Write connection. All further transmissions will be disallowed.
@kwindex SHUT_RDWR
@item SHUT_RDWR
Shut down both read and write parts.
@end table
@end deftypefn
@deftypefn {Built-in Function} number tempfile ([string @var{tmpdir}])
Creates a nameless temporary file and returns its descriptor.
Optional @var{tmpdir} supplies the directory where to create the file,
instead of the default @file{/tmp}.
@end deftypefn
@deftypefn {Built-in Function} void rewind (number @var{rd})
Rewinds the stream identified by @var{rd} to its beginning.
@end deftypefn
@deftypefn {Built-in Function} number copy (number @var{dst}, number @var{src})
Copies all data from the stream @var{src} to @var{dst}. Returns
number of bytes copied.
@end deftypefn
The following functions provide basic read/write capabilities.
@deftypefn {Built-in Function} void write (number @var{rd}, string @var{str} @
[, number @var{size}])
Writes the string @var{str} to the resource descriptor @var{rd}. If
the @var{size} argument is given, writes this number of bytes.
The function will signal @code{e_range} exception if @var{rd} lies
outside of allowed range of resource descriptors, and @code{e_io}
exception if an @acronym{I/O} error occurs.
@end deftypefn
@deftypefn {Built-in Function} void write_body (number @var{rd}, pointer @var{bp
} @
, number @var{size})
Write the body segment of length @var{size} from pointer @var{bp} to
the stream @var{rd}. This function can be used only in @code{prog
body} (@pxref{body handler}). Its second and third arguments
correspond exactly to the parameters of the @code{body} handler, so
the following construct writes the message body to the resource
@code{fd}, which should have been open prior to invoking the
@code{body} handler:
@example
@group
prog body
do
write_body(fd, $1, $2)
done
@end group
@end example
@end deftypefn
@deftypefn {Built-in Function} string read (number @var{rd}, number @var{n})
Read and return @var{n} bytes from the resource descriptor @var{rd}.
The function may signal the following exceptions:
@table @asis
@item e_range
@var{rd} lies outside of allowed range of resource descriptors.
@item e_eof
End of file encountered.
@item e_io
An @acronym{I/O} error occurred.
@end table
@end deftypefn
@deftypefn {Built-in Function} string getdelim (number @var{rd}, string @var{del
im})
Read and return the next string terminated by @var{delim} from the
resource descriptor @var{rd}.
The terminating @var{delim} string will be removed from the return
value.
The function may signal the following exceptions:
@table @asis
@item e_range
@var{rd} lies outside of allowed range of resource descriptors.
@item e_eof
End of file encountered.
@item e_io
An @acronym{I/O} error occurred.
@end table
@end deftypefn
@deftypefn {Built-in Function} string getline (number @var{rd})
Read and return the next @dfn{line} from the resource
descriptor @var{rd}. A line is any sequence of characters terminated
with the default @dfn{line delimiter}. The default delimiter is
a property of @var{rd}, i.e. different descriptors can have different
line delimiters. The default value is @samp{\n} (ASCII 10), and can
be changed using the @code{fd_set_delimiter} function (see below).
The function may signal the following exceptions:
@table @asis
@item e_range
@var{rd} lies outside of allowed range of resource descriptors.
@item e_eof
End of file encountered.
@item e_io
An @acronym{I/O} error occurred.
@end table
@end deftypefn
@deftypefn {Built-in Function} void fd_set_delimiter (number @var{fd}, @
string @var{delim})
Set new line delimiter for the descriptor @var{fd}, which must be in
opened state.
Default delimiter is a newline character (ASCII 10). The following
example shows how to change it to CRLF sequence:
@example
fd_set_delimiter(fd, "\r\n")
@end example
@end deftypefn
@deftypefn {Built-in Function} string fd_delimiter (number @var{fd})
Returns the line delimiter string for @var{fd}.
@end deftypefn
The following example shows how @command{mailfromd} @acronym{I/O} functions can
be used to automatically add @acronym{IP} addresses to an @acronym{RBL} zone:
@example
@group
set nsupdate_cmd
"/usr/bin/nsupdate -k /etc/bind/Kmail.+157+14657.private"
func block_address(string addr)
do
number fd
string domain
set fd open "|%nsupdate_cmd"
set domain revip(addr) . ".rbl.myzone.come"
write(fd, "prereq nxrrset %domain A\n"
"update add %domain 86400 A %addr\n\n"
done
@end group
@end example
@noindent
The function @code{revip} is defined in @ref{revip}.
@node Filtering functions
@section Filtering functions
This section describes functions that transform data using
Mailutils @dfn{filter pipes}. Filter pipe is a string defining data
flow between several @dfn{filters}. Each filter takes input,
transforms it according to certain rules and produces the transformed
data on its output. As in shell, multiple filters are connected
using pipe characters (@samp{|}). For example, the @code{crlf} filter
inserts a carriage return character before each newline character. A
filter doing that kind of transformation is defined as:
@example
"crlf"
@end example
Another filter, @code{base64}, converts its input to a BASE64 encoded
string. To transform each newline into carriage return + newline pair
and encode the resulting stream in BASE64, one would write:
@example
"crlf | base64"
@end example
Some filters take one or more @dfn{arguments}. These are specified as
a comma-delimited list in parentheses after the filter name. For
example, the @code{linelen} filter limits the length of each output
line to the given number of octets. The following filter pipe will
limit the length of base64 lines in the filter above to 62 octets:
@example
"crlf | base64 | linelen(62)"
@end example
Many filters operate in two modes: @dfn{encode} and @dfn{decode}. By
default all MFL functions apply filters in encode mode. The desired
mode can be stated explicitly in the filter string by using
@code{encode()} and @code{decode()} functions. They take a filter
pipe line as their argument. For example, the following will decode
the stream produced by the example filter above:
@example
"decode(base64 | crlf)"
@end example
@xref{Filters}, for a discussion of available filters and their arguments.
@deftypefn {Built-in Function} string filter_string (string @var{input}, string
@var{filter_pipe})
Transforms the string @var{input} using filters in @var{filter_pipe}
and returns the result. Example:
@example
set input "test\ninput\n"
filter_string(input, "crlf|base64") @result{} "dGVzdA0KaW5wdXQNCg=="
@end example
@end deftypefn
@deftypefn {Built-in Function} void filter_fd (number @var{src_fd}, number @var{
dst_fd}, string @var{filter_pipe})
Given two I/O descriptors, reads data from @var{src_fd}, transforms it
using @var{filter_pipe} and writes the result to descriptor
@var{dst_fd}.
Both descriptors must be obtained using functions described in
@ref{I/O functions}.
@end deftypefn
@node Filters
@subsection Filters and Filter Pipes
@include filter_pipe.texi
@node Email processing functions @node Email processing functions
@section Email processing functions. @section Email processing functions.
@deftypefn {Built-in Function} number email_map (string @var{email}) @deftypefn {Built-in Function} number email_map (string @var{email})
Parses @var{email} and returns a bitmap, consisting of zero or more of Parses @var{email} and returns a bitmap, consisting of zero or more of
the following flags: the following flags:
@table @samp @table @samp
@kwindex EMAIL_MULTIPLE @kwindex EMAIL_MULTIPLE
@item EMAIL_MULTIPLE @item EMAIL_MULTIPLE
skipping to change at line 1672 skipping to change at line 2076
@deftypefn {Built-in Function} string message_read_body_line (number @var{nmsg}) @deftypefn {Built-in Function} string message_read_body_line (number @var{nmsg})
Read and return next line from the body of the message @var{nmsg}. If Read and return next line from the body of the message @var{nmsg}. If
there are no more lines to read, raise the @code{eof} exception. there are no more lines to read, raise the @code{eof} exception.
Use @code{message_body_rewind} (see above) to rewind the body stream Use @code{message_body_rewind} (see above) to rewind the body stream
and read its contents again. and read its contents again.
@end deftypefn @end deftypefn
@deftypefn {Built-in Function} void message_body_to_stream (number @var{fd},@ @deftypefn {Built-in Function} void message_body_to_stream (number @var{fd},@
number @var{nmsg}; @ number @var{nmsg}; @
string @var{filter_chain}) string @var{filter_pipe})
Copies the body of the message @var{nsmg} to stream descriptor Copies the body of the message @var{nsmg} to stream descriptor
@var{fd}. The descriptor must be obtained by a previous call to @var{fd}. The descriptor must be obtained by a previous call to
@code{open}. @code{open}.
Optional @var{filter_chain} supplies the name of a @dfn{Mailutils Optional @var{filter_pipe} supplies a sequence of @dfn{Mailutils
filter chain}, through which the data will be passed before writing filters}, through which the data will be passed before writing
them to @var{fd}. oSee @uref{http://mailutils.org/wiki/Filter_chain}, them to @var{fd}. @xref{Filtering functions}, for a discussion of
for a description of filter chains. filter pipe syntax.
@kwindex mimedecode
@cindex MIME, decoding
@cindex decode MIME
In addition to filters described in @xref{Filters}, two special
filters are provided for use with this function: @code{mimedecode} and
@code{charset}. The @code{mimedecode} filter instructs the function
to decode the message body by reverting the encoding specified by its
@code{Content-Transfer-Encoding} header. It is normally used as the
very first filter in chain. The @code{charset} filter recodes the
message body from it original charater set to the character set
specified as its argument.
@xref{mimedecode}, for a detailed discussion of this feature.
@end deftypefn @end deftypefn
@node MIME functions @node MIME functions
@subsection MIME functions @subsection MIME functions
@deftypefn {Built-in Function} boolean message_is_multipart (number @var{nmsg}) @deftypefn {Built-in Function} boolean message_is_multipart (number @var{nmsg})
Return @code{true} if message @var{nmsg} is a multipart Return @code{true} if message @var{nmsg} is a multipart
(@acronym{MIME}) message. (@acronym{MIME}) message.
@end deftypefn @end deftypefn
skipping to change at line 1707 skipping to change at line 2125
@end deftypefn @end deftypefn
@deftypefn {Built-in Function} number message_get_part (number nmsg, @ @deftypefn {Built-in Function} number message_get_part (number nmsg, @
number @var{n}) number @var{n})
Extract @var{n}th part from the multipart message @var{nmsg}. Extract @var{n}th part from the multipart message @var{nmsg}.
Numeration of parts begins from @samp{1}. Return message descriptor Numeration of parts begins from @samp{1}. Return message descriptor
referring to the extracted part. Message parts are regarded as referring to the extracted part. Message parts are regarded as
messages, so any message functions can be applied to them. messages, so any message functions can be applied to them.
@end deftypefn @end deftypefn
@deftypefn {Built-in Function} string message_content_type (number @var{nmsg})
Returns content type for the message @var{nmsg}. The returned string
is composed of content type and subtype, delimited by slash.
If @var{nmsg} is not a multipart message, the function returns
@samp{text/plain}.
@end deftypefn
@anchor{MIME decoding}
@cindex MIME, decoding
@cindex decode MIME
Several functions are provided for decoding multi-part messages. Such
decoding is governed by @code{Content-Transfer-Encoding} and
@code{Content-Type} headers of the message. The
@code{Content-Transfer-Encoding} header defines the method used to
encode the message. The value of @code{Content-Type} header is used
to determine the character set the body is written in.
@anchor{mimedecode}
@kwindex mimedecode
Basic MIME decoding facilities are provided by the built-in function
@code{message_body_to_stream}, described in the previous subsection.
To instruct it to decode the content, pass it the @var{filter_chain}
argument beginning with the word @code{mimedecode}. The usual
sequence is:
@example
set fd open("> outfile")
message_body_to_stream(fd, msg, "mimedecode")
@end example
To ensure that the produced stream is represented in a specific
character set, use the @code{charset} special filter. Its argument is
the name of the character set to recode the text to:
@example
set fd open("> outfile")
message_body_to_stream(fd, msg, "mimedecode|charset(utf-8)")
@end example
The @code{charset} filter takes also an optional second argument -- a
@dfn{fallback} method, specifying what to do when an octet sequence is
encountered that cannot be represented in the requested character set.
Possible values for this argument are:
@table @samp
@item none
Stop further conversion and signal the @code{e_ilseq} exception.
@item copy-pass
Copy the offending character to the output verbatim.
@item copy-octal
Represent the offending character as a C octal sequence
(@samp{\@var{n}@var{n}@var{n}}, where @var{n} is an octal digit).
This is the default.
@end table
To decode a particular part of the message, first extract it using the
@code{message_get_part} function. Recall that message parts are
messages as well, and as such can be passed to
@code{message_body_to_stream}. For example, the following code
fragment extracts all top-level parts of a multi-part message to files
named @samp{part.@var{N}}:
@example
@group
if message_is_multipart(msg)
set n message_count_parts(msg)
loop for set i 1, while i <= n, set i i + 1
do
set fd open("> part.%i")
message_body_to_stream(fd, message_get_part(msg, i), "mimedecode")
close(fd)
done
fi
@end group
@end example
@flindex mime.mf
The @file{mime.mf} module provides additional functions for decoding
multi-part messages:
@deftypefn {Library Function} number message_body_decode (number @var{nmsg}; @
string @var{charset}, string @var{fallback})
Decodes the body of the message (or message part) @var{nmsg},
optionally converting it to the given @var{charset}. The
@var{fallback} argument specifies what to do if a byte sequence cannot
be converted to the specified character set. @xref{iconv fallback},
for a detailed discussion.
The function returns a descriptor of the I/O stream that contains the
decoded material. @xref{I/O functions} for a discussion of functions
available for reading from it.
@end deftypefn
@deftypefn {Library Function} number message_part_decode(number @var{nmsg}, numb
er @var{part}; @
string @var{charset}, string @var{fallback})
Decodes the body of the given part of a MIME message @var{nmsg}. The
argument @var{part} is a 1-based index of the part in the message.
Optional arguments @var{charset} and @var{fallback} have the same
meaning as in @code{message_body_decode} (see above).
Returns a descriptor of the I/O stream that contains the decoded
material.
This function is equivalent to:
@example
message_body_decode(message_get_part(@var{nmsg}, @var{part}, @var{charset},
@var{fallback}))
@end example
@end deftypefn
@node Message digest functions @node Message digest functions
@subsection Message digest functions @subsection Message digest functions
@cindex message digest @cindex message digest
@cindex digest, message @cindex digest, message
@dfn{Message digests} are specially formatted messages that @dfn{Message digests} are specially formatted messages that
contain certain number of mail messages, encapsulated using contain certain number of mail messages, encapsulated using
the method described in RFC 934. Such digests are often used the method described in RFC 934. Such digests are often used
in mailing lists to reduce the frequency of sending mails. in mailing lists to reduce the frequency of sending mails.
Messages of this format are also produced by the @dfn{forward} Messages of this format are also produced by the @dfn{forward}
skipping to change at line 2970 skipping to change at line 3502
@example @example
if relayed(hostname($@{client_addr@})) if relayed(hostname($@{client_addr@}))
@dots{} @dots{}
@end example @end example
@noindent @noindent
which yields @code{true} if the @acronym{IP} address from @command{Sendmail} var iable which yields @code{true} if the @acronym{IP} address from @command{Sendmail} var iable
@samp{client_addr} is relayed by the local machine. @samp{client_addr} is relayed by the local machine.
@end deftypefn @end deftypefn
@node I/O functions
@section I/O functions
@acronym{MFL} provides a set of functions for writing to disk files,
pipes or sockets and reading from them. The idea behind them is the
same as in most other programming languages: first you open the
resource with a call to @code{open} which returns a @dfn{descriptor}
i.e. an integer number uniquely identifying the resource. Then you
can write or read from it using this descriptor. Finally, when the
resource is no longer needed, you can close it with a call to
@code{close}.
The number of available resource descriptors is limited. The
default limit is @value{MAX_IOSTREAMS}. You can tailor it to your needs
using the @code{max-streams} runtime configuration statement.
@xref{conf-runtime, max-streams}, for a detailed description.
@anchor{open}
@deftypefn {Built-in Function} number open (string @var{name})
The @var{name} argument specifies the name of a resource to open and
the access rights you need to have on it. The function returns a
descriptor of the opened stream, which can subsequently be used
as an argument to other @acronym{I/O} operations.
First symbols of @var{name} determine the type of the resource to be
opened and the access mode:
@table @samp
@item >
The rest of @var{name} is a name of a file. Open the file for
read-write access. If the file exists, truncate it to zero length,
otherwise create the file.
@item >>
The rest of @var{name} is a name of a file. Open the file for
appending (writing at end of file). The file is created if it does
not exist.
@item |
Treat the rest of @var{name} as the command name and its arguments.
Run this command and open its standard input for writing. The standard
error is closed before launching the program. This can be altered by
using the following versions of this construct:
@table @asis
@item |2>null: @var{command}
Standard error is redirected to @file{/dev/null}.
@item |2>file:@var{name} @var{command}
Execute @var{command} with its standard error redirected to the file
@var{name}. If the file exists, it will be truncated.
@item |2>>file:@var{name} @var{command}
Standard error of the @var{command} is appended to the file
@var{name}. If file does not exist, it will be created.
The @samp{|2>null:} construct described above is a shortcut for
@example
|2>>file:/dev/null @var{command}
@end example
@item |2>syslog:@var{facility}[.@var{priority}] @var{command}
Standard error is redirected to the given syslog @var{facility} and,
optionally, @var{priority}. If the latter is omitted, @samp{LOG_ERR}
is assumed.
Valid values for @var{facility} are: @samp{user}, @samp{daemon},
@samp{auth}, @samp{authpriv}, @samp{mail}, and @samp{local0}
through @samp{local7}. Valid values for @var{priority} are:
@samp{emerg}, @samp{alert}, @samp{crit}, @samp{err}, @samp{warning},
@samp{notice}, @samp{info}, @samp{debug}. Both @var{facility} and
@var{priority} may be given in upper, lower or
mixed cases.
@end table
Notice, that no whitespace characters are allowed between @samp{|} and
@samp{2>}.
@item |<
Treat the rest of @var{name} as the command name and its arguments.
Run this command with its stdin closed and stdout open for reading.
The standard error is treated as described above (see @samp{|}).
@item |&
Treat the rest of @var{name} as the command name and its arguments.
Run this command and set up for two-way communication with it, i.e
writes to the descriptor returned by @code{open} will send data to the
program's standard input, reads from the descriptor will get data from
the program's standard output.
The standard error is treated as described above (see
@samp{|}). For example, the following redirects it to
syslog @samp{mail.debug}:
@example
|&2>syslog:mail.debug @var{command}
@end example
@item @@
Treat the rest of @var{name} as the @acronym{URL} of a socket to
connect to. Valid @acronym{URL} forms are described in @ref{milter
port specification}.
@end table
If none of these prefixes is used, @var{name} is treated as a name
of an existing file and @code{open} will attempt to open this file for
reading.
The @code{open} function will signal exception @code{e_failure} if it
is unable to open the resource or get the required access to it.
@end deftypefn
@deftypefn {Built-in Function} number spawn (string @var{cmd} [, @
number @var{in}, number @var{out}, number @var{err}])
Runs the supplied command @var{cmd}. The syntax of the @var{cmd} is
the same as for the @var{name} argument to @code{open} (see above),
which begins with @samp{|}, excepting that the @samp{|} sign is
optional. That is:
@example
spawn("/bin/cat")
@end example
@noindent
has exactly the same effect as
@example
open("|/bin/cat")
@end example
Optional arguments specify file stream descriptors to be used for the
program standard input, output and error streams, correspondingly.
If supplied, these should be the values returned by a previous call to
@code{open} or @code{tempfile}. The value @samp{-1} means no
redirection.
The example below starts the @code{awk} program with a simple
expression as its argument and redirects the content of the
file @file{/etc/passwd} to its standard input. The returned
stream descriptor is bound to the command's standard output
(see the description of @samp{|<} prefix above). The standard
error is closed:
@example
number fd spawn("<awk -F: '@{print $1@}'", open("/etc/passwd"))
@end example
@end deftypefn
@deftypefn {Built-in Function} void close (number @var{rd})
The argument @var{rd} is a resource descriptor returned by a
previous call to @code{open}. The function @code{close} closes the
resource and deallocates any memory associated with it.
@code{close} will signal @code{e_range} exception if @var{rd} lies
outside of allowed range of resource descriptors. @xref{conf-runtime,
max-streams}.
@end deftypefn
Notice that you are not required to close resources opened by @code{open}.
Any unclosed resource will be closed automatically upon the
termination of the filtering program.
@deftypefn {Built-in Function} void shutdown (number @var{rd}, number @var{how})
This function causes all or part of a full-duplex connection to be
closed. The @var{rd} must be either a socket descriptor (returned by
@code{open(@@...)}) or a two-way pipe socket descriptor (returned by
@code{open(|&...)}), otherwise the call to @code{shutdown} is
completely equivalent to @code{close}.
The @code{how} argument identifies which part of the connection to
shut down:
@table @asis
@kwindex SHUT_RD
@item SHUT_RD
Read connection. All further receptions will be disallowed.
@kwindex SHUT_WR
@item SHUT_WR
Write connection. All further transmissions will be disallowed.
@kwindex SHUT_RDWR
@item SHUT_RDWR
Shut down both read and write parts.
@end table
@end deftypefn
@deftypefn {Built-in Function} number tempfile ([string @var{tmpdir}])
Creates a nameless temporary file and returns its descriptor.
Optional @var{tmpdir} supplies the directory where to create the file,
instead of the default @file{/tmp}.
@end deftypefn
@deftypefn {Built-in Function} void rewind (number @var{rd})
Rewinds the stream identified by @var{rd} to its beginning.
@end deftypefn
@deftypefn {Built-in Function} number copy (number @var{dst}, number @var{src})
Copies all data from the stream @var{src} to @var{dst}. Returns
number of bytes copied.
@end deftypefn
The following functions provide basic read/write capabilities.
@deftypefn {Built-in Function} void write (number @var{rd}, string @var{str} @
[, number @var{size}])
Writes the string @var{str} to the resource descriptor @var{rd}. If
the @var{size} argument is given, writes this number of bytes.
The function will signal @code{e_range} exception if @var{rd} lies
outside of allowed range of resource descriptors, and @code{e_io}
exception if an @acronym{I/O} error occurs.
@end deftypefn
@deftypefn {Built-in Function} void write_body (number @var{rd}, pointer @var{bp
} @
, number @var{size})
Write the body segment of length @var{size} from pointer @var{bp} to
the stream @var{rd}. This function can be used only in @code{prog
body} (@pxref{body handler}). Its second and third arguments
correspond exactly to the parameters of the @code{body} handler, so
the following construct writes the message body to the resource
@code{fd}, which should have been open prior to invoking the
@code{body} handler:
@example
@group
prog body
do
write_body(fd, $1, $2)
done
@end group
@end example
@end deftypefn
@deftypefn {Built-in Function} string read (number @var{rd}, number @var{n})
Read and return @var{n} bytes from the resource descriptor @var{rd}.
The function may signal the following exceptions:
@table @asis
@item e_range
@var{rd} lies outside of allowed range of resource descriptors.
@item e_eof
End of file encountered.
@item e_io
An @acronym{I/O} error occurred.
@end table
@end deftypefn
@deftypefn {Built-in Function} string getdelim (number @var{rd}, string @var{del
im})
Read and return the next string terminated by @var{delim} from the
resource descriptor @var{rd}.
The terminating @var{delim} string will be removed from the return
value.
The function may signal the following exceptions:
@table @asis
@item e_range
@var{rd} lies outside of allowed range of resource descriptors.
@item e_eof
End of file encountered.
@item e_io
An @acronym{I/O} error occurred.
@end table
@end deftypefn
@deftypefn {Built-in Function} string getline (number @var{rd})
Read and return the next @dfn{line} from the resource
descriptor @var{rd}. A line is any sequence of characters terminated
with the default @dfn{line delimiter}. The default delimiter is
a property of @var{rd}, i.e. different descriptors can have different
line delimiters. The default value is @samp{\n} (ASCII 10), and can
be changed using the @code{fd_set_delimiter} function (see below).
The function may signal the following exceptions:
@table @asis
@item e_range
@var{rd} lies outside of allowed range of resource descriptors.
@item e_eof
End of file encountered.
@item e_io
An @acronym{I/O} error occurred.
@end table
@end deftypefn
@deftypefn {Built-in Function} void fd_set_delimiter (number @var{fd}, @
string @var{delim})
Set new line delimiter for the descriptor @var{fd}, which must be in
opened state.
Default delimiter is a newline character (ASCII 10). The following
example shows how to change it to CRLF sequence:
@example
fd_set_delimiter(fd, "\r\n")
@end example
@end deftypefn
@deftypefn {Built-in Function} string fd_delimiter (number @var{fd})
Returns the line delimiter string for @var{fd}.
@end deftypefn
The following example shows how @command{mailfromd} @acronym{I/O} functions can
be used to automatically add @acronym{IP} addresses to an @acronym{RBL} zone:
@example
@group
set nsupdate_cmd
"/usr/bin/nsupdate -k /etc/bind/Kmail.+157+14657.private"
func block_address(string addr)
do
number fd
string domain
set fd open "|%nsupdate_cmd"
set domain revip(addr) . ".rbl.myzone.come"
write(fd, "prereq nxrrset %domain A\n"
"update add %domain 86400 A %addr\n\n"
done
@end group
@end example
@noindent
The function @code{revip} is defined in @ref{revip}.
@node System functions @node System functions
@section System functions @section System functions
@deftypefn {Built-in Function} boolean access (string @var{pathname}, @ @deftypefn {Built-in Function} boolean access (string @var{pathname}, @
number @var{mode}) number @var{mode})
Checks whether the calling process can access the file @var{pathname}. Checks whether the calling process can access the file @var{pathname}.
If @var{pathname} is a symbolic link, it is dereferenced. The If @var{pathname} is a symbolic link, it is dereferenced. The
function returns @samp{True} if the file can be accessed and function returns @samp{True} if the file can be accessed and
@samp{False} otherwise@footnote{@emph{Note}, that the return code is @samp{False} otherwise@footnote{@emph{Note}, that the return code is
inverted in respect to the system function @samp{access(2)}.}. inverted in respect to the system function @samp{access(2)}.}.
 End of changes. 7 change blocks. 
341 lines changed or deleted 543 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)