Note: This post assumes you are already familiar with the socket extensions for IPv6 (RFC 3493).

Linux and Mac
Good news… they both fully support RFC 3493.

Windows
Windows IPv6 support varies based on which version you’re targeting. Microsoft started adding IPv6 in Windows 2000, and they’ve continued adding more of the socket extensions as time went on. Most of the core functionality is present in XP, and what’s missing is easily replaced by using Winsock calls directly (more on this later).

Windows gained IPv6 support while RFC 2553 was still the supported standard. Since then, it has been deprecated by RFC 3493. However, Microsoft doesn’t want to break existing code written against it’s API, so the older API lives on. The main impact of this is that sockaddr_in6 and sockaddr_storage are slightly different on Windows than Mac and Linux. The size of the structures across platforms is the same (the sa_family_t member was shortened), it’s just that the Windows structures don’t begin with the length member. For example:

// Linux and Mac
struct sockaddr_in6 {
    uint8_t      sin6_len;    /* Added in RFC 3493 */
    sa_family_t  sin6_family;
    ...
};
struct sockaddr_storage {
    uint8_t      ss_len;      /* Added in RFC 3493 */
    sa_family_t  ss_family;
    ...
};

// Windows
struct sockaddr_in6 {
    sa_family_t  sin6_family;
    ...
};
struct sockaddr_storage {
    sa_family_t  ss_family;
    ...
};

I’ve never had a problem with this, because the size of sockaddr_in6 is easily determined (sizeof(sockaddr_in6)) and I always end up casting sockaddr_storage to the specific type (sockaddr_in or sockaddr_in6) based on ss_family.

Besides the data structure differences, it’s important to remember that Microsoft added IPv6 support over multiple versions. Support first appeared in Windows 2000, but more of the extensions have been added over time. Most of the core functionality was present in XP (including multicast), but not everything is implemented as of Windows 7. It’s annoying, but I will say that what’s missing is easily replaced by using Winsock calls directly.

Here’s the breakdown of IPv6 socket extensions by Windows version:

As you can see, you may still have to call Winsock directly depending on what version of Windows you are targeting. In my opinion, programming IPv6 on Windows is a lot easier if you only support XP and later, but I know that’s not always possible.

Summary

Modern operating systems all support IPv6. However, for business reasons, Windows has a slightly older version of the socket API which requires special consideration. My goal was to enumerate those differences to help make the transition to IPv6 smoother. Writing cross-platform code can be a fun challenge at times, but it’s also a little tedious. Hopefully, this post helps ease the pain.

There are many pages describing how to resample audio using the ffmpeg command line application, but what about doing resampling in your own program? To do that, you need to use the avcodec library (libavcodec.so on Linux and avcodec.dll on Windows).

1. Include avcodec.h
2. Call avcodec_init() to initialize the FFMpeg library.
3. Create a resampling context using av_resample_init() that describes how you want the resampling done.
4. Call av_resample() to do the actual resampling on your audio buffer.
5. When you’re done with the resampling context, delete it with av_resample_close().
6. Finally, link your application against avcodec, avutil, and zlib (it won’t work on Linux without this one).

Here it is in pseudocode:

#include "libavcodec/avcodec.h"

avcodec_init();

struct AVResampleContext* ctx = av_resample_init( ... );

av_resample( ctx, ... );

av_resample_close( ctx );

That’s it… seriously!

Sample Code (Linux):

Here’s a sample program I wrote that takes a raw 44.1kHz/16bit/mono audio file and plays it back using the pulseaudio API. The catch is that it allows you to specify a “skew” parameter which will cause the audio to dynamically speed up and slow down (via resampling). The amount of resampling is controlled by a sine wave, which is what drives the speed changes.

Download: resample.tar.bz

To unpack and build, type:

$ tar -xjvf resample.tar.bz
$ make

First, run the sample with no skew:

$ ./resample audio_16b_44k_mono_pcm_raw 0

Now, try it with a heavy skew:

$ ./resample audio_16b_44k_mono_pcm_raw -10000

ThreadNinja is a Linux library my team created that tracks pthread_create() and pthread_join() calls in an application. It prints a stacktrace where each thread is created and where it is joined. Any rogue (unjoined) threads are reported when the application exits. ThreadNinja is unobtrusive: it does NOT have to be compiled into the code. This means you can use it on applications you didn’t compile.

We found it useful and thought we’d share it. It’s be no means production code… just a tool. Hack on it, expand it, change it… whatever. It’s pretty small, so it should be easy to dive right in. We’ve released it under the BSD license.

Cut To The Chase

You can checkout the source code from Google Code, or download the version 1.0 tarball directly (threadninja.tar.gz).

To build ThreadNinja, simply untar it and call make:
> tar -zxf threadninja.tar.gz
> make

Now, simply use LD_PRELOAD to run the application:

> LD_PRELOAD=/path/to/threadninja/build/libthreadninja.so.1 TheApplication

If you don’t see function names in the stacktraces that are generated, then the application needs to be compiled with debug symbols. For my test app, I had to compile with the -rdynamic option:

> g++ -Wall -rdynamic main.cpp -lpthread

This causes the global symbol table to be included in the executable, which contains all the application’s function names. For more info, look at the --export-dynamic option on the GNU linker (ld) man page.

The Story Behind ThreadNinja

My team was assigned to stabilize a large video application that runs as a Linux-based appliance. The application consisted of 100,000+ of lines to code that was a tangle of build warnings, circular references, and many creative hacks. Our particular task was to fix a persistent set of seg-faults and memory leaks.

One of the first things we noticed was that the application didn’t shutdown properly. The shutdown logic was something akin to: signal components to exit, sleep 2 seconds, call Release() a couple times to clean up extra ref-counts, sleep 2 seconds, and then just call exit() to get the process to terminate (bypassing the remaining clean up code). Of course, this renders Valgrind useless when trying to find memory leaks, because the automatic memory cleanup code gets bypassed during the process abort.

As a result, our first priority was to get the app to shutdown cleanly. The first issue we ran into was that pthread_join() blocked indefinitely because threads were failing to terminate. We tried using GDB to track the threads, but many hundreds of threads were being created and destroyed dynamically. We needed a way to let the application run for hours, allow 1000+ threads to live and die, and still be able to track rogue threads. Hence, ThreadNinja was born.

How It Works

Through the magic of LD_PRELOAD, ThreadNinja “injects” itself between all calls to pthread_create() and pthread_join(). This happens because LD_PRELOAD instructs the loader to load ThreadNinja into memory first, before other libraries (in this case, before the pthread library). The result is that ThreadNinja’s implementation of pthread_create() and pthread_join() are used by the application instead of pthread’s own implementation. What ThreadNinja does is track the calls to these methods and then pass the call on to the “real” pthread implementation. From the application’s point-of-view, the behavior of the thread methods are the same… the tracking is transparent.

Output

Each time pthread_create() is called, a stacktrace and timestamp are printed to stdout:

Thread Created: 3047947120
[bt] Thu Jul 8 16:31:23 2010

[bt] ./a.out(StartService(unsigned long*, int))
[bt] ./a.out(Initialize())
[bt] ./a.out(main+0xb) [0x80489fa]
[bt] /lib/libc.so.6(__libc_start_main+0xe6) [0xb5bbb6]
[bt] ./a.out() [0x8048811]

The first line (“Thread Created”) gives the value of the pthread_t handle, so you can later track where rogue threads where created. The next line is the time when the create happened. The remaining lines are the call stack that led to the pthread_create() call.

Each time pthread_join() is called, similar information is printed to stdout:

Thread Joined: 3047947120
[bt] Thu Jul 8 16:31:31 2010

[bt] ./a.out(Terminate())
[bt] ./a.out(main+0x10) [0x80489ff]
[bt] /lib/libc.so.6(__libc_start_main+0xe6) [0xb5bbb6]
[bt] ./a.out() [0x8048811]

When the application terminates (cleanly or uncleanly), a summary of the current state of the application threads is printed:

exit_handler()
[Thread Summary]
Total Created: 573
Total Joined: 568
Total Running: 5

In this case, you’ll notice that 5 threads were never joined on.

Limitations

ThreadNinja only tracks calls to pthread_create() and pthread_join(). This means calls like system(), exec(), and fork() are not tracked. Also, calls to pthread_cancel() are not tracked. We had started adding code to track pthread mutexes and stuff, but it turned out we didn’t need it. Feel free to add support for all this stuff and submit changes to the Google code site.

Happy coding!

Note: I’m talking here about interval timing (i.e. accurately measuring the duration between 2 events). This is different than synchronizing different clocks or maintaining accurate wall time.

Anatomy of the Clock

The first mistake most people make when doing timing is to use functions like gettimeofday(), GetSystemTime(), etc. These functions return what is called “wall time”… time that corresponds to a calendar date/time. These clocks suffer from the follow limitations:

1. They have a low resolution: “High-performance” timing, by my definition, requires clock resolutions into the microseconds or better.
2. They can jump forwards and backwards in time: Computer clocks all tick at slightly different rates, which causes the time to drift. Most systems have NTP enabled which periodically adjusts the system clock to keep them in sync with “actual” time. The adjustment can cause the clock to suddenly jump forward (artificially inflating your timing numbers) or jump backwards (causing your timing calculations to go negative or hugely positive).

For interval timing, all that’s needed for a clock is a simple counter that increments at a stable rate. For high-performance timing, the rate this counter increments should be high. A related constraint is that the counter must be monotonic (can never “tick” backwards… ever). The counter may overflow and wrap back to 0, but using unsigned math in your timing calculations can compensate for that (see example below).

Something to note: since we are usually measuring short durations, the drift of the clock is so small that we aren’t concerned by it (what matters is the drift between successive reads, not total drift over time).

Using the Clock

To use the clock, you need access to 2 pieces of information: the clock value, and the rate (frequency) at which it increments. Once you have that information, it’s trivial to calculate the duration between 2 successive reads of the clock.

For example, consider the following:

-        start equals the clock value at the beginning of the interval to measure.

-        end equals the clock value at the end of the interval.

-        frequency equals the frequency that the clock increments per second.

Calculating the duration of the interval (in seconds) is as simple as:

duration = (end – start) / frequency

duration will equal the floating-point interval time in seconds (e.g. 0.000237 = 237us).

A common use case I’ve seen is wanting to measure the duration between successive calls to a function. Here’s one way to implement that:

float freq = (float) get_frequency();

Foo()
{
    unsigned now = read_clock();
    float duration = (float)(now – last) / (float)freq;
    last = now;

    /* Your code here */
}

It is important to use unsigned variables for now and last or your calculations will go haywire if the clock ever wraps back to 0. Consider what happens if now is less than last. Using unsigned variables allows the math operation to underflow, which produces the correct result. If you don’t believe me, just write some test code and see for yourself… it’s an important concept to understand.

Don’t Use RDTSC As Your Clock

I’m dismayed by how many forum posts suggest that newbie’s use RDTSC for timing. Don’t get me wrong; the TSC isn’t bad in-and-of-itself. It’s just way too hard to get timing right with it unless you’re an expert… and if you’re reading this, chances are you aren’t . Stick to the higher level API’s I present below.

Even if you are an expert, I still suggest avoiding RDTSC for the following reasons:

1. It’s processor core specific: Using RDTSC will give different values on different processor cores. This causes non-monotonic clock behavior as a thread is migrated across cores during execution (i.e. the clock can tick backwards on two successive reads). Conversely, the clock may also appear to jump forwards if the thread moves to a different core.
2. It doesn’t always tick at the same rate: On some systems, the clock frequency will vary as the CPU load changes. This is due to power saving features in the processor that throttle down the clock speed when the load is low (e.g. Intel SpeedStep).
3. It’s unnecessary: there are better alternatives to RDTSC that are readily available (HPET and APIC).

“Game Timing and Multicore Processors” has more info, though it’s centered around Windows.

“Guidelines For Providing Multimedia Support” has a good summary of the hardware clocks on the PC platform, and justification for the creation of the HPET.

A more technical look into the past problems with RDTSC can be found in this email from Rick Brunner (AMD Fellow).

If you’re having trouble sleeping, you can look at Intel’s HPET design document.

Linux Clock

POSIX.1b defines realtime clock methods that you’ll find on most *NIX systems (the full spec can be viewed HERE). Specifically, you want to use clock_getres() and clock_gettime(). clock_getres() returns the resolution (frequency) of the clock, and clock_gettime() returns the current value of the clock. Most systems implement the CLOCK_MONOTONIC type, which provides a frequency-stable, monotonically-increasing counter. The resolution of CLOCK_MONOTONIC is high on the 2.6 kernel, in my experience. I recommend using this clock when building a high-performance timing solutions on Linux.

The methods are defined in time.h, and you need to link against librt (pass ‘-lrt’ to gcc). The prototypes for the functions are:

int clock_getres(clockid_t clock_id, struct timespec *res);
int clock_gettime(clockid_t clock_id, struct timespec *tp);

A detailed description of these methods can be found HERE.

I also suggest looking at clock_nanosleep(), but that’s a separate topic.

Windows Clock

On Windows, QueryPerformanceFrequency() and QueryPerformanceCounter() are the obvious choice. QueryPerformanceFrequency() returns (surprise!) the frequency of the counter. QueryPerformanceCounter() returns the current value of the counter. Just like CLOCK_MONOTONIC on Linux, the Windows performance counter is a high-frequency, stable, monotonically-increasing counter.

The methods are defined in windows.h. The prototypes are:

BOOL QueryPerformanceFrequency(LARGE_INTEGER *lpFrequency);
BOOL QueryPerformanceCounter(LARGE_INTEGER *lpPerformanceCount);

Windows Timing Errata

Note: The follow items do NOT affect the resolution of the Window’s performance counter, but I think it’s still important to know when doing timing on Windows.

One problem you may run into on Windows is that the default system clock interval defaults to 10 or 15ms (depending of the OS version). This clock is what drives all the timers and sleep functions for that platform. What this means is that, left to the default, your timers will trigger 5 to 7.5ms late, on average.

You can fix this by increasing the system clock resolution to 2ms (I remember reading a tech article by Microsoft saying that 2ms gave better system performance than 1ms, but I can’t find it for the life of me). You do this by using the timeGetDevCaps(), timeBeginPeriod() and timeEndPeriod(). Sample code can be found HERE. You have to include mmsystem.h and link against Winmm.lib.

I feel it necessary to note that increasing the system clock interval negatively affects power consumption. The Windows 7 blog as an interesting breakdown of “Windows 7 Energy Efficiency”. Specifically, they noticed a 10% drop in battery life when the clock resolution was set to 1ms using timeBeginPeriod().

Maybe this last section belongs in a separate post, but whatever…

Looking at the logs, we found that our audio pipeline was failing to open /dev/dsp on the restart. We then used lsof to list the open file descriptors to see which process currently held /dev/dsp:

# lsof | grep /dev/dsp
ntpd   18857    root   16u    CHR     14,3    180099 /dev/dsp


What!?!?… why the heck is NTP opening the sound device and how did it steal it from us??? After some discussion we started remembering a problem in the past with ntpd stealing our SNMP diagnostics port. This just didn’t make any sense.

Digging into our appliance code, we found this line:

system( "service ntpd restart" );

This would be called each time we were notified by the security system that the NTP server address had changed (which fired once each time the process was started so we could get the initial address). But this still didn’t explain why NTP took over ownership of our file descriptors on restart.

Long story short: system() is implemented as fork() followed by execv(). By default, fork() gives a copy of the parent’s file descriptors to the child process (i.e. the ntpd child process got a copy of the /dev/dsp file descriptor). To prevent this, you have to set the FD_CLOEXEC flag on the file desciptors you don’t want copied.

For example:

fd = open( "/dev/dsp", O_RDWR );
fcntl( fd, F_SETFD, FD_CLOEXEC );

Conclusion: setting the FD_CLOEXEC flag on the /dev/dsp file descriptor fixed the problem for audio. However, most of the other file desciptors still got owned by ntpd. Did we go back and set the FD_CLOEXEC flag on all file descriptors, you ask? Nope. It turns out we had a script monitoring the NTP config file and restarting ntpd for us when the file got updated… we just had to update the config file and remove the system( "service ntpd restart" ) call.

Oh, and the reason audio worked on first boot but not subsequent restarts was due to a weird race condition around when /dev/dsp got opened.

find . -name “*.cpp” -print

Then I piped the files to ‘sed’ via ‘xargs’ (Note: replace the ‘-e’ with ‘-i’ to actually modify the files inline):

find . -name “*.cpp” -print | xargs sed -e ‘/STRING_TO_INGORE/! { d }’

The trick is adding the ‘!’ (exclamation point) after the search expression. Without it, ‘sed’ would think you only want lines with the string, not without it.

This is different than another syntax I’ve seen used: /(?!STRING_TO_IGNORE)/.

Here’s another example. Say you want to replace STRING1 with STRING2 only if the first characters of the line (ignoring white space) are NOT “//”… i.e. skip the string replacement in code comments:

sed -i ‘/^[ \t]*\/\/.*/! { s/STRING1/STRING2/ }’

NOTE: ‘[ \t]*’ means ignore 0 or more spaces or tabs.

find . -name “*.cpp” -print | xargs sed -i ‘s/[find]/[replace]/g’

where “[find]” and “[replace]” are the things you are searching for and substituting.

To search files with multiple file extensions, use:

find . -name “*.cpp” -o -name “*.h” -o -name “*.c” | xargs sed -i ‘s/[find]/[replace]/g’

ADDED 4-13-2009: See comments for other variations.

rm -rf `find . -type d -name .svn`

NOTE: Those are back ticks around the ‘find’ command, not apostrophes. I recommend you just run the ‘find’ command first and verify it is listing the directories you expect.

First, you need to include execinfo.h to your code:

#include <execinfo.h>

Next, call the backtrace() function to get an array of void pointers that represents the current stack (the pointers are the return addresses for each stack frame).

void* tracePtrs[100];
int count = backtrace( tracePtrs, 100 );

The backtrace() function returns the number of entries in the array (read the man pages for more info about the array size).

Finally, you need to resolve the function names associated with the pointers. You have 2 options: backtrace_symbols() and backtrace_symbols_fd(). Both of these methods resolve the pointers to strings, but the difference is that backtrace_symbols() allocates the strings on the heap while backtrace_symbols_fd() writes the strings to a file descriptor that you can read. Just keep in mind that backtrace_symbols() won’t work if the heap has been trashed.

Here’s an example using backtrace_symbols():

char** funcNames = backtrace_symbols( tracePtrs, count );

// Print the stack trace
for( int ii = 0; ii < count; ii++ )
    printf( "%s\n", funcNames[ii] );

// Free the string pointers
free( funcNames );

NOTE: Make sure you call free() on the array of strings returned from backtrace_symbols().

For more information, here’s a good article from the Linux Journal.

• 500 x 750 JPEG
• 500 x 750 PNG

Breakpoint Basics:

Setting a breakpoint in GDB is supposed to be simple. Here we set a breakpoint at line 50 in file main.cpp:

(gdb) b main.cpp:50
Breakpoint 1 at 0x804937a: file main.cpp, line 50.

We can also use the function name and GDB will attempt to find the correct location for us:

(gdb) b DoSomething
Breakpoint 2 at 0×8049334: file main.cpp, line 150

Simple, right? Just wait…

Breakpoint Gotchas:

GDB’s breakpoint logic is pretty handy for simple projects, but it can break down fast when things get more complicated.

For example, let’s say your application is plugin-driven, with each plugin being a separate library. Now assume each plugin has a Plugin.cpp file under it’s own Source directory. Try to set a breakpoint in the Initialize() method of the Plugin class:

(gdb) b Initialize
Breakpoint 3 at 0×8049717: file main.cpp, line 230

Oops! There is an Initialize() method in main.cpp and GDB thought that’s where we wanted to put it: wrong!

Okay, let’s be more specific:

(gbd) b Plugin::Initialize
Breakpoint 4 at 0×8046194: file Source/Plugin.cpp, line 89

Okay, that looks better, but which Plugin.cpp file did GDB put the breakpoint? How do we know it’s the file for the plugin we want?

If we used namespaces, then we can get more specific:

(gdb) b MY_PLUGIN_A::Plugin::Initialize
Breakpoint 5 at 0×8050039: file Source/Plugin.cpp, line 130

We can see from the address and line number that the previous breakpoint was at the wrong place. Okay, moving on…

Setting Breakpoint in Templates:

Templates can be much harder to set breakpoints in because we have to specify the exact prototype for the fully-defined template. We as programmers are used to the compiler handling the template type stuff for us, so it can be difficult to guess the correct type.

For example, assume we have some abstract class BarAbstract that uses the template Foo<> to make it concrete. Now assume we’re really clever and we want to hide this from the users of our class. We could use a typedef to hide the true type:

typedef Foo<BarAbstract> Bar;

Now, all the user needs to do is instantiate Bar without a thought to the Foo<> template.

int DoSomething()
{
Bar b;
return b.Baz();
}

So far so good? Okay, now how the heck do you set a breakpoint in the Baz() method of class Bar?

The quick answer: use objdump, c++filt, and grep to find the complete definition that GDB will need.

$ objdump -t libMyLib.so | c++filt | grep ‘BarAbstract.*Baz’
0000d2d6 w F .text 0000000a     MY_PLUGIN_A::Foo<MY_PLUGIN_A::BarAbstract>::Baz()

Now, simply copy-n-paste the full method definition to GDB when setting the breakpoint:

(gdb) b MY_PLUGIN_A::Foo<MY_PLUGIN_A::BarAbstract>::Baz()
Breakpoint 6 at 0×8048890: file Source/Bar.cpp, line 355

That’s it! Happy debugging!

First, I made sure to disable access control from outside the chroot (warning: make sure you understand the security implications of this!):

[dev]$ xhost + localhost
localhost being added to access control list

Next, I entered the chroot’d environment and attempted to run the application, but it failed with the following error:

[chroot]$ valkyrie
valkyrie: cannot connect to X server 127.0.0.1:0.0

The problem is that the X server is configured by default NOT to listen for remote connections (usually on port 6000). I verified that this was the problem by leaving the chroot and trying to connect via telnet:

[dev]$ telnet 127.0.0.1 6000
Trying 127.0.0.1…
telnet: connect to address 127.0.0.1: Connection refused

The way to fix this on previous Fedora installations was to use gdmsetup. However, this is no longer available. Hunting through the KDE config files I found the solution: change the arguments passed to the X server after login in the kdmrc file.

NOTE: I’m using fluxbox as my desktop environment… KDE is used for the Fedora login screen, which is why we are messing with its config files.

[dev]$ sudo su
[root]# cd /etc/kde/kdm
[root]# cp kdmrc kdmrc.old
[root]# vi kdmrc

On my system, the problem was this line:

ServerArgsLocal=-br -nolisten tcp

I simply changed it to:

ServerArgLocal=-br

I restarted my X server and tried to connect with telnet again (this time with success):

[dev]$ telnet 127.0.0.1 6000
Trying 127.0.0.1…
Connected to 127.0.0.1.
Escape character is ‘^]’.

Then, I once again disabled X access control (`xhost + localhost`) and everything worked fine. Hope this helps!

EDITED 11/17/2008: Changed ‘xhost +’ to ‘xhost + localhost’

1. Set the hostname: `# hostname <hostname>`
2. Add ‘HOSTNAME=<hostname>’ to ‘/etc/sysconfig/network’ (makes the change permanent).
3. Add ‘DHCP_HOSTNAME=<hostname>’ to ‘/etc/sysconfig/network-scripts/ifcfg-eth0′
4. Restart the networking service: `# service network restart`

Volia! Now you can connect to your box via hostname.

References:

• Configuring Linux Static DHCP Clients by Sending Host Name
• Linux setting hostname and domain name of my server

(requires Adobe Flash plugin… click HERE to watch it on YouTube)

I found this information interesting:

• The application code is written mostly in Python (the web app is not the bottleneck… the database RPC is)
• They use Apache for page content and lighttpd for serving video
• Thumbnails are now served by Google’s BigTable
• They’re running SuSE Linux with MySQL
• HW RAID-10 across multiple disks was too slow. HW RAID-1 with SW RAID-0 was faster because the Linux I/O scheduler could see the multiple volumes and would therefore schedule more I/O

You can read a good summary of the talk HERE from the High Scalability website.

TechCruch has a good article of the YouTube API.

When writing a shared library, it is sometimes useful to have a set of functions that get called when the library is loaded and unloaded. In Windows, this is done by implementing the DllMain function. This function is called by the loader whenever a DLL is loaded or unloaded into the address space of a process (and also when the process creates a new thread, but it is less common to handle this case). A value is passed in as an argument to the DllMain function that indicates which event is occurring: DLL load or unload.

On Linux, one must use the GCC __attribute__((constructor)) and __attribute__((destructor)) keywords (double underscores before and after) to explicitly declare functions to be called on load and unload. These keywords cause the compiler/linker to add the specified functions to the __CTOR_LIST__ and __DTOR_LIST__ (“ConstrucTOR LIST” and “DestrucTOR LIST” respectively) in the object file. Functions on the __CTOR_LIST__ are called by the loader when the library is loaded (either implicitly or by dlopen()). The main purpose for this list is to call the constructors on global objects in the library. Conversely, functions on the __DTOR_LIST__ are called when the library is unloaded (either implicitly or by dlclose()). By adding initialization and clean-up functions to this list, one can effectively replicate the DllMain functionality on Linux.

NOTE: There are many ways to “shoot yourself in the foot” with these methods (on both Windows and Linux) because certain things aren’t available to your library until loading is complete. Don’t use these methods unless you have a real need… just export an Initialize() and Destroy() function instead, and force the consuming application to call them. Please read the “Gotcha’s” section below.

External Resources:

• MSDN: DllMain
• Misc. Linux Library Information
• Extended GCC Features
• Dynamic Linking on Linux and Windows

Example: Linux

Example: Windows

Gotcha’s

Linux

From www.dwheeler.com:

Shared libraries must not be compiled with the gcc arguments “-nostartfiles” or “-nostdlib”. If those arguments are used, the constructor/destructor routines will not be executed (unless special measures are taken).

Windows

From Microsoft’s MSDN page on DllMain:

The entry-point function should perform only simple initialization or termination tasks. It must not call the LoadLibrary or LoadLibraryEx function (or a function that calls these functions), because this may create dependency loops in the DLL load order. This can result in a DLL being used before the system has executed its initialization code. Similarly, the entry-point function must not call the FreeLibrary function (or a function that calls FreeLibrary) during process termination, because this can result in a DLL being used after the system has executed its termination code.

Because Kernel32.dll is guaranteed to be loaded in the process address space when the entry-point function is called, calling functions in Kernel32.dll does not result in the DLL being used before its initialization code has been executed. Therefore, the entry-point function can call functions in Kernel32.dll that do not load other DLLs. For example, DllMain can create synchronization objects such as critical sections and mutexes, and use TLS. Unfortunately, there is not a comprehensive list of safe functions in Kernel32.dll.

Windows 2000: Do not create a named synchronization object in DllMain because the system will then load an additional DLL. This restriction does not apply to subsequent versions of Windows.

Calling functions that require DLLs other than Kernel32.dll may result in problems that are difficult to diagnose. For example, calling User, Shell, and COM functions can cause access violation errors, because some functions load other system components. Conversely, calling functions such as these during termination can cause access violation errors because the corresponding component may already have been unloaded or uninitialized.

Because DLL notifications are serialized, entry-point functions should not attempt to communicate with other threads or processes. Deadlocks may occur as a result.

For information on best practices when writing a DLL, see http://www.microsoft.com/whdc/driver/kernel/DLL_bestprac.mspx.

If your DLL is linked with the C run-time library (CRT), the entry point provided by the CRT calls the constructors and destructors for global and static C++ objects. Therefore, these restrictions for DllMain also apply to constructors and destructors and any code that is called from them.