.help zfsubd May84 "System Interface"
.ih
NAME
zfsubd -- get host name of a subdirectory
.ih
SYNOPSIS
.nf
zfsubd (osdir, subdir, new_osdir, maxch, nchars)

char	osdir[ARB]		# directory pathname
char	subdir[ARB]		# subdirectory of osdir
char	new_osdir[maxch]	# pathname of osdir/subdir
int	maxch			# maximum length of new_osdir
int	nchars			# length of new_osdir
.fi
.ih
DESCRIPTION
Given \fIosdir\fR, the machine dependent name of a host directory,
and \fIsubdir\fR, the filename of a subdirectory of \fIosdir\fR, \fBzfsubd\fR
returns the machine dependent name of the subdirectory.
The machine dependent directory specification \fInew_osdir\fR may be
concatenated with a filename to produce an OSFN, or may be used in another
call to \fBzfsubd\fR to generate the name of a directory lower in the hierarchy.

If \fIosdir\fR is null the current working directory is assumed.
If \fIsubdir\fR is null or has the value "." \fIosdir\fR is either copied to
the output or modified as necessary to return a concatenatable directory
prefix string.  If \fIsubdir\fR has the value ".." the name of the next
\fIhigher\fR directory is returned, i.e., the directory in which \fIosdir\fR
appears as a subdirectory.
.ih
RETURN VALUE
ERR is returned if the translation cannot be performed (but the existence of
the new directory is not checked).  If the translation is successful the number
of characters in the string \fInew_osdir\fR is returned, excluding the EOS
delimiter.
.ih
NOTES
This primitive is used by FIO to convert subdirectory references in virtual
filenames into machine dependent directory specifications.
An arbitrary virtual pathname is translated by repeatedly calling \fBzfsubd\fR
to add successive / delimited subdirectory names into the OS directory name.
The new OS directory name is not necessarily an absolute pathname; on some
systems it may be a pathname relative to the current directory.  If an absolute
pathname is desired an additional call should be made to \fBzfpath\fR to
convert \fInew_osdir\fR into an absolute pathname.
This primitive is normally coded in SPP hence all strings are normal SPP
character strings rather than packed Fortran strings.
.ih
EXAMPLE
Consider the following VFN:

	pkg$images/imdelete.x

The logical directory "pkg" is defined in the environment as "iraf$pkg/".
Assume the host system is VMS and "iraf", the root directory of the IRAF
system, is defined as "dra0:[iraf]".  Recursive expansion of logical
directories will result in the following virtual pathname:

	dra0:[iraf]pkg/images/imdelete.x

FIO will next call \fBzfxdir\fR to extract the OSDIR "dra0:[iraf]",
followed by \fBzfsubd\fR to combine this OSDIR and the subdirectory
name "pkg" to produce the new OSDIR "dra0:[iraf.pkg]".  The process is
repeated until the final OSFN is generated:

	dra0:[iraf.pkg.images]imdelete.x
.ih
BUGS
We assume that an OSFN can be generated by a simple concatenation of an OS
directory specification and a filename.  This assumption is valid on all
systems we are familiar with, but may be false on some unfamiliar host.
.ih
SEE ALSO
zfxdir, zfpath
.endhelp