USE

Purpose

The USE statement is a module reference that provides local access to the public entities of a module.

Rules

The USE statement can only appear prior to all other statements in specification_part. Multiple USE statements may appear within a scoping unit.

At the time the file containing the USE statement is being compiled, the specified module must precede the USE statement in the file or the module must have been already compiled in another file. Each referenced entity must be the name of a public entity in the module.

Entities in the scoping unit become use-associated with the module entities, and the local entities have the attributes of the corresponding module entities.

By default, either an intrinsic module or a non-intrinsic module with the specified name is accessed. If both an intrinsic module and a non-intrinsic module have this name, the non-intrinsic module is accessed. If you specify INTRINSIC or NON_INTRINSIC, only an intrinsic module or only a non-intrinsic module can be accessed.

When you rename an operator in a rename-list or an only-list, the use-defined-operator is identified by the local-defined-operator for the scoping unit that contains the USE statement. That operator must be a public entity that is not a generic binding within the module you specify in the USE statement.

In addition to the PRIVATE attribute, the ONLY clause of the USE statement provides further constraint on which module entities can be accessed. If the ONLY clause is specified, only entities named in the only_list are accessible. If no list follows the keyword, no module entities are accessible. If the ONLY clause is absent, all public entities are accessible.

If a scoping unit contains multiple USE statements, all specifying the same module, and one of the statements does not include the ONLY clause, all public entities are accessible. If each USE statement includes the ONLY clause, only those entities named in one or more of the only_lists are accessible.

You can rename an accessible entity for local use. A module entity can be accessed by more than one local name. If no renaming is specified, the name of the use-associated entity becomes the local name. The local name of a use-associated entity cannot be redeclared. However, if the USE statement appears in the scoping unit of a module, the local name can appear in a PUBLIC or PRIVATE statement.

If multiple generic interfaces that are accessible to a scoping unit have the same local name, operator, or assignment, they are treated as a single generic interface. In such a case, one of the generic interfaces can contain an interface body to an accessible procedure with the same name. Otherwise, any two different use-associated entities can only have the same name if the name is not used to refer to an entity in the scoping unit. If a use-associated entity and host entity share the same name, the host entity becomes inaccessible through host association by that name.

The accessed entities have the attributes specified in the module, except that an entity may have a different accessibility attribute or it can have the VOLATILE attribute in the local scoping unit even if the associated module entity does not.

A module must not reference itself, either directly or indirectly. For example, module X cannot reference module Y if module Y references module X.

Consider the situation where a module (for example, module B) has access through use association to the public entities of another module (for example, module A). The accessibility of module B's local entities (which includes those entities that are use-associated with entities from module A) to other program units is determined by the PRIVATE and PUBLIC attributes, or, if absent, through the default accessibility of module B. Of course, other program units can access the public entities of module A directly.

Example: Renaming a defined operator (Fortran 2003)

module temp
	type real_num
	real :: x
	end type

	interface operator (.add.)
	module procedure real_add
	end interface

	contains
	funtion real_add(a,b)
	type(real_num) :: real_add
	type(real_num), intent(in) :: a,b
	real_add%x = a%x+b%x
	end function real_add

end module

program main
use temp , operator(.plus.) => operator(.add.)
type(real_num) :: a,b,c
c=a.plus.b
end program

Example: Invalid because operator has a private attribute

module temp
	type real_num
	real :: x
	end type

	interface operator (.add.)
	module procedure real_add
	end interface

	private :: operator(.add.) !operator is given the private attribute

	contains
	function real_add(a,b)
	type(real_num) :: real_add
	type(real_num), intent(in) :: a,b
	real_add%x = a%x+b%x
	end function real_add

	contains

	end module

program main
!operator cannot be renamed because it has a private attribute. 
use temp , operator(.plus.) => operator(.add.)
type(real_num) :: a,b,c
c=a.plus.b
end program

The following example is invalid:

Module mod1
    use, intrinsic :: ieee_exceptions
end Module

Module mod2
   use, non_intrinsic :: ieee_exceptions
end Module

Program invalid_example
   use mod1
   use mod2
! ERROR: a scoping unit must not access an
! intrinsic module and a non-intrinsic module
! with the same name.

end program

Related information

• Modules
• PRIVATE
• VOLATILE
• PUBLIC
• Order of statements and execution sequence