From patchwork Sun Jul 12 08:46:33 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Valters Jansons X-Patchwork-Id: 10035 Return-Path: Received: from mail01.ipfire.org (mail01.haj.ipfire.org [172.28.1.202]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange x25519) (Client CN "mail01.haj.ipfire.org", Issuer "YR2" (not verified)) by web04.haj.ipfire.org (Postfix) with ESMTPS id 4gyfLv2w6Sz3wb0 for ; Sun, 12 Jul 2026 08:46:47 +0000 (UTC) Received: from mail02.haj.ipfire.org (mail02.haj.ipfire.org [172.28.1.201]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange x25519) (Client CN "mail02.haj.ipfire.org", Issuer "YE1" (not verified)) by mail01.ipfire.org (Postfix) with ESMTPS id 4gyfLv2CnKz45Q for ; Sun, 12 Jul 2026 08:46:47 +0000 (UTC) Received: from mail02.haj.ipfire.org (localhost [IPv6:::1]) by mail02.haj.ipfire.org (Postfix) with ESMTP id 4gyfLv1Kl6z2xWm for ; Sun, 12 Jul 2026 08:46:47 +0000 (UTC) X-Original-To: location@lists.ipfire.org Received: from mail01.ipfire.org (mail01.haj.ipfire.org [IPv6:2001:678:b28::25]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange x25519 server-signature ECDSA (secp384r1 raw public key) server-digest SHA384 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mail01.haj.ipfire.org", Issuer "YR2" (not verified)) by mail02.haj.ipfire.org (Postfix) with ESMTPS id 4gyfLt3jg8z2xHj for ; Sun, 12 Jul 2026 08:46:46 +0000 (UTC) Received: from mail-pl1-x631.google.com (mail-pl1-x631.google.com [IPv6:2607:f8b0:4864:20::631]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange x25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "smtp.gmail.com", Issuer "WR4" (verified OK)) by mail01.ipfire.org (Postfix) with ESMTPS id 4gyfLs2h66zNZ for ; Sun, 12 Jul 2026 08:46:45 +0000 (UTC) Authentication-Results: mail01.ipfire.org; dkim=pass header.d=gmail.com header.s=20251104 header.b="Bzv/1Z/X"; spf=pass (mail01.ipfire.org: domain of valter.jansons@gmail.com designates 2607:f8b0:4864:20::631 as permitted sender) smtp.mailfrom=valter.jansons@gmail.com; dmarc=pass (policy=none) header.from=gmail.com ARC-Seal: i=1; a=rsa-sha256; d=lists.ipfire.org; s=202003rsa; cv=none; t=1783846005; b=F1AeKYAXEo9uWVYS4tN49e5+SBkE0c4eIUU8d5KIFuQPNdAbeysxQ95ynrqoJJEvR8Uj8t MRCFXCEUohQo7TQPRJoVnJzyVkfT5yx7vpcqU1FoimVOhgxLCMOJa0wzioXnticM4Y1FMG +Uo9+eDJzacsE/WarVTkFNPuGDFM/z+RuTjfhjjYPcs/RkhlCSgm0BggaH5qj9BnCu3NYy RN2HICVLEjbrq6PzobIVKKgEll/8YYRBXI4lqqsR3VFfiEts1LgWXanw7Yr6b/P18nZW0o 3Fhi8vQi6BQVCGq5yZvqvZvjHUTblZptHVfxyvg2jQXWhnSxH1wnNeAjNzL77A== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=lists.ipfire.org; s=202003rsa; t=1783846005; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding:dkim-signature; bh=PRx6O86oaREap7dSk5Eli6yXbsxtpEyKSvJBz+MuKd0=; b=LPi4PZo7zjM6JtpwaWceG/qFRWe2lNc4zYhWpkAeUjfbDrtOf58Ajzw8D06Maj2XSKoukM ps3CjCUFG9/gMCBFZgo9Mw9+MRTnocko0C+inVNgOtaMyjqXu24bKSx8QEYdrew7W/CZfZ ktWVwuTjZIt21K3OmKpxKzHZCUD/xgriDWc2Zb65a3P2yRFvyvLIQwWFYiBbwkHNAgi7S4 JYPy+ju9if8TFpbs1e0kJXuhlboptAauft6rPylfI5XVrmGcEgVBKWw6U1/8xi2+xxqqvY ZomZg8JFxpvNEquFnbibJc/9aB1WqsOsmwp9nbJWJfr3DxvVWnXmq3OTlhTIfg== ARC-Authentication-Results: i=1; mail01.ipfire.org; dkim=pass header.d=gmail.com header.s=20251104 header.b="Bzv/1Z/X"; spf=pass (mail01.ipfire.org: domain of valter.jansons@gmail.com designates 2607:f8b0:4864:20::631 as permitted sender) smtp.mailfrom=valter.jansons@gmail.com; dmarc=pass (policy=none) header.from=gmail.com Received: by mail-pl1-x631.google.com with SMTP id d9443c01a7336-2ca64c3ce5fso25706065ad.3 for ; Sun, 12 Jul 2026 01:46:45 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1783846003; x=1784450803; darn=lists.ipfire.org; h=content-transfer-encoding:content-type:mime-version:message-id:date :subject:cc:to:from:from:to:cc:subject:date:message-id:reply-to :content-type; bh=PRx6O86oaREap7dSk5Eli6yXbsxtpEyKSvJBz+MuKd0=; b=Bzv/1Z/XiM3JOz3szdXYs8sbXHoVd4guZ4mX0ykdQzvjXFHWOAR7pAgYij02+h0APr y9DmAMIV9vj1/vvAENJfcQD2I2CeHPwuPUsoiMaWKA9FTjSb7HC+WjIYbUa9e8g5c6D/ unj+0bYOIn5hddWu2MUGNn7J8rnNG7ICkWkkGlJLe4UPXgpGpYCNuxgF2n3bYvqrqu2N 9acazU9YzTEEmQfTRS9sMFa8tOyntO3Iwd6DMd8thzNyo6U56Q3p0+eOn9iLJisNiril 1ssfhaYYUs61iznxfm0r4S1QHsGYFzzAVgWrYF1f/tkk1MDEMdFhvzMplgfnT9eKGQhQ KO2Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1783846003; x=1784450803; h=content-transfer-encoding:content-type:mime-version:message-id:date :subject:cc:to:from:x-gm-gg:x-gm-message-state:from:to:cc:subject :date:message-id:reply-to:content-type; bh=PRx6O86oaREap7dSk5Eli6yXbsxtpEyKSvJBz+MuKd0=; b=OL21FMHKsoEj8dvn81ZyU/q1086dDtzx7iYNldiZ6+TpnW64i5Ob+zJzMot8ojE9xn II1ivnHcuNUdRXCTdAArKvWXvXFrfg/XV+4aCcltIv9GfPonMryWSgCc+WZ/jTXpY6NG YrmI9bdxiD74FS/FGC6w718nr0j1t9VnItdBshonkwLcx/e0heRO9lbQ8MjObpU9YhYU YBjCSlFYb34uUk/NoqG9WQD1ohqVCwqZFy1uiBd56ydieK0TSmyNjzLijDc/shXpSCgB Y/UtOPvAIQa59febWvdbSJGmIfV7o5PCVyF8LsCLar8/0uBS+unrwtqykAMY9GZEBI+s VR1A== X-Gm-Message-State: AOJu0YwKUpAxsgt0ny6OIP6saqa3vNwQ0tPo51RWwzivUG+5m6q1T7/x dFx4HYX0pkVfjhfk5WuXJhRcMFOICtq3c8oKyxq6gzws21TG+D4FjW++00CFafv4 X-Gm-Gg: AfdE7clYoSMTfNIlxG+CDPFLJXQCvqqNBf5wbFWIWaCz9m//2+hHfPrugmE7yr2T5+0 ZvAS8pn+zGO/r0tkjMBzRZMHn2EDizkSZGzOIf7YlWtX4pzdfNb0BU9xYOqS+PSMjoWHzy0MidW HCcLyaIQFSjlO8kONsJm9/xmsrKsSoqqR/Sf3HgMtprHzpOjaUQ6FnfaIA/Yc/cuWbVjlJHFM2v uuehil3F7uHuJO43rsIL27pu0alrP9RhJsih4EJYWRGMipa3BN9SJzU9yVyQyYsS/PMXhKUmuGJ LvzimQvL+9Ydvh23volmLyVYcwZR1ekqMaRTi9XOWxjoknbnm1RYlKmIQsXaURKaSjIO8MLdSVF 0m4pBPzpPmBdRAASDFRCLf/g2qgNgkRTvdtA/Gn7/mpGBvxc83D5bmYbBVdRdXgzYBCAoE62VKa R3sznvkQqX1vfBw4SpvDNPDRuxUQCkWQ== X-Received: by 2002:a17:903:8cc:b0:2ce:88d7:a233 with SMTP id d9443c01a7336-2ce9f059cfbmr53591385ad.33.1783846003123; Sun, 12 Jul 2026 01:46:43 -0700 (PDT) Received: from VT14-G5.localdomain ([221.146.12.107]) by smtp.gmail.com with ESMTPSA id d9443c01a7336-2ccc9d1e284sm83273355ad.40.2026.07.12.01.46.41 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 12 Jul 2026 01:46:42 -0700 (PDT) From: Valters Jansons To: location@lists.ipfire.org Cc: Claude Fable 5 Subject: [PATCH] man: Clean up existing documentation Date: Sun, 12 Jul 2026 17:46:33 +0900 Message-ID: <20260712084638.126880-1-valter.jansons@gmail.com> X-Mailer: git-send-email 2.54.0 Precedence: list List-Id: List-Subscribe: , List-Unsubscribe: , List-Post: List-Help: Sender: Mail-Followup-To: MIME-Version: 1.0 X-Rspamd-Queue-Id: 4gyfLs2h66zNZ X-Rspamd-Action: no action X-Spamd-Result: default: False [-7.08 / 11.00]; BAYES_HAM(-3.00)[100.00%]; R_DKIM_ALLOW(-1.69)[gmail.com:s=20251104]; DKIM_REPUTATION(-0.96)[-0.95937060724739]; SPF_REPUTATION_HAM(-0.53)[-0.53142389715982]; DMARC_POLICY_ALLOW(-0.50)[gmail.com,none]; R_SPF_ALLOW(-0.20)[+ip6:2607:f8b0:4864::/56:c]; MIME_GOOD(-0.10)[text/plain]; MX_GOOD(-0.10)[gmail-smtp-in.l.google.com]; FREEMAIL_FROM(0.00)[gmail.com]; DWL_DNSWL_NONE(0.00)[gmail.com:dkim]; RCVD_TLS_LAST(0.00)[]; ARC_NA(0.00)[]; FREEMAIL_ENVFROM(0.00)[gmail.com]; TO_DN_SOME(0.00)[]; RCPT_COUNT_TWO(0.00)[2]; MIME_TRACE(0.00)[0:+]; IP_REPUTATION_HAM(0.00)[asn: 15169(-0.31), country: US(-0.01), ip: 2607:f8b0:4864:20::(-0.82)]; FROM_HAS_DN(0.00)[]; DKIM_TRACE(0.00)[gmail.com:+]; TO_MATCH_ENVRCPT_SOME(0.00)[]; RCVD_COUNT_TWO(0.00)[2]; FROM_EQ_ENVFROM(0.00)[]; RCVD_IN_DNSWL_NONE(0.00)[2607:f8b0:4864:20::631:from]; PREVIOUSLY_DELIVERED(0.00)[location@lists.ipfire.org]; MID_RHS_MATCH_FROM(0.00)[]; ALIAS_RESOLVED(0.00)[]; ASN(0.00)[asn:15169, ipnet:2607:f8b0::/32, country:US]; RCVD_VIA_SMTP_AUTH(0.00)[]; ARC_SIGNED(0.00)[lists.ipfire.org:s=202003rsa:i=1] X-Rspamd-Server: mail01.haj.ipfire.org While generating the `location-importer` manual page, tooling flagged supplemental fixes for location(1) and other man3 pages. Some are minor style and grammar fixes, as well as AsciiDoc markup fixes, but most of the changes proposed are gradual drift resulting from codebase changes. This commit incorporates those suggestions. In addition to existing manpages being cleaned up, loc_set_log_callback man3 page is being added, as loc_set_log_fn has been deprecated, and previously had a manpage created. Without the new page, the existing manpage would just be a dead-end. Co-Authored-By: Claude Fable 5 Signed-off-by: Valters Jansons --- Makefile.am | 1 + man/libloc.txt | 7 ++--- man/loc_database_get_country.txt | 1 + man/loc_database_lookup.txt | 3 ++- man/loc_database_new.txt | 8 +++--- man/loc_new.txt | 2 +- man/loc_set_log_callback.txt | 37 ++++++++++++++++++++++++++ man/loc_set_log_fn.txt | 8 +++--- man/loc_set_log_priority.txt | 4 +-- man/location.txt | 45 +++++++++++++++++++++++++++----- 10 files changed, 96 insertions(+), 20 deletions(-) create mode 100644 man/loc_set_log_callback.txt 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.