portal(5)                                                         portal(5)




 NAME    [Toc]    [Back]
      portal - a "window to the future" for applications

 SYNOPSIS    [Toc]    [Back]
      #include <sys/portal.h>

 DESCRIPTION    [Toc]    [Back]
      This header file is a "window to the future" for applications.  It
      will help you to:

      +  Write code that is portable across 32-bit and 64-bit systems,
      +  Avoid undocumented assumptions about sizes of integral types,
      +  Write portable code that needs to be explicit about the sizes of
         integral types,
      +  Write code that is portable to a platform which has different sizes
         of integral types, and
      +  Share frequently used macros that are portable across 32-bit and
         64-bit systems.

      In addition to the macros defined in this file, it includes the header
      files limits.h (see limits(5)) and inttypes.h (see inttypes(5)).

      The following macros are defined in sys/portal.h:

      SET_MASK_BIT( bit_num, type)
           This macro can be used to create a mask that has one bit set.
           bit_num is the position of the bit to set, and type is the data
           type of the mask.  A -1 is returned in the case of overflow or
           underflow.

      SET_MASK_BIT_LOOP(mask, bit_num, type)
           This macro can be used to set a bit in a mask.  mask is the
           current value of the mask, bit_num is the position of the bit to
           set, and type is the data type of the mask.

      SIGN_BIT(type)
           This macro can be used to return the bit position of the sign bit
           for the specified data type.  type is the data type for which to
           return the position of the sign bit.

      SIGN_BIT_MASK(type)
           This macro can be used to return a mask for the sign bit for the
           specified data type.  type is the data type for which to return
           the sign bit mask.

      SIGN_EXTEND(value, old_type, new_type)
           This macro can be used to do a sign extension from one data type
           to another.  value is the current value that is to be signextended.
  old_type is the current data type of value and
           new_type is the new data type of value.




 Hewlett-Packard Company            - 1 -   HP-UX 11i Version 2: August 2003






 portal(5)                                                         portal(5)




      TEST_ENDIAN(endian)
           This macro can be used to check if code has been compiled big or
           little endian.  endian is an integer in which the result will be
           returned.

      The following macros can be used for print formatting and scan
      formatting of values of data types that can change in size based upon
      the compilation flag _FILE_OFFSET_BITS.  Examples of such data types
      are off_t and fpos_t.

      PRIdF64   d print formatting option for a 32-bit or 64-bit size value.
      PRIoF64   o print formatting option for a 32-bit or 64-bit size value.
      PRIxF64   x print formatting option for a 32-bit or 64-bit size value.
      PRIuF64   u print formatting option for a 32-bit or 64-bit size value.

      SCNdF64   d scan formatting option for a 32-bit or 64-bit size value.
      SCNoF64   o scan formatting option for a 32-bit or 64-bit size value.
      SCNxF64   x scan formatting option for a 32-bit or 64-bit size value.
      SCNuF64   u scan formatting option for a 32-bit or 64-bit size value.

 EXAMPLES    [Toc]    [Back]
      The SET_MASK_BIT macro in the following example will turn on the high
      bit in a 64-bit integer.

           SET_MASK_BIT(SIGN_BIT(int64_t), int64_t)

      The SET_MASK_BIT macro in the following example will be used to turn
      on all bits except the sign bit in a 32-bit integer.

           ~SET_MASK_BIT(SIGN_BIT(int32_t), int32_t)

      The SET_MASK_BIT_LOOP macro in the following example will turn on the
      three least significant bits of the maximum integer.

           int i;
           intmax_t mask = 0;

           for (i = 0; i < 3; i++) {
               SET_MASK_BIT_LOOP(mask, i, intmax_t);
           }

      The SIGN_BIT macro in the following example will return the position
      of the sign bit in a 32-bit integer.

           SIGN_BIT(int32_t)    [Toc]    [Back]

      The SIGN_BIT_MASK macro in the following example will return a sign
      bit mask for a 32-bit integer.

           SIGN_BIT_MASK(int32_t)    [Toc]    [Back]




 Hewlett-Packard Company            - 2 -   HP-UX 11i Version 2: August 2003






 portal(5)                                                         portal(5)




      The SIGN_EXTEND macro in the following example will convert the 8-bit
      integer stored in a char data type to a 64-bit integer and correctly
      extend the sign.

           char c;
           int64_t i;

           i = SIGN_EXTEND(c, char, int64_t);

      The TEST_ENDIAN macro in the following example will store a 1 in
      endian if the compilation was big endian; otherwise, it will store a 0
      in endian.

           int endian;

           TEST_ENDIAN(endian);

           if (endian == 0)
               printf("This a little endian system\n");

           if (endian == 1)
               printf("This a big endian system\n");

 AUTHOR    [Toc]    [Back]
      portal.h was developed by HP.

 FILES    [Toc]    [Back]
      /usr/include/sys/portal.h

 SEE ALSO    [Toc]    [Back]
      inttypes(5), limits(5), printf(3S), scanf(3S).


 Hewlett-Packard Company            - 3 -   HP-UX 11i Version 2: August 2003