Download Reference Manual
The Developer's Library for D
About Wiki Forums Source Search Contact

Leave Comments, Critiques, and Suggestions Here?

Introduction

Tango offers a set of header modules intended to provide a means of interacting with both the standard C library and with core operating system C libraries, as well as a few simple tools for simplifying the process of passing data to and from C routines.

C Header Conventions

Unlike other Tango modules, C header modules names are lowercase. This is done for two reasons: first, it is important that these names match the original C header names as closely as possible to provide a consistent and predictable interface layout, and second, to make a clear distinction between C imports and native D imports. This latter aspect serves to make C API use more obvious to code reviewers and should help to point out areas where D API support is weak. In the few rare instances where module, function, or variable names were changed to avoid colliding with D keywords, the changes were made to be as invisible as possible, and each will be outlined below. Also, when available, headers have been implemented according to the available spec rather than simply translating directly from an existing C library. This serves to dramatically reduce clutter, eliminate exposure of non-portable library extensions, and aid maintenance and readability.

The Standard C Library

Tango provides an essentially complete interface to the standard C library (according to ISO/IEC 9899:1999) located in the tango.stdc package. The notable differences are:

  • assert.d - 'assert' is a keyword in D so this module is unavailable, but as 'assert' is a built-in language feature, it should not be missed.
  • float.d - 'float' is a keyword in D so this module is unavailable. Its contents are under review regarding whether there is any use to defining them elsewhere.
  • inttypes.d - The char constants have been enclosed in a version block to reduce executable size for applications not using these constants. Build with version VerboseC to expose these.
  • iso646.d - It is impossible to implement macros of this type in D so this module is unavailable.
  • setjmp.d - The features offered by this module do not integrate well with exception handling so this module is unavailable.
  • stdint.d - The numeric constants have been enclosed in a version block to reduce executable size for applications not using these constants. Build with version VerboseC to expose these.
  • wchar.d - 'wchar' is a keyword in D so this module is unavailable. Instead, its contents have been spread across related modules according to category. In general, the features of this module are available in the char-oriented module of the same purpose. So string.h contains the wchar string-handling routines and so on.

Currently, all core C types are assumed to be the same width as their corresponding D type except long and unsigned long, which commonly vary based on the underlying operating system and processor bus width. The 'config' module has been added to provide aliases for these types, which are named according to their D equivalent with a 'c_' prefix. Therefore, a C long type name is represented as c_long, and a C unsigned long type name is represented as c_ulong. This module may be used in instances where D type sizes must match their corresponding C type size. Other aliases will be added as needed, though there is currently no plan to support architectures with odd-sized bytes.

The Posix Library

Tango contains a partial implementation of the POSIX interface implemented according to the Open Group Base Specification Issue 6 (IEEE Std 1003.1), which is located in the tango.stdc.posix package. The package exists in this location because the POSIX interface is specified as an extension to the standard C library and is not system-specific. The POSIX headers have been implemented manually, and will be extended as needed. The contents of each module have been segregated by categoy, beginning with a comment describing the category, followed by a comment block describing what belongs in the category, and ending with the actual code for that category. Please note that while portable declarations of required features are available to all POSIX-compliant systems, the contents of many strucutres, the values of constants, and other details, have no common definition and therefore must be defined on a per-system basis. Currently, Linux is is fairly well supported, but coverage of other systems is somewhat sparse. Submissions to this library are welcome but must be in the style of the current headers for inclusion.

The System Library

Operating system-specific library code is located in the tango.sys package, segregated by system name. The packages are arranged in this way to clearly indicate when a platform-specific feature is being used, and which platform defines the feature.

Windows API

The Windows Win32 API is located in tango.sys.win32. In general, the modules in this package are straightforward translations of the C header files of the same name, and Microsoft's documentation is directly applicable to them. Some additional helper modules are also included. The module tango.sys.win32.UserGdi? holds the core Windows API functions, and is generally all that is required for traditional Windows SDK programming. Importing this file is equivalent to the C code:

 #define WIN32_LEAN_AND_MEAN
 #include "windows.h"

In the future, this package may also contain D code for creating services, interacting with the Windows Registry, and other common tasks.

Linux API

The Linux API is located in tango.sys.linux and is intended to contain header modules for any features specific to Linux which are not defined in the POSIX spec. Given the breadth of the POSIX feature set, this package is still relatively sparse, but it will be the destination for any kernel interface modules, support for /dev/epoll, and so on. At the moment, this package also contains the self-named module "linux" which provides linux support for the features exposes in tango.sys.Common.

Darwin API

The Darwin API is located in tango.sys.darwin and contains header modules for any features specific to Darwin (Mac OS X) which are not defined in the POSIX spec. At the moment, this package only contains the self-named module "darwin" which provides darwin support for the features exposed in sys.Common.