#lang scribble/doc @(require scribble/manual (for-label scheme (planet "main.ss" ("murphy" "packed-io.plt" 1 0)) (planet "enumeration.ss" ("untyped" "unlib.plt" 3 20)) "../data.ss")) @title[#:tag "data"]{Basic Data Structures} @local-table-of-contents[] @defmodule[(planet "data.ss" ("murphy" "9p.plt" 1 0))]{ Basic data structures that are used by the network level code as well as the high level client and server side code. } @section{File Information} @defstruct[qid ([type natural-number/c] [version natural-number/c] [path natural-number/c])]{ Information identifying a file in a filesystem uniquely. While @scheme[type] determines whether the file is a directory and contains other type flags, @scheme[path] and @scheme[version] contain an arbitrary combination of numbers unique among all files on the file system. See @hyperlink["http://swtch.com/plan9port/man/man9/stat.html"]{stat(9P)} for details about the contents of the structure. } @defstruct[stat ([type (or/c natural-number/c #f)] [dev (or/c natural-number/c #f)] [qid (or/c qid? #f)] [mode (or/c natural-number/c #f)] [atime (or/c natural-number/c #f)] [mtime (or/c natural-number/c #f)] [length (or/c natural-number/c #f)] [name (or/c string? #f)] [uid (or/c string? #f)] [gid (or/c string? #f)] [muid (or/c string? #f)])]{ A directory entry. When reading directories or asking files for their stat information, the result normally doesn't contain fields set to @scheme[#f]. When setting the stat information for a file, any field specified as @scheme[#f] is not changed. Many fields must actually be specified as @scheme[#f] in that case, because they are considered immutable. See @hyperlink["http://swtch.com/plan9port/man/man9/stat.html"]{stat(9P)} for details about the contents of the structure. } @defform[(type-flag id) #:contracts ([id (symbols 'file 'dir 'append 'excl 'mount 'auth 'temp)])]{ Enumeration of file type flags as contained in the @scheme[qid-type] field or the high bits of the @scheme[stat-mode] field. @schemeid[file] is the neutral value just indicating a normal file, @schemeid[dir] identifies directories, @schemeid[append] files that can oly be appended to, @schemeid[excl] stands for exclusive access, @schemeid[mount] indicates mountpoints, @schemeid[auth] authentication channels and @schemeid[temp] temporary files. The transformer is defined using @scheme[define-enum]. } @defform[(file-type id ...)]{ Expands to a numeric file type computed from a bitwise inclusive or of flag values specified by identifiers as for @scheme[type-flag]. } @defform[(access-flag id) #:contracts ([id (symbols 'e 'x 'w 'r)])]{ Enumeration of file permission flags as contained in the lower bits of the @scheme[stat-mode] field. @schemeid[e] is the neutral value and just indicates file existence in permission checks, @schemeid[x] means execute acces, @schemeid[w] write access and @schemeid[r] read access. The transformer is defined using @scheme[define-enum]. } @defform*[#:literals (type user group others) ((file-mode (type id ...) (user id ...) (group id ...) (others id ...)) (file-mode (user id ...) (group id ...) (others id ...)) (file-mode type-bits perm-bits))]{ Expands to a numeric file mode computed from a bitwise inclusive or of bit shifted flag values for the type, specified by identifiers as for @scheme[type-flag], and for the access permissions, specified by identifiers as for @scheme[access-flag]. The type clause can be omitted or both type and permissions can be given directly as numbers, in which case the macro may still be useful because you don't have to remember the correct bit shift counts to combine those values. } @defproc[(file-mode-type [m natural-number/c]) natural-number/c]{ Extracts the bits defining the type of a file from a numeric file mode. } @defproc[(file-mode-user [m natural-number/c]) natural-number/c]{ Extracts the bits defining the access permissions for a file's owner from a numeric file mode. } @defproc[(file-mode-group [m natural-number/c]) natural-number/c]{ Extracts the bits defining the access permissions for members of a file's owning group from a numeric file mode. } @defproc[(file-mode-others [m natural-number/c]) natural-number/c]{ Extracts the bits defining the access permissions for other users than the file's owner or members of its owning group from a numeric file mode. } @section{Operation Modes} @defform[(open-direction id) #:contracts ([id (symbols 'r 'w 'r/w 'x)])]{ Enumeration of basic access types when opening a file. @schemeid[r] means read access, @schemeid[w] write access, @scheme[r/w] both read and write access and @schemeid[x] means execute access. Execute access behaves like read access except for the permission checks which use execute instead of read permissions. The transformer is defined using @scheme[define-enum]. } @defform[(open-flag id) #:contracts ([id (symbols 'trunc 'rclose)])]{ Enumeration of additional flags that can be used when opening a file. @schemeid[trunc] means the file, if opened for writing, should have its size reset to zero, @schemeid[rclose] means the file should be removed once it is closed. The transformer is defined using @scheme[define-enum]. } @defform[(open-mode dir-id flag-id ...)]{ Expands to a numeric mode that can be passed to file open calls. The mode is computed as a bitwise inclusive or of a direction value and open flags that are specified by identifiers as for @scheme[open-direction] and @scheme[open-flag]. } @defproc[(open-mode-direction [m natural-number/c]) natural-number/c]{ Extracts the direction value from a numeric file open mode. } @defproc[(open-mode-flags [m natural-number/c]) natural-number/c]{ Extracts the additional open flags from a numeric file open mode. } @section[#:tag "data/packing"]{Packings} @defthing[nstring/p packing?]{ Packing of a string prefixed with 16 bit size information. } @defthing[nbytes/p packing?]{ Packing of a byte string prefixed with 16 bit size information } @defthing[qid/p packing?]{ Packing of a @scheme[qid] file identifier structure. } @defthing[stat/p packing?]{ Packing of a @scheme[stat] directory entry structure. }