cdecl - Man Page

cdecl may be invoked under a number of different names (by either renaming the executable or creating either a symbolic or hard link to it). If it is invoked as:

cdecl

Runs with the latest supported version of C as the default language.

c++decl | cppdecl | cxxdecl

Runs with the latest supported version of C++ as the default language.

explain

Runs with the latest supported version of C as the default language interpreting the rest of the command-line (if given) as gibberish, performs the conversion to pseudo-English, and exits.

For example (where $ is the shell prompt):

   $ explain 'int *const (*p)[4]'
   declare p as pointer to array 4 of constant pointer to integer

For declarations given on the command line, care must be taken either to escape or quote shell metacharacters. The default language can be specified via the cdeclrc file (see Configuration Files).

cdecl will also behave as above if the first non-option argument on the command-line or the first whitespace separated word thereof is a cdecl command (see Commands):

   $ cdecl declare p as pointer to array 4 of int
   int (*p)[4];

$ c++decl 'reinterpret cast n into pointer to unsigned'
reinterpret_cast<unsigned*>(n)

If no arguments are given, standard input will be read until end-of-file is encountered or one of the exit, q, or quit commands is read.

You can use cdecl as you create a C (or C++) program from within an editor. For example, in vi(1), type the declaration in pseudo-English, then filter the line through cdecl:

   !!cdecl<CR>

where <CR> is the return key.

If standard input is coming from a terminal, a prompt of either cdecl> or c++decl> will be written to the terminal before each line of input. The prompt can be turned off by either the --no-prompt or -P option or the set noprompt command.

cdecl uses the GNU readline(3) library (if available and compiled in) to provide keyword completion, command-line history, and editing.

In what follows, [] means zero or one, * means zero or more, {} means one of, and | means alternate.

cdecl has the following commands:

cast [s-name] {as|[in]to} english

Composes a C (or C++) cast from pseudo-English.

{const|dynamic|reinterpret|static} cast s-name {as|[in]to} english

Composes a C++ new-style cast from pseudo-English.

declare s-name [, s-name]* as english [width number [bits]]

Composes C (or C++) declarations from pseudo-English with an optional bit-field width (for integral types only).

declare s-name [, s-name]* as english aligned [as|to] { number [bytes] | english }

Composes C (or C++) declarations from pseudo-English aligned to either a specific number of bytes or the same alignment as english.

declare operator as english

For C++ only, composes an overloaded operator declaration from pseudo-English.

declare store* lambda [[captures] [captures]] [([args])] [returning english]

For C++ only, composes a lambda declaration from pseudo-English.

declare store* user-defined conversion [operator] [of scope-e s-name]* returning english

For C++ only, composes a user-defined conversion operator from pseudo-English.

define s-name as english

Defines a type (typedef) from pseudo-English.

#define name [pp-tokens]

Defines an object-like macro that expands into pp-tokens.

#define name([pp-params]) [pp-tokens]

Defines a function-like macro that expands into pp-tokens. Note that the ( must be adjacent to name.

enum [class] s-name [: type]

Defines s-name as an enum (or an enum class in C++) type optionally of a fixed underlying type. In C, this is equivalent to:

   typedef enum s-name s-name

expand name [([pp-args])] [pp-tokens]

Expands a previously defined macro step by step using the supplied arguments (if given). The additional pp-tokens (if given) are appended and expanded.

explain gibberish [, gibberish]*

Deciphers C (or C++) declarations or a new-style cast (C++ only) into pseudo-English.

explain (gibberish)[s-name]

Deciphers a C (or C++) cast into pseudo-English.

include "path"

Includes the file denoted by path and performs the contained commands. (This is typically used in a configuration file to include another configuration file.) Shell meta characters in path, e.g., ~, are expanded.

Note that include is recognized as a cdecl command only when immediately followed by a string literal.

#include "path"

Same as include, except #include may not end with ; and must be on a line by itself.

{ struct | union | class } s-name

Defines s-name as a struct, union, or class (C++ only) type. In C, this is equivalent to:

   typedef { struct | union } s-name s-name

scope-c s-name { [{ scope-c | typedef | using } ;]* }

For C++ only, defines s-name as a scope-c (struct, union, or class) type; or begins a namespace. Also executes zero or more class, struct, typedef, union, or using commands within the scope of s-name thus declaring type(s) within that scope.

set [option [= value] | options | lang]*

In the first form, sets a particular option (see Set Options for valid options); in the second form, prints the current value of all options; in the third form, sets the current language to lang. If no argument is given, it's equivalent to the second form.

show [ s-name | [all] [predefined | user] [glob]] [[as] {english | typedef | using}]

• For s-name, shows the definition for a previously defined type (via define, typedef, or using) having that name.
• For all only, shows all predefined and user-defined types.
• For predefined, shows only predefined types that are valid in the current language or later.
• For user, shows only user-defined types that were defined in the current language or later.
• For either all predefined or all user, shows their respective set of types regardless of the current language.
• For none of s-name, all, predefined, user, or glob, equivalent to show user.

By default, types are shown as they were defined. If typedef is given, types are shown as typedef declarations. For C++11 or later only, if using is given, types are shown as using declarations.

show { name | [predefined | user] macros }

• For name, shows the definition for a previously defined macro (via #define) having that name.
• For predefined, shows only predefined macros that are valid in the current language or later.
• For user, shows only user-defined macros.
• For neither predefined nor user, equivalent to show user.

type[def] gibberish [, gibberish]*

Defines types via a C (or C++) typedef declaration.

#undef name

Undefines a previously defined macro.

using name = gibberish

For C++11 or later only, defines a type via a using declaration.

{ help | ? } [ command[s] | command | english | options ]

Prints help that's sensitive to the current programming language (C or C++). By default or when command or commands is given, prints help on cdecl's commands (this section); if command is given, prints help only for that command; if english is given, prints help on pseudo-English (see English below); if options is given, prints help on cdecl's options (see Set Options below).

exit | q[uit]

Quits cdecl. Note that q is recognized as a synonym for quit only when it's the only thing on a line other than whitespace.

where:

In what follows, [] means zero or one, * means zero or more, {} means one of, and | means alternate. The only punctuation characters used in pseudo-English are hyphens in hyphenated words and parentheses around and commas between constructor, function, operator, user-defined literal, or block parameters, and brackets around lambda captures.

English is one of:

where:

ar-qual

One of: non-empty, const, restrict, or volatile.

C-type

One of: auto (C23 or C++11 or later), bool, char, char8_t, char16_t, char32_t, wchar_t, int, float, double, parameter pack, or void; or for C99 only: _Accum or _Fract.

cv-qual

One of: _Atomic, const, restrict, or volatile.

fn-qual

One of: const, final, override, reference, restrict, rvalue reference, or volatile.

modifier

One of: short, long, signed, unsigned, _Complex, _Imaginary, or _Sat (C99 only).

number

One of a decimal, octal (if starting with 0), hexadecimal (if starting with either 0x or 0X), or binary (if starting with either 0b or 0B) number.

store

One of: auto (C17 or earlier, or C++03 or earlier), block, carries-dependency, consteval, constexpr, deprecated, explicit, export, extern, extern "C", final, friend, inline, maybe-unused, mutable, nodiscard, non-throwing, noreturn, override, register, reproducible, static, thread-local, typedef, unsequenced, virtual, or pure virtual.

If returning english is omitted, it's equivalent to returning int in C95 and earlier or returning void in C99 and later or C++.

Some synonyms are permitted within pseudo-English. The terms on the left are synonyms for what's on the right:

                     accum  _Accum
                    atomic  _Atomic
                 automatic  auto
       bit precise integer  _BitInt
       bit-precise integer  _BitInt
                      bool  _Bool
                   boolean  _Bool
                   Boolean  _Bool
                   capture  capturing
                  captures  capturing
        carries dependency  carries_dependency
        carries-dependency  carries_dependency
                    char 8  char8_t
                   char 16  char16_t
                   char 32  char32_t
                 character  char
                   command  commands
                   complex  _Complex
                  constant  const
       constant evaluation  consteval
       constant-evaluation  consteval
                const-eval  consteval
       constant expression  constexpr
       constant-expression  constexpr
                const-expr  constexpr
   constant initialization  constinit
   constant-initialization  constinit
                const-init  constinit
                      conv  conversion
                      ctor  constructor
          double precision  double
          double-precision  double
                      dtor  destructor
               enumeration  enum
                      eval  evaluation
                  exported  export
                      expr  expression
                  external  extern
            floating point  float
            floating-point  float
                     fract  _Fract
                      func  function
                 imaginary  _Imaginary
                      init  initialization
                   integer  int
                       len  length
              maybe unused  maybe_unused
              maybe-unused  maybe_unused
                       mbr  member
                no discard  nodiscard
                no-discard  nodiscard
           non-discardable  nodiscard
                 no except  noexcept
                 no-except  noexcept
              no-exception  noexcept
         no unique address  no_unique_address
         no-unique-address  no_unique_address
        non-unique-address  no_unique_address
                   non-mbr  non-member
                  noreturn  _Noreturn
                 no return  _Noreturn
                 no-return  _Noreturn
             non-returning  _Noreturn
              non-throwing  throw()
                      oper  operator
                overridden  override
                    predef  predefined
                       ptr  pointer
                       ref  reference
                restricted  restrict
                       ret  returning
                       sat  _Sat
                 saturated  _Sat
                 structure  struct
                      type  typedef
              thread local  thread_local
              thread-local  thread_local
              thread_local  _Thread_local
              user defined  user-defined
                  user-def  user-defined
                       var  variable
                   varargs  ...
                  variadic  ...
                    vector  array
            wide character  wchar_t

Gibberish is any supported C (for cdecl) or C++ (for c++decl) declaration of a variable, constant, array, macro, pointer, reference, rvalue reference, function, constructor, destructor, or overloaded operator; or user-defined type, conversion, or literal; or type cast. (See Examples for examples and Caveats for unsupported declarations.)

Gibberish also includes support for the following:

• Apple's “blocks” syntax and the __block storage class.
• For C99 only, Embedded C's _Accum and _Fract types, and the _Sat modifier.
• For C99 only, Unified Parallel C's relaxed, shared, and strict qualifiers.
• GNU C's __auto_type, __complex, __complex__, __const, __inline, __inline__, __restrict, __restrict__, __signed, __signed__, __thread, __typeof__, __volatile, and __volatile__.
• GNU C's __attribute__ syntax, but all attributes are ignored.
• Microsoft C's __declspec syntax, but all attributes are ignored.
• Microsoft C's calling conventions __cdecl, __clrcall, __fastcall, __stdcall (also WINAPI), __thiscall, and __vectorcall. Pseudo-English also allows the same convention names but without the leading __.
• Microsoft C's __forceinline, but it's treated as a synonym for inline.
• Microsoft C's _asm, _cdecl, _declspec, _fastcall, _forceinline, _inline, _restrict, _stdcall, and _vectorcall that are synonyms for their respective __ counterparts.

The set command takes several options (which ignore hyphens). Unambiguous option abbreviations may be used.

[no]alt-tokens

Turns [off] on alternative token output — default is off. (Supported only in C95 and later.)

[no]bison-debug

Turns [off] on bison(1) debugging output (if compiled in) — default is off.

debug[=s]

Turns on cdecl debugging output — default is off. (See the --debug or -d option for details.)

nodebug

Turns off cdecl debugging output.

nographs

Turns off either digraph or trigraph output, i.e., reverts to emitting all characters as-is.

digraphs

Turns on digraph output for [ and ] — default is off. (Supported only in C95 and later.)

[no]east-const

Turns [off] on “east const” output where const (and volatile) are printed to the right (“east”) of the type — default is off. (Not supported in K&R C.)

[no]echo-commands

Turns [off] on echoing commands before corresponding output, but only when not interactive — default is off.

[no]english-types

Turns [off] on printing types in pseudo-English (e.g., integer), not C/C++ (e.g., int) when explaining gibberish — default is on.

explicit-ecsu=s

For C++ only, turns on explicit enum, class, struct, or union in declarations — default is su (for struct and union). (See the --explicit-ecsu or -S option for details.)

explicit-int=s

Turns on explicit int for the integer types s — default is none. (See the --explicit-int or -i option for details.)

noexplicit-ecsu

For C++ only, turns off explicit enum, class, struct, and union in declarations.

noexplicit-int

Turns off explicit int for all integer types.

[no]flex-debug

Turns [off] on flex(1) debugging output (if compiled in) — default is off.

[no]infer-command

Turns [off] on trying to infer a command when an input line doesn't start with any — default is off. (See the --infer-command or -I option for details.)

language=s

Use s (which is case-insensitive) as the current language. (See C and C++ Language Versions for valid languages.)

lang

Shorthand for language=lang.

options

Prints the current value of all options.

[no]permissive-types

Turns [off] on permitting keywords in language versions other than the current language as types — default is off. (See the --permissive-types or -p option for details.)

[no]prompt

Turns [off] on the prompt — default is on.

[no]semicolon

Turns [off] on printing a semicolon at the end of a C (or C++) declaration — default is on.

trigraphs

Turns on trigraph output for [, ], ^, |, and ~ — default is off. (Supported only between C89 and C17 and between C++03 and C++14.)

[no]trailing-return

Turns [off] on declaring functions and operators using the trailing return type syntax in C++11 and later — default is off.

[no]using

Turns [off] on declaring types with using rather than typedef in C++11 and later — default is on.

west-decl=s

Turns on printing the * for pointer and & and && for reference types adjacent to the type (“west”) to s — default is r (only all return types). (See the --west-decl or -w option for details.)

nowest-decl

Turns off printing the * for pointer and & and && for reference types adjacent to the type (“west”) for all types.

caddr_t, daddr_t, dev_t, FILE, ino_t, jmp_buf, off_t, time_t, tm

blkcnt_t, blksize_t, cc_t, clockid_t, clock_t, DIR, div_t, double_t, errno_t, fd_set, femode_t, fenv_t, fexcept_t, float_t, fpos_t, fsblkcnt_t, fsfilcnt_t, gid_t, iconv_t, id_t, imaxdiv_t, in_addr_t, in_port_t, key_t, lconv, ldiv_t, lldiv_t, locale_t, long_double_t, mbstate_t, mode_t, nfds_t, nlink_t, pid_t, posix_spawnattr_t, posix_spawn_file_actions_t, ptrdiff_t, regex_t, regmatch_t, regoff_t, rlim_t, sa_family_t, sig_atomic_t, sighandler_t, sigset_t, sig_t, size_t, socklen_t, ssize_t, suseconds_t, timer_r, uid_t, useconds_t, va_list,

_Decimal32, _Decimal32_t, _Decimal64, _Decimal64_t, _Decimal64x, _Decimal128, _Decimal128_t, _Decimal128x,

_Float16, _Float16_t, _Float32, _Float32_t, _Float32x, _Float64, _Float64_t, _Float64x, _Float128, _Float128_t, _Float128x

pthread_t, pthread_barrier_t, pthread_barrierattr_t, pthread_cond_t, pthread_condattr_t, pthread_key_t, pthread_mutex_t, pthread_mutexattr_t, pthread_once_t, pthread_rwlock_t, pthread_rwlockattr_t, pthread_spinlock_t, wctrans_t, wctype_t, wint_t,

__float80, __float128, __fp16, __ibm128, __int128, __m128, __m128d, __m128i, __m64,

ATOM, BOOL, BOOLEAN, BYTE, CCHAR, CHAR, COLORREF, DWORD, DWORD32, DWORD64, DWORDLONG, DWORD_PTR, FLOAT, HALF_PTR, HANDLE, HBITMAP, HBRUSH, HCOLORSPACE, HCONV, HCONVLIST, HCURSOR, HDC, HDDEDATA, HDESK, HDROP, HDWP, HENHMETAFILE, HFILE, HFONT, HGDIOBJ, HGLOBAL, HHOOK, HICON, HINSTANCE, HKEY, HKL, HLOCAL, HMENU, HMETAFILE, HMODULE, HMONITOR, HPALETTE, HPEN, HRESULT, HRGN, HRSRC, HSZ, HWINSTA, HWND, INT, _int8, _int16, _int32, _int64, __int8, __int16, __int32, __int64, INT_PTR, LANGID, LARGE_INTEGER, LCID, LCTYPE, LGRPID, LONG, LONG32, LONG64, LONGLONG, LONG_PTR, LPBOOL, LPBYTE, LPCHAR, LPCOLORREF, LPCSTR, LPCTSTR, LPCVOID, LPCWSTR, LPDWORD, LPHANDLE, LPINT, LPLONG, LPSTR, LPTSTR, LPVOID, LPWORD, LPWSTR, LRESULT, PBOOL, PBOOLEAN, PBYTE, PCHAR, PCSTR, PCTSTR, PCWSTR, PDWORD, PDWORD32, PDWORD64, PDWORDLONG, PDWORD_PTR, PFLOAT, PHALF_PTR, PHANDLE, PHKEY, PINT, PINT16, PINT32, PINT64, PINT8, PINT_PTR, PLCID, PLONG, PLONG32, PLONG64, PLONGLONG, PLONG_PTR, PSHORT, PSIZE_T, PSSIZE_T, PSTR, PTBYTE, PTCHAR, PTSTR, PUCHAR, PUHALF_PTR, PUINT, PUINT16, PUINT32, PUINT64, PUINT8, PUINT_PTR, PULONG, PULONG32, PULONG64, PULONGLONG, PULONG_PTR, PUSHORT, PVOID, PWCHAR, PWORD, PWSTR, QWORD, SC_HANDLE, SC_LOCK, SERVICE_STATUS_HANDLE, SHORT, SIZE_T, SSIZE_T, TBYTE, TCHAR, UCHAR, UHALF_PTR, UINT, UINT16, UINT32, UINT64, UINT8, UINT_PTR, ULARGE_INTEGER, ULONG, ULONG32, ULONG64, ULONGLONG, ULONG_PTR, UNICODE_STRING, USHORT, USN, WCHAR, __wchar_t, WORD, WPARAM

int8_t, int16_t, int32_t, int64_t, intmax_t, intptr_t, uint8_t, uint16_t, uint32_t, uint64_t, uintmax_t, uintptr_t,

int_fast8_t, int_fast16_t, int_fast32_t, int_fast64_t, int_least8_t, int_least16_t, int_least32_t, int_least64_t, uint_fast8_t, uint_fast16_t, uint_fast32_t, uint_fast64_t, uint_least8_t, uint_least16_t, uint_least32_t, uint_least64_t,

int_hk_t, int_hr_t, int_k_t, int_lk_t, int_lr_t, int_r_t, uint_uhk_t, uint_uhr_t, uint_uk_t, uint_ulk_t, uint_ulr_t, uint_ur_t

atomic_bool, atomic_char16_t, atomic_char32_t, atomic_char, atomic_flag, atomic_int, atomic_intmax_t, atomic_intptr_t, atomic_llong, atomic_long, atomic_ptrdiff_t, atomic_schar, atomic_short, atomic_size_t, atomic_uchar, atomic_uint, atomic_uintmax_t, atomic_uintptr_t, atomic_ullong, atomic_ulong, atomic_ushort, atomic_wchar_t,

atomic_int_fast8_t, atomic_int_fast16_t, atomic_int_fast32_t, atomic_int_fast64_t, atomic_int_least8_t, atomic_int_least16_t, atomic_int_least32_t, atomic_int_least64_t, atomic_uint_fast8_t, atomic_uint_fast16_t, atomic_uint_fast32_t, atomic_uint_fast64_t, atomic_uint_least8_t, atomic_uint_least16_t, atomic_uint_least32_t, atomic_uint_least64_t,

cnd_t, constraint_handler_t, max_align_t, memory_order, mtx_t, once_flag, rsize_t, thrd_start_t, thrd_t, tss_dtor_t, tss_t

std::bad_alloc, std::bad_cast, std::bad_exception, std::bad_type_id, std::codecvt_base, std::ctype_base, std::ctype_base::mask, std::div_t, std::domain_error, std::exception, std::filebuf, std::fstream, std::ifstream, std::invalid_argument, std::ios, std::ios_base::Init, std::ios_base::event, std::ios_base::event_callback, std::ios_base::fmtflags, std::ios_base::iostate, std::ios_base::openmode, std::ios_base::seekdir, std::ios_base, std::iostream, std::istream, std::istringstream, std::lconv, std::ldiv_t, std::length_error, std::locale, std::logic_error, std::messages_base, std::money_base, std::new_handler, std::nothrow_t, std::ofstream, std::ostream, std::ostringstream, std::osyncstream, std::out_of_range, std::overflow_error, std::ptrdiff_t, std::range_error, std::runtime_error, std::sig_atomic_t, std::size_t, std::streambuf, std::streamoff, std::streamsize, std::string, std::stringbuf, std::stringstream, std::syncbuf, std::time_base, std::tm, std::underflow_error, std::wfilebuf, std::wfstream, std::wifstream, std::wios, std::wiostream, std::wistream, std::wistringstream, std::wofstream, std::wostream, std::wostringstream, std::wosyncstream, std::wstreambuf, std::wstring, std::wstringbuf, std::wstringstream, std::wsyncbuf

std::atomic_bool, std::atomic_char16_t, std::atomic_char32_t, std::atomic_char8_t, std::atomic_char, std::atomic_flag, std::atomic_int16_t, std::atomic_int32_t, std::atomic_int64_t, std::atomic_int8_t, std::atomic_int_fast16_t, std::atomic_int_fast32_t, std::atomic_int_fast64_t, std::atomic_int_fast8_t, std::atomic_int, std::atomic_int_least16_t, std::atomic_int_least32_t, std::atomic_int_least64_t, std::atomic_int_least8_t, std::atomic_intmax_t, std::atomic_intptr_t, std::atomic_llong, std::atomic_long, std::atomic_ptrdiff_t, std::atomic_schar, std::atomic_short, std::atomic_signed_lock_free, std::atomic_size_t, std::atomic_uchar, std::atomic_uint16_t, std::atomic_uint32_t, std::atomic_uint64_t, std::atomic_uint8_t, std::atomic_uint_fast16_t, std::atomic_uint_fast32_t, std::atomic_uint_fast64_t, std::atomic_uint_fast8_t, std::atomic_uint, std::atomic_uint_least16_t, std::atomic_uint_least32_t, std::atomic_uint_least64_t, std::atomic_uint_least8_t, std::atomic_uintmax_t, std::atomic_uintptr_t, std::atomic_ullong, std::atomic_ulong, std::atomic_unsigned_lock_free, std::atomic_ushort, std::atomic_wchar_t,

std::adopt_lock_t, std::allocator_arg_t, std::bad_array_new_length, std::bad_function_call, std::bad_weak_ptr, std::bernoulli_distribution, std::chrono::high_resolution_clock, std::chrono::steady_clock, std::condition_variable, std::condition_variable_any, std::cv_status, std::defer_lock_t, std::error_category, std::error_code, std::error_condition, std::future_errc, std::future_error, std::future_status, std::imaxdiv_t, std::ios_base::failure, std::launch, std::lldiv_t, std::max_align_t, std::mutex, std::nullptr_t, std::random_device, std::recursive_mutex, std::recursive_timed_mutex, std::regex, std::regex_constants::error_type, std::regex_constants::match_flag_type, std::regex_constants::syntax_option_type, std::regex_error, std::shared_mutex, std::shared_timed_mutex, std::system_error, std::thread, std::timed_mutex, std::try_to_lock_t, std::u32string, std::u32string_view, std::wregex

std::align_val_t, std::any, std::bad_any_cast, std::bad_optional_access, std::bad_variant_access, std::byte, std::chars_format, std::from_chars_result, std::memory_resource, std::mono_state, std::string_view, std::to_chars_result, std::u16string, std::u16string_view, std::wstring_view,

std::filesystem::copy_options, std::filesystem::directory_entry, std::filesystem::directory_iterator, std::filesystem::directory_options, std::filesystem::file_status, std::filesystem::file_type, std::filesystem::filesystem_error, std::filesystem::path, std::filesystem::perm_options, std::filesystem::perms, std::filesystem::recursive_directory_iterator, std::filesystem::space_info,

std::pmr::memory_resource std::pmr::monotonic_buffer_resource std::pmr::pool_options std::pmr::synchronized_pool_resource std::pmr::unsynchronized_pool_resource

std::ambiguous_local_time, std::compare_three_way, std::endian, std::latch, std::noop_coroutine_promise, std::strong_equality, std::strong_ordering, std::suspend_always, std::suspend_never, std::nonstopstate_t, std::weak_equality, std::stop_source, std::stop_token, std::destroying_delete_t, std::format_error, std::jthread, std::partial_ordering, std::u8string_view, std::weak_ordering,

std::chrono::choose, std::chrono::day, std::chrono::file_clock, std::chrono::gps_clock, std::chrono::is_clock, std::chrono::last_spec, std::chrono::leap_second, std::chrono::local_info, std::chrono::local_t, std::chrono::month, std::chrono::month_day, std::chrono::month_day_last, std::chrono::month_weekday, std::chrono::month_weekday_last, std::chrono::nonexistent_local_time, std::chrono::sys_info, std::chrono::system_clock, std::chrono::tai_clock, std::chrono::time_zone, std::chrono::time_zone_link, std::chrono::tzdb, std::chrono::tzdb_list, std::chrono::utc_clock, std::chrono::weekday, std::chrono::weekday_indexed, std::chrono::weekday_last, std::chrono::year, std::chrono::year_month, std::chrono::year_month_day, std::chrono::year_month_day_last, std::chrono::year_month_weekday, std::chrono::year_month_weekday_last

std::bfloat16_t, std::float128_t, std::float16_t, std::float32_t, std::float64_t, std::ispanstream, std::ospanstream, std::range_format, std::spanbuf, std::spanstream, std::stacktrace, std::stacktrace_entry, std::unexpect_t, std::wispanstream std::wospanstream, std::wspanbuf, std::wspanstream

__DATE__

The local date in the form "Mmm dd yyyy".

__FILE__

The current file name, if any, or "stdin".

__LINE__

The current line number within __FILE__, if any, or an arbitrary line number.

__STDC__

1. (Not defined in C++.)

__STDC_VERSION__

The current C version, e.g., 202311L for C23. (Not defined in C++.)

__TIME__

The local time in the form "hh:mm:ss".

__VA_ARGS__

The variable arguments of a macro, if any.

__cplusplus

The current C++ version e.g., 202302L for C++23. (Not defined in C.)

__VA_OPT__

Optional preprocessor tokens enclosed between parentheses.

In C, a function named main has its parameters and return type checked for those required by main; in C++, this occurs only if it is not declared const, consteval, constexpr, default, delete, final, inline, override, __restrict, static, virtual, nor volatile. If it is so declared, it's assumed to be a member function.

Permissive types via the --permissive-types or -p option is not the default because always permitting keywords in language versions other than the current language as types can result in confusing errors. For example, if permissive types were the default, then you would get the following in C:

   cdecl> declare D as virtual destructor
                       ^
   14: warning: "virtual" is a keyword in C++
   virtual D;
                               ^
   22: syntax error: "destructor": unexpected token ...

Here, virtual, not being a keyword in C and therefore a valid name for a user-defined type, would be taken to be a type name, so cdecl would interpret that to mean you want to declare D as a variable of type virtual — and cdecl would do so by printing virtual D (but still warning that virtual is a keyword in C++). But then destructor would be unexpectedly encountered and generate an error. (It could easily be the case that you simply forgot to set the current language to C++ instead of C.)

With the default non-permissive behavior, you instead get:

   cdecl> declare D as virtual destructor
                       ^
   14: error: "virtual": unsupported keyword in C

which is clearer, but at the cost of not permitting valid declarations that use or keywords in language versions other than the current language as types.

The cdeclrc file is used to configure cdecl by executing the contained commands on start-up (unless either the --no-config or -C option is given). The full path of this file can be specified by either the --config or -c option; or, if not, the path is taken from the value of the CDECLRC environment variable unless it is either unset or empty in which case the path defaults to ~/.cdeclrc.

The commands useful within a configuration file are:

• class, define, enum, namespace, struct, typedef, union, or using to pre-define user-specific types so that they may be subsequently used when either composing or deciphering declarations.
• #define to pre-define macros so that they may be subsequently expanded.
• include to include other configuration files.
• set to set the language or other options initially.

Configuration files may include blank lines, C-style /* */ comments, and C++-style // comments, all of which are ignored.

To declare an array of pointers to functions that are like malloc(3):

   cdecl> declare fptab as array of pointer to function \
   cdecl+     returning pointer to void
   void *(*fptab[])();

When you see this declaration in someone else's code, you can make sense out of it by doing:

   cdecl> explain void *(*fptab[])()

The function prototype for a function such as _exit(2) would be declared with:

   cdecl> declare _exit as function (retval as int) returning void
   void _exit(int retval);

As a more complex example, signal(2) would be fully defined as:

   cdecl> declare signal as function \
   cdecl+     (sig as int, \
   cdecl+      f as pointer to function (int) returning void) \
   cdecl+     returning pointer to function (int) returning void
   void (*signal(int sig, void (*f)(int)))(int);

This is made more comprehensible with one of define, typedef, or using:

   cdecl> define pfi_v as pointer to function (int) returning void
   cdecl> declare signal as function \
   cdecl+     (sig as int, f as pfi_v) returning pfi_v
   pfi_v signal(int sig, pfi_v f);

cdecl can help figure out where to put const and volatile qualifiers:

   cdecl> declare pci as pointer to const int
   const int *pci;

cdecl> declare cpi as const pointer to int
int *const cpi;

c++decl can help with declaring references:

   c++decl> declare rpc as reference to pointer to char
   char *&rpc;

c++decl can help with pointers to member of classes:

   c++decl> declare p as pointer to member of class C int
   int C::*p;

and:

   c++decl> declare p as pointer to member of class C \
   c++decl+     function (i as int, j as int) \
   c++decl+     returning pointer to class D
   D *(C::*p)(int i, int j)

To define types within scopes:

   c++decl> define A::B::T1 as int
   c++decl> define T2 of scope A as int
   c++decl> define T3 of scope B of scope A as int
   c++decl> define T4 of scope A::B as int
   c++decl> define T5 of class C::D as int
   c++decl> class C { typedef int T; }
   c++decl> class C1 { class C2 { typedef int T; }; }
   c++decl> struct S { typedef int T; }
   c++decl> namespace N { typedef int T; }
   c++decl> namespace N::M { typedef int T; }
   c++decl> union U { typedef int T; }

cdecl can help with understanding how macros expand:

   cdecl> #define NAME2_HELPER(A,B)        A ## B
   cdecl> #define NAME2(A,B)               NAME2_HELPER(A,B)
   cdecl> expand NAME2(var_, __LINE__)
   NAME2(var_, __LINE__) => NAME2_HELPER(A,B)
   | A => var_
   | B => __LINE__
   | | __LINE__ => 42
   | B => 42
   NAME2(var_, 42) => NAME2_HELPER(var_,42)
   | NAME2_HELPER(var_, 42) => A ## B
   | NAME2_HELPER(var_, 42) => var_ ## 42
   | NAME2_HELPER(var_, 42) => var_42
   NAME2(var_, 42) => var_42

On systems where the readline(3) API is provided but is just a wrapper around the Editline Library, (e.g., macOS), there are a few issues:

• The wrapper has a bug that prevents color prompts from working correctly. Therefore, the PROMPT color cabapility is ignored on systems that do not provide genuine GNU readline(3).
• Hitting tab when there are no completion matches ordinarily rings the terminal's bell. However, older versions of the wrapper don't provide the rl_ding() function needed to ring the bell so cdecl provides a substitute. However, the substitute doesn't respect the user's preferred bell style (none, audible, or visual) and always does an audible bell.
• In some cases, hitting tab causes the wrapper to suggest only a single completion rather than simply inserting it.

To avoid these issues, compile cdecl against the genuine GNU Readline Library.

https://github.com/paul-j-lucas/cdecl/issues

The following types of declarations are not currently supported:

• Only enum, class, struct, and union names and scoped type declarations are supported; complete declarations are not:

     struct S s;                     // supported
     struct S { typedef int Int; };  // supported (C++ only)
     struct S { int i; char c; } s;  // not supported

• For array sizes, only integer literals, names, and * are supported; arbitrary expressions are not.
• In C23 and later, auto as a storage-class specifier is no longer supported.

• For C23 typeof and typeof_unqual declarations, only types are supported; arbitrary expressions are not:

     typeof(int*) x                  // supported
     typeof(x) y                     // not supported

• Only C++ lambda signature declarations are supported; complete lambda declarations are not:

     [n](int x)                      // supported
     [n](int x) { return n * x; }    // not supported

• C++ decltype, abbreviated function template, default argument, and template declarations are not supported.
• For C++ function exception specifications, only noexcept, noexcept(true), noexcept(false), and throw(), are supported; arbitrary expressions for noexcept or types for throw are not.

• C++ namespace alias declarations are not supported:

     namespace ALN = A_Long_Name;    // not supported

• Multiple _Alignas or alignas specifiers in the same declaration are not supported.
• For the argument to either the _Alignas or alignas specifier, only integer literals or types are supported; arbitrary expressions are not.
• Only simple C++ attribute specifiers like [[this]] are supported; attribute specifiers with namespaces are not. Additionally, optional arguments for deprecated and nodiscard are ignored.
• C++20 contracts ([[assert]], [[ensures]], and [[expects]]) are not supported.
• The C++20 explicit specifier with an expression is not supported.

• Macros are expanded only via the expand command and can't be used elsewhere:

     cdecl> #define exp      explain
     cdecl> exp int *p           // error: can't alias commands
     cdecl> #define FILE_PTR FILE*
     cdecl> explain FILE_PTR f   // error: can't use as type

• When converting from pseudo-English to a C++ declaration, any enum, class, struct, or union type keyword omitted from a declaration (via omission from either the --explicit-ecsu or -S option, or the set explicit-ecsu command) makes the declaration not “round-trippable”:

     c++decl> declare pt as pointer to class T
     T *pt;
     c++decl> explain T *pt
                      ^
     18: error: "T": unknown name

  This is because, when going from a C++ declaration to pseudo-English, cdecl doesn't know that an arbitrary name, in this example, T, is a class name.

  To include the type keywords explicitly and thus make the declarations “round-trippable,” include them via either the --explicit-ecsu or -S option, or the set explicit-ecsu command.

  Alternatively, declare the type via one of class, define, enum, struct, typedef, union, or using:

     c++decl> class T
     c++decl> explain T *pt
     declare pt as pointer to T

• While class, enum, explain, namespace, struct, typedef, union, and using can accept names that are cdecl keywords, cast, declare, and define can not; hence, not all explanations are “round-trippable”:

     cdecl> explain int explain
     declare explain as integer
     cdecl> declare explain as integer
                    ^
     9: syntax error: "explain": name expected

• When converting from one of the C++ overloaded operators &, *, +, ++, -, or --, to pseudo-English when declared as:

     T operator OP(U);

  i.e., taking one parameter, it's ambiguous (to cdecl) between being a member or non-member operator since cdecl doesn't have the context in which the operator is declared. If it were declared in-class, e.g.:

     class T {
     public:
         // ...
         T operator OP(U);
     };

  then clearly it's a member operator; if it were declared at file scope, then clearly it's a non-member operator; but cdecl doesn't have this context. In such cases, cdecl omits either member or non-member from its output.

• When converting from pseudo-English to a C23 or C++11 declaration for auto (or __auto_type in GNU C), or a const, constinit, reference, or an rvalue reference variable that is not a function parameter, the output doesn't include an initializer:

     c++decl> declare x as auto
     auto x;
     c++decl> declare x, y as structured binding
     auto [x, y];
     c++decl> declare r as reference to int
     int &r;

  These are illegal C++ declarations since such declarations must be initialized.

• Only casting a name is supported; casting an expression is not.
• When converting from or to a C++ new-style cast, only some semantic validation is performed to determine whether the type of cast is legal.
• When a predefined type, e.g., size_t, uint16_t, etc., is shown (via the show command), the underlying type is merely typical and does not necessarily match the underlying type on any particular platform or even the platform on which cdecl is running.
• An integer literal given as the argument for an alignment specifier is only checked to ensure it's either zero or a power of two; it is not checked to see whether it meets the minimum alignment for the type.

• In GNU C, the type __int128 is a distinct type; in Microsoft C, the types __int8, __int16, __int32, __int64, and __wchar_t are keyword synonyms. These types can take modifiers:

     unsigned __int128 x128;     // legal in GNU C
     unsigned __int32  x32;      // legal in Microsoft C

  In cdecl, these types are typedefs and can't take modifiers since that's illegal in C.

• When using the --lineno or -L option with a here document containing escaped newlines (lines ending in \), the \s also need to be escaped to get the line numbers correct because the shell ordinarily strips escaped newlines; for example:

     #define IDENT_CHARS "ABCDEFGHIJKLMNOPQRSTUVWXYZ_" \\
                         "abcdefghijklmnopqrstuvwxyz" \\
                         "0123456789"