From c853b8b668668105c08cb284352247854742dc0e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fredrik=20H=C3=BCbinette=20=28Hubbe=29?= <hubbe@hubbe.net>
Date: Tue, 10 Dec 1996 17:26:25 -0800
Subject: [PATCH] more documentation on internals added
Rev: doc/internal/low_level/hashmem:1.1
Rev: doc/internal/low_level/init_memsearch:1.1
Rev: doc/internal/low_level/low_level:1.1
Rev: doc/internal/low_level/memory_search:1.1
Rev: doc/internal/low_level/reorder:1.1
Rev: doc/internal/low_level/set_close_on_exec:1.1
Rev: doc/internal/low_level/set_nonblocking:1.1
Rev: doc/internal/low_level/set_read_callback:1.1
Rev: doc/internal/low_level/set_write_callback:1.1
Rev: doc/internal/low_level/xalloc:1.1
Rev: doc/internal/pike/SETJMP:1.1
Rev: doc/internal/pike/SET_ONERROR:1.1
Rev: doc/internal/pike/UNSETJMP:1.1
Rev: doc/internal/pike/UNSET_ONERROR:1.1
Rev: doc/internal/pike/error:1.2
Rev: doc/internal/pike/throw:1.1
---
doc/internal/low_level/hashmem | 16 ++++++++
doc/internal/low_level/init_memsearch | 28 +++++++++++++
doc/internal/low_level/low_level | 9 +++++
doc/internal/low_level/memory_search | 23 +++++++++++
doc/internal/low_level/reorder | 22 ++++++++++
doc/internal/low_level/set_close_on_exec | 18 +++++++++
doc/internal/low_level/set_nonblocking | 20 +++++++++
doc/internal/low_level/set_read_callback | 24 +++++++++++
doc/internal/low_level/set_write_callback | 24 +++++++++++
doc/internal/low_level/xalloc | 18 +++++++++
doc/internal/pike/SETJMP | 49 +++++++++++++++++++++++
doc/internal/pike/SET_ONERROR | 38 ++++++++++++++++++
doc/internal/pike/UNSETJMP | 9 +++++
doc/internal/pike/UNSET_ONERROR | 9 +++++
doc/internal/pike/error | 3 ++
doc/internal/pike/throw | 20 +++++++++
16 files changed, 330 insertions(+)
create mode 100644 doc/internal/low_level/hashmem
create mode 100644 doc/internal/low_level/init_memsearch
create mode 100644 doc/internal/low_level/low_level
create mode 100644 doc/internal/low_level/memory_search
create mode 100644 doc/internal/low_level/reorder
create mode 100644 doc/internal/low_level/set_close_on_exec
create mode 100644 doc/internal/low_level/set_nonblocking
create mode 100644 doc/internal/low_level/set_read_callback
create mode 100644 doc/internal/low_level/set_write_callback
create mode 100644 doc/internal/low_level/xalloc
create mode 100644 doc/internal/pike/SETJMP
create mode 100644 doc/internal/pike/SET_ONERROR
create mode 100644 doc/internal/pike/UNSETJMP
create mode 100644 doc/internal/pike/UNSET_ONERROR
create mode 100644 doc/internal/pike/throw
diff --git a/doc/internal/low_level/hashmem b/doc/internal/low_level/hashmem
new file mode 100644
index 0000000000..f3818b0286
--- /dev/null
+++ b/doc/internal/low_level/hashmem
@@ -0,0 +1,16 @@
+NAME
+ hashmem - hash a memory region
+
+SYNTAX
+ #include "memory.h"
+
+ unsigned INT32 hashmem(const unsigned char *a,INT32 len,INT32 mlen);
+
+DESCRIPTION
+ This function looks at the memory region beginning at 'a' and is 'len'
+ bytes long and returns a hash value depending on the bytes in that
+ region. The argument 'mlen' is how many bytes it should actually look
+ at, larger mlen gives better values but slower hashing.
+
+KEYWORDS
+ low_level
diff --git a/doc/internal/low_level/init_memsearch b/doc/internal/low_level/init_memsearch
new file mode 100644
index 0000000000..d85edd37ed
--- /dev/null
+++ b/doc/internal/low_level/init_memsearch
@@ -0,0 +1,28 @@
+NAME
+ init_memsearch - initialize a memory search struct
+
+SYNTAX
+ #include "memory.h"
+
+ void init_memsearch(struct mem_searcher *s,
+ char *needle,
+ SIZE_T needlelen,
+ SIZE_T max_haystacklen);
+
+DESCRIPTION
+ This function initializes a struct mem_searcher to be used with
+ the function memory_search. 'needle' is the byte sequence to
+ search for, and needlelen is how many bytes long the 'needle' is.
+ The argument 'max_haystacklen' is an approximation of how much
+ this memory searcher will be used. More time will be spent optimizing
+ the memory searcher struct if max_haystacklen is large.
+
+NOTA BENE
+ The needle is not copied by this function. It must still be available
+ when memory_search is called.
+
+KEYWORDS
+ low_level
+
+SEE ALSO
+ memory_search
\ No newline at end of file
diff --git a/doc/internal/low_level/low_level b/doc/internal/low_level/low_level
new file mode 100644
index 0000000000..768e9f3c41
--- /dev/null
+++ b/doc/internal/low_level/low_level
@@ -0,0 +1,9 @@
+NAME
+ low_level - low level routines supplied by pike
+
+DESCRIPTIONS
+ These functions are here to help you write fast and portable modules.
+ Pike itself also uses them for the same purpose.
+
+KEYWORDS
+ internals
diff --git a/doc/internal/low_level/memory_search b/doc/internal/low_level/memory_search
new file mode 100644
index 0000000000..94fa2d9ce7
--- /dev/null
+++ b/doc/internal/low_level/memory_search
@@ -0,0 +1,23 @@
+NAME
+ memory_search - search memory for a sequence of bytes
+
+SYNTAX
+ #include "memory.h"
+
+ char *memory_search(struct mem_searcher *s,
+ char *haystack,
+ SIZE_T haystacklen);
+
+DESCRIPTION
+ This function searches through a memory region (called 'haystack')
+ for a sequence of bytes (called 'needle'). If found, a pointer to
+ the first occurance of 'needle' in 'haystack' is returned. The needle
+ is given by calling init_memsearch to initialize a struct mem_searcher
+ that can then be used with this function.
+
+KEYWORDS
+ low_level
+
+SEE ALSO
+ init_memsearch
+
diff --git a/doc/internal/low_level/reorder b/doc/internal/low_level/reorder
new file mode 100644
index 0000000000..d208424b62
--- /dev/null
+++ b/doc/internal/low_level/reorder
@@ -0,0 +1,22 @@
+NAME
+ reorder - re-order an array of memory blocks
+
+SYNTAX
+ #include "memory.h"
+
+ void reorder(char *memory, INT32 nitems, INT32 size,INT32 *order);
+
+DESCRIPTION
+ This function takes an array of memory blocks and re-organizes them
+ according to the argument 'order'. 'nitems' tells how many memory
+ blocks there are, and 'size' tells how big they are in bytes.
+ 'order' is simply an array of INT32 of size 'nitems' in which each
+ int tells which memory block from 'memory' should be placed in that
+ position. In pseudo code, this could be written as:
+
+ mem_copy=copy_memory(memory);
+ for(int e=0;e<nitems;e++)
+ memory[e]=mem_copy[order[e]];
+
+KEYWORDS
+ low_level
diff --git a/doc/internal/low_level/set_close_on_exec b/doc/internal/low_level/set_close_on_exec
new file mode 100644
index 0000000000..bc08afe115
--- /dev/null
+++ b/doc/internal/low_level/set_close_on_exec
@@ -0,0 +1,18 @@
+NAME
+ set_close_on_exec - set the close-on-exec flag on a filedescriptor
+
+SYNTAX
+ #include "fd_control.h"
+
+ void set_close_on_exec(int fd, int onoff)
+
+DESCRIPTION
+ This function sets the close-on-exec flag on a filedescriptor. If
+ onoff is true, the filedescriptor will be closed whenever an exec()
+ is executed. If it is false, the fildescriptor will remain open.
+
+KEYWORDS
+ low_level
+
+SEE ALSO
+ set_nonblocking
diff --git a/doc/internal/low_level/set_nonblocking b/doc/internal/low_level/set_nonblocking
new file mode 100644
index 0000000000..86767100a3
--- /dev/null
+++ b/doc/internal/low_level/set_nonblocking
@@ -0,0 +1,20 @@
+NAME
+ set_nonblocking - set a filedescriptor nonblocking
+
+SYNTAX
+ #include "fd_control.h"
+
+ void set_nonblocking(int fd, int onoff)
+
+DESCRIPTION
+ This function sets a filedescriptor in nonblocking mode. Nonblocking
+ mode means that any read() or write() exits insteads of waits when
+ no more data can be read/written immediately. If 'onoff' is true,
+ the fd will be set to nonblocking, otherwise it will be set to
+ blocking mode.
+
+KEYWORDS
+ low_level
+
+SEE ALSO
+ set_close_on_exec
diff --git a/doc/internal/low_level/set_read_callback b/doc/internal/low_level/set_read_callback
new file mode 100644
index 0000000000..3eaee90ab5
--- /dev/null
+++ b/doc/internal/low_level/set_read_callback
@@ -0,0 +1,24 @@
+NAME
+ set_read_callback - set 'data available' callback
+
+SYNTAX
+ #include "backend.h"
+
+ void set_read_callback(int fd,file_callback cb,void *data);
+
+DESCRIPTION
+ This function sets what function should be called when there is
+ more data to be read from 'fd'. The 'file_callback' should be a
+ function like this:
+
+ void file_callback(int fd, void *data);
+
+ The arguments are the same as sent to set_read_callback().
+ To disable the read callback, call set_read_callback again with
+ cb and data equal to zero.
+
+KEYWORDS
+ low_level
+
+SEE ALSO
+ set_write_callback, set_nonblocking
diff --git a/doc/internal/low_level/set_write_callback b/doc/internal/low_level/set_write_callback
new file mode 100644
index 0000000000..21fbca0766
--- /dev/null
+++ b/doc/internal/low_level/set_write_callback
@@ -0,0 +1,24 @@
+NAME
+ set_read_callback - set 'buffer available' callback
+
+SYNTAX
+ #include "backend.h"
+
+ void set_write_callback(int fd,file_callback cb,void *data);
+
+DESCRIPTION
+ This function sets what function should be called when there is
+ time to write more data to 'fd'. The 'file_callback' should be a
+ function like this:
+
+ void file_callback(int fd, void *data);
+
+ The arguments are the same as sent to set_write_callback().
+ To disable the write callback, call set_write_callback again with
+ cb and data equal to zero.
+
+KEYWORDS
+ low_level
+
+SEE ALSO
+ set_read_callback, set_nonblocking
diff --git a/doc/internal/low_level/xalloc b/doc/internal/low_level/xalloc
new file mode 100644
index 0000000000..7fe8cf299c
--- /dev/null
+++ b/doc/internal/low_level/xalloc
@@ -0,0 +1,18 @@
+NAME
+ xalloc - fail-safe memory allocation
+
+SYNTAX
+ #include "memory.h"
+
+ char *xalloc(long size);
+
+DESCRIPTION
+ This function works exactly like the malloc() function, it will
+ never return NULL. Instead it will try to free up any pike resources
+ that are not needed any longer and try again. If that doesn't work
+ either it will call fatal("out of memory\n"); and Pike will dump core.
+ This type of error handling makes it easier to code, but is not
+ always what you want.
+
+KEYWORDS
+ low_level
diff --git a/doc/internal/pike/SETJMP b/doc/internal/pike/SETJMP
new file mode 100644
index 0000000000..6283a08c64
--- /dev/null
+++ b/doc/internal/pike/SETJMP
@@ -0,0 +1,49 @@
+NAME
+ SETJMP - catch errors
+
+SYNTAX
+ #include "error.h"
+
+ int SETJMP(JMP_BUF buf);
+
+DESCRIPTION
+ These macros are wrappers to the setjmp/longjmp routines with some
+ added support for cleaning up the Pike stack and other things that
+ might need freeing. What SETJUMP does is that it lets you catch
+ Pike errors much like the Pike function catch(). When called,
+ SETJMP returns zero, so the 'failsafe' code is executed. If an error
+ occurs in that code the processor will jump directly to the SETJMP
+ again and it will return 'true'. Then the 'error' code will be
+ executed.
+
+NOTA BENE
+ SETJMP is a macro
+
+ 'buf' has to be a local variable
+
+ There are some limitations to how you can use local variables in the
+ same function as setjump/longjump. See setjup(3) for more details.
+
+EXAMPLE
+ #include "error.h"
+
+ void do_catch()
+ {
+ JMP_BUF buf;
+
+ if(SETJMP(buf)) {
+ /* An error / longjump occured */
+ } else {
+ /* Execute failsafe code here */
+ }
+
+ UNSETJMP(foo)
+ }
+
+
+
+KEYWORDS
+ internals
+
+SEE ALSO
+ throw, error, UNSETJMP, SET_ONERROR, UNSET_ONERROR
diff --git a/doc/internal/pike/SET_ONERROR b/doc/internal/pike/SET_ONERROR
new file mode 100644
index 0000000000..b49be06079
--- /dev/null
+++ b/doc/internal/pike/SET_ONERROR
@@ -0,0 +1,38 @@
+NAME
+ SET_ONERROR - call this function if an error occurs
+
+SYNTAX
+ #include "error.h"
+
+ void SET_ONERROR(ONERROR tmp, void (*func)(void *), void *arg);
+
+DESCRIPTION
+ This function sets an error handler to be called when an error
+ occurs. When an error occurs the function 'func' is called with
+ the argument 'arg'. The advantage of this method over using SETJMP
+ for cleanup handling is that this should be slightly faster and it
+ does not have problems with undefined local variables.
+
+NOTA BENE
+ SET_ONERROR is a macro
+
+ 'tmp' has to be a local variable.
+
+EXAMPLE
+ #include "error.h"
+ #include "memory.h"
+
+ void do_something()
+ {
+ ONERROR tmp;
+ char *mem=xalloc(4711);
+
+ SET_ONERROR(tmp, (void (*)(void *)) free, mem);
+
+ /* Do some code that might cause an Pike error */
+
+ UNSET_ONERROR(tmp);
+ }
+
+SEE ALSO
+ UNSET_ONERROR, error
diff --git a/doc/internal/pike/UNSETJMP b/doc/internal/pike/UNSETJMP
new file mode 100644
index 0000000000..64835503eb
--- /dev/null
+++ b/doc/internal/pike/UNSETJMP
@@ -0,0 +1,9 @@
+NAME
+ UNSETJMP - stop catching error
+
+DESCRIPTION
+ This macro cleans up after calling SETJMP. See the page for SETJMP
+ for more details.
+
+SEE ALSO
+ SETJMP
diff --git a/doc/internal/pike/UNSET_ONERROR b/doc/internal/pike/UNSET_ONERROR
new file mode 100644
index 0000000000..663bfd3340
--- /dev/null
+++ b/doc/internal/pike/UNSET_ONERROR
@@ -0,0 +1,9 @@
+NAME
+ UNSET_ONERROR - cleanup after an SET_ONERROR
+
+DESCRIPTION
+ This function cleans up after a SET_ONERROR call.
+ See SET_ONERROR for more details.
+
+SEE ALSO
+ SET_ONERROR, SETJMP
diff --git a/doc/internal/pike/error b/doc/internal/pike/error
index 158b687edd..47dcea7dca 100644
--- a/doc/internal/pike/error
+++ b/doc/internal/pike/error
@@ -16,3 +16,6 @@ DESCRIPTION
KEYWORDS
internals
+
+SEE ALSO
+ SET_ONERROR, fatal, throw
diff --git a/doc/internal/pike/throw b/doc/internal/pike/throw
new file mode 100644
index 0000000000..e5ee768eab
--- /dev/null
+++ b/doc/internal/pike/throw
@@ -0,0 +1,20 @@
+NAME
+ throw - throw an exception
+
+SYNTAX
+ #include "error.h"
+
+ int throw(void);
+
+DESCRIPTION
+ This function calls longjmp and does all the cleanup and popping
+ the Pike stack etc. etc. This function does not setup any error
+ message or backtrace like error() does. error() calls this function
+ after doing all that. Since this function calls longjmp, it does
+ not return. See SETJMP for more details.
+
+KEYWORDS
+ internals
+
+SEE ALSO
+ SETJMP, error
--
GitLab