[patch] ldconfig.8: Document file filter and symlink pattern expectations

[Michael Kerrisk (man-pages)]

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