# define_c_proc

Definition: | integer rid = define_c_proc(object lib, object fname, sequence args, bool bCrash=true)
Description: | Define the characteristics of a C function that you wish to call as a procedure from your Phix program. A small integer, known as a routine id, will be returned, or -1 if the function cannot be found (and bCrash is false).
pwa/p2js: | Not supported.
Comments: | lib is an address returned by open_dll(), or {}. If lib is an atom, fname is the name of a function within that dll, optionally as either {'+',"name"} or "+name" to specify the CDECL calling convention. If lib is {}, fname is the (atom) address of a machine code function, optionally as {'+',addr} to specify the CDECL calling convention. CDECL is the default/only calling convention on a Linux system. STDCALL is the default in a Windows system. The CDECL convention requires the callee to clean up the stack, and is therefore more suited to variable numbers of arguments, whereas with STDCALL the routine cleans up the stack before returning. args is a list of the parameter types for the routine. A list of C types is contained in dll.e, and define_c_func. The define_cffi_proc routine is a string-based wrapper of this routine, which you may find easier to use. The routine id, rid, can be passed to c_proc(), when you want to call the C function. You can pass any C integer type or pointer type. You can also pass a Phix atom as a C double or float. In C (on Windows and Linux), parameter types which use 4 bytes or less are all passed the same way, so it is not necessary to be exact. Currently, there is no way to pass a C structure by value. You can only pass a pointer to a structure. The C function can return a value but it will be ignored. If you want to use the value returned by the C function, you must instead define it with define_c_func() and call it with c_func(). In fact, define_c_proc(lib, name, args) is implemented simply as return define_c_func(lib, name, args, NULL), which can simplify some libraries by allowing everything to be defined via define_c_func, however they must still call the correct one of c_func() or c_proc.
Example: |
    -- user32.dll contains the ShowWindow C function which takes two integer parameters
    atom user32 = open_dll("user32.dll")
    integer ShowWindow = define_c_proc(user32, "ShowWindow", {C_INT, C_INT})
Implementation: | See builtins\VM\pcfunc.e (an autoinclude) for details of the actual implementation.
See Also: | c_proc, define_cffi_proc, define_c_func, c_func, open_dll, Calling C Functions