---
name: "VistaIOReadFile"
section: "3"
platform: "linux"
package: "libvistaio-dev"
version: "1.2.19-3+b2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/VistaIOReadFile"
---

# VistaIOReadFile(3)

read a Vista data file

## NAME

VistaIOReadFile - read a Vista data file

## SYNOPSIS

```
#include <stdio>
#include <vistaio.h>
```

**VistaIOAttrList VistaIOReadFile (***file***,** *filter***)**

**FILE \****file***;** **VistaIOReadFileFilterProc \****filter***;**

**typedef VistaIOBoolean VistaIOReadFileFilterProc (VistaIOBundle, VistaIORepnKind);**

## ARGUMENTS

- *file*

  **Specifies the open stream from which the data file should be read.**

- *filter*

  **May specify a function that determines which attributes' binary data is** **read from the file, or it may be**  **NULL** **to indicate that all binary data should be read.**

## DESCRIPTION

**VistaIOReadFile reads the contents of a Vista data file. It returns a list of the attributes**  **found in the file. Attribute values in that list will have been converted**  **to internal form, as described by [VistaIOattribute(3)](/VistaIOattribute/3.md) and**  **[VistaIOtype(3)](/VistaIOtype/3.md).**

**With the** *filter* **argument you may supply a function that gets to**  **decide for each attribute value that is an object whether or not that**  **object's binary data should be read. This mechanism allows you to avoid the**  **expense of reading binary data that is not of interest (e.g., image pixel**  **values when images are not of concern). However, you need only supply a**  **filter function if you are particularly concerned about efficiency.**  **Your filter function should be declared:**

```
VistaIOBoolean MyFilter (bundle, repn)
VistaIOBundle bundle;
VistaIORepnKind repn;
```

**Your filter function will be called once for each object encountered at any** **level in the file. It will be passed a VistaIOBundle representing the** **object (including its type name and attribute list, but not its binary** **data), and the** *repn* **value obtained by looking up its type name (i.e.,** **the value returned by VistaIOLookupType(3) on the type name, which could** **be VistaIOUnknownRepn). The object's binary data will be read only if the** **filter function returns** **TRUE** **. If it returns**  **FALSE** **, the object will be represented in the attribute list as a VistaIOBundle,**  **without binary data — it will not be converted to internal form (e.g.,**  **not to a VistaIOImage). If no filter function is supplied (i.e.,**  *filter* **is**  **NULL** **), VistaIOReadFile will read all binary data associated with all objects.**

**For backwards compatibility VistaIOReadFile will recognize and read the**  **contents of a UBC image file format (IFF) file. If the first character read**  **from the stream is \`\`I'', VistaIOReadFile uses VistaIOReadUbcIff to read a**  **single UBC IFF image. The image is returned as a VistaIOImage attribute**  **value in a list containing a single attribute. In this case, the**  *filter* **argument has no effect.**

## RETURN VALUE

**VistaIOReadData returns an attribute list representing the file's contents, or** **NULL** **if an error is encountered. In the case of an error, the stream may** **not have been completely read.**

## SEE ALSO

[**VistaIOReadObjects**(3)](/VistaIOReadObjects/3.md), **VistaIOReadUbcIff**(3), [**stdio**(3)](/stdio/3.md),\
 [**VistaIOBundle**(3)](/VistaIOBundle/3.md), [**VistaIOattribute**(3)](/VistaIOattribute/3.md), [**VistaIOtype**(3)](/VistaIOtype/3.md)

## NOTES

**Data is read from the stream sequentially, permitting the stream to be** **a pipe. No rewind is performed either before reading or after.**

## DIAGNOSTIC

- \`\`EOF encountered in *name* attribute.''

  **The end-of-file was encountered unexpectedly while reading the value of**  **the named attribute.**

- \`\`File continues beyond expected EOF.''

  **The end-of-file wasn't encountered immediately after all expected binary**  **data.**

- \`\`Invalid *name* attribute.''

  **The named attribute is encoded incorrectly in the stream. It may, for**  **example, be missing the \`\`:'' that should separate its name and value.**

- \`\`Missing {.''

  **The \`\`{'' marking the start of an attribute list is missing.**

- \`\`Missing }.''

  **The \`\`}'' marking the end of an attribute list is missing.**

- \`\`*name* attribute has data but not length.''

  **The named attribute's value is an object whose attribute list contains a**  **data attribute but not a length attribute. Both attributes**  **must be present to specify binary data. (A similar diagnostic is produced**  **if there is a length attribute but no data attribute.)**

- \`\`*name* attribute's *attr* attribute incorrect.''

  **The named attribute's value is an object whose attribute list indicates**  **it has binary data. However, its data attribute specifies an offset**  **too early in the binary data portion of the file, or its data or** **length attribute has a non-integer value.**

- \`\`Read from stream failed.''

  **An attempt to read a block of binary data failed, perhaps because of a**  **premature end-of-file.**

- \`\`Vista data file delimiter not found.''

  **The** **FORMFEED NEWLINE** **sequence terminating the attribute list portion of the data file wasn't**  **found.**

- \`\`Vista data file isn't version 2.''

  **The data file's header indicates a file format version other than 2, the**  **current version.**

## AUTHOR

**Art Pope \<pope@cs.ubc.ca\>**

**Adaption to vistaio: Gert Wollny \<gw.fossdev@gmail.com\>**