C++ Dynamic Shared Library on Linux

Question

This is a follow-up to Dynamic Shared Library compilation with g++.

I'm trying to create a shared class library in C++ on Linux. I'm able to get the library to compile, and I can call some of the (non-class) functions using the tutorials that I found here and here. My problems start when I try to use the classes that are defined in the library. The second tutorial that I linked to shows how to load the symbols for creating objects of the classes defined in the library, but stops short of using those objects to get any work done.

Does anyone know of a more complete tutorial for creating shared C++ class libraries that also shows how to use those classes in a separate executable? A very simple tutorial that shows object creation, use (simple getters and setters would be fine), and deletion would be fantastic. A link or a reference to some open source code that illustrates the use of a shared class library would be equally good.

---

Although the answers from codelogic and nimrodm do work, I just wanted to add that I picked up a copy of Beginning Linux Programming since asking this question, and its first chapter has example C code and good explanations for creating and using both static and shared libraries. These examples are available through Google Book Search in an older edition of that book.

Desk

I'm not sure I understand what you mean by "using" it, once a pointer to the object is returned, you could use it like you use any other pointer to an object. – Haden

The article I linked to shows how to create a function pointer to an object factory function using dlsym. It doesn't show the syntax for creating and using objects from the library. – Desk

You will need the header file describing the class. Why do you think you have to use "dlsym" instead of just letting the OS find and link the library at load time? Let me know if you need a simple example. – Toe

@nimrodm: What's the alternative to using "dlsym"? I'm (supposed to be) writing 3 C++ programs that will all use the classes defined in the shared library. I also have 1 Perl script that will use it, but that's a whole other problem for next week. – Desk

Answer 1

myclass.h

#ifndef __MYCLASS_H__
#define __MYCLASS_H__

class MyClass
{
public:
  MyClass();

  /* use virtual otherwise linker will try to perform static linkage */
  virtual void DoSomething();

private:
  int x;
};

#endif

myclass.cc

#include "myclass.h"
#include <iostream>

using namespace std;

extern "C" MyClass* create_object()
{
  return new MyClass;
}

extern "C" void destroy_object( MyClass* object )
{
  delete object;
}

MyClass::MyClass()
{
  x = 20;
}

void MyClass::DoSomething()
{
  cout<<x<<endl;
}

class_user.cc

#include <dlfcn.h>
#include <iostream>
#include "myclass.h"

using namespace std;

int main(int argc, char **argv)
{
  /* on Linux, use "./myclass.so" */
  void* handle = dlopen("myclass.so", RTLD_LAZY);

  MyClass* (*create)();
  void (*destroy)(MyClass*);

  create = (MyClass* (*)())dlsym(handle, "create_object");
  destroy = (void (*)(MyClass*))dlsym(handle, "destroy_object");

  MyClass* myClass = (MyClass*)create();
  myClass->DoSomething();
  destroy( myClass );
}

On Mac OS X, compile with:

g++ -dynamiclib -flat_namespace myclass.cc -o myclass.so
g++ class_user.cc -o class_user

On Linux, compile with:

g++ -fPIC -shared myclass.cc -o myclass.so
g++ class_user.cc -ldl -o class_user

If this were for a plugin system, you would use MyClass as a base class and define all the required functions virtual. The plugin author would then derive from MyClass, override the virtuals and implement create_object and destroy_object. Your main application would not need to be changed in any way.

Haden

I'm in the process of trying this, but just have one question. Is it strictly necessary to use void*, or could the create_object function return MyClass* instead? I'm not asking you to change this for me, I'd just like to know if there's a reason to use one over the other. – Desk

It can be MyClass*, no reason for it to be void*, I've updated it. – Haden

Thanks, I tried this and it worked as is on Linux from the command line (once I made the change you suggested in the code comments). I appreciate your time. – Desk

Is there any reason you would declare these with extern "C"? As this is compiled using a g++ compiler. Why would you want to use c naming convention? C can not call c++. A wrapper interface written in c++ is the only way to call this from c. – Atonal

@Atonal you need the extern "C" because the dlsym function is a C function. And to dynamically load the create_object function, it will use C-style linkage. If you wouldn't use the extern "C", there would be no way of knowing the name of the create_object function in the .so file, because of name-mangling in the C++ compiler. – Gatlin

Looks like the cast in MyClass* myClass = (MyClass*)create(); isn't necessary (anymore). Somewhat strange that none of the the previous 49K viewers noticed it :) Or am I wrong? Also, wouldn't it be nice to hint the readers on why the client code will not even link had it tried to call the constructor, while calling a virtual function is ok (the answer would also clarify the cryptic-looking comment on linker's tastes :))? – Mihalco

Nice method, it's very similar to what someone would do on a Microsoft compiler. with a bit of #if #else work, you can get a nice platform independent system – Gustafsson

I know this is old (I nearly said "three years", but then I realized it's more like nearly 5 years), but it's important to call dlclose on the handle. Please add that. – Obed

The function ptrs are a bit messy – Dantedanton

is -fPIC necessary? – Jacobi

Why is destroy_object function needed? Can we just call delete myClass in main? – Rondarondeau

No explanation whatsoever on the compilation commands and the flags. If someone could elaborate and edit the answer it would be awesome. – Aeronautics

The -fPIC (Position Independent Code) flag is necessary because you can't require the shared library to provide the things in its interface at a specific address. Havinc PIC allows for different versions of the library to work even though all the addresses of functions etc are different. The -shared flag lets the linker know to make it a .so (shared object) instead of an .a (static library). See gcc.gnu.org/onlinedocs/gcc/Link-Options.html#Link-Options for details. – Uxorious

You don't need to write extern "C" for every function. Just wrap all the functions in an extern "C" { ... } block – Unaccompanied

Answer 2

The following shows an example of a shared class library shared.[h,cpp] and a main.cpp module using the library. It's a very simple example and the makefile could be made much better. But it works and may help you:

shared.h defines the class:

class myclass {
   int myx;

  public:

    myclass() { myx=0; }
    void setx(int newx);
    int  getx();
};

shared.cpp defines the getx/setx functions:

#include "shared.h"

void myclass::setx(int newx) { myx = newx; }
int  myclass::getx() { return myx; }

main.cpp uses the class,

#include <iostream>
#include "shared.h"

using namespace std;

int main(int argc, char *argv[])
{
  myclass m;

  cout << m.getx() << endl;
  m.setx(10);
  cout << m.getx() << endl;
}

and the makefile that generates libshared.so and links main with the shared library:

main: libshared.so main.o
    $(CXX) -o main  main.o -L. -lshared

libshared.so: shared.cpp
    $(CXX) -fPIC -c shared.cpp -o shared.o
    $(CXX) -shared  -Wl,-soname,libshared.so -o libshared.so shared.o

clean:
    $rm *.o *.so

To actual run 'main' and link with libshared.so you will probably need to specify the load path (or put it in /usr/local/lib or similar).

The following specifies the current directory as the search path for libraries and runs main (bash syntax):

export LD_LIBRARY_PATH=.
./main

To see that the program is linked with libshared.so you can try ldd:

LD_LIBRARY_PATH=. ldd main

Prints on my machine:

  ~/prj/test/shared$ LD_LIBRARY_PATH=. ldd main
    linux-gate.so.1 =>  (0xb7f88000)
    libshared.so => ./libshared.so (0xb7f85000)
    libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0xb7e74000)
    libm.so.6 => /lib/libm.so.6 (0xb7e4e000)
    libgcc_s.so.1 => /usr/lib/libgcc_s.so.1 (0xb7e41000)
    libc.so.6 => /lib/libc.so.6 (0xb7cfa000)
    /lib/ld-linux.so.2 (0xb7f89000)

Toe

This appears (to my very untrained eye) to be statically linking libshared.so to your executable, rather than using dynamic linking at run-time. Am I correct? – Desk

No. This is standard Unix (Linux) dynamic linking. A dynamic library has the extension ".so" (Shared Object) and is linked with the executable (main in this case) at load time -- every time main is loaded. Static linking occurs at link time and uses libraries with the extension ".a" (archive). – Toe

This is dynamically linked at build time. In other words you need prior knowledge of the library you're linking against (e.g. linking against 'dl' for dlopen). This is different from dynamically loading a library, based on say, a user specified filename, where prior knowledge is not needed. – Haden

Build time? What exactly do you mean by build? The library is linked in when 'main' is loaded. This is handled by the linux dynamic linker (ld-linux.so - last in the dependency list). Replacing libshared.so with a newer library will work automatically. No need to recompile/re-link (rebuild?) – Toe

Thank you, I did finally get this to work. I also verified that the shared library is loaded at run time. Pretty simple to verify by just deleting the library and running main. :) – Desk

What I was trying to explain (badly) is that in this case, you need to know the name of the library at build time (you need to pass -lshared to gcc). Usually, one uses dlopen() when that information is not available, i.e. the library's name is discovered at runtime (eg: plugin enumeration). – Haden

Use -L. -lshared -Wl,-rpath=$$(ORIGIN) when linking and drop that LD_LIBRARY_PATH=.. – Putout

Answer 3

On top of previous answers, I'd like to raise awareness about the fact that you should use the RAII (Resource Acquisition Is Initialisation) idiom to be safe about handler destruction.

Here is a complete working example:

Interface declaration: Interface.hpp:

class Base {
public:
    virtual ~Base() {}
    virtual void foo() const = 0;
};

using Base_creator_t = Base *(*)();

Shared library content:

#include "Interface.hpp"

class Derived: public Base {
public:
    void foo() const override {}
};

extern "C" {
Base * create() {
    return new Derived;
}
}

Dynamic shared library handler: Derived_factory.hpp:

#include "Interface.hpp"
#include <dlfcn.h>

class Derived_factory {
public:
    Derived_factory() {
        handler = dlopen("libderived.so", RTLD_NOW);
        if (! handler) {
            throw std::runtime_error(dlerror());
        }
        Reset_dlerror();
        creator = reinterpret_cast<Base_creator_t>(dlsym(handler, "create"));
        Check_dlerror();
    }

    std::unique_ptr<Base> create() const {
        return std::unique_ptr<Base>(creator());
    }

    ~Derived_factory() {
        if (handler) {
            dlclose(handler);
        }
    }

private:
    void * handler = nullptr;
    Base_creator_t creator = nullptr;

    static void Reset_dlerror() {
        dlerror();
    }

    static void Check_dlerror() {
        const char * dlsym_error = dlerror();
        if (dlsym_error) {
            throw std::runtime_error(dlsym_error);
        }
    }
};

Client code:

#include "Derived_factory.hpp"

{
    Derived_factory factory;
    std::unique_ptr<Base> base = factory.create();
    base->foo();
}

Note:

• I put everything in header files for conciseness. In real life you should of course split your code between .hpp and .cpp files.
• To simplify, I ignored the case where you want to handle a new/delete overload.

Two clear articles to get more details:

• C++ dlopen mini how-to
• C++ Dynamic Loading of Shared Objects at Runtime

Hepatica

This is an excellent example. RAII is definitely the way to go. – Among

Why not std::unique_ptr<void, void(*)(void *)> handle (or an explicit dlcloser functor)? – Amharic

Answer 4

Basically, you should include the class' header file in the code where you want to use the class in the shared library. Then, when you link, use the '-l' flag to link your code with the shared library. Of course, this requires the .so to be where the OS can find it. See 3.5. Installing and Using a Shared Library

Using dlsym is for when you don't know at compile time which library you want to use. That doesn't sound like it's the case here. Maybe the confusion is that Windows calls the dynamically loaded libraries whether you do the linking at compile or run-time (with analogous methods)? If so, then you can think of dlsym as the equivalent of LoadLibrary.

If you really do need to dynamically load the libraries (i.e., they're plug-ins), then this FAQ should help.

Belgravia

The reason I need a dynamic shared library is that I'll also be calling it from Perl code. It may be a complete misconception on my own part that I also need to call it dynamically from other C++ programs that I'm developing. – Desk

I've never tried integrated perl and C++, but I think you need to use XS: johnkeiser.com/perl-xs-c++.html – Belgravia