#!/usr/local/bin/scripts/sh
#
#.Y / 70 83 / / / / 105 / / / /  / /               ;A4_QUER.Y
#.YT 3 2 0 0 3 3 1 / / /
#.H!a!0:linux/<scripts>/io/disk/mediaAccess/mediaHandlers.d/A8A2BB3E_78F0_11E6_B6F3_0000C00A45A9!0.!c
#
#/*******************************************************************************
#     io disk mediaAccess mediaHandlers.d/A8A2BB3E_78F0_11E6_B6F3_0000C00A45A9
#     ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
#
#     purpose             : media handler for a simple dm-snapshot on a media
#
#     begin               : Sat May 26 18:40:22 CEST 2018
#
#     changes             :
#
#     copyright           : (C) 2018 by Thomas Bruecker
#
#     email               : public@thomas-r-bruecker.ch
#
#     version             : -0.0.0
#
#*******************************************************************************/

#/***************************************************************************
# *                                                                         *
# *   This program is free software; you can redistribute it and/or modify  *
# *   it under the terms of the GNU General Public License as published by  *
# *   the Free Software Foundation; either version 2 of the License, or     *
# *   (at your option) any later version.                                   *
# *                                                                         *
# *   This program is distributed in the hope that it will be useful, but   *
# *   WITHOUT ANY WARRANTY; without even the implied warranty of            *
# *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU      *
# *   General Public License for more details.                              *
# *                                                                         *
# *   You should have received a copy of the GNU General Public License     *
# *   along with this program; if not, write to the Free Software           *
# *   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,            *
# *   MA 02110-1301 USA.                                                    *
# *                                                                         *
# ***************************************************************************/

# MyHash("A8A2BB3E_78F0_11E6_B6F3_0000C00A45A9") = 0x089E_3E
#
# * for every function:
#   * if returned result is not commented, the function returns 0 on no-error.


disk_mediaAccess_A8A2BB3E_78F0_11E6_B6F3_0000C00A45A9() {
  # handles basically a dm-linear media;
  # $1: command, in {
  #       "2QualifiedChildDev", "2ChildMedia", "DESTROY", "REALIZE", "RealizeForced",
  #       "SIZE", "VERIFY", "WAIT", "_:", "__:"
  #     },
  #     * $1 in {
  #         "2QualifiedChildDev", "2ChildMedia", "DESTROY", "REALIZE", "RealizeForced",
  #         "SIZE", "VERIFY", "WAIT"
  #       }: see "../CommonCommandsSpecification.TXT",
  #     * "_:":  ^verify command,
  #              ^$2: path to the media (device, file, rootFolder of a filsystem),
  #              ^$3: index into container,
  #     * "__:": ^verify command,
  #              $2: media-handler-uuid,
  #              $3: size,
  #              $4: uuid,
  #              $5: prefix, most often: indent;
  #              ^* writes the size-parameter to "stdout".

  local  COMMAND FORCED INDEX MediaInfo ParentMedia ParentMediaPath

  COMMAND="$1"
  INDEX="$2"
  MediaInfo="$3"
  ParentMedia="$4"
  ParentMediaPath="$5"

  # echo  $COMMAND                                                >>/dev/stderr
  # echo  $INDEX                                                  >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  # quick, for verifying and 'wait':
    disk_mediaAccess__VerifyNoWait  "$COMMAND"  && return 0
                                                   # if ok, return 0; no
                                                   # waiting for component
                                                   # medias at all.

  disk_mediaAccess__RealizeForced2Forced  "$COMMAND"
  # echo  $FORCED                                                 >>/dev/stderr

  case "$COMMAND" in
      2QualifiedChildDev)
        disk_mediaAccess___2QualifiedChildDev                                   \
          "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      2ChildMedia)
        disk_mediaAccess___2ChildMedia0                                \
                   "$MediaInfo"                                    ;;
      CHECK|REPAIR)  return  0                                     ;;
      DESTROY)
        disk_mediaAccess__0x089E_3E_DESTROY                            \
                   "$MediaInfo"                                    ;;
# ^ok.
      MERGE)
        disk_mediaAccess__0x089E_3E_MERGE                              \
          "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      REALIZE|RealizeForced)
        disk_mediaAccess__0x089E_3E_REALIZE                            \
          "$FORCED"                                                    \
          "$INDEX" "$MediaInfo"                "$ParentMediaPath"  ;;
# ^ok.
      REVERT)
        disk_mediaAccess__0x089E_3E_REVERT                             \
                   "$MediaInfo"                                    ;;
      SIZE)
        disk_mediaAccess__Size0                                        \
          '0'      "$MediaInfo"                                    ;;
# ^ok.
      STATUS)
        disk_mediaAccess__0x089E_3E_STATUS                             \
          "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      _:)
        shift 1
        disk_mediaAccess_0x089E_3E_col__   "$@"                    ;;
                                                   # ^
      __:)
        shift 1
        disk_mediaAccess_0x089E_3E_col___  "$@"                    ;;
                                                   # ^
      *)
        disk_mediaAccess___NoContainer                                 \
          "$COMMAND" "$INDEX" "$ParentMedia"                           \
          || return                                # return on error.

        disk_mediaAccess__InvalidCommandError                          \
          "$COMMAND" "$INDEX"                                          \
          'A8A2BB3E_78F0_11E6_B6F3_0000C00A45A9'                       \
          "$ParentMedia"                                           ;;
    esac                                           # return result of previous
}                                                  # command.


disk_mediaAccess_0x089E_3E_col__() {
  # $1: size,
  # $2: uuid,
  # $3: prefix; most often: indent,
  # * writes the size-parameter to "stdout".

  local  MediaHandlerUuid PREFIX SIZE UUID

  PREFIX="$3"
  PREFIX1="  $PREFIX0"
  SIZE="$1"
  UUID="$2"

  MediaHandlerUuid="$(
    echo  "${FUNCNAME[1]}"                                      \
      | string__SearchAndReplace   '^disk_mediaAccess_*' ''     \
        | string_SearchAndReplace  '_'                   '-'    \
  )"

  disk_mediaAccess_0x089E_3E_col___  \
    "$MediaHandlerUuid" "$SIZE" "$UUID" "$PREFIX"
}


disk_mediaAccess_0x089E_3E_col___() {
  # $1: media-handler-uuid,
  # $2: size,
  # $3: uuid,
  # $4: prefix; most often: indent,
  # ^* writes the size-parameter to "stdout".

  local  MediaHandlerUuid PREFIX SIZE UUID

  MediaHandlerUuid="$1"
  PREFIX0="$4"
  PREFIX1="  $PREFIX0"
  SIZE="$2"
  UUID="$3"

  START='8' # ^
  # ^ sort parameters.

  disk_mediaAccess_col__METHOD              "$MediaHandlerUuid" "$PREFIX0"
    disk_mediaAccess_col__CommonParameters  "$MediaHandlerUuid" "$PREFIX1"
    disk_mediaAccess_col__SIZE              "$SIZE"             "$PREFIX1"
    disk_mediaAccess_col__START             "$START"            "$PREFIX1"
    disk_mediaAccess_col__UUID              "$UUID"             "$PREFIX1"
  disk_mediaAccess_col__MethodEnd                               "$PREFIX0"
}


disk_mediaAccess_col__LINEAR() {                  # ': _LINEAR'
  # $1: size,
  # $2: uuid,
  # $3: prefix; most often: indent,
  # * writes the size-parameter to "stdout".

  disk_mediaAccess__A8A2BB3E_78F0_11E6_B6F3_0000C00A45A9  "_:"  "$@"
}


disk_mediaAccess_col___LINEAR() {                  # ': __LINEAR'
  # $1: media-handler-uuid,
  # $2: size,
  # $3: uuid,
  # $4: prefix; most often: indent,
  # ^* writes the size-parameter to "stdout".

  disk_mediaAccess__A8A2BB3E_78F0_11E6_B6F3_0000C00A45A9  "__:" "$@"
}


disk_mediaAccess__0x089E_3E_DESTROY() {
  # destroys the media;
  # $1: <MediaInfo>.

  local  ChildMediaName MediaInfo OriginMediaName ShiftMediaName

  MediaInfo="$1"

  # echo  "$MediaInfo"                                            >>/dev/stderr

  ChildMediaName="$(disk_mediaAccess___2ChildUuid  "$MediaInfo")"  \
    || return                                      # return on error.
  # echo  "$ChildMediaName"                                       >>/dev/stderr

  # destroy the child-media.
    disk_mediaAccess___Destroy0  "$MediaInfo" ''                   \
      || return                                    # return on error.

  # destroy the origin-media.
    OriginMediaName="${ChildMediaName}.ORIGIN"
    # echo  "$OriginMediaName"                                    >>/dev/stderr

    disk_mediaAccess____Destroy  "$OriginMediaName"

  # destroy the shift-media.
    ShiftMediaName="${ChildMediaName}.SHIFT"
    # echo  "$ShiftMediaName"                                     >>/dev/stderr

    disk_mediaAccess____Destroy  "$ShiftMediaName"
}


disk_mediaAccess__0x089E_3E_MERGE() {
  # merges the snapshot into the parent media;
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMedia>,
  # $4: <ParentMediaPath>.

  local  ChildDev ChildMediaName CowMediaPath INDEX MediaInfo MediaIndexPair
  local  ParametersFile ParentMedia ParentMediaPath QualifiedChildMediaName
  local  ReadOnlyParent ShiftMediaPath

  INDEX="$1"
  MediaInfo="$2"
  ParentMedia="$3"
  ParentMediaPath="$4"

  # echo  "$INDEX"                                                >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  "$ParentMedia"                                          >>/dev/stderr
  # echo  "$ParentMediaPath"                                      >>/dev/stderr

  ParametersFile="$(disk_mediaAccess__Parameters2File  "$MediaInfo")"       \
    || return                                      # return on error.
    .  "$ParametersFile"  || return                # return on error.

  # echo  "$ChunkSize"                                            >>/dev/stderr
  # echo  "$RealizationOptions"                                   >>/dev/stderr
  # echo  "$UUID"                                                 >>/dev/stderr

  ChildMediaName="${UUID}"
  # echo  "$ChildMediaName"                                       >>/dev/stderr

  QualifiedChildMediaName="$(disk_mediaAccess__WriteQualifiedUuid           \
    "$ChildMediaName")"
  # echo  "$QualifiedChildMediaName"                              >>/dev/stderr

  ReadOnlyParent="$(
    disk_mediaAccess__GetRealizationOption                                  \
      "$RealizationOptions" 'parent'
  )"
  # echo  "$ReadOnlyParent"                                       >>/dev/stderr

 [ 'ro' == "$ReadOnlyParent" ]  && {
    MediaIndexPair="$ParentMedia, (index) $INDEX"
    echo      ''                                                  >>/dev/stderr
    echo  -n  'Error: It is not possible to merge the Media '     >>/dev/stderr
    echo       "\"$MediaIndexPair\";"                             >>/dev/stderr
    echo  -n  "       the Media \"$MediaIndexPair\" is "          >>/dev/stderr
    echo      "is read-only."                                     >>/dev/stderr
    return  1
  }

  disk_mediaAccess__isMedia  "$QualifiedChildMediaName"  && {
    ChildDev="$(disk_mediaAccess___Uuid2AbsolutePath0  "$ChildMediaName")"  \
      || return                                    # return on error.
    # echo  "$ChildDev"                                           >>/dev/stderr

    [ "0" != "$(disk_dm_OpenCount  "$ChildDev")" ]  && {
      MediaIndexPair="$ParentMedia, (index) $INDEX"
      echo      ''                                                >>/dev/stderr
      echo  -n  'Error: It is not possible to merge the Media '   >>/dev/stderr
      echo       "\"$MediaIndexPair\";"                           >>/dev/stderr
      echo      '       Device or Resource busy.'                 >>/dev/stderr
      return 1
    }

    disk_mediaAccess__0x089E_3E_DESTROY  "$MediaInfo"                       \
      || return                                    # return on error.
  }

  ShiftMediaPath="$(
    disk_mediaAccess___0x089E_3E_RealizeShiftMedia                          \
      "$ChildMediaName" "$ParentMediaPath" "$RealizationOptions"            \
      "$SIZE" "$START"
  )"  || return                                    # return on error.
  # echo  "$ShiftMediaPath"                                       >>/dev/stderr

  CowMediaPath="$(disk_mediaAccess__QualifiedName2Path  "$CowMedia")"       \
    || return                                      # return on error.
  # echo  $CowMediaPath                                           >>/dev/stderr

  disk_mediaAccess___0x089E_3E_RealizeSnapshotOrSnapshotMergeMedia          \
    "$ChildMediaName" "$ChunkSize" "$CowMediaPath" "$ShiftMediaPath"        \
    "$PERSISTENT" "$RealizationOptions" "$SIZE" 'snapshot-merge'            \
      || return                                    # return on error.

  disk_mediaAccess__LinkAndMap                                              \
    "$ChildMediaName" "$INDEX" "$ParentMediaPath"                           \
    >/dev/null  || return                          # return on error.

  disk_mediaAccess__0x089E_3E_STATUS                                        \
    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"

  # destroy the child-media.
    disk_mediaAccess___Destroy0  "$MediaInfo"                               \
      || return                                    # return on error.

  disk_mediaAccess___0x089E_3E_DestroyShiftMedia  "$ChildMediaName"
}                                                  # returns result of previous
                                                   # command.

disk_mediaAccess__0x089E_3E_REALIZE() {
  # realize media or realize media forced;
  # $1: <FORCED>,
  # $2: <INDEX>,
  # $3: <MediaInfo>,
  # $4: <ParentMediaPath>.

  local    ChildMediaName FORCED INDEX MediaInfo ParametersFile ParentMediaPath
  local    _PERSISTENT

  # parameters:
    local  ChunkSize COPYRIGHT CopyrightDetails CowMedia NOTES OnlyOnHosts
    local  PERSISTENT RealizationOptions SIZE START URL UUID

  FORCED="$1"
  INDEX="$2"
  MediaInfo="$3"
  ParentMediaPath="$4"

  # echo  "$FORCED"                                               >>/dev/stderr
  # echo  "$INDEX"                                                >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  "$ParentMediaPath"                                      >>/dev/stderr

  # clear global optional not ignored parameters.
    OnlyOnHosts=''
    RealizationOptions=''

  ParametersFile="$(disk_mediaAccess__Parameters2File  "$MediaInfo")"  \
    || return                                      # return on error.
    .  "$ParametersFile"  || return                # return on error.

  # echo  "$ChunkSize"                                            >>/dev/stderr
  # echo  "$COPYRIGHT"                                            >>/dev/stderr
  # echo  "$CopyrightDetails"                                     >>/dev/stderr
  # echo  "$CowMedia"                                             >>/dev/stderr
  # echo  "$NOTES"                                                >>/dev/stderr
  # echo  "$OnlyOnHosts"                                          >>/dev/stderr
  # echo  "$PERSISTENT"                                           >>/dev/stderr
  # echo  "$RealizationOptions"                                   >>/dev/stderr
  # echo  "$SIZE"                                                 >>/dev/stderr
  # echo  "$START"                                                >>/dev/stderr
  # echo  "$URL"                                                  >>/dev/stderr
  # echo  "$UUID"                                                 >>/dev/stderr

  ChildMediaName="${UUID}"
  # echo  "$ChildMediaName"                                       >>/dev/stderr

  disk_mediaAccess_isHandled                                           \
    "$FORCED" "$OnlyOnHosts" "$RealizationOptions"  || return 0

  # must be first to detect an invalid <CowMedia> .
    CowMediaPath="$(
      disk_mediaAccess___Media2AbsolutePath  "$CowMedia"
    )"  || return                                  # return on error.
    # echo  "$CowMediath"                                         >>/dev/stderr

  ReadOnlyParent="$(
    disk_mediaAccess__GetRealizationOption                             \
      "$RealizationOptions" 'parent'
  )"
  # echo  "$ReadOnlyParent"                                       >>/dev/stderr

  ShiftMediaOptions="$(
    echo  "$RealizationOptions"                                        \
      | disk_mediaAccess__DeleteRealizationOption  'parent'
  )"

  [ 'ro' == "$ReadOnlyParent" ]  && ShiftMediaOptions+=' ro'
  # echo  "$ShiftMediaOptions"                                    >>/dev/stderr

  ShiftMediaName="${ChildMediaName}.SHIFT"
  # echo  "$ShiftMediaName"                                       >>/dev/stderr

  disk_mediaAccess____LinearTable                                      \
    "$ShiftMediaName"                                                  \
    "$ParentMediaPath" "$ShiftMediaOptions" "$SIZE" "$START"           \
    || return                                      # return on error.

  ShiftMedia="$(
    disk_mediaAccess__LinkAndMap                                       \
     "$ShiftMediaName" "$INDEX" "$ParentMediaPath"
  )"  || return                                    # return on error.
  # echo  "$ShiftMedia"                                           >>/dev/stderr

  ShiftMediaPath="$(
    disk_mediaAccess___Media2AbsolutePath  "$ShiftMedia"
  )"  || return                                    # return on error.
  # echo  "$ShiftMediaPath"                                       >>/dev/stderr

  OriginMediaName="${ChildMediaName}.ORIGIN"
  # echo  "$OriginMediaName"                                      >>/dev/stderr

  TABLE="0 $SIZE  snapshot-origin  $ShiftMediaPath"
    # echo  "$TABLE"                                              >>/dev/stderr
    echo  -n  "$TABLE"  | disk_mediaAccess__DmCreate                   \
      "$OriginMediaName" "$RealizationOptions"  || return

  disk_mediaAccess__LinkAndMap                                         \
    "$OriginMediaName" "$INDEX" "$ParentMediaPath"         >/dev/null  \
    || return                                      # return on error.

  TABLE="0 $SIZE  snapshot  $ShiftMediaPath $CowMediaPath "

    if [ "1" == "$PERSISTENT" ]; then
        TABLE+='P '
      else
        TABLE+='N '
      fi

    TABLE+="$ChunkSize"
    # echo  "$TABLE"                                              >>/dev/stderr

    echo  -n  "$TABLE"  | disk_mediaAccess__DmCreate                   \
      "$ChildMediaName" "$RealizationOptions"  || return

  disk_mediaAccess__LinkAndMap                                         \
   "$ChildMediaName" "$INDEX" "$ParentMediaPath"
}


disk_mediaAccess__0x089E_3E_REVERT() {
  # reverts the snapshot to the 'origin'.
  # $1: <MediaInfo>.

  # global: BlkDiscard0x0EAA DD0x0EAA

  local     CowMedia CowMediaPath MediaInfo ParametersFile

  MediaInfo="$1"

  # echo  "$MediaInfo"                                            >>/dev/stderr

  ParametersFile="$(disk_mediaAccess__Parameters2File  "$MediaInfo")"   \
    || return                                      # return on error.
    .  "$ParametersFile"  || return                # return on error.

  # echo  $CowMedia                                               >>/dev/stderr

  CowMediaPath="$(disk_mediaAccess___Media2AbsolutePath  "$CowMedia")"  \
    || return                                      # return on error.
  # echo  "$CowMediaPath"                                         >>/dev/stderr

  if  disk_dm__hasHolders  "$CowMediaPath"; then
      # disk_dm__Setup  status                                    >>/dev/stderr

      MediaIndexPair="$ParentMedia, (index) $INDEX"
      echo      ''                                                >>/dev/stderr
      echo  -n  'Error: It is not possible to revert the Media '  >>/dev/stderr
      echo       "\"$MediaIndexPair\";"                           >>/dev/stderr
      echo  -n  "       the Media \"$MediaIndexPair\" is "        >>/dev/stderr
      echo      "either realized or merging."                     >>/dev/stderr
      return  1
    fi

  # "blkdiscard  <...>" does not discard blocks on a media in a container on
  # a thin media; so:
    # zero first <CowMediaPath> .
      # a linefeed before ... .
        echo  ''                                                  >>/dev/stderr

      "$DD0x0EAA"  if=/dev/zero  of="$CowMediaPath"  bs=4096  count=1

    # 'blkdiscard' .
      "$BlkDiscard0x0EAA"  -fv      "$CowMediaPath"

      # a linefeed after ... .
        echo  ''

  # ignore errors from 'blkdiscard' .
    return 0
}


disk_mediaAccess__0x089E_3E_STATUS() {
  # shows the status of the snapshot;
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMedia>,
  # $4: <ParentMediaPath>.

  local  ChildDev INDEX MediaInfo ParentMedia ParentMediaPath

  INDEX="$1"
  MediaInfo="$2"
  ParentMedia="$3"
  ParentMediaPath="$4"

  # echo  "$INDEX"                                                >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  "$ParentMedia"                                          >>/dev/stderr
  # echo  "$ParentMediaPath"                                      >>/dev/stderr

  ChildDev="$(
    disk_mediaAccess___2ChildDev                                     \
      "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"
  )"  || return                                    # return on error.
  # echo  "$ChildDev"                                             >>/dev/stderr

  while
    echo  "$(disk_mediaAccess___0x089E_3E_STATUS      "$ChildDev")"  \
                                                                  >>/dev/stderr

      ! disk_mediaAccess___0x089E_3E_isMergeComplete  "$ChildDev"
    do
        sleep 2
      done
}


disk_mediaAccess___0x089E_3E_2MetaDataSectors() {
  string__SearchAndReplace ".* " ""
}


disk_mediaAccess___0x089E_3E_2ShiftMediaName() {
  # $1: <ChildMediaName>.

  local  ChildMediaName

  ChildMediaName="$1"

  echo  "${ChildMediaName}.SHIFT"
}


disk_mediaAccess___0x089E_3E_2TotalSectors() {
  string__SearchAndReplace      "\/.*$" ""  \
    | string__SearchAndReplace  ".* " ""
}


disk_mediaAccess___0x089E_3E_DestroyShiftMedia() {
  # $1: <ChildMediaName>.

  local  ChildMediaName ShiftMediaName

  ChildMediaName="$1"

  ShiftMediaName="$(
    disk_mediaAccess___0x089E_3E_2ShiftMediaName  "$ChildMediaName"
  )"
  # echo  "$ShiftMediaName"                                       >>/dev/stderr

  disk_mediaAccess____Destroy                     "$ShiftMediaName"
}                                                  # returns result of previous
                                                   # command.

disk_mediaAccess___0x089E_3E_isMergeComplete() {
  # returns true (0), if the merge is complete;
  # $1: <ChildDevice>.

  local  ChildDev MetaDataSectors Sectors Status TotalSectors

  ChildDev="$1"

  Status="$(disk_mediaAccess___0x089E_3E_STATUS  "$ChildDev")"
  Sectors="$(echo $Status  | string__SearchAndReplace "^.*snapshot-merge " "")"
  MetaDataSectors="$(
    echo  "$Sectors"  |  disk_mediaAccess___0x089E_3E_2MetaDataSectors
  )"
  # echo  "$MetaDataSectors"                                      >>/dev/stderr

  TotalSectors="$(
    echo  "$Sectors"  | disk_mediaAccess___0x089E_3E_2TotalSectors
  )"
  # echo  "$TotalSectors"                                         >>/dev/stderr

  [ "$MetaDataSectors" == "$TotalSectors" ]
  return                                           # result of previous command
}


disk_mediaAccess___0x089E_3E_RealizeShiftMedia() {
  # realizes the shift media and writes its path to "stdout";
  # $1: <ChildMediaName>,
  # $2: <ParentMediaPath>,
  # $3: <RealizationOptions>,
  # $4: <SIZE>,
  # $5: <START>.

  local  ChildMediaName ParentMediaPath RealizationOptions ShiftMediaName
  local  ShiftMediaOptions SIZE START TABLE

  ChildMediaName="$1"
  ParentMediaPath="$2"
  RealizationOptions="$3"
  SIZE="$4"
  START="$5"

  ShiftMediaName="$(
    disk_mediaAccess___0x089E_3E_2ShiftMediaName  "$ChildMediaName"
  )"
  # echo  "$ShiftMediaName"                                       >>/dev/stderr

  ReadOnlyParent="$(
    disk_mediaAccess__GetRealizationOption                           \
      "$RealizationOptions" 'parent'
  )"
  # echo  "$ReadOnlyParent"                                       >>/dev/stderr

  ShiftMediaOptions="$(
    echo  "$RealizationOptions"                                      \
      | disk_mediaAccess__DeleteRealizationOption  'parent'
  )"

  [ 'ro' == "$ReadOnlyParent" ]  && ShiftMediaOptions+=' ro'
  # echo  "$ShiftMediaOptions"                                    >>/dev/stderr

  TABLE="0 $SIZE  linear  $ParentMediaPath $START"
    # echo $TABLE                                                 >>/dev/stderr
    echo -n "$TABLE"  | disk_mediaAccess__DmCreate                   \
                          "$ShiftMediaName" "$ShiftMediaOptions"     \
      || return                                    # return on error.

  ShiftMedia="$(
    disk_mediaAccess__LinkAndMap                                     \
      "$ShiftMediaName" "$INDEX" "$ParentMediaPath"
  )"  || return                                    # return on error.
  # echo  $ShiftMedia                                             >>/dev/stderr

  disk_mediaAccess__QualifiedName2Path  "$ShiftMedia"
}                                                  # returns result of previous
                                                   # command.

disk_mediaAccess___0x089E_3E_RealizeSnapshotOrSnapshotMergeMedia() {
  # $1: <ChildMediaName>,
  # $2: <ChunkSize>,
  # $3: <CowMediaPath>,
  # $4: <ParentMediaPath>,
  # $5: <PERSISTENT>,
  # $6: <RealizationOptions>,
  # $7: <SIZE>,
  # $8: <TargetType>.

  local  ChildMediaName ChunkSize CowMediaPath ParentMediaPath PERSISTENT
  local  RealizationOptions SIZE TABLE TargetType

  ChildMediaName="$1"
  ChunkSize="$2"
  CowMediaPath="$3"
  ParentMediaPath="$4"
  PERSISTENT="$5"
  RealizationOptions="$6"
  SIZE="$7"
  TargetType="$8"

  TABLE="0 $SIZE  $TargetType  $ParentMediaPath $CowMediaPath "  \

    if [ "1" == "$PERSISTENT" ]; then
        TABLE+='P '
      else
        TABLE+='N '
      fi

    TABLE+="$ChunkSize"
    # echo  "$TABLE"                                            >>/dev/stderr
    echo  -n  "$TABLE"  | disk_mediaAccess__DmCreate             \
      "$ChildMediaName" "$RealizationOptions"
}                                                  # returns result of previous
                                                   # command.

disk_mediaAccess___0x089E_3E_STATUS() {
  # writes the status of the snapshot to "stdout";
  # $1: <ChildDevice>.

  local  ChildDev

  ChildDev="$1"
  # echo  "$ChildDev"                                             >>/dev/stderr

  disk_dm__Setup  status  "$ChildDev"
}