From c96d948a4b76875c91848518aa2f55f2774a4118 Mon Sep 17 00:00:00 2001
From: Robin Krahl <me@robin-krahl.de>
Date: Mon, 6 Jun 2016 18:20:10 +0200
Subject: dbfp: add man pages for dbfp_init, dbfp_close

---
 man/dbfp_init.pod | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 man/dbfp_init.pod

(limited to 'man/dbfp_init.pod')

diff --git a/man/dbfp_init.pod b/man/dbfp_init.pod
new file mode 100644
index 0000000..8749a2f
--- /dev/null
+++ b/man/dbfp_init.pod
@@ -0,0 +1,78 @@
+=head1 NAME
+
+dbfp_init - initialize the metadata for queries to the DB timetable API
+
+=head1 SYNOPSIS
+
+    #include <dbfp.h>
+
+    int dbfp_init(struct dbfp *dbfp, char *key);
+
+=head1 DESCRIPTION
+
+B<dbfp_init> initializes a I<dbfp> structure that stores the metadata for
+queries to the DB timetable API.  I<key> is the API key to use for the
+connections.  I<dbfp> must already be allocated.  I<dbfp> and I<key> must not
+be NULL.  I<key> is copied to the structure, so it can be changed or freed
+after calling this function.
+
+B<dbfp> is a structure defined as:
+
+    struct dbfp {
+            char *key;
+            CURL *curl;
+    };
+
+The user does not have to deal with the fields of this structure.
+
+I<dbfp> structures initialized with this method should be closed by calling
+B<dbfp_close>.
+
+=head1 RETURN VALUE
+
+B<dbfp_init> returns zero if successful, or a non-zero error code.  Positive
+error codes are from I<errno.h>, negative error codes are specific to dbfp.
+
+=head1 ERRORS
+
+=over
+
+=item EINVAL
+
+if I<dbfp> or I<key> is NULL
+
+=item ENOMEM
+
+if there is not enoguh memory to copy I<key> to I<dbfp>
+
+=item DBFP_ERROR_CURL
+
+if curl could not be initialized
+
+=back
+
+=head1 EXAMPLE
+
+    #include <dbfp.h>
+    #include <stdio.h>
+    #include <stdlib.h>
+    #include <string.h>
+    
+    int main(int argc, char **argv)
+    {
+            struct dbfp dbfp;
+	    int err;
+    
+            err = dbfp_init(&dbfp, "API key");
+            if (!err)
+                    printf("DBFP structure created.\n");
+            else
+                    printf("Could not create DBFP: %s\n", strerror(err));
+            dbfp_close(&dbfp);
+            
+            return err ? EXIT_FAILURE : EXIT_SUCCESS;
+    }
+
+=head1 SEE ALSO
+
+L<dbfp_close(3)>
-- 
cgit v1.2.1