.\"Copyright 2010 (c) EPFL
.TH XDF_ADD_CHANNEL 3 2010 "EPFL" "xdffileio library manual"
.SH NAME
xdf_add_channel - Appends a channel to a XDF file
.SH SYNOPSIS
.LP
.B #include <xdfio.h>
.sp
.BI "struct xdfch* xdf_add_channel(struct xdf* " xdf ", const char* " label ");"
.br
.SH DESCRIPTION
.LP
\fBxdf_add_channel\fP() appends a channel to the file referenced by the
handle \fIxdf\fP. The new channel is initialized with the \fIlabel\fP
argument (if not \fBNULL\fP) and with the default channel values set in the
XDF file, i.e. those set using channel configuration fields in
\fBxdf_set_conf\fP(3) (See the related manpage).
.LP
If the call to \fBxdf_add_channel\fP(3) is successful, the default offset
value (the field referenced by \fBXDF_CF_ARROFFSET\fP) is incremented by the
size of the current default stored type (field referenced by
\fBXDF_CF_STOTYPE\fP). As a consequence, if the channel default values have
not changed in-between, the next call to \fBxdf_add_channel\fP() will create
a channel whose location is the array will be next to the previous one.
.LP
This type of initialization allows the user to add channels without having
to specifically pack them: this is achieved by default.
.SH "RETURN VALUE"
.LP
\fBxdf_add_channel\fP() returns the handle to newly created channel
descriptor in case of success. Otherwise NULL is returned  and \fIerrno\fP
is set appropriately.
.SH ERRORS
.TP
.B EINVAL
\fIxdf\fP is NULL.
.TP
.B ENOMEM
The system is unable to allocate resources.
.TP
.B EPERM
the file referenced by \fIxdf\fP has been opened with the mode \fBXDF_READ\fP
.SH "SEE ALSO"
.BR xdf_copy_chconf (3),
.BR xdf_set_conf (3),
.BR xdf_set_chconf (3)