The Phantasmal MUDlib for DGD: Driver & Auto APIs

Phantasmal MUD Lib for DGD

Phantasmal Site

Phantasmal Site > DGD > The Kernel Library > Driver & Auto APIs

Specific Operations

Note: all specifics given here are current as of DGD 1.2.35. While the Kernel MUDLib tends to change very little, these operations are, in fact, subject to change at any time by Dworkin.

Also, this page details only those APIs that are exported to code outside of /kernel -- static and private functions of the Driver object, for instance, aren't listed here even though DGD or the Driver itself may call them.

Driver Operations

Your Driver object is the first object that exists, the one DGD creates before absolutely anything else. The Kernel MUDLib writes it for you, but you'll still want to know what it does. You can look at its code in /kernel/sys/driver.

Any of these operations may be called as DRIVER->operation() like a normal call_other. You can also use an explicit call_other, naturally. Operations you don't have access to perform will usually fail silently, so *check your results*.

Some operations are described as system-only. That means they can be called by any .c file under the /kernel or /usr/System directories, but anybody else silently gets no useful result.

Operations:

string creator(string file): This simple operation is publicly accessible. It tells you the creator of an object, which it figures out entirely from its path. Anything in the /kernel or /usr/System directories or their subdirectories has a creator of "System". Anything in a /usr/XXX/ directory or one of its subdirectories has a creator of XXX. Anything not in a /usr/blah/ subdirectory has no creator at all: some operations, like, cloning, may be forbidden from such files.
string normalize_path(string file, string dir, varargs string creator): This publicly accessible operation allows you to resolve a path like "~System/obj/user.c" into "/usr/System/obj/user.c". It's a convenience function, also used for security -- if there's only one kind of path, you only need to check one kind of thing. So you run your paths through DRIVER->normalize_path first to make sure you're good. File is the filename you're checking out, dir is the current directory (if any) and creator is the username that "~" resolves to. So if creator is "butch" then ~/obj/goblin.c resolves to "/usr/butch/obj/goblin.c".
int file_size(string file, varargs int dir): This system-only call returns the size of the file, or 0 if it doesn't exist. You'll normally want to call get_dir instead. The second, optional arg should be 1 if the supplied file name is that of a directory. This call is system-only since it returns information about the file without doing any further security checking.
void set_object_manager(object obj): This system-only operation sets the object manager. What that means is documented elsewhere.
void set_error_manager(object obj): This system-only operation sets the error manager. What that means is documented elsewhere.
compiling, compile, compile_lib, compile_failed, clone, destruct, destruct_lib: All these operations may be called only by AUTO. That means you just can't. If you want to get the same information usefully, read up on the object manager which receives more useful (to you) versions of each of these.
string query_owner(): For completeness and to avoid errors, even the Driver responds to query_owner() (see AUTO). Its owner is System.
set_tls_size, query_tls_size, get_tlvar, set_tlvar: these query and affect Thread-Local Storage. While query_tls_size is publicly accessible, this stuff is very Deep Voodoo. If you genuinely need a document like the one you're reading here instead of just skimming the source code I highly recommend you not mess with this.
void message(string str): This system-only function sends a time-tagged message to the console. Look at the messages you get on bootup that say things like "Jan 27 17:26:17 ** DGD 1.2.35". The format looks like that.
prepare_reboot: These calls are kernel-only. Since you're not modifying the Kernel MUDLib (right?) that means you'll never call them. Fuhgeddaboudit.
mixed* query_wfile(): This publicly accessible function gives you the name and size of the editor file last written. However, since it always wipes out the file afterwards and AUTO always calls it after calling editor(), you can't do anything useful with it.

AUTO Object Operations

Your AUTO object is automatically inherited by every other object in the MUD except the Driver. Any operation it defines can be used on any other object in the MUD as though it were a Kernel Function. In fact, this is how the Kernel MUDLib alters the Kernel Functions that it alters.

Public (including nomask) or static function may be called on any object inheriting from AUTO, but private functions may not, so I don't bother to list them here. For the same reason, I don't bother to list access controlled functions which must be called by specific Kernel MUDLib programs. Technically you could call these by modifying the Kernel MUDLib, but that makes this whole security overview moot.

Many comments here are by direct inspection of the code. That means several things. For one, it means that all these comments may be very specific to DGD 1.2.35, especially since I've submitted some of them to Dworkin for possible alteration or correction. It also means that if you try things and the code just doesn't behave the way I say it does, I'm probably wrong. Don't treat the COMMENTS sections especially as canon.

None of these may be called directly on a library, only on a clone, clonable or LWO. That's because no function may be directly called on a library, only on a clone, clonable or LWO.

Things labelled "From the docs" refer to the /doc/kernel/efun/XXX file for a given function XXX.

Operations:

nomask string query_owner()

This publicly accessible function returns the owner of the object. It overrides nothing and is undocumented.

find_object

From the docs:

The string argument is resolved as a file path, and the object with the resulting name is searched for. Either the object, if found, or zero is returned.

Objects with "lib" as a path component cannot be found with this function.

destruct_object

From the docs:

Destruct the object given as the argument, which can be an object or the name of an object. Any value holding the object will immediately change into nil, and the object will cease to exist.

If an object destructs itself, it will cease to exist as soon as execution leaves it. If the last reference to a master object is removed (including cloned objects and inheriting objects), the function remove_program(objname) will be called in the driver object.

Return 1 if the object existed and was destructed, 0 otherwise.

ACCESS: Unless the creator of the current object is "System", an object can only be destructed if it has the same owner as the current object.

COMMENTS: You can't call this from (or on) a destructed object. You can call it with a string as an argument, which will be looked up for you with find_object. You can't call it on a non-persistent (i.e. LWO) object. Only Kernel objects can destruct clonable objects under /kernel.

compile_object

From the docs:

Compile an object from a LPC file, specified by the first argument with ".c" appended. If the optional source argument is supplied, the object is compiled from that string, instead. The returned object will have the file string as name.

If the object to be compiled already exists and is not inherited by any other object, it and all of its clones will be upgraded to the new version. Variables will be preserved only if they also exist in the new version and have the same type; new variables will be initialized to nil. The actual upgrading is done immediately upon completion of the current thread.

If the new object has "lib" as a path component, it can only be inherited and nil is returned. Otherwise, if the object has "obj" as a path component, it can be cloned.

ACCESS: The current object must have write access to the file to be compiled.

COMMENTS: Note the phrase "write access" under ACCESS. It's important.

This call will fail with an "Access denied" error in a number of cases, often for quite good reason. If you call it from a destructed object, or if you're a non-System file and don't have write access it'll happen. You'll get a "Too many objects" error if the wizard exceeds his/her RSRC object quota. For clonables, the wizard must have appropriate "create stack" and "create ticks" RSRCD quotas. A non-library will then be initialized immediately with a call_other call.

clone_object

From the docs:

Create a clone of the specified object with an unique name of the form "object_name#1234". The cloned object must not itself be a clone. The new object is returned. The create() function will be called in the cloned object immediately.

If the optional second argument is specified and non-zero, and the owner of the current object is "System", the new object will have the specified owner. Otherwise, it will have the same owner as the current object.

ACCESS: The current object must have read access to the file of the object to be cloned.

COMMENTS: This call will fail with an "Access denied" error in a number of cases, often for quite good reason. If you call it from a destructed object, or if you're a non-System file and don't have read access it'll happen. If you're a non-Kernel program trying to clone a Kernel object it'll happen.

There's a different "Cannot clone XXX" error which occurs under a different set of conditions. It'll happen if the object calling clone_object has no owner, or if the object being cloned doesn't exist, or if the path being cloned doesn't contain "/obj/", or if it contains "/data/" or "/lib/". Note this error message is likely to be changed very soon, though the same circumstances will cause errors.

Every wizard gets a RSRCD object quota. If cloning would exceed that, a "Too many objects" error occurs. The wizard must also have enough "create stack" and "create ticks" quota.

new_object

From the docs:

Create a new light-weight instance of the specified object with a name of the form "object_name#-1". If the master object is itself a light-weight object, it will be copied. Light-weight objects cannot be destructed and are automatically deallocated once the last reference to them is removed. The new object is returned. The create() function will be called in the new object immediately.

If the optional second argument is specified and non-zero and the owner of the current object is "System", the new object will have the specified owner. Otherwise, it will have the same owner as the current object.

ACCESS: Unless the master object is itself a light-weight object to be copied, the current object must have read access to the file of the object to be created.

COMMENTS: You cannot call this function from a destructed object. If the object is being created from a path rather than an existing LWO, there are a number of other restrictions: The owner of the current object must exist, the object being compiled from must exist, the path to that object must contain "/data/", and it must contain neither "/obj" nor "/lib/". If any of these is violated the error "Cannot create new instance of XXX" will occur.

LWOs don't count against a wizard's RSRCD object count, but the wizard must have enough "create stack" and "create ticks" to create the new object.

call_trace

From the docs:

Return the function call trace as an array. The elements are of the following format:

({ objname, progname, function, line, extern, arg1, ..., argn })

The line number is 0 if the function is in a compiled object. Extern is 1 if the function was called with call_other(), and 0 otherwise.

The offsets in the array are named in the include file <trace.h>. The last element of the returned array is the trace of the current function.

ACCESS: If the owner of the current object is not the same as the creator of the program containing a function, the arguments are omitted.

COMMENTS: If called by a non-System program, this returns an abbreviated stack.

status

From the docs:

Called without an argument, this kfun returns information about resources used by the system. With an object as argument, resource usage by that object is given. The returned value is an array, the fields of which are described in the include file <status.h>. ACCESS: If the current object is not the owner of the argument object, if any, callout arguments are omitted in the returned status array.

COMMENTS: The calling object may not be destructed. Arguments are, of course, checked for validity and security. The callouts shown for objects have some restrictions: kernel object callouts are never shown. Ownerless objects may only see the arguments of their own callouts. Owned objects may only see arguments of callouts of objects owned by their owner ("sibling objects" if you will).

object this_user()

This publicly available API returns the user object currently active, or nil. No access control. Overrides a Kernel Function of the same name.

object* users()

This publicly available API calls query_users() on the USERD for you. Access to the regular Kernel Function ::users() call is filtered through USERD.

void swapout(), void shutdown()

In the Kernel MUDLib, these calls are system-only but otherwise basically identical.

void dump_state(void)

In the Kernel MUDLib, this call is system-only. It also calls prepare_reboot on your initd if you have one.

mixed call_limited(string function, mixed args...)

From the docs:

Call a function in the current object, using the resource limits of the current object's owner.

ACCESS: Publicly available.

COMMENTS: the Kernel MUDLib does a little extra stuff here -- sets up thread-local storage (TLS), manages ticks and stack usage -- but the result should look the same as the non-overridden call_out other than being resource-limited.

int call_out(string function, mixed delay, mixed args...)

From the Kernel Function (not Kernel MUDLib) docs:

Call a function in the current object with a delay. The function to be called must not be private. The delay is specified in seconds. The minimum delay is 0 seconds, for a function that is to be called as soon as possible after termination of the current thread.

If the delay is an integer, the function will be called after approximately the specified number of seconds. Otherwise, the delay must be a floating point number less than or equal to 60.0, and the function will be called with a millisecond resolution.

The returned value is the callout handle, an integer > 0 which must be used if the callout is to be removed.

COMMENTS: The Kernel MUDLib docs don't seem to mention this, but there are several things it alters in its version (which calls the original). It checks the arguments for permissions. It makes sure you're not trying to call_out from a non-persistent object (i.e. a LWO). It also does resource tracking via RSRCD to make sure that there aren't more callouts than currently allowed for the current user.

mixed call_out(int handle)

From the Kernel Function (not Kernel MUDLib) docs:

Remove the callout associated with handle. The delay after which the function would have been called is returned. The delay is an integer or a floating point number, depending on how the callout was started. If there is no scheduled call associated with the handle in the current object, return -1.

COMMENTS: This is another call that the Kernel MUDLib overrides without it being documented. It looks like the Kernel MUDLib will return 0 rather than a delay when callouts are suspended by RSRCD.

add_event

From the docs:

Define a new event type for which this object can broadcast events. If the event type already existed, nothing is changed.

ACCESS: (not documented)

COMMENTS: Looks like this is publicly available and it directly affects only the object it gets called on.

remove_event

From the docs:

Remove an event type defined by the current object, automatically unsubscribing all objects that are subscribed to it. If the event type did not exist, nothing is changed.

ACCESS: (not documented)

COMMENTS: Looks like this is publicly available and it directly affects only the object it gets called on.

query_events

From the docs:

Return an array with names of events defined by the current object.

ACCESS: (not documented)

COMMENTS: Looks like this is publicly available and it directly affects only the object it gets called on.

subscribe_event

From the docs:

Subscribe to an event in the given object. The object defining the event subscribed to controls access to events with the allow_subscribe(obj, name) function, which must return 0 to block object `obj' from subscribing to event `name'.

ACCESS: (not documented)

COMMENTS: Looks like this is publicly available and it directly affects only the object it gets called on. A "Cannot subscribe to event" error can be generated by this function for a number of reasons. The object being subscribed to may not define the allow_subscribe method, that method may have returned false, the object may not exist, or the calling object may be non-persistent (i.e. an LWO). All of these yield the same "Cannot subscribe to event" error.

A number of other errors can be generated by either this or unsubscribe_event(below). "No such event", "Already subscribed to event", "Not subscribed to event" (for unsubscribe) are all what they sound like. "Too many events" means that the owner of the object trying to subscribe doesn't have enough RSRCD quota for events left.

unsubscribe_event

From the docs:

Unsubscribe to an event in the given object.

ACCESS: (not documented)

COMMENTS: Looks like this is publicly available and it directly affects only the object it gets called on. See subscribe_event for some errors that can occur when this is called.

query_subscribed_event

From the docs:

Return an array containing the objects subscribed to the given event.

ACCESS: (not documented)

COMMENTS: Looks like this is publicly available and it directly affects only the object it gets called on.

event

From the docs:

Immediately after termination of the current thread, the function "evt_" + name is called in all objects subscribed to the named event, with the current object as first argument. Each call is done using the tick and stack resources of the subscribed object.

ACCESS: (not documented)

COMMENTS: Looks like this is publicly available and it directly affects only the object it gets called on. It can generate a "Too many callouts" error if the owner of the object calling event() has exceeded his/her RSRCD callouts quota.

event_except

From the docs:

Immediately after termination of the current thread, the function "evt_" + name is called in all objects subscribed to the named event, with the current object as first argument. Each call is done using the tick and stack resources of the subscribed object. Objects in the exclude list will be skipped.

ACCESS: (not documented)

COMMENTS: Looks like this is publicly available and it directly affects only the object it gets called on. It can generate a "Too many callouts" error if the owner of the object calling event() has exceeded his/her RSRCD callouts quota.

read_file

From the Kernel Function (not Kernel MUDLib) docs:

Read a file. The optional second and third arguments specify an offset in the file and the maximum length of the string to be read, and default to the whole file from the beginning. The offset may be specified as negative, to read from the end of a file.

COMMENTS: This is another call that the Kernel MUDLib overrides without it being documented. This call will fail with an "Access denied" error in a number of cases, often for quite good reason. If you call it from a destructed object, or if you don't have read access to the file you're reading and aren't a program in the System directory this will happen.

write_file

From the Kernel Function (not Kernel MUDLib) docs:

Write a string to a file. If the optional third argument is specified and non-zero, write the string at the given offset in the file; otherwise, append to the file. The offset may be negative to offset backwards from the end of the file. To write a string to the beginning of a file, let the offset be equal to minus the length of the file.

The return value is 1 for success, 0 for failure.

COMMENTS: This is another call that the Kernel MUDLib overrides without it being documented. This call will fail with an "Access denied" error in a number of cases, often for quite good reason. If you call it from a destructed object, or if you're a non-System file and don't have write access it'll happen. You can get a "File quota exceeded" if you're not created by System and you've alread exceeded your file quota. You can get a similar error if this write would bring you above your quota.

remove_file

From the Kernel Function (not Kernel MUDLib) docs:

Remove a file. 1 is returned if the file could be removed, 0 otherwise.

COMMENTS: This is another call that the Kernel MUDLib overrides without it being documented. This call will fail with an "Access denied" error in a number of cases, often for quite good reason. If you call it from a destructed object, or or if you're a non-System file and don't have write access it'll happen.

rename_file

From the Kernel Function (not Kernel MUDLib) docs:

Rename a file. The destination file must not yet exist. 1 is returned if the file could be renamed, 0 otherwise.

COMMENTS: This is another call that the Kernel MUDLib overrides without it being documented. This call will fail with an "Access denied" error in a number of cases, often for quite good reason. If you call it from a destructed object, or if you're a non-System file and don't have write access it'll happen. If you try to rename to or from a file under /kernel or /include/kernel, it'll happen. If you try to rename from a file in /include, it'll happen. You'll also need write access to both locations to make it happen. If you rename somebody else's file that you have write access to, it correctly gets tallied to your filequota instead of theirs.

get_dir

From the docs:

Get information about a file or files in a directory. The return value is of the form

({ ({ file names }), ({ file sizes }), ({ file mod times }), ({ objects }) })

If a file is a directory, the file size will be given as -2. If the last path component of the specified file can be interpreted as a regular expression, all files which match this regular expression are collected. Otherwise, only the file itself is taken. If no files match, or if the file is not present, the return value of get_dir() will be ({ ({ }), ({ }), ({ }), ({ }) }).

Objects that have "lib" as a path component are replaced with 1 in the object array.

The following characters have a special meaning in a regular expression:

            ?       any single character
            *       any (possibly empty) string
            [a-z]   any character in the range a-z
            [^a-z]  any character not in range a-z
            \c      the character c, not interpreted as having a special
                    meaning

The files will be sorted by file name. Only as many files as specified by status()[ST_ARRAYSIZE], with ST_ARRAYSIZE defined in the include file <status.h>, will be collected.

ACCESS: (not documented)

COMMENTS: This call will fail with an "Access denied" error in a number of cases, often for quite good reason. If you call it from a destructed object, or if you're a non-System file and don't have read access to the file(s) it'll happen. Inheritable (library) objects are treated specially in the Kernel MUDLib version, and will be returned with different information available.

file_info

From the docs:

Get information about a file. The return value is of the form

({ file size, file modification time, object })

If a file is a directory, the file size will be given as -2. The object value is set to 1 if the object exists and has "lib" as a path component.

If the file doesn't exist, nil is returned.

ACCESS: (not documented)

COMMENTS: This call will fail with an "Access denied" error in a number of cases, often for quite good reason. If you call it from a destructed object, or if you're a non-System file and don't have read access to the file it'll happen. Some information isn't available for inheritable (library) objects, those with "/lib/" in the path.

make_dir

From the Kernel Function (not Kernel MUDLib) docs:

Create a new directory. 1 is returned if the directory could be created, 0 otherwise.

COMMENTS: This is another call that the Kernel MUDLib overrides without it being documented. It will fail with an "Access denied" error in a number of cases, often for quite good reason. If you call it from a destructed object, or if you're a non-System file and don't have write access to the file it'll happen. If you try to make a subdirectory of /include/kernel or /kernel, it'll happen. If you've already exceeded your file quota or would with this operation, a different error will occur to let you know.

remove_dir

From the Kernel Function (not Kernel MUDLib) docs:

Remove a directory, which must be empty. 1 is returned if the directory could be removed, 0 otherwise.

COMMENTS: This is another call that the Kernel MUDLib overrides without it being documented. It will fail with an "Access denied" error in a number of cases, often for quite good reason. If you call it from a destructed object, or if you're a non-System file and don't have write access to the file it'll happen. If you try to remove the /kernel or /include/kernel directories it'll happen.

restore_object

From the Kernel Function (not Kernel MUDLib) docs:

Restore all global variables in an object that are not private or static from a file. All variables which qualify, but were not restored and do not contain object values, will be set to 0. 1 is returned if the variables could be restored, 0 otherwise.

COMMENTS: This is another call that the Kernel MUDLib overrides without it being documented. It will fail with an "Access denied" error in a number of cases, often for quite good reason. If you call it from a destructed object, or if you're a non-System file and don't have read access to the file it'll happen.

save_object

From the Kernel Function (not Kernel MUDLib) docs:

Save all global variables in an object that are not private or static to a file. Only non-zero and non-object values are actually saved.

COMMENTS: This is another call that the Kernel MUDLib overrides without it being documented. It will fail with an "Access denied" error in a number of cases, often for quite good reason. If you call it from a destructed object, or if you're a non-System file and don't have write access to the file it'll happen. If you try to save a non-kernel object under the /kernel directory, it'll happen. If you try to save anything into /include/kernel, it'll happen. Saved objects also count against your file quota, so you have all the usual file quota errors that can occur.

editor

From the Kernel Function (not Kernel MUDLib) docs:

Execute an editor command for the current object. If the editor command is the first for this object, an editor instance will be created for it. The editor instance will remain active until an editor command is specified that terminates it, or until the object is destructed. Editor output will be returned as a string. The editor status of an object can be queried with the kfun query_editor(). File paths for reading and writing will be translated by path_read() and path_write(), respectively, in the driver object.

COMMENTS: This is another call that the Kernel MUDLib overrides without it being documented. Only a persistent, non-destructed System object may start an editor instance. There is an editor RSRCD quota for wizards determining how many editor instances they can keep going at once. Editing files, naturally, affects one's filequota.

connect, open_port, ports

These only work if you've installed the net package, since it opens outbound connections. It's not ever expected to work with vanilla DGD for reasons explained elsewhere.

This website is released to the public under the terms of the GNU Free Documentation License, Version 1.3 or later