diff --git a/Makefile.am b/Makefile.am index 0d03238..90406ab 100644 --- a/Makefile.am +++ b/Makefile.am @@ -562,6 +562,7 @@ MANPAGES_3 = \ man/loc_database_new.3 \ man/loc_get_log_priority.3 \ man/loc_new.3 \ + man/loc_set_log_callback.3 \ man/loc_set_log_fn.3 \ man/loc_set_log_priority.3 diff --git a/man/libloc.txt b/man/libloc.txt index ec14e16..7d24ed7 100644 --- a/man/libloc.txt +++ b/man/libloc.txt @@ -2,7 +2,7 @@ == Name -libloc - A tool to query the IPFire Location database +libloc - A library to query the IPFire Location database == Synopsis [verse] @@ -21,7 +21,8 @@ See * link:loc_new[3] * link:loc_get_log_priority[3] * link:loc_set_log_priority[3] - * link:loc_get_log_fn[3] + * link:loc_set_log_fn[3] + * link:loc_set_log_callback[3] * link:loc_database_count_as[3] * link:loc_database_get_as[3] * link:loc_database_get_country[3] @@ -32,7 +33,7 @@ for more information about the functions available. == Copying -Copyright (C) 2022 {author}. + +Copyright (C) 2022 IPFire Development Team. + 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. diff --git a/man/loc_database_get_country.txt b/man/loc_database_get_country.txt index b5ab8ec..a5d7b0c 100644 --- a/man/loc_database_get_country.txt +++ b/man/loc_database_get_country.txt @@ -5,6 +5,7 @@ loc_database_get_country - Fetch country information from the database == Synopsis +[verse] #include diff --git a/man/loc_database_lookup.txt b/man/loc_database_lookup.txt index b6f780a..9039c3e 100644 --- a/man/loc_database_lookup.txt +++ b/man/loc_database_lookup.txt @@ -5,6 +5,7 @@ loc_database_lookup - Lookup a network from the database == Synopsis +[verse] #include @@ -21,7 +22,7 @@ The lookup functions try finding a network in the database. _loc_database_lookup_ takes the IP address as _struct in6_addr_ format which can either be a regular IPv6 address or a mapped IPv4 address. -_loc_database_lookup_string_ takes the IP address as string and will parse it automatically. +_loc_database_lookup_from_string_ takes the IP address as string and will parse it automatically. == Return Value diff --git a/man/loc_database_new.txt b/man/loc_database_new.txt index 86a021b..e640ea3 100644 --- a/man/loc_database_new.txt +++ b/man/loc_database_new.txt @@ -2,7 +2,7 @@ == Name -loc_database_new - Create a new libloc context +loc_database_new - Open a location database == Synopsis [verse] @@ -33,9 +33,9 @@ const char{empty}* loc_database_get_license(struct loc_database{empty}* db); == Description -loc_database_new() opens a new database from the given file descriptor. -The file descriptor can be closed after this operation because the function is creating -its own copy. +loc_database_new() opens a new database from the given file handle. +The file handle can be closed after this operation because the function duplicates +the underlying file descriptor. If the database could be opened successfully, zero is returned. Otherwise a non-zero return code will indicate an error and errno will be set appropriately. diff --git a/man/loc_new.txt b/man/loc_new.txt index c1000be..67003de 100644 --- a/man/loc_new.txt +++ b/man/loc_new.txt @@ -19,7 +19,7 @@ struct loc_ctx{empty}* loc_unref(struct loc_ctx{empty}* ctx); == Description -Every operation in libloc requires to set up a context first. +Every operation in libloc requires a context to be set up first. This is done by calling loc_new(3). Every time another part of your code is holding a reference to the context, diff --git a/man/loc_set_log_callback.txt b/man/loc_set_log_callback.txt new file mode 100644 index 0000000..864b885 --- /dev/null +++ b/man/loc_set_log_callback.txt @@ -0,0 +1,37 @@ += loc_set_log_callback(3) + +== Name + +loc_set_log_callback - Set a callback for log messages + +== Synopsis +[verse] + +#include + +typedef void ({empty}*loc_log_callback)(struct loc_ctx{empty}* ctx, void{empty}* data, + int priority, const char{empty}* file, int line, const char{empty}* fn, + const char{empty}* format, va_list args); + +void loc_set_log_callback(struct loc_ctx{empty}* ctx, loc_log_callback callback, + void{empty}* data); + +== 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 +priority (see link:loc_set_log_priority[3]). + +_data_ is an opaque pointer which is passed through to the callback on every +invocation. + +This function replaces the deprecated link:loc_set_log_fn[3]. + +== See Also + +link:libloc[3] + +== Authors + +Michael Tremer diff --git a/man/loc_set_log_fn.txt b/man/loc_set_log_fn.txt index 00c1854..27da04c 100644 --- a/man/loc_set_log_fn.txt +++ b/man/loc_set_log_fn.txt @@ -12,17 +12,19 @@ loc_set_log_fn - Sets the log callback function 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) + va_list args)); == Description -libloc can use the calling application's logging system by setting this callback. +This function is deprecated and has no effect. -It will be called once for each log message according to the configured log level. +Use link:loc_set_log_callback[3] to send log messages to the calling +application's logging system instead. == See Also link:libloc[3] +link:loc_set_log_callback[3] == Authors diff --git a/man/loc_set_log_priority.txt b/man/loc_set_log_priority.txt index 76556bb..a561994 100644 --- a/man/loc_set_log_priority.txt +++ b/man/loc_set_log_priority.txt @@ -9,7 +9,7 @@ loc_set_log_priority - Sets the log level of a libloc context #include -void loc_set_log_priority(struct loc_ctx{empty}* ctx, int priority) +void loc_set_log_priority(struct loc_ctx{empty}* ctx, int priority); == Description @@ -18,7 +18,7 @@ Sets the log priority of the given context. See loc_get_log_priority(3) for more == See Also link:libloc[3] -link:loc_set_log_fn(3) +link:loc_set_log_fn[3] == Authors diff --git a/man/location.txt b/man/location.txt index 70352d2..b473f6e 100644 --- a/man/location.txt +++ b/man/location.txt @@ -5,12 +5,15 @@ location - Query the location database == SYNOPSIS [verse] -`location export --directory=DIR [--format=FORMAT] [--family=ipv6|ipv4] [ASN|CC ...]` +`location dump [OUTPUT]` +`location export [--directory=DIR] [--format=FORMAT] [--family=ipv6|ipv4] [ASN|CC ...]` +`location export-zone --output=FILE --origin=ORIGIN [--ttl=TTL] [--master=MASTER] [--zonemaster=EMAIL] [--nameserver=NS ...] TYPE` `location get-as ASN [ASN...]` +`location list-bogons [--family=ipv6|ipv4] [--format=FORMAT]` `location list-countries [--show-name] [--show-continent]` -`location list-networks-by-as ASN` -`location list-networks-by-cc COUNTRY_CODE` -`location list-networks-by-flags [--anonymous-proxy|--satellite-provider|--anycast|--drop]` +`location list-networks-by-as [--family=ipv6|ipv4] [--format=FORMAT] ASN` +`location list-networks-by-cc [--family=ipv6|ipv4] [--format=FORMAT] COUNTRY_CODE` +`location list-networks-by-flags [--family=ipv6|ipv4] [--format=FORMAT] [--anonymous-proxy|--satellite-provider|--anycast|--drop]` `location lookup ADDRESS [ADDRESS...]` `location search-as STRING` `location update [--cron=daily|weekly|monthly]` @@ -31,6 +34,14 @@ or countries. + If this option is omitted, the system's database will be opened. +--public-key FILE:: +-k FILE:: + The path of the public key which is used to verify the database + (see 'verify' command). + + + If this option is omitted, the vendor's public key that is shipped + with libloc will be used. + --quiet:: Enable quiet mode @@ -39,6 +50,13 @@ or countries. == COMMANDS +'dump [OUTPUT]':: + This command dumps the entire database as text, preceded by a header + with its metadata (creation time, vendor, license, and description). + + + The output is written to the given file, or to stdout if OUTPUT is + omitted. + 'export [--directory=DIR] [--format=FORMAT] [--family=ipv6|ipv4] [ASN|CC ...]':: This command exports the whole database into the given directory. + @@ -51,6 +69,21 @@ or countries. If the '--directory' option is omitted, the output will be written to stdout which is useful when you want to load any custom exports straight into nftables or ipset. +'export-zone --output=FILE --origin=ORIGIN [--ttl=TTL] [--master=MASTER] [--zonemaster=EMAIL] [--nameserver=NS ...] TYPE':: + This command exports the database as a DNS zone file. + + + TYPE selects which data is being exported: 'asn' (AS names), 'cc' + (country codes of all networks), 'bogons', 'origin' (the AS of each + network), 'prefix', or 'everything'. + + + The zone is written to the file given with '--output' and rooted at + the origin given with '--origin'. Both options are required. + + + The '--ttl', '--master', and '--zonemaster' parameters set the TTL, + the zone master, and the email address of the zone's administrator, + respectively. Nameservers can be added to the zone by passing + '--nameserver' one or more times. + 'get-as ASN [ASN...]':: This command returns the name of the owning organisation of the Autonomous System. @@ -73,7 +106,7 @@ or countries. 'list-networks-by-cc [--family=[ipv6|ipv4]] [--format=FORMAT] COUNTRY_CODE':: Lists all networks that belong to a country. + - The country has to be encoded in ISO3166 Alpha-2 notation. + The country has to be encoded in ISO 3166 Alpha-2 notation. + See above for usage of the '--family' and '--format' parameters. @@ -117,7 +150,7 @@ or countries. Shows a short help text on using this program. '--version':: - Shows the program's version and exists. + Shows the program's version and exits. == EXIT CODES The 'location' command will normally exit with code zero.