United States

Compaq C

# Compaq C
User's Guide for OpenVMS Systems

Previous | Contents | Index

### 6.2.1.32 Cosine ( __COS)

The __COS built-in function is functionally equivalent to its counterpart, `cos` , in the standard header file `<math.h>` .

Its format is also the same:

`#include <math.h> double __COS (double x);`

> ### x

> A radian value.

This built-in offers performance improvements because there is less call overhead associated with its use.

If you include `<math.h>` , the built-in is automatically used for all occurrences of `cos` . To disable the built-in, use `#undef cos` .

### 6.2.1.33 Double-Precision, Floating-Point Arithmetic Built-in Functions

The following built-in functions provide double-precision, floating-point chopped arithmetic:

__ADDG_C | __ADDT_C | __SUBG_C | __SUBT_C
__MULG_C | __MULT_C | __DIVG_C | __DIVT_C

They have the following format:

`double __op{G,T}_C (double operand1, double operand2);`

Where op is one of ADD, SUB, MUL, DIV, and {G,T} represents VAX or IEEE floating-point arithmetic, respectively.

The result of the arithmetic operation is returned.

### 6.2.1.34 Floating-Point Absolute Value ( __FABS)

The __FABS built-in function is functionally equivalent to its counterpart, `fabs` , in the standard header file `<math.h>` .

Its format is also the same:

`#include <math.h> double __FABS (double x);`

> ### x

> A floating-point number.

This built-in offers performance improvements because there is no call overhead associated with its use.

If you include `<math.h>` , the built-in is automatically used for all occurrences of `fab` . To disable the built-in, use `#undef fab` .

### 6.2.1.35 _LEADZ

The _LEADZ built-in function returns the number of leading zeroes (starting at the most significant bit position) in its argument. For example, _LEADZ(1) returns 63, and _LEADZ(0) returns 64.

This function has the following format:

`int64 _LEADZ (unsigned int64);`

### 6.2.1.36 Long Double-Precision, Floating-Point Arithmetic Built-in Functions

The following built-in functions provide long double-precision, floating-point chopped arithmetic:

__ADDX_C | __SUBX_C
__MULX_C | __DIVX_C

They have the following format:

`long double __opX_C (long double operand1, long double operand2);`

Where op is one of ADD, SUB, MUL, DIV.

The result of the arithmetic operation is returned.

### 6.2.1.37 Longword Absolute Value ( __LABS)

The __LABS built-in is functionally equivalent to its counterpart, `labs` , in the standard header file `<stdlib.h>` .

Its format is also the same:

`#include <stdlib.h> long int __LABS (long int x);`

> ### x

> An integer.

This built-in offers performance improvements because there is less call overhead associated with its use.

If you include `<stdlib.h>` , the built-in is automatically used for all occurrences of `labs` . To disable the built-in, use `#undef labs` .

### 6.2.1.38 Lock and Unlock Longword (__LOCK_LONG, __UNLOCK_LONG)

The __LOCK_LONG and __UNLOCK_LONG functions provide a binary spinlock capability based on the low-order bit of a longword.

The __LOCK_LONG function executes in a loop waiting for the bit to be cleared and then sets it within a load-locked/store-conditional sequence; it then issues a memory barrier. The __UNLOCK_LONG function issues a memory barrier and then zeroes the longword.

The __LOCK_LONG_RETRY function returns 1 if the lock was acquired in the specified number of retries and 0 if the lock was not acquired.

The __LOCK_LONG function has one of the following formats:

`int __LOCK_LONG (volatile void *address); int __LOCK_LONG_RETRY (volatile void *address, int retry);`

The __UNLOCK_LONG function has the following format:

`int __UNLOCK_LONG (volatile void *address);`

> ### address

> The quadword-aligned address of the longword used for the lock.

> ### retry

> A retry count of type `int` that indicates the number of times the operation is attempted (which is at least once, even if the retry argument is 0). If the operation cannot be performed successfully in the specified number of retries, the function returns without updating the longword.

### 6.2.1.39 Memory Barrier ( __MB)

The __MB function directs the compiler to generate a memory barrier instruction.

This function has the following format:

`void __MB (void);`

### 6.2.1.40 Memory Copy and Set Functions ( __MEMCPY, __MEMMOVE, __MEMSET)

The __MEMCPY, __MEMMOVE, and __MEMSET built-ins are functionally equivalent to their run-time routine counterparts in the standard header file `<string.h>` .

Their format is also the same:

`#include <string.h> void *__MEMCPY (void *s1, const void *s2, size_t size); void *__MEMMOVE (void *s1, const void *s2, size_t size); void *__MEMSET (void *s, int value, size_t size);`

These built-ins offer performance improvements because there is less call overhead associated with their use.

If you include `<string.h>` , the built-ins are automatically used for all occurrences of `memcpy` , `memmove` , and `memset` . To disable the built-ins, use `#undef memcpy` , `#undef memmove` , and `#undef memset` .

### 6.2.1.41 OR Atomic Longword ( __OR_ATOMIC_LONG)

The __OR_ATOMIC_LONG function performs a logical OR of the specified expression with the aligned longword pointed to by the address parameter within a load-locked/store-conditional code sequence.

This function has the following format:

`int __OR_ATOMIC_LONG (void *address, int expression, ...);`

> ### address

> The address of the aligned longword.

> ### expression

> An integer expression.

> ### ...

> An optional retry count of type `int` . If specified, the retry count indicates the number of times the operation is attempted (which will be at least once, even if the count argument is 0). If the operation cannot be performed successfully in the specified number of retries, a value of 0 is returned. If the operation is successful, a value of 1 is returned.

Note If the optional retry count is omitted, this function loops back for a retry unconditionally on failure. In this case, the function can never return a failure value. It can either return a value of 1 upon successful completion, or it can hang in an endless failure loop.

### 6.2.1.42 OR Atomic Quadword ( __OR_ATOMIC_QUAD)

The __OR_ATOMIC_QUAD function performs a logical OR of the specified expression with the aligned quadword pointed to by the address parameter within a load-locked/store-conditional code sequence.

This function has the following format:

`int __OR_ATOMIC_QUAD (void *address, int expression, ...);`

> ### address

> The address of the aligned quadword.

> ### expression

> An integer expression.

> ### ...

> An optional retry count of type `int` . If specified, the retry count indicates the number of times the operation is attempted (which will be at least once, even if the count argument is 0). If the operation cannot be performed successfully in the specified number of retries, a value of 0 is returned. If the operation is successful, a value of 1 is returned.

Note If the optional retry count is omitted, this function loops back for a retry unconditionally on failure. In this case, the function can never return a failure value. It can either return a value of 1 upon successful completion, or it can hang in an endless failure loop.

### 6.2.1.43 Privileged Architecture Library Code Instructions

The following sections describe the Privileged Architecture Library Code (PALcode) instructions that are available as built-in functions.

### 6.2.1.44 __PAL_BPT

This function is provided for program debugging. It switches the processor to kernel mode and pushes registers R2 through R7, the updated PC, and PS onto the kernel stack. It then dispatches to the address in the breakpoint vector, which is stored in a control block.

This function has the following format:

`void __PAL_BPT (void);`

### 6.2.1.45 __PAL_BUGCHK

This function is provided for error reporting. It switches the processor to kernel mode and pushes registers R2 through R7, the updated PC, and PS onto the kernel stack. It then dispatches to the address in the bugcheck vector, which is stored in a control block.

This function has the following format:

`void __PAL_BUGCHK (void);`

### 6.2.1.46 __PAL_CFLUSH

This function flushes at least the entire physical page specified by the page frame number value from any data caches associated with the current processor. After a CFLUSH is done, the first subsequent load on the same processor to an arbitrary address in the target page is fetched from physical memory.

This function has the following format:

`void __PAL_CFLUSH (int value);`

> ### value

> A page frame number.

### 6.2.1.47 __PAL_CHME

This function allows a process to change its mode to Executive in a controlled manner. The change in mode also results in a change of stack pointers: the old pointer is saved and the new pointer is loaded. Registers R2 through R7, PS, and PC are pushed onto the selected stack. The saved PC addresses the instruction following the CHME instruction.

This function has the following format:

`void __PAL_CHME (void);`

### 6.2.1.48 __PAL_CHMK

This function allows a process to change its mode to kernel in a controlled manner. The change in mode also results in a change of stack pointers: the old pointer is saved and the new pointer is loaded. Registers R2 through R7, PS, and PC are pushed onto the kernel stack. The saved PC addresses the instruction following the CHMK instruction.

This function has the following format:

`void __PAL_CHMK (void);`

### 6.2.1.49 __PAL_CHMS

This function allows a process to change its mode to Supervisor in a controlled manner. The change in mode also results in a change of stack pointers: the old pointer is saved and the new pointer is loaded. Registers R2 through R7, PS, and PC are pushed onto the selected stack. The saved PC addresses the instruction following the CHMS instruction.

This function has the following format:

`void __PAL_CHMS (void);`

### 6.2.1.50 __PAL_CHMU

This function allows a process to call a routine using the change mode mechanism. Registers R2 through R7, PS, and PC are pushed onto the current stack. The saved PC addresses the instruction following the CHMU instruction.

This function has the following format:

`void __PAL_CHMU (void);`

### 6.2.1.51 __PAL_DRAINA

This function stalls instruction issuing until all prior instructions are guaranteed to complete without incurring aborts.

This function has the following format:

`void __PAL_DRAINA (void);`

### 6.2.1.52 __PAL_GENTRAP

This function is used for reporting run-time software conditions.

This function has the following format:

`void __PAL_GENTRAP (uint64 encoded_software_trap);`

> ### encoded_software_trap

> The particular software condition that has occurred.

### 6.2.1.53 __PAL_HALT

This function halts the processor when executed by a process running in kernel mode. This is a privileged function.

This function has the following format:

`void __PAL_HALT (void);`

### 6.2.1.54 __PAL_INSQHIL

This function inserts an entry at the front of a longword queue in an indivisible manner. This operation is interlocked against similar operations by other processors or devices in the system. This function must have write access to header and queue entries. The pointers to head and new_entry must not be equal.

This function has the following format:

`int __PAL_INSQHIL (void *head, void *new_entry); /* At head, interlocked */`

> ### head

> A pointer to the queue header. The header must be aligned on a quadword boundary.

> ### new_entry

> A pointer to the new entry to be inserted. The entry must be aligned on a longword boundary.

There are three possible return values:

- --1 if the entry was not inserted because the secondary interlock failed
- 0 if the entry was inserted but it was not the only entry in the list
- 1 if the entry was inserted and it was the only entry in the list

### 6.2.1.55 __PAL_INSQHILR

This function inserts an entry into the front of a longword queue in an indivisible manner. This operation is interlocked against similar operations by other processors or devices in the system. This function must have write access to the header and queue entries. The pointers to head and new_entry must not be equal. All parts of the queue must be memory resident.

This function has the following format:

`int __PAL_INSQHILR (void *head, void *new_entry); /* At head, interlocked resident */`

> ### head

> A pointer to the queue header. The header must be aligned on a quadword boundary.

> ### new_entry

> A pointer to the new entry to be inserted. The entry must be aligned on a quadword boundary.

There are three possible return values:

- --1 if the entry was not inserted because the secondary interlock failed
- 0 if the entry was inserted but it was not the only entry in the list
- 1 if the entry was inserted and it was the only entry in the list

### 6.2.1.56 __PAL_INSQHIQ

This function inserts an entry at the front of a quadword queue in an indivisible manner. This operation is interlocked against similar operations by other processors or devices in the system. This function must have write access to header and queue entries. The pointers to head and new_entry must not be equal.

This function has the following format:

`int __PAL_INSQHIQ (void *head, void *new_entry); /* At head, interlocked */`

> ### head

> A pointer to the queue header. The header must be aligned on an octaword boundary.

> ### new_entry

> A pointer to the new entry to be inserted. The entry must be aligned on an octaword boundary.

There are three possible return values:

- --1 if the entry was not inserted because the secondary interlock failed
- 0 if the entry was inserted but it was not the only entry in the list
- 1 if the entry was inserted and it was the only entry in the list

### 6.2.1.57 __PAL_INSQHIQR

This function inserts an entry into the front of a quadword queue in an indivisible manner. This operation is interlocked against similar operations by other processors or devices in the system. This function must have write access to the header and queue entries. The pointers to head and new_entry must not be equal. All parts of the queue must be memory resident.

This function has the following format:

`int __PAL_INSQHIQR (void *head, void *new_entry); /* At head, interlocked resident */`

> ### head

> A pointer to the queue header. The header must be aligned on an octaword boundary.

> ### new_entry

> A pointer to the new entry to be inserted. The entry must be aligned on an octaword boundary.

There are three possible return values:

- --1 if the entry was not inserted because the secondary interlock failed
- 0 if the entry was inserted but it was not the only entry in the list
- 1 if the entry was inserted and it was the only entry in the list

### 6.2.1.58 __PAL_INSQTIL

This function inserts an entry at the end of a longword queue in an indivisible manner. This operation is interlocked against similar operations by other processors or devices in the system. This function must have write access to header and queue entries. The pointers to head and new_entry must not be equal.

This function has the following format:

`int __PAL_INSQTIL (void *head, void *new_entry); /* At tail, interlocked */`

> ### head

> A pointer to the queue header. The header must be aligned on a quadword boundary.

> ### new_entry

> A pointer to the new entry to be inserted. The entry must be aligned on a quadword boundary.

There are three possible return values:

- --1 if the entry was not inserted because the secondary interlock failed
- 0 if the entry was inserted but it was not the only entry in the list
- 1 if the entry was inserted and it was the only entry in the list

Previous | Next | Contents | Index

privacy and legal statement