rtld-audit.7: Clarify la_version handshake
PATCH 1/1 rtld-audit.7: Clarify la_version handshake
Returning its argument without further checks is almost always wrong for la_version.
--- man7/rtld-audit.7 | 31 ++++++++++++++++++++++--------- 1 file changed, 22 insertions(+), 9 deletions(-)
man7/rtld-audit.7 +22 -9
@@ -70,17 +70,30 @@ the auditing library. When invoking this function, the dynamic linker passes, in .IR version , the highest version of the auditing interface that the linker supports. -If necessary, the auditing library can check that this version -is sufficient for its requirements. .PP -As its function result, -this function should return the version of the auditing interface -that this auditing library expects to use (returning +A typical implementation of this function simply returns the constant +.BR LAV_CURRENT , +which indicates the version of +.I <link.h> +that was used to build the audit module. If the dynamic linker does +not support this version of the audit interface, it will refuse to +activate this audit module. If the function returns zero, the dynamic +linker also does not activate this audit module. +.PP +In order to enable backwards compatibility with older dynamic linkers, +an audit module can examine the +.I version +argument and return an earlier version than +.BR LAV_CURRENT , +assuming the module can adjust its implement to match the requirements +of the previous version of the audit interface. The +.B la_version +function should not return the value of .I version -is acceptable). -If the returned value is 0, -or a version that is greater than that supported by the dynamic linker, -then the audit library is ignored. +without further checks because it could correspond to an interface +that does not match the +.I <link.h> +definitions used to build the audit module. .SS la_objsearch() \& .nf
Signature · 3 lines
Red Hat GmbH, https://de.redhat.com/ , Registered seat: Grasbrunn, Commercial register: Amtsgericht Muenchen, HRB 153243, Managing Directors: Charles Cachera, Brian Klemm, Laurie Krebs, Michael O'Neill
man7/rtld-audit.7 the auditing library. · line 88
Quoted 7 lines · Florian Weimer via Libc-alpha
+.PP
man7/rtld-audit.7 +6
-0+In order to enable backwards compatibility with older dynamic linkers, +an audit module can examine the +.I version +argument and return an earlier version than +.BR LAV_CURRENT , +assuming the module can adjust its implement to match the requirements
s/implement/interface/ ?
Andreas.
Signature · 3 lines
Andreas Schwab, [email protected] GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510 2552 DF73 E780 A9DA AEC1 "And now for something completely different."
* Andreas Schwab:
Quoted 11 lines · Florian Weimer via Libc-alpha
man7/rtld-audit.7 the auditing library. · line 88
Quoted 8 lines
+.PP
man7/rtld-audit.7 +6
-0+In order to enable backwards compatibility with older dynamic linkers, +an audit module can examine the +.I version +argument and return an earlier version than +.BR LAV_CURRENT , +assuming the module can adjust its implement to match the requirementss/implement/interface/ ?
Thanks. I meant to write “implementation”. Fixed locally.
Do you agree that this is how the handshake should work?
Florian
Signature · 3 lines
Red Hat GmbH, https://de.redhat.com/ , Registered seat: Grasbrunn, Commercial register: Amtsgericht Muenchen, HRB 153243, Managing Directors: Charles Cachera, Brian Klemm, Laurie Krebs, Michael O'Neill
Quoted 1 line · Florian Weimer
Do you agree that this is how the handshake should work?
I have never seen the audit interface being used, so I have no opinion.
Andreas.
Signature · 3 lines
Andreas Schwab, [email protected] GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510 2552 DF73 E780 A9DA AEC1 "And now for something completely different."
Quoted 2 lines · Florian Weimer via Libc-alpha
Returning its argument without further checks is almost always wrong for
la_version.
What you write here is the way I understand the interface to work.
As Andreas noted there is one typo.
I suggest changing the example to match, otherwise people might keep cribbing that code ;-)
Quoted 2 lines
Signed-off-by Florian Weimer <[email protected]>
I agree that la_version should return LAV_CURRENT, that is the expected way to implement the function, and returning less than LAV_CURRENT is required to implement older interfaces and be more compatible with older releases.
As an example I encouraged Ludovic to solve a Guix path problem with LD_AUDIT and you can see it here:
https://issues.guix.gnu.org/41189
+unsigned int
+la_version (unsigned int v)
+{
+ if (v != LAV_CURRENT)
+ error (1, 0, "cannot handle interface version %u", v);
+
...
+ return v;
+}
While this is OK, in that if it's not an exact match the audit module errors out, or if it is a match returns v which is LAV_CURRENT.
It could have been more relaxed:
if (v < LAV_CURRENT)
error (...)
...
return LAV_CURRENT;
Your changes here int he man page would have clarified that to some extent.
Quoted 23 lines
--- man7/rtld-audit.7 | 31 ++++++++++++++++++++++--------- 1 file changed, 22 insertions(+), 9 deletions(-)man7/rtld-audit.7 +5
-5@@ -70,17 +70,30 @@ the auditing library. When invoking this function, the dynamic linker passes, in .IR version , the highest version of the auditing interface that the linker supports. -If necessary, the auditing library can check that this version -is sufficient for its requirements. .PP -As its function result, -this function should return the version of the auditing interface -that this auditing library expects to use (returning +A typical implementation of this function simply returns the constant +.BR LAV_CURRENT , +which indicates the version of +.I <link.h> +that was used to build the audit module. If the dynamic linker does
man7/rtld-audit.7 the auditing library. · line 88
Quoted 10 lines
man7/rtld-audit.7 +10
-0+not support this version of the audit interface, it will refuse to +activate this audit module. If the function returns zero, the dynamic +linker also does not activate this audit module. +.PP +In order to enable backwards compatibility with older dynamic linkers, +an audit module can examine the +.I version +argument and return an earlier version than +.BR LAV_CURRENT , +assuming the module can adjust its implement to match the requirements
s/implement/implementation/g (Andreas caught this in his review)
Quoted 6 lines
man7/rtld-audit.7 +3
-1+of the previous version of the audit interface. The +.B la_version +function should not return the value of .I version -is acceptable).
man7/rtld-audit.7 the auditing library. · line 99
Quoted 10 lines
man7/rtld-audit.7 +4
-3-If the returned value is 0, -or a version that is greater than that supported by the dynamic linker, -then the audit library is ignored. +without further checks because it could correspond to an interface +that does not match the +.I <link.h> +definitions used to build the audit module. .SS la_objsearch() \& .nf
May I additionally suggest something like this to the example?
man7/rtld-audit.7 +5 -1
@@ -510,7 +510,11 @@ la_version(unsigned int version) { printf("la_version(): %u\en", version); - return version; + if (version > LAV_CURRENT) + printf ("la_version(): rtld supports newer interfaces.\n"); + + /* Request the version we knew about at compile time. */ + return LAV_CURRENT; } char *
---
Post a v2?
Signature · 2 lines
Cheers, Carlos.
* Carlos O'Donell:
Quoted 1 line
May I additionally suggest something like this to the example?
Ah, I had missed the example at the end. Yes, I'm going to send a v2.
Thanks,
Florian
Signature · 3 lines
Red Hat GmbH, https://de.redhat.com/ , Registered seat: Grasbrunn, Commercial register: Amtsgericht Muenchen, HRB 153243, Managing Directors: Charles Cachera, Brian Klemm, Laurie Krebs, Michael O'Neill