0
# Low-Level API
1

2
Direct access to LittleFS C API through Cython bindings, providing precise control over filesystem operations, configuration parameters, and block-level access patterns. This API closely mirrors the original C implementation and is suitable for embedded systems development and advanced use cases.
3

4
## Capabilities
5

6
### Configuration Classes
7

8
Core configuration and filesystem objects that represent the LittleFS state.
9

10
```python { .api }
11
class LFSConfig:
12
    def __init__(self, context=None, *, block_size: int = 128, block_count: int = 64,
13
                 read_size: int = 0, prog_size: int = 0, block_cycles: int = -1,
14
                 cache_size: int = 0, lookahead_size: int = 8, name_max: int = 255,
15
                 file_max: int = 0, attr_max: int = 0, metadata_max: int = 0,
16
                 disk_version: int = 0):
17
        """
18
        LittleFS Configuration object.
19

20
        Parameters:
21
        - context: UserContext, storage backend (default: memory buffer)
22
        - block_size: int, block size in bytes (minimum 128)
23
        - block_count: int, number of blocks (0 to autodetect from filesystem)
24
        - read_size: int, minimum read size (default: block_size)
25
        - prog_size: int, minimum program size (default: block_size)  
26
        - block_cycles: int, erase cycles before wear leveling (-1 to disable)
27
        - cache_size: int, block cache size (default: max of read_size/prog_size)
28
        - lookahead_size: int, lookahead buffer size in bytes (must be multiple of 8)
29
        - name_max: int, maximum filename length (default 255, max 1022)
30
        - file_max: int, maximum file size (0 for no limit)
31
        - attr_max: int, maximum attribute size (0 for no limit)
32
        - metadata_max: int, maximum metadata size (0 for no limit)
33
        - disk_version: int, disk format version (0 for default)
34
        """
35

36
class LFSFilesystem:
37
    """Low-level filesystem object representing mounted LittleFS state."""
38
    
39
    @property
40
    def block_count(self) -> int:
41
        """Number of blocks in the filesystem."""
42

43
class LFSFile:
44
    """Low-level file handle for opened files."""
45
    
46
    @property 
47
    def flags(self) -> LFSFileFlag:
48
        """File mode flags of the opened file."""
49

50
class LFSDirectory:
51
    """Low-level directory handle for opened directories."""
52
```
53

54
### Configuration Properties
55

56
Access to LFSConfig parameters for runtime inspection.
57

58
```python { .api }
59
# LFSConfig properties (read-only)
60
@property
61
def read_size(self) -> int:
62
    """Minimum read size in bytes."""
63

64
@property  
65
def prog_size(self) -> int:
66
    """Minimum program size in bytes."""
67

68
@property
69
def block_size(self) -> int:
70
    """Block size in bytes."""
71

72
@property
73
def block_count(self) -> int:
74
    """Number of blocks in filesystem."""
75

76
@property
77
def cache_size(self) -> int:
78
    """Block cache size in bytes."""
79

80
@property
81
def lookahead_size(self) -> int:
82
    """Lookahead buffer size in bytes."""
83

84
@property
85
def name_max(self) -> int:
86
    """Maximum filename length."""
87

88
@property
89
def file_max(self) -> int:
90
    """Maximum file size (0 for no limit)."""
91

92
@property
93
def attr_max(self) -> int:
94
    """Maximum attribute size (0 for no limit)."""
95

96
@property
97
def metadata_max(self) -> int:
98
    """Maximum metadata size (0 for no limit)."""
99

100
@property
101
def disk_version(self) -> int:
102
    """Disk format version."""
103

104
@property
105
def user_context(self) -> UserContext:
106
    """Associated user context (storage backend)."""
107
```
108

109
### Filesystem Operations
110

111
Core filesystem management functions that directly map to LittleFS C API.
112

113
```python { .api }
114
def format(fs: LFSFilesystem, cfg: LFSConfig) -> int:
115
    """
116
    Format the filesystem.
117
    
118
    Parameters:
119
    - fs: LFSFilesystem, filesystem object
120
    - cfg: LFSConfig, configuration object
121
    
122
    Returns:
123
    int: 0 on success, negative error code on failure
124
    """
125

126
def mount(fs: LFSFilesystem, cfg: LFSConfig) -> int:
127
    """
128
    Mount the filesystem.
129
    
130
    Parameters:
131
    - fs: LFSFilesystem, filesystem object
132
    - cfg: LFSConfig, configuration object
133
    
134
    Returns:
135
    int: 0 on success, negative error code on failure
136
    """
137

138
def unmount(fs: LFSFilesystem) -> int:
139
    """
140
    Unmount the filesystem.
141
    
142
    Parameters:
143
    - fs: LFSFilesystem, filesystem object
144
    
145
    Returns:
146
    int: 0 on success, negative error code on failure
147
    """
148

149
def fs_stat(fs: LFSFilesystem) -> LFSFSStat:
150
    """
151
    Get filesystem status.
152
    
153
    Parameters:
154
    - fs: LFSFilesystem, filesystem object
155
    
156
    Returns:
157
    LFSFSStat: Filesystem statistics
158
    """
159

160
def fs_size(fs: LFSFilesystem) -> int:
161
    """
162
    Get number of blocks currently in use.
163
    
164
    Parameters:
165
    - fs: LFSFilesystem, filesystem object
166
    
167
    Returns:
168
    int: Number of used blocks
169
    """
170

171
def fs_gc(fs: LFSFilesystem) -> int:
172
    """
173
    Perform garbage collection.
174
    
175
    Parameters:
176
    - fs: LFSFilesystem, filesystem object
177
    
178
    Returns:
179
    int: 0 on success, negative error code on failure
180
    """
181

182
def fs_mkconsistent(fs: LFSFilesystem) -> int:
183
    """
184
    Make filesystem consistent and ready for writing.
185
    
186
    Parameters:
187
    - fs: LFSFilesystem, filesystem object
188
    
189
    Returns:
190
    int: 0 on success, negative error code on failure
191
    """
192

193
def fs_grow(fs: LFSFilesystem, block_count: int) -> int:
194
    """
195
    Grow filesystem to new size.
196
    
197
    Parameters:
198
    - fs: LFSFilesystem, filesystem object
199
    - block_count: int, new number of blocks
200
    
201
    Returns:
202
    int: 0 on success, negative error code on failure
203
    """
204
```
205

206
### File Operations
207

208
Low-level file I/O operations with direct control over flags and buffering.
209

210
```python { .api }
211
def file_open(fs: LFSFilesystem, path: str, flags: Union[str, int]) -> LFSFile:
212
    """
213
    Open a file.
214
    
215
    Parameters:
216
    - fs: LFSFilesystem, filesystem object
217
    - path: str, file path
218
    - flags: str or int, open flags ('r', 'w', 'a', 'x', '+') or LFSFileFlag values
219
    
220
    Returns:
221
    LFSFile: File handle
222
    
223
    Raises:
224
    LittleFSError: On open failure
225
    """
226

227
def file_close(fs: LFSFilesystem, fh: LFSFile) -> int:
228
    """
229
    Close a file.
230
    
231
    Parameters:
232
    - fs: LFSFilesystem, filesystem object
233
    - fh: LFSFile, file handle
234
    
235
    Returns:
236
    int: 0 on success, negative error code on failure
237
    """
238

239
def file_sync(fs: LFSFilesystem, fh: LFSFile) -> None:
240
    """
241
    Sync file to storage.
242
    
243
    Parameters:
244
    - fs: LFSFilesystem, filesystem object
245
    - fh: LFSFile, file handle
246
    
247
    Raises:
248
    LittleFSError: On sync failure
249
    """
250

251
def file_read(fs: LFSFilesystem, fh: LFSFile, size: int) -> bytes:
252
    """
253
    Read from file.
254
    
255
    Parameters:
256
    - fs: LFSFilesystem, filesystem object
257
    - fh: LFSFile, file handle
258
    - size: int, number of bytes to read
259
    
260
    Returns:
261
    bytes: Data read (may be shorter than requested)
262
    
263
    Raises:
264
    LittleFSError: On read failure
265
    """
266

267
def file_write(fs: LFSFilesystem, fh: LFSFile, data: bytes) -> int:
268
    """
269
    Write to file.
270
    
271
    Parameters:
272
    - fs: LFSFilesystem, filesystem object
273
    - fh: LFSFile, file handle  
274
    - data: bytes, data to write
275
    
276
    Returns:
277
    int: Number of bytes written
278
    
279
    Raises:
280
    LittleFSError: On write failure
281
    RuntimeError: If not all data was written
282
    """
283

284
def file_seek(fs: LFSFilesystem, fh: LFSFile, off: int, whence: int) -> int:
285
    """
286
    Seek to position in file.
287
    
288
    Parameters:
289
    - fs: LFSFilesystem, filesystem object
290
    - fh: LFSFile, file handle
291
    - off: int, offset
292
    - whence: int, seek reference (io.SEEK_SET, io.SEEK_CUR, io.SEEK_END)
293
    
294
    Returns:
295
    int: New file position
296
    
297
    Raises:
298
    LittleFSError: On seek failure
299
    """
300

301
def file_tell(fs: LFSFilesystem, fh: LFSFile) -> int:
302
    """
303
    Get current file position.
304
    
305
    Parameters:
306
    - fs: LFSFilesystem, filesystem object
307
    - fh: LFSFile, file handle
308
    
309
    Returns:
310
    int: Current file position
311
    
312
    Raises:
313
    LittleFSError: On error
314
    """
315

316
def file_truncate(fs: LFSFilesystem, fh: LFSFile, size: int) -> int:
317
    """
318
    Truncate file to specified size.
319
    
320
    Parameters:
321
    - fs: LFSFilesystem, filesystem object
322
    - fh: LFSFile, file handle
323
    - size: int, new file size
324
    
325
    Returns:
326
    int: 0 on success, negative error code on failure
327
    """
328

329
def file_rewind(fs: LFSFilesystem, fh: LFSFile) -> int:
330
    """
331
    Rewind file to beginning.
332
    
333
    Parameters:
334
    - fs: LFSFilesystem, filesystem object
335
    - fh: LFSFile, file handle
336
    
337
    Returns:
338
    int: 0 on success, negative error code on failure
339
    """
340

341
def file_size(fs: LFSFilesystem, fh: LFSFile) -> int:
342
    """
343
    Get file size.
344
    
345
    Parameters:
346
    - fs: LFSFilesystem, filesystem object
347
    - fh: LFSFile, file handle
348
    
349
    Returns:
350
    int: File size in bytes
351
    
352
    Raises:
353
    LittleFSError: On error
354
    """
355
```
356

357
### Directory Operations
358

359
Low-level directory access and iteration.
360

361
```python { .api }
362
def mkdir(fs: LFSFilesystem, path: str) -> int:
363
    """
364
    Create a directory.
365
    
366
    Parameters:
367
    - fs: LFSFilesystem, filesystem object
368
    - path: str, directory path
369
    
370
    Returns:
371
    int: 0 on success, negative error code on failure
372
    """
373

374
def dir_open(fs: LFSFilesystem, path: str) -> LFSDirectory:
375
    """
376
    Open a directory for reading.
377
    
378
    Parameters:
379
    - fs: LFSFilesystem, filesystem object
380
    - path: str, directory path
381
    
382
    Returns:
383
    LFSDirectory: Directory handle
384
    
385
    Raises:
386
    LittleFSError: On open failure
387
    """
388

389
def dir_close(fs: LFSFilesystem, dh: LFSDirectory) -> int:
390
    """
391
    Close a directory handle.
392
    
393
    Parameters:
394
    - fs: LFSFilesystem, filesystem object
395
    - dh: LFSDirectory, directory handle
396
    
397
    Returns:
398
    int: 0 on success, negative error code on failure
399
    """
400

401
def dir_read(fs: LFSFilesystem, dh: LFSDirectory) -> Optional[LFSStat]:
402
    """
403
    Read next directory entry.
404
    
405
    Parameters:
406
    - fs: LFSFilesystem, filesystem object
407
    - dh: LFSDirectory, directory handle
408
    
409
    Returns:
410
    LFSStat or None: Directory entry info, None when no more entries
411
    
412
    Raises:
413
    LittleFSError: On read failure
414
    """
415

416
def dir_tell(fs: LFSFilesystem, dh: LFSDirectory) -> int:
417
    """
418
    Get current directory position.
419
    
420
    Parameters:
421
    - fs: LFSFilesystem, filesystem object
422
    - dh: LFSDirectory, directory handle
423
    
424
    Returns:
425
    int: Directory position
426
    
427
    Raises:
428
    LittleFSError: On error
429
    """
430

431
def dir_rewind(fs: LFSFilesystem, dh: LFSDirectory) -> int:
432
    """
433
    Rewind directory to beginning.
434
    
435
    Parameters:
436
    - fs: LFSFilesystem, filesystem object
437
    - dh: LFSDirectory, directory handle
438
    
439
    Returns:
440
    int: 0 on success, negative error code on failure
441
    """
442
```
443

444
### Path Operations
445

446
File and directory manipulation at the path level.
447

448
```python { .api }
449
def remove(fs: LFSFilesystem, path: str) -> int:
450
    """
451
    Remove a file or empty directory.
452
    
453
    Parameters:
454
    - fs: LFSFilesystem, filesystem object
455
    - path: str, path to remove
456
    
457
    Returns:
458
    int: 0 on success, negative error code on failure
459
    """
460

461
def rename(fs: LFSFilesystem, oldpath: str, newpath: str) -> int:
462
    """
463
    Rename or move a file or directory.
464
    
465
    Parameters:
466
    - fs: LFSFilesystem, filesystem object
467
    - oldpath: str, current path
468
    - newpath: str, new path
469
    
470
    Returns:
471
    int: 0 on success, negative error code on failure
472
    """
473

474
def stat(fs: LFSFilesystem, path: str) -> LFSStat:
475
    """
476
    Get file or directory status.
477
    
478
    Parameters:
479
    - fs: LFSFilesystem, filesystem object
480
    - path: str, path to examine
481
    
482
    Returns:
483
    LFSStat: Status information
484
    
485
    Raises:
486
    LittleFSError: On stat failure
487
    """
488
```
489

490
### Extended Attributes
491

492
Low-level attribute operations for metadata storage.
493

494
```python { .api }
495
def getattr(fs: LFSFilesystem, path: str, typ: int) -> bytes:
496
    """
497
    Get extended attribute.
498
    
499
    Parameters:
500
    - fs: LFSFilesystem, filesystem object
501
    - path: str, file or directory path
502
    - typ: int, attribute type (0-255)
503
    
504
    Returns:
505
    bytes: Attribute data
506
    
507
    Raises:
508
    LittleFSError: On failure
509
    """
510

511
def setattr(fs: LFSFilesystem, path: str, typ: int, data: bytes) -> None:
512
    """
513
    Set extended attribute.
514
    
515
    Parameters:
516
    - fs: LFSFilesystem, filesystem object
517
    - path: str, file or directory path
518
    - typ: int, attribute type (0-255)
519
    - data: bytes, attribute data
520
    
521
    Raises:
522
    LittleFSError: On failure
523
    """
524

525
def removeattr(fs: LFSFilesystem, path: str, typ: int) -> None:
526
    """
527
    Remove extended attribute.
528
    
529
    Parameters:
530
    - fs: LFSFilesystem, filesystem object
531
    - path: str, file or directory path
532
    - typ: int, attribute type (0-255)
533
    
534
    Raises:
535
    LittleFSError: On failure
536
    """
537
```
538

539
## Constants
540

541
```python { .api }
542
__LFS_VERSION__: Tuple[int, int]  # LittleFS library version
543
__LFS_DISK_VERSION__: Tuple[int, int]  # LittleFS disk format version
544
FILENAME_ENCODING: str = 'ascii'  # Default filename encoding
545
```
546

547
## Usage Examples
548

549
### Basic Low-Level Usage
550

551
```python
552
from littlefs import lfs
553

554
# Create configuration and filesystem objects
555
cfg = lfs.LFSConfig(block_size=512, block_count=256)
556
fs = lfs.LFSFilesystem()
557

558
# Format and mount
559
lfs.format(fs, cfg)
560
lfs.mount(fs, cfg)
561

562
# Create a file and write data
563
fh = lfs.file_open(fs, 'test.txt', 'w')
564
lfs.file_write(fs, fh, b'Hello, World!')
565
lfs.file_close(fs, fh)
566

567
# Read the file back
568
fh = lfs.file_open(fs, 'test.txt', 'r')
569
data = lfs.file_read(fs, fh, 1024)
570
lfs.file_close(fs, fh)
571
print(data)  # b'Hello, World!'
572

573
# Clean up
574
lfs.unmount(fs)
575
```
576

577
### Directory Iteration
578

579
```python
580
# Create some files and directories
581
lfs.mkdir(fs, 'data')
582
fh = lfs.file_open(fs, 'data/file1.txt', 'w')
583
lfs.file_write(fs, fh, b'content1')
584
lfs.file_close(fs, fh)
585

586
# Iterate through directory
587
dh = lfs.dir_open(fs, 'data')
588
while True:
589
    entry = lfs.dir_read(fs, dh)
590
    if entry is None:
591
        break
592
    if entry.name not in ['.', '..']:
593
        print(f"{entry.name}: type={entry.type}, size={entry.size}")
594
lfs.dir_close(fs, dh)
595
```
596

597
### Advanced Configuration
598

599
```python
600
from littlefs.context import UserContext
601

602
# Custom context with specific buffer size
603
ctx = UserContext(buffsize=1024*1024)  # 1MB buffer
604

605
# Advanced configuration
606
cfg = lfs.LFSConfig(
607
    context=ctx,
608
    block_size=4096,
609
    block_count=256,
610
    read_size=256,
611
    prog_size=256,
612
    block_cycles=500,
613
    cache_size=1024,
614
    lookahead_size=32,
615
    name_max=255
616
)
617

618
fs = lfs.LFSFilesystem()
619
lfs.format(fs, cfg)
620
lfs.mount(fs, cfg)
621

622
# Check filesystem statistics
623
stat = lfs.fs_stat(fs)
624
print(f"Block size: {stat.block_size}")
625
print(f"Block count: {stat.block_count}")
626
print(f"Used blocks: {lfs.fs_size(fs)}")
627
```