include/rtems/fsmount.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /**
0004  * @file
0005  *
0006  * @defgroup rtems_fstab File System Mount Support
0007  *
0008  * @ingroup FileSystemTypesAndMount
0009  * @brief File System Mount Functions
0010  *
0011  * This file contains the fsmount functions. These functions
0012  * are used to mount a list of filesystems (and create their mount
0013  * points before).
0014  */
0015
0016 /*
0017  * Copyright (c) 2003 IMD Ingenieurbuero fuer Microcomputertechnik
0018  * All rights reserved.
0019  *
0020  * Redistribution and use in source and binary forms, with or without
0021  * modification, are permitted provided that the following conditions
0022  * are met:
0023  * 1. Redistributions of source code must retain the above copyright
0024  *    notice, this list of conditions and the following disclaimer.
0025  * 2. Redistributions in binary form must reproduce the above copyright
0026  *    notice, this list of conditions and the following disclaimer in the
0027  *    documentation and/or other materials provided with the distribution.
0028  *
0029  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0030  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0031  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0032  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0033  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0034  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0035  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0036  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0037  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0038  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0039  * POSSIBILITY OF SUCH DAMAGE.
0040  */
0041
0042 #ifndef _FSMOUNT_H
0043 #define _FSMOUNT_H
0044
0045 #include <rtems.h>
0046 #include <rtems/libio.h>
0047 #include <rtems/libcsupport.h>
0048
0049 #ifdef __cplusplus
0050 extern "C" {
0051 #endif
0052
0053 /**
0054  * @defgroup rtems_fstab File System Mount Support
0055  *
0056  * @ingroup FileSystemTypesAndMount
0057  */
0058 /**@{**/
0059
0060 /**
0061  * File system mount report and abort condition flags.
0062  *
0063  * The flags define, which conditions will cause a report during the mount
0064  * process (via printf()) or abort the mount process.
0065  *
0066  * @see rtems_fstab_entry and rtems_fsmount().
0067  */
0068 typedef enum {
0069   /**
0070    * No conditions.
0071    */
0072   RTEMS_FSTAB_NONE = 0U,
0073
0074   /**
0075    * Complete mount process was successful.
0076    */
0077   RTEMS_FSTAB_OK = 0x1U,
0078
0079   /**
0080    * Mount point creation failed.
0081    */
0082   RTEMS_FSTAB_ERROR_MOUNT_POINT = 0x2U,
0083
0084   /**
0085    * File system mount failed.
0086    */
0087   RTEMS_FSTAB_ERROR_MOUNT = 0x4U,
0088
0089   /**
0090    * Something failed.
0091    */
0092   RTEMS_FSTAB_ERROR = RTEMS_FSTAB_ERROR_MOUNT_POINT | RTEMS_FSTAB_ERROR_MOUNT,
0093
0094   /**
0095    * Any condition.
0096    */
0097   RTEMS_FSTAB_ANY = RTEMS_FSTAB_OK | RTEMS_FSTAB_ERROR
0098 } rtems_fstab_conditions;
0099
0100 /**
0101  * File system table entry.
0102  */
0103 typedef struct {
0104   /**
0105    * Source for the mount.
0106    */
0107   const char *source;
0108
0109   /**
0110    * Target for the mount.
0111    */
0112   const char *target;
0113
0114   /**
0115    * File system operations.
0116    */
0117   const char *type;
0118
0119   /**
0120    * File system mount options.
0121    */
0122   rtems_filesystem_options_t options;
0123
0124   /**
0125    * Report @ref rtems_fstab_conditions "condition flags".
0126    */
0127   uint16_t report_reasons;
0128
0129   /**
0130    * Abort @ref rtems_fstab_conditions "condition flags".
0131    */
0132   uint16_t abort_reasons;
0133 } rtems_fstab_entry;
0134
0135 /**
0136  * @brief Mounts the file systems listed in the file system mount table.
0137  *
0138  * Mounts the file systems listed in the file system mount table @a fstab of
0139  * size @a size.
0140  *
0141  * Each file system will be mounted according to its table entry parameters.
0142  * In case of an abort condition the corresponding table index will be reported
0143  * in @a abort_index.  The pointer @a abort_index may be @c NULL.  The mount
0144  * point paths will be created with rtems_mkdir() and need not exist
0145  * beforehand.
0146  *
0147  * On success, zero is returned.  On error, -1 is returned, and @c errno is set
0148  * appropriately.
0149  *
0150  * @see rtems_bdpart_register_from_disk().
0151  *
0152  * The following example code tries to mount a FAT file system within a SD
0153  * Card.  Some cards do not have a partition table so at first it tries to find
0154  * a file system inside the hole disk.  If this is successful the mount process
0155  * will be aborted because the @ref RTEMS_FSTAB_OK condition is true.  If this
0156  * did not work it tries to mount the file system inside the first partition.
0157  * If this fails the mount process will not be aborted (this is already the
0158  * last entry), but the last error status will be returned.
0159  *
0160  * @code
0161  * #include <stdio.h>
0162  * #include <string.h>
0163  * #include <errno.h>
0164  *
0165  * #include <rtems.h>
0166  * #include <rtems/bdpart.h>
0167  * #include <rtems/error.h>
0168  * #include <rtems/fsmount.h>
0169  *
0170  * static const rtems_fstab_entry fstab [] = {
0171  *   {
0172  *     .source = "/dev/sd-card-a",
0173  *     .target = "/mnt",
0174  *     .type = "dosfs",
0175  *     .options = RTEMS_FILESYSTEM_READ_WRITE,
0176  *     .report_reasons = RTEMS_FSTAB_ANY,
0177  *     .abort_reasons = RTEMS_FSTAB_OK
0178  *   }, {
0179  *     .source = "/dev/sd-card-a1",
0180  *     .target = "/mnt",
0181  *     .type = "dosfs",
0182  *     .options = RTEMS_FILESYSTEM_READ_WRITE,
0183  *     .report_reasons = RTEMS_FSTAB_ANY,
0184  *     .abort_reasons = RTEMS_FSTAB_NONE
0185  *   }
0186  * };
0187  *
0188  * static void my_mount(void)
0189  * {
0190  *   rtems_status_code sc = RTEMS_SUCCESSFUL;
0191  *   int rv = 0;
0192  *   size_t abort_index = 0;
0193  *
0194  *   sc = rtems_bdpart_register_from_disk("/dev/sd-card-a");
0195  *   if (sc != RTEMS_SUCCESSFUL) {
0196  *     printf("read partition table failed: %s\n", rtems_status_text(sc));
0197  *   }
0198  *
0199  *   rv = rtems_fsmount(fstab, sizeof(fstab) / sizeof(fstab [0]), &abort_index);
0200  *   if (rv != 0) {
0201  *     printf("mount failed: %s\n", strerror(errno));
0202  *   }
0203  *   printf("mount aborted at %zu\n", abort_index);
0204  * }
0205  * @endcode
0206  */
0207 int rtems_fsmount(
0208   const rtems_fstab_entry *fstab,
0209   size_t                   size,
0210   size_t                  *abort_index
0211 );
0212
0213 /** @} */
0214
0215 typedef rtems_fstab_entry fstab_t;
0216
0217 #define FSMOUNT_MNT_OK RTEMS_FSTAB_OK
0218
0219 #define FSMOUNT_MNTPNT_CRTERR RTEMS_FSTAB_ERROR_MOUNT_POINT
0220
0221 #define FSMOUNT_MNT_FAILED RTEMS_FSTAB_ERROR_MOUNT
0222
0223 #ifdef __cplusplus
0224 }
0225 #endif
0226
0227 #endif /* _FSMOUNT_H */