From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from gnu.wildebeest.org (gnu.wildebeest.org [45.83.234.184]) by sourceware.org (Postfix) with ESMTPS id D77333895FE3 for ; Fri, 21 Jun 2024 13:28:35 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org D77333895FE3 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=klomp.org Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=klomp.org ARC-Filter: OpenARC Filter v1.0.0 sourceware.org D77333895FE3 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=45.83.234.184 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1718976518; cv=none; b=AgwcpdToPzYyf7BFzdUuMhcRBgOdns+PFVm5H+lH23lcKT6Pk94aWqLGcU0z6OIKSYc2wUwSrs9Xov2WSWvD8ZNoU//LV9H5LeebZHyTS5DMb5slmRfWI1tR+tw46IVGVSERXbFMPV+APbX4amzEq9d1vvPa8vkyffv8e5Wag6M= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1718976518; c=relaxed/simple; bh=hqIf5eCMBA8CJtTupyiAwDmEQuHqFcUED8lJjH2efOY=; h=Message-ID:Subject:From:To:Date:MIME-Version; b=LZJx3y0uDxLpEZmgzX2rxbfp0NuMZM9KjHvOSyTu6TF9K6JH0R4rqU358yQvTkiLakyvi1/rgkFBP+rCZQY/uZFNIt1Vv0Bc/dSIQOo+tS1TTfzEozKwnzmODoJ43YXg7wfVz8UNLKLC67UOM4IL0bXmgLBSG2D+h5UHmyGpWGQ= ARC-Authentication-Results: i=1; server2.sourceware.org Received: from r6.localdomain (82-217-174-174.cable.dynamic.v4.ziggo.nl [82.217.174.174]) (using TLSv1.2 with cipher ADH-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by gnu.wildebeest.org (Postfix) with ESMTPSA id 41B3B3000593; Fri, 21 Jun 2024 15:28:34 +0200 (CEST) Received: by r6.localdomain (Postfix, from userid 1000) id D4D1D340382; Fri, 21 Jun 2024 15:28:33 +0200 (CEST) Message-ID: <3cd2095372fc3184dc1af0704cec1d5ec13d3299.camel@klomp.org> Subject: Re: [PATCH] Add man pages for some libelf functions From: Mark Wielaard To: Aaron Merey , elfutils-devel@sourceware.org Date: Fri, 21 Jun 2024 15:28:33 +0200 In-Reply-To: References: Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable User-Agent: Evolution 3.52.2 (3.52.2-1.fc40) MIME-Version: 1.0 X-Spam-Status: No, score=-7.9 required=5.0 tests=BAYES_00,GIT_PATCH_0,JMQ_SPF_NEUTRAL,KAM_DMARC_STATUS,KAM_SHORT,RCVD_IN_BARRACUDACENTRAL,SPF_HELO_NONE,SPF_PASS,TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: Hi Aaron, On Thu, 2024-06-13 at 16:01 -0400, Aaron Merey wrote: > I've attached a patch that adds man pages for a few libelf functions. > These man pages were originally generated using ChatGPT (model > GPT-4o). I edited each man page by hand to help ensure brevity and > accuracy. > > Parts of the original descriptions generated by ChatGPT have been left > as is. I've attached the original man pages generated by ChatGPT for > comparison. So the first question really is where did ChatGPT get this information from? I see it produces Copyright statements, but it is clear to me those aren't accurate. What is the copyright status of these generated manual pages? It looks like your edits are so extensive that you can claim your own copyright on them. But make sure that your Signed-off-by is really accurate. CONTRIBUTING says: The sign-off is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to pass it on as a patch under an appropriate license. The rules are pretty simple: if you can certify the below: Developer's Certificate of Origin By making a contribution to this project, I certify that: (a) The contribution was created in whole or in part by me, and I have the right to submit the contribution under each license indicated in, or otherwise designated as being applicable to, the file. (b) The contribution was provided directly to me by some other person who certified (a), and I have not modified it. (c) I understand and agree that the project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed. I see it also sometimes generates a HISTORY section with a bogus "first appeared in..." line. We do have symbol versioning, so you can get some of this information from the libelf/libelf.maps file. But note that the symbol version isn't the same as the elfutils version (you can use git to map them). There are only 8 different versions that introduced new symbols. In general I wonder how useful the description text generated by chatgtp is. It looks very generic and I am a little worried it seems to happily generate "descriptions" for none-exiting libelf functions. > The prompt used to generate the man pages was: > Write a linux man page for the function called in the open > source project called elfutils. I think it would be easier if you make the prompt less specific. How about just asking for a template that you can then fill in yourself? Write a template man page for the function called for the libelf library in the elfutils project for the "libelf Programmer's Manual" =20 > My goal is to eventually add man pages for all elfutils library functions= . > If the man pages in this patch are acceptable then I will use the above > method to create the remaining man pages. I will post these to > elfutils-devel in batches to avoid the need for reviewing very large > individual patches. Thanks. A couple of minor comments below. > From 920a9ac8875d82e8014bf5f3afa6d85dbf00b6cb Mon Sep 17 00:00:00 2001 > From: Aaron Merey > Date: Thu, 13 Jun 2024 15:20:03 -0400 > Subject: [PATCH] Add man pages for some libelf functions >=20 > Add man pages for elf32_getehdr.3, elf64_getehdr.3, elf_errmsg.3, > elf_errno.3 and elf_version.3 >=20 > Signed-off-by: Aaron Merey > --- > doc/Makefile.am | 6 +++++- > doc/elf32_getehdr.3 | 36 ++++++++++++++++++++++++++++++++++++ > doc/elf64_getehdr.3 | 36 ++++++++++++++++++++++++++++++++++++ > doc/elf_errmsg.3 | 26 ++++++++++++++++++++++++++ > doc/elf_errno.3 | 24 ++++++++++++++++++++++++ > doc/elf_version.3 | 23 +++++++++++++++++++++++ > 6 files changed, 150 insertions(+), 1 deletion(-) > create mode 100644 doc/elf32_getehdr.3 > create mode 100644 doc/elf64_getehdr.3 > create mode 100644 doc/elf_errmsg.3 > create mode 100644 doc/elf_errno.3 > create mode 100644 doc/elf_version.3 >=20 > diff --git a/doc/Makefile.am b/doc/Makefile.am > index 0c094af2..6a858c59 100644 > --- a/doc/Makefile.am > +++ b/doc/Makefile.am > @@ -18,7 +18,11 @@ > ## along with this program. If not, see . > EXTRA_DIST =3D COPYING-GFDL README > dist_man1_MANS=3Dreadelf.1 elfclassify.1 srcfiles.1 > -notrans_dist_man3_MANS=3Delf_update.3 elf_getdata.3 elf_clone.3 elf_begi= n.3 > + > +notrans_dist_man3_MANS =3D elf_update.3 elf_getdata.3 elf_clone.3 elf_be= gin.3 \ > + elf32_getehdr.3 elf64_getehdr.3 elf_errmsg.3 elf_errno.3 \ > + elf_version.3 > + Note that it doesn't apply anymore because I tweaked this in commit 80aeca1b836e ("doc: Always distribute all man pages") by adding some comments before this line. While you fix that merge conflict maybe also put one man page file on one line. That makes it easier to insert new pages in the future. > notrans_dist_man7_MANS=3D > notrans_dist_man8_MANS=3D > notrans_dist_man1_MANS=3D > diff --git a/doc/elf32_getehdr.3 b/doc/elf32_getehdr.3 > new file mode 100644 > index 00000000..4dbb3886 > --- /dev/null > +++ b/doc/elf32_getehdr.3 > @@ -0,0 +1,36 @@ > +.TH ELF32_GETEHDR 3 Could you use the same .TH template as the existing doc/elf*1 manpages which say "Libelf" "Libelf Programmer's Manual" > +.SH NAME > +elf32_getehdr \- retrieve the ELF header for a 32-bit ELF descriptor > + > +.SH SYNOPSIS > +.nf > +#include > + > +Elf32_Ehdr *elf32_getehdr(Elf *elf); > +.fi > + > +.SH DESCRIPTION > +.B elf32_getehdr > +retrieves the ELF header for the given 32-bit ELF descriptor > +.I elf. > +The ELF header contains crucial metadata about the ELF file, such as the= type, machine, version, entry point, program header table offset, and sect= ion header table offset. Should it list the actual Elf32_Ehdr struct from elf.h here? > +.SH PARAMETERS > +.TP > +.I elf > +Pointer to the ELF descriptor from which to retrieve the ELF header. > + > +.SH RETURN VALUE > +On success, > +.B elf32_getehdr > +returns a pointer to the > +.B Elf32_Ehdr > +structure. If the ELF descriptor is invalid or not a 32-bit ELF, it retu= rns NULL and sets an error code retrievable by > +.BR elf_errno (3). > + > +.SH SEE ALSO > +.BR elf64_getehdr (3), > +.BR elf_begin (3) Add elf_errno (3) ? > +.SH REPORTING BUGS > +Report bugs to or https://sourceware.org= /bugzilla/. > diff --git a/doc/elf64_getehdr.3 b/doc/elf64_getehdr.3 > new file mode 100644 > index 00000000..acf9a125 > --- /dev/null > +++ b/doc/elf64_getehdr.3 Same questions as for the elf32 variant. > diff --git a/doc/elf_errmsg.3 b/doc/elf_errmsg.3 > new file mode 100644 > index 00000000..1031b581 > --- /dev/null > +++ b/doc/elf_errmsg.3 > @@ -0,0 +1,26 @@ > +.TH ELF_ERRMSG 3 > + > +.SH NAME > +elf_errmsg \- return the error message string for a given libelf error c= ode. > + > +.SH SYNOPSIS > +.B #include > + > +.BI "const char *elf_errmsg(int " err ");" > + > +.SH DESCRIPTION > +The \fBelf_errmsg\fP function retrieves a human-readable string correspo= nding to the most recent error code set by a libelf library function. If \f= Ierr\fP is 0, the function returns the error message for the most recent er= ror code. If \fIerr\fP is non-zero, the function returns the error message = for the specified error code. > + > +.SH PARAMETERS > +.TP > +.I err > +An \fIint\fP value specifying the error code. If this value is 0, the fu= nction returns the error message for the most recent error. If this value i= s non-zero, the function returns the error message for the specified error = code. >=20 Note that the libelf.h description describes the special argument value -1: /* Return error string for ERROR. If ERROR is zero, return error string for most recent error or NULL is none occurred. If ERROR is -1 the behaviour is similar to the last case except that not NULL but a legal string is returned. */ > +.SH RETURN VALUE > +The \fBelf_errmsg\fP function returns a string containing the error mess= age. If there is no corresponding error message, it returns NULL. > + > +.SH SEE ALSO > +.BR elf_errno (3) > + > +.SH REPORTING BUGS > +Report bugs to or https://sourceware.org= /bugzilla/. > diff --git a/doc/elf_errno.3 b/doc/elf_errno.3 > new file mode 100644 > index 00000000..e25f5207 > --- /dev/null > +++ b/doc/elf_errno.3 > @@ -0,0 +1,24 @@ > +.TH ELF_ERRNO 3 > + > +.SH NAME > +elf_errno \- retrieve the error code of the last failing libelf function= call. > + > +.SH SYNOPSIS > +.B #include > + > +.BI "int elf_errno(void);" > + > +.SH DESCRIPTION > +The \fBelf_errno\fP function retrieves the error code of the last failin= g libelf library function. This error code indicates the type of error that= occurred during the failing function call. Maybe include the description from libelf.h (specifically mention the value is thread local): /* Return error code of last failing function call. This value is kept separately for each thread. */ > + > +.SH PARAMETERS > +This function does not take any parameters. > + > +.SH RETURN VALUE > +The \fBelf_errno\fP function returns an integer representing the most re= cent error code. If no error has occurred, it returns 0. If an error occurr= ed, the function returns a non-zero error code that corresponds to the spec= ific error. Error codes can be passed to \fBelf_errmsg\fP in order to crea= te a string describing the error. > + > +.SH SEE ALSO > +.BR elf_errmsg (3) > + > +.SH REPORTING BUGS > +Report bugs to or https://sourceware.org= /bugzilla/. > diff --git a/doc/elf_version.3 b/doc/elf_version.3 > new file mode 100644 > index 00000000..fd309ae1 > --- /dev/null > +++ b/doc/elf_version.3 > @@ -0,0 +1,23 @@ > +.TH ELF_VERSION 3 > + > +.SH NAME > +elf_version \- set the ELF library version > + > +.SH SYNOPSIS > +.B #include > + > +.BI "unsigned int elf_version(unsigned int " version ");" > + > +.SH DESCRIPTION > +The \fBelf_version\fP function sets the library's ELF version to the spe= cified value. This function must be called before any other libelf function= s are used. > + > +.SH PARAMETERS > +.TP > +.I version > +An \fIunsigned int\fP value specifying the desired ELF library version. = This is should be set to \fBEV_CURRENT\fP to indicate the current version o= f the library. At this time the only supported \fIversion\fP values are \fB= EV_CURRENT\fP and \fBEV_NONE\fP. > + > +.SH RETURN VALUE > +The \fBelf_version\fP function returns \fBEV_CURRENT\fP when \fIversion\= fP is supported. If the specified version is not supported, it returns \fBE= V_NONE\fP. > + > +.SH REPORTING BUGS > +Report bugs to or https://sourceware.org= /bugzilla/. >=20 elf_version is kind of funny. EV_CURRENT is 1 and I don't believe we will ever see another ELF version. Cheers, Mark