C String strstr() Function

What You’ll Learn

The strstr() function locates the first occurrence of a substring inside a larger C string. It is one of the most common search tools in <string.h> when you need to find words, file extensions, or any multi-character pattern.

Definition and Usage

strstr searches a haystack string for a needle substring. When the needle appears, the function returns a pointer to the first character of the match inside the haystack—not a copy of the substring.

For example, searching "simple" in "This is a simple example." returns a pointer to the 's' in "simple example."

📝 Syntax

Standard C declaration:

char *strstr(const char *haystack, const char *needle);

Parameters

• haystack — null-terminated string to search in.
• needle — null-terminated substring to find.

Return Value

• Pointer to the first byte of the first occurrence of needle in haystack.
• NULL if needle is not found.
• If needle is empty (""), returns haystack.

Header

• #include <string.h>

Examples Gallery

Compile with gcc strstr.c -std=c11 -o strstr. Every example checks for NULL before using the result.

#include <stdio.h>
#include <string.h>

int main(void) {
    const char *haystack = "This is a simple example.";
    const char *needle   = "simple";

    char *result = strstr(haystack, needle);

    if (result != NULL) {
        printf("Substring found: %s\n", result);
    } else {
        printf("Substring not found.\n");
    }

    return 0;
}

Substring found: simple example.

#include <stdio.h>
#include <string.h>

int main(void) {
    const char *text = "CodeToFun tutorials";
    const char *word = "Python";

    char *hit = strstr(text, word);

    if (hit) {
        printf("Found at: %s\n", hit);
    } else {
        printf("'%s' was not found in '%s'.\n", word, text);
    }

    return 0;
}

'Python' was not found in 'CodeToFun tutorials'.

#include <stdio.h>
#include <string.h>

int main(void) {
    const char *line = "user=admin;role=editor";
    const char *key  = "role=";

    char *p = strstr(line, key);

    if (p != NULL) {
        size_t index = (size_t)(p - line);
        printf("Found '%s' at index %zu\n", key, index);
        printf("Value starts at: %s\n", p + strlen(key));
    }

    return 0;
}

Found 'role=' at index 11
Value starts at: editor

#include <stdio.h>
#include <string.h>

int main(void) {
    const char *text   = "foo bar foo baz foo";
    const char *needle = "foo";
    const char *cursor = text;
    int count = 0;

    while ((cursor = strstr(cursor, needle)) != NULL) {
        printf("Match %d at index %td: %s\n",
               ++count, cursor - text, cursor);
        cursor++;  /* move past current 'f' to find overlapping? no - next char */
    }

    printf("Total: %d\n", count);

    return 0;
}

Match 1 at index 0: foo bar foo baz foo
Match 2 at index 8: foo baz foo
Match 3 at index 16: foo
Total: 3

#include <stdio.h>
#include <string.h>

int main(void) {
    const char *path = "/home/user/report.pdf";

    char *ext = strstr(path, ".pdf");
    char *slash = strrchr(path, '/');

    if (ext) {
        printf("Extension match: %s\n", ext);
    }
    if (slash) {
        printf("Filename:        %s\n", slash + 1);
    }

    return 0;
}

Extension match: .pdf
Filename:        report.pdf

🚀 Common Use Cases

• Keyword detection — check whether user input contains a command or flag.
• File extensions — locate ".txt", ".json", or similar suffixes.
• Config parsing — find "key=" before reading a value.
• Log filtering — detect error codes or module names inside log lines.
• Simple replace prep — find a match, then copy or overwrite surrounding text manually.

📝 Notes

• Case-sensitive byte comparison—"ABC" and "abc" do not match.
• The returned pointer aliases haystack; do not free it separately.
• Empty needle ("") returns haystack per the C standard.
• Do not pass NULL for either argument—behavior is undefined.
• For bounded buffers (not guaranteed null-terminated), prefer memmem on POSIX or manual length-limited search.

⚡ Optimization

Standard library implementations often use efficient algorithms (such as Two-Way search) for long needles. If you call strstr repeatedly on the same haystack, save the result pointer instead of searching again. For very large data or binary blobs, consider specialized search routines with explicit lengths.

💡 Best Practices