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