# libcurl状态码（C SDK)
#### 概述
OBS C SDK基于libcurl实现HTTP通信。当curl_easy_perform执行失败时，SDK会在日志中输出libcurl状态码（CURLcode）及错误信息，格式如下：
```
curl_easy_perform failed, CURLcode = 6, curl_error_message is 'Could not resolve host', obs_status = NameLookupError(5), curlErrorBuffer = ...
```
其中关键字段含义：
| 字段                 | 含义  |
|:---|:---|
| CURLcode           | libcurl返回的状态码，用于定位底层网络/SSL/协议错误          |
| curl_error_message | libcurl提供的错误描述文本                         |
| obs_status         | SDK将CURLcode映射后的OBS状态码                   |
| curlErrorBuffer    | libcurl的详细错误缓冲区信息                        |
   
#### SDK中CURLcode到OBS状态的映射
SDK通过request_curl_code_to_status函数将CURLcode映射为OBS状态码，映射关系如下：
| CURLcode                    | 数值 | curl_error_message                 | 映射的OBS状态码                           | 说明                 |
|:---|:---|:---|:---|:---|
| CURLE_OK                    | 0  | No error                           | OBS_STATUS_OK                       | 请求成功               |
| CURLE_OUT_OF_MEMORY         | -1 | Out of memory                      | OBS_STATUS_OutOfMemory              | 内存分配失败             |
| CURLE_COULDNT_RESOLVE_PROXY | 5  | Couldn't resolve proxy name        | OBS_STATUS_NameLookupError          | 代理域名解析失败           |
| CURLE_COULDNT_RESOLVE_HOST  | 6  | Couldn't resolve host name         | OBS_STATUS_NameLookupError          | 服务端域名解析失败          |
| CURLE_COULDNT_CONNECT       | 7  | Failed to connect to host or proxy | OBS_STATUS_FailedToConnect          | 连接服务端或代理失败         |
| CURLE_WRITE_ERROR           | 23 | Write error                        | OBS_STATUS_ConnectionFailed         | 数据写入失败             |
| CURLE_OPERATION_TIMEDOUT    | 28 | Operation timeout                  | OBS_STATUS_ConnectionFailed         | 操作超时               |
| CURLE_PARTIAL_FILE          | 18 | Transferred a partial file         | OBS_STATUS_PartialFile              | 文件传输不完整            |
| CURLE_SSL_CACERT            | 60 | SSL certificate problem            | OBS_STATUS_ServerFailedVerification | SSL证书验证失败          |
| 其他CURLcode                  | -  | -                                  | OBS_STATUS_InternalError            | SDK未显式映射的错误均归为内部错误 |
   
#### 常见CURLcode定位指南
**CURLE_COULDNT_RESOLVE_HOST（6）**
**现象**：日志中出现CURLcode = 6, curl_error_message is 'Could not resolve host'
**可能原因**：
1. DNS配置错误，无法解析OBS服务端域名。
2. 网络不通或DNS服务器不可达。
3. host_name参数配置错误（如拼写错误、缺少域名后缀）。
4. /etc/resolv.conf中DNS服务器配置不正确。
**定位步骤**：
1. 检查options.bucket_options.host_name是否正确，应为OBS服务端域名，如obs.cn-north-4.myhuaweicloud.com。
2. 在服务器上执行nslookup obs.cn-north-4.myhuaweicloud.com验证DNS解析。
3. 检查/etc/resolv.conf中DNS服务器配置。
4. 尝试在/etc/hosts中添加OBS服务端IP映射作为临时验证。
**CURLE_COULDNT_CONNECT（7）**
**现象**：日志中出现CURLcode = 7, curl_error_message is 'Failed to connect to host or proxy'。
**可能原因**：
1. 网络不通，无法建立TCP连接到OBS服务端。
2. 防火墙或安全组规则阻止了出站访问。
3. 代理配置错误。
4. OBS服务端端口被屏蔽（HTTP:80, HTTPS:443）。
**定位步骤**：
1. 执行telnet obs.cn-north-4.myhuaweicloud.com 443验证TCP连通性。
2. 检查防火墙规则和安全组配置，确保出站443端口放通。
3. 如使用代理，检查options.request_options.proxy_host配置是否正确。
4. 执行curl -v https://obs.cn-north-4.myhuaweicloud.com测试连通性。
**CURLE_OPERATION_TIMEDOUT（28）**
**现象**：日志中出现CURLcode = 28, curl_error_message is 'Operation timeout'。
**可能原因**：
1. 网络延迟过高，请求在超时时间内未完成。
2. 上传/下载大文件时超时时间设置过短。
3. 服务端响应慢。
4. 限速设置过低导致传输超时。
**定位步骤**：
1. 检查options.request_options.connect_time（连接超时，单位秒）是否设置合理。
2. 检查options.request_options.speed_time和speed_limit配置。
3. 对于大文件传输，适当增大connect_time和max_connected_time。
4. 检查网络带宽和延迟情况。
**CURLE_SSL_CACERT（60）**
**现象**：日志中出现CURLcode = 60, curl_error_message is 'SSL certificate problem'。
**可能原因**：
1. 服务器缺少CA证书包。
2. options.request_options.server_cert_path指向的证书文件不存在或格式错误。
3. 中间人攻击或证书被篡改。
4. libcurl编译时未正确链接OpenSSL。
**定位步骤**：
1. 检查系统CA证书包是否安装：ls /etc/ssl/certs/。
2. 如设置了server_cert_path，验证证书文件路径和格式。
3. 执行curl -v https://obs.cn-north-4.myhuaweicloud.com验证SSL握手。
4. 如需跳过证书验证（仅测试环境），确认编译时是否启用了相关选项。
**CURLE_PARTIAL_FILE（18）**
**现象**：日志中出现CURLcode = 18, curl_error_message is 'Transferred a partial file'。
**可能原因**：
1. 传输过程中网络中断。
2. 服务端提前关闭连接。
3. 磁盘空间不足导致写入失败。
4. 下载大文件时连接不稳定。
**定位步骤**：
1. 检查网络稳定性。
2. 检查磁盘空间是否充足。
3. 对于大文件下载，建议使用断点续传下载（download_file）接口。
4. 检查服务端返回的Content-Length与实际接收数据量是否一致。
**CURLE_WRITE_ERROR（23）**
**现象**：日志中出现CURLcode = 23, curl_error_message is 'Write error'。
**可能原因**：
1. 回调函数返回错误导致写入中止。
2. 本地磁盘写入失败。
3. 回调函数中发生异常。
**定位步骤**：
1. 检查put_object_data_callback或get_object_data_callback回调函数逻辑。
2. 确认回调函数返回值正确（上传回调应返回写入字节数，非0表示错误）。
3. 检查磁盘空间和文件权限。
**CURLE_OUT_OF_MEMORY（-1 / 其他值）**
**现象**：日志中出现CURLcode = -1或内存相关错误。
**可能原因**：
1. 系统可用内存不足。
2. 上传大文件时缓冲区分配失败。
3. 内存泄漏导致可用内存减少。
**定位步骤**：
1. 执行free -m检查系统内存使用情况。
2. 对于大文件上传，考虑使用分段上传而非一次性上传。
3. 检查是否存在内存泄漏。
4. 调整options.request_options.buffer_size。
**CURLE_COULDNT_RESOLVE_PROXY（5）**
**现象**：日志中出现CURLcode = 5, curl_error_message is 'Couldn't resolve proxy name'。
**可能原因**：
1. 代理服务器域名配置错误。
2. 代理服务器域名无法解析。
**定位步骤**：
1. 检查options.request_options.proxy_host配置格式，应为hostname:port或http://hostname:port。
2. 执行nslookup验证代理域名解析。
3. 如不需要代理，确保proxy_host未设置。
 
#### 日志中CURLcode排查流程
1. 在SDK日志中找到 CURLcode = X。
2. 根据X值对照本文档定位问题类别。
3. 按对应定位步骤逐一排查。
4. 如CURLcode不在本文档映射表中，属于未显式映射的错误，SDK会返回OBS_STATUS_InternalError，可查阅[libcurl官方文档](https://curl.se/libcurl/c/libcurl-errors.html)。
 
#### 相关链接
- libcurl错误码完整列表：[请单击此处](https://curl.se/libcurl/c/libcurl-errors.html)。
- OBS错误码含义、问题原因及处理措施可参考[SDK错误码(C SDK)](https://support.huaweicloud.com/sdk-c-devg-obs/obs_20_1602.html)。