man: Add pages for top level functions

Signed-off-by: Michael Tremer <michael.tremer@ipfire.org>

diff --git a/Makefile.am b/Makefile.am
index c1185b197efb19ed30d5291d7dcffeb1acd7d678..92c09d7a7f1d1287297a84e04cd6ce7df3f04c03 100644 (file)
--- a/Makefile.am
+++ b/Makefile.am
@@ -420,11 +420,18 @@ src_test_signature_LDADD = \
 # ------------------------------------------------------------------------------
 
 MANPAGES = \
-       man/location.8
-
-MANPAGES_TXT  = $(patsubst %.8,%.txt,$(MANPAGES))
-MANPAGES_HTML = $(patsubst %.txt,%.html,$(MANPAGES_TXT))
-MANPAGES_XML  = $(patsubst %.txt,%.xml,$(MANPAGES_TXT))
+       man/libloc.3 \
+       man/location.8 \
+       man/loc_get_log_priority.3 \
+       man/loc_new.3 \
+       man/loc_set_log_fn.3 \
+       man/loc_set_log_priority.3
+
+MANPAGES_TXT   = $(MANPAGES_TXT_3) $(MANPAGES_TXT_8)
+MANPAGES_TXT_3 = $(patsubst %.3,%.txt,$(MANPAGES))
+MANPAGES_TXT_8 = $(patsubst %.8,%.txt,$(MANPAGES))
+MANPAGES_HTML  = $(patsubst %.txt,%.html,$(MANPAGES_TXT))
+MANPAGES_XML   = $(patsubst %.txt,%.xml,$(MANPAGES_TXT))
 
 .PHONY: man
 man: $(MANPAGES) $(MANPAGES_HTML)
@@ -467,6 +474,9 @@ man/%.xml: man/%.txt man/asciidoc.conf
                -f $(abs_srcdir)/man/asciidoc.conf \
                -d manpage -b docbook -o $@ $<
 
+man/%.3: man/%.xml
+       $(XSLTPROC_COMMAND_MAN)
+
 man/%.8: man/%.xml
        $(XSLTPROC_COMMAND_MAN)
 

diff --git a/man/libloc.txt b/man/libloc.txt
new file mode 100644 (file)
index 0000000..fb031e7
--- /dev/null
+++ b/man/libloc.txt
@@ -0,0 +1,46 @@
+= libloc(3)
+
+== Name
+
+libloc - A tool to query the IPFire Location database
+
+== Synopsis
+[verse]
+
+#include <libloc/libloc.h>
+
+`pkg-config --cflags --libs libloc`
+
+== Description
+
+`libloc` is a lightweight library which can be used to query the IPFire
+Location database.
+
+See
+
+       * link:loc_new[3]
+       * link:loc_get_log_priority[3]
+       * link:loc_set_log_priority[3]
+       * link:loc_get_log_fn[3]
+
+for more information about the functions available.
+
+== Copying
+
+Copyright (C) 2022 {author}. +
+This library is free software; you can redistribute it and/or modify it under the terms
+of the GNU Lesser General Public License as published by the Free Software Foundation;
+either version 2.1 of the License, or (at your option) any later version.
+
+== See Also
+
+link:location[8]
+
+== Bug Reports
+
+Please report all bugs to the bugtracker at https://bugzilla.ipfire.org/;
+refer to https://wiki.ipfire.org/devel/bugzilla for details.
+
+== Authors
+
+Michael Tremer

diff --git a/man/loc_get_log_priority.txt b/man/loc_get_log_priority.txt
new file mode 100644 (file)
index 0000000..447a8c8
--- /dev/null
+++ b/man/loc_get_log_priority.txt
@@ -0,0 +1,28 @@
+= loc_get_log_priority(3)
+
+== Name
+
+loc_get_log_priority - Fetches the log level of a libloc context
+
+== Synopsis
+[verse]
+
+#include <libloc/libloc.h>
+
+int loc_get_log_priority(struct loc_ctx{empty}* ctx);
+
+== Description
+
+Returns the log priority of the given context.
+
+The returned integer is a valid syslog log level as defined in syslog(3).
+
+The default value is LOG_ERR.
+
+== See Also
+
+link:libloc[3]
+
+== Authors
+
+Michael Tremer

diff --git a/man/loc_new.txt b/man/loc_new.txt
new file mode 100644 (file)
index 0000000..c1000be
--- /dev/null
+++ b/man/loc_new.txt
@@ -0,0 +1,35 @@
+= loc_new(3)
+
+== Name
+
+loc_new - Create a new libloc context
+
+== Synopsis
+[verse]
+
+#include <libloc/libloc.h>
+
+struct loc_ctx;
+
+int loc_new(struct loc_ctx{empty}*{empty}* ctx);
+
+struct loc_ctx{empty}* loc_ref(struct loc_ctx{empty}* ctx);
+
+struct loc_ctx{empty}* loc_unref(struct loc_ctx{empty}* ctx);
+
+== Description
+
+Every operation in libloc requires to set up a context first.
+This is done by calling loc_new(3).
+
+Every time another part of your code is holding a reference to the context,
+you will need to call loc_ref() to increase the reference counter.
+If you no longer need the context, you will need to call loc_unref().
+
+== See Also
+
+link:libloc[3]
+
+== Authors
+
+Michael Tremer

diff --git a/man/loc_set_log_fn.txt b/man/loc_set_log_fn.txt
new file mode 100644 (file)
index 0000000..00c1854
--- /dev/null
+++ b/man/loc_set_log_fn.txt
@@ -0,0 +1,29 @@
+= loc_set_log_fn(3)
+
+== Name
+
+loc_set_log_fn - Sets the log callback function
+
+== Synopsis
+[verse]
+
+#include <libloc/libloc.h>
+
+void loc_set_log_fn(struct loc_ctx{empty}* ctx,
+       void ({empty}*log_fn)(struct loc_ctx{empty}* ctx, int priority,
+       const char{empty}* file, int line, const char{empty}* fn, const char{empty}* format,
+       va_list args)
+
+== Description
+
+libloc can use the calling application's logging system by setting this callback.
+
+It will be called once for each log message according to the configured log level.
+
+== See Also
+
+link:libloc[3]
+
+== Authors
+
+Michael Tremer

diff --git a/man/loc_set_log_priority.txt b/man/loc_set_log_priority.txt
new file mode 100644 (file)
index 0000000..76556bb
--- /dev/null
+++ b/man/loc_set_log_priority.txt
@@ -0,0 +1,25 @@
+= loc_set_log_priority(3)
+
+== Name
+
+loc_set_log_priority - Sets the log level of a libloc context
+
+== Synopsis
+[verse]
+
+#include <libloc/libloc.h>
+
+void loc_set_log_priority(struct loc_ctx{empty}* ctx, int priority)
+
+== Description
+
+Sets the log priority of the given context. See loc_get_log_priority(3) for more details.
+
+== See Also
+
+link:libloc[3]
+link:loc_set_log_fn(3)
+
+== Authors
+
+Michael Tremer