| | 1 | .\" -*-nroff-*- |
| | 2 | .TH selbuf 3 "23 May 1999" "Straylight/Edgeware" "mLib utilities library" |
| | 3 | .SH NAME |
| | 4 | selbuf \- line-buffering input selector |
| | 5 | .\" @selbuf_enable |
| | 6 | .\" @selbuf_disable |
| | 7 | .\" @selbuf_setsize |
| | 8 | .\" @selbuf_init |
| | 9 | .\" @selbuf_destroy |
| | 10 | .SH SYNOPSIS |
| | 11 | .nf |
| | 12 | .B "#include <mLib/selbuf.h>" |
| | 13 | |
| | 14 | .BI "void selbuf_enable(selbuf *" b ); |
| | 15 | .BI "void selbuf_disable(selbuf *" b ); |
| | 16 | .BI "void selbuf_setsize(selbuf *" b ", size_t " sz ); |
| | 17 | .ds mT \fBvoid selbuf_init( |
| | 18 | .BI "\*(mTselbuf *" b ", sel_state *" s ", int " fd , |
| | 19 | .BI "\h'\w'\*(mT'u'lbuf_func *" func ", void *" p ); |
| | 20 | .BI "void selbuf_destroy(selbuf *" b ); |
| | 21 | .fi |
| | 22 | .SH DESCRIPTION |
| | 23 | The |
| | 24 | .B selbuf |
| | 25 | subsystem is a selector which integrates with the |
| | 26 | .BR sel (3) |
| | 27 | system for I/O multiplexing. It reads entire text lines from a file |
| | 28 | descriptor and passes them to a caller-defined function. It uses the |
| | 29 | line buffer described in |
| | 30 | .BR lbuf (3) |
| | 31 | to do its work: you should read about it in order to understand exactly |
| | 32 | what gets considered to be a line of text and what doesn't, and the |
| | 33 | exact rules about what your line handling function should and shouldn't |
| | 34 | do. |
| | 35 | .PP |
| | 36 | The data for a line selector is stored in an object of type |
| | 37 | .BR selbuf . |
| | 38 | This object must be allocated by the caller, and initialized using the |
| | 39 | .B selbuf_init |
| | 40 | function. This requires a fair few arguments: |
| | 41 | .TP |
| | 42 | .BI "selbuf *" b |
| | 43 | Pointer to the |
| | 44 | .B selbuf |
| | 45 | object to initialize. |
| | 46 | .TP |
| | 47 | .BI "sel_state *" s |
| | 48 | Pointer to a multiplexor object (type |
| | 49 | .BR sel_state ) |
| | 50 | to which this selector should be attached. See |
| | 51 | .BR sel (3) |
| | 52 | for more details about multiplexors, and how this whole system works. |
| | 53 | .TP |
| | 54 | .BI "int " fd |
| | 55 | The file descriptor of the stream the selector should read from. |
| | 56 | .TP |
| | 57 | .BI "lbuf_func *" func |
| | 58 | The |
| | 59 | .I "line handler" |
| | 60 | function. It is passed a pointer to each line read from the file (or |
| | 61 | null to indicate end-of-file), the length of the line, and an arbitrary |
| | 62 | pointer (the |
| | 63 | .I p |
| | 64 | argument to |
| | 65 | .B selbuf_init |
| | 66 | described below). For full details, see |
| | 67 | .BR lbuf (3). |
| | 68 | .TP |
| | 69 | .BI "void *" p |
| | 70 | A pointer argument passed to |
| | 71 | .I func |
| | 72 | for each line read from the file. Apart from this, the pointer is not |
| | 73 | used at all. |
| | 74 | .PP |
| | 75 | The |
| | 76 | .B selbuf |
| | 77 | selector is immediately active. Subsequent calls to |
| | 78 | .B sel_select |
| | 79 | on the same multiplexor will cause any complete lines read from the file |
| | 80 | to be passed to your handling function. This function can at any time |
| | 81 | call |
| | 82 | .B selbuf_disable |
| | 83 | to stop itself from being called any more. The selector is then |
| | 84 | disengaged from the I/O multiplexor and won't do anything until |
| | 85 | .B selbuf_enable |
| | 86 | is called. Note that |
| | 87 | .B selbuf_enable |
| | 88 | may well immediately start emitting complete lines of text which were |
| | 89 | queued up from the last I/O operation: it doesn't necessarily wait for |
| | 90 | the next |
| | 91 | .B sel_select |
| | 92 | call. |
| | 93 | .PP |
| | 94 | The line buffer has a finite amount of memory for reading strings. The |
| | 95 | size of this buffer is set by calling |
| | 96 | .B selbuf_setsize |
| | 97 | with the requested size. The default buffer size is 256 bytes. |
| | 98 | .PP |
| | 99 | When it's finished with, a line buffer selector must be destroyed by |
| | 100 | calling |
| | 101 | .BR selbuf_destroy . |
| | 102 | .SH "SEE ALSO" |
| | 103 | .BR lbuf (3), |
| | 104 | .BR sel (3), |
| | 105 | .BR mLib (3). |
| | 106 | .SH AUTHOR |
| | 107 | Mark Wooding, <mdw@distorted.org.uk> |
~mdw / mLib / blame_incremental