NAME

       memcached - libmemcached Documentation

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) libmemcached(3) memcached_strerror(3)