---
name: "ACE_DLL"
section: "3"
platform: "linux"
package: "libace-doc"
version: "5.0.7-4"
release: "Debian 2.2 (Potato)"
platforms: ["linux"]
url: "https://new.carta.tech/ACE_DLL"
---

# ACE\_DLL(3)

Provides an abstract interface for handling various DLL operations.

## NAME

ACE\_DLL -  Provides an abstract interface for handling various DLL operations.

## SYNOPSIS

```
#include <ace/DLL.h>
class ACE_DLL
{
  public:
    ACE_DLL (int close_on_destruction = 1);
    ACE_DLL (
        const ASYS_TCHAR *dll_name,
        int open_mode = ACE_DEFAULT_SHLIB_MODE,
        int close_on_destruction = 1
        );
    int open (
        const ASYS_TCHAR *dll_name,
        int open_mode = ACE_DEFAULT_SHLIB_MODE,
        int close_on_destruction = 1
        );
    int close (void);
    ~ACE_DLL (void);
    void *symbol (const char *symbol_name);
    ASYS_TCHAR *error (void);
    ACE_SHLIB_HANDLE get_handle (int become_owner = 0);
    int set_handle (
        ACE_SHLIB_HANDLE handle,
        int close_on_destruction = 1
        );
  private:
    ACE_SHLIB_HANDLE handle_;
    int close_on_destruction_;
    inline ACE_UNIMPLEMENTED_FUNC (ACE_DLL (const ACE_DLL &));
};
```

## DESCRIPTION

This class is an wrapper over the various methods for utilizing a dynamically linked library (DLL), which is called a shared library on some platforms.  Operations open, close, and symbol have been implemented to help opening/closing and extracting symbol information from a DLL, respectively.

## Initialization and termination methods.

```
ACE_DLL (int close_on_destruction = 1);
```

Default constructor.  By default, the close operation on the object will be invoked before it is destroyed.

```
ACE_DLL (
    const ASYS_TCHAR *dll_name,
    int open_mode = ACE_DEFAULT_SHLIB_MODE,
    int close_on_destruction = 1
    );
```

This constructor opens and dynamically links dll\_name.  The default mode is RTLD\_LAZY, which loads identifier symbols but not the symbols for functions, which are loaded dynamically on-demand.  Other supported modes include: RTLD\_NOW, which performs all necessary relocations when dll\_name is first loaded and RTLD\_GLOBAL, which makes symbols available for relocation processing of any other DLLs.

```
int open (
    const ASYS_TCHAR *dll_name,
    int open_mode = ACE_DEFAULT_SHLIB_MODE,
    int close_on_destruction = 1
    );
```

This method opens and dynamically links dll\_name.  The default mode is RTLD\_LAZY, which loads identifier symbols but not the symbols for functions, which are loaded dynamically on-demand. Other supported modes include: RTLD\_NOW, which performs all necessary relocations when dll\_name is first loaded and RTLD\_GLOBAL, which makes symbols available for relocation processing of any other DLLs.  Returns -1 on failure and 0 on success.

```
int close (void);
```

Call to close the DLL object.

```
~ACE_DLL (void);
```

Called when the DLL object is destroyed -- invokes close if the close\_on\_destruction flag is set in the constructor or open method.

```
void *symbol (const char *symbol_name);
```

If symbol\_name is in the symbol table of the DLL a pointer to the symbol\_name is returned.  Otherwise, returns 0.

```
ASYS_TCHAR *error (void);
```

Returns a pointer to a string explaining why symbol or open failed.

```
ACE_SHLIB_HANDLE get_handle (int become_owner = 0);
```

Return the handle to the caller.  If become\_owner is non-0 then caller assumes ownership of the handle and the ACE\_DLL object won't call close when it goes out of scope, even if close\_on\_destruction is set.

```
int set_handle (
    ACE_SHLIB_HANDLE handle,
    int close_on_destruction = 1
    );
```

Set the handle for the DLL object. By default, the close operation on the object will be invoked before it is destroyed.

## Disallow copying and assignment since we don't handle these.

```
inline ACE_UNIMPLEMENTED_FUNC (ACE_DLL (const ACE_DLL &));
```

## AUTHOR

Kirthika Parameswaran kirthika@cs.wustl.edu

## LIBRARY

ace