1 files changed, 185 insertions, 0 deletions
diff --git a/man/buffer.3 b/man/buffer.3
new file mode 100644
index 0000000..2d4d0d2
--- /dev/null
+++ b/man/buffer.3
@@ -0,0 +1,185 @@
+.TH buffer 3
+.SH NAME
+buffer \- generic read/write buffering
+.SH SYNTAX
+.B #include \(dqbuffer.h\(dq
+
+buffer* buffer_0;   /* like stdio's stdin */
+.br
+buffer* buffer_1;   /* like stdio's stdout */
+.br
+buffer* buffer_2;   /* like stdio's stderr */
+
+void \fBbuffer_init\fR(buffer &\fIb\fR,ssize_t (*\fIop\fR)(int,char *,size_t),
+                int \fIfd\fR, char *\fIy\fR, size_t \fIylen\fR);
+.br
+ssize_t \fBbuffer_get\fP(buffer *\fIb\fR,char *\fIx\fR,size_t \fIlen\fR);
+
+int \fBbuffer_put\fP(buffer *\fIb\fR,const char *\fIx\fR,size_t \fIlen\fR);
+.br
+int \fBbuffer_puts\fP(buffer *\fIb\fR,const char *\fIx\fR);
+.br
+int \fBbuffer_putalign\fP(buffer *\fIb\fR,char *\fIx\fR,unsigned int \fIlen\fR);
+.br
+int \fBbuffer_putsalign\fP(buffer *\fIb\fR,char *\fIx\fR);
+
+int \fBbuffer_putflush\fP(buffer *\fIb\fR,char *\fIx\fR,unsigned int \fIlen\fR);
+.br
+int \fBbuffer_putsflush\fP(buffer *\fIb\fR,char *\fIx\fR);
+
+int \fBbuffer_flush\fP(buffer *\fIb\fR);
+.br
+int \fBbuffer_copy\fP(buffer *\fIbo\fR,buffer *\fIbi\fR);
+
+int \fBbuffer_unixread\fP(int \fIfd\fR,char *\fIbuf\fR,size_t \fIlen\fR);
+.br
+int \fBbuffer_unixwrite\fP(int \fIfd\fR,char *\fIbuf\fR,size_t \fIlen\fR);
+.SH DESCRIPTION
+.B buffer.h 
+describes a generic buffer interface that can be used for
+read and write buffering. Buffers must be initialized with
+\fBbuffer_init\fR.
+
+A buffer can only be used for reading or writing at the same time, not
+both.
+
+Unlike 
+.BR stdio ,
+these write buffers are not flushed automatically at
+program termination; you must manually call \fBbuffer_flush\fR,
+\fBbuffer_putflush\fR, or \fBbuffer_putsflush\fR.
+
+.B buffer_init 
+prepares \fIb\fR to store a string in \fIy\fR[0], \fIy\fR[1], ...,
+\fIy\fR[\fIylen\fR-1].  Initially the string is empty.
+
+.B buffer_init 
+also prepares \fIb\fR to use the read/write operation specified by
+\fIop\fR and \fIfd\fR.
+
+You can use
+
+  buffer \fIb\fR = BUFFER_INIT(\fIop\fR,\fIfd\fR,\fIy\fR,\fIylen\fR);
+
+to initialize \fIb\fR statically if \fIop\fR, \fIfd\fR, \fIy\fR, and \fIylen\fR
+are compile-time constants.
+
+You can call 
+.B buffer_init 
+again at any time. Note that this discards the currently buffered string.
+
+.B buffer_get 
+copies data to \fIx\fR[0], \fIx\fR[1], ...,
+\fIx\fR[\fIlen\fR-1] from the beginning of a string stored in
+preallocated space; removes these \fIlen\fR bytes from the string; and
+returns \fIlen\fR.
+
+If, however, the string has fewer than \fIlen\fR (but more than 0)
+bytes, 
+.I buffer_get 
+copies only that many bytes, and returns that number.
+
+If the string is empty, 
+.B buffer_get 
+first uses a \fBread operation\fR to
+feed data into the string. The \fBread operation\fR may indicate end of
+input.
+
+The preallocated space and the \fBread operation\fR are specified by
+\fIb\fR. You must initialize \fBb\fR using 
+.B buffer_init 
+before calling
+.B buffer_get 
+(or use the pre-initialized \fIbuffer_0\fR).
+
+.B buffer_put 
+writes \fIlen\fR bytes from \fIx\fR to \fIb\fR.
+
+The difference to 
+.B buffer_putalign 
+is that, when there isn't enough space
+for new data, 
+.B buffer_put 
+calls 
+.B buffer_flush 
+before copying any data, while 
+.B buffer_putalign 
+fills all available space with data before calling
+.B buffer_flush.
+
+.B buffer_copy
+copies one buffer to other one. 
+The output buffer needs to have at least the 
+preallocated size of the input buffer.
+.B buffer_unixread
+and
+.B buffer_unixwrite
+perform the same operation like standard Unix
+.B read
+or 
+.BR write.
+.SH MACROS
+Apart from this basic usage, some helpful macro 
+definitions are provided:
+.B BUFFER_INIT(op,fd,buf,len)
+uses 
+.I op
+function to operate (read/write) on
+.I buf
+with 
+.I len 
+to file descriptor
+.IR fd .
+.B buffer_GETC(buf,c) 
+returns the upmost position of character
+.I c
+within buffer
+.I buf 
+or 0.
+.B buffer_PUTC(buf,c)
+adds character
+.I c
+to buffer
+.IR buf.
+.SH EXAMPLE
+  #include <buffer.h>
+  #include <open.h>
+
+  char buf[BUFFER_INSIZE]; // defined in buffer.h
+  int fd = open_read("/etc/services");
+  buffer input;
+
+  if (fd >= 0) {
+    char x;
+    buffer_init(&input,read,fd,buf,sizeof buf);
+    while (buffer_get(&input,&x,1) == 1) {
+      buffer_put(buffer_1,&x,1);
+      if (x == '\\n') break;
+    }
+    buffer_flush(buffer_1);
+  }
+.SH "RETURN CODES"
+.B buffer_put 
+and 
+.B buffer_get
+return
+.I 0 
+if everything was fine, 
+.IR -1 ,
+on error (setting \fIerrno\fR).
+.B buffer_copy
+returns
+.IR -2 ,
+if the input buffer can't be read, and
+.IR -3 ,
+if the data can't successfully copied 
+to the output buffer. On success
+.B buffer_copy 
+returns 
+.IR 0 .
+.SH "REFERENCES"
+https://cr.yp.to/lib/buffer_get.html
+
+https://cr.yp.to/lib/buffer_put.html
+.SH "SEE ALSO"
+stdio(3)