# libmemcached Configuration

## SYNOPSIS

#include <libmemcached-1.0/memcached.h>

  Compile and link with -lmemcached

memcached_st *memcached(const char *string, size_t string_length)
  Parameters:

    - string -- configuration string

    - string_length -- length of the configuration string without any terminating zero

  Returns:

    allocated and initialized `memcached_st` struct

memcached_return_t libmemcached_check_configuration(const char *option_string, size_t length, char *error_buffer, size_t error_buffer_size)
  Parameters:

    - option_string -- configuration string

    - length -- length of the configuration string without any terminating zero

    - error_buffer -- buffer used to store any error message

    - error_buffer_size -- available size of the `error_buffer`

  Returns:

    `memcached_return_t` indicating success

## DESCRIPTION

`libmemcached` implements a custom language for configuring and modifying servers. By passing in an option string you can generate a `memcached_st` object that you can use in your application directly.

### General Options:

--SERVER=<servername>:<optional_port>/?<optional_weight>

  Provide a servername to be used by the client.

  Providing a weight will cause weighting to occur with all hosts with each server getting a default weight of 1.

--SOCKET=\"<filepath>/?<optional_weight>\"

  Provide a filepath to a UNIX socket file. Providing a weight will cause weighting to occur with all hosts with each server getting a default weight of 1.

--VERIFY-KEY

  Verify that keys that are being used fit within the design of the protocol being used.

--REMOVE_FAILED_SERVERS

  Enable the behavior `MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS`.

--BINARY-PROTOCOL

  Force all connections to use the binary protocol.

--BUFFER-REQUESTS

  Please see `MEMCACHED_BEHAVIOR_BUFFER_REQUESTS`.

--CONFIGURE-FILE=

  Provide a configuration file to be used to load requests. Beware that by using a configuration file `libmemcached` will reset `memcached_st` based on information only contained in the file.

--CONNECT-TIMEOUT=

  See `memcached_behavior_set()` for `MEMCACHED_BEHAVIOR_CONNECT_TIMEOUT`.

--DISTRIBUTION=

  Set the distribution model used by the client. See `memcached_behavior_set()` for more details.

--HASH=

  Set the hashing algorithm used for placing keys on servers.

--HASH-WITH-NAMESPACE

  When enabled the prefix key will be added to the key when determining which server to store the data in.

--NOREPLY

  Enable "no reply" for all calls that support this. It is highly recommended that you use this option with the binary protocol only.

--NUMBER-OF-REPLICAS=

  Set the number of servers that keys will be replicated to.

--RANDOMIZE-REPLICA-READ

  Select randomly the server within the replication pool to read from.

--SORT-HOSTS

  When adding new servers always calculate their distribution based on sorted naming order.

--SUPPORT-CAS

  See `memcached_behavior_set()` for `MEMCACHED_BEHAVIOR_SUPPORT_CAS`

--USE-UDP

  See `memcached_behavior_set()` for `MEMCACHED_BEHAVIOR_USE_UDP`

--NAMESPACE=

  A namespace is a container that provides context for keys, only other requests that know the namespace can access these values. This is accomplished by prepending the namespace value to all keys.

### Memcached Pool Options:

--POOL-MIN

  Initial size of pool.

--POOL-MAX

  Maximize size of the pool.

### I/O Options:

--TCP-NODELAY

  See `memcached_behavior_set()` for `MEMCACHED_BEHAVIOR_TCP_NODELAY`

--TCP-KEEPALIVE

  See `memcached_behavior_set()` for `MEMCACHED_BEHAVIOR_TCP_KEEPALIVE`

--RETRY-TIMEOUT=

  See `memcached_behavior_set()` for `MEMCACHED_BEHAVIOR_RETRY_TIMEOUT`

--SERVER-FAILURE-LIMIT=

  See `memcached_behavior_set()` for `MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT`

--SND-TIMEOUT=

  See `memcached_behavior_set()` for `MEMCACHED_BEHAVIOR_SND_TIMEOUT`

--SOCKET-RECV-SIZE=

  See `memcached_behavior_set()` for `MEMCACHED_BEHAVIOR_SOCKET_RECV_SIZE`

--SOCKET-SEND-SIZE=

  See `memcached_behavior_set()` for `MEMCACHED_BEHAVIOR_SOCKET_SEND_SIZE`

--POLL-TIMEOUT=

  Set the timeout used by poll(3).

--IO-BYTES-WATERMARK=

--IO-KEY-PREFETCH=

--IO-MSG-WATERMARK=

--TCP-KEEPIDLE

--RCV-TIMEOUT=

### Other Options:

INCLUDE

  Include a file in configuration. Unlike `--CONFIGURE-FILE=` this will not reset `memcached_st`.

RESET

  Reset `memcached_st` and continue to process.

END

  End configuration processing.

ERROR

  End configuration processing and throw an error.

## ENVIRONMENT

LIBMEMCACHED

## RETURN VALUE

`memcached()` returns a pointer to the `memcached_st` that was created (or initialized). On an allocation failure, it returns NULL.

## EXAMPLE

    const char *config_string=
      "--SERVER=host10.example.com "
      "--SERVER=host11.example.com "
      "--SERVER=host10.example.com";
    memcached_st *memc= memcached(config_string, strlen(config_string));
    {
      // ...
    }
    memcached_free(memc);

## SEE ALSO

- memcached(1)

- C/C++ Client Library for memcached

- Converting Error Codes to Messages