.\" Copyright (c) 2015-2026, The matio contributors
.\" Copyright (c) 2012-2014, Christopher C. Hulbert
.\" All rights reserved.
.\"
.\" SPDX-License-Identifier: BSD-2-Clause
.\"
.Dd April 23, 2026
.Dt MAT_VARGETSTRUCTFIELD 3
.Os
.Sh NAME
.Nm Mat_VarGetStructField
.Nd Gets a field from a structure array.
.Sh SYNOPSIS
.Fd #include <matio.h>
.Ft matvar_t *
.Fo Mat_VarGetStructField
.Fa "const matvar_t *matvar"
.Fa "void *name_or_index"
.Fa "int opt"
.Fa "int index"
.Fc
.Sh DESCRIPTION
The
.Fn Mat_VarGetStructField
function returns a pointer to a field of the structure variable
.Fa matvar
for the structure element at linear index
.Fa index .
If
.Fa opt
is
.Cm MAT_BY_NAME ,
then
.Fa name_or_index
must point to a field name string.
If
.Fa opt
is
.Cm MAT_BY_INDEX ,
then
.Fa name_or_index
must point to an integer containing the 1-relative field index.

The function requires
.Fa matvar
to be a valid structure or object variable.
.Sh RETURN VALUES
On success, a pointer to the requested field is returned.
Otherwise NULL is returned.
.Sh EXAMPLES
This example gets a structure field by name and by index.
.Bd -literal
int field_index = 2;
matvar_t *field;

field = Mat_VarGetStructField(matvar, "field1", MAT_BY_NAME, 0);
field = Mat_VarGetStructField(matvar, &field_index, MAT_BY_INDEX, 0);
.Ed
.Sh SEE ALSO
.Xr Mat_VarGetStructFieldByIndex 3 ,
.Xr Mat_VarGetStructFieldByName 3 ,
.Xr Mat_VarGetStructFieldnames 3 ,
.Xr Mat_VarGetNumberOfFields 3