intro_libm(3M)
INTRO_LIBM - Introduction to math library routines
As shipped in IRIX 6.5. First release of IRIX 6.5.
NAME INTRO_LIBM - Introduction to math library routines IMPLEMENTATION See individual man pages for implementation details DESCRIPTION The math routines are listed with the other intrinsic procedures in alphabetical order, usually by generic function name. Generic function names are function calls that cause the compiler to compile automatically the appropriate data type version of a routine, based on the type of the input data. For example, a call to the generic function LOG with a type of input data of complex compiles as CLOG. In general, on UNICOS systems, real functions have no prefix; integer functions are prefixed with I, double precision functions are prefixed with D, complex functions are prefixed with C, and double precision complex functions are prefixed with CD (for example, ABS, IABS, DABS, CABS, and CDABS). Functions with a type different from their arguments are noted. Real functions are usually the same as the generic function name. On UNICOS/mk systems, two precisions are provided for real data: 32-bit or half precision real and 64-bit or single precision real. The specific names for single precision real data provide a link to the 64-bit intrinsic functions. To ensure a link to the 32-bit intrinsic functions, use the generic function names with 32-bit real arguments. For example, use LOG for any of the types of real data. Use ALOG for single precision real arguments. Extended precision routines of math library routines are not provided on UNICOS/mk systems and only some routines have vector versions. UNICOS/mk systems have an additional library named libmfastv. It contains versions of selected math intrinsics which can be faster than those in the default Math library. These alternate versions are not as accurate as the default library, and in some cases there are argument restrictions, such as not allowing the use of the -O option on the compiler command line, or not allowing the use of infinities. These alternate versions are generally faster for loops with 50 or more iterations. To use libmfastv, use the -l mfastv option on the compiler's command line to load the library file. You must compile your code with the -O3 or -Ovector3 option for the Fortran compiler or use -h vector3 with the C compiler. For information on inlining and vectorization of the Fortran 90 intrinsic procedures, see INTRO_INTRIN(3I). The documentation for some of the most often used math library routines also contains information on Cray Assembly Language (CAL) register usage. For more information on calling library routines from various programming languages, see the subsection on this man page titled "Calling Functions from Fortran, C, or CAL." The math routines can be divided into the following general categories: * General arithmetic functions - In the routine descriptions, complex arguments are represented as x = x + ix . r i The real part of the complex number is x ; x is the imaginary part. r i Arguments and results are of the same type unless otherwise indicated. Base values raised to a power and 64-bit integer division are called implicitly from Fortran. * Exponential and logarithmic functions - The Cray Resesarch exponential and logarithmic functions are similar to the ANSI standard functions. Each function has variations for real, double precision, and complex values except the common logarithm function, which addresses only real and double-precision values. Complex arguments are represented as x = x + ix . r i x is the real part of the complex number; x is the imaginary part. r i * Trigonometric functions - The trigonometric functions are based on the ANSI standard for Fortran, except for the cotangent function and the COSS (cosine and sine) function, which are Cray Research extensions. * Type conversion functions - Type conversion functions change the type of an argument. In the routine description, complex arguments are represented as x = x + ix . r i x is the real part of the complex number; x is the imaginary part. r i Arguments and results are of the same type, unless indicated otherwise. * Special functions - The special functions provide Fortran access to a number of Standard C functions on UNICOS/mk and UNICOS systems. * Extended-precision routines - The extended-precision routines perform double- and triple-precision arithmetic on UNICOS systems. * Boolean functions - The Boolean functions perform logical operations and bit manipulations. On UNICOS systems, the scalar subprograms are external versions of Fortran inline functions. They are all called by address; results are returned in register S1. All Boolean functions are extensions. These functions cannot be passed as arguments with CF90 on any system. Calling Functions from Fortran, C, or CAL Because of differences in the calling sequences for these languages, and other language differences, important variations must be noted in what functions can be called and how they are called. Calling from Fortran programs Some function names are in uppercase, and some are in lowercase. The Fortran language is case-insensitive; the Cray Research Fortran compilers map all code in uppercase. This means that functions with lowercase names cannot be called from Fortran programs. Calling from C programs The C language is case-sensitive. You must use the exact case specified in the documentation when coding references to a function. All functions documented in this manual are callable from C programs. The following rules can be used: * Because the function is not declared in a Standard C header, explicitly declare the function as external, and specify the type of the return value. * When calling the function, pass the address of the arguments by using the address operator (&) for each argument or by using a pointer to the argument. Array names are considered to be addresses; the address operator is not needed when using them. * The value returned by the function is the value, rather than the address of the value. * Specify the fortran keyword. The fortran keyword is an extension to the C language and is useful when a C program calls a function following the Cray Fortran calling sequence. Specifying the fortran keyword causes the C compiler to verify that the arguments used in each call to the function are pass-by-address. Calling from Cray Assembly Language (CAL) External references from Cray Assembly Language (CAL) are case- sensitive, so you must use the exact name for functions as specified on the man pages. Two standard calling methods are supported by Cray for math functions: call-by-register and call-by-address. For more information on the details of calling sequences, see the documentation for the CALL macro in UNICOS Macros and Opdefs Reference Manual, publication SR-2403. It is strongly recommended that function linkage be done using the CALL macros. Direct user calls to functions by using the return-jump instruction should be avoided. Scalar functions return the result in registers S1 (and S2 if needed); results for complex double precision are returned in S1 through S4. Vector functions return their result in registers V1 (and V2 if needed); complex double precision are returned in V1 through V4. The number of elements computed for vector functions is determined by the contents of the vector-length register (VL) upon entry. For example, to call the SQRT routine using the call-by-address sequence, let arg1 be the address of the argument. CAL usage: EXT SQRT Declare the name to be an external CALL SQRT,(arg1) Call the function (result)S1 The result is returned in register S1 and stored at the address result Note that the name SQRT must be uppercase. To call the SQRT routine by using the call-by-register convention: (S1) Value of the argument CAL usage: EXT SQRT% Declare the name to be an external CALLV SQRT% Call the function (result)S1 The result is returned in register S1 and stored at the address result To call the routine for vector SQRT using the call-by-register convention, let V1 be the value of the vector argument and VL be the vector length (between 1 and 64 values will be returned). CAL usage: EXT %SQRT% Declare the name to be an external CALLV %SQRT% Call the function The result is returned in register V1. The vector-length register VL is unchanged. Naming conventions Most of the UNICOS math library functions adhere to the following naming convention: NAME Entry for call-by-address NAME% Entry for scalar call-by-register %NAME% Entry for vector call-by-register Note that assembly language does not support generic function names or automatic data type conversion. For example, there is no math library LOG function for the logarithm routine. You must specify either ALOG, DLOG, or CLOG for real, double-precision, or complex logarithm respectively, and the argument must be of the correct type (real, double-precision, or complex). Register conventions The documentation for some of the widely used user-callable functions contains the register usage convention for the function. By default all the Cray Fortran compilers use the call-by-register convention for math library functions (it is the fastest calling sequence), and will put the % prefix or suffix on the function name where needed. If a math library function is declared EXTERNAL or INTRINSIC, the compilers will generate code for the call-by-address method. SEE ALSO INTRO_INTRIN(3I) Cray Standard C Reference Manual, publication SR-2074 CF90 Commands and Directives Reference Manual, publication SR-3901 Fortran Language Reference Manual, Volume 1, publication SR-3902 Fortran Language Reference Manual, Volume 2, publication SR-3903 Fortran Language Reference Manual, Volume 3, publication SR-3905 Intrinsic Procedures Reference Manual, publication SR-2138, for the