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
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
===========================
File and directory handling
===========================
Directory traversal
===================
libHX provides a minimal readdir-style wrapper for cross-platform directory
traversal. This is needed because the Win32 platforms does not have readdir,
and there is some housekeeping to do on Unixish platforms, since the dirent
structure needs allocation of a path-specific size.
.. code-block:: c
#include <libHX/io.h>
struct HXdir *HXdir_open(const char *directory);
const char *HXdir_read(struct HXdir *handle);
void HXdir_close(struct HXdir *handle);
``HXdir_open`` returns a pointer to its private data area, or ``NULL`` upon
failure, in which case ``errno`` is preserved from the underlying system calls.
``HXdir_read`` causes the next entry from the directory to be fetched. The
pointer returned by ``HXdir_read`` must not be freed, and the data is
overwritten in subsequent calls to the same handle. If you want to keep it
around, you will have to duplicate it yourself. ``HXdir_close`` will close the
directory and free the private data it held.
Example
-------
.. code-block:: c
#include <errno.h>
#include <stdio.h>
#include <libHX/io.h>
struct HXdir *dh;
if ((dh = HXdir_open(".")) == NULL) {
fprintf(stderr, "Could not open directory: %s\n", strerror(errno));
return;
}
while ((dentry = HXdir_read(dh)) != NULL)
printf("%s\n", dentry);
HXdir_close(dh);
This sample will open the current directory, and print out all entries as it
iterates over them.
Operation on directory entries
==============================
.. code-block:: c
#include <libHX/io.h>
int HX_readlink(hxmc_t **buf, const char *path);
int HX_realpath(hxmc_t **buf, const char *path, unsigned int flags);
``HX_readlink`` calls through to readlink to read the target of a symbolic
link, and stores the result in the memory container referenced by ``*buf``
(similar to ``HX_getl`` semantics). If ``*buf`` is ``NULL``, a new container
will be allocated and a pointer to it stored in ``*buf``. The container's
content is naturally zero-terminated automatically. The return value of the
function will be the length of the link target, or negative to indicate the
system error value.
``HX_realpath`` will normalize the given path by transforming various path
components into alternate descriptions. The flags parameter controls its
actions:
``HX_REALPATH_DEFAULT``
A mnemonic for a set of standard flags: ``HX_REALPATH_SELF |
HX_REALPATH_PARENT``. Note that ``HX_REALPATH_ABSOLUTE``, which would
also be required to get libc's ``realpath``(3) behavior, is not
included in the set.
``HX_REALPATH_ABSOLUTE``
Requests that the output path shall be absolute. In the absence of this
flag, an absolute output path will only be produced if the input path
is also absolute.
``HX_REALPATH_SELF``
Request resolution of `.` path components.
``HX_REALPATH_PARENT`
Request resolution of `..` path components.
The result is stored in a memory container whose pointer is returned through
``*buf``. The return value of the function will be negative to indicate a
possible system error, or be positive non-zero for success.
Operations on directories
=========================
.. code-block:: c
#include <libHX/io.h>
int HX_mkdir(const char *path, unsigned int mode);
int HX_rrmdir(const char *path);
``HX_mkdir`` will create the directory given by path and all its parents that
do not exist yet using the given mode. It is equivalent to the ``mkdir -p``
shell command. It will return >0 for success, or ``-errno`` on error.
``HX_rrmdir`` also maps to an operation commonly done on the shell, ``rm -Rf``,
deleting the directory given by path, including all files within it and its
subdirectories. Errors during deletion are ignored, but if there was any, the
errno value of the first one is returned negated.
Operations on files
===================
.. code-block:: c
#include <libHX/io.h>
#define HXF_KEEP ...
#define HXF_UID ...
#define HXF_GID ...
int HX_copy_file(const char *src, const char *dest, unsigned int flags, ...);
int HX_copy_dir(const char *src, const char *dest, unsigned int flags, ...);
char *HX_slurp_fd(int fd, size_t *outsize);
char *HX_slurp_file(const char *file, size_t *outsize);
``HX_copy_file``
Copies one named file to a new location. Possible ``flags`` are
``HXF_KEEP``, ``HXF_UID`` and ``HXF_GID``. Error checking by
``HX_copy_file`` is flakey. ``HX_copy_file`` will return >0 on success,
or ``-errno`` on failure. Errors can arise from the use of the syscalls
``open``, ``read`` and ``write``. The return value of ``fchmod``, which
is used to set the UID and GID, is actually ignored, which means
verifying that the owner has been set cannot be detected with
``HX_copy_file`` alone (historic negligience?).
``HXF_KEEP``
Do not overwrite existing files.
``HXF_UID``
Change the new file's owner to the UID given in the varargs section
(...). ``HXF_UID`` is processed before ``HXF_GID``.
``HXF_GID``
Change the new file's group owner to the GID given in the varargs
section. This is processed after ``HXF_UID``.
``HX_copy_dir``
Copies one named directory to a new location, recursively.
(Uses ``HX_copy_file`` and ``HX_copy_dir``.) Error checking by
``HX_copy_dir`` is flakey.
``HX_slurp_fd``
Reads all remaining bytes from the given filedescriptor ``fd`` and
returns a pointer to a newly-allocated content buffer. If ``outsize``
is not ``NULL``, the size of the buffer will be written to it. The
buffer is always terminated by a gratuitious NUL (not counted in
``outsize``). Once no longer needed, the buffer should be released with
``free``.
``HX_slurp_file``
Reads all bytes from the given filename and returns a pointer to the
content buffer. Inherits all the characteristics from ``HX_slurp_fd``.
Filedescriptor helpers
======================
.. code-block:: c
#include <libHX/io.h>
ssize_t HXio_fullread(int fd, void *buf, size_t size, unsigned int flags);
ssize_t HXio_fullwrite(int fd, const void *buf, size_t size, unsigned int flags);
ssize_t HX_sendfile(int dst, int src, size_t count);
Since plain ``read``(2) and ``write``(2) may process only part of the buffer —
even more likely so with sockets —, libHX provides two functions that calls
these in a loop to retry said operations until the full amount has been
processed. Since read and write can also be used with socket file descriptors,
so can these.
``HX_sendfile`` wraps ``sendfile``(2) for the same reason; in addition, it
falls back to a read-write loop on platforms which do not offer sendfile.
|
