man: dbfp.3: add man page for dbfp, dbfp_init, dbfp_close

1 files changed, 75 insertions, 0 deletions

diff --git a/man/dbfp.3 b/man/dbfp.3
new file mode 100644
index 0000000..968ef0e
--- /dev/null
+++ b/man/dbfp.3
@@ -0,0 +1,75 @@
+.TH DBFP 3 2016-03-08 dbfp "DB timetable API"
+.SH NAME
+dbfp, dbfp_init, dbfp_close \- handle metadata for connections to the DB timetable API
+.SH SYNOPSIS
+.HP
+.B #include <dbfp.h>
+.HP
+.B struct dbfp {
+.RS
+.B char *key;
+.RE
+.B };
+.HP
+.B int dbfp_init(struct dbfp *dbfp, char *key);
+.HP
+.B void dbfp_close(struct dbfp *dbfp);
+.SH DESCRIPTION
+.B dbfp
+stores the metadata for connections to the DB timetable API.
+.B key
+is the API key used for API queries.
+.PP
+.B dbfp_init
+initializes a dbfp structure and sets the API key to the given value.  dbfp and
+key may not be NULL.  dbfp must already be allocated. The key is copied to the
+dbfp structure.  Every structure that was initialized with this function must
+be closed with dbfp_close.
+.PP
+.B dbfp_close
+closes a dbfp structure and releases its allocated resources.  dbfp itself is
+not freed.  If dbfp is NULL, the function returns.  You should call dbfp_close
+for all dbfp structures.  You have to call it for all dbfp structures
+initialized with dbfp_init.  
+.SH RETURN VALUE
+.B dbfp_init
+returns zero if successful, or an error code if an error occured.
+.SH ERRORS
+EINVAL
+.RS
+if one of the arguments of dbfp_init is NULL
+.RE
+ENOMEM
+.RS
+if there is not enough memory to copy the key in dbfp_init
+.RE
+.SH EXAMPLE
+#include <dbfp.h>
+.br
+#include <stdio.h>
+.br
+#include <string.h>
+.PP
+int main(int argc, char *argv)
+.br
+{
+.RS
+struct dbfp dbfp;
+.br
+int err;
+.PP
+err = dbfp_init(&dbfp, "API key");
+.br
+if (!err)
+.RS
+printf("DBFP structure created.\\n");
+.RE
+else
+.RS
+printf("Could not create DBFP: %s\\n", strerror(err));
+.RE
+dbfp_close(&dbfp);
+.PP
+return 0;
+.RE
+}