GOLF(2gg)

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