NAME
    custom - custom builtin interface

SYNOPSIS
    custom([custname [, arg ...]])

TYPES
    custname	string
    arg		any

    return	any

DESCRIPTION
    This function will invoke the custom function interface.  Custom
    functions are accessed by the custname argument.  The remainder
    of the args, if any, are passed to the custom function.  The
    custom function may return any value, including null.  Calling
    custom with no args is equivalent to the command 'show custom'.

    In order to use the custom interface, two things must happen:

	1) Calc must be built to allow custom functions.  By default,
	   the master Makefile is shipped with ALLOW_CUSTOM= -DCUSTOM
	   which causes custom functions to be compiled in.

	2) Calc must be invoked with an argument of -C as in:

		calc -C

    In other words, explicit action must be taken in order to
    enable the use of custom functions.  By default (no -C arg)
    custom functions are compiled in but disabled so that only
    portable calc scripts may be used.

    The main focus for calc is to provide a portable platform for
    multi-precision calculations in a C-like environment.  You should
    consider implementing algorithms in the calc language as a first
    choice.  Sometimes an algorithm requires use of special hardware, a
    non-portable OS or pre-compiled C library.  In these cases a custom
    interface may be needed.

    The custom function interface is intended to make is easy for
    programmers to add functionality that would be otherwise
    un-suitable for general distribution.  Functions that are
    non-portable (machine, hardware or OS dependent) or highly
    specialized are possible candidates for custom functions.

    To add a new custom function requires access to calc source.
    For information on how to add a new custom function, try:

	    help new_custom

    To serve as examples, calc is shipped with a few custom functions.
    If calc if invoked with -C, then either of the following will
    display information about the custom functions that are available:

	    show custom
    or:

	    custom()

    A few library script that uses these function are also provided
    to serve as usage examples.

    We welcome submissions for new custom functions.  For information
    on how to submit new custom functions for general distribution, see:

	    help contrib

EXAMPLE
    If calc compiled with ALLOW_CUSTOM= (custom disabled):

    > print custom("sysinfo", "baseb")
	    Calc was built with custom functions disabled
    Error 10195

    If calc compiled with ALLOW_CUSTOM= -DCUSTOM and is invoked without -C:

    > print custom("sysinfo", "baseb")
	    Calc must be run with a -C argument to use custom function
    Error 10194

    If calc compiled with ALLOW_CUSTOM= -DCUSTOM and is invoked with -C:

    > print custom("sysinfo", "baseb")
    32

LIMITS
    By default, custom is limited to 100 args.

LIBRARY
    none

SEE ALSO
    custom_cal, new_custom, contrib