Changeset 27170bae in rtems


Ignore:
Timestamp:
May 31, 2013, 8:49:59 AM (6 years ago)
Author:
Ralf Kirchner <ralf.kirchner@…>
Branches:
4.11, master
Children:
cffa5b7
Parents:
581c9982
git-author:
Ralf Kirchner <ralf.kirchner@…> (05/31/13 08:49:59)
git-committer:
Sebastian Huber <sebastian.huber@…> (06/03/13 15:28:42)
Message:

dosfs: Documentation

File:
1 edited

Legend:

Unmodified
Added
Removed
  • cpukit/libfs/src/dosfs/dosfs.h

    r581c9982 r27170bae  
    205205typedef struct {
    206206  /**
    207    * @brief Converter implementation for new filesystem instance.
     207   * @brief Converter implementation for new file system instance.
     208   *
     209   * Before converters have been added to the RTEMS implementation of the FAT
     210   * file system, the implementation was:
     211   * - Short names were saved in code page format (as is still the case).
     212   * - Long names were not saved in UTF-16 format as mandated by the FAT file
     213   *   system specification.  Instead the character in the local encoding was
     214   *   stored to the low byte directly and the high byte was set to zero.
     215   *
     216   * There are a few compatibility issues due to a non-standard conform
     217   * implementation of the FAT file system before the UTF-8 support was added.
     218   * These following issues affect the default converter and the UTF-8
     219   * converter:
     220   * - Before UTF-8 support was added, it was possible to create files with the
     221   *   the same short name in single case and mixed case in a directory.  It
     222   *   was for example possible to have files "ABC" and "aBc" in a single
     223   *   directory.  Now this bug is fixed.
     224   * - Before UTF-8 support was added, it was possible to create files with a
     225   *   name length of slightly more than 255 characters.  Now the
     226   *   implementation adheres exactly to the 255 character limit.
     227   * - Long file names saved before UTF-8 support was added could contain
     228   *   non-ASCII characters in the low byte which was saved for a long name
     229   *   character.  With the default converter this means such files can be read
     230   *   only by their short file name.  With the UTF-8 converter file names will
     231   *   be read correctly as long as the characters written with the old
     232   *   implementation were Latin-1 characters.
     233   *
     234   * The following sample code demonstrates how to mount a file
     235   * system with UTF-8 support:
     236   * @code
     237   * #include <errno.h>
     238   * #include <assert.h>
     239   * #include <rtems/dosfs.h>
     240   * #include <rtems/libio.h>
     241   *
     242   * static int mount_with_utf8(
     243   *   const char *device_file,
     244   *   const char *mount_point
     245   * )
     246   * {
     247   *   rtems_dosfs_convert_control *convert_ctrl;
     248   *   int                          rv;
     249   *
     250   *   convert_ctrl = rtems_dosfs_create_utf8_converter( "CP850" );
     251   *
     252   *   if ( convert_ctrl != NULL ) {
     253   *     rtems_dosfs_mount_options mount_opts;
     254   *
     255   *     memset( &mount_opts, 0, sizeof( mount_opts ) );
     256   *     mount_opts.converter = convert_ctrl;
     257   *
     258   *     rv = mount_and_make_target_path(
     259   *       device_file,
     260   *       mount_point,
     261   *       RTEMS_FILESYSTEM_TYPE_DOSFS,
     262   *       RTEMS_FILESYSTEM_READ_WRITE,
     263   *       &mount_opts
     264   *     );
     265   *   } else {
     266   *     rv = -1;
     267   *     errno = ENOMEM;
     268   *   }
     269   *
     270   *   return rv;
     271   * }
     272   * @endcode
     273   *
     274   * In case you do not want UTF-8 support, you can simply pass a NULL pointer
     275   * to mount_and_make_target_path() respectively to mount() instead of the
     276   * mount_opts address.
    208277   *
    209278   * @see rtems_dosfs_create_default_converter() and
     
    216285 * @brief Allocates and initializes a default converter.
    217286 *
     287 * This default converter will accept only POSIX file names with pure ASCII
     288 * characters. This largely corresponds to the file name handling before the
     289 * optional UTF-8 support was added to the RTEMS implementation of the FAT file
     290 * system.  This handling is mostly backwards compatible to the previous RTEMS
     291 * implementation of the FAT file system.
     292 *
     293 * For backwards compatibility and the previous RTEMS implementation of the FAT
     294 * file system please see also @ref rtems_dosfs_mount_options and mount().
     295 *
    218296 * @retval NULL Something failed.
    219297 * @retval other Pointer to initialized converter.
    220  *
    221  * @see rtems_dosfs_mount_options and mount().
    222298 */
    223299rtems_dosfs_convert_control *rtems_dosfs_create_default_converter(void);
     
    226302 * @brief Allocates and initializes a UTF-8 converter.
    227303 *
    228  * @param[in] codepage The iconv() identification string for the used codepage.
     304 * This converter will assume that all file names passed to POSIX file handling
     305 * methods are UTF-8 strings and will convert them to the selected code page
     306 * for short file names and to UTF-16 for long file names.  This conversion
     307 * will be done during reading and writing.  These conversions correspond to
     308 * the specification of the FAT file system.  This handling is mostly backwards
     309 * compatible to the previous RTEMS implementation of the FAT file system.
     310 *
     311 * For backwards compatibility and the previous RTEMS implementation of the FAT
     312 * file system please see also @ref rtems_dosfs_mount_options and mount().
     313 *
     314 * One possible issue with this converter is: When reading file names which
     315 * have been created with other implementations of the FAT file system, it can
     316 * happen that during the conversion to UTF-8 a long file name becomes longer
     317 * and exceeds the 255 bytes limit.  In such a case only the short file name
     318 * will get read.
     319 *
     320 * @param[in] codepage The iconv() identification string for the used code
     321 * page.
    229322 *
    230323 * @retval NULL Something failed.
    231324 * @retval other Pointer to initialized converter.
    232  *
    233  * @see rtems_dosfs_mount_options and mount().
    234325 */
    235326rtems_dosfs_convert_control *rtems_dosfs_create_utf8_converter(
Note: See TracChangeset for help on using the changeset viewer.