Skip to contentSkip to conversation

ldconfig.8: Document file filter and symlink pattern expectations

PATCH In review DJ Delorie 3 participants 4 messages Dec 2, 2019 – Dec 14, 2019 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore

DJ Delorie

author
#0 lore raw

PATCH 1/1 ldconfig.8: Document file filter and symlink pattern expectations

Information gleaned from comments in glibc's elf/ldconfig.c

man8/ldconfig.8 +22 -0
index 4f799962c..15585243c 100644
@@ -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
#1 lore raw
Quoted 27 lines · DJ Delorie

Information gleaned from comments in glibc's elf/ldconfig.c

man8/ldconfig.8 +15 -0
index 4f799962c..15585243c 100644
@@ -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

man8/ldconfig.8 option. · line 120

Quoted 10 lines
man8/ldconfig.8 +7 -0
+.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 :-)

Signature · 2 lines
Cheers,
Carlos.
#3 lore raw
In reply to DJ Delorie
Quoted 2 lines · DJ Delorie

Information gleaned from comments in glibc's elf/ldconfig.c

Thanks, DJ. Patch applied.

Cheers,

Michael

Quoted 34 lines
man8/ldconfig.8 +22 -0
index 4f799962c..15585243c 100644
@@ -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
#2 lore raw
In reply to Carlos O'Donell

Hi Carlis,

Quoted 58 lines · Carlos O'Donell
Quoted 27 lines · DJ Delorie

Information gleaned from comments in glibc's elf/ldconfig.c

man8/ldconfig.8 +15 -0
index 4f799962c..15585243c 100644
@@ -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

man8/ldconfig.8 option. · line 120

Quoted 10 lines
man8/ldconfig.8 +7 -0
+.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

Quoted 10 lines
  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.

Quoted 5 lines

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