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