enum

Syntax

    -qenum=small | -qenum=int | -qenum=intlong | -qenum=1 | -qenum=2 | -qenum=4 | -qenum=8
    ENUM=SMALL | ENUM=INT | ENUM=INTLONG | ENUM=1 | ENUM=2 | ENUM=4 | ENUM=8 | ENUM=RESET

Purpose
Specifies the amount of storage occupied by enumerations.

Notes
Valid suboptions are:

The -qenum=small option allocates to an enum variable the amount of storage that is required by the smallest predefined type that can represent that range of enum constants. By default, an unsigned predefined type is used. If any enum constant is negative, a signed predefined type is used.

The enum constants are always of type int, except for the following cases:

• If -q64 is not specified, and if the range of these constants is beyond the range of int, enum constants will have type unsigned int and be 4 bytes long.
• If -q64 is specified, and if the range of these constants is beyond the range of int, enum constants will have type long and be 8 bytes long.

The -qenum=1|2|4 options allocate a specific amount of storage to an enum variable. If the specified storage size is smaller than that required by the range of enum variables, the requested size is kept but a warning is issued. For example:

enum {frog, toad=257} amph;
1506-387 (W) The enum cannot be packed to the requested size.
         Use a larger value for -qenum.
(The enum size is 1 and the value of toad is 1)

For every #pragma options enum= directive that you put in your program, it is good practice to have a corresponding #pragma options=reset as well. This is the only way to prevent one file from potentially changing the enum= setting of another file that #includes it. It is good practice to specify #pragma options enum=reset at the end of any file that contains #pragma options enum= directives.

The table below shows the priority for selecting a predefined type. It also shows the the predefined type, the maximum range of enum constants for the corresponding predefined type, and the amount of storage that is required for that predefined type (that is, the value that the sizeof operator would yield when applied to the minimum-sized enum).

• When you specify #pragma options enum=small, the option stays in effect until it is explicitly turned off with a #pragma options enum=int or #pragma options enum=reset directive.
• If you compile the file using the -qenum=int option on the command line, the first #pragma options=small directive encountered in the source file will override it.
• If you specify -qenum=small on the command line, it is turned off by the first #pragma options enum=int directive found in the source code.
• You cannot change the storage allocation of an enum using a #pragma options enum= within the declaration of an enum. The following code segment generates a warning and the second occurrence of the enum option is ignored:

      #pragma options enum=small
        enum e_tag
        { a,
          b,
      #pragma options enum=int /* cannot be within a declaration */
          c
        } e_var;

  The range of enum constants must fall within the range of either unsigned int or int (signed int). For example, the following code segments contain errors:

      #pragma options enum=small
        enum e_tag { a=-1,
                     b=2147483648   /* larger than maximum int */
                   } e_var;

  The enum constant range does not fit within the range of an int (signed int).

      #pragma options enum=small
        enum e_tag { a=0,
                     b=4294967296 /* larger than maximum int */
                   } e_var;

  The enum constant range does not fit within the range of an unsigned int.

      #pragma options enum=small
        enum e_tag { a=-1,
                     b=2147483647,  /* max int                 */
                     c              /* larger than maximum int */
                  } e_var;

  The enum constant range does not fit within the range of an int (signed int).

The #pragma options keywords are ENUM=SMALL, to specify minimum-sized ENUMS; ENUM=INT, to disable minimum-sized enums; and ENUM=RESET, to reset the enum mapping rule to the rule that was in effect before the current mapping rule. If no previous enum mapping rule was specified in the file, the rule specified when the compiler was invoked is used.

A -qenum=reset option corresponding to the #pragma options ENUM=RESET directive does not exist. Attempting to use -qenum=reset generates a warning message and the option is ignored.

Examples

1. One typical use for the reset suboption is to reset the enumeration size set at the end of an include file that specifies an enumeration storage different from the default in the main file. For example, the following include file, small_enum.h, declares various minimum-sized enumerations, then resets the specification at the end of the include file to the last value on the option stack:

      /*
       * File small_enum.h
       * This enum must fit within an unsigned char type
       */
      #pragma options enum=small
         enum e_tag {a, b=255};
         enum e_tag u_char_e_var; /* occupies 1 byte of storage */
    
      /* Reset the enumeration size to whatever it was before */
      #pragma options enum=reset

   The following source file, int_file.c, includes small_enum.h:

      /*
       * File int_file.c
       * Defines 4 byte enums
       */
      #pragma options enum=int
      enum testing {ONE, TWO, THREE};
      enum testing test_enum;
   
      /* various minimum-sized enums are declared */
      #include "small_enum.h"
    
      /* return to int-sized enums. small_enum.h has reset the
       * enum size
       */
      enum sushi {CALIF_ROLL, SALMON_ROLL, TUNA, SQUID, UNI};
      enum sushi first_order = UNI;

   The enumerations test_enum and test_order both occupy 4 bytes of storage and are of type int. The variable u_char_e_var defined in small_enum.h occupies 1 byte of storage and is represented by an unsigned char data type.

2. If the following C fragment is compiled with the enum=small option:

        enum e_tag {a, b, c} e_var;

   the range of enum constants is 0 through 2. This range falls within all of the ranges described in the table above. Based on priority, the compiler uses predefined type unsigned char.

3. If the following C code fragment is compiled with the enum=small option:

         enum e_tag {a=-129, b, c} e_var;

   the range of enum constants is -129 through -127. This range only falls within the ranges of short (signed short) and int (signed int). Because short (signed short) has a higher priority, it will be used to represent the enum.

4. If you compile a file myprogram.c using the command:

        xlC myprogram.c -qenum=small

   assuming file myprogram.c does not contain #pragma options=int statements, all enum variables within your source file will occupy the minimum amount of storage.

5. If you compile a file yourfile.c that contains the following lines:

          enum testing {ONE, TWO, THREE};
          enum testing test_enum;
    
        #pragma options enum=small
          enum sushi {CALIF_ROLL, SALMON_ROLL, TUNA, SQUID, UNI};
          enum sushi first_order = UNI;
    
        #pragma options enum=int
          enum music {ROCK, JAZZ, NEW_WAVE, CLASSICAL};
          enum music listening_type;

   using the command:

        xlC yourfile.c

   only the enum variable first_order will be minimum-sized (that is, enum variable first_order will only occupy 1 byte of storage). The other two enum variables test_enum and listening_type will be of type int and occupy 4 bytes of storage.

List of Compiler Options and Their Defaults