[Help] Reason on when to declare and protect ZEND_API function View as Markdown

Hello internals,

I am trying to read Zend header files to understand its functional interfaces,
but have got confusion and anybody knows why zend_startup_system_id()
and zend_finalize_system_id()
do not have to be protected by BEGIN_EXTERN_C()/END_EXTERN_C()
enclosure,
but zend_add_system_entropy() has to.

Is the following code intentional for any reason?
And also, these two functions do not have ZEND_API attribute. Thanks.

Zend/zend_system_id.h
BEGIN_EXTERN_C()
/* True global; Write-only during MINIT/startup */
extern ZEND_API char zend_system_id[32];

ZEND_API ZEND_RESULT_CODE zend_add_system_entropy(const char
*module_name, const char *hook_name, const void *data, size_t size);
END_EXTERN_C()

void zend_startup_system_id(void);
void zend_finalize_system_id(void);

=======================================
Tony Su (Su, Tao)
make a 'lazy' programmer diligently with efficiency

I haven't looked at the details of these specific functions recently,
but in general functions which are marked ZEND_API are capable of
being called from extensions and modules. These same ZEND_API
functions need to be in extern "C" sections for that to happen if
the extension or module is using C++.

I would guess that zend_startup_system_id and
zend_finalize_system_id do not need to be used outside of the engine
but needed to have a forward declaration for code organization
reasons.

Thanks Levi for the clarification. Things become clearer. Here are some following questions

1. when you say 'outside of the engine', what is the boundary of outside/inside?
   My understanding is that all code under Zend/ folder is considered as inside the Zend engine;
   Other components outside that folder should be considered as consumer/user of Zend.
   Is this correct? Pls fix me if I mistook something.

   Functions marked with ZEND_API in header files under Zend/ folder
   should be thought as the interface for outside users. Technically,
   these functions should be marked with extern "C" to support
   C++ extension/module.
   Is this correct? Pls fix me if I mistook something.

2. a quick search shows that main/main.c calls zend_startup_system_id()
   If main/main.c is a Zend user, logically, zend_startup_system_id()
   should be declared with ZEND_API and extern "C"?

   /* extract from main/main.c::php_module_startup() /
   / Begin to fingerprint the process state */
   zend_startup_system_id();

3. I found another Zend/zend_gdb.h header file where three functions
   are marked with ZEND_API but are not enclosed by extern "C".
   /* Zend/zend_gdb.h */
   ZEND_API bool zend_gdb_register_code(const void *object, size_t size);
   ZEND_API void zend_gdb_unregister_all(void);
   ZEND_API bool zend_gdb_present(void);

4. In Zend/zend.gdb.c source file, I saw a function __jit_debug_register_code()
   marked with ZEND_API, but not declared in header file?
   Logically and programmatically, I got confused and could not grasp ZEND_API usage style.

   /* Zend/zend_gdb.c */
   ZEND_API zend_never_inline void __jit_debug_register_code(void)
   {
   asm volatile("");
   }

-- Tao Su