hoardboard / r-internals

Documentation for R's internal C API

R internals

This repo aims to provide some useful additional information about R's internal C API, or Rapi for short. This site draws heavily from Section 5 ("System and foreign language interfaces") of Writing R extensions, R internals, and inspection of R's source code to see how functions are used.

Here we focus on best practices and modern tools. To wit, we recommend that you use R_NO_REMAP so all API functions have the prefix R_ or Rf_:

#define R_NO_REMAP
#include <R.h>
#include <Rinternals.h>

(Including <Rinternals.h> seems like bad form. However, it doesn't actually give you access to the "internal" internal API unless you set some additional flags. Instead it lets you access the "public" internal API, which is both necessary and safe. Yes, this is confusing.)

SEXPs

At the C-level, all R objects are stored in a common datatype, the SEXP, or S-expression. A SEXP is a variant type, with subtypes or SEXPTYPEs for all R's data structures. This site roughly breaks Rapi into chapters based on the SEXPTYPE the functions work with:

• Vectors cover the most important data structures: vectors. This includes LGLSXP, INTSXP, REALSXP, CPLXSXP, STRSXP, VECSXP, RAWSXP, and EXPRSXP.

• Strings: Character vectors are a more complex object made of vector CHARSXPs.

• Environments, or ENVSXPs.

• Functions, including CLOSXPs and the rarer BUILTINSXPs, SPECIALSXPs and FUNSXPs.

• Symbols, SYMSXPs.

• Pairlists, including LISTSXPs and the related NILSXP, LANGSXP, and DOTSXP. This chapter also includes a discussion of attributes, which are powered by pair lists.

• External pointers, or XPTRSXPs.

Other categories are:

• Evaluating code and handling errors.
• Garbage collection and reference counting.
• Object oriented code (including S4SXPs).
• Other miscellaneous functions.
• Serialisation.