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

12.1.3.43. 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)

Descrição

mysql_real_connect() tenta estabelecer uma conexão mecanismo MySQL de banco de dados executando em host. mysql_real_connect() deve completar com suceeso antes que você possa executar qualquer um das outars funçãoes da API, com a excessão de mysql_get_client_info().

Os parâmetros são especificados da seguinte forma:

  • O primeiro parâmetro deve ser o endereço de uma estrutura MYSQL existente. Antes de chamar mysql_real_connect() você deve chamar mysql_init() para inicializar a estrutura MYSQL. Você pode alterar vária opções de conexão com a chamada mysql_options(). See Secção 12.1.3.40, “mysql_options()”.

  • O valor de host pode ser tanto um nome de máquivo quanto um endereço IP. Se host é NULL ou a string "localhost", a conexão é feita na máquina local. Se o SO suporta sockets (Unix) ou named pipes (Windows), eles são utilizados em vez de TCP/IP para a conexão ao servidor.

  • O parâmetro user contém a indetificação do usuário MySQL. Se user é NULL ou a string vazia "", considera-se o usuário padrão. Sob Unix, ele é o login atual. Sob ODBC no Windows, o usuário atual deve ser especificado explicitamente. See Secção 12.2.2, “Como Preencher os Vários Campos no Programa de Administração do ODBC”.

  • O parâmetro passwd contém a senha para user. Se passwd é NULL, somente entradas na tabela user para usuários que tenham campo de senha em branco (vazia) serão verificados ipor um padrão coincidenete. Isto permite que o admistrador do banco de dados configure o sistema de privilégios do MySQL de tal maneira que usuários os usuários conseguirão privileios diferentes, dependendo se ele espcificou ou não uma senha.

    Nota: Não tente criptografar a senha antes de chamar mysql_real_connect(); senhas criptografadas são tratadas automaticamente pela API cliente.

  • db é o nome de banco de dados. Se db não é NULL, a conexão definirá o banco de dados padrão com este valor.

  • Se port não é 0, o valor será usado como o número da porta para as conexões TCP/IP. Note que o parâmetro host determina o tipo da conexão.

  • Se unix_socket não é NULL, a string especifica o socket ou named pipe que deve ser usado. Note que o parâmetro host determina o tipo de conexão.

  • O valor de client_flag é normalmente 0, mas pode ser definido como uma combinação dos parâmetro seguintes em circunstâncias especiais:

    Nome do parâmetro Descrição do parâmetro
    CLIENT_COMPRESS Usa protocolo compactado.
    CLIENT_FOUND_ROWS Retorna o número de linhas encontradas (correspondentes a um padrão), não o número de linha efetivo.
    CLIENT_IGNORE_SPACE Permite espaço depois do nome de funções. torna todos os nomes de funções palavras reservadas.
    CLIENT_INTERACTIVE Permite interactive_timeout segundos (no lugar de wait_timeout segundos) de inatividade antes de fechar a conexão.
    CLIENT_LOCAL_FILES Habilita LOAD DATA LOCAL.
    CLIENT_MULTI_STATEMENTS Diz ao servidor que o cliente pode enviar consultas multi linhas (separado com ‘;’). Se este parâmetro não está definido, consultas de multil linhas está disabilitado. (Novo na versão 4.1).
    CLIENT_MULTI_RESULTS Diz ao servidor que o cliente pode tratar multíplos conjuntos de resultados de um multi consulta ou stored procedures. Isto é definido automaticamente se CLIENT_MULTI_STATEMENTS está lidado. Novo na versão 4.1.
    CLIENT_NO_SCHEMA Não permite a sintaxe db_name.nome_tabela.nome_coluna. Isto é para o ODBC. Ele faz com que o analizador gere um erro se você utilizar aquela sintaxe. É útil para achar erros em alguns programas ODBC.
    CLIENT_ODBC O cliente é um cliente ODBC. Torna o mysqld mais amigável ao ODBC.
    CLIENT_SSL Usa SSL (protocolo criptografado). Esta opção não deve ser configuração pelo aplicativo; ele é definida internamente na biblioteca cliente.

Valor Retornado

Um handle de conexão MYSQL* se a conexão foi obtida com sucesso, NULL se a conexão falhou. Para um conexão estabelecida o valor de retorn é o mesmo que o valor do primeiro parâmetro.

Erros

  • CR_CONN_HOST_ERROR

    Falhou ao conectar ao servidor MySQL.

  • CR_CONNECTION_ERROR

    Falhou ao conectar ao servidor MySQL local.

  • CR_IPSOCK_ERROR

    Falhou au criar um socket IP.

  • CR_OUT_OF_MEMORY

    Sem memória.

  • CR_SOCKET_CREATE_ERROR

    Falhou ao criar um socket Unix.

  • CR_UNKNOWN_HOST

    Falhou ao procurar o endereço IP para o nome de maquina.

  • CR_VERSION_ERROR

    Um erro de protocolo resultou da tentativa de conexao a um servidor com uma biblioteca cliente que utiliza uma versão de protocolo diferente. Isto pode acontecer se você utiliza uma biblioteca cliente muito antiga para se conectar a um novo servidor qua não foi iniciado com a opção --old-protocol.

  • CR_NAMEDPIPEOPEN_ERROR

    Falhou ao criar um named pipe no Windows.

  • CR_NAMEDPIPEWAIT_ERROR

    Falhou ao esperar por um named pipe no Windows.

  • CR_NAMEDPIPESETSTATE_ERROR

    Falhou ao conseguir mainpulador do pipe no Windows.

  • CR_SERVER_LOST

    Se connect_timeout > 0 e leva mais que connect_timeout segundos para conectar ao servidor ou se o servidro foi finalizado ao executar o init-command.

Exemplo 

MYSQL mysql;

mysql_init(&mysql);
mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,"seu_programa");
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));
}

Usando mysql_options() a biblioteca MySQL irá ler as seções [client] e [seu_programa] no arquivo my.cnf o qual irá assegurar que seu programa irá funcionar, mesmo se alguem tiver configurado o MySQL de um modo fora do padrão.

Note que sob a conexão, mysql_real_connect() define o parâmetro reconnect (parte da estrutura MYSQL) para um valor de 1. Este parâmetro indica, no evento em que uma consulta não pode ser realizada devido a perda de conexão, para tentar se reconectar ao servidor antes de esgotar as tentativas.

This is a translation of the MySQL Reference Manual that can be found at dev.mysql.com. The original Reference Manual is in English, and this translation is not necessarily as up to date as the English version.