omp_get_mapped_ptr (GNU libgomp)

#### 3.8.13 `omp_get_mapped_ptr` – Return device pointer to a host pointer ¶

Description:

  If the device number refers to the initial device, `omp_get_mapped_ptr` returns the value of the passed ptr. Otherwise, if associated storage to the passed host pointer ptr exists on device associated with device_num, it returns that pointer. In all other cases and in cases of an error, a null pointer is returned.

  If the device number is not the initial device and the pointer points to a variable that is specified in a `declare target` directive: When requiring `unified_shared_memory` or `self_maps`, a null pointer is returned if the variable appears in a `link` or `enter` clause. Otherwise, the corresponding device memory is returned; with the `link` clause, GCC returns the address of the pointer-typed link variable on the device, not to the data that is mapped to that variable.

  The association of storage location is established either via an explicit or implicit `map` clause, the `declare target` directive or the `omp_target_associate_ptr` routine.

  Running this routine in a `target` region except on the initial device is not supported.

C/C++

  Prototype: | `void *omp_get_mapped_ptr(const void *ptr, int device_num);`

Fortran:

  Interface: | `type(c_ptr) function omp_get_mapped_ptr(ptr, device_num) bind(C)`
  | `use, intrinsic :: iso_c_binding, only: c_ptr, c_int`
  | `type(c_ptr), value :: ptr`
  | `integer(c_int), value :: device_num`

See also:

  `omp_target_is_present` – Check whether storage is mapped, `omp_target_associate_ptr` – Associate a device pointer with a host pointer

Reference:

  OpenMP specification v5.1, Section 3.8.11