Skip navigation links
24.2.3.52 mysql_real_escape_string() »
Section Navigation      [Toggle]

24.2.3.51. mysql_real_connect()

MYSQL *mysql_real_connect(MYSQL *mysql, const char *host, const char *user, const char *passwd, const char *db, unsigned int port, const char *unix_socket, unsigned long client_flag)

Beschreibung

mysql_real_connect() versucht, eine Verbindung zu einer MySQL-Datenbank-Engine auf host herzustellen. mysql_real_connect() muss erfolgreich zum Abschluss kommen, ehe Sie irgendwelche anderen API-Funktionen ausführen können, die eine gültige MYSQL-Verbindungs-Handle-Struktur erfordern.

Die Parameter werden folgendermaßen angegeben:

  • Der erste Parameter sollte die Adresse einer bestehenden MYSQL-Struktur sein. Bevor Sie mysql_real_connect() aufrufen können, müssen Sie die MYSQL-Struktur mit mysql_init() initialisieren. Mit dem mysql_options()-Aufruf können Sie viele Verbindungsoptionen ändern. Siehe Abschnitt 24.2.3.48, „mysql_options()“.

  • Der Wert von host ist entweder ein Hostname oder eine IP-Adresse. Wenn host der Wert NULL oder der String "localhost" ist, wird eine Verbindung mit dem lokalen Host zugrunde gelegt. Wenn das Betriebssystem Sockets (Unix) oder Named Pipes (Windows) unterstützt, werden diese anstelle von TCP/IP für die Serververbindung benutzt.

  • Der Parameter user enthält die MySQL-Kennung für die Anmeldung des Benutzers. Wenn user NULL oder der leere String "" ist, wird der aktuelle Benutzer vorausgesetzt. Bei Unix ist dies der aktuelle Login-Name und bei Windows ODBC muss der aktuelle Benutzername explizit angegeben werden. Siehe Abschnitt 25.1.3.2, „Konfiguration einer MyODBC-DSN unter Windows“.

  • Der Parameter passwd enthält das Passwort für den user. Wenn passwd NULL ist, werden nur diejenigen Einträge der user-Tabelle, die ein leeres Passwortfeld aufweisen, auf Übereinstimmung mit dem Benutzer überprüft. Dadurch kann der Datenbankadministrator das Berechtigungssystem von MySQL so einrichten, dass die Benutzer je nachdem, ob sie ein Passwort angegeben haben oder nicht, unterschiedliche Rechte bekommen.

    Hinweis: Versuchen Sie nicht, das Passwort zu verschlüsseln, ehe Sie mysql_real_connect() aufrufen. Die Passwortverschlüsselung wird automatisch von der Client-API vorgenommen.

  • db ist der Datenbankname. Wenn db nicht NULL ist, stellt die Verbindung diesen Wert als Standarddatenbank ein.

  • Wenn port nicht 0 ist, wird dieser Wert als Portnummer für die TCP/IP-Verbindung benutzt. Beachten Sie, dass der Parameter host den Verbindungstyp definiert.

  • Wenn unix_socket nicht NULL ist, gibt der String den Socket oder die Named Pipe für die Verbindung an. Beachten Sie, dass der Parameter host den Verbindungstyp definiert.

  • Der Wert von client_flag ist normalerweise 0, kann aber auf eine Kombination der folgenden Flags eingestellt werden, um bestimmte Features einzuschalten:

    Flag-Name Flag-Beschreibung
    CLIENT_COMPRESS Verwendet das komprimierte Protokoll.
    CLIENT_FOUND_ROWS Liefert die Anzahl der gefundenen (erkannten) anstatt der Anzahl der betroffenen Zeilen.
    CLIENT_IGNORE_SPACE Erlaubt Leerzeichen hinter Funktionsnamen. Macht alle Funktionsnamen zu reservierten Wörtern.
    CLIENT_INTERACTIVE Erlaubt interactive_timeout Sekunden (anstatt wait_timeout Sekunden) Müßiggang, bevor die Verbindung geschlossen wird. Die wait_timeout-Variable der Client-Session wird auf den Wert der Session-Variablen interactive_timeout gesetzt.
    CLIENT_LOCAL_FILES Ermöglicht LOAD DATA LOCAL.
    CLIENT_MULTI_STATEMENTS Teilt dem Server mit, dass der Client mehrere Anweisungen (durch ‘;’ getrennt) in einem einzigen String senden darf. Ist dieses Flag nicht gesetzt, ist die Ausführung von Mehrfachanweisungen nicht möglich.
    CLIENT_MULTI_RESULTS Teilt dem Server mit, dass der Client mehrere Ergebnismengen von Mehrfachanweisungen oder mehrfachen gespeicherten Prozeduren behandeln kann. Wird automatisch gesetzt, wenn CLIENT_MULTI_STATEMENTS eingestellt ist.
    CLIENT_NO_SCHEMA Verbietet die db_name.tbl_name.col_name-Syntax. Dies gilt für ODBC. Der Parser löst bei Verwendung dieser Syntax einen Fehler aus, was für die Fehlerdiagnose in manchen ODBC-Programmen nützlich ist.
    CLIENT_ODBC Der Client ist ein ODBC-Client. Damit wird mysqld ODBC-freundlicher.
    CLIENT_SSL Verwendet SSL (verschlüsseltes Protokoll). Diese Option sollte nicht von Anwendungsprogrammen gesetzt werden, sondern intern in der Clientbibliothek. Verwenden Sie stattdessen mysql_ssl_set() vor dem Aufruf von mysql_real_connect().

Manche Parameterwerte können einer Optionsdatei entnommen werden, anstatt sie explizit im Aufruf von mysql_real_connect() zu setzen. Um dies zu tun, rufen Sie mysql_options() mit der Option MYSQL_READ_DEFAULT_FILE oder MYSQL_READ_DEFAULT_GROUP auf, bevor Sie mysql_real_connect() verwenden. Danach geben Sie im Aufruf von mysql_real_connect() den Wert „no-value“ für jeden Parameter an, der seinen Wert aus einer Optionsdatei holen soll:

  • Für host geben Sie NULL oder den leeren String ("") an.

  • Für user geben Sie NULL oder den leeren String ("") an.

  • Für passwd geben Sie NULL an. (Ein leerer String als Passwortwert kann im mysql_real_connect()-Aufruf nicht durch einen Wert aus einer Optionsdatei überschrieben werden, da der leere String ausdrücklich besagt, dass das MySQL-Konto ein leeres Passwort besitzen muss.)

  • Für db geben Sie NULL oder den leeren String ("") an.

  • Für port geben Sie den Wert 0 an.

  • Für unix_socket geben Sie den Wert NULL an.

Wenn in der Optionsdatei für einen Parameter kein Wert gefunden wird, wird sein Standardwert gemäß der Beschreibung weiter oben in diesem Abschnitt verwendet.

Rückgabewerte

Ein MYSQL*-Verbindungs-Handle, wenn die Verbindung erfolgreich eingerichtet wurde, und NULL, wenn der Verbindungsversuch keinen Erfolg hatte. Der Rückgabewert für eine erfolgreiche Verbindung ist derselbe wie der Wert des ersten Parameters.

Fehler

  • CR_CONN_HOST_ERROR

    Verbindung zum MySQL Server konnte nicht hergestellt werden.

  • CR_CONNECTION_ERROR

    Verbindung zum lokalen MySQL Server konnte nicht hergestellt werden.

  • CR_IPSOCK_ERROR

    Es konnte kein IP-Socket hergestellt werden.

  • CR_OUT_OF_MEMORY

    Speicherüberlauf.

  • CR_SOCKET_CREATE_ERROR

    Es konnte kein Unix-Socket erzeugt werden.

  • CR_UNKNOWN_HOST

    Die IP-Adresse des Hostnamens konnte nicht gefunden werden.

  • CR_VERSION_ERROR

    Bei einem Versuch einer Verbindungsaufnahme zwischen einem Server und einer Clientbibliothek, die eine andere Protokollversion verwendet, wurde eine Diskrepanz der Protokolle festgestellt. Das kann geschehen, wenn Sie eine sehr alte Clientbibliothek zur Verbindung mit einem neuen Server verwenden, der nicht mit der Option --old-protocol gestartet wurde.

  • CR_NAMEDPIPEOPEN_ERROR

    Es konnte keine Named Pipe für Windows hergestellt werden.

  • CR_NAMEDPIPEWAIT_ERROR

    Es konnte nicht auf eine Named Pipe auf Windows gewartet werden.

  • CR_NAMEDPIPESETSTATE_ERROR

    Es konnte kein Pipe-Handler auf Windows beschafft werden.

  • CR_SERVER_LOST

    Wenn connect_timeout > 0 und es mehr als connect_timeout Sekunden dauerte, eine Verbindung mit dem Server herzustellen, oder wenn der Server während der Ausführung des Befehls init-command abgestürzt ist.

Beispiel 

MYSQL mysql;

mysql_init(&mysql);
mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,"your_prog_name");
if (!mysql_real_connect(&mysql,"host","user","passwd","database",0,NULL,0))
{
    fprintf(stderr, "Failed to connect to database: Error: %s\n",
          mysql_error(&mysql));
}

Wenn Sie mysql_options() aufrufen, liest die MySQL-Bibliothek die Abschnitte [client] und [your_prog_name] in der Datei my.cnf. So ist gewährleistet, dass Ihr Programm auch dann funktioniert, wenn jemand MySQL in nichtstandardmäßiger Weise eingerichtet hat.

Beachten Sie, dass mysql_real_connect() beim Einrichten einer Verbindung das Flag reconnect (ein Teil der MYSQL-Struktur) bei API-Versionen vor 5.0.3 auf 1 und bei neueren Versionen auf 0 setzt. Hat das Flag den Wert 1, versucht sich das System erneut mit dem Server zu verbinden, wenn eine Anweisung wegen einer abgebrochenen Verbindung nicht ausgeführt werden konnte. Seit MySQL 5.0.13 können Sie das Verhalten in Bezug auf Neuverbindungen mit der Option MYSQL_OPT_RECONNECT zu mysql_options() steuern.

Dies ist eine Übersetzung des MySQL-Referenzhandbuchs, das sich auf dev.mysql.com befindet. Das ursprüngliche Referenzhandbuch ist auf Englisch, und diese Übersetzung ist nicht notwendigerweise so aktuell wie die englische Ausgabe. Das vorliegende deutschsprachige Handbuch behandelt MySQL bis zur Version 5.1.