.comm pseudo-op

Purpose

Defines an uninitialized block of storage called a common block.

Syntax

Item	Description
.comm	Qualname , Expression, [, Number [ , Visibility ] ]

where QualName = Name[[StorageMappingClass]]

Note: Name is required. StorageMappingClass is optional and enclosed within brackets if specified. RW is the assumed default if StorageMappingClass is omitted. If Visibility is specified, Number can be omitted.

Description

The .comm pseudo-op defines a common block, which is an uninitialized block of storage. The QualName parameter specifies the name of the common block. QualName is defined as a global symbol.

The Expression parameter specifies the size of the common block in bytes.

Note: Symbols with the TD StorageMappingClass are conventionally no longer than a pointer. (A pointer is 4 bytes long in 32-bit mode and 8 bytes long in 64-bit mode.)

The valid values for the StorageMappingClass parameter are BS, RW, TD, UC, and UL. These values are explained in the description of the .csect pseudo-op. If any other value is used for the StorageMappingClass parameter, the default value RW is used, and if the -w flag was used, a warning message is reported.

If TD is used for the storage mapping class, a block of zeroes, the length specified by the Expression parameter, will be written into the TOC area as an initialized csect in the .data section. If RW, UC, or BS is used as the storage mapping class, the block is not initialized in the current module and has symbol type CM (Common). At load time, the space for CM control sections with RW, UC, or BC storage mapping classes is created in the .bss section at the end of the .data section.

Several modules can share the same common block. If any of those modules have an external Control Section (csect) with the same name and the csect with the same name has a storage mapping class other than BS or UC, then the common block is initialized and becomes that other Control Section. If the common block has TD as its storage mapping class, the csect will be in the TOC area. This is accomplished at bind time.

If more than one uninitialized common block with the same Qualname is found at link time, space is reserved for the largest one.

A common block can be aligned by using the Number parameter, which is specified as the log base 2 of the alignment desired.

The visibility of the common block can be specified by using the Visibility parameter.

Parameters

Item	Description
Qualname	Specifies the name and storage mapping class of the common block. If the StorageMappingClass part of the parameter is omitted, the default value RW is used. Valid StorageMappingClass values for a common block are RW, TD, UC, BS, and UL.
Expression	Specifies the absolute expression that gives the length of the specified common block in bytes.
Number	Specifies the optional alignment of the specified common block. This is specified as the log base 2 of the alignment desired. For example, an alignment of 8 (or doubleword) would be 3 and an alignment of 2048 would be 11. This is similar to the argument for the .align pseudo-op.
Visibility	Specifies the visibility of the symbol. Valid values are exported, protected, hidden, and internal. Symbol visibilities are used by linker.

Examples

The following example demonstrates the use of the .comm pseudo-op:


        .comm proc,5120
# proc is an uninitialized common block of
# storage 5120 bytes long which is
# global
 
# Assembler SourceFile A contains:
        .comm st,1024
# Assembler SourceFile B contains:
 
        .globl st[RW]
        .csect st[RW]
        .long 1
        .long 2
 
# Using st in the above two programs refers to
# Control Section st in Assembler SourceFile B.

This example shows how two different modules access the same data:

Source code for C module td2.c:


/* This C module named td2.c   */
extern long   t_data;
extern  void mod_s();
main()
{
        t_data = 1234;
         mod_s();
         printf("t_data is %d\n", t_data);
}

Source for assembler module mod2.s:


        .file "mod2.s"
        .csect .mod_s[PR]
        .globl .mod_s[PR]
        .set    RTOC, 2
        l   5, t_data[TD](RTOC)  # Now GPR5 contains the
                                 # t_data value
        ai  5,5,14
        stu 5, t_data[TD](RTOC)
        br
        .toc
        .comm  t_data[TD],4  # t_data is a global symbol

Instructions for making executable td2 from the C and assembler source:
```
as -o mod2.o mod2.s
cc -o td2 td2.c mod2.o
```
Running td2 will cause the following to be printed:
```
t_data is 1248
```

The following example shows how to specify visibility for a symbol:

		.comm block, 1024, , exported
		# block is an uninitialized block of storage 1024 bytes 
		# long. At link time, block is exported.