Update Doku aus Driversourcen
Change-Id: I455f0813b970151089b3dc1b8d9407eea323cdd1
diff --git a/doc/LPC/arrays b/doc/LPC/arrays
index 883dddb..6dc4905 100644
--- a/doc/LPC/arrays
+++ b/doc/LPC/arrays
@@ -2,9 +2,14 @@
arrays
DESCRIPTION
- There is support for arrays. The arrays can't be declared, but
- should be allocated dynamically with the function 'allocate()'
- (see efun/allocate).
+ There is support for arrays. Arrays can be declared with the
+ type of its members appended by a star (e.g. string* for an
+ array with string elements). But this declaration is not
+ sufficient to actually create an array at runtime, as all
+ variables (even arrays) are initialized with 0 which is not
+ a valid array. Arrays must either be allocated dynamically
+ with the function 'allocate()' (see efun/allocate), or
+ created with the ({}) array constructor.
Arrays are stored by reference, so all assignments of whole
arrays will just copy the address. The array will be
diff --git a/doc/LPC/closure_guide b/doc/LPC/closure_guide
index 438ba46..b2538fe 100644
--- a/doc/LPC/closure_guide
+++ b/doc/LPC/closure_guide
@@ -390,7 +390,7 @@
// with 0 now.
({ (#'do),
({ (#'write),'i }), // give out i
- ({ (#'+=),'i,1 }) // increase i
+ ({ (#'+=),'i,1 }), // increase i
({ (#'<),'i,10 }), // condition: i < 10
42 // result is not interesting
})
@@ -427,7 +427,7 @@
lambda(0,({ (#'while),// loop
1, // condition is 1 ==> endles loop
42, // return value (which will never be used)
- ({ (#'write),"grin" })
+ ({ (#'write),"grin" }),
({ (#'?!), // ifnot
({ (#'random),10 }), // (random(10))
({ (#'return),100 }) // return 100;
diff --git a/doc/LPC/closures-example b/doc/LPC/closures-example
index f50fd35..fcc4e6d 100644
--- a/doc/LPC/closures-example
+++ b/doc/LPC/closures-example
@@ -102,7 +102,7 @@
map( filter(all_inventory(room), #'living)
, lambda( ({ 'liv })
- , ({'#, , ({#'=, 'hp, ({#'call_other, 'liv, "QueryHP" }) })
+ , ({#', , ({#'=, 'hp, ({#'call_other, 'liv, "QueryHP" }) })
, ({#'?, ({#'>, 'hp, 10 })
, ({#'call_other, 'liv, "SetHP"
, ({#'-, 'hp, 10 })
diff --git a/doc/LPC/ed2 b/doc/LPC/ed2
index 85d520e..22277b8 100644
--- a/doc/LPC/ed2
+++ b/doc/LPC/ed2
@@ -15,7 +15,7 @@
Any character can used instead of '/':
s!apa!bepa!g
- The 'g' specifies that all occurences of apa on this line are
+ The 'g' specifies that all occurrences of apa on this line are
changed to bepa.
The pattern that are supposed to be replaced, can be a regular
diff --git a/doc/LPC/escape b/doc/LPC/escape
index 8518749..ee99efa 100644
--- a/doc/LPC/escape
+++ b/doc/LPC/escape
@@ -35,21 +35,23 @@
The numeric escapes could be used to express a character directly
by its code in binary, octal, decimal or hexadecimal notation.
- \0b Beginning of binary notation
- \0o Beginning of octal notation
- \0x Beginning of hexadecimal notation
- \x Beginning of hexadecimal notation
+ \0b Beginning of binary notation
+ \0o Beginning of octal notation
+ \0x Beginning of hexadecimal notation
+ \x Beginning of hexadecimal notation
+ \u, \U Beginning of extended hexadecimal notation
A backslash followed by a digit ([0-9]) which does not map to one
of the above starts an escape in decimal notation.
A numeric escape terminates when N digits have been used up or
when the first character that is not a valid digit in that
- notation is encountered. N is 2 for hexadeximals, 3 for
- decimals and octals and 8 for binarys.
+ notation is encountered. N is 2 for hexadeximals with \0x and \x,
+ 3 for decimals and octals, 4 for hexadecimals with \u,
+ 8 for binarys and for hexadecimals with \U.
If the specified code is greater than 255 a warning is issued and
- the value modulo 256 is used.
+ the value modulo 256 is used (except for \u and \U).
EXAMPLES
Put a newline at the end of user output
diff --git a/doc/LPC/foreach b/doc/LPC/foreach
index 7e6060b..9e4df32 100644
--- a/doc/LPC/foreach
+++ b/doc/LPC/foreach
@@ -80,7 +80,7 @@
a = ({1, 2, 3})
foreach(x : a) { a[1..2] = ({4, 5}); write(x+" "); }
will write ("1 4 5 ").
- - operations which implicitely copy the array or struct (this
+ - operations which implicitly copy the array or struct (this
includes range assignments which change the size) don't
have an effect on the loop.
diff --git a/doc/LPC/inline-closures b/doc/LPC/inline-closures
index 3a2ecdd..ee7d0a1 100644
--- a/doc/LPC/inline-closures
+++ b/doc/LPC/inline-closures
@@ -43,7 +43,7 @@
But changes of the closure context will not reflect on the
local variable it was copied from and vice versa.
- In addition to the implicite context inherited from the
+ In addition to the implicit context inherited from the
defining function, additional context variables can be defined
in the closure:
@@ -64,7 +64,7 @@
{ return val * x; };
}
- These explicite context variables are useful when the closures
+ These explicit context variables are useful when the closures
needs to keep a state, or to improve performance:
mapping m = ...;
diff --git a/doc/LPC/modifiers b/doc/LPC/modifiers
index 0268105..7639741 100644
--- a/doc/LPC/modifiers
+++ b/doc/LPC/modifiers
@@ -172,7 +172,7 @@
(and 'static' for functions only) are allowed here.
The default visibility thus set affects only variables/functions with
- no explicite visibility:
+ no explicit visibility:
default private;
diff --git a/doc/LPC/operators b/doc/LPC/operators
index 18406a3..911007b 100644
--- a/doc/LPC/operators
+++ b/doc/LPC/operators
@@ -116,7 +116,7 @@
expr1 - expr2 Subtract 'expr2' from 'expr1'. Valid for
numbers, strings, arrays, mappings.
- For arrays and strings, all occurences of the
+ For arrays and strings, all occurrences of the
elements resp. characters in 'expr2' are removed
from 'expr1', and the result is returned.
For mapping, all occurances of elemens in 'expr1'
diff --git a/doc/LPC/pragma b/doc/LPC/pragma
index d26f326..21d4881 100644
--- a/doc/LPC/pragma
+++ b/doc/LPC/pragma
@@ -24,19 +24,32 @@
save_types: the declaration data is kept after compilation and
checked at runtime. This is important for type-safe
inheritance.
+ no_bytes_type: removes the keyword 'bytes', also 'string' then
+ denotes the type <string|bytes>.
+ bytes_type: reactivates the keyword 'bytes' and distinguishes
+ between the 'bytes' and 'string' type.
rtt_checks: runtime checks during execution of this program will be
- enabled. The interpreter will check for correct datatypes of
- arguments on function calls. (Later it will include checks
- upon assignments.)
+ enabled. The interpreter will check for correct datatypes in
+ the following circumstances:
+ - arguments on function calls,
+ - return values of functions,
+ - assignment to variables,
+ - restoration of values to variables or struct members.
Don't confuse this with strong/strict_types, they only
check at compile time.
strong_types/strict_types is seriously recommended.
This pragma implicitly enables save_types as well.
+ warn_rtt_checks: runtime checks are enabled, just like rtt_checks,
+ but errors will be shown as warnings only.
no_rtt_checks: disable runtime type checks for this program (default).
pedantic: Certain warnings are treated as errors:
- - failure to pass enough arguments to simul efuns
+ - failure to pass enough arguments to simul efuns
+ - type casts with no effect
+ - inconsistent declarations
+ - inconsistent overloads
+ - double inherits
sloppy: Turns off pedantic (the default).
range_check: Use of questionable ranges (ranges of negative sizes,
@@ -49,8 +62,8 @@
no_warn_deprecated: Turns off warn_deprecated.
warn_empty_casts: A cast of a value to its own type generates
- a warning (the default). Exception are casts to type
- 'mixed'.
+ a warning. Also casting a value of mixed/unknown type or
+ casting to mixed will generate a warning (the default).
no_warn_empty_casts: Turns off warn_empty_casts.
warn_missing_return: Warn if a value-returning function is missing
diff --git a/doc/LPC/structs b/doc/LPC/structs
index 217b0a6..0774e18 100644
--- a/doc/LPC/structs
+++ b/doc/LPC/structs
@@ -151,7 +151,7 @@
struct passed as first argument. The content of the template
struct is irrelevant, so an empty struct suffices. For
example, to create an instance of struct Foo:
-
+
({ #'(<, (<Foo>), 1, ({ 2 }), (<Bar>) })
The order of the member values is the order in which they
@@ -174,15 +174,14 @@
Support for structs is signaled by the macro __LPC_STRUCTS__.
- Since structs are tied to the program they are defined in,
- re-compiling a program creates new struct types which are
- in principle incompatible to the old ones. However, the LPC
- compiler checks if the newly compiled structs have the same
- structure as their older counterparts of the same name
- (and defining program). If the structures conform, the existing
- older struct types are used instead of the new ones. This way
- an accidental of for example /std/types.c doesn't break
- the whole mud.
+ Though structs are tied to the program the are defined in,
+ re-compiling a program doesn't make the struct types
+ incompatible. Even if the newly compiled struct has a
+ different structure it will be accepted by routines that
+ expect the old struct definition. When members disappeared
+ in the new struct definition, read access to those members
+ will return 0, write access to vanished members however
+ will result in a runtime error.
EXAMPLES
diff --git a/doc/LPC/types b/doc/LPC/types
index 903a1be..e104951 100644
--- a/doc/LPC/types
+++ b/doc/LPC/types
@@ -11,9 +11,9 @@
macros __INT_MIN__ and __INT_MAX__.
Integer values can be specified in decimal, in
- sedecimal when preceeded by '0x' (e.g. 0x11), binary
+ sedecimal when preceded by '0x' (e.g. 0x11), binary
when preceeded by '0b' (e.g. 0b00010001), octal when
- preceeded by '0o' (e.g. 0o21) and as character
+ preceded by '0o' (e.g. 0o21) and as character
yielding the charset value for the character as the number
to use (e.g. '0' yields 48 on ASCII machines).
@@ -60,19 +60,21 @@
\<LF> : ignored
\<LF><CR> : ignored
- \N : the character code N in decimal
- \0xN : the character code N in sedecimal
- \xN : the character code N in sedecimal
- \0oN : the character code N in octal
- \0bN : the character code N in binary
- \a : BEL (0x07)
- \b : Backspace (0x08)
- \t : Tab (0x09)
- \e : Escape (0x1b)
- \n : Newline (0x0a)
- \f : Formfeed (0x0c)
- \r : Carriage Return (0x0d)
- \" : The double quote (")
+ \N : the character code N in decimal
+ \0xN : the character code N in sedecimal
+ \xN : the character code N in sedecimal
+ \0oN : the character code N in octal
+ \0bN : the character code N in binary
+ \uNNNN : Unicode character N in sedicimal
+ \UNNNNNNNN: Unicode character N in sedicimal
+ \a : BEL (0x07)
+ \b : Backspace (0x08)
+ \t : Tab (0x09)
+ \e : Escape (0x1b)
+ \n : Newline (0x0a)
+ \f : Formfeed (0x0c)
+ \r : Carriage Return (0x0d)
+ \" : The double quote (")
\<other character>: the given character
Adjacent string literals are automatically
@@ -80,6 +82,18 @@
compiled. String literals joined with '+' are
concatenated by the LPC compiler as well.
+ o bytes Byte sequences are similar to strings. They offer
+ the same operations, but cannot be mixed with strings.
+
+ Byte sequence literals are written between double-quotes
+ prefixed with a 'b' (e.g. b""). Adjacent byte sequence
+ literals are automatically concatenated.
+
+ The text is allowed to consist of ASCII characters
+ (equivalent to bytes 0-127) and escape-sequences
+ just like strings, with the exception of the \u and \U
+ unicode escape sequences.
+
o object Pointer to an object. Objects are always passed by
reference.
diff --git a/doc/applied/__INIT b/doc/applied/__INIT
index dc56f6c..baf6b4c 100644
--- a/doc/applied/__INIT
+++ b/doc/applied/__INIT
@@ -3,7 +3,7 @@
DESCRIPTION
This function is constructed automagically by the parser at
- compiler, if the parser was compiled with #define
+ compile time, if the parser was compiled with #define
INITIALISATION__INIT. This function is not intended to be
defined by the lpc objects, and never to be called from lpc
objects. This man page is here just for completeness.
diff --git a/doc/applied/catch_msg b/doc/applied/catch_msg
index d244af4..c38cee0 100644
--- a/doc/applied/catch_msg
+++ b/doc/applied/catch_msg
@@ -2,10 +2,10 @@
void catch_msg(mixed *|struct|mapping|object msg, object obj)
DESCRIPTION
- When say(), tell_room() or tell_object() are used with an
+ When say(), tell_room() or tell_object() are used with a
non-string as message, the value will be passed to catch_msg()
in all living objects that can hear it, instead of writing to
- the user resp. sending to catch_tell(). This can be used to
+ the user resp. sending to catch_tell(). This can be used to
implement communication protocols between livings. The second
argument denotes the object that has sent the message.
diff --git a/doc/applied/catch_tell b/doc/applied/catch_tell
index 942a81a..48c6eeb 100644
--- a/doc/applied/catch_tell
+++ b/doc/applied/catch_tell
@@ -11,11 +11,11 @@
object's catch_tell() lfun, _if it has one_. If the receiver
(or one of its shadows) doesn't have that lfun, the text is sent
to the socket directly. Only messages sent by an interactive
- object to itself inside a catch_tell always written to the socket
- immediately.
+ object to itself inside a catch_tell are always written to the
+ socket immediately.
- This allows to filter and process text before it is written
- to a player.
+ This allows text to be filtered and processed before it is
+ written to a player.
SEE ALSO
enable_commands(E), say(E), tell_object(E), tell_room(E),
diff --git a/doc/applied/clean_up b/doc/applied/clean_up
new file mode 100644
index 0000000..ed066bf
--- /dev/null
+++ b/doc/applied/clean_up
@@ -0,0 +1,51 @@
+SYNOPSIS
+ int <lfun> (int refcount)
+ int <closure>(int ref, object ob)
+
+DESCRIPTION
+ The hook H_CLEAN_UP defines a lfun or a closure used to clean
+ up an object. In older drivers this was hardwired to the lfun
+ clean_up().
+
+ The function is applied by the driver when an object hasn't been
+ used for a long time, to give it a chance to self-destruct. The
+ refcount <ref> passed as argument will be 0 for clone objects,
+ 1 for a simple loaded object, and greater when the object is
+ cloned or inherited by some existing object. It is recommended
+ not to self_destruct the object when the reference count is
+ greater than one.
+
+ By convention, a refcount < 0 is used if some other object
+ asks the called object to clean_up.
+
+ If the function is a closure, the second argument <ob> is the
+ object to clean up.
+
+ If the hook specifies a non-existing lfun, or if the call
+ returns 0, no further attempt to clean up this object will be made.
+
+ Returning a non-zero value is only recommended when the reason
+ why the object can't self-destruct is likely to vanish without
+ the object being touched, that is, when no local function is
+ called in it, (and in compat mode also when the object is not
+ being moved around).
+
+ A typical mud configuration defines the time to wait for
+ clean_up() so long that you can assert reset() has been
+ called since the object has been touched last time.
+
+EXAMPLES
+ A clone of /std/drink defines clean_up() to self-destruct if
+ it is empty, not carried a living being and not touched for
+ a long time.
+
+ A room that inherits /std/room defines clean_up() to
+ self-destruct if it is neither inherited nor used as a
+ blueprint, is empty and was not entered for a long time.
+
+HISTORY
+ Before 3.2.1, the function was hardwired to the lfun clean_up().
+
+SEE ALSO
+ reset(A), heart_beat(A), call_out(E), destruct(E), remove(A),
+ hooks(C)
diff --git a/doc/applied/heart_beat b/doc/applied/heart_beat
index 9876b03..96abdee 100644
--- a/doc/applied/heart_beat
+++ b/doc/applied/heart_beat
@@ -18,9 +18,6 @@
The function this_player() will return this object, but only if
it is living. Otherwise, this_player() will return 0.
- The function will be called only if there is at least one interactive
- user in the game.
-
Note that error messages will be given to the current user
which will be the object itself or nobody.
diff --git a/doc/applied/id b/doc/applied/id
index bdb1fb2..c0ffd32 100644
--- a/doc/applied/id
+++ b/doc/applied/id
@@ -1,9 +1,9 @@
SYNOPSIS
- varargs int id(string str, int lvl);
+ int id(string str)
DESCRIPTION
Let the object identify itself. If str matches an id of the
- current object then return a none zero value.
+ current object then return a non-zero value.
This lfun is applied for the efun present().
@@ -14,4 +14,3 @@
SEE ALSO
present(E)
- id(L)
diff --git a/doc/applied/init b/doc/applied/init
index 17675da..4e8c46f 100644
--- a/doc/applied/init
+++ b/doc/applied/init
@@ -55,10 +55,10 @@
n2
If we now move another living object l3 into l1, the call
- suequence of the init() functions looks like this:
+ sequence of the init() functions looks like this:
l1->init() first init() of the destination will be called
- n1->init() now iterate throw the inventory of the destination
+ n1->init() now iterate through the inventory of the destination
l3->init()
l2->init()
n2->init()
diff --git a/doc/applied/query_weight b/doc/applied/query_weight
index 7d30b85..7a3ab92 100644
--- a/doc/applied/query_weight
+++ b/doc/applied/query_weight
@@ -4,7 +4,7 @@
DESCRIPTION
In compat mode this lfun is used by the efun transfer().
- Not that no set_weight() is required by the parser.
+ Note that no set_weight() is required by the parser.
HISTORY
Deprecated in LDMud 3.3 as transfer() has been deprecated.
diff --git a/doc/applied/remove b/doc/applied/remove
index bb732b2..48228ef 100644
--- a/doc/applied/remove
+++ b/doc/applied/remove
@@ -7,7 +7,7 @@
This lfun is not applied by the parser, but by other objects
to tell the current object to self-destruct. remove() should
- be supplied by the base classes of the library. Return 1 if
+ be supplied by the base classes of the library. Return 1 if
actually self-destructed, 0 otherwise.
An alternative way to ensure the housekeeping on destruction
diff --git a/doc/applied/reset b/doc/applied/reset
index db08bec..9a83018 100644
--- a/doc/applied/reset
+++ b/doc/applied/reset
@@ -9,7 +9,7 @@
implementations still follow this tradition.
In compat mode, reset() was called with arg 0 after the object
- was compiled, and with arg != 0 every once in a while. In
+ was compiled, and with arg != 0 every once in a while. In
native mode, create() is called after compiling, and reset()
is called without arguments every once in a while.
@@ -18,7 +18,7 @@
called, you're on the new version and reset() is not called
for object creation. You may call reset() from create() and
vice versa, but make sure they do not call each other
- recursive on either type of driver.
+ recursively on either type of driver.
reset() will be called only in objects that have been used
since the last call to reset(), i.e. a function in them was
diff --git a/doc/concepts/erq b/doc/concepts/erq
index 378d59d..8db9216 100644
--- a/doc/concepts/erq
+++ b/doc/concepts/erq
@@ -5,11 +5,11 @@
Up to version 3.2.1@61, LPMud utilized two external programs
in an ad-hoc manner to solve problems: the 'hname' program to
resolve IP addresses into meaningful hostnames, and the
- 'indent' program to properly indent LPC files.
- In version 3.2.1@61 both functions were united in a
- generalized 'erq' process, to which additional functions may
- be attached. Unfortunately it was never documented by Amylaar,
- so the information presented here had to be reverse engineered
+ 'indent' program to properly indent LPC files. In version
+ 3.2.1@61 both functions were united in a generalized 'erq'
+ process, to which additional functions may be attached.
+ Unfortunately it was never documented by Amylaar, so the
+ information presented here had to be reverse engineered
from the sources - better take it with a grain of salt.
The erq feature is available if the driver is compiled with
@@ -34,10 +34,10 @@
an interactive object as argument, and takes the connection
away(!) from this object and stores it as the erq connection
to use (an old erq connection is closed first). The object
- (which now no longer is interactive) is then no longer needed,
- but may continue to exist.
- The erq attached this way of course has to use the sockets it
- opened to communicate with the driver.
+ (which is now no longer is interactive) is then no longer
+ needed, but may continue to exist. The erq attached this way
+ of course has to use the sockets it opened to communicate
+ with the driver.
Most of the communication between erq and driver is going to
be initiated by the driver (the erq has to look up the
@@ -97,6 +97,7 @@
identified by 'header.handle'. Normally, one request results
in just one response sent by the erq using struct from_erq_msg,
so the handle is recycled after this response.
+
Shall the erq send several responses (or break one response
into several parts), the struct from_erq_keep_msg has to be
used for all but the last response - this message with its
@@ -298,7 +299,7 @@
ERQ_E_UNKNOWN : Process terminated for unknown reason.
- Authentificate connection (see rfc 931):
+ Authenticate connection (see rfc 931):
request : ERQ_AUTH
data sent: struct sockaddr_in remote // the address to check
@@ -313,7 +314,7 @@
The erq attempts to connect the authd on the remote system
and to verify the connection between the remote port and the
mud port. The latter will normally be the port number of the
- socket on besides of the gamedriver, retrieveable by
+ socket on besides of the gamedriver, retrievable by
query_ip_number().
The answer from the authd (one line of text) if there is any
@@ -323,7 +324,7 @@
the xerq as alternative.
- Open an UPD port:
+ Open an UDP port:
request : ERQ_OPEN_UDP
data sent: char[2] port // the port number to open (network order)
@@ -342,7 +343,7 @@
of two bytes.
ERQ_E_NSLOTS : The max number of child processes (given
in <info>) is exhausted.
- ERQ_E_UNKNOWN : Error <info> occured in one of the system
+ ERQ_E_UNKNOWN : Error <info> occurred in one of the system
calls done to open the port.
Once the port is open, it is treated as if is just another
@@ -398,7 +399,7 @@
the network from the sender at <addr>, reply port number <port>.
- Open an TCP to listen for connections:
+ Open a TCP port to listen for connections:
request : ERQ_LISTEN
data sent: struct addr.sin_port port // the port number to open
@@ -409,7 +410,7 @@
char rc = ERQ_OK
char[] ticket // the connection ticket.
- The erq opens an TCP-port on the host machine with the given
+ The erq opens a TCP-port on the host machine with the given
port number to listen for connections.
Possible exit codes are:
ERQ_OK : Operation succeeded.
@@ -417,14 +418,14 @@
of two bytes.
ERQ_E_NSLOTS : The max number of child processes (given
in <info>) is exhausted.
- ERQ_E_UNKNOWN : Error <info> occured in one of the system
+ ERQ_E_UNKNOWN : Error <info> occurred in one of the system
calls done to open the port.
Once the port is open, it is treated as if is just another
spawned program.
- Open an TCP port:
+ Open a TCP port:
request : ERQ_OPEN_TCP
data sent: struct in_addr.s_addr ip // the ip to address
@@ -436,7 +437,7 @@
char rc = ERQ_OK
char[] ticket // the connection ticket.
- The erq opens an TCP-port on the host machine and tries to connect
+ The erq opens a TCP-port on the host machine and tries to connect
it to the address <ip>:<port>.
Possible exit codes are:
ERQ_OK : Operation succeeded.
@@ -444,7 +445,7 @@
of two bytes.
ERQ_E_NSLOTS : The max number of child processes (given
in <info>) is exhausted.
- ERQ_E_UNKNOWN : Error <info> occured in one of the system
+ ERQ_E_UNKNOWN : Error <info> occurred in one of the system
calls done to open the port.
Once the port is open, it is treated as if is just another
@@ -529,7 +530,7 @@
char[] ticket // the new ticket.
The erq accepts a new connection on an accept-TCP-port, creates
- an child and ticket for it and returns its ticket together with
+ a child and ticket for it, and returns its ticket together with
the remote's side <ip>:<port> number (in network byte order).
Possible exit codes are:
ERQ_OK : Operation succeeded.
@@ -538,13 +539,12 @@
ERQ_E_NSLOTS : The max number of child processes (given
in <info>) is exhausted.
ERQ_E_TICKET : the ticket didn't match
- ERQ_E_UNKNOWN : Error <info> occured in one of the system
+ ERQ_E_UNKNOWN : Error <info> occurred in one of the system
calls done to open the port.
- Once the port is open, it is treated as if is just another
+ Once the port is open, it is treated as if it is just another
spawned program.
-
EXAMPLE
Assume you have a script 'welcome-mail' to send a welcome mail
to a new player. Put this script into the directory for the callable
@@ -563,7 +563,6 @@
, #'erq_response);
}
-
HISTORY
The erq was introduced with 3.2.1@61.
ERQ_AUTH was introduced with 3.2.1@81.
diff --git a/doc/concepts/hooks b/doc/concepts/hooks
index 108da08..aada84e 100644
--- a/doc/concepts/hooks
+++ b/doc/concepts/hooks
@@ -11,6 +11,7 @@
Some of the hooks are mandatory, some not. Most hooks accept
unbound lambda closures as values, some also lfun closures or
even strings.
+
The hooks are identified by an ordinal number, for which
symbolic names are defined in /sys/driverhooks.h.
@@ -30,7 +31,7 @@
H_CREATE_CLONE
Optional hooks to initialize an object after creation.
- H_CREATE_SUPER is called for blueprints implicitely loaded
+ H_CREATE_SUPER is called for blueprints implicitly loaded
by inheritance, H_CREATE_OB for explicitely loaded
blueprints/objects, and H_CREATE_CLONE for cloned objects.
@@ -104,9 +105,14 @@
the source of every compiled LPC object.
+ H_FILE_ENCODING
+ Optonal hook specifying the name of the encoding to be used
+ for decoding a file (default: "ascii").
+
+
H_TELNET_NEG
Optional hook to specifiy how to perform a single telnet
- negotiation. If not set, most telnet options are rejected (read:
+ negotiation. If not set, most telnet options are rejected (read:
only a very minimal negotiation takes place).
@@ -125,6 +131,10 @@
the erq demon.
+ H_MSG_DISCARDED
+ Optional hook to specify a message or take other measures
+ when a message had to be discarded.
+
HISTORY
The hooks concept was introduced in 3.2.1
H_MOVE_OBJECT0/1 were introduced in 3.2.1@1
diff --git a/doc/concepts/hsregexp b/doc/concepts/hsregexp
index 04266be..9905215 100644
--- a/doc/concepts/hsregexp
+++ b/doc/concepts/hsregexp
@@ -1,13 +1,11 @@
SYNOPSIS
Henry Spencer Regular Expressions
-
DESCRIPTION
This document describes the regular expressions supported by the
implementation by Henry Spencer (the traditional package for
LPMud).
-
OPTIONS
The following bitflag options modify the behaviour of the
regular expressions - both interpretation and actual matching.
@@ -20,7 +18,6 @@
editor would do it: () match literally, and the \( \) group
expressions.
-
REGULAR EXPRESSION DETAILS
A regular expression is a pattern that is matched against a
subject string from left to right. Most characters stand for
@@ -77,7 +74,6 @@
\c match character c even if it's one of the special
characters.
-
NOTES
The \< and \> metacharacters from Henry Spencers package
are not available in PCRE, but can be emulate with \b,
@@ -87,13 +83,11 @@
limit, to avoid freezing the driver with a match
like regexp(({"=XX==================="}), "X(.+)+X").
-
AUTHOR
Mark H. Colburn, NAPS International (mark@jhereg.mn.org)
Henry Spencer, University of Torronto (henry@utzoo.edu)
Joern Rennecke
Ian Phillipps
-
SEE ALSO
regexp(C), pcre(C)
diff --git a/doc/concepts/imp b/doc/concepts/imp
index 27d9ab9..5ac1259 100644
--- a/doc/concepts/imp
+++ b/doc/concepts/imp
@@ -3,7 +3,7 @@
LAST UPDATED
Deepthought, 10-Nov-92
- Pepel, 18-Nov-93
+ Pepel, 18-Nov-93
DESRIPTION
This document describes IMP, the intermud message protocol,
@@ -13,8 +13,8 @@
(unreliable datagram protocol) packets. Each mud provides
a connection endpoint which is given by the ip host address
and the UDP port number. Muds may then send messages to
- this port by using the efun send_udp(). The applied function
- receive_udp will be called by the driver in the master
+ this port by using the efun send_imp(). The applied function
+ receive_imp will be called by the driver in the master
object if a imp message arrives at the mud's UDP port.
Imp message packets have the following format:
@@ -48,8 +48,8 @@
NOTE
The above is only particularly correct nowadays. Recently a
- package name ``inetd'' was published, that is based on the IMP
- mechanism in the driver (send_udp() and receive_udp()), but
+ package name "inetd" was published, that is based on the IMP
+ mechanism in the driver (send_imp() and receive_imp()), but
it uses a different message format. That package seems to
enjoy much publicity and is installed in a number of muds. For
details look into the inetd description.
@@ -60,4 +60,4 @@
the connection to other muds.
SEE ALSO
- send_udp(E), receive_udp(M), intermud(C)
+ send_imp(E), receive_imp(M), intermud(C)
diff --git a/doc/concepts/inheritance b/doc/concepts/inheritance
index 46bf338..127b7e6 100644
--- a/doc/concepts/inheritance
+++ b/doc/concepts/inheritance
@@ -10,11 +10,11 @@
some special changes to it. That doesn't work by copying the
file.. Ouch! Don't replicate code! But by putting a tiny inherit
declaration
-
+
inherit "<model-class>";
-
+
at the beginning of your new file. This must come before any local
- ariables or functions. Once inherited your class will behave just
+ variables or functions. Once inherited your class will behave just
like the model class, because all the public methods are available
to the outside world. Now it is in your hands to change such an
inherited behaviour. You have the following tools to do so:
@@ -52,7 +52,6 @@
variant.
EXAMPLE
-
Let's imagine very simple food in a file called "/the/food.c":
// unless "modified" variables are accessible by inheritors
@@ -124,7 +123,6 @@
}
ADVANCED USAGE
-
* Doing multiple inheritance
While the Java(TM) language has so-called interfaces as a kludge,
@@ -137,16 +135,17 @@
* Wildcarded multiple inheritance
- LDMUD 3.2.1@117 introduces an advanced voodoo syntax which allows
- you to call several methods in model classes at once, but for some
- technical reasons it cannot pass any arguments. This works by
+ LDMud 3.2.1@117 introduces an advanced voodoo syntax which allows
+ you to call several methods in model classes at once. This works by
writing a glob type match ('*' and '?' wildcards) into the string
- in front of the double colon, as in "*"::create(). I wouldn't
- recommend you to use this, it's better to be clearly conscious of
- what you inherit and do. But if you're desperate, there you go.
+ in front of the double colon, as in "*"::create().
+ I wouldn't recommend you to use this, it's better to be clearly
+ conscious of what you inherit and do. But if you're desperate, there
+ you go.
+
+ Since LDMud 3.5.0 it is possible to pass arguments as well.
ADVANCED EXAMPLE
-
inherit "foo";
inherit "bar";
inherit "baz";
@@ -172,6 +171,6 @@
SEE ALSO
functions(LPC), initialisation(LPC), modifiers(LPC), pragma(LPC),
- overloading(C)
- function_exists(efun), functionlist(efun), inherit_list(efun),
- symbol_variable(efun), variable_exists(efun), variable_list(efun).
+ overloading(C),
+ function_exists(E), functionlist(E), inherit_list(E),
+ symbol_variable(E), variable_exists(E), variable_list(E)
diff --git a/doc/concepts/intermud b/doc/concepts/intermud
index abe2b4f..5db726b 100644
--- a/doc/concepts/intermud
+++ b/doc/concepts/intermud
@@ -8,7 +8,7 @@
implementations is limited.
This text is about the rather old widely spread 'Zebedee Intermud',
- which is also called 'Intermud 2' altough it differs quite a lot
+ which is also called 'Intermud 2' although it differs quite a lot
from the real Intermud 2 protocol.
Full information on the newer Intermud 3 could be found on the
diff --git a/doc/concepts/mccp b/doc/concepts/mccp
index f3e31fb..5cb605d 100644
--- a/doc/concepts/mccp
+++ b/doc/concepts/mccp
@@ -2,14 +2,14 @@
mccp - The Mud Client Compression Protocol
DESCRIPTION
- Informations and code taken from the MCCP Homepage
+ Information and code taken from the MCCP Homepage
http://www.randomly.org/projects/MCCP/
MCCP is implemented as a Telnet option [RFC854, RFC855]. The server
and client negotiate the use of MCCP as they would any other telnet
option. Once agreement has been reached on the use of the option,
option subnegotiation is used to determine acceptable compression
- methods to use, and to indicate the start of a compressed data stream.
+ methods to use, and to indicate the start of a compressed data stream.
If the driver is compiled with MCCP Support there is a
define __MCCP__.
@@ -24,7 +24,7 @@
Notice: when the client uses compressions all binary_message calls
are executed with flag=3. This is because writing to the
socket would disturb zlib stream.
-
+
mccp-efuns:
start_mccp_compress(int telopt) (only needed with H_NOECHO)
@@ -32,7 +32,7 @@
query_mccp(object player)
query_mccp_stats(object player)
- Initiating MCCP without H_NOECHO hook:
+ Initiating MCCP without H_NOECHO hook:
if(!query_mccp()){
binary_message(({ IAC, WILL, TELOPT_COMPRESS2 }),1)
@@ -41,42 +41,43 @@
the driver will parse the clients answers and start compression.
(The connection might already be compressed, because although the
- documentation says clients should not negotiate from themselfes,
+ documentation says clients should not negotiate from themselves,
zmud e.g. does.)
You can start and stop compression manually by efuns
when you are sure client supports compression :)
- Initiating MCCP compression with H_NOECHO hook:
+ Initiating MCCP compression with H_NOECHO hook:
If your mudlib uses the H_NOECHO driver-hook you decided to do
all the negotiation by yourself:
Server Commands
- IAC WILL COMPRESS indicates the sender supports version 1 of the
- protocol, and is willing to compress data it sends.
+ IAC WILL COMPRESS indicates the sender supports version 1 of the
+ protocol, and is willing to compress data it sends.
IAC WILL COMPRESS2 indicates the sender supports version 2, and is
- willing to compress data it sends.
+ willing to compress data it sends.
- IAC WONT COMPRESS indicates the sender refuses to compress data using
- version 1.
+ IAC WONT COMPRESS indicates the sender refuses to compress data using
+ version 1.
IAC WONT COMPRESS2 indicates the sender refuses to compress data
- using version 2.
+ using version 2.
Client Commands
- IAC DO COMPRESS indicates the sender supports version 1 of the
- protocol, and is willing to decompress data received.
+ IAC DO COMPRESS indicates the sender supports version 1 of the
+ protocol, and is willing to decompress data
+ received.
- IAC DO COMPRESS2 indicates the sender supports version 2 or above,
- and is willing to decompress data received.
+ IAC DO COMPRESS2 indicates the sender supports version 2 or above,
+ and is willing to decompress data received.
- IAC DONT COMPRESS indicates the sender refuses to support version 1.
- If compression was previously negotiated and is
- currently being used, the server should terminate
- compression.
+ IAC DONT COMPRESS indicates the sender refuses to support version 1.
+ If compression was previously negotiated and is
+ currently being used, the server should terminate
+ compression.
IAC DONT COMPRESS2 indicates the sender refuses to support version 2.
If compression was previously negotiated and is
@@ -96,5 +97,4 @@
SEE ALSO
start_mccp_compress(E), end_mccp_compress(E), query_mccp(E),
- query_mccp_stats(object player)
-
+ query_mccp_stats(E)
diff --git a/doc/concepts/memory b/doc/concepts/memory
index 9524eb3..95b0b2d 100644
--- a/doc/concepts/memory
+++ b/doc/concepts/memory
@@ -1,9 +1,7 @@
CONCEPT
- memory
- swapping
+ memory / swapping
DESCRIPTION
-
TODO: This is out of date. Also document the relation with reset
(Collected from the Changelogs of the driver source)
@@ -35,8 +33,8 @@
Any feedback of how to best tune these values are welcome. The
call of reset will be done once, and not yet again until the
object has been touched. This enables reset'ed objects to stay
- swapped out. If you have a mudlib that has no ojbects that
- defines 'clean_up', then you may better define this time as 0,
+ swapped out. If you have a mudlib that has no objects that
+ define 'clean_up', then you may better define this time as 0,
which means never call clean_up (and thus never swap the
object in needlessly). A well implemented usage of clean_up is
better than the swap algorithm, as even cloned objects can be
@@ -44,13 +42,14 @@
swapping (memory wise).
Changed mechanism of calling clean_up() slightly. Only objects
- that defines the function will be called. And, only clean_up()
+ that define the function will be called. And, only clean_up()
that returns non-zero will be called again. This will minimize
- calls of clean_up(), while still cost very litte to maintain.
+ calls of clean_up(), while still costing little to maintain.
clean_up() now gets a flag as argument, which will be non-zero
if the the program of this object is used for inheritance by
other objects.
SEE ALSO
- clean_up(A), slow_shut_down(M), quota_demon(M), malloc(D)
+ clean_up(A), slow_shut_down(M), quota_demon(M), low_memory(M)
+ malloc(D), garbage_collection(E)
diff --git a/doc/concepts/mysql b/doc/concepts/mysql
index 4fb6dee..66f4e7d 100644
--- a/doc/concepts/mysql
+++ b/doc/concepts/mysql
@@ -1,5 +1,5 @@
CONCEPT
- mysql - mySQL support
+ mysql - mySQL support
DESCRIPTION
On hosts with the mySQL package installed, the driver can be
@@ -12,9 +12,9 @@
Create a dedicated user in the mySQL database for the driver.
Enter this username and password in the file pkg-mysql.c, function
mysql_real_connect(), and compile the driver (the username and
- password are built into the driver for security reasons).
- If you chose to not create either a username and/or a password,
- leave the corresponding entry at 0.
+ password are built into the driver for security reasons). If you
+ choose to not create either a username and/or a password, leave the
+ corresponding entry at 0.
Use mysqladmin to create any databases you want to provide - the
names are later used in the efun db_connect() to connect to
@@ -32,7 +32,7 @@
To connect to your mySQL-server, use the efun db_connect(). It
takes only one argument which is the name of the database (which
- must exist). The return-value of db_connect() is an integer
+ must exist). The return-value of db_connect() is an integer
representing the unique handle to the database with which you will
identify your connection later.
@@ -94,6 +94,16 @@
db_conv_string()
+ -- Caveats --
+
+ The driver enables automatic reconnects on the database connections.
+ This means that if a connection is lost - the most common case for
+ this is timeouts, which by default happen after 28800 seconds of
+ inactivity - an attempt will be made to establish a new connection to
+ the database server. When that happens, all session state (temprary
+ tables and state changes from SET statements) will be lost. It's best
+ not to rely on such state.
+
EXAMPLE
A simple server to store aliases could be implemented like this:
diff --git a/doc/concepts/native b/doc/concepts/native
index 13cf008..49b9b38 100644
--- a/doc/concepts/native
+++ b/doc/concepts/native
@@ -97,7 +97,7 @@
These exist only in compat mode (creator() is
identical with getuid()).
- object_name(),function_exists()
+ object_name(), function_exists()
In !compat mode, the returned filenames start with a
leading '/', in compat mode they don't.
@@ -134,18 +134,21 @@
--- In Detail ---
Userids of the Master
- The masters (e)uid is determined by a call to
+ The master's (e)uid is determined by a call to
master->get_master_uid().
+
In strict-euids mode, the result has to be a string,
otherwise the driver won't start up at all. If the result is
- valid it is set as the masters uid and euid.
+ valid it is set as the master's uid and euid.
+
In !strict-euids mode, the result may be any value: 0 or a
string are treated as the uid to set, a non-zero integer
leads to the use of the uid set in the default 'global'
wizlist entry, and any other value defaults to 0.
The euid is either set to the returned string (if any),
or to 0.
- The masters uid is determined only on startup this way,
+
+ The master's uid is determined only on startup this way;
at runtime the uids of a reloaded master determined as
for every object by a call to the appropriate driver
hooks.
@@ -156,8 +159,10 @@
evaluated (H_LOAD_UIDS, H_CLONE_UIDS) and the result set
as (e)uid. The result may be a single value, in which case the
euid is set to 0, or an array ({ uid, euid }).
+
In strict-euids mode, both uid and euid must be 0 or a string,
any other value causes the load/clone to fail.
+
In !strict-euids mode, the uid (however returned) may also be
a non-zero integer to use the uid of the global
wizlist entry as uid. The euid is then
diff --git a/doc/concepts/negotiation b/doc/concepts/negotiation
index ed2318f..f00aba9 100644
--- a/doc/concepts/negotiation
+++ b/doc/concepts/negotiation
@@ -6,14 +6,14 @@
between a client (the 'telnet' program or a mud client) and a
server (the game driver). Most of the options offered by the
protocol are optional and need to be negotiated between the
- client and the server. Consequently, and due to their
+ client and the server. Consequently, and due to their
specialized nature, mud clients don't have to support the full
telnet option feature set.
For the server to find out if a client supports the telnet
- protocol at all, one good approach is to a simple, commonly
- used telnet command to the client. If the client reacts
- conform to the protocol (or sends telnet commands itself), the
+ protocol at all, one good approach is to issue a simple,
+ commonly used telnet command to the client. If the client reaction
+ conforms to the protocol (or sends telnet commands itself), the
mud can continue to negotiate further options. If the client
does not react, the mud can safely refrain from further
negotiations.
@@ -22,58 +22,58 @@
the telnet related RFCs (available for example on
http://www.faqs.org/rfcs):
- RFC Titel rel. Code
+ RFC Title rel. Code
- 495 TELNET Protocol Specification
- 513 Comments on the new TELNET specifications
- 559 Comments on the new TELNET Protocol and its Implem
- 595 Some Thoughts in Defense of the TELNET Go-Ahead
- 596 Second Thoughts on Telnet Go-Ahead
- 652 Telnet Output Carriage-Return Disposition Option NAOCRD 10
- 653 Telnet Output Horizontal Tabstops Option NAOHTS 11
- 654 Telnet Output Horizontal Tab Disposition Option NAOHTD 12
- 655 Telnet Output Formfeed Disposition Option NAOFFD 13
- 656 Telnet Output Vertical Tabstops Option NAOVTS 14
- 657 Telnet Output Vertical Tab Disposition Option NAOVTD 15
- 658 Telnet Output Linefeed Disposition NAOLFD 16
- 698 Telnet Extended Ascii Option X-ASCII 17
- 727 Telnet Logout Option LOGOUT 18
- 728 A Minor Pitfall in the Telnet Protocol
- 735 Revised TELNET Byte Macro Option BM 19
- 749 Telnet SUPDUP-OUTPUT Option SUPDUP 22
- 764 Telnet Protocol Specification
- 779 Telnet SEND-LOCATION Option SENDLOC 23
- 818 The Remote User Telnet Service
- 854 Telnet Protocol Specification
- 855 Telnet Option Specifications
- 856 Telnet Binary Transmission BINARY 0
- 857 Telnet Echo Option ECHO 1
- 858 Telnet Suppress Go Ahead Option SGA 3
- 859 Telnet Status Option STATUS 5
- 860 Telnet Timing Mark Option TM 6
- 861 Telnet Extended Options - List Option EXOPL 255
- 884 Telnet Terminal Type Option TTYPE 24
- 885 Telnet End of Record Option EOR 25
- 930 Telnet Terminal Type Option TTYPE 24
- 933 Output Marking Telnet Option OUTMRK 27
- 946 Telnet Terminal Location Number Option TTYLOC 28
- 1043 Telnet Data Entry Terminal Option DODIIS Implement DET 20
- 1053 Telnet X.3 PAD Option X.3-PAD 30
- 1073 Telnet Window Size Option NAWS 31
- 1079 Telnet Terminal Speed Option TSPEED 32
- 1080 Telnet Remote Flow Control Option FLOWCTRL 33
- 1091 Telnet Terminal-Type Option TTYPE 24
- 1096 Telnet X Display Location Option XDISPLOC 35
- 1116 Telnet Linemode Option LINEMODE 34
- 1143 The Q Method of Implementing TELNET Option Negotia
- 1184 Telnet Linemode Option LINEMODE 34
- 1372 Telnet Remote Flow Control Option FLOWCTRL 33
- 1408 Telnet Environment Option ENVIRON 36
- 1571 Telnet Environment Option Interoperability Issues
- 1572 Telnet Environment Option NEWENV 39
- 2066 Telnet Charset Option CHARSET 42
- 2217 Telnet Com Port Control Option COMPORT 44
- 2877 5250 Telnet Enhancements
+ 495 TELNET Protocol Specification
+ 513 Comments on the new TELNET specifications
+ 559 Comments on the new TELNET Protocol and its Implem
+ 595 Some Thoughts in Defense of the TELNET Go-Ahead
+ 596 Second Thoughts on Telnet Go-Ahead
+ 652 Telnet Output Carriage-Return Disposition Option NAOCRD 10
+ 653 Telnet Output Horizontal Tabstops Option NAOHTS 11
+ 654 Telnet Output Horizontal Tab Disposition Option NAOHTD 12
+ 655 Telnet Output Formfeed Disposition Option NAOFFD 13
+ 656 Telnet Output Vertical Tabstops Option NAOVTS 14
+ 657 Telnet Output Vertical Tab Disposition Option NAOVTD 15
+ 658 Telnet Output Linefeed Disposition NAOLFD 16
+ 698 Telnet Extended Ascii Option X-ASCII 17
+ 727 Telnet Logout Option LOGOUT 18
+ 728 A Minor Pitfall in the Telnet Protocol
+ 735 Revised TELNET Byte Macro Option BM 19
+ 749 Telnet SUPDUP-OUTPUT Option SUPDUP 22
+ 764 Telnet Protocol Specification
+ 779 Telnet SEND-LOCATION Option SENDLOC 23
+ 818 The Remote User Telnet Service
+ 854 Telnet Protocol Specification
+ 855 Telnet Option Specifications
+ 856 Telnet Binary Transmission BINARY 0
+ 857 Telnet Echo Option ECHO 1
+ 858 Telnet Suppress Go Ahead Option SGA 3
+ 859 Telnet Status Option STATUS 5
+ 860 Telnet Timing Mark Option TM 6
+ 861 Telnet Extended Options - List Option EXOPL 255
+ 884 Telnet Terminal Type Option TTYPE 24
+ 885 Telnet End of Record Option EOR 25
+ 930 Telnet Terminal Type Option TTYPE 24
+ 933 Output Marking Telnet Option OUTMRK 27
+ 946 Telnet Terminal Location Number Option TTYLOC 28
+ 1043 Telnet Data Entry Terminal Option DODIIS Implement DET 20
+ 1053 Telnet X.3 PAD Option X.3-PAD 30
+ 1073 Telnet Window Size Option NAWS 31
+ 1079 Telnet Terminal Speed Option TSPEED 32
+ 1080 Telnet Remote Flow Control Option FLOWCTRL 33
+ 1091 Telnet Terminal-Type Option TTYPE 24
+ 1096 Telnet X Display Location Option XDISPLOC 35
+ 1116 Telnet Linemode Option LINEMODE 34
+ 1143 The Q Method of Implementing TELNET Option Negotia
+ 1184 Telnet Linemode Option LINEMODE 34
+ 1372 Telnet Remote Flow Control Option FLOWCTRL 33
+ 1408 Telnet Environment Option ENVIRON 36
+ 1571 Telnet Environment Option Interoperability Issues
+ 1572 Telnet Environment Option NEWENV 39
+ 2066 Telnet Charset Option CHARSET 42
+ 2217 Telnet Com Port Control Option COMPORT 44
+ 2877 5250 Telnet Enhancements
All negotiations start with the special character IAC which is
defined in /usr/include/arpa/telnet.h (or in
@@ -81,8 +81,7 @@
255. Negotiations are based on different telnetoptions (their
values are defined in telnet.h too). Before a negotiation can
start the client and the server have to agree that they
- support the option.
- This works in the following way:
+ support the option. This works in the following way:
If a client wants to send something to the server it has to
send 'IAC WILL option' (For terminaltype negotation this would
@@ -100,17 +99,17 @@
sent a WILL or WONT it has to reply with either 'IAC WILL
option' if it supports the option or 'IAC WONT option' if not.
- A small example: Lets assume we want to negotiating
+ A small example: Lets assume we want to negotiate
terminaltype. (TELOPT_TTYPE with value 24). client is the
telnet executable on the playerside, the server is the
gamedriver.
client server
IAC WILL TTYPE
- IAC DO TTYPE
+ IAC DO TTYPE
Or:
- IAC DO TTYPE
+ IAC DO TTYPE
IAC WILL TTYPE
After this we are ready to transfer the terminaltype from the
@@ -137,18 +136,18 @@
Example: (we have exchanged WILL/DO already)
client server
- IAC SB TTYPE SEND IAC SE
+ IAC SB TTYPE SEND IAC SE
IAC SB TTYPE IS VT200 IAC SE
- IAC SB TTYPE SEND IAC SE
+ IAC SB TTYPE SEND IAC SE
IAC SB TTYPE IS VT100 IAC SE
- IAC SB TTYPE SEND IAC SE
+ IAC SB TTYPE SEND IAC SE
IAC SB TTYPE IS VT52 IAC SE
- IAC SB TTYPE SEND IAC SE
+ IAC SB TTYPE SEND IAC SE
IAC SB TTYPE IS VT52 IAC SE
/* this marks that we have all terminaltypes. We decide to use the
* vt200 mode so we have to skip to VT200
*/
- IAC SB TTYPE SEND IAC SE
+ IAC SB TTYPE SEND IAC SE
IAC SB TTYPE IS VT200 IAC SE
@@ -166,7 +165,7 @@
Example: (WILL/DO exchanged)
client server
IAC SB NAWS 0 80 0 24 IAC SE /* the standard vt100 windowsize */
- /* no reply */
+ /* no reply */
And, a bit less important but most complex, the LINEMODE (34)
option. It was implemented it due to the fact, that
@@ -178,7 +177,7 @@
commandline-editing for the client. If a client supports
LINEMODE it HAS to support this modechange. The client will
reply with IAC SB LINEMODE LM_MODE MODE_EDIT|MODE_ACK IAC SE
- (x|y is bitwise or). Thats it for linemode. (You will perhaps
+ (x|y is bitwise or). That's it for linemode. (You will perhaps
receive other IAC SB LINEMODEs with other LM_xxx ... you may
ignore them. (At least IRIX 5.x sends IAC SB LINEMODE LM_SLC
.... IAC SE which declares the local characterset.)).
@@ -191,9 +190,9 @@
IAC SB LINEMODE LM_MODE
MODE_EDIT|MODE_ACK IAC SE
- Note: The option is much more funnier as it looks here, it for
- example supports a mixed mode between linemode and
- charactermode... flushing the input at certain characters (at
+ Note: The option is more interesting than it looks here. For
+ example it supports a mixed mode between linemode and
+ charactermode, flushing the input at certain characters (at
ESC or TAB for shell-like commandline completition). We suggest
reading RFC 1184.
@@ -232,7 +231,7 @@
using binary_message() (appropiate meaning sending the
right DO/DONT/WILL/WONT if not sent before and using the SB
return values).
- 3.1. Sent IAC DO TTYPE IAC DO NAWS IAC DO LINEMODE at the
+ 3.1. Send IAC DO TTYPE IAC DO NAWS IAC DO LINEMODE at the
first time you can do it (before cat()ing /WELCOME perhaps).
3.2. Note all sent and received WILL/WONT/DO/DONT options for
conforming to the standard, avoiding endless loops and for
@@ -243,7 +242,7 @@
linkdead or quits. You won't need to save this data.
3.4. Lower_case() terminaltypes... ;)
3.5. Use reasonable defaultvalues if the client does not
- support one of the options. (columns 80,lines 24 if not
+ support one of the options. (columns 80, lines 24 if not
NAWS, unknown or vt100 for no terminaltype)
The WILL/WONT/DO/DONT data is best saved in a mapping looking
@@ -287,6 +286,7 @@
Tinyfugue and some other mudclients usually do not support
negotiations.
+
Except for TF, which supports the Telnet End-Of-Record option
as marker for the end of the prompt. So if you send IAC EOR
after every prompt, it will print the prompt always in the
@@ -306,7 +306,6 @@
For getting RFCs you can for example use
ftp://ftp.uni-erlangen.de/pub/doc/rfc/
-
BUGS
Not all aspects of the options are mentioned to keep this doc
at a reasonable size. Refer to the RFCs to get more confused.
diff --git a/doc/concepts/objects b/doc/concepts/objects
index b9c7eb9..bae3b30 100644
--- a/doc/concepts/objects
+++ b/doc/concepts/objects
@@ -10,10 +10,10 @@
The only way to manipulate the data contained in an object is
via one of the functions defined by the object.
- Every single thing in a mud is an object. Rooms are objects.
- Weapons are objects. Even your character is an object (a special
+ Every single thing in a mud is an object. Rooms are objects.
+ Weapons are objects. Even your character is an object (a special
kind of object called "interactive" but still an object in most
- every respect). Each object (except possibly virtual objects) in
+ every respect). Each object (except possibly virtual objects) in
the mud is associated with some file written in LPC (in the mud's
directory structure) that describes how the object is to interact
with the gamedriver and the rest of the objects in the mud.
diff --git a/doc/concepts/overloading b/doc/concepts/overloading
index 06209e9..70c3544 100644
--- a/doc/concepts/overloading
+++ b/doc/concepts/overloading
@@ -6,10 +6,12 @@
A function is called 'overloaded' if it is defined more than once
in an object. This can happen if the object inherits other objects
which have defined a function with the same name.
+
Usually the overloading is wanted and intended by the inheriting
object to change the behaviour of the function it overloads.
To call the overloaded functions from the overloading object the
::-operator is used.
+
From outside the object only one of the functions can be called
via call_other() or the like; this will be the topmost of all
overloaded functions.
@@ -37,12 +39,12 @@
foo() {
a::foo();
- b::foo();
- write("C");
- }
+ b::foo();
+ write("C");
+ }
- To call "players/alfe/c"->foo() will now result in the output of
- ABC.
+ To call "players/alfe/c"->foo() will now result in the output of
+ ABC.
SEE ALSO
modifiers(LPC), inheritance(C), functions(LPC)
diff --git a/doc/concepts/pcre b/doc/concepts/pcre
index f863ffd..4c4cc02 100644
--- a/doc/concepts/pcre
+++ b/doc/concepts/pcre
@@ -1,58 +1,54 @@
SYNOPSIS
PCRE - Perl-compatible regular expressions
-
DESCRIPTION
- This document describes the regular expressions supported by the
- PCRE package. When the package is compiled into the driver, the
- macro __PCRE__ is defined.
+ This document describes the regular expressions supported by the PCRE
+ package. When the package is compiled into the driver, the macro
+ __PCRE__ is defined.
- Most of this manpage is lifted directly from the original PCRE
- manpage (dated January 2003).
+ Most of this manpage is lifted directly from the original PCRE manpage
+ (dated January 2003).
- The PCRE library is a set of functions that implement regular
- expression pattern matching using the same syntax and semantics
- as Perl 5, with just a few differences (see below). The
- current implementation corresponds to Perl 5.005, with some
- additional features from later versions. This includes some
- experimental, incomplete support for UTF-8 encoded strings.
- Details of exactly what is and what is not supported are given
- below.
-
+ The PCRE library is a set of functions that implement regular
+ expression pattern matching using the same syntax and semantics as
+ Perl 5, with just a few differences (see below). The current
+ implementation corresponds to Perl 5.005, with some additional features
+ from later versions. This includes some experimental, incomplete
+ support for UTF-8 encoded strings. Details of exactly what is and what
+ is not supported are given below.
PCRE REGULAR EXPRESSION DETAILS
+ The syntax and semantics of the regular expressions supported by PCRE
+ are described below. Regular expressions are also described in the Perl
+ documentation and in a number of other books, some of which have
+ copious examples. Jeffrey Friedl's "Mastering Regular Expressions",
+ published by O'Reilly, covers them in great detail. The description
+ here is intended as reference documentation.
- The syntax and semantics of the regular expressions supported by PCRE
- are described below. Regular expressions are also described in the Perl
- documentation and in a number of other books, some of which have copi-
- ous examples. Jeffrey Friedl's "Mastering Regular Expressions", pub-
- lished by O'Reilly, covers them in great detail. The description here
- is intended as reference documentation.
+ The basic operation of PCRE is on strings of bytes. However, there is
+ also support for UTF-8 character strings. To use this support you must
+ build PCRE to include UTF-8 support, and then call pcre_compile() with
+ the PCRE_UTF8 option. How this affects the pattern matching is
+ mentioned in several places below. There is also a summary of UTF-8
+ features in the section on UTF-8 support in the main pcre page.
- The basic operation of PCRE is on strings of bytes. However, there is
- also support for UTF-8 character strings. To use this support you must
- build PCRE to include UTF-8 support, and then call pcre_compile() with
- the PCRE_UTF8 option. How this affects the pattern matching is men-
- tioned in several places below. There is also a summary of UTF-8 fea-
- tures in the section on UTF-8 support in the main pcre page.
-
- A regular expression is a pattern that is matched against a subject
- string from left to right. Most characters stand for themselves in a
- pattern, and match the corresponding characters in the subject. As a
- trivial example, the pattern
+ A regular expression is a pattern that is matched against a subject
+ string from left to right. Most characters stand for themselves in a
+ pattern, and match the corresponding characters in the subject. As a
+ trivial example, the pattern
The quick brown fox
- matches a portion of a subject string that is identical to itself. The
- power of regular expressions comes from the ability to include alterna-
- tives and repetitions in the pattern. These are encoded in the pattern
- by the use of meta-characters, which do not stand for themselves but
- instead are interpreted in some special way.
+ matches a portion of a subject string that is identical to itself. The
+ power of regular expressions comes from the ability to include
+ alternatives and repetitions in the pattern. These are encoded in the
+ pattern by the use of meta-characters, which do not stand for
+ themselves but instead are interpreted in some special way.
- There are two different sets of meta-characters: those that are recog-
- nized anywhere in the pattern except within square brackets, and those
- that are recognized in square brackets. Outside square brackets, the
- meta-characters are as follows:
+ There are two different sets of meta-characters: those that are
+ recognized anywhere in the pattern except within square brackets, and
+ those that are recognized in square brackets. Outside square brackets,
+ the meta-characters are as follows:
\ general escape character with several uses
^ assert start of string (or line, in multiline mode)
@@ -70,8 +66,8 @@
also "possessive quantifier"
{ start min/max quantifier
- Part of a pattern that is in square brackets is called a "character
- class". In a character class the only meta-characters are:
+ Part of a pattern that is in square brackets is called a "character
+ class". In a character class the only meta-characters are:
\ general escape character
^ negate the class, but only if the first character
@@ -80,34 +76,32 @@
syntax)
] terminates the character class
- The following sections describe the use of each of the meta-characters.
-
+ The following sections describe the use of each of the meta-characters.
BACKSLASH
+ The backslash character has several uses. Firstly, if it is followed by
+ a non-alphameric character, it takes away any special meaning that
+ character may have. This use of backslash as an escape character
+ applies both inside and outside character classes.
- The backslash character has several uses. Firstly, if it is followed by
- a non-alphameric character, it takes away any special meaning that
- character may have. This use of backslash as an escape character
- applies both inside and outside character classes.
+ For example, if you want to match a * character, you write \* in the
+ pattern. This escaping action applies whether or not the following
+ character would otherwise be interpreted as a meta-character, so it is
+ always safe to precede a non-alphameric with backslash to specify that
+ it stands for itself. In particular, if you want to match a backslash,
+ you write \\.
- For example, if you want to match a * character, you write \* in the
- pattern. This escaping action applies whether or not the following
- character would otherwise be interpreted as a meta-character, so it is
- always safe to precede a non-alphameric with backslash to specify that
- it stands for itself. In particular, if you want to match a backslash,
- you write \\.
+ If a pattern is compiled with the PCRE_EXTENDED option, whitespace in
+ the pattern (other than in a character class) and characters between a
+ # outside a character class and the next newline character are ignored.
+ An escaping backslash can be used to include a whitespace or #
+ character as part of the pattern.
- If a pattern is compiled with the PCRE_EXTENDED option, whitespace in
- the pattern (other than in a character class) and characters between a
- # outside a character class and the next newline character are ignored.
- An escaping backslash can be used to include a whitespace or # charac-
- ter as part of the pattern.
-
- If you want to remove the special meaning from a sequence of charac-
- ters, you can do so by putting them between \Q and \E. This is differ-
- ent from Perl in that $ and @ are handled as literals in \Q...\E
- sequences in PCRE, whereas in Perl, $ and @ cause variable interpola-
- tion. Note the following examples:
+ If you want to remove the special meaning from a sequence of
+ characters, you can do so by putting them between \Q and \E. This is
+ different from Perl in that $ and @ are handled as literals in \Q...\E
+ sequences in PCRE, whereas in Perl, $ and @ cause variable
+ interpolation. Note the following examples:
Pattern PCRE matches Perl matches
@@ -116,15 +110,15 @@
\Qabc\$xyz\E abc\$xyz abc\$xyz
\Qabc\E\$\Qxyz\E abc$xyz abc$xyz
- The \Q...\E sequence is recognized both inside and outside character
- classes.
+ The \Q...\E sequence is recognized both inside and outside character
+ classes.
- A second use of backslash provides a way of encoding non-printing char-
- acters in patterns in a visible manner. There is no restriction on the
- appearance of non-printing characters, apart from the binary zero that
- terminates a pattern, but when a pattern is being prepared by text
- editing, it is usually easier to use one of the following escape
- sequences than the binary character it represents:
+ A second use of backslash provides a way of encoding non-printing
+ characters in patterns in a visible manner. There is no restriction on
+ the appearance of non-printing characters, apart from the binary zero
+ that terminates a pattern, but when a pattern is being prepared by text
+ editing, it is usually easier to use one of the following escape
+ sequences than the binary character it represents:
\a alarm, that is, the BEL character (hex 07)
\cx "control-x", where x is any character
@@ -137,45 +131,45 @@
\xhh character with hex code hh
\x{hhh..} character with hex code hhh... (UTF-8 mode only)
- The precise effect of \cx is as follows: if x is a lower case letter,
- it is converted to upper case. Then bit 6 of the character (hex 40) is
- inverted. Thus \cz becomes hex 1A, but \c{ becomes hex 3B, while \c;
- becomes hex 7B.
+ The precise effect of \cx is as follows: if x is a lower case letter,
+ it is converted to upper case. Then bit 6 of the character (hex 40) is
+ inverted. Thus \cz becomes hex 1A, but \c{ becomes hex 3B, while \c;
+ becomes hex 7B.
- After \x, from zero to two hexadecimal digits are read (letters can be
- in upper or lower case). In UTF-8 mode, any number of hexadecimal dig-
- its may appear between \x{ and }, but the value of the character code
- must be less than 2**31 (that is, the maximum hexadecimal value is
- 7FFFFFFF). If characters other than hexadecimal digits appear between
- \x{ and }, or if there is no terminating }, this form of escape is not
- recognized. Instead, the initial \x will be interpreted as a basic hex-
- adecimal escape, with no following digits, giving a byte whose value is
- zero.
+ After \x, from zero to two hexadecimal digits are read (letters can be
+ in upper or lower case). In UTF-8 mode, any number of hexadecimal
+ dig-its may appear between \x{ and }, but the value of the character
+ code must be less than 2**31 (that is, the maximum hexadecimal value is
+ 7FFFFFFF). If characters other than hexadecimal digits appear between
+ \x{ and }, or if there is no terminating }, this form of escape is not
+ recognized. Instead, the initial \x will be interpreted as a basic
+ hexadecimal escape, with no following digits, giving a byte whose value
+ is zero.
- Characters whose value is less than 256 can be defined by either of the
- two syntaxes for \x when PCRE is in UTF-8 mode. There is no difference
- in the way they are handled. For example, \xdc is exactly the same as
- \x{dc}.
+ Characters whose value is less than 256 can be defined by either of the
+ two syntaxes for \x when PCRE is in UTF-8 mode. There is no difference
+ in the way they are handled. For example, \xdc is exactly the same as
+ \x{dc}.
- After \0 up to two further octal digits are read. In both cases, if
- there are fewer than two digits, just those that are present are used.
- Thus the sequence \0\x\07 specifies two binary zeros followed by a BEL
- character (code value 7). Make sure you supply two digits after the
- initial zero if the character that follows is itself an octal digit.
+ After \0 up to two further octal digits are read. In both cases, if
+ there are fewer than two digits, just those that are present are used.
+ Thus the sequence \0\x\07 specifies two binary zeros followed by a BEL
+ character (code value 7). Make sure you supply two digits after the
+ initial zero if the character that follows is itself an octal digit.
- The handling of a backslash followed by a digit other than 0 is compli-
- cated. Outside a character class, PCRE reads it and any following dig-
- its as a decimal number. If the number is less than 10, or if there
- have been at least that many previous capturing left parentheses in the
- expression, the entire sequence is taken as a back reference. A
- description of how this works is given later, following the discussion
- of parenthesized subpatterns.
+ The handling of a backslash followed by a digit other than 0 is
+ complicated. Outside a character class, PCRE reads it and any following
+ digits as a decimal number. If the number is less than 10, or if there
+ have been at least that many previous capturing left parentheses in the
+ expression, the entire sequence is taken as a back reference. A
+ description of how this works is given later, following the discussion
+ of parenthesized subpatterns.
- Inside a character class, or if the decimal number is greater than 9
- and there have not been that many capturing subpatterns, PCRE re-reads
- up to three octal digits following the backslash, and generates a sin-
- gle byte from the least significant 8 bits of the value. Any subsequent
- digits stand for themselves. For example:
+ Inside a character class, or if the decimal number is greater than 9
+ and there have not been that many capturing subpatterns, PCRE re-reads
+ up to three octal digits following the backslash, and generates a
+ single byte from the least significant 8 bits of the value. Any
+ subsequent digits stand for themselves. For example:
\040 is another way of writing a space
\40 is the same, provided there are fewer than 40
@@ -192,16 +186,16 @@
\81 is either a back reference, or a binary zero
followed by the two characters "8" and "1"
- Note that octal values of 100 or greater must not be introduced by a
- leading zero, because no more than three octal digits are ever read.
+ Note that octal values of 100 or greater must not be introduced by a
+ leading zero, because no more than three octal digits are ever read.
- All the sequences that define a single byte value or a single UTF-8
- character (in UTF-8 mode) can be used both inside and outside character
- classes. In addition, inside a character class, the sequence \b is
- interpreted as the backspace character (hex 08). Outside a character
- class it has a different meaning (see below).
+ All the sequences that define a single byte value or a single UTF-8
+ character (in UTF-8 mode) can be used both inside and outside character
+ classes. In addition, inside a character class, the sequence \b is
+ interpreted as the backspace character (hex 08). Outside a character
+ class it has a different meaning (see below).
- The third use of backslash is for specifying generic character types:
+ The third use of backslash is for specifying generic character types:
\d any decimal digit
\D any character that is not a decimal digit
@@ -210,35 +204,35 @@
\w any "word" character
\W any "non-word" character
- Each pair of escape sequences partitions the complete set of characters
- into two disjoint sets. Any given character matches one, and only one,
- of each pair.
+ Each pair of escape sequences partitions the complete set of characters
+ into two disjoint sets. Any given character matches one, and only one,
+ of each pair.
- In UTF-8 mode, characters with values greater than 255 never match \d,
- \s, or \w, and always match \D, \S, and \W.
+ In UTF-8 mode, characters with values greater than 255 never match \d,
+ \s, or \w, and always match \D, \S, and \W.
- For compatibility with Perl, \s does not match the VT character (code
- 11). This makes it different from the the POSIX "space" class. The \s
- characters are HT (9), LF (10), FF (12), CR (13), and space (32).
+ For compatibility with Perl, \s does not match the VT character (code
+ 11). This makes it different from the the POSIX "space" class. The \s
+ characters are HT (9), LF (10), FF (12), CR (13), and space (32).
- A "word" character is any letter or digit or the underscore character,
- that is, any character which can be part of a Perl "word". The defini-
- tion of letters and digits is controlled by PCRE's character tables,
- and may vary if locale- specific matching is taking place (see "Locale
- support" in the pcreapi page). For example, in the "fr" (French)
- locale, some character codes greater than 128 are used for accented
- letters, and these are matched by \w.
+ A "word" character is any letter or digit or the underscore character,
+ that is, any character which can be part of a Perl "word". The
+ definition of letters and digits is controlled by PCRE's character
+ tables, and may vary if locale-specific matching is taking place (see
+ "Locale support" in the pcreapi page). For example, in the "fr"
+ (French) locale, some character codes greater than 128 are used for
+ accented letters, and these are matched by \w.
- These character type sequences can appear both inside and outside char-
- acter classes. They each match one character of the appropriate type.
- If the current matching point is at the end of the subject string, all
- of them fail, since there is no character to match.
+ These character type sequences can appear both inside and outside
+ character classes. They each match one character of the appropriate
+ type. If the current matching point is at the end of the subject
+ string, all of them fail, since there is no character to match.
- The fourth use of backslash is for certain simple assertions. An asser-
- tion specifies a condition that has to be met at a particular point in
- a match, without consuming any characters from the subject string. The
- use of subpatterns for more complicated assertions is described below.
- The backslashed assertions are
+ The fourth use of backslash is for certain simple assertions. An
+ assertion specifies a condition that has to be met at a particular
+ point in a match, without consuming any characters from the subject
+ string. The use of subpatterns for more complicated assertions is
+ described below. The backslashed assertions are:
\b matches at a word boundary
\B matches when not at a word boundary
@@ -247,205 +241,196 @@
\z matches at end of subject
\G matches at first matching position in subject
- These assertions may not appear in character classes (but note that \b
- has a different meaning, namely the backspace character, inside a char-
- acter class).
+ These assertions may not appear in character classes (but note that \b
+ has a different meaning, namely the backspace character, inside a
+ character class).
- A word boundary is a position in the subject string where the current
- character and the previous character do not both match \w or \W (i.e.
- one matches \w and the other matches \W), or the start or end of the
- string if the first or last character matches \w, respectively.
+ A word boundary is a position in the subject string where the current
+ character and the previous character do not both match \w or \W (i.e.
+ one matches \w and the other matches \W), or the start or end of the
+ string if the first or last character matches \w, respectively.
- The \A, \Z, and \z assertions differ from the traditional circumflex
- and dollar (described below) in that they only ever match at the very
- start and end of the subject string, whatever options are set. Thus,
- they are independent of multiline mode.
+ The \A, \Z, and \z assertions differ from the traditional circumflex
+ and dollar (described below) in that they only ever match at the very
+ start and end of the subject string, whatever options are set. Thus,
+ they are independent of multiline mode.
- They are not affected by the PCRE_NOTBOL or PCRE_NOTEOL options. If the
- startoffset argument of pcre_exec() is non-zero, indicating that match-
- ing is to start at a point other than the beginning of the subject, \A
- can never match. The difference between \Z and \z is that \Z matches
- before a newline that is the last character of the string as well as at
- the end of the string, whereas \z matches only at the end.
+ They are not affected by the PCRE_NOTBOL or PCRE_NOTEOL options. If the
+ startoffset argument of pcre_exec() is non-zero, indicating that
+ matching is to start at a point other than the beginning of the
+ subject, \A can never match. The difference between \Z and \z is that
+ \Z matches before a newline that is the last character of the string as
+ well as at the end of the string, whereas \z matches only at the end.
- The \G assertion is true only when the current matching position is at
- the start point of the match, as specified by the startoffset argument
- of pcre_exec(). It differs from \A when the value of startoffset is
- non-zero. By calling pcre_exec() multiple times with appropriate argu-
- ments, you can mimic Perl's /g option, and it is in this kind of imple-
- mentation where \G can be useful.
+ The \G assertion is true only when the current matching position is at
+ the start point of the match, as specified by the startoffset argument
+ of pcre_exec(). It differs from \A when the value of startoffset is
+ non-zero. By calling pcre_exec() multiple times with appropriate
+ arguments, you can mimic Perl's /g option, and it is in this kind of
+ implementation where \G can be useful.
- Note, however, that PCRE's interpretation of \G, as the start of the
- current match, is subtly different from Perl's, which defines it as the
- end of the previous match. In Perl, these can be different when the
- previously matched string was empty. Because PCRE does just one match
- at a time, it cannot reproduce this behaviour.
+ Note, however, that PCRE's interpretation of \G, as the start of the
+ current match, is subtly different from Perl's, which defines it as the
+ end of the previous match. In Perl, these can be different when the
+ previously matched string was empty. Because PCRE does just one match
+ at a time, it cannot reproduce this behaviour.
- If all the alternatives of a pattern begin with \G, the expression is
- anchored to the starting match position, and the "anchored" flag is set
- in the compiled regular expression.
-
+ If all the alternatives of a pattern begin with \G, the expression is
+ anchored to the starting match position, and the "anchored" flag is set
+ in the compiled regular expression.
CIRCUMFLEX AND DOLLAR
+ Outside a character class, in the default matching mode, the circumflex
+ character is an assertion which is true only if the current matching
+ point is at the start of the subject string. If the startoffset
+ argument of pcre_exec() is non-zero, circumflex can never match if the
+ PCRE_MULTILINE option is unset. Inside a character class, circumflex
+ has an entirely different meaning (see below).
- Outside a character class, in the default matching mode, the circumflex
- character is an assertion which is true only if the current matching
- point is at the start of the subject string. If the startoffset argu-
- ment of pcre_exec() is non-zero, circumflex can never match if the
- PCRE_MULTILINE option is unset. Inside a character class, circumflex
- has an entirely different meaning (see below).
+ Circumflex need not be the first character of the pattern if a number
+ of alternatives are involved, but it should be the first thing in each
+ alternative in which it appears if the pattern is ever to match that
+ branch. If all possible alternatives start with a circumflex, that is,
+ if the pattern is constrained to match only at the start of the
+ subject, it is said to be an "anchored" pattern. (There are also other
+ constructs that can cause a pattern to be anchored.)
- Circumflex need not be the first character of the pattern if a number
- of alternatives are involved, but it should be the first thing in each
- alternative in which it appears if the pattern is ever to match that
- branch. If all possible alternatives start with a circumflex, that is,
- if the pattern is constrained to match only at the start of the sub-
- ject, it is said to be an "anchored" pattern. (There are also other
- constructs that can cause a pattern to be anchored.)
+ A dollar character is an assertion which is true only if the current
+ matching point is at the end of the subject string, or immediately
+ before a newline character that is the last character in the string (by
+ default). Dollar need not be the last character of the pattern if a
+ number of alternatives are involved, but it should be the last item in
+ any branch in which it appears. Dollar has no special meaning in a
+ character class.
- A dollar character is an assertion which is true only if the current
- matching point is at the end of the subject string, or immediately
- before a newline character that is the last character in the string (by
- default). Dollar need not be the last character of the pattern if a
- number of alternatives are involved, but it should be the last item in
- any branch in which it appears. Dollar has no special meaning in a
- character class.
+ The meaning of dollar can be changed so that it matches only at the
+ very end of the string, by setting the PCRE_DOLLAR_ENDONLY option at
+ compile time. This does not affect the \Z assertion.
- The meaning of dollar can be changed so that it matches only at the
- very end of the string, by setting the PCRE_DOLLAR_ENDONLY option at
- compile time. This does not affect the \Z assertion.
+ The meanings of the circumflex and dollar characters are changed if the
+ PCRE_MULTILINE option is set. When this is the case, they match
+ immediately after and immediately before an internal newline character,
+ respectively, in addition to matching at the start and end of the
+ subject string. For example, the pattern /^abc$/ matches the subject
+ string "def\nabc" in multiline mode, but not otherwise. Consequently,
+ patterns that are anchored in single line mode because all branches
+ start with ^ are not anchored in multiline mode, and a match for
+ circumflex is possible when the startoffset argument of pcre_exec() is
+ non-zero. The PCRE_DOLLAR_ENDONLY option is ignored if PCRE_MULTILINE
+ is set.
- The meanings of the circumflex and dollar characters are changed if the
- PCRE_MULTILINE option is set. When this is the case, they match immedi-
- ately after and immediately before an internal newline character,
- respectively, in addition to matching at the start and end of the sub-
- ject string. For example, the pattern /^abc$/ matches the subject
- string "def\nabc" in multiline mode, but not otherwise. Consequently,
- patterns that are anchored in single line mode because all branches
- start with ^ are not anchored in multiline mode, and a match for cir-
- cumflex is possible when the startoffset argument of pcre_exec() is
- non-zero. The PCRE_DOLLAR_ENDONLY option is ignored if PCRE_MULTILINE
- is set.
-
- Note that the sequences \A, \Z, and \z can be used to match the start
- and end of the subject in both modes, and if all branches of a pattern
- start with \A it is always anchored, whether PCRE_MULTILINE is set or
- not.
-
+ Note that the sequences \A, \Z, and \z can be used to match the start
+ and end of the subject in both modes, and if all branches of a pattern
+ start with \A it is always anchored, whether PCRE_MULTILINE is set or
+ not.
FULL STOP (PERIOD, DOT)
-
- Outside a character class, a dot in the pattern matches any one charac-
- ter in the subject, including a non-printing character, but not (by
- default) newline. In UTF-8 mode, a dot matches any UTF-8 character,
- which might be more than one byte long, except (by default) for new-
- line. If the PCRE_DOTALL option is set, dots match newlines as well.
- The handling of dot is entirely independent of the handling of circum-
- flex and dollar, the only relationship being that they both involve
- newline characters. Dot has no special meaning in a character class.
-
+ Outside a character class, a dot in the pattern matches any one
+ character in the subject, including a non-printing character, but not
+ (by default) newline. In UTF-8 mode, a dot matches any UTF-8 character,
+ which might be more than one byte long, except (by default) for
+ newline. If the PCRE_DOTALL option is set, dots match newlines as well.
+ The handling of dot is entirely independent of the handling of
+ circumflex and dollar, the only relationship being that they both
+ involve newline characters. Dot has no special meaning in a character
+ class.
MATCHING A SINGLE BYTE
+ Outside a character class, the escape sequence \C matches any one byte,
+ both in and out of UTF-8 mode. Unlike a dot, it always matches a
+ newline. The feature is provided in Perl in order to match individual
+ bytes in UTF-8 mode. Because it breaks up UTF-8 characters into
+ individual bytes, what remains in the string may be a malformed UTF-8
+ string. For this reason it is best avoided.
- Outside a character class, the escape sequence \C matches any one byte,
- both in and out of UTF-8 mode. Unlike a dot, it always matches a new-
- line. The feature is provided in Perl in order to match individual
- bytes in UTF-8 mode. Because it breaks up UTF-8 characters into indi-
- vidual bytes, what remains in the string may be a malformed UTF-8
- string. For this reason it is best avoided.
-
- PCRE does not allow \C to appear in lookbehind assertions (see below),
- because in UTF-8 mode it makes it impossible to calculate the length of
- the lookbehind.
-
+ PCRE does not allow \C to appear in lookbehind assertions (see below),
+ because in UTF-8 mode it makes it impossible to calculate the length of
+ the lookbehind.
SQUARE BRACKETS
+ An opening square bracket introduces a character class, terminated by a
+ closing square bracket. A closing square bracket on its own is not
+ special. If a closing square bracket is required as a member of the
+ class, it should be the first data character in the class (after an
+ initial circumflex, if present) or escaped with a backslash.
- An opening square bracket introduces a character class, terminated by a
- closing square bracket. A closing square bracket on its own is not spe-
- cial. If a closing square bracket is required as a member of the class,
- it should be the first data character in the class (after an initial
- circumflex, if present) or escaped with a backslash.
+ A character class matches a single character in the subject. In UTF-8
+ mode, the character may occupy more than one byte. A matched character
+ must be in the set of characters defined by the class, unless the first
+ character in the class definition is a circumflex, in which case the
+ subject character must not be in the set defined by the class. If a
+ circumflex is actually required as a member of the class, ensure it is
+ not the first character, or escape it with a backslash.
- A character class matches a single character in the subject. In UTF-8
- mode, the character may occupy more than one byte. A matched character
- must be in the set of characters defined by the class, unless the first
- character in the class definition is a circumflex, in which case the
- subject character must not be in the set defined by the class. If a
- circumflex is actually required as a member of the class, ensure it is
- not the first character, or escape it with a backslash.
+ For example, the character class [aeiou] matches any lower case vowel,
+ while [^aeiou] matches any character that is not a lower case vowel.
+ Note that a circumflex is just a convenient notation for specifying the
+ characters which are in the class by enumerating those that are not. It
+ is not an assertion: it still consumes a character from the subject
+ string, and fails if the current pointer is at the end of the string.
- For example, the character class [aeiou] matches any lower case vowel,
- while [^aeiou] matches any character that is not a lower case vowel.
- Note that a circumflex is just a convenient notation for specifying the
- characters which are in the class by enumerating those that are not. It
- is not an assertion: it still consumes a character from the subject
- string, and fails if the current pointer is at the end of the string.
+ In UTF-8 mode, characters with values greater than 255 can be included
+ in a class as a literal string of bytes, or by using the \x{ escaping
+ mechanism.
- In UTF-8 mode, characters with values greater than 255 can be included
- in a class as a literal string of bytes, or by using the \x{ escaping
- mechanism.
+ When caseless matching is set, any letters in a class represent both
+ their upper case and lower case versions, so for example, a caseless
+ [aeiou] matches "A" as well as "a", and a caseless [^aeiou] does not
+ match "A", whereas a caseful version would. PCRE does not support the
+ concept of case for characters with values greater than 255.
- When caseless matching is set, any letters in a class represent both
- their upper case and lower case versions, so for example, a caseless
- [aeiou] matches "A" as well as "a", and a caseless [^aeiou] does not
- match "A", whereas a caseful version would. PCRE does not support the
- concept of case for characters with values greater than 255.
+ The newline character is never treated in any special way in character
+ classes, whatever the setting of the PCRE_DOTALL or PCRE_MULTILINE
+ options is. A class such as [^a] will always match a newline.
- The newline character is never treated in any special way in character
- classes, whatever the setting of the PCRE_DOTALL or PCRE_MULTILINE
- options is. A class such as [^a] will always match a newline.
+ The minus (hyphen) character can be used to specify a range of
+ characters in a character class. For example, [d-m] matches any letter
+ between d and m, inclusive. If a minus character is required in a
+ class, it must be escaped with a backslash or appear in a position
+ where it cannot be interpreted as indicating a range, typically as the
+ first or last character in the class.
- The minus (hyphen) character can be used to specify a range of charac-
- ters in a character class. For example, [d-m] matches any letter
- between d and m, inclusive. If a minus character is required in a
- class, it must be escaped with a backslash or appear in a position
- where it cannot be interpreted as indicating a range, typically as the
- first or last character in the class.
+ It is not possible to have the literal character "]" as the end
+ character of a range. A pattern such as [W-]46] is interpreted as a
+ class of two characters ("W" and "-") followed by a literal string
+ "46]", so it would match "W46]" or "-46]". However, if the "]" is
+ escaped with a backslash it is interpreted as the end of range, so
+ [W-\]46] is interpreted as a single class containing a range followed
+ by two separate characters. The octal or hexadecimal representation of
+ "]" can also be used to end a range.
- It is not possible to have the literal character "]" as the end charac-
- ter of a range. A pattern such as [W-]46] is interpreted as a class of
- two characters ("W" and "-") followed by a literal string "46]", so it
- would match "W46]" or "-46]". However, if the "]" is escaped with a
- backslash it is interpreted as the end of range, so [W-\]46] is inter-
- preted as a single class containing a range followed by two separate
- characters. The octal or hexadecimal representation of "]" can also be
- used to end a range.
+ Ranges operate in the collating sequence of character values. They can
+ also be used for characters specified numerically, for example
+ [\000-\037]. In UTF-8 mode, ranges can include characters whose values
+ are greater than 255, for example [\x{100}-\x{2ff}].
- Ranges operate in the collating sequence of character values. They can
- also be used for characters specified numerically, for example
- [\000-\037]. In UTF-8 mode, ranges can include characters whose values
- are greater than 255, for example [\x{100}-\x{2ff}].
+ If a range that includes letters is used when caseless matching is set,
+ it matches the letters in either case. For example, [W-c] is equivalent
+ to [][\^_`wxyzabc], matched caselessly, and if character tables for the
+ "fr" locale are in use, [\xc8-\xcb] matches accented E characters in
+ both cases.
- If a range that includes letters is used when caseless matching is set,
- it matches the letters in either case. For example, [W-c] is equivalent
- to [][\^_`wxyzabc], matched caselessly, and if character tables for the
- "fr" locale are in use, [\xc8-\xcb] matches accented E characters in
- both cases.
+ The character types \d, \D, \s, \S, \w, and \W may also appear in a
+ character class, and add the characters that they match to the class.
+ For example, [\dABCDEF] matches any hexadecimal digit. A circumflex can
+ conveniently be used with the upper case character types to specify a
+ more restricted set of characters than the matching lower case type.
+ For example, the class [^\W_] matches any letter or digit, but not
+ underscore.
- The character types \d, \D, \s, \S, \w, and \W may also appear in a
- character class, and add the characters that they match to the class.
- For example, [\dABCDEF] matches any hexadecimal digit. A circumflex can
- conveniently be used with the upper case character types to specify a
- more restricted set of characters than the matching lower case type.
- For example, the class [^\W_] matches any letter or digit, but not
- underscore.
-
- All non-alphameric characters other than \, -, ^ (at the start) and the
- terminating ] are non-special in character classes, but it does no harm
- if they are escaped.
-
+ All non-alphameric characters other than \, -, ^ (at the start) and the
+ terminating ] are non-special in character classes, but it does no harm
+ if they are escaped.
POSIX CHARACTER CLASSES
-
- Perl supports the POSIX notation for character classes, which uses
- names enclosed by [: and :] within the enclosing square brackets. PCRE
- also supports this notation. For example,
+ Perl supports the POSIX notation for character classes, which uses
+ names enclosed by [: and :] within the enclosing square brackets. PCRE
+ also supports this notation. For example,
[01[:alpha:]%]
- matches "0", "1", any alphabetic character, or "%". The supported class
- names are
+ matches "0", "1", any alphabetic character, or "%". The supported class
+ names are
alnum letters and digits
alpha letters
@@ -462,168 +447,158 @@
word "word" characters (same as \w)
xdigit hexadecimal digits
- The "space" characters are HT (9), LF (10), VT (11), FF (12), CR (13),
- and space (32). Notice that this list includes the VT character (code
- 11). This makes "space" different to \s, which does not include VT (for
- Perl compatibility).
+ The "space" characters are HT (9), LF (10), VT (11), FF (12), CR (13),
+ and space (32). Notice that this list includes the VT character (code
+ 11). This makes "space" different to \s, which does not include VT (for
+ Perl compatibility).
- The name "word" is a Perl extension, and "blank" is a GNU extension
- from Perl 5.8. Another Perl extension is negation, which is indicated
- by a ^ character after the colon. For example,
+ The name "word" is a Perl extension, and "blank" is a GNU extension
+ from Perl 5.8. Another Perl extension is negation, which is indicated
+ by a ^ character after the colon. For example,
[12[:^digit:]]
- matches "1", "2", or any non-digit. PCRE (and Perl) also recognize the
- POSIX syntax [.ch.] and [=ch=] where "ch" is a "collating element", but
- these are not supported, and an error is given if they are encountered.
+ matches "1", "2", or any non-digit. PCRE (and Perl) also recognize the
+ POSIX syntax [.ch.] and [=ch=] where "ch" is a "collating element", but
+ these are not supported, and an error is given if they are encountered.
- In UTF-8 mode, characters with values greater than 255 do not match any
- of the POSIX character classes.
-
+ In UTF-8 mode, characters with values greater than 255 do not match any
+ of the POSIX character classes.
VERTICAL BAR
-
- Vertical bar characters are used to separate alternative patterns. For
- example, the pattern
+ Vertical bar characters are used to separate alternative patterns. For
+ example, the pattern
gilbert|sullivan
- matches either "gilbert" or "sullivan". Any number of alternatives may
- appear, and an empty alternative is permitted (matching the empty
- string). The matching process tries each alternative in turn, from
- left to right, and the first one that succeeds is used. If the alterna-
- tives are within a subpattern (defined below), "succeeds" means match-
- ing the rest of the main pattern as well as the alternative in the sub-
- pattern.
-
+ matches either "gilbert" or "sullivan". Any number of alternatives may
+ appear, and an empty alternative is permitted (matching the empty
+ string). The matching process tries each alternative in turn, from
+ left to right, and the first one that succeeds is used. If the
+ alternatives are within a subpattern (defined below), "succeeds" means
+ matching the rest of the main pattern as well as the alternative in the
+ subpattern.
INTERNAL OPTION SETTING
-
- The settings of the PCRE_CASELESS, PCRE_MULTILINE, PCRE_DOTALL, and
- PCRE_EXTENDED options can be changed from within the pattern by a
- sequence of Perl option letters enclosed between "(?" and ")". The
- option letters are
+ The settings of the PCRE_CASELESS, PCRE_MULTILINE, PCRE_DOTALL, and
+ PCRE_EXTENDED options can be changed from within the pattern by a
+ sequence of Perl option letters enclosed between "(?" and ")". The
+ option letters are
i for PCRE_CASELESS
m for PCRE_MULTILINE
s for PCRE_DOTALL
x for PCRE_EXTENDED
- For example, (?im) sets caseless, multiline matching. It is also possi-
- ble to unset these options by preceding the letter with a hyphen, and a
- combined setting and unsetting such as (?im-sx), which sets PCRE_CASE-
- LESS and PCRE_MULTILINE while unsetting PCRE_DOTALL and PCRE_EXTENDED,
- is also permitted. If a letter appears both before and after the
- hyphen, the option is unset.
+ For example, (?im) sets caseless, multiline matching. It is also
+ possible to unset these options by preceding the letter with a hyphen,
+ and a combined setting and unsetting such as (?im-sx), which sets
+ PCRE_CASELESS and PCRE_MULTILINE while unsetting PCRE_DOTALL and
+ PCRE_EXTENDED, is also permitted. If a letter appears both before and
+ after the hyphen, the option is unset.
- When an option change occurs at top level (that is, not inside subpat-
- tern parentheses), the change applies to the remainder of the pattern
- that follows. If the change is placed right at the start of a pattern,
- PCRE extracts it into the global options (and it will therefore show up
- in data extracted by the pcre_fullinfo() function).
+ When an option change occurs at top level (that is, not inside
+ subpattern parentheses), the change applies to the remainder of the
+ pattern that follows. If the change is placed right at the start of a
+ pattern, PCRE extracts it into the global options (and it will
+ therefore show up in data extracted by the pcre_fullinfo() function).
- An option change within a subpattern affects only that part of the cur-
- rent pattern that follows it, so
+ An option change within a subpattern affects only that part of the
+ current pattern that follows it, so
(a(?i)b)c
- matches abc and aBc and no other strings (assuming PCRE_CASELESS is not
- used). By this means, options can be made to have different settings
- in different parts of the pattern. Any changes made in one alternative
- do carry on into subsequent branches within the same subpattern. For
- example,
+ matches abc and aBc and no other strings (assuming PCRE_CASELESS is not
+ used). By this means, options can be made to have different settings
+ in different parts of the pattern. Any changes made in one alternative
+ do carry on into subsequent branches within the same subpattern. For
+ example,
(a(?i)b|c)
- matches "ab", "aB", "c", and "C", even though when matching "C" the
- first branch is abandoned before the option setting. This is because
- the effects of option settings happen at compile time. There would be
- some very weird behaviour otherwise.
+ matches "ab", "aB", "c", and "C", even though when matching "C" the
+ first branch is abandoned before the option setting. This is because
+ the effects of option settings happen at compile time. There would be
+ some very weird behaviour otherwise.
- The PCRE-specific options PCRE_UNGREEDY and PCRE_EXTRA can be changed
- in the same way as the Perl-compatible options by using the characters
- U and X respectively. The (?X) flag setting is special in that it must
- always occur earlier in the pattern than any of the additional features
- it turns on, even when it is at top level. It is best put at the start.
-
+ The PCRE-specific options PCRE_UNGREEDY and PCRE_EXTRA can be changed
+ in the same way as the Perl-compatible options by using the characters
+ U and X respectively. The (?X) flag setting is special in that it must
+ always occur earlier in the pattern than any of the additional features
+ it turns on, even when it is at top level. It is best put at the start.
SUBPATTERNS
+ Subpatterns are delimited by parentheses (round brackets), which can be
+ nested. Marking part of a pattern as a subpattern does two things:
- Subpatterns are delimited by parentheses (round brackets), which can be
- nested. Marking part of a pattern as a subpattern does two things:
-
- 1. It localizes a set of alternatives. For example, the pattern
+ 1. It localizes a set of alternatives. For example, the pattern
cat(aract|erpillar|)
- matches one of the words "cat", "cataract", or "caterpillar". Without
- the parentheses, it would match "cataract", "erpillar" or the empty
- string.
+ matches one of the words "cat", "cataract", or "caterpillar". Without
+ the parentheses, it would match "cataract", "erpillar" or the empty
+ string.
- 2. It sets up the subpattern as a capturing subpattern (as defined
- above). When the whole pattern matches, that portion of the subject
- string that matched the subpattern is passed back to the caller via the
- ovector argument of pcre_exec(). Opening parentheses are counted from
- left to right (starting from 1) to obtain the numbers of the capturing
- subpatterns.
+ 2. It sets up the subpattern as a capturing subpattern (as defined
+ above). When the whole pattern matches, that portion of the subject
+ string that matched the subpattern is passed back to the caller via the
+ ovector argument of pcre_exec(). Opening parentheses are counted from
+ left to right (starting from 1) to obtain the numbers of the capturing
+ subpatterns.
- For example, if the string "the red king" is matched against the pat-
- tern
+ For example, if the string "the red king" is matched against the
+ pattern
the ((red|white) (king|queen))
- the captured substrings are "red king", "red", and "king", and are num-
- bered 1, 2, and 3, respectively.
+ the captured substrings are "red king", "red", and "king", and are
+ numbered 1, 2, and 3, respectively.
- The fact that plain parentheses fulfil two functions is not always
- helpful. There are often times when a grouping subpattern is required
- without a capturing requirement. If an opening parenthesis is followed
- by a question mark and a colon, the subpattern does not do any captur-
- ing, and is not counted when computing the number of any subsequent
- capturing subpatterns. For example, if the string "the white queen" is
- matched against the pattern
+ The fact that plain parentheses fulfil two functions is not always
+ helpful. There are often times when a grouping subpattern is required
+ without a capturing requirement. If an opening parenthesis is followed
+ by a question mark and a colon, the subpattern does not do any
+ capturing, and is not counted when computing the number of any
+ subsequent capturing subpatterns. For example, if the string "the white
+ queen" is matched against the pattern
the ((?:red|white) (king|queen))
- the captured substrings are "white queen" and "queen", and are numbered
- 1 and 2. The maximum number of capturing subpatterns is 65535, and the
- maximum depth of nesting of all subpatterns, both capturing and non-
- capturing, is 200.
+ the captured substrings are "white queen" and "queen", and are numbered
+ 1 and 2. The maximum number of capturing subpatterns is 65535, and the
+ maximum depth of nesting of all subpatterns, both capturing and
+ noncapturing, is 200.
- As a convenient shorthand, if any option settings are required at the
- start of a non-capturing subpattern, the option letters may appear
- between the "?" and the ":". Thus the two patterns
+ As a convenient shorthand, if any option settings are required at the
+ start of a non-capturing subpattern, the option letters may appear
+ between the "?" and the ":". Thus the two patterns
(?i:saturday|sunday)
(?:(?i)saturday|sunday)
- match exactly the same set of strings. Because alternative branches are
- tried from left to right, and options are not reset until the end of
- the subpattern is reached, an option setting in one branch does affect
- subsequent branches, so the above patterns match "SUNDAY" as well as
- "Saturday".
-
+ match exactly the same set of strings. Because alternative branches are
+ tried from left to right, and options are not reset until the end of
+ the subpattern is reached, an option setting in one branch does affect
+ subsequent branches, so the above patterns match "SUNDAY" as well as
+ "Saturday".
NAMED SUBPATTERNS
+ Identifying capturing parentheses by number is simple, but it can be
+ very hard to keep track of the numbers in complicated regular
+ expressions. Furthermore, if an expression is modified, the numbers may
+ change. To help with the difficulty, PCRE supports the naming of
+ subpatterns, something that Perl does not provide. The Python syntax
+ (?P<name>...) is used. Names consist of alphanumeric characters and
+ underscores, and must be unique within a pattern.
- Identifying capturing parentheses by number is simple, but it can be
- very hard to keep track of the numbers in complicated regular expres-
- sions. Furthermore, if an expression is modified, the numbers may
- change. To help with the difficulty, PCRE supports the naming of sub-
- patterns, something that Perl does not provide. The Python syntax
- (?P<name>...) is used. Names consist of alphanumeric characters and
- underscores, and must be unique within a pattern.
-
- Named capturing parentheses are still allocated numbers as well as
- names. The PCRE API provides function calls for extracting the name-to-
- number translation table from a compiled pattern. For further details
- see the pcreapi documentation.
-
+ Named capturing parentheses are still allocated numbers as well as
+ names. The PCRE API provides function calls for extracting the name-to-
+ number translation table from a compiled pattern. For further details
+ see the pcreapi documentation.
REPETITION
-
- Repetition is specified by quantifiers, which can follow any of the
- following items:
+ Repetition is specified by quantifiers, which can follow any of the
+ following items:
a literal data character
the . metacharacter
@@ -633,693 +608,681 @@
a back reference (see next section)
a parenthesized subpattern (unless it is an assertion)
- The general repetition quantifier specifies a minimum and maximum num-
- ber of permitted matches, by giving the two numbers in curly brackets
- (braces), separated by a comma. The numbers must be less than 65536,
- and the first must be less than or equal to the second. For example:
+ The general repetition quantifier specifies a minimum and maximum
+ number of permitted matches, by giving the two numbers in curly
+ brackets (braces), separated by a comma. The numbers must be less than
+ 65536, and the first must be less than or equal to the second. For
+ example:
z{2,4}
- matches "zz", "zzz", or "zzzz". A closing brace on its own is not a
- special character. If the second number is omitted, but the comma is
- present, there is no upper limit; if the second number and the comma
- are both omitted, the quantifier specifies an exact number of required
- matches. Thus
+ matches "zz", "zzz", or "zzzz". A closing brace on its own is not a
+ special character. If the second number is omitted, but the comma is
+ present, there is no upper limit; if the second number and the comma
+ are both omitted, the quantifier specifies an exact number of required
+ matches. Thus
[aeiou]{3,}
- matches at least 3 successive vowels, but may match many more, while
+ matches at least 3 successive vowels, but may match many more, while
\d{8}
- matches exactly 8 digits. An opening curly bracket that appears in a
- position where a quantifier is not allowed, or one that does not match
- the syntax of a quantifier, is taken as a literal character. For exam-
- ple, {,6} is not a quantifier, but a literal string of four characters.
+ matches exactly 8 digits. An opening curly bracket that appears in a
+ position where a quantifier is not allowed, or one that does not match
+ the syntax of a quantifier, is taken as a literal character. For
+ example, {,6} is not a quantifier, but a literal string of four
+ characters.
- In UTF-8 mode, quantifiers apply to UTF-8 characters rather than to
- individual bytes. Thus, for example, \x{100}{2} matches two UTF-8 char-
- acters, each of which is represented by a two-byte sequence.
+ In UTF-8 mode, quantifiers apply to UTF-8 characters rather than to
+ individual bytes. Thus, for example, \x{100}{2} matches two UTF-8
+ characters, each of which is represented by a two-byte sequence.
- The quantifier {0} is permitted, causing the expression to behave as if
- the previous item and the quantifier were not present.
+ The quantifier {0} is permitted, causing the expression to behave as if
+ the previous item and the quantifier were not present.
- For convenience (and historical compatibility) the three most common
- quantifiers have single-character abbreviations:
+ For convenience (and historical compatibility) the three most common
+ quantifiers have single-character abbreviations:
* is equivalent to {0,}
+ is equivalent to {1,}
? is equivalent to {0,1}
- It is possible to construct infinite loops by following a subpattern
- that can match no characters with a quantifier that has no upper limit,
- for example:
+ It is possible to construct infinite loops by following a subpattern
+ that can match no characters with a quantifier that has no upper limit,
+ for example:
(a?)*
- Earlier versions of Perl and PCRE used to give an error at compile time
- for such patterns. However, because there are cases where this can be
- useful, such patterns are now accepted, but if any repetition of the
- subpattern does in fact match no characters, the loop is forcibly bro-
- ken.
+ Earlier versions of Perl and PCRE used to give an error at compile time
+ for such patterns. However, because there are cases where this can be
+ useful, such patterns are now accepted, but if any repetition of the
+ subpattern does in fact match no characters, the loop is forcibly
+ broken.
- By default, the quantifiers are "greedy", that is, they match as much
- as possible (up to the maximum number of permitted times), without
- causing the rest of the pattern to fail. The classic example of where
- this gives problems is in trying to match comments in C programs. These
- appear between the sequences /* and */ and within the sequence, indi-
- vidual * and / characters may appear. An attempt to match C comments by
- applying the pattern
+ By default, the quantifiers are "greedy", that is, they match as much
+ as possible (up to the maximum number of permitted times), without
+ causing the rest of the pattern to fail. The classic example of where
+ this gives problems is in trying to match comments in C programs. These
+ appear between the sequences /* and */ and within the sequence,
+ individual * and / characters may appear. An attempt to match C
+ comments by applying the pattern
/\*.*\*/
- to the string
+ to the string
- /* first command */ not comment /* second comment */
+ /* first command */ not comment /* second comment */
- fails, because it matches the entire string owing to the greediness of
- the .* item.
+ fails, because it matches the entire string owing to the greediness of
+ the .* item.
- However, if a quantifier is followed by a question mark, it ceases to
- be greedy, and instead matches the minimum number of times possible, so
- the pattern
+ However, if a quantifier is followed by a question mark, it ceases to
+ be greedy, and instead matches the minimum number of times possible, so
+ the pattern
/\*.*?\*/
- does the right thing with the C comments. The meaning of the various
- quantifiers is not otherwise changed, just the preferred number of
- matches. Do not confuse this use of question mark with its use as a
- quantifier in its own right. Because it has two uses, it can sometimes
- appear doubled, as in
+ does the right thing with the C comments. The meaning of the various
+ quantifiers is not otherwise changed, just the preferred number of
+ matches. Do not confuse this use of question mark with its use as a
+ quantifier in its own right. Because it has two uses, it can sometimes
+ appear doubled, as in
\d??\d
- which matches one digit by preference, but can match two if that is the
- only way the rest of the pattern matches.
+ which matches one digit by preference, but can match two if that is the
+ only way the rest of the pattern matches.
- If the PCRE_UNGREEDY option is set (an option which is not available in
- Perl), the quantifiers are not greedy by default, but individual ones
- can be made greedy by following them with a question mark. In other
- words, it inverts the default behaviour.
+ If the PCRE_UNGREEDY option is set (an option which is not available in
+ Perl), the quantifiers are not greedy by default, but individual ones
+ can be made greedy by following them with a question mark. In other
+ words, it inverts the default behaviour.
- When a parenthesized subpattern is quantified with a minimum repeat
- count that is greater than 1 or with a limited maximum, more store is
- required for the compiled pattern, in proportion to the size of the
- minimum or maximum.
+ When a parenthesized subpattern is quantified with a minimum repeat
+ count that is greater than 1 or with a limited maximum, more store is
+ required for the compiled pattern, in proportion to the size of the
+ minimum or maximum.
- If a pattern starts with .* or .{0,} and the PCRE_DOTALL option (equiv-
- alent to Perl's /s) is set, thus allowing the . to match newlines, the
- pattern is implicitly anchored, because whatever follows will be tried
- against every character position in the subject string, so there is no
- point in retrying the overall match at any position after the first.
- PCRE normally treats such a pattern as though it were preceded by \A.
+ If a pattern starts with .* or .{0,} and the PCRE_DOTALL option
+ (equivalent to Perl's /s) is set, thus allowing the . to match
+ newlines, the pattern is implicitly anchored, because whatever follows
+ will be tried against every character position in the subject string,
+ so there is no point in retrying the overall match at any position
+ after the first. PCRE normally treats such a pattern as though it were
+ preceded by \A.
- In cases where it is known that the subject string contains no new-
- lines, it is worth setting PCRE_DOTALL in order to obtain this opti-
- mization, or alternatively using ^ to indicate anchoring explicitly.
+ In cases where it is known that the subject string contains no
+ newlines, it is worth setting PCRE_DOTALL in order to obtain this
+ optimization, or alternatively using ^ to indicate anchoring
+ explicitly.
- However, there is one situation where the optimization cannot be used.
- When .* is inside capturing parentheses that are the subject of a
- backreference elsewhere in the pattern, a match at the start may fail,
- and a later one succeed. Consider, for example:
+ However, there is one situation where the optimization cannot be used.
+ When .* is inside capturing parentheses that are the subject of a
+ backreference elsewhere in the pattern, a match at the start may fail,
+ and a later one succeed. Consider, for example:
(.*)abc\1
- If the subject is "xyz123abc123" the match point is the fourth charac-
- ter. For this reason, such a pattern is not implicitly anchored.
+ If the subject is "xyz123abc123" the match point is the fourth
+ character. For this reason, such a pattern is not implicitly anchored.
- When a capturing subpattern is repeated, the value captured is the sub-
- string that matched the final iteration. For example, after
+ When a capturing subpattern is repeated, the value captured is the
+ substring that matched the final iteration. For example, after
(tweedle[dume]{3}\s*)+
- has matched "tweedledum tweedledee" the value of the captured substring
- is "tweedledee". However, if there are nested capturing subpatterns,
- the corresponding captured values may have been set in previous itera-
- tions. For example, after
+ has matched "tweedledum tweedledee" the value of the captured substring
+ is "tweedledee". However, if there are nested capturing subpatterns,
+ the corresponding captured values may have been set in previous
+ iterations. For example, after
/(a|(b))+/
- matches "aba" the value of the second captured substring is "b".
-
+ matches "aba" the value of the second captured substring is "b".
ATOMIC GROUPING AND POSSESSIVE QUANTIFIERS
+ With both maximizing and minimizing repetition, failure of what follows
+ normally causes the repeated item to be re-evaluated to see if a
+ different number of repeats allows the rest of the pattern to match.
+ Sometimes it is useful to prevent this, either to change the nature of
+ the match, or to cause it fail earlier than it otherwise might, when
+ the author of the pattern knows there is no point in carrying on.
- With both maximizing and minimizing repetition, failure of what follows
- normally causes the repeated item to be re-evaluated to see if a dif-
- ferent number of repeats allows the rest of the pattern to match. Some-
- times it is useful to prevent this, either to change the nature of the
- match, or to cause it fail earlier than it otherwise might, when the
- author of the pattern knows there is no point in carrying on.
-
- Consider, for example, the pattern \d+foo when applied to the subject
- line
+ Consider, for example, the pattern \d+foo when applied to the subject
+ line
123456bar
- After matching all 6 digits and then failing to match "foo", the normal
- action of the matcher is to try again with only 5 digits matching the
- \d+ item, and then with 4, and so on, before ultimately failing.
- "Atomic grouping" (a term taken from Jeffrey Friedl's book) provides
- the means for specifying that once a subpattern has matched, it is not
- to be re-evaluated in this way.
+ After matching all 6 digits and then failing to match "foo", the normal
+ action of the matcher is to try again with only 5 digits matching the
+ \d+ item, and then with 4, and so on, before ultimately failing.
+ "Atomic grouping" (a term taken from Jeffrey Friedl's book) provides
+ the means for specifying that once a subpattern has matched, it is not
+ to be re-evaluated in this way.
- If we use atomic grouping for the previous example, the matcher would
- give up immediately on failing to match "foo" the first time. The nota-
- tion is a kind of special parenthesis, starting with (?> as in this
- example:
+ If we use atomic grouping for the previous example, the matcher would
+ give up immediately on failing to match "foo" the first time. The
+ notation is a kind of special parenthesis, starting with (?> as in this
+ example:
(?>\d+)foo
- This kind of parenthesis "locks up" the part of the pattern it con-
- tains once it has matched, and a failure further into the pattern is
- prevented from backtracking into it. Backtracking past it to previous
- items, however, works as normal.
+ This kind of parenthesis "locks up" the part of the pattern it
+ contains once it has matched, and a failure further into the pattern is
+ prevented from backtracking into it. Backtracking past it to previous
+ items, however, works as normal.
- An alternative description is that a subpattern of this type matches
- the string of characters that an identical standalone pattern would
- match, if anchored at the current point in the subject string.
+ An alternative description is that a subpattern of this type matches
+ the string of characters that an identical standalone pattern would
+ match, if anchored at the current point in the subject string.
- Atomic grouping subpatterns are not capturing subpatterns. Simple cases
- such as the above example can be thought of as a maximizing repeat that
- must swallow everything it can. So, while both \d+ and \d+? are pre-
- pared to adjust the number of digits they match in order to make the
- rest of the pattern match, (?>\d+) can only match an entire sequence of
- digits.
+ Atomic grouping subpatterns are not capturing subpatterns. Simple cases
+ such as the above example can be thought of as a maximizing repeat that
+ must swallow everything it can. So, while both \d+ and \d+? are
+ prepared to adjust the number of digits they match in order to make the
+ rest of the pattern match, (?>\d+) can only match an entire sequence of
+ digits.
- Atomic groups in general can of course contain arbitrarily complicated
- subpatterns, and can be nested. However, when the subpattern for an
- atomic group is just a single repeated item, as in the example above, a
- simpler notation, called a "possessive quantifier" can be used. This
- consists of an additional + character following a quantifier. Using
- this notation, the previous example can be rewritten as
+ Atomic groups in general can of course contain arbitrarily complicated
+ subpatterns, and can be nested. However, when the subpattern for an
+ atomic group is just a single repeated item, as in the example above, a
+ simpler notation, called a "possessive quantifier" can be used. This
+ consists of an additional + character following a quantifier. Using
+ this notation, the previous example can be rewritten as
\d++bar
- Possessive quantifiers are always greedy; the setting of the
- PCRE_UNGREEDY option is ignored. They are a convenient notation for the
- simpler forms of atomic group. However, there is no difference in the
- meaning or processing of a possessive quantifier and the equivalent
- atomic group.
+ Possessive quantifiers are always greedy; the setting of the
+ PCRE_UNGREEDY option is ignored. They are a convenient notation for the
+ simpler forms of atomic group. However, there is no difference in the
+ meaning or processing of a possessive quantifier and the equivalent
+ atomic group.
- The possessive quantifier syntax is an extension to the Perl syntax. It
- originates in Sun's Java package.
+ The possessive quantifier syntax is an extension to the Perl syntax. It
+ originates in Sun's Java package.
- When a pattern contains an unlimited repeat inside a subpattern that
- can itself be repeated an unlimited number of times, the use of an
- atomic group is the only way to avoid some failing matches taking a
- very long time indeed. The pattern
+ When a pattern contains an unlimited repeat inside a subpattern that
+ can itself be repeated an unlimited number of times, the use of an
+ atomic group is the only way to avoid some failing matches taking a
+ very long time indeed. The pattern
(\D+|<\d+>)*[!?]
- matches an unlimited number of substrings that either consist of non-
- digits, or digits enclosed in <>, followed by either ! or ?. When it
- matches, it runs quickly. However, if it is applied to
+ matches an unlimited number of substrings that either consist of non-
+ digits, or digits enclosed in <>, followed by either ! or ?. When it
+ matches, it runs quickly. However, if it is applied to
aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
- it takes a long time before reporting failure. This is because the
- string can be divided between the two repeats in a large number of
- ways, and all have to be tried. (The example used [!?] rather than a
- single character at the end, because both PCRE and Perl have an opti-
- mization that allows for fast failure when a single character is used.
- They remember the last single character that is required for a match,
- and fail early if it is not present in the string.) If the pattern is
- changed to
+ it takes a long time before reporting failure. This is because the
+ string can be divided between the two repeats in a large number of
+ ways, and all have to be tried. (The example used [!?] rather than a
+ single character at the end, because both PCRE and Perl have an
+ optimization that allows for fast failure when a single character is
+ used. They remember the last single character that is required for a
+ match, and fail early if it is not present in the string.) If the
+ pattern is changed to
((?>\D+)|<\d+>)*[!?]
- sequences of non-digits cannot be broken, and failure happens quickly.
-
+ sequences of non-digits cannot be broken, and failure happens quickly.
BACK REFERENCES
+ Outside a character class, a backslash followed by a digit greater than
+ 0 (and possibly further digits) is a back reference to a capturing
+ subpattern earlier (that is, to its left) in the pattern, provided
+ there have been that many previous capturing left parentheses.
- Outside a character class, a backslash followed by a digit greater than
- 0 (and possibly further digits) is a back reference to a capturing sub-
- pattern earlier (that is, to its left) in the pattern, provided there
- have been that many previous capturing left parentheses.
+ However, if the decimal number following the backslash is less than 10,
+ it is always taken as a back reference, and causes an error only if
+ there are not that many capturing left parentheses in the entire
+ pattern. In other words, the parentheses that are referenced need not
+ be to the left of the reference for numbers less than 10. See the
+ section entitled "Backslash" above for further details of the handling
+ of digits following a backslash.
- However, if the decimal number following the backslash is less than 10,
- it is always taken as a back reference, and causes an error only if
- there are not that many capturing left parentheses in the entire pat-
- tern. In other words, the parentheses that are referenced need not be
- to the left of the reference for numbers less than 10. See the section
- entitled "Backslash" above for further details of the handling of dig-
- its following a backslash.
-
- A back reference matches whatever actually matched the capturing sub-
- pattern in the current subject string, rather than anything matching
- the subpattern itself (see "Subpatterns as subroutines" below for a way
- of doing that). So the pattern
+ A back reference matches whatever actually matched the capturing
+ subpattern in the current subject string, rather than anything matching
+ the subpattern itself (see "Subpatterns as subroutines" below for a way
+ of doing that). So the pattern
(sens|respons)e and \1ibility
- matches "sense and sensibility" and "response and responsibility", but
- not "sense and responsibility". If caseful matching is in force at the
- time of the back reference, the case of letters is relevant. For exam-
- ple,
+ matches "sense and sensibility" and "response and responsibility", but
+ not "sense and responsibility". If caseful matching is in force at the
+ time of the back reference, the case of letters is relevant. For
+ example,
((?i)rah)\s+\1
- matches "rah rah" and "RAH RAH", but not "RAH rah", even though the
- original capturing subpattern is matched caselessly.
+ matches "rah rah" and "RAH RAH", but not "RAH rah", even though the
+ original capturing subpattern is matched caselessly.
- Back references to named subpatterns use the Python syntax (?P=name).
- We could rewrite the above example as follows:
+ Back references to named subpatterns use the Python syntax (?P=name).
+ We could rewrite the above example as follows:
(?<p1>(?i)rah)\s+(?P=p1)
- There may be more than one back reference to the same subpattern. If a
- subpattern has not actually been used in a particular match, any back
- references to it always fail. For example, the pattern
+ There may be more than one back reference to the same subpattern. If a
+ subpattern has not actually been used in a particular match, any back
+ references to it always fail. For example, the pattern
(a|(bc))\2
- always fails if it starts to match "a" rather than "bc". Because there
- may be many capturing parentheses in a pattern, all digits following
- the backslash are taken as part of a potential back reference number.
- If the pattern continues with a digit character, some delimiter must be
- used to terminate the back reference. If the PCRE_EXTENDED option is
- set, this can be whitespace. Otherwise an empty comment can be used.
+ always fails if it starts to match "a" rather than "bc". Because there
+ may be many capturing parentheses in a pattern, all digits following
+ the backslash are taken as part of a potential back reference number.
+ If the pattern continues with a digit character, some delimiter must be
+ used to terminate the back reference. If the PCRE_EXTENDED option is
+ set, this can be whitespace. Otherwise an empty comment can be used.
- A back reference that occurs inside the parentheses to which it refers
- fails when the subpattern is first used, so, for example, (a\1) never
- matches. However, such references can be useful inside repeated sub-
- patterns. For example, the pattern
+ A back reference that occurs inside the parentheses to which it refers
+ fails when the subpattern is first used, so, for example, (a\1) never
+ matches. However, such references can be useful inside repeated
+ subpatterns. For example, the pattern
(a|b\1)+
- matches any number of "a"s and also "aba", "ababbaa" etc. At each iter-
- ation of the subpattern, the back reference matches the character
- string corresponding to the previous iteration. In order for this to
- work, the pattern must be such that the first iteration does not need
- to match the back reference. This can be done using alternation, as in
- the example above, or by a quantifier with a minimum of zero.
-
+ matches any number of "a"s and also "aba", "ababbaa" etc. At each
+ iteration of the subpattern, the back reference matches the character
+ string corresponding to the previous iteration. In order for this to
+ work, the pattern must be such that the first iteration does not need
+ to match the back reference. This can be done using alternation, as in
+ the example above, or by a quantifier with a minimum of zero.
ASSERTIONS
+ An assertion is a test on the characters following or preceding the
+ current matching point that does not actually consume any characters.
+ The simple assertions coded as \b, \B, \A, \G, \Z, \z, ^ and $ are
+ described above. More complicated assertions are coded as subpatterns.
+ There are two kinds: those that look ahead of the current position in
+ the subject string, and those that look behind it.
- An assertion is a test on the characters following or preceding the
- current matching point that does not actually consume any characters.
- The simple assertions coded as \b, \B, \A, \G, \Z, \z, ^ and $ are
- described above. More complicated assertions are coded as subpatterns.
- There are two kinds: those that look ahead of the current position in
- the subject string, and those that look behind it.
-
- An assertion subpattern is matched in the normal way, except that it
- does not cause the current matching position to be changed. Lookahead
- assertions start with (?= for positive assertions and (?! for negative
- assertions. For example,
+ An assertion subpattern is matched in the normal way, except that it
+ does not cause the current matching position to be changed. Lookahead
+ assertions start with (?= for positive assertions and (?! for negative
+ assertions. For example,
\w+(?=;)
- matches a word followed by a semicolon, but does not include the semi-
- colon in the match, and
+ matches a word followed by a semicolon, but does not include the
+ semicolon in the match, and
foo(?!bar)
- matches any occurrence of "foo" that is not followed by "bar". Note
- that the apparently similar pattern
+ matches any occurrence of "foo" that is not followed by "bar". Note
+ that the apparently similar pattern
(?!foo)bar
- does not find an occurrence of "bar" that is preceded by something
- other than "foo"; it finds any occurrence of "bar" whatsoever, because
- the assertion (?!foo) is always true when the next three characters are
- "bar". A lookbehind assertion is needed to achieve this effect.
+ does not find an occurrence of "bar" that is preceded by something
+ other than "foo"; it finds any occurrence of "bar" whatsoever, because
+ the assertion (?!foo) is always true when the next three characters are
+ "bar". A lookbehind assertion is needed to achieve this effect.
- If you want to force a matching failure at some point in a pattern, the
- most convenient way to do it is with (?!) because an empty string
- always matches, so an assertion that requires there not to be an empty
- string must always fail.
+ If you want to force a matching failure at some point in a pattern, the
+ most convenient way to do it is with (?!) because an empty string
+ always matches, so an assertion that requires there not to be an empty
+ string must always fail.
- Lookbehind assertions start with (?<= for positive assertions and (?<!
- for negative assertions. For example,
+ Lookbehind assertions start with (?<= for positive assertions and (?<!
+ for negative assertions. For example,
(?<!foo)bar
- does find an occurrence of "bar" that is not preceded by "foo". The
- contents of a lookbehind assertion are restricted such that all the
- strings it matches must have a fixed length. However, if there are sev-
- eral alternatives, they do not all have to have the same fixed length.
- Thus
+ does find an occurrence of "bar" that is not preceded by "foo". The
+ contents of a lookbehind assertion are restricted such that all the
+ strings it matches must have a fixed length. However, if there are
+ several alternatives, they do not all have to have the same fixed
+ length. Thus
(?<=bullock|donkey)
- is permitted, but
+ is permitted, but
(?<!dogs?|cats?)
- causes an error at compile time. Branches that match different length
- strings are permitted only at the top level of a lookbehind assertion.
- This is an extension compared with Perl (at least for 5.8), which
- requires all branches to match the same length of string. An assertion
- such as
+ causes an error at compile time. Branches that match different length
+ strings are permitted only at the top level of a lookbehind assertion.
+ This is an extension compared with Perl (at least for 5.8), which
+ requires all branches to match the same length of string. An assertion
+ such as
(?<=ab(c|de))
- is not permitted, because its single top-level branch can match two
- different lengths, but it is acceptable if rewritten to use two top-
- level branches:
+ is not permitted, because its single top-level branch can match two
+ different lengths, but it is acceptable if rewritten to use two top-
+ level branches:
(?<=abc|abde)
- The implementation of lookbehind assertions is, for each alternative,
- to temporarily move the current position back by the fixed width and
- then try to match. If there are insufficient characters before the cur-
- rent position, the match is deemed to fail.
+ The implementation of lookbehind assertions is, for each alternative,
+ to temporarily move the current position back by the fixed width and
+ then try to match. If there are insufficient characters before the
+ current position, the match is deemed to fail.
- PCRE does not allow the \C escape (which matches a single byte in UTF-8
- mode) to appear in lookbehind assertions, because it makes it impossi-
- ble to calculate the length of the lookbehind.
+ PCRE does not allow the \C escape (which matches a single byte in UTF-8
+ mode) to appear in lookbehind assertions, because it makes it
+ impossible to calculate the length of the lookbehind.
- Atomic groups can be used in conjunction with lookbehind assertions to
- specify efficient matching at the end of the subject string. Consider a
- simple pattern such as
+ Atomic groups can be used in conjunction with lookbehind assertions to
+ specify efficient matching at the end of the subject string. Consider a
+ simple pattern such as
abcd$
- when applied to a long string that does not match. Because matching
- proceeds from left to right, PCRE will look for each "a" in the subject
- and then see if what follows matches the rest of the pattern. If the
- pattern is specified as
+ when applied to a long string that does not match. Because matching
+ proceeds from left to right, PCRE will look for each "a" in the subject
+ and then see if what follows matches the rest of the pattern. If the
+ pattern is specified as
^.*abcd$
- the initial .* matches the entire string at first, but when this fails
- (because there is no following "a"), it backtracks to match all but the
- last character, then all but the last two characters, and so on. Once
- again the search for "a" covers the entire string, from right to left,
- so we are no better off. However, if the pattern is written as
+ the initial .* matches the entire string at first, but when this fails
+ (because there is no following "a"), it backtracks to match all but the
+ last character, then all but the last two characters, and so on. Once
+ again the search for "a" covers the entire string, from right to left,
+ so we are no better off. However, if the pattern is written as
^(?>.*)(?<=abcd)
- or, equivalently,
+ or, equivalently,
^.*+(?<=abcd)
- there can be no backtracking for the .* item; it can match only the
- entire string. The subsequent lookbehind assertion does a single test
- on the last four characters. If it fails, the match fails immediately.
- For long strings, this approach makes a significant difference to the
- processing time.
+ there can be no backtracking for the .* item; it can match only the
+ entire string. The subsequent lookbehind assertion does a single test
+ on the last four characters. If it fails, the match fails immediately.
+ For long strings, this approach makes a significant difference to the
+ processing time.
- Several assertions (of any sort) may occur in succession. For example,
+ Several assertions (of any sort) may occur in succession. For example,
(?<=\d{3})(?<!999)foo
- matches "foo" preceded by three digits that are not "999". Notice that
- each of the assertions is applied independently at the same point in
- the subject string. First there is a check that the previous three
- characters are all digits, and then there is a check that the same
- three characters are not "999". This pattern does not match "foo" pre-
- ceded by six characters, the first of which are digits and the last
- three of which are not "999". For example, it doesn't match "123abc-
- foo". A pattern to do that is
+ matches "foo" preceded by three digits that are not "999". Notice that
+ each of the assertions is applied independently at the same point in
+ the subject string. First there is a check that the previous three
+ characters are all digits, and then there is a check that the same
+ three characters are not "999". This pattern does not match "foo"
+ preceded by six characters, the first of which are digits and the last
+ three of which are not "999". For example, it doesn't match
+ "123abcfoo". A pattern to do that is
(?<=\d{3}...)(?<!999)foo
- This time the first assertion looks at the preceding six characters,
- checking that the first three are digits, and then the second assertion
- checks that the preceding three characters are not "999".
+ This time the first assertion looks at the preceding six characters,
+ checking that the first three are digits, and then the second assertion
+ checks that the preceding three characters are not "999".
- Assertions can be nested in any combination. For example,
+ Assertions can be nested in any combination. For example,
(?<=(?<!foo)bar)baz
- matches an occurrence of "baz" that is preceded by "bar" which in turn
- is not preceded by "foo", while
+ matches an occurrence of "baz" that is preceded by "bar" which in turn
+ is not preceded by "foo", while
(?<=\d{3}(?!999)...)foo
- is another pattern which matches "foo" preceded by three digits and any
- three characters that are not "999".
+ is another pattern which matches "foo" preceded by three digits and any
+ three characters that are not "999".
- Assertion subpatterns are not capturing subpatterns, and may not be
- repeated, because it makes no sense to assert the same thing several
- times. If any kind of assertion contains capturing subpatterns within
- it, these are counted for the purposes of numbering the capturing sub-
- patterns in the whole pattern. However, substring capturing is carried
- out only for positive assertions, because it does not make sense for
- negative assertions.
-
+ Assertion subpatterns are not capturing subpatterns, and may not be
+ repeated, because it makes no sense to assert the same thing several
+ times. If any kind of assertion contains capturing subpatterns within
+ it, these are counted for the purposes of numbering the capturing
+ subpatterns in the whole pattern. However, substring capturing is
+ carried out only for positive assertions, because it does not make
+ sense for negative assertions.
CONDITIONAL SUBPATTERNS
-
- It is possible to cause the matching process to obey a subpattern con-
- ditionally or to choose between two alternative subpatterns, depending
- on the result of an assertion, or whether a previous capturing
- subpattern matched or not. The two possible forms of conditional sub-
- pattern are
+ It is possible to cause the matching process to obey a subpattern
+ conditionally or to choose between two alternative subpatterns,
+ depending on the result of an assertion, or whether a previous
+ capturing subpattern matched or not. The two possible forms of
+ conditional subpattern are
(?(condition)yes-pattern)
(?(condition)yes-pattern|no-pattern)
- If the condition is satisfied, the yes-pattern is used; otherwise the
- no-pattern (if present) is used. If there are more than two alterna-
- tives in the subpattern, a compile-time error occurs.
+ If the condition is satisfied, the yes-pattern is used; otherwise the
+ no-pattern (if present) is used. If there are more than two
+ alternatives in the subpattern, a compile-time error occurs.
- There are three kinds of condition. If the text between the parentheses
- consists of a sequence of digits, the condition is satisfied if the
- capturing subpattern of that number has previously matched. The number
- must be greater than zero. Consider the following pattern, which con-
- tains non-significant white space to make it more readable (assume the
- PCRE_EXTENDED option) and to divide it into three parts for ease of
- discussion:
+ There are three kinds of condition. If the text between the parentheses
+ consists of a sequence of digits, the condition is satisfied if the
+ capturing subpattern of that number has previously matched. The number
+ must be greater than zero. Consider the following pattern, which
+ contains non-significant white space to make it more readable (assume
+ the PCRE_EXTENDED option) and to divide it into three parts for ease of
+ discussion:
- ( \( )? [^()]+ (?(1) \) )
+ ( \( )? [^()]+ (?(1) \) )
- The first part matches an optional opening parenthesis, and if that
- character is present, sets it as the first captured substring. The sec-
- ond part matches one or more characters that are not parentheses. The
- third part is a conditional subpattern that tests whether the first set
- of parentheses matched or not. If they did, that is, if subject started
- with an opening parenthesis, the condition is true, and so the yes-pat-
- tern is executed and a closing parenthesis is required. Otherwise,
- since no-pattern is not present, the subpattern matches nothing. In
- other words, this pattern matches a sequence of non-parentheses,
- optionally enclosed in parentheses.
+ The first part matches an optional opening parenthesis, and if that
+ character is present, sets it as the first captured substring. The
+ second part matches one or more characters that are not parentheses.
+ The third part is a conditional subpattern that tests whether the first
+ set of parentheses matched or not. If they did, that is, if subject
+ started with an opening parenthesis, the condition is true, and so the
+ yes-pattern is executed and a closing parenthesis is required.
+ Otherwise, since no-pattern is not present, the subpattern matches
+ nothing. In other words, this pattern matches a sequence of
+ non-parentheses, optionally enclosed in parentheses.
- If the condition is the string (R), it is satisfied if a recursive call
- to the pattern or subpattern has been made. At "top level", the condi-
- tion is false. This is a PCRE extension. Recursive patterns are
- described in the next section.
+ If the condition is the string (R), it is satisfied if a recursive call
+ to the pattern or subpattern has been made. At "top level", the
+ condition is false. This is a PCRE extension. Recursive patterns are
+ described in the next section.
- If the condition is not a sequence of digits or (R), it must be an
- assertion. This may be a positive or negative lookahead or lookbehind
- assertion. Consider this pattern, again containing non-significant
- white space, and with the two alternatives on the second line:
+ If the condition is not a sequence of digits or (R), it must be an
+ assertion. This may be a positive or negative lookahead or lookbehind
+ assertion. Consider this pattern, again containing non-significant
+ white space, and with the two alternatives on the second line:
(?(?=[^a-z]*[a-z])
\d{2}-[a-z]{3}-\d{2} | \d{2}-\d{2}-\d{2} )
- The condition is a positive lookahead assertion that matches an
- optional sequence of non-letters followed by a letter. In other words,
- it tests for the presence of at least one letter in the subject. If a
- letter is found, the subject is matched against the first alternative;
- otherwise it is matched against the second. This pattern matches
- strings in one of the two forms dd-aaa-dd or dd-dd-dd, where aaa are
- letters and dd are digits.
-
+ The condition is a positive lookahead assertion that matches an
+ optional sequence of non-letters followed by a letter. In other words,
+ it tests for the presence of at least one letter in the subject. If a
+ letter is found, the subject is matched against the first alternative;
+ otherwise it is matched against the second. This pattern matches
+ strings in one of the two forms dd-aaa-dd or dd-dd-dd, where aaa are
+ letters and dd are digits.
COMMENTS
+ The sequence (?# marks the start of a comment which continues up to the
+ next closing parenthesis. Nested parentheses are not permitted. The
+ characters that make up a comment play no part in the pattern matching
+ at all.
- The sequence (?# marks the start of a comment which continues up to the
- next closing parenthesis. Nested parentheses are not permitted. The
- characters that make up a comment play no part in the pattern matching
- at all.
-
- If the PCRE_EXTENDED option is set, an unescaped # character outside a
- character class introduces a comment that continues up to the next new-
- line character in the pattern.
-
+ If the PCRE_EXTENDED option is set, an unescaped # character outside a
+ character class introduces a comment that continues up to the next
+ newline character in the pattern.
RECURSIVE PATTERNS
-
- Consider the problem of matching a string in parentheses, allowing for
- unlimited nested parentheses. Without the use of recursion, the best
- that can be done is to use a pattern that matches up to some fixed
- depth of nesting. It is not possible to handle an arbitrary nesting
- depth. Perl has provided an experimental facility that allows regular
- expressions to recurse (amongst other things). It does this by interpo-
- lating Perl code in the expression at run time, and the code can refer
- to the expression itself. A Perl pattern to solve the parentheses prob-
- lem can be created like this:
+ Consider the problem of matching a string in parentheses, allowing for
+ unlimited nested parentheses. Without the use of recursion, the best
+ that can be done is to use a pattern that matches up to some fixed
+ depth of nesting. It is not possible to handle an arbitrary nesting
+ depth. Perl has provided an experimental facility that allows regular
+ expressions to recurse (amongst other things). It does this by
+ interpolating Perl code in the expression at run time, and the code can
+ refer to the expression itself. A Perl pattern to solve the parentheses
+ problem can be created like this:
$re = qr{\( (?: (?>[^()]+) | (?p{$re}) )* \)}x;
- The (?p{...}) item interpolates Perl code at run time, and in this case
- refers recursively to the pattern in which it appears. Obviously, PCRE
- cannot support the interpolation of Perl code. Instead, it supports
- some special syntax for recursion of the entire pattern, and also for
- individual subpattern recursion.
+ The (?p{...}) item interpolates Perl code at run time, and in this case
+ refers recursively to the pattern in which it appears. Obviously, PCRE
+ cannot support the interpolation of Perl code. Instead, it supports
+ some special syntax for recursion of the entire pattern, and also for
+ individual subpattern recursion.
- The special item that consists of (? followed by a number greater than
- zero and a closing parenthesis is a recursive call of the subpattern of
- the given number, provided that it occurs inside that subpattern. (If
- not, it is a "subroutine" call, which is described in the next sec-
- tion.) The special item (?R) is a recursive call of the entire regular
- expression.
+ The special item that consists of (? followed by a number greater than
+ zero and a closing parenthesis is a recursive call of the subpattern of
+ the given number, provided that it occurs inside that subpattern. (If
+ not, it is a "subroutine" call, which is described in the next
+ section.) The special item (?R) is a recursive call of the entire
+ regular expression.
- For example, this PCRE pattern solves the nested parentheses problem
- (assume the PCRE_EXTENDED option is set so that white space is
- ignored):
+ For example, this PCRE pattern solves the nested parentheses problem
+ (assume the PCRE_EXTENDED option is set so that white space is
+ ignored):
\( ( (?>[^()]+) | (?R) )* \)
- First it matches an opening parenthesis. Then it matches any number of
- substrings which can either be a sequence of non-parentheses, or a
- recursive match of the pattern itself (that is a correctly parenthe-
- sized substring). Finally there is a closing parenthesis.
+ First it matches an opening parenthesis. Then it matches any number of
+ substrings which can either be a sequence of non-parentheses, or a
+ recursive match of the pattern itself (that is a correctly
+ parenthesized substring). Finally there is a closing parenthesis.
- If this were part of a larger pattern, you would not want to recurse
- the entire pattern, so instead you could use this:
+ If this were part of a larger pattern, you would not want to recurse
+ the entire pattern, so instead you could use this:
( \( ( (?>[^()]+) | (?1) )* \) )
- We have put the pattern into parentheses, and caused the recursion to
- refer to them instead of the whole pattern. In a larger pattern, keep-
- ing track of parenthesis numbers can be tricky. It may be more conve-
- nient to use named parentheses instead. For this, PCRE uses (?P>name),
- which is an extension to the Python syntax that PCRE uses for named
- parentheses (Perl does not provide named parentheses). We could rewrite
- the above example as follows:
+ We have put the pattern into parentheses, and caused the recursion to
+ refer to them instead of the whole pattern. In a larger pattern,
+ keeping track of parenthesis numbers can be tricky. It may be more
+ convenient to use named parentheses instead. For this, PCRE uses
+ (?P>name), which is an extension to the Python syntax that PCRE uses
+ for named parentheses (Perl does not provide named parentheses). We
+ could rewrite the above example as follows:
(?P<pn> \( ( (?>[^()]+) | (?P>pn) )* \) )
- This particular example pattern contains nested unlimited repeats, and
- so the use of atomic grouping for matching strings of non-parentheses
- is important when applying the pattern to strings that do not match.
- For example, when this pattern is applied to
+ This particular example pattern contains nested unlimited repeats, and
+ so the use of atomic grouping for matching strings of non-parentheses
+ is important when applying the pattern to strings that do not match.
+ For example, when this pattern is applied to
(aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa()
- it yields "no match" quickly. However, if atomic grouping is not used,
- the match runs for a very long time indeed because there are so many
- different ways the + and * repeats can carve up the subject, and all
- have to be tested before failure can be reported.
+ it yields "no match" quickly. However, if atomic grouping is not used,
+ the match runs for a very long time indeed because there are so many
+ different ways the + and * repeats can carve up the subject, and all
+ have to be tested before failure can be reported.
- At the end of a match, the values set for any capturing subpatterns are
- those from the outermost level of the recursion at which the subpattern
- value is set. If you want to obtain intermediate values, a callout
- function can be used (see below and the pcrecallout documentation). If
- the pattern above is matched against
+ At the end of a match, the values set for any capturing subpatterns are
+ those from the outermost level of the recursion at which the subpattern
+ value is set. If you want to obtain intermediate values, a callout
+ function can be used (see below and the pcrecallout documentation). If
+ the pattern above is matched against
(ab(cd)ef)
- the value for the capturing parentheses is "ef", which is the last
- value taken on at the top level. If additional parentheses are added,
- giving
+ the value for the capturing parentheses is "ef", which is the last
+ value taken on at the top level. If additional parentheses are added,
+ giving
\( ( ( (?>[^()]+) | (?R) )* ) \)
^ ^
^ ^
- the string they capture is "ab(cd)ef", the contents of the top level
- parentheses. If there are more than 15 capturing parentheses in a pat-
- tern, PCRE has to obtain extra memory to store data during a recursion,
- which it does by using pcre_malloc, freeing it via pcre_free after-
- wards. If no memory can be obtained, the match fails with the
- PCRE_ERROR_NOMEMORY error.
+ the string they capture is "ab(cd)ef", the contents of the top level
+ parentheses. If there are more than 15 capturing parentheses in a
+ pattern, PCRE has to obtain extra memory to store data during a
+ recursion, which it does by using pcre_malloc, freeing it via pcre_free
+ afterwards. If no memory can be obtained, the match fails with the
+ PCRE_ERROR_NOMEMORY error.
- Do not confuse the (?R) item with the condition (R), which tests for
- recursion. Consider this pattern, which matches text in angle brack-
- ets, allowing for arbitrary nesting. Only digits are allowed in nested
- brackets (that is, when recursing), whereas any characters are permit-
- ted at the outer level.
+ Do not confuse the (?R) item with the condition (R), which tests for
+ recursion. Consider this pattern, which matches text in angle
+ brackets, allowing for arbitrary nesting. Only digits are allowed in
+ nested brackets (that is, when recursing), whereas any characters are
+ permitted at the outer level.
< (?: (?(R) \d++ | [^<>]*+) | (?R)) * >
- In this pattern, (?(R) is the start of a conditional subpattern, with
- two different alternatives for the recursive and non-recursive cases.
- The (?R) item is the actual recursive call.
-
+ In this pattern, (?(R) is the start of a conditional subpattern, with
+ two different alternatives for the recursive and non-recursive cases.
+ The (?R) item is the actual recursive call.
SUBPATTERNS AS SUBROUTINES
-
- If the syntax for a recursive subpattern reference (either by number or
- by name) is used outside the parentheses to which it refers, it oper-
- ates like a subroutine in a programming language. An earlier example
- pointed out that the pattern
+ If the syntax for a recursive subpattern reference (either by number or
+ by name) is used outside the parentheses to which it refers, it
+ operates like a subroutine in a programming language. An earlier
+ example pointed out that the pattern
(sens|respons)e and \1ibility
- matches "sense and sensibility" and "response and responsibility", but
- not "sense and responsibility". If instead the pattern
+ matches "sense and sensibility" and "response and responsibility", but
+ not "sense and responsibility". If instead the pattern
(sens|respons)e and (?1)ibility
- is used, it does match "sense and responsibility" as well as the other
- two strings. Such references must, however, follow the subpattern to
- which they refer.
-
+ is used, it does match "sense and responsibility" as well as the other
+ two strings. Such references must, however, follow the subpattern to
+ which they refer.
CALLOUTS
+ Perl has a feature whereby using the sequence (?{...}) causes arbitrary
+ Perl code to be obeyed in the middle of matching a regular expression.
+ This makes it possible, amongst other things, to extract different
+ substrings that match the same pair of parentheses when there is a
+ repetition.
- Perl has a feature whereby using the sequence (?{...}) causes arbitrary
- Perl code to be obeyed in the middle of matching a regular expression.
- This makes it possible, amongst other things, to extract different sub-
- strings that match the same pair of parentheses when there is a repeti-
- tion.
+ PCRE provides a similar feature, but of course it cannot obey arbitrary
+ Perl code. The feature is called "callout". The caller of PCRE provides
+ an external function by putting its entry point in the global variable
+ pcre_callout. By default, this variable contains NULL, which disables
+ all calling out.
- PCRE provides a similar feature, but of course it cannot obey arbitrary
- Perl code. The feature is called "callout". The caller of PCRE provides
- an external function by putting its entry point in the global variable
- pcre_callout. By default, this variable contains NULL, which disables
- all calling out.
-
- Within a regular expression, (?C) indicates the points at which the
- external function is to be called. If you want to identify different
- callout points, you can put a number less than 256 after the letter C.
- The default value is zero. For example, this pattern has two callout
- points:
+ Within a regular expression, (?C) indicates the points at which the
+ external function is to be called. If you want to identify different
+ callout points, you can put a number less than 256 after the letter C.
+ The default value is zero. For example, this pattern has two callout
+ points:
(?C1)abc(?C2)def
- During matching, when PCRE reaches a callout point (and pcre_callout is
- set), the external function is called. It is provided with the number
- of the callout, and, optionally, one item of data originally supplied
- by the caller of pcre_exec(). The callout function may cause matching
- to backtrack, or to fail altogether. A complete description of the
- interface to the callout function is given in the pcrecallout documen-
- tation.
-
+ During matching, when PCRE reaches a callout point (and pcre_callout is
+ set), the external function is called. It is provided with the number
+ of the callout, and, optionally, one item of data originally supplied
+ by the caller of pcre_exec(). The callout function may cause matching
+ to backtrack, or to fail altogether. A complete description of the
+ interface to the callout function is given in the pcrecallout
+ documentation.
DIFFERENCES FROM PERL
- This section escribes the differences in the ways that PCRE and Perl
- handle regular expressions. The differences described here are with
- respect to Perl 5.8.
+ This section escribes the differences in the ways that PCRE and Perl
+ handle regular expressions. The differences described here are with
+ respect to Perl 5.8.
- 1. PCRE does not have full UTF-8 support. Details of what it does have
- are given in the section on UTF-8 support in the main pcre page.
+ 1. PCRE does not have full UTF-8 support. Details of what it does have
+ are given in the section on UTF-8 support in the main pcre page.
- 2. PCRE does not allow repeat quantifiers on lookahead assertions. Perl
- permits them, but they do not mean what you might think. For example,
- (?!a){3} does not assert that the next three characters are not "a". It
- just asserts that the next character is not "a" three times.
+ 2. PCRE does not allow repeat quantifiers on lookahead assertions.
+ Perl permits them, but they do not mean what you might think. For
+ example, (?!a){3} does not assert that the next three characters are
+ not "a". It just asserts that the next character is not "a" three
+ times.
- 3. Capturing subpatterns that occur inside negative lookahead asser-
- tions are counted, but their entries in the offsets vector are never
- set. Perl sets its numerical variables from any such patterns that are
- matched before the assertion fails to match something (thereby succeed-
- ing), but only if the negative lookahead assertion contains just one
- branch.
+ 3. Capturing subpatterns that occur inside negative lookahead
+ assertions are counted, but their entries in the offsets vector are
+ never set. Perl sets its numerical variables from any such patterns
+ that are matched before the assertion fails to match something
+ (thereby succeeding), but only if the negative lookahead assertion
+ contains just one branch.
- 4. Though binary zero characters are supported in the subject string,
- they are not allowed in a pattern string because it is passed as a nor-
- mal C string, terminated by zero. The escape sequence "\0" can be used
- in the pattern to represent a binary zero.
+ 4. Though binary zero characters are supported in the subject string,
+ they are not allowed in a pattern string because it is passed as a
+ normal C string, terminated by zero. The escape sequence "\0" can be
+ used in the pattern to represent a binary zero.
- 5. The following Perl escape sequences are not supported: \l, \u, \L,
- \U, \P, \p, \N, and \X. In fact these are implemented by Perl's general
- string-handling and are not part of its pattern matching engine. If any
- of these are encountered by PCRE, an error is generated.
+ 5. The following Perl escape sequences are not supported: \l, \u, \L,
+ \U, \P, \p, \N, and \X. In fact these are implemented by Perl's general
+ string-handling and are not part of its pattern matching engine. If any
+ of these are encountered by PCRE, an error is generated.
- 6. PCRE does support the \Q...\E escape for quoting substrings. Charac-
- ters in between are treated as literals. This is slightly different
- from Perl in that $ and @ are also handled as literals inside the
- quotes. In Perl, they cause variable interpolation (but of course PCRE
- does not have variables). Note the following examples:
+ 6. PCRE does support the \Q...\E escape for quoting substrings.
+ Characters in between are treated as literals. This is slightly
+ different from Perl in that $ and @ are also handled as literals inside
+ the quotes. In Perl, they cause variable interpolation (but of course
+ PCRE does not have variables). Note the following examples:
Pattern PCRE matches Perl matches
@@ -1328,61 +1291,59 @@
\Qabc\$xyz\E abc\$xyz abc\$xyz
\Qabc\E\$\Qxyz\E abc$xyz abc$xyz
- The \Q...\E sequence is recognized both inside and outside character
- classes.
+ The \Q...\E sequence is recognized both inside and outside character
+ classes.
- 7. Fairly obviously, PCRE does not support the (?{code}) and (?p{code})
- constructions. However, there is some experimental support for recur-
- sive patterns using the non-Perl items (?R), (?number) and (?P>name).
- Also, the PCRE "callout" feature allows an external function to be
- called during pattern matching.
+ 7. Fairly obviously, PCRE does not support the (?{code}) and
+ (?p{code}) constructions. However, there is some experimental support
+ for recursive patterns using the non-Perl items (?R), (?number) and
+ (?P>name). Also, the PCRE "callout" feature allows an external function
+ to be called during pattern matching.
- 8. There are some differences that are concerned with the settings of
- captured strings when part of a pattern is repeated. For example,
- matching "aba" against the pattern /^(a(b)?)+$/ in Perl leaves $2
- unset, but in PCRE it is set to "b".
+ 8. There are some differences that are concerned with the settings of
+ captured strings when part of a pattern is repeated. For example,
+ matching "aba" against the pattern /^(a(b)?)+$/ in Perl leaves $2
+ unset, but in PCRE it is set to "b".
- 9. PCRE provides some extensions to the Perl regular expression
- facilities:
+ 9. PCRE provides some extensions to the Perl regular expression
+ facilities:
- (a) Although lookbehind assertions must match fixed length strings,
- each alternative branch of a lookbehind assertion can match a different
- length of string. Perl requires them all to have the same length.
+ (a) Although lookbehind assertions must match fixed length strings,
+ each alternative branch of a lookbehind assertion can match a different
+ length of string. Perl requires them all to have the same length.
- (b) If PCRE_DOLLAR_ENDONLY is set and PCRE_MULTILINE is not set, the $
- meta-character matches only at the very end of the string.
+ (b) If PCRE_DOLLAR_ENDONLY is set and PCRE_MULTILINE is not set, the $
+ meta-character matches only at the very end of the string.
- (c) If PCRE_EXTRA is set, a backslash followed by a letter with no spe-
- cial meaning is faulted.
+ (c) If PCRE_EXTRA is set, a backslash followed by a letter with no
+ special meaning is faulted.
- (d) If PCRE_UNGREEDY is set, the greediness of the repetition quanti-
- fiers is inverted, that is, by default they are not greedy, but if fol-
- lowed by a question mark they are.
+ (d) If PCRE_UNGREEDY is set, the greediness of the repetition
+ quantifiers is inverted, that is, by default they are not greedy, but
+ if followed by a question mark they are.
- (e) PCRE_ANCHORED can be used to force a pattern to be tried only at
- the first matching position in the subject string.
+ (e) PCRE_ANCHORED can be used to force a pattern to be tried only at
+ the first matching position in the subject string.
- (f) The PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, and PCRE_NO_AUTO_CAP-
- TURE options for pcre_exec() have no Perl equivalents.
+ (f) The PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, and
+ PCRE_NO_AUTO_CAPTURE options for pcre_exec() have no Perl equivalents.
- (g) The (?R), (?number), and (?P>name) constructs allows for recursive
- pattern matching (Perl can do this using the (?p{code}) construct,
- which PCRE cannot support.)
+ (g) The (?R), (?number), and (?P>name) constructs allows for recursive
+ pattern matching (Perl can do this using the (?p{code}) construct,
+ which PCRE cannot support.)
- (h) PCRE supports named capturing substrings, using the Python syntax.
+ (h) PCRE supports named capturing substrings, using the Python syntax.
- (i) PCRE supports the possessive quantifier "++" syntax, taken from
- Sun's Java package.
+ (i) PCRE supports the possessive quantifier "++" syntax, taken from
+ Sun's Java package.
- (j) The (R) condition, for testing recursion, is a PCRE extension.
+ (j) The (R) condition, for testing recursion, is a PCRE extension.
- (k) The callout facility is PCRE-specific.
-
-
+ (k) The callout facility is PCRE-specific.
NOTES
The \< and \> metacharacters from Henry Spencers package
- are not available in PCRE, but can be emulate with \b,
+ are not available in PCRE, but can be emulated with \b,
as required, also in conjunction with \W or \w.
In LDMud, backtracks are limited by the EVAL_COST runtime
@@ -1391,25 +1352,23 @@
LDMud doesn't support PCRE callouts.
-
LIMITATIONS
There are some size limitations in PCRE but it is hoped that
- they will never in practice be relevant. The maximum length
- of a compiled pattern is 65539 (sic) bytes. All values in
- repeating quantifiers must be less than 65536. There max-
- imum number of capturing subpatterns is 65535. There is no
- limit to the number of non-capturing subpatterns, but the
- maximum depth of nesting of all kinds of parenthesized sub-
- pattern, including capturing subpatterns, assertions, and
- other types of subpattern, is 200.
+ they will never in practice be relevant. The maximum length
+ of a compiled pattern is 65539 (sic) bytes. All values in
+ repeating quantifiers must be less than 65536. There
+ maximum number of capturing subpatterns is 65535. There is no
+ limit to the number of non-capturing subpatterns, but the
+ maximum depth of nesting of all kinds of parenthesized
+ subpattern, including capturing subpatterns, assertions,
+ and other types of subpattern, is 200.
- The maximum length of a subject string is the largest posi-
- tive number that an integer variable can hold. However, PCRE
- uses recursion to handle subpatterns and indefinite repeti-
- tion. This means that the available stack space may limit
- the size of a subject string that can be processed by cer-
- tain patterns.
-
+ The maximum length of a subject string is the largest
+ positive number that an integer variable can hold. However,
+ PCRE uses recursion to handle subpatterns and indefinite
+ repetition. This means that the available stack space may
+ limit the size of a subject string that can be processed by
+ certain patterns.
AUTHOR
Philip Hazel <ph10@cam.ac.uk>
diff --git a/doc/concepts/pgsql b/doc/concepts/pgsql
index 12f2cc4..0249ed0 100644
--- a/doc/concepts/pgsql
+++ b/doc/concepts/pgsql
@@ -40,7 +40,7 @@
row).
PGRES_COMMAND_OK: <ret> is a string which contains the
- server response (e.g. on INSERT or DELETE)
+ server response (e.g. on INSERT or DELETE)
PGRES_BAD_RESPONSE,
PGRES_NONFATAL_ERROR,
@@ -49,7 +49,7 @@
void <callback>(int type, mixed ret [, mixed extra...])
- <type> is the type of the call, which is not related a
+ <type> is the type of the call, which is not related to a
specific query:
PGCONN_SUCCESS: The database-connection was established,
@@ -65,7 +65,7 @@
we try to re-establish (reset) it. If the
reset fails, the connection is closed and
this value is returned. Consider the
- connection gone and don't try to close or
+ connection gone and don't try to close or
otherwise operate further on it.
<ret> is a dummy string.
diff --git a/doc/concepts/python b/doc/concepts/python
new file mode 100644
index 0000000..0fe48b7
--- /dev/null
+++ b/doc/concepts/python
@@ -0,0 +1,191 @@
+PRELIMINARY
+CONCEPT
+ python
+
+DESCRIPTION
+ Python can be used to extend the LDMud driver. At the startup
+ of LDMud a python script will be called that can register
+ additional efuns. The python script can either be given
+ on the command line using the --python-script option,
+ or at compile time with the --with-python-script configuration
+ option.
+
+ The python script can import the builtin ldmud module.
+ This module provides the following functions:
+
+ - register_efun(name, function) -> None
+ Registers a new efun name. This is not allowed during
+ compilation of an LPC object.
+
+ If the Python function has type annotations for its
+ arguments and return value, the type is checked
+ at compile and runtime. Union types can be specified
+ as tuples of types.
+
+ - unregister_efun(name) -> None
+ Removes a python efun from registration. This is not
+ allowed during compilation of an LPC object. The
+ removal will only affect newly compiled code,
+ already compiled code will produce errors when
+ calling this efun.
+
+ - register_socket(fd, function [,eventmask]) -> None
+ Registers a socket <fd> to watch for events (like
+ poll/select). The socket must be either given as
+ an integer or an object with a fileno() method
+ returning an integer. The function must be a callable
+ accepting one argument, the actual event mask.
+ <eventmask> may be an combination of select.POLLIN,
+ select.POLLOUT and select.POLLPRI or a callable
+ returning such a combination.
+
+ - unregister_socket(fd) -> None
+ Removes a previously registered socket from the
+ watch list.
+
+ - register_hook(hook, function) -> None
+ Register a hook. The python function will be called
+ whenever <hook> happens. <hook> can be one of the
+ following:
+
+ ON_HEARTBEAT
+ Called without arguments for every backend loop
+
+ ON_OBJECT_CREATED
+ Called whenever an object was created, with the
+ object as its first and only argument. This call
+ happens before any LPC code of the object ran.
+
+ ON_OBJECT_DESTRUCTED
+ Called just before an object will be destructed,
+ with the object as its first and only argument.
+
+ - unregister_hook(hook, function) -> None
+ Removes a hook function.
+
+ - get_master() - > Object
+ Returns the current master object.
+ Returns None, if there is no master object (yet).
+
+ - get_simul_efun() - > Object
+ Returns the current simul-efun object
+ (or None if there is none).
+
+
+ This module provides the following types:
+
+ - Object(filename)
+ Corresponds to the LPC object type.
+ On instantiation a filename for an object
+ to search or load is required.
+
+ - Array([values | size])
+ Corresponds to an LPC array.
+ Can either be initialized with a list of values
+ or to a given size.
+
+ Supports element access with [], len() and __contains__.
+
+ - Mapping([values | width])
+ Corresponds to an LPC mapping.
+ Can either be initialized with a dict, a list of tuples
+ or as an empty mapping with a given width.
+
+ Supports element access with [], len(), __contains__
+ and has a width member.
+
+ - Struct(object, name [, values])
+ Corresponds to an LPC struct.
+ On initialization the name of the struct definition and
+ the correspopnding object is required. It can be initialized
+ with a list of values or dict.
+
+ Supports member access as regular python members.
+
+ - Closure(object [,name [, lfun_object]])
+ Corresponds to an LPC closure.
+ On initialization a closure bound to <object> will be created,
+ like a call to symbol_function(<name> [, <lfun_object>]).
+
+ Supports function calls.
+
+ - Symbol(name [, quotes])
+ Corresponds to an LPC symbol.
+ On initialization the name of the symbol is required.
+ Optionally the number of quotes (at least 1) can be specified.
+
+ Has two members: name and quotes.
+
+ - QuotedArray(array [, quotes])
+ Corresponds to an LPC quoted array.
+ On initialization an array is required.
+ Optionally the number of quotes (at least 1) can be specified.
+
+ Has two members: array and quotes.
+
+
+ This module contains the following sub-namespaces:
+
+ - efuns
+ This namespace contains all original efuns (without any
+ registered python efuns or simul-efuns). These can be called
+ as a regular function.
+
+
+EXAMPLE
+ import ldmud
+
+ def hello_world(name: str) -> int:
+ print("Hello, world, %s!\n" % (name,))
+ return 1
+
+ ldmud.register_efun("hello", hello_world)
+
+NOTES
+ Just like simul-efuns python efuns can shadow real efuns. The
+ original efun is then inaccessible for LPC code (except for code
+ that was compiled before the efun was registered). Python efuns are
+ nearly indistinguishable from real efuns, they also use the efun::
+ prefix. However they can be detected with
+ CLOSURE_IS_PYTHON_EFUN(get_type_info(#'efun,1))
+
+ Without the prefix the order of name resolution for function calls is:
+ 1. lfuns
+ 2. simul-efuns
+ 3. python efuns
+ 4. real efuns
+
+ Also just like simul-efuns python-registered efuns are called
+ from LPC code that was compiled after the registration. LPC code
+ that was compiled before the registration will still call the
+ original efuns (or throw a compile error if that efun doesn't exist).
+ Therefore such efuns should be registered in the python startup
+ script.
+
+ When a python efun is unregistered, code that was compiled while the
+ registration was in effect will throw a runtime error. (Regardless
+ of whether a driver efun with the same name exists or not.)
+
+ There is a limit of 2048 python efuns. Not only registered, but also
+ formerly registered - but now unregistered - efuns count toward that
+ limit. Re-registering the same efun name again won't count a second
+ time. (LPC code that was compiled during the previous registration
+ will also call the new efun after the re-registration.)
+
+ As LDMud is single-threaded, the python code will run in the same
+ thread as the LPC machine. So any long-running python function will
+ halt the MUD for all players. Hence python functions should return
+ promptly and source out any lengthy tasks to another process. If
+ other threads are spawned from python, then these threads are not
+ allowed to access any LDMud functions or objects.
+
+ Finally a note of caution: Don't change the meaning of base efuns
+ fundamentally as it furthers confusion and hinders exchange of LPC
+ code and knowledge between mudlibs.
+
+HISTORY
+ LDMud 3.5 implemented the python functionality.
+ LDMud 3.6 added type checks.
+
+SEE ALSO
+ simul_efun(C)
diff --git a/doc/concepts/regexp b/doc/concepts/regexp
index 9a9d70e..b04ca1b 100644
--- a/doc/concepts/regexp
+++ b/doc/concepts/regexp
@@ -1,16 +1,18 @@
SYNOPSIS
Regular Expressions
-
DESCRIPTION
LDMud supports both the traditional regular expressions as
- implemented by Henry Spencer ("HS" or "traditional"), and the
- Perl-compatible regular expressions by Philip Hazel ("PCRE").
+ implemented by Henry Spencer ("HS" or "traditional"), and
+ optionally the Perl-compatible regular expressions by Philip
+ Hazel ("PCRE").
Both packages can be used concurrently, with the selection
being made through extra option flags argument to the efuns.
One of the two packages can be selected at compile time, by
commandline argument, and by driver hook to be the default
package.
+ If the host system does not supply PCREs at compile-time, they
+ will not be availablea in the driver.
The packages differ in the expressivity of their expressions
(PCRE offering more options that Henry Spencer's package),
@@ -25,7 +27,6 @@
For details, refer to the detailed manpages: hsregexp(C) for
the Henry Spencer package, pcre(C) for the PCRE package.
-
REGULAR EXPRESSION DETAILS
A regular expression is a pattern that is matched against a
subject string from left to right. Most characters stand for
@@ -84,7 +85,6 @@
\< HS: Match begin of word.
\> HS: Match end of word.
-
OPTIONS
The package is selected with these option flags:
diff --git a/doc/concepts/simul_efun b/doc/concepts/simul_efun
index 8c4a2a0..d42c957 100644
--- a/doc/concepts/simul_efun
+++ b/doc/concepts/simul_efun
@@ -8,7 +8,7 @@
object (except the master object). To get access to efuns that
are overloaded by the simul_efun object, you can use the
efun::function() to bypass the simul_efun (unless the
- simul_efun object has defined the function as ``nomask'').
+ simul_efun object has defined the function as "nomask").
SEE ALSO
get_simul_efun(M), inheritance(LPC), operators(LPC)
diff --git a/doc/concepts/tls b/doc/concepts/tls
index 25946a2..d42d8de 100644
--- a/doc/concepts/tls
+++ b/doc/concepts/tls
@@ -3,53 +3,55 @@
tls (transport layer security)
DESCRIPTION
- TLS stands for Transport Layer Security which is the successor
- of the well known SSL (Secure Socket Layer). Both techniques
- provide a way to authenticate and encrypt the data send through
- a network connection.
- By enabling TLS during compilation of the driver you can provide
- a secure channel into the mud to your players.
- In difference to other solutions as "sslwrap" or "stunnel" the
- driver integrated approach has the advantage that the mud sees
- the real IP of the player, not the IP of the local mud host.
+ TLS stands for Transport Layer Security which is the successor
+ of the well known SSL (Secure Socket Layer). Both techniques
+ provide a way to authenticate and encrypt the data send through
+ a network connection.
+
+ By enabling TLS during compilation of the driver you can provide
+ a secure channel into the mud to your players.
+
+ In difference to other solutions as "sslwrap" or "stunnel" the
+ driver integrated approach has the advantage that the mud sees
+ the real IP of the player, not the IP of the local mud host.
USAGE
- To use TLS configure your driver with --enable-tls option.
- After starting your driver you have five new efuns
- (tls_init_connection(), tls_deinit_connection(), tls_error(),
- tls_query_connection_info(), tls_query_connection_state()).
+ To use TLS configure your driver with --enable-tls option.
+ After starting your driver you have five new efuns
+ (tls_init_connection(), tls_deinit_connection(), tls_error(),
+ tls_query_connection_info(), tls_query_connection_state()).
- You can switch on TLS by calling tls_init_connection().
- This can happen in three ways:
+ You can switch on TLS by calling tls_init_connection().
+ This can happen in three ways:
- 1) in telnet_neg()
+ 1) in telnet_neg()
- Advantage of this method is that you can offer TLS on a normal
- mud port. If you have a limited number of ports this can
- become important. The TLS connection will be started by
+ Advantage of this method is that you can offer TLS on a normal
+ mud port. If you have a limited number of ports this can
+ become important. The TLS connection will be started by
the client with help of telnet option STARTTLS. Currently
there are no mudclients that support this method.
-
+
You will have to implement the telnet option STARTTLS (46) for
this method. The draft for this can be found here:
http://www.ietf.org/proceedings/99mar/I-D/draft-ietf-tn3270e-telnet-tls-01.txt
Call tls_init_connection() to initiate the TLS handshake.
- 2) in master_ob->connect()
+ 2) in master_ob->connect()
Advantage of this method is that your users can connect with
any program that supports TLS/SSL. Examples are telnet-ssl,
sslwrap or stunnel. Disadvantage is that you have to spend
a dedicated port for this.
-
+
You have to call tls_init_connection() as first command
after the player connected (normally in master_ob->connect())
3) in an interactive object using a callback.
This method is similar to method (1), but not limited to
- telnet: it is useful for implementing protocols thta use
+ telnet: it is useful for implementing protocols that use
STARTTLS like SMTP or IMAP. tls_init_connection() can be
called at any time by the interactive object.
diff --git a/doc/concepts/uids b/doc/concepts/uids
index 724a7af..26a94e9 100644
--- a/doc/concepts/uids
+++ b/doc/concepts/uids
@@ -28,11 +28,9 @@
As uids, euids are assigned at an objects creation through
the two aformentioned driverhooks. They can be queried with
- the efun geteuid() and changed with the efun seteuid(). Calls
- to the latter are verified by the master lfun valid_seteuid().
-
- Additionally objects can impose their uid onto an other objects
- euid with the efun export_uid().
+ the efun geteuid() and changed with the efun configure_object
+ (using the OC_EUID option). Calls to the latter are verified by
+ the master lfun privilege_violation().
If the driver is run in 'strict euids' mode, euids are taken
@@ -51,9 +49,11 @@
When an object is newly loaded, the H_LOAD_UIDS hook is
called with the object name as argument.
+
When an object is cloned, the H_CLONE_UIDS hook is called
with the blueprint object as first and the clone's designated
name as second argument.
+
In both cases the new object already exists, but has 0 uids.
For the result, the following possibilities exist (<num> is
@@ -71,9 +71,8 @@
({ <num>, <no-string> }) -> uid = 'default', euid = 0
-
Slightly different rules apply to the (e)uid of the master.
- The masters (e)uid is determined by a call to
+ The master's (e)uid is determined by a call to
master->get_master_uid():
"<uid"> -> uid = "<uid>", euid = "<uid>"
@@ -92,5 +91,6 @@
the appropriate driver hooks.
SEE ALSO
- native(C), get_root_uid(M), valid_seteuid(M),
- objects(C), clone_object(E), geteuid(E), getuid(E), seteuid(E)
+ native(C), get_root_uid(M), privilege_violation(M),
+ objects(C), clone_object(E), geteuid(E), getuid(E),
+ configure_object(E)
diff --git a/doc/concepts/unicode b/doc/concepts/unicode
new file mode 100644
index 0000000..5c22ecc
--- /dev/null
+++ b/doc/concepts/unicode
@@ -0,0 +1,56 @@
+CONCEPT
+ unicode
+
+DESCRIPTION
+ LPC strings come in two flavors: As byte sequences and as unicode
+ strings. For both types almost the full range of string operations
+ is available, but the types are not to be mixed. So for example
+ you cannot add a byte sequence to an unicode string or vice versa.
+
+ Byte sequences can store only bytes (values from 0 to 255),
+ but unicode strings can store the full unicode character set
+ (values from 0 to 1114111).
+
+ There are two conversion functions to convert between byte sequences
+ and unicode strings: to_text() which will return a unicode string,
+ and to_bytes() which returns a byte sequence. Both take either
+ a string or an array, and when converting between bytes and unicode
+ also the name of the encoding (to be) used for the byte sequence.
+
+ -- File handling --
+
+ When a file is accessed either by compiling, read_file(), write_file()
+ (not read_bytes() or write_bytes(), or when an explicit encoding was
+ given), the master is asked via the driver hook H_FILE_ENCODING for
+ the encoding of the file. If none is given, 7 bit ASCII is assumed.
+ Whenever codes are encounted that are not valid in the given encoding
+ a compile or runtime error will be raised.
+
+ -- File names --
+
+ The filesystem encoding can be set with a call to
+ configure_driver(DC_FILESYSTEM_ENCODING, <encoding>). The default
+ encoding is derived from the LC_CTYPE environment setting.
+ If there is no environment setting (or it is set to the default
+ "C" locale), then UTF-8 is used.
+
+ -- Interactives --
+
+ Each interactive has its own encoding. It can be set with
+ configure_interactive(IC_ENCODING, <encoding>). The default is
+ "ISO-8859-1//TRANSLIT" which maps each incoming byte to the
+ first 256 unicode characters and uses transliteration to encode
+ characters that are not in this character set. If an input or
+ output character can not be converted to/from the configured
+ encoding it will be silently discarded.
+
+ -- ERQ / UDP --
+
+ Only byte sequences can be sent to the ERQ or via UDP,
+ and only byte sequences can be received from them.
+
+HISTORY
+ Introduced in LDMud 3.6.
+
+SEE ALSO
+ to_text(E), to_bytes(E), configure_driver(E)
diff --git a/doc/driver/architectures b/doc/driver/architectures
new file mode 100644
index 0000000..430ee21
--- /dev/null
+++ b/doc/driver/architectures
@@ -0,0 +1,15 @@
+Actively supported and tested architectures:
+- i386
+- x86_64 (work in progress until the release of 3.5.0)
+
+Other architectures can't be tested by us. Many will probably work as well.
+Your mileage may vary, but we encourage you to test it. And please tell us
+about your experiences.
+
+Platforms which require aligned memory access seem to be not used by the users
+of LDMud (e.g. ARM, PowerPC, Sparc). For the sake of code simplicity and/or
+speed some code pieces (bytecode, murmur hash functions) don't care about
+alignment. On these platforms, the driver will probably not work at all right
+now. That can be fixed, but only if needed (there are users) and if the
+potential users support us (e.g. testing).
+
diff --git a/doc/driver/invocation b/doc/driver/invocation
index 5760b46..5cc4800 100644
--- a/doc/driver/invocation
+++ b/doc/driver/invocation
@@ -1,335 +1,365 @@
NAME
- driver/invocation
+ driver/invocation
PURPOSE
- Description of the invocation of the gamedriver, especially of the command
- arguments. This document describes the commandline version of the driver
- only; non-commandline versions are platform specific and described in
- the related documentation.
+ Description of the invocation of the gamedriver, especially of the
+ command arguments. This document describes the commandline version of
+ the driver only; non-commandline versions are platform specific and
+ described in the related documentation.
DESCRIPTION
- The driver is invoked from the commandline as other normal programs.
- Neither the current directory nor the directory the executable is in need
- to be in any special relation the directory of the mudlib. Once the driver
- is running, it emits two streams of outputs:
+ The driver is invoked from the commandline as other normal programs.
+ Neither the current directory nor the directory the executable is in
+ need to be in any special relation the directory of the mudlib. Once
+ the driver is running, it emits two streams of outputs:
- - driver-related messages on stderr; this unfortunately includes
- LPC compiler diagnostics
- - LPC runtime-related messages in the logfile <mudlib>/<host>.parse.log
- (the name can be changed).
+ - driver-related messages on stderr; this unfortunately includes
+ LPC compiler diagnostics
+ - LPC runtime-related messages in the logfile
+ <mudlib>/<host>.parse.log (the name can be changed).
- It is possible to start the driver without any commandline arguments as
- suitable defaults are specified at compile time. The invocation syntax
- is:
+ It is possible to start the driver without any commandline arguments as
+ suitable defaults are specified at compile time. The invocation syntax
+ is:
- driver [options] [<portnumber>]...
+ driver [options] [<portnumber>]...
- <portnumber> the number of the port the driver shall use to accept
- connections. The maximum number of ports is determined by MAXNUMPORTS
- in the source file config.h.
+ <portnumber> the number of the port the driver shall use to accept
+ connections. The maximum number of ports is determined by MAXNUMPORTS
+ in the source file config.h.
- The options modify the behaviour of the gamedriver. Some of them are only
- available if a certain compile-time option was enabled (typically in
- the source file config.h). The following options are recognized:
+ The options modify the behaviour of the gamedriver. Some of them are
+ only available if a certain compile-time option was enabled (typically
+ in the source file config.h). The following options are recognized:
- -P|--inherit <fd-number>
- Inherit filedescriptor <fd-number> from the parent process
- as socket to listen for connections.
- Only available if compiled with MAXNUMPORTS.
+ -P|--inherit <fd-number>
+ Inherit filedescriptor <fd-number> from the parent process
+ as socket to listen for connections.
+ Only available if compiled with MAXNUMPORTS.
- -u|--udp <portnumber>
- Specify the <portnumber> for the UDP port, overriding the compiled-in
- default.
- Only available if compiled with CATCH_UDP_PORT.
+ -u|--udp <portnumber>
+ Specify the <portnumber> for the UDP port, overriding the
+ compiled-in default.
+ Only available if compiled with CATCH_UDP_PORT.
- -D|--define <macro>[=<text>]
- Add <macro> (optionally to be expanded to <text>) to the list of
- predefined macros known by the LPC compiler.
+ -D|--define <macro>[=<text>]
+ Add <macro> (optionally to be expanded to <text>) to the list of
+ predefined macros known by the LPC compiler.
- -E|--eval-cost <ticks>
- Set the number of <ticks> available for one evaluation thread.
- If 0, execution is unlimited.
+ -E|--eval-cost <ticks>
+ Set the number of <ticks> available for one evaluation thread.
+ If 0, execution is unlimited.
- -M|--master <filename>
- Use <filename> for the master object.
+ -M|--master <filename>
+ Use <filename> for the master object.
- -m|--mudlib <pathname>
- Use <pathname> as the top directory of the mudlib.
+ -m|--mudlib <pathname>
+ Use <pathname> as the top directory of the mudlib.
- --debug-file <filename>
- Log all debug output in <filename> instead of
- <mudlib>/<host>.debug.log .
+ --debug-file <filename>
+ Log all debug output in <filename> instead of
+ <mudlib>/<host>.debug.log .
- --hostname <name>
- Use <name> as hostname instead of what the system says.
+ --hostname <name>
+ Use <name> as hostname instead of what the system says.
- --hostaddr <addr>
- Use <addr> as address of this machine, instead of what the
- system says. In particular this address will be used to open
- the driver ports.
+ --hostaddr <addr>
+ Use <addr> as address of this machine, instead of what the
+ system says. In particular this address will be used to open
+ the driver ports.
- --no-compat
- --compat
- Select the mode (plain or compat) of the driver.
- This choice does not affect the default name of the master object.
+ --no-compat
+ --compat
+ Select the mode (plain or compat) of the driver.
+ This choice does not affect the default name of the master object.
- -d|--debug
- Generate debug output; repeat the argument for even more output:
- >= 1: log resets, clean ups, swaps, reception of urgend data,
- telnet negotiation states.
- check_a_lot_of_refcounts() on startup when swapping of
- variables is disabled.
- >= 2: log all add_message()s, name lookup failures, new players.
- >= 3: progress of garbage collection
- >= 4: even more junk from garbage collection
+ -d|--debug
+ Generate debug output; repeat the argument for even more output:
+ >= 1: log resets, clean ups, swaps, reception of urgend data,
+ telnet negotiation states.
+ check_a_lot_of_refcounts() on startup when swapping of
+ variables is disabled.
+ >= 2: log all add_message()s, name lookup failures, new players.
+ >= 3: progress of garbage collection
+ >= 4: even more junk from garbage collection
- -c|--list-compiles
- List the name of every compiled file on stderr.
+ -c|--list-compiles
+ List the name of every compiled file on stderr.
- -e|--no-preload
- Pass a non-zero argument (the number of occurences of this option)
- to master->preload(), which usually inhibits all preloads of castles
- and other objects.
+ -e|--no-preload
+ Pass a non-zero argument (the number of occurrences of this option)
+ to master->preload(), which usually inhibits all preloads of
+ castles and other objects.
- --erq <filename>
- --erq "<filename> <erq args>"
- Use <filename> instead of 'erq' as the basename of the ERQ executable.
- If the name starts with a '/', it is take to be an absolute pathname,
- otherwise it is interpreted relative to <bindir>. If not specified,
- 'erq' is used as the executable name.
+ --erq <filename>
+ --erq "<filename> <erq args>"
+ Use <filename> instead of 'erq' as the basename of the ERQ
+ executable. If the name starts with a '/', it is take to be an
+ absolute pathname, otherwise it is interpreted relative to
+ <bindir>. If not specified, 'erq' is used as the executable name.
- By enclosing the argument value in quotes, it is possible to pass
- arguments (e.g. --execdir) to the erq. These arguments however must
- not contain embedded spaces.
+ By enclosing the argument value in quotes, it is possible to pass
+ arguments (e.g. --execdir) to the erq. These arguments however must
+ not contain embedded spaces.
- -N|--no-erq
- Don't start the erq demon (if it would be started at all).
+ -N|--no-erq
+ Don't start the erq demon (if it would be started at all).
- --alarm-time <seconds>
- Set the granularity of call_out() and heartbeat timing. Minimum
- value is 1.
+ --alarm-time <seconds>
+ Set the granularity of call_out() and heartbeat timing. Minimum
+ value is 1.
- --heart-interval <seconds>
- Set the interval between two heartbeats. Minimum value is 1.
+ --heart-interval <seconds>
+ Set the interval between two heartbeats. Minimum value is 1.
- --sync-heart
- All heartbeats occur at the same time (modulo granularity).
-
- --async-heart
- Heartbeats occur when they are due (modulo granularity).
+ --sync-heart
+ All heartbeats occur at the same time (modulo granularity).
- -t|--no-heart
- Disable heartbeats and call_outs.
+ --async-heart
+ Heartbeats occur when they are due (modulo granularity).
- -f|--funcall <word>
- The lfun master->flag() is called with <word> as argument before the
- gamedriver accepts netword connections.
+ -t|--no-heart
+ Disable heartbeats and call_outs.
- --regexp pcre | traditional
- Select the default regexp package.
+ -f|--funcall <word>
+ The lfun master->flag() is called with <word> as argument before
+ the gamedriver accepts netword connections.
- --max-array <size>
- The maximum number of elements an array can hold.
- Set to 0, arrays of any size are allowed.
+ --regexp pcre | traditional
+ Select the default regexp package.
- --max-mapping <size>
- The maximum number of elements a mapping can hold.
- Set to 0, mappings of any size are allowed.
+ --max-array <size>
+ The maximum number of elements an array can hold.
+ Set to 0, arrays of any size are allowed.
- --max-mapping-keys <size>
- The maximum number of entries a mapping can hold.
- Set to 0, mappings of any size are allowed.
+ --max-mapping <size>
+ The maximum number of elements a mapping can hold.
+ Set to 0, mappings of any size are allowed.
- --max-callouts <size>
- The maximum number of callouts at one time.
- Set to 0, any number is allowed.
+ --max-mapping-keys <size>
+ The maximum number of entries a mapping can hold.
+ Set to 0, mappings of any size are allowed.
- --max-bytes <size>
- The maximum number of bytes one read_bytes()/write_bytes() call
- can handle.
- Set to 0, reads and writes of any size are allowed.
+ --max-callouts <size>
+ The maximum number of callouts at one time.
+ Set to 0, any number is allowed.
- --max-file <size>
- The maximum number of bytes one read_file()/write_file() call
- can handle.
- Set to 0, reads and writes of any size are allowed.
+ --max-bytes <size>
+ The maximum number of bytes one read_bytes()/write_bytes() call
+ can handle.
+ Set to 0, reads and writes of any size are allowed.
- --max-thread-pending <size>\n"
- The maximum number of bytes to be kept pending by the socket write
- thread.
- Set to 0, an unlimited amount of data can be kept pending.
+ --max-file <size>
+ The maximum number of bytes one read_file()/write_file() call
+ can handle.
+ Set to 0, reads and writes of any size are allowed.
- This option is ignored if pthreads are not used.
+ --max-thread-pending <size>\n"
+ The maximum number of bytes to be kept pending by the socket write
+ thread.
+ Set to 0, an unlimited amount of data can be kept pending.
- --cleanup-time <time>
- The idle time in seconds for an object before the driver tries to
- clean it up. It should be substantially longer than the reset time.
- A time <= 0 disables the cleanup mechanism.
+ This option is ignored if pthreads are not used.
+
+ --cleanup-time <time>
+ The idle time in seconds for an object before the driver tries to
+ clean it up. It should be substantially longer than the reset time.
+ A time <= 0 disables the cleanup mechanism.
+
+ --reset-time <time>
+ The time in seconds before an object is reset. A time <= 0 disables
+ the reset mechanism.
+
+ -s <time> | --swap-time <time>
+ -s v<time> | --swap-variables <time>
+ Time in seconds before an object (or its variables) are swapped
+ out. A time less or equal 0 disables swapping.
+
+ -s f<name> | --swap-file <name>
+ Swap into file '<name>' instead of '<mudlib>/LP_SWAP.<host>'.
+
+ -s c | --swap-compact
+ Reuse free space in the swap file immediately.
+ Giving this option results in smaller, but also more fragmented
+ swapfiles, and the swap performance may degrade.
- --reset-time <time>
- The time in seconds before an object is reset. A time <= 0 disables
- the reset mechanism.
+ --hard-malloc-limit <size>
+ Restrict total memory allocation to <size> bytes.
+ A <size> of 0 or 'unlimited' removes any restriction.
- -s <time> | --swap-time <time>
- -s v<time> | --swap-variables <time>
- Time in seconds before an object (or its variables) are swapped out.
- A time less or equal 0 disables swapping.
+ --soft-malloc-limit <size>
+ This value gives a soft limit of the allocated memory (kind of low
+ watermark). If this value is exceeded, the driver will call
+ low_memory() in the master to inform the mudlib about the
+ (potentially) developing low memory situation.
+ A <size> of 0 or 'unlimited' removes this threshold.
- -s f<name> | --swap-file <name>
- Swap into file <name> instead of <mudlib>/LP_SWAP.<host> .
+ --min-malloc <size>
+ --min-small-malloc <size>
+ Determine the sizes for the explicit initial large resp. small
+ chunk allocation. A size of 0 disables the explicit initial
+ allocations.
- -s c | --swap-compact
- Reuse free space in the swap file immediately.
- Giving this option results in smaller, but also more fragmented
- swapfiles, and the swap performance may degrade.
+ -r u<size> | --reserve-user <size>
+ -r m<size> | --reserve-master <size>
+ -r s<size> | --reserve-system <size>
+ Reserve <size> amount of memory for user/master/system allocations
+ to be held until main memory runs out.
- --max-malloc <size>
- Restrict total memory allocations to <size> bytes.
- A <size> of 0 or 'unlimited' removes any restriction.\n"
+ --filename-spaces
+ --no-filename-spaces
+ Allow/disallow the use of spaces in filenames.
- --min-malloc <size>
- --min-small-malloc <size>
- Determine the sizes for the explicite initial large resp. small chunk
- allocation. A size of 0 disables the explicite initial allocations.
+ --strict-euids
+ --no-strict-euids
+ Enable/disable the enforced use of euids.
- -r u<size> | --reserve-user <size>
- -r m<size> | --reserve-master <size>
- -r s<size> | --reserve-system <size>
- Reserve <size> amount of memory for user/master/system allocations to
- be held until main memory runs out.
+ --share-variables
+ --init-variables
+ Select how clones initialize their variables:
+ - by sharing the current values of their blueprint
+ - by initializing them afresh (using __INIT()).
- --filename-spaces
- --no-filename-spaces
- Allow/disallow the use of spaces in filenames.
+ --pidfile <filename>\n"
+ Write the pid of the driver process into <filename>.\n"
- --strict-euids
- --no-strict-euids
- Enable/disable the enforced use of euids.
+ --tls-key <pathname>
+ Use <pathname> as the x509 keyfile, default is 'key.pem'.
+ If relative, <pathname> is interpreted relative to <mudlib>.
- --share-variables
- --init-variables
- Select how clones initialize their variables:
- - by sharing the current values of their blueprint
- - by initializing them afresh (using __INIT()).
+ --tls-cert <pathname>
+ Use <pathname> as the x509 certfile, default is 'cert.pem'.
+ If relative, <pathname> is interpreted relative to <mudlib>.
- --pidfile <filename>\n"
- Write the pid of the driver process into <filename>.\n"
+ --tls-crlfile <pathname>
+ Use <pathname> as the filename holding your certificate revocation
+ lists. If relative, <pathname> is interpreted relative to <mudlib>.
- --tls-key <pathname>
- Use <pathname> as the x509 keyfile, default is 'key.pem'.
- If relative, <pathname> is interpreted relative to <mudlib>.
+ --tls-crldirectory <pathname>
+ Use <pathname> as the directory where your certificate revocation
+ lists reside. If relative, <pathname> is interpreted relative to
+ <mudlib>.
- --tls-cert <pathname>
- Use <pathname> as the x509 certfile, default is 'cert.pem'.
- If relative, <pathname> is interpreted relative to <mudlib>.
+ --tls-trustfile <pathname>
+ Use <pathname> as the filename holding your trusted PEM
+ certificates. If relative, <pathname> is interpreted relative to
+ <mudlib>.
- --tls-trustfile <pathname>
- Use <pathname> as the filename holding your trusted PEM certificates.
- If relative, <pathname> is interpreted relative to <mudlib>.
+ --tls-trustdirectory <pathname>
+ Use <pathname> as the directory where your trusted
+ PEM certificates reside, default is '/etc/ssl/certs'.
+ If relative, <pathname> is interpreted relative to <mudlib>.
- --tls-trustdirectory <pathname>
- Use <pathname> as the directory where your trusted
- PEM certificates reside, default is '/etc/ssl/certs'.
- If relative, <pathname> is interpreted relative to <mudlib>.
+ --wizlist-file <filename>
+ --no-wizlist-file
+ Read and save the wizlist in the named file (always interpreted
+ relative the mudlib); resp. don't read or save the wizlist.
- --wizlist-file <filename>
- --no-wizlist-file
- Read and save the wizlist in the named file (always interpreted
- relative the mudlib); resp. don't read or save the wizlist.
+ --gcollect-outfd <filename>|<num>
+ Garbage collector output (like a log of all reclaimed memory
+ blocks) is sent to <filename> (or inherited fd <num>) instead of
+ stderr. Only available if compiled with MALLOC_smalloc.
- --gcollect-outfd <filename>|<num>
- Garbage collector output (like a log of all reclaimed memory blocks)
- is sent to <filename> (or inherited fd <num>) instead of stderr.
- Only available if compiled with MALLOC_smalloc.
+ --y|--yydebug
+ Enable debugging of the LPC compiler.
+ Only available if compiled with YYDEBUG.
- --y|--yydebug
- Enable debugging of the LPC compiler.
- Only available if compiled with YYDEBUG.
+ --randomdevice <filename>
+ Chooses the source of the seed for the random number generator.
+ Default is /dev/urandom, Fall-back if <filename> is not readable
+ is the system clock. If you want to seed the PRNG with a specific
+ seed, you can use a filename with the seed and give it here instead
+ of using --random-seed. (Note: the last one of --randominit and
+ --random-seed wins!)
- --random-seed <num>
- Seed value for the random number generator. If not given, the
- driver chooses a seed value on its own.
- This option is for debugging.
+ --random-seed <num>
+ Seed value for the random number generator. If not given, the
+ driver chooses a seed value on its own.
+ This option is for debugging.
- --check-state <lvl>
- Perform a regular simplistic check of the virtual machine according
- to <lvl>:
- = 0: no check
- = 1: once per backend loop
- = 2: at various points in the backend loop
- Only available if compiled with DEBUG.
+ --check-state <lvl>
+ Perform a regular simplistic check of the virtual machine according
+ to <lvl>:
+ = 0: no check
+ = 1: once per backend loop
+ = 2: at various points in the backend loop
+ Only available if compiled with DEBUG.
- --check-refcounts
- Every backend cycle, all refcounts in the system are checked.
- SLOW! Only available if compiled with DEBUG.
+ --check-refcounts
+ Every backend cycle, all refcounts in the system are checked.
+ SLOW! Only available if compiled with DEBUG.
- --gobble-descriptors <num>
- <num> (more) filedescriptors are used up. You'll know when you need it.
- Only available if compiled with DEBUG.
+ --gobble-descriptors <num>
+ <num> (more) filedescriptors are used up. You'll know when you need
+ it. Only available if compiled with DEBUG.
- --check-strings
- Every backend cycle, all shared strings in the system are checked.
- SLOW! Only available if compiled with DEBUG and CHECK_STRINGS.
+ --check-strings
+ Every backend cycle, all shared strings in the system are checked.
+ SLOW! Only available if compiled with DEBUG and CHECK_STRINGS.
- -V|--version
- Print the version of the driver and exit.
+ -V|--version
+ Print the version of the driver and exit.
- --options
- Print the version and compilation options of the driver and exit.
+ --options
+ Print the version and compilation options of the driver and exit.
- -h|-?|--help
- Display a command help and exit.
+ -h|-?|--help
+ Display a command help and exit.
- --longhelp
- Display a long command help and exit.
+ --longhelp
+ Display a long command help and exit.
- --args <filename>
- The driver reads and parses the given file and treats its contents
- as if given on the commandline right where the --args option
- occured. The file itself can again contain --args options.
+ --args <filename>
+ The driver reads and parses the given file and treats its contents
+ as if given on the commandline right where the --args option
+ occurred. The file itself can again contain --args options.
-DESCRIPTION -- Argument Parser
- The parser analyses the commandline arguments given with the driver
- invocation and distinguishes 'options', which start with a '-', from
- proper arguments. Options are further distinguished by their name and
- may take an additional value. In general, options and arguments can be
- givein in any order.
+DESCRIPTION
+ -- Argument Parser
+ The parser analyses the commandline arguments given with the driver
+ invocation and distinguishes 'options', which start with a '-', from
+ proper arguments. Options are further distinguished by their name and
+ may take an additional value. In general, options and arguments can be
+ given in any order.
- Options are recognized in two forms. In the short form the option must
- be given as a single '-' followed by a single letter. In the long form,
- options start with '--' followed by a string of arbitrary length. The
- short options are case sensitive, the long options aren't.
- Most options can be specified in both the short and long form, but that
- is not mandatory. Examples: '-r' and '--recursive'.
+ Options are recognized in two forms. In the short form the option must
+ be given as a single '-' followed by a single letter. In the long
+ form, options start with '--' followed by a string of arbitrary length.
+ The short options are case sensitive, the long options aren't. Most
+ options can be specified in both the short and long form, but that is
+ not mandatory. Examples: '-r' and '--recursive'.
- If an option takes a value, it must follow the option immediately after
- a separating space or '='. Additionally, the value for a short option
- may follow the option without separator. Examples are: '-fMakefile',
- '-f Makefile', '--file=Makefile' and '--file Makefile'.
+ If an option takes a value, it must follow the option immediately after
+ a separating space or '='. Additionally, the value for a short option
+ may follow the option without separator. Examples are: '-fMakefile',
+ '-f Makefile', '--file=Makefile' and '--file Makefile'.
- Short options may be collated into one argument, e.g. '-rtl', but
- of these only the last may take a value.
+ Short options may be collated into one argument, e.g. '-rtl', but
+ of these only the last may take a value.
- The option '--' marks the end of options. All following command arguments
- are considered proper arguments even if they start with a '-' or '--'.
+ The option '--' marks the end of options. All following command
+ arguments are considered proper arguments even if they start with a '-'
+ or '--'.
- The arguments are usually taken from the commandline; but the parser
- is also able to read them from a textfiles, which can be nested. The
- content of the textfiles is broken down into words delimited by whitespace,
- which are then treated as given on the commandline at the place where
- the instruction to read the textfile stood.
+ The arguments are usually taken from the commandline; but the parser
+ is also able to read them from a textfiles, which can be nested. The
+ content of the textfiles is broken down into words delimited by
+ whitespace, which are then treated as given on the commandline at the
+ place where the instruction to read the textfile stood.
- The file parser recognizes simple double-quoted strings, which must be
- contained on a single line. Additionally, the '#' character given by
- itself is a comment marker - everthing after the '#' until the end
- of the current line is ignored.
+ The file parser recognizes simple double-quoted strings, which must be
+ contained on a single line. Additionally, the '#' character given by
+ itself is a comment marker - everthing after the '#' until the end
+ of the current line is ignored.
HISTORY
- LDMud 3.2.9 added the --max-thread-pending, --hostname,
- --hostaddr, --args and --random-seed options.
- LDMud 3.2.10 added the --filename-spaces options.
- LDMud 3.3.378 added --share-variables, --init-variables.
- LDMud 3.3.475/3.2.11 added --tls-key, --tls-cert.
- LDMud 3.3.672/3.2.11 added --tls-trustfile, --tls-trustdirectory.
- LDMud 3.3.677 added --max-mapping-keys.
+ LDMud 3.2.9 added the --max-thread-pending, --hostname,
+ --hostaddr, --args and --random-seed options.
+ LDMud 3.2.10 added the --filename-spaces options.
+ LDMud 3.3.378 added --share-variables, --init-variables.
+ LDMud 3.3.475/3.2.11 added --tls-key, --tls-cert.
+ LDMud 3.3.672/3.2.11 added --tls-trustfile, --tls-trustdirectory.
+ LDMud 3.3.677 added --max-mapping-keys.
+ LDMud 3.3.714/3.2.15 added --tls-crlfile, --tls-crldirectory.
+ LDMud 3.3.x added --randominit.
diff --git a/doc/driver/limitations b/doc/driver/limitations
new file mode 100644
index 0000000..1504238
--- /dev/null
+++ b/doc/driver/limitations
@@ -0,0 +1,82 @@
+This file contains a collection of non-configurable limits:
+
+Program properties
+==================
+* maximum program length: 1 MB (1048575 Bytes)
+ This is defined by FUNSTART_MASK in exec.h, which is the maximum offset
+ (address) of a functions code within the program block (relativ to the
+ beginning). Changing it involves changing funflag_t and probably other
+ stuff.
+
+* maximum number of programs: 2^32-1
+ The unique program ID number is a int32. It is incremented for each compiled
+ program. If it reaches zero (after wrapping to negative values) the
+ compiler or swapper calls renumber_programs(), which recycles numbers from
+ old programs.
+ (exec.h, prolang.y, swap.c, ...)
+
+* maximum number of functions in a program: 65534
+ The lookup table for function indexes holding the offsets of the function in
+ the functions tables is unsigned short.
+ The types of function arguments are stored in program_s.argument_types,
+ which is index by the unsigned short programs_s.type_start. 65535 has a
+ special meaning. Some code relies that this is unsigned short.
+ (exec.h, ...)
+ program_s.num_function_names and num_functions are unsigned short as well.
+
+* maximum length of switch: 256k (262143 Bytes)
+ Limited by BREAK_ADDRESS_MASK and CONTINUE_ADDRESS_MASK?
+
+* maximum offset for branches: 32765 (0x7ffd)
+ (prolang.y)
+
+* number of virtual variables: 256
+* number of global variables: 65536 (F_IDENTIFIER16)
+* number of local variables: 256 (F_PUSH_LOCAL_VARIABLE_LVALUE)
+* number of context variables: 256 (Should be consistent with local
+ variables, MAX_LOCAL applies to both. 16 bit opcodes are not used yet.)
+
+* max number of struct members: 255
+ (exec.h, ...)
+
+* max number of structs per program: usually 32767 (short)
+
+
+Hash tables
+===========
+* maximum size of the hash table for identifiers (ITABLE): 32768
+ The hashes of identifiers are signed short which are in most cases 16 bit
+ wide integers (lex.h, lex.c, ...)
+
+* maximum size of the hash table for objects (OTABLE): 65536
+* maximum size of the hash table for shared strings (HTABLE): 65536
+ The hashes are of type unsigned short which are in most cases 16 bit
+ wide integers.
+
+
+Objects
+=======
+* maximum clone ID number: 2^32-1
+ Not a real limitation, after that the driver starts checking if
+ blueprint name + #cloneid are unique.
+
+
+Memory management
+=================
+* max. size of single large block in slaballo.c and smalloc.c:
+ 0x07ffffff (134217727, defined by M_MASK)
+
+
+Language
+========
+* maximum number of simul-efuns: 2048
+ Only values 0xf800-0xffff in .x.closure_type of
+ a T_CLOSURE svalue are reserved for simul-efuns.
+ F_SIMUL_EFUN however takes a short int, so there 65536
+ simul-efuns would be possible.
+
+* maximum number of python efuns: 2048
+ Only values 0xe800-0xefff in .x.closure_type of
+ a T_CLOSURE svalue are reserved for python efuns.
+ F_PYTHON_EFUN however takes a short int, so there 65536
+ python efuns would be possible.
diff --git a/doc/driver/predefined b/doc/driver/predefined
index 17a7eb0..8d46e67 100644
--- a/doc/driver/predefined
+++ b/doc/driver/predefined
@@ -1,130 +1,138 @@
NAME
- predefined - predefined #defines by the parser
+ predefined - predefined #defines by the parser
DESCRIPTION
- Several preprocessor macros are pre#defined by the parser,
- to provide information about parser version, compile time
- options and parser invocation options:
+ Several preprocessor macros are pre#defined by the parser,
+ to provide information about parser version, compile time
+ options and parser invocation options:
- LPC3 : always defined.
- __LDMUD__ : always defined.
- __EUIDS__ : always (for compatibility).
- COMPAT_FLAG : defined if the driver runs in compat mode.
- __COMPAT_MODE__ : ditto
- __STRICT_EUIDS__: defined if strict euid usage is enforced.
- __FILENAME_SPACES__: defined if filenames may contain spaces.
+ LPC3 : always defined.
+ __LDMUD__ : always defined.
+ __EUIDS__ : always (for compatibility).
+ COMPAT_FLAG : defined if the driver runs in compat mode.
+ __COMPAT_MODE__ : ditto
+ __STRICT_EUIDS__ : defined if strict euid usage is enforced.
+ __FILENAME_SPACES__ : defined if filenames may contain spaces.
- __MASTER_OBJECT__ : the name of the master object (in compat mode
- without leading '/').
- __FILE__ : the name of the compiled file (in compat mode
- without leading '/').
- __LINE__ : the current line number.
- __FUNCTION__ : the current function name.
- __DIR__ : the directory path of the compiled file (in
- compat mode without leading '/').
- __PATH__(n) : the directory path of the compiled file without
- the <n> trailing elements (in compat mode without
- leading '/').
- __VERSION__ : the version string of the driver.
- __VERSION_MAJOR__ : the major version number of the driver.
- __VERSION_MINOR__ : the minor version number of the driver.
- __VERSION_MICRO__ : the micro version number of the driver.
- __VERSION_PATCH__ : the patchlevel of the driver; a 0 here means
- 'no patchlevel'.
- __VERSION_COMMITID__ : the commit ID of the source of the driver
- (attention: it might be <unknown>, if the driver
- was not compiled from a git repository)
- __VERSION_LOCAL__ : the (optional) LOCAL_LEVEL, the user has defined.
+ __MASTER_OBJECT__ : the name of the master object (in compat
+ mode without leading '/').
+ __FILE__ : the name of the compiled file (in compat
+ mode without leading '/').
+ __LINE__ : the current line number.
+ __FUNCTION__ : the current function name.
+ __DIR__ : the directory path of the compiled file
+ (in compat mode without leading '/').
+ __PATH__(n) : the directory path of the compiled file
+ without the <n> trailing elements (in
+ compat mode without leading '/').
+ __VERSION__ : the version string of the driver.
+ __VERSION_MAJOR__ : the major version number of the driver.
+ __VERSION_MINOR__ : the minor version number of the driver.
+ __VERSION_MICRO__ : the micro version number of the driver.
+ __VERSION_PATCH__ : the patchlevel of the driver; a 0 here
+ means 'no patchlevel'.
+ __VERSION_COMMITID__ : the commit ID of the source of the driver
+ (attention: it might be <unknown>, if the
+ driver was not compiled from a git
+ repository)
+ __VERSION_LOCAL__ : the (optional) LOCAL_LEVEL, the user has
+ defined.
+ __DOMAIN_NAME__ : the domain the host is part of.
+ __HOST_IP_NUMBER__ : the hosts IP number (as a string).
+ __HOST_NAME__ : the full hostname.
+ __MAX_RECURSION__ : the max count of nested function calls
+ (this is config.h:MAX_USER_TRACE).
+ __MAX_EVAL_COST__ : the max evaluation cost.
+ __RESET_TIME__ : default interval time between object
+ resets.
+ __CLEANUP_TIME__ : default interval time between object
+ cleanups.
+ __ALARM_TIME__ : the configured timing granularity.
+ __HEART_BEAT_INTERVAL__ : the configured heartbeat time.
+ __SYNCHRONOUS_HEART_BEAT__ : defined if synchronous heartbeats are
+ enabled.
+ __MAX_COMMAND_LENGTH__ : the maximum length a command can have.
+ __EFUN_DEFINED__(name) : if the efun 'name' exists, this
+ macro evaluates to " 1 ", else to " 0 ".
+ __DRIVER_LOG__ : the name of the default debug.log file
+ (within the mudlib); undefined if a
+ different name has been specified on the
+ commandline.
+ __WIZLIST__ : the name of the (mudlib) file from where
+ the driver read the initial WIZLIST
+ information. It is undefined if the driver
+ was configured to not read the
+ information.
- __DOMAIN_NAME__ : the domain the host is part of.
- __HOST_IP_NUMBER__ : the hosts IP number (as a string).
- __HOST_NAME__ : the full hostname.
- __MAX_RECURSION__ : the max count of nested function calls
- (this is config.h:MAX_USER_TRACE).
- __MAX_EVAL_COST__ : the max evaluation cost.
- __RESET_TIME__ : default interval time between object resets.
- __CLEANUP_TIME__ : default interval time between object cleanups.
- __ALARM_TIME__ : the configured timing granularity.
- __HEART_BEAT_INTERVAL__: the configured heartbeat time.
- __SYNCHRONOUS_HEART_BEAT__: defined if synchronous heartbeats are
- enabled.
- __MAX_COMMAND_LENGTH__: the maximum length a command can have.
- __EFUN_DEFINED__(name) : if the efun 'name' exists, this
- macro evaluates to " 1 ", else to " 0 ".
- __DRIVER_LOG__ : the name of the default debug.log file (within
- the mudlib); undefined if a different name
- has been specified on the commandline.
- __WIZLIST__ : the name of the (mudlib) file from where the
- driver read the initial WIZLIST information.
- It is undefined if the driver was configured
- to not read the information.
- __MAX_MALLOC__ : the internal upper limit for total memory
- usage.
- __INT_MAX__ : the largest integer number
- __INT_MIN__ : the smallest integer number
- __FLOAT_MAX__ : the largest (positive) float number
- __FLOAT_MIN__ : the smallest (positive) float number
+ __MAX_MALLOC__ : the internal upper limit for total memory
+ usage.
+ __INT_MAX__ : the largest integer number.
+ __INT_MIN__ : the smallest integer number.
+ __FLOAT_MAX__ : the largest (positive) float number.
+ __FLOAT_MIN__ : the smallest (positive) float number.
- __LPC_NOSAVE__ : always defined
- __LPC_STRUCTS__ : defined when struct support is enabled.
- Once structs are fully supported, this macro
- will always be defined.
- __LPC_INLINE_CLOSURES__: defined when the 'real' inline closures
- are enabled.
- __LPC_ARRAY_CALLS__: call_other()s on arrays of objects enabled.
- __BOOT_TIME__ : the time() the driver was started.
+ __LPC_NOSAVE__ : always defined.
+ __LPC_STRUCTS__ : always defined.
+ __LPC_INLINE_CLOSURES__ : always defined.
+ __LPC_ARRAY_CALLS__ : always defined.
+ __BOOT_TIME__ : the time() the driver was started.
- If the ERQ is supported, the following macros are defined:
+ If the ERQ is supported, the following macros are defined:
- __ERQ_MAX_SEND__ : the max size of the send buffer
- __ERQ_MAX_REPLY__ : the max size of the reply buffer
+ __ERQ_MAX_SEND__ : the max size of the send buffer.
+ __ERQ_MAX_REPLY__ : the max size of the reply buffer.
- The following macros are defined if their associated package
- has been compiled into the driver:
+ The following macros are defined if their associated package
+ has been compiled into the driver:
- __IDNA__ : support for IDNA
- __IPV6__ : support for IP v.6
- __MYSQL__ : support for mySQL
- __PGSQL__ : support for PostgreSQL
- __SQLITE__ : support for SQLite 3.
- __XML_DOM__ : support for XML parsing.
- __JSON__ : support for JSON parsing/serializing.
- __MCCP__: support for MCCP http://www.randomly.org/projects/MCCP
- __ALISTS__: support for alists
- __PCRE__: support for PCRE
- __TLS__: support for TLS (internal)
- __GNUTLS__: if __TLS__: TLS support provided by GnuTLS.
- __OPENSSL__: if __TLS__: TLS support provided by OpenSSL.
- __GCRYPT__: cryptographic routines provided by libgcrypt.
- __DEPRECATED__: support for obsolete and deprecated efuns.
-
+ __IDNA__ : support for IDNA.
+ __IPV6__ : support for IP v.6.
+ __MYSQL__ : support for mySQL.
+ __PGSQL__ : support for PostgreSQL.
+ __SQLITE__ : support for SQLite 3.
+ __XML_DOM__ : support for XML parsing.
+ __MCCP__ : support for MCCP.
+ http://www.randomly.org/projects/MCCP
+ __ALISTS__ : support for alists.
+ __PCRE__ : support for PCRE (always defined).
+ __TLS__ : support for TLS (internal).
+ __GNUTLS__ : if __TLS__: TLS support provided by
+ GnuTLS.
+ __OPENSSL__ : if __TLS__: TLS support provided by
+ OpenSSL.
+ __GCRYPT__ : cryptographic routines provided by
+ libgcrypt.
+ __DEPRECATED__ : support for obsolete and deprecated efuns.
HISTORY
- 3.2.1 added __DOMAIN_NAME__, __HOST_IP_NUMBER__, __HOST_NAME__,
- __MAX_RECURSION__, __EFUN_DEFINED__().
- 3.2.5 added __COMPAT_MODE__, __NATIVE_MODE__, __EUIDS__,
- __ERQ_MAX_SEND__ and __ERQ_MAX_REPLY__.
- 3.2.6 added __MAX_EVAL_COST__.
- 3.2.7 added __STRICT_EUIDS__ and made __EUIDS__ standard.
- 3.2.8 added __IPV6__, __LPC_NOSAVE__, __DIR__, __PATH__().
- 3.2.9 added __LDMUD__, __MYSQL__, __DEPRECATED__, __VERSION_MAJOR__,
- __VERSION_MINOR__, __VERSION_MICRO__, __VERSION_PATCH__,
- __INT_MAX__, __INT_MIN__, __FLOAT_MIN__, __FLOAT_MAX__,
- __CATCH_EVAL_COST__, __MASTER_EVAL_COST__, __RESET_TIME__,
- __CLEANUP_TIME__, __DRIVER_LOG__, and __WIZLIST__.
- 3.2.10 added __MAX_MALLOC__, __MSDOS_FS__, __LPC_ARRAY_CALLS__
- and __FILENAME_SPACES__.
- 3.3 made __LPC_NOSAVE__ always defined and added __ALISTS__,
- __MCCP__, __LPC_STRUCTS__, __LPC_INLINE_CLOSURES__, __PGSQL__,
- __PTHREADS__, __TLS__, __BOOT_TIME__, __ALARM_TIME__,
- __HEART_BEAT_INTERVAL__, __SYNCHRONOUS_HEART_BEAT__, and __PCRE__.
- 3.3.713 added __IDNA__, __SQLITE__.
- 3.3.714 added __OPENSSL__, __GNUTLS__.
- 3.3.718 added __XML_DOM__.
- 3.3.719 removed __PTHREADS__, AMIGA, MSDOS_FS, __BEOS__
- and added __GCRYPT__.
- 3.3.721 added __FUNCTION__.
+ 3.2.1 added __DOMAIN_NAME__, __HOST_IP_NUMBER__, __HOST_NAME__,
+ __MAX_RECURSION__, __EFUN_DEFINED__().
+ 3.2.5 added __COMPAT_MODE__, __NATIVE_MODE__, __EUIDS__,
+ __ERQ_MAX_SEND__ and __ERQ_MAX_REPLY__.
+ 3.2.6 added __MAX_EVAL_COST__.
+ 3.2.7 added __STRICT_EUIDS__ and made __EUIDS__ standard.
+ 3.2.8 added __IPV6__, __LPC_NOSAVE__, __DIR__, __PATH__().
+ 3.2.9 added __LDMUD__, __MYSQL__, __DEPRECATED__, __VERSION_MAJOR__,
+ __VERSION_MINOR__, __VERSION_MICRO__, __VERSION_PATCH__,
+ __INT_MAX__, __INT_MIN__, __FLOAT_MIN__, __FLOAT_MAX__,
+ __CATCH_EVAL_COST__, __MASTER_EVAL_COST__, __RESET_TIME__,
+ __CLEANUP_TIME__, __DRIVER_LOG__, and __WIZLIST__.
+ 3.2.10 added __MAX_MALLOC__, __MSDOS_FS__, __LPC_ARRAY_CALLS__
+ and __FILENAME_SPACES__.
+ 3.3 made __LPC_NOSAVE__ always defined and added __ALISTS__,
+ __MCCP__, __LPC_STRUCTS__, __LPC_INLINE_CLOSURES__, __PGSQL__,
+ __PTHREADS__, __TLS__, __BOOT_TIME__, __ALARM_TIME__,
+ __HEART_BEAT_INTERVAL__, __SYNCHRONOUS_HEART_BEAT__, and __PCRE__.
+ 3.3.713 added __IDNA__, __SQLITE__.
+ 3.3.714 added __OPENSSL__, __GNUTLS__.
+ 3.3.718 added __XML_DOM__.
+ 3.3.719 removed __PTHREADS__, AMIGA, MSDOS_FS, __BEOS__
+ and added __GCRYPT__.
+ 3.3.721 added __FUNCTION__.
+ 3.5.0 changed __LPC_STRUCTS__, __LPC_INLINE_CLOSURES__,
+ __LPC_ARRAY_CALLS__ to be always on.
+ removed __ALISTS__
SEE ALSO
- pragma(LPC), preprocessor(LPC)
+ pragma(LPC), preprocessor(LPC)
diff --git a/doc/hook/auto_include b/doc/hook/auto_include
index a82adda..14683f5 100644
--- a/doc/hook/auto_include
+++ b/doc/hook/auto_include
@@ -10,9 +10,8 @@
, int sys_include)
DESCRIPTION
- Optional hook specifying a string to be included before
- the source of every compiled LPC object.
- Hook setting can be a string or a closure.
+ Optional hook specifying a string to be included before the source of
+ every compiled LPC object. Hook setting can be a string or a closure.
If the setting is a string, it will be automatically included before
the source of every compiled LPC object.
diff --git a/doc/hook/clean_up b/doc/hook/clean_up
index e00521a..d72999d 100644
--- a/doc/hook/clean_up
+++ b/doc/hook/clean_up
@@ -9,9 +9,8 @@
void|int <name>(int ref)
DESCRIPTION
- Optional hook to clean up an object.
- Hook setting can be any closure, or the name of the function
- to call in the object.
+ Optional hook to clean up an object. Hook setting can be any
+ closure, or the name of the function to call in the object.
This hook is called for an object if it hasn't been used
for at least TIME_TO_CLEAN_UP seconds, to give it the
@@ -37,7 +36,7 @@
the call has to result in a non-zero value.
If the hook specifies a non-existing lfun, or if the call
- returns 0, no further attempt to clean up this object will be done.
+ returns 0, no further attempt to clean up this object will be made.
HISTORY
diff --git a/doc/hook/clone_uids b/doc/hook/clone_uids
index 4bf902a..8d85790 100644
--- a/doc/hook/clone_uids
+++ b/doc/hook/clone_uids
@@ -9,12 +9,12 @@
DESCRIPTION
Mandatory hooks to determine the uid and euid of cloned
- objects. Hook settings can be any closure.
+ objects. Hook settings can be any closure.
When an object is cloned, the H_CLONE_UIDS hook is called with
- the blueprint object as first and the clone's designated name
- as second argument. The new object already exists, but has 0
- uids.
+ the blueprint object as the first argument and the clone's
+ designated name as the second. The new object already exists,
+ but has 0 uids.
For the result, the following possibilities exist (<num> is
a non-zero number, <no-string> is anything but a string):
diff --git a/doc/hook/create_clone b/doc/hook/create_clone
index bf3100e..3b349b7 100644
--- a/doc/hook/create_clone
+++ b/doc/hook/create_clone
@@ -16,7 +16,7 @@
If the hook is a closure expecting an argument, it is bound
to the current object and called with the created object as
- argument. If the hook as a closure without arguments, it is bound to
+ argument. If the hook is a closure without arguments, it is bound to
the object to be initalized and called.
If the result of the closure call is a non-zero number, it is used
diff --git a/doc/hook/create_ob b/doc/hook/create_ob
index 7de7ba3..3bb8798 100644
--- a/doc/hook/create_ob
+++ b/doc/hook/create_ob
@@ -10,14 +10,14 @@
int <closure> (object obj_to_init)
DESCRIPTION
- Optional hooks to initialize an explictely loaded
- object/blueprint after creation. Hook setting can be unbound
- lambda closures, or the name of the function (static or public) to
+ Optional hooks to initialize an explicitly loaded
+ object/blueprint after creation. Hook setting can be unbound
+ lambda closures or the name of the function (static or public) to
call in the object.
If the hook is a closure expecting an argument, it is bound
to the current object and called with the created object as
- argument. If the hook as a closure without arguments, it is bound to
+ argument. If the hook is a closure without arguments, it is bound to
the object to be initalized and called.
If the result of the closure call is a non-zero number, it is used
@@ -25,7 +25,7 @@
interval computed from TIME_TO_RESET is used.
If the hook is defined as the name of an lfun in the object,
- it is called in the object with 0 as argument, and any result
+ it is called in the object with 0 as argument and any result
is ignored.
HISTORY
diff --git a/doc/hook/create_super b/doc/hook/create_super
index a502730..0e51a4b 100644
--- a/doc/hook/create_super
+++ b/doc/hook/create_super
@@ -12,20 +12,21 @@
DESCRIPTION
Optional hooks to initialize a blueprint which is loaded by
inheritance after creation.
+
Hook setting can be unbound lambda closures, or the name of
the function (static or public) to call in the object.
If the hook is a closure expecting an argument, it is bound
to the current object and called with the created object as
- argument. If the hook as a closure without arguments, it is bound to
- the object to be initalized and called.
+ argument. If the hook is a closure without arguments, it is bound to
+ the object to be initialized and called.
If the result of the closure call is a non-zero number, it is used
as the interval to wait before the first reset(), else the default
interval computed from TIME_TO_RESET is used.
If the hook is defined as the name of an lfun in the object,
- it is called in the object with 0 as argument, and any result
+ it is called in the object with 0 as argument and any result
is ignored.
HISTORY
diff --git a/doc/hook/default_method b/doc/hook/default_method
index 427a131..9f3cbab 100644
--- a/doc/hook/default_method
+++ b/doc/hook/default_method
@@ -36,7 +36,6 @@
If the hook can not (or doesn't want to) resolve the call, it
has to return 0.
-
HISTORY
Introduced in LDMud 3.3.113
diff --git a/doc/hook/default_prompt b/doc/hook/default_prompt
index 6231bb4..b3cfa55 100644
--- a/doc/hook/default_prompt
+++ b/doc/hook/default_prompt
@@ -14,8 +14,8 @@
The hook can be given as string or as closure. If it is a
closure, it is called with the commandgiver being the calling
- object. If the result is a string, it will be printed,
- otherwise ignored.
+ object. If the result is a string it will be printed,
+ otherwise it will be ignored.
HISTORY
Introduced in LDMud 3.3.163.
diff --git a/doc/hook/erq_stop b/doc/hook/erq_stop
index a135a1c..c5e08e3 100644
--- a/doc/hook/erq_stop
+++ b/doc/hook/erq_stop
@@ -9,7 +9,7 @@
DESCRIPTION
Optional hook to notify the mudlib about the termination of
- the erq demon. Hook setting may be any closure.
+ the erq demon. Hook setting may be any closure.
The closure is called without arguments and may do whatever it
likes to clean-up after the erq.
diff --git a/doc/hook/file_encoding b/doc/hook/file_encoding
new file mode 100644
index 0000000..3c7c6d8
--- /dev/null
+++ b/doc/hook/file_encoding
@@ -0,0 +1,27 @@
+SYNOPSIS
+ #include <sys/driver_hooks.h>
+
+ set_driver_hook(H_FILE_ENCODING, value)
+
+ <value> being:
+
+ string <text>
+ string <closure>(string filename)
+
+DESCRIPTION
+ Optonal hook specifying the name of the encoding to be used
+ for decoding a file. Hook setting can be a string or a closure.
+
+ If no hook was specified or the closure returns 0, then the
+ default "ascii" is used (and thus will throw an error upon
+ chars greater than 0x7f in the file).
+
+ If the settings is a closure, it will be called for every file
+ opened by the compiler or by read_file() and write_file()
+ (unless an explicit encoding was given).
+
+HISTORY
+ Introduced in LDMud 3.5.1
+
+SEE ALSO
+ hooks(C)
diff --git a/doc/hook/hook b/doc/hook/hook
index 3218445..7e66879 100644
--- a/doc/hook/hook
+++ b/doc/hook/hook
@@ -11,6 +11,7 @@
Some of the hooks are mandatory, some not. Most hooks accept
unbound lambda closures as values, some also lfun closures or
even strings.
+
The hooks are identified by an ordinal number, for which
symbolic names are defined in /sys/driverhooks.h.
diff --git a/doc/hook/include_dirs b/doc/hook/include_dirs
index 6557359..9ee2fb6 100644
--- a/doc/hook/include_dirs
+++ b/doc/hook/include_dirs
@@ -11,7 +11,7 @@
DESCRIPTION
Semi-mandatory hook specifying the directories where <>-type
include files are searched (this includes ""-includes not
- found as specified). Hook setting may be any closure or a
+ found as specified). Hook setting may be any closure or a
string array. If not set, only ""-type includes may be used in LPC
programs.
@@ -27,9 +27,9 @@
If the setting is a closure, it is called with the name of the
desired include file as first, and the name of the compiled
- LPC file as second argument. Result has to be the complete
+ LPC file as second argument. Result has to be the complete
path name of the include file to use. Leading slashes may be
- omitted. If the closure is a lambda closure, it is bound to
+ omitted. If the closure is a lambda closure, it is bound to
this_object() prior to execution.
HISTORY
diff --git a/doc/hook/load_uids b/doc/hook/load_uids
index 9d1e160..7221dd5 100644
--- a/doc/hook/load_uids
+++ b/doc/hook/load_uids
@@ -9,10 +9,10 @@
DESCRIPTION
Mandatory hooks to determine the uid and euid of loaded or
- cloned objects. Hook settings can be any closure.
+ cloned objects. Hook settings can be any closure.
When an object is newly loaded, the H_LOAD_UIDS hook is called
- with the object name as argument. The new object already
+ with the object name as argument. The new object already
exists, but has 0 uids.
For the result, the following possibilities exist (<num> is
diff --git a/doc/hook/no_echo b/doc/hook/no_echo
index b592529..fb30b9b 100644
--- a/doc/hook/no_echo
+++ b/doc/hook/no_echo
@@ -11,10 +11,10 @@
DESCRIPTION
Optional hook to specifiy how to perform the telnet actions to
switch the echo mode (used for e.g. password input_to()s).
- Hook setting may be any closure or a string. If not set, a
+ Hook setting may be any closure or a string. If not set, a
default handling is performed.
- If the setting is a string, it used as name of an lfun to call
+ If the setting is a string, it is used as name of an lfun to call
in the interactive <user>, where <flag> is the echo-flag
passed to the input_to() statement.
diff --git a/doc/hook/notify_fail b/doc/hook/notify_fail
index 8a4bacf..d229a55 100644
--- a/doc/hook/notify_fail
+++ b/doc/hook/notify_fail
@@ -11,7 +11,7 @@
DESCRIPTION
Mandatory hook to issue the default message if an entered
command couldn't be parsed and no notify_fail() command is in
- effect. Hook setting can be a any closure, or a string.
+ effect. Hook setting can be a any closure, or a string.
If set to a string, it is the message returned to the
player.
diff --git a/doc/hook/reset b/doc/hook/reset
index 23f1dea..dcb1c9d 100644
--- a/doc/hook/reset
+++ b/doc/hook/reset
@@ -9,23 +9,23 @@
void <name>(1)
DESCRIPTION
- Optional hook to reset an object.
- Hook setting can be unbound lambda closures, or the name of
- the function (static or public) to call in the object.
+ Optional hook to reset an object. Hook setting can be unbound
+ lambda closures, or the name of the function (static or public)
+ to call in the object.
If the hook is a closure, it is bound to the object to be
reset and called with no argument.
If the result of this call is a positive number, it is used as
- the interval to wait before the next reset(). If the result
+ the interval to wait before the next reset(). If the result
is 0, the default interval computed from TIME_TO_RESET is
- used. If the result is a negative number, the object will not
+ used. If the result is a negative number, the object will not
be reset again, unless directed otherwise by set_next_reset().
If the hook is defined as the name of an lfun in the object,
it is called in the object with 1 as argument, and any result
- is ignored. In this call the previous_object() is the object
- initiating the reset. If the function does not exist, the
+ is ignored. In this call the previous_object() is the object
+ initiating the reset. If the function does not exist, the
object won't be reset again.
Note that an object is only reset by call to this hook if it
diff --git a/doc/hook/telnet_neg b/doc/hook/telnet_neg
index 0f8b8c1..937c5b7 100644
--- a/doc/hook/telnet_neg
+++ b/doc/hook/telnet_neg
@@ -10,7 +10,7 @@
DESCRIPTION
Optional hook to specifiy how to perform a single telnet
- negotiation. Hook setting may be any closure or a string. If
+ negotiation. Hook setting may be any closure or a string. If
not set, most telnet options are rejected (read: only a very
minimal negotiation takes place).
@@ -30,10 +30,9 @@
Alternatively, if H_NOECHO is set, this hook is called for
_all_ telnet data received.
- If the setting is a string, it used as name of an lfun to call
- in this_player(). Closures are just called, with unbound
- lambda-closures being bound to this_player() prior to
- execution.
+ If the setting is a string, it used as the name of an lfun to
+ call in this_player(). Closures are just called, with unbound
+ lambda-closures being bound to this_player() prior to execution.
The hook is called for a 'DO/DONT/WILL/WONT <opt>' with the action
(DO/DONT/...) as the first, and <opt> as the second argument.
@@ -42,7 +41,7 @@
IAC SB <opt> <opts>...
- followed by IAC SB/SE, the hook is called with 'SB' as first
+ followed by IAC SB/SE, the hook is called with 'SB' as first
argument, <opt> as second, and <opts> as an array of integers as
third argument.
diff --git a/doc/master/compile_object b/doc/master/compile_object
index 1b55658..b9425bd 100644
--- a/doc/master/compile_object
+++ b/doc/master/compile_object
@@ -1,11 +1,11 @@
SYNOPSIS
- object compile_object(string filename)
+ object compile_object(string filename)
DESCRIPTION
- This function is caled if the interpreter cannot find the
- file for an object to be loaded. The master object has now
- the opportunity to return an object that will then serve as if
- compiled from the given filename.
+ This function is caled if the interpreter cannot find the
+ file for an object to be loaded. The master object has now
+ the opportunity to return an object that will then serve as if
+ compiled from the given filename.
- If 0 is returned, the usual ``Could not load descr for'' error
- will occur.
+ If 0 is returned, the usual "Could not load descr for" error
+ will occur.
diff --git a/doc/master/connect b/doc/master/connect
index a1c7315..d98f5d5 100644
--- a/doc/master/connect
+++ b/doc/master/connect
@@ -1,13 +1,26 @@
SYNOPSIS
- object connect(void)
+ object connect(void)
DESCRIPTION
- Return a login object that the requested connection should be
- bound to. Note that the connection is not bound yet.
+ Return a login object that the requested connection should be
+ bound to.
- The lfun logon() will be applied to the login object after
- binding the connection to it. That lfun has to return != 0 to
- indicate success.
+ Note that the connection is at this time bound to the master object,
+ and will be re-bound to the returned object.
+
+ The lfun logon() will be applied to the login object after
+ binding the connection to it. That lfun has to return != 0 to
+ indicate success.
+
+ If connect() initiates a secure connection without setting a callback,
+ and the connection is still handshaking at the time connect() returns,
+ the driver will delay the call to logon() until the handshake either
+ succeeds or fails.
+
+HISTORY
+ LDMud 3.2.13/3.3.713 streamlined the handling of secure connections
+ during logon.
SEE ALSO
- logon(A), disconnect(M), interactive(E), exec(E)
+ logon(A), disconnect(M), interactive(E), exec(E),
+ net_connect(E), tls_init_connection(E)
diff --git a/doc/master/dangling_lfun_closure b/doc/master/dangling_lfun_closure
index 6bfaeb5..0bd881f 100644
--- a/doc/master/dangling_lfun_closure
+++ b/doc/master/dangling_lfun_closure
@@ -1,26 +1,30 @@
SYNOPSIS
- void dangling_lfun_closure()
+ void dangling_lfun_closure()
DESCRIPTION
- Handle a dangling lfun-closure.
+ Handle a dangling lfun-closure.
- This is called when the gamedriver executes a closure using a
- vanished lfun. A proper handling is to raise a runtime error.
+ This is called when the gamedriver executes a closure using a
+ vanished lfun, with previous_object() showing the originating
+ object. A proper handling is to raise a runtime error.
- Technical:
- Upon replacing programs (see efun replace_program()), any
- existing lambda closures of the object are adjusted to the
- new environment. If a closure uses a lfun which vanished in
- the replacement process, the reference to this lfun is
- replaced by a reference to this function. The error will
- then occur when the execution of the adjusted lambda reaches
- the point of the lfun reference. There are two reasons for
- the delayed handling. First is that the program replacement
- and with it the closure adjustment happens at the end of a
- backend cycle, outside of any execution thread: noone would
- see the error at this time. Second, smart closures might
- know/recognize the program replacement and skip the call to
- the vanished lfun.
+ Technical:
+ Upon replacing programs (see efun replace_program()), any
+ existing lambda closures of the object are adjusted to the
+ new environment. If a closure uses a lfun which vanished in
+ the replacement process, the reference to the lfun is
+ replaced by an alien-lfun closure referencing to this function.
+ The error will then occur when the execution of the adjusted lambda
+ reaches the point of the lfun reference. There are two reasons for
+ the delayed handling. First is that the program replacement and with
+ it the closure adjustment happens at the end of a backend cycle,
+ outside of any execution thread: noone would see the error at this
+ time. Second, smart closures might know/recognize the program
+ replacement and skip the call to the vanished lfun.
+
+HISTORY
+ Since LDMud 3.2.9, all references to dangling_lfun_closure() are
+ created as alien-lfun closures.
SEE ALSO
- closures(LPC)
+ closures(LPC)
diff --git a/doc/master/disconnect b/doc/master/disconnect
index f7a9f3d..5f54c5f 100644
--- a/doc/master/disconnect
+++ b/doc/master/disconnect
@@ -1,13 +1,27 @@
SYNOPSIS
- void disconnect(object ob)
+ void disconnect(object ob, string remaining)
DESCRIPTION
- Handle the loss of the IP connection for the (formerly)
- interactive object ob. The connection can be lost because the
- the underlying transport connection was lost (``netdead''), or
- because of a call to exec() or remove_interactive(). The
- connection will be unbound upon return from this call.
+ Handle the loss of the IP connection for the (formerly)
+ interactive object <ob>. The connection can be lost because the
+ the underlying transport connection was lost ('netdead'), or
+ because of a call to exec() or remove_interactive().
+
+ <remaining> is a string holding the remaining unread input data from
+ the connection, if any. This data is unprocessed just as it was
+ received.
+
+ The connection will be unbound upon return from this call, so
+ for the time of this call, interactive(ob) will still
+ return TRUE even if the actual network connection has already
+ been lost.
+
+ This method is not called if the object has been destructed
+ already.
+
+HISTORY
+ LDMud 3.3.713 added the second argument for the remaining input data.
SEE ALSO
- connect(M), remove_player(M), remove_interactive(E), exec(E),
- interactive(E)
+ connect(M), remove_player(M), remove_interactive(E), exec(E),
+ interactive(E)
diff --git a/doc/master/epilog b/doc/master/epilog
index eb51d75..b065d26 100644
--- a/doc/master/epilog
+++ b/doc/master/epilog
@@ -1,24 +1,16 @@
SYNOPSIS
- void epilog(void) /* compat in 3.2 */
- string *epilog(int eflag) /* !compat or 3.2.1 */
+ string *epilog(int eflag)
DESCRIPTION
- Perform final actions before opening the system to users.
- The semantics of this function differ for compat and !compat
- mode, and between 3.2 and 3.2.1.
+ Perform final actions before opening the system to users.
- Compat in 3.2: the objects from the INIT_FILE (#defined to
- "room/init_file" at compile time in the parser) are already
- loaded at this time. Normally there is nothing left to do for
- this function.
+ The argument is the number of -e options that were
+ given to the parser on the commandline. Normally it is just 0
+ or 1. The function should return an array of strings, which
+ traditionally denote the objects to be preloaded with
+ master->preload(). Any other return value is interpreted as
+ "no object to preload". The resulting strings will be passed
+ one at a time as arguments to preload().
- !Compat and 3.2.1: the argument is the number of -e options that were
- given to the parser on the commandline. Normally it is just 0
- or 1. The function should return an array of strings, which
- traditionally denote the objects to be preloaded with
- master->preload(). Any other return value is interpreted as
- ``no object to preload''. The resulting strings will be passed
- one at a time as arguments to preload().
-
-SEE ALSO
- preload(M), master(M)
+SEE ALSO
+ preload(M), master(M)
diff --git a/doc/master/external_master_reload b/doc/master/external_master_reload
index 57913f0..8768506 100644
--- a/doc/master/external_master_reload
+++ b/doc/master/external_master_reload
@@ -1,10 +1,10 @@
SYNOPSIS
- void external_master_reload()
+ void external_master_reload()
DESCRIPTION
- Master was reloaded on external request by SIGUSR1.
- It will be called after inaugurate_master() of course.
- If you plan to do additional magic here, you're welcome.
+ Master was reloaded on external request by SIGUSR1.
+ It will be called after inaugurate_master() of course.
+ If you plan to do additional magic here, you're welcome.
SEE ALSO
- inaugurate_master(M)
+ inaugurate_master(M)
diff --git a/doc/master/flag b/doc/master/flag
index e04e91d..dccb52b 100644
--- a/doc/master/flag
+++ b/doc/master/flag
@@ -1,41 +1,41 @@
SYNOPSIS
- void flag(string arg)
+ void flag(string arg)
DESCRIPTION
- Evaluate an argument given as option '-f' to the driver.
- If several '-f' options are given, this function will be
- called sequentially with all given arguments.
- This function can be used to pass the master commands via
- arguments to the driver. This is useful when building a new
- mudlib from scratch. It is called only when the system is
- started.
+ Evaluate an argument given as option '-f' to the driver.
+ If several '-f' options are given, this function will be
+ called sequentially with all given arguments.
+ This function can be used to pass the master commands via
+ arguments to the driver. This is useful when building a new
+ mudlib from scratch. It is called only when the system is
+ started.
EXAMPLE
- // The code given implements these commands:
- // '-fcall <ob> <fun> <arg>': call function <fun> in object <ob> with
- // argument <arg>.
- // '-fshutdown': shutdown the system immediately.
- // Thus, starting the driver as
- // 'parse "-fcall foo bar Yow!" -fshutdown' would
- // first do foo->bar("Yow!") and then shut down the system.
+ // The code given implements these commands:
+ // '-fcall <ob> <fun> <arg>': call function <fun> in object <ob> with
+ // argument <arg>.
+ // '-fshutdown': shutdown the system immediately.
+ // Thus, starting the driver as
+ // 'parse "-fcall foo bar Yow!" -fshutdown' would
+ // first do foo->bar("Yow!") and then shut down the system.
- {
- string obj, fun, rest;
+ {
+ string obj, fun, rest;
- if (arg == "shutdown")
- {
- shutdown();
- return;
- }
- if (sscanf(arg, "call %s %s %s", obj, fun, rest) >= 2)
- {
- write(obj+"->"+fun+"(\""+rest+"\") = ");
- write(call_other(obj, fun, rest));
- write("\n");
- return;
- }
- write("master: Unknown flag "+arg+"\n");
- }
+ if (arg == "shutdown")
+ {
+ shutdown();
+ return;
+ }
+ if (sscanf(arg, "call %s %s %s", obj, fun, rest) >= 2)
+ {
+ write(obj+"->"+fun+"(\""+rest+"\") = ");
+ write(call_other(obj, fun, rest));
+ write("\n");
+ return;
+ }
+ write("master: Unknown flag "+arg+"\n");
+ }
SEE ALSO
- master(M)
+ master(M)
diff --git a/doc/master/get_bb_uid b/doc/master/get_bb_uid
index 5a4dc8b..2be9c89 100644
--- a/doc/master/get_bb_uid
+++ b/doc/master/get_bb_uid
@@ -1,18 +1,18 @@
SYNOPSIS
- string get_bb_uid(void)
+ string get_bb_uid(void)
DESCRIPTION
- Is called to get the ``backbone id''. Objects whose creator is
- the backbone id are ``trusted'', and will automagically get
- the uid and euid of the object that caused to load or clone
- them.
+ This method is called when efun process_string() is used without a
+ current object (e.g. from notify_fail method). The current object
+ will be set to the current command giver, and will receive the euid
+ returned from this function.
- The backbone id is also temporary given to objects while being
- called via process_string().
+ If strict-euids, this function must exist and return a string.
+ Otherwise the function is optional and/or may return 0.
HISTORY
- Since 3.2.1, get_bb_uid() is needed just for process_string()
- if no this_object() is present.
+ Since 3.2.1, get_bb_uid() is needed just for process_string()
+ if no this_object() is present.
SEE ALSO
- uids(C), creator_file(M), creator(E), get_root_id(M)
+ uids(C), creator_file(M), creator(E), get_master_uid(M)
diff --git a/doc/master/get_ed_buffer_save_file_name b/doc/master/get_ed_buffer_save_file_name
index 50a23c3..e13e66b 100644
--- a/doc/master/get_ed_buffer_save_file_name
+++ b/doc/master/get_ed_buffer_save_file_name
@@ -1,22 +1,22 @@
SYNOPSIS
- string get_ed_buffer_save_object_name(string edited_file)
+ string get_ed_buffer_save_file_name(string edited_file)
DESCRIPTION
- This function is called when an interactive user object is
- destructed or looses connection through remove_interactive()
- while editing with ed() the file edite_file (emergency save).
- this_player() is set to the object that loosing connection.
- The function should return a file name for the emergency save
- file.
+ This function is called when an interactive user object is
+ destructed or loses connection through remove_interactive()
+ while editing with ed() the file edited_file (emergency save).
+ this_player() is set to the object that lost connection.
+ The function should return a file name for the emergency save
+ file.
EXAMPLE
- string get_ed_buffer_save_object_name(string file) {
- return "/players/"+getuid(this_player())+"/.dead_ed_files/"
- + explode(file, "/")[<1];
- }
+ string get_ed_buffer_save_file_name(string file) {
+ return "/players/"+getuid(this_player())+"/.dead_ed_files/"
+ + explode(file, "/")[<1];
+ }
- This breaks up file into its components and stores it in the
- user's emergency save directory under the file's basename.
+ This breaks up file into its components and stores it in the
+ user's emergency save directory under the file's basename.
SEE ALSO
- ed(E), destruct(E), remove_interactive(E), valid_write(M)
+ ed(E), destruct(E), remove_interactive(E), valid_write(M)
diff --git a/doc/master/get_master_uid b/doc/master/get_master_uid
index a0c6737..3cc7985 100644
--- a/doc/master/get_master_uid
+++ b/doc/master/get_master_uid
@@ -1,12 +1,12 @@
SYNOPSIS
- string get_master_uid(void)
+ string get_master_uid(void)
DESCRIPTION
- Return the string to be used as root-uid.
- Under !native, the function is expendable.
+ Return the string to be used as root-uid.
+ Under !strict_euids, the function is expendable.
HISTORY
- Introduced in 3.2.1@40 replacing get_root_uid().
+ Introduced in 3.2.1@40 replacing get_root_uid().
SEE ALSO
- get_bb_uid(M), get_master_uid(M), uids(C), creator_file(M), creator(E)
+ get_bb_uid(M), get_master_uid(M), uids(C), creator_file(M), creator(E)
diff --git a/doc/master/get_simul_efun b/doc/master/get_simul_efun
index 88adba0..ac6f582 100644
--- a/doc/master/get_simul_efun
+++ b/doc/master/get_simul_efun
@@ -1,24 +1,20 @@
SYNOPSIS
- mixed get_ simul_efun(void) // 3.2
- string|string* get_simul_efun(void) // 3.2.1
+ string|string* get_simul_efun(void)
DESCRIPTION
- Load the simul_efun object(s) and return one or more paths of it.
-// Note that the object(s) must be loaded by this function!
-//
-// When you return an array of strings, the first string is taken as path
-// to the simul_efun object, and all other paths are used for backup
-// simul_efun objects to call simul_efuns that are not present in the
-// main simul_efun object. This allows to remove simul_efuns at runtime
-// without getting errors from old compiled programs that still use the
-// obsolete simul_efuns. A side use of this mechanism is to provide
-// a 'spare' simul_efun object in case the normal one fails to load.
-//
- Should return either the object_name of the simul_efun object as
- a string, or an array containing as first element a string
- with the file name of the simul_efun object and the following
- elements strings with file names of alternate simul_efun
- objects that will be used if the first one cannot be loaded.
+ Load the simul_efun object(s) and return one or more paths of it.
+
+ Note that the object(s) must be loaded by this function!
+
+ When you return an array of strings, the first string is taken as path
+ to the simul_efun object, and all other paths are used for backup
+ simul_efun objects to call simul_efuns that are not present in the
+ main simul_efun object. This allows the removal of simul_efuns at
+ runtime without getting errors from old compiled programs that still
+ use the obsolete simul_efuns.
+
+ The additional simul-efun objects can not serve as backups for
+ the primary one!
SEE ALSO
- simul_efun(C)
+ simul_efun(C)
diff --git a/doc/master/get_wiz_name b/doc/master/get_wiz_name
index 6056965..81befb7 100644
--- a/doc/master/get_wiz_name
+++ b/doc/master/get_wiz_name
@@ -1,13 +1,12 @@
SYNOPSIS
- string get_wiz_name(string file)
+ string get_wiz_name(string file)
DESCRIPTION
- Argument is a file name, which we want to get the owner of.
- This used for the wizlist, to determine who gets the score for
- the file being used.
+ Argument is a file name, which we want to get the owner of.
+ This used for the wizlist, to determine who gets the score for
+ the file being used.
- For 3.2.1, it is used only to score errors to the right wizard.
+ This call is used only to score errors to the right wizard.
SEE ALSO
- wizlist(E), get_wiz_info(E), query_real_name(A),
- query_creator(M), getuid(E)
+ wizlist(E), get_wiz_info(E), query_creator(M), getuid(E)
diff --git a/doc/master/heart_beat_error b/doc/master/heart_beat_error
index d4d15f2..11985b8 100644
--- a/doc/master/heart_beat_error
+++ b/doc/master/heart_beat_error
@@ -1,24 +1,30 @@
SYNOPSIS
- mixed heart_beat_error(object culprit, string err, string prg,
- string curobj, int line)
+ mixed heart_beat_error(object culprit, string err, string prg,
+ string curobj, int line, int caught)
DESCRIPTION
- This function is called when a runtime error occurs while
- executing the heart_beat() function of the object culprit. prg
- is program where the actual error happened, in object curobj
- at the given line.
+ This function is called when a runtime error occurs while
+ executing the heart_beat() function of the object culprit. prg
+ is program where the actual error happened, in object curobj
+ at the given line.
- At time of call, the heart_beat has been turned off.
- Return anything != 0 to restart the heart_beat in culprit.
+ At time of call, the heart_beat has been turned off.
+ Return anything != 0 to restart the heart_beat in culprit.
- If culprit is a user, it should at least get the message ``You
- have no heartbeat''. A more advanced handling would destruct
- the offending object curobj and and allow the heartbeat to
- restart.
+ If culprit is a user, it should at least get the message "You
+ have no heartbeat". A more advanced handling would destruct
+ the offending object curobj and and allow the heartbeat to
+ restart.
- Note that prg denotes the program actually executed (which
- might be an inherited one) whereas curobj is just the
- offending object.
+ If the error is caught on a higher level, <caught> is non-zero;
+ otherwise it is 0.
+
+ Note that prg denotes the program actually executed (which
+ might be an inherited one) whereas curobj is just the
+ offending object.
+
+HISTORY
+ LDMud 3.2.12/3.3.705 added the <caught> argument.
SEE ALSO
- set_heart_beat(E), heart_beat(A), runtime_error(M)
+ set_heart_beat(E), heart_beat(A), runtime_error(M)
diff --git a/doc/master/inaugurate_master b/doc/master/inaugurate_master
index 85c9526..2cf612b 100644
--- a/doc/master/inaugurate_master
+++ b/doc/master/inaugurate_master
@@ -1,30 +1,29 @@
SYNOPSIS
- void inaugurate_master(int arg)
+ void inaugurate_master(int arg)
DESCRIPTION
- This function is called in the master object after it has been
- created and is fully functional. Note that the create()
- function is of little use in the master object, because at the
- time it is called there is no simul_efun object yet, and the
- interpreter does not know anything about the user-ids and
- access permissions.
+ This function is called in the master object after it has been
+ created and is fully functional. Note that the create()
+ function is of little use in the master object, because at the
+ time it is called there is no simul_efun object yet, and the
+ interpreter does not know anything about the user-ids and
+ access permissions.
- The argument <arg> denotes why this function is called:
- arg = 0: the mud just started, this is the first master of all.
- = 1: the master was destructed and then reactivated
- (because a new one couldn't be loaded).
- = 2: the master was destructed and then reactivated, but
- additionally lost all variable contents.
- = 3: this is a reloaded master.
+ The argument <arg> denotes why this function is called:
+ arg = 0: the mud just started, this is the first master of all.
+ = 1: the master was destructed and then reactivated
+ (because a new one couldn't be loaded).
+ = 2: the master was destructed and then reactivated, but
+ additionally lost all variable contents.
+ = 3: this is a reloaded master.
- This function has at least to set up the driverhooks to use
- (in 3.2.1). Also, any mudwho or wizlist handling has to be
- initialized here.
+ This function has to at least set up the driverhooks to use
+ (in 3.2.1). Also, any mudwho or wizlist handling has to be
+ initialized here.
- Besides that, do whatever you feel you need to do,
- e.g. set_auto_include_string(), or give the master a decent euid.
+ Besides that, do whatever you feel you need to do,
+ e.g. set_auto_include_string(), or give the master a decent euid.
SEE ALSO
- initialisation(M), create(M), simul_efun(C), get_bb_id(M),
- get_root_id(M), get_master_uid(M), flag(M),
- reactivate_destructed_master(M)
+ initialisation(M), create(A), simul_efun(C), get_master_uid(M),
+ flag(M), reactivate_destructed_master(M)
diff --git a/doc/master/initialisation b/doc/master/initialisation
index e08d34a..89def0a 100644
--- a/doc/master/initialisation
+++ b/doc/master/initialisation
@@ -1,16 +1,15 @@
SYNOPSIS
- Initialization of the master object (since 3.2.1).
+ Initialization of the master object.
- As since 3.2.1 the lfuns which are called to initialize
- objects after a load are defined through driver hooks, and
- these hooks are cleared prior to a master (re)load, the first
- function called is inaugurate_master(). Anyway it's not very
- sensible to do anything earlier as the master is not
- recognized as such at that time, and so a number of
- (important) things would not work.
- Which lfun is called during runtime to reset the master is also
- depending on the driverhook settings. Arbitrary actions may be done
- on a reset.
+DESCRIPTION
+ As the lfuns which are called to initialize objects after a load
+ are defined through driver hooks, and these hooks are cleared
+ prior to a master (re)load, the first function called is
+ inaugurate_master(). It's not very sensible to do anything earlier
+ as the master is not recognized as such at that time, and so a
+ number of (important) things would not work. Which lfun is called
+ during runtime to reset the master also depends on the driverhook
+ settings. Arbitrary actions may be done on a reset.
SEE ALSO
- inaugurate_master(M)
+ inaugurate_master(M)
diff --git a/doc/master/log_error b/doc/master/log_error
index afc3385..9a0fd0c 100644
--- a/doc/master/log_error
+++ b/doc/master/log_error
@@ -1,11 +1,16 @@
SYNOPSIS
- void log_error(string file, string err)
+ void log_error(string file, string err, int warn)
DESCRIPTION
- Announce a compiler-time error in the named file. Whenever the
- LPC compiler detects an error, this function is called. It
- should at least log the error in a file, and also announce it
- to the active user.
+ Announce a compiler-time error (warn == 0) or warning (warn != 0)
+ in the named file.
+
+ Whenever the LPC compiler detects an error or issues a warning,
+ this function is called. It should at least log the error in a file,
+ and also announce it to the active user.
+
+HISTORY
+ LDMud 3.2.8 added the 'warn' argument and the warnings in general.
SEE ALSO
- runtime_error(M)
+ runtime_error(M)
diff --git a/doc/master/low_memory b/doc/master/low_memory
new file mode 100644
index 0000000..0621925
--- /dev/null
+++ b/doc/master/low_memory
@@ -0,0 +1,56 @@
+SYNOPSIS
+ void low_memory(int what, int limitvalue, int memory, int reservestate)
+
+DESCRIPTION
+ This efun is called when there is a (potential) low-memory situation.
+ Two different limits for the amount of allocated memory can be
+ configured: a soft limit and a hard limit. If the soft limit is
+ exceeded, the driver calls low_memory() but does nothing else.
+ If the hard limit is exceeded, the driver calls low_memory() as well,
+ but initiates a garbage collection directly after the call. The efun
+ is called as well directly before a user-initiated garbage collection
+ is started.
+
+ <what> denotes the type of limit which was exceeded:
+ - NO_MALLOC_LIMIT_EXCEEDED (0)
+ No limit was exceeded, but a garbage collection was requested by a
+ call to garbage_collection() and it will begin right after
+ low_memory() returns.
+ - SOFT_MALLOC_LIMIT_EXCEEDED (1)
+ The soft limit was exceeded.
+ - HARD_MALLOC_LIMIT_EXCEEDED (2)
+ The hard limit was exceeded. A garbage collection will begin right
+ after low_memory() returns.
+
+ <limit> specifies the numerical value of the limit which was exceeded.
+ It is 0 in case of NO_MALLOC_LIMIT_EXCEEDED.
+
+ <memory> specifies the amount of allocated memory right now.
+
+ <reservestate> specifies the current state of the memory reserves of
+ the driver. The states of the 3 different reserves are OR'ed together.
+ - USER_RESERVE_AVAILABLE (1)
+ The user reserve is available.
+ - MASTER_RESERVE_AVAILABLE (2)
+ The master reserve is available.
+ - SYSTEM_RESERVE_AVAILABLE (4)
+ The system reserve is available.
+
+ This efun might be used to inform users about the garbage collection
+ and the expected long lag.
+
+ Another possibility is to initiate a garbage collection deliberately
+ at a suitable time (e.g. during the following night) after the soft
+ limit was hit.
+
+REMARKS
+ If in a low_memory condition when the memory reserves have been used
+ already and they could not be re-allocated after a garbage collection
+ slow_shut_down() is called instead of calling this function again.
+
+HISTORY
+ Introduced in 3.3.719
+
+SEE ALSO
+ debug_info(E), garbage_collection(E), slow_shut_down(M), memory(C)
+ malloc(D)
diff --git a/doc/master/make_path_absolute b/doc/master/make_path_absolute
index e0a0019..6093b1a 100644
--- a/doc/master/make_path_absolute
+++ b/doc/master/make_path_absolute
@@ -1,10 +1,10 @@
SYNOPSIS
- string make_path_absolute(string str)
+ string make_path_absolute(string str)
DESCRIPTION
- Absolutize a relative filename str given to the editor. Should
- return the full pathname of the file to use. Any non-string
- result will act as ``bad file name''.
+ Absolutize a relative filename str given to the editor. Should
+ return the full pathname of the file to use. Any non-string
+ result will act as "bad file name".
SEE ALSO
- ed(E), valid_write(M)
+ ed(E), valid_write(M)
diff --git a/doc/master/master b/doc/master/master
index 7d88855..f94f1f7 100644
--- a/doc/master/master
+++ b/doc/master/master
@@ -1,30 +1,30 @@
NAME
- master
+ master
DESCRIPTION
- This directory contains descriptions for the functions that
- Amylaar's version of the LPC parser, expects to find in the
- master object (similar to lfuns, but for the master object
- only). The name of the master object is hardcoded in the
- parser (to "secure/master").
+ This directory contains descriptions for the functions that
+ Amylaar's version of the LPC parser, expects to find in the
+ master object (similar to lfuns, but for the master object
+ only). The name of the master object is hardcoded in the
+ parser (to "secure/master").
- The master is the gateway between the interpreter and the
- mudlib to perform actions with mudlib specific effects. Calls
- to the master by the interpreter have an automatic catch() in
- effect.
+ The master is the gateway between the interpreter and the
+ mudlib to perform actions with mudlib specific effects. Calls
+ to the master by the interpreter have an automatic catch() in
+ effect. Functions to be called by the driver can be public
+ or static, but not private.
- Note that the master is loaded first of all objects. Thus you
- shouldn't inherit an other object, nor is the compiler able to
- search include files (read: they must be specified with full
- path).
+ Note that the master is loaded first of all objects. Thus you
+ shouldn't inherit an other object, nor is the compiler able to
+ search include files (read: they must be specified with full
+ path).
- Amylaar says: actually, you can inherit, but the file will be
- loaded then before the master, which isn't good for most
- files.
+ Amylaar says: actually, you can inherit, but the file will be
+ loaded then before the master, which isn't good for most
+ files.
- Refer to 'master-3.2' and 'master-3.2.1' for the surveys of
- the masters internals.
+ Refer to 'master-all' for the survey of the masters internals.
SEE ALSO
- master-3.2(M), master-3.2.1(M)
- efun(E), applied(A), concepts(C), driver(D), lpc(LPC)
+ master-all(M)
+ efun(E), applied(A), concepts(C), driver(D), lpc(LPC)
diff --git a/doc/master/master-all b/doc/master/master-all
new file mode 100644
index 0000000..0a325bc
--- /dev/null
+++ b/doc/master/master-all
@@ -0,0 +1,234 @@
+NAME
+ master for LDMud 3.3
+
+DESCRIPTION
+ This directory contains descriptions for the functions that
+ LDMud expects to find in the master object (similar to lfuns,
+ but for the master object only). The name of the master object
+ is hardcoded in the parser, but can also be specified on
+ the commandline (usually to "secure/master").
+
+ The master is the gateway between the interpreter and the
+ mudlib to perform actions with mudlib specific effects. Calls
+ to the master by the interpreter have an automatic catch() in
+ effect. Functions to be called by the driver can be public
+ or static, but not private.
+
+ Note that the master is loaded first of all objects. Thus you
+ shouldn't inherit an other object, nor is the compiler able to
+ search include files (read: they must be specified with full
+ path).
+
+ Amylaar says: actually, you can inherit, but the file will be
+ loaded then before the master, which isn't good for most
+ files.
+
+ A short survey of the things that happen at system startup
+ time:
+
+ The Initialisation functions are called after (re)loading the
+ master to establish the most basic operation parameters.
+
+ The initialisation of the mud on startup follows this schedule:
+ - The interpreter evaluates the commandline options and
+ initializes itself.
+ - The master is loaded, but since the driverhooks are not set yet,
+ no standard initialisation lfun is called.
+ - get_master_uid() is called. If the result is valid, it becomes the
+ masters uid.
+ - inaugurate_master() is called.
+ - flag() is called for each given '-f' commandline option.
+ - get_simul_efun() is called.
+ - the WIZLIST is read in.
+ - epilog() is called. If it returns an array of strings,
+ they are given one at a time as argument to preload().
+ Traditionally, these strings are the filenames of the objects to
+ pre-load, which preload() then does.
+ - The interpreter sets up the IP communication and enters
+ the backend loop.
+
+ If the master is reloaded during system operation, these
+ actions are taken:
+ - The master is loaded, and its initialisation lfun is
+ called according to the settings of the driverhooks (if set).
+ - Any auto-include string and all driverhooks are cleared.
+ - get_master_uid() is called. If the result is valid, it becomes the
+ masters uid and euid.
+ - inaugurate_master() is called.
+
+ If the master was destructed, but couldn't be reloaded, the old
+ master object could be reactivated. In that case:
+ - reactivate_destructed_master() is called.
+ - inaugurate_master() is called.
+
+
+ Security hint: most of these functions are not useful to be
+ called directly from other objects and can be made private or
+ static. Unlike create(), these functions that are applied to
+ the master object are found by the interpreter even if not
+ publicly accessible.
+
+
+
+ A short reference to all expected master functions...
+ ----------------------------------------------------------------
+ Initialisation
+
+ void inaugurate_master ()
+ Perform mudlib specific setup of the master.
+
+ string get_master_uid ()
+ Return the string to be used as uid (and -euid) of a
+ (re)loaded master.
+
+ void flag (string arg)
+ Evaluate an argument given as option '-f' to the driver.
+
+ string *epilog (int eflag)
+ Perform final actions before opening the system to users.
+
+ void preload (string file)
+ Preload a given object.
+
+ void external_master_reload ()
+ Called after a reload of the master on external request.
+
+ void reactivate_destructed_master (int removed)
+ Reactivate a formerly destructed master.
+
+ string|string * get_simul_efun ()
+ Load the simul_efun object and return one or more paths of it.
+
+ ----------------------------------------------------------------
+ Handling of user connections
+
+ object connect ()
+ Handle the request for a new connection.
+
+ void disconnect (object obj)
+ Handle the loss of an IP connection.
+
+ void remove_player (object user)
+ Remove a user object from the system.
+
+ void stale_erq (closure callback)
+ Notify the loss of the erq demon.
+
+ -----------------------------------------------------------------
+ Runtime Support
+
+ object compile_object (string filename)
+ Compile a virtual object.
+
+ mixed include_file (string file, string compiled_file, int sys_include)
+ Return the full pathname for an included file. // 3.2.8 and later
+
+ mixed inherit_file (string file, string compiled_file)
+ Return the full pathname for an inherited object. // 3.2.8 and later
+
+ string get_wiz_name (string file)
+ Return the author of a file.
+
+ string printf_obj_name (object obj) // 3.2.6 and later
+ string object_name (object obj) // 3.2.1 .. 3.2.5
+ Return a printable name for an object.
+
+ mixed prepare_destruct (object obj)
+ Prepare the destruction of the given object.
+
+ void quota_demon (void)
+ Handle quotas in times of memory shortage.
+
+ void receive_imp (string host, string msg, int port)
+ Handle a received IMP message.
+
+ void slow_shut_down (int minutes)
+ Schedule a shutdown for the near future.
+
+ void notify_shutdown ()
+ Notify the master about an immediate shutdown.
+
+ -----------------------------------------------------------------
+ Error Handling
+
+ void dangling_lfun_closure ()
+ Handle a dangling lfun-closure.
+
+ void log_error (string file, string err, int warn)
+ Announce a compiler-time error or warning.
+
+ mixed heart_beat_error (object culprit, string err,
+ string prg, string curobj, int line)
+ Announce an error in the heart_beat() function.
+
+ void runtime_error (string err, string prg, string curobj, int line)
+ Announce a runtime error.
+
+ void runtime_warning (string msg, string curobj, string prg, int line)
+ Announce a runtime warning.
+
+ -----------------------------------------------------------------
+ Security and Permissions
+
+ int privilege_violation (string op, mixed who, mixed arg3, mixed arg4)
+ Validate the execution of a privileged operation.
+
+ int query_allow_shadow (object victim)
+ Validate a shadowing.
+
+ int valid_exec (string name)
+ Validate the rebinding of an IP connection by usage of efun
+ exec().
+
+ int valid_query_snoop (object obj)
+ Validate if the snoopers of an object may be revealed by
+ usage of the efun query_snoop().
+
+ int valid_snoop (object snoopee, object snooper)
+ Validate the start/stop of a snoop.
+
+ ------------------------------------------------------------------
+ Userids and depending Security
+
+ string get_bb_uid()
+ Return the string to be used as root-uid.
+
+ int|string valid_read (string path, string euid, string fun, object caller)
+ int|string valid_write (string path, string euid, string fun, object caller)
+ Validate a reading/writing file operation.
+
+ -----------------------------------------------------------------
+ ed() Support
+
+ string make_path_absolute (string str)
+ Absolutize a relative filename given to the editor.
+
+ int save_ed_setup (object who, int code)
+ Save individual settings of ed for a wizard.
+
+ int retrieve_ed_setup (object who)
+ Retrieve individual settings of ed for a wizard.
+
+ string get_ed_buffer_save_file_name (string file)
+ Return a filename for the ed buffer to be saved into.
+
+ ----------------------------------------------------------------
+ parse_command() Support (!compat, SUPPLY_PARSE_COMMAND defined)
+
+ string *parse_command_id_list ()
+ Return generic singular ids.
+
+ string *parse_command_plural_id_list ()
+ Return generic plural ids.
+
+ string *parse_command_adjectiv_id_list ()
+ Return generic adjective ids.
+
+ string *parse_command_prepos_list ()
+ Return common prepositions.
+
+ string parse_command_all_word()
+ Return the one(!) 'all' word.
+
+SEE ALSO
+ master(M), efun(E), applied(A), concepts(C), driver(D), lpc(LPC)
diff --git a/doc/master/notify_shutdown b/doc/master/notify_shutdown
index d23cd98..7fd24cc 100644
--- a/doc/master/notify_shutdown
+++ b/doc/master/notify_shutdown
@@ -11,7 +11,7 @@
done when remove_player() is called because the udp connectivity is
already gone then.
- If the gamedriver shuts down normally , this is the last function
+ If the gamedriver shuts down normally, this is the last function
called before the mud shuts down the udp connections and the accepting
socket for new players.
diff --git a/doc/master/parse_command_adjectiv_id_list b/doc/master/parse_command_adjectiv_id_list
new file mode 100644
index 0000000..a27d475
--- /dev/null
+++ b/doc/master/parse_command_adjectiv_id_list
@@ -0,0 +1,14 @@
+SYNOPSIS
+ string *parse_command_adjectiv_id_list(void)
+
+DESCRIPTION
+ Used by parse_command(). Return an array of common
+ adjectives in the installation's native language.
+
+EXAMPLE
+ string * parse_command_adjectiv_id_list() {
+ return ({ "iffish" });
+ }
+
+SEE ALSO
+ parse_command(E)
diff --git a/doc/master/parse_command_all_word b/doc/master/parse_command_all_word
index b57ab05..bf182f0 100644
--- a/doc/master/parse_command_all_word
+++ b/doc/master/parse_command_all_word
@@ -1,9 +1,14 @@
SYNOPSIS
- string *parse_command_all_word(void)
+ string parse_command_all_word(void)
DESCRIPTION
- Used by parse_command(). Return the word for ``all'' in the
- installations native language.
+ Used by parse_command(). Return the word for "all" in the
+ installation's native language.
+
+EXAMPLE
+ string parse_command_all_word() {
+ return "all";
+ }
SEE ALSO
- parse_command(E)
+ parse_command(E)
diff --git a/doc/master/parse_command_id_list b/doc/master/parse_command_id_list
new file mode 100644
index 0000000..a7b1a33
--- /dev/null
+++ b/doc/master/parse_command_id_list
@@ -0,0 +1,14 @@
+SYNOPSIS
+ string *parse_command_id_list(void)
+
+DESCRIPTION
+ Used by parse_command(). Return an array of common
+ singular 'thing' ids in the installation's native language.
+
+EXAMPLE
+ string *parse_command_id_list() {
+ return ({ "one", "thing" });
+ }
+
+SEE ALSO
+ parse_command(E)
diff --git a/doc/master/parse_command_plural_id_list b/doc/master/parse_command_plural_id_list
new file mode 100644
index 0000000..5beab22
--- /dev/null
+++ b/doc/master/parse_command_plural_id_list
@@ -0,0 +1,14 @@
+SYNOPSIS
+ string *parse_command_plural_id_list(void)
+
+DESCRIPTION
+ Used by parse_command(). Return an array of common
+ plural 'thing' ids in the installation's native language.
+
+EXAMPLE
+ string *parse_command_pural_id_list() {
+ return: ({ "ones", "things", "them" });
+ }
+
+SEE ALSO
+ parse_command(E)
diff --git a/doc/master/parse_command_prepos_list b/doc/master/parse_command_prepos_list
index 24706ce..0f71a61 100644
--- a/doc/master/parse_command_prepos_list
+++ b/doc/master/parse_command_prepos_list
@@ -1,9 +1,14 @@
SYNOPSIS
- string *parse_command_prepos_list(void)
+ string *parse_command_prepos_list(void)
DESCRIPTION
- Used by parse_command(). Return an array of common
- prepositions in the installations native language.
+ Used by parse_command(). Return an array of common
+ prepositions in the installation's native language.
+
+EXAMPLE
+ string *parse_command_prepos_list() {
+ return ({ "in", "on", "under", "behind", "beside" });
+ }
SEE ALSO
- parse_command(E)
+ parse_command(E)
diff --git a/doc/master/preload b/doc/master/preload
index 95f27d7..1eea4a4 100644
--- a/doc/master/preload
+++ b/doc/master/preload
@@ -1,18 +1,18 @@
SYNOPSIS
- void preload(string file)
+ void preload(string file)
DESCRIPTION
- Load the object with the given file name, that was returned by
- epilog(). It is task of the epilog()/preload() pair to ensure
- the validity of the given strings (e.g. filtering out comments
- and blank lines). For preload itself a call_other(file, "???")
- s sufficient, but it should be guarded by a catch() to avoid
- premature blockings. Also it is wise to change the master's
- euid from root_uid to something less privileged for the time
- of the preload.
+ Load the object with the given file name (which was returned by
+ epilog()). It is the task of the epilog()/preload() pair to ensure
+ the validity of the given strings (e.g. filtering out comments
+ and blank lines). For preload itself a call_other(file, "???")
+ is sufficient, but it should be guarded by a catch() to avoid
+ premature blockings. Also it is wise to change the master's
+ euid from root_uid to something less privileged for the time
+ of the preload.
- You can of course do anything else with the passed strings -
- preloading is just the traditional task.
+ You can of course do anything else with the passed strings -
+ preloading is just the traditional task.
SEE ALSO
- epilog(M), master(M)
+ epilog(M), master(M)
diff --git a/doc/master/prepare_destruct b/doc/master/prepare_destruct
index 3121b88..f24391f 100644
--- a/doc/master/prepare_destruct
+++ b/doc/master/prepare_destruct
@@ -1,22 +1,31 @@
SYNOPSIS
- mixed prepare_destruct(object obj)
+ mixed prepare_destruct(object obj)
DESCRIPTION
- Prepare the destruction of the object obj. Return 0 if the
- object is ready for destruction, any other value will abort
- the attempt. If a string is returned, an error with the string
- as message will be issued.
+ Prepare the destruction of the object obj. Return 0 if the
+ object is ready for destruction; any other value will abort
+ the attempt. If a string is returned, an error with the string
+ as message will be issued.
- The interpreter calls this function whenever an object shall
- be destructed. It expects, that this function cleans the
- inventory of the object, or the destruct will fail.
- Furthermore, the function could notify the former inventory
- objects that their holder is under destruction (useful to move
- users out of rooms which re updated); and it could announce
- systemwide the destruction(quitting) of users.
+ The interpreter calls this function whenever an object shall
+ be destructed. It expects that this function cleans the
+ inventory of the object, or the destruct will fail. It is also
+ recommended to clean up all shadows on obj at this point.
- Strange things will happen if the mastor object does not
- provide this function.
+ Furthermore, the function could notify the former inventory
+ objects that their holder is under destruction (useful to move
+ users out of rooms which are updated); and it could announce
+ systemwide the destruction(quitting) of users.
+
+ Another use for this apply is to take care of any other
+ 'cleanup' work needed to be done, like adjusting weights,
+ light levels, and such. Alternatively and traditionally this
+ is done by calling an lfun 'remove()' in the object, which
+ then calls the efun destruct() after performing all the
+ adjustments.
+
+ Strange things will happen if the master object does not
+ provide this function.
SEE ALSO
- remove_player(M), destruct(E)
+ remove_player(M), destruct(E)
diff --git a/doc/master/printf_obj_name b/doc/master/printf_obj_name
new file mode 100644
index 0000000..401e446
--- /dev/null
+++ b/doc/master/printf_obj_name
@@ -0,0 +1,14 @@
+SYNOPSIS
+ string printf_obj_name(object ob)
+
+DESCRIPTION
+ Return a printable name for an object. This function is called
+ by sprintf() to print a meaningful name in addition to the
+ normal object_name().
+
+HISTORY
+ Renamed in LDMud 3.2.6 from object_name() due to the introduction
+ of an efun with this name.
+
+SEE ALSO
+ sprintf(E), object_name(E)
diff --git a/doc/master/privilege_violation b/doc/master/privilege_violation
index 957a4b9..2918663 100644
--- a/doc/master/privilege_violation
+++ b/doc/master/privilege_violation
@@ -1,63 +1,106 @@
SYNOPSIS
- int privilege_violation(string op, mixed who, mixed arg3, mixed arg4)
+ int privilege_violation(string op, mixed who, mixed arg, mixed arg2, mixed arg3)
DESCRIPTION
- Validate the execution of a privileged operation.
- op denotes the requested operation, who is the object
- requesting the operation (object_name or object pointer), arg3
- and arg4 are additional arguments, depending on the operation.
+ Validate the execution of a privileged operation.
+ op denotes the requested operation, who is the object
+ requesting the operation (file_name or object pointer), <arg>
+ and <arg2> are additional arguments, depending on the operation.
- The function should return >0 to grant the privilege, 0 to
- indicate that the caller was probably misleaded and the error
- might be fixed, and anything else to indicate a real
- violation, that will be handled as run time error.
+ The function should return >0 to grant the privilege, 0 to
+ indicate that the caller was probably misled and the error
+ might be fixed, and anything else to indicate a real
+ violation that will be handled as run time error.
- The privileged operations are:
- attach_erq_demon Attach the erq demon to object <arg> with
- flag <args>.
- bind_lambda Bind a lambda-closure to object arg3.
- call_out_info Return an array with all call_out
- informations.
- nomask simul_efun Attempt to get an efun <arg> via efun:: when
- it is shadowed by a nomask type simul_efun.
- rename_object The object who tries to rename the object
- arg3 to the name arg4.
- send_udp Send UDP-data to host arg3.
- set_auto_include_string Set the string automatically included
- by the compiler into every object.
- get_extra_wizinfo Get the additional wiz-list info for user
- arg3.
- set_extra_wizinfo Set the additional wiz-list info for user
- arg3.
- set_extra_wizinfo_size Set the size of the additional user
- info in the wiz-list to arg3.
- set_driver_hook : Set hook <arg> to <arg2>.
- set_this_object Set this_object() to arg3.
- shadow_add_action Add an action to function arg4 that is
- shadowed by the object arg3.
- symbol_variable Attempt to make a symbol from a hidden
- inherited variable. arg3 is the object in
- question, arg4 the number of the variable in
- the variable table.
- wizlist_info Return an array with all wiz-list
- information.
+ The privileged operations are:
+ attach_erq_demon : Attach the erq demon to object <arg> with
+ flag <arg2>.
+ bind_lambda : Bind a lambda-closure to object <arg>.
+ call_out_info : Return an array with all call_out
+ informations.
+ configure_interactive : Set option <arg2> with value <arg3> as
+ default (<arg>==0) or for object <arg>.
+ configure_object : Set option <arg2> with value <arg3> for
+ object <arg>.
+ configure_driver : Set option <arg1> to value(s) <arg2>.
+ enable_telnet : Enable/disable telnet (<arg2>) for object
+ <arg>.
+ execute_command : Execute command string <arg2> for the object
+ <arg>.
+ erq : At the request <arg2> is to be sent to the
+ : erq-demon by the object <who>.
+ garbage_collection : Object <who> calls the efun
+ garbage_collection() with <arg> as filename
+ and <arg2> as flag.
+ input_to : Object <who> redirects the next input from
+ commandgiver <arg>, using <arg2> as value
+ for the flags. This is used for flag values
+ including the 'no bang' option.
+ limited : Execute <arg> with reduced/changed limits
+ 1<arg2> (as return by query_limits()).
+ mysql : Object <who> attempted to execute mySQL efun
+ <arg>.
+ pgsql : Object <who> attempted to execute Postgres efun
+ <arg>.
+ net_connect : Attempt to open a connection to host <arg>,
+ port <arg2>.
+ nomask simul_efun : Attempt to get an efun <arg> via efun:: when
+ it is shadowed by a nomask type simul_efun.
+ rename_object : The object <who> tries to rename the object
+ <arg> to the name <arg2>.
+ send_udp : Send UDP-data to host <arg>.
+ get_extra_wizinfo : Get the additional wiz-list info for user
+ <arg>.
+ set_extra_wizinfo : Set the additional wiz-list info for user
+ <arg>.
+ set_extra_wizinfo_size : Set the size of the additional user
+ info in the wiz-list to <arg>.
+ set_driver_hook : Set hook <arg> to <arg2>.
+ set_limits : Set limits to <arg> (as returned by
+ query_limits()).
+ set_max_commands : Set the max. number of commands interactive
+ object <arg> can issue per second to <arg2>.
+ set_this_object : Set this_object() to <arg>.
+ shadow_add_action : Add an action to function <arg2> of object
+ <arg> from the shadow <who> which is shadowing
+ <arg>.
+ shutdown : Object <who> calls the efun shutdown with <arg>
+ as argument.
+ sqlite_pragma : Execute pragma statement in SQLite.
+ symbol_variable : Attempt to make a symbol from a hidden
+ inherited variable. <arg> is the object in
+ question, <arg2> the number of the variable in
+ the variable table.
+ variable_list : An attempt to return the variable values of
+ object <arg> is made from a different object
+ <who>.
+ wizlist_info : Return an array with all wiz-list
+ information.
- call_out_info() can return the arguments to functions and
- lambda closures to be called by call_out(); you should
- consider that read access to closures, mappings and arrays
- means write access and/or other privileges.
- wizlist_info() will return an array which holds, among others,
- the extra wizlist field. While a toplevel array, if found,
- will be copied, this does not apply to nested arrays or to any
- mappings. You might also have some sensitive closures there.
- send_udp() should be watched as it could be abused to mess up
- the IMP.
- The xxx_extra_wizinfo operations are necessary for a proper
- wizlist and should therefore be restricted to admins.
- All other operations are potential sources for direct security
- breaches - any use of them should be scrutinized closely.
+ call_out_info() can return the arguments to functions and
+ lambda closures to be called by call_out(); you should
+ consider that read access to closures, mappings and arrays
+ means write access and/or other privileges.
+ wizlist_info() will return an array which holds, among others,
+ the extra wizlist field. While a toplevel array, if found,
+ will be copied, this does not apply to nested arrays or to any
+ mappings. You might also have some sensitive closures there.
+ send_udp() should be watched as it could be abused.
+ The xxx_extra_wizinfo operations are necessary for a proper
+ wizlist and should therefore be restricted to admins.
+ All other operations are potential sources for direct security
+ breaches - any use of them should be scrutinized closely.
-SEE ALSO
- simul_efun(C), call_out_info(E), shadow(E), add_action(E),
- wizlist(E), set_this_object(E), rename_object(E),
- bind_lambda(E), send_udp(E), set_auto_include_string(E)
+HISTORY
+ LDMud 3.2.10 added the "enable_telnet", "net_connect",
+ "set_max_commands" and "variable_list" violations.
+ LDMud 3.3.563 added the passing of the limits to the "limited"
+ and "set_limits".
+ LDMud 3.2.11/3.3.640 added the "mysql" violation.
+ LDMud 3.3.717 added the "sqlite_pragma" violation.
+
+SEE ALSO
+ net_connect(E), send_erq(E), set_this_object(E), rename_object(E),
+ simul_efun(C), call_out_info(E), shadow(E), add_action(E),
+ bind_lambda(E), send_udp(E), input_to(E), execute_command(E),
+ variable_list(E), enable_telnet(E), mysql(C)
diff --git a/doc/master/query_allow_shadow b/doc/master/query_allow_shadow
index 47d2e95..a331a47 100644
--- a/doc/master/query_allow_shadow
+++ b/doc/master/query_allow_shadow
@@ -1,23 +1,14 @@
-query_allow_shadow(M)
-FUNKTION:
- int query_allow_shadow(object victim)
+SYNOPSIS
+ int query_allow_shadow(object victim)
-DEFINITION:
- /secure/master.c
+DESCRIPTION
+ Return 1 if previous_object() is allowed to use efun shadow()
+ on object victim, 0 if it is not.
-BESCHREIBUNG:
- Gibt 1 zurueck, wenn das Objekt victim von previous_object() beschattet
- werden darf, 0 sonst.
+ The function should deny shadowing on all root objects, else
+ it might query the victim for clearance. Most installations
+ seem to use victim->prevent_shadow(previous_object()) to
+ check if the victim denies being shadowed.
- Die Funktion prueft, ob das Objekt victim ein Root-Objekt ist, oder
- ob es beim Aufruf von query_prevent_shadow() 1 zurueckgibt.
-
-BEMERKUNGEN:
- Wird automatisch bei shadow() ausgefuehrt.
-
-SIEHE AUCH:
- Rechte: query_prevent_shadow(L)
- Generell: shadow(E), unshadow(E)
- Informationen: query_shadowing(E)
-
-20. Mai 2004 Gloinson
\ No newline at end of file
+SEE ALSO
+ shadow(E)
diff --git a/doc/master/quota_demon b/doc/master/quota_demon
index f7f8d95..08f76fd 100644
--- a/doc/master/quota_demon
+++ b/doc/master/quota_demon
@@ -1,18 +1,18 @@
SYNOPSIS
- void quota_demon(void)
+ void quota_demon(void)
DESCRIPTION
- Handle quotas in times of memory shortage.
+ Handle quotas in times of memory shortage.
- This function is called during the final phase of a garbage
- collection if the reserved user area couldn't be reallocated.
- This function (or a called demon) has now the opportunity to
- remove some (still active) objects from the system. If this does
- not free enough memory to reallocate the user reserve,
- slow_shut_down() will be called to start Armageddon.
+ This function is called during the final phase of a garbage
+ collection if the reserved user area couldn't be reallocated.
+ This function (or a called demon) has now the opportunity to
+ remove some (still active) objects from the system. If this does
+ not free enough memory to reallocate the user reserve,
+ slow_shut_down() will be called to start Armageddon.
- Up to now, the wizlist lacks various informations needed to
- detect the memory-hungriest users.
+ Up to now, the wizlist lacks various informations needed to
+ detect the memory-hungriest users.
SEE ALSO
- slow_shut_down(M), wizlist(E)
+ slow_shut_down(M)
diff --git a/doc/master/reactivate_destructed_master b/doc/master/reactivate_destructed_master
index e90d2a1..64f68b5 100644
--- a/doc/master/reactivate_destructed_master
+++ b/doc/master/reactivate_destructed_master
@@ -1,15 +1,15 @@
SYNOPSIS
- void reactivate_destructed_master(int flag)
+ void reactivate_destructed_master(int flag)
DESCRIPTION
- This function is called in an already destructed master object
- if no new master object could be loaded. flag will be 1 if the
- old master object could be reclaimed form the list of objects
- that were marked for destruction but not yet terminated. If
- flag is 0, all variables of the object have been set to 0 and
- must be re-initialized.
+ This function is called in an already destructed master object
+ if no new master object could be loaded. flag will be 1 if the
+ old master object could be reclaimed from the list of objects
+ that were marked for destruction but not yet terminated. If
+ flag is 0, all variables of the object have been set to 0 and
+ must be re-initialized.
- After this function, inaugurate_master() will be applied again.
+ After this function, inaugurate_master() will be applied again.
SEE ALSO
- destruct(E), inaugurate_master(M), master(M)
+ destruct(E), inaugurate_master(M), master(M)
diff --git a/doc/master/receive_udp b/doc/master/receive_udp
index a1b58c5..60cb80f 100644
--- a/doc/master/receive_udp
+++ b/doc/master/receive_udp
@@ -1,17 +1,16 @@
SYNOPSIS
- void receive_udp(string host, string msg, int hostport)
+ void receive_udp(string host, bytes msg, int hostport)
DESCRIPTION
- Handle a received IMP message.
+ Handle a received UDP message.
- This function is called for every message received on the IMP
- port. Usually it is passed on to some object that handles
- inter mud communications.
+ This function is called for every message received on the UDP
+ port. Usually it is passed on to some object that handles
+ inter-mud communications.
HISTORY
- The 'hostport' argument was added in 3.2.1.
+ The 'hostport' argument was added in 3.2.1.
+ LDMud 3.2.9 renamed this method from receive_imp().
SEE ALSO
- send_udp(E), query_udp_port(E)
-
-29.10.2006 Zesstra
+ send_udp(E), query_udp_port(E)
diff --git a/doc/master/remove_player b/doc/master/remove_player
index b70a1fb..10ffd22 100644
--- a/doc/master/remove_player
+++ b/doc/master/remove_player
@@ -1,14 +1,14 @@
SYNOPSIS
- void remove_player(object ob)
+ void remove_player(object ob)
DESCRIPTION
- Remove an interactive user object ob from the system. This
- function is called by the interpreter to expell remaining
- users from the system on shutdown in a polite way. If this
- functions fails to quit/destruct the user, he will be
- destructed the hard way by the interpreter.
+ Remove an interactive user object ob from the system. This
+ function is called by the interpreter to expell remaining
+ users from the system on shutdown in a polite way. If this
+ functions fails to quit/destruct the user, he will be
+ destructed the hard way by the interpreter.
- This function must not cause runtime errors.
+ This function must not cause runtime errors.
SEE ALSO
- remove_interactive(E), slow_shut_down(M)
+ remove_interactive(E), slow_shut_down(M)
diff --git a/doc/master/retrieve_ed_setup b/doc/master/retrieve_ed_setup
index 4d92ef0..77213d0 100644
--- a/doc/master/retrieve_ed_setup
+++ b/doc/master/retrieve_ed_setup
@@ -1,9 +1,9 @@
SYNOPSIS
- int retrieve_ed_setup(object command_giver)
+ int retrieve_ed_setup(object command_giver)
DESCRIPTION
- Should return an integer that gives the ed setup flags for the
- user that is denoted by command_giver.
+ Should return an integer that gives the ed setup flags for the
+ user that is denoted by command_giver.
SEE ALSO
- save_ed_setup(M)
+ save_ed_setup(M)
diff --git a/doc/master/runtime_error b/doc/master/runtime_error
index d109df8..835d6a5 100644
--- a/doc/master/runtime_error
+++ b/doc/master/runtime_error
@@ -1,16 +1,57 @@
SYNOPSIS
- void runtime_error(string err, string prg, string curobj, int line)
+ void runtime_error( string err, string prg, string curobj, int line
+ , mixed culprit, int caught)
DESCRIPTION
- This function has to announce a runtime error to the active
- user. If the user has enough privileges, it might give him the
- full error message together with the source line. Else it
- should issue a decent message ("Your sensitive mind notices a
- wrongness in the fabric of space").
+ This function has to announce a runtime error to the active
+ user. If the user has enough privileges, it might give him the
+ full error message together with the source line. Else it
+ should issue a decent message ("Your sensitive mind notices a
+ wrongness in the fabric of space").
- Note that prg denotes the program actually executed (which
- might be an inherited one) whereas curobj is just the
- offending object.
+ <err> is the error message, <prg> is the program executed (which
+ might be an inherited program), <curobj> is the current object at
+ the time of the error. <line> is the linenumber within the program.
+
+ If the error is a normal runtime error, <culprit> is -1. Otherwise,
+ the error occurred during a heartbeat and <culprit> is the object which
+ heart_beat() function was executed. Also, in case of a heartbeat error,
+ the heartbeat for the <culprit> has been turned off.
+
+ If the error is caught on a higher level, <caught> is non-zero;
+ otherwise it is 0.
+
+ Note that any of the the objects or programs might be destructed, ie.
+ might be passed as 0.
+
+ One common pitfall in the implementation of runtime_error() is
+ that runtime_error() itself could run out of evaluation ticks,
+ causing a runtime error itself. The workaround is to use
+ limited() like this:
+
+ static void
+ handle_runtime_error ( string err, string prg, string curobj
+ , int line)
+ { ... the actual error handler ... }
+
+ static void
+ call_runtime_error (string err, string prg, string curobj, int line)
+ {
+ limited(#'handle_runtime_error, ({ 200000 }), err, prg, curobj
+ , line);
+ }
+
+ void
+ runtime_error (string err, string prg, string curobj, int line)
+ {
+ limited(#'call_runtime_error, ({ LIMIT_UNLIMITED })
+ , err, prg, curobj, line);
+ }
+
+HISTORY
+ LDMud 3.2.9 added the <culprit> argument.
+ LDMud 3.2.12/3.3.705 added the <caught> argument.
SEE ALSO
- log_error(M), heart_beat_error(M), raise_error(E)
+ log_error(M), heart_beat_error(M), runtime_warning(M),
+ raise_error(E), expand_define(E)
diff --git a/doc/master/runtime_warning b/doc/master/runtime_warning
index 80864ab..82e6226 100644
--- a/doc/master/runtime_warning
+++ b/doc/master/runtime_warning
@@ -11,7 +11,7 @@
(the object itself might already be destructed), or 0 if there
is none.
<prog>, <line> determine the name of the program and the line where
- the error occured if the current object exists, otherwise
+ the error occurred if the current object exists, otherwise
they are 0.
<inside_catch> : != 0 if the warning occurs inside a catch().
diff --git a/doc/master/save_ed_setup b/doc/master/save_ed_setup
index feaaf71..3e5d0db 100644
--- a/doc/master/save_ed_setup
+++ b/doc/master/save_ed_setup
@@ -1,33 +1,33 @@
SYNOPSIS
- int save_ed_setup(object who, int code)
+ int save_ed_setup(object who, int code)
DESCRIPTION
- Save individual option settings of the builtin ed, encoded
- into code, for the user denoted by who. These functions are
- located in the master object so that the local gods can decide
- what strategy they want to use. suggestions:
- A setup file for every user.
- advantages: transparent to the user
- independent of user count
- disadvantage: extra file access at ed invocation
- An array in the master object, users are searched by member_array
- advantage: easy to implement
- disadvantage: performance degradation with high user counts
- An AVL-tree to access users by name
- advantage: can fit any need
- disadvantage: hard to implement, will need more
- overhead on small and medium
- installations than it can ever make
- good by lg(usercount) complexity
- Dedicated flags in every user object.
- advantages: easy to implement
- independent of user count
- Will also work for nusers w/o file
- access privileges.
- disadvantage: care has to be taken to avoid
- collision with other uses of the flags
- in the user object
+ Save individual option settings of the builtin ed, encoded
+ into code, for the user denoted by who. These functions are
+ located in the master object so that the local gods can decide
+ what strategy they want to use. suggestions:
+ A setup file for every user.
+ advantages: transparent to the user
+ independent of user count
+ disadvantage: extra file access at ed invocation
+ An array in the master object, users are searched by member_array
+ advantage: easy to implement
+ disadvantage: performance degradation with high user counts
+ An AVL-tree to access users by name
+ advantage: can fit any need
+ disadvantage: hard to implement, will need more
+ overhead on small and medium
+ installations than it can ever make
+ good by lg(usercount) complexity
+ Dedicated flags in every user object.
+ advantages: easy to implement
+ independent of user count
+ Will also work for nusers w/o file
+ access privileges.
+ disadvantage: care has to be taken to avoid
+ collision with other uses of the flags
+ in the user object
SEE ALSO
- ed(E), retrieve_ed_setup(M), valid_write(M),
- get_ed_buffer_save_object_name(M)
+ ed(E), retrieve_ed_setup(M), valid_write(M),
+ get_ed_buffer_save_file_name(M)
diff --git a/doc/master/slow_shut_down b/doc/master/slow_shut_down
index 9a7fe8d..3c72869 100644
--- a/doc/master/slow_shut_down
+++ b/doc/master/slow_shut_down
@@ -1,40 +1,44 @@
SYNOPSIS
- void slow_shut_down(int minutes)
+ void slow_shut_down(int minutes)
DESCRIPTION
- Schedule a shutdown for the near future. minutes is the
- desired time in minutes till the shutdown:
- six, if just the user reserve has been put into use.
- one, if the (smaller) master reserve has been put into use as
- well.
+ Schedule a shutdown for the near future. minutes is the
+ desired time in minutes till the shutdown:
+ six, if just the user reserve has been put into use.
+ one, if the (smaller) master reserve has been put into use as
+ well.
- The interpreter calls this function when it runs low on
- memory. At this time, it has freed its reserve, but since it
- won't last long, the interpreter needs to be shut down. The
- delay is to give the users the opportunity to finish their
- current tasks, but don't take the 'minutes' for granted, just
- deduce the urgency from it.
- It is possible that the driver may reallocate some memory
- after the function has been called, and then run again into a
- low memory situation, calling this function again.
- This function might load an 'Armageddon' object and tell it
- what to do. It is the Armageddon object then which performs
- the shutdown.
+ The interpreter calls this function when it runs low on
+ memory. At this time, it has freed its reserve, but since it
+ won't last long, the interpreter needs to be shut down. The
+ delay is to give the users the opportunity to finish their
+ current tasks, but don't take the 'minutes' for granted, just
+ deduce the urgency from it.
- Technical: The memory handling of the interpreter includes
- three reserved areas: user, system and master. All three are
- there to insure that the system shuts down gracefully when the
- memory runs out: the user area to give the users time to
- quit normally, the others to enable emergency-logouts when the
- user reserve is used up as well.
- The areas are allocated at start of the interpreter, and
- released when no more memory could be obtained from the host.
- In such a case, one of the remaining areas is freed (so the
- operation can continue a short while) and a garbage collection
- is initiated. If the garbage collection recycles enough memory
- (either true garbage or by the aid of the quota_demon) to
- reallocate the areas, all is fine, else the system shut down
- is invoked by a call to this function.
+ It is possible that the driver may reallocate some memory
+ after the function has been called, and then run again into a
+ low memory situation, calling this function again.
+
+ This function might load an 'Armageddon' object and tell it
+ what to do. It is the Armageddon object then which performs
+ the shutdown.
+
+ Technical: The memory handling of the interpreter includes
+ three reserved areas: user, system and master. All three are
+ there to insure that the system shuts down gracefully when the
+ memory runs out: the user area to give the users time to
+ quit normally, the others to enable emergency-logouts when the
+ user reserve is used up as well.
+
+ The areas are allocated at start of the interpreter, and
+ released when no more memory could be obtained from the host.
+ In such a case, one of the remaining areas is freed (so the
+ operation can continue a short while) and a garbage collection
+ is initiated. If the garbage collection recycles enough memory
+ (either true garbage or by the aid of the quota_demon) to
+ reallocate the areas, all is fine, else the system shut down
+ is invoked by a call to this function.
SEE ALSO
- quota_demon(M), notify_shutdown(M), shutdown(E), malloc(D), memory(C)
+ quota_demon(M), notify_shutdown(M), shutdown(E), malloc(D), memory(C)
+ low_memory(M)
diff --git a/doc/master/stale_erq b/doc/master/stale_erq
index a05ca31..8a5bcff 100644
--- a/doc/master/stale_erq
+++ b/doc/master/stale_erq
@@ -1,17 +1,17 @@
SYNOPSIS
- void stale_erq (closure callback)
+ void stale_erq (closure callback)
DESCRIPTION
- Notify the loss of the erq demon.
- Argument is the callback closure set for an erq request.
+ Notify the loss of the erq demon.
+ Argument is the callback closure set for an erq request.
- If the erq connection dies prematurely, the driver will call
- this lfun for every pending request with set callback. This
- function should notify the originating object that the answer
- will never arrive.
+ If the erq connection dies prematurely, the driver will call
+ this lfun for every pending request with set callback. This
+ function should notify the originating object that the answer
+ will never arrive.
HISTORY
- Introduced in 3.2.1@61.
+ Introduced in 3.2.1@61.
SEE ALSO
- erq(C)
+ erq(C)
diff --git a/doc/master/valid_exec b/doc/master/valid_exec
index 2c0b67b..04f2c62 100644
--- a/doc/master/valid_exec
+++ b/doc/master/valid_exec
@@ -1,15 +1,15 @@
SYNOPSIS
- int valid_exec(string name, object ob, object obfrom)
+ int valid_exec(string name, object ob, object obfrom)
DESCRIPTION
- Validate the rebinding of an IP connection by usage of efun
- exec(). Arguments are the <name> of the _program_ attempting
- to rebind the connection, the object <ob> to receive the
- connection, and the object <obfrom> giving the connection.
- Note that the program name is not the object_name() of the
- object, and has no leading slash.
+ Validate the rebinding of an IP connection by usage of efun
+ exec(). Arguments are the <name> of the _program_ attempting
+ to rebind the connection, the object <ob> to receive the
+ connection, and the object <obfrom> giving the connection.
+ Note that the program name is not the file_name() of the
+ object, and has no leading slash.
- Return 0 to disallow the action, any other value to allow it.
+ Return 0 to disallow the action, any other value to allow it.
SEE ALSO
- exec(E)
+ exec(E)
diff --git a/doc/master/valid_query_snoop b/doc/master/valid_query_snoop
index e92378a..9be180f 100644
--- a/doc/master/valid_query_snoop
+++ b/doc/master/valid_query_snoop
@@ -1,12 +1,12 @@
SYNOPSIS
- valid_query_snoop(object ob)
+ int valid_query_snoop(object ob)
DESCRIPTION
- Should return 1 if previous_object() (the one that called the
- efun query_snoop()) is allowed to query wether ob is being
- snooped, 0 if not.
+ Should return 1 if previous_object() (the one that called the
+ efun query_snoop()) is allowed to query whether ob is being
+ snooped, 0 if not.
- The master object is always allowed to use query_snoop().
+ The master object is always allowed to use query_snoop().
SEE ALSO
- valid_snoop(M), query_snoop(E), snoop(E)
+ valid_snoop(M), query_snoop(E), snoop(E)
diff --git a/doc/master/valid_read b/doc/master/valid_read
index 2dafbae..45f0bb6 100644
--- a/doc/master/valid_read
+++ b/doc/master/valid_read
@@ -1,32 +1,40 @@
SYNOPSIS
- string valid_read(string path, string uid, string func, object ob)
+ string valid_read(string path, string uid, string func, object ob)
DESCRIPTION
- This function is called to check if the object ob with the
- user-id uid has read permissions for the file given by path
- for the operation named by func. It should return 0 if
- permission is denied, or the normalized path if permission is
- granted. You can also return 1 to indicate that the path can
- be used unchanged.
+ This function is called to check if the object ob with the
+ user-id uid has read permissions for the file given by path
+ for the operation named by func. It should return 0 if
+ permission is denied, or the normalized path if permission is
+ granted. You can also return 1 to indicate that the path can
+ be used unchanged.
- The returned pathname must not contain ``..'', a leading /
- will be stripped by the interpreter.
+ The returned pathname must not contain "..", a leading /
+ will be stripped by the interpreter. By default, the returned
+ path must also not contain space characters; if the driver
+ is instructed to allow them, the preprocessor macro
+ __FILENAME_SPACES__ is defined.
- Func denotes the efun call or other operation that caused
- valid_read() to be called:
- ed_start (check if the file to be edited is readable),
- file_size,
- get_dir,
- print_file (efun cat()),
- read_bytes,
- read_file,
- restore_object,
- tail.
+ Func denotes the efun call or other operation that caused
+ valid_read() to be called:
- Note that this function is called in compat mode as well. If
- you need to be compatible with the old 2.4.5-mudlib, redirect
- these calls to the valid_read/valid_write in the user
- object.
+ copy_file
+ ed_start (check if the file to be edited is readable),
+ file_size,
+ get_dir,
+ print_file (efun cat()),
+ read_bytes,
+ read_file,
+ restore_object,
+ tail.
+
+ For restore_object(), the <path> passed is the filename as given
+ in the efun call.
+
+ This function is called in compat mode as well. If
+ you need to be compatible with the old 2.4.5-mudlib, redirect
+ these calls to the valid_read/valid_write in the user
+ object.
SEE ALSO
- valid_write(M), make_path_absolute(M)
+ valid_write(M), make_path_absolute(M)
diff --git a/doc/master/valid_snoop b/doc/master/valid_snoop
index 5bff987..0b8d195 100644
--- a/doc/master/valid_snoop
+++ b/doc/master/valid_snoop
@@ -1,8 +1,8 @@
SYNOPSIS
- int valid_snoop(object me, object you)
+ int valid_snoop(object me, object you)
DESCRIPTION
- Should return 1 if me is allowed to snoop you, 0 if not.
+ Should return 1 if me is allowed to snoop you, 0 if not.
SEE ALSO
- snoop(E), query_snoop(E), valid_query_snoop(M)
+ snoop(E), query_snoop(E), valid_query_snoop(M)
diff --git a/doc/master/valid_trace b/doc/master/valid_trace
new file mode 100644
index 0000000..a3776e8
--- /dev/null
+++ b/doc/master/valid_trace
@@ -0,0 +1,16 @@
+SYNOPSIS
+ int valid_trace(string what, int|string arg)
+
+DESCRIPTION
+ Check if the interactive user is allowed to use tracing.
+
+ The argument <what> denotes the action for which permission is to be
+ checked, <arg> is the argument given to the traceing efun:
+
+ "trace" Is the user allowed to use tracing?
+ <arg> is the tracelevel argument given.
+ "traceprefix" Is the user allowed to set a traceprefix?
+ <arg> is the prefix given.
+
+SEE ALSO
+ trace(E), showsmallnewmalloced(D), malloc(D), status(D), memory(C)
diff --git a/doc/master/valid_write b/doc/master/valid_write
index 31fe43b..3f73ca3 100644
--- a/doc/master/valid_write
+++ b/doc/master/valid_write
@@ -1,33 +1,52 @@
SYNOPSIS
- string valid_write(string path, string uid, string func, object ob)
+ string valid_write(string path, string uid, string func, object ob)
DESCRIPTION
- This function is called to check if the object ob with the
- user-id uid has write permissions to the file given by path
- for the operation named by func. It should return 0 if
- permission is denied, or the normalized path if permission is
- granted. You can also return 1 to indicate that the path can
- be used unchanged.
+ This function is called to check if the object ob with the
+ user-id uid has write permissions to the file given by path
+ for the operation named by func. It should return 0 if
+ permission is denied, or the normalized path if permission is
+ granted. You can also return 1 to indicate that the path can
+ be used unchanged.
- The returned pathname must not contain ``..'', a leading /
- will be stripped by the interpreter.
+ The returned pathname must not contain "..", a leading /
+ will be stripped by the interpreter. By default, the returned
+ path must also not contain space characters; if the driver
+ is instructed to allow them, the preprocessor macro
+ __FILENAME_SPACES__ is defined.
- Func denotes the efun call or other operation that caused
- valid_write() to be called:
- cindent,
- do_rename (efun rename(), for the old and then for the new name),
- ed_start (whenever the builtin ed tries to write to a file),
- mkdir,
- remove_file (efun rm()),
- rmdir,
- save_object,
- write_bytes,
- write_file.
+ Func denotes the efun call or other operation that caused
+ valid_write() to be called:
- Note that this function is called in compat mode as well. If
- you need to be compatible with the old 2.4.5-mudlib, redirect
- these calls to the valid_read/valid_write in the user
- object.
+ copy_file : for the target file or directory name
+ rename_from : efun rename(), for the original name
+ rename_to : efun rename(), for the new name
+ ed_start : whenever the builtin ed tries to write to a file
+ garbage_collection
+ mkdir
+ memdump
+ objdump
+ opcdump
+ remove_file : efun rm()
+ rmdir
+ save_object
+ write_bytes
+ write_file
+
+ For save_object(), the <path> passed is the filename as given
+ in the efun call. If for this efun a filename ending in ".c" is
+ returned, the ".c" will be stripped from the filename.
+
+ This function is called in compat mode as well. If
+ you need to be compatible with the old 2.4.5-mudlib, redirect
+ these calls to the valid_read/valid_write in the user
+ object.
+
+HISTORY
+ LDMud 3.2.8 adds operation "copy_file", and replaces "do_rename"
+ by "rename_from" and "rename_to".
+ LDMud 3.2.9 adds operation "garbage_collection".
+ LDMud 3.3.526 adds operation "memdump".
SEE ALSO
- valid_read(M), make_path_absolute(M)
+ valid_read(M), make_path_absolute(M)