Add API manual page.

3 files changed, 174 insertions, 21 deletions

diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am
index 07da8fa..117d12b 100644
--- a/doc/man/Makefile.am
+++ b/doc/man/Makefile.am
@@ -1,10 +1,10 @@
-dist_man_MANS = pwmake.1 pwscore.1 pwquality.conf.5
+dist_man_MANS = pwmake.1 pwscore.1 pwquality.conf.5 pwquality.3
 
 if HAVE_PAM
 dist_man_MANS += pam_pwquality.8
 endif
 
-EXTRA_DIST=pam_pwquality.8.pod pwmake.1.pod pwscore.1.pod pwquality.conf.5.pod
+EXTRA_DIST=pam_pwquality.8.pod pwmake.1.pod pwscore.1.pod pwquality.conf.5.pod pwquality.3.pod
 
 %.8: %.8.pod
 	bash -c 'declare -u ucname=$*; pod2man --utf8 --name="$$ucname" --section=8 --center="Linux-PAM Manual" --release="Red Hat, Inc." $< $@'
@@ -15,5 +15,8 @@ EXTRA_DIST=pam_pwquality.8.pod pwmake.1.pod pwscore.1.pod pwquality.conf.5.pod
 %.5: %.5.pod
 	bash -c 'declare -u ucname=$*; pod2man --utf8 --name="$$ucname" --section=5 --center="File Formats Manual" --release="Red Hat, Inc." $< $@'
 
+%.3: %.3.pod
+	bash -c 'declare -u ucname=$*; pod2man --utf8 --name="$$ucname" --section=5 --center="Libpwquality API Manual" --release="Red Hat, Inc." $< $@'
+
 manclean:
-	rm *.8 *.1 *.5
+	rm *.8 *.1 *.5 *.3
diff --git a/doc/man/pwquality.3.pod b/doc/man/pwquality.3.pod
new file mode 100644
index 0000000..79e97a3
--- /dev/null
+++ b/doc/man/pwquality.3.pod
@@ -0,0 +1,133 @@
+=pod
+
+=head1 NAME
+
+pwquality - Documentation of the libpwquality API
+
+=head1 SYNOPSIS
+
+ #include <pwquality.h>
+
+ pwquality_settings_t *pwquality_default_settings(void);
+ void pwquality_free_settings(pwquality_settings_t *pwq);
+
+ int pwquality_read_config(pwquality_settings_t *pwq, const char *cfgfile,
+        void **auxerror);
+
+ int pwquality_set_option(pwquality_settings_t *pwq, const char *option);
+ int pwquality_set_int_value(pwquality_settings_t *pwq, int setting, int value);
+ int pwquality_set_str_value(pwquality_settings_t *pwq, int setting,
+        const char *value);
+ int pwquality_get_int_value(pwquality_settings_t *pwq, int setting, int *value);
+ int pwquality_get_str_value(pwquality_settings_t *pwq, int setting, const char **value);
+
+ int pwquality_generate(pwquality_settings_t *pwq, int entropy_bits,
+        char **password);
+
+ int pwquality_check(pwquality_settings_t *pwq, const char *password,
+        const char *oldpassword, const char *user, void **auxerror);
+
+ const char *pwquality_strerror(char *buf, size_t len, int errcode, void *auxerror);
+
+=head1 DESCRIPTION
+
+Function I<pwquality_default_settings()> allocates and returns default pwquality settings
+to be used in other library calls. The allocated opaque structure has to be freed
+with the I<pwquality_free_settings()> call.
+
+The I<pwquality_read_config()> parses the configuration file (if B<cfgfile> is NULL
+then the default one). If B<auxerror> is not NULL it also possibly returns auxiliary
+error information that must be passed into I<pwquality_strerror()> function.
+
+=over 4
+
+=item B<New in 1.3.0:>
+
+The library first tries to parse all F<*.conf> configuration files from
+F<< <cfgfile>.d >> directory if it exists. Order of parsing determines what values will
+be in effect - the latest wins.
+
+=back
+
+Function I<pwquality_set_option()> is useful for setting the options as configured
+on a pam module command line in form of <opt>=<val>.
+
+Getter and setter functions for the individual integer and string setting values are:
+I<pwquality_set_int_value()>, I<pwquality_set_str_value()>,
+I<pwquality_get_int_value()>, and I<pwquality_get_str_value()>. In case of the
+string getter the caller must copy the string before another calls that can
+manipulate the B<pwq> settings object.
+
+The I<pwquality_generate()> function generates a random password of B<entropy_bits> entropy
+and check it according to the settings. The B<*password> is allocated on heap by the
+library.
+
+The I<pwquality_check()> function checks the B<password> according to the settings. It
+returns either score <0-100>, negative error number, and possibly also auxiliary error
+information that must be passed into I<pwquality_strerror()> function.
+The B<oldpassword> is optional and can be NULL.
+The B<user> is used for checking the B<password> against the user name
+and potentially other L<passwd(5)> information and can be NULL.
+The B<auxerror> can be NULL - in that case the auxiliary error information
+is not returned.
+However if it is non-NULL not passing the returned B<*auxerror> into
+I<pwquality_strerror()> can lead to memory leaks.
+The score depends on value of the setting B<PWQ_SETTING_MIN_LENGTH>. If it is
+set higher, the score for the same passwords will be lower.
+
+Function I<pwquality_strerror()> translates the B<errcode> and B<auxerror> auxiliary
+data into localized text message. If B<buf> is NULL the function uses an internal static
+buffer which makes the function non-reentrant in that case. The returned pointer is not
+guaranteed to point to the B<buf>.
+
+=head1 RETURN VALUES
+
+In general the functions which return B<int> return 0 as success value and negative values
+as concrete B<PWQ_ERROR> error code. I<pwquality_strerror()> does not allocate data
+and so it cannot fail.
+
+The returned positive or zero score from I<pwquality_check()> should not be used for
+rejection of passwords, it should be used only as approximate indicator of entropy present
+in the password with values such as 0-30 being low, 30-60 medium, and 60-100 high.
+
+=head1 EXAMPLE
+
+Typical use of the libpwquality API:
+
+ #include <pwquality.h>
+ 
+ ...
+
+        pwquality_settings_t *pwq;
+        int rv;
+        void *auxerror;
+        char buf[1024];
+
+        pwq = pwquality_default_settings();
+        if (pwq == NULL) {
+                fprintf(stderr, "Error: %s\n", pwquality_strerror(buf, sizeof(buf), PWQ_ERROR_MEM_ALLOC, NULL));
+                return -1;
+        }
+ 
+        if ((rv=pwquality_read_config(pwq, NULL, &auxerror)) != 0) {
+                pwquality_free_settings(pwq);
+                fprintf(stderr, "Error: %s\n", pwquality_strerror(buf, sizeof(buf), rv, auxerror));
+                return -1;
+        }
+ 
+        rv = pwquality_check(pwq, buf, NULL, user, &auxerror);
+        pwquality_free_settings(pwq);
+
+        if (rv >= 0) {
+                fprintf(stderr, "Password entropy score is: %d\n", rv);
+        } else {
+                fprintf(stderr, "Password is rejected with error: %s\n", pwquality_strerror(buf, sizeof(buf), rv, auxerror));
+        }
+
+=head1 SEE ALSO
+
+L<pwquality.conf(5)>
+
+=head1 AUTHORS
+
+Tomas Mraz <tmraz@redhat.com>
diff --git a/po/es.po b/po/es.po
index 358e2a8..61a4450 100644
--- a/po/es.po
+++ b/po/es.po
@@ -1,7 +1,7 @@
 # SOME DESCRIPTIVE TITLE.
 # Copyright (C) YEAR libpwquality project
 # This file is distributed under the same license as the PACKAGE package.
-# 
+#
 # Translators:
 # Adolfo Jayme Barrientos, 2015
 # Claudio Rodrigo Pereyra Diaz <elsupergomez@gmail.com>, 2011
@@ -16,11 +16,12 @@ msgstr ""
 "POT-Creation-Date: 2014-08-06 16:45+0200\n"
 "PO-Revision-Date: 2015-02-01 00:56+0000\n"
 "Last-Translator: Adolfo Jayme Barrientos\n"
-"Language-Team: Spanish (http://www.transifex.com/projects/p/libpwquality/language/es/)\n"
+"Language-Team: Spanish (http://www.transifex.com/projects/p/libpwquality/"
+"language/es/)\n"
+"Language: es\n"
 "MIME-Version: 1.0\n"
 "Content-Type: text/plain; charset=UTF-8\n"
 "Content-Transfer-Encoding: 8bit\n"
-"Language: es\n"
 "Plural-Forms: nplurals=2; plural=(n != 1);\n"
 
 #: src/pam_pwquality.c:25
@@ -50,9 +51,10 @@ msgstr "Uso: %s [usuario]\n"
 #: src/pwscore.c:23
 #, c-format
 msgid ""
-"       The command reads the password to be scored from the standard "
-"input.\n"
-msgstr "       La orden lee la contraseña que se valorará a partir de la entrada estándar.\n"
+"       The command reads the password to be scored from the standard input.\n"
+msgstr ""
+"       La orden lee la contraseña que se valorará a partir de la entrada "
+"estándar.\n"
 
 #: src/pwscore.c:51 src/pwscore.c:59 src/pwscore.c:65
 #, c-format
@@ -68,7 +70,9 @@ msgstr "No se pudo obtener la contraseña que se valorará"
 msgid ""
 "Password quality check failed:\n"
 " %s\n"
-msgstr "Falló la comprobación de calidad de la contraseña:\n %s\n"
+msgstr ""
+"Falló la comprobación de calidad de la contraseña:\n"
+" %s\n"
 
 #: src/pwmake.c:22
 #, c-format
@@ -104,9 +108,10 @@ msgid "The password contains the user name in some form"
 msgstr "De alguna manera, en la contraseña se lee el nombre del usuario "
 
 #: src/error.c:47
-msgid ""
-"The password contains words from the real name of the user in some form"
-msgstr "De alguna manera, en la contraseña existen palabras del nombre real del usuario"
+msgid "The password contains words from the real name of the user in some form"
+msgstr ""
+"De alguna manera, en la contraseña existen palabras del nombre real del "
+"usuario"
 
 #: src/error.c:49
 msgid "The password contains forbidden words in some form"
@@ -168,37 +173,47 @@ msgstr "La contraseña contiene menos de %ld clases de caracteres"
 
 #: src/error.c:87
 msgid "The password does not contain enough character classes"
-msgstr "La contraseña no contiene la suficiente cantidad de clases de caracteres"
+msgstr ""
+"La contraseña no contiene la suficiente cantidad de clases de caracteres"
 
 #: src/error.c:90
 #, c-format
 msgid "The password contains more than %ld same characters consecutively"
-msgstr "La contraseña contiene más de %ld caracteres iguales en forma consecutiva"
+msgstr ""
+"La contraseña contiene más de %ld caracteres iguales en forma consecutiva"
 
 #: src/error.c:93
 msgid "The password contains too many same characters consecutively"
-msgstr "La contraseña contiene en forma consecutiva demasiados caracteres iguales"
+msgstr ""
+"La contraseña contiene en forma consecutiva demasiados caracteres iguales"
 
 #: src/error.c:96
 #, c-format
 msgid ""
 "The password contains more than %ld characters of the same class "
 "consecutively"
-msgstr "La contraseña contiene m ás de %ld caracteres de la misma clase en forma consecutiva"
+msgstr ""
+"La contraseña contiene m ás de %ld caracteres de la misma clase en forma "
+"consecutiva"
 
 #: src/error.c:99
 msgid ""
 "The password contains too many characters of the same class consecutively"
-msgstr "La contraseña contiene en forma consecutiva demasiados caracteres de la misma clase"
+msgstr ""
+"La contraseña contiene en forma consecutiva demasiados caracteres de la "
+"misma clase"
 
 #: src/error.c:102
 #, c-format
 msgid "The password contains monotonic sequence longer than %ld characters"
-msgstr "La contraseña contiene una secuencia monotónica mayor de %ld caracteres"
+msgstr ""
+"La contraseña contiene una secuencia monotónica mayor de %ld caracteres"
 
 #: src/error.c:105
 msgid "The password contains too long of a monotonic character sequence"
-msgstr "La contraseña contiene una secuencia de caracteres monotónica demasiado extensa"
+msgstr ""
+"La contraseña contiene una secuencia de caracteres monotónica demasiado "
+"extensa"
 
 #: src/error.c:107
 msgid "No password supplied"
@@ -210,7 +225,9 @@ msgstr "No es posible obtener números aleatorios desde el dispositivo RNG"
 
 #: src/error.c:111
 msgid "Password generation failed - required entropy too low for settings"
-msgstr "Falló la creación de la contraseña - es necesaria una entropía demasiado pequeña para las configuraciones"
+msgstr ""
+"Falló la creación de la contraseña - es necesaria una entropía demasiado "
+"pequeña para las configuraciones"
 
 #: src/error.c:114 src/error.c:117
 msgid "The password fails the dictionary check"