To change the way a package behaves at startup, edit its startup script. For example, to start snmpd with an argument of −D you would edit the start line. Pick out the portion of the command where snmpd is actually started, and insert your change there:

...............................................................................................

[ −x ${PREFIX}/sbin/snmpd ] && ${PREFIX}/sbin/snmpd −D && echo −n ' snmpd'

...............................................................................................

Using Scripts to Manage Running Programs

You can also use these scripts when the system is running. For example, to restart snmpd to make it reread its configuration file, you could run this command:

...............................................................................................

# /usr/local/etc/rc.d/snmpd.sh stop && /usr/local/etc/rc.d/snmpd.sh start

...............................................................................................

NoteIt's not entirely necessary to use the scripts to manage a running program. If you've read the snmpd.sh shell script, you know that to stop the program the script runs the command killall snmpd, and that it starts the program by running snmpd. You could just enter these commands at the command line, and it would have the exact same effect as running the previous script twice. You either have to remember what each script does for its particular program or you have to type the full path to the startup scripts. If you're in doubt, use the scripts!

Managing Shared Libraries

The basic idea behind a shared library is quite straightforward: It's a chunk of compiled code that provides services and functions to other chunks of compiled code. Shared libraries provide popular functions for all programs to use, and they are designed to be reused by as many different programs as possible.

For example, many programs must hash (or one−way encrypt) data as part of their function. But if every program had to include hashing code, each would be larger, harder to write, and more unpleasant to maintain. What's more, programs would have interoperability problems if they implemented hashes differently. By using a shared library (in this example, libcrypt), a program that needs hashing has access to the functions while eliminating problems of maintenance and interoperability. Similarly, other shared libraries provide common functions to support other software. This reduces the average size of programs, freeing up a reasonably large amount of system memory.

FreeBSD builds a cache of available shared libraries at boottime. Programs don't have to scan the whole disk looking for shared libraries; they just ask the cache for the functions they want. In fact, the ability to manage the library cache is one thing that separates a newbie from a professional.

While FreeBSD provides quite a few sensible defaults for the cache, we'll discuss the tools you need to properly configure and manage your cache in all sorts of odd circumstances. Shared libraries are complex beasts. With ldconfig, ldd, and a little bit of thought, you can start to tame

252

them.

Ldconfig

The main tool for managing shared libraries is ldconfig(8). (You'll probably hear all sorts of references to it, in one place or another.) We'll discuss a few different ldconfig−related commands: rtld(1), ldd(1), and ldconfig itself.

Binary Types: Aout and ELF

First we have the issue of binary types: aout and ELF. While as an administrator you don't need to know the details of aout and ELF, you should know that aout is the old standard, ELF is the new standard, and programs compiled as one type cannot use shared libraries of the other type. ELF programs cannot use aoutshared libraries. (The FreeBSD Netscape binary is in aout format, which is why you must install XFree86's aout compatibility libraries to use it.) While aout binaries are slowly vanishing, FreeBSD will need to support both types indefinitely.

When you execute an ELF binary that needs shared libraries, the system calls rtld(1), the "run−time linker." Rtld examines binaries as they're loaded, determines which shared libraries they need, and loads those libraries. There's a separate runtime linker for aout binaries called ld(aout).

Rather than searching the entire system for anything that looks like a shared library everytime anything is executed, rtld pulls the shared libraries from a library cache. The cache lives on your system in two separate files: /var/run/ld.so.hints (aout) and /var/run/ld−elf.so.hints (ELF). A misconfigured cache is the most likely cause of shared library problems.

What Libraries Do You Have?

To see the list of libraries you already have, run ldconfig with the −r flag:

...............................................................................................

# ldconfig −r

/var/run/ld−elf.so.hints: search directories:

/usr/lib:/usr/lib/compat:/usr/X11R6/lib:/usr/local/lib:/usr/local/lib/mysql:/usr/local/pilot/li 0:−lcom_err.2 => /usr/lib/libcom_err.so.2

1:−lscrypt.2 => /usr/lib/libscrypt.so.2 2:−lcrypt.2 => /usr/lib/libcrypt.so.2

...

...............................................................................................

ldconfig −r examines the shared library cache and lists every shared library it finds. On my system, this list runs to 229 shared libraries.

Note If a program complains that it can't find a library, check ldconfig −r. If the library isn't there, your cache is either misconfigured or incomplete, or the library really isn't on your system.

Building the Cache

The cache is built during the system boot process, using ldconfig. For ELF binaries, it's done like this:

253

...............................................................................................

# ldconfig −elf /list/of /path/names/here

...............................................................................................

Similarly, aout uses this:

...............................................................................................

# ldconfig −aout /other/list /of/paths

...............................................................................................

Note The list of path names is set in /etc/rc.conf as ldconfig_paths and ldconfig_paths_aout.

If you're trying to use shared libraries that you've just installed, they won't be in the cache, and programs may fail. In that case, you need to rebuild the cache, and it's fairly easy to do. Just run ldconfig without any arguments, and ldconfig will rescan the directories listed in ldconfig −r and rebuild the cache.

Finding a Library

If the library isn't in one of the directories previously scanned, you need to find it. Generally speaking, if you cut the initial "lib" off the library name and use locate or find / −name libname −print, you should be able to find the file. In the worst case, you'll have to dig through a long list of results to find the library you want.

Adding Libraries

You might find, after you install a piece of software, that you have a new directory of shared libraries. (You'll sometimes find these in a private subdirectory; my PalmPilot software uses /usr/local/pilot/lib, for example.)

It's easy enough to merge a new directory of shared libraries into the existing cache with the −m option. Some ports even use the −m option to configure shared libraries at boot, which eliminates any tedious mucking about in /etc/rc.conf. To merge my Palm library into my existing cache, I would enter this command:

...............................................................................................

# ldconfig −m /usr/local/pilot/lib

...............................................................................................

LD_LIBRARY_PATH

While the −m option works very well if you're the systems administrator, it won't work if you're just a lowly user without root access.[1] Also, if you have your personal set of shared libraries, your sysadmin won't want to make them globally available, and root must own the shared library directory so that regular users can't just dump things in there willy−nilly. Sysadmins probably won't even want to take the slightest chance of system programs linking against your personal libraries.

Here's where the LD_LIBRARY_PATH environment variable appears. Rather than create a cache, LD_LIBRARY_PATH tells the system to check the directories it lists for new shared libraries.

254

Note This isn't at all secure; if you set LD_LIBRARY_PATH to an overly accessible location, your program can link against whatever's there. LD_LIBRARY_PATH also overrides the cache, so be careful what you put in there!

You can specify any number of directories in LD_LIBRARY_PATH, separated with colons. For example, I might want to put the directories /home/mwlucas/lib and /compat/linux/usr/lib/local into my LD_LIBRARY_PATH to complete a software install. I would do this like so:

...............................................................................................

# setenv LD_LIBRARY_PATH /home/mwlucas/lib:/compat/linux/usr/lib/local

...............................................................................................

For example, I generally install StarOffice manually rather than via the port. When I do, the install routine extracts a variety of libraries in /tmp/sv001.tmp and expects to be able to find them when it starts the graphical installer. To make sure that it can find these libraries, I start setup using the LD_LIBRARY_PATH variable to point to the /tmp/sv001.tmp directory, like this:

...............................................................................................

# LD_LIBRARY_PATH /tmp/sv001.tmp ./setup

...............................................................................................

When the graphical StarOffice installer starts, it then checks that directory for extracted libraries. The result is that I don't have to reconfigure my entire FreeBSD system just to use this program.

Note Remember, you can set an environment variable automatically at login by entering it in your .cshrc or .profile file.

What Libraries Do My Programs Need?

Lastly, there's the question of what libraries a program expects to have available. You can get this information with ldd(1). For example, to find out what Emacs needs, enter this command:

...............................................................................................

# ldd /usr/local/bin/emacs

/usr/local/bin/emacs:

libXaw.so.6 => /usr/X11R6/lib/libXaw.so.6 (0x28159000) libXmu.so.6 => /usr/X11R6/lib/libXmu.so.6 (0x2818e000) libXt.so.6 => /usr/X11R6/lib/libXt.so.6 (0x2819f000) libSM.so.6 => /usr/X11R6/lib/libSM.so.6 (0x281e2000) libICE.so.6 => /usr/X11R6/lib/libICE.so.6 (0x281ea000) libXext.so.6 => /usr/X11R6/lib/libXext.so.6 (0x281fe000) libX11.so.6 => /usr/X11R6/lib/libX11.so.6 (0x28209000) libutil.so.3 => /usr/lib/libutil.so.3 (0x282a2000) libm.so.2 => /usr/lib/libm.so.2 (0x282ab000)

libc.so.4 => /usr/lib/libc.so.4 (0x282c6000)

libXThrStub.so.6 => /usr/X11R6/lib/libXThrStub.so.6 (0x28361000)

#

...............................................................................................

This output tells us the names of the shared libraries Emacs requires, and the locations of the files that contain those libraries. You can check this list of required libraries against the output of ldconfig −r to confirm that your program has what it needs. Or you can use this as a shopping list and then go out and get the needed libraries.

255