From f691523042f9e5e86cc1d553f10e417eeb880cb2 Mon Sep 17 00:00:00 2001
From: Brad House <brad@brad-house.com>
Date: Tue, 23 Jul 2024 19:32:59 -0400
Subject: [PATCH] man: ares_dns_record_set_id()

Add missing manpage

Fixes #817
Fix By: Brad House (@bradh352)
---
 docs/Makefile.inc             |  1 +
 docs/ares_dns_record.3        | 23 +++++++++++++++++------
 docs/ares_dns_record_set_id.3 |  3 +++
 3 files changed, 21 insertions(+), 6 deletions(-)
 create mode 100644 docs/ares_dns_record_set_id.3

diff --git a/docs/Makefile.inc b/docs/Makefile.inc
index 83d85ebf..46e30346 100644
--- a/docs/Makefile.inc
+++ b/docs/Makefile.inc
@@ -36,6 +36,7 @@ MANPAGES = ares_cancel.3		\
   ares_dns_record_rr_del.3		\
   ares_dns_record_rr_get.3		\
   ares_dns_record_rr_get_const.3	\
+  ares_dns_record_set_id.3		\
   ares_dns_rec_type_fromstr.3		\
   ares_dns_rec_type_tostr.3		\
   ares_dns_rec_type_t.3			\
diff --git a/docs/ares_dns_record.3 b/docs/ares_dns_record.3
index 11c59a64..47ca95b0 100644
--- a/docs/ares_dns_record.3
+++ b/docs/ares_dns_record.3
@@ -32,6 +32,9 @@ ares_dns_record_t *ares_dns_record_duplicate(const ares_dns_record_t *dnsrec);
 
 unsigned short ares_dns_record_get_id(const ares_dns_record_t *dnsrec);
 
+ares_bool_t ares_dns_record_set_id(ares_dns_record_t *dnsrec,
+                                   unsigned short id);
+
 unsigned short ares_dns_record_get_flags(const ares_dns_record_t *dnsrec);
 
 ares_dns_opcode_t ares_dns_record_get_opcode(const ares_dns_record_t *dnsrec);
@@ -343,6 +346,14 @@ message id from the DNS record provided in the
 .IR dnsrec
 parameter.
 
+The \fIares_dns_record_set_id(3)\fP function is used to set the DNS
+message id in the
+.IR id
+parameter from the DNS record provided in the
+.IR dnsrec
+parameter.  This id will be overwritten when passing the record to c-ares,
+so mostly exists for external purposes.
+
 The \fIares_dns_record_get_flags(3)\fP function is used to retrieve the DNS
 message flags from the DNS record provided in the
 .IR dnsrec
@@ -428,12 +439,12 @@ is returned on out of memory,
 .B ARES_EFORMERR
 is returned on misuse.
 
-\fIares_dns_record_get_id(3)\fP, \fIares_dns_record_get_flags(3)\fP,
-\fIares_dns_record_get_opcode(3)\fP, \fIares_dns_record_get_rcode(3)\fP, and
-\fIares_dns_record_query_cnt(3)\fP all returned their prescribed datatype
-values and in general can't fail except for misuse cases, in which a 0 may
-be returned, however 0 can also be a valid return value for most of these
-functions.
+\fIares_dns_record_get_id(3)\fP, \fIares_dns_record_set_id(3)\fP,
+\fIares_dns_record_get_flags(3)\fP, \fIares_dns_record_get_opcode(3)\fP,
+\fIares_dns_record_get_rcode(3)\fP, and \fIares_dns_record_query_cnt(3)\fP
+all returned their prescribed datatype values and in general can't fail except
+for misuse cases, in which a 0 may be returned, however 0 can also be a valid
+return value for most of these functions.
 
 
 .SH AVAILABILITY
diff --git a/docs/ares_dns_record_set_id.3 b/docs/ares_dns_record_set_id.3
new file mode 100644
index 00000000..4acc581d
--- /dev/null
+++ b/docs/ares_dns_record_set_id.3
@@ -0,0 +1,3 @@
+.\" Copyright (C) 2023 The c-ares project and its contributors.
+.\" SPDX-License-Identifier: MIT
+.so man3/ares_dns_record.3