unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



builtins(4)							  builtins(4)



NAME

  builtins.h - Header file declaring functions that are	unconditionally
  intrinsic.

SYNOPSIS

  #include <&lt;builtins.h>&gt;

DESCRIPTION

  A builtin is a function whose	name is	specially recognized by	the compiler
  and is similar to declaring the function to be intrinsic.  Intrinsic func-
  tions	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 impossible
  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 /usr/include/c_asm.h 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 func-
  tion in your program.	Instead, the compiler generates	the machine instruc-
  tions	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	following to
  the cc command line (the file	is not located in the default header file
  directory (/usr/include)).

  -I /usr/include/machine

  Note that by convention, the suffixes	_LONG and _QUAD	designate, respec-
  tively, 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 language 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 exceptions 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 parame-
       ter 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_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 addition 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 specified
       expression with the aligned longword pointed to by the address parame-
       ter 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_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 specified
       expression with the aligned quadword pointed to by the address parame-
       ter 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:



       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	long-
       word 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 Increment	Quadword

       The __ATOMIC_INCREMENT_QUAD function increments by 1 the	aligned	quad-
       word 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 Decrement	Longword

       The __ATOMIC_DECREMENT_LONG function decrements by 1 the	aligned	long-
       word 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 Decrement	Quadword

       The __ATOMIC_DECREMENT_QUAD function decrements by 1 the	aligned	quad-
       word 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 specified
       expression into the aligned longword specified by the address parame-
       ter 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 specified
       expression into the aligned quadword specified by the address parame-
       ter 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	func-
       tions 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-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
       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 longword 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 barrier.  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 formats:



	    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 Semaphore 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 opera-
       tion 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 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 opera-
       tion 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	Interlocked

       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 instruc-
       tions 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 generally	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 functions 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