.\"Copyright 2011 (c) EPFL
.TH EGD_OPEN 3 2010 "EPFL" "EEGDEV library manual"
.SH NAME
egd_open - Open an EEG device
.SH SYNOPSIS
.LP
.B #include <eegdev.h>
.sp
.BI "struct eegdev* egd_open(const char* " devstring ");"
.br
.SH DESCRIPTION
.LP
\fBegd_open\fP() opens a EEG device according to the \fIdevstring\fP
description. If \fIdevstring\fP is NULL, the first device supported by the
library will be opened.
.LP
The \fIdevstring\fP argument specifies the type of EEG device required to be
opened and the parameters parameters which the system should be configured
with (overriding defaults settings). The syntax of the string is defined in
\fBeegdev-open-options\fP(5).
.LP
The syntax may change in future releases and programs should not rely on it
to configure the device. It is provided only to users of the programs to
select the EEG acquisition device and configure it. Programs using the
eegdev library should pass the string provided by the users untouched.
.LP
\fIdevstring\fP is not the only way to provides configuration information
about the device to open. The configuration is read from the configuration
files. The final values of the settings provided to the opening function are
defined (and overriden) in the following order:
.IP " *" 3
default values
.IP " *" 3
shared configuration file
.IP " *" 3
device specific configuration file
.IP " *" 3
\fIdevstring\fP
.LP
This order indicates that a setting value specified in \fIdevstring\fP
will always override any setting value defined by other mean.
.SH "RETURN VALUE"
.LP
The function returns a pointer to the opened EEG device in case of success.
Otherwise NULL is returned \fIerrno\fP is set accordingly.
.SH ERRORS
.LP
\fBegd_open\fP() will fail if:
.TP
.B ENOSYS
the device part of \fIdevstring\fP does not refer to a device supported by
any of the installed eegdev plugin modules.
.TP
.B EINVAL
one of the option specified in \fIdevstring\fP is unknown.
.TP
.B ENODEV
The specified device is not connected.
.TP
.B EBUSY
The specified device is already in use.
.TP
.B ECHILD
The specified device needs an auxiliary child process whose executable
file cannot be found.
.SH ENVIRONMENT
.IP "\fBEEGDEV_PLUGINS_DIR\fP" 4
.PD
This variable controls which folder should be search to find plugin modules.
If unset, they will be searched in the subfolder \fB@PACKAGE_NAME@\fP of the
installation folder of the libraries.
.IP "\fBEEGDEV_CONF_DIR\fP" 4
.PD
This variable controls which folder should be search to find the
configuration files. If unset, they will be searched in
\fB@SYSCONFDIR@/@PACKAGE_NAME@\fP.
.SH "SEE ALSO"
.BR egd_close (3),
.BR eegdev-open-options (5)
