genwrite.html (3466B)
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 genwrite library interface</title> 7 <meta name="Description" content="skalibs: the genwrite library interface" /> 8 <meta name="Keywords" content="skalibs c unix genwrite buffer stralloc write 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>genwrite</tt> library interface </h1> 22 23 <p> 24 The following functions are declared in the <tt>skalibs/genwrite.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>genwrite</tt> is syntactic sugar to help write functions that might 32 want to write either to memory or to a file descriptor. 33 </p> 34 35 <p> 36 Writing to memory is achieved via appending to a 37 <a href="stralloc.html">stralloc</a>; writing to a file descriptor is achieved 38 via appending to a <a href="buffer.html">buffer</a> or a 39 <a href="bufalloc.html">bufalloc</a>. 40 </p> 41 42 <h2> Usage </h2> 43 44 <p> 45 A <tt>genwrite_t</tt> structure contains a pointer to a function that writes 46 stuff to the target without flushing it 47 (which can be <tt>genwrite_put_stralloc</tt>, <tt>genwrite_put_buffer</tt>, 48 <tt>genwrite_put_bufalloc</tt> or any 49 compatible user-defined function) in <tt>.put</tt>, a pointer to a function 50 that flushes the target (which can be <tt>genwrite_flush_stralloc</tt>, 51 <tt>genwrite_flush_buffer</tt>, <tt>genwrite_flush_bufalloc</tt> or any 52 compatible user-defined function) in <tt>.flush</tt>, and a pointer to 53 the target writing structure in <tt>.target</tt>. 54 </p> 55 56 <p> 57 Users should define a <tt>genwrite_t</tt> first, using the provided functions, 58 and give applications a pointer <tt>gp</tt> to this structure. To write <em>len</em> 59 characters at position <em>s</em> to the target, the application should then call 60 <code>(*gp->put)(gp->target, s, len)</code>. When it is done writing, the 61 application should call <code>(*gp->flush)(gp->target)</code> to flush the 62 output. 63 </p> 64 65 <p> 66 <tt>genwrite_stdout</tt> and <tt>genwrite_stderr</tt> are predefined; they 67 write to <tt>buffer_1</tt> and <tt>buffer_2</tt> respectively. 68 </p> 69 70 <h2> Macros </h2> 71 72 <p> 73 <code> GENWRITE_STRALLOC_INIT(sa) </code> <br /> 74 Declares a <tt>genwrite_t</tt> writing to the stralloc *<em>sa</em>. 75 </p> 76 77 <p> 78 <code> GENWRITE_BUFFER_INIT(b) </code> <br /> 79 Declares a <tt>genwrite_t</tt> writing to the buffer *<em>b</em>. Use 80 of such a buffer might interact badly with nonblocking I/O. 81 </p> 82 83 <p> 84 <code> GENWRITE_BUFALLOC_INIT(ba) </code> <br /> 85 Declares a <tt>genwrite_t</tt> writing to the bufalloc *<em>ba</em>. 86 </p> 87 88 <h2> Note </h2> 89 90 <p> 91 Object-oriented programming in C is inefficient and cumbersome. It is 92 usually possible to avoid it in Unix system programming, because Unix 93 primitives are often generic enough. Unfortunately, it is not the case 94 here: Unix does not provide an abstraction representing either a file 95 or a memory buffer. So an object-oriented approach is unavoidable. 96 </p> 97 98 </body> 99 </html>