cchBufferLength

cchBufferLength is a variable name commonly used in Windows API documentation and C/C++ code to denote the capacity of a character buffer. The prefix cch stands for “count of characters,” distinguishing it from a byte count prefix such as cb. The full name, cchBufferLength, conveys that the value represents how many characters the buffer can hold, not how many bytes.

In practice, cchBufferLength is used as a parameter or field that communicates the destination buffer size to a function or a data structure. The function is expected to write up to that many characters into the buffer, typically including space for a terminating null character when dealing with null-terminated strings. Because the actual usable string length is usually one less than the total capacity, the specification often requires one extra character for the terminator, so callers must account for that when preparing or validating buffers.

If the provided buffer is too small for the operation, many APIs return an error such as insufficient buffer and may provide a separate value indicating the required size. This allows the caller to allocate a larger buffer and retry. The distinction between cch (characters) and cb (bytes) is important in Unicode and ANSI contexts, where the same logical buffer may have different byte lengths depending on character width.

Developers frequently encounter cchBufferLength in function prototypes, structures, and samples that deal with strings, paths, names, or other text data. For safer string handling, Windows provides functions like StringCchCopy and StringCbCopy that explicitly use character-count or byte-count parameters to prevent overruns.