Kernel/include/vfs_ext.h

   1 /**
   2  * \file vfs_ext.h
   3  * \brief Exported VFS Definitions
   4  * \author John Hodge (thePowersGang)
   5  */
   6 #ifndef _VFS_EXT_H
   7 #define _VFS_EXT_H
   8
   9 // === CONSTANTS ===
  10 //! Maximum size of a Memory Path generated by VFS_GetMemPath
  11 #define VFS_MEMPATH_SIZE        (3 + (BITS/4)*2)
  12 /**
  13  * \name Flags for VFS_Open
  14  * \{
  15  */
  16 //! Open for execution
  17 #define VFS_OPENFLAG_EXEC       0x01
  18 //! Open for reading
  19 #define VFS_OPENFLAG_READ       0x02
  20 //! Open for writing
  21 #define VFS_OPENFLAG_WRITE      0x04
  22 //! Do not resolve the final symbolic link
  23 #define VFS_OPENFLAG_NOLINK     0x40
  24 //! Open as a user
  25 #define VFS_OPENFLAG_USER       0x80
  26 /**
  27  * \}
  28  */
  29 //! Marks a VFS handle as belonging to the kernel
  30 #define VFS_KERNEL_FLAG 0x40000000
  31
  32 //! Architectual maximum number of file descriptors
  33 #define MAX_FILE_DESCS  128
  34
  35 /**
  36  * \brief VFS_Seek directions
  37  */
  38 enum eVFS_SeekDirs
  39 {
  40         SEEK_SET = 1,   //!< Set the current file offset
  41         SEEK_CUR = 0,   //!< Seek relative to the current position
  42         SEEK_END = -1   //!< Seek from the end of the file backwards
  43 };
  44
  45 /**
  46  * \name ACL Permissions
  47  * \{
  48  */
  49 /**
  50  * \brief Readable
  51  */
  52 #define VFS_PERM_READ   0x00000001
  53 /**
  54  * \brief Writeable
  55  */
  56 #define VFS_PERM_WRITE  0x00000002
  57 /**
  58  * \brief Append allowed
  59  */
  60 #define VFS_PERM_APPEND 0x00000004
  61 /**
  62  * \brief Executable
  63  */
  64 #define VFS_PERM_EXECUTE        0x00000008
  65 /**
  66  * \brief All permissions granted
  67  */
  68 #define VFS_PERM_ALL    0x7FFFFFFF      // Mask for permissions
  69 /**
  70  * \brief Denies instead of granting permissions
  71  * \note Denials take precedence
  72  */
  73 #define VFS_PERM_DENY   0x80000000      // Inverts permissions
  74 /**
  75  * \}
  76  */
  77
  78 // -- System Call Structures ---
  79 /**
  80  * \brief ACL Defintion Structure
  81  */
  82 typedef struct sVFS_ACL
  83 {
  84         struct {
  85                 unsigned Group: 1;      //!< Group (as opposed to user) flag
  86                 unsigned ID:    31;     //!< ID of Group/User (-1 for nobody/world)
  87         };
  88         struct {
  89                 unsigned Inv:   1;      //!< Invert Permissions
  90                 unsigned Perms: 31;     //!< Permission Flags
  91         };
  92 }       tVFS_ACL;
  93
  94 /**
  95  * \brief SYS_FINFO structure
  96  */
  97 typedef struct sFInfo
  98 {
  99         Uint    uid;    //!< Owning User ID
 100         Uint    gid;    //!< Owning Group ID
 101         Uint    flags;  //!< File flags
 102         Uint64  size;   //!< File Size
 103         Sint64  atime;  //!< Last Accessed time
 104         Sint64  mtime;  //!< Last modified time
 105         Sint64  ctime;  //!< Creation time
 106          int    numacls;        //!< Total number of ACL entries
 107         tVFS_ACL        acls[]; //!< ACL buffer (size is passed in the \a MaxACLs argument to VFS_FInfo)
 108 }       tFInfo;
 109
 110 /**
 111  * \brief fd_set for select()
 112  */
 113 typedef struct
 114 {
 115         Uint16  flags[MAX_FILE_DESCS/16];
 116 }       fd_set;
 117
 118 #define FD_CLR(fd, fdsetp) ((fdsetp)->flags[(fd)/16]&=~(1<<((fd)%16)))
 119 #define FD_SET(fd, fdsetp) ((fdsetp)->flags[(fd)/16]|=~(1<<((fd)%16)))
 120 #define FD_ISSET(fd, fdsetp) ((fdsetp)->flags[(fd)/16]&(1<<((fd)%16)))
 121
 122 // === FUNCTIONS ===
 123 /**
 124  * \brief Initialise the VFS (called by system.c)
 125  * \return Boolean Success
 126  */
 127 extern int      VFS_Init(void);
 128
 129 /**
 130  * \brief Open a file
 131  * \param Path  Absolute or relative path to the file
 132  * \param Mode  Flags defining how to open the file
 133  * \return VFS Handle (an integer) or -1 if an error occured
 134  */
 135 extern int      VFS_Open(const char *Path, Uint Mode);
 136 /**
 137  * \brief Close a currently open file
 138  * \param FD    Handle returned by ::VFS_Open
 139  */
 140 extern void     VFS_Close(int FD);
 141
 142 /**
 143  * \brief Get file information from an open file
 144  * \param FD    File handle returned by ::VFS_Open
 145  * \param Dest  Destination for the read information
 146  * \param MaxACLs       Number of ACL slots allocated in the \a Dest structure
 147  * \return Boolean Success
 148  *
 149  * If the \a NumACLs is smaller than the number of ACLs the node has, only
 150  * \a NumACLs will be copied into \a Dest, but the tFInfo.numacls field
 151  * will be set to the true ammount of ACLs. It is up to the user to do with
 152  * this information how they like.
 153  */
 154 extern int      VFS_FInfo(int FD, tFInfo *Dest, int MaxACLs);
 155 /**
 156  * \brief Gets the permissions appling to a user/group.
 157  * \param FD    File handle returned by ::VFS_Open
 158  * \param Dest  ACL information structure to edit
 159  * \return Boolean success
 160  *
 161  * This function sets the tVFS_ACL.Inv and tVFS_ACL.Perms fields to what
 162  * permissions the user/group specied in tVFS_ACL.ID has on the file.
 163  */
 164 extern int      VFS_GetACL(int FD, tVFS_ACL *Dest);
 165 /**
 166  * \brief Changes the user's current working directory
 167  * \param Dest  New working directory (either absolute or relative to the current)
 168  * \return Boolean Success
 169  */
 170 extern int      VFS_ChDir(const char *Dest);
 171 /**
 172  * \brief Change the current virtual root for the user
 173  * \param New New virtual root (same as ::VFS_ChDir but cannot go
 174  *            above the current virtual root)
 175  * \return Boolean success
 176  */
 177 extern int      VFS_ChRoot(const char *New);
 178
 179 /**
 180  * \brief Change the location of the current file pointer
 181  * \param FD    File handle returned by ::VFS_Open
 182  * \param Offset        Offset within the file to go to
 183  * \param Whence        A direction from ::eVFS_SeekDirs
 184  * \return Boolean success
 185  */
 186 extern int      VFS_Seek(int FD, Sint64 Offset, int Whence);
 187 /**
 188  * \brief Returns the current file pointer
 189  * \param FD    File handle returned by ::VFS_Open
 190  * \return Current file position
 191  */
 192 extern Uint64   VFS_Tell(int FD);
 193
 194 /**
 195  * \brief Reads data from a file
 196  * \param FD    File handle returned by ::VFS_Open
 197  * \param Length        Number of bytes to read from the file
 198  * \param Buffer        Destination of read data
 199  * \return Number of read bytes
 200  */
 201 extern Uint64   VFS_Read(int FD, Uint64 Length, void *Buffer);
 202 /**
 203  * \brief Writes data to a file
 204  * \param FD    File handle returned by ::VFS_Open
 205  * \param Length        Number of bytes to write to the file
 206  * \param Buffer        Source of written data
 207  * \return Number of bytes written
 208  */
 209 extern Uint64   VFS_Write(int FD, Uint64 Length, const void *Buffer);
 210
 211 /**
 212  * \brief Reads from a specific offset in the file
 213  * \param FD    File handle returned by ::VFS_Open
 214  * \param Offset        Byte offset in the file
 215  * \param Length        Number of bytes to read from the file
 216  * \param Buffer        Source of read data
 217  * \return Number of bytes read
 218  */
 219 extern Uint64   VFS_ReadAt(int FD, Uint64 Offset, Uint64 Length, void *Buffer);
 220 /**
 221  * \brief Writes to a specific offset in the file
 222  * \param FD    File handle returned by ::VFS_Open
 223  * \param Offset        Byte offset in the file
 224  * \param Length        Number of bytes to write to the file
 225  * \param Buffer        Source of written data
 226  * \return Number of bytes written
 227  */
 228 extern Uint64   VFS_WriteAt(int FD, Uint64 Offset, Uint64 Length, const void *Buffer);
 229
 230 /**
 231  * \brief Sends an IOCtl request to the driver
 232  * \param FD    File handle returned by ::VFS_Open
 233  * \param ID    IOCtl call ID (driver specific)
 234  * \param Buffer        Data pointer to send to the driver
 235  * \return Driver specific response
 236  */
 237 extern int      VFS_IOCtl(int FD, int ID, void *Buffer);
 238
 239 /**
 240  * \brief Creates a VFS Memory path from a pointer and size
 241  * \param Dest  Destination for the created path
 242  * \param Base  Base of the memory file
 243  * \param Length        Length of the memory buffer
 244  * \note A maximum of VFS_MEMPATH_SIZE bytes will be required in \a Dest
 245  */
 246 extern void     VFS_GetMemPath(char *Dest, void *Base, Uint Length);
 247 /**
 248  * \brief Gets the canoical (true) path of a file
 249  * \param Path  File path (may contain symlinks, relative elements etc.)
 250  * \return Absolute path with no symlinks
 251  */
 252 extern char     *VFS_GetTruePath(const char *Path);
 253
 254 /**
 255  * \brief Mounts a filesystem
 256  * \param Device        Device to mount
 257  * \param MountPoint    Location to mount
 258  * \param Filesystem    Filesystem to use
 259  * \param Options       Options string to pass the driver
 260  * \return 1 on succes, -1 on error
 261  */
 262 extern int      VFS_Mount(const char *Device, const char *MountPoint, const char *Filesystem, const char *Options);
 263 /**
 264  * \brief Create a new directory
 265  * \param Path  Path to new directory (absolute or relative)
 266  * \return Boolean success
 267  * \note The parent of the directory must exist
 268  */
 269 extern int      VFS_MkDir(const char *Path);
 270 /**
 271  * \brief Create a symbolic link
 272  * \param Name  Name of the symbolic link
 273  * \param Link  File the symlink points to
 274  * \return Boolean success (\a Link is not tested for existence)
 275  */
 276 extern int      VFS_Symlink(const char *Name, const char *Link);
 277 /**
 278  * \brief Read from a directory
 279  * \param FD    File handle returned by ::VFS_Open
 280  * \param Dest  Destination array for the file name (max 255 bytes)
 281  * \return Boolean Success
 282  */
 283 extern int      VFS_ReadDir(int FD, char *Dest);
 284 /**
 285  * \brief Opens a file via an open directory
 286  * \note The file to open must be a direct child of the parent
 287  * \param Errno Error number
 288  * \param FD    Parent Directory
 289  * \param Name  Child name
 290  * \param Mode  Open mode
 291  * \return File handle (same as returned from VFS_Open)
 292  */
 293 extern int      VFS_OpenChild(Uint *Errno, int FD, const char *Name, Uint Mode);
 294
 295 /**
 296  * \brief Wait for an aciton on a file descriptor
 297  * \param MaxHandle     Maximum set handle in \a *Handles
 298  * \param ReadHandles   Handles to wait for data on
 299  * \param WriteHandles  Handles to wait to write to
 300  * \param ErrHandles    Handle to wait for errors on
 301  * \param Timeout       Timeout for select() (if null, there is no timeout), if zero select() is non blocking
 302  * \param IsKernel      Use kernel handles as opposed to user handles
 303  * \return Number of handles that actioned
 304  */
 305 extern int VFS_Select(int MaxHandle, fd_set *ReadHandles, fd_set *WriteHandles, fd_set *ErrHandles, tTime *Timeout, BOOL IsKernel);
 306
 307 /**
 308  * \brief Map a file into memory
 309  * \param ErrNo Error status pointer
 310  * \param DestHint      Suggested place for read data
 311  * \param Length        Size of area to map
 312  * \param Protection    Protection type (see `man mmap`)
 313  * \param Flags Mapping flags
 314  * \param FD    File descriptor to load from
 315  * \param Offset        Start of region
 316  */
 317 extern void     *VFS_MMap(int *ErrNo, void *DestHint, size_t Length, int Protection, int Flags, int FD, Uint64 Offset);
 318
 319 /**
 320  * \brief Unmap memory allocated by VFS_MMap
 321  * \param ErrNo Error status pointer
 322  * \param Addr  Address of data to unmap
 323  * \param Length        Length of data
 324  */
 325 extern int      VFS_MUnmap(int *ErrNo, void *Addr, size_t Length);
 326 #endif