Welcome to little lamb

Code » limb » master » tree

[master] / src / doc / djbunix.h / rm_rf.3.md 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
% limb manual
% rm_rf(3)
% limb 0.1.0
% 2023-07-24

# NAME

rm_rf, rm_rfat, rm_rf_tmp, rm_rf_tmpat, rm_rf_in_tmp, rm_rf_in_tmpat - remove
an entire directory entry

rmstar, rmstarat, rmstar_tmp, rmstar_tmpat, rmstar_in_tmp, rmstar_in_tmpat -
remove the full content of a directory

# SYNOPSIS

    #include <fcntl.h> /* AT_FDCWD */
    #include <limb/djbunix.h>

```pre hl
int rm_rf(const char *<em>name</em>)
int rm_rfat(int <em>fd</em>, const char *<em>name</em>)

int rm_rf_tmp(const char *<em>name</em>, stralloc *<em>sa</em>)
int rm_rf_tmpat(int <em>fd</em>, const char *<em>name</em>, stralloc *<em>sa</em>)

int rm_rf_in_tmp(stralloc *<em>sa</em>, size_t <em>offset</em>)
int rm_rf_in_tmpat(int <em>fd</em>, stralloc *<em>sa</em>, size_t <em>offset</em>)

int rmstar(const char *<em>name</em>)
int rmstarat(int <em>fd</em>, const char *<em>name</em>)

int rmstar_tmp(const char *<em>name</em>, stralloc *<em>sa</em>)
int rmstar_tmpat(int <em>fd</em>, const char *<em>name</em>, stralloc *<em>sa</em>)

int rmstar_in_tmpat(int <em>fd</em>, stralloc *<em>sa</em>, size_t <em>offset</em>)
```

# DESCRIPTION

The `rm_rf`() function removes the entire directory entry named `name` from
the filesystem, whether a file, a directory (empty or not), etc.

The `rm_rfat`() function is similar to `rm_rf`() except when `name` specifies a
relative path, relative to the directory associated with the file descriptor
`fd` instead of the current working directory.
If passed the special value *AT_FDCWD* in the `fd` parameter, the current
working directory is used.

The `rm_rf_tmp`() and `rm_rf_tmpat`() functions are similar to `rm_rf`() and
`rm_rfat`() respectively, except that they will use the given stralloc `sa` as
heap-allocated temporary space.

The `rm_rf_in_tp`() and `rm_rf_in_tmpat`() functions are similar to
`rm_rm_tmp`() and `rm_rm_tmpat`() respectively, except that they expect `sa` to
contain a NUL-terminated string of the name at offset `offset`.


The `rmstar`() function removes the full content of directory `name` recursively
(leaving only the (empty) directory itself).

The `rmstarat`() function is similar to `rmstar`() except when `name` specifies
a relative path, relative to the directory associated with the file descriptor
`fd` instead of the current working directory.
If passed the special value *AT_FDCWD* in the `fd` parameter, the current
working directory is used.

The `rmstar_tmp`() and `rmstar_tmpat`() function are similar to `rmstar`() and
`rm_starat`() respectively, except that they will use the given stralloc `sa` as
heap-allocated temporary space.

The `rmstar_in_tmpat`() function is similar to `rmstar_tmpat`() except that it
expects `sa` to contain a NUL-terminated string of the name at offset `offset`.


# RETURN VALUE

Upon successful completion, these functions return 0. Otherwise, they return -1
and set `errno` to indicate the error.

Note that these functions are *not* atomic and, in case of failure, might leave
the relevant directory partially removed.

# ERRORS

These functions may fail if :

: *ENOMEM*
:: Out of memory

The `rm*at`() family of functions may also fail and set `errno` for any of the
errors specified for the functions [unlinkat](3) and [sa_lsat](3).

The other family of functions may also fail and set `errno` for any of the
errors specified for the functions [unlink](3), [rmdir](3) and [sa_ls](3).