* [patch] ldconfig.8: Document file filter and symlink pattern expectations
@ 2019-12-02 20:32 DJ Delorie
2019-12-02 21:41 ` Carlos O'Donell
2019-12-14 4:54 ` Michael Kerrisk (man-pages)
0 siblings, 2 replies; 4+ messages in thread
From: DJ Delorie @ 2019-12-02 20:32 UTC (permalink / raw)
To: mtk.manpages; +Cc: linux-man, libc-alpha
Information gleaned from comments in glibc's elf/ldconfig.c
diff --git a/man8/ldconfig.8 b/man8/ldconfig.8
index 4f799962c..15585243c 100644
--- a/man8/ldconfig.8
+++ b/man8/ldconfig.8
@@ -93,6 +93,28 @@ option.
.B ldconfig
should normally be run by the superuser as it may require write
permission on some root owned directories and files.
+.PP
+Note that
+.B ldconfig
+will only look at files that are named
+.I lib*.so*
+(for regular shared objects) or
+.I ld-*.so*
+(for the dynamic loader itsef). Other files will be ignored. Also,
+.B ldconfig
+expects a certain pattern to how the symlinks are set up, like this
+example, where the middle file
+.RB ( libfoo.so.1
+here) is the SONAME for the library:
+.PP
+.in +4n
+.EX
+libfoo.so -> libfoo.so.1 -> libfoo.so.1.12
+.EE
+.in
+.PP
+Failure to follow this pattern may result in compatibility issues
+after an upgrade.
.SH OPTIONS
.TP
.BR \-c " \fIfmt\fP, " \-\-format=\fIfmt\fP
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [patch] ldconfig.8: Document file filter and symlink pattern expectations
2019-12-02 20:32 [patch] ldconfig.8: Document file filter and symlink pattern expectations DJ Delorie
@ 2019-12-02 21:41 ` Carlos O'Donell
2019-12-14 4:54 ` Michael Kerrisk (man-pages)
2019-12-14 4:54 ` Michael Kerrisk (man-pages)
1 sibling, 1 reply; 4+ messages in thread
From: Carlos O'Donell @ 2019-12-02 21:41 UTC (permalink / raw)
To: DJ Delorie, mtk.manpages; +Cc: linux-man, libc-alpha
On 12/2/19 3:32 PM, DJ Delorie wrote:
>
> Information gleaned from comments in glibc's elf/ldconfig.c
>
> diff --git a/man8/ldconfig.8 b/man8/ldconfig.8
> index 4f799962c..15585243c 100644
> --- a/man8/ldconfig.8
> +++ b/man8/ldconfig.8
> @@ -93,6 +93,28 @@ option.
> .B ldconfig
> should normally be run by the superuser as it may require write
> permission on some root owned directories and files.
> +.PP
> +Note that
> +.B ldconfig
> +will only look at files that are named
> +.I lib*.so*
> +(for regular shared objects) or
> +.I ld-*.so*
> +(for the dynamic loader itsef). Other files will be ignored. Also,
> +.B ldconfig
> +expects a certain pattern to how the symlinks are set up, like this
> +example, where the middle file
> +.RB ( libfoo.so.1
> +here) is the SONAME for the library:
> +.PP
> +.in +4n
> +.EX
> +libfoo.so -> libfoo.so.1 -> libfoo.so.1.12
> +.EE
> +.in
> +.PP
> +Failure to follow this pattern may result in compatibility issues
> +after an upgrade.
> .SH OPTIONS
> .TP
> .BR \-c " \fIfmt\fP, " \-\-format=\fIfmt\fP
>
I wrote the relevant comment in glibc here after a frustrating
night of debugging :-)
elf/ldconfig.c
884 /* If the path the link points to isn't its soname or it is not
885 the .so symlink for ld(1), we treat it as a normal file.
886
887 You should always do this:
888
889 libfoo.so -> SONAME -> Arbitrary package-chosen name.
890
891 e.g. libfoo.so -> libfoo.so.1 -> libfooimp.so.9.99.
892 Given a SONAME of libfoo.so.1.
893
894 You should *never* do this:
895
896 libfoo.so -> libfooimp.so.9.99
897
898 If you do, and your SONAME is libfoo.so.1, then libfoo.so
899 fails to point at the SONAME. In that case ldconfig may consider
900 libfoo.so as another implementation of SONAME and will create
901 symlinks against it causing problems when you try to upgrade
902 or downgrade. The problems will arise because ldconfig will,
903 depending on directory ordering, creat symlinks against libfoo.so
904 e.g. libfoo.so.1.2 -> libfoo.so, but when libfoo.so is removed
905 (typically by the removal of a development pacakge not required
906 for the runtime) it will break the libfoo.so.1.2 symlink and the
907 application will fail to start. */
Should we be more specific about always doing:
libfoo.so -> SONAME -> Arbitrary package-chosen name.
Users love having examples of how to do it right :-)
--
Cheers,
Carlos.
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [patch] ldconfig.8: Document file filter and symlink pattern expectations
2019-12-02 21:41 ` Carlos O'Donell
@ 2019-12-14 4:54 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 4+ messages in thread
From: Michael Kerrisk (man-pages) @ 2019-12-14 4:54 UTC (permalink / raw)
To: Carlos O'Donell, DJ Delorie; +Cc: linux-man, libc-alpha
Hi Carlis,
On 12/2/19 10:41 PM, Carlos O'Donell wrote:
> On 12/2/19 3:32 PM, DJ Delorie wrote:
>>
>> Information gleaned from comments in glibc's elf/ldconfig.c
>>
>> diff --git a/man8/ldconfig.8 b/man8/ldconfig.8
>> index 4f799962c..15585243c 100644
>> --- a/man8/ldconfig.8
>> +++ b/man8/ldconfig.8
>> @@ -93,6 +93,28 @@ option.
>> .B ldconfig
>> should normally be run by the superuser as it may require write
>> permission on some root owned directories and files.
>> +.PP
>> +Note that
>> +.B ldconfig
>> +will only look at files that are named
>> +.I lib*.so*
>> +(for regular shared objects) or
>> +.I ld-*.so*
>> +(for the dynamic loader itsef). Other files will be ignored. Also,
>> +.B ldconfig
>> +expects a certain pattern to how the symlinks are set up, like this
>> +example, where the middle file
>> +.RB ( libfoo.so.1
>> +here) is the SONAME for the library:
>> +.PP
>> +.in +4n
>> +.EX
>> +libfoo.so -> libfoo.so.1 -> libfoo.so.1.12
>> +.EE
>> +.in
>> +.PP
>> +Failure to follow this pattern may result in compatibility issues
>> +after an upgrade.
>> .SH OPTIONS
>> .TP
>> .BR \-c " \fIfmt\fP, " \-\-format=\fIfmt\fP
>>
>
> I wrote the relevant comment in glibc here after a frustrating
> night of debugging :-)
>
> elf/ldconfig.c
>
> 884 /* If the path the link points to isn't its soname or it is not
> 885 the .so symlink for ld(1), we treat it as a normal file.
> 886
> 887 You should always do this:
> 888
> 889 libfoo.so -> SONAME -> Arbitrary package-chosen name.
> 890
> 891 e.g. libfoo.so -> libfoo.so.1 -> libfooimp.so.9.99.
> 892 Given a SONAME of libfoo.so.1.
> 893
> 894 You should *never* do this:
> 895
> 896 libfoo.so -> libfooimp.so.9.99
> 897
> 898 If you do, and your SONAME is libfoo.so.1, then libfoo.so
> 899 fails to point at the SONAME. In that case ldconfig may consider
> 900 libfoo.so as another implementation of SONAME and will create
> 901 symlinks against it causing problems when you try to upgrade
> 902 or downgrade. The problems will arise because ldconfig will,
> 903 depending on directory ordering, creat symlinks against libfoo.so
> 904 e.g. libfoo.so.1.2 -> libfoo.so, but when libfoo.so is removed
> 905 (typically by the removal of a development pacakge not required
> 906 for the runtime) it will break the libfoo.so.1.2 symlink and the
> 907 application will fail to start. */
Thanks for that added info.
> Should we be more specific about always doing:
>
> libfoo.so -> SONAME -> Arbitrary package-chosen name.
>
> Users love having examples of how to do it right :-)
Well, I applied DJ's patch. Would you be willing to send a small patch
with this extra info?
Thanks,
Michael
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [patch] ldconfig.8: Document file filter and symlink pattern expectations
2019-12-02 20:32 [patch] ldconfig.8: Document file filter and symlink pattern expectations DJ Delorie
2019-12-02 21:41 ` Carlos O'Donell
@ 2019-12-14 4:54 ` Michael Kerrisk (man-pages)
1 sibling, 0 replies; 4+ messages in thread
From: Michael Kerrisk (man-pages) @ 2019-12-14 4:54 UTC (permalink / raw)
To: DJ Delorie; +Cc: linux-man, libc-alpha
On 12/2/19 9:32 PM, DJ Delorie wrote:
>
> Information gleaned from comments in glibc's elf/ldconfig.c
Thanks, DJ. Patch applied.
Cheers,
Michael
> diff --git a/man8/ldconfig.8 b/man8/ldconfig.8
> index 4f799962c..15585243c 100644
> --- a/man8/ldconfig.8
> +++ b/man8/ldconfig.8
> @@ -93,6 +93,28 @@ option.
> .B ldconfig
> should normally be run by the superuser as it may require write
> permission on some root owned directories and files.
> +.PP
> +Note that
> +.B ldconfig
> +will only look at files that are named
> +.I lib*.so*
> +(for regular shared objects) or
> +.I ld-*.so*
> +(for the dynamic loader itsef). Other files will be ignored. Also,
> +.B ldconfig
> +expects a certain pattern to how the symlinks are set up, like this
> +example, where the middle file
> +.RB ( libfoo.so.1
> +here) is the SONAME for the library:
> +.PP
> +.in +4n
> +.EX
> +libfoo.so -> libfoo.so.1 -> libfoo.so.1.12
> +.EE
> +.in
> +.PP
> +Failure to follow this pattern may result in compatibility issues
> +after an upgrade.
> .SH OPTIONS
> .TP
> .BR \-c " \fIfmt\fP, " \-\-format=\fIfmt\fP
>
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2019-12-14 4:54 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-12-02 20:32 [patch] ldconfig.8: Document file filter and symlink pattern expectations DJ Delorie
2019-12-02 21:41 ` Carlos O'Donell
2019-12-14 4:54 ` Michael Kerrisk (man-pages)
2019-12-14 4:54 ` Michael Kerrisk (man-pages)
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).