Updated on 2026-08-03 GMT+08:00

Listing Files in a Parallel File System (SDK for C)

If you have any questions during development, post them on the Issues page of GitHub.

You can call list_bucket_objects to list files in a parallel file system.

Restrictions

Method

1
2
void list_bucket_objects(const obs_options *options, const char *prefix, const char *marker, 
            const char *delimiter, int maxkeys, obs_list_objects_handler *handler, void *callback_data);

Request Parameters

Table 1 List of request parameters

Parameter

Type

Mandatory (Yes/No)

Description

options

const obs_options *

Yes

The context of the requested bucket. Refer to Configuring option (SDK for C) to set the AK, SK, endpoint, bucket, timeout, and temporary credentials through obs_options.

prefix

char *

No

Prefix that the names of objects to list must contain.

marker

char *

No

Object name to start with when listing objects. All objects are listed in the lexicographical order.

delimiter

char *

No

The character used to group object names. If the object name contains the value specified by the delimiter parameter, the string from the first character to the first delimiter in the object name (excluding the prefix if prefix is specified) is grouped into one commonPrefix to be returned.

For a parallel file system, if this parameter is not specified, all the content in the directory is recursively listed by default, including the content in subdirectories. In big data scenarios, file systems usually have multiple directory levels with a huge number of objects. In this case, you are advised to configure [delimiter="/"] to list only the objects in the current directory with no subdirectories included, making your listing more efficient.

maxkeys

int

Yes

Maximum number of objects listed in the response body. The value ranges from 1 to 1000. If the value exceeds 1000, only 1,000 objects are returned.

handler

obs_list_objects_handler *

Yes

A callback structure where all members are pointers to callback functions, used to set the callback functions that handle response data. You can set a callback function to copy the response data from the server to your custom callback_data.

callback_data

void *

No

Custom callback data.

Sample Code

This example lists objects in a parallel file system.
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
#include "eSDKOBS.h"
#include <stdio.h>
#include <time.h>
#include <sys/stat.h>
// The response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).
obs_status response_properties_callback(const obs_response_properties *properties, void *callback_data);
void listobjects_complete_callback(obs_status status,
    const obs_error_details *error,
    void *callback_data);
typedef struct list_object_callback_data
{
    int is_truncated;
    char next_marker[1024];
    int keyCount;
    int allDetails;
    obs_status ret_status;
} list_object_callback_data; 
obs_status list_objects_callback(int is_truncated, const char *next_marker,
    int contents_count,
    const obs_list_objects_content *contents,
    int common_prefixes_count,
    const char **common_prefixes,
    void *callback_data);
int main()
{
    // The following code shows how to use the list_bucket_objects function to list objects in a bucket:
    // Call the obs_initialize method at the program entry to initialize global resources such as the network and memory.
    obs_status ret_status = obs_initialize(OBS_INIT_ALL);
    if (OBS_STATUS_OK != ret_status)
    {
        printf("obs_initialize failed(%s).\n", obs_get_status_name(ret_status));
        return -1;
    }
    obs_options options;
    // Create and initialize options, including the access domain name (host_name), access keys (access_key_id and access_key_secret), bucket name (bucket_name), and bucket storage class (storage_class).
    init_obs_options(&options);
    // Enter the endpoint corresponding to the bucket for host_name. CN-Hong Kong is used here as an example. Replace it with the one in your actual situation.
    options.bucket_options.host_name = "obs.ap-southeast-1.myhuaweicloud.com";
    // Hard-coded or plaintext AK and SK are risky. For security purposes, encrypt your AK and SK and store them in the configuration file or environment variables.
    // In this example, the AK and SK are stored in environment variables for identity authentication. Before running the code in this example, configure local environment variables ACCESS_KEY_ID and SECRET_ACCESS_KEY.
    options.bucket_options.access_key = getenv("ACCESS_KEY_ID");
    options.bucket_options.secret_access_key = getenv("SECRET_ACCESS_KEY");
    // Specify the bucket name, for example, example-bucket-name.
    char * bucket_name = "example-bucket-name";
    options.bucket_options.bucket_name = bucket_name;
    // Set the response callback function.
    obs_list_objects_handler list_bucket_objects_handler =
    {
        { &response_properties_callback, &listobjects_complete_callback },
        &list_objects_callback
    };
    // Customize callback data.
    list_object_callback_data data;
    memset(&data, 0, sizeof(list_object_callback_data));
    data.allDetails = 1;
    const char* prefix = NULL;
    const char* marker = NULL;
    const char* delimiter = "/";
    int maxkeys = 1000;
    // List objects.
    list_bucket_objects(&options, prefix, marker, delimiter, maxkeys, &list_bucket_objects_handler, &data);
    if (OBS_STATUS_OK == data.ret_status) {
        printf("list bucket objects successfully. \n");
    }
    else
    {
        printf("list bucket objects failed(%s).\n",
            obs_get_status_name(data.ret_status));
    }
    // Release the allocated global resources.
    obs_deinitialize();
}
// The response callback function. The content of properties in the callback can be recorded in callback_data (custom callback data).
obs_status response_properties_callback(const obs_response_properties *properties, void *callback_data)
{
    if (properties == NULL)
    {
        printf("error! obs_response_properties is null!");
        return OBS_STATUS_OK;      
    }
    // Print the response.
#define print_nonnull(name, field)                                 \
    do {                                                           \
        if (properties-> field) {                                  \
            printf("%s: %s\n", name, properties->field);          \
        }                                                          \
    } while (0)
    print_nonnull("request_id", request_id);
    print_nonnull("request_id2", request_id2);
    print_nonnull("content_type", content_type);
    if (properties->content_length) {
        printf("content_length: %llu\n", properties->content_length);
    }
    print_nonnull("server", server);
    print_nonnull("ETag", etag);
    print_nonnull("expiration", expiration);
    print_nonnull("website_redirect_location", website_redirect_location);
    print_nonnull("version_id", version_id);
    print_nonnull("allow_origin", allow_origin);
    print_nonnull("allow_headers", allow_headers);
    print_nonnull("max_age", max_age);
    print_nonnull("allow_methods", allow_methods);
    print_nonnull("expose_headers", expose_headers);
    print_nonnull("storage_class", storage_class);
    print_nonnull("server_side_encryption", server_side_encryption);
    print_nonnull("kms_key_id", kms_key_id);
    print_nonnull("customer_algorithm", customer_algorithm);
    print_nonnull("customer_key_md5", customer_key_md5);
    print_nonnull("bucket_location", bucket_location);
    print_nonnull("obs_version", obs_version);
    print_nonnull("restore", restore);
    print_nonnull("obs_object_type", obs_object_type);
    print_nonnull("obs_next_append_position", obs_next_append_position);
    print_nonnull("obs_head_epid", obs_head_epid);
    print_nonnull("reserved_indicator", reserved_indicator);
    int i;
    for (i = 0; i < properties->meta_data_count; i++) {
        printf("x-obs-meta-%s: %s\n", properties->meta_data[i].name,
            properties->meta_data[i].value);
    }
    return OBS_STATUS_OK;
}
void print_error_details(const obs_error_details *error) {
    if (error && error->message) {
        printf("Error Message: \n   %s\n", error->message);
    }
    if (error && error->resource) {
        printf("Error Resource: \n  %s\n", error->resource);
    }
    if (error && error->further_details) {
        printf("Error further_details: \n   %s\n", error->further_details);
    }
    if (error && error->extra_details_count) {
        int i;
        for (i = 0; i < error->extra_details_count; i++) {
            printf("Error Extra Detail(%d):\n   %s:%s\n", i, error->extra_details[i].name,
                error->extra_details[i].value);
        }
    }
    if (error && error->error_headers_count) {
        int i;
        for (i = 0; i < error->error_headers_count; i++) {
            const char *errorHeader = error->error_headers[i];
            printf("Error Headers(%d):\n    %s\n", i, errorHeader == NULL ? "NULL Header" : errorHeader);
        }
    }
}
void listobjects_complete_callback(obs_status status,
    const obs_error_details *error,
    void *callback_data)
{
    if (callback_data)
    {
        list_object_callback_data *data = (list_object_callback_data *)callback_data;
        data->ret_status = status;
    }
    else {
        printf("Callback_data is NULL");
    }
    print_error_details(error);
}
static void printListBucketHeader(int allDetails)
{
    printf("%-50s  %-20s  %-5s",
        "   Key",
        "   Last Modified", "Size");
    if (allDetails) {
        printf("  %-34s  %-64s  %-12s            %-12s",
            "   ETag",
            "   Owner ID",
            "Display Name",
            "StorageClass");
    }
    printf("\n");
    printf("--------------------------------------------------  "
        "--------------------  -----");
    if (allDetails) {
        printf("  ----------------------------------  "
            "-------------------------------------------------"
            "---------------  ------------            ------------");
    }
    printf("\n");
}
obs_status list_objects_callback(int is_truncated, const char *next_marker,
    int contents_count,
    const obs_list_objects_content *contents,
    int common_prefixes_count,
    const char **common_prefixes,
    void *callback_data)
{
    list_object_callback_data *data = (list_object_callback_data *)callback_data;
    data->is_truncated = is_truncated;
    if ((!next_marker || !next_marker[0]) && contents_count) {
        next_marker = contents[contents_count - 1].key;
    }
    if (next_marker) {
        snprintf(data->next_marker, sizeof(data->next_marker), "%s",
            next_marker);
    }
    else {
        data->next_marker[0] = 0;
    }
    if (contents_count && !data->keyCount) {
        printListBucketHeader(data->allDetails);
    }
    int i;
    for (i = 0; i < contents_count; i++) {
        const obs_list_objects_content *content = &(contents[i]);
        char timebuf[256] = { 0 };
        time_t t = (time_t)content->last_modified;
        strftime(timebuf, sizeof(timebuf), "%Y-%m-%dT%H:%M:%SZ",
            gmtime(&t));
        char sizebuf[16] = { 0 };
        if (content->size < 100000) {
            sprintf_s(sizebuf, sizeof(sizebuf), "%5llu", (unsigned long long) content->size);
        }
        else if (content->size < (1024 * 1024)) {
            sprintf_s(sizebuf, sizeof(sizebuf), "%4lluK",
                ((unsigned long long) content->size) / 1024ULL);
        }
        else if (content->size < (10 * 1024 * 1024)) {
            float f = content->size;
            f /= (1024 * 1024);
            sprintf_s(sizebuf, sizeof(sizebuf), "%1.2fM", f);
        }
        else if (content->size < (1024 * 1024 * 1024)) {
            sprintf_s(sizebuf, sizeof(sizebuf), "%4lluM",
                ((unsigned long long) content->size) /
                (1024ULL * 1024ULL));
        }
        else {
            float f = (content->size / 1024);
            f /= (1024 * 1024);
            sprintf_s(sizebuf, sizeof(sizebuf), "%1.2fG", f);
        }
        printf("%-50s  %s  %s", content->key, timebuf, sizebuf);
        if (data->allDetails) {
            printf("  %-36s  %-64s  %-20s  %-16s  %-16s",
                content->etag,
                content->owner_id ? content->owner_id : "",
                content->owner_display_name ? content->owner_display_name : "",
                content->storage_class ? content->storage_class : "",
                content->type ? content->type : ""
            );
        }
        printf("\n");
    }
    data->keyCount += contents_count;
    for (i = 0; i < common_prefixes_count; i++) {
        printf("\nCommon Prefix: %s\n", common_prefixes[i]);
    }
    printf("contents_count:%d\n", contents_count);
    return OBS_STATUS_OK;
}