ossp-pkg/lmtp2nntp/lmtp.pod
1.1
##
## lmtp.pod: LMTP library (Unix manual page)
##
## Copyright (c) 2001 The OSSP Project (http://www.ossp.org/)
## Copyright (c) 2001 Cable & Wireless Deutschland (http://www.cw.com/de/)
##
## This file is part of OSSP lmtp2nntp, an LMTP speaking local
## mailer which forwards mails as Usenet news articles via NNTP.
## It can be found at http://www.ossp.com/pkg/lmtp2nntp/.
##
## Permission to use, copy, modify, and distribute this software for
## any purpose with or without fee is hereby granted, provided that
## the above copyright notice and this permission notice appear in all
## copies.
##
## THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
## WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
## MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
## IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
## CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
## USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
## ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
## OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
## OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
## SUCH DAMAGE.
##
=pod
=head1 NAME
B<lmtp> - Local Mail Transfer Protocol (LMTP) Library
=head1 SYNOPSIS
=over 4
=item Headers:
B<lmtp.h>.
=item Types:
B<lmtp_t>,
B<lmtp_io_t>,
B<lmtp_req_t>,
B<lmtp_res_t>,
B<lmtp_rc_t>,
B<lmtp_cb_t>.
=item Functions:
B<lmtp_create>,
B<lmtp_destroy>,
B<lmtp_readline>,
B<lmtp_readmsg>,
B<lmtp_request>,
B<lmtp_response>,
B<lmtp_error>,
B<lmtp_register>,
B<lmtp_loop>.
=item Return Codes:
B<LMTP_OK>,
B<LMTP_EOF>,
B<LMTP_ERR_SYSTEM>,
B<LMTP_ERR_MEM>,
B<LMTP_ERR_OVERFLOW>,
B<LMTP_ERR_ARG>,
B<LMTP_ERR_UNKNOWN>.
=back
=head1 DESCRIPTION
This library provides a generic framework for implementing the Local Mail
Transport Protocol (LMTP) in a server application.
The following data types are declared:
=over 4
=item B<lmtp_t>
This is the opaque data type which forms the LMTP session handle.
It is passed through every API function as its context.
=item B<lmtp_io_t>
This is a simple I/O structure which can be passed to ltmp_create(3) in
order override the underlying I/O routines used by the LMTP library.
It contains the following two attributes which match the prototype of
read(2) and write(2).
ssize_t (*read)(int, void *, size_t);
ssize_t (*write)(int, const void *, size_t);
=item B<lmtp_req_t>
This is a simple Request structure.
It contains the following two attributes:
char *verb; /* LMTP request verb */
char *msg; /* LMTP request message (whole line) */
=item B<lmtp_res_t>
...
char *statuscode; /* digit digit digit NUL */
char *dsncode; /* digit dot digit dot digit NUL */
char *statusmsg; /* message with >=0*NLs, not terminating with NL. NUL */
=item B<lmtp_rc_t>
...
LMTP_OK
LMTP_EOF /* eof */
LMTP_ERR_SYSTEM /* see errno */
LMTP_ERR_MEM /* dynamic memory allocation failed */
LMTP_ERR_OVERFLOW /* static allocated memory exhausted */
LMTP_ERR_ARG /* invalid arg was passed to function */
LMTP_ERR_UNKNOWN /* guru meditation */
=item B<lmtp_cb_t>
...
lmtp_rc_t (*B<lmtp_cb_t>)(lmtp_t *I<lmtp>, lmtp_io_t *I<io>, lmtp_req_t
*I<req>, void *I<ctx>);
=back
The following API functions are provided:
=item lmtp_t *B<lmtp_create>(int I<rfd>, int I<wfd>, lmtp_io_t *I<io>);
...
=item void B<lmtp_destroy>(lmtp_t *I<lmtp>);
...
=item lmtp_rc_t B<lmtp_readline>(lmtp_t *I<lmtp>, char *I<buf>, size_t I<buflen>);
...
=item lmtp_rc_t B<lmtp_readmsg>(lmtp_t *I<lmtp>, char **I<buf>, size_t I<maxlen>);
...
=item lmtp_rc_t B<lmtp_request>(lmtp_t *I<lmtp>, lmtp_req_t *I<req>);
...
=item lmtp_rc_t B<lmtp_response>(lmtp_t *I<lmtp>, lmtp_res_t *I<res>);
...
=item char *B<lmtp_error>(lmtp_t *I<lmtp>, lmtp_rc_t I<rc>);
...
=item lmtp_rc_t B<lmtp_register>(lmtp_t *I<lmtp>, char *I<verb>, lmtp_cb_t I<cb>, void *I<ctx>, lmtp_cb_t *I<oldcb>, void **I<oldctx>);
...
=item lmtp_rc_t B<lmtp_loop>(lmtp_t *I<lmtp>);
...
=back
=head1 EXAMPLE
...
=head1 STANDARDS
RFC 2033: Local Mail Transfer Protocol (SMTP)
RFC 821, STD 90: Simple Mail Transfer Protocol (SMTP)
RFC 1891: Delivery Status Notification (DSN)
RFC 2920: SMTP Service Extension for Command Pipelining
=head1 AUTHORS
Thomas Lotterer
thomas.lotterer@cw.com
Cable & Wireless Deutschland GmbH
Ralf S. Engelschall
ralf.engelschall@cw.com
Cable & Wireless Deutschland GmbH
=cut
