.. _implementation_standard:

Convention for implementing entrypoints

The implementations of LLVM-libc entrypoints live in the src/ directory, organized by the public header they belong to. Some entrypoints are platform- specific, and so their implementations are in a subdirectory with the name of the platform (e.g., stdio/linux/remove.cpp).

For a complete overview of what an entrypoint is and how it is managed in the build system, see the :ref:entrypoints documentation.

Implementation of entrypoints can span multiple .cpp and .h files, but there will be at least one header file with name of the form <entrypoint name>.h for every entrypoint. This header file is called the implementation header file. For the isalpha function, the path to the implementation header file is src/ctype/isalpha.h.

Implementation Header File Structure

We will use the isalpha function from the public ctype.h header file as an example. The isalpha function will be declared in an internal header file src/ctype/isalpha.h as follows::

// --- isalpha.h --- //
#ifndef LLVM_LIBC_SRC_CTYPE_ISALPHA_H
#define LLVM_LIBC_SRC_CTYPE_ISALPHA_H

namespace LIBC_NAMESPACE_DECL {

int isalpha(int c);

} // namespace LIBC_NAMESPACE_DECL

#endif LLVM_LIBC_SRC_CTYPE_ISALPHA_H

All LLVM-libc implementation constructs must be enclosed in the LIBC_NAMESPACE_DECL namespace. See :ref:code_style for the full technical rationale and macro definitions.

.cpp File Structure

The main .cpp file is named <entrypoint name>.cpp and is usually in the same folder as the header. It contains the signature of the entrypoint function, which must be defined with the LLVM_LIBC_FUNCTION macro. For example, the isalpha function from ctype.h is defined as follows, in the file src/ctype/isalpha.cpp::

// --- isalpha.cpp --- //

namespace LIBC_NAMESPACE_DECL {

LLVM_LIBC_FUNCTION(int, isalpha, (int c)) {
  // ... implementation goes here.
}

} // namespace LIBC_NAMESPACE_DECL

Notice the use of the macro LLVM_LIBC_FUNCTION. This macro helps us define a C alias symbol for the C++ implementation. For example, for a library build, the macro is defined as follows::

#define LLVM_LIBC_FUNCTION(type, name, arglist)
    LLVM_LIBC_FUNCTION_IMPL(type, name, arglist)
#define LLVM_LIBC_FUNCTION_IMPL(type, name, arglist)
    LLVM_LIBC_FUNCTION_ATTR decltype(LIBC_NAMESPACE::name)
        __##name##_impl__ __asm__(#name);
    decltype(LIBC_NAMESPACE::name) name [[gnu::alias(#name)]];
    type __##name##_impl__ arglist

The LLVM_LIBC_FUNCTION_ATTR macro is normally defined to nothing, but can be defined by vendors who want to set their own attributes.