builtins man page on Tru64

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
Tru64 logo
[printable version]

builtins(4)							   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.
       Intrinsic functions are functions for which the	C  compiler  generates
       optimized 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
       instructions to perform operations that are cumbersome, slow, or impos‐
       sible to implement in the C language.  While the user of inline	assem‐
       bly  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,
       respectively,  32-bit  longword	and  64-bit  quadword  operations  (as
       defined by the Alpha architecture).  In particular,  the	 _LONG	suffix
       designating  a  32-bit longword, should not be confused with the C lan‐
       guage type long, which is 64-bits on Tru64 UNIX.

       The following describes the DEC C (-newc) built-in functions  available
       on  Tru64  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
	      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_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
	      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_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
	      Exchange Longword

	      The  __ATOMIC_EXCH_LONG  function stores the value of the speci‐
	      fied expression into  the	 aligned  longword  specified  by  the
	      address  parameter  within  a load-locked/store-conditional code
	      sequence, 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
	      address  parameter  within  a load-locked/store-conditional code
	      sequence, 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
	      Interlocked

	      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
	      __UNLOCK_LONG  function  issues a memory barrier and then zeroes
	      the longword.

	      The  __LOCK_LONG_RETRY  function	returns	 1  if	the  lock  was
	      acquired	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
	      Release 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
	      region.	The  value  pointed  to by source is compared with the
	      longword 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
	      returns  1  if the store does complete.  Compare and Store Quad‐
	      word

	      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
	      region.  The value pointed to by source  is  compared  with  the
	      quadword	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
	      returns 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)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server Tru64

List of man pages available for Tru64

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net