.\" -*- coding: UTF-8 -*- '\" t .\" Copyright 1993, David Metcalfe .\" Copyright 2006, Michael Kerrisk .\" Copyright, the authors of the Linux man-pages project .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH strtol 3 "8 فبراير 2026" "صفحات دليل لينكس 6.18" .SH الاسم strtol, strtoll, strtoq \- تحويل سلسلة محارف إلى عدد صحيح طويل .SH المكتبة مكتبة سي المعيارية (\fIlibc\fP،\ \fI\-lc\fP) .SH موجز .nf \fB#include \fP .P \fBlong strtol(const char *restrict \fP\fInptr\fP\fB,\fP \fB char **_Nullable restrict \fP\fIendptr\fP\fB, int \fP\fIbase\fP\fB);\fP \fBlong long strtoll(const char *restrict \fP\fInptr\fP\fB,\fP \fB char **_Nullable restrict \fP\fIendptr\fP\fB, int \fP\fIbase\fP\fB);\fP .fi .P .RS -4 متطلبات ماكروات اختبار الميزات لـ glibc (انظر \fBfeature_test_macros\fP(7)): .RE .P \fBstrtoll\fP(): .nf _ISOC99_SOURCE || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE .fi .SH الوصف تحوّل الدالة \fBstrtol\fP() الجزء الأولي من السلسلة في \fInptr\fP إلى قيمة عدد صحيح طويل وفقًا لـ \fIbase\fP المُعطى، والذي يجب أن يكون بين 2 و36 شاملًا، أو أن يكون القيمة الخاصة 0. .P قد تبدأ السلسلة بكمية اختيارية من المسافات البيضاء (كما يحددها \fBisspace\fP(3)) تليها علامة \[aq]+\[aq] أو \[aq]\-\[aq] اختيارية واحدة. إذا كانت \fIbase\fP صفرًا أو 16، فقد تتضمن السلسلة بادئة "0x" أو "0X"، وسيُقرأ الرقم بالأساس 16؛ أما إذا كانت \fIbase\fP صفرًا أو 2، فقد تتضمن السلسلة بادئة "0b" أو "0B"، وسيُقرأ الرقم بالأساس 2؛ وخلاف ذلك، تُتخذ \fIbase\fP الصفرية على أنها 10 (عشري) ما لم يكن المحرف التالي هو \[aq]0\[aq]، وفي هذه الحالة تُتخذ على أنها 8 (ثماني). .P يُحوّل باقي السلسلة إلى قيمة \fIlong\fP بالطريقة الواضحة، ويتوقف عند أول محرف ليس رقمًا صالحًا في الأساس المُعطى. (في الأساسات فوق 10، يمثل الحرف \[aq]A\[aq] سواء بالأحرف الكبيرة أو الصغيرة 10، ويمثل \[aq]B\[aq] 11، وهكذا، مع \[aq]Z\[aq] الذي يمثل 35.) .P إذا لم يكن \fIendptr\fP فارغًا (NULL)، وكان \fIbase\fP مدعومًا، تخزّن \fBstrtol\fP() عنوان أول محرف غير صالح في \fI*endptr\fP. إذا لم تكن هناك أرقام على الإطلاق، تخزّن \fBstrtol\fP() القيمة الأصلية لـ \fInptr\fP في \fI*endptr\fP (وتُعيد 0). على وجه الخصوص، إذا لم يكن \fI*nptr\fP هو \[aq]\[rs]0\[aq] ولكن \fI**endptr\fP هو \[aq]\[rs]0\[aq] عند الإرجاع، تكون السلسلة بأكملها صالحة. .P تعمل الدالة \fBstrtoll\fP() تمامًا مثل الدالة \fBstrtol\fP() ولكنها تُعيد قيمة عدد صحيح من نوع \fIlong long\fP. .SH "قيمة الإرجاع" تُعيد الدالة \fBstrtol\fP() نتيجة التحويل، إلا إذا كانت القيمة ستؤدي إلى تجاوز سفلي أو تجاوز علوي. إذا حدث تجاوز سفلي، تُعيد \fBstrtol\fP() \fBLONG_MIN\fP. إذا حدث تجاوز علوي، تُعيد \fBstrtol\fP() \fBLONG_MAX\fP. في كلتا الحالتين، يُضبط \fIerrno\fP على \fBERANGE\fP. ينطبق نفس الشيء تمامًا على \fBstrtoll\fP() (مع \fBLLONG_MIN\fP و\fBLLONG_MAX\fP بدلاً من \fBLONG_MIN\fP و\fBLONG_MAX\fP). .SH الأخطاء لا تعدل هذه الدالة \fIerrno\fP عند النجاح. .TP \fBEINVAL\fP (ليس في C99) يحتوي \fIالأساس\fP المعطى على قيمة غير مدعومة. .TP \fBERANGE\fP القيمة الناتجة كانت خارج النطاق. .P قد يقوم التنفيذ أيضًا بضبط \fIerrno\fP على \fBEINVAL\fP في حالة عدم إجراء أي تحويل (لم تُرَ أي أرقام، وأُرْجِعَ 0). .SH السمات للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر \fBattributes\fP(7). .TS allbox; lbx lb lb l l l. الواجهة السمة القيمة T{ .na .nh \fBstrtol\fP(), \fBstrtoll\fP(), \fBstrtoq\fP() T} سلامة الخيوط المنطقة (locale) آمنة لتعدد المسالك (MT\-Safe) .TE .SH الإصدارات وفقًا لـ POSIX.1، في الإعدادات المحلية غير "C" و"POSIX"، قد تقبل هذه الدوال سلاسل رقمية أخرى محددة بالتنفيذ. .P يمتلك BSD أيضًا .P .in +4n .EX \fBquad_t strtoq(const char *\fP\fInptr\fP\fB, char **\fP\fIendptr\fP\fB, int \fP\fIbase\fP\fB);\fP .EE .in .P بتعريف مشابه تمامًا. اعتمادًا على حجم الكلمة في البنية الحالية، قد يكون هذا مكافئًا لـ \fBstrtoll\fP() أو لـ \fBstrtol\fP(). .SH المعايير C23، ‏POSIX.1\-2024. .SH التاريخ .TP \fBstrtol\fP() POSIX.1\-2001، C89، SVr4، 4.3BSD. .TP \fBstrtoll\fP() POSIX.1\-2001، C99. .TP "0b"، "0B" C23. glibc 2.38. (ليس في POSIX.) .SH تحذيرات .SS "فحوصات النطاق" نظرًا لأن \fBstrtol\fP() يمكنها قانونيًا إرجاع 0 أو \fBLONG_MAX\fP أو \fBLONG_MIN\fP (\fBLLONG_MAX\fP أو \fBLLONG_MIN\fP لـ \fBstrtoll\fP()) في كل من النجاح والفشل، يجب على البرنامج المستدعي ضبط \fIerrno\fP على 0 قبل الاستدعاء، ثم تحديد ما إذا حدث خطأ بالتحقق مما إذا كان \fIerrno == ERANGE\fP بعد الاستدعاء. .P .in +4n .EX errno = 0; n = strtol(s, &end, base); if (end == s) goto no_number; if ((errno == ERANGE && n == _Minof(long)) || n < min) goto too_low; if ((errno == ERANGE && n == _Maxof(long)) || n > max) goto too_high; .EE .in .SS base إذا كان \fIbase\fP بحاجة إلى الاختبار، فيجب اختباره في استدعاء حيث من المعروف أن السلسلة ستنجح. وإلا، فمن المستحيل التمييز بين الأخطاء بشكل محمول. .P .in +4n .EX errno = 0; strtol("0", NULL, base); if (errno == EINVAL) goto unsupported_base; .EE .in .SH العلل .SS "مساحة فارغة" تقبل هذه الدوال المسافات البيضاء البادئة بصمت. لرفض المسافات البيضاء، استدع \fBisspace\fP(3) قبل \fBstrtol\fP(). .SH أمثلة يُظهر البرنامج الموضح أدناه استخدام \fBstrtol\fP(). يُحدد وسيط سطر الأوامر الأولى سلسلة محارف يجب أن تحلل منها \fBstrtol\fP() رقمًا. يُحدد الوسيط الثاني (الاختياري) الأساس المستخدم للتحويل. (يُحوَّل هذا الوسيط إلى شكل رقمي باستخدام \fBatoi\fP(3)، وهي دالة لا تؤدي فحص الأخطاء ولها واجهة أبسط من \fBstrtol\fP().) بعض الأمثلة على النتائج التي ينتجها هذا البرنامج هي التالية: .P .in +4n .EX $\fB ./a.out 123\fP strtol() returned 123 $\fB ./a.out \[aq] 123\[aq]\fP strtol() returned 123 $\fB ./a.out 123abc\fP strtol() returned 123 Further characters after number: "abc" $\fB ./a.out 123abc 55\fP strtol: Invalid argument $\fB ./a.out \[aq]\[aq]\fP No digits were found $\fB ./a.out 4000000000\fP strtol: Numerical result out of range .EE .in .SS "مصدر البرنامج" .\" SRC BEGIN (strtol.c) \& .EX #include #include #include \& int main(int argc, char *argv[]) { int base; char *endptr, *str; long val; \& if (argc < 2) { fprintf(stderr, "Usage: %s str [base]\[rs]n", argv[0]); exit(EXIT_FAILURE); } \& str = argv[1]; base = (argc > 2) ? atoi(argv[2]) : 0; \& errno = 0; /* To distinguish success/failure after call */ strtol("0", NULL, base); if (errno == EINVAL) { perror("strtol"); exit(EXIT_FAILURE); } \& errno = 0; /* To distinguish success/failure after call */ val = strtol(str, &endptr, base); \& /* Check for various possible errors. */ \& if (errno == ERANGE) { perror("strtol"); exit(EXIT_FAILURE); } \& if (endptr == str) { fprintf(stderr, "No digits were found\[rs]n"); exit(EXIT_FAILURE); } \& /* If we got here, strtol() successfully parsed a number. */ \& printf("strtol() returned %ld\[rs]n", val); \& if (*endptr != \[aq]\[rs]0\[aq]) /* Not necessarily an error. */ printf("Further characters after number: \[rs]"%s\[rs]"\[rs]n", endptr); \& exit(EXIT_SUCCESS); } .EE .\" SRC END .SH "انظر أيضًا" \fBatof\fP(3), \fBatoi\fP(3), \fBatol\fP(3), \fBstrtod\fP(3), \fBstrtoimax\fP(3), \fBstrtoul\fP(3) .PP .SH ترجمة تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي . .PP هذه الترجمة هي وثيقة مجانية؛ راجع .UR https://www.gnu.org/licenses/gpl-3.0.html رخصة جنو العامة الإصدار 3 .UE أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات. .PP إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: .MT kde-l10n-ar@kde.org .ME .