# USE

Statement: Gives a program unit accessibility to public entities in a module.

USE [[, mod-nature] ::] name [, rename-list]

USE [[, mod-nature] ::] name, ONLY : [ only-list]

mod-nature | Is INTRINSIC or NON_INTRINSIC. If INTRINSIC is used, name must be the name of an intrinsic module. If NON_INTRINSIC is used, name must be the name of an nonintrinsic module. If mod-nature is not specified, name must be the name of an intrinsic or nonintrinsic module. If both are provided, the nonintrinsic module is used. It is an error to specify a user module and an intrinsic module of the same name in the same program unit (see Examples).
name | Is the name of the module.
rename-list | Is one or more items, separated by commas, having the following form: local-name=> mod-name
local-name | Is the name of the entity in the program unit using the module or is "OPERATOR (op-name)", where op-name is the name of a defined operator in the program unit using the module.
mod-name | Is the name of a public entity in the module or is "OPERATOR (op-name)", where op-name is the name of a public entity in the module.
only-list | Is one or more items, separated by commas, where each item is the name of a public entity in the module or a generic identifier (a generic name, a defined operator specified as "OPERATOR (op-name)", or defined assignment). An entity in the only-list can also take the form: [local-name =>] mod-name

## Description

If the USE statement is specified without the ONLY option, the program unit has access to all public entities in the named module.

If the USE statement is specified with the ONLY option, the program unit has access to only those entities following the option.

If more than one USE statement for a given module appears in a scoping unit, the following rules apply:

- If one USE statement does not have the ONLY option, all public entities in the module are accessible, and any rename-lists and only-lists are interpreted as a single, concatenated rename-list.

- If all the USE statements have ONLY options, all the only-lists are interpreted as a single, concatenated only-list. Only those entities named in one or more of the only-lists are accessible.

If two or more generic interfaces that are accessible in a scoping unit have the same name, the same operator, or are both assignments, they are interpreted as a single generic interface. Otherwise, multiple accessible entities can have the same name only if no reference to the name is made in the scoping unit.

The local names of entities made accessible by a USE statement must not be declared locally other than in a PUBLIC, PRIVATE, VOLATILE, or ASYNCHRONOUS statement. Within a module, if a use-associated entity is declared VOLATILE or ASYNCHRONOUS, it has the default accessibility of a locally declared identifier.

The local names of use-associated entities can appear in namelist group lists, but not in a COMMON or EQUIVALENCE statement.

If the name of every module from which a use-associated entity is accessed appears in an accessibility statement, the default accessibility of the entity is PRIVATE if every such accessibility statement is PRIVATE, and PUBLIC if any such accessibility statement is PUBLIC.

The accessibility of a use associated entity within a module can be determined by applying the following rules in the specified order:

1. It is PUBLIC if the entity is specified in the entity-list of a PUBLIC statement. It is PRIVATE if the entity is specified in the entity-list of a PRIVATE statement.

2. If the entity is declared locally in an ASYNCHRONOUS or VOLATILE statement, go to 5.

3. It is PUBLIC if any module through which the entity is accessible appears in a PUBLIC statement.

4. It is PRIVATE if every module thru which the entity is accessible appears in a PRIVATE statement.

5. It is PUBLIC if there is a PUBLIC statement with no entity-list specified in the module. It is PRIVATE if there is a PRIVATE statement with no entity-list specified in the module.

6. It is PUBLIC.

## Examples

The following shows examples of the USE statement:

    MODULE MOD_A
      INTEGER :: B, C
      REAL E(25,5), D(100)
    END MODULE MOD_A
    ...
    SUBROUTINE SUB_Y
      USE MOD_A, DX => D, EX => E   ! Array D has been renamed DX and array E
      ...                           ! has been renamed EX. Scalar variables B
    END SUBROUTINE SUB_Y            ! and C are also available to this
    ...                             ! subroutine (using their module names).
    SUBROUTINE SUB_Z
      USE MOD_A, ONLY: B, C         ! Only scalar variables B and C are
      ...                           !   available to this subroutine
    END SUBROUTINE SUB_Z
    ...

You must not specify a user module and an intrinsic module of the same name in the same program unit. For example, if you specify a user module named ISO_FORTRAN_ENV, then it is illegal to specify the following in the same program unit:

    USE :: ISO_FORTRAN_ENV
    USE, INTRINSIC :: ISO_FORTRAN_ENV

The following example shows a module containing common blocks:

    MODULE COLORS
      COMMON /BLOCKA/ C, D(15)
      COMMON /BLOCKB/ E, F
      ...
    END MODULE COLORS
    ...
    FUNCTION HUE(A, B)
      USE COLORS
      ...
    END FUNCTION HUE

The USE statement makes all of the variables in the common blocks in module COLORS available to the function HUE.

To provide data abstraction, a user-defined data type and operations to be performed on values of this type can be packaged together in a module. The following example shows such a module:

    MODULE CALCULATION
      TYPE ITEM
        REAL :: X, Y
      END TYPE ITEM

      INTERFACE OPERATOR (+)
        MODULE PROCEDURE ITEM_CALC
      END INTERFACE

    CONTAINS
      FUNCTION ITEM_CALC (A1, A2)
        TYPE(ITEM) A1, A2, ITEM_CALC
        ...
      END FUNCTION ITEM_CALC
      ...
    END MODULE CALCULATION

    PROGRAM TOTALS
    USE CALCULATION
    TYPE(ITEM) X, Y, Z
      ...
      X = Y + Z
      ...
    END

The USE statement allows program TOTALS access to both the type ITEM and the extended intrinsic operator + to perform calculations.

The following shows another example:

     ! Module containing original type declarations
     MODULE geometry
     type square
        real side
        integer border
     end type
     type circle
        real radius
        integer border
     end type
     END MODULE

     ! Program renames module types for local use.
     PROGRAM test
     USE GEOMETRY,LSQUARE=>SQUARE,LCIRCLE=>CIRCLE
     ! Now use these types in declarations
     type (LSQUARE) s1,s2
     type (LCIRCLE) c1,c2,c3

The following shows a defined operator in a USE statement:

      USE mymod, OPERATOR(.localop.) => OPERATOR(.moduleop.)

Entities in modules can be accessed either through their given name, or through aliases declared in the USE statement of the main program unit. For example:

      USE MODULE_LIB, XTABS => CROSSTABS

This statement accesses the routine called `CROSSTABS` in `MODULE_LIB` by the name `XTABS`. This way, if two modules have routines called `CROSSTABS`, one program can use them both simultaneously by assigning a local name in its USE statement.

When a program or subprogram renames a module entity, the local name (`XTABS`, in the preceding example) is accessible throughout the scope of the program unit that names it.

The ONLY option also allows public variables to be renamed. Consider the following:

      USE MODULE_A, ONLY: VARIABLE_A => VAR_A

In this case, the host program accesses only `VAR_A` from module `A`, and refers to it by the name `VARIABLE_A`.

Consider the following example:

      MODULE FOO
         integer foos_integer
       PRIVATE
         integer foos_my_integer
      END MODULE FOO

PRIVATE, in this case, makes the PRIVATE attribute the default for the entire module `FOO`. To make `foos_integer` accessible to other program units, add the line:

      PUBLIC :: foos_integer

Alternatively, to make only `foos_my_integer` inaccessible outside the module, rewrite the module as follows:

      MODULE FOO
        integer foos_integer
        integer, private::foos_my_integer
      END MODULE FOO

Given the following module declarations:

      MODULE mod1
        INTEGER x1
      END MODULE

      MODULE mod2
        USE mod1
        INTEGER x2
      END MODULE

Then in module mod3 below, x1 has default accessibility of PRIVATE:

      MODULE mod3
        USE mod2
        PUBLIC x2     ! x2 is PUBLIC
        PRIVATE       ! x1 is PRIVATE
      END MODULE

In mod4 below, even though x1 is declared in mod1, and mod1 is declared PRIVATE in mod4, x1 is PUBLIC since it is declared VOLATILE and it assumes the default accessibility of PUBLIC of a locally declared identifier in mod4:

      MODULE mod4
        USE mod1
        PRIVATE mod1
        VOLATILE x1    ! x1 is PUBLIC
      END MODULE

In mod5 below, x1 and x2 are both PRIVATE since all modules from which they are accessed appear in PRVATE statements:

      MODULE mod5
        USE mod1
        USE mod2
        PRIVATE mod1
        PRIVATE mod2   ! x1 and x2 are PRIVATE
      END MODULE

However, in mod6 below, both x1 and x2 are PUBLIC since they are accessible thru the use of mod2 which is declared PUBLIC:

      MODULE mod6
        USE mod1
        USE mod2
        PRIVATE mod1
        PUBLIC mod2    !  x1 and x2 are PUBLIC
      END MODULE

Parent topic: T to Z

## See Also

Program Units and Procedures