===================================================================
@@ -12988,28 +12988,27 @@ Search the library named @var{library} w
alternative with the library as a separate argument is only for
POSIX compliance and is not recommended.)
+The @option{-l} option is passed directly to the linker by GCC. Refer
+to your linker documentation for exact details. The general
+description below applies to the GNU linker.
+
+The linker searches a standard list of directories for the library.
+The directories searched include several standard system directories
+plus any that you specify with @option{-L}.
+
+Static libraries are archives of object files, and have file names
+like @file{lib@var{library}.a}. Some targets also support shared
+libraries, which typically have names like @file{lib@var{library}.so}.
+If both static and shared libraries are found, the linker gives
+preference to linking with the shared library unless the
+@option{-static} option is used.
+
It makes a difference where in the command you write this option; the
linker searches and processes libraries and object files in the order they
are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers
to functions in @samp{z}, those functions may not be loaded.
-The linker searches a standard list of directories for the library,
-which is actually a file named @file{lib@var{library}.a}. The linker
-then uses this file as if it had been specified precisely by name.
-
-The directories searched include several standard system directories
-plus any that you specify with @option{-L}.
-
-Normally the files found this way are library files---archive files
-whose members are object files. The linker handles an archive file by
-scanning through it for members which define symbols that have so far
-been referenced but not defined. But if the file that is found is an
-ordinary object file, it is linked in the usual fashion. The only
-difference between using an @option{-l} option and specifying a file name
-is that @option{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
-and searches several directories.
-
@item -lobjc
@opindex lobjc
You need this special case of the @option{-l} option in order to