From: "Mark E." <snowball3 AT softhome DOT net>
To: djgpp-workers AT delorie DOT com
Date: Wed, 25 Sep 2002 18:49:11 -0400
MIME-Version: 1.0
Subject: realpath doc
Message-ID: <3D920527.5023.3301B@localhost>
X-mailer: Pegasus Mail for Windows (v4.02a)
Content-type: text/plain; charset=US-ASCII
Content-transfer-encoding: 7BIT
Content-description: Mail message body
Reply-To: djgpp-workers AT delorie DOT com

The realpath doc. Taken from fixpath and tweaked.

@node realpath, file system
@subheading Syntax

@example
#include <stdlib.h>

void realpath(const char *in_path, char *out_path);
@end example

@subheading Description

This function canonicalizes the input path @var{in_path} and stores the
result in the buffer pointed to by @var{out_path}.

The path is canonicialized by removing consecutive and trailing slashes,
making the path absolute if it's relative by prepending the current drive
letter and working directory, removing "." components, collapsing
".." components, adding a drive specifier if needed, and converting all
slashes to '/'.  DOS-style 8+3 names of directories which are part of
the pathname, as well as its final filename part, are returned
lower-cased in @var{out_path}, but long filenames are left intact.
@xref{_preserve_fncase}, for more details on letter-case conversions in
filenames.

Since the returned path name can be longer than the original one, the
caller should ensure there is enough space in the buffer pointed to by
@var{out_path}.  Using ANSI-standard constant @code{FILENAME_MAX}
(defined on @file{stdio.h}) or Posix-standard constant @code{PATH_MAX}
(defined on @file{limits.h}) is recommended.

@subheading Return Value

If successful, a pointer to the result buffer is returned. Otherwise,
@code{NULL} is returned and @var{errno} is set to indicate which error
was detected.

@subheading Portability

@portability !ansi, posix

@subheading Example

@example
char oldpath[100], newpath[PATH_MAX];
scanf("%s", oldpath);
realpath(oldpath, newpath);
printf("that really is %s\n", newpath);
@end example