L

libemailvalidation

RFC-compliant e-mail validation library written in C

Name Last Update
.gitignore Loading commit data...
COPYING Loading commit data...
Makefile Loading commit data...
README Loading commit data...
grammar-obsolete.abnf Loading commit data...
grammar-utf8.abnf Loading commit data...
grammar.abnf Loading commit data...
test-validate.c Loading commit data...
validate.c Loading commit data...
validate.h Loading commit data...
validator.c Loading commit data...
libemailvalidation
==================

libemailvalidation is a self-contained implementation of the e-mail syntax
specified in various internet RFCs, to allow validation of input strings as
e-mail addresses.

See the documentation in validate.c for an overview of how to use this code,
when it is appropriate to validate an e-mail address formally (using this code),
or informally (for example, simply checking the string contains exactly one ‘@’
symbol and a non-empty component either side).

This is a mostly-unsupported code dump at the moment, with only a basic build
system, and some basic documentation and tests. As it is only a few hundred
lines of code, it is suggested that you import it into your project as as
git submodule or copylib.

Some unit tests are provided in test-validate.c, and some others with
validator.c, courtesy of abnfgen. Use `make check` to run them all.

How do I use this?
==================

Use git submodules, or copy the files, to compile validate.c and validate.h
into your project. To validate an e-mail address, call:

   size_t error_position;

   is_valid = emv_validate_email_address (address_to_check,
                                          length_of_address_to_check,
                                          EMV_VALIDATE_FLAGS_NONE,
                                          &error_position);

   if (!is_valid)
     fprintf (stderr, "Invalid e-mail address; error at byte %zu\n",
              error_position);

See the documentation in validate.c for more details. For examples of using
the API, see test-validate.c and validator.c.

Note: unless deprecated syntax is disabled using the
EMV_VALIDATE_FLAGS_DISABLE_DEPRECATED flag, it is possible for a valid e-mail
address to contain a nul byte. Therefore it is important that input is
handled using explicit string lengths, rather than nul-terminated strings.

References
==========

The implementation is up to date with the following RFCs and their errata as
of September 2016:
 • RFC 3696
 • RFC 5234
 • RFC 5321
 • RFC 5322
 • RFC 6531

Dependencies
============

 • C99
 • abnfgen to generate the test cases

Why not use a parser generator?
-------------------------------

There is only one parser generator for ABNF: apg
(http://www.coasttocoastresearch.com/). It does not generate the parser code;
it requires linking the parser against libapg, which is a bit of a pain.

Validation of e-mail addresses, as opposed to parsing them, does not require
a full parser, since an abstract syntax tree does not need to be produced as
the result.

However, using the same ABNF rules as defined in the RFCs to generate the
parser would significantly increase confidence in the implementation of the
library. Instead, we have to rely on testing.

Licensing
=========

libemailvalidation is licensed under the LGPL; see COPYING for more details.

The ABNF rules from the RFCs in the .abnf files count as ‘Code Components’
from a licensing point of view, and hence are under a simplified BSD license,
under the copyright of the IETF Trust.

See http://trustee.ietf.org/trust-legal-provisions.html and section 4 of
http://trustee.ietf.org/documents/IETF-TLP-5_001.html.

Contact
=======

Philip Withnall <philip@tecnocode.co.uk>