File Primitives

int access( string  path, int  mode )

Test file accessibility.

Description

The access() primitive is used to check the accessibility of a file.  The file parameter is the name of a directory or file which is to be tested and mode are a set of access bits which are used to check the effective access.

When the value of mode is zero, only the existence of the file is verified.  The meaning of mode is operating system dependent yet most operating systems support the following definitions:

Returns

On successful return this primitive returns >= 0; -1 is returned on an error, and the global variable errno is set to the reason for the failure.

Portability

A GriefEdit extension.

See Also

exist, stat, lstat, ftest, chmod

int basename( string  pathname,   [string suffix] )

Return the last component of a pathname.

Description

The basename() primitive returns a string containing the final component of a pathname contained in the string path argument, deleting trailing path separators.

To accomplish this, basename first checks to see if name consists of nothing. but slash (/) or backslash (\) characters.  If so, basename replaces name with a single slash and the process is complete.  If not, basename removes any trailing slashes.  If slashes still remain, basename strips off all leading characters up to and including the final slash.

If you specify suffix and the remaining portion of name contains a suffix which matches suffix, basename removes that suffix.

Returns

The basename() primitive returns a string containing the final component of the specified pathname after processing following the above rules.

See Also

dirname, strfilecmp

int chdir( string  path )

Change directory.

Description

The chdir() primitive changes the current directory on the specified drive to the specified path.

Unlike cd no shell expansion shall occur.

Returns

The chdir() primitive returns zero if successful, and a non-zero value (-1) otherwise.  When an error has occurred, the global errno contains a value indicating the type of error that has been detected.

Portability

A GriefEdit extension.

See Also

cd, mkdir, rmdir, getwd

int chmod( string  path, int  mode )

Change mode.

Description

The chmod() primitive changes the permissions for a file specified by path to be the settings in the mode given by permission.

The access permissions for the file or directory are specified as a combination of bits which are operating system specific.

Returns

The chmod() primitive returns zero if successful, and a non-zero value (-1) otherwise.  When an error has occurred, the global errno contains a value indicating the type of error that has been detected.

See Also

chown, stat, lstat, umask

int chown( string  path, int  owner, int  group )

Change owner.

Description

The chown() primitive is reserved for future use.

Returns

The chown() primitive returns zero if successful, and a non-zero value (-1) otherwise.  When an error has occurred, the global errno contains a value indicating the type of error that has been detected.

See Also

chmod, stat, lstat, umask

int compare_files(   [int flags], string  file1, string  file2 )

Binary file compare.

Description

The compare_files performs simple comparison byte-for-byte of the on disk images of the two file file1 and file2.

The flags are intended for future options, supporting simple line processing.

It can be used to quickly determine if two files are identical (byte for byte).  Note that if either file is an active buffer, no unsaved changes shall be included.

In contrast, the <diff_buffers> primitive is used to compare files and mark up the differences.

Returns

Returns 1 if the files are identical, 0 if they differ.  -1 if the first file cannot be read, -2 if the second file cannot be read.

Portability

A GriefEdit extension.

See Also

<diff_buffers>

int copy_ea_info( string  sourcename, string  destname )

Copy file extended information.

Description

The copy_ea() primitive is reserved for future BRIEF compatibility.

Parameters

n/a

Returns

n/a

Portability

Provided for BRIEF compatibility.

See Also

read_ea, set_ea

int del( string  name )

Delete a file.

Description

The del() primitive deletes the specified file name.

This function is provided for compatibility using the remove interface; see the remove primitive and the brief macro module for details.

Parameters

Returns

remove, delete_buffer

int dirname( string  path )

Report the parent directory name of a file pathname.

Description

The dirname() primitive shall take a string path that contains a pathname, and return a string containing that is a pathname of the parent directory of that file.  Trailing directory separators (/ and \) characters in the path are not counted as part of the path.

If path does not contain a directory separator (/ and \) or is an empty string, then dirname shall return a string “.”.

Returns

The dirname() primitive returns string containing the parent directory name of a file pathname, otherwise a string containing “.”.

Portiablity

A GriefEdit extension.

See Also

basename

int edit_file( ... )

Edit a file.

Description

The edit_file() primitive creates a new buffer, loads the contents, attaches the buffer to the current window and executes any registered macros, see register_macro.

The argument specification is a set of one or more strings with optional leading integer modes.  Modes control the flags under which the subsequent files are processed.

If the specified file is already within another buffer, that buffer becomes the current buffer and is attached to the current window.

If more than one argument is specified; either directly or as the result of file expansion; then a separate edit action is performed on each file, with the current buffer being the last processed file.

File Expansion

The edit_file() primitive performs file name globbing in a fashion similar to the csh shell.  It returns a list of the files whose names match any of the pattern arguments.

The pattern arguments may contain any of the following special characters:

When multiple files are matched, note that the return value represents only the last file processed.

File detection

During file loading GRIEF performs a number of tests against the sections of the file content in an attempt to determine the file encoding.  These operations are generally invisible to end user and behave on most file types without interaction.

The current default scanners include, see set_file_magic for additional details on each.

Parameters

Modes

Returns

The edit_file() primitive returns a positive value on success, 0 if the user was prompted and cancelled, otherwise -1 on error.

If more than one argument is specified; either directly or as the result of file expansion; the return relates to the last loaded file.

Under EDIT_RC the return code is extended to differentiation between success conditions as follows.

Example

Expand and load all .cpp files located within the current working directory.

edit_file(".cpp");

Loads a system buffer with the content from config.ini sourced from the users home directory.

edit_file(EDIT_SYSTEM, "~/config.ini");

Portability

The feature set exposed differs from implementations.  It is therefore advised that the symbolic constants are using within a #ifdef construct.

See Also

edit_file2, read_file, attach_buffer, call_registered_macro, create_buffer, set_buffer, set_file_magic

int edit_file2(   [int &files],   [string encoding],     [int mode], string|list  file )

Extended file edit.

Description

The edit_file2() primitive extends the functionality provided by edit_file with the leading parameter of encoding.

Parameters

Returns

The edit_file2() primitive returns a positive value on success, 0 if the user was prompted and cancelled, otherwise -1 on error.

See edit_file for additional return information.

Portability

A GriefEdit extension.

See Also

edit_file, read_file, attach_buffer, call_registered_macro, create_buffer, set_buffer, set_file_magic

int exist( string  path,   [int canon = TRUE] )

Check file existence.

Description

The exist() primitive tests whether of the specified file path exists.

If canon is not specified, then the filename is canonised first.  This involves expanding any tilde prefixes and converting DOS style filenames to Unix style ones.

Returns

The exist() primitive returns non-zero if the file exists, otherwise 0 on error.  When an error has occurred, the global errno contains a value indicating the type of error that has been detected.

See Also

access, stat, ftest

string expandpath( string  path,   [int env] )

Expand the path.

Description

The expandpath() primitive expands any shell style home directory ~[user] references/short-hands contained within the specified path, returning the result.

The supported shell constructs are.

If env is specified and is non-zero, then the any embedded environment variable references are also expanded following the following syntax.  When a macro is not defined it expands to \”\” (an empty string), and {} are synonyms for ().

Returns

The expandpath() primitive returns a string containing the expanded path following the above rules, otherwise an empty string.

Portability

A GriefEdit extension.

See Also

strfilecmp, file_canon, file_glob, getenv, searchpath

int fclose( int  handle )

Close a stream.

Description

The fclose() primitive shall cause the stream pointed to by stream to be flushed and the associated file to be closed.  Any unwritten buffered data for the stream shall be written to the file; any unread buffered data shall be discarded.

Returns

On successful completion, fclose() shall return 0; otherwise, it shall return -1 and set errno to indicate the error.

Portability

A GriefEdit extension.

See Also

fopen, fread, fwrite

int feof( int  handle )

Test end-of-file indicator on a stream.

Description

The feof() primitive shall test the end-of-file indicator for the stream pointed to by stream.

Returns

The feof() primitive returns non-zero if and only if the end-of-file indicator is set for stream.

Portability

A GriefEdit extension.

Notes

The feof() primitive is reserved for future use, and currently returns -1 in all cases.

See Also

fopen, ferror

int ferror( int  handle,   [int clearerr] )

Test error indicator on a stream.

Description

The ferror() primitive shall test the error indicator for the stream referenced by handle.

Returns

The ferror() primitive shall return non-zero if and only if the error indicator is set for stream.

Portability

A GriefEdit extension.

Notes

The ferror() primitive is reserved for future use, and currently returns -1 in all cases.

See Also

fopen, feof

int fflush( int  handle,   [int sync] )

Flush a stream.

Description

The fflush() primitive is reserved for future use.

Returns

The fflush function returns non-zero if a write error occurs and zero otherwise.  When an error has occurred, errno contains a value indicating the type of error that has been detected

Portability

An experimental GriefEdit extension; functionality may change.

Notes

The fflush() primitive is reserved for future use, and currently returns -1 in all cases.

See Also

fopen

string file_canon( string  filepath )

Canonicalize a path.

Description

The file_canon() primitive performs canonicalizes the specified path filepath and returns a new path.

The new path differs from path in

• Slashes are normalised with \ replaced with ‘/’.
• Relative paths are prefixed with the current working directory.
• Multiple `/’s are collapsed to a single `/’.
• Leading `./’s and trailing `/.’s are removed.
• Trailing `/’s are removed.
• Non-leading `../’s and trailing `..’s are handled by removing portions of the path.

Returns

The file_canon() primitive returns the canonicalized file path.

Portability

A GriefEdit extension.

See Also

glob, file_pattern, find_file, expandpath

int file_match( pattern, file, [flags] )

File match utility.

Description

The file_match() primitive performs wild-card name matching, which has two major uses.  It could be used by an application or utility that needs to read a directory and apply a pattern against each entry.

The find_file() primitive is an example of this.  It can also be used by the ts macro to process its pattern operands, or by applications that need to match strings in a similar manner.

The file_match() primitive is intended to imply filename match, rather than pathname match.  The default action of this primitive is to match filenames, rather than path names, since it gives no special significance to the slash character.

pattern can be a list of search expressions or a string containing a single expression.  file is the file-name that shall be tested.

If supplied, flags allows control over how directory delimiters slash(/) and dots (.) are matched within file-name.  Otherwise it defaults to setting the MATCH_PERIODA and MATCH_NOCASE based on the current operating environment similar to ones used during edit_file() pattern matching.

Pattern

The following patterns matching a single character match a single character: ordinary characters, special pattern characters and pattern bracket expressions.  The pattern bracket expression will also match a single collating element.

An ordinary character is a pattern that matches itself.  It can be any character in the supported character set except for NUL, those special shell characters that require quoting, and the following three special pattern characters.

When unquoted and outside a bracket expression, the following three characters will have special meaning in the specification of patterns:

Patterns Matching Multiple Characters

The following rules are used to construct patterns matching multiple characters from patterns matching a single character:

• The asterisk (*) is a pattern that will match any string, including the null string.
• The concatenation of patterns matching a single character is a valid pattern that will match the concatenation of the single characters or collating elements matched by each of the concatenated patterns.
• The concatenation of one or more patterns matching a single character with one or more asterisks is a valid pattern.  In such patterns, each asterisk will match a string of zero or more characters, matching the greatest possible number of characters that still allows the remainder of the pattern to match the string.

Character Set Range Match

[ introduces a pattern bracket expression, that will matches a single collating element contained in the non-empty set of collating elements.  The following rules apply:

• A bracket expression is either a matching list expression or a non-matching list expression.  It consists of one or more expressions.
• A matching list expression specifies a list that matches any one of the expressions represented in the list.  The first character in the list must not be the circumflex (^).  For example, [abc] is a pattern that matches any of the characters a, b or c.
• A non-matching list expression begins with a circumflex (^), and specifies a list that matches any character or collating element except for the expressions represented in the list after the leading circumflex.  The circumflex will have this special meaning only when it occurs first in the list, immediately following the left-bracket.
• A range expression represents the set of collating elements that fall between two elements in the current collation sequence, inclusively.  It is expressed as the starting point and the ending point separated by a hyphen (-).  For example, [a-z] is a pattern that matches any of the characters a to z inclusive.
• A bracket expression followed by + means one or more times.

Character Classes

Within bracket expressions, the name of a character class enclosed in [: and :] stands for the list of all characters belonging to that class.

Standard (POSIX style) character classes are;

Flags

If supplied the flags argument shall modify the interpretation of pattern and string.  It is the bitwise-inclusive OR of zero or more of the flags defined in grief.h.

MATCH_PATHNAME - If the MATCH_PATHNAME flag is set in flags, then a slash character (‘/’) in string shall be explicitly matched by a slash in pattern; it shall not be matched by either the asterisk (*) or question-mark (?) special characters, nor by a bracket expression ([]).  If the MATCH_PATHNAME flag is not set, the slash character shall be treated as an ordinary character.

MATCH_NOCASE - If the MATCH_NOCASE flag is set in flags, then the pattern is treated non-case sensitively, i.e. A matches a.  Otherwise the search is performed with case being sensitive.

MATCH_NOESCAPE - If MATCH_NOESCAPE is not set in flags, a backslash character (\\) in pattern followed by any other character shall match that second character in string.  In particular, “\\” shall match a backslash in string.  If MATCH_NOESCAPE is set, a backslash character shall be treated as an ordinary character.

MATCH_PERIOD - If MATCH_PERIOD is set, a leading period in string will match a period in pattern; where the location of “leading” is indicated by the value of MATCH_PATHNAME as follows:

If not set, no special restrictions are placed on matching a period.

• is set, a period is “leading” if it is the first character in string or if it immediately follows a slash.
• is not set, a period is “leading” only if it is the first character of string.

MATCH_PERIODA, MATCH_PERIODQ and MATCH_PERIODB - If set these allow selective control whether the asterisk (*) or question mark (?) special characters, nor by a bracket ([]) expression have affect.

Examples

a[bc]

matches the strings ab and ac.

a*d

matches the strings ad, abd and abcd, but not the string abc.

a*d*

matches the strings ad, abcd, abcdef, aaaad and adddd.

*a*d

matches the strings ad, abcd, efabcd, aaaad and adddd.

Note

file_match() does not perform tilde expansion (See: expandpath).

Returns

The file_match() primitive returns 1 if file matches the specified pattern; returns 0 if pattern isnt matched.  If pattern is a list, then the index into the list that matched the expression or -1.

Portability

A GriefEdit extension.

See Also

file_pattern, filename_match

int file_pattern( string  filespec )

Directory file pattern.

Description

The file_pattern() primitive sets the search pattern for files, using find_file, and reset the internal status to the first matching file.

Parameters

Returns

The file_pattern() primitive returns 0 on success, otherwise -1 on error.  When an error has occurred, the global errno contains a value indicating the type of error that has been detected.

Notes

This interface enforces the rule (MATCH_PERIODA) that a leading “” wont match any files which begin with a “.” as such use “?” to match all files contained within a directory.  See file_match for details on the filespec syntax.

See Also

file_match, glob, expandpath

int filename_match( string  file, declare  pattern )

Perform file pattern matching.

Description

The filename_match() primitive is similar to the file_match() primitive but is provided for CRiSP ™ compatibility.  It is used to compare a filename to see if it matches a filename regular expression.

A filename expression is a regular expression similar to that accepted by the command line shells on Unix systems (e.g. you can use * for wildcard, ? for wild-character, and [..] to select a range of characters).

file is the filename that shall be tested.  pattern can be a list of search expressions or a string containing a single expression (See: file_match) for details on the expression syntax.

Returns

The filname_match() primitive return value is dependent on the pattern type.  If pattern is a string, then 1 if the filename matches; 0 otherwise.  If pattern is a list, then the index into the list that matched the expression or -1.

Portability

Functionality has not been formally verified against CRiSPEdit and whether it supports the [..]+ expression construct.

See Also

file_match, strfilecmp, file_glob

string filename_realpath( string  pathname )

Return a resolved pathname.

Description

The filename_realpath() primitive shall derive, from the pathname an absolute pathname that names the same file, whose resolution does not involve ., .., or symbolic links.

Returns

The file_realpath() primitive returns the resolved file if successful otherwise the original pathname.

See Also

realpath

int find_file( [string &filename], [int &size],   [int &mtime], [int &ctime], [int &mode] )

Read next directory entry.

Description

The find_file() primitive retrieves the next file which matches the current file pattern.  The active source directory and pattern are controlled using file_pattern.

Example

The following example retrieves are .txt files within the current working directory.

string name;
int size;

file_pattern("*.txt");
while (file_find(name)) {
    parsename(name, size);
}

This primitive is used in conjunction with file_pattern.

Parameters

For regular files, the file size in bytes.
For symbolic links, the length in bytes of the path-name contained in the symbolic link.
For a shared memory object, the length in bytes.
For a typed memory object, the length in bytes.
For other file types, the use of this field is unspecified.

Returns

Returns zero if there are no more files; returns 1 if next directory entry successfully received.

Portability

The mtime, ctime and mode parameters are GriefEdit extensions.

See Also

file_pattern, find_file2, file_glob, expandpath, stat, mode_string

int find_file2( string  filename,   [int &size],     [int &mtime],   [int &ctime],   [int &atime],   [int &mode],     [int &uid],   [string &uid2name],     [int &gid],   [string &gid2name],     [int &nlink],   [int &inode] )

Extended read next directory entry.

Description

The find_file2() primitive is an extended version of find_file returning additional file information on which matching file.

Parameters

For regular files, the file size in bytes.
For symbolic links, the length in bytes of the path-name contained in the symbolic link.
For a shared memory object, the length in bytes.
For a typed memory object, the length in bytes.
For other file types, the use of this field is unspecified.

Returns

Returns zero if there are no more files; returns 1 if next directory entry successfully received.

Portability

A GriefEdit extension.

See Also

file_pattern, find_file, file_glob, expandpath, stat, mode_string

string find_macro( string  filename )

Determine path of a macro object.

Description

The find_module resolves the full-path to the macro object filename.  Using the same mechanism as load_macro, the macro object search path environment variable GRPATH is utilised to search for the specified macro object.

Parameters

Returns

The find_module returns a string containing the full-path to the resolved macro object, otherwise an empty string if the object could not be found.

Portability

n/a

See Also

autoload, load_macro

int fioctl( int  handle,   .. )

File miscellaneous control.

Description

The fioctl() primitive is reserved for future use.

Returns

Returns -1.

Portability

An experimental GriefEdit extension; functionality may change.

See Also

fopen, flock

int flock( int  handle,   .. )

File lock operations.

Description

The flock() primitive is reserved for future use.

Returns

Returns -1.

Portability

A GriefEdit extension.

Notes

The flock() primitive is reserved for future use, and currently returns -1 in all cases.

See Also

fopen, fioctl

int fmktemp( string  template );

Make a unique filename.

Description

The fmktemp() primitive shall replace the contents of the string template by a unique filename, and return a stream for the file open for reading and writing.

The primitive is equivalent to the mkstemp().

The function thus prevents any possible race condition between testing whether the file exists and opening it for use.  The string in template should look like a filename with six trailing X s; fmktemp replaces each X with a character from the portable filename character set.

The characters are chosen such that the resulting name does not duplicate the name of an existing file at the time of a call to fmktemp.

Returns

Upon successful completion, fmktemp() shall return an open stream and return the resulting filename.  Otherwise, -1 shall be returned if no suitable file could be created.

Portability

A GriefEdit extension.

See Also

fopen, mktemp

int fopen( string  path, int|string  flags,     [int mode = 0644],   [int bufsiz] )

Open a stream.

Description

The fopen() primitive shall open the file whose pathname is the string path, and associates a stream with it.

The flags argument contains a string.  If the string is one of the following, the file shall be opened in the indicated mode.

Parameters

Returns

Upon successful completion, fopen() shall return a handle to the stream.  Otherwise, -1 shall be returned, and errno shall be set to indicate the error.

Portability

A GriefEdit extension.

See Also

fclose, fread, fwrite

int fread( int  handle, string  buffer,     [int bufsiz = BUFSIZ],   [int null = ' '] )

Read from a stream.

Description

The fread() primitive shall read into the array pointed to by ptr up to nitems elements whose size is specified by size in bytes, from the stream referenced by handle.

Parameters

Returns

Upon successful completion, fread() shall return the number of elements successfully read which is less than bufsiz only if a read error or end-of-file is encountered.

If nitems is 0, fread() shall return 0 and the contents of the array and the state of the stream remain unchanged.  Otherwise, if a read error occurs, the error indicator for the stream shall be set, and errno shall be set to indicate the error.

Portability

A GriefEdit extension.

See Also

fopen, fwrite

int fseek( int  handle, int  offset, int  whence )

Reposition a file-position indicator in a stream.

Description

The fseek() primitive shall set the file-position indicator for the stream pointed to by stream.  If a read or write error occurs, the error indicator for the stream shall be set and fseek() fails.

The argument offset is the position to seek to relative to one of three positions specified by the argument whence.

Parameters

Returns

On success the fseek() functions returns, otherwise -1 and set errno to indicate the error.

Portability

A GriefEdit extension.

See Also

ftell, fwrite, fread

int fstat( int  handle,   [int size],   [int mtime],   [int ctime],     [int atime],   [int mode],   [int uid],   [string uid2name],     [int gid],   [string gid2name],   [int nlink] )

Stream status information.

Description

The fstat() primitive obtain information about the file referenced by the handle handle.

This information is returned in the parameters following the handle parameter (if supported by the underlying filesystem)

Returns

The fstat function returns zero if successful, and a non-zero value (-1) otherwise.  When an error has occurred, errno contains a value indicating the type of error that has been detected.

Portability

A GriefEdit extension.

See Also

fopen, stat, lstat

int ftell( int  handle )

Report the file-position indicator of a stream.

Description

The ftell() primitive shall obtain the current value of the file-position indicator for the stream pointed to by stream.

Returns

On successful completion, ftell() shall return the current value of the file-position indicator for the stream measured in bytes from the beginning of the file.

Otherwise, ftell() shall return -1, and set errno to indicate the error.

Portability

A GriefEdit extension.

See Also

fseek, fwrite, fread

int ftest( int|string  condition, string  path )

Test file type.

Description

The ftest() primitive tests the type of the specified file path against the type condition.  The file test operations are modelled on standard unix test operators as follows.

Returns

The ftest() primitive returns the result of the test operation either 1 when true otherwise 0.

Portability

A GriefEdit extenions.

See Also

access, exist, stat, chmod, chown

int ftruncate( int  handle,   [int size] )

Truncate the specified file.

Description

The ftruncate() primitive cause the regular file referenced by handle to be truncated to a size of precisely length bytes.

If the file previously was larger than this size, the extra data is lost.  If the file previously was shorter, it is extended, and the extended part reads as null bytes (\0).

The file offset is not changed.

With ftruncate(), the file must be open for writing.

Returns

The ftruncate function returns zero on success.  When an error has occurred, errno contains a value indicating the type of error that has been detected

Portability

A GriefEdit extension.

Notes

The ftruncate() primitive is reserved for future use, and currently returns -1 in all cases.

See Also

fseek, ftell, fwrite

int fwrite( int  handle, string  buffer,   [int length] )

Write to a stream.

Description

The fwrite() primitive shall write, from the string buffer, up to length, to the stream pointed to by handle.  If omitted, length by default to the string current length.

The file-position indicator for the stream (if defined) shall be advanced by the number of bytes successfully written.  If an error occurs, the resulting value of the file-position indicator for the stream is unspecified.

Parameters

Returns

The fwrite() primitive shall return the number of elements successfully written, which may be less than length if a write error is encountered.

If length is 0, fwrite() shall return 0 and the state of the stream remains unchanged.  Otherwise, if a write error occurs, the error indicator for the stream shall be set, and errno shall be set to indicate the error.

Portability

A GriefEdit extension.

See Also

fopen, fclose

string glob( string  pattern )

Generate pathnames matching a pattern.

Description

The glob() primitive expands the specified pattern into single string similar to that which occurs on the shell command line.

Returns

The glob() primitive returns a string containing the result of the pattern expansion on success, otherwise an empty string.

Portability

A GriefEdit extension.

See Also

file_glob, file_pattern, find_file, expandpath

int inq_buffer( [string filename] )

Retrieve a buffer identifier.

Description

The inq_buffer() primitive retrieves either the identifier associated with the buffer containing the specified file filename, otherwise if omitted the identifier of the current buffer.

Parameters

Returns

The inq_buffer() primitive returns the unique identifier associated with the referenced file or the current buffer if no file_name was specified.  If the specified file_name was not matched, zero is returned.

If omitted then the current buffer is returned.

Portability

Unlike BRIEF partial matches do not occur.

See Also

attach_buffer, create_buffer, delete_buffer, next_buffer, set_buffer

string inq_file_magic( [int &isdefault] )

Retrieve the file type detection rules.

Description

The inq_file_magic primitive retrieves the current file character encoding detection rules.  The returned shall contain one or comma separated detector names with optional arguments, see set_file_magic.

Example

mark,utf8,udet,xascii,ascii

Parameters

n/a

Returns

The inq_file_magic() primitive returns a string containing the current encoder specification.

Portability

A GriefEdit extension.

See Also

edit_file, set_file_magic

string inq_home()

Retrieve the user home directory.

Description

The inq_home() primitive retrieves the current users home directory.

Parameters

none

Returns

The inq_home() primitive returns a string containing the users home directory.

Portability

A GriefEdit extension.

See Also

inq_username, getenv

string inq_tmpdir()

Get the temporary-file directory.

Description

The inq_tmpdir() primitive retrieves the temporary file directory.  The directory is determined by the current environment, which is host specific, for example on UNIX systems the default value of this property is typically “/tmp” or “/var/tmp”; on Microsoft Windows systems it is typically “c:\temp”.

Windows

On XP and greater the system folder local application data directory is queried.

If this fails, the function checks for the existence of environment variables in the following order and uses the first path found:

• The path specified by the TMP environment variable.
• The path specified by the TEMP environment variable.
• The path specified by the USERPROFILE environment variable.
• The Windows directory.

UNIX like Systems

TMPDIR is the canonical Unix environment variable that should be used to specify a temporary directory for scratch space.

Other forms accepted are TEMP, TEMPDIR and TMP, but these alternatives are used more commonly by non-POSIX operating systems or non-conformant programs.

Parameters

none

Returns

The inq_tmpdir() primitive returns a string containing the temporary file directory.

Portability

A GriefEdit extension.

See Also

getenv

list inq_vfs_mounts()

Retrieve list of mounts.

Description

The inq_vfs_mounts() primitive retrieves a list of three elements describing each of the current mounted virtual file-systems.

Parameters

none

Returns

Returns a list of mount points, each mount description contains the following elements.

Portability

A GriefEdit extension.

See Also

vfs_mount, vfs_unmount

int link( string  path1, string  path2 )

Link a file.

Description

The link() primitive is reserved for future use.

The link() primitive shall create a new link (directory entry) for the existing file, path1.

The path1 argument points to a pathname naming an existing file.  The path2 argument points to a pathname naming the new directory entry to be created.  The link() primitive shall atomically create a new link for the existing file and the link count of the file shall be incremented by one.

If path1 names a directory, link() shall fail unless the process has appropriate privileges and the implementation supports using link() on directories.

If path1 names a symbolic link, it is implementation-defined whether link() follows the symbolic link, or creates a new link to the symbolic link itself.

If link() fails, no link shall be created and the link count of the file shall remain unchanged.

Returns

Upon successful completion, link shall return 0; otherwise, it shall return -1 and set the global errno to indicate the error.

Portability

A GriefEdit extension.

See Also

symlink, unlink, stat, remove

int lstat( string  path,   [int size],     [int mtime],   [int ctime],   [int atime],   [int mode],     [int uid],   [string uid2name],     [int gid],   [string gid2name],     [int nlink],   [int inode] )

Get symbolic link status.

Description

The lstat() primitive shall be equivalent to stat, except when path refers to a symbolic link.  In that case lstat shall return information about the link, while stat shall return information about the file the link references.

For symbolic links, the mode member shall contain meaningful information when used with the file type macros, and the size member shall contain the length of the pathname contained in the symbolic link.  File mode bits and the contents of the remaining members of the stat structure are unspecified.  The value returned in the size member is the length of the contents of the symbolic link, and does not count any trailing null.

Parameters

For regular files, the file size in bytes.
For symbolic links, the length in bytes of the path-name contained in the symbolic link.
For a shared memory object, the length in bytes.
For a typed memory object, the length in bytes.
For other file types, the use of this field is unspecified.

Returns

The lstat() primitive returns zero if successful, and a non-zero value (-1) otherwise.  When an error has occurred, the global errno contains a value indicating the type of error that has been detected.

Portability

A GriefEdit extension.

See Also

stat

int mkdir( string  pathname,    int  mode  =  0755 )

Create a directory.

Description

The mkdir() primitive creates a new subdirectory with name path.  The path can be either relative to the current working directory or it can be an absolute path name.

mode is the protection codes used to create the directory.  If omitted, the value 0755 (-rwxr-xr-x) will be used.

Returns

The mkdir() primitive returns zero if successful, and a non-zero value (-1) otherwise.  When an error has occurred, the global errno contains a value indicating the type of error that has been detected.

See Also

rmdir, cd, getwd

string mktemp( string  path )

Make a temporary filename.

Description

The mktemp() primitive shall replace the contents of the string path to by template by a unique filename and return template.

The application shall initialize template to be a filename with six trailing ‘X’s. mktemp() shall replace each X with a single byte character from the portable filename character set.

Returns

The mktemp() primitive shall return the string template.  If a unique name cannot be created, template shall point to an empty string.

See Also

fmktemp, create_buffer

int output_file( [string filename] )

Change the output file-name.

Description

The output_file() primitive changes the file-name associated with the current buffer to filename; the new name should be unique, it cannot be the file-name of an exist buffer or file.

By default the associated file-name associated with a buffer is the file-name specified on an edit_file or create_buffer.

If filename is omitted the user shall be prompted as follows;

Enter new output file name:

Parameters

Returns

The output_file() primitive returns greater than zero on success, otherwise zero or less on error.

The following error conditions shall be reported to the user;

• filename must be a unique buffer.

Duplicate buffer name 'xxx'.

• Unless a system buffer stated filename must not already exist on the file-system.

Output file 'xxx' already exists.

Portability

n/a

See Also

edit_file, create_buffer

int read_ea( string  filename,   ... )

Read file extended information.

Description

The read_ea() primitive is reserved for future BRIEF compatibility.

Parameters

n/a

Returns

n/a

Portability

Provided for BRIEF compatibility.

See Also

copy_ea_info, set_ea

int read_file( [string filename],   [int glob = TRUE], [string encoding = NULL] )

Read into the current buffer.

Description

The read_file() primitive reads the content of the specified file filename into the current buffer.

If filename is omitted the user shall be prompted as follows;

File to read:

Parameters

Returns

The read_file() primitive returns a positive value on success, 0 if the user was prompted and canceled, otherwise -1 on error.

Portability

n/a

See Also

create_buffer, edit_file

string|int readlink( string  path,   [string &link] )

Read the contents of a symbolic link.

Description

The readlink() primitive shall place the contents of the symbolic link referred to by path in the string link.

Returns

If link is omitted the return value is a string.  Upon successful completion readlink() shall return the resolved link, otherwise it shall return an empty string and set the global errno to indicate the error.

Then link is given the return value is an int.  Upon successful completion, readlink shall return the count of character placed in the string.  Otherwise, it shall return a value of -1, and set the global errno to indicate the error.

Portability

A GriefEdit extension.

See Also

lstat, realpath, symlink

int realpath( string  pathname, string  resolved_path )

Resolve a pathname.

Description

The realpath() primitive shall derive, from the pathname an absolute pathname that names the same file, whose resolution does not involve ., .., or symbolic links.

Returns

The realpath() primitive returns 0 if successful otherwise -1 on error.  When an error has occurred, the global errno contains a value indicating the type of error that has been detected.

Portability

A GriefEdit extension.

See Also

getwd, symlink

int remove( string  filename )

Remove a file.

Description

The remove() primitive deletes the file whose name is contained within the string filename.

Returns

The remove() primitive returns zero if successful, and a non-zero value (-1)f otherwise.  When an error has occurred, the global errno contains a value indicating the type of error that has been detected.

See Also

exist, access

int rename( string  old, string  new )

Rename a file.

Description

The rename() primitive causes the file whose name is indicated by the string old to be renamed to the name given by the string new.

Returns

The rename() primitive returns zero if successful, and a non-zero value (-1) otherwise.  When an error has occurred, the global errno contains a value indicating the type of error that has been detected.

See Also

remove, create_buffer, link, unlink

int rmdir( string  path )

Remove directory.

Description

The rmdir() primitive removes (deletes) the specified directory.  The directory must not contain any files or directories.  The path can be either relative to the current working directory or it can be an absolute path name.

Returns

The rmdir() primitive returns zero if successful, and a non-zero value (-1) otherwise.  When an error has occurred, the global errno contains a value indicating the type of error that has been detected.

See Also

mkdir, chdir, cd, getwd

int searchpath(   [string path], string  filename,     [string extension], string  & result,   [int mode],   [int expand = FALSE] )

Searches for a given file in a specified path.

Description

The searchpath() primitives searches the directory path path for a instance of the file name file.  path is a list of delimiter separated directory names, with the same syntax as the shell variable GRPATH.

Parameters

Returns

The expandsearch() primitive returns the length of the string that is copied to the buffer result; otherwise on failure returns a value of zero.

Portability

A GriefEdit extension.

See Also

expandpath

int set_binary_size( [int size] )

Set binary chunk size.

Description

The set_binary_size() primitive sets the chunk or block size utilised when loading binary file images.  Each chunk shall be represented within the buffer as a single line.

Note:!  If the specified value is equal or less-then zero (<= 0), then files shall never be interpreted as binary when read; instead the default system specific type as be applied.

Parameters

Returns

The set_binary_size() primitive returns the previous chunk size.

Portability

n/a

See Also

inq_terminator

int set_ea( string  filename,   ... )

Set file extended information.

Description

The set_ea() primitive is reserved for future BRIEF compatibility.

Parameters

n/a

Returns

n/a

Portability

Provided for BRIEF compatibility.

See Also

read_ea, copy_ea_info

int set_file_magic( [string encoding], [int cost] )

Define the file type detection rules.

Description

The set_file_magic primitive configures the global file character encoding detection logic.

Parameters

Detection Types

The order below is somewhat important as the MBCS checks can result in false positives, as such are generally last in line.

Without going into the full details of each search algorithms, several are summarised below.

mark

Markup languages have ways of specifying the encoding in a signature near the top of the file.

The following appears inside the <head> area of an HTML page.

<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

In XML, the XML declaration specifies the encoding.

<?xml version="1.0" encoding="iso-8859-1"?>

Recognised formats are.

utf32bom, utf16bom

BOM stands for Byte Order Mark which literally is meant to distinguish between little-endian LE and big-endian BE byte order.  For UTF-32 and UTF-16 the code point U+FEFF (“zero width no-break space”) are used.

UTF-32 Big Endian         0X00,0X00,0XFE,0XFF
UTF-32 Little Endian      0XFF,0XFE,0X00,0X00

UTF-16 Big Endian         0XFE,0XFF
UTF-16 Little Endian      0XFF,0XFE

uft8

UTF-8 auto-detection (when there is no UTF-8 BOM), performs UTF-8 decoding on the file looking for an invalid UTF-8 sequence; correct UTF-8 sequences look like this:

0xxxxxxx                              ASCII < 0x80 (128)
110xxxxx 10xxxxxx                     2-byte >= 0x80
1110xxxx 10xxxxxx 10xxxxxx            3-byte >= 0x400
11110xxx 10xxxxxx 10xxxxxx 10xxxxxx   4-byte >= 0x10000

bom

BOM stands for Byte Order Mark which literally is meant to distinguish between little-endian LE and big-endian BE byte order.

For Unicode files, the BOM (“Byte Order Mark” also called the signature or preamble) is a set of leading bytes at the beginning used to indicate the type of Unicode encoding.

The key to the BOM is that it is generally not included with the content of the file when the file’s text is loaded into memory, but it may be used to affect how the file is loaded into memory.

Recognised sequences include;

UTF-32 Big Endian         0X00,0X00,0XFE,0XFF
UTF-32 Little Endian      0XFF,0XFE,0X00,0X00

UTF-16 Big Endian         0XFE,0XFF
UTF-16 Little Endian      0XFF,0XFE

UTF-7                     0X2B,0X2F,0X76,0X38
UTF-7                     0X2B,0X2F,0X76,0X39
UTF-7                     0X2B,0X2F,0X76,0X2B
UTF-7                     0X2B,0X2F,0X76,0X2F

UTF-EBCDIC                0XDD,0X73,0X66,0X73
GB18030                   0X84,0X31,0X95,0X33
BOCU-1                    0XFB,0XEE,0X28,0xFF
BOCU-1                    0XFB,0XEE,0X28
SCSU                      0X0E,0XFE,0XFF
UTF-1                     0XF7,0X64,0X4C
UTF-8                     0XEF,0XBB,0XBF

udet

Mozilla Universal Character Detector employs a composite approach that utilizes Code Scheme, Character Distribution and 2-Char Sequence Distribution methods to identify language/encodings has been proven to be very effective and efficient in our environment; see libcharudet.

http://www-archive.mozilla.org- /projects- /intl- /UniversalCharsetDetection.html

big5

Performs Big5 decoding on the file looking for an invalid sequences.

Big5 does not conform to the ISO-2022 standard, but rather bears a certain similarity to Shift-JIS.

It is a double-byte character set with the following structure.

First Byte:         0xA1 - 0xf9 (non-user-defined characters)
                or  0x81 - 0xfe (extended range)
Second Byte:        0x40 - 0x7e or 0xa1 - 0xfe

gb18030

Performs GB18030 decoding on the file looking for an invalid sequences.

GB18030-2000 has the following significant properties;

• It incorporates Unicode’s CJK Unified Ideographs Extension A completely.
• It provides code space for all used and unused code points of Unicode’s plane 0 (BMP) and its 15 additional planes.  While being a code- and character-compatible “superset” of GBK, GB18030-2000, at the same time, intends to provide space for all remaining code points of Unicode.  Thus, it effectively creates a one-to-one relationship between parts of GB18030-2000 and Unicode’s complete encoding space.
• In order to accomplish the Unihan incorporation and code space allocation for Unicode 3.0, GB18030-2000 defines and applies a four-byte encoding mechanism.

GB18030-2000 encodes characters in sequences of one, two, or four bytes.  The following are valid byte sequences (byte values are hexadecimal):

Single-byte: 0x00-0x7f
Two-byte:    0x81-0xfe + 0x40-0x7e, 0x80-0xfe
Four-byte:   0x81-0xfe + 0x30-0x39 + 0x81-0xfe + 0x30-0x39

The single-byte portion applies the coding structure and principles of the standard GB 11383 (identical to ISO 4873:1986) by using the code points 0x00 through 0x7f.

The two-byte portion uses two eight-bit binary sequences to express a character.  The code points of the first (leading) byte range from 0x81 through 0xfe.  The code points of the second (trailing) byte ranges from 0x40 through 0x7e and 0x80 through 0xfe.

The four-byte portion uses the code points 0x30 through 0x39, which are vacant in GB 11383, as an additional means to extend the two-byte encodings, thus effectively increasing the number of four-byte codes to now include code points ranging from 0x81308130 through 0xfe39fe39.

GB18030-2000 has 1.6 million valid byte sequences, but there are only 1.1 million code points in Unicode, so there are about 500, 000 byte sequences in GB18030-2000 that are currently unassigned.

shiftjis

Performs Shift-JIS decoding on the file looking for an invalid sequences.

• Single Byte

ASCII:                  0x21 - 0x7F (also allow control)
Katakana:               0xA1 - 0xDF

• Multiple Byte

JIS X 0208 character
First byte:             0x81 - 0x9F or 0xE0 - 0xEF
Second byte (old 1st):  0x40 - 0x9E
Second byte (even 1st): 0xA0 - 0xFD

guess

libguess employs discrete-finite automata to deduce the character set of the input buffer.  The advantage of this is that all character sets can be checked in parallel, and quickly.  Right now, libguess passes a byte to each DFA on the same pass, meaning that the winning character set can be deduced as efficiently as possible; see libguess.

Returns

The set_file_magic() primitive returns a positive value on success, otherwise -1 on error.

Portability

A GriefEdit extension.

See Also

edit_file, inq_file_magic

int splithpath( string  path,     [string &dir],   [string &name],   [string &ext],   [string &drive] )

Searches for a given file in a specified path.

Description

The splitpath() primitive break a path into components.

Parameters

Returns

The splitpath() primitive returns pothing.

Portability

A GriefEdit extension.

See Also

expandpath

int stat( [string path], [int size],   [int mtime], [int ctime],   [int atime], [int mode], [int uid], [string uid2name],   [int gid], [string gid2name],   [int nlink], [int inode] )

Obtain file information.

Description

The stat() primitive obtain information about the file or directory referenced in path.

This information is returned in the parameters following the path parameter (if supported by the underlying filesystem).

• size - Total file size, in bytes.
• mode - File mode ((see File Modes )).
• mtime - The files “last modified” time (See: time).
• atime - Time the file was “last accessed”.
• ctime - Time of the files “last status change”.
• uid - User identifier.
• uid2name - User name associated with the file uid.
• gid - Group identifier.
• gid2name - Group name associated with the file gid.
• nlink - Number of hard links.
• inode - File-system internal node number.

Parameters

For regular files, the file size in bytes.

• For symbolic links, the length in bytes of the path-name contained in the symbolic link.
For a shared memory object, the length in bytes.
For a typed memory object, the length in bytes.
For other file types, the use of this field is unspecified.

Returns

The stat() primitive returns zero if successful, and a non-zero value (-1) otherwise.  When an error has occurred, the global errno contains a value indicating the type of error that has been detected.

Portability

n/a

See Also

lstat, access, exist, ftest

int symlink( string  path1, string  path2 )

Create a symbolic link.

Description

The symlink() primitive shall create a symbolic link called path2 that contains the string path1.

In other words, path2 is the name of the symbolic link created, path1 is the string contained in the symbolic link.

If the symlink() primitive fails for any reason other than any file named by path2 shall be unaffected.

Returns

Upon successful completion, symlink() shall return 0; otherwise, it shall return -1 and set the global errno to indicate the error.

Portability

A GriefEdit extension.

See Also

lstat, readlink

int umask( int  cmask  =  NULL )

Set and get the file mode creation mask.

Description

The umask() primitive shall set the processes file mode creation mask to cmask and return the previous value of the mask.

Only the file permission bits of cmask are used; the meaning of the other bits is implementation-defined.

The process’ file mode creation mask is used to turn off permission bits in the mode argument supplied during calls to the following functions:

• fopen
• create_buffer
• mkdir

Returns

The file permission bits in the value returned by umask() shall be the previous value of the file mode creation mask.

See Also

chmod, stat, lstat

int unlink( string  path )

Unlink a file.

Description

The unlink() primitive is reserved for future use.

The unlink() primitive shall remove a link to a file.  If path names a symbolic link, unlink() shall remove the symbolic link named by path and shall not affect any file or directory named by the contents of the symbolic link.  Otherwise, unlink() shall remove the link named by the pathname pointed to by path and shall decrement the link count of the file referenced by the link.

When the file’s link count becomes 0 and no process has the file open, the space occupied by the file shall be freed and the file shall no longer be accessible.  If one or more processes have the file open when the last link is removed, the link shall be removed before unlink() returns, but the removal of the file contents shall be postponed until all references to the file are closed.

The path argument shall not name a directory unless the process has appropriate privileges and the implementation supports using unlink() on directories.

Returns

Upon successful completion, link shall return 0; otherwise, it shall return -1 and set the global errno to indicate the error.

Portability

A GriefEdit extension.

See Also

link, symlink, stat, remove

int vfs_mount(   string  mountpoint,    int  flags  =  0, string  vfsname,        [string arguments]    )

Mount a virtual file-system.

Description

The vfs_mount() primitive mounts a virtual file-system.

Parameters

Returns

The vfs_mount() primitive returns 0 on success, otherwise -1 on error and errno contains a value indicating the type of error that has been detected.

Portability

A GriefEdit extension.

See Also

vfs_unmount, inq_vfs_mounts

int vfs_unmount( string  mountpoint,    int  flags  =  0 )

Unmount a virtual file-system.

Description

The vfs_unmount() primitive unmounts the specified virtual file-system referenced by mountpoint.

Parameters

Returns

The vfs_unmount() primitive returns 0 on success, otherwise -1 on error and errno contains a value indicating the type of error that has been detected.

Portability

A GriefEdit extension.

See Also

vfs_mount, inq_vfs_mounts