gcc/fortran/doc/gfortran/intrinsic-procedures/cassociated.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. _c_associated:
   7
   8 C_ASSOCIATED --- Status of a C pointer
   9 **************************************
  10
  11 .. index:: C_ASSOCIATED, association status, C pointer, pointer, C association status
  12
  13 .. function:: C_ASSOCIATED(c_ptr_1, c_ptr_2)
  14
  15   ``C_ASSOCIATED(c_ptr_1[, c_ptr_2])`` determines the status of the C pointer
  16   :samp:`{c_ptr_1}` or if :samp:`{c_ptr_1}` is associated with the target :samp:`{c_ptr_2}`.
  17
  18   :param c_ptr_1:
  19     Scalar of the type ``C_PTR`` or ``C_FUNPTR``.
  20
  21   :param c_ptr_2:
  22     (Optional) Scalar of the same type as :samp:`{c_ptr_1}`.
  23
  24   :return:
  25     The return value is of type ``LOGICAL`` ; it is ``.false.`` if either
  26     :samp:`{c_ptr_1}` is a C NULL pointer or if :samp:`{c_ptr1}` and :samp:`{c_ptr_2}`
  27     point to different addresses.
  28
  29   Standard:
  30     Fortran 2003 and later
  31
  32   Class:
  33     Inquiry function
  34
  35   Syntax:
  36     .. code-block:: fortran
  37
  38       RESULT = C_ASSOCIATED(c_ptr_1[, c_ptr_2])
  39
  40   Example:
  41     .. code-block:: fortran
  42
  43       subroutine association_test(a,b)
  44         use iso_c_binding, only: c_associated, c_loc, c_ptr
  45         implicit none
  46         real, pointer :: a
  47         type(c_ptr) :: b
  48         if(c_associated(b, c_loc(a))) &
  49            stop 'b and a do not point to same target'
  50       end subroutine association_test
  51
  52   See also:
  53     :ref:`C_LOC`,
  54     :ref:`C_FUNLOC`