.ig
 Copyright (C) 1993,1994 by the author(s).
 
 This software is published in the hope that it will be useful, but
 WITHOUT ANY WARRANTY for any part of this software to work correctly
 or as described in the manuals. See the ShapeTools Public License
 for details.

 Permission is granted to use, copy, modify, or distribute any part of
 this software but only under the conditions described in the ShapeTools 
 Public License. A copy of this license is supposed to have been given
 to you along with ShapeTools in a file named LICENSE. Among other
 things, this copyright notice and the Public License must be
 preserved on all copies.


Author: Juergen Nickelsen (Juergen.Nickelsen@cs.tu-berlin.de)

$Header: atread.3[7.0] Fri Jun 25 16:39:47 1993 andy@cs.tu-berlin.de frozen $
..
.TH atReadExpand 3 "Tue Feb 16 20:33:25 1993" "AtFStk-1.12" "AtFS Toolkit Library"
.SH NAME
atOpenExpand, atReadExpand, atCloseExpand \- read version objects with
attribute citations expanded
.br
atGetWriteName \- get bound version name of a version object opened with
atOpenExpand
.SH SYNOPSIS
#include <atfs.h>
.br
#include <atfstk.h>
.sp
int   atOpenExpand(char *version, int expand_busy) ;
.sp
int   atReadExpand(int desc, char *bufp, int nbytes) ;
.sp
void  atCloseExpand(int desc) ;
.sp
char *atGetWriteName(int desc) ;
.sp
extern int  atBindError ;
.br
extern char atBindErrorMsg[] ;
.SH DESCRIPTION
.IR atOpenExpand ,
.IR atReadExpand ,
and
.I atCloseExpand
are designed as a nearly plug-compatible replacement for the system
calls
.IR open (2),
.IR read (2),
and
.IR close (2)
for reading of AtFS version objects with attribute citations expanded.
.LP
.I atOpenExpand
opens the file or AtFS version object
.I version
for reading with
.IR atReadExpand .
.I Version
points to the pathname of a file or AtFS version object.
If the flag
.I expand_busy
is non-zero, attribute citations are expanded in busy versions also.
.I atOpenExpand
returns a descriptor that is valid as argument to successive calls to 
.I atReadExpand
and
.IR atCloseExpand .
.LP
.I atReadExpand
attempts to read
.I nbytes
of data
from the object referenced by the descriptor
.I desc
into the buffer pointed to by
.IR bufp .
If 
.I desc
is zero, 
.I atReadExpand
reads from the standard input.
.I atReadExpand
returns the number of bytes actually read.
.LP
.I atCloseExpand
frees the resources associated with the descriptor
.IR desc .
.LP
.I atGetWriteName
returns a pointer to the bound version name of the version object for
which
.I atOpenExpand
returned the descriptor
.IR desc .
.SH DIAGNOSTICS
On error 
.I atOpenExpand
and
.I atReadExpand
return \-1 and set
.I errno
appropriately.
If one of these returns an error and 
.I errno 
is set to ENOMEM, the application may retry the operation, possibly
after freeing some memory.
.LP
If 
.I atOpenExpand
returns an error and
.I atBindError
has a non-zero value, the string
.I version
did not select a version object or not a unique version object.
In this case 
.I atBindErrorMsg
contains an appropriate error message.
.LP
Possible Values of errno after a call to
.IR atOpenExpand :
.in
.TP
ENOMEM
Not enough memory could be allocated.
.TP
EMFILE
All available descriptors are in use.
.LP
All errno values returned by 
.IR open (2)
or
.IR read (2).
.LP
Possible Values of errno after a call to
.IR atReadExpand :
.TP
ENOMEM
Not enough memory could be allocated.
.TP
EBADF
Invalid descriptor.
.SH BUGS
Since 
.I atOpenExpand
reads the complete contents of
.I version
into memory, it fails on very large version objects.
.SH SEE ALSO
intro(2), open(2), read(2), close(2), errno(3), atattribute(3),
atbind(3).