User Tools

Site Tools


6.6 Class Stat

The Stat (gb) class provides you with all the information returned by the system about a particular file. It must be emphasised that a Stat object is unsuitable for making selected changes to file properties! The class cannot be created.

  • The Stat() function returns a Stat object with which you can read out information on file and directory properties.
  • The information is read out for exactly one selected file whose path you must specify in the Path property (Properties table).
  • Attention: Six types of files are distinguished.
  • Also note that the information about a file is static when using this class because it has been read at a certain point in time. If you want to record and evaluate certain changes to a selected file dynamically at runtime (via a task), then you will find the Watch class suitable for this in the gb.inotify component.

6.6.1 Properties

The Stat class has these properties:

PropertyData typeDescription
PathStringReturns the path of the file referenced by the Stat object or sets the path.
AuthStringReturns the file permissions as a string; with the same syntax as the instruction CHMOD.
GroupStringReturns the group to which the file belongs.
HiddenBooleanReturns True if the file is hidden.
LastAccessDateReturns the date and time the file was last accessed.
LastChangeDateReturns the time when the attributes of the file were last changed.
LastModifiedDateOutputs the time when the contents of the file were last modified.
TimeDateSynonym for the LastModified property.
LinkStringIf the file is a symbolic link, then the path of the file is returned.
ModeIntegerReturns the mode (access mask) of the file encoded as a number. You should use the more specific and easier to handle properties such as Perm or SetUID.
SetGIDBooleanReturns True if the SetGID bit is set in the Permissions mask.
SetUIDBooleanReturns True if the SetUID bit is set in the rights mask.
SizeLongReturns the file size in bytes.
StickyBooleanReturns True if the Sticky bit is set in the rights mask.
UserStringReturns the name of the user/owner.
TypeIntegerReturns the type of a file (type symbol or number).
Perm.Stat.PermReturns a virtual class describing the file permissions (permissions mask).

Table : Properties of the class Stat

6.6.2 File types

The type of a file can be described by one of the following constants:

Type - symbolType - numberDescription
gb.File1Normal file (Regular file)
gb.Directory2Directory (Directory)
gb.Device3Special file for a device
gb.Pipe4Named pipe (FIFO file)
gb.Socket5Special file for a socket (Special file for a socket)
gb.Link6Symbolic link (Symbolic link)

Table : File type constants of the Stat class

6.6.3 Class .Stat.Perm

The .Stat.Perm (gb) virtual class describes the file permissions for the selected file and can be used like a read-only array.

PropertyData typeDescription
.Stat.Perm.UserStringReturns the user/owner permission of the file as a string.
.Stat.Perm.GroupStringReturns the group permission of the file as a string.
.Stat.Perm.OtherStringReturns the default permissions as string.

Table : Properties of the .Stat.Perm class

In all three cases, the (permission) string contains the following characters if the respective permission has been granted:

  • r → for the read permission.
  • w → for the write right,
  • x → for the execute right.

Attention: In particular, no character is output for missing permissions. This differs from the output of commands like 'ls -l', where missing permissions are noted with a minus sign at their fixed position.

6.6.4 Project

First, a temporary file is created in the presented project and content is inserted. Then the file permissions are explicitly changed. Then a Stat object is created and the file information of the temporary file is read and displayed.

' Gambas class file
Public sFilePath As String
Public Sub Form_Open()
  Dim sGroup, sRandomFileName As String
  FMain.Resizable = False
  sRandomFileName = SetRandomFileName()
  sFilePath = Temp(sRandomFileName)
  File.Save(sFilePath, "Text line 1.\nText line 2.")
  Chown sFilePath To User.Name
  Exec ["id", "-gn"] To sGroup ' Find out the group of the current user
  sGroup = Trim$(sGroup)
  Chgrp sFilePath To sGroup
  Chmod sFilePath To "rwxrw-r--" ' Test 1 perfect
' Chmod sFilePath To "rwSrwSr-T" ' Test 2 not error-free
' Chmod sFilePath To "rwxrw-rw-" ' Test 3 perfect
' Error correction:
' Shell "chmod u+s " & sFilePath Wait
' Shell "chmod g+s " & sFilePath Wait
' Shell "chmod o+t " & sFilePath Wait
Public Sub btnGetInformation_Click()
  Dim FileInfo As Stat
  Dim aTypes As String[] = ["Regular file", "Directory", "Special file for a device", "Named pipe", /
                            "Special file for a socket", "Symbolic link"]
  Dim hFile As File
  Dim sLine, sLink As String
  FileInfo = Stat(sFilePath) ' txaOutput(TypeOf(Stat(sFilePath)) --> Stat-Object
  txaOutput.Insert("Path = " & FileInfo.Path & gb.Lf)
  txaOutput.Insert("File-Type (Integer) = " & FileInfo.Type & gb.Lf)
  txaOutput.Insert("File-Type = " & aTypes[FileInfo.Type - 1] & gb.Lf) ' aTypes array index starts with 0
  txaOutput.Insert("Permissions (Symbolic notation) = " & FileInfo.Auth & gb.Lf)
  txaOutput.Insert("File-Modus (Numeric notation)   = " & Oct$(FileInfo.Mode) & gb.Lf)
  txaOutput.Insert("SetUID set? = " & Str(FileInfo.SetUID) & gb.Lf)
  txaOutput.Insert("SetGID set? = " & Str(FileInfo.SetGID) & gb.Lf)
  txaOutput.Insert("Sticky-Bit set? = " & Str(FileInfo.Sticky) & gb.Lf)
  txaOutput.Insert("User permissions  = " & FileInfo.Perm.User & gb.Lf)
  txaOutput.Insert("Group permissions = " & FileInfo.Perm.Group & gb.Lf)
  txaOutput.Insert("Other permissions = " & FileInfo.Perm.Other & gb.Lf)
  txaOutput.Insert("File-Size = " & FileInfo.Size & " Byte" & gb.Lf)
  sLink = IIf(FileInfo.Link, FileInfo.Link, "No")
  txaOutput.Insert("Symbolic link? = " & sLink & gb.Lf)
  txaOutput.Insert("Contents of the text file:" & gb.Lf)
  hFile = Open sFilePath For Input
  While Not Eof(hFile)
    Line Input #hFile, sLine
    txaOutput.Insert(sLine & gb.Lf)
  txaOutput.Insert("User = " & FileInfo.User & gb.Lf)
  txaOutput.Insert("Group = " & FileInfo.Group & gb.Lf)
  txaOutput.Insert("File hidden? = " & Str(FileInfo.Hidden) & gb.Lf)
  txaOutput.Insert("Permissions (Numeric notation)  = " & ModeStringToOctalString(FileInfo.Auth) & gb.Lf)
  txaOutput.Insert("Last access to file = " & FileInfo.LastAccess & "(UTC)" & gb.Lf)
  txaOutput.Insert("Last change of file content = " & FileInfo.LastModified &  "(UTC)" &  gb.Lf)
  txaOutput.Insert("Last change of file attributes  = " & FileInfo.LastChange &  "(UTC)" & gb.Lf)
  txaOutput.Insert("Permission R or W  = " & Str(Access(sFilePath, gb.Read Or gb.Write)) & gb.Lf)
  txaOutput.Insert("Permission R       = " & Str(Access(sFilePath, gb.Read)) & gb.Lf)
  txaOutput.Insert("Permission W       = " & Str(Access(sFilePath, gb.Write)) & gb.Lf)
  txaOutput.Insert("Permission X       = " & Str(Access(sFilePath, gb.Exec)) & gb.Lf)
' is default if the optional mode argument is missing
  txaOutput.Insert("Permission R       = " & Str(Access(sFilePath)) & gb.Lf)
Private Function SetRandomFileName() As String
  Dim sFileName As String
  sFileName = Hex$(Rand(0, 2 ^ 32 - 1)) ' Random file name
  Return sFileName
Public Sub ModeStringToOctalString(ModeString As String) As String
  Dim i, k, iValue, iExtendedFileAttribute As Integer
  Dim sOctal, s As String
  For k = 1 To 7 Step 3
    s = Mid(ModeString, k, 3)
    iValue = 0
    For i = 1 To 3
      Select Mid(s, i, 1)
        Case "r"
          iValue += 4
        Case "w"
          iValue += 2
        Case "x", "s", "t"
          iValue += 1
      End Select
      If k = 1 Then
         Select Mid(s, i, 1)
           Case "s", "S"
             iExtendedFileAttribute += 4
         End Select
      If k = 4 Then
         Select Mid(s, i, 1)
           Case "s", "S"
           iExtendedFileAttribute += 2
         End Select
      If k = 7 Then
         Select Mid(s, i, 1)
           Case "t", "T"
           iExtendedFileAttribute += 1
         End Select
    sOctal &= CStr(iValue) ' String!
  If iExtendedFileAttribute = 0 Then
     Return sOctal
     Return CStr(iExtendedFileAttribute) & sOctal ' String!


Figure Output file information

An alternative to the use of the virtual class .Stat.Perm is the Access function, about which you can read information under the link and which was also used selectively in the above project.

Attention: All files in the logical folder Data (and also in all subdirectories therein) in the project directory are treated as read-only, no matter what the actual mode settings are. This also applies to files with mode 777 (full read and write access for owner, group and others). This means, for example, that Access(“texts/mytext.txt”) never returns gb.Write. The reason is that when the executable file *.gambas is executed, all project files from the Data folder are inserted into the executable file and therefore cannot be changed at runtime!

Note that the CHMOD instruction is (partially) faulty up to (stable) Gambas version 3.11.3. A correction option is given in the presented project. The bug was fixed with commit d44b4bd7f in the development version.

To change file attributes, you can use the three instructions CHGRP, CHMOD and CHOWN, which are described in the next chapter.


The website uses a temporary session cookie. This technically necessary cookie is deleted when the browser is closed. You can find information on cookies in our privacy policy.
k6/k6.6/start.txt · Last modified: 16.01.2022 (external edit)

Page Tools