djbunix.html (26841B)
1 <html> 2 <head> 3 <meta name="viewport" content="width=device-width, initial-scale=1.0" /> 4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 5 <meta http-equiv="Content-Language" content="en" /> 6 <title>skalibs: the djbunix library interface</title> 7 <meta name="Description" content="skalibs: the djbunix library interface" /> 8 <meta name="Keywords" content="skalibs c unix djbunix library libstddjb" /> 9 <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> 10 </head> 11 <body> 12 13 <p> 14 <a href="index.html">libstddjb</a><br /> 15 <a href="../libskarnet.html">libskarnet</a><br /> 16 <a href="../index.html">skalibs</a><br /> 17 <a href="//skarnet.org/software/">Software</a><br /> 18 <a href="//skarnet.org/">skarnet.org</a> 19 </p> 20 21 <h1> The <tt>djbunix</tt> library interface </h1> 22 23 <p> 24 The following functions are declared in the <tt>skalibs/djbunix.h</tt> header, 25 and implemented in the <tt>libskarnet.a</tt> or <tt>libskarnet.so</tt> library. 26 </p> 27 28 <h2> General information </h2> 29 30 <p> 31 <tt>djbunix</tt> is an alternative API to management of basic Unix 32 concepts: file descriptors, files, environment, and so on. It is a 33 rather chaotic mix of <a href="safewrappers.html">safe wrappers</a> 34 around Unix system calls, better reimplementations of standard libc 35 functionalities, and higher-level manipulations of Unix concepts. 36 </p> 37 38 <p> 39 Understanding <tt>djbunix</tt> is essential to understanding any piece 40 of code depending on skalibs. 41 </p> 42 43 <h2> Functions </h2> 44 45 <h3> Basic fd operations </h3> 46 47 <p> 48 <code> int coe (int fd) </code> <br /> 49 Sets the close-on-exec flag on <em>fd</em>. 50 Returns 0 if it succeeds, or -1 (and sets errno) if it fails. 51 </p> 52 53 <p> 54 <code> int uncoe (int fd) </code> <br /> 55 Clears the close-on-exec flag on <em>fd</em>. 56 Returns 0 if it succeeds, or -1 (and sets errno) if it fails. 57 </p> 58 59 <p> 60 <code> int ndelay_on (int fd) </code> <br /> 61 Sets the O_NONBLOCK flag on <em>fd</em>: sets it to non-blocking mode. 62 Returns 0 if it succeeds, or -1 (and sets errno) if it fails. 63 </p> 64 65 <p> 66 <code> int ndelay_off (int fd) </code> <br /> 67 Clears the O_NONBLOCK flag on <em>fd</em>: sets it to blocking mode. 68 Returns 0 if it succeeds, or -1 (and sets errno) if it fails. 69 </p> 70 71 <p> 72 <code> int pipenb (int *p) </code> <br /> 73 Like 74 <a href="https://www.opengroup.org/onlinepubs/9699919799/functions/pipe.html">pipe()</a>, 75 but both ends of the created pipe are in non-blocking mode. 76 </p> 77 78 <p> 79 <code> int pipecoe (int *p) </code> <br /> 80 Like 81 <a href="https://www.opengroup.org/onlinepubs/9699919799/functions/pipe.html">pipe()</a>, 82 but both ends of the created pipe are close-on-exec. 83 </p> 84 85 <p> 86 <code> int pipenbcoe (int *p) </code> <br /> 87 Like 88 <a href="https://www.opengroup.org/onlinepubs/9699919799/functions/pipe.html">pipe()</a>, 89 but both ends of the created pipe are in non-blocking mode <em>and</em> close-on-exec. 90 </p> 91 92 <p> 93 <code> int fd_copy (int to, int from) </code> <br /> 94 Copies the open fd <em>from</em> to number <em>to</em>. If <em>to</em> 95 was already open, it is closed before the copy. 96 Returns 0 if it succeeds, or -1 (and sets errno) if it fails. 97 </p> 98 99 <p> 100 <code> int fd_copy2 (int to1, int from1, int to2, int from2) </code> <br /> 101 Copies the open fd <em>from1</em> to number <em>to2</em>. Also copies 102 <em>from2</em> to <em>to2</em> at the same time. 103 Returns 0 if it succeeds, or -1 (and sets errno) if it fails. 104 </p> 105 106 <p> 107 <code> int fd_move (int to, int from) </code> <br /> 108 Moves the open fd <em>from</em> to number <em>to</em>. If <em>to</em> 109 was already open, it is closed before the move. 110 Returns 0 if it succeeds, or -1 (and sets errno) if it fails. 111 </p> 112 113 <p> 114 <code> int fd_move2 (int to1, int from1, int to2, int from2) </code> <br /> 115 Moves the open fd <em>from</em> to number <em>to</em>. Also moves 116 <em>from2</em> to <em>to2</em> at the same time. This is useful for instance 117 when you want to swap two fds: <tt>fd_move2</tt> will handle the situation 118 correctly. 119 Returns 0 if it succeeds, or -1 (and sets errno) if it fails. 120 </p> 121 122 <p> 123 <code> void fd_close (int fd) </code> <br /> 124 Closes <em>fd</em>. 125 This is a <a href="safewrappers.html">safe wrapper</a> around 126 <a href="https://www.opengroup.org/onlinepubs/9699919799/functions/close.html">close()</a>. 127 </p> 128 129 <p> 130 <code> int fd_chmod (int fd, unsigned int mode) </code> <br /> 131 Safe wrapper around 132 <a href="https://www.opengroup.org/onlinepubs/9699919799/functions/fchmod.html">fchmod()</a>. 133 </p> 134 135 <p> 136 <code> int fd_chown (int fd, uid_t uid, gid_t gid) </code> <br /> 137 Safe wrapper around 138 <a href="https://www.opengroup.org/onlinepubs/9699919799/functions/fchown.html">fchown()</a>. 139 This function requires root privileges. 140 </p> 141 142 <p> 143 <code> int fd_sync (int fd) </code> <br /> 144 Safe wrapper around 145 <a href="https://www.opengroup.org/onlinepubs/9699919799/functions/fsync.html">fsync()</a>. 146 </p> 147 148 <p> 149 <code> int fd_chdir (int fd) </code> <br /> 150 Safe wrapper around 151 <a href="https://www.opengroup.org/onlinepubs/9699919799/functions/fchdir.html">fchdir()</a>. 152 </p> 153 154 <p> 155 <code> off_t fd_cat (int from, int to) </code> <br /> 156 Synchronously copies data from fd <em>from</em> to fd <em>to</em>, 157 until it encounters EOF or an error. Returns -1 (and sets errno) if 158 it fails; returns the number of transmitted bytes if it gets an EOF. 159 </p> 160 161 <p> 162 When the underlying OS allows it, zero-copy transmission is 163 performed. Currently, the following zero-copy implementations are 164 supported: 165 </p> 166 167 <ul> 168 <li> <a href="https://man7.org/linux/man-pages/man2/splice.2.html">splice()</a>, 169 in Linux 2.6.17 and later </li> 170 </ul> 171 172 <p> 173 <code> off_t fd_catn (int from, int to, off_t n) </code> <br /> 174 Synchronously copies at most <em>n</em> bytes from fd <em>from</em> to fd <em>to</em>. 175 Returns the total number of transmitted bytes; sets errno if this number 176 is lesser than <em>n</em>. EOF is reported as EPIPE. See above for zero-copy 177 transmission; zero-copy transmission is not attempted for less than 64k of data. 178 </p> 179 180 <p> 181 <code> int fd_ensure_open (int fd, int w) </code> <br /> 182 If <em>fd</em> is not open, opens it to <tt>/dev/null</tt>, 183 for reading if <em>w</em> is zero, and for writing otherwise. 184 Returns 1 if it succeeds and 0 if it fails. 185 </p> 186 187 <p> 188 <code> int fd_sanitize (void) </code> <br /> 189 Ensures stdin, stdout and stderr are open. If one of those 190 file descriptors was closed, it now points to <tt>/dev/null</tt>. 191 Returns 1 if it succeeds and 0 if it fails. 192 </p> 193 194 <p> 195 <code> void fd_shutdown (int fd, int w) </code> <br /> 196 Shuts down socket <em>fd</em>, for reading if <em>w</em> is zero, 197 and for writing otherwise. Does not return an error code; does 198 not modify errno. This is just a call to 199 <a href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/shutdown.html">shutdown()</a> 200 with errno saved, used essentially to isolate application code from 201 <tt>sys/socket.h</tt> which is a portability nightmare. 202 </p> 203 204 <p> 205 <code> int fd_lock (int fd, int w, int nb) </code> <br /> 206 Gets an advisory lock on <em>fd</em>: shared if <em>w</em> is 207 zero, exclusive otherwise. <em>fd</em> must point to 208 a regular file, open for writing or reading depending on whether 209 you want an exclusive lock or not. If <em>nb</em> is zero, the 210 function blocks until the lock can be obtained; otherwise it 211 returns 0 immediately. On success, the function returns 1 ; it 212 returns 0 if it cannot take the lock, or -1 (and sets errno) if 213 an error occurs. 214 </p> 215 216 <p> 217 <code> void fd_unlock (int fd) </code> <br /> 218 Releases a previously held lock on <em>fd</em>. 219 </p> 220 221 <p> 222 <code> int fd_islocked (int fd) </code> <br /> 223 Returns 1 if a lock is currently held on fd, 0 otherwise. 224 Returns -1 (and sets errno) if an error occurs. 225 </p> 226 227 <p> 228 <code> int open2 (char const *file, unsigned int flags) </code> <br /> 229 Safe wrapper around 230 <a href="https://www.opengroup.org/onlinepubs/9699919799/functions/open.html">open()</a> 231 when it takes 2 arguments. 232 </p> 233 234 <p> 235 <code> int open3 (char const *file, unsigned int flags, unsigned int mode) </code> <br /> 236 Safe wrapper around 237 <a href="https://www.opengroup.org/onlinepubs/9699919799/functions/open.html">open()</a> 238 when it takes 3 arguments. 239 </p> 240 241 <p> 242 <code> int open_read (char const *file) </code> <br /> 243 Opens <em>file</em> in read-only, non-blocking mode. 244 Returns a valid fd number if it succeeds, or -1 (and sets errno) if it fails. 245 </p> 246 247 <p> 248 <code> int openc_read (char const *file) </code> <br /> 249 Opens <em>file</em> in read-only, non-blocking mode, close-on-exec. 250 Returns a valid fd number if it succeeds, or -1 (and sets errno) if it fails. 251 </p> 252 253 <p> 254 <code> int openb_read (char const *file) </code> <br /> 255 Opens <em>file</em> in read-only, blocking mode. 256 Returns a valid fd number if it succeeds, or -1 (and sets errno) if it fails. 257 </p> 258 259 <p> 260 <code> int openbc_read (char const *file) </code> <br /> 261 Opens <em>file</em> in read-only, blocking mode, close-on-exec. 262 Returns a valid fd number if it succeeds, or -1 (and sets errno) if it fails. 263 </p> 264 265 <p> 266 <code> int open_readb (char const *file) </code> <br /> 267 Opens <em>file</em> in read-only, blocking mode. 268 Returns a valid fd number if it succeeds, or -1 (and sets errno) if it fails. 269 <em>This call does not block.</em> The 270 <a href="https://www.opengroup.org/onlinepubs/9699919799/functions/open.html">open()</a> 271 system call is actually performed with the O_NONBLOCK option, and blocking mode 272 is set afterwards; this behaviour allows for more transparent interactions 273 with FIFOs. 274 </p> 275 276 <p> 277 <code> int openc_readb (char const *file) </code> <br /> 278 Same as above, but the file is opened close-on-exec. 279 </p> 280 281 <p> 282 <code> int open_excl (char const *file) </code> <br /> 283 Opens <em>file</em> in write-only, non-blocking mode, with the 284 additional O_EXCL and O_CREAT flags. 285 Returns a valid fd number if it succeeds, or -1 (and sets errno) if it fails. 286 </p> 287 288 <p> 289 <code> int openc_excl (char const *file) </code> <br /> 290 Opens <em>file</em> in write-only, non-blocking mode, close-on-exec, with the 291 additional O_EXCL and O_CREAT flags. 292 Returns a valid fd number if it succeeds, or -1 (and sets errno) if it fails. 293 </p> 294 295 <p> 296 <code> int open_append (char const *file) </code> <br /> 297 Opens <em>file</em> in write-only, non-blocking mode, with the 298 additional O_APPEND and O_CREAT flags. 299 Returns a valid fd number if it succeeds, or -1 (and sets errno) if it fails. 300 </p> 301 302 <p> 303 <code> int openc_append (char const *file) </code> <br /> 304 Opens <em>file</em> in write-only, non-blocking mode, close-on-exec, with the 305 additional O_APPEND and O_CREAT flags. 306 Returns a valid fd number if it succeeds, or -1 (and sets errno) if it fails. 307 </p> 308 309 <p> 310 <code> int open_trunc (char const *file) </code> <br /> 311 Opens <em>file</em> in write-only, non-blocking mode, with the 312 additional O_TRUNC and O_CREAT flags. 313 Returns a valid fd number if it succeeds, or -1 (and sets errno) if it fails. 314 </p> 315 316 <p> 317 <code> int openc_trunc (char const *file) </code> <br /> 318 Opens <em>file</em> in write-only, non-blocking mode, close-on-exec, with the 319 additional O_TRUNC and O_CREAT flags. 320 Returns a valid fd number if it succeeds, or -1 (and sets errno) if it fails. 321 </p> 322 323 <p> 324 <code> int open_create (char const *file) </code> <br /> 325 Opens <em>file</em> in write-only, non-blocking mode, with the 326 additional O_CREAT flag. 327 Returns a valid fd number if it succeeds, or -1 (and sets errno) if it fails. 328 </p> 329 330 <p> 331 <code> int openc_create (char const *file) </code> <br /> 332 Opens <em>file</em> in write-only, non-blocking mode, close-on-exec, with the 333 additional O_CREAT flag. 334 Returns a valid fd number if it succeeds, or -1 (and sets errno) if it fails. 335 </p> 336 337 <p> 338 <code> int open_write (char const *file) </code> <br /> 339 Opens <em>file</em> in write-only, non-blocking mode. 340 Returns a valid fd number if it succeeds, or -1 (and sets errno) if it fails. 341 </p> 342 343 <p> 344 <code> int openc_write (char const *file) </code> <br /> 345 Opens <em>file</em> in write-only, non-blocking mode, close-on-exec. 346 Returns a valid fd number if it succeeds, or -1 (and sets errno) if it fails. 347 </p> 348 349 <h3> Forking children </h3> 350 351 <p> 352 <code> pid_t doublefork () </code> <br /> 353 Performs a double fork. Returns -1 if it fails (and 354 sets errno, EINTR meaning that the intermediate process 355 was killed by a signal), 0 if the current process is the grandchild, 356 and the grandchild's PID if the current process is the parent. 357 </p> 358 359 <p> 360 The <tt>child_spawn</tt> family of functions has been moved to the 361 <a href="cspawn.html">skalibs/cspawn.h</a> header. 362 </p> 363 364 <h3> Waiting for children </h3> 365 366 <p> 367 <code> unsigned int wait_reap () </code> <br /> 368 Instantly reaps all the pending zombies, without blocking, without a look at 369 the exit codes. 370 Returns the number of reaped zombies. 371 </p> 372 373 <p> 374 <code> int waitn (pid_t *pids, unsigned int n) </code> <br /> 375 Waits until all processes whose PIDs are stored in the 376 <em>pids</em> array, of size <em>n</em>, have died. 377 Returns 1 if it succeeds, and 0 (and sets errno) if it fails. The 378 <em>pid</em> array is not guaranteed to be unchanged. 379 </p> 380 381 <p> 382 <code> int waitn_posix (pid_t *pids, unsigned int n, int *wstat) </code> <br /> 383 Like <tt>waitn</tt>, but stores into <em>*wstat</em> the status 384 of the last process in the <em>pids</em> array (i.e. <tt>pids[n-1]</tt>). 385 </p> 386 387 <p> 388 <code> int waitn_reap (pid_t *pids, unsigned int n) </code> <br /> 389 Instantly reaps all zombies whose PIDs are stored in the 390 <em>pids</em> array, of size <em>n</em>. 391 Returns -1 (and sets errno) if it fails, and the number of reaped 392 zombies if it succeeds. The <em>pid</em> array is not guaranteed to 393 be unchanged. 394 </p> 395 396 <p> 397 <code> int waitn_reap_posix (pid_t *pids, unsigned int n, int *wstat) </code> <br /> 398 Like <tt>waitn_reap</tt>, but stores into <em>*wstat</em> the status 399 of the last process in the <em>pids</em> array (i.e. <tt>pids[n-1]</tt>), 400 if applicable; otherwise <em>*wstat</em> is unchanged. 401 </p> 402 403 <p> 404 <code> pid_t wait_nohang (int *wstat) </code> <br /> 405 Instantly reaps one zombie, and stores the status information into 406 *<em>wstat</em>. 407 Returns the PID of the reaped zombie if it succeeds, 0 if there was 408 nothing to reap (and the current process still has children), -1 ECHILD 409 if there was nothing to reap (and the current process has no children), 410 or -1 (and sets errno) if it fails. 411 </p> 412 413 <p> 414 <code> pid_t waitpid_nointr (pid_t pid, int *wstat, int flags) </code> <br /> 415 Safe wrapper around 416 <a href="https://www.opengroup.org/onlinepubs/9699919799/functions/waitpid.html">waitpid()</a>. 417 </p> 418 419 <p> 420 <code> pid_t wait_pid_nohang (pid_t pid, int *wstat) </code> <br /> 421 Instantly reaps an undetermined number of zombies until it finds <em>pid</em>. 422 Stores the status information for dead <em>pid</em> into *<em>wstat</em>. 423 Returns <em>pid</em> if it succeeds, 0 if there was 424 nothing to reap (and the current process still has children), -1 ECHILD 425 if there was nothing to reap (and the current process has no children), 426 or -1 (and sets errno) if it fails. 427 </p> 428 429 <p> 430 <code> int wait_pids_nohang (pid_t const *pids, unsigned int len, int *wstat) </code> <br /> 431 Instantly reaps an undetermined number of zombies until it finds one whose 432 PID is in the <em>pids</em> array, of size <em>len</em>. 433 Stores the status information for that dead process into *<em>wstat</em>. 434 Returns the index of the found PID in <em>pids</em>, starting at 1. 435 Returns 0 if there was 436 nothing to reap (and the current process still has children), -1 ECHILD 437 if there was nothing to reap (and the current process has no children), 438 or -1 (and sets errno) if it fails. 439 </p> 440 441 <p> 442 When asynchronously dealing with a child (resp. several children) and 443 getting a SIGCHLD - which should be handled via a 444 <a href="selfpipe.html">selfpipe</a> - it is generally a good idea to 445 use the <tt>wait_pid_nohang()</tt> (resp. <tt>wait_pids_nohang()</tt>) 446 function over the basic Unix APIs. This allows a program to: 447 </p> 448 449 <ul> 450 <li> Automatically and silently take care of children it does not know 451 it has. This situation can happen when a process forks and the parent 452 execs. When the child dies, the new parent process has to drag the 453 "zombie bastard" along, which is ugly; <tt>wait_pids_nohang()</tt> 454 prevents this. </li> 455 <li> Still take appropriate care of its legitimate children, in 456 any order. </li> 457 </ul> 458 459 <h3> Reading and writing whole files </h3> 460 461 <p> 462 <code> int slurp (stralloc *sa, int fd) </code> <br /> 463 Slurps the contents of open descriptor <em>fd</em> into 464 the *<em>sa</em> <a href="stralloc.html">stralloc</a>. If you are 465 doing this, you should either have full control over the slurped 466 file, or run your process with suitable 467 <a href="//skarnet.org/software/s6/s6-softlimit.html">limits</a> 468 to the amount of heap memory it can get. 469 The function returns 1 if it succeeds, or 0 (and sets errno) if it fails. 470 </p> 471 472 <p> 473 <code> int slurpn (stralloc *sa, int fd, size_t max) </code> <br /> 474 Same as <tt>slurp</tt>, but only grows the stralloc to a maximum 475 of <em>max</em> bytes of total length. If there is still more to 476 read on <em>fd</em> after <em>sa→len</em> has reached <em>max</em>, 477 the function returns 0 with errno set to ENOBUFS. 478 </p> 479 480 <p> 481 <code> int openslurpclose (stralloc *sa, char const *file) </code> <br /> 482 Slurps the contents of file <em>file</em> into *<em>sa</em>. 483 Returns 1 if it succeeds, and 0 (and sets errno) if it fails. 484 </p> 485 486 <p> 487 <code> ssize_t openreadnclose (char const *file, char *s, size_t n) </code> <br /> 488 Reads at most <em>n</em> bytes from file <em>file</em> into preallocated 489 buffer <em>s</em>. Returns -1 (and sets errno) if it fails; else returns the 490 number of read bytes. 491 </p> 492 493 <p> 494 <code> ssize_t openreadnclose_nb (char const *file, char *s, size_t n) </code> <br /> 495 Like <tt>openreadnclose</tt>, but can fail with EAGAIN if the file cannot be 496 immediately read (for instance if it's a named pipe or other special file). 497 </p> 498 499 <p> 500 <code> int openreadfileclose (char const *file, stralloc *sa, size_t n) </code> <br /> 501 Reads at most <em>n</em> bytes from file <em>file</em> into the *<em>sa</em> 502 stralloc, which is grown (if needed) to <em>just</em> accommodate the file 503 size. Returns 1 if it succeeds and 0 (and sets errno) if it fails. 504 </p> 505 506 <p> 507 <code> int openwritenclose_unsafe5 (char const *file, char const *s, size_t len, devino *devino, unsigned int options) </code> <br> 508 Writes the <em>n</em> bytes stored at <em>s</em> into file <em>file</em>. 509 The previous contents of <em>file</em> are destroyed even if the function 510 fails. If <em>options</em> has bit 0 set, the new contents of <em>file</em> 511 are synced to disk before the function returns. If <em>devino</em> is not null, 512 the device number of <em>file</em> is stored in <em>devino→dev</em> 513 and its inode number in <em>devino&arr;ino</em>. 514 The function returns 1 if it succeeds, or 0 (and sets errno) if it fails. 515 </p> 516 517 <p> 518 <code> int openwritenclose_unsafe (char const *file, char const *s, size_t len) <br> 519 int openwritenclose_unsafe_sync (char const *file, char const *s, size_t len) </code> <br> 520 Trivial shortcuts around <tt>openwritenclose_unsafe5()</tt>. The 521 reader can easily figure out what they do. 522 </p> 523 524 <p> 525 <code> int openwritenclose_suffix6 (char const *file, char const *s, size_t len, devino *devino, unsigned int options, char const *suffix) </code> <br> 526 Writes the <em>n</em> bytes stored at <em>s</em> into file <em>file</em>, 527 by first writing into <em>filesuffix</em> and atomically renaming 528 <em>filesuffix</em> to <em>file</em>. IOW, the old contents of <em>file</em> 529 are preserved if the operation fails, and are atomically replaced with the 530 new contents if the operation succeeds. 531 If <em>options</em> has bit 0 set, the new contents of <em>filesuffix</em> 532 are synced to disk before the atomic replace. If <em>devino</em> is not null, 533 the device number of <em>file</em> is stored in <em>devino→dev</em> 534 and its inode number in <em>devino&arr;ino</em>. 535 The function returns 1 if it succeeds, or 0 (and sets errno) if it fails. 536 </p> 537 538 <p> 539 <code> int openwritenclose_suffix (char const *file, char const *s, size_t len, char const *suffix) <br> 540 int openwritenclose_suffix_sync (char const *file, char const *s, size_t len, char const *suffix) </code> <br> 541 Trivial shortcuts around <tt>openwritenclose_suffix_internal()</tt>. The 542 reader can easily figure out what they do. 543 </p> 544 545 <p> 546 <code> int openwritevnclose_unsafe5 (char const *file, struct iovec const *v, unsigned int vlen, devino *devino, int dosync) </code> <br> 547 Like <tt>openwritenclose_unsafe5</tt>, but the content to 548 write is taken from a 549 <a href="siovec.html">scatter/gather array</a> of <em>vlen</em> 550 elements instead of a single string. 551 </p> 552 553 <p> 554 <code> int openwritevnclose_unsafe (char const *file, struct iovec const *v, unsigned int vlen) <br> 555 int openwritevnclose_unsafe_sync (char const *file, struct iovec const *v, unsigned int vlen) </code> <br> 556 Trivial wrappers around <tt>openwritevnclose_unsafe5()</tt>. 557 </p> 558 559 <p> 560 <code> int openwritevnclose_suffix6 (char const *file, struct iovec const *v, unsigned int vlen, devino *devino, int dosync, char const *suffix) </code> <br> 561 Like <tt>openwritenclose_suffix6</tt>, but the content to 562 write is taken from a 563 <a href="siovec.html">scatter/gather array</a> of <em>vlen</em> 564 elements instead of a single string. 565 </p> 566 567 <p> 568 <code> int openwritevnclose_suffix (char const *file, struct iovec const *v, unsigned int vlen, char const *suffix) <br> 569 int openwritevnclose_suffix_sync (char const *file, struct iovec const *v, unsigned int vlen, char const *suffix) </code> <br> 570 Trivial wrappers around <tt>openwritevnclose_suffix6()</tt>. 571 </p> 572 573 <h3> Filesystem deletion </h3> 574 575 <p> 576 The following operations are not atomic, so if they fail, the 577 relevant subtree might end up partially deleted. 578 </p> 579 580 <p> 581 <code> int rm_rf (char const *path) </code> <br /> 582 Deletes the filesystem subtree at <em>path</em>. 583 Returns 0 if it succeeds or -1 (and sets errno) if it fails. 584 </p> 585 586 <p> 587 <code> int rm_rf_tmp (char const *path, stralloc *tmp) </code> <br /> 588 Deletes the filesystem subtree at <em>path</em>, using *<em>tmp</em> 589 as heap-allocated temporary space. 590 Returns 0 if it succeeds or -1 (and sets errno) if it fails. 591 </p> 592 593 <p> 594 <code> int rm_rf_in_tmp (stralloc *tmp, size_t n) </code> <br /> 595 Deletes a filesystem subtree, using *<em>tmp</em> 596 as heap-allocated temporary space. 597 Returns 0 if it succeeds or -1 (and sets errno) if it fails. 598 When the function is called, *<em>tmp</em> must contain the 599 null-terminated name of the subtree to delete at offset <em>n</em>. 600 </p> 601 602 <p> 603 <code> int rmstar (char const *dir) </code> <br /> 604 Deletes all the filesystem subtrees in directory <em>dir</em>. 605 Returns 0 if it succeeds or -1 (and sets errno) if it fails. 606 </p> 607 608 <p> 609 <code> int rmstar_tmp (char const *dir, stralloc *tmp) </code> <br /> 610 Deletes all the filesystem subtrees in directory <em>dir</em>, 611 using *<em>tmp</em> as heap-allocated temporary space. 612 Returns 0 if it succeeds or -1 (and sets errno) if it fails. 613 </p> 614 615 <h3> Filesystem copy </h3> 616 617 <p> 618 <code> int hiercopy_tmp (char const *src, char const *dst, stralloc *tmp) </code> <br /> 619 Recursively copies the filesystem hierarchy at <em>src</em> into 620 <em>dst</em>, preserving modes, and also preserving the uids/gids if the 621 process is running as the super-user. 622 Uses *<em>tmp</em> as heap-allocated temporary space. 623 Returns 1 if it succeeds or 0 (and sets errno) if it fails. 624 </p> 625 626 <p> 627 <code> int hiercopy (char const *src, char const *dst) </code> <br /> 628 Same as above, using the <tt>satmp</tt> global stralloc as 629 heap-allocated temporary space. 630 </p> 631 632 <h3> Directory listing </h3> 633 634 <p> 635 <code> int sals (char const *dir, stralloc *sa, size_t *maxlen) </code> <br /> 636 Appends the base names of all the files (save <tt>.</tt> and <tt>..</tt>) in 637 <em>dir</em> to the stralloc <em>*sa</em>; each name is null-terminated. 638 On error, returns -1 and sets errno. On success, returns the number of files 639 it found, and writes to <em>*maxlen</em> the size of the largest file name 640 it found (0 for an empty directory). 641 </p> 642 643 <h3> Variable length wrappers around Single Unix calls </h3> 644 645 <p> 646 <code> int sarealpath (stralloc *sa, char const *path) </code> <br /> 647 Resolves <em>path</em> into a symlink-free absolute path, appending 648 the result to the *<em>sa</em> 649 <a href="stralloc.html">stralloc</a>. 650 Returns 0 if it succeeds and -1 (and sets errno) if it fails. 651 </p> 652 653 <p> 654 <code> int sarealpath_tmp (stralloc *sa, char const *path, stralloc *tmp) </code> <br /> 655 Resolves <em>path</em> into a symlink-free absolute path, appending 656 the result to *<em>sa</em>. Uses *<em>tmp</em> as heap-allocated 657 temporary space. 658 Returns 0 if it succeeds and -1 (and sets errno) if it fails. 659 </p> 660 661 <p> 662 <code> int sabasename (stralloc *sa, char const *s, size_t len) </code> <br /> 663 Appends the basename of filename <em>s</em> (of length <em>len</em>) 664 to *<em>sa</em>. 665 Returns 1 if it succeeds and 0 (and sets errno) if it fails. 666 </p> 667 668 <p> 669 <code> int sadirname (stralloc *sa, char const *s, size_t len) </code> <br /> 670 Appends the dirname of filename <em>s</em> (of length <em>len</em>) 671 to *<em>sa</em>. 672 Returns 1 if it succeeds and 0 (and sets errno) if it fails. 673 </p> 674 675 <p> 676 <code> int sagetcwd (stralloc *sa) </code> <br /> 677 Appends the current working directory to *<em>sa</em>. 678 Returns 0 if it succeeds and -1 (and sets errno) if it fails. 679 </p> 680 681 <p> 682 <code> int sareadlink (stralloc *sa, char const *link) </code> <br /> 683 Appends the contents of symbolic link <em>link</em> to *<em>sa</em>. 684 Returns 0 if it succeeds and -1 (and sets errno) if it fails. 685 </p> 686 687 <p> 688 <code> int sagethostname (stralloc *sa) </code> <br /> 689 Appends the machine's hostname to *<em>sa</em>. 690 Returns 0 if it succeeds and -1 (and sets errno) if it fails. 691 </p> 692 693 <h3> Temporization </h3> 694 695 <p> 696 <code> void deepsleepuntil (tain const *deadline, tain *stamp) </code> <br /> 697 Sleeps until the absolute time represented by the 698 <a href="tai.html">tain</a> *<em>deadline</em>. *<em>stamp</em> 699 must contain the current time. When the function returns, *<em>stamp</em> 700 has been updated to reflect the new current time. 701 </p> 702 703 <p> 704 <code> void deepsleep (unsigned int n) </code> <br /> 705 Sleeps <em>n</em> seconds. Signals received during that time are handled, 706 but <em>do not</em> interrupt the sleep. 707 </p> 708 709 <p> 710 <code> void deepmillisleep (unsigned long n) </code> <br /> 711 Sleeps <em>n</em> milliseconds. Signals received during that time are handled, 712 but <em>do not</em> interrupt the sleep. 713 </p> 714 715 <h3> Miscellaneous functions </h3> 716 717 <p> 718 <code> size_t path_canonicalize (char *out, char const *in, int check) </code> <br /> 719 Writes into <em>out</em> the canonical form of the Unix path given in 720 <em>in</em>. The <em>out</em> array must be preallocated with at least 721 <tt>strlen(in)+2</tt> bytes. Returns the length of the <em>out</em> path, without 722 counting the terminating null byte. If <em>check</em> is nonzero, <em>in</em> is tested 723 for every <tt>foobar/..</tt> element, and the function returns 0, and sets errno 724 appropriately, if <tt>foobar</tt> is not a valid directory; in that case, <em>out</em> 725 contains the problematic path. 726 </p> 727 728 </body> 729 </html>