/*
 *  OO_Copyright_BEGIN
 *
 *
 *  Copyright 2010, 2020 IBM Corp. All rights reserved.
 *
 *  Redistribution and use in source and binary forms, with or without
 *   modification, are permitted provided that the following conditions
 *  are met:
 *  1. Redistributions of source code must retain the above copyright
 *     notice, this list of conditions and the following disclaimer.
 *  2. Redistributions in binary form must reproduce the above copyright
 *     notice, this list of conditions and the following disclaimer in the
 *  documentation and/or other materials provided with the distribution.
 *  3. Neither the name of the copyright holder nor the names of its
 *     contributors may be used to endorse or promote products derived from
 *     this software without specific prior written permission.
 *
 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
 *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 *  POSSIBILITY OF SUCH DAMAGE.
 *
 *
 *  OO_Copyright_END
 */

README for the Linear Tape File System messaging architecture (SDE)

                ----------------------------------

Background
=============================

LTFS uses the ICU resource bundle mechanism to generate messages. Each message
generated by the system has an integer ID and a level (Error, Warning,
Information, Debug). The LTFS utilities print E, W, and I messages by default.

Message IDs are allocated in blocks of 1000, starting at a multiple of 1000.
The coarse message ID allocation is as follows.
  * 0-9999:      Reserved. There are a few IDs allocated around 9000 for legacy
                 reasons. DO NOT allocate any new IDs in this range.
  * 10000-19999: Messages for libltfs, the LTFS utilities, and the plugins
                 shipped with the IBM Linear Tape File System. 3rd-party
                 plugins must not use the messages in this range.
  * 20000-20999: Messages for 3rd-party tape drive plugins.
  * 21000-21999: Messages for 3rd-party I/O scheduler plugins.
  * 22000-29999: Reserved
  == Tape Drivers (30000-39999) ==
  * 30000-30199: Generic file debug tape backend
  * 30200-30399: sg tape backend for IBM tape drives
  * 30400-30599: Tape backend for IBM lin_tape driver
  * 30600-30799: Tape backend for IBM scsi lib (Windows)
  * 30800-30999: iokit tape backend for IBM tape drives
  * 31000-31199: ITDT tape image backend
  * 31200-31399: Tape backend for the FreeBSD sa(4) driver.
  * 31400-39799: Reserved
  * 39800-39999: Tape Driver common
  == Changer Drivers for LE (40000-49999) ==
  * 40000-49999: Permanently Reserved
  ==
  * 50000+:      Reserved

Each shared library distributed with LTFS provides its own message bundle. Each
subdirectory under the "messages" directory provides a bundle for a single
shared library.

Refer to the following files and directories to see how a plugin provides
its messages to libltfs.
  * messages/Makefile.am, messages/Makefile.osx, messages/make_message_src.sh
        These files implement a system for compiling message bundle objects.
  * messages/tape_generic_file
        This directory implements messages for the sample "file" backend.
        3rd-party plugins should use a start_id of 20000 or 21000 (see above).
  * src/tape_drivers/generic/file/Makefile.am
        This file has DEPENDENCIES and LIBADD lines that link the compiled
        message bundle into the final plugin.
  * src/tape_drivers/generic/file/filedebug_tc.c
        This file implements a function to initialize the message bundle and
        tell libltfs the name of the bundle.