Structured Lists

This section documents the data structures used by servedat to deliver directory listings to clients.  It may be useful for advanced movedat scripts, implementations of the ExpeDat Client SDK, or when generating listings within an object handler.

Structured listings are requested by using one of three built-in handler types:

*ls	List information only for the specified file or directory path.
*li	List all files in the specified directory path.
*lr	List the entire directory tree, including all files in the specified directory path and recursing into all sub-directories.

For example, to obtain a structured list of all files at the top level of a directory, you might type:

movedat -D 'user@example.com=*li:pathname'

Note the use of movedat's -D option to permit display of the raw data.  When using an object handler, you can request a structured listing by passing one of the above types after the handler's type as shown below.  Not all handlers may support all listing types for all objects, so the results may vary from what is described on this page.

movedat -D 'user@example.com=S3,*li:pathname'

Notice the use of single quotes to escape the asterisk character from the command shell.  In some embedded environments that do not include shell parsing, you may need to leave that out.

The server will return a series of text lines.  Each line is terminated with a single newline character ('\n').  The fields within each line are delimited by tab characters ('\t').

Text fields are UTF-8 encoded.  Reserved characters, such as tab and newline, are escaped when they occur within a text field.  Escaping uses the notation %XX, where "XX" is a hexadecimal code for the byte value.  Note that some operating systems allow pathnames to contain arbitrary binary strings, which may not be valid unicode.

Numeric fields should be parsed only up to the first non-numeric character (as for strtoull()).  Parsing should be tolerant of future servers adding more sub-fields delimited by non-numeric characters such as ',' or ':'.  Some numeric fields are specified in decimal notations, others are specified in hexadecimal.  When parsing hexadecimal fields, allow for values up to 64-bits (16 characters).

Future versions of servedat may add additional fields, past versions may return fewer fields.  For specifications relating to other versions, refer to the documentation which came with the server.

Header Format

The first line of a structured listing, or the fourth line of an mtping structured response contains information about the server.

Name	The name of the server application, usually "servedat".
Version	The revision code of the server.
Platform	An MTP platform specifier identifying the server's system type.
Current Time	The server's local clock time, given in hexadecimal seconds UTC since January 1, 1970 ("unix time").
Time Zone	The three character time-zone abbreviation for the server's clock.
Path Delimiter	The delimiting character used to separate path components.  As of version 1.13, this is always a forward slash: '/'.
Restrictions	A comma separated list of access restrictions, based on the server configuration and any given credentials.  This field is advisory: additional restrictions and exceptions may apply depending on the server configuration, user authorization, and individual file properties.  Possible values include:
ro	ReadOnly
wo	WriteOnly
rh	RestrictHome
nl	No links (symbolic links may not be created)
no	NoOverwrite
wl	WriteListOnly
go	GetOnly
Reserved	This field is reserved for future use.
Load	A comma separated list of server load counts in base-ten (decimal).
load	The number of transactions being processed by the server at the start of this transaction.  This will include any listing transaction used to retrieve the header.
maxconfig	The highest load value experienced by the server since the last configuration reload.
maxstart	The highest load value experienced by the server since it was started.
initcount	The total number of transactions attempted since the last configuration reload.
Capacity	A comma separated list of base-ten (decimal) values related to server capacity.
maxcapacity	The maximum number of concurrent transactions allowed by the server.
exceeded	The number of transactions which were denied because the server load was at maximum capacity.  This number is also included in denycount.
Uptime	The hexadecimal number of seconds elapsed since the server process was started. servedat 1.12.2 and earlier reported this value in milliseconds.
Config Time	The hexadecimal number of seconds elapsed since the server configuration was last changed. servedat 1.12.2 and earlier reported this value in milliseconds.
Idle Time	The hexadecimal number of seconds elapsed since the last transaction.
Errors	A comma separated list of server error counts in base-ten (decimal).
errorcount	The number of critical server errors logged since the last configuration reload.  This approximately equals the number 'E' log entries.
failcount	The number of transactions which failed after a successful start since the last configuration reload.  This includes user aborts as well as network disruptions.
warncount	The number of server warnings and non-critical transaction errors which have occurred since the last configuration reload.  This approximately equals the number 'W' log entries.
denycount	The number of transactions which failed to start since the last configuration reload.  This counts failures which occurred before any data could be sent, such as permission or path errors.
Free Space	If this header was obtained via the listing of a directory, then this field contains the hexadecimal number of bytes available in the filesystem at that path as reported by the operating system.  If this value is 0 or writeonly is set, then uploads are not permitted.  A positive value does not guarantee that an upload will be permitted as file permissions and other restrictions may apply.  This field is empty for ping responses.
Data	The number of bytes transferred in and out of the server since the last configuration update.  Formatted as comma separated, hexadecimal, 64-bit numbers.
Bandwidth	The bits per second, incoming and outgoing, averaged over the previous minute.  Formatted as comma separated, hexadecimal, 64-bit numbers.
Drops	The number of datagrams dropped due to bad checksums and due to bad headers.  Formatted as comma separated, hexadecimal, 64-bit numbers.

Listing Format

Each line after the header corresponds to one file or directory.

Relative Path	The pathname of the file relative to the path being listed.  Files in subdirectories will use the delimiter specified in the header.  Reserved characters will be escaped using a percent character followed by two hexadecimal characters specifying the byte code.  For example, %09 is substituted for the tab character and %25 is substituted for the percent character.
Size	The size of the file in hexadecimal bytes.  This value may have no meaning for directories or other irregular files.  For valid symbolic links, the size of the target is given.
Modification Date	A hexadecimal integer specifying the modification time stamp of the file in "unix time".  For valid symbolic links, the modification date of the target is given.
File Type	The first character is one of 'D'irectory, 'F'ile, 'L'ink, 'M'eta, 'T'emp, 'O'ther, or 'E'rror.  The second character may be 'h for "hidden" files which the server operating system would not normally display to users.  For symbolic links, type 'L', the next character will be one of the types above describing the link target.
Access Mode	A 9-bit hexadecimal integer specifying the Read Write eXecute permissions for the owner, group, and world.  For unix servers, this is the lower 9-bits of the file mode.  For Windows servers it is contrived from the Read-Only setting of the file.  Additional high bits, if present, should be ignored.  For valid symbolic links, the mode of the target is given.
UserID:GroupID	One or two hexadecimal integers, separated by a colon ':', specifying the file's unix user id and group id numbers.  This field may be omitted or empty, particularly for Windows servers.  For valid symbolic links, the ids of the target is given.
Description	An optional description of the file.  For symbolic links, the target path is given.

If the file type is 'E', then the Access Mode, UserID:GroupID, and Description fields will be omitted.  In their place, a fifth field may contain a text string describing the error.

Example Listing

prompt# movedat -D 'demo.mtpip.net:=*li'