0
# Core Filesystem Operations
1

2
Essential filesystem operations that form the foundation of any FUSE filesystem implementation. These methods handle basic file system functionality including attribute retrieval, directory operations, and file content access.
3

4
## Capabilities
5

6
### File Attribute Operations
7

8
Retrieve and modify file and directory attributes including permissions, ownership, timestamps, and size information.
9

10
```python { .api }
11
def getattr(self, path):
12
    """
13
    Get file/directory attributes.
14
    
15
    Args:
16
        path (str): Path to file or directory
17
        
18
    Returns:
19
        Stat: File attributes object
20
        int: Negative errno on error
21
    """
22

23
def chmod(self, path, mode):
24
    """
25
    Change file permissions.
26
    
27
    Args:
28
        path (str): Path to file or directory
29
        mode (int): New permission mode
30
        
31
    Returns:
32
        int: 0 on success, negative errno on error
33
    """
34

35
def chown(self, path, uid, gid):
36
    """
37
    Change file ownership.
38
    
39
    Args:
40
        path (str): Path to file or directory  
41
        uid (int): New user ID
42
        gid (int): New group ID
43
        
44
    Returns:
45
        int: 0 on success, negative errno on error
46
    """
47

48
def truncate(self, path, size):
49
    """
50
    Truncate file to specified size.
51
    
52
    Args:
53
        path (str): Path to file
54
        size (int): New file size in bytes
55
        
56
    Returns:
57
        int: 0 on success, negative errno on error
58
    """
59

60
def utime(self, path, times):
61
    """
62
    Change file access and modification times.
63
    
64
    Args:
65
        path (str): Path to file or directory
66
        times (tuple): (atime, mtime) tuple or None for current time
67
        
68
    Returns:
69
        int: 0 on success, negative errno on error
70
    """
71

72
def utimens(self, path, ts_acc, ts_mod):
73
    """
74
    Change file timestamps with nanosecond precision.
75
    
76
    Args:
77
        path (str): Path to file or directory
78
        ts_acc (Timespec): Access time specification
79
        ts_mod (Timespec): Modification time specification
80
        
81
    Returns:
82
        int: 0 on success, negative errno on error
83
    """
84
```
85

86
**Usage Example:**
87

88
```python
89
def getattr(self, path):
90
    st = fuse.Stat()
91
    if path == '/':
92
        st.st_mode = stat.S_IFDIR | 0o755
93
        st.st_nlink = 2
94
        st.st_size = 4096
95
    elif path in self.files:
96
        st.st_mode = stat.S_IFREG | 0o644
97
        st.st_nlink = 1
98
        st.st_size = len(self.files[path])
99
    else:
100
        return -errno.ENOENT
101
    
102
    # Set timestamps
103
    st.st_atime = st.st_mtime = st.st_ctime = time.time()
104
    return st
105
```
106

107
### Directory Operations
108

109
Handle directory listing, creation, and navigation operations.
110

111
```python { .api }
112
def readdir(self, path, offset):
113
    """
114
    Read directory contents.
115
    
116
    Args:
117
        path (str): Path to directory
118
        offset (int): Starting offset for reading (typically 0)
119
        
120
    Yields:
121
        Direntry: Directory entry objects for each item
122
    """
123

124
def opendir(self, path):
125
    """
126
    Open directory for reading.
127
    
128
    Args:
129
        path (str): Path to directory
130
        
131
    Returns:
132
        int: 0 on success, negative errno on error
133
    """
134

135
def releasedir(self, path):
136
    """
137
    Release (close) directory.
138
    
139
    Args:
140
        path (str): Path to directory
141
        
142
    Returns:
143
        int: 0 on success, negative errno on error
144
    """
145

146
def fsyncdir(self, path, datasync):
147
    """
148
    Synchronize directory contents.
149
    
150
    Args:
151
        path (str): Path to directory
152
        datasync (bool): If True, sync only data, not metadata
153
        
154
    Returns:
155
        int: 0 on success, negative errno on error
156
    """
157
```
158

159
**Usage Example:**
160

161
```python
162
def readdir(self, path, offset):
163
    # Always include . and .. entries
164
    yield fuse.Direntry('.')
165
    yield fuse.Direntry('..')
166
    
167
    # Add directory contents
168
    if path == '/':
169
        for filename in self.files:
170
            yield fuse.Direntry(filename.lstrip('/'))
171
```
172

173
### File Content Operations
174

175
Read and write file content, with support for arbitrary offsets and partial operations.
176

177
```python { .api }
178
def open(self, path, flags):
179
    """
180
    Open file for reading/writing.
181
    
182
    Args:
183
        path (str): Path to file
184
        flags (int): Open flags (O_RDONLY, O_WRONLY, O_RDWR, etc.)
185
        
186
    Returns:
187
        int: 0 on success, negative errno on error
188
    """
189

190
def read(self, path, size, offset):
191
    """
192
    Read file content.
193
    
194
    Args:
195
        path (str): Path to file
196
        size (int): Number of bytes to read
197
        offset (int): Byte offset to start reading from
198
        
199
    Returns:
200
        bytes: File content
201
        int: Negative errno on error
202
    """
203

204
def write(self, path, buf, offset):
205
    """
206
    Write file content.
207
    
208
    Args:
209
        path (str): Path to file
210
        buf (bytes): Data to write
211
        offset (int): Byte offset to start writing at
212
        
213
    Returns:
214
        int: Number of bytes written on success, negative errno on error
215
    """
216

217
def flush(self, path):
218
    """
219
    Flush cached data for file (called on each close() of a file descriptor).
220
    
221
    Args:
222
        path (str): Path to file
223
        
224
    Returns:
225
        int: 0 on success, negative errno on error
226
        
227
    Note:
228
        This is called for every close() of a file descriptor, not just
229
        when the file is finally released. Can be used to write back
230
        dirty data before the file is closed.
231
    """
232

233
def release(self, path, flags):
234
    """
235
    Release (close) file.
236
    
237
    Args:
238
        path (str): Path to file
239
        flags (int): Open flags used when file was opened
240
        
241
    Returns:
242
        int: 0 on success, negative errno on error
243
    """
244

245
def fsync(self, path, datasync):
246
    """
247
    Synchronize file contents.
248
    
249
    Args:
250
        path (str): Path to file
251
        datasync (bool): If True, sync only data, not metadata
252
        
253
    Returns:
254
        int: 0 on success, negative errno on error
255
    """
256
```
257

258
**Usage Example:**
259

260
```python
261
def read(self, path, size, offset):
262
    if path not in self.files:
263
        return -errno.ENOENT
264
        
265
    content = self.files[path]
266
    return content[offset:offset + size]
267

268
def write(self, path, buf, offset):
269
    if path not in self.files:
270
        self.files[path] = b''
271
        
272
    # Extend file if necessary
273
    if offset + len(buf) > len(self.files[path]):
274
        self.files[path] += b'\0' * (offset + len(buf) - len(self.files[path]))
275
    
276
    # Write data
277
    content = bytearray(self.files[path])
278
    content[offset:offset + len(buf)] = buf
279
    self.files[path] = bytes(content)
280
    
281
    return len(buf)
282
```
283

284
### Filesystem Information
285

286
Retrieve overall filesystem statistics and information.
287

288
```python { .api }
289
def statfs(self, path):
290
    """
291
    Get filesystem statistics.
292
    
293
    Args:
294
        path (str): Path within filesystem
295
        
296
    Returns:
297
        StatVfs: Filesystem statistics object
298
        int: Negative errno on error
299
    """
300
```
301

302
**Usage Example:**
303

304
```python
305
def statfs(self, path):
306
    stv = fuse.StatVfs()
307
    stv.f_bsize = 4096      # Block size
308
    stv.f_frsize = 4096     # Fragment size
309
    stv.f_blocks = 1000000  # Total blocks
310
    stv.f_bfree = 500000    # Free blocks
311
    stv.f_bavail = 500000   # Available blocks
312
    stv.f_files = 100000    # Total inodes
313
    stv.f_ffree = 50000     # Free inodes
314
    stv.f_favail = 50000    # Available inodes
315
    stv.f_namemax = 255     # Maximum filename length
316
    return stv
317
```
318

319
## Error Handling
320

321
Core operations should handle errors consistently:
322

323
- Return negative errno values for errors (e.g., `-errno.ENOENT`, `-errno.EACCES`)
324
- Return 0 for successful operations that don't return data
325
- Return positive values or objects for successful operations that return data
326
- Common errno values:
327
  - `ENOENT`: File or directory not found
328
  - `EACCES`: Permission denied
329
  - `EISDIR`: Is a directory (when file expected)
330
  - `ENOTDIR`: Not a directory (when directory expected)
331
  - `EEXIST`: File or directory already exists
332

333
## Performance Considerations
334

335
- Implement caching where appropriate to reduce repeated operations
336
- Use `fgetattr` and `ftruncate` variants when file handles are available
337
- Consider filesystem-specific optimizations for large directories
338
- Handle partial reads/writes efficiently for large files