.\" 
.\" Copyright 2003 Michael B. Allen <mba2000 ioplex.com>
.\" 
.TH path 3m "Apr 29, 2005" "libmba-0.9.1" "MBA Library Functions"
.SH NAME
path \- manipulate file path names
.SH SYNOPSIS
.nf
.B #include <mba/path.h>
.sp
.BI "int path_canon(const unsigned char *" src ",
.BI "            const unsigned char *" slim ",
.BI "            unsigned char *" dst ",
.BI "            unsigned char *" dlim ",
.BI "            int " srcsep ",
.BI "            int " dstsep ");
.br

.fi
.SH DESCRIPTION
The
.BR "path" (3m)
module provides functions for some common path manipulations.
.PP
.TP
.B canon
The
.I path_canon
function canonicalizes the path at
.I src
up to but not including the memory at
.I slim
into the memory at
.I dst
up to but not including
.IR "dlim" .
The character that separates path components in the
.I src
path is specified with the
.I srcsep
parameter whereas
.I dstsep
specifies the separator with which the
.I dst
path is constructed.
.sp
Specifically, canonicalization will eliminate '.' and '..' components in paths in the conventional way as well as normalize redundant separators. The presence or lack of an initial and/or trailing separator is preserved. The following lists some examples of paths before and after canonicalization:
.PP
.RS
.nf
.ta 4n 19n 31n

before      after
.
..
/           /
/.          /
./
../
.../        .../
a/..        
abc/../
a/b/c       a/b/c
/a/b/c      /a/b/c 
/./a/b/c    /a/b/c
/../a/b/c   /a/b/c
..a/b/c     ..a/b/c
a/b/c/      a/b/c/
a/b/c/..    a/b/
a/b/c/../   a/b/
a/b/c/./    a/b/c/

.ta
.fi
.RE
.PP

.SH RETURNS
.TP
.B canon
The
.I path_canon
function returns the number of bytes written to
.I dst
not including the zero terminator or -1 if
.I slim
or
.I dlim
has been reached in which case
.B errno
is set to
.BR "ERANGE" .