.B conn_init
with a fairly large number of arguments:
.TP
-.I c
+.BI "conn *" c
Pointer to
.B conn
object which needs to be initialized.
.TP
-.I s
+.BI "sel_state *" s
Pointer to a multiplexor object (type
.BR sel_state )
to which this selector should be attached. See
.BR sel (3)
for more details about multiplexors, and how this whole system works.
.TP
-.I fd
+.BI "int " fd
File descriptor for the socket you want to connect. This becomes the
`property' of the
.B conn
selector until the connection attempt finishes. For example, if there's
an error, the descriptor will be closed.
.TP
-.I dst
+.BI "struct sockaddr *" dst
Pointer to destination socket address for the connection. Make sure
that the address has the right family.
.TP
-.I dsz
+.BI "int " dsz
Size of the destination socket address.
.TP
-.I func
+.BI "void (*" func ")(int " fd ", void *" p )
A function to call when the connection is complete. It is passed the
file descriptor of the connected socket, and the pointer passed
to
.B errno
value is set appropriately.
.TP
-.I p
+.BI "void *" p
An arbitrary pointer whose value is passed to the handler function when
the connection finishes.
.PP
.B hash_table
structure. It contains two members:
.TP
-.B mask
+.B "uint32 mask"
The current bitmask to be applied to hashes. This is one less than the
current number of bins in the hashtable, and is applied to hash values
in order to decide which bin an item should be in.
.TP
-.B v
+.B "hash_base **v"
The bin vector. It is an array of pointers to hashtable items.
.PP
A hashtable item consists of a
only contains the bare minimum of information needed to maintain the
hashtable at a low level. It contains the following members:
.TP
-.B next
+.B "hash_base *next"
Pointer to the next item in the bin list. The final item has a null
.B next
pointer. The entry in the bin vector is null if the bin list is empty.
It is up to the high-level implementation to insert items into the list.
.TP
-.B hash
+.B "uint32 hash"
The hash for this item. This must be the full 32-bit hash for the
current item. It is used during hashtable expansion to determine which
bin an item should be moved to.
.B lbuf_init
initializes a line buffer ready for use. It is given three arguments:
.TP
-.I b
+.BI "lbuf *" b
A pointer to the block of memory to use for the line buffer. This is
all the memory the line buffer requires.
.TP
-.I func
+.BI "void (*" func ")(char *" s ", void *" p )
The
.I line-handler
function to which the line buffer should pass completed lines of text.
.TP
-.I p
+.BI "void *" p
A pointer argument to be passed to the function when a completed line of
text arrives.
.PP
is called to examine the new data and break it into text lines. This is
given three arguments:
.TP
-.I b
+.BI "lbuf *" b
The address of the line buffer.
.TP
-.I p
+.BI "char *" p
The address at which the new data has been written. This must be the
base address returned from
.BR lbuf_free .
.TP
-.I len
+.BI "size_t " len
The number of bytes which have been written to the buffer.
.PP
The
.PP
The data block is a structure containing at least the following members:
.TP
-.B arg
+.B "char *arg"
Pointer to the argument of the current option, or null. Argument
strings persist for as long as the underlying command line argument
array
.I argv
does, so it's usually safe just to remember the pointer.
.TP
-.B opt
+.B "int opt"
Value of the current option
.TP
-.B int
+.B "int ind"
Must be initialized to 0 before the first call to
.BR mdwopt .
After the last call, it is the index into
.I argv
of the first nonoption argument.
.TP
-.B err
+.B "int err"
Set to nonzero to allow
.B mdwopt
to emit error messages about illegal option syntax. (This would be a
.B getopt
compatibility.)
.TP
-.B prog
+.B "char *prog"
Contains the program's name, stripped of any path prefix. This is an
obsolete feature: the
.BR quis (3)
.BR "struct option" ,
which contains the following members (in order):
.TP
-.B name
+.B "const char *name"
Pointer to the option's name.
.TP
-.B has_arg
+.B "int has_arg"
A flags word describing the option. (The name is historical.)
.TP
-.B flag
+.B "int *flag"
Address of the flag variable to use when this option is matched.
.TP
-.B val
+.B "int val"
Value to store or return when this option is matched.
.PP
The table is terminated by an entry whose
.B selbuf_init
function. This requires a fair few arguments:
.TP
-.I b
+.BI "selbuf *" b
Pointer to the
.B selbuf
object to initialize.
.TP
-.I s
+.BI "sel_state *" s
Pointer to a multiplexor object (type
.BR sel_state )
to which this selector should be attached. See
.BR sel (3)
for more details about multiplexors, and how this whole system works.
.TP
-.I fd
+.BI "int " fd
The file descriptor of the stream the selector should read from.
.TP
-.I func
+.BI "void (*" func ")(char *" s ", void *" p )
The
.I "line handler"
function. It is passed a pointer to each line read from the file (or
.B selbuf_init
described below).
.TP
-.I p
+.BI "void *" p
A pointer argument passed to
.I func
for each line read from the file. Apart from this, the pointer is not
divides a string into whitespace-separated words. The arguments are as
follows:
.TP
-.I p
+.BI "char *" p
The address of the string to split. The string is modified by having
null terminators written after each word extracted.
.TP
-.I v
+.BI "char *" v []
The address of an array of pointers to characters. This array will be
filled in by
.BR str_split :
and so on. If there aren't enough words in the string, the remaining
array elements are filled with null pointers.
.TP
-.I c
+.BI "size_t " c
The maximum number of words to extract; also, the number of elements in
the array
.IR v .
.TP
-.I rest
+.BI "char **" rest
The address of a pointer in which to store the address of the remainder
of the string. Leading whitespace is removed from the remainder before
storing. If the remainder string is empty, a null pointer is stored
It does both lookup and creation, depending on its arguments. To do its
job, it needs to know the following bits of information:
.TP
-.I t
+.BI "sym_table *" t
A pointer to a symbol table to manipulate.
.TP
-.I n
+.BI "const char *" n
The address of the
.I key
to look up or create. Usually this will be a simple text string,
although it can actually be any arbitrary binary data.
.TP
-.I l
+.BI "long " l
The length of the key. If this is \-1,
.B sym_find
assumes that the key is a null-terminated string, and calculates its
length itself.
.TP
-.I sz
+.BI "size_t " sz
The size of the value block to allocate if the key could not be found.
If this is zero, no value is allocated, and a null pointer is returned
to indicate an unsuccessful lookup.
.TP
-.I f
+.BI "unsigned *" f
The address of a `found' flag to set. This is an output parameter. On
exit,
.B sym_find
.VE
The members of this structure are as follows:
.TP
-.I "name"
+.B "const char *name"
The name of the chunk described by this chunk definition, or null if
this is the termination marker.
.TP
-.I "test"
+.B "int (*test)(dstr dv[])"
The test function. It is passed an array of dynamic strings, one for
each field, and must return nonzero if the test succeeded or zero if the
test failed. On success, the function should not write anything to
stdout or stderr; on failure, a report of the test arguments should be
emitted to stderr.
.TP
-.I "f"
+.B "test_type *f[TEST_FIELDMAX]"
Definitions of the fields. This is an array of pointers to
.I "field types"
(see below), terminated by a null pointer.
} test_type;
.VE
The
-.I cvt
+.B cvt
member is a function called to read an input string stored in
-.I buf
+.B buf
and output internal-format data in the dynamic string
.IR d .
The testrig driver has already stripped of quotes and dealt with
backslash escapes.
The
-.I dump
+.B dump
member is called to write the internal-format data in dynamic string
.I d
to the
.B TV_CMP
is stolen from the
.B timercmp
-macro in the GNU C library. I don't know whether this macro is a GNU
-original, but it certainly doesn't seem to be portable. The
+macro in the GNU C library. This doesn't look like a GNU original,
+however; whatever, it doesn't seem to be very portable. The GNU
.B timercmp
macro had a warning attached to it that it wouldn't work for operators
like
~mdw / mLib / commitdiff