*** UNIX MANUAL PAGE BROWSER ***

builtins(4) Kernel Interfaces Manual builtins(4) NAME builtins.h - Header file declaring functions that are unconditionally intrinsic. SYNOPSIS #include <builtins.h> DESCRIPTION A builtin is a function whose name is specially recognized by the com- piler and is similar to declaring the function to be intrinsic. In- trinsic functions are functions for which the C compiler generates op- timized code in certain situations possibly avoiding a function call. While intrinsic functions can have their special treatment enabled or disabled by pragmas, builtin functions are always treated specially and always have names in the reserved namespace. Builtin functions allow you to directly access hardware and machine in- structions to perform operations that are cumbersome, slow, or impossi- ble to implement in the C language. While the user of inline assembly code can provide similar capabilities, builtin functions provide a higher-level interface for some common operations that are complex to implement well in assembly language. See the file for further informa- tion on asm in-line assembly language generator functions. These functions are very efficient because they are built into the DEC C (-newc) compiler. This means that a call to one of these functions does not result in a reference to a function in the run-time library or to a function in your program. Instead, the compiler generates the machine instructions necessary to carry out the function directly at the call site. Be sure to include the <builtins.h> header file in your source program to access these built-in functions and add a line similar to the fol- lowing to the cc command line (the file is not located in the default header file directory (/usr/include)). -I /usr/includemachine Note that by convention, the suffixes _LONG and _QUAD designate, re- spectively, 32-bit longword and 64-bit quadword operations (as defined by the Alpha architecture). In particular, the _LONG suffix designat- ing a 32-bit longword, should not be confused with the C language type long, which is 64-bits on Digital UNIX. The following describes the DEC C (-newc) built-in functions available on Digital UNIX. Note that the return value is always the old value of the location before the operation is performed. The retry variants provide successful status through the status pointer. The only excep- tions are the __LOCK_LONG_RETRY and __ACQUIRE_SEM_LONG_RETRY functions. Atomic Add Longword The __ATOMIC_ADD_LONG function adds the specified expression to the aligned longword pointed to by the address parameter within a load-locked/store-conditional code sequence and returns the value of the longword before the addition was performed. This function has one of the following formats: int __ATOMIC_ADD_LONG ( volatile void *__address, int __expression); int __ATOMIC_ADD_LONG_RETRY ( volatile void *__address, int __expression, int __retry, int *__status); address The longword-aligned address ofthe data segment. expression An integer expression. retry A count of type int. 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, the function returns without updating the longword. status A pointer to an integer that is set to 0 if the operation did not succeed within the specified number of retries, and set to 1 if the operation succeeded. Atomic Add Quadword The __ATOMIC_ADD_QUAD function adds the specified expression to the aligned quadword pointed to by the address parameter within a load-locked/store-conditional code sequence and returns the value of the quadword before the operation was performed. This function has one of the following formats: long __ATOMIC_ADD_QUAD ( volatile void *__address, long __expression); long __ATOMIC_ADD_QUAD_RETRY ( volatile void *__address, long __expression, int __retry, int *__status); address The quadword-aligned address of the data segment. expression An expression of type long. retry A count of type int. 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, the function returns without updating the longword. status A pointer to an integer that is set to 0 if the operation did not succeed with in the specified number of retries, and set to 1 if the operation succeeded. Atomic AND Longword The __ATOMIC_AND_LONG function performs a logical AND of the specified expression with the aligned longword pointed to by the address parameter within a load-locked/store-conditional code sequence and returns the value of the longword before the addi- tion was performed. This function has one of the following formats: int __ATOMIC_AND_LONG ( volatile void *__address, int __expression); int __ATOMIC_AND_LONG_RETRY ( volatile void *__address, int __expression, int __retry, int *__status); address The longword-aligned address of the data segment. expression An integer expression. retry A count of type int. 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, the function returns without updating the longword. status A pointer to an integer that is set to 0 if the operation did not succeed with in the specified number of retries, and set to 1 if the operation succeeded. Atomic AND Quadword The __ATOMIC_AND_QUAD function performs a logical AND of the specified expression with the aligned quadword pointed to by the address parameter within a load-locked/store-conditional code sequence and returns the value of the longword before the addi- tion was performed. This function has one of the following formats: long __ATOMIC_AND_QUAD ( volatile void *__address, long __expression); long __ATOMIC_AND_QUAD_RETRY ( volatile void *__address, long __expression, int __retry, int *__status); address The quadword-aligned address of the data segment. expression An expression of type long. retry A count of type int. 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, the function returns without updating the longword. status A pointer to an integer that is set to 0 if the operation did not succeed with in the specified number of retries, and set to 1 if the operation succeeded. Atomic OR Longword The __ATOMIC_OR_LONG function performs a logical OR of the spec- ified expression with the aligned longword pointed to by the ad- dress parameter within a load-locked/store-conditional code se- quence and returns the value of the longword before the addition was performed. This function has one of the following formats: int __ATOMIC_OR_LONG ( volatile void *__address, int __expression); int __ATOMIC_OR_LONG_RETRY ( volatile void *__address, int __expression, int __retry, int *__status); address The longword-aligned address of the data segment. expression An integer expression. retry A count of type int. 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, the function returns without updating the longword. status A pointer to an integer that is set to 0 if the operation did not succeed with in the specified number of retries, and set to 1 if the operation succeeded. Atomic OR Quadword The __ATOMIC_OR_QUAD function performs a logical OR of the spec- ified expression with the aligned quadword pointed to by the ad- dress parameter within a load-locked/store-conditional code se- quence and returns the value of the longword before the addition was performed. This function has one of the following formats: long __ATOMIC_OR_QUAD ( volatile void *__address, long __expression); long __ATOMIC_OR_QUAD_RETRY ( volatile void *__address, long __expression, int __retry, int *__status); address The quadword-aligned address of the data segment. expression An expression of type long. retry A count of type int. 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, the function returns without updating the longword. status A pointer to an integer that is set to 0 if the operation did not succeed with in the specified number of retries, and set to 1 if the operation succeeded. Atomic Increment Longword The __ATOMIC_INCREMENT_LONG function increments by 1 the aligned longword pointed to by the address parameter within a load- locked/store-conditional code sequence and returns the value of the longword before the addition was performed. This function has the following format: int __ATOMIC_INCREMENT_LONG ( volatile void *__address); address The longword-aligned address of the data segment. Atomic Incre- ment Quadword The __ATOMIC_INCREMENT_QUAD function increments by 1 the aligned quadword pointed to by the address parameter within a load- locked/store-conditional code sequence and returns the value of the longword before the addition was performed. This function has the following format: long __ATOMIC_INCREMENT_QUAD ( volatile void *__address); address The quadword-aligned address of the data segment. Atomic Decre- ment Longword The __ATOMIC_DECREMENT_LONG function decrements by 1 the aligned longword pointed to by the address parameter within a load- locked/store-conditional code sequence and returns the value of the longword before the addition was performed. This function has the following format: int __ATOMIC_DECREMENT_LONG ( volatile void *__address); address The longword-aligned address of the data segment. Atomic Decre- ment Quadword The __ATOMIC_DECREMENT_QUAD function decrements by 1 the aligned quadword pointed to by the address parameter within a load- locked/store-conditional code sequence and returns the value of the longword before the addition was performed. This function has the following format: long __ATOMIC_DECREMENT_QUAD ( volatile void *__address); address The quadword-aligned address of the data segment. Atomic Ex- change Longword The __ATOMIC_EXCH_LONG function stores the value of the speci- fied expression into the aligned longword specified by the ad- dress parameter within a load-locked/store-conditional code se- quence, and returns the value of the longword before the store was performed. This function has one of the following formats: int __ATOMIC_EXCH_LONG ( volatile void *__address, int __expression); int __ATOMIC_EXCH_LONG_RETRY ( volatile void *__address, int __expression, int __retry, int *__status); address The longword-aligned address of the data segment. expression An integer expression. retry A count of type int. 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, the function returns without updating the longword. status A pointer to an integer that is set to 0 if the operation did not succeed with in the specified number of retries, and set to 1 if the operation succeeded. Atomic Exchange Quadword The __ATOMIC_EXCH_QUAD function stores the value of the speci- fied expression into the aligned quadword specified by the ad- dress parameter within a load-locked/store-conditional code se- quence, and returns the value of the quadword before the store was performed. This function has one of the following formats: long __ATOMIC_EXCH_QUAD ( volatile void *__address, long __expression); long __ATOMIC_EXCH_QUAD_RETRY ( volatile void *__address, long __expression, int __retry, int *__status); address The quadword-aligned address of the data segment. expression An expression of type long. retry A count of type int. 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, the function returns without updating the longword. status A pointer to an integer that is set to 0 if the operation did not succeed with in the specified number of retries, and set to 1 if the operation succeeded. Test for Bit Clear Then Clear Bit Interlocked The __INTERLOCKED_TESTBITCC_QUAD function performs the following functions in interlocked fashion: Returns the complement of the specified bit before being cleared Clears the bit This function has one of the following formats: int __INTERLOCKED_TESTBITCC_QUAD ( volatile void *__address, int __bit_position); int __INTERLOCKED_TESTBITCC_QUAD_RETRY ( volatile void *__address, int __bit_position, int __retry, int *__status); address The quadword-aligned base address of the bit field. position The position within the field of the bit that you want cleared, in the range of 0 to 63. retry A count of type int. 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, the function returns without updating the longword. status A pointer to an integer that is set to 0 if the operation did not succeed with in the specified number of retries, and set to 1 if the operation succeeded. Test for Bit Set Then Set Bit In- terlocked The __INTERLOCKED_TESTBITSS_QUAD function performs the following operations in interlocked fashion: Returns the value of the specified bit before being set Sets the bit This function has one of the following formats: int __INTERLOCKED_TESTBITSS_QUAD ( volatile void *__address, int __bit_position); int __INTERLOCKED_TESTBITSS_QUAD_RETRY ( volatile void *__address, int __bit_position, int __retry, int *__status); address The quadword-aligned base address of the bit field. position The position within the field of the bit that you want set, in the range of 0 to 63. retry A count of type int. 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, the function returns without updating the longword. status A pointer to an integer that is set to 0 if the operation did not succeed with in the specified number of retries, and set to 1 if the operation succeeded. Lock and Unlock Longword 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-condi- tional sequence; it then issues a memory barrier. The __UN- LOCK_LONG function issues a memory barrier and then zeroes the longword. The __LOCK_LONG_RETRY function returns 1 if the lock was ac- quired within the specified number of returns and 0 if the lock was not acquired. This function has one of the following formats: void __LOCK_LONG ( volatile void *__address); int __LOCK_LONG_RETRY ( volatile void *__address, int __retry); The __UNLOCK_LONG function has the following format: void __UNLOCK_LONG ( volatile void *__address); address The quadword-aligned address of the longword used for the lock. retry A count of type int. 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, the function returns without updating the longword. Acquire and Re- lease Longword Semaphore The __ACQUIRE_SEM_LONG and__RELEASE_SEM_LONG functions provide a counted semaphore capability where the positive value of a long- word is interpreted as the number of resources are available. The __ACQUIRE_SEM_LONG function loops until the longword has a positive value and then decrements it within a load- locked/store-conditional sequence; it then issues a memory bar- rier. The __RELEASE_SEM_LONG function issues a memory barrier and then does an _ATOMIC_INCREMENT_LONG on the longword. The __ACQUIRE_SEM_LONG_RETRY function returns 1 if the resource count was successfully decremented within the specified number of retries, and 0 otherwise. Acquire Semaphore Longword The __ACQUIRE_SEM_LONG function has one of the following for- mats: void __ACQUIRE_SEM_LONG ( volatile void *__address); int __ACQUIRE_SEM_LONG_RETRY ( volatile void *__address, int __retry); address The longword-aligned address of the resource count. retry A count of type int. 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, the function returns without updating the longword. Release Sema- phore Longword The __RELEASE_SEM_LONG function has the following format: void __RELEASE_SEM_LONG ( volatile void *__address); address The longword-aligned address of the resource count. Compare and Store Longword The __CMP_STORE_LONG function has the following format: int __CMP_STORE_LONG ( volatile void *__source, int __old_value, int __new_value, volatile void *__dest); This function performs a conditional atomic compare and update operation involving one or two longwords in the same lock re- gion. The value pointed to by source is compared with the long- word old_value. If they are equal, the longword new_value is conditionally stored into the longword pointed to by dest. The store will not complete if the compare yields unequal values or if there is an intervening store to the lock region involved. To be in the same lock region, source and dest must point to aligned longwords in the same naturally aligned 16-byte region. The function returns 0 if the store does not complete, and re- turns 1 if the store does complete. Compare and Store Quadword The __CMP_STORE_QUAD function has the following format: int __CMP_STORE_QUAD ( volatile void *__source, long __old_value, long __new_value, volatile void *__dest); This function performs a conditional atomic compare and update operation involving one or two quadwords in the same lock re- gion. The value pointed to by source is compared with the quad- word old_value. If they are equal, the quadword new_value is conditionally stored into the quadword pointed to by dest. The store will not complete if the compare yields unequal values or if there is an intervening store to the lock region involved. To be in the same lock region, source and dest must point to aligned quadwords in the same naturally aligned 16-byte region. The function returns 0 if the store does not complete, and re- turns 1 if the store does complete. Add Aligned Word Inter- locked The __ADAWI function adds its source operand to the destination. This function is interlocked against similar operations by other processors or devices in the system and is provided to emulate the VAX instructions of that name. This function returns the value of bits 0:3 of a VAX Program Status Longword. The __ADAWI function has the following format: int __ADAWI ( short __src, volatile short *__dest); __src The value to be added to the destination. __dest A pointer to the destination. The destination must be aligned on a word boundary. Because of their prior availability on the OpenVMS Alpha platform, there are a number of additional builtins that are recognized by DEC C and declared in the builtins.h file. These builtins should not gener- ally be used in new code. These include a number of atomic/interlocked operations that issue memory barriers before and after the load- locked/store-conditional sequence, and some single-instruction func- tions that are more naturally implemented using the asm facility. The referenced header files contain more specific information. FILES /usr/include/machine/builtins.h RELATED INFORMATION Functions: asm, fasm, dasm cc (1) Programmer's Guide Files: /usr/include/c_asm.h delim off builtins(4)