NAME

       call-extended -  (C-language)

PURPOSE

       Call external function or macro (extended mode only).

SYNTAX

           call-extended <function> "( " [ & ]<variable>  [ , ... ]  " )"

DESCRIPTION

       call-extended calls <function> (which can be a function or macro) with a list of parameter variables. The
       <function> is defined either in:

           •  a library with C interop - note that such library can be written in many different languages. Most
           compiled languages can produce such libraries (such as Rust, C/C++ and others),

           • a ".c" file residing in the directory that contains application source code - again such a  C  file
           can in turn call code from libraries produced by any language that supports C interop (most do).

           • if a macro, in a ".h" file residing in the directory that contains application source code.

       The <function> must be declared via C-style declaration in a ".h" file residing in the application source
       code  directory. You can use "--lflag" and "--cflag" options of gg to supply libraries used. In addition,
       if you need to, you can also have any number of ".c" and ".h" files which will be automatically  included
       in your project. A macro must be defined in ".h" file.

       call-extended statement can only be used in extended mode (see extended-mode). By default, Golf code runs
       in safe mode which does not allow use of call-extended statement. Note that using call-extended statement
       does  not  automatically  make your application unsafe; rather, extended code can be written in a memory-
       safe language (such as Rust), or even if written in C it can be made in such a way not to  cause  out-of-
       band memory reads and writes.

       C SIGNATURE, INPUT/OUTPUT VARIABLES, TYPES

       Each <variable> can be of C type (or a pointer to C type):

           • "gg_num" which is a signed integer 8 bytes in length (int64_t type). This represents Golf number.

           • "char *" which is a pointer to an array of characters. This represents Golf string value.

           • "bool" which is a boolean variable. This represents Golf boolean.

       A  <function>  should  not return a value. Rather, use a variable passed as a pointer if you wish to pass
       the function's output back to your Golf code.

       For more on using C in <function>s, see Server-API.

       CHANGING CURRENT WORKING DIRECTORY

       If you change current working directory from your C code (such as with C chmod() function), you must  set
       Golf internal boolean variable "gg_path_changed" to true.

       WEB FRAMEWORK FOR C PROGRAMMING LANGUAGE

       Note that when you use call-extended, Golf becomes a web-framework-for-C-programming-language.

EXAMPLES

       For instance, consider C file "calc.c":

           #include "golf.h"

           // Compute factorial of f, and store result into res
           void factorial(gg_num f, gg_num *res)
           {
               *res = 1;
               gg_num i;
               for (i = 2; i <= f; i++) {
                   *res *= i;
               }
           }

       Declare this C function in a header file, for instance "calc.h":

           void factorial(gg_num f, gg_num *res);

       You can also have macros in a header file, so for example "calc.h" could be:

           void factorial(gg_num f, gg_num *res);

           #define mod10(n, m) m=(n)%10

       In  this  case  you have defined a macro that calculates the moduo of 10 and stores a result into another
       variable.

       Use these in your Golf code with call-extended statement, for instance to use a function "factorial()":

           extended-mode

           begin-handler /fact public
               set-number fact
               call-extended factorial (10, &fact)
               print-out fact
           end-handler

       In the above example, number "fact" is passed by reference (as a pointer), and it will contain the  value
       of factorial of 10 on return. The result printed out is "3628800".

       To use macro "mod10()":

           extended-mode

           begin-handler /mod public
               set-number mod
               call-extended mod10(103, mod)
               print-out mod
           end-handler

       In  this  example, you are using a C macro, so number "fact" is assigned a value directly, per C language
       rules. The result printed out is "3".

SEE ALSO

        C language

       call-extended extended-mode web-framework-for-C-programming-language See all documentation

$DATE                                               $VERSION                                           GOLF(2gg)