From 754bbf7a25a8dda49b5d08ef0d0443bbf5af0e36 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Sun, 7 Apr 2024 13:41:34 -0500 Subject: new repository --- devdocs/c/11.html | 69 +++++ devdocs/c/17.html | 70 +++++ devdocs/c/23.html | 193 ++++++++++++ devdocs/c/95.html | 14 + devdocs/c/99.html | 142 +++++++++ devdocs/c/algorithm%2Fbsearch.html | 104 +++++++ devdocs/c/algorithm%2Fqsort.html | 85 ++++++ devdocs/c/algorithm.html | 22 ++ devdocs/c/atomic%2Fatomic_compare_exchange.html | 45 +++ devdocs/c/atomic%2Fatomic_exchange.html | 24 ++ devdocs/c/atomic%2Fatomic_fetch_add.html | 53 ++++ devdocs/c/atomic%2Fatomic_fetch_and.html | 26 ++ devdocs/c/atomic%2Fatomic_fetch_or.html | 26 ++ devdocs/c/atomic%2Fatomic_fetch_sub.html | 25 ++ devdocs/c/atomic%2Fatomic_fetch_xor.html | 26 ++ devdocs/c/atomic%2Fatomic_flag.html | 26 ++ devdocs/c/atomic%2Fatomic_flag_clear.html | 22 ++ devdocs/c/atomic%2Fatomic_flag_init.html | 26 ++ devdocs/c/atomic%2Fatomic_flag_test_and_set.html | 22 ++ devdocs/c/atomic%2Fatomic_init.html | 26 ++ devdocs/c/atomic%2Fatomic_is_lock_free.html | 39 +++ devdocs/c/atomic%2Fatomic_load.html | 24 ++ devdocs/c/atomic%2Fatomic_lock_free_consts.html | 27 ++ devdocs/c/atomic%2Fatomic_signal_fence.html | 19 ++ devdocs/c/atomic%2Fatomic_store.html | 24 ++ devdocs/c/atomic%2Fatomic_thread_fence.html | 19 ++ devdocs/c/atomic%2Fatomic_var_init.html | 24 ++ devdocs/c/atomic%2Fkill_dependency.html | 20 ++ devdocs/c/atomic%2Fmemory_order.html | 92 ++++++ devdocs/c/atomic.html | 109 +++++++ devdocs/c/chrono%2Fasctime.html | 85 ++++++ devdocs/c/chrono%2Fclock.html | 83 ++++++ devdocs/c/chrono%2Fclock_t.html | 37 +++ devdocs/c/chrono%2Fclocks_per_sec.html | 24 ++ devdocs/c/chrono%2Fctime.html | 79 +++++ devdocs/c/chrono%2Fdifftime.html | 45 +++ devdocs/c/chrono%2Fgmtime.html | 71 +++++ devdocs/c/chrono%2Flocaltime.html | 72 +++++ devdocs/c/chrono%2Fmktime.html | 46 +++ devdocs/c/chrono%2Fstrftime.html | 146 +++++++++ devdocs/c/chrono%2Ftime.html | 40 +++ devdocs/c/chrono%2Ftime_t.html | 38 +++ devdocs/c/chrono%2Ftimespec.html | 43 +++ devdocs/c/chrono%2Ftimespec_get.html | 43 +++ devdocs/c/chrono%2Ftimespec_getres.html | 34 +++ devdocs/c/chrono%2Ftm.html | 41 +++ devdocs/c/chrono%2Fwcsftime.html | 136 +++++++++ devdocs/c/chrono.html | 60 ++++ devdocs/c/comment.html | 86 ++++++ devdocs/c/current_status.html | 11 + devdocs/c/error%2Fabort_handler_s.html | 51 ++++ devdocs/c/error%2Fassert.html | 48 +++ devdocs/c/error%2Ferrno.html | 78 +++++ devdocs/c/error%2Ferrno_macros.html | 44 +++ devdocs/c/error%2Fignore_handler_s.html | 52 ++++ devdocs/c/error%2Fset_constraint_handler_s.html | 57 ++++ devdocs/c/error%2Fstatic_assert.html | 23 ++ devdocs/c/error.html | 78 +++++ devdocs/c/index | 1 + devdocs/c/index.html | 50 ++++ devdocs/c/io%2Fclearerr.html | 45 +++ devdocs/c/io%2Ffclose.html | 57 ++++ devdocs/c/io%2Ffeof.html | 56 ++++ devdocs/c/io%2Fferror.html | 44 +++ devdocs/c/io%2Ffflush.html | 26 ++ devdocs/c/io%2Ffgetc.html | 73 +++++ devdocs/c/io%2Ffgetpos.html | 58 ++++ devdocs/c/io%2Ffgets.html | 71 +++++ devdocs/c/io%2Ffgetwc.html | 75 +++++ devdocs/c/io%2Ffgetws.html | 32 ++ devdocs/c/io%2Ffile.html | 53 ++++ devdocs/c/io%2Ffopen.html | 89 ++++++ devdocs/c/io%2Ffpos_t.html | 37 +++ devdocs/c/io%2Ffprintf.html | 278 ++++++++++++++++++ devdocs/c/io%2Ffputc.html | 66 +++++ devdocs/c/io%2Ffputs.html | 38 +++ devdocs/c/io%2Ffputwc.html | 63 ++++ devdocs/c/io%2Ffputws.html | 40 +++ devdocs/c/io%2Ffread.html | 70 +++++ devdocs/c/io%2Ffreopen.html | 82 ++++++ devdocs/c/io%2Ffscanf.html | 232 +++++++++++++++ devdocs/c/io%2Ffseek.html | 74 +++++ devdocs/c/io%2Ffsetpos.html | 73 +++++ devdocs/c/io%2Fftell.html | 77 +++++ devdocs/c/io%2Ffwide.html | 97 ++++++ devdocs/c/io%2Ffwprintf.html | 208 +++++++++++++ devdocs/c/io%2Ffwrite.html | 59 ++++ devdocs/c/io%2Ffwscanf.html | 216 ++++++++++++++ devdocs/c/io%2Fgetchar.html | 49 +++ devdocs/c/io%2Fgets.html | 40 +++ devdocs/c/io%2Fgetwchar.html | 19 ++ devdocs/c/io%2Fperror.html | 36 +++ devdocs/c/io%2Fputchar.html | 57 ++++ devdocs/c/io%2Fputs.html | 40 +++ devdocs/c/io%2Fputwchar.html | 51 ++++ devdocs/c/io%2Fremove.html | 61 ++++ devdocs/c/io%2Frename.html | 59 ++++ devdocs/c/io%2Frewind.html | 51 ++++ devdocs/c/io%2Fsetbuf.html | 46 +++ devdocs/c/io%2Fsetvbuf.html | 85 ++++++ devdocs/c/io%2Fstd_streams.html | 68 +++++ devdocs/c/io%2Ftmpfile.html | 62 ++++ devdocs/c/io%2Ftmpnam.html | 83 ++++++ devdocs/c/io%2Fungetc.html | 76 +++++ devdocs/c/io%2Fungetwc.html | 27 ++ devdocs/c/io%2Fvfprintf.html | 242 +++++++++++++++ devdocs/c/io%2Fvfscanf.html | 191 ++++++++++++ devdocs/c/io%2Fvfwprintf.html | 227 ++++++++++++++ devdocs/c/io%2Fvfwscanf.html | 157 ++++++++++ devdocs/c/io.html | 155 ++++++++++ devdocs/c/keyword%2F_alignas.html | 7 + devdocs/c/keyword%2F_alignof.html | 7 + devdocs/c/keyword%2F_atomic.html | 7 + devdocs/c/keyword%2F_bool.html | 7 + devdocs/c/keyword%2F_complex.html | 7 + devdocs/c/keyword%2F_decimal128.html | 7 + devdocs/c/keyword%2F_decimal32.html | 7 + devdocs/c/keyword%2F_decimal64.html | 7 + devdocs/c/keyword%2F_generic.html | 7 + devdocs/c/keyword%2F_imaginary.html | 7 + devdocs/c/keyword%2F_noreturn.html | 11 + devdocs/c/keyword%2F_static_assert.html | 7 + devdocs/c/keyword%2F_thread_local.html | 7 + devdocs/c/keyword%2Falignas.html | 7 + devdocs/c/keyword%2Falignof.html | 7 + devdocs/c/keyword%2Fauto.html | 9 + devdocs/c/keyword%2Fbool.html | 7 + devdocs/c/keyword%2Fbreak.html | 6 + devdocs/c/keyword%2Fcase.html | 6 + devdocs/c/keyword%2Fchar.html | 6 + devdocs/c/keyword%2Fconst.html | 6 + devdocs/c/keyword%2Fconstexpr.html | 7 + devdocs/c/keyword%2Fcontinue.html | 6 + devdocs/c/keyword%2Fdefault.html | 9 + devdocs/c/keyword%2Fdo.html | 6 + devdocs/c/keyword%2Fdouble.html | 9 + devdocs/c/keyword%2Felse.html | 6 + devdocs/c/keyword%2Fenum.html | 6 + devdocs/c/keyword%2Fextern.html | 6 + devdocs/c/keyword%2Ffalse.html | 7 + devdocs/c/keyword%2Ffloat.html | 6 + devdocs/c/keyword%2Ffor.html | 6 + devdocs/c/keyword%2Ffortran.html | 6 + devdocs/c/keyword%2Fgoto.html | 6 + devdocs/c/keyword%2Fif.html | 6 + devdocs/c/keyword%2Finline.html | 7 + devdocs/c/keyword%2Fint.html | 6 + devdocs/c/keyword%2Flong.html | 6 + devdocs/c/keyword%2Fnullptr.html | 7 + devdocs/c/keyword%2Fregister.html | 6 + devdocs/c/keyword%2Frestrict.html | 7 + devdocs/c/keyword%2Freturn.html | 6 + devdocs/c/keyword%2Fshort.html | 6 + devdocs/c/keyword%2Fsigned.html | 6 + devdocs/c/keyword%2Fsizeof.html | 6 + devdocs/c/keyword%2Fstatic.html | 12 + devdocs/c/keyword%2Fstatic_assert.html | 7 + devdocs/c/keyword%2Fstruct.html | 6 + devdocs/c/keyword%2Fswitch.html | 6 + devdocs/c/keyword%2Fthread_local.html | 7 + devdocs/c/keyword%2Ftrue.html | 7 + devdocs/c/keyword%2Ftypedef.html | 6 + devdocs/c/keyword%2Ftypeof.html | 7 + devdocs/c/keyword%2Ftypeof_unqual.html | 7 + devdocs/c/keyword%2Funion.html | 6 + devdocs/c/keyword%2Funsigned.html | 6 + devdocs/c/keyword%2Fvoid.html | 9 + devdocs/c/keyword%2Fvolatile.html | 6 + devdocs/c/keyword%2Fwhile.html | 9 + devdocs/c/keyword.html | 111 +++++++ devdocs/c/language%2F_alignas.html | 85 ++++++ devdocs/c/language%2F_alignof.html | 51 ++++ devdocs/c/language%2F_noreturn.html | 61 ++++ devdocs/c/language%2F_static_assert.html | 58 ++++ devdocs/c/language%2Falignas.html | 85 ++++++ devdocs/c/language%2Falignof.html | 51 ++++ devdocs/c/language%2Fanalyzability.html | 49 +++ devdocs/c/language%2Farithmetic_types.html | 302 +++++++++++++++++++ devdocs/c/language%2Farray.html | 198 +++++++++++++ devdocs/c/language%2Farray_initialization.html | 127 ++++++++ devdocs/c/language%2Fas_if.html | 20 ++ devdocs/c/language%2Fascii.html | 131 +++++++++ devdocs/c/language%2Fasm.html | 68 +++++ devdocs/c/language%2Fatomic.html | 77 +++++ devdocs/c/language%2Fattributes%2Fdeprecated.html | 65 ++++ devdocs/c/language%2Fattributes%2Ffallthrough.html | 45 +++ .../c/language%2Fattributes%2Fmaybe_unused.html | 33 +++ devdocs/c/language%2Fattributes%2Fnodiscard.html | 42 +++ devdocs/c/language%2Fattributes%2Fnoreturn.html | 24 ++ .../c/language%2Fattributes%2Freproducible.html | 22 ++ devdocs/c/language%2Fattributes%2Funsequenced.html | 22 ++ devdocs/c/language%2Fattributes.html | 102 +++++++ devdocs/c/language%2Fbasic_concepts.html | 13 + devdocs/c/language%2Fbehavior.html | 166 +++++++++++ devdocs/c/language%2Fbit_field.html | 102 +++++++ devdocs/c/language%2Fbool_constant.html | 21 ++ devdocs/c/language%2Fbreak.html | 62 ++++ devdocs/c/language%2Fcast.html | 64 ++++ devdocs/c/language%2Fcharacter_constant.html | 106 +++++++ devdocs/c/language%2Fcharset.html | 112 +++++++ devdocs/c/language%2Fcompatible_type.html | 233 +++++++++++++++ devdocs/c/language%2Fcompound_literal.html | 89 ++++++ devdocs/c/language%2Fconformance.html | 55 ++++ devdocs/c/language%2Fconst.html | 65 ++++ devdocs/c/language%2Fconstant_expression.html | 107 +++++++ devdocs/c/language%2Fconstexpr.html | 33 +++ devdocs/c/language%2Fcontinue.html | 61 ++++ devdocs/c/language%2Fconversion.html | 304 +++++++++++++++++++ devdocs/c/language%2Fdeclarations.html | 142 +++++++++ devdocs/c/language%2Fdo.html | 61 ++++ devdocs/c/language%2Fenum.html | 140 +++++++++ devdocs/c/language%2Fescape.html | 82 ++++++ devdocs/c/language%2Feval_order.html | 43 +++ devdocs/c/language%2Fexpressions.html | 79 +++++ devdocs/c/language%2Fextern.html | 56 ++++ devdocs/c/language%2Ffile_scope.html | 27 ++ devdocs/c/language%2Ffloating_constant.html | 87 ++++++ devdocs/c/language%2Ffor.html | 63 ++++ devdocs/c/language%2Ffunction_declaration.html | 102 +++++++ devdocs/c/language%2Ffunction_definition.html | 93 ++++++ devdocs/c/language%2Ffunctions.html | 53 ++++ devdocs/c/language%2Fgeneric.html | 62 ++++ devdocs/c/language%2Fgoto.html | 64 ++++ devdocs/c/language%2Fhistory.html | 154 ++++++++++ devdocs/c/language%2Fidentifier.html | 142 +++++++++ devdocs/c/language%2Fif.html | 65 ++++ devdocs/c/language%2Finitialization.html | 89 ++++++ devdocs/c/language%2Finline.html | 77 +++++ devdocs/c/language%2Finteger_constant.html | 135 +++++++++ devdocs/c/language%2Flifetime.html | 41 +++ devdocs/c/language%2Fmain_function.html | 60 ++++ devdocs/c/language%2Fmemory_model.html | 49 +++ devdocs/c/language%2Fname_space.html | 74 +++++ devdocs/c/language%2Fnullptr.html | 59 ++++ devdocs/c/language%2Fobject.html | 137 +++++++++ devdocs/c/language%2Foperator_alternative.html | 85 ++++++ devdocs/c/language%2Foperator_arithmetic.html | 327 +++++++++++++++++++++ devdocs/c/language%2Foperator_assignment.html | 139 +++++++++ devdocs/c/language%2Foperator_comparison.html | 149 ++++++++++ devdocs/c/language%2Foperator_incdec.html | 98 ++++++ devdocs/c/language%2Foperator_logical.html | 111 +++++++ devdocs/c/language%2Foperator_member_access.html | 170 +++++++++++ devdocs/c/language%2Foperator_other.html | 225 ++++++++++++++ devdocs/c/language%2Foperator_precedence.html | 68 +++++ devdocs/c/language%2Fpointer.html | 95 ++++++ devdocs/c/language%2Fpunctuators.html | 175 +++++++++++ devdocs/c/language%2Frestrict.html | 160 ++++++++++ devdocs/c/language%2Freturn.html | 70 +++++ devdocs/c/language%2Fscalar_initialization.html | 50 ++++ devdocs/c/language%2Fscope.html | 128 ++++++++ devdocs/c/language%2Fsizeof.html | 69 +++++ devdocs/c/language%2Fstatements.html | 113 +++++++ devdocs/c/language%2Fstatic_assert.html | 58 ++++ devdocs/c/language%2Fstatic_storage_duration.html | 32 ++ devdocs/c/language%2Fstorage_duration.html | 144 +++++++++ devdocs/c/language%2Fstring_literal.html | 123 ++++++++ devdocs/c/language%2Fstruct.html | 163 ++++++++++ devdocs/c/language%2Fstruct_initialization.html | 125 ++++++++ devdocs/c/language%2Fswitch.html | 88 ++++++ devdocs/c/language%2Fthread_storage_duration.html | 14 + devdocs/c/language%2Ftranslation_phases.html | 105 +++++++ devdocs/c/language%2Ftype.html | 233 +++++++++++++++ devdocs/c/language%2Ftypedef.html | 60 ++++ devdocs/c/language%2Ftypeof.html | 21 ++ devdocs/c/language%2Ftypes.html | 233 +++++++++++++++ devdocs/c/language%2Funion.html | 80 +++++ devdocs/c/language%2Fvalue_category.html | 58 ++++ devdocs/c/language%2Fvariadic.html | 73 +++++ devdocs/c/language%2Fvolatile.html | 86 ++++++ devdocs/c/language%2Fwhile.html | 59 ++++ devdocs/c/language.html | 27 ++ devdocs/c/locale%2Flc_categories.html | 50 ++++ devdocs/c/locale%2Flconv.html | 71 +++++ devdocs/c/locale%2Flocaleconv.html | 33 +++ devdocs/c/locale%2Fsetlocale.html | 49 +++ devdocs/c/locale.html | 29 ++ devdocs/c/memory%2Faligned_alloc.html | 42 +++ devdocs/c/memory%2Fcalloc.html | 62 ++++ devdocs/c/memory%2Ffree.html | 50 ++++ devdocs/c/memory%2Ffree_aligned_sized.html | 20 ++ devdocs/c/memory%2Ffree_sized.html | 70 +++++ devdocs/c/memory%2Fmalloc.html | 52 ++++ devdocs/c/memory%2Frealloc.html | 102 +++++++ devdocs/c/memory.html | 18 ++ devdocs/c/metadata | 2 + devdocs/c/numeric%2Fcomplex%2Fcabs.html | 47 +++ devdocs/c/numeric%2Fcomplex%2Fcacos.html | 76 +++++ devdocs/c/numeric%2Fcomplex%2Fcacosh.html | 80 +++++ devdocs/c/numeric%2Fcomplex%2Fcarg.html | 55 ++++ devdocs/c/numeric%2Fcomplex%2Fcasin.html | 59 ++++ devdocs/c/numeric%2Fcomplex%2Fcasinh.html | 77 +++++ devdocs/c/numeric%2Fcomplex%2Fcatan.html | 56 ++++ devdocs/c/numeric%2Fcomplex%2Fcatanh.html | 78 +++++ devdocs/c/numeric%2Fcomplex%2Fccos.html | 52 ++++ devdocs/c/numeric%2Fcomplex%2Fccosh.html | 71 +++++ devdocs/c/numeric%2Fcomplex%2Fcexp.html | 66 +++++ devdocs/c/numeric%2Fcomplex%2Fcimag.html | 41 +++ devdocs/c/numeric%2Fcomplex%2Fclog.html | 74 +++++ devdocs/c/numeric%2Fcomplex%2Fcmplx.html | 33 +++ devdocs/c/numeric%2Fcomplex%2Fcomplex.html | 37 +++ devdocs/c/numeric%2Fcomplex%2Fcomplex_i.html | 40 +++ devdocs/c/numeric%2Fcomplex%2Fconj.html | 43 +++ devdocs/c/numeric%2Fcomplex%2Fcpow.html | 56 ++++ devdocs/c/numeric%2Fcomplex%2Fcproj.html | 49 +++ devdocs/c/numeric%2Fcomplex%2Fcreal.html | 41 +++ devdocs/c/numeric%2Fcomplex%2Fcsin.html | 58 ++++ devdocs/c/numeric%2Fcomplex%2Fcsinh.html | 71 +++++ devdocs/c/numeric%2Fcomplex%2Fcsqrt.html | 62 ++++ devdocs/c/numeric%2Fcomplex%2Fctan.html | 54 ++++ devdocs/c/numeric%2Fcomplex%2Fctanh.html | 67 +++++ devdocs/c/numeric%2Fcomplex%2Fi.html | 45 +++ devdocs/c/numeric%2Fcomplex%2Fimaginary.html | 47 +++ devdocs/c/numeric%2Fcomplex%2Fimaginary_i.html | 46 +++ devdocs/c/numeric%2Fcomplex.html | 139 +++++++++ devdocs/c/numeric%2Ffenv%2Ffe_dfl_env.html | 80 +++++ devdocs/c/numeric%2Ffenv%2Ffe_exceptions.html | 87 ++++++ devdocs/c/numeric%2Ffenv%2Ffe_round.html | 71 +++++ devdocs/c/numeric%2Ffenv%2Ffeclearexcept.html | 63 ++++ devdocs/c/numeric%2Ffenv%2Ffeenv.html | 116 ++++++++ devdocs/c/numeric%2Ffenv%2Ffeexceptflag.html | 68 +++++ devdocs/c/numeric%2Ffenv%2Ffeholdexcept.html | 74 +++++ devdocs/c/numeric%2Ffenv%2Fferaiseexcept.html | 55 ++++ devdocs/c/numeric%2Ffenv%2Fferound.html | 88 ++++++ devdocs/c/numeric%2Ffenv%2Ffetestexcept.html | 60 ++++ devdocs/c/numeric%2Ffenv%2Ffeupdateenv.html | 74 +++++ devdocs/c/numeric%2Ffenv.html | 52 ++++ devdocs/c/numeric%2Fmath%2Fabs.html | 53 ++++ devdocs/c/numeric%2Fmath%2Facos.html | 99 +++++++ devdocs/c/numeric%2Fmath%2Facosh.html | 87 ++++++ devdocs/c/numeric%2Fmath%2Fasin.html | 98 ++++++ devdocs/c/numeric%2Fmath%2Fasinh.html | 59 ++++ devdocs/c/numeric%2Fmath%2Fatan.html | 79 +++++ devdocs/c/numeric%2Fmath%2Fatan2.html | 103 +++++++ devdocs/c/numeric%2Fmath%2Fatanh.html | 84 ++++++ devdocs/c/numeric%2Fmath%2Fcbrt.html | 71 +++++ devdocs/c/numeric%2Fmath%2Fceil.html | 74 +++++ devdocs/c/numeric%2Fmath%2Fcopysign.html | 51 ++++ devdocs/c/numeric%2Fmath%2Fcos.html | 103 +++++++ devdocs/c/numeric%2Fmath%2Fcosh.html | 77 +++++ devdocs/c/numeric%2Fmath%2Fcospi.html | 77 +++++ devdocs/c/numeric%2Fmath%2Fdiv.html | 120 ++++++++ devdocs/c/numeric%2Fmath%2Ferf.html | 69 +++++ devdocs/c/numeric%2Fmath%2Ferfc.html | 75 +++++ devdocs/c/numeric%2Fmath%2Fexp.html | 90 ++++++ devdocs/c/numeric%2Fmath%2Fexp2.html | 77 +++++ devdocs/c/numeric%2Fmath%2Fexpm1.html | 83 ++++++ devdocs/c/numeric%2Fmath%2Ffabs.html | 96 ++++++ devdocs/c/numeric%2Fmath%2Ffdim.html | 63 ++++ devdocs/c/numeric%2Fmath%2Ffloat_t.html | 34 +++ devdocs/c/numeric%2Fmath%2Ffloor.html | 58 ++++ devdocs/c/numeric%2Fmath%2Ffma.html | 94 ++++++ devdocs/c/numeric%2Fmath%2Ffmax.html | 56 ++++ devdocs/c/numeric%2Fmath%2Ffmin.html | 50 ++++ devdocs/c/numeric%2Fmath%2Ffmod.html | 95 ++++++ devdocs/c/numeric%2Fmath%2Ffp_categories.html | 54 ++++ devdocs/c/numeric%2Fmath%2Ffpclassify.html | 52 ++++ devdocs/c/numeric%2Fmath%2Ffrexp.html | 79 +++++ devdocs/c/numeric%2Fmath%2Fhuge_val.html | 52 ++++ devdocs/c/numeric%2Fmath%2Fhypot.html | 81 +++++ devdocs/c/numeric%2Fmath%2Filogb.html | 91 ++++++ devdocs/c/numeric%2Fmath%2Finfinity.html | 33 +++ devdocs/c/numeric%2Fmath%2Fisfinite.html | 44 +++ devdocs/c/numeric%2Fmath%2Fisgreater.html | 44 +++ devdocs/c/numeric%2Fmath%2Fisgreaterequal.html | 41 +++ devdocs/c/numeric%2Fmath%2Fisinf.html | 46 +++ devdocs/c/numeric%2Fmath%2Fisless.html | 39 +++ devdocs/c/numeric%2Fmath%2Fislessequal.html | 41 +++ devdocs/c/numeric%2Fmath%2Fislessgreater.html | 43 +++ devdocs/c/numeric%2Fmath%2Fisnan.html | 51 ++++ devdocs/c/numeric%2Fmath%2Fisnormal.html | 42 +++ devdocs/c/numeric%2Fmath%2Fisunordered.html | 40 +++ devdocs/c/numeric%2Fmath%2Fldexp.html | 79 +++++ devdocs/c/numeric%2Fmath%2Flgamma.html | 85 ++++++ devdocs/c/numeric%2Fmath%2Flog.html | 84 ++++++ devdocs/c/numeric%2Fmath%2Flog10.html | 83 ++++++ devdocs/c/numeric%2Fmath%2Flog1p.html | 82 ++++++ devdocs/c/numeric%2Fmath%2Flog2.html | 85 ++++++ devdocs/c/numeric%2Fmath%2Flogb.html | 88 ++++++ devdocs/c/numeric%2Fmath%2Fmath_errhandling.html | 81 +++++ devdocs/c/numeric%2Fmath%2Fmodf.html | 78 +++++ devdocs/c/numeric%2Fmath%2Fnan.html | 74 +++++ devdocs/c/numeric%2Fmath%2Fnearbyint.html | 78 +++++ devdocs/c/numeric%2Fmath%2Fnextafter.html | 109 +++++++ devdocs/c/numeric%2Fmath%2Fpow.html | 122 ++++++++ devdocs/c/numeric%2Fmath%2Fremainder.html | 87 ++++++ devdocs/c/numeric%2Fmath%2Fremquo.html | 99 +++++++ devdocs/c/numeric%2Fmath%2Frint.html | 134 +++++++++ devdocs/c/numeric%2Fmath%2Fround.html | 124 ++++++++ devdocs/c/numeric%2Fmath%2Froundeven.html | 57 ++++ devdocs/c/numeric%2Fmath%2Fscalbn.html | 99 +++++++ devdocs/c/numeric%2Fmath%2Fsignbit.html | 35 +++ devdocs/c/numeric%2Fmath%2Fsin.html | 104 +++++++ devdocs/c/numeric%2Fmath%2Fsinh.html | 77 +++++ devdocs/c/numeric%2Fmath%2Fsinpi.html | 77 +++++ devdocs/c/numeric%2Fmath%2Fsqrt.html | 76 +++++ devdocs/c/numeric%2Fmath%2Ftan.html | 106 +++++++ devdocs/c/numeric%2Fmath%2Ftanh.html | 60 ++++ devdocs/c/numeric%2Fmath%2Ftgamma.html | 83 ++++++ devdocs/c/numeric%2Fmath%2Ftrunc.html | 57 ++++ devdocs/c/numeric%2Fmath.html | 212 +++++++++++++ devdocs/c/numeric%2Frandom%2Frand.html | 46 +++ devdocs/c/numeric%2Frandom%2Frand_max.html | 34 +++ devdocs/c/numeric%2Frandom%2Fsrand.html | 38 +++ devdocs/c/numeric%2Frandom.html | 20 ++ devdocs/c/numeric%2Ftgmath.html | 138 +++++++++ devdocs/c/numeric.html | 31 ++ devdocs/c/preprocessor%2Fconditional.html | 89 ++++++ devdocs/c/preprocessor%2Fembed.html | 112 +++++++ devdocs/c/preprocessor%2Ferror.html | 37 +++ devdocs/c/preprocessor%2Fimpl.html | 82 ++++++ devdocs/c/preprocessor%2Finclude.html | 72 +++++ devdocs/c/preprocessor%2Fline.html | 37 +++ devdocs/c/preprocessor%2Freplace.html | 160 ++++++++++ devdocs/c/preprocessor.html | 36 +++ devdocs/c/program%2F_exit.html | 48 +++ devdocs/c/program%2Fabort.html | 45 +++ devdocs/c/program%2Fat_quick_exit.html | 45 +++ devdocs/c/program%2Fatexit.html | 50 ++++ devdocs/c/program%2Fexit.html | 51 ++++ devdocs/c/program%2Fexit_status.html | 41 +++ devdocs/c/program%2Fgetenv.html | 62 ++++ devdocs/c/program%2Fjmp_buf.html | 20 ++ devdocs/c/program%2Flongjmp.html | 64 ++++ devdocs/c/program%2Fquick_exit.html | 52 ++++ devdocs/c/program%2Fraise.html | 43 +++ devdocs/c/program%2Fsetjmp.html | 56 ++++ devdocs/c/program%2Fsig_atomic_t.html | 41 +++ devdocs/c/program%2Fsig_err.html | 49 +++ devdocs/c/program%2Fsig_strategies.html | 41 +++ devdocs/c/program%2Fsig_types.html | 32 ++ devdocs/c/program%2Fsignal.html | 78 +++++ devdocs/c/program%2Fsystem.html | 33 +++ devdocs/c/program%2Funreachable.html | 79 +++++ devdocs/c/program.html | 73 +++++ devdocs/c/string%2Fbyte%2Fatof.html | 73 +++++ devdocs/c/string%2Fbyte%2Fatoi.html | 60 ++++ devdocs/c/string%2Fbyte%2Fisalnum.html | 124 ++++++++ devdocs/c/string%2Fbyte%2Fisalpha.html | 121 ++++++++ devdocs/c/string%2Fbyte%2Fisblank.html | 112 +++++++ devdocs/c/string%2Fbyte%2Fiscntrl.html | 118 ++++++++ devdocs/c/string%2Fbyte%2Fisdigit.html | 115 ++++++++ devdocs/c/string%2Fbyte%2Fisgraph.html | 118 ++++++++ devdocs/c/string%2Fbyte%2Fislower.html | 119 ++++++++ devdocs/c/string%2Fbyte%2Fisprint.html | 116 ++++++++ devdocs/c/string%2Fbyte%2Fispunct.html | 118 ++++++++ devdocs/c/string%2Fbyte%2Fisspace.html | 127 ++++++++ devdocs/c/string%2Fbyte%2Fisupper.html | 119 ++++++++ devdocs/c/string%2Fbyte%2Fisxdigit.html | 116 ++++++++ devdocs/c/string%2Fbyte%2Fmemccpy.html | 106 +++++++ devdocs/c/string%2Fbyte%2Fmemchr.html | 51 ++++ devdocs/c/string%2Fbyte%2Fmemcmp.html | 57 ++++ devdocs/c/string%2Fbyte%2Fmemcpy.html | 94 ++++++ devdocs/c/string%2Fbyte%2Fmemmove.html | 93 ++++++ devdocs/c/string%2Fbyte%2Fmemset.html | 73 +++++ devdocs/c/string%2Fbyte%2Fstrcat.html | 76 +++++ devdocs/c/string%2Fbyte%2Fstrchr.html | 45 +++ devdocs/c/string%2Fbyte%2Fstrcmp.html | 50 ++++ devdocs/c/string%2Fbyte%2Fstrcoll.html | 60 ++++ devdocs/c/string%2Fbyte%2Fstrcpy.html | 82 ++++++ devdocs/c/string%2Fbyte%2Fstrcspn.html | 39 +++ devdocs/c/string%2Fbyte%2Fstrdup.html | 30 ++ devdocs/c/string%2Fbyte%2Fstrerror.html | 67 +++++ devdocs/c/string%2Fbyte%2Fstrfromf.html | 24 ++ devdocs/c/string%2Fbyte%2Fstrlen.html | 49 +++ devdocs/c/string%2Fbyte%2Fstrncat.html | 93 ++++++ devdocs/c/string%2Fbyte%2Fstrncmp.html | 58 ++++ devdocs/c/string%2Fbyte%2Fstrncpy.html | 101 +++++++ devdocs/c/string%2Fbyte%2Fstrndup.html | 46 +++ devdocs/c/string%2Fbyte%2Fstrpbrk.html | 49 +++ devdocs/c/string%2Fbyte%2Fstrrchr.html | 39 +++ devdocs/c/string%2Fbyte%2Fstrspn.html | 38 +++ devdocs/c/string%2Fbyte%2Fstrstr.html | 56 ++++ devdocs/c/string%2Fbyte%2Fstrtof.html | 90 ++++++ devdocs/c/string%2Fbyte%2Fstrtoimax.html | 78 +++++ devdocs/c/string%2Fbyte%2Fstrtok.html | 108 +++++++ devdocs/c/string%2Fbyte%2Fstrtol.html | 105 +++++++ devdocs/c/string%2Fbyte%2Fstrtoul.html | 75 +++++ devdocs/c/string%2Fbyte%2Fstrxfrm.html | 65 ++++ devdocs/c/string%2Fbyte%2Ftolower.html | 49 +++ devdocs/c/string%2Fbyte%2Ftoupper.html | 49 +++ devdocs/c/string%2Fbyte.html | 203 +++++++++++++ devdocs/c/string%2Fmultibyte%2Fbtowc.html | 57 ++++ devdocs/c/string%2Fmultibyte%2Fc16rtomb.html | 67 +++++ devdocs/c/string%2Fmultibyte%2Fc32rtomb.html | 60 ++++ devdocs/c/string%2Fmultibyte%2Fc8rtomb.html | 23 ++ devdocs/c/string%2Fmultibyte%2Fchar16_t.html | 35 +++ devdocs/c/string%2Fmultibyte%2Fchar32_t.html | 35 +++ devdocs/c/string%2Fmultibyte%2Fchar8_t.html | 24 ++ devdocs/c/string%2Fmultibyte%2Fmblen.html | 73 +++++ devdocs/c/string%2Fmultibyte%2Fmbrlen.html | 58 ++++ devdocs/c/string%2Fmultibyte%2Fmbrtoc16.html | 76 +++++ devdocs/c/string%2Fmultibyte%2Fmbrtoc32.html | 77 +++++ devdocs/c/string%2Fmultibyte%2Fmbrtoc8.html | 29 ++ devdocs/c/string%2Fmultibyte%2Fmbrtowc.html | 67 +++++ devdocs/c/string%2Fmultibyte%2Fmbsinit.html | 50 ++++ devdocs/c/string%2Fmultibyte%2Fmbsrtowcs.html | 79 +++++ devdocs/c/string%2Fmultibyte%2Fmbstate_t.html | 18 ++ devdocs/c/string%2Fmultibyte%2Fmbstowcs.html | 78 +++++ devdocs/c/string%2Fmultibyte%2Fmbtowc.html | 56 ++++ devdocs/c/string%2Fmultibyte%2Fwcrtomb.html | 84 ++++++ devdocs/c/string%2Fmultibyte%2Fwcsrtombs.html | 83 ++++++ devdocs/c/string%2Fmultibyte%2Fwcstombs.html | 104 +++++++ devdocs/c/string%2Fmultibyte%2Fwctob.html | 54 ++++ devdocs/c/string%2Fmultibyte%2Fwctomb.html | 82 ++++++ devdocs/c/string%2Fmultibyte.html | 90 ++++++ devdocs/c/string%2Fwide%2Fiswalnum.html | 116 ++++++++ devdocs/c/string%2Fwide%2Fiswalpha.html | 116 ++++++++ devdocs/c/string%2Fwide%2Fiswblank.html | 117 ++++++++ devdocs/c/string%2Fwide%2Fiswcntrl.html | 116 ++++++++ devdocs/c/string%2Fwide%2Fiswctype.html | 46 +++ devdocs/c/string%2Fwide%2Fiswdigit.html | 145 +++++++++ devdocs/c/string%2Fwide%2Fiswgraph.html | 116 ++++++++ devdocs/c/string%2Fwide%2Fiswlower.html | 116 ++++++++ devdocs/c/string%2Fwide%2Fiswprint.html | 119 ++++++++ devdocs/c/string%2Fwide%2Fiswpunct.html | 116 ++++++++ devdocs/c/string%2Fwide%2Fiswspace.html | 116 ++++++++ devdocs/c/string%2Fwide%2Fiswupper.html | 116 ++++++++ devdocs/c/string%2Fwide%2Fiswxdigit.html | 145 +++++++++ devdocs/c/string%2Fwide%2Ftowctrans.html | 39 +++ devdocs/c/string%2Fwide%2Ftowlower.html | 39 +++ devdocs/c/string%2Fwide%2Ftowupper.html | 35 +++ devdocs/c/string%2Fwide%2Fwcscat.html | 62 ++++ devdocs/c/string%2Fwide%2Fwcschr.html | 50 ++++ devdocs/c/string%2Fwide%2Fwcscmp.html | 55 ++++ devdocs/c/string%2Fwide%2Fwcscoll.html | 58 ++++ devdocs/c/string%2Fwide%2Fwcscpy.html | 70 +++++ devdocs/c/string%2Fwide%2Fwcscspn.html | 39 +++ devdocs/c/string%2Fwide%2Fwcslen.html | 38 +++ devdocs/c/string%2Fwide%2Fwcsncat.html | 67 +++++ devdocs/c/string%2Fwide%2Fwcsncmp.html | 56 ++++ devdocs/c/string%2Fwide%2Fwcsncpy.html | 76 +++++ devdocs/c/string%2Fwide%2Fwcspbrk.html | 47 +++ devdocs/c/string%2Fwide%2Fwcsrchr.html | 51 ++++ devdocs/c/string%2Fwide%2Fwcsspn.html | 37 +++ devdocs/c/string%2Fwide%2Fwcsstr.html | 50 ++++ devdocs/c/string%2Fwide%2Fwcstof.html | 77 +++++ devdocs/c/string%2Fwide%2Fwcstoimax.html | 69 +++++ devdocs/c/string%2Fwide%2Fwcstok.html | 80 +++++ devdocs/c/string%2Fwide%2Fwcstol.html | 65 ++++ devdocs/c/string%2Fwide%2Fwcstoul.html | 65 ++++ devdocs/c/string%2Fwide%2Fwcsxfrm.html | 59 ++++ devdocs/c/string%2Fwide%2Fwctrans.html | 27 ++ devdocs/c/string%2Fwide%2Fwctype.html | 36 +++ devdocs/c/string%2Fwide%2Fwmemchr.html | 51 ++++ devdocs/c/string%2Fwide%2Fwmemcmp.html | 68 +++++ devdocs/c/string%2Fwide%2Fwmemcpy.html | 69 +++++ devdocs/c/string%2Fwide%2Fwmemmove.html | 66 +++++ devdocs/c/string%2Fwide%2Fwmemset.html | 45 +++ devdocs/c/string%2Fwide.html | 231 +++++++++++++++ devdocs/c/string.html | 10 + devdocs/c/thread%2Fcall_once.html | 55 ++++ devdocs/c/thread%2Fcnd_broadcast.html | 20 ++ devdocs/c/thread%2Fcnd_destroy.html | 19 ++ devdocs/c/thread%2Fcnd_init.html | 18 ++ devdocs/c/thread%2Fcnd_signal.html | 20 ++ devdocs/c/thread%2Fcnd_timedwait.html | 24 ++ devdocs/c/thread%2Fcnd_wait.html | 22 ++ devdocs/c/thread%2Fmtx_destroy.html | 21 ++ devdocs/c/thread%2Fmtx_init.html | 31 ++ devdocs/c/thread%2Fmtx_lock.html | 28 ++ devdocs/c/thread%2Fmtx_timedlock.html | 35 +++ devdocs/c/thread%2Fmtx_trylock.html | 33 +++ devdocs/c/thread%2Fmtx_types.html | 23 ++ devdocs/c/thread%2Fmtx_unlock.html | 28 ++ devdocs/c/thread%2Fthrd_create.html | 29 ++ devdocs/c/thread%2Fthrd_current.html | 16 + devdocs/c/thread%2Fthrd_detach.html | 19 ++ devdocs/c/thread%2Fthrd_equal.html | 17 ++ devdocs/c/thread%2Fthrd_errors.html | 25 ++ devdocs/c/thread%2Fthrd_exit.html | 25 ++ devdocs/c/thread%2Fthrd_join.html | 25 ++ devdocs/c/thread%2Fthrd_sleep.html | 36 +++ devdocs/c/thread%2Fthrd_yield.html | 52 ++++ devdocs/c/thread%2Fthread_local.html | 15 + devdocs/c/thread%2Ftss_create.html | 27 ++ devdocs/c/thread%2Ftss_delete.html | 21 ++ devdocs/c/thread%2Ftss_dtor_iterations.html | 14 + devdocs/c/thread%2Ftss_get.html | 20 ++ devdocs/c/thread%2Ftss_set.html | 29 ++ devdocs/c/thread.html | 205 +++++++++++++ devdocs/c/types%2Finteger.html | 140 +++++++++ devdocs/c/types%2Flimits%2Fflt_eval_method.html | 19 ++ devdocs/c/types%2Flimits%2Fflt_rounds.html | 21 ++ devdocs/c/types%2Flimits.html | 218 ++++++++++++++ devdocs/c/types%2Fmax_align_t.html | 34 +++ devdocs/c/types%2Fnull.html | 47 +++ devdocs/c/types%2Fnullptr_t.html | 32 ++ devdocs/c/types%2Foffsetof.html | 39 +++ devdocs/c/types%2Fptrdiff_t.html | 56 ++++ devdocs/c/types%2Fsize_t.html | 49 +++ devdocs/c/types.html | 87 ++++++ devdocs/c/variadic%2Fva_arg.html | 54 ++++ devdocs/c/variadic%2Fva_copy.html | 56 ++++ devdocs/c/variadic%2Fva_end.html | 25 ++ devdocs/c/variadic%2Fva_list.html | 23 ++ devdocs/c/variadic%2Fva_start.html | 77 +++++ devdocs/c/variadic.html | 62 ++++ 597 files changed, 39040 insertions(+) create mode 100644 devdocs/c/11.html create mode 100644 devdocs/c/17.html create mode 100644 devdocs/c/23.html create mode 100644 devdocs/c/95.html create mode 100644 devdocs/c/99.html create mode 100644 devdocs/c/algorithm%2Fbsearch.html create mode 100644 devdocs/c/algorithm%2Fqsort.html create mode 100644 devdocs/c/algorithm.html create mode 100644 devdocs/c/atomic%2Fatomic_compare_exchange.html create mode 100644 devdocs/c/atomic%2Fatomic_exchange.html create mode 100644 devdocs/c/atomic%2Fatomic_fetch_add.html create mode 100644 devdocs/c/atomic%2Fatomic_fetch_and.html create mode 100644 devdocs/c/atomic%2Fatomic_fetch_or.html create mode 100644 devdocs/c/atomic%2Fatomic_fetch_sub.html create mode 100644 devdocs/c/atomic%2Fatomic_fetch_xor.html create mode 100644 devdocs/c/atomic%2Fatomic_flag.html create mode 100644 devdocs/c/atomic%2Fatomic_flag_clear.html create mode 100644 devdocs/c/atomic%2Fatomic_flag_init.html create mode 100644 devdocs/c/atomic%2Fatomic_flag_test_and_set.html create mode 100644 devdocs/c/atomic%2Fatomic_init.html create mode 100644 devdocs/c/atomic%2Fatomic_is_lock_free.html create mode 100644 devdocs/c/atomic%2Fatomic_load.html create mode 100644 devdocs/c/atomic%2Fatomic_lock_free_consts.html create mode 100644 devdocs/c/atomic%2Fatomic_signal_fence.html create mode 100644 devdocs/c/atomic%2Fatomic_store.html create mode 100644 devdocs/c/atomic%2Fatomic_thread_fence.html create mode 100644 devdocs/c/atomic%2Fatomic_var_init.html create mode 100644 devdocs/c/atomic%2Fkill_dependency.html create mode 100644 devdocs/c/atomic%2Fmemory_order.html create mode 100644 devdocs/c/atomic.html create mode 100644 devdocs/c/chrono%2Fasctime.html create mode 100644 devdocs/c/chrono%2Fclock.html create mode 100644 devdocs/c/chrono%2Fclock_t.html create mode 100644 devdocs/c/chrono%2Fclocks_per_sec.html create mode 100644 devdocs/c/chrono%2Fctime.html create mode 100644 devdocs/c/chrono%2Fdifftime.html create mode 100644 devdocs/c/chrono%2Fgmtime.html create mode 100644 devdocs/c/chrono%2Flocaltime.html create mode 100644 devdocs/c/chrono%2Fmktime.html create mode 100644 devdocs/c/chrono%2Fstrftime.html create mode 100644 devdocs/c/chrono%2Ftime.html create mode 100644 devdocs/c/chrono%2Ftime_t.html create mode 100644 devdocs/c/chrono%2Ftimespec.html create mode 100644 devdocs/c/chrono%2Ftimespec_get.html create mode 100644 devdocs/c/chrono%2Ftimespec_getres.html create mode 100644 devdocs/c/chrono%2Ftm.html create mode 100644 devdocs/c/chrono%2Fwcsftime.html create mode 100644 devdocs/c/chrono.html create mode 100644 devdocs/c/comment.html create mode 100644 devdocs/c/current_status.html create mode 100644 devdocs/c/error%2Fabort_handler_s.html create mode 100644 devdocs/c/error%2Fassert.html create mode 100644 devdocs/c/error%2Ferrno.html create mode 100644 devdocs/c/error%2Ferrno_macros.html create mode 100644 devdocs/c/error%2Fignore_handler_s.html create mode 100644 devdocs/c/error%2Fset_constraint_handler_s.html create mode 100644 devdocs/c/error%2Fstatic_assert.html create mode 100644 devdocs/c/error.html create mode 100644 devdocs/c/index create mode 100644 devdocs/c/index.html create mode 100644 devdocs/c/io%2Fclearerr.html create mode 100644 devdocs/c/io%2Ffclose.html create mode 100644 devdocs/c/io%2Ffeof.html create mode 100644 devdocs/c/io%2Fferror.html create mode 100644 devdocs/c/io%2Ffflush.html create mode 100644 devdocs/c/io%2Ffgetc.html create mode 100644 devdocs/c/io%2Ffgetpos.html create mode 100644 devdocs/c/io%2Ffgets.html create mode 100644 devdocs/c/io%2Ffgetwc.html create mode 100644 devdocs/c/io%2Ffgetws.html create mode 100644 devdocs/c/io%2Ffile.html create mode 100644 devdocs/c/io%2Ffopen.html create mode 100644 devdocs/c/io%2Ffpos_t.html create mode 100644 devdocs/c/io%2Ffprintf.html create mode 100644 devdocs/c/io%2Ffputc.html create mode 100644 devdocs/c/io%2Ffputs.html create mode 100644 devdocs/c/io%2Ffputwc.html create mode 100644 devdocs/c/io%2Ffputws.html create mode 100644 devdocs/c/io%2Ffread.html create mode 100644 devdocs/c/io%2Ffreopen.html create mode 100644 devdocs/c/io%2Ffscanf.html create mode 100644 devdocs/c/io%2Ffseek.html create mode 100644 devdocs/c/io%2Ffsetpos.html create mode 100644 devdocs/c/io%2Fftell.html create mode 100644 devdocs/c/io%2Ffwide.html create mode 100644 devdocs/c/io%2Ffwprintf.html create mode 100644 devdocs/c/io%2Ffwrite.html create mode 100644 devdocs/c/io%2Ffwscanf.html create mode 100644 devdocs/c/io%2Fgetchar.html create mode 100644 devdocs/c/io%2Fgets.html create mode 100644 devdocs/c/io%2Fgetwchar.html create mode 100644 devdocs/c/io%2Fperror.html create mode 100644 devdocs/c/io%2Fputchar.html create mode 100644 devdocs/c/io%2Fputs.html create mode 100644 devdocs/c/io%2Fputwchar.html create mode 100644 devdocs/c/io%2Fremove.html create mode 100644 devdocs/c/io%2Frename.html create mode 100644 devdocs/c/io%2Frewind.html create mode 100644 devdocs/c/io%2Fsetbuf.html create mode 100644 devdocs/c/io%2Fsetvbuf.html create mode 100644 devdocs/c/io%2Fstd_streams.html create mode 100644 devdocs/c/io%2Ftmpfile.html create mode 100644 devdocs/c/io%2Ftmpnam.html create mode 100644 devdocs/c/io%2Fungetc.html create mode 100644 devdocs/c/io%2Fungetwc.html create mode 100644 devdocs/c/io%2Fvfprintf.html create mode 100644 devdocs/c/io%2Fvfscanf.html create mode 100644 devdocs/c/io%2Fvfwprintf.html create mode 100644 devdocs/c/io%2Fvfwscanf.html create mode 100644 devdocs/c/io.html create mode 100644 devdocs/c/keyword%2F_alignas.html create mode 100644 devdocs/c/keyword%2F_alignof.html create mode 100644 devdocs/c/keyword%2F_atomic.html create mode 100644 devdocs/c/keyword%2F_bool.html create mode 100644 devdocs/c/keyword%2F_complex.html create mode 100644 devdocs/c/keyword%2F_decimal128.html create mode 100644 devdocs/c/keyword%2F_decimal32.html create mode 100644 devdocs/c/keyword%2F_decimal64.html create mode 100644 devdocs/c/keyword%2F_generic.html create mode 100644 devdocs/c/keyword%2F_imaginary.html create mode 100644 devdocs/c/keyword%2F_noreturn.html create mode 100644 devdocs/c/keyword%2F_static_assert.html create mode 100644 devdocs/c/keyword%2F_thread_local.html create mode 100644 devdocs/c/keyword%2Falignas.html create mode 100644 devdocs/c/keyword%2Falignof.html create mode 100644 devdocs/c/keyword%2Fauto.html create mode 100644 devdocs/c/keyword%2Fbool.html create mode 100644 devdocs/c/keyword%2Fbreak.html create mode 100644 devdocs/c/keyword%2Fcase.html create mode 100644 devdocs/c/keyword%2Fchar.html create mode 100644 devdocs/c/keyword%2Fconst.html create mode 100644 devdocs/c/keyword%2Fconstexpr.html create mode 100644 devdocs/c/keyword%2Fcontinue.html create mode 100644 devdocs/c/keyword%2Fdefault.html create mode 100644 devdocs/c/keyword%2Fdo.html create mode 100644 devdocs/c/keyword%2Fdouble.html create mode 100644 devdocs/c/keyword%2Felse.html create mode 100644 devdocs/c/keyword%2Fenum.html create mode 100644 devdocs/c/keyword%2Fextern.html create mode 100644 devdocs/c/keyword%2Ffalse.html create mode 100644 devdocs/c/keyword%2Ffloat.html create mode 100644 devdocs/c/keyword%2Ffor.html create mode 100644 devdocs/c/keyword%2Ffortran.html create mode 100644 devdocs/c/keyword%2Fgoto.html create mode 100644 devdocs/c/keyword%2Fif.html create mode 100644 devdocs/c/keyword%2Finline.html create mode 100644 devdocs/c/keyword%2Fint.html create mode 100644 devdocs/c/keyword%2Flong.html create mode 100644 devdocs/c/keyword%2Fnullptr.html create mode 100644 devdocs/c/keyword%2Fregister.html create mode 100644 devdocs/c/keyword%2Frestrict.html create mode 100644 devdocs/c/keyword%2Freturn.html create mode 100644 devdocs/c/keyword%2Fshort.html create mode 100644 devdocs/c/keyword%2Fsigned.html create mode 100644 devdocs/c/keyword%2Fsizeof.html create mode 100644 devdocs/c/keyword%2Fstatic.html create mode 100644 devdocs/c/keyword%2Fstatic_assert.html create mode 100644 devdocs/c/keyword%2Fstruct.html create mode 100644 devdocs/c/keyword%2Fswitch.html create mode 100644 devdocs/c/keyword%2Fthread_local.html create mode 100644 devdocs/c/keyword%2Ftrue.html create mode 100644 devdocs/c/keyword%2Ftypedef.html create mode 100644 devdocs/c/keyword%2Ftypeof.html create mode 100644 devdocs/c/keyword%2Ftypeof_unqual.html create mode 100644 devdocs/c/keyword%2Funion.html create mode 100644 devdocs/c/keyword%2Funsigned.html create mode 100644 devdocs/c/keyword%2Fvoid.html create mode 100644 devdocs/c/keyword%2Fvolatile.html create mode 100644 devdocs/c/keyword%2Fwhile.html create mode 100644 devdocs/c/keyword.html create mode 100644 devdocs/c/language%2F_alignas.html create mode 100644 devdocs/c/language%2F_alignof.html create mode 100644 devdocs/c/language%2F_noreturn.html create mode 100644 devdocs/c/language%2F_static_assert.html create mode 100644 devdocs/c/language%2Falignas.html create mode 100644 devdocs/c/language%2Falignof.html create mode 100644 devdocs/c/language%2Fanalyzability.html create mode 100644 devdocs/c/language%2Farithmetic_types.html create mode 100644 devdocs/c/language%2Farray.html create mode 100644 devdocs/c/language%2Farray_initialization.html create mode 100644 devdocs/c/language%2Fas_if.html create mode 100644 devdocs/c/language%2Fascii.html create mode 100644 devdocs/c/language%2Fasm.html create mode 100644 devdocs/c/language%2Fatomic.html create mode 100644 devdocs/c/language%2Fattributes%2Fdeprecated.html create mode 100644 devdocs/c/language%2Fattributes%2Ffallthrough.html create mode 100644 devdocs/c/language%2Fattributes%2Fmaybe_unused.html create mode 100644 devdocs/c/language%2Fattributes%2Fnodiscard.html create mode 100644 devdocs/c/language%2Fattributes%2Fnoreturn.html create mode 100644 devdocs/c/language%2Fattributes%2Freproducible.html create mode 100644 devdocs/c/language%2Fattributes%2Funsequenced.html create mode 100644 devdocs/c/language%2Fattributes.html create mode 100644 devdocs/c/language%2Fbasic_concepts.html create mode 100644 devdocs/c/language%2Fbehavior.html create mode 100644 devdocs/c/language%2Fbit_field.html create mode 100644 devdocs/c/language%2Fbool_constant.html create mode 100644 devdocs/c/language%2Fbreak.html create mode 100644 devdocs/c/language%2Fcast.html create mode 100644 devdocs/c/language%2Fcharacter_constant.html create mode 100644 devdocs/c/language%2Fcharset.html create mode 100644 devdocs/c/language%2Fcompatible_type.html create mode 100644 devdocs/c/language%2Fcompound_literal.html create mode 100644 devdocs/c/language%2Fconformance.html create mode 100644 devdocs/c/language%2Fconst.html create mode 100644 devdocs/c/language%2Fconstant_expression.html create mode 100644 devdocs/c/language%2Fconstexpr.html create mode 100644 devdocs/c/language%2Fcontinue.html create mode 100644 devdocs/c/language%2Fconversion.html create mode 100644 devdocs/c/language%2Fdeclarations.html create mode 100644 devdocs/c/language%2Fdo.html create mode 100644 devdocs/c/language%2Fenum.html create mode 100644 devdocs/c/language%2Fescape.html create mode 100644 devdocs/c/language%2Feval_order.html create mode 100644 devdocs/c/language%2Fexpressions.html create mode 100644 devdocs/c/language%2Fextern.html create mode 100644 devdocs/c/language%2Ffile_scope.html create mode 100644 devdocs/c/language%2Ffloating_constant.html create mode 100644 devdocs/c/language%2Ffor.html create mode 100644 devdocs/c/language%2Ffunction_declaration.html create mode 100644 devdocs/c/language%2Ffunction_definition.html create mode 100644 devdocs/c/language%2Ffunctions.html create mode 100644 devdocs/c/language%2Fgeneric.html create mode 100644 devdocs/c/language%2Fgoto.html create mode 100644 devdocs/c/language%2Fhistory.html create mode 100644 devdocs/c/language%2Fidentifier.html create mode 100644 devdocs/c/language%2Fif.html create mode 100644 devdocs/c/language%2Finitialization.html create mode 100644 devdocs/c/language%2Finline.html create mode 100644 devdocs/c/language%2Finteger_constant.html create mode 100644 devdocs/c/language%2Flifetime.html create mode 100644 devdocs/c/language%2Fmain_function.html create mode 100644 devdocs/c/language%2Fmemory_model.html create mode 100644 devdocs/c/language%2Fname_space.html create mode 100644 devdocs/c/language%2Fnullptr.html create mode 100644 devdocs/c/language%2Fobject.html create mode 100644 devdocs/c/language%2Foperator_alternative.html create mode 100644 devdocs/c/language%2Foperator_arithmetic.html create mode 100644 devdocs/c/language%2Foperator_assignment.html create mode 100644 devdocs/c/language%2Foperator_comparison.html create mode 100644 devdocs/c/language%2Foperator_incdec.html create mode 100644 devdocs/c/language%2Foperator_logical.html create mode 100644 devdocs/c/language%2Foperator_member_access.html create mode 100644 devdocs/c/language%2Foperator_other.html create mode 100644 devdocs/c/language%2Foperator_precedence.html create mode 100644 devdocs/c/language%2Fpointer.html create mode 100644 devdocs/c/language%2Fpunctuators.html create mode 100644 devdocs/c/language%2Frestrict.html create mode 100644 devdocs/c/language%2Freturn.html create mode 100644 devdocs/c/language%2Fscalar_initialization.html create mode 100644 devdocs/c/language%2Fscope.html create mode 100644 devdocs/c/language%2Fsizeof.html create mode 100644 devdocs/c/language%2Fstatements.html create mode 100644 devdocs/c/language%2Fstatic_assert.html create mode 100644 devdocs/c/language%2Fstatic_storage_duration.html create mode 100644 devdocs/c/language%2Fstorage_duration.html create mode 100644 devdocs/c/language%2Fstring_literal.html create mode 100644 devdocs/c/language%2Fstruct.html create mode 100644 devdocs/c/language%2Fstruct_initialization.html create mode 100644 devdocs/c/language%2Fswitch.html create mode 100644 devdocs/c/language%2Fthread_storage_duration.html create mode 100644 devdocs/c/language%2Ftranslation_phases.html create mode 100644 devdocs/c/language%2Ftype.html create mode 100644 devdocs/c/language%2Ftypedef.html create mode 100644 devdocs/c/language%2Ftypeof.html create mode 100644 devdocs/c/language%2Ftypes.html create mode 100644 devdocs/c/language%2Funion.html create mode 100644 devdocs/c/language%2Fvalue_category.html create mode 100644 devdocs/c/language%2Fvariadic.html create mode 100644 devdocs/c/language%2Fvolatile.html create mode 100644 devdocs/c/language%2Fwhile.html create mode 100644 devdocs/c/language.html create mode 100644 devdocs/c/locale%2Flc_categories.html create mode 100644 devdocs/c/locale%2Flconv.html create mode 100644 devdocs/c/locale%2Flocaleconv.html create mode 100644 devdocs/c/locale%2Fsetlocale.html create mode 100644 devdocs/c/locale.html create mode 100644 devdocs/c/memory%2Faligned_alloc.html create mode 100644 devdocs/c/memory%2Fcalloc.html create mode 100644 devdocs/c/memory%2Ffree.html create mode 100644 devdocs/c/memory%2Ffree_aligned_sized.html create mode 100644 devdocs/c/memory%2Ffree_sized.html create mode 100644 devdocs/c/memory%2Fmalloc.html create mode 100644 devdocs/c/memory%2Frealloc.html create mode 100644 devdocs/c/memory.html create mode 100644 devdocs/c/metadata create mode 100644 devdocs/c/numeric%2Fcomplex%2Fcabs.html create mode 100644 devdocs/c/numeric%2Fcomplex%2Fcacos.html create mode 100644 devdocs/c/numeric%2Fcomplex%2Fcacosh.html create mode 100644 devdocs/c/numeric%2Fcomplex%2Fcarg.html create mode 100644 devdocs/c/numeric%2Fcomplex%2Fcasin.html create mode 100644 devdocs/c/numeric%2Fcomplex%2Fcasinh.html create mode 100644 devdocs/c/numeric%2Fcomplex%2Fcatan.html create mode 100644 devdocs/c/numeric%2Fcomplex%2Fcatanh.html create mode 100644 devdocs/c/numeric%2Fcomplex%2Fccos.html create mode 100644 devdocs/c/numeric%2Fcomplex%2Fccosh.html create mode 100644 devdocs/c/numeric%2Fcomplex%2Fcexp.html create mode 100644 devdocs/c/numeric%2Fcomplex%2Fcimag.html create mode 100644 devdocs/c/numeric%2Fcomplex%2Fclog.html create mode 100644 devdocs/c/numeric%2Fcomplex%2Fcmplx.html create mode 100644 devdocs/c/numeric%2Fcomplex%2Fcomplex.html create mode 100644 devdocs/c/numeric%2Fcomplex%2Fcomplex_i.html create mode 100644 devdocs/c/numeric%2Fcomplex%2Fconj.html create mode 100644 devdocs/c/numeric%2Fcomplex%2Fcpow.html create mode 100644 devdocs/c/numeric%2Fcomplex%2Fcproj.html create mode 100644 devdocs/c/numeric%2Fcomplex%2Fcreal.html create mode 100644 devdocs/c/numeric%2Fcomplex%2Fcsin.html create mode 100644 devdocs/c/numeric%2Fcomplex%2Fcsinh.html create mode 100644 devdocs/c/numeric%2Fcomplex%2Fcsqrt.html create mode 100644 devdocs/c/numeric%2Fcomplex%2Fctan.html create mode 100644 devdocs/c/numeric%2Fcomplex%2Fctanh.html create mode 100644 devdocs/c/numeric%2Fcomplex%2Fi.html create mode 100644 devdocs/c/numeric%2Fcomplex%2Fimaginary.html create mode 100644 devdocs/c/numeric%2Fcomplex%2Fimaginary_i.html create mode 100644 devdocs/c/numeric%2Fcomplex.html create mode 100644 devdocs/c/numeric%2Ffenv%2Ffe_dfl_env.html create mode 100644 devdocs/c/numeric%2Ffenv%2Ffe_exceptions.html create mode 100644 devdocs/c/numeric%2Ffenv%2Ffe_round.html create mode 100644 devdocs/c/numeric%2Ffenv%2Ffeclearexcept.html create mode 100644 devdocs/c/numeric%2Ffenv%2Ffeenv.html create mode 100644 devdocs/c/numeric%2Ffenv%2Ffeexceptflag.html create mode 100644 devdocs/c/numeric%2Ffenv%2Ffeholdexcept.html create mode 100644 devdocs/c/numeric%2Ffenv%2Fferaiseexcept.html create mode 100644 devdocs/c/numeric%2Ffenv%2Fferound.html create mode 100644 devdocs/c/numeric%2Ffenv%2Ffetestexcept.html create mode 100644 devdocs/c/numeric%2Ffenv%2Ffeupdateenv.html create mode 100644 devdocs/c/numeric%2Ffenv.html create mode 100644 devdocs/c/numeric%2Fmath%2Fabs.html create mode 100644 devdocs/c/numeric%2Fmath%2Facos.html create mode 100644 devdocs/c/numeric%2Fmath%2Facosh.html create mode 100644 devdocs/c/numeric%2Fmath%2Fasin.html create mode 100644 devdocs/c/numeric%2Fmath%2Fasinh.html create mode 100644 devdocs/c/numeric%2Fmath%2Fatan.html create mode 100644 devdocs/c/numeric%2Fmath%2Fatan2.html create mode 100644 devdocs/c/numeric%2Fmath%2Fatanh.html create mode 100644 devdocs/c/numeric%2Fmath%2Fcbrt.html create mode 100644 devdocs/c/numeric%2Fmath%2Fceil.html create mode 100644 devdocs/c/numeric%2Fmath%2Fcopysign.html create mode 100644 devdocs/c/numeric%2Fmath%2Fcos.html create mode 100644 devdocs/c/numeric%2Fmath%2Fcosh.html create mode 100644 devdocs/c/numeric%2Fmath%2Fcospi.html create mode 100644 devdocs/c/numeric%2Fmath%2Fdiv.html create mode 100644 devdocs/c/numeric%2Fmath%2Ferf.html create mode 100644 devdocs/c/numeric%2Fmath%2Ferfc.html create mode 100644 devdocs/c/numeric%2Fmath%2Fexp.html create mode 100644 devdocs/c/numeric%2Fmath%2Fexp2.html create mode 100644 devdocs/c/numeric%2Fmath%2Fexpm1.html create mode 100644 devdocs/c/numeric%2Fmath%2Ffabs.html create mode 100644 devdocs/c/numeric%2Fmath%2Ffdim.html create mode 100644 devdocs/c/numeric%2Fmath%2Ffloat_t.html create mode 100644 devdocs/c/numeric%2Fmath%2Ffloor.html create mode 100644 devdocs/c/numeric%2Fmath%2Ffma.html create mode 100644 devdocs/c/numeric%2Fmath%2Ffmax.html create mode 100644 devdocs/c/numeric%2Fmath%2Ffmin.html create mode 100644 devdocs/c/numeric%2Fmath%2Ffmod.html create mode 100644 devdocs/c/numeric%2Fmath%2Ffp_categories.html create mode 100644 devdocs/c/numeric%2Fmath%2Ffpclassify.html create mode 100644 devdocs/c/numeric%2Fmath%2Ffrexp.html create mode 100644 devdocs/c/numeric%2Fmath%2Fhuge_val.html create mode 100644 devdocs/c/numeric%2Fmath%2Fhypot.html create mode 100644 devdocs/c/numeric%2Fmath%2Filogb.html create mode 100644 devdocs/c/numeric%2Fmath%2Finfinity.html create mode 100644 devdocs/c/numeric%2Fmath%2Fisfinite.html create mode 100644 devdocs/c/numeric%2Fmath%2Fisgreater.html create mode 100644 devdocs/c/numeric%2Fmath%2Fisgreaterequal.html create mode 100644 devdocs/c/numeric%2Fmath%2Fisinf.html create mode 100644 devdocs/c/numeric%2Fmath%2Fisless.html create mode 100644 devdocs/c/numeric%2Fmath%2Fislessequal.html create mode 100644 devdocs/c/numeric%2Fmath%2Fislessgreater.html create mode 100644 devdocs/c/numeric%2Fmath%2Fisnan.html create mode 100644 devdocs/c/numeric%2Fmath%2Fisnormal.html create mode 100644 devdocs/c/numeric%2Fmath%2Fisunordered.html create mode 100644 devdocs/c/numeric%2Fmath%2Fldexp.html create mode 100644 devdocs/c/numeric%2Fmath%2Flgamma.html create mode 100644 devdocs/c/numeric%2Fmath%2Flog.html create mode 100644 devdocs/c/numeric%2Fmath%2Flog10.html create mode 100644 devdocs/c/numeric%2Fmath%2Flog1p.html create mode 100644 devdocs/c/numeric%2Fmath%2Flog2.html create mode 100644 devdocs/c/numeric%2Fmath%2Flogb.html create mode 100644 devdocs/c/numeric%2Fmath%2Fmath_errhandling.html create mode 100644 devdocs/c/numeric%2Fmath%2Fmodf.html create mode 100644 devdocs/c/numeric%2Fmath%2Fnan.html create mode 100644 devdocs/c/numeric%2Fmath%2Fnearbyint.html create mode 100644 devdocs/c/numeric%2Fmath%2Fnextafter.html create mode 100644 devdocs/c/numeric%2Fmath%2Fpow.html create mode 100644 devdocs/c/numeric%2Fmath%2Fremainder.html create mode 100644 devdocs/c/numeric%2Fmath%2Fremquo.html create mode 100644 devdocs/c/numeric%2Fmath%2Frint.html create mode 100644 devdocs/c/numeric%2Fmath%2Fround.html create mode 100644 devdocs/c/numeric%2Fmath%2Froundeven.html create mode 100644 devdocs/c/numeric%2Fmath%2Fscalbn.html create mode 100644 devdocs/c/numeric%2Fmath%2Fsignbit.html create mode 100644 devdocs/c/numeric%2Fmath%2Fsin.html create mode 100644 devdocs/c/numeric%2Fmath%2Fsinh.html create mode 100644 devdocs/c/numeric%2Fmath%2Fsinpi.html create mode 100644 devdocs/c/numeric%2Fmath%2Fsqrt.html create mode 100644 devdocs/c/numeric%2Fmath%2Ftan.html create mode 100644 devdocs/c/numeric%2Fmath%2Ftanh.html create mode 100644 devdocs/c/numeric%2Fmath%2Ftgamma.html create mode 100644 devdocs/c/numeric%2Fmath%2Ftrunc.html create mode 100644 devdocs/c/numeric%2Fmath.html create mode 100644 devdocs/c/numeric%2Frandom%2Frand.html create mode 100644 devdocs/c/numeric%2Frandom%2Frand_max.html create mode 100644 devdocs/c/numeric%2Frandom%2Fsrand.html create mode 100644 devdocs/c/numeric%2Frandom.html create mode 100644 devdocs/c/numeric%2Ftgmath.html create mode 100644 devdocs/c/numeric.html create mode 100644 devdocs/c/preprocessor%2Fconditional.html create mode 100644 devdocs/c/preprocessor%2Fembed.html create mode 100644 devdocs/c/preprocessor%2Ferror.html create mode 100644 devdocs/c/preprocessor%2Fimpl.html create mode 100644 devdocs/c/preprocessor%2Finclude.html create mode 100644 devdocs/c/preprocessor%2Fline.html create mode 100644 devdocs/c/preprocessor%2Freplace.html create mode 100644 devdocs/c/preprocessor.html create mode 100644 devdocs/c/program%2F_exit.html create mode 100644 devdocs/c/program%2Fabort.html create mode 100644 devdocs/c/program%2Fat_quick_exit.html create mode 100644 devdocs/c/program%2Fatexit.html create mode 100644 devdocs/c/program%2Fexit.html create mode 100644 devdocs/c/program%2Fexit_status.html create mode 100644 devdocs/c/program%2Fgetenv.html create mode 100644 devdocs/c/program%2Fjmp_buf.html create mode 100644 devdocs/c/program%2Flongjmp.html create mode 100644 devdocs/c/program%2Fquick_exit.html create mode 100644 devdocs/c/program%2Fraise.html create mode 100644 devdocs/c/program%2Fsetjmp.html create mode 100644 devdocs/c/program%2Fsig_atomic_t.html create mode 100644 devdocs/c/program%2Fsig_err.html create mode 100644 devdocs/c/program%2Fsig_strategies.html create mode 100644 devdocs/c/program%2Fsig_types.html create mode 100644 devdocs/c/program%2Fsignal.html create mode 100644 devdocs/c/program%2Fsystem.html create mode 100644 devdocs/c/program%2Funreachable.html create mode 100644 devdocs/c/program.html create mode 100644 devdocs/c/string%2Fbyte%2Fatof.html create mode 100644 devdocs/c/string%2Fbyte%2Fatoi.html create mode 100644 devdocs/c/string%2Fbyte%2Fisalnum.html create mode 100644 devdocs/c/string%2Fbyte%2Fisalpha.html create mode 100644 devdocs/c/string%2Fbyte%2Fisblank.html create mode 100644 devdocs/c/string%2Fbyte%2Fiscntrl.html create mode 100644 devdocs/c/string%2Fbyte%2Fisdigit.html create mode 100644 devdocs/c/string%2Fbyte%2Fisgraph.html create mode 100644 devdocs/c/string%2Fbyte%2Fislower.html create mode 100644 devdocs/c/string%2Fbyte%2Fisprint.html create mode 100644 devdocs/c/string%2Fbyte%2Fispunct.html create mode 100644 devdocs/c/string%2Fbyte%2Fisspace.html create mode 100644 devdocs/c/string%2Fbyte%2Fisupper.html create mode 100644 devdocs/c/string%2Fbyte%2Fisxdigit.html create mode 100644 devdocs/c/string%2Fbyte%2Fmemccpy.html create mode 100644 devdocs/c/string%2Fbyte%2Fmemchr.html create mode 100644 devdocs/c/string%2Fbyte%2Fmemcmp.html create mode 100644 devdocs/c/string%2Fbyte%2Fmemcpy.html create mode 100644 devdocs/c/string%2Fbyte%2Fmemmove.html create mode 100644 devdocs/c/string%2Fbyte%2Fmemset.html create mode 100644 devdocs/c/string%2Fbyte%2Fstrcat.html create mode 100644 devdocs/c/string%2Fbyte%2Fstrchr.html create mode 100644 devdocs/c/string%2Fbyte%2Fstrcmp.html create mode 100644 devdocs/c/string%2Fbyte%2Fstrcoll.html create mode 100644 devdocs/c/string%2Fbyte%2Fstrcpy.html create mode 100644 devdocs/c/string%2Fbyte%2Fstrcspn.html create mode 100644 devdocs/c/string%2Fbyte%2Fstrdup.html create mode 100644 devdocs/c/string%2Fbyte%2Fstrerror.html create mode 100644 devdocs/c/string%2Fbyte%2Fstrfromf.html create mode 100644 devdocs/c/string%2Fbyte%2Fstrlen.html create mode 100644 devdocs/c/string%2Fbyte%2Fstrncat.html create mode 100644 devdocs/c/string%2Fbyte%2Fstrncmp.html create mode 100644 devdocs/c/string%2Fbyte%2Fstrncpy.html create mode 100644 devdocs/c/string%2Fbyte%2Fstrndup.html create mode 100644 devdocs/c/string%2Fbyte%2Fstrpbrk.html create mode 100644 devdocs/c/string%2Fbyte%2Fstrrchr.html create mode 100644 devdocs/c/string%2Fbyte%2Fstrspn.html create mode 100644 devdocs/c/string%2Fbyte%2Fstrstr.html create mode 100644 devdocs/c/string%2Fbyte%2Fstrtof.html create mode 100644 devdocs/c/string%2Fbyte%2Fstrtoimax.html create mode 100644 devdocs/c/string%2Fbyte%2Fstrtok.html create mode 100644 devdocs/c/string%2Fbyte%2Fstrtol.html create mode 100644 devdocs/c/string%2Fbyte%2Fstrtoul.html create mode 100644 devdocs/c/string%2Fbyte%2Fstrxfrm.html create mode 100644 devdocs/c/string%2Fbyte%2Ftolower.html create mode 100644 devdocs/c/string%2Fbyte%2Ftoupper.html create mode 100644 devdocs/c/string%2Fbyte.html create mode 100644 devdocs/c/string%2Fmultibyte%2Fbtowc.html create mode 100644 devdocs/c/string%2Fmultibyte%2Fc16rtomb.html create mode 100644 devdocs/c/string%2Fmultibyte%2Fc32rtomb.html create mode 100644 devdocs/c/string%2Fmultibyte%2Fc8rtomb.html create mode 100644 devdocs/c/string%2Fmultibyte%2Fchar16_t.html create mode 100644 devdocs/c/string%2Fmultibyte%2Fchar32_t.html create mode 100644 devdocs/c/string%2Fmultibyte%2Fchar8_t.html create mode 100644 devdocs/c/string%2Fmultibyte%2Fmblen.html create mode 100644 devdocs/c/string%2Fmultibyte%2Fmbrlen.html create mode 100644 devdocs/c/string%2Fmultibyte%2Fmbrtoc16.html create mode 100644 devdocs/c/string%2Fmultibyte%2Fmbrtoc32.html create mode 100644 devdocs/c/string%2Fmultibyte%2Fmbrtoc8.html create mode 100644 devdocs/c/string%2Fmultibyte%2Fmbrtowc.html create mode 100644 devdocs/c/string%2Fmultibyte%2Fmbsinit.html create mode 100644 devdocs/c/string%2Fmultibyte%2Fmbsrtowcs.html create mode 100644 devdocs/c/string%2Fmultibyte%2Fmbstate_t.html create mode 100644 devdocs/c/string%2Fmultibyte%2Fmbstowcs.html create mode 100644 devdocs/c/string%2Fmultibyte%2Fmbtowc.html create mode 100644 devdocs/c/string%2Fmultibyte%2Fwcrtomb.html create mode 100644 devdocs/c/string%2Fmultibyte%2Fwcsrtombs.html create mode 100644 devdocs/c/string%2Fmultibyte%2Fwcstombs.html create mode 100644 devdocs/c/string%2Fmultibyte%2Fwctob.html create mode 100644 devdocs/c/string%2Fmultibyte%2Fwctomb.html create mode 100644 devdocs/c/string%2Fmultibyte.html create mode 100644 devdocs/c/string%2Fwide%2Fiswalnum.html create mode 100644 devdocs/c/string%2Fwide%2Fiswalpha.html create mode 100644 devdocs/c/string%2Fwide%2Fiswblank.html create mode 100644 devdocs/c/string%2Fwide%2Fiswcntrl.html create mode 100644 devdocs/c/string%2Fwide%2Fiswctype.html create mode 100644 devdocs/c/string%2Fwide%2Fiswdigit.html create mode 100644 devdocs/c/string%2Fwide%2Fiswgraph.html create mode 100644 devdocs/c/string%2Fwide%2Fiswlower.html create mode 100644 devdocs/c/string%2Fwide%2Fiswprint.html create mode 100644 devdocs/c/string%2Fwide%2Fiswpunct.html create mode 100644 devdocs/c/string%2Fwide%2Fiswspace.html create mode 100644 devdocs/c/string%2Fwide%2Fiswupper.html create mode 100644 devdocs/c/string%2Fwide%2Fiswxdigit.html create mode 100644 devdocs/c/string%2Fwide%2Ftowctrans.html create mode 100644 devdocs/c/string%2Fwide%2Ftowlower.html create mode 100644 devdocs/c/string%2Fwide%2Ftowupper.html create mode 100644 devdocs/c/string%2Fwide%2Fwcscat.html create mode 100644 devdocs/c/string%2Fwide%2Fwcschr.html create mode 100644 devdocs/c/string%2Fwide%2Fwcscmp.html create mode 100644 devdocs/c/string%2Fwide%2Fwcscoll.html create mode 100644 devdocs/c/string%2Fwide%2Fwcscpy.html create mode 100644 devdocs/c/string%2Fwide%2Fwcscspn.html create mode 100644 devdocs/c/string%2Fwide%2Fwcslen.html create mode 100644 devdocs/c/string%2Fwide%2Fwcsncat.html create mode 100644 devdocs/c/string%2Fwide%2Fwcsncmp.html create mode 100644 devdocs/c/string%2Fwide%2Fwcsncpy.html create mode 100644 devdocs/c/string%2Fwide%2Fwcspbrk.html create mode 100644 devdocs/c/string%2Fwide%2Fwcsrchr.html create mode 100644 devdocs/c/string%2Fwide%2Fwcsspn.html create mode 100644 devdocs/c/string%2Fwide%2Fwcsstr.html create mode 100644 devdocs/c/string%2Fwide%2Fwcstof.html create mode 100644 devdocs/c/string%2Fwide%2Fwcstoimax.html create mode 100644 devdocs/c/string%2Fwide%2Fwcstok.html create mode 100644 devdocs/c/string%2Fwide%2Fwcstol.html create mode 100644 devdocs/c/string%2Fwide%2Fwcstoul.html create mode 100644 devdocs/c/string%2Fwide%2Fwcsxfrm.html create mode 100644 devdocs/c/string%2Fwide%2Fwctrans.html create mode 100644 devdocs/c/string%2Fwide%2Fwctype.html create mode 100644 devdocs/c/string%2Fwide%2Fwmemchr.html create mode 100644 devdocs/c/string%2Fwide%2Fwmemcmp.html create mode 100644 devdocs/c/string%2Fwide%2Fwmemcpy.html create mode 100644 devdocs/c/string%2Fwide%2Fwmemmove.html create mode 100644 devdocs/c/string%2Fwide%2Fwmemset.html create mode 100644 devdocs/c/string%2Fwide.html create mode 100644 devdocs/c/string.html create mode 100644 devdocs/c/thread%2Fcall_once.html create mode 100644 devdocs/c/thread%2Fcnd_broadcast.html create mode 100644 devdocs/c/thread%2Fcnd_destroy.html create mode 100644 devdocs/c/thread%2Fcnd_init.html create mode 100644 devdocs/c/thread%2Fcnd_signal.html create mode 100644 devdocs/c/thread%2Fcnd_timedwait.html create mode 100644 devdocs/c/thread%2Fcnd_wait.html create mode 100644 devdocs/c/thread%2Fmtx_destroy.html create mode 100644 devdocs/c/thread%2Fmtx_init.html create mode 100644 devdocs/c/thread%2Fmtx_lock.html create mode 100644 devdocs/c/thread%2Fmtx_timedlock.html create mode 100644 devdocs/c/thread%2Fmtx_trylock.html create mode 100644 devdocs/c/thread%2Fmtx_types.html create mode 100644 devdocs/c/thread%2Fmtx_unlock.html create mode 100644 devdocs/c/thread%2Fthrd_create.html create mode 100644 devdocs/c/thread%2Fthrd_current.html create mode 100644 devdocs/c/thread%2Fthrd_detach.html create mode 100644 devdocs/c/thread%2Fthrd_equal.html create mode 100644 devdocs/c/thread%2Fthrd_errors.html create mode 100644 devdocs/c/thread%2Fthrd_exit.html create mode 100644 devdocs/c/thread%2Fthrd_join.html create mode 100644 devdocs/c/thread%2Fthrd_sleep.html create mode 100644 devdocs/c/thread%2Fthrd_yield.html create mode 100644 devdocs/c/thread%2Fthread_local.html create mode 100644 devdocs/c/thread%2Ftss_create.html create mode 100644 devdocs/c/thread%2Ftss_delete.html create mode 100644 devdocs/c/thread%2Ftss_dtor_iterations.html create mode 100644 devdocs/c/thread%2Ftss_get.html create mode 100644 devdocs/c/thread%2Ftss_set.html create mode 100644 devdocs/c/thread.html create mode 100644 devdocs/c/types%2Finteger.html create mode 100644 devdocs/c/types%2Flimits%2Fflt_eval_method.html create mode 100644 devdocs/c/types%2Flimits%2Fflt_rounds.html create mode 100644 devdocs/c/types%2Flimits.html create mode 100644 devdocs/c/types%2Fmax_align_t.html create mode 100644 devdocs/c/types%2Fnull.html create mode 100644 devdocs/c/types%2Fnullptr_t.html create mode 100644 devdocs/c/types%2Foffsetof.html create mode 100644 devdocs/c/types%2Fptrdiff_t.html create mode 100644 devdocs/c/types%2Fsize_t.html create mode 100644 devdocs/c/types.html create mode 100644 devdocs/c/variadic%2Fva_arg.html create mode 100644 devdocs/c/variadic%2Fva_copy.html create mode 100644 devdocs/c/variadic%2Fva_end.html create mode 100644 devdocs/c/variadic%2Fva_list.html create mode 100644 devdocs/c/variadic%2Fva_start.html create mode 100644 devdocs/c/variadic.html (limited to 'devdocs/c') diff --git a/devdocs/c/11.html b/devdocs/c/11.html new file mode 100644 index 00000000..b4044d37 --- /dev/null +++ b/devdocs/c/11.html @@ -0,0 +1,69 @@ +

C11

ISO/IEC 9899:2011, a.k.a. C11, is a previous revision of the C standard.

+

Obsolete

Removed

New language features

Feature test macros for optional features

New library features

New headers

Library features

Defect reports

Template:c/language/history/DR11

+

Compiler support

Template:c/compiler support/11

+
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/11 +

+
diff --git a/devdocs/c/17.html b/devdocs/c/17.html new file mode 100644 index 00000000..2cb44849 --- /dev/null +++ b/devdocs/c/17.html @@ -0,0 +1,70 @@ +

C17

ISO/IEC 9899:2018, a.k.a. C17/C18 (denote the year of completion and publication respectively), is the current revision of the C standard.

+

C17 is same as C11, except that it bumps the __STDC_VERSION__ predefined macro to 201710L, contains several defect reports, and deprecates some features.

+

Obsolete

Deprecated

Defect reports

+ + +
Defect Reports fixed in C17 (54 defects)
+
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/17 +

+
diff --git a/devdocs/c/23.html b/devdocs/c/23.html new file mode 100644 index 00000000..e3a73d0b --- /dev/null +++ b/devdocs/c/23.html @@ -0,0 +1,193 @@ +

C23

The next generation of the C standard.

+

See: The current WD of C23.

+

Obsolete

Removed

Deprecated

New language features

Feature test macros for optional features

New library features

New headers

Library features

Defect reports

+ + +
Defect Reports fixed in C23 (? defects)
+

Compiler support

C23 core language features

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
C23 feature

 Paper(s)
GCC
Clang
MSVC
Apple Clang
EDG eccp
Intel C++
IBM XL C++
IBM Open XL C++ for AIX
IBM Open XL C++ for z/OS
Sun/Oracle C++
Embarcadero C++ Builder
Cray
Nvidia HPC C++ (ex PGI)*
Nvidia nvcc
_Static_assert with no message N2265 9 9 Yes Yes 6.5 2021.1.2 (clang based)
[[nodiscard]] N2267 10 9 Yes 6.4 2021.1.2 (clang based)
[[maybe_unused]] N2270 10 9 Yes 6.4 2021.1.2 (clang based)
[[deprecated]] N2334 10 9 Yes 6.4 2021.1.2 (clang based)
Attributes N2335
N2554 		10 9 Yes 6.4 2021.1.2 (clang based)
IEEE 754 decimal floating-point types N2341 4.2 (partial)* 13.0 (partial)*
[[fallthrough]] N2408 10 9 Yes 6.4 2021.1.2 (clang based)
u8 character constants N2418 10 15 6.5 2022.2
Removal of function definitions without prototype N2432 10 15 2022.2
[[nodiscard]] with message N2448 11 10 Yes 6.4 2021.1.2 (clang based)
Unnamed parameters in function definitions N2480 11 11 Yes 6.4 2021.1.2 (clang based)
Labels before declarations and end of blocks N2508 11 16 Partial* 6.5 17.0*
Binary integer constants N2549 4.3*
11 		2.9*
9 		+19.0 (2015)** Yes 6.5 11.0*
__has_c_attribute in preprocessor conditionals N2553 11 9 Yes 6.5 2021.1.2 (clang based)
Allow duplicate attributes N2557 11 13 Yes 6.5 2021.4 (clang-based
IEEE 754 interchange and extended types N2601 7 (partial)* 6 (partial)* +Partial*
Digit separators N2626 12 13 +19.0 (2015)** Yes 6.5 18.0*
#elifdef and #elifndef N2645 12 13

13.1.6*

+		 6.5 2021.4
Type change of u8 string literals N2653
[[maybe_unused]] for labels N2662 11 16 6.5 2022.2
#warning N2686 Yes Yes Yes 6.5 Yes
Bit-precise integer types (_BitInt) N2763 15 6.5 2022.2
[[noreturn]] N2764 13 15 6.5 2022.2
Suffixes for bit-precise integer constants N2775 15 2022.2
__has_include in preprocessor conditionals N2799 5 Yes +19.11* Yes 6.5 18.0
Identifier Syntax using Unicode Standard Annex 31 N2836 13 15 6.5 2022.2
Removal of function declarations without prototype N2841 13 15 2022.2
Empty initializers N2900 Partial* Partial* Partial* Partial* Partial*
typeof and typeof_unqual N2927
N2930 		Partial*
13 		Partial*
16 		Partial* Partial* Partial* Partial*
New spelling of keywords N2934 13 16 6.5
Predefined true and false N2935 13 15 2022.2
[[unsequenced]] and [[reproducible]] N2956
Relax requirements for variadic parameter list N2975 13 16 6.5 2023.1
Type inference in object definitions N3007 13
#embed N3017
constexpr objects N3018 13
Improved Normal Enumerations N3029 13
Enhancements to Enumerations N3030 13 Maybe
__VA_OPT__ N3033 8 12 6.5
Storage-class specifiers for compound literals N3038 13
nullptr N3042 13 16


C23 feature

Paper(s)
GCC
Clang
MSVC
Apple Clang
EDG eccp
Intel C++
IBM XL C++
IBM Open XL C++ for AIX
IBM Open XL C++ for z/OS
Sun/Oracle C++
Embarcadero C++ Builder
Cray
Nvidia HPC C++ (ex PGI)*
Nvidia nvcc

C23 library features

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/23 +

+
diff --git a/devdocs/c/95.html b/devdocs/c/95.html new file mode 100644 index 00000000..32318a0a --- /dev/null +++ b/devdocs/c/95.html @@ -0,0 +1,14 @@ +

C95

ISO/IEC 9899/AMD1:1995, a.k.a. C95, is a previous revision of the C standard.

+

New language features

New library features

New headers

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/95 +

+
diff --git a/devdocs/c/99.html b/devdocs/c/99.html new file mode 100644 index 00000000..50a02097 --- /dev/null +++ b/devdocs/c/99.html @@ -0,0 +1,142 @@ +

C99

ISO/IEC 9899:1999, a.k.a. C99, is a previous revision of the C standard.

+

Obsolete

Removed

Deprecated

New language features

Feature test macros for optional features

New library features

New headers

Library features

Defect reports

Template:c/language/history/DR99

+

Compiler support

C99 core language features

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
C99 feature

 Paper(s)
GCC
Clang
MSVC
Apple Clang
EDG eccp
Intel C++
IBM XL C++
IBM Open XL C++ for AIX
IBM Open XL C++ for z/OS
Sun/Oracle C++
Embarcadero C++ Builder
Cray
Nvidia HPC C++ (ex PGI)*
Nvidia nvcc
Universal-character-names in identifiers N/A 3.1 Yes Yes
Increased translation limits N590 0.9 N/A
// comments N644 2.7 Yes Yes
restrict pointers N448 2.95 Yes partial*
Enhanced arithmetic types N815
N601
N620
N638
N657
N694
N809 		Yes partial Maybe
Flexible array members N/A 3.0 Yes Yes
Variable-length array (VLA) types N683 0.9 Yes
Variably-modified (VM) types N2778 N/A Yes
Designated initializers N494 3.0 Yes Yes
Non-constant initializers N/A 1.21 N/A
Idempotent cvr-qualifiers N505 3.0 N/A
Trailing comma in enumerator-list N/A 0.9 Yes Yes
Hexadecimal floating constants N308 2.8 Yes Yes
Compound literals N716 3.1 Yes Yes
Floating-point environment N/A partial partial
Requiring truncation for divisions of signed integer types N617 0.9 N/A
Implicit return 0; in the main() function N/A Yes Yes Yes
Declarations and statements in mixed order N740 3.0 Yes Yes
init-statement in for loops N/A Yes Yes Yes
inline functions N741 4.3 Yes Yes
Predefined variable __func__ N611 2.95 Yes Yes
Cvr-qualifiers and static in [] within function declarations N/A 3.1 Yes
Variadic macros N707 2.95 Yes Yes
_Pragma preprocessor operator N634 3.0 Yes partial*
Standard pragmas for floating-point evaluation N631
N696 		No No Yes


C99 feature

Paper(s)
GCC
Clang
MSVC
Apple Clang
EDG eccp
Intel C++
IBM XL C++
IBM Open XL C++ for AIX
IBM Open XL C++ for z/OS
Sun/Oracle C++
Embarcadero C++ Builder
Cray
Nvidia HPC C++ (ex PGI)*
Nvidia nvcc
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/99 +

+
diff --git a/devdocs/c/algorithm%2Fbsearch.html b/devdocs/c/algorithm%2Fbsearch.html new file mode 100644 index 00000000..295e3093 --- /dev/null +++ b/devdocs/c/algorithm%2Fbsearch.html @@ -0,0 +1,104 @@ +

bsearch, bsearch_s

Defined in header <stdlib.h> 
void* bsearch( const void *key, const void *ptr, size_t count, size_t size,
+               int (*comp)(const void*, const void*) );
+		 (1) 
void* bsearch_s( const void *key, const void *ptr, rsize_t count, rsize_t size,
+                 int (*comp)(const void *, const void *, void *),
+                 void *context );
+		 (2) (since C11) 
/*QVoid*/* bsearch( const void *key, /*QVoid*/ *ptr, size_t count, size_t size,
+                    int (*comp)(const void*, const void*) );
+		 (3) (since C23) 
/*QVoid*/* bsearch_s( const void *key, /*QVoid*/ *ptr, rsize_t count, rsize_t size,
+                      int (*comp)(const void *, const void *, void *),
+                      void *context );
+		 (4) (since C23)
+1) Finds an element equal to element pointed to by key in an array pointed to by ptr. The array contains count elements of size bytes and must be partitioned with respect to key, that is, all the elements that compare less than must appear before all the elements that compare equal to, and those must appear before all the elements that compare greater than the key object. A fully sorted array satisfies these requirements. The elements are compared using function pointed to by comp. The behavior is undefined if the array is not already partitioned with respect to *key in ascending order according to the same criterion that comp uses.
+2) Same as (1), except that the additional state argument context is passed to comp and that the following errors are detected at runtime and call the currently installed constraint handler function:
+
+
    +
  • count or size is greater than RSIZE_MAX
    • +
  • key, ptr or comp is a null pointer (unless count is zero)
    • +
+
As with all bounds-checked functions, bsearch_s (and the corresponding type-generic macro)(since C23) is only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <stdlib.h>.
+
+
+3,4) Type-generic macros equivalent to (1) and (2) respectively. Let T be a unqualified object type (including void). If a macro definition of each of these generic functions is suppressed to access an actual function (e.g. if (bsearch), (bsearch_s), or a function pointer is used), the actual function declaration (1) or (2) becomes visible.

If the array contains several elements that comp would indicate as equal to the element searched for, then it is unspecified which element the function will return as the result.

+ + +

Direct usages of actual functions (1) and (2) are deprecated.

+		 (since C23)

Parameters

+ + + + + + +
key - pointer to the element to search for
ptr - pointer to the array to examine
count - number of element in the array
size - size of each element in the array in bytes
comp - comparison function which returns ​a negative integer value if the first argument is less than the second, a positive integer value if the first argument is greater than the second and zero if the arguments are equivalent. key is passed as the first argument, an element from the array as the second.

The signature of the comparison function should be equivalent to the following:

+

int cmp(const void *a, const void *b);

+

The function must not modify the objects passed to it and must return consistent results when called for the same objects, regardless of their positions in the array.

+

​

+
context - state of the comparator (e.g., collating sequence), passed to comp as the third argument

Return value

+1) Pointer to an element in the array that compares equal to *key, or null pointer if such element has not been found.
+2) Same as (1), except that the null pointer is also returned on runtime constraints violations.
+3,4) Same as (1) and (2) respectively, except that cv-qualification is adjusted.

Notes

Despite the name, neither C nor POSIX standards require this function to be implemented using binary search or make any complexity guarantees.

+

Unlike other bounds-checked functions, bsearch_s does not treat arrays of zero size as a runtime constraint violation and instead indicates element not found (the other function that accepts arrays of zero size is qsort_s).

+

Until bsearch_s, users of bsearch often used global variables to represent the state of the comparator.

+

Example

#include <stdlib.h>
+#include <stdio.h>
+ 
+struct data {
+    int nr;
+    char const *value;
+} dat[] = {
+    {1, "Foo"}, {2, "Bar"}, {3, "Hello"}, {4, "World"}
+};
+ 
+int data_cmp(void const *lhs, void const *rhs) 
+{
+    struct data const *const l = lhs;
+    struct data const *const r = rhs;
+ 
+    if (l->nr < r->nr) return -1;
+    else if (l->nr > r->nr) return 1;
+    else return 0;
+ 
+    // return (l->nr > r->nr) - (l->nr < r->nr); // possible shortcut
+    // return l->nr - r->nr; // erroneous shortcut (fails if INT_MIN is present)
+}
+ 
+int main(void) 
+{
+    struct data key = { .nr = 3 };
+    struct data const *res = bsearch(&key, dat, sizeof dat / sizeof dat[0],
+                                     sizeof dat[0], data_cmp);
+    if (res) {
+        printf("No %d: %s\n", res->nr, res->value);
+    } else {
+        printf("No %d not found\n", key.nr);
+    }
+}

Output:

+
No 3: Hello

References

See also

+ +
+
(C11)
 sorts a range of elements with unspecified type
(function)
C++ documentation for bsearch
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/algorithm/bsearch +

+
diff --git a/devdocs/c/algorithm%2Fqsort.html b/devdocs/c/algorithm%2Fqsort.html new file mode 100644 index 00000000..f1006ea4 --- /dev/null +++ b/devdocs/c/algorithm%2Fqsort.html @@ -0,0 +1,85 @@ +

qsort, qsort_s

Defined in header <stdlib.h> 
void qsort( void *ptr, size_t count, size_t size,
+            int (*comp)(const void *, const void *) );
+		 (1) 
errno_t qsort_s( void *ptr, rsize_t count, rsize_t size,
+                 int (*comp)(const void *, const void *, void *),
+                 void *context );
+		 (2) (since C11)
+1) Sorts the given array pointed to by ptr in ascending order. The array contains count elements of size bytes. Function pointed to by comp is used for object comparison.
+2) Same as (1), except that the additional context parameter context is passed to comp and that the following errors are detected at runtime and call the currently installed constraint handler function:
+
+
    +
  • count or size is greater than RSIZE_MAX
    • +
  • ptr or comp is a null pointer (unless count is zero)
    • +
+
As with all bounds-checked functions, qsort_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <stdlib.h>.
+
+

If comp indicates two elements as equivalent, their order in the resulting sorted array is unspecified.

+

Parameters

+ + + + + +
ptr - pointer to the array to sort
count - number of elements in the array
size - size of each element in the array in bytes
comp - comparison function which returns ​a negative integer value if the first argument is less than the second, a positive integer value if the first argument is greater than the second and zero if the arguments are equivalent.

The signature of the comparison function should be equivalent to the following:

+

int cmp(const void *a, const void *b);

+

The function must not modify the objects passed to it and must return consistent results when called for the same objects, regardless of their positions in the array.

+

​

+
context - additional information (e.g., collating sequence), passed to comp as the third argument

Return value

+1) (none)
+2) zero on success, non-zero if a runtime constraints violation was detected

Notes

Despite the name, neither C nor POSIX standards require this function to be implemented using quicksort or make any complexity or stability guarantees.

+

Unlike other bounds-checked functions, qsort_s does not treat arrays of zero size as a runtime constraint violation and instead returns successfully without altering the array (the other function that accepts arrays of zero size is bsearch_s).

+

Until qsort_s, users of qsort often used global variables to pass additional context to the comparison function.

+

Example

#include <stdio.h>
+#include <stdlib.h>
+#include <limits.h>
+ 
+int compare_ints(const void* a, const void* b)
+{
+    int arg1 = *(const int*)a;
+    int arg2 = *(const int*)b;
+ 
+    if (arg1 < arg2) return -1;
+    if (arg1 > arg2) return 1;
+    return 0;
+ 
+    // return (arg1 > arg2) - (arg1 < arg2); // possible shortcut
+    // return arg1 - arg2; // erroneous shortcut (fails if INT_MIN is present)
+}
+ 
+int main(void)
+{
+    int ints[] = { -2, 99, 0, -743, 2, INT_MIN, 4 };
+    int size = sizeof ints / sizeof *ints;
+ 
+    qsort(ints, size, sizeof(int), compare_ints);
+ 
+    for (int i = 0; i < size; i++) {
+        printf("%d ", ints[i]);
+    }
+ 
+    printf("\n");
+}

Output:

+
-2147483648 -743 -2 0 2 4 99

References

See also

+ +
+
(C11)
 searches an array for an element of unspecified type
(function)
C++ documentation for qsort
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/algorithm/qsort +

+
diff --git a/devdocs/c/algorithm.html b/devdocs/c/algorithm.html new file mode 100644 index 00000000..103b3fd5 --- /dev/null +++ b/devdocs/c/algorithm.html @@ -0,0 +1,22 @@ +

Algorithms

+ + +
Defined in header <stdlib.h>
+
(C11)
 sorts a range of elements with unspecified type
(function)
+
(C11)
 searches an array for an element of unspecified type
(function)

References

See also

+
C++ documentation for Algorithms library
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/algorithm +

+
diff --git a/devdocs/c/atomic%2Fatomic_compare_exchange.html b/devdocs/c/atomic%2Fatomic_compare_exchange.html new file mode 100644 index 00000000..5075a508 --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_compare_exchange.html @@ -0,0 +1,45 @@ +

atomic_compare_exchange_weak, atomic_compare_exchange_strong, atomic_compare_exchange_weak_explicit, atomic_compare_exchange_strong_explicit

Defined in header <stdatomic.h> 
_Bool atomic_compare_exchange_strong( volatile A* obj,
+                                      C* expected, C desired );
+		 (1) (since C11) 
_Bool atomic_compare_exchange_weak( volatile A *obj, 
+                                    C* expected, C desired );
+		 (2) (since C11) 
_Bool atomic_compare_exchange_strong_explicit( volatile A* obj, 
+                                               C* expected, C desired,
+                                               memory_order succ, 
+                                               memory_order fail );
+		 (3) (since C11) 
_Bool atomic_compare_exchange_weak_explicit( volatile A *obj, 
+                                             C* expected, C desired,
+                                             memory_order succ, 
+                                             memory_order fail );
+		 (4) (since C11)

Atomically compares the contents of memory pointed to by obj with the contents of memory pointed to by expected, and if those are bitwise equal, replaces the former with desired (performs read-modify-write operation). Otherwise, loads the actual contents of memory pointed to by obj into *expected (performs load operation).

+

The memory models for the read-modify-write and load operations are succ and fail respectively. The (1-2) versions use memory_order_seq_cst by default.

+

The weak forms ((2) and (4)) of the functions are allowed to fail spuriously, that is, act as if *obj != *expected even if they are equal. When a compare-and-exchange is in a loop, the weak version will yield better performance on some platforms. When a weak compare-and-exchange would require a loop and a strong one would not, the strong one is preferable.

+

This is a generic function defined for all atomic object types A. The argument is pointer to a volatile atomic type to accept addresses of both non-volatile and volatile (e.g. memory-mapped I/O) atomic objects, and volatile semantic is preserved when applying this operation to volatile atomic objects. C is the non-atomic type corresponding to A.

+

It is unspecified whether the name of a generic function is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual function (e.g. parenthesized like (atomic_compare_exchange)(...)), or a program defines an external identifier with the name of a generic function, the behavior is undefined.

+

Parameters

+ + + + + +
obj - pointer to the atomic object to test and modify
expected - pointer to the value expected to be found in the atomic object
desired - the value to store in the atomic object if it is as expected
succ - the memory synchronization ordering for the read-modify-write operation if the comparison succeeds. All values are permitted.
fail - the memory synchronization ordering for the load operation if the comparison fails. Cannot be memory_order_release or memory_order_acq_rel and cannot specify stronger ordering than succ

Return value

The result of the comparison: true if *obj was equal to *exp, false otherwise.

+

Notes

The behavior of atomic_compare_exchange_* family is as if the following was executed atomically:

+
if (memcmp(obj, expected, sizeof *obj) == 0) {
+    memcpy(obj, &desired, sizeof *obj);
+    return true;
+} else {
+    memcpy(expected, obj, sizeof *obj);
+    return false;
+}

References

See also

+ +
+
(C11)
 swaps a value with the value of an atomic object
(function)
C++ documentation for atomic_compare_exchange_weak, atomic_compare_exchange_strong, atomic_compare_exchange_weak_explicit, atomic_compare_exchange_strong_explicit
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/atomic/atomic_compare_exchange +

+
diff --git a/devdocs/c/atomic%2Fatomic_exchange.html b/devdocs/c/atomic%2Fatomic_exchange.html new file mode 100644 index 00000000..d508573b --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_exchange.html @@ -0,0 +1,24 @@ +

atomic_exchange, atomic_exchange_explicit

Defined in header <stdatomic.h> 
C atomic_exchange( volatile A* obj, C desired );
+		 (1) (since C11) 
C atomic_exchange_explicit( volatile A* obj, C desired, memory_order order );
+		 (2) (since C11)

Atomically replaces the value pointed by obj with desired and returns the value obj held previously. The operation is read-modify-write operation. The first version orders memory accesses according to memory_order_seq_cst, the second version orders memory accesses according to order.

+

This is a generic function defined for all atomic object types A. The argument is pointer to a volatile atomic type to accept addresses of both non-volatile and volatile (e.g. memory-mapped I/O) atomic objects, and volatile semantic is preserved when applying this operation to volatile atomic objects. C is the non-atomic type corresponding to A.

+

It is unspecified whether the name of a generic function is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual function (e.g. parenthesized like (atomic_exchange)(...)), or a program defines an external identifier with the name of a generic function, the behavior is undefined..

+

Parameters

+ + + +
obj - pointer to the atomic object to modify
desired - the value to replace the atomic object with
order - the memory synchronization ordering for this operation: all values are permitted

Return value

The value held previously be the atomic object pointed to by obj.

+

References

See also

+ +
+
(C11)
 swaps a value with an atomic object if the old value is what is expected, otherwise reads the old value
(function)
C++ documentation for atomic_exchange, atomic_exchange_explicit
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/atomic/atomic_exchange +

+
diff --git a/devdocs/c/atomic%2Fatomic_fetch_add.html b/devdocs/c/atomic%2Fatomic_fetch_add.html new file mode 100644 index 00000000..8bfa2a40 --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_fetch_add.html @@ -0,0 +1,53 @@ +

atomic_fetch_add, atomic_fetch_add_explicit

Defined in header <stdatomic.h> 
C atomic_fetch_add( volatile A* obj, M arg );
+		 (1) (since C11) 
C atomic_fetch_add_explicit( volatile A* obj, M arg, memory_order order );
+		 (2) (since C11)

Atomically replaces the value pointed by obj with the result of addition of arg to the old value of obj, and returns the value obj held previously. The operation is read-modify-write operation. The first version orders memory accesses according to memory_order_seq_cst, the second version orders memory accesses according to order.

+

This is a generic function defined for all atomic object types A. The argument is pointer to a volatile atomic type to accept addresses of both non-volatile and volatile (e.g. memory-mapped I/O) atomic objects, and volatile semantic is preserved when applying this operation to volatile atomic objects. M is either the non-atomic type corresponding to A if A is atomic integer type, or ptrdiff_t if A is atomic pointer type.

+

It is unspecified whether the name of a generic function is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual function (e.g. parenthesized like (atomic_fetch_add)(...)), or a program defines an external identifier with the name of a generic function, the behavior is undefined.

+

For signed integer types, arithmetic is defined to use two’s complement representation. There are no undefined results. For pointer types, the result may be an undefined address, but the operations otherwise have no undefined behavior.

+

Parameters

+ + + +
obj - pointer to the atomic object to modify
arg - the value to add to the value stored in the atomic object
order - the memory synchronization ordering for this operation: all values are permitted

Return value

The value held previously by the atomic object pointed to by obj.

+

Example

#include <stdio.h>
+#include <threads.h>
+#include <stdatomic.h>
+ 
+atomic_int acnt;
+int cnt;
+ 
+int f(void* thr_data)
+{
+    for(int n = 0; n < 1000; ++n) {
+        atomic_fetch_add_explicit(&acnt, 1, memory_order_relaxed); // atomic
+        ++cnt; // undefined behavior, in practice some updates missed
+    }
+    return 0;
+}
+ 
+int main(void)
+{
+    thrd_t thr[10];
+    for(int n = 0; n < 10; ++n)
+        thrd_create(&thr[n], f, NULL);
+    for(int n = 0; n < 10; ++n)
+        thrd_join(thr[n], NULL);
+ 
+    printf("The atomic counter is %u\n", acnt);
+    printf("The non-atomic counter is %u\n", cnt);
+}

Possible output:

+
The atomic counter is 10000
+The non-atomic counter is 9511

References

See also

+ +
+
(C11)
 atomic subtraction
(function)
C++ documentation for atomic_fetch_add, atomic_fetch_add_explicit
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/atomic/atomic_fetch_add +

+
diff --git a/devdocs/c/atomic%2Fatomic_fetch_and.html b/devdocs/c/atomic%2Fatomic_fetch_and.html new file mode 100644 index 00000000..3c5f0033 --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_fetch_and.html @@ -0,0 +1,26 @@ +

atomic_fetch_and, atomic_fetch_and_explicit

Defined in header <stdatomic.h> 
C atomic_fetch_and( volatile A* obj, M arg );
+		 (1) (since C11) 
C atomic_fetch_and_explicit( volatile A* obj, M arg, memory_order order );
+		 (2) (since C11)

Atomically replaces the value pointed by obj with the result of bitwise AND between the old value of obj and arg, and returns the value obj held previously. The operation is read-modify-write operation. The first version orders memory accesses according to memory_order_seq_cst, the second version orders memory accesses according to order.

+

This is a generic function defined for all atomic object types A. The argument is pointer to a volatile atomic type to accept addresses of both non-volatile and volatile (e.g. memory-mapped I/O) atomic objects, and volatile semantic is preserved when applying this operation to volatile atomic objects. M is either the non-atomic type corresponding to A if A is atomic integer type, or ptrdiff_t if A is atomic pointer type.

+

It is unspecified whether the name of a generic function is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual function (e.g. parenthesized like (atomic_fetch_and)(...)), or a program defines an external identifier with the name of a generic function, the behavior is undefined.

+

Parameters

+ + + +
obj - pointer to the atomic object to modify
arg - the value to bitwise AND to the value stored in the atomic object
order - the memory synchronization ordering for this operation: all values are permitted

Return value

The value held previously be the atomic object pointed to by obj.

+

References

See also

+ + +
+
(C11)
 atomic bitwise OR
(function)
+
(C11)
 atomic bitwise exclusive OR
(function)
C++ documentation for atomic_fetch_and, atomic_fetch_and_explicit
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/atomic/atomic_fetch_and +

+
diff --git a/devdocs/c/atomic%2Fatomic_fetch_or.html b/devdocs/c/atomic%2Fatomic_fetch_or.html new file mode 100644 index 00000000..5479688c --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_fetch_or.html @@ -0,0 +1,26 @@ +

atomic_fetch_or, atomic_fetch_or_explicit

Defined in header <stdatomic.h> 
C atomic_fetch_or( volatile A* obj, M arg );
+		 (1) (since C11) 
C atomic_fetch_or_explicit( volatile A* obj, M arg, memory_order order );
+		 (2) (since C11)

Atomically replaces the value pointed by obj with the result of bitwise OR between the old value of obj and arg, and returns the value obj held previously. The operation is read-modify-write operation. The first version orders memory accesses according to memory_order_seq_cst, the second version orders memory accesses according to order.

+

This is a generic function defined for all atomic object types A. The argument is pointer to a volatile atomic type to accept addresses of both non-volatile and volatile (e.g. memory-mapped I/O) atomic objects, and volatile semantic is preserved when applying this operation to volatile atomic objects. M is either the non-atomic type corresponding to A if A is atomic integer type, or ptrdiff_t if A is atomic pointer type.

+

It is unspecified whether the name of a generic function is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual function (e.g. parenthesized like (atomic_fetch_or)(...)), or a program defines an external identifier with the name of a generic function, the behavior is undefined.

+

Parameters

+ + + +
obj - pointer to the atomic object to modify
arg - the value to bitwise OR to the value stored in the atomic object
order - the memory synchronization ordering for this operation: all values are permitted

Return value

The value held previously be the atomic object pointed to by obj.

+

References

See also

+ + +
+
(C11)
 atomic bitwise AND
(function)
+
(C11)
 atomic bitwise exclusive OR
(function)
C++ documentation for atomic_fetch_or, atomic_fetch_or_explicit
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/atomic/atomic_fetch_or +

+
diff --git a/devdocs/c/atomic%2Fatomic_fetch_sub.html b/devdocs/c/atomic%2Fatomic_fetch_sub.html new file mode 100644 index 00000000..2ce31ca1 --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_fetch_sub.html @@ -0,0 +1,25 @@ +

atomic_fetch_sub, atomic_fetch_sub_explicit

Defined in header <stdatomic.h> 
C atomic_fetch_sub( volatile A* obj, M arg );
+		 (1) (since C11) 
C atomic_fetch_sub_explicit( volatile A* obj, M arg, memory_order order );
+		 (2) (since C11)

Atomically replaces the value pointed by obj with the result of subtraction of arg from the old value of obj, and returns the value obj held previously. The operation is read-modify-write operation. The first version orders memory accesses according to memory_order_seq_cst, the second version orders memory accesses according to order.

+

This is a generic function defined for all atomic object types A. The argument is pointer to a volatile atomic type to accept addresses of both non-volatile and volatile (e.g. memory-mapped I/O) atomic objects, and volatile semantic is preserved when applying this operation to volatile atomic objects. M is either the non-atomic type corresponding to A if A is atomic integer type, or ptrdiff_t if A is atomic pointer type.

+

It is unspecified whether the name of a generic function is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual function (e.g. parenthesized like (atomic_fetch_sub)(...)), or a program defines an external identifier with the name of a generic function, the behavior is undefined.

+

For signed integer types, arithmetic is defined to use two’s complement representation. There are no undefined results. For pointer types, the result may be an undefined address, but the operations otherwise have no undefined behavior.

+

Parameters

+ + + +
obj - pointer to the atomic object to modify
arg - the value to subtract from the value stored in the atomic object
order - the memory synchronization ordering for this operation: all values are permitted

Return value

The value held previously by the atomic object pointed to by obj.

+

References

See also

+ +
+
(C11)
 atomic addition
(function)
C++ documentation for atomic_fetch_sub, atomic_fetch_sub_explicit
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/atomic/atomic_fetch_sub +

+
diff --git a/devdocs/c/atomic%2Fatomic_fetch_xor.html b/devdocs/c/atomic%2Fatomic_fetch_xor.html new file mode 100644 index 00000000..34db6b5b --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_fetch_xor.html @@ -0,0 +1,26 @@ +

atomic_fetch_xor, atomic_fetch_xor_explicit

Defined in header <stdatomic.h> 
C atomic_fetch_xor( volatile A* obj, M arg );
+		 (1) (since C11) 
C atomic_fetch_xor_explicit( volatile A* obj, M arg, memory_order order );
+		 (2) (since C11)

Atomically replaces the value pointed by obj with the result of bitwise XOR between the old value of obj and arg, and returns the value obj held previously. The operation is read-modify-write operation. The first version orders memory accesses according to memory_order_seq_cst, the second version orders memory accesses according to order.

+

This is a generic function defined for all atomic object types A. The argument is pointer to a volatile atomic type to accept addresses of both non-volatile and volatile (e.g. memory-mapped I/O) atomic objects, and volatile semantic is preserved when applying this operation to volatile atomic objects. M is either the non-atomic type corresponding to A if A is atomic integer type, or ptrdiff_t if A is atomic pointer type.

+

It is unspecified whether the name of a generic function is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual function (e.g. parenthesized like (atomic_fetch_xor)(...)), or a program defines an external identifier with the name of a generic function, the behavior is undefined.

+

Parameters

+ + + +
obj - pointer to the atomic object to modify
arg - the value to bitwise XOR to the value stored in the atomic object
order - the memory synchronization ordering for this operation: all values are permitted

Return value

The value held previously be the atomic object pointed to by obj.

+

References

See also

+ + +
+
(C11)
 atomic bitwise OR
(function)
+
(C11)
 atomic bitwise AND
(function)
C++ documentation for atomic_fetch_xor, atomic_fetch_xor_explicit
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/atomic/atomic_fetch_xor +

+
diff --git a/devdocs/c/atomic%2Fatomic_flag.html b/devdocs/c/atomic%2Fatomic_flag.html new file mode 100644 index 00000000..9ce4958c --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_flag.html @@ -0,0 +1,26 @@ +

atomic_flag

Defined in header <stdatomic.h> 
struct atomic_flag;
+		 (since C11)

atomic_flag is an atomic boolean type. Unlike other atomic types, it is guaranteed to be lock-free. Unlike atomic_bool, atomic_flag does not provide load or store operations.

+

References

See also

+ + + +
+
(C11)
 initializes a new atomic_flag
(macro constant)
+
(C11)
 sets an atomic_flag to true and returns the old value
(function)
+
(C11)
 sets an atomic_flag to false
(function)
C++ documentation for atomic_flag
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/atomic/atomic_flag +

+
diff --git a/devdocs/c/atomic%2Fatomic_flag_clear.html b/devdocs/c/atomic%2Fatomic_flag_clear.html new file mode 100644 index 00000000..a9afc72a --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_flag_clear.html @@ -0,0 +1,22 @@ +

atomic_flag_clear, atomic_flag_clear_explicit

Defined in header <stdatomic.h> 
void atomic_flag_clear( volatile atomic_flag* obj );
+		 (1) (since C11) 
void atomic_flag_clear_explicit( volatile atomic_flag* obj, memory_order order );
+		 (2) (since C11)

Atomically changes the state of a atomic_flag pointed to by obj to clear (false). The first version orders memory accesses according to memory_order_seq_cst, the second version orders memory accesses according to order.

+

The argument is pointer to a volatile atomic flag to accept addresses of both non-volatile and volatile (e.g. memory-mapped I/O) atomic flags.

+

Parameters

+ + +
obj - pointer to the atomic flag object to modify
order - the memory synchronization ordering for this operation: all values are permitted

Return value

(none)

+

References

See also

+ +
+
(C11)
 sets an atomic_flag to true and returns the old value
(function)
C++ documentation for atomic_flag_clear, atomic_flag_clear_explicit
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/atomic/atomic_flag_clear +

+
diff --git a/devdocs/c/atomic%2Fatomic_flag_init.html b/devdocs/c/atomic%2Fatomic_flag_init.html new file mode 100644 index 00000000..dbe9fef1 --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_flag_init.html @@ -0,0 +1,26 @@ +

ATOMIC_FLAG_INIT

Defined in header <stdatomic.h> 
#define ATOMIC_FLAG_INIT /* unspecified */
+		 (since C11)

Expands to an initializer that can be used to initialize atomic_flag type to the clear state. The value atomic_flag that is not initialized using this macro is indeterminate.

+

Example

#include <stdatomic.h>
+ 
+atomic_flag flag = ATOMIC_FLAG_INIT;

References

See also

+ + +
+
(C11)(deprecated in C17)(removed in C23)
 initializes a new atomic object
(function macro)
+
(C11)
 lock-free atomic boolean flag
(struct)
C++ documentation for ATOMIC_FLAG_INIT
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/atomic/ATOMIC_FLAG_INIT +

+
diff --git a/devdocs/c/atomic%2Fatomic_flag_test_and_set.html b/devdocs/c/atomic%2Fatomic_flag_test_and_set.html new file mode 100644 index 00000000..cd9bf556 --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_flag_test_and_set.html @@ -0,0 +1,22 @@ +

atomic_flag_test_and_set, atomic_flag_test_and_set_explicit

Defined in header <stdatomic.h> 
_Bool atomic_flag_test_and_set( volatile atomic_flag* obj );
+		 (1) (since C11) 
_Bool atomic_flag_test_and_set_explicit( volatile atomic_flag* obj, memory_order order );
+		 (2) (since C11)

Atomically changes the state of a atomic_flag pointed to by obj to set (true) and returns the previous value. The first version orders memory accesses according to memory_order_seq_cst, the second version orders memory accesses according to order.

+

The argument is pointer to a volatile atomic flag to accept addresses of both non-volatile and volatile (e.g. memory-mapped I/O) atomic flags.

+

Parameters

+ + +
obj - pointer to the atomic flag object to modify
order - the memory synchronization ordering for this operation: all values are permitted

Return value

The previous value held by the atomic flag pointed to by obj.

+

References

See also

+ +
+
(C11)
 sets an atomic_flag to false
(function)
C++ documentation for atomic_flag_test_and_set, atomic_flag_test_and_set_explicit
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/atomic/atomic_flag_test_and_set +

+
diff --git a/devdocs/c/atomic%2Fatomic_init.html b/devdocs/c/atomic%2Fatomic_init.html new file mode 100644 index 00000000..a6790747 --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_init.html @@ -0,0 +1,26 @@ +

atomic_init

Defined in header <stdatomic.h> 
void atomic_init( volatile A* obj, C desired );
+		 (since C11)

Initializes the default-constructed atomic object obj with the value desired. The function is not atomic: concurrent access from another thread, even through an atomic operation, is a data race.

+

This is a generic function defined for all atomic object types A. The argument is pointer to a volatile atomic type to accept addresses of both non-volatile and volatile (e.g. memory-mapped I/O) atomic objects, and volatile semantic is preserved when applying this operation to volatile atomic objects. C is the non-atomic type corresponding to A.

+

It is unspecified whether the name of a generic function is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual function (e.g. parenthesized like (atomic_init)(...)), or a program defines an external identifier with the name of a generic function, the behavior is undefined.

+

Parameters

+ + +
obj - pointer to an atomic object to initialize
desired - the value to initialize atomic object with

Return value

(none)

+

Notes

atomic_init is the only way to initialize dynamically-allocated atomic objects. For example:

+
_Atomic int *p = malloc(sizeof(_Atomic int));
+atomic_init(p, 42);

References

See also

+ +
+
(C11)(deprecated in C17)(removed in C23)
 initializes a new atomic object
(function macro)
C++ documentation for atomic_init
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/atomic/atomic_init +

+
diff --git a/devdocs/c/atomic%2Fatomic_is_lock_free.html b/devdocs/c/atomic%2Fatomic_is_lock_free.html new file mode 100644 index 00000000..373ff242 --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_is_lock_free.html @@ -0,0 +1,39 @@ +

atomic_is_lock_free

Defined in header <stdatomic.h> 
_Bool atomic_is_lock_free( const volatile A* obj );
+		 (since C11)

Determines if the atomic operations on all objects of the type A (the type of the object pointed to by obj) are lock-free. In any given program execution, the result of calling atomic_is_lock_free is the same for all pointers of the same type.

+

This is a generic function defined for all atomic object types A. The argument is pointer to a volatile atomic type to accept addresses of both non-volatile and volatile (e.g. memory-mapped I/O) atomic objects, and volatile semantic is preserved when applying this operation to volatile atomic objects.

+

It is unspecified whether the name of a generic function is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual function (e.g. parenthesized like (atomic_is_lock_free)(...)), or a program defines an external identifier with the name of a generic function, the behavior is undefined.

+

Parameters

+ +
obj - pointer to the atomic object to inspect

Return value

true if the operations on all objects of the type A are lock-free, false otherwise.

+

Example

#include <stdio.h>
+#include <stdatomic.h>
+ 
+_Atomic struct A { int a[100]; } a;
+_Atomic struct B { int x, y; } b;
+int main(void)
+{
+    printf("_Atomic struct A is lock free? %s\n", 
+            atomic_is_lock_free(&a) ? "true" : "false");
+    printf("_Atomic struct B is lock free? %s\n", 
+            atomic_is_lock_free(&b) ? "true" : "false");
+}

Possible output:

+
_Atomic struct A is lock free? false
+_Atomic struct B is lock free? true

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C standards.

+ + + +
DR Applied to Behavior as published Correct behavior
+DR 465 C11 this function was per-object this functions is per-type

References

See also

+ +
+
(C11)
 indicates that the given atomic type is lock-free
(macro constant)
C++ documentation for atomic_is_lock_free
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/atomic/atomic_is_lock_free +

+
diff --git a/devdocs/c/atomic%2Fatomic_load.html b/devdocs/c/atomic%2Fatomic_load.html new file mode 100644 index 00000000..6c2bd77f --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_load.html @@ -0,0 +1,24 @@ +

atomic_load, atomic_load_explicit

Defined in header <stdatomic.h> 
C atomic_load( const volatile A* obj );
+		 (1) (since C11) 
C atomic_load_explicit( const volatile A* obj, memory_order order );
+		 (2) (since C11)

Atomically loads and returns the current value of the atomic variable pointed to by obj. The operation is atomic read operation.

+

The first version orders memory accesses according to memory_order_seq_cst, the second version orders memory accesses according to order. order must be one of memory_order_relaxed, memory_order_consume, memory_order_acquire or memory_order_seq_cst. Otherwise the behavior is undefined.

+

This is a generic function defined for all atomic object types A. The argument is pointer to a volatile atomic type to accept addresses of both non-volatile and volatile (e.g. memory-mapped I/O) atomic objects, and volatile semantic is preserved when applying this operation to volatile atomic objects. C is the non-atomic type corresponding to A.

+

It is unspecified whether the name of a generic function is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual function (e.g. parenthesized like (atomic_load)(...)), or a program defines an external identifier with the name of a generic function, the behavior is undefined.

+

Parameters

+ + +
obj - pointer to the atomic object to access
order - the memory synchronization ordering for this operation

Return value

The current value of the atomic variable pointed to by obj.

+

References

See also

+ +
+
(C11)
 stores a value in an atomic object
(function)
C++ documentation for atomic_load, atomic_load_explicit
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/atomic/atomic_load +

+
diff --git a/devdocs/c/atomic%2Fatomic_lock_free_consts.html b/devdocs/c/atomic%2Fatomic_lock_free_consts.html new file mode 100644 index 00000000..ad4bd120 --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_lock_free_consts.html @@ -0,0 +1,27 @@ +

ATOMIC_*_LOCK_FREE

Defined in header <stdatomic.h> 
#define ATOMIC_BOOL_LOCK_FREE     /* implementation-defined */
+#define ATOMIC_CHAR_LOCK_FREE     /* implementation-defined */
+#define ATOMIC_CHAR16_T_LOCK_FREE /* implementation-defined */
+#define ATOMIC_CHAR32_T_LOCK_FREE /* implementation-defined */
+#define ATOMIC_WCHAR_T_LOCK_FREE  /* implementation-defined */
+#define ATOMIC_SHORT_LOCK_FREE    /* implementation-defined */
+#define ATOMIC_INT_LOCK_FREE      /* implementation-defined */
+#define ATOMIC_LONG_LOCK_FREE     /* implementation-defined */
+#define ATOMIC_LLONG_LOCK_FREE    /* implementation-defined */
+#define ATOMIC_POINTER_LOCK_FREE  /* implementation-defined */
+		 (since C11) 
#define ATOMIC_CHAR8_T_LOCK_FREE  /* implementation-defined */
+		 (since C23)

Expands to preprocessor constant expressions that evaluate to either 0, 1, or 2 which indicate the lock-free property of the corresponding atomic types (both signed and unsigned).

+ + + + +
Value Explanation
0 The atomic type is never lock-free
1 The atomic type is sometimes lock-free
2 The atomic type is always lock-free

References

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/atomic/ATOMIC_LOCK_FREE_consts +

+
diff --git a/devdocs/c/atomic%2Fatomic_signal_fence.html b/devdocs/c/atomic%2Fatomic_signal_fence.html new file mode 100644 index 00000000..6dec1af8 --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_signal_fence.html @@ -0,0 +1,19 @@ +

atomic_signal_fence

Defined in header <stdatomic.h> 
void atomic_signal_fence( memory_order order );
+		 (since C11)

Establishes memory synchronization ordering of non-atomic and relaxed atomic accesses, as instructed by order, between a thread and a signal handler executed on the same thread. This is equivalent to atomic_thread_fence, except no CPU instructions for memory ordering are issued. Only reordering of the instructions by the compiler is suppressed as order instructs. For example, a fence with release semantics prevents reads or writes from being moved past subsequent writes and a fence with acquire semantics prevents reads or writes from being moved ahead of preceding reads.

+

Parameters

+ +
order - the memory ordering executed by this fence

Return value

(none)

+

References

See also

+ +
+
(C11)
 generic memory order-dependent fence synchronization primitive
(function)
C++ documentation for atomic_signal_fence
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/atomic/atomic_signal_fence +

+
diff --git a/devdocs/c/atomic%2Fatomic_store.html b/devdocs/c/atomic%2Fatomic_store.html new file mode 100644 index 00000000..c213430e --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_store.html @@ -0,0 +1,24 @@ +

atomic_store, atomic_store_explicit

Defined in header <stdatomic.h> 
void atomic_store( volatile A* obj , C desired );
+		 (1) (since C11) 
void atomic_store_explicit( volatile A* obj, C desired, memory_order order );
+		 (2) (since C11)

Atomically replaces the value of the atomic variable pointed to by obj with desired. The operation is atomic write operation.

+

The first version orders memory accesses according to memory_order_seq_cst, the second version orders memory accesses according to order. order must be one of memory_order_relaxed, memory_order_release or memory_order_seq_cst. Otherwise the behavior is undefined.

+

This is a generic function defined for all atomic object types A. The argument is pointer to a volatile atomic type to accept addresses of both non-volatile and volatile (e.g. memory-mapped I/O) atomic objects, and volatile semantic is preserved when applying this operation to volatile atomic objects. C is the non-atomic type corresponding to A.

+

It is unspecified whether the name of a generic function is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual function (e.g. parenthesized like (atomic_store)(...)), or a program defines an external identifier with the name of a generic function, the behavior is undefined.

+

Parameters

+ + +
obj - pointer to the atomic object to modify
order - the memory synchronization ordering for this operation

Return value

(none)

+

References

See also

+ +
+
(C11)
 reads a value from an atomic object
(function)
C++ documentation for atomic_store, atomic_store_explicit
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/atomic/atomic_store +

+
diff --git a/devdocs/c/atomic%2Fatomic_thread_fence.html b/devdocs/c/atomic%2Fatomic_thread_fence.html new file mode 100644 index 00000000..73fd6206 --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_thread_fence.html @@ -0,0 +1,19 @@ +

atomic_thread_fence

Defined in header <stdatomic.h> 
void atomic_thread_fence( memory_order order );
+		 (since C11)

Establishes memory synchronization ordering of non-atomic and relaxed atomic accesses, as instructed by order, without an associated atomic operation. For example, all non-atomic and relaxed atomic stores that happen before a memory_order_release fence in thread A will be synchronized with non-atomic and relaxed atomic loads from the same locations made in thread B after an memory_order_acquire fence.

+

Parameters

+ +
order - the memory ordering executed by this fence

Return value

(none)

+

References

See also

+ +
+
(C11)
 fence between a thread and a signal handler executed in the same thread
(function)
C++ documentation for atomic_thread_fence
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/atomic/atomic_thread_fence +

+
diff --git a/devdocs/c/atomic%2Fatomic_var_init.html b/devdocs/c/atomic%2Fatomic_var_init.html new file mode 100644 index 00000000..66208dac --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_var_init.html @@ -0,0 +1,24 @@ +

ATOMIC_VAR_INIT

Defined in header <stdatomic.h> 
#define ATOMIC_VAR_INIT(value) /* unspecified */
+		 (since C11)
(deprecated in C17)
(removed in C23)

Expands to an expression that can be used to initialize an atomic variable of the same type as value.

+

The initial value of atomic object of automatic storage duration that is not explicitly initialized is indeterminate. The default (zero) initialization of static and thread-local variables produces a valid value however.

+

When initializing an atomic variable, any concurrent access, even through an atomic operation, is a data race (it may happen if the address is immediately passed to another thread with a memory_order_relaxed operation).

+

Notes

This macro was a part of early draft design for C11 atomic types. It is not needed in C11, and is deprecated in C17 and removed in C23.

+

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C standards.

+ + + +
DR Applied to Behavior as published Correct behavior
+DR 485 C11 the specification was redundant and contradictory to the core language fixed

References

See also

+ +
+
(C11)
 initializes a new atomic_flag
(macro constant)
C++ documentation for ATOMIC_VAR_INIT
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/atomic/ATOMIC_VAR_INIT +

+
diff --git a/devdocs/c/atomic%2Fkill_dependency.html b/devdocs/c/atomic%2Fkill_dependency.html new file mode 100644 index 00000000..3a4d470f --- /dev/null +++ b/devdocs/c/atomic%2Fkill_dependency.html @@ -0,0 +1,20 @@ +

kill_dependency

Defined in header <stdatomic.h> 
A kill_dependency( A y );
+		 (since C11)

Informs the compiler that the dependency tree started by an memory_order_consume atomic load operation does not extend past the return value of kill_dependency; that is, the argument does not carry a dependency into the return value.

+

The function is implemented as a macro. A is the type of y.

+

Parameters

+ +
y - the expression whose return value is to be removed from a dependency tree

Return value

Returns y, no longer a part of a dependency tree.

+

References

See also

+
C++ documentation for kill_dependency
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/atomic/kill_dependency +

+
diff --git a/devdocs/c/atomic%2Fmemory_order.html b/devdocs/c/atomic%2Fmemory_order.html new file mode 100644 index 00000000..e7d320ac --- /dev/null +++ b/devdocs/c/atomic%2Fmemory_order.html @@ -0,0 +1,92 @@ +

memory_order

Defined in header <stdatomic.h> 
enum memory_order {
+    memory_order_relaxed,
+    memory_order_consume,
+    memory_order_acquire,
+    memory_order_release,
+    memory_order_acq_rel,
+    memory_order_seq_cst
+};
+		 (since C11)

memory_order specifies how memory accesses, including regular, non-atomic memory accesses, are to be ordered around an atomic operation. Absent any constraints on a multi-core system, when multiple threads simultaneously read and write to several variables, one thread can observe the values change in an order different from the order another thread wrote them. Indeed, the apparent order of changes can even differ among multiple reader threads. Some similar effects can occur even on uniprocessor systems due to compiler transformations allowed by the memory model.

+

The default behavior of all atomic operations in the language and the library provides for sequentially consistent ordering (see discussion below). That default can hurt performance, but the library's atomic operations can be given an additional memory_order argument to specify the exact constraints, beyond atomicity, that the compiler and processor must enforce for that operation.

+

Constants

+ + + + + + + +
Defined in header <stdatomic.h>
Value Explanation
memory_order_relaxed Relaxed operation: there are no synchronization or ordering constraints imposed on other reads or writes, only this operation's atomicity is guaranteed (see Relaxed ordering below).
memory_order_consume A load operation with this memory order performs a consume operation on the affected memory location: no reads or writes in the current thread dependent on the value currently loaded can be reordered before this load. Writes to data-dependent variables in other threads that release the same atomic variable are visible in the current thread. On most platforms, this affects compiler optimizations only (see Release-Consume ordering below).
memory_order_acquire A load operation with this memory order performs the acquire operation on the affected memory location: no reads or writes in the current thread can be reordered before this load. All writes in other threads that release the same atomic variable are visible in the current thread (see Release-Acquire ordering below).
memory_order_release A store operation with this memory order performs the release operation: no reads or writes in the current thread can be reordered after this store. All writes in the current thread are visible in other threads that acquire the same atomic variable (see Release-Acquire ordering below) and writes that carry a dependency into the atomic variable become visible in other threads that consume the same atomic (see Release-Consume ordering below).
memory_order_acq_rel A read-modify-write operation with this memory order is both an acquire operation and a release operation. No memory reads or writes in the current thread can be reordered before the load, nor after the store. All writes in other threads that release the same atomic variable are visible before the modification and the modification is visible in other threads that acquire the same atomic variable.
memory_order_seq_cst A load operation with this memory order performs an acquire operation, a store performs a release operation, and read-modify-write performs both an acquire operation and a release operation, plus a single total order exists in which all threads observe all modifications in the same order (see Sequentially-consistent ordering below).

Relaxed ordering

Atomic operations tagged memory_order_relaxed are not synchronization operations; they do not impose an order among concurrent memory accesses. They only guarantee atomicity and modification order consistency.

+

For example, with x and y initially zero,

+

// Thread 1:
r1 = atomic_load_explicit(y, memory_order_relaxed); // A
atomic_store_explicit(x, r1, memory_order_relaxed); // B
// Thread 2:
r2 = atomic_load_explicit(x, memory_order_relaxed); // C
atomic_store_explicit(y, 42, memory_order_relaxed); // D

+

is allowed to produce r1 == r2 == 42 because, although A is sequenced-before B within thread 1 and C is sequenced before D within thread 2, nothing prevents D from appearing before A in the modification order of y, and B from appearing before C in the modification order of x. The side-effect of D on y could be visible to the load A in thread 1 while the side effect of B on x could be visible to the load C in thread 2. In particular, this may occur if D is completed before C in thread 2, either due to compiler reordering or at runtime.

+

Typical use for relaxed memory ordering is incrementing counters, such as the reference counters , since this only requires atomicity, but not ordering or synchronization .

+

Release-Consume ordering

If an atomic store in thread A is tagged memory_order_release, an atomic load in thread B from the same variable is tagged memory_order_consume, and the load in thread B reads a value written by the store in thread A, then the store in thread A is dependency-ordered before the load in thread B.

+

All memory writes (non-atomic and relaxed atomic) that happened-before the atomic store from the point of view of thread A, become visible side-effects within those operations in thread B into which the load operation carries dependency, that is, once the atomic load is completed, those operators and functions in thread B that use the value obtained from the load are guaranteed to see what thread A wrote to memory.

+

The synchronization is established only between the threads releasing and consuming the same atomic variable. Other threads can see different order of memory accesses than either or both of the synchronized threads.

+

On all mainstream CPUs other than DEC Alpha, dependency ordering is automatic, no additional CPU instructions are issued for this synchronization mode, only certain compiler optimizations are affected (e.g. the compiler is prohibited from performing speculative loads on the objects that are involved in the dependency chain).

+

Typical use cases for this ordering involve read access to rarely written concurrent data structures (routing tables, configuration, security policies, firewall rules, etc) and publisher-subscriber situations with pointer-mediated publication, that is, when the producer publishes a pointer through which the consumer can access information: there is no need to make everything else the producer wrote to memory visible to the consumer (which may be an expensive operation on weakly-ordered architectures). An example of such scenario is rcu_dereference.

+

Note that currently (2/2015) no known production compilers track dependency chains: consume operations are lifted to acquire operations.

+

Release sequence

If some atomic is store-released and several other threads perform read-modify-write operations on that atomic, a "release sequence" is formed: all threads that perform the read-modify-writes to the same atomic synchronize with the first thread and each other even if they have no memory_order_release semantics. This makes single producer - multiple consumers situations possible without imposing unnecessary synchronization between individual consumer threads.

+

Release-Acquire ordering

If an atomic store in thread A is tagged memory_order_release, an atomic load in thread B from the same variable is tagged memory_order_acquire, and the load in thread B reads a value written by the store in thread A, then the store in thread A synchronizes-with the load in thread B.

+

All memory writes (including non-atomic and relaxed atomic) that happened-before the atomic store from the point of view of thread A, become visible side-effects in thread B. That is, once the atomic load is completed, thread B is guaranteed to see everything thread A wrote to memory. This promise only holds if B actually returns the value that A stored, or a value from later in the release sequence.

+

The synchronization is established only between the threads releasing and acquiring the same atomic variable. Other threads can see different order of memory accesses than either or both of the synchronized threads.

+

On strongly-ordered systems — x86, SPARC TSO, IBM mainframe, etc. — release-acquire ordering is automatic for the majority of operations. No additional CPU instructions are issued for this synchronization mode; only certain compiler optimizations are affected (e.g., the compiler is prohibited from moving non-atomic stores past the atomic store-release or performing non-atomic loads earlier than the atomic load-acquire). On weakly-ordered systems (ARM, Itanium, PowerPC), special CPU load or memory fence instructions are used.

+

Mutual exclusion locks, such as mutexes or atomic spinlocks, are an example of release-acquire synchronization: when the lock is released by thread A and acquired by thread B, everything that took place in the critical section (before the release) in the context of thread A has to be visible to thread B (after the acquire) which is executing the same critical section.

+

Sequentially-consistent ordering

Atomic operations tagged memory_order_seq_cst not only order memory the same way as release/acquire ordering (everything that happened-before a store in one thread becomes a visible side effect in the thread that did a load), but also establish a single total modification order of all atomic operations that are so tagged.

+

Formally,

+

each memory_order_seq_cst operation B that loads from atomic variable M, observes one of the following:

+

If there was a memory_order_seq_cst atomic_thread_fence operation X sequenced-before B, then B observes one of the following:

+

For a pair of atomic operations on M called A and B, where A writes and B reads M's value, if there are two memory_order_seq_cst atomic_thread_fences X and Y, and if A is sequenced-before X, Y is sequenced-before B, and X appears before Y in the Single Total Order, then B observes either:

+

For a pair of atomic modifications of M called A and B, B occurs after A in M's modification order if

+

Note that this means that:

+
+1) as soon as atomic operations that are not tagged memory_order_seq_cst enter the picture, the sequential consistency is lost,
+2) the sequentially-consistent fences are only establishing total ordering for the fences themselves, not for the atomic operations in the general case (sequenced-before is not a cross-thread relationship, unlike happens-before).

Sequential ordering may be necessary for multiple producer-multiple consumer situations where all consumers must observe the actions of all producers occurring in the same order.

+

Total sequential ordering requires a full memory fence CPU instruction on all multi-core systems. This may become a performance bottleneck since it forces the affected memory accesses to propagate to every core.

+

Relationship with volatile

Within a thread of execution, accesses (reads and writes) through volatile lvalues cannot be reordered past observable side-effects (including other volatile accesses) that are separated by a sequence point within the same thread, but this order is not guaranteed to be observed by another thread, since volatile access does not establish inter-thread synchronization.

+

In addition, volatile accesses are not atomic (concurrent read and write is a data race) and do not order memory (non-volatile memory accesses may be freely reordered around the volatile access).

+

One notable exception is Visual Studio, where, with default settings, every volatile write has release semantics and every volatile read has acquire semantics (Microsoft Docs), and thus volatiles may be used for inter-thread synchronization. Standard volatile semantics are not applicable to multithreaded programming, although they are sufficient for e.g. communication with a signal handler that runs in the same thread when applied to sig_atomic_t variables.

+

Examples

References

See also

+
C++ documentation for memory order
+ + + + + +
1. +MOESI protocol
2. +x86-TSO: A Rigorous and Usable Programmer’s Model for x86 Multiprocessors P. Sewell et. al., 2010
3. +A Tutorial Introduction to the ARM and POWER Relaxed Memory Models P. Sewell et al, 2012
4. +MESIF: A Two-Hop Cache Coherency Protocol for Point-to-Point Interconnects J.R. Goodman, H.H.J. Hum, 2009
5. +Memory Models Russ Cox, 2021
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/atomic/memory_order +

+
diff --git a/devdocs/c/atomic.html b/devdocs/c/atomic.html new file mode 100644 index 00000000..e0c45c68 --- /dev/null +++ b/devdocs/c/atomic.html @@ -0,0 +1,109 @@ +

Atomic operations library

If the macro constant __STDC_NO_ATOMICS__(C11) is defined by the compiler, the header <stdatomic.h>, the keyword _Atomic, and all of the names listed here are not provided.

+

Types

+ + +
Defined in header <stdatomic.h>
+
(C11)
 defines memory ordering constraints
(enum)
+
(C11)
 lock-free atomic boolean flag
(struct)

Macros

+ + + + +
Defined in header <stdatomic.h>
+
(C11)
 indicates that the given atomic type is lock-free
(macro constant)
+
(C11)
 initializes a new atomic_flag
(macro constant)
+
(C11)(deprecated in C17)(removed in C23)
 initializes a new atomic object
(function macro)
+
(C11)
 breaks a dependency chain for memory_order_consume
(function macro)

Functions

+ + + + + + + + + + + + + + + +
Defined in header <stdatomic.h>
+
(C11)
 sets an atomic_flag to true and returns the old value
(function)
+
(C11)
 sets an atomic_flag to false
(function)
+
(C11)
 initializes an existing atomic object
(function)
+
(C11)
 indicates whether the atomic object is lock-free
(function)
+
(C11)
 stores a value in an atomic object
(function)
+
(C11)
 reads a value from an atomic object
(function)
+
(C11)
 swaps a value with the value of an atomic object
(function)
+
(C11)
 swaps a value with an atomic object if the old value is what is expected, otherwise reads the old value
(function)
+
(C11)
 atomic addition
(function)
+
(C11)
 atomic subtraction
(function)
+
(C11)
 atomic bitwise OR
(function)
+
(C11)
 atomic bitwise exclusive OR
(function)
+
(C11)
 atomic bitwise AND
(function)
+
(C11)
 generic memory order-dependent fence synchronization primitive
(function)
+
(C11)
 fence between a thread and a signal handler executed in the same thread
(function)

Types

The standard library offers convenience typedefs for the core language atomic types.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Typedef name Full type name
atomic_bool _Atomic _Bool
atomic_char _Atomic char
atomic_schar _Atomic signed char
atomic_uchar _Atomic unsigned char
atomic_short _Atomic short
atomic_ushort _Atomic unsigned short
atomic_int _Atomic int
atomic_uint _Atomic unsigned int
atomic_long _Atomic long
atomic_ulong _Atomic unsigned long
atomic_llong _Atomic long long
atomic_ullong _Atomic unsigned long long
atomic_char8_t (C23) _Atomic char8_t
atomic_char16_t _Atomic char16_t
atomic_char32_t _Atomic char32_t
atomic_wchar_t _Atomic wchar_t
atomic_int_least8_t _Atomic int_least8_t
atomic_uint_least8_t _Atomic uint_least8_t
atomic_int_least16_t _Atomic int_least16_t
atomic_uint_least16_t _Atomic uint_least16_t
atomic_int_least32_t _Atomic int_least32_t
atomic_uint_least32_t _Atomic uint_least32_t
atomic_int_least64_t _Atomic int_least64_t
atomic_uint_least64_t _Atomic uint_least64_t
atomic_int_fast8_t _Atomic int_fast8_t
atomic_uint_fast8_t _Atomic uint_fast8_t
atomic_int_fast16_t _Atomic int_fast16_t
atomic_uint_fast16_t _Atomic uint_fast16_t
atomic_int_fast32_t _Atomic int_fast32_t
atomic_uint_fast32_t _Atomic uint_fast32_t
atomic_int_fast64_t _Atomic int_fast64_t
atomic_uint_fast64_t _Atomic uint_fast64_t
atomic_intptr_t _Atomic intptr_t
atomic_uintptr_t _Atomic uintptr_t
atomic_size_t _Atomic size_t
atomic_ptrdiff_t _Atomic ptrdiff_t
atomic_intmax_t _Atomic intmax_t
atomic_uintmax_t _Atomic uintmax_t

References

See also

+
C++ documentation for Atomic operations library
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/atomic +

+
diff --git a/devdocs/c/chrono%2Fasctime.html b/devdocs/c/chrono%2Fasctime.html new file mode 100644 index 00000000..436673de --- /dev/null +++ b/devdocs/c/chrono%2Fasctime.html @@ -0,0 +1,85 @@ +

asctime, asctime_s

Defined in header <time.h>
(1) 
char*                asctime( const struct tm* time_ptr );
 (until C23) 
[[deprecated]] char* asctime( const struct tm* time_ptr );
+		 (since C23) 
errno_t asctime_s( char* buf, rsize_t bufsz, const struct tm* time_ptr );
+		 (2) (since C11)
1) Converts given calendar time tm to a textual representation of the following fixed 25-character form: Www Mmm dd hh:mm:ss yyyy\n
+ The behavior is undefined if any member of *time_ptr is outside its normal range
+ The behavior is undefined if the calendar year indicated by time_ptr->tm_year has more than 4 digits or is less than the year 1000.
+ The function does not support localization, and the newline character cannot be removed.
+ The function modifies static storage and is not thread-safe.
+ +
This function is deprecated and should not be used in new code. (since C23)
+2) Same as (1), except that the message is written into user-provided storage buf, which is guaranteed to be null-terminated, and the following errors are detected at runtime and call the currently installed constraint handler function:
+
+
    +
  • buf or time_ptr is a null pointer
    • +
  • bufsz is less than 26 or greater than RSIZE_MAX
    • +
  • not all members of *time_ptr are within their normal ranges
    • +
  • the year indicated by time_ptr->tm_year is less than 0 or greater than 9999
    • +
+
As with all bounds-checked functions, asctime_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <time.h>.
+
+

Parameters

+ + + +
time_ptr - pointer to a tm object specifying the time to print
buf - pointer to a user-supplied buffer at least 26 bytes in length
bufsz - size of the user-supplied buffer

Return value

+1) pointer to a static null-terminated character string holding the textual representation of date and time as described above. The string may be shared between asctime and ctime, and may be overwritten on each invocation of any of those functions.
+2) zero on success, non-zero on failure, in which case buf[0] is set to zero (unless buf is a null pointer or bufsz is zero or greater than RSIZE_MAX).

Notes

asctime returns a pointer to static data and is not thread-safe. POSIX marks this function obsolete and recommends strftime instead. The C standard also recommends strftime instead of asctime and asctime_s because strftime is more flexible and locale-sensitive.

+

POSIX limits undefined behaviors only to when the output string would be longer than 25 characters, when timeptr->tm_wday or timeptr->tm_mon are not within the expected ranges, or when timeptr->tm_year exceeds INT_MAX-1990.

+

Some implementations handle timeptr->tm_mday==0 as meaning the last day of the preceding month.

+

Example

#define __STDC_WANT_LIB_EXT1__ 1
+#include <time.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    struct tm tm = *localtime(&(time_t){time(NULL)});
+    printf("%s", asctime(&tm));
+ 
+#ifdef __STDC_LIB_EXT1__
+    char str[26];
+    asctime_s(str, sizeof str, &tm);
+    printf("%s", str);
+#endif
+}

Possible output:

+
Tue May 26 21:51:50 2015
+Tue May 26 21:51:50 2015

References

See also

+ + +
+
(deprecated in C23)(C11)
 converts a time_t object to a textual representation
(function)
converts a tm object to custom textual representation
(function)
C++ documentation for asctime
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/chrono/asctime +

+
diff --git a/devdocs/c/chrono%2Fclock.html b/devdocs/c/chrono%2Fclock.html new file mode 100644 index 00000000..3f1ec38a --- /dev/null +++ b/devdocs/c/chrono%2Fclock.html @@ -0,0 +1,83 @@ +

clock

Defined in header <time.h> 
clock_t clock(void);
+

Returns the approximate processor time used by the process since the beginning of an implementation-defined era related to the program's execution. To convert result value to seconds, divide it by CLOCKS_PER_SEC.

+

Only the difference between two values returned by different calls to clock is meaningful, as the beginning of the clock era does not have to coincide with the start of the program. clock time may advance faster or slower than the wall clock, depending on the execution resources given to the program by the operating system. For example, if the CPU is shared by other processes, clock time may advance slower than wall clock. On the other hand, if the current process is multithreaded and more than one execution core is available, clock time may advance faster than wall clock.

+

Parameters

(none)

+

Return value

Processor time used by the program so far or (clock_t)(-1) if that information is unavailable or its value cannot be represented.

+

Notes

On POSIX-compatible systems, clock_gettime with clock id CLOCK_PROCESS_CPUTIME_ID offers better resolution.

+

The value returned by clock() may wrap around on some non-conforming implementations. For example, on such an implementation, if clock_t is a signed 32-bit integer and CLOCKS_PER_SEC is 1000000, it will wrap after about 2147 seconds (about 36 minutes).

+

Example

+

This example demonstrates the difference between clock() time and real time.

+
#ifndef __STDC_NO_THREADS__
+    #include <threads.h>
+#else
+    // POSIX alternative
+    #define _POSIX_C_SOURCE 199309L
+    #include <pthread.h>
+#endif
+ 
+#include <stdio.h>
+#include <stdlib.h>
+#include <time.h>
+ 
+// the function f() does some time-consuming work
+int f(void* thr_data) // return void* in POSIX
+{
+    (void) thr_data;
+    volatile double d = 0;
+    for (int n = 0; n < 10000; ++n)
+       for (int m = 0; m < 10000; ++m)
+           d += d * n * m;
+    return 0;
+}
+ 
+int main(void)
+{
+    struct timespec ts1, tw1; // both C11 and POSIX
+    clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &ts1); // POSIX
+    clock_gettime(CLOCK_MONOTONIC, &tw1); // POSIX; use timespec_get in C11
+    clock_t t1 = clock();
+ 
+#ifndef __STDC_NO_THREADS__
+    thrd_t thr1, thr2;  // C11; use pthread_t in POSIX
+    thrd_create(&thr1, f, NULL); // C11; use pthread_create in POSIX
+    thrd_create(&thr2, f, NULL);
+    thrd_join(thr1, NULL); // C11; use pthread_join in POSIX
+    thrd_join(thr2, NULL);
+#endif
+ 
+    struct timespec ts2, tw2;
+    clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &ts2);
+    clock_gettime(CLOCK_MONOTONIC, &tw2);
+    clock_t t2 = clock();
+ 
+    double dur = 1000.0 * (t2 - t1) / CLOCKS_PER_SEC;
+    double posix_dur = 1000.0 * ts2.tv_sec + 1e-6 * ts2.tv_nsec
+                       - (1000.0 * ts1.tv_sec + 1e-6 * ts1.tv_nsec);
+    double posix_wall = 1000.0 * tw2.tv_sec + 1e-6 * tw2.tv_nsec
+                        - (1000.0 * tw1.tv_sec + 1e-6 * tw1.tv_nsec);
+ 
+    printf("CPU time used (per clock()): %.2f ms\n", dur);
+    printf("CPU time used (per clock_gettime()): %.2f ms\n", posix_dur);
+    printf("Wall time passed: %.2f ms\n", posix_wall);
+}

Possible output:

+
CPU time used (per clock()): 1580.00 ms
+CPU time used (per clock_gettime()): 1582.76 ms
+Wall time passed: 792.13 ms

References

See also

+ + +
+
(deprecated in C23)(C11)
 converts a time_t object to a textual representation
(function)
returns the current calendar time of the system as time since epoch
(function)
C++ documentation for clock
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/chrono/clock +

+
diff --git a/devdocs/c/chrono%2Fclock_t.html b/devdocs/c/chrono%2Fclock_t.html new file mode 100644 index 00000000..5946393a --- /dev/null +++ b/devdocs/c/chrono%2Fclock_t.html @@ -0,0 +1,37 @@ +

clock_t

Defined in header <time.h> 
typedef /* unspecified */ clock_t;
+

Arithmetic(until C11)Real(since C11) type capable of representing the processor time used by a process. It has implementation-defined range and precision.

+

Example

#include <stdio.h>
+#include <time.h>
+#include <math.h>
+ 
+volatile double sink;
+int main (void)
+{
+  clock_t start = clock();
+ 
+  for(size_t i=0; i<3141592; ++i)
+      sink+=sin(i);
+ 
+  clock_t end = clock();
+  double cpu_time_used = ((double) (end - start)) / CLOCKS_PER_SEC;
+ 
+  printf("for loop took %f seconds to execute \n", cpu_time_used);
+}

Possible output:

+
for loop took 0.271828 seconds to execute

References

See also

+ + +
returns raw processor clock time since the program is started
(function)
number of processor clock ticks per second
(macro constant)
C++ documentation for clock_t
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/chrono/clock_t +

+
diff --git a/devdocs/c/chrono%2Fclocks_per_sec.html b/devdocs/c/chrono%2Fclocks_per_sec.html new file mode 100644 index 00000000..a162b3ea --- /dev/null +++ b/devdocs/c/chrono%2Fclocks_per_sec.html @@ -0,0 +1,24 @@ +

CLOCKS_PER_SEC

Defined in header <time.h> 
#define CLOCKS_PER_SEC /*implementation defined*/
+

Expands to an expression (not necessarily a compile-time constant) of type clock_t equal to the number of clock ticks per second, as returned by clock().

+

Notes

POSIX defines CLOCKS_PER_SEC as one million, regardless of the actual precision of clock.

+

Until standardized as CLOCKS_PER_SEC in C89, this macro was sometimes known by its IEEE std 1003.1-1988 name CLK_TCK: that name was not included in C89 and was removed from POSIX itself in 1996 over ambiguity with _SC_CLK_TCK, which gives number of clocks per second for the function times()).

+

References

See also

+ + +
returns raw processor clock time since the program is started
(function)
processor time since era type
(typedef)
C++ documentation for CLOCKS_PER_SEC
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/chrono/CLOCKS_PER_SEC +

+
diff --git a/devdocs/c/chrono%2Fctime.html b/devdocs/c/chrono%2Fctime.html new file mode 100644 index 00000000..f68df0e7 --- /dev/null +++ b/devdocs/c/chrono%2Fctime.html @@ -0,0 +1,79 @@ +

ctime, ctime_s

Defined in header <time.h>
(1) 
char*                ctime( const time_t* timer );
 (until C23) 
[[deprecated]] char* ctime( const time_t* timer );
+		 (since C23) 
errno_t ctime_s( char *buf, rsize_t bufsz, const time_t* timer );
+		 (2) (since C11)
+1) Converts given time since epoch to a calendar local time and then to a textual representation, as if by calling asctime(localtime(timer)) or asctime(localtime_r(timer, &(struct tm){0}))(since C23). This function is deprecated and should not be used in new code.(since C23) +
+2) Same as (1), except that the function is equivalent to asctime_s(buf, bufsz, localtime_s(timer, &(struct tm){0})), and the following errors are detected at runtime and call the currently installed constraint handler function:
+
+
    +
  • buf or timer is a null pointer
    • +
  • bufsz is less than 26 or greater than RSIZE_MAX
    • +
+
As with all bounds-checked functions, ctime_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <time.h>.
+
+

The resulting string has the following format:

+
Www Mmm dd hh:mm:ss yyyy\n

The function does not support localization.

+

Parameters

+ + + +
timer - pointer to a time_t object specifying the time to print
buf - pointer to the first element of a char array of size at least bufsz
bufsz - max number of bytes to output, typically the size of the buffer pointed to by buf

Return value

+1) pointer to a static null-terminated character string holding the textual representation of date and time. The string may be shared between asctime and ctime, and may be overwritten on each invocation of any of those functions.
+2) zero on success (in which case the string representation of time has been written out to the array pointed to by buf), or non-zero on failure (in which case, the terminating null character is always written to buf[0] unless buf is a null pointer or bufsz is zero or greater than RSIZE_MAX.

Notes

ctime returns a pointer to static data and is not thread-safe. In addition, it modifies the static tm object which may be shared with gmtime and localtime. POSIX marks this function obsolete and recommends strftime instead. The C standard also recommends strftime instead of ctime and ctime_s because strftime is more flexible and locale-sensitive.

+

The behavior of ctime is undefined for the values of time_t that result in the string longer than 25 characters (e.g. year 10000).

+

Example

#define __STDC_WANT_LIB_EXT1__ 1
+#include <time.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    time_t result = time(NULL);
+    printf("%s", ctime(&result));
+ 
+#ifdef __STDC_LIB_EXT1__
+    char str[26];
+    ctime_s(str,sizeof str,&result);
+    printf("%s", str);
+#endif
+}

Possible output:

+
Tue May 26 21:51:03 2015
+Tue May 26 21:51:03 2015

References

See also

+ + +
+
(deprecated in C23)(C11)
 converts a tm object to a textual representation
(function)
converts a tm object to custom textual representation
(function)
C++ documentation for ctime
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/chrono/ctime +

+
diff --git a/devdocs/c/chrono%2Fdifftime.html b/devdocs/c/chrono%2Fdifftime.html new file mode 100644 index 00000000..d72402bb --- /dev/null +++ b/devdocs/c/chrono%2Fdifftime.html @@ -0,0 +1,45 @@ +

difftime

Defined in header <time.h> 
double difftime( time_t time_end, time_t time_beg );
+

Computes difference between two calendar times as time_t objects (time_end - time_beg) in seconds. If time_end refers to time point before time_beg then the result is negative.

+

Parameters

+ +
time_beg, time_end - times to compare

Return value

Difference between two times in seconds.

+

Notes

On POSIX systems, time_t is measured in seconds, and difftime is equivalent to arithmetic subtraction, but C and C++ allow fractional units for time_t.

+

Example

+

The following program computes the number of seconds that have passed since the beginning of the month.

+
#include <stdio.h>
+#include <time.h>
+ 
+int main(void)
+{
+    time_t now = time(0);
+ 
+    struct tm beg = *localtime(&now);
+ 
+    // set beg to the beginning of the month
+    beg.tm_hour = 0,
+    beg.tm_min = 0,
+    beg.tm_sec = 0,
+    beg.tm_mday = 1;
+ 
+    double seconds = difftime(now, mktime(&beg));
+ 
+    printf("%.f seconds have passed since the beginning of the month.\n", seconds);
+ 
+    return 0;
+}

Output:

+
1937968 seconds have passed since the beginning of the month.

References

See also

+
C++ documentation for difftime
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/chrono/difftime +

+
diff --git a/devdocs/c/chrono%2Fgmtime.html b/devdocs/c/chrono%2Fgmtime.html new file mode 100644 index 00000000..7aaae09c --- /dev/null +++ b/devdocs/c/chrono%2Fgmtime.html @@ -0,0 +1,71 @@ +

gmtime, gmtime_r, gmtime_s

Defined in header <time.h> 
struct tm *gmtime  ( const time_t *timer );
+		 (1) 
struct tm *gmtime_r( const time_t *timer, struct tm *buf );
+		 (2) (since C23) 
struct tm *gmtime_s( const time_t *restrict timer, struct tm *restrict buf );
+		 (3) (since C11)
+1) Converts given time since epoch (a time_t value pointed to by timer) into calendar time, expressed in Coordinated Universal Time (UTC) in the struct tm format. The result is stored in static storage and a pointer to that static storage is returned.
+2) Same as (1), except that the function uses user-provided storage buf for the result.
+3) Same as (1), except that the function uses user-provided storage buf for the result and that the following errors are detected at runtime and call the currently installed constraint handler function:
+
+
  • timer or buf is a null pointer
+
As with all bounds-checked functions, gmtime_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <time.h>.
+
+

Parameters

+ + +
timer - pointer to a time_t object to convert
buf - pointer to a struct tm object to store the result

Return value

+1) pointer to a static internal tm object on success, or null pointer otherwise. The structure may be shared between gmtime, localtime, and ctime and may be overwritten on each invocation.
+2-3) copy of the buf pointer, or null pointer on error (which may be a runtime constraint violation or a failure to convert the specified time to UTC)

Notes

gmtime may not be thread-safe.

+

POSIX requires that gmtime and gmtime_r set errno to EOVERFLOW if they fail because the argument is too large.

+

The implementation of gmtime_s in Microsoft CRT is incompatible with the C standard since it has reversed parameter order.

+

Example

#define __STDC_WANT_LIB_EXT1__ 1
+#define _XOPEN_SOURCE // for putenv
+#include <time.h>
+#include <stdio.h>
+#include <stdlib.h>   // for putenv
+ 
+int main(void)
+{
+    time_t t = time(NULL);
+    printf("UTC:       %s", asctime(gmtime(&t)));
+    printf("local:     %s", asctime(localtime(&t)));
+    // POSIX-specific
+    putenv("TZ=Asia/Singapore");
+    printf("Singapore: %s", asctime(localtime(&t)));
+ 
+#ifdef __STDC_LIB_EXT1__
+    struct tm buf;
+    char str[26];
+    asctime_s(str,sizeof str,gmtime_s(&t, &buf));
+    printf("UTC:       %s", str);
+    asctime_s(str,sizeof str,localtime_s(&t, &buf));
+    printf("local:     %s", str);
+#endif
+}

Possible output:

+
UTC:       Fri Sep 15 14:22:05 2017
+local:     Fri Sep 15 14:22:05 2017
+Singapore: Fri Sep 15 22:22:05 2017
+UTC:       Fri Sep 15 14:22:05 2017
+local:     Fri Sep 15 14:22:05 2017

References

See also

+ +
+
(C23)(C11)
 converts time since epoch to calendar time expressed as local time
(function)
C++ documentation for gmtime
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/chrono/gmtime +

+
diff --git a/devdocs/c/chrono%2Flocaltime.html b/devdocs/c/chrono%2Flocaltime.html new file mode 100644 index 00000000..75756995 --- /dev/null +++ b/devdocs/c/chrono%2Flocaltime.html @@ -0,0 +1,72 @@ +

localtime, localtime_r, localtime_s

Defined in header <time.h> 
struct tm *localtime  ( const time_t *timer );
+		 (1) 
struct tm *localtime_r( const time_t *timer, struct tm *buf );
+		 (2) (since C23) 
struct tm *localtime_s( const time_t *restrict timer, struct tm *restrict buf );
+		 (3) (since C11)
+1) Converts given time since epoch (a time_t value pointed to by timer) into calendar time, expressed in local time, in the struct tm format. The result is stored in static storage and a pointer to that static storage is returned.
+2) Same as (1), except that the function uses user-provided storage buf for the result.
+3) Same as (1), except that the function uses user-provided storage buf for the result and that the following errors are detected at runtime and call the currently installed constraint handler function:
+
+
  • timer or buf is a null pointer
+
As with all bounds-checked functions, localtime_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <time.h>.
+
+

Parameters

+ + +
timer - pointer to a time_t object to convert
buf - pointer to a struct tm object to store the result

Return value

+1) pointer to a static internal tm object on success, or null pointer otherwise. The structure may be shared between gmtime, localtime, and ctime and may be overwritten on each invocation.
+2-3) copy of the buf pointer, or null pointer on error (which may be a runtime constraint violation or a failure to convert the specified time to local calendar time)

Notes

The function localtime may not be thread-safe.

+

POSIX requires that localtime and localtime_r set errno to EOVERFLOW if it fails because the argument is too large.

+

POSIX specifies that the timezone information is determined by localtime and localtime_r as if by calling tzset, which reads the environment variable TZ.

+

The implementation of localtime_s in Microsoft CRT is incompatible with the C standard since it has reversed parameter order and returns errno_t.

+

Example

#define __STDC_WANT_LIB_EXT1__ 1
+#define _XOPEN_SOURCE // for putenv
+#include <time.h>
+#include <stdio.h>
+#include <stdlib.h>   // for putenv
+ 
+int main(void)
+{
+    time_t t = time(NULL);
+    printf("UTC:       %s", asctime(gmtime(&t)));
+    printf("local:     %s", asctime(localtime(&t)));
+    // POSIX-specific
+    putenv("TZ=Asia/Singapore");
+    printf("Singapore: %s", asctime(localtime(&t)));
+ 
+#ifdef __STDC_LIB_EXT1__
+    struct tm buf;
+    char str[26];
+    asctime_s(str,sizeof str,gmtime_s(&t, &buf));
+    printf("UTC:       %s", str);
+    asctime_s(str,sizeof str,localtime_s(&t, &buf));
+    printf("local:     %s", str);
+#endif
+}

Possible output:

+
UTC:       Fri Sep 15 14:22:05 2017
+local:     Fri Sep 15 14:22:05 2017
+Singapore: Fri Sep 15 22:22:05 2017
+UTC:       Fri Sep 15 14:22:05 2017
+local:     Fri Sep 15 14:22:05 2017

References

See also

+ +
+
(C23)(C11)
 converts time since epoch to calendar time expressed as Coordinated Universal Time (UTC)
(function)
C++ documentation for localtime
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/chrono/localtime +

+
diff --git a/devdocs/c/chrono%2Fmktime.html b/devdocs/c/chrono%2Fmktime.html new file mode 100644 index 00000000..d4a34bc9 --- /dev/null +++ b/devdocs/c/chrono%2Fmktime.html @@ -0,0 +1,46 @@ +

mktime

Defined in header <time.h> 
time_t mktime( struct tm *arg );
+

Renormalizes local calendar time expressed as a struct tm object and also converts it to time since epoch as a time_t object. arg->tm_wday and arg->tm_yday are ignored. The values in arg are not checked for being out of range.

+

A negative value of arg->tm_isdst causes mktime to attempt to determine if Daylight Saving Time was in effect in the specified time.

+

If the conversion to time_t is successful, the arg object is modified. All fields of arg are updated to fit their proper ranges. arg->tm_wday and arg->tm_yday are recalculated using information available in other fields.

+

Parameters

+ +
arg - pointer to a tm object specifying local calendar time to convert

Return value

time since epoch as a time_t object on success, or -1 if arg cannot be represented as a time_t object (POSIX also requires EOVERFLOW to be stored in errno in this case).

+

Notes

If the struct tm object was obtained from POSIX strptime or equivalent function, the value of tm_isdst is indeterminate, and needs to be set explicitly before calling mktime.

+

Example

#define _POSIX_C_SOURCE 200112L // for setenv on gcc
+#include <stdlib.h>
+#include <stdio.h>
+#include <time.h>
+ 
+int main(void)
+{
+    setenv("TZ", "/usr/share/zoneinfo/America/New_York", 1); // POSIX-specific
+ 
+    struct tm tm = *localtime(&(time_t){time(NULL)});
+    printf("Today is           %s", asctime(&tm));
+    printf("(DST is %s)\n", tm.tm_isdst ? "in effect" : "not in effect");
+    tm.tm_mon -= 100;  // tm_mon is now outside its normal range
+    mktime(&tm);       // tm_isdst is not set to -1; today's DST status is used
+    printf("100 months ago was %s", asctime(&tm));
+    printf("(DST was %s)\n", tm.tm_isdst ? "in effect" : "not in effect");
+}

Possible output:

+
Today is           Fri Apr 22 11:53:36 2016
+(DST is in effect)
+100 months ago was Sat Dec 22 10:53:36 2007
+(DST was not in effect)

References

See also

+ +
+
(C23)(C11)
 converts time since epoch to calendar time expressed as local time
(function)
C++ documentation for mktime
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/chrono/mktime +

+
diff --git a/devdocs/c/chrono%2Fstrftime.html b/devdocs/c/chrono%2Fstrftime.html new file mode 100644 index 00000000..8cef9684 --- /dev/null +++ b/devdocs/c/chrono%2Fstrftime.html @@ -0,0 +1,146 @@ +

strftime

Defined in header <time.h> 
size_t strftime( char*          str, size_t count,
+                 const char*          format, const struct tm*          tp );
+		 (until C99) 
size_t strftime( char* restrict str, size_t count,
+                 const char* restrict format, const struct tm* restrict tp );
+		 (since C99)

Converts the date and time information from a given calendar time tp to a null-terminated multibyte character string str according to format string format. Up to count bytes are written.

+

Parameters

+ + + + +
str - pointer to the first element of the char array for output
count - maximum number of bytes to write
format - pointer to a null-terminated multibyte character string specifying the format of conversion
tp - pointer to a struct tm object specifying the time to format

Format string

The format string consists of zero or more conversion specifiers and ordinary characters (except %). All ordinary characters, including the terminating null character, are copied to the output string without modification. Each conversion specification begins with % character, optionally followed by E or O modifier (ignored if unsupported by the locale), followed by the character that determines the behavior of the specifier. The following format specifiers are available:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Conversion
specifier 		Explanation Used fields
% writes literal %. The full conversion specification must be %%.
n
(C99) 		writes newline character
t
(C99) 		writes horizontal tab character
Year
Y writes year as a decimal number, e.g. 2017 tm_year
EY
(C99) 		writes year in the alternative representation, e.g.平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale tm_year
y writes last 2 digits of year as a decimal number (range [00,99]) tm_year
Oy
(C99) 		writes last 2 digits of year using the alternative numeric system, e.g. 十一 instead of 11 in ja_JP locale tm_year
Ey
(C99) 		writes year as offset from locale's alternative calendar period %EC (locale-dependent) tm_year
C
(C99) 		writes first 2 digits of year as a decimal number (range [00,99]) tm_year
EC
(C99) 		writes name of the base year (period) in the locale's alternative representation, e.g. 平成 (Heisei era) in ja_JP tm_year
G
(C99) 		writes ISO 8601 week-based year, i.e. the year that contains the specified week.

In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the following requirements:

+
    +
  • Includes January 4
    • +
  • Includes first Thursday of the year
    • +
 tm_year, tm_wday, tm_yday
g
(C99) 		writes last 2 digits of ISO 8601 week-based year, i.e. the year that contains the specified week (range [00,99]).

In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the following requirements:

+
    +
  • Includes January 4
    • +
  • Includes first Thursday of the year
    • +
 tm_year, tm_wday, tm_yday
Month
b writes abbreviated month name, e.g. Oct (locale dependent) tm_mon
Ob
(C23) 		writes abbreviated month name in the locale's alternative representation tm_mon
h
(C99) 		synonym of b tm_mon
B writes full month name, e.g. October (locale dependent) tm_mon
OB
(C23) 		writes appropriate full month name in the locale's alternative representation tm_mon
m writes month as a decimal number (range [01,12]) tm_mon
Om
(C99) 		writes month using the alternative numeric system, e.g. 十二 instead of 12 in ja_JP locale tm_mon
Week
U writes week of the year as a decimal number (Sunday is the first day of the week) (range [00,53]) tm_year, tm_wday, tm_yday
OU
(C99) 		writes week of the year, as by %U, using the alternative numeric system, e.g. 五十二 instead of 52 in ja_JP locale tm_year, tm_wday, tm_yday
W writes week of the year as a decimal number (Monday is the first day of the week) (range [00,53]) tm_year, tm_wday, tm_yday
OW
(C99) 		writes week of the year, as by %W, using the alternative numeric system, e.g. 五十二 instead of 52 in ja_JP locale tm_year, tm_wday, tm_yday
V
(C99) 		writes ISO 8601 week of the year (range [01,53]).

In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the following requirements:

+
    +
  • Includes January 4
    • +
  • Includes first Thursday of the year
    • +
 tm_year, tm_wday, tm_yday
OV
(C99) 		writes week of the year, as by %V, using the alternative numeric system, e.g. 五十二 instead of 52 in ja_JP locale tm_year, tm_wday, tm_yday
Day of the year/month
j writes day of the year as a decimal number (range [001,366]) tm_yday
d writes day of the month as a decimal number (range [01,31]) tm_mday
Od
(C99) 		writes zero-based day of the month using the alternative numeric system, e.g. 二十七 instead of 27 in ja_JP locale

Single character is preceded by a space.

+		 tm_mday
e
(C99) 		writes day of the month as a decimal number (range [1,31]).

Single digit is preceded by a space.

+		 tm_mday
Oe
(C99) 		writes one-based day of the month using the alternative numeric system, e.g. 二十七 instead of 27 in ja_JP locale

Single character is preceded by a space.

+		 tm_mday
Day of the week
a writes abbreviated weekday name, e.g. Fri (locale dependent) tm_wday
A writes full weekday name, e.g. Friday (locale dependent) tm_wday
w writes weekday as a decimal number, where Sunday is 0 (range [0-6]) tm_wday
Ow
(C99) 		writes weekday, where Sunday is 0, using the alternative numeric system, e.g. 二 instead of 2 in ja_JP locale tm_wday
u
(C99) 		writes weekday as a decimal number, where Monday is 1 (ISO 8601 format) (range [1-7]) tm_wday
Ou
(C99) 		writes weekday, where Monday is 1, using the alternative numeric system, e.g. 二 instead of 2 in ja_JP locale tm_wday
Hour, minute, second
H writes hour as a decimal number, 24 hour clock (range [00-23]) tm_hour
OH
(C99) 		writes hour from 24-hour clock using the alternative numeric system, e.g. 十八 instead of 18 in ja_JP locale tm_hour
I writes hour as a decimal number, 12 hour clock (range [01,12]) tm_hour
OI
(C99) 		writes hour from 12-hour clock using the alternative numeric system, e.g. 六 instead of 06 in ja_JP locale tm_hour
M writes minute as a decimal number (range [00,59]) tm_min
OM
(C99) 		writes minute using the alternative numeric system, e.g. 二十五 instead of 25 in ja_JP locale tm_min
S writes second as a decimal number (range [00,60]) tm_sec
OS
(C99) 		writes second using the alternative numeric system, e.g. 二十四 instead of 24 in ja_JP locale tm_sec
Other
c writes standard date and time string, e.g. Sun Oct 17 04:41:13 2010 (locale dependent) all
Ec
(C99) 		writes alternative date and time string, e.g. using 平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale all
x writes localized date representation (locale dependent) all
Ex
(C99) 		writes alternative date representation, e.g. using 平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale all
X writes localized time representation, e.g. 18:40:20 or 6:40:20 PM (locale dependent) all
EX
(C99) 		writes alternative time representation (locale dependent) all
D
(C99) 		equivalent to "%m/%d/%y" tm_mon, tm_mday, tm_year
F
(C99) 		equivalent to "%Y-%m-%d" (the ISO 8601 date format) tm_mon, tm_mday, tm_year
r
(C99) 		writes localized 12-hour clock time (locale dependent) tm_hour, tm_min, tm_sec
R
(C99) 		equivalent to "%H:%M" tm_hour, tm_min
T
(C99) 		equivalent to "%H:%M:%S" (the ISO 8601 time format) tm_hour, tm_min, tm_sec
p writes localized a.m. or p.m. (locale dependent) tm_hour
z
(C99) 		writes offset from UTC in the ISO 8601 format (e.g. -0430), or no characters if the time zone information is not available tm_isdst
Z writes locale-dependent time zone name or abbreviation, or no characters if the time zone information is not available tm_isdst

Return value

The number of bytes written into the character array pointed to by str not including the terminating '\0' on success. If count was reached before the entire string could be stored, ​0​ is returned and the contents are indeterminate.

+

Example

#include <locale.h>
+#include <stdio.h>
+#include <time.h>
+ 
+int main(void)
+{
+    char buff[70];
+    struct tm my_time = { .tm_year=112, // = year 2012
+                          .tm_mon=9,    // = 10th month
+                          .tm_mday=9,   // = 9th day
+                          .tm_hour=8,   // = 8 hours
+                          .tm_min=10,   // = 10 minutes
+                          .tm_sec=20    // = 20 secs
+    };
+ 
+    if (strftime(buff, sizeof buff, "%A %c", &my_time))
+        puts(buff);
+    else
+        puts("strftime failed");
+ 
+    setlocale(LC_TIME, "el_GR.utf8");
+ 
+    if (strftime(buff, sizeof buff, "%A %c", &my_time))
+        puts(buff);
+    else
+        puts("strftime failed");
+}

Possible output:

+
Sunday Sun Oct  9 08:10:20 2012
+Κυριακή Κυρ 09 Οκτ 2012 08:10:20 πμ EST

References

See also

+ + + +
+
(deprecated in C23)(C11)
 converts a tm object to a textual representation
(function)
+
(deprecated in C23)(C11)
 converts a time_t object to a textual representation
(function)
+
(C95)
 converts a tm object to custom wide string textual representation
(function)
C++ documentation for strftime
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/chrono/strftime +

+
diff --git a/devdocs/c/chrono%2Ftime.html b/devdocs/c/chrono%2Ftime.html new file mode 100644 index 00000000..b7656af1 --- /dev/null +++ b/devdocs/c/chrono%2Ftime.html @@ -0,0 +1,40 @@ +

time

Defined in header <time.h> 
time_t time( time_t *arg );
+

Returns the current calendar time encoded as a time_t object, and also stores it in the time_t object pointed to by arg (unless arg is a null pointer)

+

Parameters

+ +
arg - pointer to a time_t object where the time will be stored, or a null pointer

Return value

Current calendar time encoded as time_t object on success, (time_t)(-1) on error. If arg is not a null pointer, the return value is also stored in the object pointed to by arg.

+

Notes

The encoding of calendar time in time_t is unspecified, but most systems conform to POSIX specification and return a value of integral type holding the number of seconds since the Epoch. Implementations in which time_t is a 32-bit signed integer (many historical implementations) fail in the year 2038.

+

Example

#include <stdio.h>
+#include <time.h>
+#include <stdint.h>
+ 
+int main(void)
+{
+    time_t result = time(NULL);
+    if(result != (time_t)(-1))
+        printf("The current time is %s(%jd seconds since the Epoch)\n",
+               asctime(gmtime(&result)), (intmax_t)result);
+}

Possible output:

+
The current time is Fri Apr 24 15:05:25 2015
+(1429887925 seconds since the Epoch)

References

See also

+ + + +
+
(C23)(C11)
 converts time since epoch to calendar time expressed as local time
(function)
+
(C23)(C11)
 converts time since epoch to calendar time expressed as Coordinated Universal Time (UTC)
(function)
+
(C11)
 returns the calendar time in seconds and nanoseconds based on a given time base
(function)
C++ documentation for time
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/chrono/time +

+
diff --git a/devdocs/c/chrono%2Ftime_t.html b/devdocs/c/chrono%2Ftime_t.html new file mode 100644 index 00000000..d6e589de --- /dev/null +++ b/devdocs/c/chrono%2Ftime_t.html @@ -0,0 +1,38 @@ +

time_t

Defined in header <time.h> 
typedef /* unspecified */ time_t;
+

Real arithmetic type capable of representing times.

+

Although not defined by the C standard, this is almost always an integral value holding the number of seconds (not counting leap seconds) since 00:00, Jan 1 1970 UTC, corresponding to POSIX time.

+

Notes

The standard uses the term calendar time when referring to a value of type time_t.

+

Example

+

Show the start of the epoch.

+
#include <stdio.h>
+#include <time.h>
+#include <stdint.h>
+ 
+int main(void)
+{
+    time_t epoch = 0;
+    printf("%jd seconds since the epoch began\n", (intmax_t)epoch);
+    printf("%s", asctime(gmtime(&epoch)));
+}

Possible output:

+
0 seconds since the epoch began
+Thu Jan  1 00:00:00 1970

References

See also

+ + + +
returns the current calendar time of the system as time since epoch
(function)
+
(C23)(C11)
 converts time since epoch to calendar time expressed as local time
(function)
+
(C23)(C11)
 converts time since epoch to calendar time expressed as Coordinated Universal Time (UTC)
(function)
C++ documentation for time_t
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/chrono/time_t +

+
diff --git a/devdocs/c/chrono%2Ftimespec.html b/devdocs/c/chrono%2Ftimespec.html new file mode 100644 index 00000000..f799f3a3 --- /dev/null +++ b/devdocs/c/chrono%2Ftimespec.html @@ -0,0 +1,43 @@ +

timespec

Defined in header <time.h> 
struct timespec;
+		 (since C11)

Structure holding an interval broken down into seconds and nanoseconds.

+

Member objects

+ +
time_t tv_sec whole seconds (valid values are >= 0)
/* see below */ tv_nsec nanoseconds (valid values are [0, 999999999])
+ + + +

The type of tv_nsec is long.

+		 (until C23)

The type of tv_nsec is an implementation-defined signed integer type that can represent integers in [0, 999999999].

+		 (since C23)

The declaration order of tv_sec and tv_nsec is unspecified. Implementation may add other members to struct timespec.

+

Notes

The type of tv_nsec is long long on some platforms, which is conforming only since C23.

+

Example

#include <stdio.h>
+#include <time.h>
+#include <stdint.h>
+ 
+int main(void)
+{
+    struct timespec ts;
+    timespec_get(&ts, TIME_UTC);
+    char buff[100];
+    strftime(buff, sizeof buff, "%D %T", gmtime(&ts.tv_sec));
+    printf("Current time: %s.%09ld UTC\n", buff, ts.tv_nsec);
+    printf("Raw timespec.time_t: %jd\n", (intmax_t)ts.tv_sec);
+    printf("Raw timespec.tv_nsec: %09ld\n", ts.tv_nsec);
+}

Possible output:

+
Current time: 11/24/21 03:10:50.408191283 UTC
+Raw timespec.time_t: 1637723450
+Raw timespec.tv_nsec: 408191283

References

See also

+ + +
+
(C11)
 returns the calendar time in seconds and nanoseconds based on a given time base
(function)
calendar time type
(struct)
C++ documentation for timespec
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/chrono/timespec +

+
diff --git a/devdocs/c/chrono%2Ftimespec_get.html b/devdocs/c/chrono%2Ftimespec_get.html new file mode 100644 index 00000000..ab32e7f2 --- /dev/null +++ b/devdocs/c/chrono%2Ftimespec_get.html @@ -0,0 +1,43 @@ +

timespec_get

Defined in header <time.h> 
int timespec_get( struct timespec *ts, int base );
+		 (1) (since C11) 
#define TIME_UTC /* implementation-defined */
+		 (2) (since C11)
+1) Modifies the timespec object pointed to by ts to hold the current calendar time in the time base base.
+2) Expands to a value suitable for use as the base argument of timespec_get +

Other macro constants beginning with TIME_ may be provided by the implementation to indicate additional time bases

+

If base is TIME_UTC, then

+

Parameters

+ + +
ts - pointer to an object of type struct timespec
base - TIME_UTC or another nonzero integer value indicating the time base

Return value

The value of base if successful, zero otherwise.

+

Notes

The POSIX function clock_gettime(CLOCK_REALTIME, ts) may also be used to populate a timespec with the time since the Epoch.

+

Example

#include <stdio.h>
+#include <time.h>
+ 
+int main(void)
+{
+    struct timespec ts;
+    timespec_get(&ts, TIME_UTC);
+    char buff[100];
+    strftime(buff, sizeof buff, "%D %T", gmtime(&ts.tv_sec));
+    printf("Current time: %s.%09ld UTC\n", buff, ts.tv_nsec);
+}

Possible output:

+
Current time: 02/18/15 14:34:03.048508855 UTC

References

See also

+ + + +
+
(C11)
 time in seconds and nanoseconds
(struct)
+
(C23)
 returns the resolution of calendar time based on a given time base
(function)
returns the current calendar time of the system as time since epoch
(function)
C++ documentation for timespec_get
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/chrono/timespec_get +

+
diff --git a/devdocs/c/chrono%2Ftimespec_getres.html b/devdocs/c/chrono%2Ftimespec_getres.html new file mode 100644 index 00000000..b40a3243 --- /dev/null +++ b/devdocs/c/chrono%2Ftimespec_getres.html @@ -0,0 +1,34 @@ +

timespec_getres

Defined in header <time.h> 
int timespec_getres( struct timespec *ts, int base );
+		 (since C23)

If ts is non-null and base is supported by timespec_get, modifies *ts to hold the resolution of time provided by timespec_get for base. For each supported base, multiple calls to timespec_getres during the same program execution have identical results.

+

Parameters

+ + +
ts - pointer to an object of type struct timespec
base - TIME_UTC or another nonzero integer value indicating the time base

Return value

The value of base if base is supported, zero otherwise.

+

Notes

The POSIX function clock_getres(clock_id, ts) may also be used to populate a timespec with the resolution of time identified by clock_id.

+

Example

#include <stdio.h>
+#include <time.h>
+ 
+int main(void)
+{
+    char buff[128];
+    struct timespec ts;
+    const int res = timespec_getres(&ts, TIME_UTC);
+    if (res == TIME_UTC) {
+        struct tm timer;
+        strftime(buff, sizeof buff, "%D %T", gmtime_r(&ts.tv_sec, &timer));
+        printf("Time resolution info: %s.%09ld UTC\n", buff, ts.tv_nsec);
+    } else {
+        printf("TIME_UTC base is not supported.");
+    }
+}

Possible output:

+
Time resolution info: 01/01/70 00:00:00.000000001 UTC

See also

+ + +
+
(C11)
 time in seconds and nanoseconds
(struct)
+
(C11)
 returns the calendar time in seconds and nanoseconds based on a given time base
(function)
returns the current calendar time of the system as time since epoch
(function)
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/chrono/timespec_getres +

+
diff --git a/devdocs/c/chrono%2Ftm.html b/devdocs/c/chrono%2Ftm.html new file mode 100644 index 00000000..f14a6474 --- /dev/null +++ b/devdocs/c/chrono%2Ftm.html @@ -0,0 +1,41 @@ +

tm

Defined in header <time.h> 
struct tm;
+

Structure holding a calendar date and time broken down into its components.

+

Member objects

+ + + + + + + + +
int tm_sec
 seconds after the minute – [0, 61](until C99)[0, 60](since C99)[note 1]
(public member object)
int tm_min
 minutes after the hour – [0, 59]
(public member object)
int tm_hour
 hours since midnight – [0, 23]
(public member object)
int tm_mday
 day of the month – [1, 31]
(public member object)
int tm_mon
 months since January – [0, 11]
(public member object)
int tm_year
 years since 1900
(public member object)
int tm_wday
 days since Sunday – [0, 6]
(public member object)
int tm_yday
 days since January 1 – [0, 365]
(public member object)
int tm_isdst
 Daylight Saving Time flag. The value is positive if DST is in effect, zero if not and negative if no information is available
(public member object)
Notes

The Standard mandates only the presence of the aforementioned members in either order. The implementations usually add more data-members to this structure.

+
  1. Range allows for a positive leap second. Two leap seconds in the same minute are not allowed (the C89 range 0..61 was a defect)

Example

#include <stdio.h>
+#include <time.h>
+ 
+int main(void)
+{
+    struct tm start = {.tm_year=2022-1900, .tm_mday=1};
+    mktime(&start);
+    printf("%s", asctime(&start));
+}

Output:

+
Sat Jan  1 00:00:00 2022

References

See also

+ + +
+
(C23)(C11)
 converts time since epoch to calendar time expressed as local time
(function)
+
(C23)(C11)
 converts time since epoch to calendar time expressed as Coordinated Universal Time (UTC)
(function)
C++ documentation for tm
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/chrono/tm +

+
diff --git a/devdocs/c/chrono%2Fwcsftime.html b/devdocs/c/chrono%2Fwcsftime.html new file mode 100644 index 00000000..1b020763 --- /dev/null +++ b/devdocs/c/chrono%2Fwcsftime.html @@ -0,0 +1,136 @@ +

wcsftime

Defined in header <wchar.h> 
size_t wcsftime( wchar_t* str, size_t count, const wchar_t* format, tm* time );
+		 (since C95)

Converts the date and time information from a given calendar time time to a null-terminated wide character string str according to format string format. Up to count bytes are written.

+

Parameters

+ + + +
str - pointer to the first element of the wchar_t array for output
count - maximum number of wide characters to write
format - pointer to a null-terminated wide character string specifying the format of conversion

Format string

The format string consists of zero or more conversion specifiers and ordinary characters (except %). All ordinary characters, including the terminating null character, are copied to the output string without modification. Each conversion specification begins with % character, optionally followed by E or O modifier (ignored if unsupported by the locale), followed by the character that determines the behavior of the specifier. The following format specifiers are available:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Conversion
specifier 		Explanation Used fields
% writes literal %. The full conversion specification must be %%.
n
(C99) 		writes newline character
t
(C99) 		writes horizontal tab character
Year
Y writes year as a decimal number, e.g. 2017 tm_year
EY
(C99) 		writes year in the alternative representation, e.g.平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale tm_year
y writes last 2 digits of year as a decimal number (range [00,99]) tm_year
Oy
(C99) 		writes last 2 digits of year using the alternative numeric system, e.g. 十一 instead of 11 in ja_JP locale tm_year
Ey
(C99) 		writes year as offset from locale's alternative calendar period %EC (locale-dependent) tm_year
C
(C99) 		writes first 2 digits of year as a decimal number (range [00,99]) tm_year
EC
(C99) 		writes name of the base year (period) in the locale's alternative representation, e.g. 平成 (Heisei era) in ja_JP tm_year
G
(C99) 		writes ISO 8601 week-based year, i.e. the year that contains the specified week.

In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the following requirements:

+
    +
  • Includes January 4
    • +
  • Includes first Thursday of the year
    • +
 tm_year, tm_wday, tm_yday
g
(C99) 		writes last 2 digits of ISO 8601 week-based year, i.e. the year that contains the specified week (range [00,99]).

In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the following requirements:

+
    +
  • Includes January 4
    • +
  • Includes first Thursday of the year
    • +
 tm_year, tm_wday, tm_yday
Month
b writes abbreviated month name, e.g. Oct (locale dependent) tm_mon
Ob
(C23) 		writes abbreviated month name in the locale's alternative representation tm_mon
h
(C99) 		synonym of b tm_mon
B writes full month name, e.g. October (locale dependent) tm_mon
OB
(C23) 		writes appropriate full month name in the locale's alternative representation tm_mon
m writes month as a decimal number (range [01,12]) tm_mon
Om
(C99) 		writes month using the alternative numeric system, e.g. 十二 instead of 12 in ja_JP locale tm_mon
Week
U writes week of the year as a decimal number (Sunday is the first day of the week) (range [00,53]) tm_year, tm_wday, tm_yday
OU
(C99) 		writes week of the year, as by %U, using the alternative numeric system, e.g. 五十二 instead of 52 in ja_JP locale tm_year, tm_wday, tm_yday
W writes week of the year as a decimal number (Monday is the first day of the week) (range [00,53]) tm_year, tm_wday, tm_yday
OW
(C99) 		writes week of the year, as by %W, using the alternative numeric system, e.g. 五十二 instead of 52 in ja_JP locale tm_year, tm_wday, tm_yday
V
(C99) 		writes ISO 8601 week of the year (range [01,53]).

In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the following requirements:

+
    +
  • Includes January 4
    • +
  • Includes first Thursday of the year
    • +
 tm_year, tm_wday, tm_yday
OV
(C99) 		writes week of the year, as by %V, using the alternative numeric system, e.g. 五十二 instead of 52 in ja_JP locale tm_year, tm_wday, tm_yday
Day of the year/month
j writes day of the year as a decimal number (range [001,366]) tm_yday
d writes day of the month as a decimal number (range [01,31]) tm_mday
Od
(C99) 		writes zero-based day of the month using the alternative numeric system, e.g. 二十七 instead of 27 in ja_JP locale

Single character is preceded by a space.

+		 tm_mday
e
(C99) 		writes day of the month as a decimal number (range [1,31]).

Single digit is preceded by a space.

+		 tm_mday
Oe
(C99) 		writes one-based day of the month using the alternative numeric system, e.g. 二十七 instead of 27 in ja_JP locale

Single character is preceded by a space.

+		 tm_mday
Day of the week
a writes abbreviated weekday name, e.g. Fri (locale dependent) tm_wday
A writes full weekday name, e.g. Friday (locale dependent) tm_wday
w writes weekday as a decimal number, where Sunday is 0 (range [0-6]) tm_wday
Ow
(C99) 		writes weekday, where Sunday is 0, using the alternative numeric system, e.g. 二 instead of 2 in ja_JP locale tm_wday
u
(C99) 		writes weekday as a decimal number, where Monday is 1 (ISO 8601 format) (range [1-7]) tm_wday
Ou
(C99) 		writes weekday, where Monday is 1, using the alternative numeric system, e.g. 二 instead of 2 in ja_JP locale tm_wday
Hour, minute, second
H writes hour as a decimal number, 24 hour clock (range [00-23]) tm_hour
OH
(C99) 		writes hour from 24-hour clock using the alternative numeric system, e.g. 十八 instead of 18 in ja_JP locale tm_hour
I writes hour as a decimal number, 12 hour clock (range [01,12]) tm_hour
OI
(C99) 		writes hour from 12-hour clock using the alternative numeric system, e.g. 六 instead of 06 in ja_JP locale tm_hour
M writes minute as a decimal number (range [00,59]) tm_min
OM
(C99) 		writes minute using the alternative numeric system, e.g. 二十五 instead of 25 in ja_JP locale tm_min
S writes second as a decimal number (range [00,60]) tm_sec
OS
(C99) 		writes second using the alternative numeric system, e.g. 二十四 instead of 24 in ja_JP locale tm_sec
Other
c writes standard date and time string, e.g. Sun Oct 17 04:41:13 2010 (locale dependent) all
Ec
(C99) 		writes alternative date and time string, e.g. using 平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale all
x writes localized date representation (locale dependent) all
Ex
(C99) 		writes alternative date representation, e.g. using 平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale all
X writes localized time representation, e.g. 18:40:20 or 6:40:20 PM (locale dependent) all
EX
(C99) 		writes alternative time representation (locale dependent) all
D
(C99) 		equivalent to "%m/%d/%y" tm_mon, tm_mday, tm_year
F
(C99) 		equivalent to "%Y-%m-%d" (the ISO 8601 date format) tm_mon, tm_mday, tm_year
r
(C99) 		writes localized 12-hour clock time (locale dependent) tm_hour, tm_min, tm_sec
R
(C99) 		equivalent to "%H:%M" tm_hour, tm_min
T
(C99) 		equivalent to "%H:%M:%S" (the ISO 8601 time format) tm_hour, tm_min, tm_sec
p writes localized a.m. or p.m. (locale dependent) tm_hour
z
(C99) 		writes offset from UTC in the ISO 8601 format (e.g. -0430), or no characters if the time zone information is not available tm_isdst
Z writes locale-dependent time zone name or abbreviation, or no characters if the time zone information is not available tm_isdst

Return value

number of wide characters written into the wide character array pointed to by str not including the terminating L'\0' on success. If count was reached before the entire string could be stored, ​0​ is returned and the contents are undefined.

+

Example

#include <stdio.h>
+#include <time.h>
+#include <wchar.h>
+#include <locale.h>
+ 
+int main(void)
+{
+    wchar_t buff[40];
+    struct tm my_time = { .tm_year=112, // = year 2012
+                          .tm_mon=9,    // = 10th month
+                          .tm_mday=9,   // = 9th day
+                          .tm_hour=8,   // = 8 hours
+                          .tm_min=10,   // = 10 minutes
+                          .tm_sec=20    // = 20 secs
+    };
+ 
+    if (wcsftime(buff, sizeof buff, L"%A %c", &my_time)) {
+        printf("%ls\n", buff);
+    } else {
+        puts("wcsftime failed");
+    }
+ 
+    setlocale(LC_ALL, "ja_JP.utf8");
+ 
+    if (wcsftime(buff, sizeof buff, L"%A %c", &my_time)) {
+        printf("%ls\n", buff);
+    } else {
+        puts("wcsftime failed");
+    }
+}

Output:

+
Sunday Sun Oct  9 08:10:20 2012
+日曜日 2012年10月09日 08時10分20秒

References

See also

+ +
converts a tm object to custom textual representation
(function)
C++ documentation for wcsftime
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/chrono/wcsftime +

+
diff --git a/devdocs/c/chrono.html b/devdocs/c/chrono.html new file mode 100644 index 00000000..2cd9fef6 --- /dev/null +++ b/devdocs/c/chrono.html @@ -0,0 +1,60 @@ +

Date and time utilities

Functions

+ + + + + + + + + + + + + + + + + +
Time manipulation
Defined in header <time.h>
computes the difference between times
(function)
returns the current calendar time of the system as time since epoch
(function)
returns raw processor clock time since the program is started
(function)
+
(C11)
 returns the calendar time in seconds and nanoseconds based on a given time base
(function)
+
(C23)
 returns the resolution of calendar time based on a given time base
(function)
Format conversions
Defined in header <time.h>
+
(deprecated in C23)(C11)
 converts a tm object to a textual representation
(function)
+
(deprecated in C23)(C11)
 converts a time_t object to a textual representation
(function)
converts a tm object to custom textual representation
(function)
Defined in header <wchar.h>
+
(C95)
 converts a tm object to custom wide string textual representation
(function)
Defined in header <time.h>
+
(C23)(C11)
 converts time since epoch to calendar time expressed as Coordinated Universal Time (UTC)
(function)
+
(C23)(C11)
 converts time since epoch to calendar time expressed as local time
(function)
converts calendar time to time since epoch
(function)

Constants

+ +
Defined in header <time.h>
number of processor clock ticks per second
(macro constant)

Types

+ + + + +
Defined in header <time.h>
calendar time type
(struct)
calendar time since epoch type
(typedef)
processor time since era type
(typedef)
+
(C11)
 time in seconds and nanoseconds
(struct)

References

See also

+
C++ documentation for C Date and time utilities
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/chrono +

+
diff --git a/devdocs/c/comment.html b/devdocs/c/comment.html new file mode 100644 index 00000000..07ac5f27 --- /dev/null +++ b/devdocs/c/comment.html @@ -0,0 +1,86 @@ +

Comments

Comments serve as a sort of in-code documentation. When inserted into a program, they are effectively ignored by the compiler; they are solely intended to be used as notes by the humans that read source code.

+

Syntax

+ + +
/* comment */ (1)
// comment (2) (since C99)
+1) Often known as "C-style" or "multi-line" comments.
+2) Often known as "C++-style" or "single-line" comments.

All comments are removed from the program at translation phase 3 by replacing each comment with a single whitespace character.

+

C-style

C-style comments are usually used to comment large blocks of text or small fragments of code; however, they can be used to comment single lines. To insert text as a C-style comment, simply surround the text with /* and */. C-style comments tell the compiler to ignore all content between /* and */. Although it is not part of the C standard, /** and **/ are often used to indicate documentation blocks; this is legal because the second asterisk is simply treated as part of the comment.

+

Except within a character constant, a string literal, or a comment, the characters /* introduce a comment. The contents of such a comment are examined only to identify multibyte characters and to find the characters */ that terminate the comment. C-style comments cannot be nested.

+ + +

C++-style

C++-style comments are usually used to comment single lines of text or code; however, they can be placed together to form multi-line comments. To insert text as a C++-style comment, simply precede the text with // and follow the text with the new line character. C++-style comments tell the compiler to ignore all content between // and a new line.

+

Except within a character constant, a string literal, or a comment, the characters // introduce a comment that includes all multibyte characters up to, but not including, the next new-line character. The contents of such a comment are examined only to identify multibyte characters and to find the new-line character that terminates the comment. C++-style comments can be nested:

+
//  y = f(x);   // invoke algorithm

A C-style comment may appear within a C++-style comment:

+
//  y = f(x);   /* invoke algorithm */

A C++-style comment may appear within a C-style comment; this is a mechanism for excluding a small block of source code:

+
/*
+    y = f(x);   // invoke algorithms
+    z = g(x);
+*/
 (since C99)

Notes

Because comments are removed before the preprocessor stage, a macro cannot be used to form a comment and an unterminated C-style comment doesn't spill over from an #include'd file.

+
/* An attempt to use a macro to form a comment. */
+/* But, a space replaces characters "//".       */
+#ifndef DEBUG
+    #define PRINTF //
+#else
+    #define PRINTF printf
+#endif
+...  
+PRINTF("Error in file %s at line %i\n", __FILE__, __LINE__);

Besides commenting out, other mechanisms used for source code exclusion are:

+
#if 0
+    puts("this will not be compiled");
+    /* no conflict with C-style comments */
+    // no conflict with C++-style comments
+#endif

and

+
if(0) {
+    puts("this will be compiled but not be executed");
+    /* no conflict with C-style comments */
+    // no conflict with C++-style comments
+}

The introduction of // comments in C99 was a breaking change in some rare circumstances:

+
a = b //*divisor:*/ c
++ d; /* C89 compiles a = b / c + d;
+        C99 compiles a = b + d; */

Example

#include <stdio.h>
+/*
+C-style comments can contain
+multiple lines.
+*/
+ 
+/* Or, just one line. */
+ 
+// C++-style comments can comment one line.
+ 
+// Or, they can
+// be strung together.
+ 
+int main(void)
+{
+  // The below code won't be run
+  // puts("Hello");
+ 
+  // The below code will be run
+  puts("World");
+ 
+  // A note regarding backslash + newline.
+  // Despite belonging to translation phase 2 (vs phase 3 for comments),
+  // '\' still determines which portion of the source code is considered
+  // as 'comments':
+  // This comment will be promoted to the next line \
+  puts("Won't be run"); // may issue a warning "multi-line comment"
+  puts("Hello, again");
+}

Output:

+
World
+Hello, again

References

See also

+
C++ documentation for Comments
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/comment +

+
diff --git a/devdocs/c/current_status.html b/devdocs/c/current_status.html new file mode 100644 index 00000000..9108bd03 --- /dev/null +++ b/devdocs/c/current_status.html @@ -0,0 +1,11 @@ +

Current Status

Recent milestones: C17 published, C23 underway

+

C17 has been published, and work is now underway on C23.

+

The current schedule is in paper N2984.

+

You can also visit open-std.org to get the latest C standards committee papers. Reading through those proposals, you can track the C developing trends and know how does a cool idea turned into the standard. However, those papers ARE NOT and also SHOULD NOT BE TREATED AS the standard documents.

+

See also

+
C++ documentation for Current status
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/current_status +

+
diff --git a/devdocs/c/error%2Fabort_handler_s.html b/devdocs/c/error%2Fabort_handler_s.html new file mode 100644 index 00000000..dbf90720 --- /dev/null +++ b/devdocs/c/error%2Fabort_handler_s.html @@ -0,0 +1,51 @@ +

abort_handler_s

Defined in header <stdlib.h> 
void abort_handler_s( const char * restrict msg,
+                      void * restrict ptr,
+                      errno_t error
+                    );
+		 (since C11)

Writes an implementation-defined message to stderr which must include the string pointed to by msg and calls abort().

+

A pointer to this function can be passed to set_constraint_handler_s to establish a runtime constraints violation handler. As with all bounds-checked functions, abort_handler_s is only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <stdlib.h>.

+

Parameters

+ + + +
msg - pointer to the message written to the standard error stream
ptr - pointer to an implementation-defined object or a null pointer. Examples of implementation-defined objects are objects that give the name of the function that detected the violation and the line number when the violation was detected
error - a positive value of type errno_t

Return value

none; this function does not return to its caller

+

Notes

If set_constraint_handler_s is never called, the default handler is implementation-defined: it may be abort_handler_s, ignore_handler_s, or some other implementation-defined handler.

+

Example

#define __STDC_WANT_LIB_EXT1__ 1
+#include <string.h>
+#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+#ifdef __STDC_LIB_EXT1__
+    char dst[2];
+    set_constraint_handler_s(ignore_handler_s);
+    int r = strcpy_s(dst, sizeof dst, "Too long!");
+    printf("dst = \"%s\", r = %d\n", dst, r);
+    set_constraint_handler_s(abort_handler_s);
+    r = strcpy_s(dst, sizeof dst, "Too long!");
+    printf("dst = \"%s\", r = %d\n", dst, r);
+#endif
+}

Possible output:

+
dst = "", r = 22
+abort_handler_s was called in response to a runtime-constraint violation.
+ 
+The runtime-constraint violation was caused by the following expression in strcpy_s:
+(s1max <= (s2_len=strnlen_s(s2, s1max)) ) (in string_s.c:62)
+ 
+Note to end users: This program was terminated as a result
+of a bug present in the software. Please reach out to your
+software's vendor to get more help.
+Aborted

References

See also

+ +
+
(C11)
 ignore callback for the bounds-checked functions
(function)
+
(C11)
 set the error callback for bounds-checked functions
(function)
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/error/abort_handler_s +

+
diff --git a/devdocs/c/error%2Fassert.html b/devdocs/c/error%2Fassert.html new file mode 100644 index 00000000..d194a1b0 --- /dev/null +++ b/devdocs/c/error%2Fassert.html @@ -0,0 +1,48 @@ +

assert

Defined in header <assert.h> 
#ifdef NDEBUG
+#define assert(condition) ((void)0)
+#else
+#define assert(condition) /*implementation defined*/
+#endif
+

The definition of the macro assert depends on another macro, NDEBUG, which is not defined by the standard library.

+

If NDEBUG is defined as a macro name at the point in the source code where <assert.h> is included, then assert does nothing.

+

If NDEBUG is not defined, then assert checks if its argument (which must have scalar type) compares equal to zero. If it does, assert outputs implementation-specific diagnostic information on the standard error output and calls abort(). The diagnostic information is required to include the text of expression, as well as the values of the predefined variable __func__ and of(since C99) the predefined macros __FILE__ and __LINE__.

+

Parameters

+ +
condition - expression of scalar type

Return value

(none)

+

Notes

There is no standardized interface to add an additional message to assert errors. A portable way to include one is to use a comma operator:

+
assert(("There are five lights", 2 + 2 == 5));

The implementation of assert in Microsoft CRT does not conform to C99 and later revisions, because its underlying function (_wassert) takes neither __func__ nor an equivalent replacement.

+

Example

#include <stdio.h>
+// uncomment to disable assert()
+// #define NDEBUG
+#include <assert.h>
+#include <math.h>
+ 
+int main(void)
+{
+    double x = -1.0;
+    assert(x >= 0.0);
+    printf("sqrt(x) = %f\n", sqrt(x));   
+ 
+    return 0;
+}

Output:

+
output with NDEBUG not defined:
+a.out: main.cpp:10: main: Assertion `x >= 0.0' failed.
+ 
+output with NDEBUG defined:
+sqrt(x) = -nan

References

See also

+ +
causes abnormal program termination (without cleaning up)
(function)
C++ documentation for assert
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/error/assert +

+
diff --git a/devdocs/c/error%2Ferrno.html b/devdocs/c/error%2Ferrno.html new file mode 100644 index 00000000..687e991b --- /dev/null +++ b/devdocs/c/error%2Ferrno.html @@ -0,0 +1,78 @@ +

errno

Defined in header <errno.h> 
#define errno /*implementation-defined*/
+

errno is a preprocessor macro (but see note below) that expands to a thread-local(since C11) modifiable lvalue of type int. Several standard library functions indicate errors by writing positive integers to errno. Typically, the value of errno is set to one of the error codes listed in <errno.h> as macro constants beginning with the letter E followed by uppercase letters or digits.

+

The value of errno is ​0​ at program startup, and although library functions are allowed to write positive integers to errno whether or not an error occurred, library functions never store ​0​ in errno.

+

Library functions perror and strerror can be used to obtain textual descriptions of the error conditions that correspond to the current errno value.

+

Note: Until C11, the C standards had contradictory requirements, in that they said that errno is a macro but also that "it is unspecified whether errno is a macro or an identifier declared with external linkage". C11 fixes this, requiring that it be defined as a macro (see also WG14 N1338).

+

Example

#include <stdio.h>
+#include <math.h>
+#include <errno.h>
+ 
+void show_errno(void)
+{
+    const char *err_info = "unknown error";
+    switch (errno) {
+    case EDOM:
+        err_info = "domain error";
+        break;
+    case EILSEQ:
+        err_info = "illegal sequence";
+        break;
+    case ERANGE:
+        err_info = "pole or range error";
+        break;
+    case 0:
+        err_info = "no error";
+    }
+    fputs(err_info, stdout);
+    puts(" occurred");
+}
+ 
+int main(void)
+{
+    fputs("MATH_ERRNO is ", stdout);
+    puts(math_errhandling & MATH_ERRNO ? "set" : "not set");
+ 
+    errno = 0;
+    1.0/0.0;
+    show_errno();
+ 
+    errno = 0;
+    acos(+1.1);
+    show_errno();
+ 
+    errno = 0;
+    log(0.0);
+    show_errno();
+ 
+    errno = 0;
+    sin(0.0);
+    show_errno();
+}

Possible output:

+
MATH_ERRNO is set
+no error occurred
+domain error occurred
+pole or range error occurred
+no error occurred

References

See also

+ + + + +
macros for standard POSIX-compatible error conditions
(macro constant)
displays a character string corresponding of the current error to stderr
(function)
+
(C11)(C11)
 returns a text version of a given error code
(function)
+
(C99)(C99)(C99)
 defines the error handling mechanism used by the common mathematical functions
(macro constant)
C++ documentation for errno
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/error/errno +

+
diff --git a/devdocs/c/error%2Ferrno_macros.html b/devdocs/c/error%2Ferrno_macros.html new file mode 100644 index 00000000..5ecee98f --- /dev/null +++ b/devdocs/c/error%2Ferrno_macros.html @@ -0,0 +1,44 @@ +

Error numbers

Each of the macros defined in <errno.h> expands to an integer constant expression with type int and with a unique positive value. The following constants are defined by ISO C. The implementation may define more, as long as they begin with 'E' followed by digits or uppercase letters.

+ + + + +
Defined in header <errno.h>
EDOM
 Mathematics argument out of domain of function
(macro constant)
EILSEQ
+
(C95)
 Illegal byte sequence
(macro constant)
ERANGE
 Result too large
(macro constant)

Notes

Many additional errno constants are defined by POSIX and by the C++ standard library, and individual implementations may define even more, e.g. errno(3) on Linux or intro(2) on BSD and OS X.

+

Example

#include <stdio.h>
+#include <math.h>
+#include <errno.h>
+#include <string.h>
+ 
+int main(void)
+{
+    errno = 0;
+    printf("log(-1.0) = %f\n", log(-1.0));
+    printf("%s\n\n",strerror(errno));
+ 
+    errno = 0;
+    printf("log(0.0)  = %f\n", log(0.0));
+    printf("%s\n",strerror(errno));
+}

Possible output:

+
log(-1.0) = nan
+Numerical argument out of domain
+ 
+log(0.0)  = -inf
+Numerical result out of range

References

See also

+ + + +
macro which expands to POSIX-compatible thread-local error number variable
(macro variable)
displays a character string corresponding of the current error to stderr
(function)
+
(C11)(C11)
 returns a text version of a given error code
(function)
C++ documentation for Error numbers
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/error/errno_macros +

+
diff --git a/devdocs/c/error%2Fignore_handler_s.html b/devdocs/c/error%2Fignore_handler_s.html new file mode 100644 index 00000000..844d8b6b --- /dev/null +++ b/devdocs/c/error%2Fignore_handler_s.html @@ -0,0 +1,52 @@ +

ignore_handler_s

Defined in header <stdlib.h> 
void ignore_handler_s( const char * restrict msg,
+                       void * restrict ptr,
+                       errno_t error
+                     );
+		 (since C11)

The function simply returns to the caller without performing any other action.

+

A pointer to this function can be passed to set_constraint_handler_s to establish a runtime constraints violation handler that does nothing. As with all bounds-checked functions, ignore_handler_s is only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <stdlib.h>.

+

Parameters

+ + + +
msg - pointer to character string that describes the error
ptr - pointer to an implementation-defined object or a null pointer. Examples of implementation-defined objects are objects that give the name of the function that detected the violation and the line number when the violation was detected
error - the error about to be returned by the calling function, if it happens to be one of the functions that return errno_t

Return value

(none)

+

Notes

If ignore_handler_s is used as a the runtime constraints handler, the violations may be detected by examining the results of the bounds-checked function calls, which may be different for different functions (non-zero errno_t, null character written to the first byte of the output string, etc)

+

If set_constraint_handler_s is never called, the default handler is implementation-defined: it may be abort_handler_s, ignore_handler_s, or some other implementation-defined handler.

+

Example

#define __STDC_WANT_LIB_EXT1__ 1
+#include <string.h>
+#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+#ifdef __STDC_LIB_EXT1__
+    char dst[2];
+    set_constraint_handler_s(ignore_handler_s);
+    int r = strcpy_s(dst, sizeof dst, "Too long!");
+    printf("dst = \"%s\", r = %d\n", dst, r);
+    set_constraint_handler_s(abort_handler_s);
+    r = strcpy_s(dst, sizeof dst, "Too long!");
+    printf("dst = \"%s\", r = %d\n", dst, r);
+#endif
+}

Possible output:

+
dst = "", r = 22
+abort_handler_s was called in response to a runtime-constraint violation.
+ 
+The runtime-constraint violation was caused by the following expression in strcpy_s:
+(s1max <= (s2_len=strnlen_s(s2, s1max)) ) (in string_s.c:62)
+ 
+Note to end users: This program was terminated as a result
+of a bug present in the software. Please reach out to your
+software's vendor to get more help.
+Aborted

References

See also

+ +
+
(C11)
 abort callback for the bounds-checked functions
(function)
+
(C11)
 set the error callback for bounds-checked functions
(function)
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/error/ignore_handler_s +

+
diff --git a/devdocs/c/error%2Fset_constraint_handler_s.html b/devdocs/c/error%2Fset_constraint_handler_s.html new file mode 100644 index 00000000..d8c0c19e --- /dev/null +++ b/devdocs/c/error%2Fset_constraint_handler_s.html @@ -0,0 +1,57 @@ +

set_constraint_handler_s, constraint_handler_t

Defined in header <stdlib.h> 
constraint_handler_t set_constraint_handler_s( constraint_handler_t handler );
+		 (since C11)

Configures the handler to be called by all bounds-checked functions on a runtime constraint violation or restores the default handler (if handler is a null pointer)

+

The handler must be a pointer to function of type constraint_handler_t, which is defined as

+
Defined in header <stdlib.h> 
typedef void (*constraint_handler_t)( const char *restrict msg,
+                                      void *restrict ptr,
+                                      errno_t error);
+		 (since C11)

On a runtime constraint violation, it is called with the following arguments:

+
+1) pointer to character string that describes the error
+2) pointer to an implementation-defined object or a null pointer. Examples of implementation-defined objects are objects that give the name of the function that detected the violation and the line number when the violation was detected
+3) the error about to be returned by the calling function, if it happens to be one of the functions that return errno_t +

If set_constraint_handler_s is never called, the default handler is implementation-defined: it may be abort_handler_s, ignore_handler_s, or some other implementation-defined handler. As with all bounds-checked functions, set_constraint_handler_s and constraint_handler_t are only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <stdlib.h>.

+

Parameters

+ +
handler - pointer to function of type constraint_handler_t or a null pointer

Return value

A pointer to the previously-installed runtime constraints handler. (note: this pointer is never a null pointer because calling set_constraint_handler_s(NULL) sets up the system default handler)

+

Example

#define __STDC_WANT_LIB_EXT1__ 1
+#include <string.h>
+#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+#ifdef __STDC_LIB_EXT1__
+    char dst[2];
+    set_constraint_handler_s(ignore_handler_s);
+    int r = strcpy_s(dst, sizeof dst, "Too long!");
+    printf("dst = \"%s\", r = %d\n", dst, r);
+    set_constraint_handler_s(abort_handler_s);
+    r = strcpy_s(dst, sizeof dst, "Too long!");
+    printf("dst = \"%s\", r = %d\n", dst, r);
+#endif
+}

Possible output:

+
dst = "", r = 22
+abort_handler_s was called in response to a runtime-constraint violation.
+ 
+The runtime-constraint violation was caused by the following expression in strcpy_s:
+(s1max <= (s2_len=strnlen_s(s2, s1max)) ) (in string_s.c:62)
+ 
+Note to end users: This program was terminated as a result
+of a bug present in the software. Please reach out to your
+software's vendor to get more help.
+Aborted

References

See also

+ +
+
(C11)
 abort callback for the bounds-checked functions
(function)
+
(C11)
 ignore callback for the bounds-checked functions
(function)
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/error/set_constraint_handler_s +

+
diff --git a/devdocs/c/error%2Fstatic_assert.html b/devdocs/c/error%2Fstatic_assert.html new file mode 100644 index 00000000..59b96576 --- /dev/null +++ b/devdocs/c/error%2Fstatic_assert.html @@ -0,0 +1,23 @@ +

static_assert

Defined in header <assert.h> 
#define static_assert _Static_assert
+		 (since C11)
(removed in C23)

This convenience macro expands to the keyword _Static_assert.

+

Example

#include <assert.h>
+ 
+int main(void)
+{
+    static_assert(2 + 2 == 4, "2+2 isn't 4");   // well-formed
+ 
+    static_assert(sizeof(int) < sizeof(char),   // compile-time error
+                  "this program requires that int is less than char");
+}

Notes

Since C23, static_assert is itself a keyword, which may also be a predefined macro, so <assert.h> no longer provides it.

+

References

See also

+
C++ documentation for Static Assertion
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/error/static_assert +

+
diff --git a/devdocs/c/error.html b/devdocs/c/error.html new file mode 100644 index 00000000..935abf5e --- /dev/null +++ b/devdocs/c/error.html @@ -0,0 +1,78 @@ +

Error handling

Error numbers

+ + +
Defined in header <errno.h>
macro which expands to POSIX-compatible thread-local error number variable
(macro variable)
macros for standard POSIX-compatible error conditions
(macro constant)

Assertions

+ + +
Defined in header <assert.h>
aborts the program if the user-specified condition is not true. May be disabled for release builds
(function macro)
+
(C11)(removed in C23)
 issues a compile-time diagnostic if the value of a constant expression is false
(keyword macro)
+ +

Bounds checking

The standard library provides bounds-checked versions of some existing functions (gets_s, fopen_s, printf_s, strcpy_s, wcscpy_s, mbstowcs_s, qsort_s, getenv_s, etc). This functionality is optional and is only available if __STDC_LIB_EXT1__ is defined. The following macros and functions support this functionality.

+ + + + + + + + + + + + + + + + +
Defined in header <errno.h>
Defined in header <stdio.h>
errno_t
+
(C11)
 a typedef for the type int, used to self-document functions that return errno values
(typedef)
Defined in header <stddef.h>
Defined in header <stdio.h>
Defined in header <stdlib.h>
Defined in header <string.h>
Defined in header <time.h>
Defined in header <wchar.h>
rsize_t
+
(C11)
 a typedef for the same type as size_t, used to self-document functions that range-check their parameters at runtime
(typedef)
Defined in header <stdint.h>
RSIZE_MAX
+
(C11)
 largest acceptable size for bounds-checked functions, expands to either constant or variable which may change at runtime (e.g. as the currently allocated memory size changes)
(macro variable)
Defined in header <stdlib.h>
+
(C11)
 set the error callback for bounds-checked functions
(function)
+
(C11)
 abort callback for the bounds-checked functions
(function)
+
(C11)
 ignore callback for the bounds-checked functions
(function)

Note: implementations of bounds-checked functions are available as open-source libraries Safe C and Slibc, and as part of Watcom C. There is also an incompatible set of bounds-checked functions available in Visual Studio.

+		 (since C11)

Notes

Since C23, static_assert is itself a keyword, which may also be a predefined macro, so <assert.h> no longer provides it.

+

References

See also

+ +
+
(C99)(C99)(C99)
 defines the error handling mechanism used by the common mathematical functions
(macro constant)
C++ documentation for Error handling
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/error +

+
diff --git a/devdocs/c/index b/devdocs/c/index new file mode 100644 index 00000000..00a36344 --- /dev/null +++ b/devdocs/c/index @@ -0,0 +1 @@ +((pages . ["index" "language" "numeric/math" "types" "program" "variadic" "memory" "numeric/fenv" "types/limits" "language/_noreturn" "numeric/random" "string/multibyte" "numeric/tgmath" "string/wide" "keyword" "preprocessor" "string" "language/expressions" "language/initialization" "language/basic_concepts" "language/declarations" "language/functions" "language/history" "comment" "language/ascii" "language/charset" "error" "algorithm" "chrono" "language/translation_phases" "thread" "language/punctuators" "language/identifier" "language/scope" "language/arithmetic_types" "language/object" "language/main_function" "language/as_if" "language/behavior" "language/memory_model" "language/statements" "preprocessor/conditional" "preprocessor/replace" "preprocessor/include" "preprocessor/impl" "numeric" "locale" "language/lifetime" "preprocessor/line" "preprocessor/embed" "language/if" "language/switch" "string/byte" "language/while" "language/do" "language/continue" "language/goto" "language/return" "language/eval_order" "language/character_constant" "language/operator_alternative" "language/string_literal" "language/compound_literal" "io" "numeric/complex" "types/integer" "language/name_space" "preprocessor/error" "language/bool_constant" "language/nullptr" "language/type" "language/for" "language/break" "language/constant_expression" "language/conversion" "language/operator_member_access" "language/operator_logical" "language/operator_comparison" "language/operator_arithmetic" "language/operator_assignment" "language/value_category" "language/integer_constant" "language/floating_constant" "language/sizeof" "language/operator_precedence" "language/array_initialization" "language/struct_initialization" "language/pointer" "language/enum" "language/operator_other" "language/_alignof" "language/cast" "language/generic" "language/struct" "language/union" "language/bit_field" "language/_alignas" "language/_static_assert" "language/atomic" "language/extern" "language/attributes" "language/function_declaration" "language/inline" "language/analyzability" "language/function_definition" "language/operator_incdec" "language/typedef" "numeric/math/remquo" "numeric/math/fdim" "numeric/math/fma" "numeric/math/nan" "numeric/math/fmax" "numeric/math/fmin" "language/variadic" "language/conformance" "language/asm" "numeric/math/exp" "numeric/math/exp2" "numeric/math/div" "numeric/math/fmod" "numeric/math/log1p" "numeric/math/hypot" "numeric/math/pow" "language/scalar_initialization" "language/storage_duration" "language/const" "numeric/math/abs" "numeric/math/fabs" "numeric/math/remainder" "numeric/math/sqrt" "numeric/math/sin" "numeric/math/cos" "numeric/math/expm1" "numeric/math/log" "numeric/math/log2" "numeric/math/cbrt" "numeric/math/tan" "numeric/math/asin" "numeric/math/acos" "numeric/math/log10" "numeric/math/atan" "numeric/math/sinpi" "numeric/math/cosh" "numeric/math/tanh" "numeric/math/atan2" "numeric/math/sinh" "numeric/math/atanh" "numeric/math/erf" "numeric/math/erfc" "numeric/math/lgamma" "language/array" "language/volatile" "language/restrict" "numeric/math/cospi" "numeric/math/asinh" "numeric/math/acosh" "numeric/math/tgamma" "numeric/math/ceil" "numeric/math/floor" "numeric/math/round" "numeric/math/roundeven" "numeric/math/trunc" "numeric/math/nearbyint" "numeric/math/rint" "numeric/math/ldexp" "numeric/math/frexp" "numeric/math/scalbn" "numeric/math/ilogb" "numeric/math/logb" "numeric/math/modf" "numeric/math/copysign" "numeric/math/isfinite" "numeric/math/signbit" "numeric/math/isunordered" "numeric/math/fpclassify" "numeric/math/isnormal" "numeric/math/isgreaterequal" "numeric/math/isless" "numeric/math/float_t" "numeric/math/huge_val" "numeric/math/infinity" "types/size_t" "numeric/math/nextafter" "numeric/math/isinf" "numeric/math/isnan" "numeric/math/islessequal" "numeric/math/fp_categories" "numeric/math/math_errhandling" "types/ptrdiff_t" "types/nullptr_t" "types/null" "types/max_align_t" "keyword/_bool" "numeric/math/isgreater" "numeric/math/islessgreater" "program/_exit" "program/atexit" "program/at_quick_exit" "program/getenv" "program/sig_atomic_t" "program/sig_strategies" "program/sig_err" "program/sig_types" "variadic/va_start" "program/setjmp" "program/longjmp" "program/jmp_buf" "variadic/va_arg" "variadic/va_copy" "variadic/va_end" "variadic/va_list" "memory/malloc" "io/fprintf" "memory/calloc" "program/quick_exit" "program/unreachable" "program/raise" "memory/free" "memory/free_sized" "memory/free_aligned_sized" "memory/aligned_alloc" "language/types" "keyword/_alignas" "keyword/_alignof" "numeric/fenv/feclearexcept" "numeric/fenv/fetestexcept" "numeric/fenv/feenv" "numeric/fenv/fe_exceptions" "language/attributes/noreturn" "numeric/fenv/fe_round" "numeric/fenv/fe_dfl_env" "types/limits/flt_eval_method" "thread/thrd_exit" "numeric/random/rand" "string/multibyte/btowc" "string/multibyte/mbsrtowcs" "types/limits/flt_rounds" "string/multibyte/mbrtoc8" "program/system" "program/exit_status" "program/signal" "numeric/random/srand" "string/multibyte/c8rtomb" "types/offsetof" "keyword/_noreturn" "program/abort" "program/exit" "numeric/random/rand_max" "string/multibyte/mbsinit" "string/multibyte/mbstowcs" "string/multibyte/mbrtoc16" "numeric/fenv/feexceptflag" "string/multibyte/wctob" "string/multibyte/wcsrtombs" "string/multibyte/mbstate_t" "string/multibyte/mbrlen" "string/multibyte/char8_t" "string/multibyte/char16_t" "string/multibyte/char32_t" "keyword/_generic" "memory/realloc" "numeric/complex/cabs" "numeric/complex/cexp" "numeric/complex/clog" "numeric/complex/cpow" "string/multibyte/mbrtowc" "string/multibyte/c16rtomb" "numeric/complex/csqrt" "numeric/complex/csin" "numeric/complex/ctan" "numeric/fenv/feround" "string/multibyte/c32rtomb" "string/multibyte/mbrtoc32" "string/multibyte/mbtowc" "numeric/complex/ccos" "numeric/complex/casin" "numeric/complex/cacos" "numeric/complex/catan" "numeric/complex/csinh" "numeric/complex/ccosh" "numeric/complex/ctanh" "numeric/complex/cacosh" "numeric/complex/catanh" "numeric/complex/carg" "numeric/complex/creal" "string/wide/iswalnum" "numeric/fenv/feraiseexcept" "numeric/fenv/feholdexcept" "numeric/fenv/feupdateenv" "string/multibyte/mblen" "string/wide/iswlower" "string/wide/iswupper" "string/wide/iswdigit" "string/wide/iswxdigit" "numeric/complex/casinh" "numeric/complex/conj" "numeric/complex/cimag" "numeric/complex/cproj" "string/wide/iswblank" "string/wide/wctype" "string/wide/iswcntrl" "string/multibyte/wctomb" "string/multibyte/wcrtomb" "string/wide/iswalpha" "string/wide/iswgraph" "string/wide/iswspace" "string/wide/iswprint" "string/wide/iswpunct" "string/wide/towlower" "string/wide/towupper" "string/wide/wctrans" "string/wide/towctrans" "string/multibyte/wcstombs" "string/wide/iswctype" "string/wide/wcstol" "string/wide/wcstoul" "string/wide/wcstof" "string/wide/wcstoimax" "string/wide/wcslen" "string/wide/wcscpy" "string/wide/wcsncpy" "string/wide/wcscat" "string/wide/wcsncat" "string/wide/wcsstr" "string/wide/wcsncmp" "string/wide/wcscoll" "string/wide/wcsxfrm" "string/wide/wcschr" "string/wide/wcsrchr" "string/wide/wcspbrk" "string/wide/wcsspn" "string/wide/wcscmp" "string/wide/wcstok" "string/wide/wmemcpy" "string/wide/wmemmove" "locale/lc_categories" "string/byte/isspace" "string/byte/isblank" "string/byte/isgraph" "string/byte/isdigit" "string/wide/wcscspn" "string/wide/wmemcmp" "string/wide/wmemchr" "string/wide/wmemset" "string/byte/iscntrl" "string/byte/isxdigit" "keyword/alignas" "keyword/alignof" "keyword/auto" "keyword/bool" "string/byte/isprint" "string/byte/ispunct" "string/byte/isalpha" "keyword/break" "keyword/case" "keyword/char" "keyword/const" "keyword/continue" "keyword/double" "keyword/enum" "keyword/false" "keyword/if" "keyword/nullptr" "string/byte/isalnum" "string/byte/isupper" "string/byte/islower" "keyword/goto" "keyword/int" "keyword/constexpr" "keyword/default" "keyword/do" "keyword/for" "keyword/inline" "keyword/long" "keyword/restrict" "keyword/return" "keyword/signed" "keyword/sizeof" "keyword/else" "keyword/extern" "keyword/float" "keyword/register" "keyword/short" "keyword/static" "keyword/static_assert" "keyword/struct" "keyword/switch" "keyword/thread_local" "keyword/typedef" "keyword/typeof" "keyword/typeof_unqual" "keyword/unsigned" "keyword/_static_assert" "thread/thread_local" "language/typeof" "keyword/void" "keyword/true" "keyword/volatile" "keyword/_atomic" "locale/lconv" "io/tmpnam" "io/setvbuf" "chrono/strftime" "io/gets" "17" "keyword/_imaginary" "error/errno_macros" "23" "io/fopen" "string/byte/strcpy" "keyword/_decimal128" "keyword/fortran" "keyword/_thread_local" "algorithm/qsort" "algorithm/bsearch" "chrono/difftime" "chrono/time" "error/errno" "error/static_assert" "chrono/timespec_getres" "keyword/union" "language/constexpr" "error/assert" "error/set_constraint_handler_s" "chrono/asctime" "chrono/ctime" "chrono/gmtime" "chrono/localtime" "keyword/while" "chrono/clocks_per_sec" "chrono/tm" "chrono/time_t" "error/abort_handler_s" "chrono/clock_t" "language/escape" "thread/thrd_create" "thread/thrd_equal" "error/ignore_handler_s" "chrono/clock" "chrono/timespec_get" "thread/thrd_join" "thread/thrd_errors" "atomic/atomic_init" "atomic/atomic_var_init" "chrono/wcsftime" "atomic/atomic_lock_free_consts" "atomic/atomic_is_lock_free" "atomic/atomic_store" "atomic/atomic_load" "atomic/atomic_exchange" "keyword/_complex" "chrono/mktime" "atomic/atomic_compare_exchange" "atomic/atomic_fetch_add" "atomic/atomic_fetch_sub" "atomic/atomic_fetch_or" "atomic/atomic_fetch_xor" "chrono/timespec" "thread/thrd_current" "thread/thrd_sleep" "thread/thrd_yield" "thread/thrd_detach" "atomic/atomic_fetch_and" "atomic/atomic_flag" "atomic/atomic_flag_init" "atomic/atomic_flag_test_and_set" "atomic/atomic_flag_clear" "atomic/memory_order" "atomic/atomic_signal_fence" "thread/mtx_lock" "keyword/_decimal64" "thread/mtx_types" "thread/cnd_wait" "thread/cnd_timedwait" "thread/cnd_destroy" "thread/tss_dtor_iterations" "thread/tss_create" "thread/tss_get" "thread/tss_set" "atomic/kill_dependency" "atomic/atomic_thread_fence" "thread/mtx_init" "thread/tss_delete" "numeric/complex/imaginary_i" "numeric/complex/complex_i" "string/byte/memmove" "keyword/_decimal32" "numeric/complex/complex" "numeric/complex/imaginary" "thread/mtx_trylock" "thread/call_once" "thread/mtx_unlock" "thread/cnd_init" "string/byte/toupper" "string/byte/strfromf" "string/byte/strtoul" "string/byte/strtoimax" "string/byte/strtof" "numeric/complex/cmplx" "string/byte/memcpy" "string/byte/strcat" "string/byte/strtok" "io/tmpfile" "locale/setlocale" "string/byte/strdup" "thread/mtx_timedlock" "io/fread" "string/byte/tolower" "string/byte/strncat" "string/byte/strxfrm" "string/byte/strndup" "string/byte/strlen" "string/byte/strcmp" "string/byte/atoi" "string/byte/atof" "string/byte/strtol" "string/byte/strncpy" "string/byte/strncmp" "string/byte/strcoll" "string/byte/strchr" "string/byte/strrchr" "thread/mtx_destroy" "thread/cnd_signal" "thread/cnd_broadcast" "locale/localeconv" "string/byte/strspn" "string/byte/strcspn" "string/byte/strpbrk" "string/byte/memcmp" "io/fscanf" "io/fpos_t" "io/fgetc" "string/byte/memset" "string/byte/memccpy" "string/byte/strstr" "string/byte/memchr" "io/putchar" "io/puts" "io/ungetc" "io/fgetwc" "io/fgetws" "io/file" "io/freopen" "io/fwide" "io/setbuf" "io/fputwc" "io/fputws" "io/getwchar" "io/putwchar" "io/ungetwc" "io/fwscanf" "io/vfscanf" "io/vfwscanf" "io/fwprintf" "io/vfprintf" "io/vfwprintf" "string/byte/strerror" "io/std_streams" "io/fclose" "io/getchar" "io/rewind" "io/clearerr" "io/ftell" "io/fgetpos" "io/fseek" "io/fsetpos" "io/ferror" "io/perror" "io/remove" "io/rename" "io/fwrite" "io/fgets" "io/fputc" "io/fputs" "language/attributes/fallthrough" "language/attributes/deprecated" "language/attributes/maybe_unused" "language/attributes/unsequenced" "99" "io/feof" "numeric/complex/i" "language/attributes/nodiscard" "11" "current_status" "atomic" "io/fflush" "language/static_storage_duration" "language/thread_storage_duration" "95" "language/alignas" "language/file_scope" "language/static_assert" "language/attributes/reproducible" "language/alignof" "language/compatible_type"]) (entries . [((name . "#define directive") (path . "preprocessor/replace") (type . "C language")) ((name . "#elif directive") (path . "preprocessor/conditional") (type . "C language")) ((name . "#else directive") (path . "preprocessor/conditional") (type . "C language")) ((name . "#endif directive") (path . "preprocessor/conditional") (type . "C language")) ((name . "#if directive") (path . "preprocessor/conditional") (type . "C language")) ((name . "#ifdef directive") (path . "preprocessor/conditional") (type . "C language")) ((name . "#ifndef directive") (path . "preprocessor/conditional") (type . "C language")) ((name . "#include directive") (path . "preprocessor/include") (type . "C language")) ((name . "#line directive") (path . "preprocessor/line") (type . "C language")) ((name . "#pragma directive") (path . "preprocessor/impl") (type . "C language")) ((name . "_Alignas") (path . "language/_alignas") (type . "C language")) ((name . "_Alignas") (path . "language/alignas") (type . "C language")) ((name . "_Alignas") (path . "keyword/_alignas") (type . "C keywords")) ((name . "_Alignof") (path . "keyword/_alignof") (type . "C keywords")) ((name . "_Alignof operator") (path . "language/_alignof") (type . "C language")) ((name . "_Alignof operator") (path . "language/alignof") (type . "C language")) ((name . "_Atomic") (path . "keyword/_atomic") (type . "C keywords")) ((name . "_Bool") (path . "keyword/_bool") (type . "C keywords")) ((name . "_Complex") (path . "keyword/_complex") (type . "C keywords")) ((name . "_Complex_I") (path . "numeric/complex/complex_i") (type . "Numerics")) ((name . "_Decimal128") (path . "keyword/_decimal128") (type . "C keywords")) ((name . "_Decimal32") (path . "keyword/_decimal32") (type . "C keywords")) ((name . "_Decimal64") (path . "keyword/_decimal64") (type . "C keywords")) ((name . "_Exit") (path . "program/_exit") (type . "Program support")) ((name . "_Generic") (path . "keyword/_generic") (type . "C keywords")) ((name . "_Imaginary") (path . "keyword/_imaginary") (type . "C keywords")) ((name . "_Imaginary_I") (path . "numeric/complex/imaginary_i") (type . "Numerics")) ((name . "_Noreturn") (path . "keyword/_noreturn") (type . "C keywords")) ((name . "_Noreturn (since C23)") (path . "language/attributes/noreturn") (type . "C language")) ((name . "_Noreturn function specifier") (path . "language/_noreturn") (type . "C language")) ((name . "_Static_assert") (path . "keyword/_static_assert") (type . "C keywords")) ((name . "_Thread_local") (path . "keyword/_thread_local") (type . "C keywords")) ((name . "abort") (path . "program/abort") (type . "Program support")) ((name . "abort_handler_s") (path . "error/abort_handler_s") (type . "Error handling")) ((name . "abs") (path . "numeric/math/abs") (type . "Numerics")) ((name . "acos") (path . "numeric/math/acos") (type . "Numerics")) ((name . "acosf") (path . "numeric/math/acos") (type . "Numerics")) ((name . "acosh") (path . "numeric/math/acosh") (type . "Numerics")) ((name . "acoshf") (path . "numeric/math/acosh") (type . "Numerics")) ((name . "acoshl") (path . "numeric/math/acosh") (type . "Numerics")) ((name . "acosl") (path . "numeric/math/acos") (type . "Numerics")) ((name . "Algorithms") (path . "algorithm") (type . "Algorithms")) ((name . "alignas") (path . "keyword/alignas") (type . "C keywords")) ((name . "alignas (since C23)") (path . "language/alignas") (type . "C language")) ((name . "alignas (since C23)") (path . "language/_alignas") (type . "C language")) ((name . "aligned_alloc") (path . "memory/aligned_alloc") (type . "Dynamic memory management")) ((name . "alignof") (path . "keyword/alignof") (type . "C keywords")) ((name . "Alternative operators and tokens") (path . "language/operator_alternative") (type . "C language")) ((name . "Analyzability") (path . "language/analyzability") (type . "C language")) ((name . "Arithmetic operators") (path . "language/operator_arithmetic") (type . "C language")) ((name . "Arithmetic types") (path . "language/arithmetic_types") (type . "C language")) ((name . "Array declaration") (path . "language/array") (type . "C language")) ((name . "Array initialization") (path . "language/array_initialization") (type . "C language")) ((name . "As-if rule") (path . "language/as_if") (type . "C language")) ((name . "ASCII Chart") (path . "language/ascii") (type . "C language")) ((name . "asctime") (path . "chrono/asctime") (type . "Date and time")) ((name . "asctime_s") (path . "chrono/asctime") (type . "Date and time")) ((name . "asin") (path . "numeric/math/asin") (type . "Numerics")) ((name . "asinf") (path . "numeric/math/asin") (type . "Numerics")) ((name . "asinh") (path . "numeric/math/asinh") (type . "Numerics")) ((name . "asinhf") (path . "numeric/math/asinh") (type . "Numerics")) ((name . "asinhl") (path . "numeric/math/asinh") (type . "Numerics")) ((name . "asinl") (path . "numeric/math/asin") (type . "Numerics")) ((name . "assert") (path . "error/assert") (type . "Error handling")) ((name . "Assignment operators") (path . "language/operator_assignment") (type . "C language")) ((name . "at_quick_exit") (path . "program/at_quick_exit") (type . "Program support")) ((name . "atan") (path . "numeric/math/atan") (type . "Numerics")) ((name . "atan2") (path . "numeric/math/atan2") (type . "Numerics")) ((name . "atan2f") (path . "numeric/math/atan2") (type . "Numerics")) ((name . "atan2l") (path . "numeric/math/atan2") (type . "Numerics")) ((name . "atanf") (path . "numeric/math/atan") (type . "Numerics")) ((name . "atanh") (path . "numeric/math/atanh") (type . "Numerics")) ((name . "atanhf") (path . "numeric/math/atanh") (type . "Numerics")) ((name . "atanhl") (path . "numeric/math/atanh") (type . "Numerics")) ((name . "atanl") (path . "numeric/math/atan") (type . "Numerics")) ((name . "atexit") (path . "program/atexit") (type . "Program support")) ((name . "atof") (path . "string/byte/atof") (type . "Strings")) ((name . "atoi") (path . "string/byte/atoi") (type . "Strings")) ((name . "atol") (path . "string/byte/atoi") (type . "Strings")) ((name . "atoll") (path . "string/byte/atoi") (type . "Strings")) ((name . "Atomic operations library") (path . "atomic") (type . "Atomic operations")) ((name . "Atomic types") (path . "language/atomic") (type . "C language")) ((name . "ATOMIC_*_LOCK_FREE") (path . "atomic/atomic_lock_free_consts") (type . "Concurrency support")) ((name . "atomic_compare_exchange_strong") (path . "atomic/atomic_compare_exchange") (type . "Concurrency support")) ((name . "atomic_compare_exchange_strong_explicit") (path . "atomic/atomic_compare_exchange") (type . "Concurrency support")) ((name . "atomic_compare_exchange_weak") (path . "atomic/atomic_compare_exchange") (type . "Concurrency support")) ((name . "atomic_compare_exchange_weak_explicit") (path . "atomic/atomic_compare_exchange") (type . "Concurrency support")) ((name . "atomic_exchange") (path . "atomic/atomic_exchange") (type . "Concurrency support")) ((name . "atomic_exchange_explicit") (path . "atomic/atomic_exchange") (type . "Concurrency support")) ((name . "atomic_fetch_add") (path . "atomic/atomic_fetch_add") (type . "Concurrency support")) ((name . "atomic_fetch_add_explicit") (path . "atomic/atomic_fetch_add") (type . "Concurrency support")) ((name . "atomic_fetch_and") (path . "atomic/atomic_fetch_and") (type . "Concurrency support")) ((name . "atomic_fetch_and_explicit") (path . "atomic/atomic_fetch_and") (type . "Concurrency support")) ((name . "atomic_fetch_or") (path . "atomic/atomic_fetch_or") (type . "Concurrency support")) ((name . "atomic_fetch_or_explicit") (path . "atomic/atomic_fetch_or") (type . "Concurrency support")) ((name . "atomic_fetch_sub") (path . "atomic/atomic_fetch_sub") (type . "Concurrency support")) ((name . "atomic_fetch_sub_explicit") (path . "atomic/atomic_fetch_sub") (type . "Concurrency support")) ((name . "atomic_fetch_xor") (path . "atomic/atomic_fetch_xor") (type . "Concurrency support")) ((name . "atomic_fetch_xor_explicit") (path . "atomic/atomic_fetch_xor") (type . "Concurrency support")) ((name . "atomic_flag") (path . "atomic/atomic_flag") (type . "Concurrency support")) ((name . "atomic_flag_clear") (path . "atomic/atomic_flag_clear") (type . "Concurrency support")) ((name . "atomic_flag_clear_explicit") (path . "atomic/atomic_flag_clear") (type . "Concurrency support")) ((name . "ATOMIC_FLAG_INIT") (path . "atomic/atomic_flag_init") (type . "Concurrency support")) ((name . "atomic_flag_test_and_set") (path . "atomic/atomic_flag_test_and_set") (type . "Concurrency support")) ((name . "atomic_flag_test_and_set_explicit") (path . "atomic/atomic_flag_test_and_set") (type . "Concurrency support")) ((name . "atomic_init") (path . "atomic/atomic_init") (type . "Concurrency support")) ((name . "atomic_is_lock_free") (path . "atomic/atomic_is_lock_free") (type . "Concurrency support")) ((name . "atomic_load") (path . "atomic/atomic_load") (type . "Concurrency support")) ((name . "atomic_load_explicit") (path . "atomic/atomic_load") (type . "Concurrency support")) ((name . "atomic_signal_fence") (path . "atomic/atomic_signal_fence") (type . "Concurrency support")) ((name . "atomic_store") (path . "atomic/atomic_store") (type . "Concurrency support")) ((name . "atomic_store_explicit") (path . "atomic/atomic_store") (type . "Concurrency support")) ((name . "atomic_thread_fence") (path . "atomic/atomic_thread_fence") (type . "Concurrency support")) ((name . "ATOMIC_VAR_INIT") (path . "atomic/atomic_var_init") (type . "Concurrency support")) ((name . "Attribute specifier sequence(since C23)") (path . "language/attributes") (type . "C language")) ((name . "auto") (path . "keyword/auto") (type . "C keywords")) ((name . "Basic concepts") (path . "language/basic_concepts") (type . "C language")) ((name . "Binary resource inclusion") (path . "preprocessor/embed") (type . "C language")) ((name . "Bit-fields") (path . "language/bit_field") (type . "C language")) ((name . "bool") (path . "keyword/bool") (type . "C keywords")) ((name . "break") (path . "keyword/break") (type . "C keywords")) ((name . "break statement") (path . "language/break") (type . "C language")) ((name . "bsearch") (path . "algorithm/bsearch") (type . "Algorithms")) ((name . "bsearch_s") (path . "algorithm/bsearch") (type . "Algorithms")) ((name . "btowc") (path . "string/multibyte/btowc") (type . "Strings")) ((name . "C attribute: deprecated") (path . "language/attributes/deprecated") (type . "C language")) ((name . "C attribute: fallthrough") (path . "language/attributes/fallthrough") (type . "C language")) ((name . "C attribute: maybe_unused") (path . "language/attributes/maybe_unused") (type . "C language")) ((name . "C attribute: nodiscard") (path . "language/attributes/nodiscard") (type . "C language")) ((name . "C attribute: noreturn") (path . "language/attributes/noreturn") (type . "C language")) ((name . "C attribute: unsequenced") (path . "language/attributes/reproducible") (type . "C language")) ((name . "C attribute: unsequenced") (path . "language/attributes/unsequenced") (type . "C language")) ((name . "C keywords") (path . "keyword") (type . "C keywords")) ((name . "C language") (path . "language") (type . "C language")) ((name . "C Operator Precedence") (path . "language/operator_precedence") (type . "C language")) ((name . "C11") (path . "11") (type . "Versions")) ((name . "c16rtomb") (path . "string/multibyte/c16rtomb") (type . "Strings")) ((name . "C17") (path . "17") (type . "Versions")) ((name . "C23") (path . "23") (type . "Versions")) ((name . "c32rtomb") (path . "string/multibyte/c32rtomb") (type . "Strings")) ((name . "c8rtomb") (path . "string/multibyte/c8rtomb") (type . "Strings")) ((name . "C95") (path . "95") (type . "Versions")) ((name . "C99") (path . "99") (type . "Versions")) ((name . "cabs") (path . "numeric/complex/cabs") (type . "Numerics")) ((name . "cabsf") (path . "numeric/complex/cabs") (type . "Numerics")) ((name . "cabsl") (path . "numeric/complex/cabs") (type . "Numerics")) ((name . "cacos") (path . "numeric/complex/cacos") (type . "Numerics")) ((name . "cacosf") (path . "numeric/complex/cacos") (type . "Numerics")) ((name . "cacosh") (path . "numeric/complex/cacosh") (type . "Numerics")) ((name . "cacoshf") (path . "numeric/complex/cacosh") (type . "Numerics")) ((name . "cacoshl") (path . "numeric/complex/cacosh") (type . "Numerics")) ((name . "cacosl") (path . "numeric/complex/cacos") (type . "Numerics")) ((name . "call_once") (path . "thread/call_once") (type . "Concurrency support")) ((name . "calloc") (path . "memory/calloc") (type . "Dynamic memory management")) ((name . "carg") (path . "numeric/complex/carg") (type . "Numerics")) ((name . "cargf") (path . "numeric/complex/carg") (type . "Numerics")) ((name . "cargl") (path . "numeric/complex/carg") (type . "Numerics")) ((name . "case") (path . "keyword/case") (type . "C keywords")) ((name . "casin") (path . "numeric/complex/casin") (type . "Numerics")) ((name . "casinf") (path . "numeric/complex/casin") (type . "Numerics")) ((name . "casinh") (path . "numeric/complex/casinh") (type . "Numerics")) ((name . "casinhf") (path . "numeric/complex/casinh") (type . "Numerics")) ((name . "casinhl") (path . "numeric/complex/casinh") (type . "Numerics")) ((name . "casinl") (path . "numeric/complex/casin") (type . "Numerics")) ((name . "cast operator") (path . "language/cast") (type . "C language")) ((name . "catan") (path . "numeric/complex/catan") (type . "Numerics")) ((name . "catanf") (path . "numeric/complex/catan") (type . "Numerics")) ((name . "catanh") (path . "numeric/complex/catanh") (type . "Numerics")) ((name . "catanhf") (path . "numeric/complex/catanh") (type . "Numerics")) ((name . "catanhl") (path . "numeric/complex/catanh") (type . "Numerics")) ((name . "catanl") (path . "numeric/complex/catan") (type . "Numerics")) ((name . "cbrt") (path . "numeric/math/cbrt") (type . "Numerics")) ((name . "cbrtf") (path . "numeric/math/cbrt") (type . "Numerics")) ((name . "cbrtl") (path . "numeric/math/cbrt") (type . "Numerics")) ((name . "ccos") (path . "numeric/complex/ccos") (type . "Numerics")) ((name . "ccosf") (path . "numeric/complex/ccos") (type . "Numerics")) ((name . "ccosh") (path . "numeric/complex/ccosh") (type . "Numerics")) ((name . "ccoshf") (path . "numeric/complex/ccosh") (type . "Numerics")) ((name . "ccoshl") (path . "numeric/complex/ccosh") (type . "Numerics")) ((name . "ccosl") (path . "numeric/complex/ccos") (type . "Numerics")) ((name . "ceil") (path . "numeric/math/ceil") (type . "Numerics")) ((name . "ceilf") (path . "numeric/math/ceil") (type . "Numerics")) ((name . "ceill") (path . "numeric/math/ceil") (type . "Numerics")) ((name . "cexp") (path . "numeric/complex/cexp") (type . "Numerics")) ((name . "cexpf") (path . "numeric/complex/cexp") (type . "Numerics")) ((name . "cexpl") (path . "numeric/complex/cexp") (type . "Numerics")) ((name . "char") (path . "keyword/char") (type . "C keywords")) ((name . "char16_t") (path . "string/multibyte/char16_t") (type . "Strings")) ((name . "char32_t") (path . "string/multibyte/char32_t") (type . "Strings")) ((name . "char8_t") (path . "string/multibyte/char8_t") (type . "Strings")) ((name . "Character constant") (path . "language/character_constant") (type . "C language")) ((name . "Character sets and encodings") (path . "language/charset") (type . "C language")) ((name . "cimag") (path . "numeric/complex/cimag") (type . "Numerics")) ((name . "cimagf") (path . "numeric/complex/cimag") (type . "Numerics")) ((name . "cimagl") (path . "numeric/complex/cimag") (type . "Numerics")) ((name . "clearerr") (path . "io/clearerr") (type . "File input/output")) ((name . "clock") (path . "chrono/clock") (type . "Date and time")) ((name . "clock_t") (path . "chrono/clock_t") (type . "Date and time")) ((name . "CLOCKS_PER_SEC") (path . "chrono/clocks_per_sec") (type . "Date and time")) ((name . "clog") (path . "numeric/complex/clog") (type . "Numerics")) ((name . "clogf") (path . "numeric/complex/clog") (type . "Numerics")) ((name . "clogl") (path . "numeric/complex/clog") (type . "Numerics")) ((name . "CMPLX") (path . "numeric/complex/cmplx") (type . "Numerics")) ((name . "CMPLXF") (path . "numeric/complex/cmplx") (type . "Numerics")) ((name . "CMPLXL") (path . "numeric/complex/cmplx") (type . "Numerics")) ((name . "cnd_broadcast") (path . "thread/cnd_broadcast") (type . "Concurrency support")) ((name . "cnd_destroy") (path . "thread/cnd_destroy") (type . "Concurrency support")) ((name . "cnd_init") (path . "thread/cnd_init") (type . "Concurrency support")) ((name . "cnd_signal") (path . "thread/cnd_signal") (type . "Concurrency support")) ((name . "cnd_timedwait") (path . "thread/cnd_timedwait") (type . "Concurrency support")) ((name . "cnd_wait") (path . "thread/cnd_wait") (type . "Concurrency support")) ((name . "Comments") (path . "comment") (type . "C language")) ((name . "Common mathematical functions") (path . "numeric/math") (type . "Numerics")) ((name . "Comparison operators") (path . "language/operator_comparison") (type . "C language")) ((name . "complex") (path . "numeric/complex/complex") (type . "Numerics")) ((name . "Complex number arithmetic") (path . "numeric/complex") (type . "Numerics")) ((name . "Compound literals") (path . "language/compound_literal") (type . "C language")) ((name . "Concurrency support library") (path . "thread") (type . "Concurrency support")) ((name . "Conditional inclusion") (path . "preprocessor/conditional") (type . "C language")) ((name . "Conformance") (path . "language/conformance") (type . "C language")) ((name . "conj") (path . "numeric/complex/conj") (type . "Numerics")) ((name . "conjf") (path . "numeric/complex/conj") (type . "Numerics")) ((name . "conjl") (path . "numeric/complex/conj") (type . "Numerics")) ((name . "const") (path . "keyword/const") (type . "C keywords")) ((name . "const type qualifier") (path . "language/const") (type . "C language")) ((name . "Constant expressions") (path . "language/constant_expression") (type . "C language")) ((name . "constexpr") (path . "keyword/constexpr") (type . "C keywords")) ((name . "constexpr specifier") (path . "language/constexpr") (type . "C language")) ((name . "constraint_handler_t") (path . "error/set_constraint_handler_s") (type . "Error handling")) ((name . "continue") (path . "keyword/continue") (type . "C keywords")) ((name . "continue statement") (path . "language/continue") (type . "C language")) ((name . "copysign") (path . "numeric/math/copysign") (type . "Numerics")) ((name . "copysignf") (path . "numeric/math/copysign") (type . "Numerics")) ((name . "copysignl") (path . "numeric/math/copysign") (type . "Numerics")) ((name . "cos") (path . "numeric/math/cos") (type . "Numerics")) ((name . "cosf") (path . "numeric/math/cos") (type . "Numerics")) ((name . "cosh") (path . "numeric/math/cosh") (type . "Numerics")) ((name . "coshf") (path . "numeric/math/cosh") (type . "Numerics")) ((name . "coshl") (path . "numeric/math/cosh") (type . "Numerics")) ((name . "cosl") (path . "numeric/math/cos") (type . "Numerics")) ((name . "cospi") (path . "numeric/math/cospi") (type . "Numerics")) ((name . "cospid128") (path . "numeric/math/cospi") (type . "Numerics")) ((name . "cospid32") (path . "numeric/math/cospi") (type . "Numerics")) ((name . "cospid64") (path . "numeric/math/cospi") (type . "Numerics")) ((name . "cospif") (path . "numeric/math/cospi") (type . "Numerics")) ((name . "cospil") (path . "numeric/math/cospi") (type . "Numerics")) ((name . "cpow") (path . "numeric/complex/cpow") (type . "Numerics")) ((name . "cpowf") (path . "numeric/complex/cpow") (type . "Numerics")) ((name . "cpowl") (path . "numeric/complex/cpow") (type . "Numerics")) ((name . "cproj") (path . "numeric/complex/cproj") (type . "Numerics")) ((name . "cprojf") (path . "numeric/complex/cproj") (type . "Numerics")) ((name . "cprojl") (path . "numeric/complex/cproj") (type . "Numerics")) ((name . "creal") (path . "numeric/complex/creal") (type . "Numerics")) ((name . "crealf") (path . "numeric/complex/creal") (type . "Numerics")) ((name . "creall") (path . "numeric/complex/creal") (type . "Numerics")) ((name . "csin") (path . "numeric/complex/csin") (type . "Numerics")) ((name . "csinf") (path . "numeric/complex/csin") (type . "Numerics")) ((name . "csinh") (path . "numeric/complex/csinh") (type . "Numerics")) ((name . "csinhf") (path . "numeric/complex/csinh") (type . "Numerics")) ((name . "csinhl") (path . "numeric/complex/csinh") (type . "Numerics")) ((name . "csinl") (path . "numeric/complex/csin") (type . "Numerics")) ((name . "csqrt") (path . "numeric/complex/csqrt") (type . "Numerics")) ((name . "csqrtf") (path . "numeric/complex/csqrt") (type . "Numerics")) ((name . "csqrtl") (path . "numeric/complex/csqrt") (type . "Numerics")) ((name . "ctan") (path . "numeric/complex/ctan") (type . "Numerics")) ((name . "ctanf") (path . "numeric/complex/ctan") (type . "Numerics")) ((name . "ctanh") (path . "numeric/complex/ctanh") (type . "Numerics")) ((name . "ctanhf") (path . "numeric/complex/ctanh") (type . "Numerics")) ((name . "ctanhl") (path . "numeric/complex/ctanh") (type . "Numerics")) ((name . "ctanl") (path . "numeric/complex/ctan") (type . "Numerics")) ((name . "ctime") (path . "chrono/ctime") (type . "Date and time")) ((name . "ctime_s") (path . "chrono/ctime") (type . "Date and time")) ((name . "Current Status") (path . "current_status") (type . "Versions")) ((name . "Date and time utilities") (path . "chrono") (type . "Date and time")) ((name . "Declarations") (path . "language/declarations") (type . "C language")) ((name . "default") (path . "keyword/default") (type . "C keywords")) ((name . "Diagnostic directives") (path . "preprocessor/error") (type . "C language")) ((name . "difftime") (path . "chrono/difftime") (type . "Date and time")) ((name . "div") (path . "numeric/math/div") (type . "Numerics")) ((name . "do") (path . "keyword/do") (type . "C keywords")) ((name . "do-while loop") (path . "language/do") (type . "C language")) ((name . "double") (path . "keyword/double") (type . "C keywords")) ((name . "double_t") (path . "numeric/math/float_t") (type . "Numerics")) ((name . "Dynamic memory management") (path . "memory") (type . "Dynamic memory management")) ((name . "else") (path . "keyword/else") (type . "C keywords")) ((name . "enum") (path . "keyword/enum") (type . "C keywords")) ((name . "Enumerations") (path . "language/enum") (type . "C language")) ((name . "erf") (path . "numeric/math/erf") (type . "Numerics")) ((name . "erfc") (path . "numeric/math/erfc") (type . "Numerics")) ((name . "erfcf") (path . "numeric/math/erfc") (type . "Numerics")) ((name . "erfcl") (path . "numeric/math/erfc") (type . "Numerics")) ((name . "erff") (path . "numeric/math/erf") (type . "Numerics")) ((name . "erfl") (path . "numeric/math/erf") (type . "Numerics")) ((name . "errno") (path . "error/errno") (type . "Error handling")) ((name . "Error handling") (path . "error") (type . "Error handling")) ((name . "Error numbers") (path . "error/errno_macros") (type . "Error handling")) ((name . "Escape sequences") (path . "language/escape") (type . "C language")) ((name . "exit") (path . "program/exit") (type . "Program support")) ((name . "EXIT_FAILURE") (path . "program/exit_status") (type . "Program support")) ((name . "EXIT_SUCCESS") (path . "program/exit_status") (type . "Program support")) ((name . "exp") (path . "numeric/math/exp") (type . "Numerics")) ((name . "exp2") (path . "numeric/math/exp2") (type . "Numerics")) ((name . "exp2f") (path . "numeric/math/exp2") (type . "Numerics")) ((name . "exp2l") (path . "numeric/math/exp2") (type . "Numerics")) ((name . "expf") (path . "numeric/math/exp") (type . "Numerics")) ((name . "expl") (path . "numeric/math/exp") (type . "Numerics")) ((name . "expm1") (path . "numeric/math/expm1") (type . "Numerics")) ((name . "expm1f") (path . "numeric/math/expm1") (type . "Numerics")) ((name . "expm1l") (path . "numeric/math/expm1") (type . "Numerics")) ((name . "Expressions") (path . "language/expressions") (type . "C language")) ((name . "extern") (path . "keyword/extern") (type . "C keywords")) ((name . "External and tentative definitions") (path . "language/extern") (type . "C language")) ((name . "fabs") (path . "numeric/math/fabs") (type . "Numerics")) ((name . "fabsd128") (path . "numeric/math/fabs") (type . "Numerics")) ((name . "fabsd32") (path . "numeric/math/fabs") (type . "Numerics")) ((name . "fabsd64") (path . "numeric/math/fabs") (type . "Numerics")) ((name . "fabsf") (path . "numeric/math/fabs") (type . "Numerics")) ((name . "fabsl") (path . "numeric/math/fabs") (type . "Numerics")) ((name . "false") (path . "keyword/false") (type . "C keywords")) ((name . "fclose") (path . "io/fclose") (type . "File input/output")) ((name . "fdim") (path . "numeric/math/fdim") (type . "Numerics")) ((name . "fdimf") (path . "numeric/math/fdim") (type . "Numerics")) ((name . "fdiml") (path . "numeric/math/fdim") (type . "Numerics")) ((name . "FE_ALL_EXCEPT") (path . "numeric/fenv/fe_exceptions") (type . "Numerics")) ((name . "FE_DFL_ENV") (path . "numeric/fenv/fe_dfl_env") (type . "Numerics")) ((name . "FE_DIVBYZERO") (path . "numeric/fenv/fe_exceptions") (type . "Numerics")) ((name . "FE_DOWNWARD") (path . "numeric/fenv/fe_round") (type . "Numerics")) ((name . "FE_INEXACT") (path . "numeric/fenv/fe_exceptions") (type . "Numerics")) ((name . "FE_INVALID") (path . "numeric/fenv/fe_exceptions") (type . "Numerics")) ((name . "FE_OVERFLOW") (path . "numeric/fenv/fe_exceptions") (type . "Numerics")) ((name . "FE_TONEAREST") (path . "numeric/fenv/fe_round") (type . "Numerics")) ((name . "FE_TOWARDZERO") (path . "numeric/fenv/fe_round") (type . "Numerics")) ((name . "FE_UNDERFLOW") (path . "numeric/fenv/fe_exceptions") (type . "Numerics")) ((name . "FE_UPWARD") (path . "numeric/fenv/fe_round") (type . "Numerics")) ((name . "feclearexcept") (path . "numeric/fenv/feclearexcept") (type . "Numerics")) ((name . "fegetenv") (path . "numeric/fenv/feenv") (type . "Numerics")) ((name . "fegetexceptflag") (path . "numeric/fenv/feexceptflag") (type . "Numerics")) ((name . "fegetround") (path . "numeric/fenv/feround") (type . "Numerics")) ((name . "feholdexcept") (path . "numeric/fenv/feholdexcept") (type . "Numerics")) ((name . "feof") (path . "io/feof") (type . "File input/output")) ((name . "feraiseexcept") (path . "numeric/fenv/feraiseexcept") (type . "Numerics")) ((name . "ferror") (path . "io/ferror") (type . "File input/output")) ((name . "fesetenv") (path . "numeric/fenv/feenv") (type . "Numerics")) ((name . "fesetexceptflag") (path . "numeric/fenv/feexceptflag") (type . "Numerics")) ((name . "fesetround") (path . "numeric/fenv/feround") (type . "Numerics")) ((name . "fetestexcept") (path . "numeric/fenv/fetestexcept") (type . "Numerics")) ((name . "feupdateenv") (path . "numeric/fenv/feupdateenv") (type . "Numerics")) ((name . "fflush") (path . "io/fflush") (type . "File input/output")) ((name . "fgetc") (path . "io/fgetc") (type . "File input/output")) ((name . "fgetpos") (path . "io/fgetpos") (type . "File input/output")) ((name . "fgets") (path . "io/fgets") (type . "File input/output")) ((name . "fgetwc") (path . "io/fgetwc") (type . "File input/output")) ((name . "fgetws") (path . "io/fgetws") (type . "File input/output")) ((name . "FILE") (path . "io/file") (type . "File input/output")) ((name . "File input/output") (path . "io") (type . "File input/output")) ((name . "File scope") (path . "language/file_scope") (type . "C language")) ((name . "Fixed width integer types") (path . "types/integer") (type . "Type support")) ((name . "float") (path . "keyword/float") (type . "C keywords")) ((name . "float_t") (path . "numeric/math/float_t") (type . "Numerics")) ((name . "Floating constant") (path . "language/floating_constant") (type . "C language")) ((name . "Floating-point environment") (path . "numeric/fenv") (type . "Numerics")) ((name . "floor") (path . "numeric/math/floor") (type . "Numerics")) ((name . "floorf") (path . "numeric/math/floor") (type . "Numerics")) ((name . "floorl") (path . "numeric/math/floor") (type . "Numerics")) ((name . "FLT_EVAL_METHOD") (path . "types/limits/flt_eval_method") (type . "Type support")) ((name . "FLT_ROUNDS") (path . "types/limits/flt_rounds") (type . "Type support")) ((name . "fma") (path . "numeric/math/fma") (type . "Numerics")) ((name . "fmaf") (path . "numeric/math/fma") (type . "Numerics")) ((name . "fmal") (path . "numeric/math/fma") (type . "Numerics")) ((name . "fmax") (path . "numeric/math/fmax") (type . "Numerics")) ((name . "fmaxf") (path . "numeric/math/fmax") (type . "Numerics")) ((name . "fmaxl") (path . "numeric/math/fmax") (type . "Numerics")) ((name . "fmin") (path . "numeric/math/fmin") (type . "Numerics")) ((name . "fminf") (path . "numeric/math/fmin") (type . "Numerics")) ((name . "fminl") (path . "numeric/math/fmin") (type . "Numerics")) ((name . "fmod") (path . "numeric/math/fmod") (type . "Numerics")) ((name . "fmodf") (path . "numeric/math/fmod") (type . "Numerics")) ((name . "fmodl") (path . "numeric/math/fmod") (type . "Numerics")) ((name . "fopen") (path . "io/fopen") (type . "File input/output")) ((name . "fopen_s") (path . "io/fopen") (type . "File input/output")) ((name . "for") (path . "keyword/for") (type . "C keywords")) ((name . "for loop") (path . "language/for") (type . "C language")) ((name . "fortran") (path . "keyword/fortran") (type . "C keywords")) ((name . "FP_INFINITE") (path . "numeric/math/fp_categories") (type . "Numerics")) ((name . "FP_NAN") (path . "numeric/math/fp_categories") (type . "Numerics")) ((name . "FP_NORMAL") (path . "numeric/math/fp_categories") (type . "Numerics")) ((name . "FP_SUBNORMAL") (path . "numeric/math/fp_categories") (type . "Numerics")) ((name . "FP_ZERO") (path . "numeric/math/fp_categories") (type . "Numerics")) ((name . "fpclassify") (path . "numeric/math/fpclassify") (type . "Numerics")) ((name . "fpos_t") (path . "io/fpos_t") (type . "File input/output")) ((name . "fprintf") (path . "io/fprintf") (type . "File input/output")) ((name . "fprintf_s") (path . "io/fprintf") (type . "File input/output")) ((name . "fputc") (path . "io/fputc") (type . "File input/output")) ((name . "fputs") (path . "io/fputs") (type . "File input/output")) ((name . "fputwc") (path . "io/fputwc") (type . "File input/output")) ((name . "fputws") (path . "io/fputws") (type . "File input/output")) ((name . "fread") (path . "io/fread") (type . "File input/output")) ((name . "free") (path . "memory/free") (type . "Dynamic memory management")) ((name . "free_aligned_sized") (path . "memory/free_aligned_sized") (type . "Dynamic memory management")) ((name . "free_sized") (path . "memory/free_sized") (type . "Dynamic memory management")) ((name . "freopen") (path . "io/freopen") (type . "File input/output")) ((name . "freopen_s") (path . "io/freopen") (type . "File input/output")) ((name . "frexp") (path . "numeric/math/frexp") (type . "Numerics")) ((name . "frexpf") (path . "numeric/math/frexp") (type . "Numerics")) ((name . "frexpl") (path . "numeric/math/frexp") (type . "Numerics")) ((name . "fscanf") (path . "io/fscanf") (type . "File input/output")) ((name . "fscanf_s") (path . "io/fscanf") (type . "File input/output")) ((name . "fseek") (path . "io/fseek") (type . "File input/output")) ((name . "fsetpos") (path . "io/fsetpos") (type . "File input/output")) ((name . "ftell") (path . "io/ftell") (type . "File input/output")) ((name . "Function declarations") (path . "language/function_declaration") (type . "C language")) ((name . "Function definitions") (path . "language/function_definition") (type . "C language")) ((name . "Functions") (path . "language/functions") (type . "C language")) ((name . "fwide") (path . "io/fwide") (type . "File input/output")) ((name . "fwprintf") (path . "io/fwprintf") (type . "File input/output")) ((name . "fwprintf_s") (path . "io/fwprintf") (type . "File input/output")) ((name . "fwrite") (path . "io/fwrite") (type . "File input/output")) ((name . "fwscanf") (path . "io/fwscanf") (type . "File input/output")) ((name . "fwscanf_s") (path . "io/fwscanf") (type . "File input/output")) ((name . "Generic selection") (path . "language/generic") (type . "C language")) ((name . "getc") (path . "io/fgetc") (type . "File input/output")) ((name . "getchar") (path . "io/getchar") (type . "File input/output")) ((name . "getenv") (path . "program/getenv") (type . "Program support")) ((name . "getenv_s") (path . "program/getenv") (type . "Program support")) ((name . "gets") (path . "io/gets") (type . "File input/output")) ((name . "gets_s") (path . "io/gets") (type . "File input/output")) ((name . "getwc") (path . "io/fgetwc") (type . "File input/output")) ((name . "getwchar") (path . "io/getwchar") (type . "File input/output")) ((name . "gmtime") (path . "chrono/gmtime") (type . "Date and time")) ((name . "gmtime_r") (path . "chrono/gmtime") (type . "Date and time")) ((name . "gmtime_s") (path . "chrono/gmtime") (type . "Date and time")) ((name . "goto") (path . "keyword/goto") (type . "C keywords")) ((name . "goto statement") (path . "language/goto") (type . "C language")) ((name . "History of C") (path . "language/history") (type . "C language")) ((name . "HUGE_VAL") (path . "numeric/math/huge_val") (type . "Numerics")) ((name . "HUGE_VALF") (path . "numeric/math/huge_val") (type . "Numerics")) ((name . "HUGE_VALL") (path . "numeric/math/huge_val") (type . "Numerics")) ((name . "hypot") (path . "numeric/math/hypot") (type . "Numerics")) ((name . "hypotf") (path . "numeric/math/hypot") (type . "Numerics")) ((name . "hypotl") (path . "numeric/math/hypot") (type . "Numerics")) ((name . "I") (path . "numeric/complex/i") (type . "Numerics")) ((name . "Identifier") (path . "language/identifier") (type . "C language")) ((name . "if") (path . "keyword/if") (type . "C keywords")) ((name . "if statement") (path . "language/if") (type . "C language")) ((name . "ignore_handler_s") (path . "error/ignore_handler_s") (type . "Error handling")) ((name . "ilogb") (path . "numeric/math/ilogb") (type . "Numerics")) ((name . "ilogbf") (path . "numeric/math/ilogb") (type . "Numerics")) ((name . "ilogbl") (path . "numeric/math/ilogb") (type . "Numerics")) ((name . "imaginary") (path . "numeric/complex/imaginary") (type . "Numerics")) ((name . "imaxabs") (path . "numeric/math/abs") (type . "Numerics")) ((name . "imaxdiv") (path . "numeric/math/div") (type . "Numerics")) ((name . "Implicit conversions") (path . "language/conversion") (type . "C language")) ((name . "Increment/decrement operators") (path . "language/operator_incdec") (type . "C language")) ((name . "INFINITY") (path . "numeric/math/infinity") (type . "Numerics")) ((name . "Initialization") (path . "language/initialization") (type . "C language")) ((name . "inline") (path . "keyword/inline") (type . "C keywords")) ((name . "Inline assembly") (path . "language/asm") (type . "C language")) ((name . "inline function specifier") (path . "language/inline") (type . "C language")) ((name . "int") (path . "keyword/int") (type . "C keywords")) ((name . "Integer constant") (path . "language/integer_constant") (type . "C language")) ((name . "isalnum") (path . "string/byte/isalnum") (type . "Strings")) ((name . "isalpha") (path . "string/byte/isalpha") (type . "Strings")) ((name . "isblank") (path . "string/byte/isblank") (type . "Strings")) ((name . "iscntrl") (path . "string/byte/iscntrl") (type . "Strings")) ((name . "isdigit") (path . "string/byte/isdigit") (type . "Strings")) ((name . "isfinite") (path . "numeric/math/isfinite") (type . "Numerics")) ((name . "isgraph") (path . "string/byte/isgraph") (type . "Strings")) ((name . "isgreater") (path . "numeric/math/isgreater") (type . "Numerics")) ((name . "isgreaterequal") (path . "numeric/math/isgreaterequal") (type . "Numerics")) ((name . "isinf") (path . "numeric/math/isinf") (type . "Numerics")) ((name . "isless") (path . "numeric/math/isless") (type . "Numerics")) ((name . "islessequal") (path . "numeric/math/islessequal") (type . "Numerics")) ((name . "islessgreater") (path . "numeric/math/islessgreater") (type . "Numerics")) ((name . "islower") (path . "string/byte/islower") (type . "Strings")) ((name . "isnan") (path . "numeric/math/isnan") (type . "Numerics")) ((name . "isnormal") (path . "numeric/math/isnormal") (type . "Numerics")) ((name . "isprint") (path . "string/byte/isprint") (type . "Strings")) ((name . "ispunct") (path . "string/byte/ispunct") (type . "Strings")) ((name . "isspace") (path . "string/byte/isspace") (type . "Strings")) ((name . "isunordered") (path . "numeric/math/isunordered") (type . "Numerics")) ((name . "isupper") (path . "string/byte/isupper") (type . "Strings")) ((name . "iswalnum") (path . "string/wide/iswalnum") (type . "Strings")) ((name . "iswalpha") (path . "string/wide/iswalpha") (type . "Strings")) ((name . "iswblank") (path . "string/wide/iswblank") (type . "Strings")) ((name . "iswcntrl") (path . "string/wide/iswcntrl") (type . "Strings")) ((name . "iswctype") (path . "string/wide/iswctype") (type . "Strings")) ((name . "iswdigit") (path . "string/wide/iswdigit") (type . "Strings")) ((name . "iswgraph") (path . "string/wide/iswgraph") (type . "Strings")) ((name . "iswlower") (path . "string/wide/iswlower") (type . "Strings")) ((name . "iswprint") (path . "string/wide/iswprint") (type . "Strings")) ((name . "iswpunct") (path . "string/wide/iswpunct") (type . "Strings")) ((name . "iswspace") (path . "string/wide/iswspace") (type . "Strings")) ((name . "iswupper") (path . "string/wide/iswupper") (type . "Strings")) ((name . "iswxdigit") (path . "string/wide/iswxdigit") (type . "Strings")) ((name . "isxdigit") (path . "string/byte/isxdigit") (type . "Strings")) ((name . "jmp_buf") (path . "program/jmp_buf") (type . "Program support")) ((name . "kill_dependency") (path . "atomic/kill_dependency") (type . "Concurrency support")) ((name . "labs") (path . "numeric/math/abs") (type . "Numerics")) ((name . "LC_ALL") (path . "locale/lc_categories") (type . "Localization support")) ((name . "LC_COLLATE") (path . "locale/lc_categories") (type . "Localization support")) ((name . "LC_CTYPE") (path . "locale/lc_categories") (type . "Localization support")) ((name . "LC_MONETARY") (path . "locale/lc_categories") (type . "Localization support")) ((name . "LC_NUMERIC") (path . "locale/lc_categories") (type . "Localization support")) ((name . "LC_TIME") (path . "locale/lc_categories") (type . "Localization support")) ((name . "lconv") (path . "locale/lconv") (type . "Localization support")) ((name . "ldexp") (path . "numeric/math/ldexp") (type . "Numerics")) ((name . "ldexpf") (path . "numeric/math/ldexp") (type . "Numerics")) ((name . "ldexpl") (path . "numeric/math/ldexp") (type . "Numerics")) ((name . "ldiv") (path . "numeric/math/div") (type . "Numerics")) ((name . "lgamma") (path . "numeric/math/lgamma") (type . "Numerics")) ((name . "lgammaf") (path . "numeric/math/lgamma") (type . "Numerics")) ((name . "lgammal") (path . "numeric/math/lgamma") (type . "Numerics")) ((name . "Lifetime") (path . "language/lifetime") (type . "C language")) ((name . "llabs") (path . "numeric/math/abs") (type . "Numerics")) ((name . "lldiv") (path . "numeric/math/div") (type . "Numerics")) ((name . "llrint") (path . "numeric/math/rint") (type . "Numerics")) ((name . "llrintf") (path . "numeric/math/rint") (type . "Numerics")) ((name . "llrintl") (path . "numeric/math/rint") (type . "Numerics")) ((name . "llround") (path . "numeric/math/round") (type . "Numerics")) ((name . "llroundf") (path . "numeric/math/round") (type . "Numerics")) ((name . "llroundl") (path . "numeric/math/round") (type . "Numerics")) ((name . "localeconv") (path . "locale/localeconv") (type . "Localization support")) ((name . "Localization support") (path . "locale") (type . "Localization support")) ((name . "localtime") (path . "chrono/localtime") (type . "Date and time")) ((name . "localtime_r") (path . "chrono/localtime") (type . "Date and time")) ((name . "localtime_s") (path . "chrono/localtime") (type . "Date and time")) ((name . "log") (path . "numeric/math/log") (type . "Numerics")) ((name . "log10") (path . "numeric/math/log10") (type . "Numerics")) ((name . "log10f") (path . "numeric/math/log10") (type . "Numerics")) ((name . "log10l") (path . "numeric/math/log10") (type . "Numerics")) ((name . "log1p") (path . "numeric/math/log1p") (type . "Numerics")) ((name . "log1pf") (path . "numeric/math/log1p") (type . "Numerics")) ((name . "log1pl") (path . "numeric/math/log1p") (type . "Numerics")) ((name . "log2") (path . "numeric/math/log2") (type . "Numerics")) ((name . "log2f") (path . "numeric/math/log2") (type . "Numerics")) ((name . "log2l") (path . "numeric/math/log2") (type . "Numerics")) ((name . "logb") (path . "numeric/math/logb") (type . "Numerics")) ((name . "logbf") (path . "numeric/math/logb") (type . "Numerics")) ((name . "logbl") (path . "numeric/math/logb") (type . "Numerics")) ((name . "logf") (path . "numeric/math/log") (type . "Numerics")) ((name . "Logical operators") (path . "language/operator_logical") (type . "C language")) ((name . "logl") (path . "numeric/math/log") (type . "Numerics")) ((name . "long") (path . "keyword/long") (type . "C keywords")) ((name . "longjmp") (path . "program/longjmp") (type . "Program support")) ((name . "Lookup and name spaces") (path . "language/name_space") (type . "C language")) ((name . "lrint") (path . "numeric/math/rint") (type . "Numerics")) ((name . "lrintf") (path . "numeric/math/rint") (type . "Numerics")) ((name . "lrintl") (path . "numeric/math/rint") (type . "Numerics")) ((name . "lround") (path . "numeric/math/round") (type . "Numerics")) ((name . "lroundf") (path . "numeric/math/round") (type . "Numerics")) ((name . "lroundl") (path . "numeric/math/round") (type . "Numerics")) ((name . "Main function") (path . "language/main_function") (type . "C language")) ((name . "malloc") (path . "memory/malloc") (type . "Dynamic memory management")) ((name . "MATH_ERREXCEPT") (path . "numeric/math/math_errhandling") (type . "Numerics")) ((name . "math_errhandling") (path . "numeric/math/math_errhandling") (type . "Numerics")) ((name . "MATH_ERRNO") (path . "numeric/math/math_errhandling") (type . "Numerics")) ((name . "max_align_t") (path . "types/max_align_t") (type . "Type support")) ((name . "mblen") (path . "string/multibyte/mblen") (type . "Strings")) ((name . "mbrlen") (path . "string/multibyte/mbrlen") (type . "Strings")) ((name . "mbrtoc16") (path . "string/multibyte/mbrtoc16") (type . "Strings")) ((name . "mbrtoc32") (path . "string/multibyte/mbrtoc32") (type . "Strings")) ((name . "mbrtoc8") (path . "string/multibyte/mbrtoc8") (type . "Strings")) ((name . "mbrtowc") (path . "string/multibyte/mbrtowc") (type . "Strings")) ((name . "mbsinit") (path . "string/multibyte/mbsinit") (type . "Strings")) ((name . "mbsrtowcs") (path . "string/multibyte/mbsrtowcs") (type . "Strings")) ((name . "mbsrtowcs_s") (path . "string/multibyte/mbsrtowcs") (type . "Strings")) ((name . "mbstate_t") (path . "string/multibyte/mbstate_t") (type . "Strings")) ((name . "mbstowcs") (path . "string/multibyte/mbstowcs") (type . "Strings")) ((name . "mbstowcs_s") (path . "string/multibyte/mbstowcs") (type . "Strings")) ((name . "mbtowc") (path . "string/multibyte/mbtowc") (type . "Strings")) ((name . "Member access operators") (path . "language/operator_member_access") (type . "C language")) ((name . "memccpy") (path . "string/byte/memccpy") (type . "Strings")) ((name . "memchr") (path . "string/byte/memchr") (type . "Strings")) ((name . "memcmp") (path . "string/byte/memcmp") (type . "Strings")) ((name . "memcpy") (path . "string/byte/memcpy") (type . "Strings")) ((name . "memcpy_s") (path . "string/byte/memcpy") (type . "Strings")) ((name . "memmove") (path . "string/byte/memmove") (type . "Strings")) ((name . "memmove_s") (path . "string/byte/memmove") (type . "Strings")) ((name . "Memory model") (path . "language/memory_model") (type . "C language")) ((name . "memory_order") (path . "atomic/memory_order") (type . "Concurrency support")) ((name . "memset") (path . "string/byte/memset") (type . "Strings")) ((name . "memset_explicit") (path . "string/byte/memset") (type . "Strings")) ((name . "memset_s") (path . "string/byte/memset") (type . "Strings")) ((name . "mktime") (path . "chrono/mktime") (type . "Date and time")) ((name . "modf") (path . "numeric/math/modf") (type . "Numerics")) ((name . "modff") (path . "numeric/math/modf") (type . "Numerics")) ((name . "modfl") (path . "numeric/math/modf") (type . "Numerics")) ((name . "mtx_destroy") (path . "thread/mtx_destroy") (type . "Concurrency support")) ((name . "mtx_init") (path . "thread/mtx_init") (type . "Concurrency support")) ((name . "mtx_lock") (path . "thread/mtx_lock") (type . "Concurrency support")) ((name . "mtx_plain") (path . "thread/mtx_types") (type . "Concurrency support")) ((name . "mtx_recursive") (path . "thread/mtx_types") (type . "Concurrency support")) ((name . "mtx_timed") (path . "thread/mtx_types") (type . "Concurrency support")) ((name . "mtx_timedlock") (path . "thread/mtx_timedlock") (type . "Concurrency support")) ((name . "mtx_trylock") (path . "thread/mtx_trylock") (type . "Concurrency support")) ((name . "mtx_unlock") (path . "thread/mtx_unlock") (type . "Concurrency support")) ((name . "nan") (path . "numeric/math/nan") (type . "Numerics")) ((name . "nand128") (path . "numeric/math/nan") (type . "Numerics")) ((name . "nand32") (path . "numeric/math/nan") (type . "Numerics")) ((name . "nand64") (path . "numeric/math/nan") (type . "Numerics")) ((name . "nanf") (path . "numeric/math/nan") (type . "Numerics")) ((name . "nanl") (path . "numeric/math/nan") (type . "Numerics")) ((name . "nearbyint") (path . "numeric/math/nearbyint") (type . "Numerics")) ((name . "nearbyintf") (path . "numeric/math/nearbyint") (type . "Numerics")) ((name . "nearbyintl") (path . "numeric/math/nearbyint") (type . "Numerics")) ((name . "nextafter") (path . "numeric/math/nextafter") (type . "Numerics")) ((name . "nextafterf") (path . "numeric/math/nextafter") (type . "Numerics")) ((name . "nextafterl") (path . "numeric/math/nextafter") (type . "Numerics")) ((name . "nexttoward") (path . "numeric/math/nextafter") (type . "Numerics")) ((name . "nexttowardf") (path . "numeric/math/nextafter") (type . "Numerics")) ((name . "nexttowardl") (path . "numeric/math/nextafter") (type . "Numerics")) ((name . "NULL") (path . "types/null") (type . "Type support")) ((name . "Null-terminated byte strings") (path . "string/byte") (type . "Strings")) ((name . "Null-terminated multibyte strings") (path . "string/multibyte") (type . "Strings")) ((name . "Null-terminated wide strings") (path . "string/wide") (type . "Strings")) ((name . "nullptr") (path . "keyword/nullptr") (type . "C keywords")) ((name . "nullptr_t") (path . "types/nullptr_t") (type . "Type support")) ((name . "Numeric limits") (path . "types/limits") (type . "Type support")) ((name . "Numerics") (path . "numeric") (type . "Numerics")) ((name . "Objects and alignment") (path . "language/object") (type . "C language")) ((name . "offsetof") (path . "types/offsetof") (type . "Type support")) ((name . "once_flag") (path . "thread/call_once") (type . "Concurrency support")) ((name . "ONCE_FLAG_INIT") (path . "thread/call_once") (type . "Concurrency support")) ((name . "Order of evaluation") (path . "language/eval_order") (type . "C language")) ((name . "Other operators") (path . "language/operator_other") (type . "C language")) ((name . "perror") (path . "io/perror") (type . "File input/output")) ((name . "Phases of translation") (path . "language/translation_phases") (type . "C language")) ((name . "Pointer declaration") (path . "language/pointer") (type . "C language")) ((name . "pow") (path . "numeric/math/pow") (type . "Numerics")) ((name . "powf") (path . "numeric/math/pow") (type . "Numerics")) ((name . "powl") (path . "numeric/math/pow") (type . "Numerics")) ((name . "Predefined Boolean constants") (path . "language/bool_constant") (type . "C language")) ((name . "Predefined null pointer constant") (path . "language/nullptr") (type . "C language")) ((name . "Preprocessor") (path . "preprocessor") (type . "C language")) ((name . "printf") (path . "io/fprintf") (type . "File input/output")) ((name . "printf_s") (path . "io/fprintf") (type . "File input/output")) ((name . "Program support utilities") (path . "program") (type . "Program support")) ((name . "Pseudo-random number generation") (path . "numeric/random") (type . "Numerics")) ((name . "ptrdiff_t") (path . "types/ptrdiff_t") (type . "Type support")) ((name . "Punctuation") (path . "language/punctuators") (type . "C language")) ((name . "putc") (path . "io/fputc") (type . "File input/output")) ((name . "putchar") (path . "io/putchar") (type . "File input/output")) ((name . "puts") (path . "io/puts") (type . "File input/output")) ((name . "putwc") (path . "io/fputwc") (type . "File input/output")) ((name . "putwchar") (path . "io/putwchar") (type . "File input/output")) ((name . "qsort") (path . "algorithm/qsort") (type . "Algorithms")) ((name . "qsort_s") (path . "algorithm/qsort") (type . "Algorithms")) ((name . "quick_exit") (path . "program/quick_exit") (type . "Program support")) ((name . "raise") (path . "program/raise") (type . "Program support")) ((name . "rand") (path . "numeric/random/rand") (type . "Numerics")) ((name . "RAND_MAX") (path . "numeric/random/rand_max") (type . "Numerics")) ((name . "realloc") (path . "memory/realloc") (type . "Dynamic memory management")) ((name . "register") (path . "keyword/register") (type . "C keywords")) ((name . "remainder") (path . "numeric/math/remainder") (type . "Numerics")) ((name . "remainderf") (path . "numeric/math/remainder") (type . "Numerics")) ((name . "remainderl") (path . "numeric/math/remainder") (type . "Numerics")) ((name . "remove") (path . "io/remove") (type . "File input/output")) ((name . "remquo") (path . "numeric/math/remquo") (type . "Numerics")) ((name . "remquof") (path . "numeric/math/remquo") (type . "Numerics")) ((name . "remquol") (path . "numeric/math/remquo") (type . "Numerics")) ((name . "rename") (path . "io/rename") (type . "File input/output")) ((name . "reproducible (since C23)") (path . "language/attributes/unsequenced") (type . "C language")) ((name . "reproducible (since C23)") (path . "language/attributes/reproducible") (type . "C language")) ((name . "restrict") (path . "keyword/restrict") (type . "C keywords")) ((name . "restrict type qualifier") (path . "language/restrict") (type . "C language")) ((name . "return") (path . "keyword/return") (type . "C keywords")) ((name . "return statement") (path . "language/return") (type . "C language")) ((name . "rewind") (path . "io/rewind") (type . "File input/output")) ((name . "rint") (path . "numeric/math/rint") (type . "Numerics")) ((name . "rintf") (path . "numeric/math/rint") (type . "Numerics")) ((name . "rintl") (path . "numeric/math/rint") (type . "Numerics")) ((name . "round") (path . "numeric/math/round") (type . "Numerics")) ((name . "roundeven") (path . "numeric/math/roundeven") (type . "Numerics")) ((name . "roundevenf") (path . "numeric/math/roundeven") (type . "Numerics")) ((name . "roundevenl") (path . "numeric/math/roundeven") (type . "Numerics")) ((name . "roundf") (path . "numeric/math/round") (type . "Numerics")) ((name . "roundl") (path . "numeric/math/round") (type . "Numerics")) ((name . "Scalar initialization") (path . "language/scalar_initialization") (type . "C language")) ((name . "scalbln") (path . "numeric/math/scalbn") (type . "Numerics")) ((name . "scalblnf") (path . "numeric/math/scalbn") (type . "Numerics")) ((name . "scalblnl") (path . "numeric/math/scalbn") (type . "Numerics")) ((name . "scalbn") (path . "numeric/math/scalbn") (type . "Numerics")) ((name . "scalbnf") (path . "numeric/math/scalbn") (type . "Numerics")) ((name . "scalbnl") (path . "numeric/math/scalbn") (type . "Numerics")) ((name . "scanf") (path . "io/fscanf") (type . "File input/output")) ((name . "scanf_s") (path . "io/fscanf") (type . "File input/output")) ((name . "Scope") (path . "language/scope") (type . "C language")) ((name . "set_constraint_handler_s") (path . "error/set_constraint_handler_s") (type . "Error handling")) ((name . "setbuf") (path . "io/setbuf") (type . "File input/output")) ((name . "setjmp") (path . "program/setjmp") (type . "Program support")) ((name . "setlocale") (path . "locale/setlocale") (type . "Localization support")) ((name . "setvbuf") (path . "io/setvbuf") (type . "File input/output")) ((name . "short") (path . "keyword/short") (type . "C keywords")) ((name . "sig_atomic_t") (path . "program/sig_atomic_t") (type . "Program support")) ((name . "SIG_DFL") (path . "program/sig_strategies") (type . "Program support")) ((name . "SIG_ERR") (path . "program/sig_err") (type . "Program support")) ((name . "SIG_IGN") (path . "program/sig_strategies") (type . "Program support")) ((name . "SIGABRT") (path . "program/sig_types") (type . "Program support")) ((name . "SIGFPE") (path . "program/sig_types") (type . "Program support")) ((name . "SIGILL") (path . "program/sig_types") (type . "Program support")) ((name . "SIGINT") (path . "program/sig_types") (type . "Program support")) ((name . "signal") (path . "program/signal") (type . "Program support")) ((name . "signbit") (path . "numeric/math/signbit") (type . "Numerics")) ((name . "signed") (path . "keyword/signed") (type . "C keywords")) ((name . "SIGSEGV") (path . "program/sig_types") (type . "Program support")) ((name . "SIGTERM") (path . "program/sig_types") (type . "Program support")) ((name . "sin") (path . "numeric/math/sin") (type . "Numerics")) ((name . "sinf") (path . "numeric/math/sin") (type . "Numerics")) ((name . "sinh") (path . "numeric/math/sinh") (type . "Numerics")) ((name . "sinhf") (path . "numeric/math/sinh") (type . "Numerics")) ((name . "sinhl") (path . "numeric/math/sinh") (type . "Numerics")) ((name . "sinl") (path . "numeric/math/sin") (type . "Numerics")) ((name . "sinpi") (path . "numeric/math/sinpi") (type . "Numerics")) ((name . "sinpid128") (path . "numeric/math/sinpi") (type . "Numerics")) ((name . "sinpid32") (path . "numeric/math/sinpi") (type . "Numerics")) ((name . "sinpid64") (path . "numeric/math/sinpi") (type . "Numerics")) ((name . "sinpif") (path . "numeric/math/sinpi") (type . "Numerics")) ((name . "sinpil") (path . "numeric/math/sinpi") (type . "Numerics")) ((name . "size_t") (path . "types/size_t") (type . "Type support")) ((name . "sizeof") (path . "keyword/sizeof") (type . "C keywords")) ((name . "sizeof operator") (path . "language/sizeof") (type . "C language")) ((name . "snprintf") (path . "io/fprintf") (type . "File input/output")) ((name . "snprintf_s") (path . "io/fprintf") (type . "File input/output")) ((name . "snwprintf_s") (path . "io/fwprintf") (type . "File input/output")) ((name . "sprintf") (path . "io/fprintf") (type . "File input/output")) ((name . "sprintf_s") (path . "io/fprintf") (type . "File input/output")) ((name . "sqrt") (path . "numeric/math/sqrt") (type . "Numerics")) ((name . "sqrtf") (path . "numeric/math/sqrt") (type . "Numerics")) ((name . "sqrtl") (path . "numeric/math/sqrt") (type . "Numerics")) ((name . "srand") (path . "numeric/random/srand") (type . "Numerics")) ((name . "sscanf") (path . "io/fscanf") (type . "File input/output")) ((name . "sscanf_s") (path . "io/fscanf") (type . "File input/output")) ((name . "Statements") (path . "language/statements") (type . "C language")) ((name . "static") (path . "keyword/static") (type . "C keywords")) ((name . "Static assertion") (path . "language/_static_assert") (type . "C language")) ((name . "Static assertion") (path . "language/static_assert") (type . "C language")) ((name . "Static storage duration") (path . "language/static_storage_duration") (type . "C language")) ((name . "static_assert") (path . "keyword/static_assert") (type . "C keywords")) ((name . "static_assert") (path . "error/static_assert") (type . "Error handling")) ((name . "stderr") (path . "io/std_streams") (type . "File input/output")) ((name . "stdin") (path . "io/std_streams") (type . "File input/output")) ((name . "stdout") (path . "io/std_streams") (type . "File input/output")) ((name . "Storage-class specifiers") (path . "language/storage_duration") (type . "C language")) ((name . "strcat") (path . "string/byte/strcat") (type . "Strings")) ((name . "strcat_s") (path . "string/byte/strcat") (type . "Strings")) ((name . "strchr") (path . "string/byte/strchr") (type . "Strings")) ((name . "strcmp") (path . "string/byte/strcmp") (type . "Strings")) ((name . "strcoll") (path . "string/byte/strcoll") (type . "Strings")) ((name . "strcpy") (path . "string/byte/strcpy") (type . "Strings")) ((name . "strcpy_s") (path . "string/byte/strcpy") (type . "Strings")) ((name . "strcspn") (path . "string/byte/strcspn") (type . "Strings")) ((name . "strdup") (path . "string/byte/strdup") (type . "Strings")) ((name . "strerror") (path . "string/byte/strerror") (type . "Strings")) ((name . "strerror_s") (path . "string/byte/strerror") (type . "Strings")) ((name . "strerrorlen_s") (path . "string/byte/strerror") (type . "Strings")) ((name . "strfromd") (path . "string/byte/strfromf") (type . "Strings")) ((name . "strfromf") (path . "string/byte/strfromf") (type . "Strings")) ((name . "strfromld") (path . "string/byte/strfromf") (type . "Strings")) ((name . "strftime") (path . "chrono/strftime") (type . "Date and time")) ((name . "String literals") (path . "language/string_literal") (type . "C language")) ((name . "Strings library") (path . "string") (type . "Strings")) ((name . "strlen") (path . "string/byte/strlen") (type . "Strings")) ((name . "strncat") (path . "string/byte/strncat") (type . "Strings")) ((name . "strncat_s") (path . "string/byte/strncat") (type . "Strings")) ((name . "strncmp") (path . "string/byte/strncmp") (type . "Strings")) ((name . "strncpy") (path . "string/byte/strncpy") (type . "Strings")) ((name . "strncpy_s") (path . "string/byte/strncpy") (type . "Strings")) ((name . "strndup") (path . "string/byte/strndup") (type . "Strings")) ((name . "strnlen_s") (path . "string/byte/strlen") (type . "Strings")) ((name . "strpbrk") (path . "string/byte/strpbrk") (type . "Strings")) ((name . "strrchr") (path . "string/byte/strrchr") (type . "Strings")) ((name . "strspn") (path . "string/byte/strspn") (type . "Strings")) ((name . "strstr") (path . "string/byte/strstr") (type . "Strings")) ((name . "strtod") (path . "string/byte/strtof") (type . "Strings")) ((name . "strtof") (path . "string/byte/strtof") (type . "Strings")) ((name . "strtoimax") (path . "string/byte/strtoimax") (type . "Strings")) ((name . "strtok") (path . "string/byte/strtok") (type . "Strings")) ((name . "strtok_s") (path . "string/byte/strtok") (type . "Strings")) ((name . "strtol") (path . "string/byte/strtol") (type . "Strings")) ((name . "strtold") (path . "string/byte/strtof") (type . "Strings")) ((name . "strtoll") (path . "string/byte/strtol") (type . "Strings")) ((name . "strtoul") (path . "string/byte/strtoul") (type . "Strings")) ((name . "strtoull") (path . "string/byte/strtoul") (type . "Strings")) ((name . "strtoumax") (path . "string/byte/strtoimax") (type . "Strings")) ((name . "struct") (path . "keyword/struct") (type . "C keywords")) ((name . "Struct and union initialization") (path . "language/struct_initialization") (type . "C language")) ((name . "Struct declaration") (path . "language/struct") (type . "C language")) ((name . "strxfrm") (path . "string/byte/strxfrm") (type . "Strings")) ((name . "switch") (path . "keyword/switch") (type . "C keywords")) ((name . "switch statement") (path . "language/switch") (type . "C language")) ((name . "swprintf") (path . "io/fwprintf") (type . "File input/output")) ((name . "swprintf_s") (path . "io/fwprintf") (type . "File input/output")) ((name . "swscanf") (path . "io/fwscanf") (type . "File input/output")) ((name . "swscanf_s") (path . "io/fwscanf") (type . "File input/output")) ((name . "system") (path . "program/system") (type . "Program support")) ((name . "tan") (path . "numeric/math/tan") (type . "Numerics")) ((name . "tanf") (path . "numeric/math/tan") (type . "Numerics")) ((name . "tanh") (path . "numeric/math/tanh") (type . "Numerics")) ((name . "tanhf") (path . "numeric/math/tanh") (type . "Numerics")) ((name . "tanhl") (path . "numeric/math/tanh") (type . "Numerics")) ((name . "tanl") (path . "numeric/math/tan") (type . "Numerics")) ((name . "tgamma") (path . "numeric/math/tgamma") (type . "Numerics")) ((name . "tgammaf") (path . "numeric/math/tgamma") (type . "Numerics")) ((name . "tgammal") (path . "numeric/math/tgamma") (type . "Numerics")) ((name . "thrd_busy") (path . "thread/thrd_errors") (type . "Concurrency support")) ((name . "thrd_create") (path . "thread/thrd_create") (type . "Concurrency support")) ((name . "thrd_current") (path . "thread/thrd_current") (type . "Concurrency support")) ((name . "thrd_detach") (path . "thread/thrd_detach") (type . "Concurrency support")) ((name . "thrd_equal") (path . "thread/thrd_equal") (type . "Concurrency support")) ((name . "thrd_error") (path . "thread/thrd_errors") (type . "Concurrency support")) ((name . "thrd_exit") (path . "thread/thrd_exit") (type . "Concurrency support")) ((name . "thrd_join") (path . "thread/thrd_join") (type . "Concurrency support")) ((name . "thrd_nomem") (path . "thread/thrd_errors") (type . "Concurrency support")) ((name . "thrd_sleep") (path . "thread/thrd_sleep") (type . "Concurrency support")) ((name . "thrd_success") (path . "thread/thrd_errors") (type . "Concurrency support")) ((name . "thrd_timedout") (path . "thread/thrd_errors") (type . "Concurrency support")) ((name . "thrd_yield") (path . "thread/thrd_yield") (type . "Concurrency support")) ((name . "Thread storage duration") (path . "language/thread_storage_duration") (type . "C language")) ((name . "thread_local") (path . "keyword/thread_local") (type . "C keywords")) ((name . "thread_local") (path . "thread/thread_local") (type . "Concurrency support")) ((name . "time") (path . "chrono/time") (type . "Date and time")) ((name . "time_t") (path . "chrono/time_t") (type . "Date and time")) ((name . "timespec") (path . "chrono/timespec") (type . "Date and time")) ((name . "timespec_get") (path . "chrono/timespec_get") (type . "Date and time")) ((name . "timespec_getres") (path . "chrono/timespec_getres") (type . "Date and time")) ((name . "tm") (path . "chrono/tm") (type . "Date and time")) ((name . "tmpfile") (path . "io/tmpfile") (type . "File input/output")) ((name . "tmpfile_s") (path . "io/tmpfile") (type . "File input/output")) ((name . "tmpnam") (path . "io/tmpnam") (type . "File input/output")) ((name . "tmpnam_s") (path . "io/tmpnam") (type . "File input/output")) ((name . "tolower") (path . "string/byte/tolower") (type . "Strings")) ((name . "toupper") (path . "string/byte/toupper") (type . "Strings")) ((name . "towctrans") (path . "string/wide/towctrans") (type . "Strings")) ((name . "towlower") (path . "string/wide/towlower") (type . "Strings")) ((name . "towupper") (path . "string/wide/towupper") (type . "Strings")) ((name . "true") (path . "keyword/true") (type . "C keywords")) ((name . "trunc") (path . "numeric/math/trunc") (type . "Numerics")) ((name . "truncf") (path . "numeric/math/trunc") (type . "Numerics")) ((name . "truncl") (path . "numeric/math/trunc") (type . "Numerics")) ((name . "tss_create") (path . "thread/tss_create") (type . "Concurrency support")) ((name . "tss_delete") (path . "thread/tss_delete") (type . "Concurrency support")) ((name . "TSS_DTOR_ITERATIONS") (path . "thread/tss_dtor_iterations") (type . "Concurrency support")) ((name . "tss_get") (path . "thread/tss_get") (type . "Concurrency support")) ((name . "tss_set") (path . "thread/tss_set") (type . "Concurrency support")) ((name . "Type") (path . "language/compatible_type") (type . "C language")) ((name . "Type") (path . "language/types") (type . "C language")) ((name . "Type") (path . "language/type") (type . "C language")) ((name . "Type support") (path . "types") (type . "Type support")) ((name . "Type-generic math") (path . "numeric/tgmath") (type . "Numerics")) ((name . "typedef") (path . "keyword/typedef") (type . "C keywords")) ((name . "Typedef declaration") (path . "language/typedef") (type . "C language")) ((name . "typeof") (path . "keyword/typeof") (type . "C keywords")) ((name . "typeof operators") (path . "language/typeof") (type . "C language")) ((name . "typeof_unqual") (path . "keyword/typeof_unqual") (type . "C keywords")) ((name . "Undefined behavior") (path . "language/behavior") (type . "C language")) ((name . "ungetc") (path . "io/ungetc") (type . "File input/output")) ((name . "ungetwc") (path . "io/ungetwc") (type . "File input/output")) ((name . "union") (path . "keyword/union") (type . "C keywords")) ((name . "Union declaration") (path . "language/union") (type . "C language")) ((name . "unreachable") (path . "program/unreachable") (type . "Program support")) ((name . "unsigned") (path . "keyword/unsigned") (type . "C keywords")) ((name . "va_arg") (path . "variadic/va_arg") (type . "Variadic functions")) ((name . "va_copy") (path . "variadic/va_copy") (type . "Variadic functions")) ((name . "va_end") (path . "variadic/va_end") (type . "Variadic functions")) ((name . "va_list") (path . "variadic/va_list") (type . "Variadic functions")) ((name . "va_start") (path . "variadic/va_start") (type . "Variadic functions")) ((name . "Value categories") (path . "language/value_category") (type . "C language")) ((name . "Variadic arguments") (path . "language/variadic") (type . "C language")) ((name . "Variadic functions") (path . "variadic") (type . "Variadic functions")) ((name . "vfprintf") (path . "io/vfprintf") (type . "File input/output")) ((name . "vfprintf_s") (path . "io/vfprintf") (type . "File input/output")) ((name . "vfscanf") (path . "io/vfscanf") (type . "File input/output")) ((name . "vfscanf_s") (path . "io/vfscanf") (type . "File input/output")) ((name . "vfwprintf") (path . "io/vfwprintf") (type . "File input/output")) ((name . "vfwprintf_s") (path . "io/vfwprintf") (type . "File input/output")) ((name . "vfwscanf") (path . "io/vfwscanf") (type . "File input/output")) ((name . "vfwscanf_s") (path . "io/vfwscanf") (type . "File input/output")) ((name . "void") (path . "keyword/void") (type . "C keywords")) ((name . "volatile") (path . "keyword/volatile") (type . "C keywords")) ((name . "volatile type qualifier") (path . "language/volatile") (type . "C language")) ((name . "vprintf") (path . "io/vfprintf") (type . "File input/output")) ((name . "vprintf_s") (path . "io/vfprintf") (type . "File input/output")) ((name . "vscanf") (path . "io/vfscanf") (type . "File input/output")) ((name . "vscanf_s") (path . "io/vfscanf") (type . "File input/output")) ((name . "vsnprintf") (path . "io/vfprintf") (type . "File input/output")) ((name . "vsnprintf_s") (path . "io/vfprintf") (type . "File input/output")) ((name . "vsnwprintf_s") (path . "io/vfwprintf") (type . "File input/output")) ((name . "vsprintf") (path . "io/vfprintf") (type . "File input/output")) ((name . "vsprintf_s") (path . "io/vfprintf") (type . "File input/output")) ((name . "vsscanf") (path . "io/vfscanf") (type . "File input/output")) ((name . "vsscanf_s") (path . "io/vfscanf") (type . "File input/output")) ((name . "vswprintf") (path . "io/vfwprintf") (type . "File input/output")) ((name . "vswprintf_s") (path . "io/vfwprintf") (type . "File input/output")) ((name . "vswscanf") (path . "io/vfwscanf") (type . "File input/output")) ((name . "vswscanf_s") (path . "io/vfwscanf") (type . "File input/output")) ((name . "vwprintf") (path . "io/vfwprintf") (type . "File input/output")) ((name . "vwprintf_s") (path . "io/vfwprintf") (type . "File input/output")) ((name . "vwscanf") (path . "io/vfwscanf") (type . "File input/output")) ((name . "vwscanf_s") (path . "io/vfwscanf") (type . "File input/output")) ((name . "wcrtomb") (path . "string/multibyte/wcrtomb") (type . "Strings")) ((name . "wcrtomb_s") (path . "string/multibyte/wcrtomb") (type . "Strings")) ((name . "wcscat") (path . "string/wide/wcscat") (type . "Strings")) ((name . "wcscat_s") (path . "string/wide/wcscat") (type . "Strings")) ((name . "wcschr") (path . "string/wide/wcschr") (type . "Strings")) ((name . "wcscmp") (path . "string/wide/wcscmp") (type . "Strings")) ((name . "wcscoll") (path . "string/wide/wcscoll") (type . "Strings")) ((name . "wcscpy") (path . "string/wide/wcscpy") (type . "Strings")) ((name . "wcscpy_s") (path . "string/wide/wcscpy") (type . "Strings")) ((name . "wcscspn") (path . "string/wide/wcscspn") (type . "Strings")) ((name . "wcsftime") (path . "chrono/wcsftime") (type . "Date and time")) ((name . "wcslen") (path . "string/wide/wcslen") (type . "Strings")) ((name . "wcsncat") (path . "string/wide/wcsncat") (type . "Strings")) ((name . "wcsncat_s") (path . "string/wide/wcsncat") (type . "Strings")) ((name . "wcsncmp") (path . "string/wide/wcsncmp") (type . "Strings")) ((name . "wcsncpy") (path . "string/wide/wcsncpy") (type . "Strings")) ((name . "wcsncpy_s") (path . "string/wide/wcsncpy") (type . "Strings")) ((name . "wcsnlen_s") (path . "string/wide/wcslen") (type . "Strings")) ((name . "wcspbrk") (path . "string/wide/wcspbrk") (type . "Strings")) ((name . "wcsrchr") (path . "string/wide/wcsrchr") (type . "Strings")) ((name . "wcsrtombs") (path . "string/multibyte/wcsrtombs") (type . "Strings")) ((name . "wcsrtombs_s") (path . "string/multibyte/wcsrtombs") (type . "Strings")) ((name . "wcsspn") (path . "string/wide/wcsspn") (type . "Strings")) ((name . "wcsstr") (path . "string/wide/wcsstr") (type . "Strings")) ((name . "wcstod") (path . "string/wide/wcstof") (type . "Strings")) ((name . "wcstof") (path . "string/wide/wcstof") (type . "Strings")) ((name . "wcstoimax") (path . "string/wide/wcstoimax") (type . "Strings")) ((name . "wcstok") (path . "string/wide/wcstok") (type . "Strings")) ((name . "wcstok_s") (path . "string/wide/wcstok") (type . "Strings")) ((name . "wcstol") (path . "string/wide/wcstol") (type . "Strings")) ((name . "wcstold") (path . "string/wide/wcstof") (type . "Strings")) ((name . "wcstoll") (path . "string/wide/wcstol") (type . "Strings")) ((name . "wcstombs") (path . "string/multibyte/wcstombs") (type . "Strings")) ((name . "wcstombs_s") (path . "string/multibyte/wcstombs") (type . "Strings")) ((name . "wcstoul") (path . "string/wide/wcstoul") (type . "Strings")) ((name . "wcstoull") (path . "string/wide/wcstoul") (type . "Strings")) ((name . "wcstoumax") (path . "string/wide/wcstoimax") (type . "Strings")) ((name . "wcsxfrm") (path . "string/wide/wcsxfrm") (type . "Strings")) ((name . "wctob") (path . "string/multibyte/wctob") (type . "Strings")) ((name . "wctomb") (path . "string/multibyte/wctomb") (type . "Strings")) ((name . "wctomb_s") (path . "string/multibyte/wctomb") (type . "Strings")) ((name . "wctrans") (path . "string/wide/wctrans") (type . "Strings")) ((name . "wctype") (path . "string/wide/wctype") (type . "Strings")) ((name . "while") (path . "keyword/while") (type . "C keywords")) ((name . "while loop") (path . "language/while") (type . "C language")) ((name . "wmemchr") (path . "string/wide/wmemchr") (type . "Strings")) ((name . "wmemcmp") (path . "string/wide/wmemcmp") (type . "Strings")) ((name . "wmemcpy") (path . "string/wide/wmemcpy") (type . "Strings")) ((name . "wmemcpy_s") (path . "string/wide/wmemcpy") (type . "Strings")) ((name . "wmemmove") (path . "string/wide/wmemmove") (type . "Strings")) ((name . "wmemmove_s") (path . "string/wide/wmemmove") (type . "Strings")) ((name . "wmemset") (path . "string/wide/wmemset") (type . "Strings")) ((name . "wprintf") (path . "io/fwprintf") (type . "File input/output")) ((name . "wprintf_s") (path . "io/fwprintf") (type . "File input/output")) ((name . "wscanf") (path . "io/fwscanf") (type . "File input/output")) ((name . "wscanf_s") (path . "io/fwscanf") (type . "File input/output"))]) (types . [((name . "Algorithms") (count . 5) (slug . "algorithms")) ((name . "Atomic operations") (count . 1) (slug . "atomic-operations")) ((name . "C keywords") (count . 60) (slug . "c-keywords")) ((name . "C language") (count . 121) (slug . "c-language")) ((name . "Concurrency support") (count . 72) (slug . "concurrency-support")) ((name . "Date and time") (count . 24) (slug . "date-and-time")) ((name . "Dynamic memory management") (count . 8) (slug . "dynamic-memory-management")) ((name . "Error handling") (count . 9) (slug . "error-handling")) ((name . "File input/output") (count . 107) (slug . "file-input-output")) ((name . "Localization support") (count . 10) (slug . "localization-support")) ((name . "Numerics") (count . 331) (slug . "numerics")) ((name . "Program support") (count . 28) (slug . "program-support")) ((name . "Strings") (count . 156) (slug . "strings")) ((name . "Type support") (count . 11) (slug . "type-support")) ((name . "Variadic functions") (count . 6) (slug . "variadic-functions")) ((name . "Versions") (count . 6) (slug . "versions"))])) \ No newline at end of file diff --git a/devdocs/c/index.html b/devdocs/c/index.html new file mode 100644 index 00000000..9e6f2236 --- /dev/null +++ b/devdocs/c/index.html @@ -0,0 +1,50 @@ +

C Programming Language

The interface of C standard library is defined by the following collection of headers.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
<assert.h> Conditionally compiled macro that compares its argument to zero
<complex.h> (since C99) Complex number arithmetic
<ctype.h> Functions to determine the type contained in character data
<errno.h> Macros reporting error conditions
<fenv.h> (since C99) Floating-point environment
<float.h> Limits of floating-point types
<inttypes.h> (since C99) Format conversion of integer types
<iso646.h> (since C95) Alternative operator spellings
<limits.h> Ranges of integer types
<locale.h> Localization utilities
<math.h> Common mathematics functions
<setjmp.h> Nonlocal jumps
<signal.h> Signal handling
<stdalign.h> (since C11) alignas and alignof convenience macros
<stdarg.h> Variable arguments
<stdatomic.h> (since C11) Atomic operations
<stdbit.h> (since C23) Macros to work with the byte and bit representations of types
<stdbool.h> (since C99) Macros for boolean type
<stdckdint.h> (since C23) macros for performing checked integer arithmetic
<stddef.h> Common macro definitions
<stdint.h> (since C99) Fixed-width integer types
<stdio.h> Input/output
<stdlib.h> General utilities: memory management, program utilities, string conversions, random numbers, algorithms
<stdnoreturn.h> (since C11) noreturn convenience macro
<string.h> String handling
<tgmath.h> (since C99) Type-generic math (macros wrapping math.h and complex.h)
<threads.h> (since C11) Thread library
<time.h> Time/date utilities
<uchar.h> (since C11) UTF-16 and UTF-32 character utilities
<wchar.h> (since C95) Extended multibyte and wide character utilities
<wctype.h> (since C95) Functions to determine the type contained in wide character data

References

See also

+
C++ documentation for C++ Standard Library header files
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/header +

+
diff --git a/devdocs/c/io%2Fclearerr.html b/devdocs/c/io%2Fclearerr.html new file mode 100644 index 00000000..0b82bfed --- /dev/null +++ b/devdocs/c/io%2Fclearerr.html @@ -0,0 +1,45 @@ +

clearerr

Defined in header <stdio.h> 
void clearerr( FILE *stream );
+

Resets the error flags and the EOF indicator for the given file stream.

+

Parameters

+ +
stream - the file to reset the error flags for

Return value

(none)

+

Example

#include <stdio.h>
+#include <assert.h>
+ 
+int main(void)
+{
+    FILE* tmpf = tmpfile();
+    fputs("cppreference.com\n", tmpf);
+    rewind(tmpf);
+ 
+    for (int ch; (ch = fgetc(tmpf)) != EOF; putchar(ch)) { }
+ 
+    assert(feof(tmpf)); // the loop is expected to terminate by EOF
+    puts("End of file reached");
+ 
+    clearerr(tmpf); // clear EOF
+ 
+    puts(feof(tmpf) ? "EOF indicator set" 
+                    : "EOF indicator cleared");
+}

Output:

+
cppreference.com
+End of file reached
+EOF indicator cleared

References

See also

+ + + +
checks for the end-of-file
(function)
displays a character string corresponding of the current error to stderr
(function)
checks for a file error
(function)
C++ documentation for clearerr
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/clearerr +

+
diff --git a/devdocs/c/io%2Ffclose.html b/devdocs/c/io%2Ffclose.html new file mode 100644 index 00000000..2c80600a --- /dev/null +++ b/devdocs/c/io%2Ffclose.html @@ -0,0 +1,57 @@ +

fclose

Defined in header <stdio.h> 
int fclose( FILE *stream );
+

Closes the given file stream. Any unwritten buffered data are flushed to the OS. Any unread buffered data are discarded.

+

Whether or not the operation succeeds, the stream is no longer associated with a file, and the buffer allocated by setbuf or setvbuf, if any, is also disassociated and deallocated if automatic allocation was used.

+

The behavior is undefined if the value of the pointer stream is used after fclose returns.

+

Parameters

+ +
stream - the file stream to close

Return value

​0​ on success, EOF otherwise

+

Example

#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    const char* fname = "/tmp/unique_name.txt"; // or tmpnam(NULL);
+    int is_ok = EXIT_FAILURE;
+ 
+    FILE* fp = fopen(fname, "w+");
+    if (!fp) {
+        perror("File opening failed");
+        return is_ok;
+    }
+    fputs("Hello, world!\n", fp);
+    rewind(fp);
+ 
+    int c; // note: int, not char, required to handle EOF
+    while ((c = fgetc(fp)) != EOF) // standard C I/O file reading loop
+        putchar(c);
+ 
+    if (ferror(fp))
+        puts("I/O error when reading");
+    else if (feof(fp)) {
+        puts("End of file is reached successfully");
+        is_ok = EXIT_SUCCESS;
+    }
+ 
+    fclose(fp);
+    remove(fname);
+    return is_ok;
+}

Possible output:

+
Hello, world!
+End of file is reached successfully

References

See also

+ + +
+
(C11)
 opens a file
(function)
+
(C11)
 open an existing stream with a different name
(function)
C++ documentation for fclose
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/fclose +

+
diff --git a/devdocs/c/io%2Ffeof.html b/devdocs/c/io%2Ffeof.html new file mode 100644 index 00000000..088f217b --- /dev/null +++ b/devdocs/c/io%2Ffeof.html @@ -0,0 +1,56 @@ +

feof

Defined in header <stdio.h> 
int feof( FILE *stream );
+

Checks if the end of the given file stream has been reached.

+

Parameters

+ +
stream - the file stream to check

Return value

nonzero value if the end of the stream has been reached, otherwise ​0​

+

Notes

This function only reports the stream state as reported by the most recent I/O operation, it does not examine the associated data source. For example, if the most recent I/O was a fgetc, which returned the last byte of a file, feof returns zero. The next fgetc fails and changes the stream state to end-of-file. Only then feof returns non-zero.

+

In typical usage, input stream processing stops on any error; feof and ferror are then used to distinguish between different error conditions.

+

Example

#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    const char* fname = "/tmp/unique_name.txt"; // or tmpnam(NULL);
+    int is_ok = EXIT_FAILURE;
+ 
+    FILE* fp = fopen(fname, "w+");
+    if (!fp) {
+        perror("File opening failed");
+        return is_ok;
+    }
+    fputs("Hello, world!\n", fp);
+    rewind(fp);
+ 
+    int c; // note: int, not char, required to handle EOF
+    while ((c = fgetc(fp)) != EOF) // standard C I/O file reading loop
+        putchar(c);
+ 
+    if (ferror(fp))
+        puts("I/O error when reading");
+    else if (feof(fp)) {
+        puts("End of file is reached successfully");
+        is_ok = EXIT_SUCCESS;
+    }
+ 
+    fclose(fp);
+    remove(fname);
+    return is_ok;
+}

Possible output:

+
Hello, world!
+End of file is reached successfully

References

See also

+ + + +
clears errors
(function)
displays a character string corresponding of the current error to stderr
(function)
checks for a file error
(function)
C++ documentation for feof
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/feof +

+
diff --git a/devdocs/c/io%2Fferror.html b/devdocs/c/io%2Fferror.html new file mode 100644 index 00000000..4742b467 --- /dev/null +++ b/devdocs/c/io%2Fferror.html @@ -0,0 +1,44 @@ +

ferror

Defined in header <stdio.h> 
int ferror( FILE *stream );
+

Checks the given stream for errors.

+

Parameters

+ +
stream - the file stream to check

Return value

Nonzero value if the file stream has errors occurred, ​0​ otherwise

+

Example

#include <stdio.h>
+#include <stdlib.h>
+#include <locale.h>
+#include <wchar.h>
+ 
+int main(void)
+{
+    char* fname = tmpnam(NULL);
+    FILE* f = fopen(fname, "wb");
+    fputs("\xff\xff\n", f); // not a valid UTF-8 character sequence
+    fclose(f);
+ 
+    setlocale(LC_ALL, "en_US.utf8");
+    f = fopen(fname, "rb");
+    wint_t ch;
+    while ((ch=fgetwc(f)) != WEOF) // attempt to read as UTF-8 fails
+          printf("%#x ", ch);
+ 
+    if (feof(f))
+        puts("EOF indicator set");
+    if (ferror(f))
+        puts("Error indicator set");
+}

Output:

+
Error indicator set

References

See also

+ + +
clears errors
(function)
checks for the end-of-file
(function)
C++ documentation for ferror
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/ferror +

+
diff --git a/devdocs/c/io%2Ffflush.html b/devdocs/c/io%2Ffflush.html new file mode 100644 index 00000000..b3ba8716 --- /dev/null +++ b/devdocs/c/io%2Ffflush.html @@ -0,0 +1,26 @@ +

fflush

Defined in header <stdio.h> 
int fflush( FILE *stream );
+

For output streams (and for update streams on which the last operation was output), writes any unwritten data from the stream's buffer to the associated output device.

+

For input streams (and for update streams on which the last operation was input), the behavior is undefined.

+

If stream is a null pointer, all open output streams are flushed, including the ones manipulated within library packages or otherwise not directly accessible to the program.

+

Parameters

+ +
stream - the file stream to write out

Return value

Returns zero on success. Otherwise EOF is returned and the error indicator of the file stream is set.

+

Notes

POSIX extends the specification of fflush by defining its effects on an input stream, as long as that stream represents a file or another seekable device: in that case the POSIX file pointer is repositioned to match the C stream pointer (which effectively undoes any read buffering) and the effects of any ungetc or ungetwc that weren't yet read back from the stream are discarded.

+

Microsoft also extends the specification of fflush by defining its effects on an input stream: in Visual Studio 2013 and prior, it discarded the input buffer, in Visual Studio 2015 and newer, it has no effect, buffers are retained.

+

References

See also

+ + +
+
(C11)
 opens a file
(function)
closes a file
(function)
C++ documentation for fflush
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/fflush +

+
diff --git a/devdocs/c/io%2Ffgetc.html b/devdocs/c/io%2Ffgetc.html new file mode 100644 index 00000000..0f73cb25 --- /dev/null +++ b/devdocs/c/io%2Ffgetc.html @@ -0,0 +1,73 @@ +

fgetc, getc

Defined in header <stdio.h> 
int fgetc( FILE *stream );
+		 (1) 
int getc( FILE *stream );
+		 (2)
+1) Reads the next character from the given input stream.
+2) Same as fgetc, except that if getc is implemented as a macro, it may evaluate stream more than once, so the corresponding argument should never be an expression with side effects.

Parameters

+ +
stream - to read the character from

Return value

On success, returns the obtained character as an unsigned char converted to an int. On failure, returns EOF.

+

If the failure has been caused by end-of-file condition, additionally sets the eof indicator (see feof()) on stream. If the failure has been caused by some other error, sets the error indicator (see ferror()) on stream.

+

Example

#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    const char* fname = "/tmp/unique_name.txt"; // or tmpnam(NULL);
+    int is_ok = EXIT_FAILURE;
+ 
+    FILE* fp = fopen(fname, "w+");
+    if (!fp) {
+        perror("File opening failed");
+        return is_ok;
+    }
+    fputs("Hello, world!\n", fp);
+    rewind(fp);
+ 
+    int c; // note: int, not char, required to handle EOF
+    while ((c = fgetc(fp)) != EOF) // standard C I/O file reading loop
+        putchar(c);
+ 
+    if (ferror(fp))
+        puts("I/O error when reading");
+    else if (feof(fp)) {
+        puts("End of file is reached successfully");
+        is_ok = EXIT_SUCCESS;
+    }
+ 
+    fclose(fp);
+    remove(fname);
+    return is_ok;
+}

Possible output:

+
Hello, world!
+End of file is reached successfully

References

See also

+ + + + +
reads a character from stdin
(function)
+
(removed in C11)(C11)
 reads a character string from stdin
(function)
writes a character to a file stream
(function)
puts a character back into a file stream
(function)
C++ documentation for fgetc, getc
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/fgetc +

+
diff --git a/devdocs/c/io%2Ffgetpos.html b/devdocs/c/io%2Ffgetpos.html new file mode 100644 index 00000000..4a403e25 --- /dev/null +++ b/devdocs/c/io%2Ffgetpos.html @@ -0,0 +1,58 @@ +

fgetpos

Defined in header <stdio.h> 
int fgetpos( FILE          *stream, fpos_t          *pos );
+		 (until C99) 
int fgetpos( FILE *restrict stream, fpos_t *restrict pos );
+		 (since C99)

Obtains the file position indicator and the current parse state (if any) for the file stream stream and stores them in the object pointed to by pos. The value stored is only meaningful as the input to fsetpos.

+

Parameters

+ + +
stream - file stream to examine
pos - pointer to a fpos_t object to store the file position indicator to

Return value

​0​ upon success, nonzero value otherwise.

+

Example

#include <stdio.h>
+#include <stdlib.h>
+#include <assert.h>
+ 
+int main(void)
+{
+    // prepare a file holding 4 values of type double
+    enum {SIZE = 4};
+    FILE* fp = fopen("test.bin", "wb");
+    assert(fp);
+    int rc = fwrite((double[SIZE]){1.1, 2.2, 3.3, 4.4}, sizeof(double), SIZE, fp);
+    assert(rc == SIZE);
+    fclose(fp);
+ 
+    // demo using fsetpos to return to the beginning of a file
+    fp = fopen("test.bin", "rb");
+    fpos_t pos;
+    fgetpos(fp, &pos);               // store start of file in pos
+    double d;
+    rc = fread(&d, sizeof d, 1, fp); // read the first double
+    assert(rc == 1);
+    printf("First value in the file: %.1f\n", d);
+    fsetpos(fp,&pos);                 // move file position back to the start of the file
+    rc = fread(&d, sizeof d, 1, fp);  // read the first double again
+    assert(rc == 1);
+    printf("First value in the file again: %.1f\n", d);
+    fclose(fp);
+ 
+    // demo error handling
+    rc = fsetpos(stdin, &pos);
+    if(rc) perror("could not fsetpos stdin");
+}

Output:

+
First value in the file: 1.1
+First value in the file again: 1.1
+could not fsetpos stdin: Illegal seek

References

See also

+ + + +
returns the current file position indicator
(function)
moves the file position indicator to a specific location in a file
(function)
moves the file position indicator to a specific location in a file
(function)
C++ documentation for fgetpos
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/fgetpos +

+
diff --git a/devdocs/c/io%2Ffgets.html b/devdocs/c/io%2Ffgets.html new file mode 100644 index 00000000..c6178a7d --- /dev/null +++ b/devdocs/c/io%2Ffgets.html @@ -0,0 +1,71 @@ +

fgets

Defined in header <stdio.h> 
char *fgets( char          *str, int count, FILE          *stream );
+		 (until C99) 
char *fgets( char *restrict str, int count, FILE *restrict stream );
+		 (since C99)

Reads at most count - 1 characters from the given file stream and stores them in the character array pointed to by str. Parsing stops if a newline character is found, in which case str will contain that newline character, or if end-of-file occurs. If bytes are read and no errors occur, writes a null character at the position immediately after the last character written to str.

+

Parameters

+ + + +
str - pointer to an element of a char array
count - maximum number of characters to write (typically the length of str)
stream - file stream to read the data from

Return value

str on success, null pointer on failure.

+

If the end-of-file condition is encountered, sets the eof indicator on stream (see feof()). This is only a failure if it causes no bytes to be read, in which case a null pointer is returned and the contents of the array pointed to by str are not altered (i.e. the first byte is not overwritten with a null character).

+

If the failure has been caused by some other error, sets the error indicator (see ferror()) on stream. The contents of the array pointed to by str are indeterminate (it may not even be null-terminated).

+

Notes

POSIX additionally requires that fgets sets errno if a read error occurs.

+

Although the standard specification is unclear in the cases where count<=1, common implementations do

+

Example

#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    FILE* tmpf = tmpfile();
+    fputs("Alan Turing\n", tmpf);
+    fputs("John von Neumann\n", tmpf);
+    fputs("Alonzo Church\n", tmpf);
+ 
+    rewind(tmpf);
+ 
+    char buf[8];
+    while (fgets(buf, sizeof buf, tmpf) != NULL)
+          printf("\"%s\"\n", buf);
+ 
+    if (feof(tmpf))
+       puts("End of file reached");
+}

Output:

+
"Alan Tu"
+"ring
+"
+"John vo"
+"n Neuma"
+"nn
+"
+"Alonzo "
+"Church
+"
+End of file reached

References

See also

+ + + + +
+
(C11)(C11)(C11)
 reads formatted input from stdin, a file stream or a buffer
(function)
+
(removed in C11)(C11)
 reads a character string from stdin
(function)
writes a character string to a file stream
(function)
+
(dynamic memory TR)
 read from a stream into an automatically resized buffer until delimiter/end of line
(function)
C++ documentation for fgets
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/fgets +

+
diff --git a/devdocs/c/io%2Ffgetwc.html b/devdocs/c/io%2Ffgetwc.html new file mode 100644 index 00000000..c17f187d --- /dev/null +++ b/devdocs/c/io%2Ffgetwc.html @@ -0,0 +1,75 @@ +

fgetwc, getwc

Defined in header <wchar.h> 
wint_t fgetwc( FILE *stream );
+		 (since C95) 
wint_t getwc( FILE *stream );
+		 (since C95)

Reads the next wide character from the given input stream. getwc() may be implemented as a macro and may evaluate stream more than once.

+

Parameters

+ +
stream - to read the wide character from

Return value

The next wide character from the stream or WEOF on failure.

+

If the failure has been caused by end-of-file condition, additionally sets the eof indicator (see feof()) on stream. If the failure has been caused by some other error, sets the error indicator (see ferror()) on stream.

+

If an encoding error occurred, additionally sets errno to EILSEQ.

+

Example

#include <stdio.h>
+#include <stdlib.h>
+#include <wchar.h>
+#include <errno.h>
+#include <locale.h>
+ 
+int main(void)
+{
+    setlocale(LC_ALL, "en_US.utf8");
+    FILE *fp = fopen("fgetwc.dat", "w");
+    if(!fp) {
+        perror("Can't open file for writing");
+        return EXIT_FAILURE;
+    }
+    fputs("кошка\n", fp);
+    fclose(fp);
+ 
+    fp = fopen("fgetwc.dat", "r");
+    if(!fp) {
+        perror("Can't open file for reading");
+        return EXIT_FAILURE;
+    }
+    wint_t wc;
+    errno = 0;
+    while ((wc = fgetwc(fp)) != WEOF)
+        putwchar(wc);
+ 
+    if (ferror(fp)) {
+        if (errno == EILSEQ)
+            puts("Character encoding error while reading.");
+        else
+            puts("I/O error when reading");
+    } else if (feof(fp))
+        puts("End of file reached successfully");
+ 
+    fclose(fp);
+}

Output:

+
кошка

References

See also

+ + + + +
gets a character from a file stream
(function)
+
(C95)
 gets a wide string from a file stream
(function)
+
(C95)
 writes a wide character to a file stream
(function)
+
(C95)
 puts a wide character back into a file stream
(function)
C++ documentation for fgetwc
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/fgetwc +

+
diff --git a/devdocs/c/io%2Ffgetws.html b/devdocs/c/io%2Ffgetws.html new file mode 100644 index 00000000..acd7f5bb --- /dev/null +++ b/devdocs/c/io%2Ffgetws.html @@ -0,0 +1,32 @@ +

fgetws

Defined in header <wchar.h> 
wchar_t* fgetws( wchar_t* str, int count, FILE* stream );
+		 (since C95)
(until C99) 
wchar_t* fgetws( wchar_t* restrict str, int count, FILE* restrict stream );
+		 (since C99)

Reads at most count - 1 wide characters from the given file stream and stores them in str. The produced wide string is always null-terminated. Parsing stops if end-of-file occurs or a newline wide character is found, in which case str will contain that wide newline character.

+

Parameters

+ + + +
str - wide string to read the characters to
count - the length of str
stream - file stream to read the data from

Return value

str on success, a null pointer on an error

+

Example

References

See also

+ + + + +
+
(C95)(C95)(C95)(C11)(C11)(C11)
 reads formatted wide character input from stdin, a file stream or a buffer
(function)
+
(C95)
 gets a wide character from a file stream
(function)
+
(C95)
 writes a wide string to a file stream
(function)
+
(dynamic memory TR)
 read from a stream into an automatically resized buffer until delimiter/end of line
(function)
C++ documentation for fgetws
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/fgetws +

+
diff --git a/devdocs/c/io%2Ffile.html b/devdocs/c/io%2Ffile.html new file mode 100644 index 00000000..2f7b23df --- /dev/null +++ b/devdocs/c/io%2Ffile.html @@ -0,0 +1,53 @@ +

FILE

Defined in header <stdio.h> 
typedef /* unspecified */ FILE;
+

Each FILE object denotes a C stream.

+

C standard does not specify whether FILE is a complete object type. While it may be possible to copy a valid FILE, using a pointer to such a copy as an argument for an I/O function invokes unspecified behavior. In other words, FILE may be semantically non-copyable.

+

I/O streams can be used for both unformatted and formatted input and output. Furthermore, the functions that handle input and output can also be locale-sensitive, such that wide/multibyte conversions are performed as necessary.

+

Stream state

Besides the system-specific information necessary to access the device (e.g., a POSIX file descriptor), each FILE object directly or indirectly holds the following:

+
    +
  1. (C95) Character width: unset, narrow, or wide.
    2. +
  2. (C95) Parse state for conversions between multibyte and wide characters (an object of type mbstate_t)
    3. +
  3. Buffering state: unbuffered, line-buffered, fully buffered.
    4. +
  4. The buffer, which may be replaced by an external, user-provided buffer.
    5. +
  5. I/O mode: input, output, or update (both input and output).
    6. +
  6. Binary/text mode indicator.
    7. +
  7. End-of-file status indicator.
    8. +
  8. Error status indicator.
    9. +
  9. File position indicator, accessible as an object of type fpos_t, which, for wide streams, includes parse state.
    10. +
  10. (C11) Reentrant lock used to prevent data races when multiple threads read, write, position, or query the position of a stream.
    11. +

Narrow and wide orientation

A newly opened stream has no orientation. The first call to fwide or to any I/O function establishes the orientation: a wide I/O function makes the stream wide-oriented; a narrow I/O function makes the stream narrow-oriented. Once set, the orientation can be changed with only freopen. Narrow I/O functions cannot be called on a wide-oriented stream; wide I/O functions cannot be called on a narrow-oriented stream. Wide I/O functions convert between wide and multibyte characters as if by calling mbrtowc or wcrtomb with the conversion state as described by the stream. Unlike the multibyte character strings that are valid in a program, multibyte character sequences in the file may contain embedded nulls and do not have to begin or end in the initial shift state.

+

The conversion state of a stream with wide orientation is established by the C locale that is installed at the time the stream's orientation is set.

+

Binary and text modes

A text stream is an ordered sequence of characters that can be composed into lines; a line can be decomposed into zero or more characters plus a terminating '\n' (“newline”) character. Whether the last line requires a terminating '\n' is implementation-defined. Furthermore, characters may have to be added, altered, or deleted on input and output to conform to the conventions for representing text in the OS (in particular, C streams on Windows OS convert '\n' to '\r\n' on output, and convert '\r\n' to '\n' on input).

+

Data read in from a text stream is guaranteed to compare equal to the data that were earlier written out to that stream only if each of the following is true:

+

A binary stream is an ordered sequence of characters that can transparently record internal data. Data read in from a binary stream always equal the data that were earlier written out to that stream, except that an implementation is allowed to append an indeterminate number of null characters to the end of the stream. A wide binary stream doesn't need to end in the initial shift state.

+

Notes

POSIX explicitly requires that the LC_CTYPE facet of the currently installed C locale be stored within the FILE object the moment the stream's orientation becomes wide; POSIX requires that this LC_CTYPE facet be used for all future I/O on this stream until the orientation is changed, regardless of any subsequent call to setlocale.

+

It is intended that each line of text be composed of data that are essentially human-readable. POSIX implementations do not distinguish between text and binary streams (there is no special mapping for '\n' or any other characters).

+

References

See also

+ +
expression of type FILE* associated with the input stream
expression of type FILE* associated with the output stream
expression of type FILE* associated with the error output stream
(macro constant)
C++ documentation for FILE
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/FILE +

+
diff --git a/devdocs/c/io%2Ffopen.html b/devdocs/c/io%2Ffopen.html new file mode 100644 index 00000000..802ab3fc --- /dev/null +++ b/devdocs/c/io%2Ffopen.html @@ -0,0 +1,89 @@ +

fopen, fopen_s

Defined in header <stdio.h>
(1) 
FILE *fopen( const char *filename, const char *mode );
+		 (until C99) 
FILE *fopen( const char *restrict filename, const char *restrict mode );
+		 (since C99) 
errno_t fopen_s( FILE *restrict *restrict streamptr,
+                 const char *restrict filename,
+                 const char *restrict mode );
+		 (2) (since C11)
+1) Opens a file indicated by filename and returns a pointer to the file stream associated with that file. mode is used to determine the file access mode.
+2) Same as (1), except that the pointer to the file stream is written to streamptr and the following errors are detected at runtime and call the currently installed constraint handler function: As with all bounds-checked functions, fopen_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <stdio.h>.

Parameters

+ + + +
filename - file name to associate the file stream to
mode - null-terminated character string determining file access mode
streamptr - pointer to a pointer where the function stores the result (an out-parameter)

File access flags

+ + + + + + + + + + + + +
File access
mode string 		Meaning Explanation Action if file
already exists 		Action if file
does not exist
"r" read Open a file for reading read from start failure to open
"w" write Create a file for writing destroy contents create new
"a" append Append to a file write to end create new
"r+" read extended Open a file for read/write read from start error
"w+" write extended Create a file for read/write destroy contents create new
"a+" append extended Open a file for read/write write to end create new
File access mode flag "b" can optionally be specified to open a file in binary mode. This flag has no effect on POSIX systems, but on Windows it disables special handling of '\n' and '\x1A'.
On the append file access modes, data is written to the end of the file regardless of the current position of the file position indicator.
The behavior is undefined if the mode is not one of the strings listed above. Some implementations define additional supported modes (e.g. Windows).
In update mode ('+'), both input and output may be performed, but output cannot be followed by input without an intervening call to fflush, fseek, fsetpos or rewind, and input cannot be followed by output without an intervening call to fseek, fsetpos or rewind, unless the input operation encountered end of file. In update mode, implementations are permitted to use binary mode even when text mode is specified.
File access mode flag "x" can optionally be appended to "w" or "w+" specifiers. This flag forces the function to fail if the file exists, instead of overwriting it. (C11)
When using fopen_s or freopen_s, file access permissions for any file created with "w" or "a" prevents other users from accessing it. File access mode flag "u" can optionally be prepended to any specifier that begins with "w" or "a", to enable the default fopen permissions. (C11)

Return value

+1) If successful, returns a pointer to the new file stream. The stream is fully buffered unless filename refers to an interactive device. On error, returns a null pointer. POSIX requires that errno be set in this case.
+2) If successful, returns zero and a pointer to the new file stream is written to *streamptr. On error, returns a non-zero error code and writes the null pointer to *streamptr (unless streamptr is a null pointer itself).

Notes

The format of filename is implementation-defined, and does not necessarily refer to a file (e.g. it may be the console or another device accessible though filesystem API). On platforms that support them, filename may include absolute or relative filesystem path.

+

Example

#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    const char* fname = "/tmp/unique_name.txt"; // or tmpnam(NULL);
+    int is_ok = EXIT_FAILURE;
+ 
+    FILE* fp = fopen(fname, "w+");
+    if (!fp) {
+        perror("File opening failed");
+        return is_ok;
+    }
+    fputs("Hello, world!\n", fp);
+    rewind(fp);
+ 
+    int c; // note: int, not char, required to handle EOF
+    while ((c = fgetc(fp)) != EOF) // standard C I/O file reading loop
+        putchar(c);
+ 
+    if (ferror(fp))
+        puts("I/O error when reading");
+    else if (feof(fp)) {
+        puts("End of file is reached successfully");
+        is_ok = EXIT_SUCCESS;
+    }
+ 
+    fclose(fp);
+    remove(fname);
+    return is_ok;
+}

Possible output:

+
Hello, world!
+End of file is reached successfully

References

See also

+ + + +
closes a file
(function)
synchronizes an output stream with the actual file
(function)
+
(C11)
 open an existing stream with a different name
(function)
C++ documentation for fopen
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/fopen +

+
diff --git a/devdocs/c/io%2Ffpos_t.html b/devdocs/c/io%2Ffpos_t.html new file mode 100644 index 00000000..7bbe71bb --- /dev/null +++ b/devdocs/c/io%2Ffpos_t.html @@ -0,0 +1,37 @@ +

fpos_t

Defined in header <stdio.h> 
typedef /* implementation-defined */ fpos_t;
+

fpos_t is a non-array complete object type, can be used to store (by fgetpos) and restore (by fsetpos) the position and multibyte parser state (if any) for a C stream.

+ + +

The multibyte parser state of a wide-oriented C stream is represented by a mbstate_t object, whose value is stored as part of the value of a fpos_t object by fgetpos.

+		 (since C95)

References

See also

+ + + +
gets the file position indicator
(function)
moves the file position indicator to a specific location in a file
(function)
+
(C95)
 conversion state information necessary to iterate multibyte character strings
(class)
C++ documentation for fpos_t
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/fpos_t +

+
diff --git a/devdocs/c/io%2Ffprintf.html b/devdocs/c/io%2Ffprintf.html new file mode 100644 index 00000000..c0309821 --- /dev/null +++ b/devdocs/c/io%2Ffprintf.html @@ -0,0 +1,278 @@ +

printf, fprintf, sprintf, snprintf, printf_s, fprintf_s, sprintf_s, snprintf_s

Defined in header <stdio.h>
(1) 
int printf( const char          *format, ... );
+		 (until C99) 
int printf( const char *restrict format, ... );
+		 (since C99)
(2) 
int fprintf( FILE          *stream, const char          *format, ... );
+		 (until C99) 
int fprintf( FILE *restrict stream, const char *restrict format, ... );
+		 (since C99)
(3) 
int sprintf( char          *buffer, const char          *format, ... );
+		 (until C99) 
int sprintf( char *restrict buffer, const char *restrict format, ... );
+		 (since C99) 
int snprintf( char *restrict buffer, size_t bufsz, 
+              const char *restrict format, ... );
+		 (4) (since C99) 
int printf_s( const char *restrict format, ... );
+		 (5) (since C11) 
int fprintf_s( FILE *restrict stream, const char *restrict format, ... );
+		 (6) (since C11) 
int sprintf_s( char *restrict buffer, rsize_t bufsz,
+               const char *restrict format, ... );
+		 (7) (since C11) 
int snprintf_s( char *restrict buffer, rsize_t bufsz,
+                const char *restrict format, ... );
+		 (8) (since C11)

Loads the data from the given locations, converts them to character string equivalents and writes the results to a variety of sinks/streams:

+
+1) Writes the results to the output stream stdout.
+2) Writes the results to the output stream stream.
+3) Writes the results to a character string buffer. The behavior is undefined if the string to be written (plus the terminating null character) exceeds the size of the array pointed to by buffer.
+4) Writes the results to a character string buffer. At most bufsz - 1 characters are written. The resulting character string will be terminated with a null character, unless bufsz is zero. If bufsz is zero, nothing is written and buffer may be a null pointer, however the return value (number of bytes that would be written not including the null terminator) is still calculated and returned.
+5-8) Same as (1-4), except that the following errors are detected at runtime and call the currently installed constraint handler function:
+
+
    +
  • the conversion specifier %n is present in format
    • +
  • any of the arguments corresponding to %s is a null pointer
    • +
  • stream or format or buffer is a null pointer
    • +
  • bufsz is zero or greater than RSIZE_MAX
    • +
  • encoding errors occur in any of string and character conversion specifiers
    • +
  • (for sprintf_s only), the string to be stored in buffer (including the trailing null) would exceed bufsz
    • +
+
As with all bounds-checked functions, printf_s , fprintf_s, sprintf_s, and snprintf_s are only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <stdio.h>.
+
+

Parameters

+ + + + + +
stream - output file stream to write to
buffer - pointer to a character string to write to
bufsz - up to bufsz - 1 characters may be written, plus the null terminator
format - pointer to a null-terminated byte string specifying how to interpret the data
... - arguments specifying data to print. If any argument after default argument promotions is not the type expected by the corresponding conversion specifier, or if there are fewer arguments than required by format, the behavior is undefined. If there are more arguments than required by format, the extraneous arguments are evaluated and ignored.


The format string consists of ordinary byte characters (except %), which are copied unchanged into the output stream, and conversion specifications. Each conversion specification has the following format:

+

The following format specifiers are available:

+ + + + + + + + + + + + + + + + +
Conversion
Specifier 		Explanation Expected
Argument Type
+Length
Modifier→ 		+hh

(C99)

+		 +h (none) +l +ll

(C99)

+		 +j

(C99)

+		 +z

(C99)

+		 +t

(C99)

+		 +L
+% Writes literal %. The full conversion specification must be %%. N/A N/A N/A N/A N/A N/A N/A N/A N/A
+c Writes a single character.

The argument is first converted to unsigned char. If the l modifier is used, the argument is first converted to a character string as if by %ls with a wchar_t[2] argument.

+		 N/A N/A +
int
 +
wint_t
 N/A N/A N/A N/A N/A
+s Writes a character string

The argument must be a pointer to the initial element of an array of characters. Precision specifies the maximum number of bytes to be written. If Precision is not specified, writes every byte up to and not including the first null terminator. If the l specifier is used, the argument must be a pointer to the initial element of an array of wchar_t, which is converted to char array as if by a call to wcrtomb with zero-initialized conversion state.

+		 N/A N/A +
char*
 +
wchar_t*
 N/A N/A N/A N/A N/A
+d
i 		Converts a signed integer into decimal representation [-]dddd.

Precision specifies the minimum number of digits to appear. The default precision is 1.

If both the converted value and the precision are ​0​ the conversion results in no characters.

+		 +
signed char
 +
short
 +
int
 +
long
 +
long long
 + +
signed size_t +
 + N/A
+o Converts an unsigned integer into octal representation oooo.

Precision specifies the minimum number of digits to appear. The default precision is 1. If both the converted value and the precision are ​0​ the conversion results in no characters. In the alternative implementation precision is increased if necessary, to write one leading zero. In that case if both the converted value and the precision are ​0​, single ​0​ is written.

+		 +
unsigned char
 +
unsigned short
 +
unsigned int
 +
unsigned long
 +
unsigned long long
 + + +
unsigned version of ptrdiff_t +
 N/A
+x
X 		Converts an unsigned integer into hexadecimal representation hhhh.

For the x conversion letters abcdef are used.
For the X conversion letters ABCDEF are used.
Precision specifies the minimum number of digits to appear. The default precision is 1. If both the converted value and the precision are ​0​ the conversion results in no characters. In the alternative implementation 0x or 0X is prefixed to results if the converted value is nonzero.

+		 N/A
+u Converts an unsigned integer into decimal representation dddd.

Precision specifies the minimum number of digits to appear. The default precision is 1. If both the converted value and the precision are ​0​ the conversion results in no characters.

+		 N/A
+f
F 		Converts floating-point number to the decimal notation in the style [-]ddd.ddd.

Precision specifies the exact number of digits to appear after the decimal point character. The default precision is 6. In the alternative implementation decimal point character is written even if no digits follow it. For infinity and not-a-number conversion style see notes.

+		 N/A N/A +
double
 +
+double(C99) +
 N/A N/A N/A N/A +
long double
+e
E 		Converts floating-point number to the decimal exponent notation.

For the e conversion style [-]d.ddde±dd is used.
For the E conversion style [-]d.dddE±dd is used.
The exponent contains at least two digits, more digits are used only if necessary. If the value is ​0​, the exponent is also ​0​. Precision specifies the exact number of digits to appear after the decimal point character. The default precision is 6. In the alternative implementation decimal point character is written even if no digits follow it. For infinity and not-a-number conversion style see notes.

+		 N/A N/A N/A N/A N/A N/A
+a
A

(C99)

+		 Converts floating-point number to the hexadecimal exponent notation.

For the a conversion style [-]0xh.hhhp±d is used.
For the A conversion style [-]0Xh.hhhP±d is used.
The first hexadecimal digit is not 0 if the argument is a normalized floating point value. If the value is ​0​, the exponent is also ​0​. Precision specifies the exact number of digits to appear after the hexadecimal point character. The default precision is sufficient for exact representation of the value. In the alternative implementation decimal point character is written even if no digits follow it. For infinity and not-a-number conversion style see notes.

+		 N/A N/A N/A N/A N/A N/A
+g
G 		Converts floating-point number to decimal or decimal exponent notation depending on the value and the precision.

For the g conversion style conversion with style e or f will be performed.
For the G conversion style conversion with style E or F will be performed.
Let P equal the precision if nonzero, 6 if the precision is not specified, or 1 if the precision is ​0​. Then, if a conversion with style E would have an exponent of X:

+
    +
  • if P > X ≥ −4, the conversion is with style f or F and precision P − 1 − X.
    • +
  • otherwise, the conversion is with style e or E and precision P − 1.
    • +

Unless alternative representation is requested the trailing zeros are removed, also the decimal point character is removed if no fractional part is left. For infinity and not-a-number conversion style see notes.

+		 N/A N/A N/A N/A N/A N/A
+n Returns the number of characters written so far by this call to the function.

The result is written to the value pointed to by the argument. The specification may not contain any flag, field width, or precision.



+		 +
signed char*
 +
short*
 +
int*
 +
long*
 +
long long*
 + +
signed size_t* +
 + N/A
+p Writes an implementation defined character sequence defining a pointer. N/A N/A +void* N/A N/A N/A N/A N/A N/A

The floating point conversion functions convert infinity to inf or infinity. Which one is used is implementation defined.

+

Not-a-number is converted to nan or nan(char_sequence). Which one is used is implementation defined.

+

The conversions F, E, G, A output INF, INFINITY, NAN instead.

+

Even though %c expects int argument, it is safe to pass a char because of the integer promotion that takes place when a variadic function is called.

+

The correct conversion specifications for the fixed-width character types (int8_t, etc) are defined in the header <inttypes.h> (although PRIdMAX, PRIuMAX, etc is synonymous with %jd, %ju, etc).

+

The memory-writing conversion specifier %n is a common target of security exploits where format strings depend on user input and is not supported by the bounds-checked printf_s family of functions.

+

There is a sequence point after the action of each conversion specifier; this permits storing multiple %n results in the same variable or, as an edge case, printing a string modified by an earlier %n within the same call.

+

If a conversion specification is invalid, the behavior is undefined.

+

Return value

+1,2) number of characters transmitted to the output stream or negative value if an output error or an encoding error (for string and character conversion specifiers) occurred
+3) number of characters written to buffer (not counting the terminating null character), or a negative value if an encoding error (for string and character conversion specifiers) occurred
+4) number of characters (not including the terminating null character) which would have been written to buffer if bufsz was ignored, or a negative value if an encoding error (for string and character conversion specifiers) occurred
+5,6) number of characters transmitted to the output stream or negative value if an output error, a runtime constraints violation error, or an encoding error occurred.
+7) number of characters written to buffer, not counting the null character (which is always written as long as buffer is not a null pointer and bufsz is not zero and not greater than RSIZE_MAX), or zero on runtime constraint violations, and negative value on encoding errors
+8) number of characters not including the terminating null character (which is always written as long as buffer is not a null pointer and bufsz is not zero and not greater than RSIZE_MAX), which would have been written to buffer if bufsz was ignored, or a negative value if a runtime constraints violation or an encoding error occurred

Notes

The C standard and POSIX specify that the behavior of sprintf and its variants is undefined when an argument overlaps with the destination buffer. Example:

+
sprintf(dst, "%s and %s", dst, t); // <- broken: undefined behavior

POSIX specifies that errno is set on error. It also specifies additional conversion specifications, most notably support for argument reordering (n$ immediately after % indicates nth argument).

+

Calling snprintf with zero bufsz and null pointer for buffer is useful to determine the necessary buffer size to contain the output:

+
const char fmt[] = "sqrt(2) = %f";
+int sz = snprintf(NULL, 0, fmt, sqrt(2));
+char buf[sz + 1]; // note +1 for terminating null byte
+snprintf(buf, sizeof buf, fmt, sqrt(2));

snprintf_s, just like snprintf, but unlike sprintf_s, will truncate the output to fit in bufsz-1.

+

Example

#include <stdio.h>
+#include <stdint.h>
+#include <inttypes.h>
+ 
+int main(void)
+{
+    const char* s = "Hello";
+    printf("Strings:\n"); // same as puts("Strings");
+    printf(" padding:\n");
+    printf("\t[%10s]\n", s);
+    printf("\t[%-10s]\n", s);
+    printf("\t[%*s]\n", 10, s);
+    printf(" truncating:\n");
+    printf("\t%.4s\n", s);
+    printf("\t%.*s\n", 3, s);
+ 
+    printf("Characters:\t%c %%\n", 'A');
+ 
+    printf("Integers:\n");
+    printf("\tDecimal:\t%i %d %.6i %i %.0i %+i %i\n",
+                         1, 2,   3, 0,   0,  4,-4);
+    printf("\tHexadecimal:\t%x %x %X %#x\n", 5, 10, 10, 6);
+    printf("\tOctal:\t\t%o %#o %#o\n", 10, 10, 4);
+ 
+    printf("Floating point:\n");
+    printf("\tRounding:\t%f %.0f %.32f\n", 1.5, 1.5, 1.3);
+    printf("\tPadding:\t%05.2f %.2f %5.2f\n", 1.5, 1.5, 1.5);
+    printf("\tScientific:\t%E %e\n", 1.5, 1.5);
+    printf("\tHexadecimal:\t%a %A\n", 1.5, 1.5);
+    printf("\tSpecial values:\t0/0=%g 1/0=%g\n", 0.0/0.0, 1.0/0.0);
+ 
+    printf("Fixed-width types:\n");
+    printf("\tLargest 32-bit value is %" PRIu32 " or %#" PRIx32 "\n",
+                                     UINT32_MAX,     UINT32_MAX );
+}

Possible output:

+
Strings:
+ padding:
+        [     Hello]
+        [Hello     ]
+        [     Hello]
+ truncating:
+        Hell
+        Hel
+Characters:        A %
+Integers:
+        Decimal:        1 2 000003 0  +4 -4
+        Hexadecimal:        5 a A 0x6
+        Octal:                12 012 04
+Floating point:
+        Rounding:        1.500000 2 1.30000000000000004440892098500626
+        Padding:        01.50 1.50  1.50
+        Scientific:        1.500000E+00 1.500000e+00
+        Hexadecimal:        0x1.8p+0 0X1.8P+0
+        Special values:        0/0=-nan 1/0=inf
+Fixed-width types:
+        Largest 32-bit value is 4294967295 or 0xffffffff

References

See also

+ + + + +
+
(C95)(C95)(C95)(C11)(C11)(C11)(C11)
 prints formatted wide character output to stdout, a file stream or a buffer
(function)
+
(C99)(C11)(C11)(C11)(C11)
 prints formatted output to stdout, a file stream or a buffer
using variable argument list
(function)
writes a character string to a file stream
(function)
+
(C11)(C11)(C11)
 reads formatted input from stdin, a file stream or a buffer
(function)
C++ documentation for printf, fprintf, sprintf, snprintf
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/fprintf +

+
diff --git a/devdocs/c/io%2Ffputc.html b/devdocs/c/io%2Ffputc.html new file mode 100644 index 00000000..d3993152 --- /dev/null +++ b/devdocs/c/io%2Ffputc.html @@ -0,0 +1,66 @@ +

fputc, putc

Defined in header <stdio.h> 
int fputc( int ch, FILE* stream );
+		 
int putc( int ch, FILE* stream );
+

Writes a character ch to the given output stream stream. putc() may be implemented as a macro and evaluate stream more than once, so the corresponding argument should never be an expression with side effects.

+

Internally, the character is converted to unsigned char just before being written.

+

Parameters

+ + +
ch - character to be written
stream - output stream

Return value

On success, returns the written character.

+

On failure, returns EOF and sets the error indicator (see ferror()) on stream.

+

Example

+

Shows putc with error checking

+
#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    int ret_code = 0;
+    for (char c = 'a'; (ret_code != EOF) && (c != 'z'); c++)
+        ret_code = putc(c, stdout);
+ 
+    // Test whether EOF was reached.
+    if (ret_code == EOF && ferror(stdout))
+    {
+        perror("putc()");
+        fprintf(stderr, "putc() failed in file %s at line # %d\n",
+                __FILE__, __LINE__ - 7);
+        exit(EXIT_FAILURE);
+    }
+    putc('\n', stdout);
+ 
+    return EXIT_SUCCESS;
+}

Output:

+
abcdefghijklmnopqrstuvwxy

References

See also

+ +
writes a character to stdout
(function)
C++ documentation for fputc, putc
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/fputc +

+
diff --git a/devdocs/c/io%2Ffputs.html b/devdocs/c/io%2Ffputs.html new file mode 100644 index 00000000..99726ec7 --- /dev/null +++ b/devdocs/c/io%2Ffputs.html @@ -0,0 +1,38 @@ +

fputs

Defined in header <stdio.h> 
int fputs( const char          *str, FILE          *stream );
+		 (until C99) 
int fputs( const char *restrict str, FILE *restrict stream );
+		 (since C99)

Writes every character from the null-terminated string str to the output stream stream, as if by repeatedly executing fputc.

+

The terminating null character from str is not written.

+

Parameters

+ + +
str - null-terminated character string to be written
stream - output stream

Return value

On success, returns a non-negative value

+

On failure, returns EOF and sets the error indicator (see ferror()) on stream.

+

Notes

The related function puts appends a newline character to the output, while fputs writes the string unmodified.

+

Different implementations return different non-negative numbers: some return the last character written, some return the number of characters written (or INT_MAX if the string was longer than that), some simply return a non-negative constant such as zero.

+

Example

#include <stdio.h>
+ 
+int main(void)
+{
+    int rc = fputs("Hello World", stdout);
+ 
+    if (rc == EOF)
+       perror("fputs()"); // POSIX requires that errno is set
+}

Output:

+
Hello World

References

See also

+ + + +
+
(C99)(C11)(C11)(C11)(C11)
 prints formatted output to stdout, a file stream or a buffer
(function)
writes a character string to stdout
(function)
gets a character string from a file stream
(function)
C++ documentation for fputs
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/fputs +

+
diff --git a/devdocs/c/io%2Ffputwc.html b/devdocs/c/io%2Ffputwc.html new file mode 100644 index 00000000..c309e8f7 --- /dev/null +++ b/devdocs/c/io%2Ffputwc.html @@ -0,0 +1,63 @@ +

fputwc, putwc

Defined in header <wchar.h> 
wint_t fputwc( wchar_t ch, FILE* stream );
+		 (1) (since C95) 
wint_t putwc( wchar_t ch, FILE* stream );
+		 (2) (since C95)

Writes a wide character ch to the given output stream stream.

+
+2) May be implemented as a macro and may evaluate stream more than once.

Parameters

+ + +
ch - wide character to be written
stream - the output stream

Return value

Returns a copy of ch on success.

+

On failure, returns WEOF and sets the error indicator (see ferror()) on stream.

+

If an encoding error occurred, additionally sets errno to EILSEQ.

+

Example

#include <errno.h>
+#include <locale.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <wchar.h>
+ 
+int main(void)
+{
+    setlocale(LC_ALL, "en_US.utf8");
+ 
+    errno = 0;
+    if (fputwc(L'🍌', stdout) == WEOF)
+    {
+        if (errno == EILSEQ)
+            puts("Encoding error in fputwc.");
+        else
+            puts("I/O error in fputwc.");
+        return EXIT_FAILURE;
+    }
+}

Possible output:

+
🍌

References

See also

+ + + +
writes a character to a file stream
(function)
+
(C95)
 writes a wide string to a file stream
(function)
+
(C95)
 gets a wide character from a file stream
(function)
C++ documentation for fputwc
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/fputwc +

+
diff --git a/devdocs/c/io%2Ffputws.html b/devdocs/c/io%2Ffputws.html new file mode 100644 index 00000000..04e2ddf9 --- /dev/null +++ b/devdocs/c/io%2Ffputws.html @@ -0,0 +1,40 @@ +

fputws

Defined in header <wchar.h> 
int fputws( const wchar_t *str, FILE *stream );
+		 (since C95)
(until C99) 
int fputws( const wchar_t * restrict str, FILE * restrict stream );
+		 (since C99)

Writes every character from the null-terminated wide string str to the output stream stream, as if by repeatedly executing fputwc.

+

The terminating null wide character from str is not written.

+

Parameters

+ + +
str - null-terminated wide string to be written
stream - output stream

Return value

On success, returns a non-negative value

+

On failure, returns EOF and sets the error indicator (see ferror) on stream.

+

Example

#include <locale.h>
+#include <stdio.h>
+#include <wchar.h>
+ 
+int main(void)
+{
+    setlocale(LC_ALL, "en_US.utf8");
+    int rc = fputws(L"御休みなさい", stdout);
+ 
+    if (rc == EOF)
+       perror("fputws()"); // POSIX requires that errno is set
+}

Output:

+
御休みなさい

References

See also

+ + + + +
writes a character string to a file stream
(function)
+
(C95)(C95)(C95)(C11)(C11)(C11)(C11)
 prints formatted wide character output to stdout, a file stream or a buffer
(function)
fputws
+
(C95)
 writes a wide string to a file stream
(function)
+
(C95)
 gets a wide string from a file stream
(function)
C++ documentation for fputws
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/fputws +

+
diff --git a/devdocs/c/io%2Ffread.html b/devdocs/c/io%2Ffread.html new file mode 100644 index 00000000..890f4374 --- /dev/null +++ b/devdocs/c/io%2Ffread.html @@ -0,0 +1,70 @@ +

fread

Defined in header <stdio.h> 
size_t fread( void          *buffer, size_t size, size_t count,
+              FILE          *stream );
+		 (until C99) 
size_t fread( void *restrict buffer, size_t size, size_t count,
+              FILE *restrict stream );
+		 (since C99)

Reads up to count objects into the array buffer from the given input stream stream as if by calling fgetc size times for each object, and storing the results, in the order obtained, into the successive positions of buffer, which is reinterpreted as an array of unsigned char. The file position indicator for the stream is advanced by the number of characters read.

+

If an error occurs, the resulting value of the file position indicator for the stream is indeterminate. If a partial element is read, its value is indeterminate.

+

Parameters

+ + + + +
buffer - pointer to the array where the read objects are stored
size - size of each object in bytes
count - the number of the objects to be read
stream - the stream to read

Return value

Number of objects read successfully, which may be less than count if an error or end-of-file condition occurs.

+

If size or count is zero, fread returns zero and performs no other action.

+

fread does not distinguish between end-of-file and error, and callers must use feof and ferror to determine which occurred.

+

Example

#include <stdio.h>
+ 
+enum { SIZE = 5 };
+ 
+int main(void)
+{
+    const double a[SIZE] = {1.0, 2.0, 3.0, 4.0, 5.0};
+    printf("Array has size %ld bytes, element size: %ld\n", sizeof a, sizeof *a);
+    FILE *fp = fopen("test.bin", "wb"); // must use binary mode
+    fwrite(a, sizeof *a, SIZE, fp); // writes an array of doubles
+    fclose(fp);
+ 
+    double b[SIZE];
+    fp = fopen("test.bin","rb");
+    const size_t ret_code = fread(b, sizeof b[0], SIZE, fp); // reads an array of doubles
+    if (ret_code == SIZE)
+    {
+        printf("Array at %p read successfully, contents:\n", (void*)&a);
+        for (int n = 0; n != SIZE; ++n)
+            printf("%f ", b[n]);
+        putchar('\n');
+    }
+    else // error handling
+    {
+        if (feof(fp))
+            printf("Error reading test.bin: unexpected end of file\n");
+        else if (ferror(fp))
+            perror("Error reading test.bin");
+    }
+ 
+    fclose(fp);
+}

Possible output:

+
Array has size 40 bytes, element size: 8
+Array at 0x1337f00d6960 read successfully, contents:
+1.000000 2.000000 3.000000 4.000000 5.000000

References

See also

+ + + +
+
(C11)(C11)(C11)
 reads formatted input from stdin, a file stream or a buffer
(function)
gets a character string from a file stream
(function)
writes to a file
(function)
C++ documentation for fread
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/fread +

+
diff --git a/devdocs/c/io%2Ffreopen.html b/devdocs/c/io%2Ffreopen.html new file mode 100644 index 00000000..74c69f8a --- /dev/null +++ b/devdocs/c/io%2Ffreopen.html @@ -0,0 +1,82 @@ +

freopen, freopen_s

Defined in header <stdio.h>
(1) 
FILE *freopen( const char *filename, const char *mode,
+               FILE *stream );
+		 (until C99) 
FILE *freopen( const char *restrict filename, const char *restrict mode, 
+               FILE *restrict stream );
+		 (since C99) 
errno_t freopen_s( FILE *restrict *restrict newstreamptr,
+                   const char *restrict filename, const char *restrict mode,
+                   FILE *restrict stream );
+		 (2) (since C11)
+1) First, attempts to close the file associated with stream, ignoring any errors. Then, if filename is not null, attempts to open the file specified by filename using mode as if by fopen, and associates that file with the file stream pointed to by stream. If filename is a null pointer, then the function attempts to reopen the file that is already associated with stream (it is implementation defined which mode changes are allowed in this case).
+2) Same as (1), except that mode is treated as in fopen_s and that the pointer to the file stream is written to newstreamptr and the following errors are detected at runtime and call the currently installed constraint handler function:
+
+
    +
  • newstreamptr is a null pointer
    • +
  • stream is a null pointer
    • +
  • mode is a null pointer
    • +
+
As with all bounds-checked functions, freopen_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <stdio.h>.
+
+

Parameters

+ + + + +
filename - file name to associate the file stream to
mode - null-terminated character string determining new file access mode
stream - the file stream to modify
newstreamptr - pointer to a pointer where the function stores the result (an out-parameter)

File access flags

+ + + + + + + + + + + + +
File access
mode string 		Meaning Explanation Action if file
already exists 		Action if file
does not exist
"r" read Open a file for reading read from start failure to open
"w" write Create a file for writing destroy contents create new
"a" append Append to a file write to end create new
"r+" read extended Open a file for read/write read from start error
"w+" write extended Create a file for read/write destroy contents create new
"a+" append extended Open a file for read/write write to end create new
File access mode flag "b" can optionally be specified to open a file in binary mode. This flag has no effect on POSIX systems, but on Windows it disables special handling of '\n' and '\x1A'.
On the append file access modes, data is written to the end of the file regardless of the current position of the file position indicator.
The behavior is undefined if the mode is not one of the strings listed above. Some implementations define additional supported modes (e.g. Windows).
In update mode ('+'), both input and output may be performed, but output cannot be followed by input without an intervening call to fflush, fseek, fsetpos or rewind, and input cannot be followed by output without an intervening call to fseek, fsetpos or rewind, unless the input operation encountered end of file. In update mode, implementations are permitted to use binary mode even when text mode is specified.
File access mode flag "x" can optionally be appended to "w" or "w+" specifiers. This flag forces the function to fail if the file exists, instead of overwriting it. (C11)
When using fopen_s or freopen_s, file access permissions for any file created with "w" or "a" prevents other users from accessing it. File access mode flag "u" can optionally be prepended to any specifier that begins with "w" or "a", to enable the default fopen permissions. (C11)

Return value

+1) A copy of the value of stream on success, null pointer on failure.
+2) zero on success (and a copy of the value of stream is written to *newstreamptr, non-zero on error (and null pointer is written to *newstreamptr unless newstreamptr is itself a null pointer).

Notes

freopen is the only way to change the narrow/wide orientation of a stream once it has been established by an I/O operation or by fwide.

+

Microsoft CRT version of freopen does not support any mode changes when filename is a null pointer and treats this as an error (see documentation). A possible workaround is the non-standard function _setmode().

+

Example

+

The following code redirects stdout to a file.

+
#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    puts("stdout is printed to console");
+    if (freopen("redir.txt", "w", stdout) == NULL)
+    {
+       perror("freopen() failed");
+       return EXIT_FAILURE;
+    }
+    puts("stdout is redirected to a file"); // this is written to redir.txt
+    fclose(stdout);
+    return EXIT_SUCCESS;
+}

Output:

+
stdout is printed to console

References

See also

+ + +
+
(C11)
 opens a file
(function)
closes a file
(function)
C++ documentation for freopen
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/freopen +

+
diff --git a/devdocs/c/io%2Ffscanf.html b/devdocs/c/io%2Ffscanf.html new file mode 100644 index 00000000..9dbe321e --- /dev/null +++ b/devdocs/c/io%2Ffscanf.html @@ -0,0 +1,232 @@ +

scanf, fscanf, sscanf, scanf_s, fscanf_s, sscanf_s

Defined in header <stdio.h>
(1) 
int scanf( const char          *format, ... );
+		 (until C99) 
int scanf( const char *restrict format, ... );
+		 (since C99)
(2) 
int fscanf( FILE          *stream, const char          *format, ... );
+		 (until C99) 
int fscanf( FILE *restrict stream, const char *restrict format, ... );
+		 (since C99)
(3) 
int sscanf( const char          *buffer, const char          *format, ... );
+		 (until C99) 
int sscanf( const char *restrict buffer, const char *restrict format, ... );
+		 (since C99) 
int scanf_s(const char *restrict format, ...);
+		 (4) (since C11) 
int fscanf_s(FILE *restrict stream, const char *restrict format, ...);
+		 (5) (since C11) 
int sscanf_s(const char *restrict buffer, const char *restrict format, ...);
+		 (6) (since C11)

Reads data from a variety of sources, interprets it according to format and stores the results into given locations.

+
+1) reads the data from stdin +
+2) reads the data from file stream stream +
+3) reads the data from null-terminated character string buffer. Reaching the end of the string is equivalent to reaching the end-of-file condition for fscanf +
+4-6) Same as (1-3), except that %c, %s, and %[ conversion specifiers each expect two arguments (the usual pointer and a value of type rsize_t indicating the size of the receiving array, which may be 1 when reading with a %c into a single char) and except that the following errors are detected at runtime and call the currently installed constraint handler function:
+
+
    +
  • any of the arguments of pointer type is a null pointer
    • +
  • format, stream, or buffer is a null pointer
    • +
  • the number of characters that would be written by %c, %s, or %[, plus the terminating null character, would exceed the second (rsize_t) argument provided for each of those conversion specifiers
    • +
  • optionally, any other detectable error, such as unknown conversion specifier
    • +
+
As with all bounds-checked functions, scanf_s , fscanf_s, and sscanf_s are only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <stdio.h>.
+
+

Parameters

+ + + + +
stream - input file stream to read from
buffer - pointer to a null-terminated character string to read from
format - pointer to a null-terminated character string specifying how to read the input
... - receiving arguments.


The format string consists of

+

The following format specifiers are available:

+ + + + + + + + + + + + + + + +
Conversion
specifier 		Explanation Argument type
+Length modifier → +hh

(C99)

+		 +h (none) +l +ll

(C99)

+		 +j

(C99)

+		 +z

(C99)

+		 +t

(C99)

+		 +L
+% Matches literal %. N/A N/A N/A N/A N/A N/A N/A N/A N/A
+c Matches a character or a sequence of characters.

If a width specifier is used, matches exactly width characters (the argument must be a pointer to an array with sufficient room). Unlike %s and %[, does not append the null character to the array.

+		 N/A N/A +
char*
 +
wchar_t*
 N/A N/A N/A N/A N/A
+s Matches a sequence of non-whitespace characters (a string).

If width specifier is used, matches up to width or until the first whitespace character, whichever appears first. Always stores a null character in addition to the characters matched (so the argument array must have room for at least width+1 characters)

+
+[set] Matches a non-empty sequence of character from set of characters.

If the first character of the set is ^, then all characters not in the set are matched. If the set begins with ] or ^] then the ] character is also included into the set. It is implementation-defined whether the character - in the non-initial position in the scanset may be indicating a range, as in [0-9]. If width specifier is used, matches only up to width. Always stores a null character in addition to the characters matched (so the argument array must have room for at least width+1 characters)

+
+d Matches a decimal integer.

The format of the number is the same as expected by strtol with the value 10 for the base argument

+		 +
+signed char* or unsigned char* +
 +
+signed short* or unsigned short* +
 +
+signed int* or unsigned int* +
 +
+signed long* or unsigned long* +
 +
+signed long long* or unsigned long long* +
 + + + N/A
+i Matches an integer.

The format of the number is the same as expected by strtol with the value ​0​ for the base argument (base is determined by the first characters parsed)

+
+u Matches an unsigned decimal integer.

The format of the number is the same as expected by strtoul with the value 10 for the base argument.

+
+o Matches an unsigned octal integer.

The format of the number is the same as expected by strtoul with the value 8 for the base argument

+
+x, X Matches an unsigned hexadecimal integer.

The format of the number is the same as expected by strtoul with the value 16 for the base argument

+
+n Returns the number of characters read so far.

No input is consumed. Does not increment the assignment count. If the specifier has assignment-suppressing operator defined, the behavior is undefined

+
+a, A(C99)
e, E
f, F(C99)
g, G 		Matches a floating-point number.

The format of the number is the same as expected by strtof

+		 N/A N/A +
float*
 +
double*
 N/A N/A N/A N/A +
long double*
+p Matches implementation defined character sequence defining a pointer.

printf family of functions should produce the same sequence using %p format specifier

+		 N/A N/A +
void**
 N/A N/A N/A N/A N/A N/A

For every conversion specifier other than n, the longest sequence of input characters which does not exceed any specified field width and which either is exactly what the conversion specifier expects or is a prefix of a sequence it would expect, is what's consumed from the stream. The first character, if any, after this consumed sequence remains unread. If the consumed sequence has length zero or if the consumed sequence cannot be converted as specified above, the matching failure occurs unless end-of-file, an encoding error, or a read error prevented input from the stream, in which case it is an input failure.

+

All conversion specifiers other than [, c, and n consume and discard all leading whitespace characters (determined as if by calling isspace) before attempting to parse the input. These consumed characters do not count towards the specified maximum field width.

+

The conversion specifiers lc, ls, and l[ perform multibyte-to-wide character conversion as if by calling mbrtowc with an mbstate_t object initialized to zero before the first character is converted.

+

The conversion specifiers s and [ always store the null terminator in addition to the matched characters. The size of the destination array must be at least one greater than the specified field width. The use of %s or %[, without specifying the destination array size, is as unsafe as gets.

+

The correct conversion specifications for the fixed-width integer types (int8_t, etc) are defined in the header <inttypes.h> (although SCNdMAX, SCNuMAX, etc is synonymous with %jd, %ju, etc).

+

There is a sequence point after the action of each conversion specifier; this permits storing multiple fields in the same "sink" variable.

+

When parsing an incomplete floating-point value that ends in the exponent with no digits, such as parsing "100er" with the conversion specifier %f, the sequence "100e" (the longest prefix of a possibly valid floating-point number) is consumed, resulting in a matching error (the consumed sequence cannot be converted to a floating-point number), with "r" remaining. Some existing implementations do not follow this rule and roll back to consume only "100", leaving "er", e.g. glibc bug 1765.

+

If a conversion specification is invalid, the behavior is undefined.

+

Return value

+1-3) Number of receiving arguments successfully assigned (which may be zero in case a matching failure occurred before the first receiving argument was assigned), or EOF if input failure occurs before the first receiving argument was assigned.
+4-6) Same as (1-3), except that EOF is also returned if there is a runtime constraint violation.

Complexity

Not guaranteed. Notably, some implementations of sscanf are O(N), where N = strlen(buffer) [1].

+

Notes

Because most conversion specifiers first consume all consecutive whitespace, code such as

+
scanf("%d", &a);
+scanf("%d", &b);

will read two integers that are entered on different lines (second %d will consume the newline left over by the first) or on the same line, separated by spaces or tabs (second %d will consume the spaces or tabs). The conversion specifiers that do not consume leading whitespace, such as %c, can be made to do so by using a whitespace character in the format string:

+
scanf("%d", &a);
+scanf(" %c", &c); // consume all consecutive whitespace after %d, then read a char

Example

#define __STDC_WANT_LIB_EXT1__ 1
+#include <stdio.h>
+#include <stddef.h>
+#include <locale.h>
+ 
+int main(void)
+{
+    int i, j;
+    float x, y;
+    char str1[10], str2[4];
+    wchar_t warr[2];
+    setlocale(LC_ALL, "en_US.utf8");
+ 
+    char input[] = "25 54.32E-1 Thompson 56789 0123 56ß水";
+    /* parse as follows:
+       %d: an integer
+       %f: a floating-point value
+       %9s: a string of at most 9 non-whitespace characters
+       %2d: two-digit integer (digits 5 and 6)
+       %f:  a floating-point value (digits 7, 8, 9)
+       %*d: an integer which isn't stored anywhere
+       ' ': all consecutive whitespace
+       %3[0-9]: a string of at most 3 decimal digits (digits 5 and 6)
+       %2lc: two wide characters, using multibyte to wide conversion  */
+    int ret = sscanf(input, "%d%f%9s%2d%f%*d %3[0-9]%2lc",
+                     &i, &x, str1, &j, &y, str2, warr);
+ 
+    printf("Converted %d fields:\n"
+           "i = %d\n"
+           "x = %f\n"
+           "str1 = %s\n"
+           "j = %d\n"
+           "y = %f\n"
+           "str2 = %s\n"
+           "warr[0] = U+%x\n"
+           "warr[1] = U+%x\n",
+           ret, i, x, str1, j, y, str2, warr[0], warr[1]);
+ 
+#ifdef __STDC_LIB_EXT1__
+    int n = sscanf_s(input, "%d%f%s", &i, &x, str1, (rsize_t)sizeof str1);
+    // writes 25 to i, 5.432 to x, the 9 bytes "Thompson\0" to str1, and 3 to n.
+#endif
+}

Possible output:

+
Converted 7 fields:
+i = 25
+x = 5.432000
+str1 = Thompson
+j = 56
+y = 789.000000
+str2 = 56
+warr[0] = U+df
+warr[1] = U+6c34

References

See also

+ + + +
+
(C99)(C99)(C99)(C11)(C11)(C11)
 reads formatted input from stdin, a file stream or a buffer
using variable argument list
(function)
gets a character string from a file stream
(function)
+
(C99)(C11)(C11)(C11)(C11)
 prints formatted output to stdout, a file stream or a buffer
(function)
C++ documentation for scanf, fscanf, sscanf
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/fscanf +

+
diff --git a/devdocs/c/io%2Ffseek.html b/devdocs/c/io%2Ffseek.html new file mode 100644 index 00000000..0d57a3fe --- /dev/null +++ b/devdocs/c/io%2Ffseek.html @@ -0,0 +1,74 @@ +

fseek

Defined in header <stdio.h> 
int fseek( FILE *stream, long offset, int origin );
+		 
#define SEEK_SET     /*unspecified*/
+#define SEEK_CUR     /*unspecified*/
+#define SEEK_END     /*unspecified*/
+

Sets the file position indicator for the file stream stream to the value pointed to by offset.

+

If the stream is open in binary mode, the new position is exactly offset bytes measured from the beginning of the file if origin is SEEK_SET, from the current file position if origin is SEEK_CUR, and from the end of the file if origin is SEEK_END. Binary streams are not required to support SEEK_END, in particular if additional null bytes are output.

+

If the stream is open in text mode, the only supported values for offset are zero (which works with any origin) and a value returned by an earlier call to ftell on a stream associated with the same file (which only works with origin of SEEK_SET).

+

If the stream is wide-oriented, the restrictions of both text and binary streams apply (result of ftell is allowed with SEEK_SET and zero offset is allowed from SEEK_SET and SEEK_CUR, but not SEEK_END).

+

In addition to changing the file position indicator, fseek undoes the effects of ungetc and clears the end-of-file status, if applicable.

+

If a read or write error occurs, the error indicator for the stream (ferror) is set and the file position is unaffected.

+

Parameters

+ + + +
stream - file stream to modify
offset - number of characters to shift the position relative to origin
origin - position to which offset is added. It can have one of the following values: SEEK_SET, SEEK_CUR, SEEK_END

Return value

​0​ upon success, nonzero value otherwise.

+

Notes

After seeking to a non-end position in a wide stream, the next call to any output function may render the remainder of the file undefined, e.g. by outputting a multibyte sequence of a different length.

+

For text streams, the only valid values of offset are ​0​ (applicable to any origin) and a value returned by an earlier call to ftell (only applicable to SEEK_SET).

+

POSIX allows seeking beyond the existing end of file. If an output is performed after this seek, any read from the gap will return zero bytes. Where supported by the filesystem, this creates a sparse file.

+

POSIX also requires that fseek first performs fflush if there are any unwritten data (but whether the shift state is restored is implementation-defined).

+

Example

+

fseek with error checking:

+
#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    /* Prepare an array of double values. */
+    #define SIZE 5
+    double A[SIZE] = {1.0, 2.0, 3.0, 4.0, 5.0};
+    /* Write array to a file. */
+    FILE * fp = fopen("test.bin", "wb");
+    fwrite(A, sizeof(double), SIZE, fp);
+    fclose (fp);
+ 
+    /* Read the double values into array B. */
+    double B[SIZE];
+    fp = fopen("test.bin", "rb");
+ 
+    /* Set the file position indicator in front of third double value. */
+    if (fseek(fp, sizeof(double) * 2L, SEEK_SET) != 0)
+    {
+        fprintf(stderr, "fseek() failed in file %s at line # %d\n", __FILE__, __LINE__ - 2);
+        fclose(fp);
+        return EXIT_FAILURE;
+    }
+ 
+    int ret_code = fread(B, sizeof(double), 1, fp); /* read one double value  */
+    printf("ret_code == %d\n", ret_code);           /* print the number of values read */
+    printf("B[0] == %.1f\n", B[0]);                 /* print one value */
+ 
+    fclose(fp);
+    return EXIT_SUCCESS;
+}

Possible output:

+
ret_code == 1
+B[0] == 3.0

References

See also

+ + + + +
moves the file position indicator to a specific location in a file
(function)
gets the file position indicator
(function)
returns the current file position indicator
(function)
moves the file position indicator to the beginning in a file
(function)
C++ documentation for fseek
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/fseek +

+
diff --git a/devdocs/c/io%2Ffsetpos.html b/devdocs/c/io%2Ffsetpos.html new file mode 100644 index 00000000..3ef15100 --- /dev/null +++ b/devdocs/c/io%2Ffsetpos.html @@ -0,0 +1,73 @@ +

fsetpos

Defined in header <stdio.h> 
int fsetpos( FILE *stream, const fpos_t *pos );
+

Sets the file position indicator and the multibyte parsing state (if any) for the file stream stream according to the value pointed to by pos.

+

Besides establishing new parse state and position, a call to this function undoes the effects of ungetc and clears the end-of-file state, if it is set.

+

If a read or write error occurs, the error indicator (ferror) for the stream is set.

+

Parameters

+ + +
stream - file stream to modify
pos - pointer to a fpos_t object to use as new value of file position indicator

Return value

​0​ upon success, nonzero value otherwise.

+

Notes

After seeking to a non-end position in a wide stream, the next call to any output function may render the remainder of the file undefined, e.g. by outputting a multibyte sequence of a different length.

+

Example

+

fsetpos with error checking

+
#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    /* Prepare an array of f-p values. */
+    #define SIZE 5
+    double A[SIZE] = {1.,2.,3.,4.,5.};
+    /* Write array to a file. */
+    FILE * fp = fopen("test.bin", "wb");
+    fwrite(A,sizeof(double),SIZE,fp);
+    fclose (fp);
+ 
+    /* Read the f-p values into array B. */
+    double B[SIZE];
+    fp = fopen("test.bin","rb");
+    fpos_t pos;
+    if (fgetpos(fp,&pos) != 0)      /* current position: start of file */
+    {
+       perror("fgetpos()");
+       fprintf(stderr,"fgetpos() failed in file %s at line # %d\n", __FILE__,__LINE__-3);
+       exit(EXIT_FAILURE);
+    }
+ 
+    int ret_code = fread(B,sizeof(double),1,fp);   /* read one f-p value */
+    /* current position: after reading one f-p value */
+    printf("%.1f; read count = %d\n", B[0], ret_code);   /* print one f-p value and ret_code */
+ 
+    if (fsetpos(fp,&pos) != 0)   /* reset current position to start of file */
+    {
+       if (ferror(fp))
+       {
+          perror("fsetpos()");
+          fprintf(stderr,"fsetpos() failed in file %s at line # %d\n", __FILE__,__LINE__-5);
+          exit(EXIT_FAILURE);
+       }
+    }
+ 
+    ret_code = fread(B,sizeof(double),1,fp);   /* reread first f-p value */
+    printf("%.1f; read count = %d\n", B[0], ret_code);   /* print one f-p value and ret_code */
+    fclose(fp);
+ 
+    return EXIT_SUCCESS; 
+}

Output:

+
1.0; read count = 1
+1.0; read count = 1

References

See also

+ + + +
gets the file position indicator
(function)
returns the current file position indicator
(function)
moves the file position indicator to a specific location in a file
(function)
C++ documentation for fsetpos
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/fsetpos +

+
diff --git a/devdocs/c/io%2Fftell.html b/devdocs/c/io%2Fftell.html new file mode 100644 index 00000000..c2696fde --- /dev/null +++ b/devdocs/c/io%2Fftell.html @@ -0,0 +1,77 @@ +

ftell

Defined in header <stdio.h> 
long ftell( FILE *stream );
+

Returns the file position indicator for the file stream stream.

+

If the stream is open in binary mode, the value obtained by this function is the number of bytes from the beginning of the file.

+

If the stream is open in text mode, the value returned by this function is unspecified and is only meaningful as the input to fseek().

+

Parameters

+ +
stream - file stream to examine

Return value

File position indicator on success or -1L if failure occurs.

+

On error, the errno variable is set to implementation-defined positive value.

+

Example

+

Demonstrates ftell() with error checking. Writes then reads a few floating-point (FP) values to/from a file.

+
#include <stdio.h>
+#include <stdlib.h>
+ 
+/* If the condition is not met then exit the program with error message. */
+void check(_Bool condition, const char* func, int line)
+{
+    if (condition)
+        return;
+    perror(func);
+    fprintf(stderr, "%s failed in file %s at line # %d\n", func, __FILE__, line - 1);
+    exit(EXIT_FAILURE);
+}
+ 
+int main(void)
+{
+    /* Prepare an array of FP values. */
+    #define SIZE 5
+    double A[SIZE] = {1.1,2.,3.,4.,5.};
+ 
+    /* Write array to a file. */
+    const char* fname = "/tmp/test.bin";
+    FILE* file = fopen(fname, "wb");
+    check(file != NULL, "fopen()", __LINE__);
+ 
+    const int write_count = fwrite(A, sizeof(double), SIZE, file);
+    check(write_count == SIZE, "fwrite()", __LINE__);
+ 
+    fclose(file);
+ 
+    /* Read the FP values into array B. */
+    double B[SIZE];
+    file = fopen(fname, "rb");
+    check(file != NULL, "fopen()", __LINE__);
+ 
+    long int pos = ftell(file); /* position indicator at start of file */
+    check(pos != -1L, "ftell()", __LINE__);
+    printf("pos: %ld\n", pos);
+ 
+    const int read_count = fread(B, sizeof(double), 1, file); /* read one FP value */
+    check(read_count == 1, "fread()", __LINE__);
+ 
+    pos = ftell(file); /* position indicator after reading one FP value */
+    check(pos != -1L, "ftell()", __LINE__);
+    printf("pos: %ld\n", pos);
+    printf("B[0]: %.1f\n", B[0]); /* print one FP value */
+ 
+    return EXIT_SUCCESS;
+}

Possible output:

+
pos: 0
+pos: 8
+B[0]: 1.1

References

See also

+ + + +
gets the file position indicator
(function)
moves the file position indicator to a specific location in a file
(function)
moves the file position indicator to a specific location in a file
(function)
C++ documentation for ftell
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/ftell +

+
diff --git a/devdocs/c/io%2Ffwide.html b/devdocs/c/io%2Ffwide.html new file mode 100644 index 00000000..4918f246 --- /dev/null +++ b/devdocs/c/io%2Ffwide.html @@ -0,0 +1,97 @@ +

fwide

Defined in header <wchar.h> 
int fwide( FILE *stream, int mode );
+		 (since C95)

If mode > 0, attempts to make stream wide-oriented. If mode < 0, attempts to make stream byte-oriented. If mode==0, only queries the current orientation of the stream.

+

If the orientation of the stream has already been decided (by executing output or by an earlier call to fwide), this function does nothing.

+

Parameters

+ + +
stream - pointer to the C I/O stream to modify or query
mode - integer value greater than zero to set the stream wide, less than zero to set the stream narrow, or zero to query only

Return value

An integer greater than zero if the stream is wide-oriented after this call, less than zero if the stream is byte-oriented after this call, and zero if the stream has no orientation.

+

Example

+

The following code sets and resets the stream orientation.

+
#include <wchar.h>
+#include <stdio.h>
+#include <stdlib.h>
+ 
+void show_orientation(int n)
+{
+    n < 0 ? puts("\tnarrow orientation"):
+    n > 0 ? puts("\twide orientation"):
+            puts("\tno orientation");
+}
+ 
+void try_read(FILE* fp)
+{
+    int c = fgetc(fp);
+    if(c == EOF)
+        puts("\tnarrow character read failed");
+    else
+        printf("\tnarrow character read '%c'\n", c);
+ 
+    wint_t wc = fgetwc(fp);
+    if(wc == WEOF)
+        puts("\twide character read failed");
+    else
+        printf("\twide character read '%lc'\n", wc);
+}
+ 
+int main(void)
+{
+    enum fwide_orientation { narrow = -1, query, wide };
+ 
+    FILE* fp = fopen("main.cpp", "r");
+    if (!fp)
+    {
+        perror("fopen() failed");
+        return EXIT_FAILURE;
+    }
+ 
+    puts("1) A newly opened stream has no orientation.");
+    show_orientation(fwide(fp, query));
+ 
+    puts("2) Establish byte orientation.");
+    show_orientation(fwide(fp, narrow));
+    try_read(fp);
+ 
+    puts("3) Only freopen() can reset stream orientation.");
+    if (freopen("main.cpp", "r", fp) == NULL)
+    {
+       perror("freopen() failed");
+       return EXIT_FAILURE;
+    }
+ 
+    puts("4) A reopened stream has no orientation.");
+    show_orientation(fwide(fp, query));
+ 
+    puts("5) Establish wide orientation.");
+    show_orientation(fwide(fp, wide));
+    try_read(fp);
+ 
+    fclose(fp);
+}

Possible output:

+
1) A newly opened stream has no orientation.
+        no orientation
+2) Establish byte orientation.
+        narrow orientation
+        narrow character read '#'
+        wide character read failed
+3) Only freopen() can reset stream orientation.
+4) A reopened stream has no orientation.
+        no orientation
+5) Establish wide orientation.
+        wide orientation
+        narrow character read failed
+        wide character read '#'

References

See also

+ +
+
(C11)
 opens a file
(function)
C++ documentation for fwide
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/fwide +

+
diff --git a/devdocs/c/io%2Ffwprintf.html b/devdocs/c/io%2Ffwprintf.html new file mode 100644 index 00000000..5ed5fda8 --- /dev/null +++ b/devdocs/c/io%2Ffwprintf.html @@ -0,0 +1,208 @@ +

wprintf, fwprintf, swprintf, wprintf_s, fwprintf_s, swprintf_s, snwprintf_s

Defined in header <wchar.h>
(1) 
int wprintf( const wchar_t *format, ... );
+		 (since C95)
(until C99) 
int wprintf( const wchar_t *restrict format, ... );
+		 (since C99)
(2) 
int fwprintf( FILE *stream, const wchar_t *format, ... );
+		 (since C95)
(until C99) 
int fwprintf( FILE *restrict stream,
+              const wchar_t *restrict format, ... );
+		 (since C99)
(3) 
int swprintf( wchar_t *buffer, size_t bufsz,
+              const wchar_t *format, ... );
+		 (since C95)
(until C99) 
int swprintf( wchar_t *restrict buffer, size_t bufsz,
+              const wchar_t *restrict format, ... );
+		 (since C99) 
int wprintf_s( const wchar_t *restrict format, ... );
+		 (4) (since C11) 
int fwprintf_s( FILE *restrict stream,
+                const wchar_t *restrict format, ... );
+		 (5) (since C11) 
int swprintf_s( wchar_t *restrict buffer, rsize_t bufsz,
+                const wchar_t *restrict format, ... );
+		 (6) (since C11) 
int snwprintf_s( wchar_t *restrict s, rsize_t n,
+                 const wchar_t *restrict format, ... );
+		 (7) (since C11)

Loads the data from the given locations, converts them to wide string equivalents and writes the results to a variety of sinks.

+
+1) Writes the results to stdout.
+2) Writes the results to a file stream stream.
+3) If bufsz is greater than zero, writes the results to a wide string buffer. At most bufsz-1 wide characters are written followed by null wide character. If bufsz is zero, nothing is written (and buffer may be a null pointer).
+4-6) Same as (1-3), except that the following errors are detected at runtime and call the currently installed constraint handler function: +
+7) Same as (6), except it will truncate the result to fit within the array pointed to by s. As with all bounds-checked functions, wprintf_s , fwprintf_s, swprintf_s, and snwprintf_s are only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <stdio.h>.

Parameters

+ + + + + +
stream - output file stream to write to
buffer - pointer to a wide character string to write to
bufsz - up to bufsz-1 wide characters may be written, plus the null terminator
format - pointer to a null-terminated wide string specifying how to interpret the data
... - arguments specifying data to print. If any argument after default argument promotions is not the type expected by the corresponding conversion specifier, or if there are fewer arguments than required by format, the behavior is undefined. If there are more arguments than required by format, the extraneous arguments are evaluated and ignored.


The format string consists of ordinary wide characters (except %), which are copied unchanged into the output stream, and conversion specifications. Each conversion specification has the following format:

+

The following format specifiers are available:

+ + + + + + + + + + + + + + + + +
Conversion
Specifier 		Explanation Expected
Argument Type
+Length
Modifier→ 		+hh

(C99)

+		 +h (none) +l +ll

(C99)

+		 +j

(C99)

+		 +z

(C99)

+		 +t

(C99)

+		 +L
+% Writes literal %. The full conversion specification must be %%. N/A N/A N/A N/A N/A N/A N/A N/A N/A
+c Writes a single character.

The argument is first converted to wchar_t as if by calling btowc. If the l modifier is used, the wint_t argument is first converted to wchar_t.

+		 N/A N/A +
int
 +
wint_t
 N/A N/A N/A N/A N/A
+s Writes a character string

The argument must be a pointer to the initial element of a character array containing a multibyte character sequence beginning in the initial shift state, which is converted to wide character array as if by a call to mbrtowc with zero-initialized conversion state. Precision specifies the maximum number of wide characters to be written. If Precision is not specified, writes every wide characters up to and not including the first null terminator. If the l specifier is used, the argument must be a pointer to the initial element of an array of wchar_t.

+		 N/A N/A +
char*
 +
wchar_t*
 N/A N/A N/A N/A N/A
+d
i 		Converts a signed integer into decimal representation [-]dddd.

Precision specifies the minimum number of digits to appear. The default precision is 1.

If both the converted value and the precision are ​0​ the conversion results in no characters.

+		 +
signed char
 +
short
 +
int
 +
long
 +
long long
 + +
signed size_t +
 + N/A
+o Converts an unsigned integer into octal representation oooo.

Precision specifies the minimum number of digits to appear. The default precision is 1. If both the converted value and the precision are ​0​ the conversion results in no characters. In the alternative implementation precision is increased if necessary, to write one leading zero. In that case if both the converted value and the precision are ​0​, single ​0​ is written.

+		 +
unsigned char
 +
unsigned short
 +
unsigned int
 +
unsigned long
 +
unsigned long long
 + + +
unsigned version of ptrdiff_t +
 N/A
+x
X 		Converts an unsigned integer into hexadecimal representation hhhh.

For the x conversion letters abcdef are used.
For the X conversion letters ABCDEF are used.
Precision specifies the minimum number of digits to appear. The default precision is 1. If both the converted value and the precision are ​0​ the conversion results in no characters. In the alternative implementation 0x or 0X is prefixed to results if the converted value is nonzero.

+		 N/A
+u Converts an unsigned integer into decimal representation dddd.

Precision specifies the minimum number of digits to appear. The default precision is 1. If both the converted value and the precision are ​0​ the conversion results in no characters.

+		 N/A
+f
F 		Converts floating-point number to the decimal notation in the style [-]ddd.ddd.

Precision specifies the exact number of digits to appear after the decimal point character. The default precision is 6. In the alternative implementation decimal point character is written even if no digits follow it. For infinity and not-a-number conversion style see notes.

+		 N/A N/A +
double
 +
+double(C99) +
 N/A N/A N/A N/A +
long double
+e
E 		Converts floating-point number to the decimal exponent notation.

For the e conversion style [-]d.ddde±dd is used.
For the E conversion style [-]d.dddE±dd is used.
The exponent contains at least two digits, more digits are used only if necessary. If the value is ​0​, the exponent is also ​0​. Precision specifies the exact number of digits to appear after the decimal point character. The default precision is 6. In the alternative implementation decimal point character is written even if no digits follow it. For infinity and not-a-number conversion style see notes.

+		 N/A N/A N/A N/A N/A N/A
+a
A

(C99)

+		 Converts floating-point number to the hexadecimal exponent notation.

For the a conversion style [-]0xh.hhhp±d is used.
For the A conversion style [-]0Xh.hhhP±d is used.
The first hexadecimal digit is not 0 if the argument is a normalized floating point value. If the value is ​0​, the exponent is also ​0​. Precision specifies the exact number of digits to appear after the hexadecimal point character. The default precision is sufficient for exact representation of the value. In the alternative implementation decimal point character is written even if no digits follow it. For infinity and not-a-number conversion style see notes.

+		 N/A N/A N/A N/A N/A N/A
+g
G 		Converts floating-point number to decimal or decimal exponent notation depending on the value and the precision.

For the g conversion style conversion with style e or f will be performed.
For the G conversion style conversion with style E or F will be performed.
Let P equal the precision if nonzero, 6 if the precision is not specified, or 1 if the precision is ​0​. Then, if a conversion with style E would have an exponent of X:

+
    +
  • if P > X ≥ −4, the conversion is with style f or F and precision P − 1 − X.
    • +
  • otherwise, the conversion is with style e or E and precision P − 1.
    • +

Unless alternative representation is requested the trailing zeros are removed, also the decimal point character is removed if no fractional part is left. For infinity and not-a-number conversion style see notes.

+		 N/A N/A N/A N/A N/A N/A
+n Returns the number of characters written so far by this call to the function.

The result is written to the value pointed to by the argument. The specification may not contain any flag, field width, or precision.



+		 +
signed char*
 +
short*
 +
int*
 +
long*
 +
long long*
 + +
signed size_t* +
 + N/A
+p Writes an implementation defined character sequence defining a pointer. N/A N/A +void* N/A N/A N/A N/A N/A N/A

The floating point conversion functions convert infinity to inf or infinity. Which one is used is implementation defined.

+

Not-a-number is converted to nan or nan(char_sequence). Which one is used is implementation defined.

+

The conversions F, E, G, A output INF, INFINITY, NAN instead.

+

Even though %c expects int argument, it is safe to pass a char because of the integer promotion that takes place when a variadic function is called.

+

The correct conversion specifications for the fixed-width character types (int8_t, etc) are defined in the header <inttypes.h> (although PRIdMAX, PRIuMAX, etc is synonymous with %jd, %ju, etc).

+

The memory-writing conversion specifier %n is a common target of security exploits where format strings depend on user input and is not supported by the bounds-checked printf_s family of functions.

+

There is a sequence point after the action of each conversion specifier; this permits storing multiple %n results in the same variable or, as an edge case, printing a string modified by an earlier %n within the same call.

+

If a conversion specification is invalid, the behavior is undefined.

+

Return value

+1,2) Number of wide characters written if successful or negative value if an error occurred.
+3) Number of wide characters written (not counting the terminating null wide character) if successful or negative value if an encoding error occurred or if the number of characters to be generated was equal or greater than size (including when size is zero).
+4,5) Number of wide characters written if successful or negative value if an error occurred.
+6) Number of wide characters (not counting the terminating null) that were written to buffer. Returns a negative value on encoding errors and on overflow. Returns zero on all other errors.
+7) Number of wide characters (not counting the terminating null) that would have been written to buffer had bufsz been sufficiently large, or a negative value if an error occurs. (meaning, write was successful and complete only if the return is nonnegative and less than bufsz)

Notes

While narrow strings provide snprintf, which makes it possible to determine the required output buffer size, there is no equivalent for wide strings (until snwprintf_s)(since C11), and in order to determine the buffer size, the program may need to call swprintf, check the result value, and reallocate a larger buffer, trying again until successful.

+

snwprintf_s, unlike swprintf_s, will truncate the result to fit within the array pointed to by buffer, even though truncation is treated as an error by most bounds-checked functions.

+

Example

#include <locale.h>
+#include <wchar.h>
+ 
+int main(void)
+{
+    char narrow_str[] = "z\u00df\u6c34\U0001f34c";
+                    // or "zß水🍌"
+                    // or "\x7a\xc3\x9f\xe6\xb0\xb4\xf0\x9f\x8d\x8c";
+    wchar_t warr[29]; // the expected string is 28 characters plus 1 null terminator
+    setlocale(LC_ALL, "en_US.utf8");
+    swprintf(warr, sizeof warr/sizeof *warr,
+              L"Converted from UTF-8: '%s'", narrow_str);
+    wprintf(L"%ls\n", warr);
+}

Output:

+
Converted from UTF-8: 'zß水🍌'

References

See also

+ + + +
+
(C99)(C11)(C11)(C11)(C11)
 prints formatted output to stdout, a file stream or a buffer
(function)
+
(C95)(C95)(C95)(C11)(C11)(C11)(C11)
 prints formatted wide character output to stdout, a file stream
or a buffer using variable argument list
(function)
+
(C95)
 writes a wide string to a file stream
(function)
C++ documentation for wprintf, fwprintf, swprintf
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/fwprintf +

+
diff --git a/devdocs/c/io%2Ffwrite.html b/devdocs/c/io%2Ffwrite.html new file mode 100644 index 00000000..35104178 --- /dev/null +++ b/devdocs/c/io%2Ffwrite.html @@ -0,0 +1,59 @@ +

fwrite

Defined in header <stdio.h> 
size_t fwrite( const void* buffer, size_t size, size_t count,
+               FILE* stream );
+		 (until C99) 
size_t fwrite( const void* restrict buffer, size_t size, size_t count,
+               FILE* restrict stream );
+		 (since C99)

Writes count of objects from the given array buffer to the output stream stream. The objects are written as if by reinterpreting each object as an array of unsigned char and calling fputc size times for each object to write those unsigned chars into stream, in order. The file position indicator for the stream is advanced by the number of characters written.

+

If an error occurs, the resulting value of the file position indicator for the stream is indeterminate.

+

Parameters

+ + + + +
buffer - pointer to the first object in the array to be written
size - size of each object
count - the number of the objects to be written
stream - pointer to the output stream

Return value

The number of objects written successfully, which may be less than count if an error occurs.

+

If size or count is zero, fwrite returns zero and performs no other action.

+

Example

#include <assert.h>
+#include <stdio.h>
+#include <stdlib.h>
+ 
+enum { SIZE = 5 };
+ 
+int main(void)
+{
+    double a[SIZE] = {1, 2, 3, 4, 5};
+    FILE* f1 = fopen("file.bin", "wb");
+    assert(f1);
+    size_t r1 = fwrite(a, sizeof a[0], SIZE, f1);
+    printf("wrote %zu elements out of %d requested\n", r1, SIZE);
+    fclose(f1);
+ 
+    double b[SIZE];
+    FILE* f2 = fopen("file.bin", "rb");
+    size_t r2 = fread(b, sizeof b[0], SIZE, f2);
+    fclose(f2);
+    printf("read back: ");
+    for (size_t i = 0; i < r2; ++i)
+        printf("%0.2f ", b[i]);
+}

Output:

+
wrote 5 elements out of 5 requested
+read back: 1.00 2.00 3.00 4.00 5.00

References

See also

+ + + +
+
(C99)(C11)(C11)(C11)(C11)
 prints formatted output to stdout, a file stream or a buffer
(function)
writes a character string to a file stream
(function)
reads from a file
(function)
C++ documentation for fwrite
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/fwrite +

+
diff --git a/devdocs/c/io%2Ffwscanf.html b/devdocs/c/io%2Ffwscanf.html new file mode 100644 index 00000000..69582d63 --- /dev/null +++ b/devdocs/c/io%2Ffwscanf.html @@ -0,0 +1,216 @@ +

wscanf, fwscanf, swscanf, wscanf_s, fwscanf_s, swscanf_s

Defined in header <wchar.h>
(1) 
int wscanf( const wchar_t *format, ... );
+		 (since C95)
(until C99) 
int wscanf( const wchar_t *restrict format, ... );
+		 (since C99)
(2) 
int fwscanf( FILE *stream, const wchar_t *format, ... );
+		 (since C95)
(until C99) 
int fwscanf( FILE *restrict stream,
+             const wchar_t *restrict format, ... );
+		 (since C99)
(3) 
int swscanf( const wchar_t *buffer, const wchar_t *format, ... );
+		 (since C95)
(until C99) 
int swscanf( const wchar_t *restrict buffer,
+             const wchar_t *restrict format, ... );
+		 (since C99) 
int wscanf_s( const wchar_t *restrict format, ...);
+		 (4) (since C11) 
int fwscanf_s( FILE *restrict stream,
+               const wchar_t *restrict format, ...);
+		 (5) (since C11) 
int swscanf_s( const wchar_t *restrict s,
+               const wchar_t *restrict format, ...);
+		 (6) (since C11)

Reads data from the a variety of sources, interprets it according to format and stores the results into given locations.

+
+1) Reads the data from stdin.
+2) Reads the data from file stream stream.
+3) Reads the data from null-terminated wide string buffer. Reaching the end of the string is equivalent to reaching the end-of-file condition for fwscanf +
+4-6) Same as (1-3), except that %c, %s, and %[ conversion specifiers each expect two arguments (the usual pointer and a value of type rsize_t indicating the size of the receiving array, which may be 1 when reading with a %lc into a single wide character) and except that the following errors are detected at runtime and call the currently installed constraint handler function:
+
+
    +
  • any of the arguments of pointer type is a null pointer
    • +
  • format, stream, or buffer is a null pointer
    • +
  • the number of characters that would be written by %c, %s, or %[, plus the terminating null character, would exceed the second (rsize_t) argument provided for each of those conversion specifiers
    • +
  • optionally, any other detectable error, such as unknown conversion specifier
    • +
+
As all bounds-checked functions, wscanf_s, fwscanf_s, and swscanf_s are only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <wchar.h>.
+
+

Parameters

+ + + + +
stream - input file stream to read from
buffer - pointer to a null-terminated wide string to read from
format - pointer to a null-terminated wide string specifying how to read the input
... - receiving arguments.


The format string consists of

+

The following format specifiers are available:

+ + + + + + + + + + + + + + + +
Conversion
specifier 		Explanation Argument type
+Length modifier → +hh

(C99)

+		 +h (none) +l +ll

(C99)

+		 +j

(C99)

+		 +z

(C99)

+		 +t

(C99)

+		 +L
+% Matches literal %. N/A N/A N/A N/A N/A N/A N/A N/A N/A
+c Matches a character or a sequence of characters.

If a width specifier is used, matches exactly width wide characters (the argument must be a pointer to an array with sufficient room). Unlike %s and %[, does not append the null character to the array.

+		 N/A N/A +
char*
 +
wchar_t*
 N/A N/A N/A N/A N/A
+s Matches a sequence of non-whitespace characters (a string).

If width specifier is used, matches up to width or until the first whitespace character, whichever appears first. Always stores a null character in addition to the characters matched (so the argument array must have room for at least width+1 characters)

+
+[set] Matches a non-empty sequence of character from set of characters.

If the first character of the set is ^, then all characters not in the set are matched. If the set begins with ] or ^] then the ] character is also included into the set. It is implementation-defined whether the character - in the non-initial position in the scanset may be indicating a range, as in [0-9]. If width specifier is used, matches only up to width. Always stores a null character in addition to the characters matched (so the argument array must have room for at least width+1 characters)

+
+d Matches a decimal integer.

The format of the number is the same as expected by wcstol with the value 10 for the base argument

+		 +
+signed char* or unsigned char* +
 +
+signed short* or unsigned short* +
 +
+signed int* or unsigned int* +
 +
+signed long* or unsigned long* +
 +
+signed long long* or unsigned long long* +
 + + + N/A
+i Matches an integer.

The format of the number is the same as expected by wcstol with the value ​0​ for the base argument (base is determined by the first characters parsed)

+
+u Matches an unsigned decimal integer.

The format of the number is the same as expected by wcstoul with the value 10 for the base argument.

+
+o Matches an unsigned octal integer.

The format of the number is the same as expected by wcstoul with the value 8 for the base argument

+
+x, X Matches an unsigned hexadecimal integer.

The format of the number is the same as expected by wcstoul with the value 16 for the base argument

+
+n Returns the number of characters read so far.

No input is consumed. Does not increment the assignment count. If the specifier has assignment-suppressing operator defined, the behavior is undefined

+
+a, A(C99)
e, E
f, F(C99)
g, G 		Matches a floating-point number.

The format of the number is the same as expected by wcstof

+		 N/A N/A +
float*
 +
double*
 N/A N/A N/A N/A +
long double*
+p Matches implementation defined character sequence defining a pointer.

printf family of functions should produce the same sequence using %p format specifier

+		 N/A N/A +
void**
 N/A N/A N/A N/A N/A N/A

For every conversion specifier other than n, the longest sequence of input characters which does not exceed any specified field width and which either is exactly what the conversion specifier expects or is a prefix of a sequence it would expect, is what's consumed from the stream. The first character, if any, after this consumed sequence remains unread. If the consumed sequence has length zero or if the consumed sequence cannot be converted as specified above, the matching failure occurs unless end-of-file, an encoding error, or a read error prevented input from the stream, in which case it is an input failure.

+

All conversion specifiers other than [, c, and n consume and discard all leading whitespace characters (determined as if by calling iswspace) before attempting to parse the input. These consumed characters do not count towards the specified maximum field width.

+

If the length specifier l is not used, the conversion specifiers c, s, and [ perform wide-to-multibyte character conversion as if by calling wcrtomb with an mbstate_t object initialized to zero before the first character is converted.

+

The conversion specifiers s and [ always store the null terminator in addition to the matched characters. The size of the destination array must be at least one greater than the specified field width. The use of %s or %[, without specifying the destination array size, is as unsafe as gets.

+

The correct conversion specifications for the fixed-width integer types (int8_t, etc) are defined in the header <inttypes.h> (although SCNdMAX, SCNuMAX, etc is synonymous with %jd, %ju, etc).

+

There is a sequence point after the action of each conversion specifier; this permits storing multiple fields in the same "sink" variable.

+

When parsing an incomplete floating-point value that ends in the exponent with no digits, such as parsing "100er" with the conversion specifier %f, the sequence "100e" (the longest prefix of a possibly valid floating-point number) is consumed, resulting in a matching error (the consumed sequence cannot be converted to a floating-point number), with "r" remaining. Some existing implementations do not follow this rule and roll back to consume only "100", leaving "er", e.g. glibc bug 1765.

+

Return value

+1-3) Number of receiving arguments successfully assigned, or EOF if read failure occurs before the first receiving argument was assigned.
+4-6) Same as (1-3), except that EOF is also returned if there is a runtime constraint violation.

Example

#include <stdio.h>
+#include <wchar.h>
+#include <string.h>
+ 
+#define NUM_VARS   3
+#define ERR_READ   2
+#define ERR_WRITE  3
+ 
+int main(void) {
+    wchar_t state[64];
+    wchar_t capital[64];
+    unsigned int population = 0;
+    int elevation = 0;
+    int age = 0;
+    float pi = 0;
+ 
+#if INTERACTIVE_MODE
+    wprintf(L"Enter state, age, and pi value: ");
+    if (wscanf(L"%ls%d%f", state, &age, &pi) != NUM_VARS) {
+        fprintf(stderr, "Error reading input.\n");
+        return ERR_READ;
+    }
+#else
+    wchar_t* input = L"California 170 3.141592";
+    if (swscanf(input, L"%ls%d%f", state, &age, &pi) != NUM_VARS) {
+        fprintf(stderr, "Error reading input.\n");
+        return ERR_READ;
+    }
+#endif
+    wprintf(L"State: %ls\nAge  : %d years\nPi   : %.5f\n\n", state, age, pi);
+ 
+    FILE* fp = tmpfile();
+    if (fp) {
+        // write some data to temp file
+        if (!fwprintf(fp, L"Mississippi Jackson 420000 807")) {
+            fprintf(stderr, "Error writing to file.\n");
+            fclose(fp);
+            return ERR_WRITE;
+        }
+        // rewind file pointer
+        rewind(fp);
+ 
+        // read data into variables
+        fwscanf(fp, L"%ls%ls%u%d", state, capital, &population, &elevation);
+        wprintf(L"State  : %ls\nCapital: %ls\nJackson population (in 2020): %u\n"
+                L"Highest elevation: %dft\n",
+                state, capital, population, elevation);
+        fclose(fp);
+    }
+}

Possible output:

+
State: California
+Age  : 170 years
+Pi   : 3.14159
+ 
+State  : Mississippi
+Capital: Jackson
+Jackson population (in 2020): 420000
+Highest elevation: 807ft

References

See also

+ +
+
(C99)(C99)(C99)(C11)(C11)(C11)
 reads formatted wide character input from stdin, a file stream
or a buffer using variable argument list
(function)
C++ documentation for wscanf, fwscanf, swscanf
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/fwscanf +

+
diff --git a/devdocs/c/io%2Fgetchar.html b/devdocs/c/io%2Fgetchar.html new file mode 100644 index 00000000..51e96aa8 --- /dev/null +++ b/devdocs/c/io%2Fgetchar.html @@ -0,0 +1,49 @@ +

getchar

Defined in header <stdio.h> 
int getchar( void );
+

Reads the next character from stdin.

+

Equivalent to getc(stdin).

+

Parameters

(none)

+

Return value

The obtained character on success or EOF on failure.

+

If the failure has been caused by end-of-file condition, additionally sets the eof indicator (see feof()) on stdin. If the failure has been caused by some other error, sets the error indicator (see ferror()) on stdin.

+

Example

+

Demonstrates getchar with error checking

+
#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    for (int ch; (ch = getchar()) != EOF;) // read/print "abcde" from stdin
+        printf("%c", ch);
+ 
+    // Test reason for reaching EOF.
+    if (feof(stdin)) // if failure caused by end-of-file condition
+        puts("End of file reached");
+    else if (ferror(stdin)) // if failure caused by some other error
+    {
+        perror("getchar()");
+        fprintf(stderr, "getchar() failed in file %s at line # %d\n",
+                __FILE__, __LINE__ - 9);
+        exit(EXIT_FAILURE);
+    }
+ 
+    return EXIT_SUCCESS;
+}

Possible output:

+
abcde
+End of file reached

References

See also

+ +
gets a character from a file stream
(function)
C++ documentation for getchar
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/getchar +

+
diff --git a/devdocs/c/io%2Fgets.html b/devdocs/c/io%2Fgets.html new file mode 100644 index 00000000..3dfd399d --- /dev/null +++ b/devdocs/c/io%2Fgets.html @@ -0,0 +1,40 @@ +

gets, gets_s

Defined in header <stdio.h> 
char *gets( char *str );
+		 (1) (removed in C11) 
char *gets_s( char *str, rsize_t n );
+		 (2) (since C11)
+1) Reads stdin into the character array pointed to by str until a newline character is found or end-of-file occurs. A null character is written immediately after the last character read into the array. The newline character is discarded but not stored in the buffer.
+2) Reads characters from stdin until a newline is found or end-of-file occurs. Writes only at most n-1 characters into the array pointed to by str, and always writes the terminating null character (unless str is a null pointer). The newline character, if found, is discarded and does not count toward the number of characters written to the buffer.
+
The following errors are detected at runtime and call the currently installed constraint handler function:
    +
  • n is zero
    • +
  • n is greater than RSIZE_MAX
    • +
  • str is a null pointer
    • +
  • endline or eof not encountered after storing n-1 characters to the buffer.
    • +
+
In any case, gets_s first finishes reading and discarding the characters from stdin until new-line character, end-of-file condition, or read error before calling the constraint handler.
+
As with all bounds-checked functions, gets_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <stdio.h>.
+
+

Parameters

+ +
str - character string to be written

Return value

str on success, a null pointer on failure.

+

If the failure has been caused by end of file condition, additionally sets the eof indicator (see feof()) on stdin. If the failure has been caused by some other error, sets the error indicator (see ferror()) on stdin.

+

Notes

The gets() function does not perform bounds checking, therefore this function is extremely vulnerable to buffer-overflow attacks. It cannot be used safely (unless the program runs in an environment which restricts what can appear on stdin). For this reason, the function has been deprecated in the third corrigendum to the C99 standard and removed altogether in the C11 standard. fgets() and gets_s() are the recommended replacements.

+

Never use gets().

+

References

See also

+ + + + +
+
(C11)(C11)(C11)
 reads formatted input from stdin, a file stream or a buffer
(function)
gets a character string from a file stream
(function)
writes a character string to a file stream
(function)
+
(dynamic memory TR)
 read from a stream into an automatically resized buffer until delimiter/end of line
(function)
C++ documentation for gets
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/gets +

+
diff --git a/devdocs/c/io%2Fgetwchar.html b/devdocs/c/io%2Fgetwchar.html new file mode 100644 index 00000000..072a1648 --- /dev/null +++ b/devdocs/c/io%2Fgetwchar.html @@ -0,0 +1,19 @@ +

getwchar

Defined in header <wchar.h> 
wint_t getwchar(void);
+		 (since C95)

Reads the next wide character from stdin.

+

Parameters

(none)

+

Return value

the obtained wide character or WEOF if an error has occurred or the end of file reached

+

References

See also

+ + +
reads a character from stdin
(function)
+
(C95)
 gets a wide character from a file stream
(function)
C++ documentation for getwchar
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/getwchar +

+
diff --git a/devdocs/c/io%2Fperror.html b/devdocs/c/io%2Fperror.html new file mode 100644 index 00000000..914c9153 --- /dev/null +++ b/devdocs/c/io%2Fperror.html @@ -0,0 +1,36 @@ +

perror

Defined in header <stdio.h> 
void perror( const char *s );
+

Prints a textual description of the error code currently stored in the system variable errno to stderr.

+

The description is formed by concatenating the following components:

+

Parameters

+ +
s - pointer to a null-terminated string with explanatory message

Return value

(none)

+

Example

#include <stdio.h>
+ 
+int main(void)
+{
+    FILE *f = fopen("non_existent", "r");
+    if (f == NULL) {
+        perror("fopen() failed");
+    } else {
+        fclose(f);
+    }
+}

Possible output:

+
fopen() failed: No such file or directory

References

See also

+ +
+
(C11)(C11)
 returns a text version of a given error code
(function)
C++ documentation for perror
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/perror +

+
diff --git a/devdocs/c/io%2Fputchar.html b/devdocs/c/io%2Fputchar.html new file mode 100644 index 00000000..aa070ceb --- /dev/null +++ b/devdocs/c/io%2Fputchar.html @@ -0,0 +1,57 @@ +

putchar

Defined in header <stdio.h> 
int putchar( int ch );
+

Writes a character ch to stdout. Internally, the character is converted to unsigned char just before being written.

+

Equivalent to putc(ch, stdout).

+

Parameters

+ +
ch - character to be written

Return value

On success, returns the written character.

+

On failure, returns EOF and sets the error indicator (see ferror()) on stdout.

+

Example

+

Shows putchar with error checking

+
#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    int ret_code = 0;
+    for (char c = 'a'; (ret_code != EOF) && (c != 'z'); c++)
+        ret_code = putchar(c);
+ 
+    // Test whether EOF was reached.
+    if (ret_code == EOF && ferror(stdout))
+    {
+        fprintf(stderr, "putchar() failed in file %s at line # %d\n",
+                __FILE__, __LINE__ - 6);
+        perror("putchar()");
+        exit(EXIT_FAILURE);
+    }
+    putchar('\n');
+ 
+    // putchar return value is not equal to the argument
+    int r = 0x1070;
+    printf("\n0x%x\n", r);
+    r = putchar(r);
+    printf("\n0x%x\n", r);
+}

Output:

+
abcdefghijklmnopqrstuvwxy
+ 
+0x1070
+p
+0x70

References

See also

+ +
writes a character to a file stream
(function)
C++ documentation for putchar
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/putchar +

+
diff --git a/devdocs/c/io%2Fputs.html b/devdocs/c/io%2Fputs.html new file mode 100644 index 00000000..40c78ddb --- /dev/null +++ b/devdocs/c/io%2Fputs.html @@ -0,0 +1,40 @@ +

puts

Defined in header <stdio.h> 
int puts( const char* str );
+

Writes every character from the null-terminated string str and one additional newline character '\n' to the output stream stdout, as if by repeatedly executing fputc.

+

The terminating null character from str is not written.

+

Parameters

+ +
str - character string to be written

Return value

On success, returns a non-negative value.

+

On failure, returns EOF and sets the error indicator (see ferror()) on stream.

+

Notes

The puts function appends the newline character to the output, while fputs function does not.

+

Different implementations return different non-negative numbers: some return the last character written, some return the number of characters written (or INT_MAX if the string was longer than that), some simply return a non-negative constant.

+

A typical cause of failure for puts is running out of space on the file system, when stdout is redirected to a file.

+

Example

#include <stdio.h>
+ 
+int main(void)
+{
+    int rc = puts("Hello World");
+ 
+    if (rc == EOF)
+        perror("puts()"); // POSIX requires that errno is set
+}

Output:

+
Hello World

References

See also

+ + +
writes a character string to a file stream
(function)
+
(C99)(C11)(C11)(C11)(C11)
 prints formatted output to stdout, a file stream or a buffer
(function)
C++ documentation for puts
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/puts +

+
diff --git a/devdocs/c/io%2Fputwchar.html b/devdocs/c/io%2Fputwchar.html new file mode 100644 index 00000000..9c73d395 --- /dev/null +++ b/devdocs/c/io%2Fputwchar.html @@ -0,0 +1,51 @@ +

putwchar

Defined in header <wchar.h> 
wint_t putwchar( wchar_t ch );
+		 (since C95)

Writes a wide character ch to stdout.

+

Parameters

+ +
ch - wide character to be written

Return value

ch on success, WEOF on failure.

+

Example

#include <locale.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <wchar.h>
+ 
+int main()
+{
+    setlocale(LC_ALL, "en_US.utf8");
+ 
+    const wchar_t data[] =
+    {
+        L'\u2200', // Unicode name: "FOR ALL"
+        L'∀',
+        L'\n',
+    };
+ 
+    for (size_t t = 0; t != (sizeof data / sizeof(wchar_t)); ++t)
+    {
+        if (putwchar(data[t]) == WEOF)
+        {
+            puts("I/O error in putwchar");
+            return EXIT_FAILURE;
+        }
+    }
+ 
+    return EXIT_SUCCESS;
+}

Possible output:

+
∀∀

References

See also

+ + +
writes a character to stdout
(function)
+
(C95)
 writes a wide character to a file stream
(function)
C++ documentation for putwchar
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/putwchar +

+
diff --git a/devdocs/c/io%2Fremove.html b/devdocs/c/io%2Fremove.html new file mode 100644 index 00000000..5813a48f --- /dev/null +++ b/devdocs/c/io%2Fremove.html @@ -0,0 +1,61 @@ +

remove

Defined in header <stdio.h> 
int remove( const char* fname );
+

Deletes the file identified by character string pointed to by fname.

+

If the file is currently open by this or another process, the behavior of this function is implementation-defined (in particular, POSIX systems unlink the file name although the file system space is not reclaimed until the last running process closes the file; Windows does not allow the file to be deleted).

+

Parameters

+ +
fname - pointer to a null-terminated string containing the path identifying the file to delete

Return value

​0​ upon success or non-zero value on error.

+

Notes

POSIX specifies many additional details for the behavior of this function.

+

Example

#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    FILE* fp = fopen("file1.txt", "w"); // create file
+    if (!fp)
+    {
+        perror("file1.txt");
+        return EXIT_FAILURE;
+    }
+    puts("Created file1.txt");
+    fclose(fp);
+ 
+    int rc = remove("file1.txt");
+    if (rc)
+    {
+        perror("remove");
+        return EXIT_FAILURE;
+    }
+    puts("Removed file1.txt");
+ 
+    fp = fopen("file1.txt", "r"); // Failure: file does not exist
+    if (!fp)
+        perror("Opening removed file failed");
+ 
+    rc = remove("file1.txt"); // Failure: file does not exist
+    if (rc)
+        perror("Double-remove failed");
+ 
+    return EXIT_SUCCESS;
+}

Possible output:

+
Created file1.txt
+Removed file1.txt
+Opening removed file failed: No such file or directory
+Double-remove failed: No such file or directory

References

See also

+ +
renames a file
(function)
C++ documentation for remove
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/remove +

+
diff --git a/devdocs/c/io%2Frename.html b/devdocs/c/io%2Frename.html new file mode 100644 index 00000000..3997966b --- /dev/null +++ b/devdocs/c/io%2Frename.html @@ -0,0 +1,59 @@ +

rename

Defined in header <stdio.h> 
int rename( const char* old_filename, const char* new_filename );
+

Changes the filename of a file. The file is identified by character string pointed to by old_filename. The new filename is identified by character string pointed to by new_filename.

+

If new_filename exists, the behavior is implementation-defined.

+

Parameters

+ + +
old_filename - pointer to a null-terminated string containing the path identifying the file to rename
new_filename - pointer to a null-terminated string containing the new path of the file

Return value

​0​ upon success or non-zero value on error.

+

Notes

POSIX specifies many additional details on the semantics of this function.

+

Example

#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    FILE* fp = fopen("from.txt", "w"); // create file "from.txt"
+    if (!fp)
+    {
+        perror("from.txt");
+        return EXIT_FAILURE;
+    }
+    fputc('a', fp); // write to "from.txt"
+    fclose(fp);
+ 
+    int rc = rename("from.txt", "to.txt");
+    if (rc)
+    {
+        perror("rename");
+        return EXIT_FAILURE;
+    }
+ 
+    fp = fopen("to.txt", "r");
+    if(!fp)
+    {
+        perror("to.txt");
+        return EXIT_FAILURE;
+    }
+    printf("%c\n", fgetc(fp)); // read from "to.txt"
+    fclose(fp);
+ 
+    return EXIT_SUCCESS;
+}

Possible output:

+
a

References

See also

+ +
erases a file
(function)
C++ documentation for rename
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/rename +

+
diff --git a/devdocs/c/io%2Frewind.html b/devdocs/c/io%2Frewind.html new file mode 100644 index 00000000..103aceef --- /dev/null +++ b/devdocs/c/io%2Frewind.html @@ -0,0 +1,51 @@ +

rewind

Defined in header <stdio.h> 
void rewind( FILE *stream );
+

Moves the file position indicator to the beginning of the given file stream.

+

The function is equivalent to fseek(stream, 0, SEEK_SET);, except that end-of-file and error indicators are cleared.

+

The function drops any effects from previous calls to ungetc.

+

Parameters

+ +
stream - file stream to modify

Return value

(none)

+

Example

+

This example shows how to read a file twice

+
#include <stdio.h>
+ 
+char str[20];
+ 
+int main(void)
+{
+    FILE *f;
+    char ch;
+ 
+    f = fopen("file.txt", "w");
+    for (ch = '0'; ch <= '9'; ch++) {
+        fputc(ch, f);
+    }
+    fclose(f);
+ 
+    f = fopen("file.txt", "r");
+    fread(str, 1, 10, f);
+    puts(str);
+ 
+    rewind(f);
+    fread(str, 1, 10, f);
+    puts(str);
+    fclose(f);
+ 
+    return 0;
+}

Output:

+
0123456789
+0123456789

References

See also

+ +
moves the file position indicator to a specific location in a file
(function)
C++ documentation for rewind
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/rewind +

+
diff --git a/devdocs/c/io%2Fsetbuf.html b/devdocs/c/io%2Fsetbuf.html new file mode 100644 index 00000000..fb5c4a93 --- /dev/null +++ b/devdocs/c/io%2Fsetbuf.html @@ -0,0 +1,46 @@ +

setbuf

Defined in header <stdio.h> 
void setbuf( FILE          *stream, char          *buffer );
+		 (until C99) 
void setbuf( FILE *restrict stream, char *restrict buffer );
+		 (since C99) 
#define BUFSIZ     /*unspecified*/
+

Sets the internal buffer to use for stream operations. It should be at least BUFSIZ characters long.

+

If buffer is not null, equivalent to setvbuf(stream, buffer, _IOFBF, BUFSIZ).

+

If buffer is null, equivalent to setvbuf(stream, NULL, _IONBF, 0), which turns off buffering.

+

Parameters

+ + +
stream - the file stream to set the buffer to
buffer - pointer to a buffer for the stream to use. If a null pointer is supplied, the buffering is turned off

Return value

None.

+

Notes

If BUFSIZ is not the appropriate buffer size, setvbuf can be used to change it.

+

setvbuf should also be used to detect errors, since setbuf does not indicate success or failure.

+

This function may only be used after stream has been associated with an open file, but before any other operation (other than a failed call to setbuf/setvbuf).

+

A common error is setting the buffer of stdin or stdout to an array whose lifetime ends before the program terminates:

+
int main(void) {
+    char buf[BUFSIZ];
+    setbuf(stdin, buf);
+} // lifetime of buf ends, undefined behavior

Example

+

setbuf may be used to disable buffering on streams that require immediate output.

+
#include <stdio.h>
+#include <threads.h>
+ 
+int main(void)
+{
+    setbuf(stdout, NULL); // unbuffered stdout
+    putchar('a'); // 'a' appears immediately if stdout is unbuffered
+    thrd_sleep(&(struct timespec){.tv_sec=1}, NULL); // sleep 1 sec
+    putchar('b'); 
+}

Output:

+
ab

References

See also

+ +
sets the buffer and its size for a file stream
(function)
C++ documentation for setbuf
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/setbuf +

+
diff --git a/devdocs/c/io%2Fsetvbuf.html b/devdocs/c/io%2Fsetvbuf.html new file mode 100644 index 00000000..25309406 --- /dev/null +++ b/devdocs/c/io%2Fsetvbuf.html @@ -0,0 +1,85 @@ +

setvbuf

Defined in header <stdio.h> 
int setvbuf( FILE *         stream, char *         buffer, 
+             int mode, size_t size );
+		 (until C99) 
int setvbuf( FILE *restrict stream, char *restrict buffer, 
+             int mode, size_t size );
+		 (since C99) 
#define _IOFBF     /*unspecified*/
+#define _IOLBF     /*unspecified*/
+#define _IONBF     /*unspecified*/
+

Changes the buffering mode of the given file stream stream as indicated by the argument mode. In addition,

+

Parameters

+ + + + +
stream - the file stream to set the buffer to
buffer - pointer to a buffer for the stream to use or null pointer to change size and mode only
mode - buffering mode to use. It can be one of the following values: + + + +
_IOFBF full buffering
_IOLBF line buffering
_IONBF no buffering
size - size of the buffer

Return value

​0​ on success or nonzero on failure.

+

Notes

This function may only be used after stream has been associated with an open file, but before any other operation (other than a failed call to setbuf/setvbuf).

+

Not all size bytes will necessarily be used for buffering: the actual buffer size is usually rounded down to a multiple of 2, a multiple of page size, etc.

+

On many implementations, line buffering is only available for terminal input streams.

+

A common error is setting the buffer of stdin or stdout to an array whose lifetime ends before the program terminates:

+
int main(void) {
+    char buf[BUFSIZ];
+    setbuf(stdin, buf);
+} // lifetime of buf ends, undefined behavior

The default buffer size BUFSIZ is expected to be the most efficient buffer size for file I/O on the implementation, but POSIX fstat often provides a better estimate.

+

Example

+

One use case for changing buffer size is when a better size is known. (This example uses some POSIX function, e.g. fileno. See also SO: #1 and #2).

+
// Make some POSIX functions, such as `int fileno(FILE*)`, visible:
+#define _POSIX_SOURCE
+ 
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/stat.h>
+ 
+int main(void)
+{
+    FILE* fp = fopen("/tmp/test.txt", "w+");
+    if (fp == NULL)
+    {
+        perror("fopen");
+        return EXIT_FAILURE;
+    }
+ 
+    struct stat stats;
+    if (fstat(fileno(fp), &stats) == -1) // POSIX only
+    {
+        perror("fstat");
+        return EXIT_FAILURE;
+    }
+ 
+    printf("BUFSIZ is %d, but optimal block size is %ld\n", BUFSIZ, stats.st_blksize);
+    if (setvbuf(fp, NULL, _IOFBF, stats.st_blksize) != 0)
+    {
+        perror("setvbuf failed"); // POSIX version sets errno
+        return EXIT_FAILURE;
+    }
+ 
+    int ch;
+    while((ch=fgetc(fp)) != EOF); // read entire file: use truss/strace to
+                                  // observe the read(2) syscalls used
+ 
+    fclose(fp);
+    return EXIT_SUCCESS;
+}

Possible output:

+
BUFSIZ is 8192, but optimal block size is 65536

References

See also

+ +
sets the buffer for a file stream
(function)
C++ documentation for setvbuf
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/setvbuf +

+
diff --git a/devdocs/c/io%2Fstd_streams.html b/devdocs/c/io%2Fstd_streams.html new file mode 100644 index 00000000..be45707e --- /dev/null +++ b/devdocs/c/io%2Fstd_streams.html @@ -0,0 +1,68 @@ +

stdin, stdout, stderr

Defined in header <stdio.h> 
#define stdin  /* implementation-defined */
+		 (1) 
#define stdout /* implementation-defined */
+		 (2) 
#define stderr /* implementation-defined */
+		 (3)

Three text streams are predefined. These streams are implicitly opened and unoriented at program startup.

+
+1) Associated with the standard input stream, used for reading conventional input. At program startup, the stream is fully buffered if and only if the stream can be determined to not refer to an interactive device.
+2) Associated with the standard output stream, used for writing conventional output. At program startup, the stream is fully buffered if and only if the stream can be determined to not refer to an interactive device.
+3) Associated with the standard error stream, used for writing diagnostic output. At program startup, the stream is not fully buffered.

What constitutes an interactive device is implementation-defined.

+

These macros are expanded to expressions of type FILE*.

+

Notes

Although not mandated by POSIX, the UNIX convention is that stdin and stdout are line-buffered if associated with a terminal and stderr is unbuffered.

+

These macros may be expanded to modifiable lvalues. If any of these FILE* lvalue is modified, subsequent operations on the corresponding stream result in unspecified or undefined behavior.

+

Example

+

This example shows a function equivalent to printf.

+
#include <stdarg.h>
+#include <stdio.h>
+ 
+int my_printf(const char * restrict fmt, ...)
+{
+    va_list vl;
+    va_start(vl, fmt);
+    int ret = vfprintf(stdout, fmt, vl);
+    va_end(vl);
+    return ret;
+}
+ 
+int main(void)
+{
+    my_printf("Rounding:\t%f %.0f %.32f\n", 1.5, 1.5, 1.3);
+    my_printf("Padding:\t%05.2f %.2f %5.2f\n", 1.5, 1.5, 1.5);
+    my_printf("Scientific:\t%E %e\n", 1.5, 1.5);
+    my_printf("Hexadecimal:\t%a %A\n", 1.5, 1.5);
+}

Possible output:

+
Rounding:       1.500000 2 1.30000000000000004440892098500626
+Padding:        01.50 1.50  1.50
+Scientific:     1.500000E+00 1.500000e+00
+Hexadecimal:    0x1.8p+0 0X1.8P+0

References

See also

+ +
object type, capable of holding all information needed to control a C I/O stream
(typedef)
C++ documentation for stdin, stdout, stderr
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/std_streams +

+
diff --git a/devdocs/c/io%2Ftmpfile.html b/devdocs/c/io%2Ftmpfile.html new file mode 100644 index 00000000..63b7e5e7 --- /dev/null +++ b/devdocs/c/io%2Ftmpfile.html @@ -0,0 +1,62 @@ +

tmpfile, tmpfile_s

Defined in header <stdio.h> 
FILE* tmpfile( void );
+		 (1) 
errno_t tmpfile_s( FILE* restrict* restrict streamptr );
+		 (2) (since C11)
+1) Creates and opens a temporary file. The file is opened as binary file for update (as if by fopen with "wb+" mode). The filename of the file is guaranteed to be unique within the filesystem. At least TMP_MAX files may be opened during the lifetime of a program (this limit may be shared with tmpnam and may be further limited by FOPEN_MAX).
+2) Same as (1), except that at least TMP_MAX_S files may be opened (the limit may be shared with tmpnam_s), and if streamptr is a null pointer, the currently installed constraint handler function is called. As with all bounds-checked functions, tmpfile_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <stdio.h>.

The temporary file created by this function is closed and deleted when the program exits normally. Whether it's deleted on abnormal termination is implementation-defined.

+

Parameters

+1) (none)
+2) pointer to a pointer that will be updated by this function call

Return value

+1) Pointer to the file stream associated with the file or null pointer if an error has occurred.
+2) Zero if the file was created and open successfully, non-zero if the file was not created or open or if streamptr was a null pointer. In addition, pointer to the associated file stream is stored in *streamptr on success, and a null pointer value is stored in *streamptr on error.

Notes

On some implementations (e.g. older Linux), this function actually creates, opens, and immediately deletes the file from the file system: as long as an open file descriptor to a deleted file is held by a program, the file exists, but since it was deleted, its name does not appear in any directory, so that no other process can open it. Once the file descriptor is closed, or once the program terminates (normally or abnormally), the space occupied by the file is reclaimed by the filesystem. Newer Linux (since 3.11 or later, depending on filesystem) creates such invisible temporary files in one step, via special flag in the open() syscall.

+

On some implementations (e.g. Windows), elevated privileges are required as the function may create the temporary file in a system directory.

+

Example

#define _POSIX_C_SOURCE 200112L
+#include <stdio.h>
+#include <unistd.h>
+ 
+int main(void)
+{
+    printf("TMP_MAX = %d, FOPEN_MAX = %d\n", TMP_MAX, FOPEN_MAX);
+    FILE* tmpf = tmpfile();
+    fputs("Hello, world", tmpf);
+    rewind(tmpf);
+    char buf[6];
+    fgets(buf, sizeof buf, tmpf);
+    printf("got back from the file: '%s'\n", buf);
+ 
+    // Linux-specific method to display the tmpfile name
+    char fname[FILENAME_MAX], link[FILENAME_MAX] = {0};
+    sprintf(fname, "/proc/self/fd/%d", fileno(tmpf));
+    if (readlink(fname, link, sizeof link - 1) > 0)
+        printf("File name: %s\n", link);
+}

Possible output:

+
TMP_MAX = 238328, FOPEN_MAX = 16
+got back from the file: 'Hello'
+File name: /tmp/tmpfjptPe5 (deleted)

References

See also

+ +
+
(C11)
 returns a unique filename
(function)
C++ documentation for tmpfile
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/tmpfile +

+
diff --git a/devdocs/c/io%2Ftmpnam.html b/devdocs/c/io%2Ftmpnam.html new file mode 100644 index 00000000..0285bdf5 --- /dev/null +++ b/devdocs/c/io%2Ftmpnam.html @@ -0,0 +1,83 @@ +

tmpnam, tmpnam_s

Defined in header <stdio.h> 
char *tmpnam( char *filename );
+		 (1) 
errno_t tmpnam_s(char *filename_s, rsize_t maxsize);
+		 (2) (since C11) 
#define TMP_MAX        /*unspecified*/
+		 
#define TMP_MAX_S      /*unspecified*/
+		 (since C11) 
#define L_tmpnam       /*unspecified*/
+		 
#define L_tmpnam_s     /*unspecified*/
+		 (since C11)
+1) Creates a unique valid file name (no longer than L_tmpnam in length) and stores it in character string pointed to by filename. The function is capable of generating up to TMP_MAX of unique filenames, but some or all of them may be in use in the filesystem and thus not suitable return values.
+2) Same as (1), except that up to TMP_MAX_S names may be generated, no longer than L_tmpnam_s in length, and the following errors are detected at runtime and call the currently installed constraint handler function:
+
+
    +
  • filename_s is a null pointer
    • +
  • maxsize is greater than RSIZE_MAX
    • +
  • maxsize is less than the generated file name string
    • +
+
As with all bounds-checked functions, tmpnam_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <stdio.h>.
+
+

tmpnam and tmpnam_s modify static state (which may be shared between these functions) and are not required to be thread-safe.

+

Parameters

+ + + +
filename - pointer to the character array capable of holding at least L_tmpnam bytes, to be used as a result buffer. If null pointer is passed, a pointer to an internal static buffer is returned.
filename_s - pointer to the character array capable of holding at least L_tmpnam_s bytes, to be used as a result buffer.
maxsize - maximum number of characters the function is allowed to write (typically the size of the filename_s array).

Return value

+1) filename if filename was not a null pointer. Otherwise a pointer to an internal static buffer is returned. If no suitable filename can be generated, null pointer is returned.
+2) Returns zero and writes the file name to filename_s on success. On error, returns non-zero and writes the null character to filename_s[0] (only if filename_s is not null and maxsize is not zero and is not greater than RSIZE_MAX).

Notes

Although the names generated by tmpnam are difficult to guess, it is possible that a file with that name is created by another process between the moment tmpnam returns and the moment this program attempts to use the returned name to create a file. The standard function tmpfile and the POSIX function mkstemp do not have this problem (creating a unique directory using only the standard C library still requires the use of tmpnam).

+

POSIX systems additionally define the similarly named function tempnam, which offers the choice of a directory (which defaults to the optionally defined macro P_tmpdir).

+

Example

#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+ 
+int main(void)
+{
+    // Note, the compiler/linker may issue a security warning, e.g. GCC:
+    // "warning: the use of `tmpnam' is dangerous, better use `mkstemp'"
+    char* name1 = tmpnam(NULL);
+    printf("temporary file name: %s\n", name1);
+ 
+    char name2[L_tmpnam];
+    if (tmpnam(name2))
+        printf("temporary file name: %s\n", name2);
+ 
+    // POSIX offers mkstemp. The following declaration might be
+    // necessary as mkstemp is absent in the standard C <stdlib.h>.
+    int mkstemp(char*);
+ 
+    char name3[] = "/tmp/fileXXXXXX"; // at least six 'X' required ^_^
+    int file_descriptor = mkstemp(name3);
+    if (file_descriptor != -1)
+        printf("temporary file name: %s\n", name3);
+    else
+        perror("mkstemp");
+}

Possible output:

+
temporary file name: /tmp/file90dLlR
+temporary file name: /tmp/fileY9LWAg
+temporary file name: /tmp/filexgv8PF

References

See also

+ +
+
(C11)
 returns a pointer to a temporary file
(function)
C++ documentation for tmpnam
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/tmpnam +

+
diff --git a/devdocs/c/io%2Fungetc.html b/devdocs/c/io%2Fungetc.html new file mode 100644 index 00000000..ace91ea5 --- /dev/null +++ b/devdocs/c/io%2Fungetc.html @@ -0,0 +1,76 @@ +

ungetc

Defined in header <stdio.h> 
int ungetc( int ch, FILE *stream );
+

If ch does not equal EOF, pushes the character ch (reinterpreted as unsigned char) into the input buffer associated with the stream stream in such a manner that subsequent read operation from stream will retrieve that character. The external device associated with the stream is not modified.

+

Stream repositioning operations fseek, fsetpos, and rewind discard the effects of ungetc.

+

If ungetc is called more than once without an intervening read or repositioning, it may fail (in other words, a pushback buffer of size 1 is guaranteed, but any larger buffer is implementation-defined). If multiple successful ungetc were performed, read operations retrieve the pushed-back characters in reverse order of ungetc.

+

If ch equals EOF, the operation fails and the stream is not affected.

+

A successful call to ungetc clears the end of file status flag feof.

+

A successful call to ungetc on a binary stream decrements the stream position indicator by one (the behavior is indeterminate if the stream position indicator was zero).

+

A successful call to ungetc on a text stream modifies the stream position indicator in unspecified manner but guarantees that after all pushed-back characters are retrieved with a read operation, the stream position indicator is equal to its value before ungetc.

+

Parameters

+ + +
ch - character to be pushed into the input stream buffer
stream - file stream to put the character back to

Return value

On success ch is returned.

+

On failure EOF is returned and the given stream remains unchanged.

+

Notes

The size of the pushback buffer varies in practice from 4k (Linux, MacOS) to as little as 4 (Solaris) or the guaranteed minimum 1 (HPUX, AIX).

+

The apparent size of the pushback buffer may be larger if the character that is pushed back equals the character existing at that location in the external character sequence (the implementation may simply decrement the read file position indicator and avoid maintaining a pushback buffer).

+

Example

+

demonstrates the original purpose of ungetc: implementation of scanf

+
#include <ctype.h>
+#include <stdio.h>
+ 
+void demo_scanf(const char* fmt, FILE* s)
+{
+    while (*fmt != '\0') {
+        if (*fmt == '%') {
+            int c;
+            switch (*++fmt) {
+                case 'u':
+                    while (isspace(c=getc(s))) {}
+                    unsigned int num = 0;
+                    while (isdigit(c)) {
+                        num = num*10 + c-'0';
+                        c = getc(s);
+                    }
+                    printf("%%u scanned %u\n", num);
+                    ungetc(c, s);
+                    break;
+                case 'c':
+                    c = getc(s);
+                    printf("%%c scanned '%c'\n", c);
+                    break;
+            }
+        } else {
+            ++fmt;
+        }
+    }
+}
+ 
+int main(void)
+{
+    FILE* f = fopen("input.txt", "w+");
+    if (f != NULL) {
+        fputs("123x", f);
+        rewind(f); 
+        demo_scanf("%u%c", f);
+        fclose(f);
+    }
+    return 0;
+}

Output:

+
%u scanned 123
+%c scanned 'x'

References

See also

+ +
gets a character from a file stream
(function)
C++ documentation for ungetc
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/ungetc +

+
diff --git a/devdocs/c/io%2Fungetwc.html b/devdocs/c/io%2Fungetwc.html new file mode 100644 index 00000000..88d39fd7 --- /dev/null +++ b/devdocs/c/io%2Fungetwc.html @@ -0,0 +1,27 @@ +

ungetwc

Defined in header <wchar.h> 
wint_t ungetwc( wint_t ch, FILE *stream );
+		 (since C95)

If ch does not equal WEOF, pushes the wide character ch into the input buffer associated with the stream stream in such a manner that subsequent read operation from stream will retrieve that wide character. The external device associated with the stream is not modified.

+

Stream repositioning operations fseek, fsetpos, and rewind discard the effects of ungetwc.

+

If ungetwc is called more than once without an intervening read or repositioning, it may fail (in other words, a pushback buffer of size 1 is guaranteed, but any larger buffer is implementation-defined). If multiple successful ungetwc were performed, read operations retrieve the pushed-back wide characters in reverse order of ungetwc

+

If ch equals WEOF, the operation fails and the stream is not affected.

+

A successful call to ungetwc clears the end of file status flag feof.

+

A successful call to ungetwc on a stream (whether text or binary) modifies the stream position indicator in unspecified manner but guarantees that after all pushed-back wide characters are retrieved with a read operation, the stream position indicator is equal to its value before ungetwc.

+

Parameters

+ + +
ch - wide character to be put back
stream - file stream to put the wide character back to

Return value

On success ch is returned.

+

On failure WEOF is returned and the given stream remains unchanged.

+

References

See also

+ + +
puts a character back into a file stream
(function)
+
(C95)
 gets a wide character from a file stream
(function)
C++ documentation for ungetwc
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/ungetwc +

+
diff --git a/devdocs/c/io%2Fvfprintf.html b/devdocs/c/io%2Fvfprintf.html new file mode 100644 index 00000000..923d109e --- /dev/null +++ b/devdocs/c/io%2Fvfprintf.html @@ -0,0 +1,242 @@ +

vprintf, vfprintf, vsprintf, vsnprintf, vprintf_s, vfprintf_s, vsprintf_s, vsnprintf_s

Defined in header <stdio.h>
(1) 
int vprintf( const char *format, va_list vlist );
+		 (until C99) 
int vprintf( const char *restrict format, va_list vlist );
+		 (since C99)
(2) 
int vfprintf( FILE *stream, const char *format, va_list vlist );
+		 (until C99) 
int vfprintf( FILE *restrict stream, const char *restrict format, 
+              va_list vlist );
+		 (since C99)
(3) 
int vsprintf( char *buffer, const char *format, va_list vlist );
+		 (until C99) 
int vsprintf( char *restrict buffer, const char *restrict format, 
+              va_list vlist );
+		 (since C99) 
int vsnprintf( char *restrict buffer, size_t bufsz, 
+               const char *restrict format, va_list vlist );
+		 (4) (since C99) 
int vprintf_s( const char *restrict format, va_list vlist );
+		 (5) (since C11) 
int vfprintf_s( FILE *restrict stream, const char *restrict format,
+                va_list vlist );
+		 (6) (since C11) 
int vsprintf_s( char *restrict buffer, rsize_t bufsz,
+                const char *restrict format, va_list vlist );
+		 (7) (since C11) 
int vsnprintf_s( char *restrict buffer, rsize_t bufsz,
+                 const char *restrict format, va_list vlist );
+		 (8) (since C11)

Loads the data from the locations, defined by vlist, converts them to character string equivalents and writes the results to a variety of sinks.

+
+1) Writes the results to stdout.
+2) Writes the results to a file stream stream.
+3) Writes the results to a character string buffer.
+4) Writes the results to a character string buffer. At most bufsz - 1 characters are written. The resulting character string will be terminated with a null character, unless bufsz is zero. If bufsz is zero, nothing is written and buffer may be a null pointer, however the return value (number of bytes that would be written not including the null terminator) is still calculated and returned.
+5-8) Same as (1-4), except that the following errors are detected at runtime and call the currently installed constraint handler function: As with all bounds-checked functions, vprintf_s , vfprintf_s, vsprintf_s, and vsnprintf_s are only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <stdio.h>.

Parameters

+ + + + + +
stream - output file stream to write to
buffer - pointer to a character string to write to
bufsz - up to bufsz - 1 characters may be written, plus the null terminator
format - pointer to a null-terminated character string specifying how to interpret the data
vlist - variable argument list containing the data to print.


The format string consists of ordinary byte characters (except %), which are copied unchanged into the output stream, and conversion specifications. Each conversion specification has the following format:

+

The following format specifiers are available:

+ + + + + + + + + + + + + + + + +
Conversion
Specifier 		Explanation Expected
Argument Type
+Length
Modifier→ 		+hh

(C99)

+		 +h (none) +l +ll

(C99)

+		 +j

(C99)

+		 +z

(C99)

+		 +t

(C99)

+		 +L
+% Writes literal %. The full conversion specification must be %%. N/A N/A N/A N/A N/A N/A N/A N/A N/A
+c Writes a single character.

The argument is first converted to unsigned char. If the l modifier is used, the argument is first converted to a character string as if by %ls with a wchar_t[2] argument.

+		 N/A N/A +
int
 +
wint_t
 N/A N/A N/A N/A N/A
+s Writes a character string

The argument must be a pointer to the initial element of an array of characters. Precision specifies the maximum number of bytes to be written. If Precision is not specified, writes every byte up to and not including the first null terminator. If the l specifier is used, the argument must be a pointer to the initial element of an array of wchar_t, which is converted to char array as if by a call to wcrtomb with zero-initialized conversion state.

+		 N/A N/A +
char*
 +
wchar_t*
 N/A N/A N/A N/A N/A
+d
i 		Converts a signed integer into decimal representation [-]dddd.

Precision specifies the minimum number of digits to appear. The default precision is 1.

If both the converted value and the precision are ​0​ the conversion results in no characters.

+		 +
signed char
 +
short
 +
int
 +
long
 +
long long
 + +
signed size_t +
 + N/A
+o Converts an unsigned integer into octal representation oooo.

Precision specifies the minimum number of digits to appear. The default precision is 1. If both the converted value and the precision are ​0​ the conversion results in no characters. In the alternative implementation precision is increased if necessary, to write one leading zero. In that case if both the converted value and the precision are ​0​, single ​0​ is written.

+		 +
unsigned char
 +
unsigned short
 +
unsigned int
 +
unsigned long
 +
unsigned long long
 + + +
unsigned version of ptrdiff_t +
 N/A
+x
X 		Converts an unsigned integer into hexadecimal representation hhhh.

For the x conversion letters abcdef are used.
For the X conversion letters ABCDEF are used.
Precision specifies the minimum number of digits to appear. The default precision is 1. If both the converted value and the precision are ​0​ the conversion results in no characters. In the alternative implementation 0x or 0X is prefixed to results if the converted value is nonzero.

+		 N/A
+u Converts an unsigned integer into decimal representation dddd.

Precision specifies the minimum number of digits to appear. The default precision is 1. If both the converted value and the precision are ​0​ the conversion results in no characters.

+		 N/A
+f
F 		Converts floating-point number to the decimal notation in the style [-]ddd.ddd.

Precision specifies the exact number of digits to appear after the decimal point character. The default precision is 6. In the alternative implementation decimal point character is written even if no digits follow it. For infinity and not-a-number conversion style see notes.

+		 N/A N/A +
double
 +
+double(C99) +
 N/A N/A N/A N/A +
long double
+e
E 		Converts floating-point number to the decimal exponent notation.

For the e conversion style [-]d.ddde±dd is used.
For the E conversion style [-]d.dddE±dd is used.
The exponent contains at least two digits, more digits are used only if necessary. If the value is ​0​, the exponent is also ​0​. Precision specifies the exact number of digits to appear after the decimal point character. The default precision is 6. In the alternative implementation decimal point character is written even if no digits follow it. For infinity and not-a-number conversion style see notes.

+		 N/A N/A N/A N/A N/A N/A
+a
A

(C99)

+		 Converts floating-point number to the hexadecimal exponent notation.

For the a conversion style [-]0xh.hhhp±d is used.
For the A conversion style [-]0Xh.hhhP±d is used.
The first hexadecimal digit is not 0 if the argument is a normalized floating point value. If the value is ​0​, the exponent is also ​0​. Precision specifies the exact number of digits to appear after the hexadecimal point character. The default precision is sufficient for exact representation of the value. In the alternative implementation decimal point character is written even if no digits follow it. For infinity and not-a-number conversion style see notes.

+		 N/A N/A N/A N/A N/A N/A
+g
G 		Converts floating-point number to decimal or decimal exponent notation depending on the value and the precision.

For the g conversion style conversion with style e or f will be performed.
For the G conversion style conversion with style E or F will be performed.
Let P equal the precision if nonzero, 6 if the precision is not specified, or 1 if the precision is ​0​. Then, if a conversion with style E would have an exponent of X:

+
    +
  • if P > X ≥ −4, the conversion is with style f or F and precision P − 1 − X.
    • +
  • otherwise, the conversion is with style e or E and precision P − 1.
    • +

Unless alternative representation is requested the trailing zeros are removed, also the decimal point character is removed if no fractional part is left. For infinity and not-a-number conversion style see notes.

+		 N/A N/A N/A N/A N/A N/A
+n Returns the number of characters written so far by this call to the function.

The result is written to the value pointed to by the argument. The specification may not contain any flag, field width, or precision.



+		 +
signed char*
 +
short*
 +
int*
 +
long*
 +
long long*
 + +
signed size_t* +
 + N/A
+p Writes an implementation defined character sequence defining a pointer. N/A N/A +void* N/A N/A N/A N/A N/A N/A

The floating point conversion functions convert infinity to inf or infinity. Which one is used is implementation defined.

+

Not-a-number is converted to nan or nan(char_sequence). Which one is used is implementation defined.

+

The conversions F, E, G, A output INF, INFINITY, NAN instead.

+

Even though %c expects int argument, it is safe to pass a char because of the integer promotion that takes place when a variadic function is called.

+

The correct conversion specifications for the fixed-width character types (int8_t, etc) are defined in the header <inttypes.h> (although PRIdMAX, PRIuMAX, etc is synonymous with %jd, %ju, etc).

+

The memory-writing conversion specifier %n is a common target of security exploits where format strings depend on user input and is not supported by the bounds-checked printf_s family of functions.

+

There is a sequence point after the action of each conversion specifier; this permits storing multiple %n results in the same variable or, as an edge case, printing a string modified by an earlier %n within the same call.

+

If a conversion specification is invalid, the behavior is undefined.

+

Return value

+1-3) The number of characters written if successful or negative value if an error occurred.
+4) The number of characters written if successful or negative value if an error occurred. If the resulting string gets truncated due to buf_size limit, function returns the total number of characters (not including the terminating null-byte) which would have been written, if the limit was not imposed.
+5,6) number of characters transmitted to the output stream or negative value if an output error, a runtime constrants violation error, or an encoding error occurred.
+7) number of characters written to buffer, not counting the null character (which is always written as long as buffer is not a null pointer and bufsz is not zero and not greater than RSIZE_MAX), or zero on runtime constraint violations, and negative value on encoding errors
+8) number of characters not including the terminating null character (which is always written as long as buffer is not a null pointer and bufsz is not zero and not greater than RSIZE_MAX), which would have been written to buffer if bufsz was ignored, or a negative value if a runtime constraints violation or an encoding error occurred

Notes

All these functions invoke va_arg at least once, the value of arg is indeterminate after the return. These functions do not invoke va_end, and it must be done by the caller.

+

vsnprintf_s, unlike vsprintf_s, will truncate the result to fit within the array pointed to by buffer.

+

Example

#include <stdio.h>
+#include <stdarg.h>
+#include <time.h>
+ 
+void debug_log(const char *fmt, ...)
+{
+    struct timespec ts;
+    timespec_get(&ts, TIME_UTC);
+    char time_buf[100];
+    size_t rc = strftime(time_buf, sizeof time_buf, "%D %T", gmtime(&ts.tv_sec));
+    snprintf(time_buf + rc, sizeof time_buf - rc, ".%06ld UTC", ts.tv_nsec / 1000);
+ 
+    va_list args1;
+    va_start(args1, fmt);
+    va_list args2;
+    va_copy(args2, args1);
+    char buf[1+vsnprintf(NULL, 0, fmt, args1)];
+    va_end(args1);
+    vsnprintf(buf, sizeof buf, fmt, args2);
+    va_end(args2);
+ 
+    printf("%s [debug]: %s\n", time_buf, buf);
+}
+ 
+int main(void)
+{
+    debug_log("Logging, %d, %d, %d", 1, 2, 3);
+}

Possible output:

+
02/20/15 21:58:09.072683 UTC [debug]: Logging, 1, 2, 3

References

See also

+ + + +
+
(C95)(C95)(C95)(C11)(C11)(C11)(C11)
 prints formatted wide character output to stdout, a file stream
or a buffer using variable argument list
(function)
+
(C99)(C11)(C11)(C11)(C11)
 prints formatted output to stdout, a file stream or a buffer
(function)
+
(C99)(C99)(C99)(C11)(C11)(C11)
 reads formatted input from stdin, a file stream or a buffer
using variable argument list
(function)
C++ documentation for vprintf, vfprintf, vsprintf, vsnprintf
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/vfprintf +

+
diff --git a/devdocs/c/io%2Fvfscanf.html b/devdocs/c/io%2Fvfscanf.html new file mode 100644 index 00000000..04e4f6b8 --- /dev/null +++ b/devdocs/c/io%2Fvfscanf.html @@ -0,0 +1,191 @@ +

vscanf, vfscanf, vsscanf, vscanf_s, vfscanf_s, vsscanf_s

Defined in header <stdio.h> 
int vscanf( const char *restrict format, va_list vlist );
+		 (1) (since C99) 
int vfscanf( FILE *restrict stream, const char *restrict format, 
+             va_list vlist );
+		 (2) (since C99) 
int vsscanf( const char *restrict buffer, const char *restrict format, 
+             va_list vlist );
+		 (3) (since C99) 
int vscanf_s(const char *restrict format, va_list vlist);
+		 (4) (since C11) 
int vfscanf_s( FILE *restrict stream, const char *restrict format,
+               va_list vlist);
+		 (5) (since C11) 
int vsscanf_s( const char *restrict buffer, const char *restrict format,
+               va_list vlist);
+		 (6) (since C11)

Reads data from the a variety of sources, interprets it according to format and stores the results into locations defined by vlist.

+
+1) Reads the data from stdin +
+2) Reads the data from file stream stream +
+3) Reads the data from null-terminated character string buffer. Reaching the end of the string is equivalent to reaching the end-of-file condition for fscanf +
+4-6) Same as (1-3), except that %c, %s, and %[ conversion specifiers each expect two arguments (the usual pointer and a value of type rsize_t indicating the size of the receiving array, which may be 1 when reading with a %c into a single char) and except that the following errors are detected at runtime and call the currently installed constraint handler function:
+
+
    +
  • any of the arguments of pointer type is a null pointer
    • +
  • format, stream, or buffer is a null pointer
    • +
  • the number of characters that would be written by %c, %s, or %[, plus the terminating null character, would exceed the second (rsize_t) argument provided for each of those conversion specifiers
    • +
  • optionally, any other detectable error, such as unknown conversion specifier
    • +
+
As with all bounds-checked functions, vscanf_s , vfscanf_s, and vsscanf_s are only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <stdio.h>.
+
+

Parameters

+ + + + +
stream - input file stream to read from
buffer - pointer to a null-terminated character string to read from
format - pointer to a null-terminated character string specifying how to read the input
vlist - variable argument list containing the receiving arguments.


The format string consists of

+

The following format specifiers are available:

+ + + + + + + + + + + + + + + +
Conversion
specifier 		Explanation Argument type
+Length modifier → +hh

(C99)

+		 +h (none) +l +ll

(C99)

+		 +j

(C99)

+		 +z

(C99)

+		 +t

(C99)

+		 +L
+% Matches literal %. N/A N/A N/A N/A N/A N/A N/A N/A N/A
+c Matches a character or a sequence of characters.

If a width specifier is used, matches exactly width characters (the argument must be a pointer to an array with sufficient room). Unlike %s and %[, does not append the null character to the array.

+		 N/A N/A +
char*
 +
wchar_t*
 N/A N/A N/A N/A N/A
+s Matches a sequence of non-whitespace characters (a string).

If width specifier is used, matches up to width or until the first whitespace character, whichever appears first. Always stores a null character in addition to the characters matched (so the argument array must have room for at least width+1 characters)

+
+[set] Matches a non-empty sequence of character from set of characters.

If the first character of the set is ^, then all characters not in the set are matched. If the set begins with ] or ^] then the ] character is also included into the set. It is implementation-defined whether the character - in the non-initial position in the scanset may be indicating a range, as in [0-9]. If width specifier is used, matches only up to width. Always stores a null character in addition to the characters matched (so the argument array must have room for at least width+1 characters)

+
+d Matches a decimal integer.

The format of the number is the same as expected by strtol with the value 10 for the base argument

+		 +
+signed char* or unsigned char* +
 +
+signed short* or unsigned short* +
 +
+signed int* or unsigned int* +
 +
+signed long* or unsigned long* +
 +
+signed long long* or unsigned long long* +
 + + + N/A
+i Matches an integer.

The format of the number is the same as expected by strtol with the value ​0​ for the base argument (base is determined by the first characters parsed)

+
+u Matches an unsigned decimal integer.

The format of the number is the same as expected by strtoul with the value 10 for the base argument.

+
+o Matches an unsigned octal integer.

The format of the number is the same as expected by strtoul with the value 8 for the base argument

+
+x, X Matches an unsigned hexadecimal integer.

The format of the number is the same as expected by strtoul with the value 16 for the base argument

+
+n Returns the number of characters read so far.

No input is consumed. Does not increment the assignment count. If the specifier has assignment-suppressing operator defined, the behavior is undefined

+
+a, A(C99)
e, E
f, F(C99)
g, G 		Matches a floating-point number.

The format of the number is the same as expected by strtof

+		 N/A N/A +
float*
 +
double*
 N/A N/A N/A N/A +
long double*
+p Matches implementation defined character sequence defining a pointer.

printf family of functions should produce the same sequence using %p format specifier

+		 N/A N/A +
void**
 N/A N/A N/A N/A N/A N/A

For every conversion specifier other than n, the longest sequence of input characters which does not exceed any specified field width and which either is exactly what the conversion specifier expects or is a prefix of a sequence it would expect, is what's consumed from the stream. The first character, if any, after this consumed sequence remains unread. If the consumed sequence has length zero or if the consumed sequence cannot be converted as specified above, the matching failure occurs unless end-of-file, an encoding error, or a read error prevented input from the stream, in which case it is an input failure.

+

All conversion specifiers other than [, c, and n consume and discard all leading whitespace characters (determined as if by calling isspace) before attempting to parse the input. These consumed characters do not count towards the specified maximum field width.

+

The conversion specifiers lc, ls, and l[ perform multibyte-to-wide character conversion as if by calling mbrtowc with an mbstate_t object initialized to zero before the first character is converted.

+

The conversion specifiers s and [ always store the null terminator in addition to the matched characters. The size of the destination array must be at least one greater than the specified field width. The use of %s or %[, without specifying the destination array size, is as unsafe as gets.

+

The correct conversion specifications for the fixed-width integer types (int8_t, etc) are defined in the header <inttypes.h> (although SCNdMAX, SCNuMAX, etc is synonymous with %jd, %ju, etc).

+

There is a sequence point after the action of each conversion specifier; this permits storing multiple fields in the same "sink" variable.

+

When parsing an incomplete floating-point value that ends in the exponent with no digits, such as parsing "100er" with the conversion specifier %f, the sequence "100e" (the longest prefix of a possibly valid floating-point number) is consumed, resulting in a matching error (the consumed sequence cannot be converted to a floating-point number), with "r" remaining. Some existing implementations do not follow this rule and roll back to consume only "100", leaving "er", e.g. glibc bug 1765.

+

Return value

+1-3) Number of receiving arguments successfully assigned, or EOF if read failure occurs before the first receiving argument was assigned.
+4-6) Same as (1-3), except that EOF is also returned if there is a runtime constraint violation.

Notes

All these functions invoke va_arg at least once, the value of arg is indeterminate after the return. These functions to not invoke va_end, and it must be done by the caller.

+

Example

#include <stdio.h>
+#include <stdbool.h>
+#include <stdarg.h>
+ 
+bool checked_sscanf(int count, const char* buf, const char *fmt, ...)
+{
+    va_list ap;
+    va_start(ap, fmt);
+    int rc = vsscanf(buf, fmt, ap);
+    va_end(ap);
+    return rc == count;
+}
+ 
+int main(void)
+{
+    int n, m;
+ 
+    printf("Parsing '1 2'...");
+    if(checked_sscanf(2, "1 2", "%d %d", &n, &m))
+        puts("success");
+    else
+        puts("failure");
+ 
+    printf("Parsing '1 a'...");
+    if(checked_sscanf(2, "1 a", "%d %d", &n, &m))
+        puts("success");
+    else
+        puts("failure");
+}

Output:

+
Parsing '1 2'...success
+Parsing '1 a'...failure

References

See also

+ + +
+
(C11)(C11)(C11)
 reads formatted input from stdin, a file stream or a buffer
(function)
+
(C99)(C11)(C11)(C11)(C11)
 prints formatted output to stdout, a file stream or a buffer
using variable argument list
(function)
C++ documentation for vscanf, vfscanf, vsscanf
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/vfscanf +

+
diff --git a/devdocs/c/io%2Fvfwprintf.html b/devdocs/c/io%2Fvfwprintf.html new file mode 100644 index 00000000..4fbbfa0c --- /dev/null +++ b/devdocs/c/io%2Fvfwprintf.html @@ -0,0 +1,227 @@ +

vwprintf, vfwprintf, vswprintf, vwprintf_s, vfwprintf_s, vswprintf_s, vsnwprintf_s

Defined in header <wchar.h>
(1) 
int vwprintf( const wchar_t *format, va_list vlist );
+		 (since C95)
(until C99) 
int vwprintf( const wchar_t *restrict format, va_list vlist );
+		 (since C99)
(2) 
int vfwprintf( FILE* stream, const wchar_t *format, va_list vlist );
+		 (since C95)
(until C99) 
int vfwprintf( FILE *restrict stream,
+               const wchar_t *restrict format, va_list vlist );
+		 (since C99)
(3) 
int vswprintf( wchar_t *buffer, size_t bufsz,
+               const wchar_t *format, va_list vlist );
+		 (since C95)
(until C99) 
int vswprintf( wchar_t *restrict buffer, size_t bufsz,
+               const wchar_t *restrict format, va_list vlist );
+		 (since C99) 
int vwprintf_s( const wchar_t *restrict format, va_list vlist);
+		 (4) (since C11) 
int vfwprintf_s( FILE * restrict stream,
+                 const wchar_t *restrict format, va_list vlist);
+		 (5) (since C11) 
int vswprintf_s( wchar_t *restrict buffer, rsize_t bufsz, 
+                 const wchar_t * restrict format, va_list vlist);
+		 (6) (since C11) 
int vsnwprintf_s( wchar_t *restrict buffer, rsize_t bufsz,
+                  const wchar_t *restrict format, va_list vlist);
+		 (7) (since C11)

Loads the data from locations, defined by vlist, converts them to wide string equivalents and writes the results to a variety of sinks.

+
+1) Writes the results to stdout.
+2) Writes the results to a file stream stream.
+3) Writes the results to a wide string buffer. At most bufsz-1 wide characters are written followed by null wide character. The resulting wide character string will be terminated with a null wide character, unless bufsz is zero.
+4-6) Same as (1-3), except that the following errors are detected at runtime and call the currently installed constraint handler function: +
+7) Same as (6), except it will truncate the result to fit within the array pointed to by buffer. As with all bounds-checked functions, vwprintf_s , vfwprintf_s, vswprintf_s, and vsnwprintf_s are only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <stdio.h>.

Parameters

+ + + + + +
stream - output wide stream to write to
buffer - pointer to a wide string to write to
bufsz - maximum number of wide characters to write
format - pointer to a null-terminated wide string specifying how to interpret the data
vlist - variable argument list containing the data to print.


The format string consists of ordinary wide characters (except %), which are copied unchanged into the output stream, and conversion specifications. Each conversion specification has the following format:

+

The following format specifiers are available:

+ + + + + + + + + + + + + + + + +
Conversion
Specifier 		Explanation Expected
Argument Type
+Length
Modifier→ 		+hh

(C99)

+		 +h (none) +l +ll

(C99)

+		 +j

(C99)

+		 +z

(C99)

+		 +t

(C99)

+		 +L
+% Writes literal %. The full conversion specification must be %%. N/A N/A N/A N/A N/A N/A N/A N/A N/A
+c Writes a single character.

The argument is first converted to wchar_t as if by calling btowc. If the l modifier is used, the wint_t argument is first converted to wchar_t.

+		 N/A N/A +
int
 +
wint_t
 N/A N/A N/A N/A N/A
+s Writes a character string

The argument must be a pointer to the initial element of a character array containing a multibyte character sequence beginning in the initial shift state, which is converted to wide character array as if by a call to mbrtowc with zero-initialized conversion state. Precision specifies the maximum number of wide characters to be written. If Precision is not specified, writes every wide characters up to and not including the first null terminator. If the l specifier is used, the argument must be a pointer to the initial element of an array of wchar_t.

+		 N/A N/A +
char*
 +
wchar_t*
 N/A N/A N/A N/A N/A
+d
i 		Converts a signed integer into decimal representation [-]dddd.

Precision specifies the minimum number of digits to appear. The default precision is 1.

If both the converted value and the precision are ​0​ the conversion results in no characters.

+		 +
signed char
 +
short
 +
int
 +
long
 +
long long
 + +
signed size_t +
 + N/A
+o Converts an unsigned integer into octal representation oooo.

Precision specifies the minimum number of digits to appear. The default precision is 1. If both the converted value and the precision are ​0​ the conversion results in no characters. In the alternative implementation precision is increased if necessary, to write one leading zero. In that case if both the converted value and the precision are ​0​, single ​0​ is written.

+		 +
unsigned char
 +
unsigned short
 +
unsigned int
 +
unsigned long
 +
unsigned long long
 + + +
unsigned version of ptrdiff_t +
 N/A
+x
X 		Converts an unsigned integer into hexadecimal representation hhhh.

For the x conversion letters abcdef are used.
For the X conversion letters ABCDEF are used.
Precision specifies the minimum number of digits to appear. The default precision is 1. If both the converted value and the precision are ​0​ the conversion results in no characters. In the alternative implementation 0x or 0X is prefixed to results if the converted value is nonzero.

+		 N/A
+u Converts an unsigned integer into decimal representation dddd.

Precision specifies the minimum number of digits to appear. The default precision is 1. If both the converted value and the precision are ​0​ the conversion results in no characters.

+		 N/A
+f
F 		Converts floating-point number to the decimal notation in the style [-]ddd.ddd.

Precision specifies the exact number of digits to appear after the decimal point character. The default precision is 6. In the alternative implementation decimal point character is written even if no digits follow it. For infinity and not-a-number conversion style see notes.

+		 N/A N/A +
double
 +
+double(C99) +
 N/A N/A N/A N/A +
long double
+e
E 		Converts floating-point number to the decimal exponent notation.

For the e conversion style [-]d.ddde±dd is used.
For the E conversion style [-]d.dddE±dd is used.
The exponent contains at least two digits, more digits are used only if necessary. If the value is ​0​, the exponent is also ​0​. Precision specifies the exact number of digits to appear after the decimal point character. The default precision is 6. In the alternative implementation decimal point character is written even if no digits follow it. For infinity and not-a-number conversion style see notes.

+		 N/A N/A N/A N/A N/A N/A
+a
A

(C99)

+		 Converts floating-point number to the hexadecimal exponent notation.

For the a conversion style [-]0xh.hhhp±d is used.
For the A conversion style [-]0Xh.hhhP±d is used.
The first hexadecimal digit is not 0 if the argument is a normalized floating point value. If the value is ​0​, the exponent is also ​0​. Precision specifies the exact number of digits to appear after the hexadecimal point character. The default precision is sufficient for exact representation of the value. In the alternative implementation decimal point character is written even if no digits follow it. For infinity and not-a-number conversion style see notes.

+		 N/A N/A N/A N/A N/A N/A
+g
G 		Converts floating-point number to decimal or decimal exponent notation depending on the value and the precision.

For the g conversion style conversion with style e or f will be performed.
For the G conversion style conversion with style E or F will be performed.
Let P equal the precision if nonzero, 6 if the precision is not specified, or 1 if the precision is ​0​. Then, if a conversion with style E would have an exponent of X:

+
    +
  • if P > X ≥ −4, the conversion is with style f or F and precision P − 1 − X.
    • +
  • otherwise, the conversion is with style e or E and precision P − 1.
    • +

Unless alternative representation is requested the trailing zeros are removed, also the decimal point character is removed if no fractional part is left. For infinity and not-a-number conversion style see notes.

+		 N/A N/A N/A N/A N/A N/A
+n Returns the number of characters written so far by this call to the function.

The result is written to the value pointed to by the argument. The specification may not contain any flag, field width, or precision.



+		 +
signed char*
 +
short*
 +
int*
 +
long*
 +
long long*
 + +
signed size_t* +
 + N/A
+p Writes an implementation defined character sequence defining a pointer. N/A N/A +void* N/A N/A N/A N/A N/A N/A

The floating point conversion functions convert infinity to inf or infinity. Which one is used is implementation defined.

+

Not-a-number is converted to nan or nan(char_sequence). Which one is used is implementation defined.

+

The conversions F, E, G, A output INF, INFINITY, NAN instead.

+

Even though %c expects int argument, it is safe to pass a char because of the integer promotion that takes place when a variadic function is called.

+

The correct conversion specifications for the fixed-width character types (int8_t, etc) are defined in the header <inttypes.h> (although PRIdMAX, PRIuMAX, etc is synonymous with %jd, %ju, etc).

+

The memory-writing conversion specifier %n is a common target of security exploits where format strings depend on user input and is not supported by the bounds-checked printf_s family of functions.

+

There is a sequence point after the action of each conversion specifier; this permits storing multiple %n results in the same variable or, as an edge case, printing a string modified by an earlier %n within the same call.

+

If a conversion specification is invalid, the behavior is undefined.

+

Return value

+1,4) The number of wide characters written if successful or negative value if an error occurred.
+3) The number of wide characters written if successful or negative value if an error occurred. If the resulting string gets truncated due to bufsz limit, function returns the total number of characters (not including the terminating null wide character) which would have been written, if the limit were not imposed.
+2,5) number of wide characters transmitted to the output stream or negative value if an output error, a runtime constraints violation error, or an encoding error occurred.
+6) number of wide characters written to buffer, not counting the null wide character (which is always written as long as buffer is not a null pointer and bufsz is not zero and not greater than RSIZE_MAX/sizeof(wchar_t)), or zero on runtime constraint violations, and negative value on encoding errors.
+7) number of wide characters not including the terminating null character (which is always written as long as buffer is not a null pointer and bufsz is not zero and not greater than RSIZE_MAX/sizeof(wchar_t)), which would have been written to buffer if bufsz was ignored, or a negative value if a runtime constraints violation or an encoding error occurred.

Notes

All these functions invoke va_arg at least once, the value of arg is indeterminate after the return. These functions to not invoke va_end, and it must be done by the caller.

+

While narrow strings provide vsnprintf, which makes it possible to determine the required output buffer size, there is no equivalent for wide strings (until C11's vsnwprintf_s), and in order to determine the buffer size, the program may need to call vswprintf, check the result value, and reallocate a larger buffer, trying again until successful.

+

vsnwprintf_s, unlike vswprintf_s, will truncate the result to fit within the array pointed to by buffer, even though truncation is treated as an error by most bounds-checked functions.

+

Example

#include <stdio.h>
+#include <time.h>
+#include <locale.h>
+#include <stdarg.h>
+#include <stddef.h>
+#include <wchar.h>
+ 
+void debug_wlog(const wchar_t *fmt, ...)
+{
+    struct timespec ts;
+    timespec_get(&ts, TIME_UTC);
+    char time_buf[100];
+    size_t rc = strftime(time_buf, sizeof time_buf, "%D %T", gmtime(&ts.tv_sec));
+    snprintf(time_buf + rc, sizeof time_buf - rc, ".%06ld UTC", ts.tv_nsec / 1000);
+ 
+    va_list args;
+    va_start(args, fmt);
+    wchar_t buf[1024];
+    int rc2 = vswprintf(buf, sizeof buf / sizeof *buf, fmt, args);
+    va_end(args);
+ 
+    if(rc2 > 0)
+       wprintf(L"%s [debug]: %ls\n", time_buf, buf);
+    else
+       wprintf(L"%s [debug]: (string too long)\n", time_buf);
+}
+ 
+int main(void)
+{
+    setlocale(LC_ALL, "");
+    debug_wlog(L"Logging, %d, %d, %d", 1, 2, 3);
+}

Possible output:

+
02/20/15 22:12:38.476575 UTC [debug]: Logging, 1, 2, 3

References

See also

+ + +
+
(C99)(C11)(C11)(C11)(C11)
 prints formatted output to stdout, a file stream or a buffer
using variable argument list
(function)
+
(C95)(C95)(C95)(C11)(C11)(C11)(C11)
 prints formatted wide character output to stdout, a file stream or a buffer
(function)
C++ documentation for vwprintf, vfwprintf, vswprintf
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/vfwprintf +

+
diff --git a/devdocs/c/io%2Fvfwscanf.html b/devdocs/c/io%2Fvfwscanf.html new file mode 100644 index 00000000..dd3e9ae2 --- /dev/null +++ b/devdocs/c/io%2Fvfwscanf.html @@ -0,0 +1,157 @@ +

vwscanf, vfwscanf, vswscanf, vwscanf_s, vfwscanf_s, vswscanf_s

Defined in header <wchar.h> 
int vwscanf( const wchar_t *restrict format, va_list vlist );
+		 (1) (since C99) 
int vfwscanf( FILE *restrict stream,
+              const wchar_t *restrict format, va_list vlist );
+		 (2) (since C99) 
int vswscanf( const wchar_t *restrict buffer,
+              const wchar_t *restrict format, va_list vlist );
+		 (3) (since C99) 
int vwscanf_s( const wchar_t *restrict format, va_list vlist );
+		 (4) (since C11) 
int vfwscanf_s( FILE *restrict stream,
+                const wchar_t *restrict format, va_list vlist );
+		 (5) (since C11) 
int vswscanf_s( const wchar_t *restrict buffer,
+                const wchar_t *restrict format, va_list vlist );
+		 (6) (since C11)

Reads data from the a variety of sources, interprets it according to format and stores the results into locations defined by vlist.

+
+1) Reads the data from stdin.
+2) Reads the data from file stream stream.
+3) Reads the data from null-terminated wide string buffer. Reaching the end of the string is equivalent to reaching the end-of-file condition for fwscanf +
+4-6) Same as (1-3), except that %c, %s, and %[ conversion specifiers each expect two arguments (the usual pointer and a value of type rsize_t indicating the size of the receiving array, which may be 1 when reading with a %lc into a single wide character) and except that the following errors are detected at runtime and call the currently installed constraint handler function:
+
+
    +
  • any of the arguments of pointer type is a null pointer
    • +
  • format, stream, or buffer is a null pointer
    • +
  • the number of characters that would be written by %c, %s, or %[, plus the terminating null character, would exceed the second (rsize_t) argument provided for each of those conversion specifiers
    • +
  • optionally, any other detectable error, such as unknown conversion specifier
    • +
+
As with all bounds-checked functions, vwscanf_s , vfwscanf_s, and vswscanf_s are only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <stdio.h>.
+
+

Parameters

+ + + + +
stream - input file stream to read from
buffer - pointer to a null-terminated wide string to read from
format - pointer to a null-terminated wide string specifying how to read the input
vlist - variable argument list containing the receiving arguments.


The format string consists of

+

The following format specifiers are available:

+ + + + + + + + + + + + + + + +
Conversion
specifier 		Explanation Argument type
+Length modifier → +hh

(C99)

+		 +h (none) +l +ll

(C99)

+		 +j

(C99)

+		 +z

(C99)

+		 +t

(C99)

+		 +L
+% Matches literal %. N/A N/A N/A N/A N/A N/A N/A N/A N/A
+c Matches a character or a sequence of characters.

If a width specifier is used, matches exactly width wide characters (the argument must be a pointer to an array with sufficient room). Unlike %s and %[, does not append the null character to the array.

+		 N/A N/A +
char*
 +
wchar_t*
 N/A N/A N/A N/A N/A
+s Matches a sequence of non-whitespace characters (a string).

If width specifier is used, matches up to width or until the first whitespace character, whichever appears first. Always stores a null character in addition to the characters matched (so the argument array must have room for at least width+1 characters)

+
+[set] Matches a non-empty sequence of character from set of characters.

If the first character of the set is ^, then all characters not in the set are matched. If the set begins with ] or ^] then the ] character is also included into the set. It is implementation-defined whether the character - in the non-initial position in the scanset may be indicating a range, as in [0-9]. If width specifier is used, matches only up to width. Always stores a null character in addition to the characters matched (so the argument array must have room for at least width+1 characters)

+
+d Matches a decimal integer.

The format of the number is the same as expected by wcstol with the value 10 for the base argument

+		 +
+signed char* or unsigned char* +
 +
+signed short* or unsigned short* +
 +
+signed int* or unsigned int* +
 +
+signed long* or unsigned long* +
 +
+signed long long* or unsigned long long* +
 + + + N/A
+i Matches an integer.

The format of the number is the same as expected by wcstol with the value ​0​ for the base argument (base is determined by the first characters parsed)

+
+u Matches an unsigned decimal integer.

The format of the number is the same as expected by wcstoul with the value 10 for the base argument.

+
+o Matches an unsigned octal integer.

The format of the number is the same as expected by wcstoul with the value 8 for the base argument

+
+x, X Matches an unsigned hexadecimal integer.

The format of the number is the same as expected by wcstoul with the value 16 for the base argument

+
+n Returns the number of characters read so far.

No input is consumed. Does not increment the assignment count. If the specifier has assignment-suppressing operator defined, the behavior is undefined

+
+a, A(C99)
e, E
f, F(C99)
g, G 		Matches a floating-point number.

The format of the number is the same as expected by wcstof

+		 N/A N/A +
float*
 +
double*
 N/A N/A N/A N/A +
long double*
+p Matches implementation defined character sequence defining a pointer.

printf family of functions should produce the same sequence using %p format specifier

+		 N/A N/A +
void**
 N/A N/A N/A N/A N/A N/A

For every conversion specifier other than n, the longest sequence of input characters which does not exceed any specified field width and which either is exactly what the conversion specifier expects or is a prefix of a sequence it would expect, is what's consumed from the stream. The first character, if any, after this consumed sequence remains unread. If the consumed sequence has length zero or if the consumed sequence cannot be converted as specified above, the matching failure occurs unless end-of-file, an encoding error, or a read error prevented input from the stream, in which case it is an input failure.

+

All conversion specifiers other than [, c, and n consume and discard all leading whitespace characters (determined as if by calling iswspace) before attempting to parse the input. These consumed characters do not count towards the specified maximum field width.

+

If the length specifier l is not used, the conversion specifiers c, s, and [ perform wide-to-multibyte character conversion as if by calling wcrtomb with an mbstate_t object initialized to zero before the first character is converted.

+

The conversion specifiers s and [ always store the null terminator in addition to the matched characters. The size of the destination array must be at least one greater than the specified field width. The use of %s or %[, without specifying the destination array size, is as unsafe as gets.

+

The correct conversion specifications for the fixed-width integer types (int8_t, etc) are defined in the header <inttypes.h> (although SCNdMAX, SCNuMAX, etc is synonymous with %jd, %ju, etc).

+

There is a sequence point after the action of each conversion specifier; this permits storing multiple fields in the same "sink" variable.

+

When parsing an incomplete floating-point value that ends in the exponent with no digits, such as parsing "100er" with the conversion specifier %f, the sequence "100e" (the longest prefix of a possibly valid floating-point number) is consumed, resulting in a matching error (the consumed sequence cannot be converted to a floating-point number), with "r" remaining. Some existing implementations do not follow this rule and roll back to consume only "100", leaving "er", e.g. glibc bug 1765.

+

Return value

+1-3) Number of receiving arguments successfully assigned, or EOF if read failure occurs before the first receiving argument was assigned.
+4-6) Same as (1-3), except that EOF is also returned if there is a runtime constraint violation.

Notes

All these functions may invoke va_arg, the value of arg is indeterminate after the return. These functions to not invoke va_end, and it must be done by the caller.

+

Example

References

See also

+ +
+
(C95)(C95)(C95)(C11)(C11)(C11)
 reads formatted wide character input from stdin, a file stream or a buffer
(function)
C++ documentation for vwscanf, vfwscanf, vswscanf
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io/vfwscanf +

+
diff --git a/devdocs/c/io.html b/devdocs/c/io.html new file mode 100644 index 00000000..fb93bb9d --- /dev/null +++ b/devdocs/c/io.html @@ -0,0 +1,155 @@ +

File input/output

The <stdio.h> header provides generic file operation support and supplies functions with narrow character input/output capabilities.

+

The <wchar.h> header supplies functions with wide character input/output capabilities.

+

I/O streams are denoted by objects of type FILE that can only be accessed and manipulated through pointers of type FILE*. Each stream is associated with an external physical device (file, standard input stream, printer, serial port, etc).

+

Types

+ + +
Defined in header <stdio.h>
object type, capable of holding all information needed to control a C I/O stream
(typedef)
non-array complete object type, capable of uniquely specifying a position and multibyte parser state in a file
(typedef)

Predefined standard streams

+ +
Defined in header <stdio.h>
expression of type FILE* associated with the input stream
expression of type FILE* associated with the output stream
expression of type FILE* associated with the error output stream
(macro constant)

Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
File access
Defined in header <stdio.h>
+
(C11)
 opens a file
(function)
+
(C11)
 open an existing stream with a different name
(function)
closes a file
(function)
synchronizes an output stream with the actual file
(function)
sets the buffer for a file stream
(function)
sets the buffer and its size for a file stream
(function)
Defined in header <wchar.h>
+
(C95)
 switches a file stream between wide character I/O and narrow character I/O
(function)
Direct input/output
Defined in header <stdio.h>
reads from a file
(function)
writes to a file
(function)
Unformatted input/output
+
Narrow character
Defined in header <stdio.h>
gets a character from a file stream
(function)
gets a character string from a file stream
(function)
writes a character to a file stream
(function)
writes a character string to a file stream
(function)
reads a character from stdin
(function)
+
(removed in C11)(C11)
 reads a character string from stdin
(function)
writes a character to stdout
(function)
writes a character string to stdout
(function)
puts a character back into a file stream
(function)
+
Wide character
Defined in header <wchar.h>
+
(C95)
 gets a wide character from a file stream
(function)
+
(C95)
 gets a wide string from a file stream
(function)
+
(C95)
 writes a wide character to a file stream
(function)
+
(C95)
 writes a wide string to a file stream
(function)
+
(C95)
 reads a wide character from stdin
(function)
+
(C95)
 writes a wide character to stdout
(function)
+
(C95)
 puts a wide character back into a file stream
(function)
Formatted input/output
+
Narrow character
Defined in header <stdio.h>
+
(C11)(C11)(C11)
 reads formatted input from stdin, a file stream or a buffer
(function)
+
(C99)(C99)(C99)(C11)(C11)(C11)
 reads formatted input from stdin, a file stream or a buffer
using variable argument list
(function)
+
(C99)(C11)(C11)(C11)(C11)
 prints formatted output to stdout, a file stream or a buffer
(function)
+
(C99)(C11)(C11)(C11)(C11)
 prints formatted output to stdout, a file stream or a buffer
using variable argument list
(function)
+
Wide character
Defined in header <wchar.h>
+
(C95)(C95)(C95)(C11)(C11)(C11)
 reads formatted wide character input from stdin, a file stream or a buffer
(function)
+
(C99)(C99)(C99)(C11)(C11)(C11)
 reads formatted wide character input from stdin, a file stream
or a buffer using variable argument list
(function)
+
(C95)(C95)(C95)(C11)(C11)(C11)(C11)
 prints formatted wide character output to stdout, a file stream or a buffer
(function)
+
(C95)(C95)(C95)(C11)(C11)(C11)(C11)
 prints formatted wide character output to stdout, a file stream
or a buffer using variable argument list
(function)
File positioning
Defined in header <stdio.h>
returns the current file position indicator
(function)
gets the file position indicator
(function)
moves the file position indicator to a specific location in a file
(function)
moves the file position indicator to a specific location in a file
(function)
moves the file position indicator to the beginning in a file
(function)
Error handling
Defined in header <stdio.h>
clears errors
(function)
checks for the end-of-file
(function)
checks for a file error
(function)
displays a character string corresponding of the current error to stderr
(function)
Operations on files
Defined in header <stdio.h>
erases a file
(function)
renames a file
(function)
+
(C11)
 returns a pointer to a temporary file
(function)
+
(C11)
 returns a unique filename
(function)

Macro constants

+ + + + + + + + +
Defined in header <stdio.h>
EOF
 integer constant expression of type int and negative value
(macro constant)
FOPEN_MAX
 maximum number of files that can be open simultaneously
(macro constant)
FILENAME_MAX
 size needed for an array of char to hold the longest supported file name
(macro constant)
BUFSIZ
 size of the buffer used by setbuf
(macro constant)
_IOFBF_IOLBF_IONBF
 argument to setvbuf indicating fully buffered I/O
argument to setvbuf indicating line buffered I/O
argument to setvbuf indicating unbuffered I/O
(macro constant)
SEEK_SETSEEK_CURSEEK_END
 argument to fseek indicating seeking from beginning of the file
argument to fseek indicating seeking from the current file position
argument to fseek indicating seeking from end of the file
(macro constant)
TMP_MAXTMP_MAX_S
+
(C11)
 maximum number of unique filenames that can be generated by tmpnam
maximum number of unique filenames that can be generated by tmpnam_s
(macro constant)
L_tmpnamL_tmpnam_s
+
(C11)
 size needed for an array of char to hold the result of tmpnam
size needed for an array of char to hold the result of tmpnam_s
(macro constant)

References

See also

+
C++ documentation for C-style file input/output
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/io +

+
diff --git a/devdocs/c/keyword%2F_alignas.html b/devdocs/c/keyword%2F_alignas.html new file mode 100644 index 00000000..bde2435b --- /dev/null +++ b/devdocs/c/keyword%2F_alignas.html @@ -0,0 +1,7 @@ +

C keywords: _Alignas (since C11) +

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/_Alignas +

+
diff --git a/devdocs/c/keyword%2F_alignof.html b/devdocs/c/keyword%2F_alignof.html new file mode 100644 index 00000000..1b375956 --- /dev/null +++ b/devdocs/c/keyword%2F_alignof.html @@ -0,0 +1,7 @@ +

C keywords: _Alignof (since C11) +

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/_Alignof +

+
diff --git a/devdocs/c/keyword%2F_atomic.html b/devdocs/c/keyword%2F_atomic.html new file mode 100644 index 00000000..55a2aa4f --- /dev/null +++ b/devdocs/c/keyword%2F_atomic.html @@ -0,0 +1,7 @@ +

C keywords: _Atomic (since C11) +

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/_Atomic +

+
diff --git a/devdocs/c/keyword%2F_bool.html b/devdocs/c/keyword%2F_bool.html new file mode 100644 index 00000000..d55eedca --- /dev/null +++ b/devdocs/c/keyword%2F_bool.html @@ -0,0 +1,7 @@ +

C keywords: _Bool (since C99) +

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/_Bool +

+
diff --git a/devdocs/c/keyword%2F_complex.html b/devdocs/c/keyword%2F_complex.html new file mode 100644 index 00000000..0e2e8d93 --- /dev/null +++ b/devdocs/c/keyword%2F_complex.html @@ -0,0 +1,7 @@ +

C keywords: _Complex (since C99) +

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/_Complex +

+
diff --git a/devdocs/c/keyword%2F_decimal128.html b/devdocs/c/keyword%2F_decimal128.html new file mode 100644 index 00000000..87b08096 --- /dev/null +++ b/devdocs/c/keyword%2F_decimal128.html @@ -0,0 +1,7 @@ +

C keywords: _Decimal128 (since C23) +

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/_Decimal128 +

+
diff --git a/devdocs/c/keyword%2F_decimal32.html b/devdocs/c/keyword%2F_decimal32.html new file mode 100644 index 00000000..928701a0 --- /dev/null +++ b/devdocs/c/keyword%2F_decimal32.html @@ -0,0 +1,7 @@ +

C keywords: _Decimal32 (since C23) +

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/_Decimal32 +

+
diff --git a/devdocs/c/keyword%2F_decimal64.html b/devdocs/c/keyword%2F_decimal64.html new file mode 100644 index 00000000..b87c110e --- /dev/null +++ b/devdocs/c/keyword%2F_decimal64.html @@ -0,0 +1,7 @@ +

C keywords: _Decimal64 (since C23) +

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/_Decimal64 +

+
diff --git a/devdocs/c/keyword%2F_generic.html b/devdocs/c/keyword%2F_generic.html new file mode 100644 index 00000000..f03c65f1 --- /dev/null +++ b/devdocs/c/keyword%2F_generic.html @@ -0,0 +1,7 @@ +

C keywords: _Generic (since C11) +

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/_Generic +

+
diff --git a/devdocs/c/keyword%2F_imaginary.html b/devdocs/c/keyword%2F_imaginary.html new file mode 100644 index 00000000..10c0e039 --- /dev/null +++ b/devdocs/c/keyword%2F_imaginary.html @@ -0,0 +1,7 @@ +

C keywords: _Imaginary (since C99) +

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/_Imaginary +

+
diff --git a/devdocs/c/keyword%2F_noreturn.html b/devdocs/c/keyword%2F_noreturn.html new file mode 100644 index 00000000..c3748ec2 --- /dev/null +++ b/devdocs/c/keyword%2F_noreturn.html @@ -0,0 +1,11 @@ +

C keywords: _Noreturn (since C11) +

Usage

Notes

Since C23, _Noreturn is also attribute token. Its usage is deprecated and noreturn should be used instead.

+
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/_Noreturn +

+
diff --git a/devdocs/c/keyword%2F_static_assert.html b/devdocs/c/keyword%2F_static_assert.html new file mode 100644 index 00000000..b4f9e344 --- /dev/null +++ b/devdocs/c/keyword%2F_static_assert.html @@ -0,0 +1,7 @@ +

C keywords: _Static_assert (since C11)(deprecated in C23) +

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/_Static_assert +

+
diff --git a/devdocs/c/keyword%2F_thread_local.html b/devdocs/c/keyword%2F_thread_local.html new file mode 100644 index 00000000..79e40060 --- /dev/null +++ b/devdocs/c/keyword%2F_thread_local.html @@ -0,0 +1,7 @@ +

C keywords: _Thread_local (since C11) +

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/_Thread_local +

+
diff --git a/devdocs/c/keyword%2Falignas.html b/devdocs/c/keyword%2Falignas.html new file mode 100644 index 00000000..78e65700 --- /dev/null +++ b/devdocs/c/keyword%2Falignas.html @@ -0,0 +1,7 @@ +

C keywords: alignas (since C23) +

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/alignas +

+
diff --git a/devdocs/c/keyword%2Falignof.html b/devdocs/c/keyword%2Falignof.html new file mode 100644 index 00000000..41b8b990 --- /dev/null +++ b/devdocs/c/keyword%2Falignof.html @@ -0,0 +1,7 @@ +

C keywords: alignof (since C23) +

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/alignof +

+
diff --git a/devdocs/c/keyword%2Fauto.html b/devdocs/c/keyword%2Fauto.html new file mode 100644 index 00000000..6cad61f3 --- /dev/null +++ b/devdocs/c/keyword%2Fauto.html @@ -0,0 +1,9 @@ +

C keywords: auto

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/auto +

+
diff --git a/devdocs/c/keyword%2Fbool.html b/devdocs/c/keyword%2Fbool.html new file mode 100644 index 00000000..4407f54c --- /dev/null +++ b/devdocs/c/keyword%2Fbool.html @@ -0,0 +1,7 @@ +

C keywords: bool (since C23) +

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/bool +

+
diff --git a/devdocs/c/keyword%2Fbreak.html b/devdocs/c/keyword%2Fbreak.html new file mode 100644 index 00000000..6d735959 --- /dev/null +++ b/devdocs/c/keyword%2Fbreak.html @@ -0,0 +1,6 @@ +

C keywords: break

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/break +

+
diff --git a/devdocs/c/keyword%2Fcase.html b/devdocs/c/keyword%2Fcase.html new file mode 100644 index 00000000..5aab6fe8 --- /dev/null +++ b/devdocs/c/keyword%2Fcase.html @@ -0,0 +1,6 @@ +

C keywords: case

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/case +

+
diff --git a/devdocs/c/keyword%2Fchar.html b/devdocs/c/keyword%2Fchar.html new file mode 100644 index 00000000..b33defe4 --- /dev/null +++ b/devdocs/c/keyword%2Fchar.html @@ -0,0 +1,6 @@ +

C keywords: char

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/char +

+
diff --git a/devdocs/c/keyword%2Fconst.html b/devdocs/c/keyword%2Fconst.html new file mode 100644 index 00000000..91847f44 --- /dev/null +++ b/devdocs/c/keyword%2Fconst.html @@ -0,0 +1,6 @@ +

C keywords: const

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/const +

+
diff --git a/devdocs/c/keyword%2Fconstexpr.html b/devdocs/c/keyword%2Fconstexpr.html new file mode 100644 index 00000000..dbda609e --- /dev/null +++ b/devdocs/c/keyword%2Fconstexpr.html @@ -0,0 +1,7 @@ +

C keywords: constexpr (since C23) +

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/constexpr +

+
diff --git a/devdocs/c/keyword%2Fcontinue.html b/devdocs/c/keyword%2Fcontinue.html new file mode 100644 index 00000000..6abe8667 --- /dev/null +++ b/devdocs/c/keyword%2Fcontinue.html @@ -0,0 +1,6 @@ +

C keywords: continue

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/continue +

+
diff --git a/devdocs/c/keyword%2Fdefault.html b/devdocs/c/keyword%2Fdefault.html new file mode 100644 index 00000000..fc0a6ffc --- /dev/null +++ b/devdocs/c/keyword%2Fdefault.html @@ -0,0 +1,9 @@ +

C keywords: default

Usage

+ + +
(since C11)
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/default +

+
diff --git a/devdocs/c/keyword%2Fdo.html b/devdocs/c/keyword%2Fdo.html new file mode 100644 index 00000000..00569117 --- /dev/null +++ b/devdocs/c/keyword%2Fdo.html @@ -0,0 +1,6 @@ +

C keywords: do

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/do +

+
diff --git a/devdocs/c/keyword%2Fdouble.html b/devdocs/c/keyword%2Fdouble.html new file mode 100644 index 00000000..00ca703b --- /dev/null +++ b/devdocs/c/keyword%2Fdouble.html @@ -0,0 +1,9 @@ +

C keywords: double

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/double +

+
diff --git a/devdocs/c/keyword%2Felse.html b/devdocs/c/keyword%2Felse.html new file mode 100644 index 00000000..ccdbf159 --- /dev/null +++ b/devdocs/c/keyword%2Felse.html @@ -0,0 +1,6 @@ +

C keywords: else

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/else +

+
diff --git a/devdocs/c/keyword%2Fenum.html b/devdocs/c/keyword%2Fenum.html new file mode 100644 index 00000000..0d1bf040 --- /dev/null +++ b/devdocs/c/keyword%2Fenum.html @@ -0,0 +1,6 @@ +

C keywords: enum

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/enum +

+
diff --git a/devdocs/c/keyword%2Fextern.html b/devdocs/c/keyword%2Fextern.html new file mode 100644 index 00000000..aeb3612f --- /dev/null +++ b/devdocs/c/keyword%2Fextern.html @@ -0,0 +1,6 @@ +

C keywords: extern

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/extern +

+
diff --git a/devdocs/c/keyword%2Ffalse.html b/devdocs/c/keyword%2Ffalse.html new file mode 100644 index 00000000..4653d07c --- /dev/null +++ b/devdocs/c/keyword%2Ffalse.html @@ -0,0 +1,7 @@ +

C keywords: false (since C23) +

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/false +

+
diff --git a/devdocs/c/keyword%2Ffloat.html b/devdocs/c/keyword%2Ffloat.html new file mode 100644 index 00000000..e64ee539 --- /dev/null +++ b/devdocs/c/keyword%2Ffloat.html @@ -0,0 +1,6 @@ +

C keywords: float

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/float +

+
diff --git a/devdocs/c/keyword%2Ffor.html b/devdocs/c/keyword%2Ffor.html new file mode 100644 index 00000000..0d679e7e --- /dev/null +++ b/devdocs/c/keyword%2Ffor.html @@ -0,0 +1,6 @@ +

C keywords: for

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/for +

+
diff --git a/devdocs/c/keyword%2Ffortran.html b/devdocs/c/keyword%2Ffortran.html new file mode 100644 index 00000000..f037b456 --- /dev/null +++ b/devdocs/c/keyword%2Ffortran.html @@ -0,0 +1,6 @@ +

C keywords: fortran

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/fortran +

+
diff --git a/devdocs/c/keyword%2Fgoto.html b/devdocs/c/keyword%2Fgoto.html new file mode 100644 index 00000000..0fd18ac3 --- /dev/null +++ b/devdocs/c/keyword%2Fgoto.html @@ -0,0 +1,6 @@ +

C keywords: goto

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/goto +

+
diff --git a/devdocs/c/keyword%2Fif.html b/devdocs/c/keyword%2Fif.html new file mode 100644 index 00000000..b873d649 --- /dev/null +++ b/devdocs/c/keyword%2Fif.html @@ -0,0 +1,6 @@ +

C keywords: if

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/if +

+
diff --git a/devdocs/c/keyword%2Finline.html b/devdocs/c/keyword%2Finline.html new file mode 100644 index 00000000..5367ee73 --- /dev/null +++ b/devdocs/c/keyword%2Finline.html @@ -0,0 +1,7 @@ +

C keywords: inline (since C99) +

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/inline +

+
diff --git a/devdocs/c/keyword%2Fint.html b/devdocs/c/keyword%2Fint.html new file mode 100644 index 00000000..8d181ebb --- /dev/null +++ b/devdocs/c/keyword%2Fint.html @@ -0,0 +1,6 @@ +

C keywords: int

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/int +

+
diff --git a/devdocs/c/keyword%2Flong.html b/devdocs/c/keyword%2Flong.html new file mode 100644 index 00000000..6e559f1f --- /dev/null +++ b/devdocs/c/keyword%2Flong.html @@ -0,0 +1,6 @@ +

C keywords: long

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/long +

+
diff --git a/devdocs/c/keyword%2Fnullptr.html b/devdocs/c/keyword%2Fnullptr.html new file mode 100644 index 00000000..16b3ddd4 --- /dev/null +++ b/devdocs/c/keyword%2Fnullptr.html @@ -0,0 +1,7 @@ +

C keywords: nullptr (since C23) +

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/nullptr +

+
diff --git a/devdocs/c/keyword%2Fregister.html b/devdocs/c/keyword%2Fregister.html new file mode 100644 index 00000000..a834474b --- /dev/null +++ b/devdocs/c/keyword%2Fregister.html @@ -0,0 +1,6 @@ +

C keywords: register

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/register +

+
diff --git a/devdocs/c/keyword%2Frestrict.html b/devdocs/c/keyword%2Frestrict.html new file mode 100644 index 00000000..49912f71 --- /dev/null +++ b/devdocs/c/keyword%2Frestrict.html @@ -0,0 +1,7 @@ +

C keywords: restrict (since C99) +

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/restrict +

+
diff --git a/devdocs/c/keyword%2Freturn.html b/devdocs/c/keyword%2Freturn.html new file mode 100644 index 00000000..071d7eed --- /dev/null +++ b/devdocs/c/keyword%2Freturn.html @@ -0,0 +1,6 @@ +

C keywords: return

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/return +

+
diff --git a/devdocs/c/keyword%2Fshort.html b/devdocs/c/keyword%2Fshort.html new file mode 100644 index 00000000..09e595ea --- /dev/null +++ b/devdocs/c/keyword%2Fshort.html @@ -0,0 +1,6 @@ +

C keywords: short

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/short +

+
diff --git a/devdocs/c/keyword%2Fsigned.html b/devdocs/c/keyword%2Fsigned.html new file mode 100644 index 00000000..c82e12e4 --- /dev/null +++ b/devdocs/c/keyword%2Fsigned.html @@ -0,0 +1,6 @@ +

C keywords: signed

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/signed +

+
diff --git a/devdocs/c/keyword%2Fsizeof.html b/devdocs/c/keyword%2Fsizeof.html new file mode 100644 index 00000000..d1d25e39 --- /dev/null +++ b/devdocs/c/keyword%2Fsizeof.html @@ -0,0 +1,6 @@ +

C keywords: sizeof

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/sizeof +

+
diff --git a/devdocs/c/keyword%2Fstatic.html b/devdocs/c/keyword%2Fstatic.html new file mode 100644 index 00000000..b76c7dc4 --- /dev/null +++ b/devdocs/c/keyword%2Fstatic.html @@ -0,0 +1,12 @@ +

C keywords: static

Usage

+ + +
(since C99)
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/static +

+
diff --git a/devdocs/c/keyword%2Fstatic_assert.html b/devdocs/c/keyword%2Fstatic_assert.html new file mode 100644 index 00000000..c3244b1b --- /dev/null +++ b/devdocs/c/keyword%2Fstatic_assert.html @@ -0,0 +1,7 @@ +

C keywords: static_assert (since C23) +

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/static_assert +

+
diff --git a/devdocs/c/keyword%2Fstruct.html b/devdocs/c/keyword%2Fstruct.html new file mode 100644 index 00000000..a9487bb0 --- /dev/null +++ b/devdocs/c/keyword%2Fstruct.html @@ -0,0 +1,6 @@ +

C keywords: struct

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/struct +

+
diff --git a/devdocs/c/keyword%2Fswitch.html b/devdocs/c/keyword%2Fswitch.html new file mode 100644 index 00000000..d8ffb988 --- /dev/null +++ b/devdocs/c/keyword%2Fswitch.html @@ -0,0 +1,6 @@ +

C keywords: switch

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/switch +

+
diff --git a/devdocs/c/keyword%2Fthread_local.html b/devdocs/c/keyword%2Fthread_local.html new file mode 100644 index 00000000..3995ff16 --- /dev/null +++ b/devdocs/c/keyword%2Fthread_local.html @@ -0,0 +1,7 @@ +

C keywords: thread_local (since C23) +

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/thread_local +

+
diff --git a/devdocs/c/keyword%2Ftrue.html b/devdocs/c/keyword%2Ftrue.html new file mode 100644 index 00000000..be5beda8 --- /dev/null +++ b/devdocs/c/keyword%2Ftrue.html @@ -0,0 +1,7 @@ +

C keywords: true (since C23) +

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/true +

+
diff --git a/devdocs/c/keyword%2Ftypedef.html b/devdocs/c/keyword%2Ftypedef.html new file mode 100644 index 00000000..bed6e86e --- /dev/null +++ b/devdocs/c/keyword%2Ftypedef.html @@ -0,0 +1,6 @@ +

C keywords: typedef

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/typedef +

+
diff --git a/devdocs/c/keyword%2Ftypeof.html b/devdocs/c/keyword%2Ftypeof.html new file mode 100644 index 00000000..8bfdee21 --- /dev/null +++ b/devdocs/c/keyword%2Ftypeof.html @@ -0,0 +1,7 @@ +

C keywords: typeof (since C23) +

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/typeof +

+
diff --git a/devdocs/c/keyword%2Ftypeof_unqual.html b/devdocs/c/keyword%2Ftypeof_unqual.html new file mode 100644 index 00000000..b328be5d --- /dev/null +++ b/devdocs/c/keyword%2Ftypeof_unqual.html @@ -0,0 +1,7 @@ +

C keywords: typeof_unqual (since C23) +

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/typeof_unqual +

+
diff --git a/devdocs/c/keyword%2Funion.html b/devdocs/c/keyword%2Funion.html new file mode 100644 index 00000000..92b91d8c --- /dev/null +++ b/devdocs/c/keyword%2Funion.html @@ -0,0 +1,6 @@ +

C keywords: union

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/union +

+
diff --git a/devdocs/c/keyword%2Funsigned.html b/devdocs/c/keyword%2Funsigned.html new file mode 100644 index 00000000..069a53c0 --- /dev/null +++ b/devdocs/c/keyword%2Funsigned.html @@ -0,0 +1,6 @@ +

C keywords: unsigned

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/unsigned +

+
diff --git a/devdocs/c/keyword%2Fvoid.html b/devdocs/c/keyword%2Fvoid.html new file mode 100644 index 00000000..9e6b2301 --- /dev/null +++ b/devdocs/c/keyword%2Fvoid.html @@ -0,0 +1,9 @@ +

C keywords: void

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/void +

+
diff --git a/devdocs/c/keyword%2Fvolatile.html b/devdocs/c/keyword%2Fvolatile.html new file mode 100644 index 00000000..808b0dd2 --- /dev/null +++ b/devdocs/c/keyword%2Fvolatile.html @@ -0,0 +1,6 @@ +

C keywords: volatile

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/volatile +

+
diff --git a/devdocs/c/keyword%2Fwhile.html b/devdocs/c/keyword%2Fwhile.html new file mode 100644 index 00000000..d66bcaac --- /dev/null +++ b/devdocs/c/keyword%2Fwhile.html @@ -0,0 +1,9 @@ +

C keywords: while

Usage

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword/while +

+
diff --git a/devdocs/c/keyword.html b/devdocs/c/keyword.html new file mode 100644 index 00000000..eff12747 --- /dev/null +++ b/devdocs/c/keyword.html @@ -0,0 +1,111 @@ +

C keywords

This is a list of reserved keywords in C. Since they are used by the language, these keywords are not available for re-definition. As an exception, they are not considered reserved in attribute-tokens(since C23)

+ + +

alignas (C23)
alignof (C23)
auto
bool (C23)
break
case
char
const
constexpr (C23)
continue
default
do
double
else
enum

+

extern
false (C23)
float
for
goto
if
inline (C99)
int
long
nullptr (C23)
register
restrict (C99)
return
short
signed

+

sizeof
static
static_assert (C23)
struct
switch
thread_local (C23)
true (C23)
typedef
typeof (C23)
typeof_unqual (C23)
union
unsigned
void
volatile
while

+

_Alignas (C11)
_Alignof (C11)
_Atomic (C11)
_BitInt (C23)
_Bool (C99)
_Complex (C99)
_Decimal128 (C23)
_Decimal32 (C23)
_Decimal64 (C23)
_Generic (C11)
_Imaginary (C99)
_Noreturn (C11)
_Static_assert (C11)
_Thread_local (C11)

+

The most common keywords that begin with an underscore are generally used through their convenience macros:

+ + + + + + + + + + + + + + + + +
keyword used as defined in
+_Alignas (C11) +alignas (removed in C23) +stdalign.h
+_Alignof (C11) +alignof (removed in C23) +stdalign.h
+_Atomic (C11) +atomic_bool, atomic_int, ... +stdatomic.h
+_BitInt (C23) (no macro)
+_Bool (C99) +bool (removed in C23) +stdbool.h
+_Complex (C99) +complex +complex.h
+_Decimal128 (C23) (no macro)
+_Decimal32 (C23) (no macro)
+_Decimal64 (C23) (no macro)
+_Generic (C11) (no macro)
+_Imaginary (C99) +imaginary +complex.h
+_Noreturn (C11) +noreturn +stdnoreturn.h
+_Static_assert (C11) +static_assert (removed in C23) +assert.h
+_Thread_local (C11) +thread_local (removed in C23) +threads.h

Also, each name that begins with a double underscore __ or an underscore _ followed by an uppercase letter is reserved: see identifier for details.

+

Note that digraphs <%, %>, <:, :>, %:, and %:%: provide an alternative way to represent standard tokens.

+

The following tokens are recognized by the preprocessor when they are used within the context of a preprocessor directive:

+ + +

if
elif
else
endif

+

ifdef
ifndef
elifdef (C23)
elifndef (C23)
define
undef

+

include
embed (C23)
line
error
warning (C23)
pragma

+

defined
__has_include (C23)
__has_embed (C23)
__has_c_attribute (C23)

+

The following tokens are recognized by the preprocessor when they are used outside the context of a preprocessor directive:

+ + +

_Pragma (C99)

+

The following additional keywords are classified as extensions and conditionally-supported:

+ + +

asm
fortran

+

References

See also

+
C++ documentation for C++ keywords
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/keyword +

+
diff --git a/devdocs/c/language%2F_alignas.html b/devdocs/c/language%2F_alignas.html new file mode 100644 index 00000000..ea0b1aa4 --- /dev/null +++ b/devdocs/c/language%2F_alignas.html @@ -0,0 +1,85 @@ +

_Alignas (since C11), alignas (since C23) +

Appears in the declaration syntax as one of the type specifiers to modify the alignment requirement of the object being declared.

+

Syntax

+ + + + +
_Alignas ( expression ) (1) (since C11)
alignas ( expression ) (2) (since C23)
_Alignas ( type ) (3) (since C11)
alignas ( type ) (4) (since C23)
+ + +
expression - any integer constant expression whose value is a valid alignment or zero
type - any type name
+ +

The keyword _Alignas is also available as convenience macro alignas, available in the header <stdalign.h>.

+		 (until C23)

Explanation

The _Alignas(until C23)alignas(since C23) specifier can only be used when declaring objects that are not bit-fields, and don't have the register storage class. It cannot be used in function parameter declarations, and cannot be used in a typedef.

+

When used in a declaration, the declared object will have its alignment requirement set to

+
+1,2) the result of the expression, unless it is zero
+3,4) the alignment requirement of type, that is, to _Alignof(type)(until C23)alignof(type)(since C23) +

except when this would weaken the alignment the type would have had naturally.

+

If expression evaluates to zero, this specifier has no effect.

+

When multiple _Alignas(until C23)alignas(since C23) specifiers appear in the same declaration, the strictest one is used.

+

_Alignas(until C23)alignas(since C23) specifier only needs to appear on the definition of an object, but if any declaration uses _Alignas(until C23)alignas(since C23), it must specify the same alignment as the _Alignas(until C23)alignas(since C23) on the definition. The behavior is undefined if different translation units specify different alignments for the same object.

+

Notes

In C++, the alignas specifier may also be applied to the declarations of class/struct/union types and enumerations. This is not supported in C, but the alignment of a struct type can be controlled by using _Alignas(until C23)alignas(since C23) in a member declaration.

+

Keywords

alignas, _Alignas

+

Example

#include <stdalign.h>
+#include <stdio.h>
+ 
+// every object of type struct sse_t will be aligned to 16-byte boundary
+// (note: needs support for DR 444)
+struct sse_t
+{
+    alignas(16) float sse_data[4];
+};
+ 
+// every object of type struct data will be aligned to 128-byte boundary
+struct data
+{
+    char x;
+    alignas(128) char cacheline[128]; // over-aligned array of char,
+                                      // not array of over-aligned chars
+};
+ 
+int main(void)
+{
+    printf("sizeof(data) = %zu (1 byte + 127 bytes padding + 128-byte array)\n",
+           sizeof(struct data));
+ 
+    printf("alignment of sse_t is %zu\n", alignof(struct sse_t));
+ 
+    alignas(2048) struct data d; // this instance of data is aligned even stricter
+    (void)d; // suppresses "maybe unused" warning
+}

Output:

+
sizeof(data) = 256 (1 byte + 127 bytes padding + 128-byte array)
+alignment of sse_t is 16

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C standards.

+ + + +
DR Applied to Behavior as published Correct behavior
+DR 444 C11 +_Alignas was not allowed in struct and union members allowed

References

See also

+
C++ documentation for alignas specifier
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/_Alignas +

+
diff --git a/devdocs/c/language%2F_alignof.html b/devdocs/c/language%2F_alignof.html new file mode 100644 index 00000000..1a478589 --- /dev/null +++ b/devdocs/c/language%2F_alignof.html @@ -0,0 +1,51 @@ +

_Alignof operator (since C11) +

Queries the alignment requirement of its operand type.

+

Syntax

+ + +
_Alignof( type-name ) (since C11)
alignof( type-name ) (since C23)
+ +

This operator is typically used through the convenience macro alignof, which is provided in the header <stdalign.h>

+		 (until C23)

Explanation

Returns the alignment requirement of the type named by type-name. If type-name is an array type, the result is the alignment requirement of the array element type. The type-name cannot be function type or an incomplete type.

+

The result is an integer constant of type size_t.

+

The operand is not evaluated (so external identifiers used in the operand do not have to be defined).

+

If type-name is a VLA type, its size expression is not evaluated.

+

Notes

The use of _Alignof(until C23)alignof(since C23) with expressions is allowed by some C compilers as a non-standard extension.

+

Keywords

alignof, _Alignof

+

Example

#include <stdalign.h>
+#include <stddef.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    printf("Alignment of char = %zu\n", alignof(char));
+    printf("Alignment of max_align_t = %zu\n", alignof(max_align_t));
+    printf("alignof(float[10]) = %zu\n", alignof(float[10]));
+    printf("alignof(struct{char c; int n;}) = %zu\n",
+            alignof(struct {char c; int n;}));
+}

Possible output:

+
Alignment of char = 1
+Alignment of max_align_t = 16
+alignof(float[10]) = 4
+alignof(struct{char c; int n;}) = 4

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C standards.

+ + + +
DR Applied to Behavior as published Correct behavior
+DR 494 C11 whether the size expression in a VLA is evaluated in _Alignof was unspecified it is unevaluated

References

See also

+ + +
+
(C11)
 a type with alignment requirement as great as any other scalar type
(typedef)
_Alignas specifier(C11) sets alignment requirements of an object
C++ documentation for alignof operator
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/_Alignof +

+
diff --git a/devdocs/c/language%2F_noreturn.html b/devdocs/c/language%2F_noreturn.html new file mode 100644 index 00000000..ff87fe14 --- /dev/null +++ b/devdocs/c/language%2F_noreturn.html @@ -0,0 +1,61 @@ +

_Noreturn function specifier

Specifies that the function does not return to its point of invocation.

+

Syntax

+ +
_Noreturn function_declaration (since C11)(deprecated in C23)

Explanation

The _Noreturn keyword appears in a function declaration and specifies that the function does not return by executing the return statement or by reaching the end of the function body (it may return by executing longjmp). If the function declared _Noreturn returns, the behavior is undefined. A compiler diagnostic is recommended if this can be detected.

+

The _Noreturn specifier may appear more than once in the same function declaration, the behavior is the same as if it appeared once.

+

This specifier is typically used through the convenience macro noreturn, which is provided in the header <stdnoreturn.h>.

+ + +

_Noreturn function specifier is deprecated. [[noreturn]] attribute should be used instead.

+

The macro noreturn is also deprecated.

+		 (since C23)

Keywords

_Noreturn

+

Standard library

The following functions are noreturn in the standard library:

+

Example

#include <stdio.h>
+#include <stdlib.h>
+#include <stdnoreturn.h>
+ 
+// causes undefined behavior if i <= 0
+// exits if i > 0
+noreturn void exit_now(int i) // or _Noreturn void exit_now(int i)
+{
+    if (i > 0)
+        exit(i);
+}
+ 
+int main(void)
+{
+    puts("Preparing to exit...");
+    exit_now(2);
+    puts("This code is never executed.");
+}

Output:

+
Preparing to exit...

References

See also

+ +
[[noreturn]](C23)
[[_Noreturn]](C23)(deprecated) 		indicates that the function does not return
(attribute specifier)
C++ documentation for [[noreturn]]
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/_Noreturn +

+
diff --git a/devdocs/c/language%2F_static_assert.html b/devdocs/c/language%2F_static_assert.html new file mode 100644 index 00000000..9ceeb593 --- /dev/null +++ b/devdocs/c/language%2F_static_assert.html @@ -0,0 +1,58 @@ +

Static assertion (since C11) +

Syntax

+ + + + +
_Static_assert ( expression , message ) (since C11)(deprecated in C23)
static_assert ( expression , message ) (since C23)
_Static_assert ( expression ) (since C23)(deprecated in C23)
static_assert ( expression ) (since C23)
+ + +
expression - any integer constant expression
message - any string literal
+ + + +

This keyword is also available as convenience macro static_assert, available in the header <assert.h>.

+		 (until C23)

Both of static_assert and _Static_assert have the same effects. _Static_assert is a deprecated spelling that is kept for compatibility.

+

An implementation may also define static_assert and/or _Static_assert as predefined macros, and static_assert is no longer provided by <assert.h>.

+		 (since C23)

Explanation

The constant expression is evaluated at compile time and compared to zero. If it compares equal to zero, a compile-time error occurs and the compiler must display message as part of the error message (except that characters not in basic character set are not required to be displayed)(until C23)should display message (if provided) as part of the error message(since C23).

+

Otherwise, if expression does not equal zero, nothing happens; no code is emitted.

+

Keywords

_Static_assert, static_assert

+

Example

#include <assert.h> // no longer needed since C23
+ 
+int main(void)
+{
+    // Test if math works, C23:
+    static_assert((2 + 2) % 3 == 1, "Whoa dude, you knew!");
+    // Pre-C23 alternative:
+    _Static_assert(2 + 2 * 2 == 6, "Lucky guess!?");
+ 
+    // This will produce an error at compile time.
+    // static_assert(sizeof(int) < sizeof(char), "Unmet condition!");
+ 
+    constexpr int _42 = 2 * 3 * 2 * 3 + 2 * 3;
+    static_assert(_42 == 42); // the message string can be omitted.
+ 
+    // const int _13 = 13;
+    // Compile time error - not an integer constant expression:
+    // static_assert(_13 == 13);
+}

References

See also

+ +
aborts the program if the user-specified condition is not true. May be disabled for release builds
(function macro)
C++ documentation for static_assert declaration
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/_Static_assert +

+
diff --git a/devdocs/c/language%2Falignas.html b/devdocs/c/language%2Falignas.html new file mode 100644 index 00000000..7ea68a4b --- /dev/null +++ b/devdocs/c/language%2Falignas.html @@ -0,0 +1,85 @@ +

_Alignas (since C11), alignas (since C23) +

Appears in the declaration syntax as one of the type specifiers to modify the alignment requirement of the object being declared.

+

Syntax

+ + + + +
_Alignas ( expression ) (1) (since C11)
alignas ( expression ) (2) (since C23)
_Alignas ( type ) (3) (since C11)
alignas ( type ) (4) (since C23)
+ + +
expression - any integer constant expression whose value is a valid alignment or zero
type - any type name
+ +

The keyword _Alignas is also available as convenience macro alignas, available in the header <stdalign.h>.

+		 (until C23)

Explanation

The _Alignas(until C23)alignas(since C23) specifier can only be used when declaring objects that are not bit-fields, and don't have the register storage class. It cannot be used in function parameter declarations, and cannot be used in a typedef.

+

When used in a declaration, the declared object will have its alignment requirement set to

+
+1,2) the result of the expression, unless it is zero
+3,4) the alignment requirement of type, that is, to _Alignof(type)(until C23)alignof(type)(since C23) +

except when this would weaken the alignment the type would have had naturally.

+

If expression evaluates to zero, this specifier has no effect.

+

When multiple _Alignas(until C23)alignas(since C23) specifiers appear in the same declaration, the strictest one is used.

+

_Alignas(until C23)alignas(since C23) specifier only needs to appear on the definition of an object, but if any declaration uses _Alignas(until C23)alignas(since C23), it must specify the same alignment as the _Alignas(until C23)alignas(since C23) on the definition. The behavior is undefined if different translation units specify different alignments for the same object.

+

Notes

In C++, the alignas specifier may also be applied to the declarations of class/struct/union types and enumerations. This is not supported in C, but the alignment of a struct type can be controlled by using _Alignas(until C23)alignas(since C23) in a member declaration.

+

Keywords

alignas, _Alignas

+

Example

#include <stdalign.h>
+#include <stdio.h>
+ 
+// every object of type struct sse_t will be aligned to 16-byte boundary
+// (note: needs support for DR 444)
+struct sse_t
+{
+    alignas(16) float sse_data[4];
+};
+ 
+// every object of type struct data will be aligned to 128-byte boundary
+struct data
+{
+    char x;
+    alignas(128) char cacheline[128]; // over-aligned array of char,
+                                      // not array of over-aligned chars
+};
+ 
+int main(void)
+{
+    printf("sizeof(data) = %zu (1 byte + 127 bytes padding + 128-byte array)\n",
+           sizeof(struct data));
+ 
+    printf("alignment of sse_t is %zu\n", alignof(struct sse_t));
+ 
+    alignas(2048) struct data d; // this instance of data is aligned even stricter
+    (void)d; // suppresses "maybe unused" warning
+}

Output:

+
sizeof(data) = 256 (1 byte + 127 bytes padding + 128-byte array)
+alignment of sse_t is 16

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C standards.

+ + + +
DR Applied to Behavior as published Correct behavior
+DR 444 C11 +_Alignas was not allowed in struct and union members allowed

References

See also

+
C++ documentation for alignas specifier
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/alignas +

+
diff --git a/devdocs/c/language%2Falignof.html b/devdocs/c/language%2Falignof.html new file mode 100644 index 00000000..3319be77 --- /dev/null +++ b/devdocs/c/language%2Falignof.html @@ -0,0 +1,51 @@ +

_Alignof operator (since C11) +

Queries the alignment requirement of its operand type.

+

Syntax

+ + +
_Alignof( type-name ) (since C11)
alignof( type-name ) (since C23)
+ +

This operator is typically used through the convenience macro alignof, which is provided in the header <stdalign.h>

+		 (until C23)

Explanation

Returns the alignment requirement of the type named by type-name. If type-name is an array type, the result is the alignment requirement of the array element type. The type-name cannot be function type or an incomplete type.

+

The result is an integer constant of type size_t.

+

The operand is not evaluated (so external identifiers used in the operand do not have to be defined).

+

If type-name is a VLA type, its size expression is not evaluated.

+

Notes

The use of _Alignof(until C23)alignof(since C23) with expressions is allowed by some C compilers as a non-standard extension.

+

Keywords

alignof, _Alignof

+

Example

#include <stdalign.h>
+#include <stddef.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    printf("Alignment of char = %zu\n", alignof(char));
+    printf("Alignment of max_align_t = %zu\n", alignof(max_align_t));
+    printf("alignof(float[10]) = %zu\n", alignof(float[10]));
+    printf("alignof(struct{char c; int n;}) = %zu\n",
+            alignof(struct {char c; int n;}));
+}

Possible output:

+
Alignment of char = 1
+Alignment of max_align_t = 16
+alignof(float[10]) = 4
+alignof(struct{char c; int n;}) = 4

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C standards.

+ + + +
DR Applied to Behavior as published Correct behavior
+DR 494 C11 whether the size expression in a VLA is evaluated in _Alignof was unspecified it is unevaluated

References

See also

+ + +
+
(C11)
 a type with alignment requirement as great as any other scalar type
(typedef)
_Alignas specifier(C11) sets alignment requirements of an object
C++ documentation for alignof operator
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/alignof +

+
diff --git a/devdocs/c/language%2Fanalyzability.html b/devdocs/c/language%2Fanalyzability.html new file mode 100644 index 00000000..5a8213a0 --- /dev/null +++ b/devdocs/c/language%2Fanalyzability.html @@ -0,0 +1,49 @@ +

Analyzability

This optional extension to the C language limits the potential results of executing some forms of undefined behavior, which improves the effectiveness of static analysis of such programs. Analyzability is only guaranteed to be enabled if the predefined macro constant __STDC_ANALYZABLE__(C11) is defined by the compiler.

+

If the compiler supports analyzability, any language or library construct whose behavior is undefined is further classified between critical and bounded undefined behavior, and the behavior of all bounded UB cases is limited as specified below.

+

Critical undefined behavior

Critical UB is undefined behavior that might perform a memory write or a volatile memory read out of bounds of any object. A program that has critical undefined behavior may be susceptible to security exploits.

+

Only the following undefined behaviors are critical:

+

Bounded undefined behavior

Bounded UB is undefined behavior that cannot perform an illegal memory write, although it may trap and may produce or store indeterminate values.

+

Notes

Bounded undefined behavior disables certain optimizations: compilation with analyzability enabled preserves source-code causality, which may be violated by undefined behavior otherwise.

+

Analyzability extension permits, as a form of implementation-defined behavior, for the runtime constraint handler to be invoked when a trap occurs.

+

References

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/analyzability +

+
diff --git a/devdocs/c/language%2Farithmetic_types.html b/devdocs/c/language%2Farithmetic_types.html new file mode 100644 index 00000000..d3423d5a --- /dev/null +++ b/devdocs/c/language%2Farithmetic_types.html @@ -0,0 +1,302 @@ +

Arithmetic types

(See also type for type system overview and the list of type-related utilities that are provided by the C library.)

+ + +

Boolean type

  • _Bool (also accessible as the macro bool)(until C23)bool(since C23) - type, capable of holding one of the two values: 1 and ​0​ (also accessible as the macros true and false)(until C23)true and false(since C23).

Note that conversion to _Bool(until C23)bool(since C23) does not work the same as conversion to other integer types: (bool)0.5 evaluates to true, whereas (int)0.5 evaluates to ​0​.

+		 (since C99)

Character types

Note that the standard library also defines typedef names wchar_t , char16_t and char32_t(since C11) to represent wide characters and char8_t for UTF-8 characters(since C23).

+

Integer types

This is the most optimal integer type for the platform, and is guaranteed to be at least 16 bits. Most current systems use 32 bits (see Data models below). + + + +
    +
  • +long long int (also accessible as long long)
    • +
  • +unsigned long long int (also accessible as unsigned long long)
    • +
 (since C99)
    +
  • +_BitInt(n) (also accessible as signed _BitInt(n)), the bit-precise signed integer types (where n is replaced by an integer constant expression denoting the precise width (including the sign bit), that cannot be larger than BITINT_MAXWIDTH from <limits.h>)
    • +
  • +unsigned _BitInt(n), the bit-precise unsigned integer types (where n is replaced by an integer constant expression denoting the precise width, that cannot be larger than BITINT_MAXWIDTH from <limits.h>)
    • +
 (since C23)

Note: as with all type specifiers, any order is permitted: unsigned long long int and long int unsigned long name the same type.

+

The following table summarizes all available integer types and their properties:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Type specifier Equivalent type Width in bits by data model
C standard LP32 ILP32 LLP64 LP64 
char
 char at least
8 		8 8 8 8 
signed char
 signed char 
unsigned char
 unsigned char 
short
 short int at least
16 		16 16 16 16 
short int
signed short
signed short int
unsigned short
 unsigned short int 
unsigned short int
int
 int at least
16 		16 32 32 32 
signed
signed int
unsigned
 unsigned int 
unsigned int
long
 long int at least
32 		32 32 32 64 
long int
signed long
signed long int
unsigned long
 unsigned long int 
unsigned long int
long long
 long long int
(C99) 		at least
64 		64 64 64 64 
long long int
signed long long
signed long long int
unsigned long long
 unsigned long long int
(C99) 
unsigned long long int

Besides the minimal bit counts, the C Standard guarantees that 1 == sizeof(char) ≤ sizeof(short) ≤ sizeof(int) ≤ sizeof(long) ≤ sizeof(long long).

+

Note: this allows the extreme case in which byte are sized 64 bits, all types (including char) are 64 bits wide, and sizeof returns 1 for every type.

+

Note: integer arithmetic is defined differently for the signed and unsigned integer types. See arithmetic operators, in particular integer overflows.

+

Data models

The choices made by each implementation about the sizes of the fundamental types are collectively known as data model. Four data models found wide acceptance:

+

32 bit systems:

+

64 bit systems:

+

Other models are very rare. For example, ILP64 (8/8/8: int, long, and pointer are 64-bit) only appeared in some early 64-bit Unix systems (e.g. Unicos on Cray).

+

Note that exact-width integer types are available in <stdint.h> since C99.

+

Real floating types

C has three or six(since C23) types for representing real floating-point values:

+ + +
+
If the implementation predefines the macro constant __STDC_IEC_60559_DFP__, the following decimal floating-point types are also supported.
+
Otherwise, these decimal floating-point types are not supported.
+
 (since C23)

Floating-point types may support special values:

+

Real floating-point numbers may be used with arithmetic operators + - / * and various mathematical functions from <math.h>. Both built-in operators and library functions may raise floating-point exceptions and set errno as described in math_errhandling.

+

Floating-point expressions may have greater range and precision than indicated by their types, see FLT_EVAL_METHOD. Assignment, return, and cast force the range and precision to the one associated with the declared type.

+

Floating-point expressions may also be contracted, that is, calculated as if all intermediate values have infinite range and precision, see #pragma STDC FP_CONTRACT.

+

Some operations on floating-point numbers are affected by and modify the state of the floating-point environment (most notably, the rounding direction).

+

Implicit conversions are defined between real floating types and integer, complex, and imaginary types.

+

See Limits of floating-point types and the <math.h> library for additional details, limits, and properties of the floating-point types.

+ + +

Complex floating types

Complex floating types model the mathematical complex number, that is the numbers that can be written as a sum of a real number and a real number multiplied by the imaginary unit: a + bi

+

The three complex types are

+

Note: as with all type specifiers, any order is permitted: long double complex, complex long double, and even double complex long name the same type.

+
#include <complex.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    double complex z = 1 + 2*I;
+    z = 1 / z;
+    printf("1/(1.0+2.0i) = %.1f%+.1fi\n", creal(z), cimag(z));
+}

Output:

+
1/(1.0+2.0i) = 0.2-0.4i
+ +

If the macro constant __STDC_NO_COMPLEX__ is defined by the implementation, the complex types (as well as the library header <complex.h>) are not provided.

+		 (since C11)

Each complex type has the same object representation and alignment requirements as an array of two elements of the corresponding real type (float for float complex, double for double complex, long double for long double complex). The first element of the array holds the real part, and the second element of the array holds the imaginary component.

+
float a[4] = {1, 2, 3, 4};
+float complex z1, z2;
+memcpy(&z1, a, sizeof z1); // z1 becomes 1.0 + 2.0i
+memcpy(&z2, a+2, sizeof z2); // z2 becomes 3.0 + 4.0i

Complex numbers may be used with arithmetic operators + - * and /, possibly mixed with imaginary and real numbers. There are many mathematical functions defined for complex numbers in <complex.h>. Both built-in operators and library functions may raise floating-point exceptions and set errno as described in math_errhandling.

+

Increment and decrement are not defined for complex types.

+

Relational operators are not defined for complex types (there is no notion of "less than"). Implicit conversions are defined between complex types and other arithmetic types.

+

In order to support the one-infinity model of complex number arithmetic, C regards any complex value with at least one infinite part as an infinity even if its other part is a NaN, guarantees that all operators and functions honor basic properties of infinities and provides cproj to map all infinities to the canonical one (see arithmetic operators for the exact rules).

+
#include <complex.h>
+#include <math.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    double complex z = (1 + 0*I) * (INFINITY + I*INFINITY);
+//  textbook formula would give
+//  (1+i0)(∞+i∞) ⇒ (1×∞ – 0×∞) + i(0×∞+1×∞) ⇒ NaN + I*NaN
+//  but C gives a complex infinity
+    printf("%f%+f*i\n", creal(z), cimag(z));
+ 
+//  textbook formula would give
+//  cexp(∞+iNaN) ⇒ exp(∞)×(cis(NaN)) ⇒ NaN + I*NaN
+//  but C gives  ±∞+i*nan
+    double complex y = cexp(INFINITY + I*NAN);
+    printf("%f%+f*i\n", creal(y), cimag(y));
+}

Possible output:

+
inf+inf*i 
+inf+nan*i

C also treats multiple infinities so as to preserve directional information where possible, despite the inherent limitations of the Cartesian representation:

+

multiplying the imaginary unit by real infinity gives the correctly-signed imaginary infinity: i × ∞ = i∞. Also, i × (∞ – i∞) = ∞ + i∞ indicates the reasonable quadrant.

+

Imaginary floating types

Imaginary floating types model the mathematical imaginary numbers, that is numbers that can be written as a real number multiplied by the imaginary unit: bi The three imaginary types are

+

Note: as with all type specifiers, any order is permitted: long double imaginary, imaginary long double, and even double imaginary long name the same type.

+
#include <complex.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    double imaginary z = 3*I;
+    z = 1 / z;
+    printf("1/(3.0i) = %+.1fi\n", cimag(z));
+}

Output:

+
1/(3.0i) = -0.3i
+ + + +

An implementation that defines __STDC_IEC_559_COMPLEX__ is recommended, but not required to support imaginary numbers. POSIX recommends checking if the macro _Imaginary_I is defined to identify imaginary number support.

+		 (until C11)

Imaginary numbers are supported if __STDC_IEC_559_COMPLEX__(until C23)__STDC_IEC_60559_COMPLEX__(since C23) is defined.

+		 (since C11)

Each of the three imaginary types has the same object representation and alignment requirement as its corresponding real type (float for float imaginary, double for double imaginary, long double for long double imaginary).

+

Note: despite that, imaginary types are distinct and not compatible with their corresponding real types, which prohibits aliasing.

+

Imaginary numbers may be used with arithmetic operators + - * and /, possibly mixed with complex and real numbers. There are many mathematical functions defined for imaginary numbers in <complex.h>. Both built-in operators and library functions may raise floating-point exceptions and set errno as described in math_errhandling.

+

Increment and decrement are not defined for imaginary types. Implicit conversions are defined between imaginary types and other arithmetic types.

+

The imaginary numbers make it possible to express all complex numbers using the natural notation x + I*y (where I is defined as _Imaginary_I). Without imaginary types, certain special complex values cannot be created naturally. For example, if I is defined as _Complex_I, then writing 0.0 + I*INFINITY gives NaN as the real part, and CMPLX(0.0, INFINITY) must be used instead. Same goes for the numbers with the negative zero imaginary component, which are meaningful when working with the library functions with branch cuts, such as csqrt: 1.0 - 0.0*I results in the positive zero imaginary component if I is defined as _Complex_I and the negative zero imaginary part requires the use of CMPLX or conj.

+

Imaginary types also simplify implementations; multiplication of an imaginary by a complex can be implemented straightforwardly with two multiplications if the imaginary types are supported, instead of four multiplications and two additions.

+		 (since C99)

Keywords

Range of values

The following table provides a reference for the limits of common numeric representations.

+

Prior to C23, the C Standard allowed any signed integer representation, and the minimum guaranteed range of N-bit signed integers was from \(\scriptsize -(2^{N-1}-1)\)-(2N-1-1) to \(\scriptsize +2^{N-1}-1\)+2N-1-1 (e.g. -127 to 127 for a signed 8-bit type), which corresponds to the limits of one's complement or sign-and-magnitude.

+

However, all popular data models (including all of ILP32, LP32, LP64, LLP64) and almost all C compilers use two's complement representation (the only known exceptions are some compliers for UNISYS), and as of C23, it is the only representation allowed by the standard, with the guaranteed range from \(\scriptsize -2^{N-1}\)-2N-1 to \(\scriptsize +2^{N-1}-1\)+2N-1-1 (e.g. -128 to 127 for a signed 8-bit type).

+ + + + + + + + + + + + + + + + + + + + +
Type Size in bits Format Value range
Approximate Exact
character 8 signed +−128 to 127
unsigned +0 to 255
16 UTF-16 +0 to 65535
32 UTF-32 +0 to 1114111 (0x10ffff)
integer 16 signed +± 3.27 · 104 +−32768 to 32767
unsigned +0 to 6.55 · 104 +0 to 65535
32 signed +± 2.14 · 109 +−2,147,483,648 to 2,147,483,647
unsigned +0 to 4.29 · 109 +0 to 4,294,967,295
64 signed +± 9.22 · 1018 +−9,223,372,036,854,775,808 to 9,223,372,036,854,775,807
unsigned +0 to 1.84 · 1019 +0 to 18,446,744,073,709,551,615
binary
floating
point 		32 +IEEE-754
    +
  • min subnormal:
    ± 1.401,298,4 · 10−45
    • +
  • min normal:
    ± 1.175,494,3 · 10−38
    • +
  • max:
    ± 3.402,823,4 · 1038
    • +
    +
  • min subnormal:
    ±0x1p−149
    • +
  • min normal:
    ±0x1p−126
    • +
  • max:
    ±0x1.fffffep+127
    • +
64 +IEEE-754
    +
  • min subnormal:
    ± 4.940,656,458,412 · 10−324
    • +
  • min normal:
    ± 2.225,073,858,507,201,4 · 10−308
    • +
  • max:
    ± 1.797,693,134,862,315,7 · 10308
    • +
    +
  • min subnormal:
    ±0x1p−1074
    • +
  • min normal:
    ±0x1p−1022
    • +
  • max:
    ±0x1.fffffffffffffp+1023
    • +
80[note 1] +x86
    +
  • min subnormal:
    ± 3.645,199,531,882,474,602,528
    · 10−4951
    • +
  • min normal:
    ± 3.362,103,143,112,093,506,263
    · 10−4932
    • +
  • max:
    ± 1.189,731,495,357,231,765,021
    · 104932
    • +
    +
  • min subnormal:
    ±0x1p−16445
    • +
  • min normal:
    ±0x1p−16382
    • +
  • max:
    ±0x1.fffffffffffffffep+16383
    • +
128 +IEEE-754
    +
  • min subnormal:
    ± 6.475,175,119,438,025,110,924,
    438,958,227,646,552,5 · 10−4966
    • +
  • min normal:
    ± 3.362,103,143,112,093,506,262,
    677,817,321,752,602,6 · 10−4932
    • +
  • max:
    ± 1.189,731,495,357,231,765,085,
    759,326,628,007,016,2 · 104932
    • +
    +
  • min subnormal:
    ±0x1p−16494
    • +
  • min normal:
    ±0x1p−16382
    • +
  • max:
    ±0x1.ffffffffffffffffffffffffffff
    p+16383
    • +
decimal
floating
point 		32 IEEE-754
    +
  • min subnormal:
    ± 1 · 10-101
    • +
  • min normal:
    ± 1 · 10-95
    • +
  • max:
    ± 9.999'999 · 1096
    • +
64 IEEE-754
    +
  • min subnormal:
    ± 1 · 10-398
    • +
  • min normal:
    ± 1 · 10-383
    • +
  • max:
    ± 9.999'999'999'999'999 · 10384
    • +
128 IEEE-754
    +
  • min subnormal:
    ± 1 · 10-6176
    • +
  • min normal:
    ± 1 · 10-6143
    • +
  • max:
    ± 9.999'999'999'999'999'999'
    999'999'999'999'999 · 106144
    • +
  1. The object representation usually occupies 96/128 bits on 32/64-bit platforms respectively.

Note: actual (as opposed to guaranteed minimal) ranges are available in the library headers <limits.h> and <float.h>.

+

See also

+
C++ documentation for Fundamental types
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/arithmetic_types +

+
diff --git a/devdocs/c/language%2Farray.html b/devdocs/c/language%2Farray.html new file mode 100644 index 00000000..34623494 --- /dev/null +++ b/devdocs/c/language%2Farray.html @@ -0,0 +1,198 @@ +

Array declaration

Array is a type consisting of a contiguously allocated nonempty sequence of objects with a particular element type. The number of those objects (the array size) never changes during the array lifetime.

+

Syntax

In the declaration grammar of an array declaration, the type-specifier sequence designates the element type (which must be a complete object type), and the declarator has the form:

+ + + + +
[ static(optional) qualifiers (optional) expression (optional) ] attr-spec-seq (optional) (1)
[ qualifiers (optional) static(optional) expression (optional) ] attr-spec-seq (optional) (2)
[ qualifiers (optional) * ] attr-spec-seq (optional) (3)
+1,2) General array declarator syntax
+3) Declarator for VLA of unspecified size (can appear in function prototype scope only) where
+ + + +
expression - any expression other than comma operator, designates the number of elements in the array
qualifiers - any combination of const, restrict, or volatile qualifiers, only allowed in function parameter lists; this qualifies the pointer type to which this array parameter is transformed
attr-spec-seq - (C23)optional list of attributes, applied to the declared array 
float fa[11], *afp[17]; // fa is an array of 11 floats
+                        // afp is an array of 17 pointers to floats

Explanation

There are several variations of array types: arrays of known constant size, variable-length arrays, and arrays of unknown size.

+

Arrays of constant known size

If expression in an array declarator is an integer constant expression with a value greater than zero and the element type is a type with a known constant size (that is, elements are not VLA)(since C99), then the declarator declares an array of constant known size:

+
int n[10]; // integer constants are constant expressions
+char o[sizeof(double)]; // sizeof is a constant expression
+enum { MAX_SZ=100 };
+int n[MAX_SZ]; // enum constants are constant expressions

Arrays of constant known size can use array initializers to provide their initial values:

+
int a[5] = {1,2,3}; // declares int[5] initialized to 1,2,3,0,0
+char str[] = "abc"; // declares char[4] initialized to 'a','b','c','\0'
+ + + + + +

In function parameter lists, additional syntax elements are allowed within the array declarators: the keyword static and qualifiers, which may appear in any order before the size expression (they may also appear even when the size expression is omitted).

+

In each function call to a function where an array parameter uses the keyword static between [ and ], the value of the actual parameter must be a valid pointer to the first element of an array with at least as many elements as specified by expression:

+
void fadd(double a[static 10], const double b[static 10])
+{
+    for (int i = 0; i < 10; i++)
+    {
+        if (a[i] < 0.0) return;
+        a[i] += b[i];
+    }
+}
+// a call to fadd may perform compile-time bounds checking
+// and also permits optimizations such as prefetching 10 doubles
+int main(void)
+{
+    double a[10] = {0}, b[20] = {0};
+    fadd(a, b); // OK
+    double x[5] = {0};
+    fadd(x, b); // undefined behavior: array argument is too small
+}

If qualifiers are present, they qualify the pointer type to which the array parameter type is transformed:

+
int f(const int a[20])
+{
+    // in this function, a has type const int* (pointer to const int)
+}
+int g(const int a[const 20])
+{
+    // in this function, a has type const int* const (const pointer to const int)
+}

This is commonly used with the restrict type qualifier:

+
void fadd(double a[static restrict 10],
+          const double b[static restrict 10])
+{
+    for (int i = 0; i < 10; i++) // loop can be unrolled and reordered
+    {
+        if (a[i] < 0.0)
+            break;
+        a[i] += b[i];
+    }
+}

Variable-length arrays

If expression is not an integer constant expression, the declarator is for an array of variable size.

+

Each time the flow of control passes over the declaration, expression is evaluated (and it must always evaluate to a value greater than zero), and the array is allocated (correspondingly, lifetime of a VLA ends when the declaration goes out of scope). The size of each VLA instance does not change during its lifetime, but on another pass over the same code, it may be allocated with a different size.

+
#include <stdio.h>
+ 
+int main(void)
+{
+   int n = 1;
+label:;
+   int a[n]; // re-allocated 10 times, each with a different size
+   printf("The array has %zu elements\n", sizeof a / sizeof *a);
+   if (n++ < 10)
+       goto label; // leaving the scope of a VLA ends its lifetime
+}

If the size is *, the declaration is for a VLA of unspecified size. Such declaration may only appear in a function prototype scope, and declares an array of a complete type. In fact, all VLA declarators in function prototype scope are treated as if expression were replaced by *.

+
void foo(size_t x, int a[*]);
+void foo(size_t x, int a[x])
+{
+    printf("%zu\n", sizeof a); // same as sizeof(int*)
+}

Variable-length arrays and the types derived from them (pointers to them, etc) are commonly known as "variably-modified types" (VM). Objects of any variably-modified type may only be declared at block scope or function prototype scope.

+
extern int n;
+int A[n];            // Error: file scope VLA
+extern int (*p2)[n]; // Error: file scope VM
+int B[100];          // OK: file-scope array of constant known size
+void fvla(int m, int C[m][m]); // OK: prototype-scope VLA

VLA must have automatic or allocated storage duration. Pointers to VLA, but not VLA themselves may also have static storage duration. No VM type may have linkage.

+
void fvla(int m, int C[m][m]) // OK: block scope/auto duration pointer to VLA
+{
+    typedef int VLA[m][m]; // OK: block scope VLA
+    int D[m];              // OK: block scope/auto duration VLA
+//  static int E[m]; // Error: static duration VLA
+//  extern int F[m]; // Error: VLA with linkage
+    int (*s)[m];     // OK: block scope/auto duration VM
+    s = malloc(m * sizeof(int)); // OK: s points to VLA in allocated storage
+//  extern int (*r)[m]; // Error: VM with linkage
+    static int (*q)[m] = &B; // OK: block scope/static duration VM}
+}

Variably-modified types cannot be members of structs or unions.

+
struct tag
+{
+    int z[n]; // Error: VLA struct member
+    int (*y)[n]; // Error: VM struct member
+};
 (since C99)

If the compiler defines the macro constant __STDC_NO_VLA__ to integer constant 1, then VLA and VM types are not supported.

+		 +(since C11)
(until C23) +

If the compiler defines the macro constant __STDC_NO_VLA__ to integer constant 1, then VLA objects with automatic storage duration are not supported.

+

The support for VM types and VLAs with allocated storage durations is mandated.

+		 (since C23)

Arrays of unknown size

If expression in an array declarator is omitted, it declares an array of unknown size. Except in function parameter lists (where such arrays are transformed to pointers) and when an initializer is available, such type is an incomplete type (note that VLA of unspecified size, declared with * as the size, is a complete type)(since C99):

+
extern int x[]; // the type of x is "array of unknown bound of int"
+int a[] = {1,2,3}; // the type of a is "array of 3 int"
+ +

Within a struct definition, an array of unknown size may appear as the last member (as long as there is at least one other named member), in which case it is a special case known as flexible array member. See struct for details:

+
struct s { int n; double d[]; }; // s.d is a flexible array member
+struct s *s1 = malloc(sizeof (struct s) + (sizeof (double) * 8)); // as if d was double d[8]
 (since C99)

Qualifiers

+ + + +

If an array type is declared with a const, volatile, or restrict(since C99) qualifier (which is possible through the use of typedef), the array type is not qualified, but its element type is:

+		 (until C23)

An array type and its element type are always considered to be identically qualified, except that an array type is never considered to be _Atomic-qualified.

+		 (since C23)
typedef int A[2][3];
+const A a = {{4, 5, 6}, {7, 8, 9}}; // array of array of const int
+int* pi = a[0]; // Error: a[0] has type const int*
+void* unqual_ptr = a; // OK until C23; error since C23
+// Notes: clang applies the rule in C++/C23 even in C89-C17 modes
+ +

_Atomic is not allowed to be applied to an array type, although an array of atomic type is allowed.

+
typedef int A[2];
+// _Atomic A a0 = {0};    // Error
+// _Atomic(A) a1 = {0};   // Error
+_Atomic int a2[2] = {0};  // OK
+_Atomic(int) a3[2] = {0}; // OK
 (since C11)

Assignment

Objects of array type are not modifiable lvalues, and although their address may be taken, they cannot appear on the left hand side of an assignment operator. However, structs with array members are modifiable lvalues and can be assigned:

+
int a[3] = {1,2,3}, b[3] = {4,5,6};
+int (*p)[3] = &a; // okay, address of a can be taken
+// a = b;            // error, a is an array
+struct { int c[3]; } s1, s2 = {3,4,5};
+s1 = s2; // okay: can assign structs holding array members

Array to pointer conversion

Any lvalue expression of array type, when used in any context other than

+ + +
(since C11)

undergoes an implicit conversion to the pointer to its first element. The result is not an lvalue.

+

If the array was declared register, the behavior of the program that attempts such conversion is undefined.

+
int a[3] = {1,2,3};
+int* p = a;
+printf("%zu\n", sizeof a); // prints size of array
+printf("%zu\n", sizeof p); // prints size of a pointer

When an array type is used in a function parameter list, it is transformed to the corresponding pointer type: int f(int a[2]) and int f(int* a) declare the same function. Since the function's actual parameter type is pointer type, a function call with an array argument performs array-to-pointer conversion; the size of the argument array is not available to the called function and must be passed explicitly:

+
#include <stdio.h>
+ 
+void f(int a[], int sz) // actually declares void f(int* a, int sz)
+{
+    for (int i = 0; i < sz; ++i)
+        printf("%d\n", a[i]);
+}
+ 
+void g(int (*a)[10]) // pointer to array parameter is not transformed
+{
+    for (int i = 0; i < 10; ++i)
+        printf("%d\n", (*a)[i]);
+}
+ 
+int main(void)
+{
+    int a[10] = {0};
+    f(a, 10); // converts a to int*, passes the pointer
+    g(&a);    // passes a pointer to the array (no need to pass the size)
+}

Multidimensional arrays

When the element type of an array is another array, it is said that the array is multidimensional:

+
// array of 2 arrays of 3 ints each
+int a[2][3] = {{1,2,3},  // can be viewed as a 2x3 matrix
+               {4,5,6}}; // with row-major layout

Note that when array-to-pointer conversion is applied, a multidimensional array is converted to a pointer to its first element, e.g., pointer to the first row:

+
int a[2][3]; // 2x3 matrix
+int (*p1)[3] = a; // pointer to the first 3-element row
+int b[3][3][3]; // 3x3x3 cube
+int (*p2)[3][3] = b; // pointer to the first 3x3 plane
+ +

Multidimensional arrays may be variably modified in every dimension if VLAs are supported(since C11):

+
int n = 10;
+int a[n][2*n];
 (since C99)

Notes

Zero-length array declarations are not allowed, even though some compilers offer them as extensions (typically as a pre-C99 implementation of flexible array members).

+

If the size expression of a VLA has side effects, they are guaranteed to be produced except when it is a part of a sizeof expression whose result doesn't depend on it:

+
int n = 5;
+size_t sz = sizeof(int (*)[n++]); // may or may not increment n

References

See also

+
C++ documentation for Array declaration
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/array +

+
diff --git a/devdocs/c/language%2Farray_initialization.html b/devdocs/c/language%2Farray_initialization.html new file mode 100644 index 00000000..c740231b --- /dev/null +++ b/devdocs/c/language%2Farray_initialization.html @@ -0,0 +1,127 @@ +

Array initialization

When initializing an object of array type, the initializer must be either a string literal (optionally enclosed in braces) or be a brace-enclosed list of initialized for array members:

+ + + + + +
= string-literal (1)
= { expression , ... } (2) (until C99)
= { designator(optional) expression , ... } (2) (since C99)
= { } (3) (since C23)
+1) string literal initializer for character and wide character arrays
+2) comma-separated list of constant(until C99) expressions that are initializers for array elements, optionally using array designators of the form [ constant-expression ] = (since C99) +
+3) empty initializer empty-initializes every element of the array

Arrays of known size and arrays of unknown size may be initialized, but not VLAs(since C99)(until C23). A VLA can only be empty-initialized.(since C23)

+

All array elements that are not initialized explicitly are empty-initialized.

+

Initialization from strings

String literal (optionally enclosed in braces) may be used as the initializer for an array of matching type:

+ + +
    +
  • u-prefixed wide string literals can be used to initialize arrays of any type compatible with (ignoring cv-qualifications) char16_t
    • +
  • U-prefixed wide string literals can be used to initialize arrays of any type compatible with (ignoring cv-qualifications) char32_t
    • +
 (since C11)

Successive bytes of the string literal or wide characters of the wide string literal, including the terminating null byte/character, initialize the elements of the array:

+
char str[] = "abc"; // str has type char[4] and holds 'a', 'b', 'c', '\0'
+wchar_t wstr[4] = L"猫"; // str has type wchar_t[4] and holds L'猫', '\0', '\0', '\0'

If the size of the array is known, it may be one less than the size of the string literal, in which case the terminating null character is ignored:

+
char str[3] = "abc"; // str has type char[3] and holds 'a', 'b', 'c'

Note that the contents of such array are modifiable, unlike when accessing a string literal directly with char* str = "abc";.

+

Initialization from brace-enclosed lists

When an array is initialized with a brace-enclosed list of initializers, the first initializer in the list initializes the array element at index zero (unless a designator is specified)(since C99), and each subsequent initializer without a designator (since C99)initializes the array element at index one greater than the one initialized by the previous initializer.

+
int x[] = {1,2,3}; // x has type int[3] and holds 1,2,3
+int y[5] = {1,2,3}; // y has type int[5] and holds 1,2,3,0,0
+int z[4] = {1}; // z has type int[4] and holds 1,0,0,0
+int w[3] = {0}; // w has type int[3] and holds all zeroes

It's an error to provide more initializers than elements when initializing an array of known size (except when initializing character arrays from string literals).

+ + +

A designator causes the following initializer to initialize of the array element described by the designator. Initialization then continues forward in order, beginning with the next element after the one described by the designator.

+
int n[5] = {[4]=5,[0]=1,2,3,4}; // holds 1,2,3,4,5
+ 
+int a[MAX] = { // starts initializing a[0] = 1, a[1] = 3, ...
+    1, 3, 5, 7, 9, [MAX-5] = 8, 6, 4, 2, 0
+};
+// for MAX=6,  array holds 1,8,6,4,2,0
+// for MAX=13, array holds 1,3,5,7,9,0,0,0,8,6,4,2,0 ("sparse array")
 (since C99)

When initializing an array of unknown size, the largest subscript for which an initializer is specified determines the size of the array being declared.

+

Nested arrays

If the elements of an array are arrays, structs, or unions, the corresponding initializers in the brace-enclosed list of initializers are any initializers that are valid for those members, except that their braces may be omitted as follows:

+

If the nested initializer begins with an opening brace, the entire nested initializer up to its closing brace initializes the corresponding array element:

+
int y[4][3] = { // array of 4 arrays of 3 ints each (4x3 matrix)
+    { 1 },      // row 0 initialized to {1, 0, 0}
+    { 0, 1 },   // row 1 initialized to {0, 1, 0}
+    { [2]=1 },  // row 2 initialized to {0, 0, 1}
+};              // row 3 initialized to {0, 0, 0}

If the nested initializer does not begin with an opening brace, only enough initializers from the list are taken to account for the elements or members of the sub-array, struct or union; any remaining initializers are left to initialize the next array element:

+
int y[4][3] = {    // array of 4 arrays of 3 ints each (4x3 matrix)
+1, 3, 5, 2, 4, 6, 3, 5, 7 // row 0 initialized to {1, 3, 5}
+};                        // row 1 initialized to {2, 4, 6}
+                          // row 2 initialized to {3, 5, 7}
+                          // row 3 initialized to {0, 0, 0}
+ 
+struct { int a[3], b; } w[] = { { 1 }, 2 }; // array of structs
+   // { 1 } is taken to be a fully-braced initializer for element #0 of the array
+   // that element is initialized to { {1, 0, 0}, 0}
+   // 2 is taken to be the first initialized for element #1 of the array
+   // that element is initialized { {2, 0, 0}, 0}
+ +

Array designators may be nested; the bracketed constant expression for nested arrays follows the bracketed constant expression for the outer array:

+
int y[4][3] = {[0][0]=1, [1][1]=1, [2][0]=1};  // row 0 initialized to {1, 0, 0}
+                                               // row 1 initialized to {0, 1, 0}
+                                               // row 2 initialized to {1, 0, 0}
+                                               // row 3 initialized to {0, 0, 0}
 (since C99)

Notes

The order of evaluation of subexpressions in an array initializer is indeterminately sequenced in C (but not in C++ since C++11):

+
int n = 1;
+int a[2] = {n++, n++}; // unspecified, but well-defined behavior,
+                       // n is incremented twice (in arbitrary order)
+                       // a initialized to {1, 2} and to {2, 1} are both valid
+puts((char[4]){'0'+n} + n++); // undefined behavior:
+                              // increment and read from n are unsequenced
+ + + +

In C, the braced list of an initializer cannot be empty. C++ allows empty list:

+		 (until C23)

An empty initializer can be used to initialize an array:

+		 (since C23)
int a[3] = {0}; // valid C and C++ way to zero-out a block-scope array
+int a[3] = {}; // valid C++ way to zero-out a block-scope array; valid in C since C23

As with all other initialization, every expression in the initializer list must be a constant expression when initializing arrays of static or thread-local storage duration:

+
static char* p[2] = {malloc(1), malloc(2)}; // error

Example

int main(void)
+{
+    // The following four array declarations are the same
+    short q1[4][3][2] = {
+        { 1 },
+        { 2, 3 },
+        { 4, 5, 6 }
+    };
+ 
+    short q2[4][3][2] = {1, 0, 0, 0, 0, 0, 2, 3, 0, 0, 0, 0, 4, 5, 6};
+ 
+    short q3[4][3][2] = {
+        {
+            { 1 },
+        },
+        {
+            { 2, 3 },
+        },
+        {
+            { 4, 5 },
+            { 6 },
+        }
+    };
+ 
+    short q4[4][3][2] = {1, [1]=2, 3, [2]=4, 5, 6};
+ 
+ 
+    // Character names can be associated with enumeration constants
+    // using arrays with designators:
+    enum { RED, GREEN, BLUE };
+    const char *nm[] = {
+        [RED] = "red",
+        [GREEN] = "green",
+        [BLUE] = "blue",
+    };
+}

References

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/array_initialization +

+
diff --git a/devdocs/c/language%2Fas_if.html b/devdocs/c/language%2Fas_if.html new file mode 100644 index 00000000..19cace76 --- /dev/null +++ b/devdocs/c/language%2Fas_if.html @@ -0,0 +1,20 @@ +

As-if rule

Allows any and all code transformations that do not change the observable behavior of the program.

+

Explanation

The C compiler is permitted to perform any changes to the program as long as the following remains true:

+ + + + +
1) At every sequence point, the values of all volatile objects are stable (previous evaluations are complete, new evaluations not started). (until C11)
1) Accesses (reads and writes) to volatile objects occur strictly according to the semantics of the expressions in which they occur. In particular, they are not reordered with respect to other volatile accesses on the same thread. (since C11)
+2) At program termination, data written to files is exactly as if the program was executed as written.
+3) Prompting text which is sent to interactive devices will be shown before the program waits for input.
+ +
4) If the pragma #pragma STDC FENV_ACCESS is supported and is set to ON, the changes to the floating-point environment (floating-point exceptions and rounding modes) are guaranteed to be observed by the floating-point arithmetic operators and function calls as if executed as written, except that
    +
  • the result of any floating-point expression other than cast and assignment may have range and precision of a floating-point type different from the type of the expression (see FLT_EVAL_METHOD),
    • +
  • notwithstanding the above, intermediate results of any floating-point expression may be calculated as if to infinite range and precision (unless #pragma STDC FP_CONTRACT is OFF).
    • +
 (since C99)

Notes

See also

+
C++ documentation for as-if rule
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/as_if +

+
diff --git a/devdocs/c/language%2Fascii.html b/devdocs/c/language%2Fascii.html new file mode 100644 index 00000000..696f68cf --- /dev/null +++ b/devdocs/c/language%2Fascii.html @@ -0,0 +1,131 @@ +

ASCII Chart

The following chart contains all 128 ASCII decimal (dec), octal (oct), hexadecimal (hex) and character (ch) codes.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
dec oct +hex +ch dec oct +hex +ch dec oct +hex +ch dec oct +hex +ch
0 0 00 +NUL (null) 32 40 20 (space) 64 100 40 @ 96 140 60 +`
1 1 01 +SOH (start of header) 33 41 21 ! 65 101 41 A 97 141 61 +a
2 2 02 +STX (start of text) 34 42 22 " 66 102 42 B 98 142 62 +b
3 3 03 +ETX (end of text) 35 43 23 # 67 103 43 C 99 143 63 +c
4 4 04 +EOT (end of transmission) 36 44 24 $ 68 104 44 D 100 144 64 +d
5 5 05 +ENQ (enquiry) 37 45 25 % 69 105 45 E 101 145 65 +e
6 6 06 +ACK (acknowledge) 38 46 26 & 70 106 46 F 102 146 66 +f
7 7 07 +BEL (bell) 39 47 27 ' 71 107 47 G 103 147 67 +g
8 10 08 +BS (backspace) 40 50 28 ( 72 110 48 H 104 150 68 +h
9 11 09 +HT (horizontal tab) 41 51 29 ) 73 111 49 I 105 151 69 +i
10 12 0a +LF (line feed - new line) 42 52 2a * 74 112 4a J 106 152 6a +j
11 13 0b +VT (vertical tab) 43 53 2b + 75 113 4b K 107 153 6b +k
12 14 0c +FF (form feed - new page) 44 54 2c , 76 114 4c L 108 154 6c +l
13 15 0d +CR (carriage return) 45 55 2d - 77 115 4d M 109 155 6d +m
14 16 0e +SO (shift out) 46 56 2e . 78 116 4e N 110 156 6e +n
15 17 0f +SI (shift in) 47 57 2f / 79 117 4f O 111 157 6f +o
16 20 10 +DLE (data link escape) 48 60 30 0 80 120 50 P 112 160 70 +p
17 21 11 +DC1 (device control 1) 49 61 31 1 81 121 51 Q 113 161 71 +q
18 22 12 +DC2 (device control 2) 50 62 32 2 82 122 52 R 114 162 72 +r
19 23 13 +DC3 (device control 3) 51 63 33 3 83 123 53 S 115 163 73 +s
20 24 14 +DC4 (device control 4) 52 64 34 4 84 124 54 T 116 164 74 +t
21 25 15 +NAK (negative acknowledge) 53 65 35 5 85 125 55 U 117 165 75 +u
22 26 16 +SYN (synchronous idle) 54 66 36 6 86 126 56 V 118 166 76 +v
23 27 17 +ETB (end of transmission block) 55 67 37 7 87 127 57 W 119 167 77 +w
24 30 18 +CAN (cancel) 56 70 38 8 88 130 58 X 120 170 78 +x
25 31 19 +EM (end of medium) 57 71 39 9 89 131 59 Y 121 171 79 +y
26 32 1a +SUB (substitute) 58 72 3a : 90 132 5a Z 122 172 7a +z
27 33 1b +ESC (escape) 59 73 3b ; 91 133 5b [ 123 173 7b +{
28 34 1c +FS (file separator) 60 74 3c < 92 134 5c \ 124 174 7c +|
29 35 1d +GS (group separator) 61 75 3d = 93 135 5d ] 125 175 7d +}
30 36 1e +RS (record separator) 62 76 3e > 94 136 5e ^ 126 176 7e +~
31 37 1f +US (unit separator) 63 77 3f ? 95 137 5f _ 127 177 7f +DEL (delete)

Note: in Unicode, the ASCII character block is known as U+0000..U+007F Basic Latin.

+

Example

#include <stdio.h>
+ 
+int main(void)
+{
+    puts("Printable ASCII:");
+    for (int i = 32; i < 127; ++i) {
+        putchar(i);
+        putchar(i % 16 == 15 ? '\n' : ' ');
+    }
+}

Possible output:

+
Printable ASCII:
+  ! " # $ % & ' ( ) * + , - . /
+0 1 2 3 4 5 6 7 8 9 : ; < = > ?
+@ A B C D E F G H I J K L M N O
+P Q R S T U V W X Y Z [ \ ] ^ _
+` a b c d e f g h i j k l m n o
+p q r s t u v w x y z { | } ~

See also

+
C++ documentation for ASCII Chart
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/ascii +

+
diff --git a/devdocs/c/language%2Fasm.html b/devdocs/c/language%2Fasm.html new file mode 100644 index 00000000..d222cf59 --- /dev/null +++ b/devdocs/c/language%2Fasm.html @@ -0,0 +1,68 @@ +

Inline assembly

Inline assembly (typically introduced by the asm keyword) gives the ability to embed assembly language source code within a C program.

+

Unlike in C++, inline assembly is treated as an extension in C. It is conditionally supported and implementation defined, meaning that it may not be present and, even when provided by the implementation, it does not have a fixed meaning.

+

Syntax

+ +
asm ( string_literal ) ;

Explanation

This kind of inline assembly syntax is accepted by the C++ standard and called asm-declaration in C++. The string_literal is typically a short program written in assembly language, which is executed whenever this declaration is executed. Different C compilers have wildly varying rules for asm-declarations, and different conventions for the interaction with the surrounding C code.

+

asm-declaration can appear inside a block (a function body or another compound statement), and, as all other declarations, this declaration can also appear outside a block.

+

Notes

MSVC does not support inline assembly on the ARM and x64 processors, and only support the form introduced by __asm on x86 processors.

+

When compiling in ISO C mode by GCC or Clang (e.g. with option -std=c11), __asm__ must be used instead of asm.

+

Examples

+

Demonstrates two kinds of inline assembly syntax offered by the GCC compiler. This program will only work correctly on x86-64 platform under Linux. Note that the "standard inline assembly" is also treated as an extension in the C standard.

+
#include <stdio.h>
+ 
+extern int func(void);
+// the definition of func is written in assembly language
+__asm__(".globl func\n\t"
+        ".type func, @function\n\t"
+        "func:\n\t"
+        ".cfi_startproc\n\t"
+        "movl $7, %eax\n\t"
+        "ret\n\t"
+        ".cfi_endproc");
+ 
+int main(void)
+{
+    int n = func();
+    // gcc's extended inline assembly
+    __asm__ ("leal (%0,%0,4),%0"
+           : "=r" (n)
+           : "0" (n));
+    printf("7*5 = %d\n", n);
+    fflush(stdout); // flush is intentional
+ 
+    // standard inline assembly in C++
+    __asm__ ("movq $60, %rax\n\t" // the exit syscall number on Linux
+             "movq $2,  %rdi\n\t" // this program returns 2
+             "syscall");
+}

Output:

+
7*5 = 35

References

See also

+
C++ documentation for asm declaration
+ + + + + + +
1. +GCC Inline Assembly HOWTO
2. +IBM XL C/C++ Inline Assembly
3. +Intel C++ Inline Assembly
4. +Visual Studio Inline Assembler
5. +Sun Studio 12 Asm Statements
6. +Inline assembly for Itanium-based HP-UX
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/asm +

+
diff --git a/devdocs/c/language%2Fatomic.html b/devdocs/c/language%2Fatomic.html new file mode 100644 index 00000000..5b8daa7a --- /dev/null +++ b/devdocs/c/language%2Fatomic.html @@ -0,0 +1,77 @@ +

Atomic types

Syntax

+ + +
_Atomic ( type-name ) (1) (since C11)
_Atomic type-name (2) (since C11)
+1) Use as a type specifier; this designates a new atomic type
+2) Use as a type qualifier; this designates the atomic version of type-name. In this role, it may be mixed with const, volatile, and restrict, although unlike other qualifiers, the atomic version of type-name may have a different size, alignment, and object representation.
+ +
type-name - any type other than array or function. For (1), type-name also cannot be atomic or cvr-qualified

The header <stdatomic.h> defines 37 convenience type aliases, from atomic_bool to atomic_uintmax_t, which simplify the use of this keyword with built-in and library types.

+
_Atomic const int * p1;  // p is a pointer to an atomic const int
+const atomic_int * p2;   // same
+const _Atomic(int) * p3; // same

If the macro constant __STDC_NO_ATOMICS__ is defined by the compiler, the keyword _Atomic is not provided.

+

Explanation

Objects of atomic types are the only objects that are free from data races; that is, they may be modified by two threads concurrently or modified by one and read by another.

+

Each atomic object has its own associated modification order, which is a total order of modifications made to that object. If, from some thread's point of view, modification A of some atomic M happens-before modification B of the same atomic M, then in the modification order of M, A occurs before B.

+

Note that although each atomic object has its own modification order, there is no single total order; different threads may observe modifications to different atomic objects in different orders.

+

There are four coherences that are guaranteed for all atomic operations:

+

Some atomic operations are also synchronization operations; they may have additional release semantics, acquire semantics, or sequentially-consistent semantics. See memory_order.

+

Built-in increment and decrement operators and compound assignment are read-modify-write atomic operations with total sequentially consistent ordering (as if using memory_order_seq_cst). If less strict synchronization semantics are desired, the standard library functions may be used instead.

+

Atomic properties are only meaningful for lvalue expressions. Lvalue-to-rvalue conversion (which models a memory read from an atomic location to a CPU register) strips atomicity along with other qualifiers.

+

Notes

Accessing a member of an atomic struct/union is undefined behavior.

+

The library type sig_atomic_t does not provide inter-thread synchronization or memory ordering, only atomicity.

+

The volatile types do not provide inter-thread synchronization, memory ordering, or atomicity.

+

Implementations are recommended to ensure that the representation of _Atomic(T) in C is same as that of std::atomic<T> in C++ for every possible type T. The mechanisms used to ensure atomicity and memory ordering should be compatible.

+

Keywords

_Atomic

+

Example

#include <stdio.h>
+#include <threads.h>
+#include <stdatomic.h>
+ 
+atomic_int acnt;
+int cnt;
+ 
+int f(void* thr_data)
+{
+    for(int n = 0; n < 1000; ++n) {
+        ++cnt;
+        ++acnt;
+        // for this example, relaxed memory order is sufficient, e.g.
+        // atomic_fetch_add_explicit(&acnt, 1, memory_order_relaxed);
+    }
+    return 0;
+}
+ 
+int main(void)
+{
+    thrd_t thr[10];
+    for(int n = 0; n < 10; ++n)
+        thrd_create(&thr[n], f, NULL);
+    for(int n = 0; n < 10; ++n)
+        thrd_join(thr[n], NULL);
+ 
+    printf("The atomic counter is %u\n", acnt);
+    printf("The non-atomic counter is %u\n", cnt);
+}

Possible output:

+
The atomic counter is 10000
+The non-atomic counter is 8644

References

See also

+ +
C documentation for thread (Concurrency support library)
C++ documentation for atomic
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/atomic +

+
diff --git a/devdocs/c/language%2Fattributes%2Fdeprecated.html b/devdocs/c/language%2Fattributes%2Fdeprecated.html new file mode 100644 index 00000000..d53195d3 --- /dev/null +++ b/devdocs/c/language%2Fattributes%2Fdeprecated.html @@ -0,0 +1,65 @@ +

C attribute: deprecated (since C23) +

Indicates that the name or entity declared with this attribute is deprecated, that is, the use is allowed, but discouraged for some reason.

+

Syntax

+ + +
[[ deprecated ]]
[[ __deprecated__ ]] 		(1)
[[ deprecated ( string-literal ) ]]
[[ __deprecated__ ( string-literal ) ]] 		(2)
+ +
string-literal - text that could be used to explain the rationale for deprecation and/or to suggest a replacing entity

Explanation

Indicates that the use of the name or entity declared with this attribute is allowed, but discouraged for some reason. Compilers typically issue warnings on such uses. The string-literal, if specified, is usually included in the warnings.

+

This attribute is allowed in declarations of the following names or entities:

+

A name declared non-deprecated may be redeclared deprecated. A name declared deprecated cannot be un-deprecated by redeclaring it without this attribute.

+

Example

#include <stdio.h>
+ 
+[[deprecated]]
+void TriassicPeriod(void)
+{
+    puts("Triassic Period: [251.9 - 208.5] million years ago.");
+}
+ 
+[[deprecated("Use NeogenePeriod() instead.")]]
+void JurassicPeriod(void)
+{
+    puts("Jurassic Period: [201.3 - 152.1] million years ago.");
+}
+ 
+[[deprecated("Use calcSomethingDifferently(int).")]]
+int calcSomething(int x)
+{
+    return x * 2;
+}
+ 
+int main(void)
+{
+    TriassicPeriod();
+    JurassicPeriod();
+}

Possible output:

+
Triassic Period: [251.9 - 208.5] million years ago.
+Jurassic Period: [201.3 - 152.1] million years ago.
+ 
+prog.c:23:5: warning: 'TriassicPeriod' is deprecated [-Wdeprecated-declarations]
+    TriassicPeriod();
+    ^
+prog.c:3:3: note: 'TriassicPeriod' has been explicitly marked deprecated here
+[[deprecated]]
+  ^
+prog.c:24:5: warning: 'JurassicPeriod' is deprecated: Use NeogenePeriod() instead. [-Wdeprecated-declarations]
+    JurassicPeriod();
+    ^
+prog.c:9:3: note: 'JurassicPeriod' has been explicitly marked deprecated here
+[[deprecated("Use NeogenePeriod() instead.")]]
+  ^
+2 warnings generated.

See also

+
C++ documentation for deprecated
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/attributes/deprecated +

+
diff --git a/devdocs/c/language%2Fattributes%2Ffallthrough.html b/devdocs/c/language%2Fattributes%2Ffallthrough.html new file mode 100644 index 00000000..c1c06f6b --- /dev/null +++ b/devdocs/c/language%2Fattributes%2Ffallthrough.html @@ -0,0 +1,45 @@ +

C attribute: fallthrough (since C23) +

Indicates that the fall through from the previous case label is intentional and should not be diagnosed by a compiler that warns on fallthrough.

+

Syntax

+ +
[[ fallthrough ]]
[[ __fallthrough__ ]]

Explanation

May only be used in an attribute declaration to create a fallthrough declaration ([[fallthrough]];).

+

A fallthrough declaration may only be used in a switch statement, where the next block item (statement, declaration, or label) to be encounted is a statement with a case or default label for that switch statement.

+

Indicates that the fall through from the previous case label is intentional and should not be diagnosed by a compiler that warns on fallthrough.

+

Example

#include <stdbool.h>
+ 
+void g(void) {}
+void h(void) {}
+void i(void) {}
+ 
+void f(int n) {
+  switch (n) {
+    case 1:
+    case 2:
+      g();
+     [[fallthrough]];
+    case 3: // no warning on fallthrough
+      h();
+    case 4: // compiler may warn on fallthrough
+      if(n < 3) {
+          i();
+          [[fallthrough]]; // OK
+      }
+      else {
+          return;
+      }
+    case 5:
+      while (false) {
+        [[fallthrough]]; // ill-formed: no subsequent case or default label
+      }
+    case 6:
+      [[fallthrough]]; // ill-formed: no subsequent case or default label
+  }
+}
+ 
+int main(void) {}

See also

+
C++ documentation for fallthrough
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/attributes/fallthrough +

+
diff --git a/devdocs/c/language%2Fattributes%2Fmaybe_unused.html b/devdocs/c/language%2Fattributes%2Fmaybe_unused.html new file mode 100644 index 00000000..e8af27c7 --- /dev/null +++ b/devdocs/c/language%2Fattributes%2Fmaybe_unused.html @@ -0,0 +1,33 @@ +

C attribute: maybe_unused (since C23) +

Suppresses warnings on unused entities.

+

Syntax

+ +
[[ maybe_unused ]]
[[ __maybe_unused__ ]]

Explanation

This attribute can appear in the declaration of the following entities:

+

If the compiler issues warnings on unused entities, that warning is suppressed for any entity declared maybe_unused.

+

Example

#include <assert.h>
+ 
+[[maybe_unused]] void f([[maybe_unused]] _Bool cond1, [[maybe_unused]] _Bool cond2)
+{
+   [[maybe_unused]] _Bool b = cond1 && cond2;
+   assert(b); // in release mode, assert is compiled out, and b is unused
+              // no warning because it is declared [[maybe_unused]]
+} // parameters cond1 and cond2 are not used, no warning
+ 
+int main(void)
+{
+    f(1, 1);
+}

See also

+
C++ documentation for maybe_unused
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/attributes/maybe_unused +

+
diff --git a/devdocs/c/language%2Fattributes%2Fnodiscard.html b/devdocs/c/language%2Fattributes%2Fnodiscard.html new file mode 100644 index 00000000..35c94f7d --- /dev/null +++ b/devdocs/c/language%2Fattributes%2Fnodiscard.html @@ -0,0 +1,42 @@ +

C attribute: nodiscard (since C23) +

If a function declared nodiscard or a function returning a struct/union/enum declared nodiscard by value is called from a discarded-value expression other than a cast to void, the compiler is encouraged to issue a warning.

+

Syntax

+ + +
[[ nodiscard ]]
[[ __nodiscard__ ]] 		(1)
[[ nodiscard ( string-literal ) ]]
[[ __nodiscard__ ( string-literal ) ]] 		(2)
+ +
string-literal - text that could be used to explain the rationale for why the result should not be discarded

Explanation

Appears in a function declaration, enumeration declaration, or struct/union declaration.

+

If, from a discarded-value expression other than a cast to void,

+

the compiler is encouraged to issue a warning.

+

The string-literal, if specified, is usually included in the warnings.

+

Example

struct [[nodiscard]] error_info { int status; /*...*/ };
+struct error_info enable_missile_safety_mode() { /*...*/ return (struct error_info){0}; }
+void launch_missiles() { /*...*/ }
+void test_missiles() {
+   enable_missile_safety_mode(); // compiler may warn on discarding a nodiscard value
+   launch_missiles();
+}
+struct error_info* foo() { static struct error_info e; /*...*/ return &e; }
+void f1() {
+    foo(); // nodiscard type itself is not returned, no warning
+}
+// nodiscard( string-literal ):
+[[nodiscard("PURE FUN")]] int strategic_value(int x, int y) { return x ^ y; }
+ 
+int main()
+{
+    strategic_value(4,2); // compiler may warn on discarding a nodiscard value
+    int z = strategic_value(0,0); // OK: return value is not discarded
+    return z;
+}

Possible output:

+
game.cpp:5:4: warning: ignoring return value of function declared with 'nodiscard' attribute
+game.cpp:17:5: warning: ignoring return value of function declared with 'nodiscard' attribute: PURE FUN

See also

+
C++ documentation for nodiscard
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/attributes/nodiscard +

+
diff --git a/devdocs/c/language%2Fattributes%2Fnoreturn.html b/devdocs/c/language%2Fattributes%2Fnoreturn.html new file mode 100644 index 00000000..6d75ac4c --- /dev/null +++ b/devdocs/c/language%2Fattributes%2Fnoreturn.html @@ -0,0 +1,24 @@ +

C attribute: noreturn, _Noreturn (since C23) +

Indicates that the function does not return.

+

Syntax

+ + +
[[ noreturn ]]
[[ __noreturn__ ]]
[[ _Noreturn ]]
[[ ___Noreturn__ ]] 		(deprecated)

Explanation

Indicates that the function does not return.

+

This attribute applies to the name of the function and specifies that the function does not return by executing the return statement or by reaching the end of the function body (it may return by executing longjmp). The behavior is undefined if the function with this attribute actually returns. A compiler diagnostic is recommended if this can be detected.

+

It has been previously denoted by the keyword _Noreturn until it was deprecated since C23 and replaced by this attribute.

+

Standard library

The following standard functions are declared with noreturn attribute (they used to be declared with _Noreturn specifier until C23):

+

See also

+ +
C documentation for _Noreturn
C++ documentation for [[noreturn]]
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/attributes/noreturn +

+
diff --git a/devdocs/c/language%2Fattributes%2Freproducible.html b/devdocs/c/language%2Fattributes%2Freproducible.html new file mode 100644 index 00000000..fa0bc584 --- /dev/null +++ b/devdocs/c/language%2Fattributes%2Freproducible.html @@ -0,0 +1,22 @@ +

C attribute: unsequenced, reproducible (since C23) +

Provides the compiler with information about the access of objects by a function such that certain properties of function calls can be deduced.

+

Syntax

+ + +
[[ unsequenced ]]
[[ __unsequenced__ ]] 		(1)
[[ reproducible ]]
[[ __reproducible__ ]] 		(2)
+1) Indicates that a function is effectless, idempotent, stateless, and independent
+2) Indicates that a function is effectless and idempotent

Explanation

These attributes apply to a function declarator or to a type specifier that has a function type. The corresponding attribute is a property of the function type.

+

Effectless

An evaluation of a function call is effectless if any store operation that is sequenced during the call is the modification of an object that synchronizes with the call; if additionally the operation is observable, all access to the object must be based on a unique pointer parameter of the function.

+

Idempotent

An evaluation E is idempotent if a second evaluation of E can be sequenced immediately after the original one without changing the resulting value, if any, or the observable state of the execution.

+

Stateless

A function F is stateless if any definition of an object of static or thread storage duration in F or in a function that is called by F is const but not volatile qualified.

+

Independent

A function F is independent if for any object X that is observed by a call to F through an lvalue that is not based on a parameter of the call, all accesses to X in all calls to F during the same program execution observe the same value; otherwise if the access is based on a pointer parameter, there shall be a unique such pointer parameter P such that any access to X shall be to an lvalue that is based on P.

+

An object X is observed by a function call if both synchronize, if X is not local to the call, if X has a lifetime that starts before the function call, and if an access of X is sequenced during the call; the last value of X, if any, that is stored before the call is said to be the value of X that is observed by the call.

+

Notes

These attributes exist for the purpose of compiler optimization.

+

If a function is reproducible, multiple subsequent calls can be treated as a single call.

+

If a function is unsequenced, multiple subsequent calls can be treated as a single call, and the calls can be parallelized and reordered arbitrarily.

+
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/attributes/reproducible +

+
diff --git a/devdocs/c/language%2Fattributes%2Funsequenced.html b/devdocs/c/language%2Fattributes%2Funsequenced.html new file mode 100644 index 00000000..cf247a64 --- /dev/null +++ b/devdocs/c/language%2Fattributes%2Funsequenced.html @@ -0,0 +1,22 @@ +

C attribute: unsequenced, reproducible (since C23) +

Provides the compiler with information about the access of objects by a function such that certain properties of function calls can be deduced.

+

Syntax

+ + +
[[ unsequenced ]]
[[ __unsequenced__ ]] 		(1)
[[ reproducible ]]
[[ __reproducible__ ]] 		(2)
+1) Indicates that a function is effectless, idempotent, stateless, and independent
+2) Indicates that a function is effectless and idempotent

Explanation

These attributes apply to a function declarator or to a type specifier that has a function type. The corresponding attribute is a property of the function type.

+

Effectless

An evaluation of a function call is effectless if any store operation that is sequenced during the call is the modification of an object that synchronizes with the call; if additionally the operation is observable, all access to the object must be based on a unique pointer parameter of the function.

+

Idempotent

An evaluation E is idempotent if a second evaluation of E can be sequenced immediately after the original one without changing the resulting value, if any, or the observable state of the execution.

+

Stateless

A function F is stateless if any definition of an object of static or thread storage duration in F or in a function that is called by F is const but not volatile qualified.

+

Independent

A function F is independent if for any object X that is observed by a call to F through an lvalue that is not based on a parameter of the call, all accesses to X in all calls to F during the same program execution observe the same value; otherwise if the access is based on a pointer parameter, there shall be a unique such pointer parameter P such that any access to X shall be to an lvalue that is based on P.

+

An object X is observed by a function call if both synchronize, if X is not local to the call, if X has a lifetime that starts before the function call, and if an access of X is sequenced during the call; the last value of X, if any, that is stored before the call is said to be the value of X that is observed by the call.

+

Notes

These attributes exist for the purpose of compiler optimization.

+

If a function is reproducible, multiple subsequent calls can be treated as a single call.

+

If a function is unsequenced, multiple subsequent calls can be treated as a single call, and the calls can be parallelized and reordered arbitrarily.

+
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/attributes/unsequenced +

+
diff --git a/devdocs/c/language%2Fattributes.html b/devdocs/c/language%2Fattributes.html new file mode 100644 index 00000000..2aa35067 --- /dev/null +++ b/devdocs/c/language%2Fattributes.html @@ -0,0 +1,102 @@ +

Attribute specifier sequence(since C23) +

Introduces implementation-defined attributes for types, objects, expressions, etc.

+

Syntax

[[attr ]] [[attr1, attr2, attr3(args)]] [[attribute-prefix::attr (args)]]

Formally, the syntax is

+ + +
[[ attribute-list ]] (since C23)

where attribute-list is a comma-separated sequence of zero or more attribute-token s

+ + + + + +
standard-attribute (1)
attribute-prefix :: identifier (2)
standard-attribute ( argument-list (optional) ) (3)
attribute-prefix :: identifier ( argument-list (optional) ) (4)

where attribute-prefix is an identifier and argument-list is a sequence of tokens where parentheses, brackets and braces are balanced (balanced-token-sequence).

+
+1) standard attribute, such as [[fallthrough]] +
+2) attribute with a namespace, such as [[gnu::unused]] +
+3) standard attribute with arguments, such as [[deprecated("reason")]] +
+4) attribute with both a namespace and an argument list, such as [[gnu::nonnull(1)]] +

Explanation

Attributes provide the unified standard syntax for implementation-defined language extensions, such as the GNU and IBM language extensions __attribute__((...)), Microsoft extension __declspec(), etc.

+

An attribute can be used almost everywhere in the C program, and can be applied to almost everything: to types, to variables, to functions, to names, to code blocks, to entire translation units, although each particular attribute is only valid where it is permitted by the implementation: [[expect_true]] could be an attribute that can only be used with an if, and not with a class declaration. [[omp::parallel()]] could be an attribute that applies to a code block or to a for loop, but not to the type int, etc. (note these two attributes are fictional examples, see below for the standard and some non-standard attributes)

+

In declarations, attributes may appear both before the whole declaration and directly after the name of the entity that is declared, in which case they are combined. In most other situations, attributes apply to the directly preceding entity.

+

Two consecutive left square bracket tokens ([[) may only appear when introducing an attribute-specifier or inside an attribute argument.

+

Besides the standard attributes listed below, implementations may support arbitrary non-standard attributes with implementation-defined behavior. All attributes unknown to an implementation are ignored without causing an error.

+

Every standard-attribute is reserved for standardization. That is, every non-standard attribute is prefixed by a attribute-prefix provided by the implementation, e.g. [[gnu::may_alias]] and [[clang::no_sanitize]].

+

Standard attributes

Only the following attributes are defined by the C standard. Every standard attribute whose name is of form attr can be also spelled as __attr__ and its meaning is not changed.

+ + + + + + + +
[[deprecated]](C23)
[[deprecated("reason")]](C23) 		indicates that the use of the name or entity declared with this attribute is allowed, but discouraged for some reason
(attribute specifier)
[[fallthrough]](C23) indicates that the fall through from the previous case label is intentional and should not be diagnosed by a compiler that warns on fall-through
(attribute specifier)
[[nodiscard]](C23)
[[nodiscard("reason")]](C23) 		encourages the compiler to issue a warning if the return value is discarded
(attribute specifier)
[[maybe_unused]](C23) suppresses compiler warnings on unused entities, if any
(attribute specifier)
[[noreturn]](C23)
[[_Noreturn]](C23)(deprecated) 		indicates that the function does not return
(attribute specifier)
[[unsequenced]](C23) indicates that a function is stateless, effectless, idempotent and independent
(attribute specifier)
[[reproducible]](C23) indicates that a function is effectless and idempotent
(attribute specifier)

Attribute testing

+ +
__has_c_attribute( attribute-token )

Checks for the presence of an attribute token named by attribute-token.

+

For standard attributes, it will expand to the year and month in which the attribute was added to the working draft (see table below), the presence of vendor-specific attributes is determined by a non-zero integer constant.

+

__has_c_attribute can be expanded in the expression of #if and #elif. It is treated as a defined macro by #ifdef, #ifndef and defined but cannot be used anywhere else.

+ + + + + + + + + +
attribute-token Attribute Value Standard
+deprecated +[[deprecated]] +201904L +(C23)
+fallthrough +[[fallthrough]] +201904L +(C23)
+maybe_unused +[[maybe_unused]] +201904L +(C23)
+nodiscard +[[nodiscard]] +202003L +(C23)
+noreturn
_Noreturn 		+[[noreturn]]
[[_Noreturn]] 		+202202L +(C23)
+unsequenced +[[unsequenced]] +202207L +(C23)
+reproducible +[[reproducible]] +202207L +(C23)

Example

[[gnu::hot]] [[gnu::const]] [[nodiscard]]
+int f(void); // declare f with three attributes
+ 
+[[gnu::const, gnu::hot, nodiscard]]
+int f(void); // the same as above, but uses a single attr
+             // specifier that contains three attributes
+ 
+int f(void) { return 0; }
+ 
+int main(void)
+{
+}

References

See also

+
C++ documentation for Attribute specifier sequence
+ + +
1. +Attributes in GCC
2. +Attributes in Clang
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/attributes +

+
diff --git a/devdocs/c/language%2Fbasic_concepts.html b/devdocs/c/language%2Fbasic_concepts.html new file mode 100644 index 00000000..f5f9fa6a --- /dev/null +++ b/devdocs/c/language%2Fbasic_concepts.html @@ -0,0 +1,13 @@ +

Basic concepts

This section provides definitions for the specific terminology and the concepts used when describing the C programming language.

+

A C program is a sequence of text files (typically header and source files) that contain declarations. They undergo translation to become an executable program, which is executed when the OS calls its main function (unless it is itself the OS or another freestanding program, in which case the entry point is implementation-defined).

+

Certain words in a C program have special meaning, they are keywords. Others can be used as identifiers, which may be used to identify objects, functions, struct, union, or enumeration tags, their members, typedef names, labels, or macros.

+

Each identifier (other than macro) is only valid within a part of the program called its scope and belongs to one of four kinds of name spaces. Some identifiers have linkage which makes them refer to the same entities when they appear in different scopes or translation units.

+

Definitions of functions include sequences of statements and declarations, some of which include expressions, which specify the computations to be performed by the program.

+

Declarations and expressions create, destroy, access, and manipulate objects. Each object, function, and expression in C is associated with a type.

+

See also

+
C++ documentation for Basic concepts
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/basic_concepts +

+
diff --git a/devdocs/c/language%2Fbehavior.html b/devdocs/c/language%2Fbehavior.html new file mode 100644 index 00000000..0a883ffc --- /dev/null +++ b/devdocs/c/language%2Fbehavior.html @@ -0,0 +1,166 @@ +

Undefined behavior

The C language standard precisely specifies the observable behavior of C language programs, except for the ones in the following categories:

+

(Note: Strictly conforming programs do not depend on any unspecified, undefined, or implementation-defined behavior)

+

The compilers are required to issue diagnostic messages (either errors or warnings) for any programs that violates any C syntax rule or semantic constraint, even if its behavior is specified as undefined or implementation-defined or if the compiler provides a language extension that allows it to accept such program. Diagnostics for undefined behavior are not otherwise required.

+

UB and optimization

Because correct C programs are free of undefined behavior, compilers may produce unexpected results when a program that actually has UB is compiled with optimization enabled:

+

For example,

+

Signed overflow

int foo(int x)
+{
+    return x + 1 > x; // either true or UB due to signed overflow
+}

may be compiled as (demo)

+
foo:
+        mov     eax, 1
+        ret

Access out of bounds

int table[4] = {0};
+int exists_in_table(int v)
+{
+    // return 1 in one of the first 4 iterations or UB due to out-of-bounds access
+    for (int i = 0; i <= 4; i++)
+        if (table[i] == v)
+            return 1;
+    return 0;
+}

May be compiled as (demo)

+
exists_in_table:
+        mov     eax, 1
+        ret

Uninitialized scalar

_Bool p; // uninitialized local variable
+if (p) // UB access to uninitialized scalar
+    puts("p is true");
+if (!p) // UB access to uninitialized scalar
+    puts("p is false");

May produce the following output (observed with an older version of gcc):

+
p is true
+p is false
size_t f(int x)
+{
+    size_t a;
+    if (x) // either x nonzero or UB
+        a = 42;
+    return a;
+}

May be compiled as (demo)

+
f:
+        mov     eax, 42
+        ret

Invalid scalar

int f(void)
+{
+    _Bool b = 0;
+    unsigned char* p = (unsigned char*)&b;
+    *p = 10;
+    // reading from b is now UB
+    return b == 0;
+}

May be compiled as (demo)

+
f:
+        mov     eax, 11
+        ret

Null pointer dereference

int foo(int* p)
+{
+    int x = *p;
+    if (!p)
+        return x; // Either UB above or this branch is never taken
+    else
+        return 0;
+}
+ 
+int bar()
+{
+    int* p = NULL;
+    return *p;    // Unconditional UB
+}

may be compiled as (demo)

+
foo:
+        xor     eax, eax
+        ret
+bar:
+        ret

Access to pointer passed to realloc +

+

Choose clang to observe the output shown

+
#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    int *p = (int*)malloc(sizeof(int));
+    int *q = (int*)realloc(p, sizeof(int));
+    *p = 1; // UB access to a pointer that was passed to realloc
+    *q = 2;
+    if (p == q) // UB access to a pointer that was passed to realloc
+        printf("%d%d\n", *p, *q);
+}

Possible output:

+
12

Infinite loop without side-effects

+

Choose clang to observe the output shown

+
#include <stdio.h>
+ 
+int fermat()
+{
+    const int MAX = 1000;
+    // Endless loop with no side effects is UB
+    for (int a = 1, b = 1, c = 1; 1;)
+    {
+        if (((a * a * a) == ((b * b * b) + (c * c * c))))
+            return 1;
+        ++a;
+        if (a > MAX)
+        {
+            a = 1;
+            ++b;
+        }
+        if (b > MAX)
+        {
+            b = 1;
+            ++c;
+        }
+        if (c > MAX)
+            c = 1;
+    }
+    return 0;
+}
+ 
+int main(void)
+{
+    if (fermat())
+        puts("Fermat's Last Theorem has been disproved.");
+    else
+        puts("Fermat's Last Theorem has not been disproved.");
+}

Possible output:

+
Fermat's Last Theorem has been disproved.

References

+ + + + + + + +
1. +What Every C Programmer Should Know About Undefined Behavior #1/3
2. +What Every C Programmer Should Know About Undefined Behavior #2/3
3. +What Every C Programmer Should Know About Undefined Behavior #3/3
4. +Undefined behavior can result in time travel (among other things, but time travel is the funkiest)
5. +Understanding Integer Overflow in C/C++
6. +Undefined Behavior and Fermat’s Last Theorem
7. +Fun with NULL pointers, part 1 (local exploit in Linux 2.6.30 caused by UB due to null pointer dereference)

See also

+
C++ documentation for Undefined behavior
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/behavior +

+
diff --git a/devdocs/c/language%2Fbit_field.html b/devdocs/c/language%2Fbit_field.html new file mode 100644 index 00000000..016f0ca2 --- /dev/null +++ b/devdocs/c/language%2Fbit_field.html @@ -0,0 +1,102 @@ +

Bit-fields

Declares a member with explicit width, in bits. Adjacent bit-field members may be packed to share and straddle the individual bytes.

+

A bit-field declaration is a struct or union member declaration which uses the following declarator:

+ + +
identifier (optional) : width
+ + +
identifier - a name of the bit-field that is being declared. The name is optional: nameless bit-fields introduce the specified number of bits of padding
width - an integer constant expression with a value greater or equal to zero and less or equal the number of bits in the underlying type. When greater than zero, this is the number of bits that this bit-field will occupy. The value zero is only allowed for nameless bit-fields and has special meaning: it specifies that the next bit-field in the class definition will begin at an allocation unit's boundary.

Explanation

Bit-fields can have only one of these three(until C99) – four(since C99)(until C23) types (possibly const or volatile qualified):

+ + + + +
  • _Bool, for single-bit bit-fields (bool x:1;) has the range 0..1 and implicit conversions to and from it follow the boolean conversion rules.
(since C99)
  • bit-precise integer types. (e.g. _BitInt(5):4; has the range -8..7 and unsigned _BitInt(5):4; has the range 0..15).
(since C23)

Additional implementation-defined types may be acceptable. It is also implementation-defined whether a bit-field may have atomic type.(since C11) The number of bits in a bit-field (width) sets the limit to the range of values it can hold:

+
#include <stdio.h>
+ 
+struct S
+{
+    // three-bit unsigned field,
+    // allowed values are 0...7
+    unsigned int b : 3;
+};
+ 
+int main(void)
+{
+    struct S s = {7};
+    ++s.b; // unsigned overflow
+    printf("%d\n", s.b); // output: 0
+}

Multiple adjacent bit-fields are permitted to be (and usually are) packed together:

+
#include <stdio.h>
+ 
+struct S
+{
+    // will usually occupy 4 bytes:
+    // 5 bits: value of b1
+    // 11 bits: unused
+    // 6 bits: value of b2
+    // 2 bits: value of b3
+    // 8 bits: unused
+    unsigned b1 : 5, : 11, b2 : 6, b3 : 2;
+};
+ 
+int main(void)
+{
+    printf("%zu\n",sizeof(struct S)); // usually prints 4
+}

The special unnamed bit-field of width zero breaks up padding: it specifies that the next bit-field begins at the beginning of the next allocation unit:

+
#include <stdio.h>
+ 
+struct S
+{
+    // will usually occupy 8 bytes:
+    // 5 bits: value of b1
+    // 27 bits: unused
+    // 6 bits: value of b2
+    // 15 bits: value of b3
+    // 11 bits: unused
+    unsigned b1 : 5;
+    unsigned :0; // start a new unsigned int
+    unsigned b2 : 6;
+    unsigned b3 : 15;
+};
+ 
+int main(void)
+{
+    printf("%zu\n", sizeof(struct S)); // usually prints 8
+}

Because bit-fields do not necessarily begin at the beginning of a byte, address of a bit-field cannot be taken. Pointers to bit-fields are not possible. Bit-fields cannot be used with sizeof and _Alignas(since C11).

+

Notes

The following usages of bit-fields causes undefined behavior:

+

The following properties of bit-fields are unspecified:

+

The following properties of bit-fields are implementation-defined:

+ + +
  • Whether atomic types are permitted
(since C11)
+ +

Even though the number of bits in the object representation of _Bool is at least CHAR_BIT, the width of the bit-field of type _Bool cannot be greater than 1.

+		 (since C99)

In the C++ programming language, the width of a bit-field can exceed the width of the underlying type (but the extra bits are padding bits), and bit-fields of type int are always signed.

+

References

See also

+
C++ documentation for Bit-field
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/bit_field +

+
diff --git a/devdocs/c/language%2Fbool_constant.html b/devdocs/c/language%2Fbool_constant.html new file mode 100644 index 00000000..f3be4efd --- /dev/null +++ b/devdocs/c/language%2Fbool_constant.html @@ -0,0 +1,21 @@ +

Predefined Boolean constants (since C23) +

Syntax

+ + +
true (1) (since C23)
false (2) (since C23)

Explanation

Keywords true and false represent predefined constants. They are non-lvalues of type bool.

+

Notes

See integral conversions for implicit conversions from bool to other types and boolean conversions for the implicit conversions from other types to bool.

+

Until C23, true and false were implemented as macros provided in <stdbool.h>. An implementation may also define bool, true, and false as predefined macros in C23 for compatibility.

+

Example

#include <stdio.h>
+ 
+int main(void)
+{
+    printf("%d\n%d\n", true, false);
+}

Output:

+
1
+0

See also

+
C++ documentation for Boolean literals
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/bool_constant +

+
diff --git a/devdocs/c/language%2Fbreak.html b/devdocs/c/language%2Fbreak.html new file mode 100644 index 00000000..bf2423f9 --- /dev/null +++ b/devdocs/c/language%2Fbreak.html @@ -0,0 +1,62 @@ +

break statement

Causes the enclosing for, while or do-while loop or switch statement to terminate.

+

Used when it is otherwise awkward to terminate the loop using the condition expression and conditional statements.

+

Syntax

+ +
attr-spec-seq (optional) break ;
+ +
attr-spec-seq - (C23) optional list of attributes, applied to the break statement

Appears only within the statement of a loop body (while, do-while, for) or within the statement of a switch.

+

Explanation

After this statement the control is transferred to the statement or declaration immediately following the enclosing loop or switch, as if by goto.

+

Keywords

break

+

Notes

A break statement cannot be used to break out of multiple nested loops. The goto statement may be used for this purpose.

+

Example

#include <stdio.h>
+ 
+int main(void)
+{
+    int i = 2;
+    switch (i)
+    {
+        case 1: printf("1");
+        case 2: printf("2");   // i==2, so execution starts at this case label
+        case 3: printf("3");
+        case 4:
+        case 5: printf("45");
+                break;         // execution of subsequent cases is terminated
+        case 6: printf("6");
+    }
+    printf("\n");
+ 
+    // Compare outputs from these two nested for loops.
+    for (int j = 0; j < 2; j++)
+        for (int k = 0; k < 5; k++)
+            printf("%d%d ", j,k);
+    printf("\n");
+ 
+    for (int j = 0; j < 2; j++)
+    {
+        for (int k = 0; k < 5; k++) // only this loop is exited by break
+        {
+            if (k == 2)
+                break;
+            printf("%d%d ", j,k);
+        }
+    }
+}

Possible output:

+
2345
+00 01 02 03 04 10 11 12 13 14
+00 01 10 11

References

See also

+ +
[[fallthrough]](C23) indicates that the fall through from the previous case label is intentional and should not be diagnosed by a compiler that warns on fall-through
(attribute specifier)
C++ documentation for break statement
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/break +

+
diff --git a/devdocs/c/language%2Fcast.html b/devdocs/c/language%2Fcast.html new file mode 100644 index 00000000..aae5fe1a --- /dev/null +++ b/devdocs/c/language%2Fcast.html @@ -0,0 +1,64 @@ +

cast operator

Performs explicit type conversion

+

Syntax

+ +
( type-name ) expression

where

+ + + +
type-name - either the type void or any scalar type
expression - any expression of scalar type (unless type-name is void, in which case it can be anything)

Explanation

If type-name is void, then expression is evaluated for its side-effects and its returned value is discarded, same as when expression is used on its own, as an expression statement.

+

Otherwise, if type-name is exactly the type of expression, nothing is done (except that if expression has floating type and is represented with greater range and precision than its type indicates -- see below)

+

Otherwise, the value of expression is converted to the type named by type-name, as follows:

+

Every implicit conversion as if by assignment is allowed.

+

In addition to the implicit conversions, the following conversions are allowed:

+

In any case (both when executing an implicit conversion and in the same-type cast), if expression and type-name are floating types and expression is represented with greater range and precision than its type indicates (see FLT_EVAL_METHOD), the range and precision are stripped off to match the target type.

+

The value category of the cast expression is always non-lvalue.

+

Notes

Because const, volatile, restrict, and _Atomic qualifiers have effect on lvalues only, a cast to a cvr-qualified or atomic type is exactly equivalent to the cast to the corresponding unqualified type.

+

The cast to void is sometimes useful to silence compiler warnings about unused results.

+

The conversions not listed here are not allowed. In particular,

+ + +

If the implementation provides intptr_t and/or uintptr_t, then a cast from a pointer to an object type (including cv void) to these types is always well-defined. However, this is not guaranteed for a function pointer.

+		 (since C99)

Note that conversions between function pointers and object pointers are accepted as extensions by many compilers, and expected by some usages of POSIX dlsym() function.

+

Example

#include <stdio.h>
+ 
+int main(void)
+{
+    // examining object representation is a legitimate use of cast
+    double d = 3.14;
+    printf("The double %.2f (%a) is: ", d, d);
+    for (size_t n = 0; n < sizeof d; ++n)
+        printf("0x%02x ", ((unsigned char*)&d)[n]);
+ 
+    // edge cases
+    struct S { int x; } s;
+//    (struct S)s; // error; not a scalar type
+                   // even though casting to the same type does nothing
+    (void)s; // okay to cast any type to void
+}

Possible output:

+
The double 3.14 (0x1.91eb851eb851fp+1) is: 0x1f 0x85 0xeb 0x51 0xb8 0x1e 0x09 0x40

References

See also

+
C++ documentation for explicit type conversion
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/cast +

+
diff --git a/devdocs/c/language%2Fcharacter_constant.html b/devdocs/c/language%2Fcharacter_constant.html new file mode 100644 index 00000000..acf4a443 --- /dev/null +++ b/devdocs/c/language%2Fcharacter_constant.html @@ -0,0 +1,106 @@ +

Character constant

Syntax

+ + + + + + + + + +
'c-char ' (1)
u8'c-char ' (2) (since C23)
u'c-char ' (3) (since C11)
U'c-char ' (4) (since C11)
L'c-char ' (5)
'c-char-sequence ' (6)
L'c-char-sequence ' (7)
u'c-char-sequence ' (8) (since C11)(removed in C23)
U'c-char-sequence ' (9) (since C11)(removed in C23)

where

+ + +
(since C99)
+1) single-byte integer character constant, e.g. 'a' or '\n' or '\13'. Such constant has type int and a value equal to the representation of c-char in the execution character set as a value of type char mapped to int. If c-char is not representable as a single byte in the execution character set, the value is implementation-defined.
+2) UTF-8 character constant, e.g. u8'a'. Such constant has type char8_t and the value equal to ISO 10646 code point value of c-char, provided that the code point value is representable with a single UTF-8 code unit (that is, c-char is in the range 0x0-0x7F, inclusive). If c-char is not representable with a single UTF-8 code unit, the program is ill-formed.
+ + + +
3) 16-bit wide character constant, e.g. u'貓', but not u'🍌' (u'\U0001f34c'). Such constant has type char16_t and a value equal to the value of c-char in the 16-bit encoding produced by mbrtoc16 (normally UTF-16). If c-char is not representable or maps to more than one 16-bit character, the value is implementation-defined. 4) 32-bit wide character constant, e.g. U'貓' or U'🍌'. Such constant has type char32_t and a value equal to the value of c-char in in the 32-bit encoding produced by mbrtoc32 (normally UTF-32). If c-char is not representable or maps to more than one 32-bit character, the value is implementation-defined. (until C23)
3) UTF-16 character constant, e.g. u'貓', but not u'🍌' (u'\U0001f34c'). Such constant has type char16_t and the value equal to ISO 10646 code point value of c-char, provided that the code point value is representable with a single UTF-16 code unit (that is, c-char is in the range 0x0-0xD7FF or 0xE000-0xFFFF, inclusive). If c-char is not representable with a single UTF-16 code unit, the program is ill-formed. 4) UTF-32 character constant, e.g. U'貓' or U'🍌'. Such constant has type char32_t and the value equal to ISO 10646 code point value of c-char, provided that the code point value is representable with a single UTF-32 code unit (that is, c-char is in the range 0x0-0xD7FF or 0xE000-0x10FFFF, inclusive). If c-char is not representable with a single UTF-32 code unit, the program is ill-formed. (since C23)
+5) wide character constant, e.g. L'β' or L'貓. Such constant has type wchar_t and a value equal to the value of c-char in the execution wide character set (that is, the value that would be produced by mbtowc). If c-char is not representable or maps to more than one wide character (e.g. a non-BMP value on Windows where wchar_t is 16-bit), the value is implementation-defined .
+6) multicharacter constant, e.g. 'AB', has type int and implementation-defined value.
+7) wide multicharacter constant, e.g. L'AB', has type wchar_t and implementation-defined value.
+8) 16-bit multicharacter constant, e.g. u'CD', has type char16_t and implementation-defined value.
+9) 32-bit multicharacter constant, e.g. U'XY', has type char32_t and implementation-defined value.

Notes

Multicharacter constants were inherited by C from the B programming language. Although not specified by the C standard, most compilers (MSVC is a notable exception) implement multicharacter constants as specified in B: the values of each char in the constant initialize successive bytes of the resulting integer, in big-endian zero-padded right-adjusted order, e.g. the value of '\1' is 0x00000001 and the value of '\1\2\3\4' is 0x01020304.

+

In C++, encodable ordinary character literals have type char, rather than int.

+

Unlike integer constants, a character constant may have a negative value if char is signed: on such implementations '\xFF' is an int with the value -1.

+

When used in a controlling expression of #if or #elif, character constants may be interpreted in terms of the source character set, the execution character set, or some other implementation-defined character set.

+

16/32-bit multicharacter constants are not widely supported and removed in C23. Some common implementations (e.g. clang) do not accept them at all.

+

Example

#include <stddef.h>
+#include <stdio.h>
+#include <uchar.h>
+ 
+int main (void)
+{
+    printf("constant value     \n");
+    printf("-------- ----------\n");
+ 
+    // integer character constants,
+    int c1='a'; printf("'a':\t %#010x\n", c1);
+    int c2='🍌'; printf("'🍌':\t %#010x\n\n", c2); // implementation-defined
+ 
+    // multicharacter constant
+    int c3='ab'; printf("'ab':\t %#010x\n\n", c3); // implementation-defined
+ 
+    // 16-bit wide character constants
+    char16_t uc1 = u'a'; printf("'a':\t %#010x\n", (int)uc1);
+    char16_t uc2 = u'¢'; printf("'¢':\t %#010x\n", (int)uc2);
+    char16_t uc3 = u'猫'; printf("'猫':\t %#010x\n", (int)uc3);
+    // implementation-defined (🍌 maps to two 16-bit characters)
+    char16_t uc4 = u'🍌'; printf("'🍌':\t %#010x\n\n", (int)uc4);
+ 
+    // 32-bit wide character constants
+    char32_t Uc1 = U'a'; printf("'a':\t %#010x\n", (int)Uc1);
+    char32_t Uc2 = U'¢'; printf("'¢':\t %#010x\n", (int)Uc2);
+    char32_t Uc3 = U'猫'; printf("'猫':\t %#010x\n", (int)Uc3);
+    char32_t Uc4 = U'🍌'; printf("'🍌':\t %#010x\n\n", (int)Uc4);
+ 
+    // wide character constants
+    wchar_t wc1 = L'a'; printf("'a':\t %#010x\n", (int)wc1);
+    wchar_t wc2 = L'¢'; printf("'¢':\t %#010x\n", (int)wc2);
+    wchar_t wc3 = L'猫'; printf("'猫':\t %#010x\n", (int)wc3);
+    wchar_t wc4 = L'🍌'; printf("'🍌':\t %#010x\n\n", (int)wc4);
+}

Possible output:

+
constant value     
+-------- ----------
+'a':         0x00000061
+'🍌':         0xf09f8d8c
+ 
+'ab':         0x00006162
+ 
+'a':         0x00000061
+'¢':         0x000000a2
+'猫':         0x0000732b
+'🍌':         0x0000df4c
+ 
+'a':         0x00000061
+'¢':         0x000000a2
+'猫':         0x0000732b
+'🍌':         0x0001f34c
+ 
+'a':         0x00000061
+'¢':         0x000000a2
+'猫':         0x0000732b
+'🍌':         0x0001f34c

References

See also

+
C++ documentation for Character literal
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/character_constant +

+
diff --git a/devdocs/c/language%2Fcharset.html b/devdocs/c/language%2Fcharset.html new file mode 100644 index 00000000..38cfbf0f --- /dev/null +++ b/devdocs/c/language%2Fcharset.html @@ -0,0 +1,112 @@ +

Character sets and encodings

Basic character set

The basic character set consists of the following 95 characters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Code unit Character Glyph
U+0009 Character tabulation
U+000B Line tabulation
U+000C Form feed (FF)
U+0020 Space
U+0021 Exclamation mark +!
U+0022 Quotation mark +"
U+0023 Number sign +#
U+0025 Percent sign +%
U+0026 Ampersand +&
U+0027 Apostrophe +'
U+0028 Left parenthesis +(
U+0029 Right parenthesis +)
U+002A Asterisk +*
U+002B Plus sign ++
U+002C Comma +,
U+002D Hyphen-minus +-
U+002E Full stop +.
U+002F Solidus +/
U+0030 .. U+0039 Digit zero .. nine +0 1 2 3 4 5 6 7 8 9
U+003A Colon +:
U+003B Semicolon +;
U+003C Less-than sign +<
U+003D Equals sign +=
U+003E Greater-than sign +>
U+003F Question mark +?
U+0041 .. U+005A Latin capital letter A .. Z +A B C D E F G H I J K L M

N O P Q R S T U V W X Y Z

+
U+005B Left square bracket +[
U+005C Reverse solidus +\
U+005D Right square bracket +]
U+005E Circumflex accent +^
U+005F Low line +_
U+0061 .. U+007A Latin small letter a .. z +a b c d e f g h i j k l m

n o p q r s t u v w x y z

+
U+007B Left curly bracket +{
U+007C Vertical line +|
U+007D Right curly bracket +}
U+007E Tilde +~

Unlike C++, the U+000A LINE FEED (LF) character is not included in basic character set. Instead, there shall be some way of indicating the end of each line of text in the source file and the document treats such an end-of-line indicator as if it were a single new-line character.

+

Basic character set is also known as basic source character set.

+

Basic execution character set

The basic execution character set contains all the members of the basic character set, plus the following characters:

+ + + + + + + +
Code unit Character
U+0000 Null
U+0007 Bell
U+0008 Backspace
U+000A Line feed (LF)
U+000D Carriage return (CR)

For each basic execution character set, the values of the members shall be non-negative and distinct from one another. In both the source and execution basic character sets, the value of each character after 0 in the above list of decimal digits shall be one greater than the value of the previous. The U+0000 NULL character has the value 0.

+

The representation of each member of the basic execution character sets fit in a byte.

+

In C++, basic execution character set is also known as basic literal character set and basic execution wide-character set.

+

Literal encodings

The literal encoding is an implementation-defined mapping of the characters of the execution character set to the values in a character constant or string literal without encoding prefix. It supports a mapping from all the basic execution character set values into the implementation-defined encoding. It may contain multibyte character sequences.

+ + +

The following characters are not in basic execution character set, but they are required to be encoded as a single byte in an ordinary character constant or ordinary string literal.

+ + + + + +
Code unit Character Glyph
U+0024 Dollar Sign +$
U+0040 Commercial At +@
U+0060 Grave Accent +`
(since C23)

The wide literal encoding is an implementation-defined mapping of the characters of the execution character set to the values in an L-prefixed character constant or string literal. It supports a mapping from all the basic execution character set values into the implementation-defined encoding. If an implementation does not define __STDC_MB_MIGHT_NEQ_WC__, the mapping produces values identical to the literal encoding for all the basic execution character set values. One or more values may map to one or more values of the extended execution character set.

+ + +

The UTF-8 encoding is used for mapping characters of the execution character set to a u8-prefixed character constant or(since C23) string literal.

+

An implementation-defined encoding(until C23)The UTF-16 encoding(since C23) is used for mapping characters of the execution character set to a u-prefixed character constant or string literal.

+

An implementation-defined encoding(until C23)The UTF-32 encoding(since C23) is used for mapping characters of the execution character set to a U-prefixed character constant or string literal.

+		 (since C11)

See also

+ +
ASCII chart
C++ documentation for Character sets and encodings
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/charset +

+
diff --git a/devdocs/c/language%2Fcompatible_type.html b/devdocs/c/language%2Fcompatible_type.html new file mode 100644 index 00000000..06a3bead --- /dev/null +++ b/devdocs/c/language%2Fcompatible_type.html @@ -0,0 +1,233 @@ +

Type

(See also arithmetic types for the details on most built-in types and the list of type-related utilities that are provided by the C library.)

+

Objects, functions, and expressions have a property called type, which determines the interpretation of the binary value stored in an object or evaluated by the expression.

+

Type classification

The C type system consists of the following types:

+ + + + +
  • bit-precise: _BitInt(N) where N is an integer constant expression that specifies the number of bits that are used to represent the type, including the sign bit. Each value of N designates a distinct type.
(since C23)
  • extended: implementation defined, e.g. __int128
(since C99)
+ + + +
  • bit-precise: unsigned _BitInt(N) where N is an integer constant expression that specifies the number of bits that are used to represent the type. Each value of N designates a distinct type. This category includes the type unsigned _BitInt(1) which does not have a corresponding bit-precise signed integer type
(since C23)
  • extended: implementation-defined, e.g. __uint128
(since C99)
+ + + +
  • decimal real floating-point types: _Decimal32, _Decimal64, _Decimal128
(since C23)
    +
  • complex types: float _Complex, double _Complex, long double _Complex
    • +
  • imaginary types: float _Imaginary, double _Imaginary, long double _Imaginary
    • +
 (since C99)
+ +
(since C11)

For every type listed above several qualified versions of its type may exist, corresponding to the combinations of one, two, or all three of the const, volatile, and restrict qualifiers (where allowed by the qualifier's semantics).

+

Type groups

Constructing a complete object type such that the number of bytes in its object representation is not representable in the type size_t (i.e. the result type of sizeof operator), including forming such a VLA type at runtime,(since C99) is undefined behavior.

+

Compatible types

In a C program, the declarations referring to the same object or function in different translation units do not have to use the same type. They only have to use sufficiently similar types, formally known as compatible types. Same applies to function calls and lvalue accesses; argument types must be compatible with parameter types and lvalue expression type must be compatible with the object type that is accessed.

+

The types T and U are compatible, if

+ + +
    +
  • one is an old-style (parameter-less) definition, the other has a parameter list, the parameter list does not use an ellipsis and each parameter is compatible (after function parameter type adjustment) with the corresponding old-style parameter after default argument promotions
    • +
  • one is an old-style (parameter-less) declaration, the other has a parameter list, the parameter list does not use an ellipsis, and all parameters (after function parameter type adjustment) are unaffected by default argument promotions
    • +
 (until C23)

The type char is not compatible with signed char and not compatible with unsigned char.

+

If two declarations refer to the same object or function and do not use compatible types, the behavior of the program is undefined.

+
// Translation Unit 1
+struct S { int a; };
+extern struct S *x; // compatible with TU2's x, but not with TU3's x
+ 
+// Translation Unit 2
+struct S;
+extern struct S *x; // compatible with both x's
+ 
+// Translation Unit 3
+struct S { float a; };
+extern struct S *x; // compatible with TU2's x, but not with TU1's x
+ 
+// the behavior is undefined
// Translation Unit 1
+#include <stdio.h>
+ 
+struct s { int i; }; // compatible with TU3's s, but not TU2's
+extern struct s x = {0}; // compatible with TU3's x
+extern void f(void); // compatible with TU2's f
+ 
+int main()
+{
+    f();
+    return x.i;
+}
+ 
+// Translation Unit 2
+struct s { float f; }; // compatible with TU4's s, but not TU1's s
+extern struct s y = {3.14}; // compatible with TU4's y
+void f() // compatible with TU1's f
+{
+    return;
+}
+ 
+// Translation Unit 3
+struct s { int i; }; // compatible with TU1's s, but not TU2's s
+extern struct s x; // compatible with TU1's x
+ 
+// Translation Unit 4
+struct s { float f; }; // compatible with TU2's s, but not TU1's s
+extern struct s y; // compatible with TU2's y
+ 
+// the behavior is well-defined: only multiple declarations
+// of objects and functions must have compatible types, not the types themselves

Note: C++ has no concept of compatible types. A C program that declares two types that are compatible but not identical in different translation units is not a valid C++ program.

+

Composite types

A composite type can be constructed from two types that are compatible; it is a type that is compatible with both of the two types and satisfies the following conditions:

+ + +
    +
  • Otherwise, if one type is a VLA whose size is specified by an expression that is not evaluated, a program necessitating the composite type of both types has undefined behavior.
    • +
  • Otherwise, if one type is a VLA whose size is specified, the composite type is a VLA of that size.
    • +
  • Otherwise, if one type is a VLA of unspecified size, the composite type is a VLA of unspecified size.
    • +
 (since C99)
The element type of the composite type is the composite type of the two element types. + +
  • If only one type is a function type with a parameter type list (a function prototype), the composite type is a function prototype with the parameter type list.
(until C23)

These rules apply recursively to the types from which the two types are derived.

+
// Given the following two file scope declarations:
+int f(int (*)(), double (*)[3]);
+int f(int (*)(char *), double (*)[]); // C23: Error: conflicting types for 'f'
+// The resulting composite type for the function is:
+int f(int (*)(char *), double (*)[3]);

For an identifier with internal or external linkage declared in a scope in which a prior declaration of that identifier is visible, if the prior declaration specifies internal or external linkage, the type of the identifier at the later declaration becomes the composite type.

+

Incomplete types

An incomplete type is an object type that lacks sufficient information to determine the size of the objects of that type. An incomplete type may be completed at some point in the translation unit.

+

The following types are incomplete:

+ 
extern char a[]; // the type of a is incomplete (this typically appears in a header)
+char a[10];      // the type of a is now complete (this typically appears in a source file)
struct node
+{
+    struct node *next; // struct node is incomplete at this point
+}; // struct node is complete at this point

Type names

A type may have to be named in context other than the declaration. In these situations, type name is used, which is, grammatically, exactly the same as a list of type-specifiers and type-qualifiers, followed by the declarator (see declarations) as would be used to declare a single object or function of this type, except that the identifier is omitted:

+
int n; // declaration of an int
+sizeof(int); // use of type name
+ 
+int *a[3]; // declaration of an array of 3 pointers to int
+sizeof(int *[3]); // use of type name
+ 
+int (*p)[3]; // declaration of a pointer to array of 3 int
+sizeof(int (*)[3]); // use of type name
+ 
+int (*a)[*] // declaration of pointer to VLA (in a function parameter)
+sizeof(int (*)[*]) // use of type name (in a function parameter)
+ 
+int *f(void); // declaration of function
+sizeof(int *(void)); // use of type name
+ 
+int (*p)(void); // declaration of pointer to function
+sizeof(int (*)(void)); // use of type name
+ 
+int (*const a[])(unsigned int, ...) = {0}; // array of pointers to functions
+sizeof(int (*const [])(unsigned int, ...)); // use of type name

Except the redundant parentheses around the identifier are meaningful in a type-name and represent "function with no parameter specification":

+
int (n); // declares n of type int
+sizeof(int ()); // uses type "function returning int"

Type names are used in the following situations:

+ + + + +
(since C99)
(since C11)


A type name may introduce a new type:

+
void* p = (void*)(struct X { int i; } *)0;
+// type name "struct X {int i;}*" used in the cast expression
+// introduces the new type "struct X"
+struct X x = {1}; // struct X is now in scope

References

See also

+
C++ documentation for Type
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/compatible_type +

+
diff --git a/devdocs/c/language%2Fcompound_literal.html b/devdocs/c/language%2Fcompound_literal.html new file mode 100644 index 00000000..6b245c1a --- /dev/null +++ b/devdocs/c/language%2Fcompound_literal.html @@ -0,0 +1,89 @@ +

Compound literals (since C99) +

Constructs an unnamed object of specified type (which may be struct, union, or even array type) in-place.

+

Syntax

+ + + +
( storage-class-specifiers (optional)(since C23) type ) { initializer-list } (since C99)
( storage-class-specifiers (optional)(since C23) type ) { initializer-list , } (since C99)
( storage-class-specifiers (optional) type ) { } (since C23)

where

+ + + + +
storage-class-specifiers - (since C23) A list of storage class specifiers that can contain only constexpr, static, register, or thread_local
type - a type name specifying any complete object type or an array of unknown size, but not a VLA
initializer-list - list of initializers suitable for initialization of an object of type

Explanation

The compound literal expression constructs an unnamed object of the type specified by type and initializes it as specified by initializer-list. Designated initializers are accepted.

+

The type of the compound literal is type (except when type is an array of unknown size; its size is deduced from the initializer-list as in array initialization).

+

The value category of a compound literal is lvalue (its address can be taken).

+ + + + +
The unnamed object to which the compound literal evaluates has static storage duration if the compound literal occurs at file scope and automatic storage duration if the compound literal occurs at block scope (in which case the object's lifetime ends at the end of the enclosing block). (until C23)
If the compound literal is evaluated outside the body of a function and outside of any parameter list, it is associated with file scope; otherwise, it is associated with the enclosing block. Depending on this association, the storage-class specifiers (possibly empty), type name, and initializer list, if any, shall be such that they are valid specifiers for an object definition in file scope or block scope, respectively, of the following form, 
   storage-class-specifiers typeof(type) ID = { initializer-list };
+
where ID is an identifier that is unique for the whole program. A compound literal provides an unnamed object whose value, type, storage duration and other properties are as if given by the definition syntax above; if the storage duration is automatic, the lifetime of the instance of the unnamed object is the current execution of the enclosing block. If the storage-class specifiers contain other specifiers than constexpr, static, register, or thread_local the behavior is undefined.		 (since C23)

Notes

Compound literals of const-qualified character or wide character array types may share storage with string literals.

+
(const char []){"abc"} == "abc" // might be 1 or 0, unspecified

Each compound literal creates only a single object in its scope:

+
int f (void)
+{
+    struct s {int i;} *p = 0, *q;
+    int j = 0;
+again:
+    q = p, p = &((struct s){ j++ });
+    if (j < 2) goto again; // note; if a loop were used, it would end scope here,
+                           // which would terminate the lifetime of the compound literal
+                           // leaving p as a dangling pointer
+    return p == q && q->i == 1; // always returns 1
+}

Because compound literals are unnamed, a compound literal cannot reference itself (a named struct can include a pointer to itself)

+

Although the syntax of a compound literal is similar to a cast, the important distinction is that a cast is a non-lvalue expression while a compound literal is an lvalue.

+

Example

#include <stdio.h>
+ 
+int *p = (int[]){2, 4}; // creates an unnamed static array of type int[2]
+                        // initializes the array to the values {2, 4}
+                        // creates pointer p to point at the first element of
+                        // the array
+const float *pc = (const float []){1e0, 1e1, 1e2}; // read-only compound literal
+ 
+struct point {double x,y;};
+ 
+int main(void)
+{
+    int n = 2, *p = &n;
+    p = (int [2]){*p}; // creates an unnamed automatic array of type int[2]
+                       // initializes the first element to the value formerly
+                       // held in *p
+                       // initializes the second element to zero
+                       // stores the address of the first element in p
+ 
+    void drawline1(struct point from, struct point to);
+    void drawline2(struct point *from, struct point *to);
+    drawline1(
+        (struct point){.x=1, .y=1},  // creates two structs with block scope and
+        (struct point){.x=3, .y=4}); // calls drawline1, passing them by value
+    drawline2(
+        &(struct point){.x=1, .y=1},  // creates two structs with block scope and
+        &(struct point){.x=3, .y=4}); // calls drawline2, passing their addresses
+}
+ 
+void drawline1(struct point from, struct point to)
+{
+    printf("drawline1: `from` @ %p {%.2f, %.2f}, `to` @ %p {%.2f, %.2f}\n",
+        (void*)&from, from.x, from.y, (void*)&to, to.x, to.y);
+}
+ 
+void drawline2(struct point *from, struct point *to)
+{
+    printf("drawline2: `from` @ %p {%.2f, %.2f}, `to` @ %p {%.2f, %.2f}\n",
+        (void*)from, from->x, from->y, (void*)to, to->x, to->y);
+}

Possible output:

+
drawline1: `from` @ 0x7ffd24facea0 {1.00, 1.00}, `to` @ 0x7ffd24face90 {3.00, 4.00}
+drawline2: `from` @ 0x7ffd24facec0 {1.00, 1.00}, `to` @ 0x7ffd24faced0 {3.00, 4.00}

References

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/compound_literal +

+
diff --git a/devdocs/c/language%2Fconformance.html b/devdocs/c/language%2Fconformance.html new file mode 100644 index 00000000..63acf442 --- /dev/null +++ b/devdocs/c/language%2Fconformance.html @@ -0,0 +1,55 @@ +

Conformance

Conformance has a three-fold definition:

+

Explanation

The standard does not define any minimum implementation limit on translation units. A hosted environment has an operating system; a freestanding environment does not. A program running in a hosted environment may use all features described in the library clause (clause 7); a program running in a freestanding environment may use a subset of library features required by clause 4.

+

Freestanding standard library headers

All standard library features in every fully freestanding header are required to be provided by a freestanding implementation.

+ + +

Some standard library headers are conditionally freestanding.

+
  • If the implementation predefines the macro __STDC_IEC_60559_BFP__ or __STDC_IEC_60559_DFP__, then

In a partially freestanding header, only a part of standard library features are required to be provided by a freestanding implementation.

+
    +
  • strdup, strndup, strcoll, strxfrm, and strerror are not required to be provided by a freestanding implementation.
    • +
  • When __STDC_IEC_60559_BFP__ or __STDC_IEC_60559_DFP__ are predefined, in <stdlib.h>, only numeric conversion functions (atoX, strtoX, and strfromX) are required to be provided by a freestanding implementation.
    • +
 (since C23)
+ + + + + + + + + + + + + + + + + +
Fully freestanding standard library headers
<float.h> Limits of floating-point types
<iso646.h> (since C95) Alternative operator spellings
<limits.h> Ranges of integer types
<stdalign.h> (since C11) alignas and alignof convenience macros
<stdarg.h> Variable arguments
<stdbool.h> (since C99) Macros for boolean type
<stddef.h> Common macro definitions
<stdint.h> (since C99) Fixed-width integer types
<stdnoreturn.h> (since C11) noreturn convenience macro
<stdbit.h> (since C23) Macros to work with the byte and bit representations of types
Partially freestanding standard library headers
<string.h> (since C23) String handling
Conditionally fully freestanding standard library headers
<fenv.h> (since C23) Floating-point environment
<math.h> (since C23) Common mathematics functions
Conditionally partially freestanding standard library headers
<stdlib.h> (since C23) General utilities: memory management, program utilities, string conversions, random numbers, algorithms

References

See also

+
C++ documentation for Freestanding and hosted implementation
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/conformance +

+
diff --git a/devdocs/c/language%2Fconst.html b/devdocs/c/language%2Fconst.html new file mode 100644 index 00000000..be91d4c7 --- /dev/null +++ b/devdocs/c/language%2Fconst.html @@ -0,0 +1,65 @@ +

const type qualifier

Each individual type in the C type system has several qualified versions of that type, corresponding to one, two, or all three of the const, volatile, and, for pointers to object types, restrict qualifiers. This page describes the effects of the const qualifier.

+

Objects declared with const-qualified types may be placed in read-only memory by the compiler, and if the address of a const object is never taken in a program, it may not be stored at all.

+

Any attempt to modify an object whose type is const-qualified results in undefined behavior.

+
const int n = 1; // object of const-qualified type
+int* p = (int*)&n;
+*p = 2; // undefined behavior

const semantics apply to lvalue expressions only; whenever a const lvalue expression is used in context that does not require an lvalue, its const qualifier is lost (note that volatile qualifier, if present, isn't lost).

+

The lvalue expressions that designate objects of const-qualified type and the lvalue expressions that designate objects of struct or union type with at least one member of const-qualified type (including members of recursively contained aggregates or unions), are not modifiable lvalues. In particular, they are not assignable:

+
const int n = 1; // object of const type
+n = 2; // error: the type of n is const-qualified
+ 
+int x = 2; // object of unqualified type
+const int* p = &x;
+*p = 3; // error: the type of the lvalue *p is const-qualified
+ 
+struct {int a; const int b; } s1 = {.b=1}, s2 = {.b=2};
+s1 = s2; // error: the type of s1 is unqualified, but it has a const member

A member of a const-qualified structure or union type acquires the qualification of the type it belongs to (both when accessed using the . operator or the -> operator).

+
struct s { int i; const int ci; } s;
+// the type of s.i is int, the type of s.ci is const int
+const struct s cs;
+// the types of cs.i and cs.ci are both const int
+ + + +

If an array type is declared with the const type qualifier (through the use of typedef), the array type is not const-qualified, but its element type is.

+		 (until C23)

An array type and its element type are always considered to be identically const-qualified.

+		 (since C23)
typedef int A[2][3];
+const A a = {{4, 5, 6}, {7, 8, 9}}; // array of array of const int
+int* pi = a[0]; // Error: a[0] has type const int*
+void *unqual_ptr = a; // OK until C23; error since C23
+// Notes: clang applies the rule in C++/C23 even in C89-C17 modes

If a function type is declared with the const type qualifier (through the use of typedef), the behavior is undefined.

+ + +

In a function declaration, the keyword const may appear inside the square brackets that are used to declare an array type of a function parameter. It qualifies the pointer type to which the array type is transformed.

+

The following two declarations declare the same function:

+
void f(double x[const], const double y[const]);
+void f(double * const x, const double * const y);
 (since C99)
+ +

const-qualified compound literals do not necessarily designate distinct objects; they may share storage with other compound literals and with string literals that happen to have the same or overlapping representation.

+
const int* p1 = (const int[]){1, 2, 3};
+const int* p2 = (const int[]){2, 3, 4}; // the value of p2 may equal p1+1
+_Bool b = "foobar" + 3 == (const char[]){"bar"}; // the value of b may be 1
 (since C99)

A pointer to a non-const type can be implicitly converted to a pointer to const-qualified version of the same or compatible type. The reverse conversion requires a cast expression.

+
int* p = 0;
+const int* cp = p; // OK: adds qualifiers (int to const int)
+p = cp; // Error: discards qualifiers (const int to int)
+p = (int*)cp; // OK: cast

Note that pointer to pointer to T is not convertible to pointer to pointer to const T; for two types to be compatible, their qualifications must be identical.

+
char *p = 0;
+const char **cpp = &p; // Error: char* and const char* are not compatible types
+char * const *pcp = &p; // OK, adds qualifiers (char* to char*const)

Keywords

const

+

Notes

C adopted the const qualifier from C++, but unlike in C++, expressions of const-qualified type in C are not constant expressions; they may not be used as case labels or to initialize static and thread storage duration objects, enumerators, or bit-field sizes. When they are used as array sizes, the resulting arrays are VLAs.

+

References

See also

+
C++ documentation for cv (const and volatile) type qualifiers
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/const +

+
diff --git a/devdocs/c/language%2Fconstant_expression.html b/devdocs/c/language%2Fconstant_expression.html new file mode 100644 index 00000000..3860cf84 --- /dev/null +++ b/devdocs/c/language%2Fconstant_expression.html @@ -0,0 +1,107 @@ +

Constant expressions

Several varieties of expressions are known as constant expressions

+

Preprocessor constant expression

The expression following #if or #elif must expand to

+

Character constants, when evaluated in #if-expressions, may be interpreted in the source character set, the execution character set, or some other implementation-defined character set.

+ + +

Integer arithmetic in #if-expressions is performed using the semantics of intmax_t for signed types and uintmax_t for unsigned types.

+		 (since C99)

Integer constant expression

An integer constant expression is an expression that consists only of

+ + +
(since C11)
+ +
  • named and compound literal constants that are of integer type or that are of arithmetic type and are the immediate operands of casts
(since C23)

Integer constant expressions are evaluated at compile time. The following contexts require expressions that are known as integer constant expressions:

+ + + + + + +
(since C99)
(since C11)
  • The number of bits N of a bit-precise integer type (_BitInt(N))
(since C23)

Static initializer

Expressions that are used in the initializers of objects with static and thread_local storage duration or declared with the constexpr storage-class specifier(since C23) must be either string literals or expressions that may be one of the following

+
+1) arithmetic constant expression, which is an expression of any arithmetic type that consists of + +
(since C11)
+ +
  • named or compound literal constants of arithmetic type
(since C23)
+
+2) a null pointer constant (e.g. NULL)
+3) address constant expression, which is
+4) address constant expression of some complete object type, plus or minus an integer constant expression +
+ +
5) a named constant which is, an identifier that is
    +
  • an enumeration constant
    • +
  • a predefined constant (one of true, false or nullptr)
    • +
  • declared with storage-class specifier constexpr and has an object type
    • +
or a postfix expression that applies the . member access operator to a named constant of structure or union type, even recursively. 6) a compound literal constant, which is
    +
  • a compound literal with storage-class specifier constexpr
    • +
  • a postfix expression that applies the . member access operator to a compound literal constant of structure or union type, even recursively.
    • +

A structure or union constant is a named constant or compound literal constant with structure or union type, respectively. If the member-access operator . accesses a member of a union constant, the accessed member shall be the same as the member that is initialized by the union constant’s initializer.

+		 (since C23)
+7) constant expression of one of the other forms accepted by the implementation.

Unlike with integer constant expressions, static initializer expressions are not required to be evaluated at compile time; the compiler is at liberty to turn such initializers into executable code which is invoked prior to program startup.

+
static int i = 2 || 1 / 0; // initializes i to value 1

The value of a floating-point static initializer is never less accurate than the value of the same expression executed at run time, but it may be better.

+

Floating-point constant expressions

Arithmetic constant expressions of floating-point types that are not used in static initializers are always evaluated as-if during run-time and are affected by the current rounding (if FENV_ACCESS is on) and report errors as specified in math_errhandling.

+
void f(void)
+{
+#pragma STDC FENV_ACCESS ON
+    static float x = 0.0/0.0; // static initializer: does not raise an exception
+    float w[] = { 0.0/0.0 }; // raises an exception
+    float y = 0.0/0.0; // raises an exception
+    double z = 0.0/0.0; // raises an exception
+}

Notes

If an expression evaluates to a value that is not representable by its type, it cannot be used as a constant expression.

+

Implementations may accept other forms of constant expressions. However, these constant expressions are not considered as integer constant expressions, arithmetic constant expressions, or address constant expressions, and thus cannot be used in the contexts requiring these kinds of constant expressions. For example, int arr[(int)+1.0]; declares a VLA.

+

References

See also

+
C++ documentation for Constant expressions
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/constant_expression +

+
diff --git a/devdocs/c/language%2Fconstexpr.html b/devdocs/c/language%2Fconstexpr.html new file mode 100644 index 00000000..5cffe330 --- /dev/null +++ b/devdocs/c/language%2Fconstexpr.html @@ -0,0 +1,33 @@ +

constexpr specifier (since C23) +

A scalar object declared with the constexpr storage-class specifier is a constant. It must be fully and explicitly initialized according to the static initialization rules. It still has linkage appropriate to its declaration and it exist at runtime to have its address taken; it simply cannot be modified at runtime in any way, i.e. the compiler can use its knowledge of the object’s fixed value in any other constant expression.

+

Additionally, the constant expression that is used for the initializer of such a constant is checked at compile time.

+

An initializer of floating-point type must be evaluated with the translation-time floating-point environment.

+

There are some restrictions on the type of an object that can be declared with constexpr. Namely, the following constructs are not allowed to be constexpr:

+

Keywords

constexpr

+

Notes

Example

#include <fenv.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    constexpr float f = 23.0f;
+    constexpr float g = 33.0f;
+    fesetround(FE_TOWARDZERO);
+    constexpr float h = f / g; // is not affected by fesetround() above
+    printf("%f\n", h);
+}

Output:

+
0.696969

References

See also

+
C++ documentation for constexpr type specifier
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/constexpr +

+
diff --git a/devdocs/c/language%2Fcontinue.html b/devdocs/c/language%2Fcontinue.html new file mode 100644 index 00000000..831fd254 --- /dev/null +++ b/devdocs/c/language%2Fcontinue.html @@ -0,0 +1,61 @@ +

continue statement

Causes the remaining portion of the enclosing for, while or do-while loop body to be skipped.

+

Used when it is otherwise awkward to ignore the remaining portion of the loop using conditional statements.

+

Syntax

+ +
attr-spec-seq(optional) continue ;
+ +
attr-spec-seq - (C23)optional list of attributes, applied to the continue statement

Explanation

The continue statement causes a jump, as if by goto, to the end of the loop body (it may only appear within the loop body of for, while, and do-while loops).

+

For while loop, it acts as

+
while (/* ... */) {
+   // ... 
+   continue; // acts as goto contin;
+   // ... 
+   contin:;
+}

For do-while loop, it acts as:

+
do {
+    // ... 
+    continue; // acts as goto contin;
+    // ... 
+    contin:;
+} while (/* ... */);

For for loop, it acts as:

+
for (/* ... */) {
+    // ... 
+    continue; // acts as goto contin;
+    // ... 
+    contin:;
+}

Keywords

continue

+

Example

#include <stdio.h>
+ 
+int main(void) 
+{
+    for (int i = 0; i < 10; i++) {
+        if (i != 5) continue;
+        printf("%d ", i);             // this statement is skipped each time i != 5
+    }
+ 
+    printf("\n");
+ 
+    for (int j = 0; j < 2; j++) {
+        for (int k = 0; k < 5; k++) { // only this loop is affected by continue
+            if (k == 3) continue;
+            printf("%d%d ", j, k);    // this statement is skipped each time k == 3
+        }
+    }
+}

Output:

+
5
+00 01 02 04 10 11 12 14

References

See also

+
C++ documentation for continue statement
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/continue +

+
diff --git a/devdocs/c/language%2Fconversion.html b/devdocs/c/language%2Fconversion.html new file mode 100644 index 00000000..f9f44d98 --- /dev/null +++ b/devdocs/c/language%2Fconversion.html @@ -0,0 +1,304 @@ +

Implicit conversions

When an expression is used in the context where a value of a different type is expected, conversion may occur:

+
int n = 1L; // expression 1L has type long, int is expected
+n = 2.1; // expression 2.1 has type double, int is expected
+char *p = malloc(10); // expression malloc(10) has type void*, char* is expected

Conversions take place in the following situations:

+

Conversion as if by assignment

Note that actual assignment, in addition to the conversion, also removes extra range and precision from floating-point types and prohibits overlaps; those characteristics do not apply to conversion as if by assignment.

+

Default argument promotions

In a function call expression when the call is made to

+
+1) a function without a prototype (until C23) +
+2) a variadic function, where the argument expression is one of the trailing arguments that are matched against the ellipsis parameter

Each argument of integer type undergoes integer promotion (see below), and each argument of type float is implicitly converted to the type double

+
int add_nums(int count, ...);
+int sum = add_nums(2, 'c', true); // add_nums is called with three ints: (2, 99, 1)
+ +

Note that float complex and float imaginary are not promoted to double complex and double imaginary in this context.

+		 (since C99)

Usual arithmetic conversions

The arguments of the following arithmetic operators undergo implicit conversions for the purpose of obtaining the common real type, which is the type in which the calculation is performed:

+ + +
1) If one operand has decimal floating type, the other operand shall not have standard floating,

complex, or imaginary type.

+
    +
  • First, if the type of either operand is _Decimal128, the other operand is converted to _Decimal128.
    • +
  • Otherwise, if the type of either operand is _Decimal64, the other operand is converted to _Decimal64.
    • +
  • Otherwise, if the type of either operand is _Decimal32, the other operand is converted to _Decimal32.
    • +
 (since C23)
+2) Otherwise, if one operand is long double, long double complex, or long double imaginary (since C99), the other operand is implicitly converted as follows: + +
    +
  • complex type to long double complex
    • +
  • imaginary type to long double imaginary
    • +
 (since C99)
+
+3) Otherwise, if one operand is double, double complex, or double imaginary (since C99), the other operand is implicitly converted as follows: + +
(since C99)
+
+4) Otherwise, if one operand is float, float complex, or float imaginary (since C99), the other operand is implicitly converted as follows: + +
(since C99)
+
+5) Otherwise, both operands are integers. Both operands undergo integer promotions (see below); then, after integer promotion, one of the following cases applies: +
+
1. Refer to "integer promotions" below for the rules on ranking.
+
2. Refer to "integer conversions" under "implicit conversion semantics" below.
+
1.f + 20000001; // int is converted to float, giving 20000000.00
+                // addition and then rounding to float gives 20000000.00
+ 
+(char)'a' + 1L; // first, char 'a', which is 97, is promoted to int
+                // different types: int and long
+                // same signedness: both signed
+                // different rank: long is of greater rank than int
+                // therefore, int 97 is converted to long 97
+                // the result is 97 + 1 = 98 of type signed long
+ 
+2u - 10; // different types: unsigned int and signed int
+         // different signedness
+         // same rank
+         // therefore, signed int 10 is converted to unsigned int 10
+         // since the arithmetic operation is performed for unsigned integers
+         // (see "Arithmetic operators" topic), the calculation performed is (2 - 10)
+         // modulo (2 raised to n), where n is the number of value bits of unsigned int
+         // if unsigned int is 32-bit long and there is no padding bits in its object
+         // representation, then the result is (-8) modulo (2 raised to 32) = 4294967288
+         // of type unsigned int
+ 
+5UL - 2ULL; // different types: unsigned long and unsigned long long
+            // same signedness
+            // different rank: rank of unsigned long long is greater
+            // therefore, unsigned long 5 is converted to unsigned long long 5
+            // since the arithmetic operation is performed for unsigned integers
+            // (see "Arithmetic operators" topic),
+            // if unsigned long long is 64-bit long, then
+            // the result is (5 - 2) modulo (2 raised to 64) = 3 of type
+            // unsigned long long
+ 
+0UL - 1LL; // different types: unsigned long and signed long long
+           // different signedness
+           // different rank: rank of signed long long is greater.
+           // if ULONG_MAX > LLONG_MAX, then signed long long cannot represent all
+           // unsigned long therefore, this is the last case: both operands are converted
+           // to unsigned long long unsigned long 0 is converted to unsigned long long 0
+           // long long 1 is converted to unsigned long long 1 since the arithmetic
+           // operation is performed for unsigned integers
+           // (see "Arithmetic operators" topic),
+           // if unsigned long long is 64-bit long, then  
+           // the calculation is (0 - 1) modulo (2 raised to 64)
+           // thus, the result is 18446744073709551615 (ULLONG_MAX) of type
+           // unsigned long long
+ +

The result type is determined as follows:

+
    +
  • if both operands are complex, the result type is complex
    • +
  • if both operands are imaginary, the result type is imaginary
    • +
  • if both operands are real, the result type is real
    • +
  • if the two floating-point operands have different type domains (complex vs. real, complex vs imaginary, or imaginary vs. real), the result type is complex
    • +
double complex z = 1 + 2*I;
+double f = 3.0;
+z + f; // z remains as-is, f is converted to double, the result is double complex
 (since C99)

As always, the result of a floating-point operator may have greater range and precision than is indicated by its type (see FLT_EVAL_METHOD).

+ + +

Note: real and imaginary operands are not implicitly converted to complex because doing so would require extra computation, while producing undesirable results in certain cases involving infinities, NaNs and signed zeros. For example, if reals were converted to complex, 2.0×(3.0+i∞) would evaluate as (2.0+i0.0)×(3.0+i∞) ⇒ (2.0×3.0–0.0×∞) + i(2.0×∞+0.0×3.0) ⇒ NaN+i∞ rather than the correct 6.0+i∞. If imaginaries were converted to complex, i2.0×(∞+i3.0) would evaluate as (0.0+i2.0) × (∞+i3.0) ⇒ (0.0×∞ – 2.0×3.0) + i(0.0×3.0 + 2.0×∞) ⇒ NaN + i∞ instead of –6.0 + i∞.

+		 (since C99)

Note: regardless of usual arithmetic conversions, the calculation may always be performed in a narrower type than specified by these rules under the as-if rule

+

Value transformations

Lvalue conversion

Any lvalue expression of any non-array type, when used in any context other than

+

undergoes lvalue conversion: the type remains the same, but loses const/volatile/restrict-qualifiers and atomic properties, if any. The value remains the same, but loses its lvalue properties (the address may no longer be taken).

+

If the lvalue has incomplete type, the behavior is undefined.

+

If the lvalue designates an object of automatic storage duration whose address was never taken and if that object was uninitialized (not declared with an initializer and no assignment to it has been performed prior to use), the behavior is undefined.

+

This conversion models the memory load of the value of the object from its location.

+
volatile int n = 1;
+int x = n;            // lvalue conversion on n reads the value of n
+volatile int* p = &n; // no lvalue conversion: does not read the value of n

Array to pointer conversion

Any lvalue expression of array type, when used in any context other than

+

undergoes a conversion to the non-lvalue pointer to its first element.

+

If the array was declared register, the behavior is undefined.

+
int a[3], b[3][4];
+int* p = a;      // conversion to &a[0]
+int (*q)[4] = b; // conversion to &b[0]

Function to pointer conversion

Any function designator expression, when used in any context other than

+

undergoes a conversion to the non-lvalue pointer to the function designated by the expression.

+
int f(int);
+int (*p)(int) = f; // conversion to &f
+(***p)(1); // repeated dereference to f and conversion back to &f

Implicit conversion semantics

Implicit conversion, whether as if by assignment or a usual arithmetic conversion, consists of two stages:

+
+1) value transformation (if applicable)
+2) one of the conversions listed below (if it can produce the target type)

Compatible types

Conversion of a value of any type to any compatible type is always a no-op and does not change the representation.

+
uint8_t (*a)[10];         // if uint8_t is a typedef to unsigned char
+unsigned char (*b)[] = a; // then these pointer types are compatible

Integer promotions

Integer promotion is the implicit conversion of a value of any integer type with rank less or equal to rank of int or of a bit-field of type _Bool(until C23)bool(since C23), int, signed int, unsigned int, to the value of type int or unsigned int.

+

If int can represent the entire range of values of the original type (or the range of values of the original bit-field), the value is converted to type int. Otherwise the value is converted to unsigned int.

+ + +

The value from a bit-field of a bit-precise integer type is converted to the corresponding bit-precise integer type. Otherwise, bit-precise integer types are exempt from the integer promotion rules.

+		 (since C23)

Integer promotions preserve the value, including the sign:

+
int main(void)
+{
+    void f(); // old-style function declaration
+              // since C23, void f(...) has the same behavior wrt promotions
+    char x = 'a'; // integer conversion from int to char
+    f(x); // integer promotion from char back to int
+}
+ 
+void f(x) int x; {} // the function expects int

rank above is a property of every integer type and is defined as follows:

+
+1) the ranks of all signed integer types are different and increase with their precision: rank of signed char < rank of short < rank of int < rank of long int < rank of long long int +
+2) the ranks of all signed integer types equal the ranks of the corresponding unsigned integer types
+3) the rank of any standard integer type is greater than the rank of any extended integer type or bit-precise integer type(since C23) of the same size (that is, rank of __int64 < rank of long long int, but rank of long long < rank of __int128 due to the rule (1))
+4) rank of char equals rank of signed char and rank of unsigned char +
+5) the rank of _Bool(until C23)bool(since C23) is less than the rank of any other standard integer type
+6) the rank of any enumerated type equals the rank of its compatible integer type
+7) ranking is transitive: if rank of T1 < rank of T2 and rank of T2 < rank of T3 then rank of T1 < rank of T3
+ +
8) the rank of a bit-precise signed integer type shall be greater than the rank of any standard integer type with less width or any bit-precise integer type with less width. 9) the rank of any bit-precise integer type relative to an extended integer type of the same width is implementation-defined. (since C23)
+10) any aspects of relative ranking of extended integer types not covered above are implementation defined.

Note: integer promotions are applied only

+ + +

Boolean conversion

A value of any scalar type can be implicitly converted to _Bool(until C23)bool(since C23). The values that compare equal to an integer constant expression of value zero(until C23)are a zero (for arithmetic types), null (for pointer types) or have a type of nullptr_t(since C23) are converted to ​0​(until C23)false(since C23), all other values are converted to 1(until C23)true(since C23).

+
bool b1 = 0.5;              // b1 == 1 (0.5 converted to int would be zero)
+bool b2 = 2.0*_Imaginary_I; // b2 == 1 (but converted to int would be zero)
+bool b3 = 0.0 + 3.0*I;      // b3 == 1 (but converted to int would be zero)
+bool b4 = 0.0/0.0;          // b4 == 1 (NaN does not compare equal to zero)
+bool b5 = nullptr;          // b5 == 0 (since C23: nullptr is converted to false)
 (since C99)

Integer conversions

A value of any integer type can be implicitly converted to any other integer type. Except where covered by promotions and boolean conversions above, the rules are:

+ 
char x = 'a'; // int -> char, result unchanged
+unsigned char n = -123456; // target is unsigned, result is 192 (that is, -123456+483*256)
+signed char m = 123456;    // target is signed, result is implementation-defined
+assert(sizeof(int) > -1);  // assert fails:
+                           // operator > requests conversion of -1 to size_t,
+                           // target is unsigned, result is SIZE_MAX

Real floating-integer conversions

A finite value of any real floating type can be implicitly converted to any integer type. Except where covered by boolean conversion above, the rules are:

+ 
int n = 3.14; // n == 3
+int x = 1e10; // undefined behavior for 32-bit int

A value of any integer type can be implicitly converted to any real floating type.

+

The result of this conversion may have greater range and precision than its target type indicates (see FLT_EVAL_METHOD).

+

If control over FE_INEXACT is needed in floating-to-integer conversions, rint and nearbyint may be used.

+
double d = 10; // d = 10.00
+float f = 20000001; // f = 20000000.00 (FE_INEXACT)
+float x = 1+(long long)FLT_MAX; // undefined behavior

Real floating point conversions

A value of any real floating type can be implicitly converted to any other real floating type.

+

The result of this conversion may have greater range and precision than its target type indicates (see FLT_EVAL_METHOD).

+
double d = 0.1; // d = 0.1000000000000000055511151231257827021181583404541015625
+float f = d;    // f = 0.100000001490116119384765625
+float x = 2*(double)FLT_MAX; // undefined
+ +

Complex type conversions

A value of any complex type can be implicitly converted to any other complex type. The real part and the imaginary part individually follow the conversion rules for the real floating types.

+
double complex d = 0.1 + 0.1*I;
+float complex f = d; // f is (0.100000001490116119384765625, 0.100000001490116119384765625)

Imaginary type conversions

A value of any imaginary type can be implicitly converted to any other imaginary type. The imaginary part follows the conversion rules for the real floating types.

+
double imaginary d = 0.1*_Imaginary_I;
+float imaginary f = d; // f is 0.100000001490116119384765625*I

Real-complex conversions

A value of any real floating type can be implicitly converted to any complex type.

+
    +
  • The real part of the result is determined by the conversion rules for the real floating types
    • +
  • The imaginary part of the result is positive zero (or unsigned zero on non-IEEE systems)
    • +

A value of any complex type can be implicitly converted to any real floating type

+
    +
  • The real part is converted following the rules for the real floating types
    • +
  • The imaginary part is discarded
    • +

Note: in complex-to-real conversion, a NaN in the imaginary part will not propagate to the real result.

+
double complex z = 0.5 + 3*I;
+float f = z;  // the imaginary part is discarded, f is set to 0.5
+z = f;        // sets z to 0.5 + 0*I

Real-imaginary conversions

A value of any imaginary type can be implicitly converted to any real type (integer or floating-point). The result is always a positive (or unsigned) zero, except when the target type is _Bool(until C23)bool(since C23), in which case boolean conversion rules apply.

+

A value of any real type can be implicitly converted to any imaginary type. The result is always a positive imaginary zero.

+
double imaginary z = 3*I;
+bool b = z;  // Boolean conversion: sets b to true 
+float f = z; // Real-imaginary conversion: sets f to 0.0 
+z = 3.14;    // Imaginary-real conversion: sets z to 0*_Imaginary_I

Complex-imaginary conversions

A value of any imaginary type can be implicitly converted to any complex type.

+
    +
  • The real part of the result is the positive zero
    • +
  • The imaginary part of the result follows the conversion rules for the corresponding real types
    • +

A value of any complex type can be implicitly converted to any imaginary type

+
    +
  • The real part is discarded
    • +
  • The imaginary part of the result follows the conversion rules for the corresponding real types
    • +
double imaginary z = I * (3*I); // the complex result -3.0+0i loses real part
+                                // sets z to 0*_Imaginary_I
 (since C99)

Pointer conversions

A pointer to void can be implicitly converted to and from any pointer to object type with the following semantics:

+ 
int* p = malloc(10 * sizeof(int)); // malloc returns void*

A pointer to an unqualified type may be implicitly converted to the pointer to qualified version of that type (in other words, const, volatile, and restrict qualifiers can be added). The original pointer and the result compare equal.

+
int n;
+const int* p = &n; // &n has type int*

Any integer constant expression with value ​0​ as well as integer pointer expression with value zero cast to the type void* can be implicitly converted to any pointer type (both pointer to object and pointer to function). The result is the null pointer value of its type, guaranteed to compare unequal to any non-null pointer value of that type. This integer or void* expression is known as null pointer constant and the standard library provides one definition of this constant as the macro NULL.

+
int* p = 0;
+double* q = NULL;

Notes

Although signed integer overflow in any arithmetic operator is undefined behavior, overflowing a signed integer type in an integer conversion is merely unspecified behavior.

+

On the other hand, although unsigned integer overflow in any arithmetic operator (and in integer conversion) is a well-defined operation and follows the rules of modulo arithmetic, overflowing an unsigned integer in a floating-to-integer conversion is undefined behavior: the values of real floating type that can be converted to unsigned integer are the values from the open interval (-1; Unnn_MAX+1).

+
unsigned int n = -1.0; // undefined behavior

Conversions between pointers and integers (except from pointer to _Bool(until C23)bool(since C23) and (since C99)from integer constant expression with the value zero to pointer), between pointers to objects (except where either to or from is a pointer to void) and conversions between pointers to functions (except when the functions have compatible types) are never implicit and require a cast operator.

+

There are no conversions (implicit or explicit) between pointers to functions and pointers to objects (including void*) or integers.

+

References

See also

+
C++ documentation for Implicit conversions
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/conversion +

+
diff --git a/devdocs/c/language%2Fdeclarations.html b/devdocs/c/language%2Fdeclarations.html new file mode 100644 index 00000000..f08779ae --- /dev/null +++ b/devdocs/c/language%2Fdeclarations.html @@ -0,0 +1,142 @@ +

Declarations

A declaration is a C language construct that introduces one or more identifiers into the program and specifies their meaning and properties.

+

Declarations may appear in any scope. Each declaration ends with a semicolon (just like a statement) and consists of two(until C23)three(since C23) distinct parts:

+ + + + +
specifiers-and-qualifiers declarators-and-initializers(optional) ; (1)
attr-spec-seq specifiers-and-qualifiers declarators-and-initializers ; (2) (since C23)
attr-spec-seq ; (3) (since C23)

where

+ + + + +
specifiers-and-qualifiers - whitespace-separated list of, in any order,
declarators-and-initializers - comma-separated list of declarators (each declarator provides additional type information and/or the identifier to declare). Declarators may be accompanied by initializers. The enum, struct, and union declarations may omit declarators, in which case they only introduce the enumeration constants and/or tags.
attr-spec-seq - (C23)optional list of attributes, applied to the declared entities, or forms an attribute declaration if appears alone.
+1-2) Simple declaration. Introduces one or more identifiers which denotes objects, functions, struct/union/enum tags, typedefs, or enumeration constants.
+3) Attribute declaration. Does not declares any identifier, and has implementation-defined meaning if the meaning is not specified by the standard.

For example,

+
int a, *b=NULL; // "int" is the type specifier,
+                // "a" is a declarator
+                // "*b" is a declarator and NULL is its initializer
+const int *f(void); // "int" is the type specifier
+                    // "const" is the type qualifier
+                    // "*f(void)" is the declarator
+enum COLOR {RED, GREEN, BLUE} c; // "enum COLOR {RED, GREEN, BLUE}" is the type specifier
+                                 // "c" is the declarator

The type of each identifier introduced in a declaration is determined by a combination of the type specified by the type specifier and the type modifications applied by its declarator. The type of a variable might also be inferred if auto specifier is used.(since C23)

+

Attributes(since C23) may appear in specifiers-and-qualifiers, in which case they apply to the type determined by the preceding specifiers.

+

Declarators

Each declarator is one of the following:

+ + + + + + +
identifier attr-spec-seq(optional) (1)
( declarator ) (2)
* attr-spec-seq(optional) qualifiers(optional) declarator (3)
noptr-declarator [ static(optional) qualifiers(optional) expression ]

noptr-declarator [ qualifiers(optional) * ]

+		 (4)
noptr-declarator ( parameters-or-identifiers ) (5)
+1) the identifier that this declarator introduces.
+2) any declarator may be enclosed in parentheses; this is required to introduce pointers to arrays and pointers to functions.
+3) pointer declarator: the declaration S * cvr D; declares D as a cvr-qualified pointer to the type determined by S.
+4) array declarator: the declaration S D[N] declares D as an array of N objects of the type determined by S. noptr-declarator is any other declarator except unparenthesized pointer declarator.
+5) function declarator: the declaration S D(params) declared D as a function taking the parameters params and returning S. noptr-declarator is any other declarator except unparenthesized pointer declarator.

The reasoning behind this syntax is that when the identifier declared by the declarator appears in an expression of the same form as the declarator, it would have the type specified by the type specifier sequence.

+
struct C {
+    int member; // "int" is the type specifier 
+                // "member" is the declarator
+} obj, *pObj = &obj;
+// "struct C { int member; }" is the type specifier
+// declarator "obj" defines an object of type struct C
+// declarator "*pObj" declares a pointer to C,
+// initializer "= &obj" provides the initial value for that pointer
+ 
+int a = 1, *p = NULL, f(void), (*pf)(double);
+// the type specifier is "int"
+// declarator "a" defines an object of type int
+//   initializer "=1" provides its initial value
+// declarator "*p" defines an object of type pointer to int
+//   initializer "=NULL" provides its initial value
+// declarator "f(void)" declares a function taking void and returning int
+// declarator "(*pf)(double)" defines an object of type pointer
+//   to function taking double and returning int
+ 
+int (*(*foo)(double))[3] = NULL;
+// the type specifier is int
+// 1. declarator "(*(*foo)(double))[3]" is an array declarator:
+//    the type declared is "/nested declarator/ array of 3 int"
+// 2. the nested declarator is "*(*foo)(double))", which is a pointer declarator
+//    the type declared is "/nested declarator/ pointer to array of 3 int"
+// 3. the nested declarator is "(*foo)(double)", which is a function declarator
+//    the type declared is "/nested declarator/ function taking double and returning
+//        pointer to array of 3 int"
+// 4. the nested declarator is "(*foo)" which is a (parenthesized, as required by
+//        function declarator syntax) pointer declarator.
+//    the type declared is "/nested declarator/ pointer to function taking double
+//        and returning pointer to array of 3 int"
+// 5. the nested declarator is "foo", which is an identifier.
+// The declaration introduces the identifier "foo" to refer to an object of type
+// "pointer to function taking double and returning pointer to array of 3 int"
+// The initializer "= NULL" provides the initial value of this pointer.
+ 
+// If "foo" is used in an expression of the form of the declarator, its type would be
+// int.
+int x = (*(*foo)(1.2))[0];

The end of every declarator that is not part of another declarator is a sequence point.

+

In all cases, attr-spec-seq is an optional sequence of attributes(since C23). When appearing immediately after the identifier, it applies to the object or function being declared.

+

Definitions

A definition is a declaration that provides all information about the identifiers it declares.

+

Every declaration of an enum or a typedef is a definition.

+

For functions, a declaration that includes the function body is a function definition:

+
int foo(double); // declaration
+int foo(double x){ return x; } // definition

For objects, a declaration that allocates storage (automatic or static, but not extern) is a definition, while a declaration that does not allocate storage (external declaration) is not.

+
extern int n; // declaration
+int n = 10; // definition

For structs and unions, declarations that specify the list of members are definitions:

+
struct X; // declaration
+struct X { int n; }; // definition

Redeclaration

A declaration cannot introduce an identifier if another declaration for the same identifier in the same scope appears earlier, except that

+ 
extern int x;
+int x = 10; // OK
+extern int x; // OK
+ 
+static int n;
+static int n = 10; // OK
+static int n; // OK
typedef int int_t; 
+typedef int int_t; // OK
struct X;
+struct X { int n; };
+struct X;

These rules simplify the use of header files.

+

Notes

+ +

In C89, declarations within any compound statement (block scope) must appear in the beginning of the block, before any statements.

+

Also, in C89, functions returning int may be implicitly declared by the function call operator and function parameters of type int do not have to be declared when using old-style function definitions.

+		 (until C99)

Empty declarators are prohibited; a simple declaration must have at least one declarator or declare at least one struct/union/enum tag, or introduce at least one enumeration constant.

+ + +

If any part of a declarator is a variable-length array (VLA) declarator, the entire declarator's type is known as "variably-modified type". Types defined from variably-modified types are also variably modified (VM).

+

Declarations of any variably-modified types may appear only at block scope or function prototype scope and cannot be members of structs or unions. Although VLA can only have automatic or allocated storage duration, a VM type such as a pointer to a VLA may be static. There are other restrictions on the use of VM types, see goto, switch. longjmp

+		 (since C99)
+ +

static_asserts are considered to be declarations from the point of view of the C grammar (so that they may appear anywhere a declaration may appear), but they do not introduce any identifiers and do not follow the declaration syntax.

+		 (since C11)
+ +

Attribute declarations are also considered to be declarations (so that they may appear anywhere a declaration may appear), but they do not introduce any identifiers. A single ; without attr-spec-seq is not an attribute declaration, but a statement.

+		 (since C23)

References

See also

+
C++ documentation for Declarations
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/declarations +

+
diff --git a/devdocs/c/language%2Fdo.html b/devdocs/c/language%2Fdo.html new file mode 100644 index 00000000..226bcf7c --- /dev/null +++ b/devdocs/c/language%2Fdo.html @@ -0,0 +1,61 @@ +

do-while loop

Executes a statement repeatedly until the value of the condition expression becomes false. The test takes place after each iteration.

+

Syntax

+ +
attr-spec-seq(optional) do statement while ( expression ) ;
+ + + +
expression - any expression of scalar type. This expression is evaluated after each iteration, and if it compares equal to zero, the loop is exited.
statement - any statement, typically a compound statement, which is the body of the loop
attr-spec-seq - (C23)optional list of attributes, applied to the loop statement

Explanation

A do-while statement causes the statement (also called the loop body) to be executed repeatedly until the expression (also called controlling expression) compares equal to 0. The repetition occurs regardless of whether the loop body is entered normally or by a goto into the middle of statement.

+

The evaluation of expression takes place after each execution of statement (whether entered normally or by a goto). If the controlling expression needs to be evaluated before the loop body, the while loop or the for loop may be used.

+

If the execution of the loop needs to be terminated at some point, break statement can be used as terminating statement.

+

If the execution of the loop needs to be continued at the end of the loop body, continue statement can be used as a shortcut.

+

A program with an endless loop has undefined behavior if the loop has no observable behavior (I/O, volatile accesses, atomic or synchronization operation) in any part of its statement or expression. This allows the compilers to optimize out all unobservable loops without proving that they terminate. The only exceptions are the loops where expression is a constant expression; do {...} while(true); is always an endless loop.

+ + +

As with all other selection and iteration statements, the do-while statement establishes block scope: any identifier introduced in the expression goes out of scope after the statement.

+		 (since C99)

Notes

Boolean and pointer expressions are often used as loop controlling expressions. The boolean value false and the null pointer value of any pointer type compare equal to zero.

+

Keywords

do, while

+

Example

#include <stdio.h>
+#include <stdlib.h>
+enum { SIZE = 8 };
+int main(void)
+{
+    // trivial example
+    int array[SIZE], n = 0;
+    do array[n++] = rand() % 2; // the loop body is a single expression statement
+    while(n < SIZE);
+    puts("Array filled!");
+    n = 0;
+    do { // the loop body is a compound statement
+        printf("%d ", array[n]);
+        ++n;
+    } while (n < SIZE);
+    printf("\n");
+ 
+    // the loop from K&R itoa(). The do-while loop is used
+    // because there is always at least one digit to generate
+    int num = 1234, i=0;
+    char s[10];
+    do s[i++] = num % 10 + '0'; // get next digit in reverse order
+    while ((num /= 10) > 0);
+    s[i] = '\0';
+    puts(s);
+}

Possible output:

+
Array filled!
+1 0 1 1 1 1 0 0
+4321

References

See also

+
C++ documentation for do-while loop
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/do +

+
diff --git a/devdocs/c/language%2Fenum.html b/devdocs/c/language%2Fenum.html new file mode 100644 index 00000000..f472e47a --- /dev/null +++ b/devdocs/c/language%2Fenum.html @@ -0,0 +1,140 @@ +

Enumerations

An enumerated type is a distinct type whose value is a value of its underlying type (see below), which includes the values of explicitly named constants (enumeration constants).

+

Syntax

Enumerated type is declared using the following enumeration specifier as the type-specifier in the declaration grammar:

+ + + +
enum attr-spec-seq (optional) identifier (optional) { enumerator-list } (1)
enum attr-spec-seq (optional) identifier (optional) : type { enumerator-list } (2) (since C23)
+1) Declares an enumeration without a fixed underlying type.
+2) Declares an enumeration of fixed underlying type type.

where enumerator-list is a comma-separated list(with trailing comma permitted)(since C99) of enumerator, each of which has the form:

+ + + +
enumeration-constant attr-spec-seq (optional) (1)
enumeration-constant attr-spec-seq (optional) = constant-expression (2)

where

+ + + + +
identifier, enumeration-constant - identifiers that are introduced by this declaration
constant-expression - integer constant expression whose value is representable as a value of type int(until C23). If the enumeration has a fixed underlying type, representable as a value of type(since C23)
attr-spec-seq - (C23)optional list of attributes,
    +
  • applied to the whole enumeration if appears after enum,
    • +
  • applied to the enumerator if appears after enumeration-constant
    • +

As with struct or union, a declaration that introduced an enumerated type and one or more enumeration constants may also declare one or more objects of that type or type derived from it.

+
enum color { RED, GREEN, BLUE } c = RED, *cp = &c;
+// introduces the type enum color
+// the integer constants RED, GREEN, BLUE
+// the object c of type enum color
+// the object cp of type pointer to enum color

Explanation

Each enumeration-constant that appears in the body of an enumeration specifier becomes an integer constant with type int(until C23) in the enclosing scope and can be used whenever integer constants are required (e.g. as a case label or as a non-VLA array size).

+ + +

During the processing of each enumeration constant in the enumerator list, the type of the enumeration constant shall be:

+
    +
  • the previously declared type, if it is a redeclaration of the same enumeration constant; or,
    • +
  • the enumerated type, for an enumeration with fixed underlying type; or,
    • +
  • int, if there are no previous enumeration constants in the enumerator list and no explicit = with a defining integer constant expression; or,
    • +
  • int, if given explicitly with = and the value of the integer constant expression is representable by an int; or,
    • +
  • the type of the integer constant expression, if given explicitly with = and if the value of the integer constant expression is not representable by int; or,
    • +
  • the type of the value from last enumeration constant with 1 added to it. If such an integer constant expression would overflow or wraparound the value of the previous enumeration constant from the addition of 1, the type takes on either:
      +
    • a suitably sized signed integer type (excluding the bit-precise signed integer types) capable of representing the value of the previous enumeration constant plus 1; or,
      • +
    • a suitably sized unsigned integer type (excluding the bit-precise unsigned integer types) capable of representing the value of the previous enumeration constant plus 1.
      • +
    • +

A signed integer type is chosen if the previous enumeration constant being added is of signed integer type. An unsigned integer type is chosen if the previous enumeration constant is of unsigned integer type. If there is no suitably sized integer type described previous which can represent the new value, then the enumeration has no type which is capable of representing all of its values.

+		 (since C23)
enum color { RED, GREEN, BLUE } r = RED;
+switch(r)
+{
+case RED:
+    puts("red");
+    break;
+case GREEN:
+    puts("green");
+    break;
+case BLUE:
+    puts("blue");
+    break;
+}

If enumeration-constant is followed by = constant-expression, its value is the value of that constant expression. If enumeration-constant is not followed by = constant-expression, its value is the value one greater than the value of the previous enumerator in the same enumeration. The value of the first enumerator (if it does not use = constant-expression) is zero.

+
enum Foo { A, B, C = 10, D, E = 1, F, G = F + C };
+// A=0, B=1, C=10, D=11, E=1, F=2, G=12

The identifier itself, if used, becomes the name of the enumerated type in the tags name space and requires the use of the keyword enum (unless typedef'd into the ordinary name space).

+
enum color { RED, GREEN, BLUE };
+enum color r = RED; // OK
+// color x = GREEN: // Error: color is not in ordinary name space
+typedef enum color color_t;
+color_t x = GREEN; // OK

Each enumerated type without a fixed underlying type(since C23) is compatible with one of: char, a signed integer type, or an unsigned integer type (excluding bool and the bit-precise integer types)(since C23). It is implementation-defined which type is compatible with any given enumerated type, but whatever it is, it must be capable of representing all enumerator values of that enumeration. For all enumerations with a fixed underlying type, the enumerated type is compatible with the underlying type of the enumeration.(since C23)

+ + + + +

The enumeration member type for an enumerated type without fixed underlying type upon completion is:

+
    +
  • int if all the values of the enumeration are representable as an int; or,
    • +
  • the enumerated type.
    • +
 (since C23)
All enumerations have an underlying type. The underlying type can be explicitly specified using an enum-type-specifier and is its fixed underlying type. If it is not explicitly specified, the underlying type is the enumeration’s compatible type, which is either a signed or unsigned integer type, or char. (since C23)

Enumerated types are integer types, and as such can be used anywhere other integer types can, including in implicit conversions and arithmetic operators.

+
enum { ONE = 1, TWO } e;
+long n = ONE; // promotion
+double d = ONE; // conversion
+e = 1.2; // conversion, e is now ONE
+e = e + 1; // e is now TWO

Notes

Unlike struct or union, there are no forward-declared enums in C:

+
enum Color; // Error: no forward-declarations for enums in C
+enum Color { RED, GREEN, BLUE };

Enumerations permit the declaration of named constants in a more convenient and structured fashion than does #define; they are visible in the debugger, obey scope rules, and participate in the type system.

+
#define TEN 10
+struct S { int x : TEN; }; // OK

or

+
enum { TEN = 10 };
+struct S { int x : TEN; }; // also OK

Since C23 constexpr can be used for the same purpose:

+
constexpr int TEN = 10;
+struct S { int x : TEN; }; // also OK

Moreover, as a struct or union does not establish its scope in C, an enumeration type and its enumeration constants may be introduced in the member specification of the former, and their scope is the same as of the former, afterwards.

+
struct Element
+{
+    int z;
+    enum State { SOLID, LIQUID, GAS, PLASMA } state;
+} oxygen = { 8, GAS };
+ 
+// type enum State and its enumeration constants stay visible here, e.g.
+void foo(void)
+{
+    enum State e = LIQUID; // OK
+    printf("%d %d %d ", e, oxygen.state, PLASMA); // prints 1 2 3
+}

Example

#include <stdio.h>
+ 
+int main(void)
+{
+    enum TV { FOX = 11, CNN = 25, ESPN = 15, HBO = 22, MAX = 30, NBC = 32 };
+ 
+    printf("List of cable stations:\n");
+    printf(" FOX: \t%2d\n", FOX);
+    printf(" HBO: \t%2d\n", HBO);
+    printf(" MAX: \t%2d\n", MAX);
+}

Output:

+
List of cable stations:
+ FOX:   11
+ HBO:   22
+ MAX:   30

References

Keywords

enum

+

See also

+
C++ documentation for enumeration declaration
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/enum +

+
diff --git a/devdocs/c/language%2Fescape.html b/devdocs/c/language%2Fescape.html new file mode 100644 index 00000000..84167c53 --- /dev/null +++ b/devdocs/c/language%2Fescape.html @@ -0,0 +1,82 @@ +

Escape sequences

Escape sequences are used to represent certain special characters within string literals and character constants.

+

The following escape sequences are available. ISO C requires a diagnostic if the backslash is followed by any character not listed here:

+ + + + + + + + + + + + + + + + + + + + +
Escape
sequence 		Description Representation
Simple escape sequences
\' single quote byte 0x27 in ASCII encoding
\" double quote byte 0x22 in ASCII encoding
\? question mark byte 0x3f in ASCII encoding
\\ backslash byte 0x5c in ASCII encoding
\a audible bell byte 0x07 in ASCII encoding
\b backspace byte 0x08 in ASCII encoding
\f form feed - new page byte 0x0c in ASCII encoding
\n line feed - new line byte 0x0a in ASCII encoding
\r carriage return byte 0x0d in ASCII encoding
\t horizontal tab byte 0x09 in ASCII encoding
\v vertical tab byte 0x0b in ASCII encoding
Numeric escape sequences
\nnn arbitrary octal value code unit nnn
\xn... arbitrary hexadecimal value code unit n... (arbitrary number of hexadecimal digits)
Universal character names
\unnnn (since C99) Unicode value in allowed range;
may result in several code units 		code point U+nnnn
\Unnnnnnnn (since C99) Unicode value in allowed range;
may result in several code units 		code point U+nnnnnnnn
+ +

Range of universal character names

If a universal character name corresponds to a code point that is not 0x24 ('$'), 0x40 ('@'), nor 0x60 ('`') and less than 0xA0, or a surrogate code point (the range 0xD800-0xDFFF, inclusive), or greater than 0x10FFFF, i.e. not a Unicode code point(since C23), the program is ill-formed. In other words, members of basic source character set and control characters (in ranges 0x0-0x1F and 0x7F-0x9F) cannot be expressed in universal character names.

+		 (since C99)

Notes

\0 is the most commonly used octal escape sequence, because it represents the terminating null character in null-terminated strings.

+

The new-line character \n has special meaning when used in text mode I/O: it is converted to the OS-specific newline byte or byte sequence.

+

Octal escape sequences have a length limit of three octal digits but terminate at the first character that is not a valid octal digit if encountered sooner.

+

Hexadecimal escape sequences have no length limit and terminate at the first character that is not a valid hexadecimal digit. If the value represented by a single hexadecimal escape sequence does not fit the range of values represented by the character type used in this string literal or character constant (char, char8_t(since C23), char16_t, char32_t(since C11), or wchar_t), the result is unspecified.

+ + +

A universal character name in a narrow string literal or a 16-bit string literal(since C11) may map to more than one code unit, e.g. \U0001f34c is 4 char code units in UTF-8 (\xF0\x9F\x8D\x8C) and 2 char16_t code units in UTF-16 (\xD83C\xDF4C)(since C11).

+		 (since C99)
+ +

A universal character name corresponding to a code pointer greater than 0x10FFFF (which is undefined in ISO/ISC 10646) can be used in character constants and string literals. Such usage is not allowed in C++20.

+		 +(since C99)
(until C23) +
+ +

The question mark escape sequence \? is used to prevent trigraphs from being interpreted inside string literals: a string such as "??/" is compiled as "\", but if the second question mark is escaped, as in "?\?/", it becomes "??/"

+		 (until C23)

Example

#include <stdio.h>
+ 
+int main(void)
+{
+    printf("This\nis\na\ntest\n\nShe said, \"How are you?\"\n");
+}

Output:

+
This
+is
+a
+test
+ 
+She said, "How are you?"

References

See also

+
C++ documentation for Escape sequences
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/escape +

+
diff --git a/devdocs/c/language%2Feval_order.html b/devdocs/c/language%2Feval_order.html new file mode 100644 index 00000000..8b1ef82e --- /dev/null +++ b/devdocs/c/language%2Feval_order.html @@ -0,0 +1,43 @@ +

Order of evaluation

Order of evaluation of the operands of any C operator, including the order of evaluation of function arguments in a function-call expression, and the order of evaluation of the subexpressions within any expression is unspecified (except where noted below). The compiler will evaluate them in any order, and may choose another order when the same expression is evaluated again.

+

There is no concept of left-to-right or right-to-left evaluation in C, which is not to be confused with left-to-right and right-to-left associativity of operators: the expression f1() + f2() + f3() is parsed as (f1() + f2()) + f3() due to left-to-right associativity of operator+, but the function call to f3 may be evaluated first, last, or between f1() or f2() at run time.

+

Definitions

Evaluations

There are two kinds of evaluations performed by the compiler for each expression or subexpression (both of which are optional):

+

If no side effects are produced by an expression and the compiler can determine that the value is not used, the expression may not be evaluated.

+

Ordering

"sequenced-before" is an asymmetric, transitive, pair-wise relationship between evaluations within the same thread (it may extend across threads if atomic types and memory barriers are involved).

+ + +
    +
  • If evaluation A is sequenced before evaluation B, then evaluation of A will be complete before evaluation of B begins.
    • +
  • If A is not sequenced before B and B is sequenced before A, then evaluation of B will be complete before evaluation of A begins.
    • +
  • If A is not sequenced before B and B is not sequenced before A, then two possibilities exist:
      +
    • evaluations of A and B are unsequenced: they may be performed in any order and may overlap (within a single thread of execution, the compiler may interleave the CPU instructions that comprise A and B)
      • +
    • evaluations of A and B are indeterminably-sequenced: they may be performed in any order but may not overlap: either A will be complete before B, or B will be complete before A. The order may be the opposite the next time the same expression is evaluated.
      • +
    • +
 (since C11)

Rules

+1) There is a sequence point after the evaluation of all function arguments and of the function designator, and before the actual function call.
+2) There is a sequence point after evaluation of the first (left) operand and before evaluation of the second (right) operand of the following binary operators: && (logical AND), || (logical OR), and , (comma).
+3) There is a sequence point after evaluation of the first (left) operand and before evaluation of the second or third operand (whichever is evaluated) of the conditional operator ?: +
+4) There is a sequence point after the evaluation of a full expression (an expression that is not a subexpression: typically something that ends with a semicolon or a controlling statement of if/switch/while/do) and before the next full expression.
+ + + +
5) There is a sequence point at the end of a full declarator. 6) There is a sequence point immediately before the return of a library function. 7) There is a sequence point after the action associated with each conversion specifier in formatted I/O (in particular, it is well-formed for scanf to write different fields into the same variable and for printf to read and modify or modify the same variable more than once using %n) 8) There are sequence points before and immediately after each call to a comparison function made by the library functions qsort and bsearch, as well as between any call to the comparison function and the movement of the associated objects made by qsort (since C99)
9) The value computations (but not the side-effects) of the operands to any operator are sequenced before the value computation of the result of the operator (but not its side-effects). 10) The side effect (modification of the left argument) of the direct assignment operator and of all compound assignment operators is sequenced after the value computation (but not the side effects) of both left and right arguments. 11) The value computation of the postincrement and postdecrement operators is sequenced before its side-effect. 12) A function call that is not sequenced before or sequenced after another function call is indeterminately sequenced (CPU instructions that constitute different function calls cannot be interleaved, even if the functions are inlined) 13) In initialization list expressions, all evaluations are indeterminately sequenced 14) With respect to an indeterminately-sequenced function call, the operation of compound assignment operators, and both prefix and postfix forms of increment and decrement operators are single evaluations. (since C11)

Undefined behavior

+1) If a side effect on a scalar object is unsequenced relative to another side effect on the same scalar object, the behavior is undefined. 
i = ++i + i++; // undefined behavior
+i = i++ + 1; // undefined behavior
+f(++i, ++i); // undefined behavior
+f(i = -1, i = -1); // undefined behavior
+
+2) If a side effect on a scalar object is unsequenced relative to a value computation using the value of the same scalar object, the behavior is undefined. 
f(i, i++); // undefined behavior
+a[i] = i++; // undefined bevahior
+
+3) The above rules apply as long as at least one allowable ordering of subexpressions permits such an unsequenced side-effect.

See also

Operator precedence which defines how expressions are built from their source code representation.

+ +
C++ documentation for Order of evaluation
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/eval_order +

+
diff --git a/devdocs/c/language%2Fexpressions.html b/devdocs/c/language%2Fexpressions.html new file mode 100644 index 00000000..77504701 --- /dev/null +++ b/devdocs/c/language%2Fexpressions.html @@ -0,0 +1,79 @@ +

Expressions

An expression is a sequence of operators and their operands, that specifies a computation.

+

Expression evaluation may produce a result (e.g., evaluation of 2+2 produces the result 4), may generate side-effects (e.g. evaluation of printf("%d",4) sends the character '4' to the standard output stream), and may designate objects or functions.

+

General

Operators

+ + +
Common operators
assignment increment
decrement 		arithmetic logical comparison member
access 		other

a = b a += b a -= b a *= b a /= b a %= b a &= b a |= b a ^= b a <<= b a >>= b

+

++a --a a++ a--

+

+a -a a + b a - b a * b a / b a % b ~a a & b a | b a ^ b a << b a >> b

+

!a a && b a || b

+

a == b a != b a < b a > b a <= b a >= b

+

a[b] *a &a a->b a.b

+

a(...) a, b (type) a a ? b : c sizeof

_Alignof
(since C11)

+

Conversions

Other

+ +
  • generic selections can execute different expressions depending on the types of the arguments
(since C11)
+ +
(since C99)

Primary expressions

The operands of any operator may be other expressions or they may be primary expressions (e.g. in 1+2*3, the operands of operator+ are the subexpression 2*3 and the primary expression 1).

+

Primary expressions are any of the following:

+
+1) Constants and literals (e.g. 2 or "Hello, world")
+2) Suitably declared identifiers (e.g. n or printf)
+ +
3) Generic selections (since C11)

Any expression in parentheses is also classified as a primary expression: this guarantees that the parentheses have higher precedence than any operator.

+

Constants and literals

Constant values of certain types may be embedded in the source code of a C program using specialized expressions known as literals (for lvalue expressions) and constants (for non-lvalue expressions)

+ + +
(since C23)
+ +
  • compound literals are values of struct, union, or array type directly embedded in program code
(since C99)

Unevaluated expressions

The operands of the sizeof operator are expressions that are not evaluated (unless they are VLAs)(since C99). Thus, size_t n = sizeof(printf("%d", 4)); does not perform console output.

+ + +

The operands of the _Alignof operator, the controlling expression of a generic selection, and size expressions of VLAs that are operands of _Alignof are also expressions that are not evaluated.

+		 (since C11)

References

See also

+
C++ documentation for Expressions
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/expressions +

+
diff --git a/devdocs/c/language%2Fextern.html b/devdocs/c/language%2Fextern.html new file mode 100644 index 00000000..f2fd53ea --- /dev/null +++ b/devdocs/c/language%2Fextern.html @@ -0,0 +1,56 @@ +

External and tentative definitions

At the top level of a translation unit (that is, a source file with all the #includes after the preprocessor), every C program is a sequence of declarations, which declare functions and objects with external or internal linkage. These declarations are known as external declarations because they appear outside of any function.

+
extern int n; // external declaration with external linkage
+int b = 1;    // external definition with external linkage
+static const char *c = "abc"; // external definition with internal linkage
+int f(void) {  // external definition with external linkage
+    int a = 1; // non-external
+    return b; 
+}
+static void x(void) { // external definition with internal linkage
+}

Objects declared with an external declaration have static storage duration, and as such cannot use auto or register specifiers except that auto can be used for type inference(since C23). The identifiers introduced by external declarations have file scope.

+

Tentative definitions

A tentative definition is an external declaration without an initializer, and either without a storage-class specifier or with the specifier static.

+

A tentative definition is a declaration that may or may not act as a definition. If an actual external definition is found earlier or later in the same translation unit, then the tentative definition just acts as a declaration.

+
int i1 = 1;     // definition, external linkage
+int i1;         // tentative definition, acts as declaration because i1 is defined
+extern int i1;  // declaration, refers to the earlier definition
+ 
+extern int i2 = 3; // definition, external linkage
+int i2;            // tentative definition, acts as declaration because i2 is defined
+extern int i2;     // declaration, refers to the external linkage definition

If there are no definitions in the same translation unit, then the tentative definition acts as an actual definition that empty-initializes the object.

+
int i3;        // tentative definition, external linkage
+int i3;        // tentative definition, external linkage
+extern int i3; // declaration, external linkage
+// in this translation unit, i3 is defined as if by "int i3 = 0;"

Unlike the extern declarations, which don't change the linkage of an identifier if a previous declaration established it, tentative definitions may disagree in linkage with another declaration of the same identifier. If two declarations for the same identifier are in scope and have different linkage, the behavior is undefined:

+
static int i4 = 2; // definition, internal linkage
+int i4;            // Undefined behavior: linkage disagreement with previous line
+extern int i4;     // declaration, refers to the internal linkage definition
+ 
+static int i5; // tentative definition, internal linkage
+int i5;        // Undefined behavior: linkage disagreement with previous line
+extern int i5; // refers to previous, whose linkage is internal

A tentative definition with internal linkage must have complete type.

+
static int i[]; // Error, incomplete type in a static tentative definition
+int i[]; // OK, equivalent to int i[1] = {0}; unless redeclared later in this file

One definition rule

Each translation unit may have zero or one external definition of every identifier with internal linkage (a static global).

+

If an identifier with internal linkage is used in any expression other than a non-VLA,(since C99) sizeof, _Alignof(since C11), or typeof(since C23), there must be one and only one external definition for that identifier in the translation unit.

+

The entire program may have zero or one external definition of every identifier with external linkage.

+

If an identifier with external linkage is used in any expression other than a non-VLA,(since C99) sizeof, _Alignof(since C11), or typeof(since C23), there must be one and only one external definition for that identifier somewhere in the entire program.

+

Notes

+ +

Inline definitions in different translation units are not constrained by one definition rule. See inline for the details on the inline function definitions.

+		 (since C99)

See storage duration and linkage for the meaning of the keyword extern with declarations at file scope

+

See definitions for the distinction between declarations and definitions.

+

Tentative definitions were invented to standardize various pre-C89 approaches to forward declaring identifiers with internal linkage.

+

References

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/extern +

+
diff --git a/devdocs/c/language%2Ffile_scope.html b/devdocs/c/language%2Ffile_scope.html new file mode 100644 index 00000000..1e49b1cf --- /dev/null +++ b/devdocs/c/language%2Ffile_scope.html @@ -0,0 +1,27 @@ +

File scope

If the declarator or type specifier that declares the identifier appears outside of any block or list of parameters, the identifier has file scope, which terminates at the end of the translation unit.

+

So, placement of an identifier's declaration (in a declarator or type specifier) outside any block or list of parameters means that the identifier has file scope. File scope of an identifier extends from the declaration to the end of the translation unit in which the declaration appears.

+

Example

+

Identifiers a, b, f, and g have file scope.

+
#include <stdio.h>
+ 
+int a = 1;
+static int b = 2;
+ 
+void f (void) {printf("from function f()\n");}
+static void g (void) {printf("from function g()\n");}
+ 
+int main(void)
+{
+    f();
+    g();
+ 
+    return 0;
+}
+/* end of this translation unit, end of file scope */

Possible output:

+
from function f()
+from function g()
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/file_scope +

+
diff --git a/devdocs/c/language%2Ffloating_constant.html b/devdocs/c/language%2Ffloating_constant.html new file mode 100644 index 00000000..112ca10b --- /dev/null +++ b/devdocs/c/language%2Ffloating_constant.html @@ -0,0 +1,87 @@ +

Floating constant

Allows values of floating type to be used directly in expressions.

+

Syntax

A floating constant is a non-lvalue expression having the form:

+ + +
significand exponent (optional) suffix (optional)

Where the significand has the form

+ + +
whole-number (optional) .(optional) fraction (optional)

The exponent has the form

+ + + +
e | E exponent-sign (optional) digit-sequence (1)
p | P exponent-sign (optional) digit-sequence (2) (since C99)
+1) The exponent syntax for a decimal floating-point constant
+2) The exponent syntax for hexadecimal floating-point constant
+ +

Optional single quotes (') can be inserted between the digits as a separator, they are ignored when compiling.

+		 (since C23)

Explanation

+ +

If the significand begins with the character sequence 0x or 0X, the floating constant is a hexadecimal floating constant. Otherwise, it is a decimal floating constant.

+

For a hexadecimal floating constant, the significand is interpreted as a hexadecimal rational number, and the digit-sequence of the exponent is interpreted as the integer power of 2 to which the significand has to be scaled.

+
double d = 0x1.2p3; // hex fraction 1.2 (decimal 1.125) scaled by 2^3, that is 9.0
 (since C99)

For a decimal floating constant, the significand is interpreted as a decimal rational number, and the digit-sequence of the exponent is interpreted as the integer power of 10 to which the significand has to be scaled.

+
double d = 1.2e3; // decimal fraction 1.2 scaled by 10^3, that is 1200.0

Suffixes

An unsuffixed floating constant has type double. If suffix is the letter f or F, the floating constant has type float. If suffix is the letter l or L, the floating constant has type long double.

+ + +

If the implementation predefines macro __STDC_IEC_60559_BFP__, the following suffixes and corresponding floating constants are additionally supported:

+
    +
  • if suffix is df or DF, the floating constant has type _Decimal32;
    • +
  • if suffix is dd or DD, the floating constant has type _Decimal64;
    • +
  • if suffix is dl or DL, the floating constant has type _Decimal128.
    • +

Suffixes for decimal floating-point types are not allowed in hexadecimal floating constants.

+		 (since C23)

Optional parts

If the exponent is present and fractional part is not used, the decimal separator may be omitted:

+
double x = 1e0; // floating-point 1.0 (period not used)

For decimal floating constants, the exponent part is optional. If it is omitted, the period is not optional, and either the whole-number or the fraction must be present.

+
double x = 1.; // floating-point 1.0 (fractional part optional)
+double y = .1; // floating-point 0.1 (whole-number part optional)
+ +

For hexadecimal floating constants, the exponent is not optional to avoid ambiguity resulting from an f suffix being mistaken as a hexadecimal digit.

+		 (since C99)

Representable values

The result of evaluating a floating constant is either the nearest representable value or the larger or smaller representable value immediately adjacent to the nearest representable value, chosen in an implementation-defined manner (in other words, default rounding direction during translation is implementation-defined).

+

All floating constants of the same source form convert to the same internal format with the same value. Floating constants of different source forms, e.g. 1.23 and 1.230, need not to convert to the same internal format and value.

+ + +

Floating-point constants may convert to more range and precision than is indicated by their type, if indicated by FLT_EVAL_METHOD. For example, the constant 0.1f may act as if it were 0.1L in an expression.

+

The result of evaluating a hexadecimal floating constant, if FLT_RADIX is 2, is the exact value represented by the floating constant, correctly rounded to the target type.

+		 (since C99)
+ +

Floating constants of decimal floating-point type that have the same numerical value \(\small x\)x but different quantum exponents, e.g. 1230.dd, 1230.0dd, and 1.23e3dd, have distinguishable internal representations.

+

The quantum exponent \(\small q\)q of a floating constant of a decimal floating-point type is determined in the manner that \(\small 10^q\)10q represents 1 at the place of last digit of the significand when possible. If the quantum exponent \(\small q\)q and the coefficient \(\small c = x\cdot 10^{-q}\)c=x·10-q determined above cannot represented exactly in the type of the floating constant, \(\small q\)q is increased as needed within the limit of the type, and \(\small c\)c is reduced correspondingly, with needed rounding. The rounding may result in zero or infinity. If (the possibly rounded) \(\small c\)c is still out of the permitted range after \(\small q\)q reaches the maximum value, the resulted floating constant has value positive infinity.

+		 (since C23)

Notes

Default rounding direction and precision are in effect when the floating constants are converted into internal representations, and floating-point exceptions are not raised even if #pragma STDC FENV_ACCESS is in effect (for execution-time conversion of character strings, strtod can be used). Note that this differs from arithmetic constant expressions of floating type.

+

Letters in the floating constants are case-insensitive, except that uppercase and lowercase cannot be both used in suffixes for decimal floating-point types(since C23): 0x1.ep+3 and 0X1.EP+3 represent the same floating-point value 15.0.

+

The decimal point specified by setlocale has no effect on the syntax of floating constants: the decimal point character is always the period.

+

Unlike integers, not every floating value can be represented directly by decimal or even hexadecimal(since C99) constant syntax: macros NAN and INFINITY as well as functions such as nan offer ways to generate those special values(since C99). Note that 0x1.FFFFFEp128f, which might appear to be an IEEE float NaN, in fact overflows to an infinity in that format.

+

There are no negative floating constants; an expression such as -1.2 is the arithmetic operator unary minus applied to the floating constant 1.2. Note that the special value negative zero may be constructed with -0.0.

+

Example

#include <stdio.h>
+ 
+int main(void)
+{
+    printf("15.0     = %a\n", 15.0);
+    printf("0x1.ep+3 = %f\n", 0x1.ep+3);
+ 
+    // Constants outside the range of type double.
+    printf("+2.0e+308 --> %g\n",  2.0e+308);
+    printf("+1.0e-324 --> %g\n",  1.0e-324);
+    printf("-1.0e-324 --> %g\n", -1.0e-324);
+    printf("-2.0e+308 --> %g\n", -2.0e+308);
+}

Output:

+
15.0     = 0x1.ep+3
+0x1.ep+3 = 15.000000
++2.0e+308 --> inf
++1.0e-324 --> 0
+-1.0e-324 --> -0
+-2.0e+308 --> -inf

References

See also

+
C++ documentation for Floating-point literal
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/floating_constant +

+
diff --git a/devdocs/c/language%2Ffor.html b/devdocs/c/language%2Ffor.html new file mode 100644 index 00000000..010d826f --- /dev/null +++ b/devdocs/c/language%2Ffor.html @@ -0,0 +1,63 @@ +

for loop

Executes a loop.

+

Used as a shorter equivalent of while loop.

+

Syntax

+ +
attr-spec-seq(since C23)(optional) for ( init-clause ; cond-expression ; iteration-expression ) loop-statement

Explanation

Behaves as follows:

+ + +
  • An init-clause, which is a declaration, is in scope in the entire loop body, including the remainder of init-clause, the entire cond-expression, the entire iteration-expression and the entire loop-statement. Only auto and register storage class specifiers are allowed for the variables declared in this declaration.
(since C99)

init-clause, cond-expression, and iteration-expression are all optional. If cond-expression is omitted, it is replaced with a non-zero integer constant, which makes the loop endless:

+
for(;;) {
+   printf("endless loop!");
+}

loop-statement is not optional, but it may be a null statement:

+
for(int n = 0; n < 10; ++n, printf("%d\n", n))
+    ; // null statement

If the execution of the loop needs to be terminated at some point, a break statement can be used anywhere within the loop-statement.

+

The continue statement used anywhere within the loop-statement transfers control to iteration-expression.

+

A program with an endless loop has undefined behavior if the loop has no observable behavior (I/O, volatile accesses, atomic or synchronization operation) in any part of its cond-expression, iteration-expression or loop-statement. This allows the compilers to optimize out all unobservable loops without proving that they terminate. The only exceptions are the loops where cond-expression is omitted or is a constant expression; for(;;) is always an endless loop.

+ + +

As with all other selection and iteration statements, the for statement establishes block scope: any identifier introduced in the init-clause, cond-expression, or iteration-expression goes out of scope after the loop-statement.

+		 (since C99)
+ +

attr-spec-seq is an optional list of attributes, applied to the for statement.

+		 (since C23)

Keywords

for

+

Notes

The expression statement used as loop-statement establishes its own block scope, distinct from the scope of init-clause, unlike in C++:

+
for (int i = 0; ; ) {
+    long i = 1;   // valid C, invalid C++
+    // ...
+}

It is possible to enter the body of a loop using goto. When entering a loop in this manner, init-clause and cond-expression are not executed. (If control then reaches the end of the loop body, repetition may occur including execution of cond-expression.)

+

Example

#include <stdio.h>
+#include <stdlib.h>
+enum { SIZE = 8 };
+int main(void)
+{
+    int array[SIZE];
+    for(size_t i = 0 ; i < SIZE; ++i)
+        array [i] = rand() % 2;
+    printf("Array filled!\n");
+    for (size_t i = 0; i < SIZE; ++i)
+        printf("%d ", array[i]);
+    putchar('\n');
+}

Possible output:

+
Array filled!
+1 0 1 1 1 1 0 0

References

See also

+
C++ documentation for for loop
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/for +

+
diff --git a/devdocs/c/language%2Ffunction_declaration.html b/devdocs/c/language%2Ffunction_declaration.html new file mode 100644 index 00000000..af2619d7 --- /dev/null +++ b/devdocs/c/language%2Ffunction_declaration.html @@ -0,0 +1,102 @@ +

Function declarations

A function declaration introduces an identifier that designates a function and, optionally, specifies the types of the function parameters (the prototype). Function declarations (unlike definitions) may appear at block scope as well as file scope.

+

Syntax

In the declaration grammar of a function declaration, the type-specifier sequence, possibly modified by the declarator, designates the return type (which may be any type other than array or function type), and the declarator has one of three forms:

+ + + + +
noptr-declarator ( parameter-list ) attr-spec-seq(optional) (1)
noptr-declarator ( identifier-list ) attr-spec-seq(optional) (2) (until C23)
noptr-declarator ( ) attr-spec-seq(optional) (3)

where

+ + + + + +
noptr-declarator - any declarator except unparenthesized pointer declarator. The identifier that is contained in this declarator is the identifier that becomes the function designator.
parameter-list - either the single keyword void or a comma-separated list of parameters, which may end with an ellipsis parameter
identifier-list - comma-separated list of identifiers, only possible if this declarator is used as part of old-style function definition
attr-spec-seq - (C23)an optional list of attributes, applied to the function type
+1) New-style (C89) function declaration. This declaration both introduces the function designator itself and also serves as a function prototype for any future function call expressions, forcing conversions from argument expressions to the declared parameter types and compile-time checks for the number of arguments. 
int max(int a, int b); // declaration
+int n = max(12.01, 3.14); // OK, conversion from double to int
+
+2) (until C23) Old-style (K&R) function definition. This declaration does not introduce a prototype and any future function call expressions will perform default argument promotions and will invoke undefined behavior if the number of arguments doesn't match the number of parameters. 
int max(a, b) 
+    int a, b; // definition expects ints; the second call is undefined
+{
+    return a > b ? a : b;
+}
+ 
+int n = max(true, (char)'a'); // calls max with two int args (after promotions)
+ 
+int n = max(12.01f, 3.14); // calls max with two double args (after promotions)
+
+3) Non-prototype function declaration. This declaration does not introduce a prototype(until C23). A new style function declaration equivalent to the parameter-list void(since C23).

Explanation

The return type of the function, determined by the type specifier in specifiers-and-qualifiers and possibly modified by the declarator as usual in declarations, must be a non-array object type or the type void. If the function declaration is not a definition, the return type can be incomplete. The return type cannot be cvr-qualified: any qualified return type is adjusted to its unqualified version for the purpose of constructing the function type.

+
void f(char *s);                    // return type is void
+int sum(int a, int b);              // return type of sum is int.
+int (*foo(const void *p))[3];       // return type is pointer to array of 3 int
+ 
+double const bar(void);             // declares function of type double(void)
+double (*barp)(void) = bar;         // OK: barp is a pointer to double(void)
+double const (*barpc)(void) = barp; // OK: barpc is also a pointer to double(void)

Function declarators can be combined with other declarators as long as they can share their type specifiers and qualifiers

+
int f(void), *fip(), (*pfi)(), *ap[3]; // declares two functions and two objects
+inline int g(int), n; // Error: inline qualifier is for functions only
+typedef int array_t[3];
+array_t a, h(); // Error: array type cannot be a return type for a function

If a function declaration appears outside of any function, the identifier it introduces has file scope and external linkage, unless static is used or an earlier static declaration is visible. If the declaration occurs inside another function, the identifier has block scope (and also either internal or external linkage).

+
int main(void)
+{
+    int f(int); // external linkage, block scope
+    f(1); // definition needs to be available somewhere in the program
+}

The parameters in a declaration that is not part of a function definition(until C23) do not need to be named:

+
int f(int, int); // declaration
+// int f(int, int) { return 7; } // Error: parameters must be named in definitions
+// This definition is allowed since C23

Each parameter in a parameter-list is a declaration that introduced a single variable, with the following additional properties:

+ 
int f(int, double); // OK
+int g(int a, double b); // also OK
+// int f(int, double) { return 1; } // Error: definition must name parameters
+// This definition is allowed since C23
int f(static int x); // Error
+int f(int [static 10]); // OK (array index static is not a storage class specifier)
int f(int[]); // declares int f(int*)
+int g(const int[10]); // declares int g(const int*)
+int h(int[const volatile]); // declares int h(int * const volatile)
+int x(int[*]); // declares int x(int*)
int f(char g(double)); // declares int f(char (*g)(double))
+int h(int(void)); // declares int h(int (*)(void))
int f(int, ...);
int f(void); // OK
+int g(void x); // Error
+ +

Attribute specifier sequences can also applied to function parameters.

+		 (since C23)

See function call operator for other details on the mechanics of a function call and return for returning from functions.

+

Notes

+ +

Unlike in C++, the declarators f() and f(void) have different meaning: the declarator f(void) is a new-style (prototype) declarator that declares a function that takes no parameters. The declarator f() is a declarator that declares a function that takes unspecified number of parameters (unless used in a function definition)

+
int f(void); // declaration: takes no parameters
+int g(); // declaration: takes unknown parameters
+ 
+int main(void) {
+    f(1); // compile-time error
+    g(2); // undefined behavior
+}
+ 
+int f(void) { return 1; } // actual definition
+int g(a,b,c,d) int a,b,c,d; { return 2; } // actual definition
 (until C23)

Unlike in a function definition, the parameter list may be inherited from a typedef

+
typedef int p(int q, int r); // p is a function type int(int, int)
+p f; // declares int f(int, int)
+ +

In C89, specifiers-and-qualifiers was optional, and if omitted, the return type of the function defaulted to int (possibly amended by the declarator).

+
*f() { // function returning int*
+   return NULL;
+}
 (until C99)

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C standards.

+ + + +
DR Applied to Behavior as published Correct behavior
+DR 423 C89 the return type might be qualified the return type is implicitly disqualified

References

See also

+
C++ documentation for Function declaration
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/function_declaration +

+
diff --git a/devdocs/c/language%2Ffunction_definition.html b/devdocs/c/language%2Ffunction_definition.html new file mode 100644 index 00000000..8efefcc2 --- /dev/null +++ b/devdocs/c/language%2Ffunction_definition.html @@ -0,0 +1,93 @@ +

Function definitions

A function definition associates the function body (a sequence of declarations and statements) with the function name and parameter list. Unlike function declaration, function definitions are allowed at file scope only (there are no nested functions).

+

C supports two different forms of function definitions:

+ + + +
attr-spec-seq(optional) specifiers-and-qualifiers parameter-list-declarator function-body (1)
specifiers-and-qualifiers identifier-list-declarator declaration-list function-body (2) (until C23)

where

+ + + + + + + +
attr-spec-seq - (C23)an optional list of attributes, applied to the function
specifiers-and-qualifiers - a combination of
parameter-list-declarator - a declarator for a function type which uses a parameter list to designate function parameters
identifier-list-declarator - a declarator for a function type which uses a identifier list to designate function parameters
declaration-list - sequence of declarations that declare every identifier in identifier-list-declarator. These declarations cannot use initializers and the only storage-class specifier allowed is register.
function-body - a compound statement, that is a brace-enclosed sequence of declarations and statements, that is executed whenever this function is called
+1) New-style (C89) function definition. This definition both introduces the function itself and serves as a function prototype for any future function call expressions, forcing conversions from argument expressions to the declared parameter types. 
int max(int a, int b)
+{
+    return a>b?a:b;
+}
+ 
+double g(void)
+{
+    return 0.1;
+}
+
+2) (until C23) Old-style (K&R) function definition. This definition does not behave as a prototype and any future function call expressions will perform default argument promotions. 
int max(a, b)
+int a, b;
+{
+    return a>b?a:b;
+}
+double g()
+{
+    return 0.1;
+}
+

Explanation

As with function declarations, the return type of the function, determined by the type specifier in specifiers-and-qualifiers and possibly modified by the declarator as usual in declarations, must be a complete non-array object type or the type void. If the return type would be cvr-qualified, it is adjusted to its unqualified version for the purpose of constructing the function type.

+
void f(char *s) { puts(s); } // return type is void
+int sum(int a, int b) { return a+b: } // return type is int
+int (*foo(const void *p))[3] { // return type is pointer to array of 3 int
+    return malloc(sizeof(int[3]));
+}

As with function declarations, the types of the parameters are adjusted from functions to pointers and from arrays to pointers for the purpose of constructing the function type and the top-level cvr-qualifiers of all parameter types are ignored for the purpose of determining compatible function type.

+ + + + +

Unlike function declarations, unnamed formal parameters are not allowed (otherwise, there would be conflicts in old-style (K&R) function definitions), they must be named even if they are not used within the function. The only exception is the special parameter list (void).

+		 (until C23)

Formal parameters may be unnamed in function definitions, because old-style (K&R) function definitions has been removed. Unnamed parameters are inaccessible by name within the function body.

+		 (since C23)
int f(int, int); // declaration
+// int f(int, int) { return 7; } // Error until C23, OK since C23
+int f(int a, int b) { return 7; } // definition
+int g(void) { return 8; } // OK: void doesn't declare a parameter

Within the function body, every named parameter is an lvalue expression, they have automatic storage duration and block scope. The layout of the parameters in memory (or if they are stored in memory at all) is unspecified: it is a part of the calling convention.

+
int main(int ac, char **av)
+{
+    ac = 2; // parameters are lvalues
+    av = (char *[]){"abc", "def", NULL};
+    f(ac, av);
+}

See function call operator for other details on the mechanics of a function call and return for returning from functions.

+ + +

__func__

Within every function-body, the special predefined variable __func__ with block scope and static storage duration is available, as if defined immediately after the opening brace by

+
static const char __func__[] = "function name";

This special identifier is sometimes used in combination with the predefined macro constants __FILE__ and __LINE__, for example, by assert.

+		 (since C99)

Notes

The argument list must be explicitly present in the declarator, it cannot be inherited from a typedef

+
typedef int p(int q, int r); // p is a function type int(int, int)
+p f { return q + r; } // Error
+ +

In C89, specifiers-and-qualifiers was optional, and if omitted, the return type of the function defaulted to int (possibly amended by the declarator).

+

In addition, old-style definition didn't require a declaration for every parameter in declaration-list. Any parameter whose declaration was missing had type int

+
max(a, b) // a and b have type int, return type is int
+{
+    return a>b?a:b;
+}
 (until C99)

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C standards.

+ + + +
DR Applied to Behavior as published Correct behavior
+DR 423 C89 the return type might be qualified the return type is implicitly disqualified

References

See also

+
C++ documentation for Function definition
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/function_definition +

+
diff --git a/devdocs/c/language%2Ffunctions.html b/devdocs/c/language%2Ffunctions.html new file mode 100644 index 00000000..23bdd021 --- /dev/null +++ b/devdocs/c/language%2Ffunctions.html @@ -0,0 +1,53 @@ +

Functions

A function is a C language construct that associates a compound statement (the function body) with an identifier (the function name). Every C program begins execution from the main function, which either terminates, or invokes other, user-defined or library functions.

+
// function definition.
+// defines a function with the name "sum" and with the body "{ return x+y; }"
+int sum(int x, int y) 
+{
+    return x + y;
+}

A function is introduced by a function declaration or a function definition.

+

Functions may accept zero or more parameters, which are initialized from the arguments of a function call operator, and may return a value to its caller by means of the return statement.

+
int n = sum(1, 2); // parameters x and y are initialized with the arguments 1 and 2

The body of a function is provided in a function definition. Each non-inline(since C99) function that is used in an expression (unless unevaluated) must be defined only once in a program.

+

There are no nested functions (except where allowed through non-standard compiler extensions): each function definition must appear at file scope, and functions have no access to the local variables from the caller:

+
int main(void) // the main function definition
+{
+    int sum(int, int); // function declaration (may appear at any scope)
+    int x = 1;  // local variable in main
+    sum(1, 2); // function call
+ 
+//    int sum(int a, int b) // error: no nested functions
+//    {
+//        return  a + b; 
+//    }
+}
+int sum(int a, int b) // function definition
+{
+//    return x + a + b; //  error: main's x is not accessible within sum
+    return a + b;
+}

References

See also

+
C++ documentation for Declaring functions
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/functions +

+
diff --git a/devdocs/c/language%2Fgeneric.html b/devdocs/c/language%2Fgeneric.html new file mode 100644 index 00000000..670853f3 --- /dev/null +++ b/devdocs/c/language%2Fgeneric.html @@ -0,0 +1,62 @@ +

Generic selection (since C11) +

Provides a way to choose one of several expressions at compile time, based on a type of a controlling expression

+

Syntax

+ +
_Generic ( controlling-expression , association-list ) (since C11)

where association-list is a comma-separated list of associations, each of which has the syntax

+ + + +
type-name : expression
default : expression

where

+ + + + +
type-name - any complete object type that isn't variably-modified (that is, not VLA or pointer to VLA).
controlling-expression - any expression (except for the comma operator) whose type must be compatible with one of the type-names if the default association is not used
expression - any expression (except for the comma operator) of any type and value category

No two type-names in the association-list may specify compatible types. There may be only one association that uses the keyword default. If default is not used and none of the type-names are compatible with the type of the controlling expression, the program will not compile.

+

Explanation

First, the type of controlling-expression undergoes lvalue conversions. The conversion is performed in type domain only: it discards the top-level cvr-qualifiers and atomicity and applies array-to-pointer/function-to-pointer transformations to the type of the controlling expression, without initiating any side-effects or calculating any values.

+

The type after conversion is compared with type-names from the list of associations.

+

If the type is compatible with the type-name of one of the associations, then the type, value, and value category of the generic selection are the type, value, and value category of the expression that appears after the colon for that type-name.

+

If none of the type-names are compatible with the type of the controlling-expression, and the default association is provided, then the type, value, and value category of the generic selection are the type, value, and value category of the expression after the default : label.

+

Notes

The controlling-expression and the expressions of the selections that are not chosen are never evaluated.

+

Because of the lvalue conversions, "abc" matches char* and not char[4] and (int const){0} matches int, and not const int.

+

All value categories, including function designators and void expressions, are allowed as expressions in a generic selection, and if selected, the generic selection itself has the same value category.

+

The type-generic math macros from <tgmath.h>, introduced in C99, were implemented in compiler-specific manner. Generic selections, introduced in C11, gave the programmers the ability to write similar type-dependent code.

+

Generic selection is similar to overloading in C++ (where one of several functions is chosen at compile time based on the types of the arguments), except that it makes the selection between arbitrary expressions.

+

Keywords

_Generic, default

+

Example

#include <math.h>
+#include <stdio.h>
+ 
+// Possible implementation of the tgmath.h macro cbrt
+#define cbrt(X) _Generic((X), \
+              long double: cbrtl, \
+                  default: cbrt,  \
+                    float: cbrtf  \
+              )(X)
+ 
+int main(void)
+{
+    double x = 8.0;
+    const float y = 3.375;
+    printf("cbrt(8.0) = %f\n", cbrt(x)); // selects the default cbrt
+    printf("cbrtf(3.375) = %f\n", cbrt(y)); // converts const float to float,
+                                            // then selects cbrtf
+}

Output:

+
cbrt(8.0) = 2.000000
+cbrtf(3.375) = 1.500000

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C standards.

+ + + +
DR Applied to Behavior as published Correct behavior
+DR 481 C11 it was underspecified if the controlling expression undergoes lvalue conversions it undergoes

References

See also

+
C++ documentation for Templates
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/generic +

+
diff --git a/devdocs/c/language%2Fgoto.html b/devdocs/c/language%2Fgoto.html new file mode 100644 index 00000000..ab3db583 --- /dev/null +++ b/devdocs/c/language%2Fgoto.html @@ -0,0 +1,64 @@ +

goto statement

Transfers control unconditionally to the desired location.

+

Used when it is otherwise impossible to transfer control to the desired location using conventional constructs.

+

Syntax

+ +
attr-spec-seq(optional) goto label ;
+ + +
label - target label for the goto statement
attr-spec-seq - (C23)optional list of attributes, applied to the goto statement

Explanation

The goto statement causes an unconditional jump (transfer of control) to the statement prefixed by the named label (which must appear in the same function as the goto statement), except when this jump would enter the scope of a variable-length array or another variably-modified type.(since C99)

+

A label is an identifier followed by a colon (:) and a statement(until C23). Labels are the only identifiers that have function scope: they can be used (in a goto statement) anywhere in the same function in which they appear. There may be multiple labels before any statement.

+ + +

Entering the scope of a non-variably modified variable is permitted:

+
goto lab1; // OK: going into the scope of a regular variable
+    int n = 5;
+lab1:; // Note, n is uninitialized, as if declared by int n;
+ 
+//   goto lab2;   // Error: going into the scope of two VM types
+     double a[n]; // a VLA
+     int (*p)[n]; // a VM pointer
+lab2:

If goto leaves the scope of a VLA, it is deallocated (and may be reallocated if its initialization is executed again):

+
{
+   int n = 1;
+label:;
+   int a[n]; // re-allocated 10 times, each with a different size
+   if (n++ < 10) goto label; // leaving the scope of a VM
+}
 (since C99)

Keywords

goto

+

Notes

+ +

Because declarations are not statements, a label before a declaration must use a null statement (a semicolon immediately after the colon). Same applies to a label before the end of a block.

+		 (until C23)

C++ imposes additional limitations on the goto statement, but allows labels before declarations (which are statements in C++).

+

Example

#include <stdio.h>
+ 
+int main(void)
+{
+    // goto can be used to leave a multi-level loop easily
+    for (int x = 0; x < 3; x++) {
+        for (int y = 0; y < 3; y++) {
+            printf("(%d;%d)\n",x,y);
+            if (x + y >= 3) goto endloop;
+        }
+    }
+endloop:;
+}

Output:

+
(0;0)
+(0;1)
+(0;2)
+(1;0)
+(1;1)
+(1;2)

References

See also

+
C++ documentation for goto statement
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/goto +

+
diff --git a/devdocs/c/language%2Fhistory.html b/devdocs/c/language%2Fhistory.html new file mode 100644 index 00000000..62ab470b --- /dev/null +++ b/devdocs/c/language%2Fhistory.html @@ -0,0 +1,154 @@ +

History of C

Early C

Standard C

    +
  1. codified existing practices
    2. +
  2. new features: volatile, enum, signed, void, locales
    3. +
  3. From C++: const, function prototypes
    4. +
    +
  1. greatly expanded wide and multibyte character support (<wctype.h>, <wchar.h>, additions and changes to stream I/O, etc)
    2. +
  2. digraphs, <iso646.h>,
    3. +
    +
  1. new features: bool, long long, <stdint.h>, <inttypes.h>, restrict, compound literals, variable length arrays, flexible array members, designated initializers, <fenv.h>, variadic macros, complex numbers, __func__, hexadecimal floating point format (%a), monetary formatting in lconv, isblank, concatenation of narrow and wide string literals, trailing comma in enumerations, empty arguments in function-like macros, STDC_* pragmas, va_copy, null return of tmpnam, null pointer in setvbuf, hh and ll length-specifiers in printf, snprintf, _Exit, <tgmath.h>, POSIX-like strftime specifiers
    2. +
  2. from C++: inline, mix declarations and code, declarations in the init-clause of the for loop, // comments, universal character names in source code
    3. +
  3. removed implicit functions and implicit int
    4. +
    +
  1. thread-aware memory model, <stdatomic.h>, <threads.h>, type-generic functions, alignas/alignof, noreturn, static_assert, analyzability extensions, extensions to complex and imaginary types, anonymous structures and unions, exclusive file open mode, quick_exit
    2. +
  2. removed gets
    3. +
  3. from Bounds-checking interfaces TR: bounds-checking interfaces,
    4. +
  4. from Unicode TR: char16_t, char32_t, and <uchar.h>
    5. +
  1. provides changes to C11 (mostly to Annex F) that cover all basic requirements and some recommendations of IEC 60559:2011 (C11 was built on IEC 60559:1989)
  1. provides changes to C11 to support all the requirements, plus some basic recommendations, of IEC 60559:2011 for decimal floating-point arithmetic. This supersedes ISO/IEC TR 24732:2009.
  1. provides changes to C11 to support the recommendations of IEC 60559:2011 for extended floating‐point formats and the interchange formats, both arithmetic and non-arithmetic.
  1. provides changes to C11 to support all mathematical operations recommended by IEC 60559:2011, including trigonometry in π units, inverse square root, compounded interest, etc.
  1. provides changes to C11 to support all supplementary attributes (evaluation model, exception handling, reproducibility, etc) recommended by IEC 60559:2011
Main Article: C17
+ + +
Defect Reports fixed in C17 (54 defects)
+

Future development

  1. List of issues that were not granted DR status: (N2556 2020-08-02)
+
+Main Article: C23
+
Next major C language standard revision
+
+ + +
Defect Reports fixed in C23 (? defects)
+

See also

+
C++ documentation for History of C++
+ + +
1. +The Development of the C Language by Dennis M. Ritchie
2. +Rationale for the C99 standard
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/history +

+
diff --git a/devdocs/c/language%2Fidentifier.html b/devdocs/c/language%2Fidentifier.html new file mode 100644 index 00000000..16963e77 --- /dev/null +++ b/devdocs/c/language%2Fidentifier.html @@ -0,0 +1,142 @@ +

Identifier

An identifier is an arbitrarily long sequence of digits, underscores, lowercase and uppercase Latin letters, and Unicode characters specified using \u and \U escape notation(since C99), of class XID_Continue(since C23). A valid identifier must begin with a non-digit character (Latin letter, underscore, or Unicode non-digit character(since C99)(until C23), or Unicode character of class XID_Start)(since C23)). Identifiers are case-sensitive (lowercase and uppercase letters are distinct). Every identifier must conform to Normalization Form C.(since C23)

+ + + + +
It is implementation-defined if raw (not escaped) Unicode characters are allowed in identifiers: 
char *\U0001f431 = "cat"; // supported
+char *🐱 = "cat"; // implementation-defined
+                  // (e.g. works with Clang, but not GCC prior to version 10)
+                  // both are ill formed in C23. Emoji are not XID_Start characters
 +(since C99)
(until C23) +
Implementation-defined characters whose corresponding code points in ISO/IEC 10646 (Unicode) have the XID_Start or XID_Continue property can appear in the beginning or after the first character of an identifier respectively. (since C23)

Identifiers can denote the following types of entities:

+

Every identifier other than macro names or macro parameter names has scope, belongs to a name space, and may have linkage. The same identifier can denote different entities at different points in the program, or may denote different entities at the same point if the entities are in different name spaces.

+

Reserved identifiers

The following identifiers are reserved and may not be declared in a program (doing so invokes undefined behavior):

+
  1. The identifiers that are keywords cannot be used for other purposes. In particular #define or #undef of an identifier that is identical to a keyword is not allowed.
  2. All external identifiers that begin with an underscore.
  3. All identifiers that begin with an underscore followed by a capital letter or by another underscore (these reserved identifiers allow the library to use numerous behind-the-scenes non-external macros and functions).
  4. All external identifiers defined by the standard library (in hosted environment). This means that no user-supplied external names are allowed to match any library names, not even if declaring a function that is identical to a library function.
  5. Identifiers declared as reserved for the implementation or future use by the standard library (see below).
  6. +Identifiers declared as potentially reserved and provided by the implementation (see below). (since C23) +

All other identifiers are available. Identifiers that are not reserved or potentially reserved(since C23) can be used with no fear of unexpected collisions when moving programs from one compiler and library to another.

+

Note: in C++, identifiers with a double underscore anywhere are reserved everywhere; in C, only the ones that begin with a double underscore are reserved.

+

Reserved and potentially reserved identifiers in the library

The standard library reserves every identifier it provides. Reserved identifiers that have external linkage (e.g. name of every standard function) are reserved regardless which header is included. Other reserved identifiers are reserved when any of its associated headers is included.

+ + +

Potentially reserved identifiers are intended to be used by the implementation and future revision of standard. If a potentially reserved identifier is provided by the implementation, it becomes reserved.

+

Implementations are only allowed to provide external definitions of potentially reserved identifiers that are reserved as function names.

+

Potentially reserved identifiers that are not provided by the implementation are not reserved. They can be declared or defined by the user without undefined behavior. However, such usage is not portable.

+		 (since C23)

Following identifiers are reserved or potentially reserved(since C23) for the implementation or future use by the standard library.

+ + +

Implementations are recommended to warn when on declaration or definition of potentially reserved identifiers, except when

+
    +
  • the declaration is a non-definition declaration of an identifier with external linkage provided by the implementation, and
    • +
  • the type used in the declaration is compatible with that used in the definition.
    • +
 (since C23)

Translation limits

Even though there is no specific limit on the length of identifiers, early compilers had limits on the number of significant initial characters in identifiers and the linkers imposed stricter limits on the names with external linkage. C requires that at least the following limits are supported by any standard-compliant implementation:

+ + + + +
    +
  • 31 significant initial characters in an internal identifier or a macro name
    • +
  • 6 significant initial characters in an external identifier
    • +
  • 511 external identifiers in one translation unit
    • +
  • 127 identifiers with block scope declared in one block
    • +
  • 1024 macro identifiers simultaneously defined in one preprocessing translation unit
    • +
 (until C99)
    +
  • 63 significant initial characters in an internal identifier or a macro name
    • +
  • 31 significant initial characters in an external identifier
    • +
  • 4095 external identifiers in one translation unit
    • +
  • 511 identifiers with block scope declared in one block
    • +
  • 4095 macro identifiers simultaneously defined in one preprocessing translation unit
    • +
 (since C99)

References

See also

+
C++ documentation for Identifiers
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/identifier +

+
diff --git a/devdocs/c/language%2Fif.html b/devdocs/c/language%2Fif.html new file mode 100644 index 00000000..b273c4e8 --- /dev/null +++ b/devdocs/c/language%2Fif.html @@ -0,0 +1,65 @@ +

if statement

Conditionally executes code.

+

Used where code needs to be executed only if some condition is true.

+

Syntax

+ + +
attr-spec-seq(optional) if ( expression ) statement-true (1)
attr-spec-seq(optional) if ( expression ) statement-true else statement-false (2)
+ + + + +
attr-spec-seq - (C23)optional list of attributes, applied to the if statement
expression - an expression of any scalar type
statement-true - any statement (often a compound statement), which is executed if expression compares not equal to ​0​
statement-false - any statement (often a compound statement), which is executed if expression compares equal to ​0​

Explanation

expression must be an expression of any scalar type.

+

If expression compares not equal to the integer zero, statement-true is executed.

+

In the form (2), if expression compares equal to the integer zero, statement_false is executed.

+ + +

As with all other selection and iteration statements, the entire if-statement has its own block scope:

+
enum {a, b};
+int different(void)
+{
+    if (sizeof(enum {b, a}) != sizeof(int))
+        return a; // a == 1
+    return b; // b == 0 in C89, b == 1 in C99
+}
 (since C99)

Notes

The else is always associated with the closest preceding if (in other words, if statement-true is also an if statement, then that inner if statement must contain an else part as well):

+
int j = 1;
+if (i > 1)
+   if(j > 2)
+       printf("%d > 1 and %d > 2\n", i, j);
+    else // this else is part of if(j>2), not part of if(i>1) 
+       printf("%d > 1 and %d <= 2\n", i, j);

If statement-true is entered through a goto, statement-false is not executed.

+

Keywords

if, else

+

Example

#include <stdio.h>
+ 
+int main(void)
+{
+    int i = 2;
+    if (i > 2) {
+        printf("first is true\n");
+    } else {
+        printf("first is false\n");
+    }
+ 
+    i = 3;
+    if (i == 3) printf("i == 3\n");
+ 
+    if (i != 3) printf("i != 3 is true\n");
+    else        printf("i != 3 is false\n");
+}

Output:

+
first is false
+i == 3
+i != 3 is false

References

See also

+
C++ documentation for if statement
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/if +

+
diff --git a/devdocs/c/language%2Finitialization.html b/devdocs/c/language%2Finitialization.html new file mode 100644 index 00000000..7cacdb5b --- /dev/null +++ b/devdocs/c/language%2Finitialization.html @@ -0,0 +1,89 @@ +

Initialization

A declaration of an object may provide its initial value through the process known as initialization.

+

For each declarator, the initializer, if not omitted, may be one of the following:

+ + + + +
= expression (1)
= { initializer-list } (2)
= { } (3) (since C23)

where initializer-list is a non-empty comma-separated list of initializer s (with an optional trailing comma), where each initializer has one of three possible forms:

+ + + + + +
expression (1)
{ initializer-list } (2)
{ } (3) (since C23)
designator-list = initializer (4) (since C99)
+ +

where designator-list is a list of either array designators of the form [ constant-expression ] or struct/union member designators of the form . identifier ; see array initialization and struct initialization.

+

Note: besides initializers, brace-enclosed initializer-list may appear in compound literals, which are expressions of the form:

+ + + +
( type ) { initializer-list }
( type ) { } (since C23)
(since C99)

Explanation

The initializer specifies the initial value stored in an object.

+

Explicit initialization

If an initializer is provided, see

+

Implicit initialization

If an initializer is not provided:

+

Empty initialization

+ +

An object is empty-initialized if it is explicitly initialized from initializer = {}.

+		 (since C23)

In some cases, an object is empty-initialized if it is not initialized explicitly, that is:

+ (on platforms where null pointer values and floating zeroes have all-bit-zero representations, this form of initialization for statics is normally implemented by allocating them in the .bss section of the program image)

Notes

When initializing an object of static or thread-local storage duration, every expression in the initializer must be a constant expression or string literal.

+

Initializers cannot be used in declarations of objects of incomplete type, VLAs, and block-scope objects with linkage.

+

The initial values of function parameters are established as if by assignment from the arguments of a function call, rather than by initialization.

+

If an indeterminate value is used as an argument to any standard library call, the behavior is undefined. Otherwise, the result of any expression involving indeterminate values is an indeterminate value (e.g. int n;, n may not compare equal to itself and it may appear to change its value on subsequent reads)

+ + + + +

There is no special construct in C corresponding to value initialization in C++; however, = {0} (or (T){0} in compound literals)(since C99) can be used instead, as the C standard does not allow empty structs, empty unions, or arrays of zero length.

+		 (until C23)

The empty initializer = {} (or (T){} in compound literals) can be used to achieve the same semantics as value initialization in C++.

+		 (since C23)

Example

#include <stdlib.h>
+int a[2]; // initializes a to {0, 0}
+int main(void)
+{
+    int i;          // initializes i to an indeterminate value
+    static int j;   // initializes j to 0
+    int k = 1;      // initializes k to 1
+ 
+    // initializes int x[3] to 1,3,5
+    // initializes int* p to &x[0]
+    int x[] = { 1, 3, 5 }, *p = x;
+ 
+    // initializes w (an array of two structs) to
+    // { { {1,0,0}, 0}, { {2,0,0}, 0} }
+    struct {int a[3], b;} w[] = {[0].a = {1}, [1].a[0] = 2};
+ 
+    // function call expression can be used for a local variable
+    char* ptr = malloc(10);
+    free(ptr);
+ 
+//  Error: objects with static storage duration require constant initializers
+//  static char* ptr = malloc(10);
+ 
+//  Error: VLA cannot be initialized
+//  int vla[n] = {0};
+}

References

See also

+
C++ documentation for Initialization
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/initialization +

+
diff --git a/devdocs/c/language%2Finline.html b/devdocs/c/language%2Finline.html new file mode 100644 index 00000000..b5413a96 --- /dev/null +++ b/devdocs/c/language%2Finline.html @@ -0,0 +1,77 @@ +

inline function specifier

Declares an inline function.

+

Syntax

+ +
inline function_declaration (since C99)

Explanation

The intent of the inline specifier is to serve as a hint for the compiler to perform optimizations, such as function inlining, which usually require the definition of a function to be visible at the call site. The compilers can (and usually do) ignore presence or absence of the inline specifier for the purpose of optimization.

+

If the compiler performs function inlining, it replaces a call of that function with its body, avoiding the overhead of a function call (placing data on stack and retrieving the result), which may result in a larger executable as the code for the function has to be repeated multiple times. The result is similar to function-like macros, except that identifiers and macros used in the function refer to the definitions visible at the point of definition, not at the point of call.

+

Regardless of whether inlining takes place, the following semantics of inline functions are guaranteed:

+

Any function with internal linkage may be declared static inline with no other restrictions.

+

A non-static inline function cannot define a non-const function-local static and cannot refer to a file-scope static.

+
static int x;
+ 
+inline void f(void)
+{
+    static int n = 1; // error: non-const static in a non-static inline function
+    int k = x; // error: non-static inline function accesses a static variable
+}

If a non-static function is declared inline, then it must be defined in the same translation unit. The inline definition that does not use extern is not externally visible and does not prevent other translation units from defining the same function. This makes the inline keyword an alternative to static for defining functions inside header files, which may be included in multiple translation units of the same program.

+

If a function is declared inline in some translation units, it does not need to be declared inline everywhere: at most one translation unit may also provide a regular, non-inline non-static function, or a function declared extern inline. This one translation unit is said to provide the external definition. In order to avoid undefined behavior, one external definition must exist in the program if the name of the function with external linkage is used in an expression, see one definition rule.

+

The address of an inline function with external linkage is always the address of the external definition, but when this address is used to make a function call, it's unspecified whether the inline definition (if present in the translation unit) or the external definition is called. The static objects defined within an inline definition are distinct from the static objects defined within the external definition:

+
inline const char *saddr(void) // the inline definition for use in this file
+{
+    static const char name[] = "saddr";
+    return name;
+}
+ 
+int compare_name(void)
+{
+    return saddr() == saddr(); // unspecified behavior, one call could be external
+}
+ 
+extern const char *saddr(void); // an external definition is generated, too

A C program should not depend on whether the inline version or the external version of a function is called, otherwise the behavior is unspecified.

+

Keywords

inline

+

Notes

The inline keyword was adopted from C++, but in C++, if a function is declared inline, it must be declared inline in every translation unit, and also every definition of an inline function must be exactly the same (in C, the definitions may be different, and depending on the differences only results in unspecified behavior). On the other hand, C++ allows non-const function-local statics and all function-local statics from different definitions of an inline function are the same in C++ but distinct in C.

+

Example

+ +

Header file "test.h"

+
#ifndef TEST_H_INCLUDED
+#define TEST_H_INCLUDED
+ 
+inline int sum(int a, int b)
+{
+    return a + b;
+}
+ 
+#endif

Source file "sum.c"

+
#include "test.h"
+ 
+extern inline int sum(int a, int b); // provides external definition

Source file "test1.c"

+
#include <stdio.h>
+#include "test.h"
+ 
+extern int f(void);
+ 
+int main(void)
+{
+    printf("%d\n", sum(1, 2) + f());
+}

Source file "test2.c"

+
#include "test.h"
+ 
+int f(void)
+{
+    return sum(3, 4);
+}

Output

+
10

References

See also

+
C++ documentation for inline specifier
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/inline +

+
diff --git a/devdocs/c/language%2Finteger_constant.html b/devdocs/c/language%2Finteger_constant.html new file mode 100644 index 00000000..999d4816 --- /dev/null +++ b/devdocs/c/language%2Finteger_constant.html @@ -0,0 +1,135 @@ +

Integer constant

Allows values of integer type to be used in expressions directly.

+

Syntax

An integer constant is a non-lvalue expression of the form

+ + + + + +
decimal-constant integer-suffix (optional) (1)
octal-constant integer-suffix (optional) (2)
hex-constant integer-suffix (optional) (3)
binary-constant integer-suffix (optional) (4) (since C23)

where

+ + +

Optional single quotes (') may be inserted between the digits as a separator. They are ignored by the compiler.

+		 (since C23)

Explanation

+1) Decimal integer constant (base 10, the first digit is the most significant).
+2) Octal integer constant (base 8, the first digit is the most significant).
+3) Hexadecimal integer constant (base 16, the first digit is the most significant, the letters a through f represent the decimal values 10 through 15).
+4) Binary integer constant (base 2, the first digit is the most significant).

The following variables are initialized to the same value:

+
int d = 42;
+int o = 052;
+int x = 0x2a;
+int X = 0X2A;
+int b = 0b101010; // C23

The following variables are also initialized to the same value:

+
unsigned long long l1 = 18446744073709550592ull; // C99
+unsigned long long l2 = 18'446'744'073'709'550'592llu; // C23
+unsigned long long l3 = 1844'6744'0737'0955'0592uLL; // C23
+unsigned long long l4 = 184467'440737'0'95505'92LLU; // C23

The type of the integer constant

The type of the integer constant is the first type in which the value can fit, from the list of types which depends on which numeric base and which integer-suffix was used.

+ + + + + + + + + + +
Types allowed for integer constants
suffix decimal bases other bases
no suffix +int

long int
unsigned long int (until C99)
long long int (since C99)

+		 +int

unsigned int
long int
unsigned long int
long long int(since C99)
unsigned long long int(since C99)

+
+u or U +unsigned int

unsigned long int
unsigned long long int(since C99)

+		 +unsigned int

unsigned long int
unsigned long long int(since C99)

+
+l or L +long int

unsigned long int(until C99)
long long int(since C99)

+		 +long int

unsigned long int
long long int(since C99)
unsigned long long int(since C99)

+
both l/L and u/U +unsigned long int

unsigned long long int(since C99)

+		 +unsigned long int

unsigned long long int(since C99)

+
+ll or LL +long long int(since C99) +long long int(since C99)

unsigned long long int(since C99)

+
both ll/LL and u/U +unsigned long long int(since C99) +unsigned long long int(since C99)
+wb or WB +_BitInt(N) where the width N is the smallest N greater than 1 which can accommodate the value and the sign bit(since C23) +_BitInt(N) where the width N is the smallest N greater than 1 which can accommodate the value and the sign bit(since C23)
both wb/WB and u/U +unsigned _BitInt(N) where the width N is the smallest N greater than 0 which can accommodate the value(since C23) +unsigned _BitInt(N) where the width N is the smallest N greater than 0 which can accommodate the value(since C23)

If the value of the integer constant is too big to fit in any of the types allowed by suffix/base combination, it does not have suffixes wb, WB, uwb, or UWB(since C23) and the compiler supports extended integer types (such as __int128), the constant may be given the extended integer type; otherwise, the program is ill-formed.

+

Notes

Letters in the integer constants are case-insensitive: 0xDeAdBaBeU and 0XdeadBABEu represent the same number (one exception is the long-long-suffix, which is either ll or LL, never lL or Ll)(since C99).

+

There are no negative integer constants. Expressions such as -1 apply the unary minus operator to the value represented by the constant.

+ + +

When used in a controlling expression of #if or #elif, all signed integer constants act as if they have type intmax_t and all unsigned integer constants act as if they have type uintmax_t.

+		 (since C99)

Integer constants may be used in integer constant expressions.

+

Due to maximal munch, hexadecimal integer constants ending in e and E, when followed by the operators + or -, must be separated from the operator with whitespace or parentheses in the source:

+
int x = 0xE+2;   // error
+int y = 0xa+2;   // OK
+int z = 0xE +2;  // OK
+int q = (0xE)+2; // OK

Otherwise, a single invalid preprocessing number token is formed, which causes further analysis to fail.

+

Example

#include <inttypes.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    printf("123 = %d\n", 123);
+    printf("0123 = %d\n", 0123);
+    printf("0x123 = %d\n", 0x123);
+    printf("12345678901234567890ull = %llu\n", 12345678901234567890ull);
+    // the type is a 64-bit type (unsigned long long or possibly unsigned long)
+    // even without a long suffix
+    printf("12345678901234567890u = %"PRIu64"\n", 12345678901234567890u );
+ 
+    // printf("%lld\n", -9223372036854775808); // Error:
+        // the value 9223372036854775808 cannot fit in signed long long, which
+        // is the biggest type allowed for unsuffixed decimal integer constant
+ 
+    printf("%llu\n", -9223372036854775808ull );
+    // unary minus applied to unsigned value subtracts it from 2^64,
+    // this gives unsigned 9223372036854775808
+ 
+    printf("%lld\n", -9223372036854775807ll - 1);
+    // correct way to form signed value -9223372036854775808
+}

Output:

+
123 = 123
+0123 = 83
+0x123 = 291
+12345678901234567890ull = 12345678901234567890
+12345678901234567890u = 12345678901234567890
+9223372036854775808
+-9223372036854775808

References

See also

+
C++ documentation for Integer literal
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/integer_constant +

+
diff --git a/devdocs/c/language%2Flifetime.html b/devdocs/c/language%2Flifetime.html new file mode 100644 index 00000000..b250592e --- /dev/null +++ b/devdocs/c/language%2Flifetime.html @@ -0,0 +1,41 @@ +

Lifetime

Every object in C exists, has a constant address, retains its last-stored value (except when the value is indeterminate), and, for VLA, retains its size(since C99) over a portion of program execution known as this object's lifetime.

+

For the objects that are declared with automatic, static, and thread storage duration, lifetime equals their storage duration (note the difference between non-VLA and VLA automatic storage duration).

+

For the objects with allocated storage duration, the lifetime begins when the allocation function returns (including the return from realloc) and ends when the realloc or deallocation function is called. Note that since allocated objects have no declared type, the type of the lvalue expression first used to access this object becomes its effective type.

+

Accessing an object outside of its lifetime is undefined behavior.

+
int* foo(void) {
+    int a = 17; // a has automatic storage duration
+    return &a;
+}  // lifetime of a ends
+int main(void) {
+    int* p = foo(); // p points to an object past lifetime ("dangling pointer")
+    int n = *p; // undefined behavior
+}

A pointer to an object (or one past the object) whose lifetime ended has indeterminate value.

+

Temporary lifetime

Struct and union objects with array members (either direct or members of nested struct/union members) that are designated by non-lvalue expressions, have temporary lifetime. Temporary lifetime begins when the expression that refers to such object is evaluated and ends at the next sequence point(until C11)when the containing full expression or full declarator ends(since C11).

+

Any attempt to modify an object with temporary lifetime results in undefined behavior.

+
struct T { double a[4]; };
+struct T f(void) { return (struct T){3.15}; }
+double g1(double* x) { return *x; }
+void g2(double* x) { *x = 1.0; }
+int main(void)
+{
+    double d = g1(f().a); // C99: UB access to a[0] in g1 whose lifetime ended
+                          //      at the sequence point at the start of g1
+                          // C11: OK, d is 3.15
+    g2(f().a); // C99: UB modification of a[0] whose lifetime ended at the sequence point
+               // C11: UB attempt to modify a temporary object
+}

References

See also

+
C++ documentation for Object lifetime
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/lifetime +

+
diff --git a/devdocs/c/language%2Fmain_function.html b/devdocs/c/language%2Fmain_function.html new file mode 100644 index 00000000..a0cfbc3e --- /dev/null +++ b/devdocs/c/language%2Fmain_function.html @@ -0,0 +1,60 @@ +

Main function

Every C program coded to run in a hosted execution environment contains the definition (not the prototype) of a function named main, which is the designated start of the program.

+ + + + +
int main (void) { body } (1)
int main (int argc, char *argv[]) { body } (2)
/* another implementation-defined signature */ (since C99) (3)

Parameters

+ + +
argc - Non-negative value representing the number of arguments passed to the program from the environment in which the program is run.
argv - Pointer to the first element of an array of argc + 1 pointers, of which the last one is null and the previous ones, if any, point to strings that represent the arguments passed to the program from the host environment. If argv[0] is not a null pointer (or, equivalently, if argc > 0), it points to a string that represents the program name, which is empty if the program name is not available from the host environment.

The names argc and argv stand for "argument count" and "argument vector", and are traditionally used, but other names may be chosen for the parameters, as well as different but equivalent declarations of their type: int main(int ac, char** av) is equally valid.

+

A common implementation-defined form of main is int main(int argc, char *argv[], char *envp[]), where a third argument, of type char**, pointing at an array of pointers to the execution environment variables, is added.

+

Return value

If the return statement is used, the return value is used as the argument to the implicit call to exit() (see below for details). The values zero and EXIT_SUCCESS indicate successful termination, the value EXIT_FAILURE indicates unsuccessful termination.

+

Explanation

The main function is called at program startup, after all objects with static storage duration are initialized. It is the designated entry point to a program that is executed in a hosted environment (that is, with an operating system). The name and type of the entry point to any freestanding program (boot loaders, OS kernels, etc) are implementation-defined.

+

The parameters of the two-parameter form of the main function allow arbitrary multibyte character strings to be passed from the execution environment (these are typically known as command line arguments). The pointers argv[1] .. argv[argc-1] point at the first characters in each of these strings. argv[0] (if non-null) is the pointer to the initial character of a null-terminated multibyte string that represents the name used to invoke the program itself (or, if this is not supported by the host environment, argv[0][0] is guaranteed to be zero).

+

If the host environment cannot supply both lowercase and uppercase letters, the command line arguments are converted to lowercase.

+

The strings are modifiable, and any modifications made persist until program termination, although these modifications do not propagate back to the host environment: they can be used, for example, with strtok.

+

The size of the array pointed to by argv is at least argc+1, and the last element, argv[argc], is guaranteed to be a null pointer.

+

The main function has several special properties:

+
+1) A prototype for this function cannot be supplied by the program.
+2) If the return type of the main function is compatible with int, then the return from the initial call to main (but not the return from any subsequent, recursive, call) is equivalent to executing the exit function, with the value that the main function is returning passed as the argument (which then calls the functions registered with atexit, flushes and closes all streams, and deletes the files created with tmpfile, and returns control to the execution environment).
+3) + + + +

If the main function executes a return that specifies no value or, which is the same, reaches the terminating } without executing a return, the termination status returned to the host environment is undefined.

+		 (until C99)

If the return type of the main function is not compatible with int (e.g. void main(void)), the value returned to the host environment is unspecified. If the return type is compatible with int and control reaches the terminating }, the value returned to the environment is the same as if executing return 0;.

+		 (since C99)
+

Example

+

Demonstrates how to inform a program about where to find its input and where to write its results. Invocation: ./a.out indatafile outdatafile

+
#include <stdio.h>
+ 
+int main(int argc, char *argv[])
+{
+    printf("argc = %d\n", argc);
+    for (int ndx = 0; ndx != argc; ++ndx)
+        printf("argv[%d] --> %s\n", ndx, argv[ndx]);
+    printf("argv[argc] = %p\n", (void*)argv[argc]);
+}

Possible output:

+
argc = 3
+argv[0] --> ./a.out
+argv[1] --> indatafile
+argv[2] --> outdatafile
+argv[argc] = (nil)

References

See also

+
C++ documentation for main function
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/main_function +

+
diff --git a/devdocs/c/language%2Fmemory_model.html b/devdocs/c/language%2Fmemory_model.html new file mode 100644 index 00000000..b0e6cfb5 --- /dev/null +++ b/devdocs/c/language%2Fmemory_model.html @@ -0,0 +1,49 @@ +

Memory model

Defines the semantics of computer memory storage for the purpose of the C abstract machine.

+

The data storage (memory) available to a C program is one or more contiguous sequences of bytes. Each byte in memory has a unique address.

+

Byte

A byte is the smallest addressable unit of memory. It is defined as a contiguous sequence of bits, large enough to hold any member of the basic execution character set (the 96 characters that are required to be single-byte). C supports bytes of sizes 8 bits and greater.

+

The types char, unsigned char, and signed char use one byte for both storage and value representation. The number of bits in a byte is accessible as CHAR_BIT.

+

For use of bytes to representation values of other fundamental types (including big-endian and little-endian memory layouts), see object representation

+

Memory location

A memory location is

+ 
struct S
+{
+    char a;     // memory location #1
+    int b : 5;  // memory location #2
+    int c : 11, // memory location #2 (continued)
+          : 0,
+        d : 8;  // memory location #3
+    struct
+    {
+        int ee : 8; // memory location #4
+    } e;
+} obj; // The object 'obj' consists of 4 separate memory locations
+ +

Threads and data races

A thread of execution is a flow of control within a program that begins with the invocation of a top-level function by thrd_create or other means.

+

Any thread can potentially access any object in the program (objects with automatic and thread-local storage duration may still be accessed by another thread through a pointer).

+

Different threads of execution are always allowed to access (read and modify) different memory locations concurrently, with no interference and no synchronization requirements. (note that it is not safe to concurrently update two non-atomic bit-fields in the same structure if all members declared between them are also (non-zero-length) bit-fields, no matter what the sizes of those intervening bit-fields happen to be)

+

When an evaluation of an expression writes to a memory location and another evaluation reads or modifies the same memory location, the expressions are said to conflict. A program that has two conflicting evaluations has a data race unless either

+

If a data race occurs, the behavior of the program is undefined. (in particular, mtx_unlock is

+synchronized-with, and therefore, happens-before mtx_lock of the same mutex by another thread, which makes it possible to use mutex locks to guard against data races)

Memory order

When a thread reads a value from a memory location, it may see the initial value, the value written in the same thread, or the value written in another thread. See memory_order for details on the order in which writes made from threads become visible to other threads.

+		 (since C11)

References

See also

+
C++ documentation for Memory model
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/memory_model +

+
diff --git a/devdocs/c/language%2Fname_space.html b/devdocs/c/language%2Fname_space.html new file mode 100644 index 00000000..46652601 --- /dev/null +++ b/devdocs/c/language%2Fname_space.html @@ -0,0 +1,74 @@ +

Lookup and name spaces

When an identifier is encountered in a C program, a lookup is performed to locate the declaration that introduced that identifier and that is currently in scope. C allows more than one declaration for the same identifier to be in scope simultaneously if these identifiers belong to different categories, called name spaces:

+
+1) Label name space: all identifiers declared as labels.
+2) Tag names: all identifiers declared as names of structs, unions and enumerated types. Note that all three kinds of tags share one name space.
+3) Member names: all identifiers declared as members of any one struct or union. Every struct and union introduces its own name space of this kind.
+ +
4) Global attribute name space: attribute tokens defined by the standard or implementation-defined attribute prefixes. 5) Non-standard attribute names: attribute names following attribute prefixes. Each attribute prefix has a separate name space for the implementation-defined attributes it introduces. (since C23)
+6) All other identifiers, called ordinary identifiers to distinguish from (1-5) (function names, object names, typedef names, enumeration constants).

At the point of lookup, the name space of an identifier is determined by the manner in which it is used:

+
+1) identifier appearing as the operand of a goto statement is looked up in the label name space.
+2) identifier that follows the keyword struct, union, or enum is looked up in the tag name space.
+3) identifier that follows the member access or member access through pointer operator is looked up in the name space of members of the type determined by the left-hand operand of the member access operator.
+ +
4) identifier that directly appears in an attribute specifier ([[...]]) is looked up in the global attribute name space. 5) identifier that follows the :: token following an attribute prefix is looked in the name space introduced by the attribute prefix. (since C23)
+6) all other identifiers are looked up in the name space of ordinary identifiers.

Notes

The names of macros are not part of any name space because they are replaced by the preprocessor prior to semantic analysis.

+

It is common practice to inject struct/union/enum names into the name space of the ordinary identifiers using a typedef declaration:

+
struct A { };       // introduces the name A in tag name space
+typedef struct A A; // first, lookup for A after "struct" finds one in tag name space
+                    // then introduces the name A in the ordinary name space
+struct A* p;        // OK, this A is looked up in the tag name space
+A* q;               // OK, this A is looked up in the ordinary name space

A well-known example of the same identifier being used across two name spaces is the identifier stat from the POSIX header sys/stat.h. It names a function when used as an ordinary identifier and indicates a struct when used as a tag.

+

Unlike in C++, enumeration constants are not struct members, and their name space is the name space of ordinary identifiers, and since there is no struct scope in C, their scope is the scope in which the struct declaration appears:

+
struct tagged_union {
+   enum {INT, FLOAT, STRING} type;
+   union {
+      int integer;
+      float floating_point;
+      char *string;
+   };
+} tu;
+ 
+tu.type = INT; // OK in C, error in C++
+ +

If a standard attribute, an attribute prefix, or a non-standard attribute name is not supported, the invalid attribute itself is ignored without causing an error.

+		 (since C23)

Example

void foo (void) { return; } // ordinary name space, file scope
+struct foo {      // tag name space, file scope
+    int foo;      // member name space for this struct foo, file scope
+    enum bar {    // tag name space, file scope
+        RED       // ordinary name space, file scope
+    } bar;        // member name space for this struct foo, file scope
+    struct foo* p; // OK: uses tag/file scope name "foo"
+};
+enum bar x; // OK: uses tag/file-scope bar
+// int foo; // Error: ordinary name space foo already in scope 
+//union foo { int a, b; }; // Error: tag name space foo in scope
+ 
+int main(void)
+{
+    goto foo; // OK uses "foo" from label name space/function scope
+ 
+    struct foo { // tag name space, block scope (hides file scope)
+       enum bar x; // OK, uses "bar" from tag name space/file scope
+    };
+    typedef struct foo foo; // OK: uses foo from tag name space/block scope
+                            // defines block-scope ordinary foo (hides file scope)
+    (foo){.x=RED}; // uses ordinary/block-scope foo and ordinary/file-scope RED
+ 
+foo:; // label name space, function scope
+}

References

See also

+
C++ documentation for Name lookup
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/name_space +

+
diff --git a/devdocs/c/language%2Fnullptr.html b/devdocs/c/language%2Fnullptr.html new file mode 100644 index 00000000..9c5d8a87 --- /dev/null +++ b/devdocs/c/language%2Fnullptr.html @@ -0,0 +1,59 @@ +

Predefined null pointer constant (since C23) +

Syntax

+ +
nullptr (since C23)

Explanation

The keyword nullptr denotes a predefined null pointer constant. It is a non-lvalue of type nullptr_t. nullptr can be converted to a pointer types or bool, where the result is the null pointer value of that type or false respectively.

+

Keywords

nullptr

+

Example

+

Demonstrates that a copy of nullptr can also be used as a null pointer constant.

+
#include <stddef.h>
+#include <stdio.h>
+ 
+void g(int*)
+{
+    puts("Function g called");
+}
+ 
+#define DETECT_NULL_POINTER_CONSTANT(e) \
+    _Generic(e,                         \
+        void* : puts("void*"),          \
+        nullptr_t : puts("nullptr_t"),  \
+        default : puts("integer")       \
+    )
+ 
+int main()
+{
+    g(nullptr); // OK
+    g(NULL); // OK
+    g(0); // OK
+ 
+    auto cloned_nullptr = nullptr;
+    g(cloned_nullptr); // OK
+ 
+    [[maybe_unused]] auto cloned_NULL = NULL;
+//  g(cloned_NULL); // implementation-defined: maybe OK
+ 
+    [[maybe_unused]] auto cloned_zero = 0;
+//  g(cloned_zero); // Error
+ 
+    DETECT_NULL_POINTER_CONSTANT(((void*)0));
+    DETECT_NULL_POINTER_CONSTANT(0);
+    DETECT_NULL_POINTER_CONSTANT(nullptr);
+    DETECT_NULL_POINTER_CONSTANT(NULL); // implementation-defined
+}

Possible output:

+
Function g called
+Function g called
+Function g called
+Function g called
+void*
+integer
+nullptr_t
+void*

See also

+ + +
implementation-defined null pointer constant
(macro constant)
+
(C23)
 the type of the predefined null pointer constant nullptr
(typedef)
C++ documentation for nullptr
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/nullptr +

+
diff --git a/devdocs/c/language%2Fobject.html b/devdocs/c/language%2Fobject.html new file mode 100644 index 00000000..18e7ee2a --- /dev/null +++ b/devdocs/c/language%2Fobject.html @@ -0,0 +1,137 @@ +

Objects and alignment

C programs create, destroy, access, and manipulate objects.

+

An object in C is a region of data storage in the execution environment, the contents of which can represent values (a value is the meaning of the contents of an object, when interpreted as having a specific type).

+

Every object has

+

Objects are created by declarations, allocation functions, string literals, compound literals, and by non-lvalue expressions that return structures or unions with array members.

+

Object representation

Except for bit-fields, objects are composed of contiguous sequences of one or more bytes, each consisting of CHAR_BIT bits, and can be copied with memcpy into an object of type unsigned char[n], where n is the size of the object. The contents of the resulting array are known as object representation.

+

If two objects have the same object representation, they compare equal (except if they are floating-point NaNs). The reverse is not true: two objects that compare equal may have different object representations because not every bit of the object representation needs to participate in the value. Such bits may be used for padding to satisfy alignment requirement, for parity checks, to indicate trap representations, etc.

+

If an object representation does not represent any value of the object type, it is known as trap representation. Accessing a trap representation in any way other than reading it through an lvalue expression of character type is undefined behavior. The value of a structure or union is never a trap representation even if any particular member is one.

+

For the objects of type char, signed char, and unsigned char, every bit of the object representation is required to participate in the value representation and each possible bit pattern represents a distinct value (no padding, trap bits, or multiple representations allowed).

+

When objects of integer types (short, int, long, long long) occupy multiple bytes, the use of those bytes is implementation-defined, but the two dominant implementations are big-endian (POWER, Sparc, Itanium) and little-endian (x86, x86_64): a big-endian platform stores the most significant byte at the lowest address of the region of storage occupied by the integer, a little-endian platform stores the least significant byte at the lowest address. See Endianness for detail. See also example below.

+

Although most implementations do not allow trap representations, padding bits, or multiple representations for integer types, there are exceptions; for example a value of an integer type on Itanium may be a trap representation.

+

Effective type

Every object has an effective type, which determines which lvalue accesses are valid and which violate the strict aliasing rules.

+

If the object was created by a declaration, the declared type of that object is the object's effective type.

+

If the object was created by an allocation function (including realloc), it has no declared type. Such object acquires an effective type as follows:

+

Strict aliasing

Given an object with effective type T1, using an lvalue expression (typically, dereferencing a pointer) of a different type T2 is undefined behavior, unless:

+ 
int i = 7;
+char* pc = (char*)(&i);
+ 
+if (pc[0] == '\x7') // aliasing through char is OK
+    puts("This system is little-endian");
+else
+    puts("This system is big-endian");
+ 
+float* pf = (float*)(&i);
+float d = *pf; // UB: float lvalue *p cannot be used to access int

These rules control whether a function that receives two pointers must re-read one after writing through another:

+
// int* and double* cannot alias
+void f1(int* pi, double* pd, double d)
+{
+    // the read from *pi can be done only once, before the loop
+    for (int i = 0; i < *pi; i++)
+        *pd++ = d;
+}
struct S { int a, b; };
+ 
+// int* and struct S* may alias because S is an aggregate type with a member of type int
+void f2(int* pi, struct S* ps, struct S s)
+{
+    // read from *pi must take place after every write through *ps
+    for (int i = 0; i < *pi; i++)
+        *ps++ = s;
+}

Note that restrict qualifier can be used to indicate that two pointers do not alias even if the rules above permit them to be.

+

Note that type-punning may also be performed through the inactive member of a union.

+

Alignment

Every complete object type has a property called alignment requirement, which is an integer value of type size_t representing the number of bytes between successive addresses at which objects of this type can be allocated. The valid alignment values are non-negative integral powers of two.

+ + +

The alignment requirement of a type can be queried with _Alignof.

+		 (since C11)

In order to satisfy alignment requirements of all members of a struct, padding may be inserted after some of its members.

+
#include <stdalign.h>
+#include <stdio.h>
+ 
+// objects of struct S can be allocated at any address
+// because both S.a and S.b can be allocated at any address
+struct S
+{
+    char a; // size: 1, alignment: 1
+    char b; // size: 1, alignment: 1
+}; // size: 2, alignment: 1
+ 
+// objects of struct X must be allocated at 4-byte boundaries
+// because X.n must be allocated at 4-byte boundaries
+// because int's alignment requirement is (usually) 4
+struct X
+{
+    int n;  // size: 4, alignment: 4
+    char c; // size: 1, alignment: 1
+    // three bytes padding
+}; // size: 8, alignment: 4
+ 
+int main(void)
+{
+    printf("sizeof(struct S) = %zu\n", sizeof(struct S));
+    printf("alignof(struct S) = %zu\n", alignof(struct S));
+    printf("sizeof(struct X) = %zu\n", sizeof(struct X));
+    printf("alignof(struct X) = %zu\n", alignof(struct X));
+}

Possible output:

+
sizeof(struct S) = 2
+alignof(struct S) = 1
+sizeof(struct X) = 8
+alignof(struct X) = 4

Each object type imposes its alignment requirement on every object of that type. The weakest (smallest) alignment is the alignment of the types char, signed char, and unsigned char, and equals 1. The strictest (largest) fundamental alignment of any type is implementation-definedand equal to the alignment of max_align_t(since C11).

+

Fundamental alignments are supported for objects of all kinds of storage durations.

+ + +

If an object's alignment is made stricter (larger) than max_align_t using _Alignas, it has extended alignment requirement. A struct or union type whose member has extended alignment is an over-aligned type. It is implementation-defined if over-aligned types are supported, and their support may be different in each kind of storage duration.

+

If a struct or union type S does not have any member of an over-aligned type or declared with an alignment specifier that specifies an extended alignment, S has a fundamental alignment.

+

The atomic version of every arithmetic or pointer type has a fundamental alignment.

+		 (since C11)

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C standards.

+ + + +
DR Applied to Behavior as published Correct behavior
+DR 445 C11 a type might have extended alignment without _Alignas involved it must have fundamental alignment

References

See also

+
C++ documentation for Object
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/object +

+
diff --git a/devdocs/c/language%2Foperator_alternative.html b/devdocs/c/language%2Foperator_alternative.html new file mode 100644 index 00000000..6d6bac63 --- /dev/null +++ b/devdocs/c/language%2Foperator_alternative.html @@ -0,0 +1,85 @@ +

Alternative operators and tokens

C source code may be written in any 8-bit character set that includes the ISO 646:1983 invariant character set, even non-ASCII ones. However, several C operators and punctuators require characters that are outside of the ISO 646 codeset: {, }, [, ], #, \, ^, |, ~. To be able to use character encodings where some or all of these symbols do not exist (such as the German DIN 66003), there are two possibilities: alternative spellings of operators that use these characters or special combinations of two or three ISO 646 compatible characters that are interpreted as if they were a single non-ISO 646 character.

+

Operator macros(C95) +

There are alternative spellings for the operators that use non-ISO646 characters, defined in <iso646.h> as macros:

+ + + + + + + + + + + + + +
Defined in header <iso646.h>
Primary Alternative
&&
 and
(operator macro)
&=
 and_eq
(operator macro)
&
 bitand
(operator macro)
|
 bitor
(operator macro)
~
 compl
(operator macro)
!
 not
(operator macro)
!=
 not_eq
(operator macro)
||
 or
(operator macro)
|=
 or_eq
(operator macro)
^
 xor
(operator macro)
^=
 xor_eq
(operator macro)

The characters & and ! are invariant under ISO-646, but alternatives are provided for the operators that use these characters anyway to accommodate even more restrictive historical charsets.

+

There is no alternative spelling (such as eq) for the equality operator == because the character = was present in all supported charsets.

+

Alternative tokens(C95) +

The following alternative tokens are part of the core language, and, in all respects of the language, each alternative token behaves exactly the same as its primary token, except for its spelling (the stringification operator can make the spelling visible). The two-letter alternative tokens are sometimes called "digraphs" (even though it is four letters long %:%: is also considered a digraph).

+ + + + + + + + +
Primary Alternative
{ +<%
+} +%>
[ +<:
] +:>
# +%:
## +%:%:

Trigraphs (removed in C23) +

The following three-character groups (trigraphs) are parsed before comments and string literals are recognized, and each appearance of a trigraph is replaced by the corresponding primary character:

+ + + + + + + + + + + +
Primary Trigraph
{ +??<
+} +??>
[ +??(
] +??)
# +??=
\ +??/
^ +??'
| +??!
~ +??-

Because trigraphs are processed early, a comment such as // Will the next line be executed?????/ will effectively comment out the following line, and the string literal such as "What's going on??!" is parsed as "What's going on|".

+

Example

+

Demonstrates alternative operator spellings from the <iso646.h> as well as use of digraphs and trigraphs. If command line arguments contain spaces they should be wrapped in the quotation marks, e.g., "Third World!".

+
%:include <stdio.h>
+%:include <stdlib.h>
+??=include <iso646.h>
+ 
+int main(int argc, char** argv)
+??<
+    if (argc > 1 and argv<:1:> not_eq NULL)
+    <%
+       printf("Hello %s??/n", argv<:1:>);
+    %>
+    else
+    <%
+       printf("Hello %s??/n", argc? argv??(42??'42??) : __FILE__);
+    %>
+ 
+    return EXIT_SUCCESS;
+??>

Possible output:

+
Hello ./a.out

See also

+
C++ documentation for Alternative operator representations
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/operator_alternative +

+
diff --git a/devdocs/c/language%2Foperator_arithmetic.html b/devdocs/c/language%2Foperator_arithmetic.html new file mode 100644 index 00000000..142a5f31 --- /dev/null +++ b/devdocs/c/language%2Foperator_arithmetic.html @@ -0,0 +1,327 @@ +

Arithmetic operators

Arithmetic operators apply standard mathematical operations to their operands.

+ + + + + + + + + + + + + + + +
Operator Operator name Example Result
+ unary plus +a the value of a after promotions
- unary minus -a the negative of a
+ addition a + b the addition of a and b
- subtraction a - b the subtraction of b from a
* product a * b the product of a and b
/ division a / b the division of a by b
% remainder a % b the remainder of a divided by b
~ bitwise NOT ~a the bitwise NOT of a
& bitwise AND a & b the bitwise AND of a and b
| bitwise OR a | b the bitwise OR of a and b
^ bitwise XOR a ^ b the bitwise XOR of a and b
<< bitwise left shift a << b a left shifted by b
>> bitwise right shift a >> b a right shifted by b

Overflows

Unsigned integer arithmetic is always performed modulo 2n where n is the number of bits in that particular integer. E.g. for unsigned int, adding one to UINT_MAX gives ​0​, and subtracting one from ​0​ gives UINT_MAX.

+

When signed integer arithmetic operation overflows (the result does not fit in the result type), the behavior is undefined: it may wrap around according to the rules of the representation (typically 2's complement), it may trap on some platforms or due to compiler options (e.g. -ftrapv in GCC and Clang), or may be completely optimized out by the compiler.

+

Floating-point environment

If #pragma STDC FENV_ACCESS is set to ON, all floating-point arithmetic operators obey the current floating-point rounding direction and report floating-point arithmetic errors as specified in math_errhandling unless part of a static initializer (in which case floating-point exceptions are not raised and the rounding mode is to nearest)

+

Floating-point contraction

Unless #pragma STDC FP_CONTRACT is set to OFF, all floating-point arithmetic may be performed as if the intermediate results have infinite range and precision, that is optimizations that omit rounding errors and floating-point exceptions that would be observed if the expression was evaluated exactly as written. For example, allows the implementation of (x*y) + z with a single fused multiply-add CPU instruction or optimization of a = x*x*x*x; as tmp = x*x; a = tmp*tmp.

+

Unrelated to contracting, intermediate results of floating-point arithmetic may have range and precision that is different from the one indicated by its type, see FLT_EVAL_METHOD

+

Unary arithmetic

The unary arithmetic operator expressions have the form

+ + + +
+ expression (1)
- expression (2)
+1) unary plus (promotion)
+2) unary minus (negation)

where

+ + +
expression - expression of any arithmetic type
+

Both unary plus and unary minus first apply integral promotions to their operand, and then

+

The type of the expression is the type after promotion, and the value category is non-lvalue.

+

Notes

The unary minus invokes undefined behavior due to signed integer overflow when applied to INT_MIN, LONG_MIN, or LLONG_MIN, on typical (2's complement) platforms.

+

In C++, unary operator + can also be used with other built-in types such as arrays and functions, not so in C.

+
#include <stdio.h>
+#include <complex.h>
+#include <limits.h>
+ 
+int main(void)
+{
+    char c = 'a';
+    printf("sizeof char: %zu sizeof int: %zu\n", sizeof c, sizeof +c);
+ 
+    printf("-1, where 1 is signed: %d\n", -1);
+ 
+    // Defined behavior since arithmetic is performed for unsigned integer.
+    // Hence, the calculation is (-1) modulo (2 raised to n) = UINT_MAX, where n is
+    // the number of bits of unsigned int. If unsigned int is 32-bit long, then this
+    // gives (-1) modulo (2 raised to 32) = 4294967295
+    printf("-1, where 1 is unsigned: %u\n", -1u); 
+ 
+    // Undefined behavior because the mathematical value of -INT_MIN = INT_MAX + 1
+    // (i.e. 1 more than the maximum possible value for signed int)
+    //
+    // printf("%d\n", -INT_MIN);
+ 
+    // Undefined behavior because the mathematical value of -LONG_MIN = LONG_MAX + 1
+    // (i.e. 1 more than the maximum possible value for signed long)
+    //
+    // printf("%ld\n", -LONG_MIN);
+ 
+    // Undefined behavior because the mathematical value of -LLONG_MIN = LLONG_MAX + 1
+    // (i.e. 1 more than the maximum possible value for signed long long)
+    //
+    // printf("%lld\n", -LLONG_MIN);
+ 
+    double complex z = 1 + 2*I;
+    printf("-(1+2i) = %.1f%+.1f\n", creal(-z), cimag(-z));
+}

Possible output:

+
sizeof char: 1 sizeof int: 4
+-1, where 1 is signed: -1
+-1, where 1 is unsigned: 4294967295
+-(1+2i) = -1.0-2.0

Additive operators

The binary additive arithmetic operator expressions have the form

+ + + +
lhs + rhs (1)
lhs - rhs (2)
+1) addition: lhs and rhs must be one of the following +
+2) subtraction: lhs and rhs must be one of the following +

Arithmetic addition and subtraction

If both operands have arithmetic types, then

+

Complex and imaginary addition and subtraction are defined as follows (note the result type is imaginary if both operands are imaginary and complex if one operand is real and the other imaginary, as specified by the usual arithmetic conversions):

+ + + + + +
+ or - u iv u + iv
x x ± u x ± iv (x ± u) ± iv
iy ±u + iy i(y ± v) ±u + i(y ± v)
x + iy (x ± u) + iy x + i(y ± v) (x ± u) + i(y ± v) 
// work in progress
+// note: take part of the c/language/conversion example

Pointer arithmetic

The behavior is defined only if both the original pointer and the result pointer are pointing at elements of the same array or one past the end of that array. Note that executing p-1 when p points at the first element of an array is undefined behavior and may fail on some platforms.

+

The behavior is defined only if the result fits in ptrdiff_t.

+

For the purpose of pointer arithmetic, a pointer to an object that is not an element of any array is treated as a pointer to the first element of an array of size 1.

+
// work in progress
+int n = 4, m = 3;
+int a[n][m];     // VLA of 4 VLAs of 3 ints each
+int (*p)[m] = a; // p == &a[0] 
+p = p + 1;       // p == &a[1] (pointer arithmetic works with VLAs just the same)
+(*p)[2] = 99;    // changes a[1][2]

Multiplicative operators

The binary multiplicative arithmetic operator expressions have the form

+ + + + +
lhs * rhs (1)
lhs / rhs (2)
lhs % rhs (3)
+1) multiplication. lhs and rhs must have arithmetic types +
+2) division. lhs and rhs must have arithmetic types +
+3) remainder. lhs and rhs must have integer types +

Multiplication

The binary operator * performs multiplication of its operands (after usual arithmetic conversions) following the usual arithmetic definitions, except that

+

Because in C, any complex value with at least one infinite part is an infinity even if its other part is a NaN, the usual arithmetic rules do not apply to complex-complex multiplication. Other combinations of floating operands follow the following table:

+ + + + + +
* u iv u + iv
x xu i(xv) (xu) + i(xv)
iy i(yu) −yv (−yv) + i(yu)
x + iy (xu) + i(yu) (−yv) + i(xv) special rules

Besides infinity handling, complex multiplication is not allowed to overflow intermediate results, except when #pragma STDC CX_LIMITED_RANGE is set to ON, in which case the value may be calculated as if by (x+iy)×(u+iv) = (xu-yv)+i(yu+xv), as the programmer assumes the responsibility of limiting the range of the operands and dealing with the infinities.

+

Despite disallowing undue overflow, complex multiplication may raise spurious floating-point exceptions (otherwise it is prohibitively difficult to implement non-overflowing versions)

+
#include <stdio.h>
+#include <stdio.h>
+#include <complex.h>
+#include <math.h>
+int main(void)
+{
+ 
+ 
+// TODO simpler cases, take some from C++
+ 
+ 
+   double complex z = (1 + 0*I) * (INFINITY + I*INFINITY);
+// textbook formula would give
+// (1+i0)(∞+i∞) ⇒ (1×∞ – 0×∞) + i(0×∞+1×∞) ⇒ NaN + I*NaN
+// but C gives a complex infinity
+   printf("%f + i*%f\n", creal(z), cimag(z));
+ 
+// textbook formula would give
+// cexp(∞+iNaN) ⇒ exp(∞)×(cis(NaN)) ⇒ NaN + I*NaN
+// but C gives  ±∞+i*nan
+   double complex y = cexp(INFINITY + I*NAN);
+   printf("%f + i*%f\n", creal(y), cimag(y));
+ 
+}

Possible output:

+
inf + i*inf 
+inf + i*nan

Division

The binary operator / divides the first operand by the second (after usual arithmetic conversions) following the usual arithmetic definitions, except that

+

Because in C, any complex value with at least one infinite part as an infinity even if its other part is a NaN, the usual arithmetic rules do not apply to complex-complex division. Other combinations of floating operands follow the following table:

+ + + + + +
/ u iv
x x/u i(−x/v)
iy i(y/u) y/v
x + iy (x/u) + i(y/u) (y/v) + i(−x/v)

Besides infinity handling, complex division is not allowed to overflow intermediate results, except when #pragma STDC CX_LIMITED_RANGE is set to ON, in which case the value may be calculated as if by (x+iy)/(u+iv) = [(xu+yv)+i(yu-xv)]/(u2+v2), as the programmer assumes the responsibility of limiting the range of the operands and dealing with the infinities.

+

Despite disallowing undue overflow, complex division may raise spurious floating-point exceptions (otherwise it is prohibitively difficult to implement non-overflowing versions)

+

If the second operand is zero, the behavior is undefined, except that if the IEEE floating-point arithmetic is supported, and the floating-point division is taking place, then

+

Remainder

The binary operator % yields the remainder of the division of the first operand by the second (after usual arithmetic conversions).

+

The sign of the remainder is defined in such a way that if the quotient a/b is representable in the result type, then (a/b)*b + a%b == a.

+

If the second operand is zero, the behavior is undefined.

+

If the quotient a/b is not representable in the result type, the behavior of both a/b and a%b is undefined (that means INT_MIN%-1 is undefined on 2's complement systems)

+

Note: the remainder operator does not work on floating-point types, the library function fmod provides that functionality.

+

Bitwise logic

The bitwise arithmetic operator expressions have the form

+ + + + + +
~ rhs (1)
lhs & rhs (2)
lhs | rhs (3)
lhs ^ rhs (4)
+1) bitwise NOT
+2) bitwise AND
+3) bitwise OR
+4) bitwise XOR

where

+ + +
lhs, rhs - expressions of integer type
+

First, operators &, ^, and | perform usual arithmetic conversions on both operands and the operator ~ performs integer promotions on its only operand.

+

Then, the corresponding binary logic operators are applied bitwise; that is, each bit of the result is set or cleared according to the logic operation (NOT, AND, OR, or XOR), applied to the corresponding bits of the operands.

+

Note: bitwise operators are commonly used to manipulate bit sets and bit masks.

+

Note: for unsigned types (after promotion), the expression ~E is equivalent to the maximum value representable by the result type minus the original value of E.

+
#include <stdio.h>
+#include <stdint.h>
+ 
+int main(void)
+{
+    uint32_t a = 0x12345678;
+    uint16_t mask = 0x00f0;
+ 
+    printf("Promoted mask:\t%#010x\n"
+           "Value:\t\t%#x\n"
+           "Setting bits:\t%#x\n"
+           "Clearing bits:\t%#x\n"
+           "Selecting bits:\t%#010x\n"
+           , mask
+           , a
+           , a | mask
+           , a & ~mask
+           , a & mask
+    );
+}

Possible output:

+
Promoted mask:  0x000000f0
+Value:          0x12345678
+Setting bits:   0x123456f8
+Clearing bits:  0x12345608
+Selecting bits: 0x00000070

Shift operators

The bitwise shift operator expressions have the form

+ + + +
lhs << rhs (1)
lhs >> rhs (2)
+1) left shift of lhs by rhs bits
+2) right shift of lhs by rhs bits

where

+ + +
lhs, rhs - expressions of integer type
+

First, integer promotions are performed, individually, on each operand (Note: this is unlike other binary arithmetic operators, which all perform usual arithmetic conversions). The type of the result is the type of lhs after promotion.

+

The behavior is undefined if rhs is negative or is greater or equal the number of bits in the promoted lhs.

+

For unsigned lhs, the value of LHS << RHS is the value of LHS * 2RHS, reduced modulo maximum value of the return type plus 1 (that is, bitwise left shift is performed and the bits that get shifted out of the destination type are discarded). For signed lhs with nonnegative values, the value of LHS << RHS is LHS * 2RHS if it is representable in the promoted type of lhs, otherwise the behavior is undefined.

+

For unsigned lhs and for signed lhs with nonnegative values, the value of LHS >> RHS is the integer part of LHS / 2RHS. For negative LHS, the value of LHS >> RHS is implementation-defined where in most implementations, this performs arithmetic right shift (so that the result remains negative). Thus in most implementations, right shifting a signed LHS fills the new higher-order bits with the original sign bit (i.e. with 0 if it was non-negative and 1 if it was negative).

+
#include <stdio.h>
+enum {ONE=1, TWO=2};
+int main(void)
+{
+    char c = 0x10;
+    unsigned long long ulong_num = 0x123;
+    printf("0x123 << 1  = %#llx\n"
+           "0x123 << 63 = %#llx\n"   // overflow truncates high bits for unsigned numbers
+           "0x10  << 10 = %#x\n",    // char is promoted to int
+           ulong_num << 1, ulong_num << 63, c << 10);
+    long long long_num = -1000;
+    printf("-1000 >> 1 = %lld\n", long_num >> ONE);  // implementation defined
+}

Possible output:

+
0x123 << 1  = 0x246
+0x123 << 63 = 0x8000000000000000
+0x10  << 10 = 0x4000
+-1000 >> 1 = -500

References

See also

Operator precedence

+ + + +
Common operators
assignment increment
decrement 		arithmetic logical comparison member
access 		other

a = b a += b a -= b a *= b a /= b a %= b a &= b a |= b a ^= b a <<= b a >>= b

+

++a --a a++ a--

+

+a -a a + b a - b a * b a / b a % b ~a a & b a | b a ^ b a << b a >> b

+

!a a && b a || b

+

a == b a != b a < b a > b a <= b a >= b

+

a[b] *a &a a->b a.b

+

a(...) a, b (type) a a ? b : c sizeof

_Alignof
(since C11)

+
+
C++ documentation for Arithmetic operators
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/operator_arithmetic +

+
diff --git a/devdocs/c/language%2Foperator_assignment.html b/devdocs/c/language%2Foperator_assignment.html new file mode 100644 index 00000000..3d44f9ef --- /dev/null +++ b/devdocs/c/language%2Foperator_assignment.html @@ -0,0 +1,139 @@ +

Assignment operators

Assignment and compound assignment operators are binary operators that modify the variable to their left using the value to their right.

+ + + + + + + + + + + + + +
Operator Operator name Example Description Equivalent of
= basic assignment a = b a becomes equal to b N/A
+= addition assignment a += b a becomes equal to the addition of a and b a = a + b
-= subtraction assignment a -= b a becomes equal to the subtraction of b from a a = a - b
*= multiplication assignment a *= b a becomes equal to the product of a and b a = a * b
/= division assignment a /= b a becomes equal to the division of a by b a = a / b
%= modulo assignment a %= b a becomes equal to the remainder of a divided by b a = a % b
&= bitwise AND assignment a &= b a becomes equal to the bitwise AND of a and b a = a & b
|= bitwise OR assignment a |= b a becomes equal to the bitwise OR of a and b a = a | b
^= bitwise XOR assignment a ^= b a becomes equal to the bitwise XOR of a and b a = a ^ b
<<= bitwise left shift assignment a <<= b a becomes equal to a left shifted by b a = a << b
>>= bitwise right shift assignment a >>= b a becomes equal to a right shifted by b a = a >> b

Simple assignment

The simple assignment operator expressions have the form

+ + +
lhs = rhs

where

+ + + +
lhs - modifiable lvalue expression of any complete object type
rhs - expression of any type implicitly convertible to lhs or compatible with lhs

Assignment performs implicit conversion from the value of rhs to the type of lhs and then replaces the value in the object designated by lhs with the converted value of rhs.

+

Assignment also returns the same value as what was stored in lhs (so that expressions such as a = b = c are possible). The value category of the assignment operator is non-lvalue (so that expressions such as (a=b)=c are invalid).

+

rhs and lhs must satisfy one of the following:

+ + +
  • lhs has type (possibly qualified or atomic(since C11)) _Bool and rhs is a pointer or a nullptr_t value(since C23)
(since C99)
+ +
(since C23)

Notes

If rhs and lhs overlap in memory (e.g. they are members of the same union), the behavior is undefined unless the overlap is exact and the types are compatible.

+

Although arrays are not assignable, an array wrapped in a struct is assignable to another object of the same (or compatible) struct type.

+

The side effect of updating lhs is sequenced after the value computations, but not the side effects of lhs and rhs themselves and the evaluations of the operands are, as usual, unsequenced relative to each other (so the expressions such as i=++i; are undefined)

+

Assignment strips extra range and precision from floating-point expressions (see FLT_EVAL_METHOD).

+

In C++, assignment operators are lvalue expressions, not so in C.

+
#include <stdio.h>
+ 
+int main(void)
+{
+    // integers
+    int i = 1, j = 2, k = 3; // initialization, not assignment
+ 
+    i = j = k;   // values of i and j are now 3
+//  (i = j) = k; // Error: lvalue required
+    printf("%d %d %d\n", i, j, k);
+ 
+    // pointers
+    const char c = 'A'; // initialization; not assignment
+    const char *p = &c;  // initialization; not assignment
+    const char **cpp = &p; // initialization; not assignment
+ 
+//  cpp = &p;   // Error: char** is not convertible to const char**
+    *cpp = &c;  // OK, char* is convertible to const char*
+    printf("%c \n", **cpp);
+    cpp = 0;    // OK, null pointer constant is convertible to any pointer
+ 
+    // arrays
+    int arr1[2] = {1,2}, arr2[2] = {3, 4};
+//  arr1 = arr2; // Error: cannot assign to an array
+    printf("arr1[0]=%d arr1[1]=%d arr2[0]=%d arr2[1]=%d\n",
+            arr1[0],   arr1[1],   arr2[0],   arr2[1]);
+ 
+    struct { int arr[2]; } sam1 = { {5, 6} }, sam2 = { {7, 8} };
+    sam1 = sam2; // OK: can assign arrays wrapped in structs
+ 
+    printf("%d %d \n", sam1.arr[0], sam1.arr[1]);
+}

Output:

+
3 3 3
+A
+arr1[0]=1 arr1[1]=2 arr2[0]=3 arr2[1]=4
+7 8

Compound assignment

The compound assignment operator expressions have the form

+ + +
lhs op rhs

where

+ + + +
op - one of *=, /= %=, += -=, <<=, >>=, &=, ^=, |=
lhs, rhs - expressions with arithmetic types (where lhs may be qualified or atomic), except when op is += or -=, which also accept pointer types with the same restrictions as + and -

The expression lhs @= rhs is exactly the same as lhs = lhs @ ( rhs ), except that lhs is evaluated only once.

+ + +

If lhs has atomic type, the operation behaves as a single atomic read-modify-write operation with memory order memory_order_seq_cst.

+

For integer atomic types, the compound assignment @= is equivalent to:

+
T1* addr = &lhs;
+T2 val = rhs;
+T1 old = *addr;
+T1 new;
+do { new = old @ val } while (!atomic_compare_exchange_strong(addr, &old, new);
 (since C11)
#include <stdio.h>
+ 
+int main(void)
+{
+    int x = 10; 
+    int hundred = 100; 
+    int ten = 10; 
+    int fifty = 50; 
+ 
+    printf("%d %d %d %d\n", x, hundred, ten, fifty);
+ 
+    hundred *= x; 
+    ten     /= x; 
+    fifty   %= x; 
+ 
+    printf("%d %d %d %d\n", x, hundred, ten, fifty);
+ 
+    return 0;
+}

Output:

+
10 100 10 50
+10 1000 1 0

References

See Also

Operator precedence

+ + + +
Common operators
assignment increment
decrement 		arithmetic logical comparison member
access 		other

a = b a += b a -= b a *= b a /= b a %= b a &= b a |= b a ^= b a <<= b a >>= b

+

++a --a a++ a--

+

+a -a a + b a - b a * b a / b a % b ~a a & b a | b a ^ b a << b a >> b

+

!a a && b a || b

+

a == b a != b a < b a > b a <= b a >= b

+

a[b] *a &a a->b a.b

+

a(...) a, b (type) a a ? b : c sizeof

_Alignof
(since C11)

+

See also

+
C++ documentation for Assignment operators
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/operator_assignment +

+
diff --git a/devdocs/c/language%2Foperator_comparison.html b/devdocs/c/language%2Foperator_comparison.html new file mode 100644 index 00000000..cd1e66ad --- /dev/null +++ b/devdocs/c/language%2Foperator_comparison.html @@ -0,0 +1,149 @@ +

Comparison operators

Comparison operators are binary operators that test a condition and return 1 if that condition is logically true and 0 if that condition is false.

+ + + + + + + + +
Operator Operator name Example Description
== equal to a == b a is equal to b
!= not equal to a != b a is not equal to b
< less than a < b a is less than b
> greater than a > b a is greater than b
<= less than or equal to a <= b a is less than or equal to b
>= greater than or equal to a >= b a is greater than or equal to b

Relational operators

The relational operator expressions have the form

+ + + + + +
lhs < rhs (1)
lhs > rhs (2)
lhs <= rhs (3)
lhs >= rhs (4)
+1) less-than expression
+2) greater-than expression
+3) less or equal expression
+4) greater or equal expression

where

+ + +
lhs, rhs - expressions that both have real type or both have pointer to object type
+

The type of any relational operator expression is int, and its value (which is not an lvalue) is 1 when the specified relationship holds true and ​0​ when the specified relationship does not hold.

+

If lhs and rhs are expressions of any real type, then

+

Note that complex and imaginary numbers cannot be compared with these operators.

+

If lhs and rhs are expressions of pointer type, they must be both pointers to objects of compatible types, except that qualifications of the pointed-to objects are ignored.

+ 
#include <assert.h>
+int main(void)
+{
+    assert(1 < 2);
+    assert(2+2 <= 4.0); // int converts to double, two 4.0's compare equal
+ 
+    struct { int x,y; } s;
+    assert(&s.x < &s.y); // struct members compare in order of declaration
+ 
+    double d = 0.0/0.0; // NaN
+    assert( !(d < d) );
+    assert( !(d > d) );
+    assert( !(d <= d) );
+    assert( !(d >= d) );
+    assert( !(d == d) );
+ 
+    float f = 0.1; // f = 0.100000001490116119384765625
+    double g = 0.1; // g = 0.1000000000000000055511151231257827021181583404541015625
+    assert(f > g); // different values
+}

Equality operators

The equality operator expressions have the form

+ + + +
lhs == rhs (1)
lhs != rhs (2)
+1) equal-to expression
+2) not equal to expression

where

+ + +
lhs, rhs - expressions that + +
    +
  • both have type nullptr_t
    • +
  • one has type nullptr_t and the other is a null pointer constant
    • +
 (since C23)
    +
  • both are pointers to objects or functions of compatible types, ignoring qualifiers of the pointed-to types
    • +
  • one is a pointer to object and the other is a pointer to (possibly qualified) void
    • +
  • one is a pointer to object or function and the other is a null pointer constant such as NULL or nullptr(since C23)
    • +
+

The type of any equality operator expression is int, and its value (which is not an lvalue) is 1 when the specified relationship holds true and ​0​ when the specified relationship does not hold.

+ + +
(since C23)

(as with relational operators, pointers to objects that aren't elements of any array behave as pointers to elements of arrays of size 1)

+

Notes

Objects of struct type do not compare equal automatically, and comparing them with memcmp is not reliable because the padding bytes may have any values.

+

Because pointer comparison works with pointers to void, the macro NULL may be defined as (void*)0 in C, although that would be invalid in C++ where void pointers do not implicitly convert to typed pointers

+

Care must be taken when comparing floating-point values for equality, because the results of many operations cannot be represented exactly and must be rounded. In practice, floating-point numbers are usually compared allowing for the difference of one or more units of the last place.

+
#include <assert.h>
+int main(void)
+{
+    assert(2+2 == 4.0); // int converts to double, two 4.0's compare equal
+ 
+    int n[2][3] = {1,2,3,4,5,6};
+    int* p1 = &n[0][2]; // last element in the first row
+    int* p2 = &n[1][0]; // start of second row
+    assert(p1+1 == p2); // compare equal
+ 
+    double d = 0.0/0.0; // NaN
+    assert( d != d ); // NaN does not equal itself
+ 
+    float f = 0.1; // f = 0.100000001490116119384765625
+    double g = 0.1; // g = 0.1000000000000000055511151231257827021181583404541015625
+    assert(f != g); // different values
+}

References

See also

Operator precedence

+ + + +
Common operators
assignment increment
decrement 		arithmetic logical comparison member
access 		other

a = b a += b a -= b a *= b a /= b a %= b a &= b a |= b a ^= b a <<= b a >>= b

+

++a --a a++ a--

+

+a -a a + b a - b a * b a / b a % b ~a a & b a | b a ^ b a << b a >> b

+

!a a && b a || b

+

a == b a != b a < b a > b a <= b a >= b

+

a[b] *a &a a->b a.b

+

a(...) a, b (type) a a ? b : c sizeof

_Alignof
(since C11)

+
+
C++ documentation for Comparison operators
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/operator_comparison +

+
diff --git a/devdocs/c/language%2Foperator_incdec.html b/devdocs/c/language%2Foperator_incdec.html new file mode 100644 index 00000000..37060cb3 --- /dev/null +++ b/devdocs/c/language%2Foperator_incdec.html @@ -0,0 +1,98 @@ +

Increment/decrement operators

Increment/decrement operators are unary operators that increment/decrement the value of a variable by 1.

+

They can have postfix form:

+ + + +
expr ++
expr --

As well as the prefix form:

+ + + +
++ expr
-- expr

The operand expr of both prefix and postfix increment or decrement must be a modifiable lvalue of integer type (including _Bool and enums), real floating type, or a pointer type. It may be cvr-qualified, unqualified, or atomic.

+

The result of the postfix increment and decrement operators is the value of expr.

+

The result of the prefix increment operator is the result of adding the value 1 to the value of expr: the expression ++e is equivalent to e += 1. The result of the prefix decrement operator is the result of subtracting the value 1 from the value of expr: the expression --e is equivalent to e -= 1.

+

Increment operators initiate the side-effect of adding the value 1 of appropriate type to the operand. Decrement operators initiate the side-effect of subtracting the value 1 of appropriate type from the operand. As with any other side-effects, these operations complete at or before the next sequence point.

+
int a = 1;
+int b = a++; // stores 1+a (which is 2) to a
+             // returns the old value of a (which is 1)
+             // After this line, b == 1 and a == 2
+a = 1;
+int c = ++a; // stores 1+a (which is 2) to a
+             // returns 1+a (which is 2)
+             // after this line, c == 2 and a == 2
+ +

Post-increment or post-decrement on any atomic variable is an atomic read-modify-write operation with memory order memory_order_seq_cst.

+		 (since C11)

See arithmetic operators for limitations on pointer arithmetic, as well as for implicit conversions applied to the operands.

+

Notes

Because of the side-effects involved, increment and decrement operators must be used with care to avoid undefined behavior due to violations of sequencing rules.

+

Increment/decrement operators are not defined for complex or imaginary types: the usual definition of adding/subtracting the real number 1 would have no effect on imaginary types, and making it add/subtract i for imaginaries but 1 for complex numbers would have made it handle 0+yi different from yi.

+

Unlike C++ (and some implementations of C), the increment/decrement expressions are never themselves lvalues: &++a is invalid.

+

Example

#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    int a = 1;
+    int b = 1;
+ 
+    printf("original values: a == %d, b == %d\n", a, b);
+    printf("result of postfix operators: a++ == %d, b-- == %d\n", a++, b--);
+    printf("after postfix operators applied: a == %d, b == %d\n", a, b);
+    printf("\n");
+ 
+    // Reset a and b.
+    a = 1;
+    b = 1;
+ 
+    printf("original values: a == %d, b == %d\n", a, b);
+    printf("result of prefix operators: ++a == %d, --b == %d\n", ++a, --b);
+    printf("after prefix operators applied: a == %d, b == %d\n", a, b);
+}

Output:

+
original values: a == 1, b == 1
+result of postfix operators: a++ == 1, b-- == 1
+after postfix operators applied: a == 2, b == 0
+ 
+original values: a == 1, b == 1
+result of prefix operators: ++a == 2, --b == 0
+after prefix operators applied: a == 2, b == 0

References

See also

Operator precedence

+ + + +
Common operators
assignment increment
decrement 		arithmetic logical comparison member
access 		other

a = b a += b a -= b a *= b a /= b a %= b a &= b a |= b a ^= b a <<= b a >>= b

+

++a --a a++ a--

+

+a -a a + b a - b a * b a / b a % b ~a a & b a | b a ^ b a << b a >> b

+

!a a && b a || b

+

a == b a != b a < b a > b a <= b a >= b

+

a[b] *a &a a->b a.b

+

a(...) a, b (type) a a ? b : c sizeof

_Alignof
(since C11)

+
+
C++ documentation for Increment/decrement operators
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/operator_incdec +

+
diff --git a/devdocs/c/language%2Foperator_logical.html b/devdocs/c/language%2Foperator_logical.html new file mode 100644 index 00000000..bdc70465 --- /dev/null +++ b/devdocs/c/language%2Foperator_logical.html @@ -0,0 +1,111 @@ +

Logical operators

Logical operators apply standard boolean algebra operations to their operands.

+ + + + + +
Operator Operator name Example Result
! logical NOT !a the logical negation of a
&& logical AND a && b the logical AND of a and b
|| logical OR a || b the logical OR of a and b

Logical NOT

The logical NOT expression has the form

+ + +
! expression

where

+ + +
expression - an expression of any scalar type

The logical NOT operator has type int. Its value is ​0​ if expression evaluates to a value that compares unequal to zero. Its value is 1 if expression evaluates to a value that compares equal to zero. (so !E is the same as (0==E))

+
#include <stdbool.h>
+#include <stdio.h>
+#include <ctype.h>
+int main(void)
+{
+    bool b = !(2+2 == 4); // not true
+    printf("!(2+2==4) = %s\n", b ? "true" : "false");
+ 
+    int n = isspace('a'); // zero if 'a' is a space, nonzero otherwise
+    int x = !!n; // "bang-bang", common C idiom for mapping integers to [0,1]
+                 // (all non-zero values become 1)
+    char *a[2] = {"nonspace", "space"};
+    printf("%s\n", a[x]); // now x can be safely used as an index to array of 2 ints
+}

Output:

+
!(2+2==4) = false
+nonspace

Logical AND

The logical AND expression has the form

+ + +
lhs && rhs

where

+ + + +
lhs - an expression of any scalar type
rhs - an expression of any scalar type, which is only evaluated if lhs does not compare equal to ​0​

The logical-AND operator has type int and the value 1 if both lhs and rhs compare unequal to zero. It has the value ​0​ otherwise (if either lhs or rhs or both compare equal to zero).

+

There is a sequence point after the evaluation of lhs. If the result of lhs compares equal to zero, then rhs is not evaluated at all (so-called short-circuit evaluation)

+
#include <stdbool.h>
+#include <stdio.h>
+int main(void)
+{
+    bool b = 2+2==4 && 2*2==4; // b == true
+ 
+    1 > 2 && puts("this won't print");
+ 
+    char *p = "abc";
+    if(p && *p) // common C idiom: if p is not null
+                // AND if p does not point at the end of the string
+    {           // (note that thanks to short-circuit evaluation, this
+                //  will not attempt to dereference a null pointer)
+    // ...      // ... then do some string processing
+    }
+}

Logical OR

The logical OR expression has the form

+ + +
lhs || rhs

where

+ + + +
lhs - an expression of any scalar type
rhs - an expression of any scalar type, which is only evaluated if lhs compares equal to ​0​

The logical-OR operator has type int and the value 1 if either lhs or rhs compare unequal to zero. It has value ​0​ otherwise (if both lhs and rhs compare equal to zero).

+

There is a sequence point after the evaluation of lhs. If the result of lhs compares unequal to zero, then rhs is not evaluated at all (so-called short-circuit evaluation)

+
#include <stdbool.h>
+#include <stdio.h>
+#include <string.h>
+#include <errno.h>
+int main(void)
+{
+    bool b = 2+2 == 4 || 2+2 == 5; // true
+    printf("true or false = %s\n", b ? "true" : "false");
+ 
+    // logical OR can be used simialar to perl's "or die", as long as rhs has scalar type
+    fopen("test.txt", "r") || printf("could not open test.txt: %s\n", strerror(errno));
+}

Possible output:

+
true or false = true
+could not open test.txt: No such file or directory

References

See Also

Operator precedence

+ + + +
Common operators
assignment increment
decrement 		arithmetic logical comparison member
access 		other

a = b a += b a -= b a *= b a /= b a %= b a &= b a |= b a ^= b a <<= b a >>= b

+

++a --a a++ a--

+

+a -a a + b a - b a * b a / b a % b ~a a & b a | b a ^ b a << b a >> b

+

!a a && b a || b

+

a == b a != b a < b a > b a <= b a >= b

+

a[b] *a &a a->b a.b

+

a(...) a, b (type) a a ? b : c sizeof

_Alignof
(since C11)

+

See also

+
C++ documentation for Logical operators
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/operator_logical +

+
diff --git a/devdocs/c/language%2Foperator_member_access.html b/devdocs/c/language%2Foperator_member_access.html new file mode 100644 index 00000000..f455d3f8 --- /dev/null +++ b/devdocs/c/language%2Foperator_member_access.html @@ -0,0 +1,170 @@ +

Member access operators

Member access operators allow access to the members of their operands.

+ + + + + + + +
Operator Operator name Example Description
[] array subscript a[b] access the bth element of array a
* pointer dereference *a dereference the pointer a to access the object or function it refers to
& address of &a create a pointer that refers to the object or function a
. member access a.b access member b of struct or union a
-> member access through pointer a->b access member b of struct or union pointed to by a

Subscript

The array subscript expression has the form

+ + + +
pointer-expression [ integer-expression ] (1)
integer-expression [ pointer-expression ] (2)

where

+ + + +
pointer-expression - an expression of type pointer to complete object
integer-expression - an expression of integer type

The subscript operator expression is an lvalue expression whose type is the type of the object pointed to by pointer-expression.

+

By definition, the subscript operator E1[E2] is exactly identical to *((E1)+(E2)). If pointer-expression is an array expression, it undergoes lvalue-to-rvalue conversion and becomes a pointer to the first element of the array.

+

Due to the definition of the addition between a pointer and an integer, the result is the element of the array with the index equal to the result of integer-expression (or, if pointer-expression was pointing at ith element of some array, the index of the result is i plus the result of integer-expression)

+

Note: see array for the details on multidimensional arrays.

+
#include <stdio.h>
+int main(void)
+{
+    int a[3] = {1,2,3};
+    printf("%d %d\n", a[2],  // n == 3
+                      2[a]); // same, n == 3
+    a[2] = 7; // subscripts are lvalues
+ 
+    int n[2][3] = {{1,2,3},{4,5,6}};
+    int (*p)[3] = &n[1]; // elements of n are arrays
+    printf("%d %d %d\n", (*p)[0], p[0][1], p[0][2]); // access n[1][] via p
+    int x = n[1][2]; // applying [] again to the array n[1]
+    printf("%d\n", x);
+ 
+    printf("%c %c\n", "abc"[2], 2["abc"]); // string literals are arrays too
+}

Output:

+
3 3
+4 5 6
+6
+c c

Dereference

The dereference or indirection expression has the form

+ + +
* pointer-expression

where

+ + +
pointer-expression - an expression of any pointer type

If pointer-expression is a pointer to function, the result of the dereference operator is a function designator for that function.

+

If pointer-expression is a pointer to object, the result is an lvalue expression that designates the pointed-to object.

+

Dereferencing a null pointer, a pointer to an object outside of its lifetime (a dangling pointer), a misaligned pointer, or a pointer with indeterminate value is undefined behavior, except when the dereference operator is nullified by applying the address-of operator to its result, as in &*E.

+
#include <stdio.h>
+int main(void)
+{
+    int n = 1;
+    int* p = &n;
+    printf("*p = %d\n", *p); // the value of *p is what's stored in n
+    *p = 7; // *p is lvalue
+    printf("*p = %d\n", *p);
+}

Output:

+
*p = 1
+*p = 7

Address of

The address-of expression has the form

+ + + + + +
& function (1)
& lvalue-expression (2)
& * expression (3)
& expression [ expression ] (4)
+1) address of a function
+2) address of an object
+3) special case: & and * cancel each other, neither one is evaluated
+4) special case: & and the * that is implied in [] cancel each other, only the addition implied in [] is evaluated.

where

+ + +
lvalue-expression - an lvalue expression of any type that is not a bit-field and does not have register storage class

The address-of operator produces the non-lvalue address of its operand, suitable for initializing a pointer to the type of the operand. If the operand is a function designator (1), the result is a pointer to function. If the operand is an object (2), the result is a pointer to object.

+

If the operand is the dereference operator, no action is taken (so it's okay to apply &* to a null pointer), except that the result is not an lvalue.

+

If the operand is an array index expression, no action is taken other than the array-to-pointer conversion and the addition, so &a[N] is valid for an array of size N (obtaining a pointer one past the end is okay, dereferencing it is not, but dereference cancels out in this expression).

+
int f(char c) { return c;}
+int main(void)
+{
+   int n = 1;
+   int *p = &n; // address of object n
+   int (*fp)(char) = &f; // address of function f
+   int a[3] = {1,2,3};
+   int *beg=a, *end=&a[3]; // same as end = a+3
+}

Member access

The member access expression has the form

+ + +
expression . member-name

where

+ + + +
expression - an expression of struct or union type
member-name - an identifier that names a member of the struct or union designated by expression

The member access expression designates the named member of the struct or union designated by its left operand. It has the same value category as its left operand.

+

If the left operand is const or volatile qualified, the result is also qualified. If the left operand is atomic, the behavior is undefined.

+

Note: besides identifiers that name objects of struct or union type, the following expressions may have struct or union types: assignment, function call, comma operator, conditional operator, and compound literal.

+
#include <stdio.h>
+struct s {int x;};
+struct s f(void) { return (struct s){1}; }
+int main(void)
+{
+    struct s s;
+    s.x = 1; // ok, changes the member of s
+    int n = f().x; // f() is an expression of type struct s
+//  f().x = 1; // Error: this member access expression is not an lvalue
+ 
+    const struct s sc;
+//  sc.x = 3;  // Error: sc.x is const, can't be assigned
+ 
+    union { int x; double d; } u = {1};
+    u.d = 0.1; // changes the active member of the union
+}

Member access through pointer

The member access expression has the form

+ + +
expression -> member-name

where

+ + + +
expression - an expression of type pointer to struct or union
member-name - an identifier that names a member of the struct or union pointed by expression

The member access through pointer expression designates the named member of the struct or union type pointed to by its left operand. Its value category is always lvalue

+

If the type pointed to by the left operand is const or volatile qualified, the result is also qualified. If the type pointed to by the left operand is atomic, the behavior is undefined.

+
#include <stdio.h>
+struct s {int x;};
+int main(void)
+{
+    struct s s={1}, *p = &s;
+    p->x = 7; // changes the value of s.x through the pointer
+    printf("%d\n", p->x); // prints 7
+}

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C standards.

+ + + +
DR Applied to Behavior as published Correct behavior
+DR 076 C89 unnessary indirection could not be cancelled by & made cancellable

References

See also

+ + +
Common operators
assignment increment
decrement 		arithmetic logical comparison member
access 		other

a = b a += b a -= b a *= b a /= b a %= b a &= b a |= b a ^= b a <<= b a >>= b

+

++a --a a++ a--

+

+a -a a + b a - b a * b a / b a % b ~a a & b a | b a ^ b a << b a >> b

+

!a a && b a || b

+

a == b a != b a < b a > b a <= b a >= b

+

a[b] *a &a a->b a.b

+

a(...) a, b (type) a a ? b : c sizeof

_Alignof
(since C11)

+
+
C++ documentation for Member access operators
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/operator_member_access +

+
diff --git a/devdocs/c/language%2Foperator_other.html b/devdocs/c/language%2Foperator_other.html new file mode 100644 index 00000000..195b38dd --- /dev/null +++ b/devdocs/c/language%2Foperator_other.html @@ -0,0 +1,225 @@ +

Other operators

A collection of operators that do not fit into any of the other major categories.

+ + + + + + + + + +
Operator Operator name Example Description
(...) function call f(...) call the function f(), with zero or more arguments
, comma operator a, b evaluate expression a, disregard its return value and complete any side-effects, then evaluate expression b, returning the type and the result of this evaluation
(type) type cast (type)a cast the type of a to type
? : conditional operator a ? b : c if a is logically true (does not evaluate to zero) then evaluate expression b, otherwise evaluate expression c
sizeof sizeof operator sizeof a the size in bytes of a
_Alignof
(since C11) 		_Alignof operator _Alignof(type) the alignment required of type
typeof typeof operators typeof(a) the type of a

Function call

The function call expression has the form

+ + +
expression ( argument-list (optional) )

where

+ + + +
expression - any expression of pointer-to-function type (after lvalue conversions)
argument-list - comma-separated list of expressions (which cannot be comma operators) of any complete object type. May be omitted when calling functions that take no arguments.

The behavior of the function call expression depends on whether the prototype of the function being called is in scope at the point of call.

+

Call to a function with a prototype

+1) The number of parameters must equal the number of arguments (unless the ellipsis parameter is used).
+2) The type of each parameter must be a type such that implicit conversion as if by assignment exists that converts the unqualified type of the corresponding argument to the type of the parameter.
+ +
Additionally, for every parameter of array type that uses the keyword static between [ and ], the argument expression must designate a pointer to the element of an array with at least that many elements as specified in the size expression of the parameter. (since C99)
+3) The arguments are evaluated in unspecified order and without sequencing.
+4) Assignment is performed to copy the value of each argument to the corresponding function parameter, ignoring any type qualifiers on the parameter type and its possibly recursive elements or members, if any (note: the function can modify its parameters, and those changes do not affect the arguments; C function calls are only call-by-value). +
+5) Function is executed, and the value it returns becomes the value of the function call expression (if the function returns void, the function call expression is a void expression) 
void f(char* p, int x) {}
+int main(void)
+{
+    f("abc", 3.14); // array to pointer and float to int conversions
+}
+
+ +

Call to a function without a prototype

1) The arguments are evaluated in unspecified order and without sequencing. 2) Default argument promotions are performed on every argument expression. 3) Assignment is performed to copy the value of each argument to the corresponding function parameter, ignoring any type qualifiers on the parameter type and its possibly recursive elements or members, if any. 4) Function is executed, and the value it returns becomes the value of the function call expression (if the function returns void, the function call expression is a void expression) 
void f(); // no prototype
+int main(void)
+{
+    f(1, 1.0f); // UB unless f is defined to take an int and a double
+}
+void f(int a, double c) {}

The behavior of a function call to a function without a prototype is undefined if

+
    +
  • the number of arguments does not match the number of parameters.
    • +
  • the promoted types of the arguments are not compatible with the promoted types of the parameters except that
    • +
      +
    • signed and unsigned versions of the same integer type are considered compatible if the value of the argument is representable by both types.
      • +
    • pointers to void and pointers to (possibly cvr-qualified) character types are considered compatible
      • +
    +
 (until C23)

Notes

The evaluations of expression that designates the function to be called and all arguments are unsequenced with respect to each other (but there is a sequence point before the body of the function begins executing)

+
(*pf[f1()]) (f2(), f3() + f4()); // f1, f2, f3, f4 may be called in any order

Although function call is only defined for pointers to functions, it works with function designators due to the function-to-pointer implicit conversion.

+
int f(void) { return 1; }
+int (*pf)(void) = f;
+ 
+int main(void)
+{
+    f();    // convert f to pointer, then call
+    (&f)(); // create a pointer to function, then call
+ 
+    pf();    // call the function
+    (*pf)(); // obtain the function designator, convert to pointer, then calls
+ 
+    (****f)(); // convert to pointer, obtain the function, repeat 4x, then call
+    (****pf)(); // also OK
+}

Functions that ignore unused arguments, such as printf, must be called with a prototype in scope (the prototype of such functions necessarily uses the trailing ellipsis parameter) to avoid invoking undefined behavior.

+

The current standard wording of the semantics of preparing function parameters is defective, because it specifies that parameters are assigned from arguments while calling, which incorrectly rejects const-qualified parameter or member types, and inappropriately applies the semantics of volatile which is unimplementable for function parameters on many platforms. A post-C11 defect report DR427 proposed change of such semantics from assignment to initialization, but was closed as not-a-defect.

+ + +

A function call expression where expression consists entirely of an identifier and that identifier is undeclared acts as though the identifier is declared as

+
extern int identifier(); // returns int and has no prototype

So the following complete program is valid C89:

+
main()
+{
+    int n = atoi("123"); // implicitly declares atoi as int atoi()
+}
 (until C99)

Comma operator

The comma operator expression has the form

+ + +
lhs , rhs

where

+ + + +
lhs - any expression
rhs - any expression other than another comma operator (in other words, comma operator's associativity is left-to-right)

First, the left operand, lhs, is evaluated and its result value is discarded.

+

Then, a sequence point takes place, so that all side effects of lhs are complete.

+

Then, the right operand, rhs, is evaluated and its result is returned by the comma operator as a non-lvalue.

+

Notes

The type of the lhs may be void (that is, it may be a call to a function that returns void, or it can be an expression cast to void)

+

The comma operator may be lvalue in C++, but never in C

+

The comma operator may return a struct (the only other expressions that return structs are compound literals, function calls, assignments, and the conditional operator)

+

In the following contexts, the comma operator cannot appear at the top level of an expression because the comma has a different meaning:

+

If the comma operator has to be used in such context, it must be parenthesized:

+
// int n = 2,3; // error, comma assumed to begin the next declarator
+// int a[2] = {1,2,3}; // error: more initializers than elements
+int n = (2,3), a[2] = {(1,2),3}; // OK
+ 
+f(a, (t=3, t+2), c); // OK, first, stores 3 in t, then calls f with three arguments

Top-level comma operator is also disallowed in array bounds

+
// int a[2,3]; // error
+int a[(2,3)]; // OK, VLA array of size 3 (VLA because (2,3) is not a constant expression)

Comma operator is not allowed in constant expressions, regardless of whether it's on the top level or not

+
// static int n = (1,2); // Error: constant expression cannot call the comma operator

Cast operator

See cast operator

+

Conditional operator

The conditional operator expression has the form

+ + +
condition ? expression-true : expression-false

where

+ + + + +
condition - an expression of scalar type
expression-true - the expression that will be evaluated if condition compares unequal to zero
expression-false - the expression that will be evaluated if condition compares equal to zero

Only the following expressions are allowed as expression-true and expression-false

+ + +
(since C23)
+1) First, evaluates condition. There is a sequence point after this evaluation.
+2) If the result of condition compares unequal to zero, executes expression-true, otherwise executes expression-false +
+3) Performs a conversion from the result of the evaluation to the common type, defined as follows:
+1) if the expressions have arithmetic type, the common type is the type after usual arithmetic conversions +
+2) if the expressions have struct/union type, the common type is that struct/union type
+3) if the expressions are both void, the entire conditional operator expression is a void expression
+4) if one is a pointer and the other is a null pointer constantor a nullptr_t value(since C23), the type is the type of that pointer
+5) if both are pointers, the result is the pointer to the type that combines cvr-qualifiers of both pointed-to types (that is, if one is const int* and the other is volatile int*, the result is const volatile int*), and if the types were different, the pointed-to type is the composite type.
+6) if one is a pointer to void, the result is a pointer to void with combined cvr-qualifiers
+ +
7) if both have nullptr_t type, the common type is also nullptr_t (since C23)
#define ICE(x) (sizeof(*(1 ? ((void*)((x) * 0l)) : (int*)1)))
+ 
+// if x is an Integer Constant Expression then macro expands to
+ 
+sizeof(*(1 ? NULL : (int *) 1))  // (void *)((x)*0l)) -> NULL
+ 
+// according to point (4) this further converts into
+ 
+sizeof(int)
+ 
+// if x is not an Integer Constant Expression then macro expands to
+// according to point (6)
+ 
+(sizeof(*(void *)(x))           // Error due incomplete type

Notes

The conditional operator is never an lvalue expression, although it may return objects of struct/union type. The only other expressions that may return structs are assignment, comma, function call, and compound literal.

+

Note that in C++, it may be an lvalue expression.

+

See operator precedence for the details on the relative precedence of this operator and assignment.

+

Conditional operator has right-to-left associativity, which allows chaining

+
#include <assert.h>
+ 
+enum vehicle { bus, airplane, train, car, horse, feet };
+ 
+enum vehicle choose(char arg)
+{
+    return arg == 'B' ? bus      :
+           arg == 'A' ? airplane :
+           arg == 'T' ? train    :
+           arg == 'C' ? car      :
+           arg == 'H' ? horse    :
+                        feet     ;
+}
+ 
+int main(void)
+{
+    assert(choose('H') == horse && choose('F') == feet);
+}

sizeof operator

See sizeof operator

+

_Alignof operator

See _Alignof operator

+

typeof operators

See typeof operators

+

References

See also

+ + +
Common operators
assignment increment
decrement 		arithmetic logical comparison member
access 		other

a = b a += b a -= b a *= b a /= b a %= b a &= b a |= b a ^= b a <<= b a >>= b

+

++a --a a++ a--

+

+a -a a + b a - b a * b a / b a % b ~a a & b a | b a ^ b a << b a >> b

+

!a a && b a || b

+

a == b a != b a < b a > b a <= b a >= b

+

a[b] *a &a a->b a.b

+

a(...) a, b (type) a a ? b : c sizeof

_Alignof
(since C11)

+
+
C++ documentation for Other operators
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/operator_other +

+
diff --git a/devdocs/c/language%2Foperator_precedence.html b/devdocs/c/language%2Foperator_precedence.html new file mode 100644 index 00000000..38517274 --- /dev/null +++ b/devdocs/c/language%2Foperator_precedence.html @@ -0,0 +1,68 @@ +

C Operator Precedence

The following table lists the precedence and associativity of C operators. Operators are listed top to bottom, in descending precedence.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Precedence Operator Description Associativity
1 ++ -- Suffix/postfix increment and decrement Left-to-right
() Function call
[] Array subscripting
. Structure and union member access
-> Structure and union member access through pointer
(type){list} Compound literal(C99)
2 ++ -- Prefix increment and decrement[note 1] Right-to-left
+ - Unary plus and minus
! ~ Logical NOT and bitwise NOT
(type) Cast
* Indirection (dereference)
& Address-of
sizeof Size-of[note 2]
_Alignof Alignment requirement(C11)
3 * / % Multiplication, division, and remainder Left-to-right
4 + - Addition and subtraction
5 << >> Bitwise left shift and right shift
6 < <= For relational operators < and ≤ respectively
> >= For relational operators > and ≥ respectively
7 == != For relational = and ≠ respectively
8 & Bitwise AND
9 ^ Bitwise XOR (exclusive or)
10 | Bitwise OR (inclusive or)
11 && Logical AND
12 || Logical OR
13 ?: Ternary conditional[note 3] Right-to-left
14[note 4] = Simple assignment
+= -= Assignment by sum and difference
*= /= %= Assignment by product, quotient, and remainder
<<= >>= Assignment by bitwise left shift and right shift
&= ^= |= Assignment by bitwise AND, XOR, and OR
15 , Comma Left-to-right
  1. The operand of prefix ++ and -- can't be a type cast. This rule grammatically forbids some expressions that would be semantically invalid anyway. Some compilers ignore this rule and detect the invalidity semantically.
  2. The operand of sizeof can't be a type cast: the expression sizeof (int) * p is unambiguously interpreted as (sizeof(int)) * p, but not sizeof((int)*p).
  3. The expression in the middle of the conditional operator (between ? and :) is parsed as if parenthesized: its precedence relative to ?: is ignored.
  4. Assignment operators' left operands must be unary (level-2 non-cast) expressions. This rule grammatically forbids some expressions that would be semantically invalid anyway. Many compilers ignore this rule and detect the invalidity semantically. For example, e = a < d ? a++ : a = d is an expression that cannot be parsed because of this rule. However, many compilers ignore this rule and parse it as e = ( ((a < d) ? (a++) : a) = d ), and then give an error because it is semantically invalid.

When parsing an expression, an operator which is listed on some row will be bound tighter (as if by parentheses) to its arguments than any operator that is listed on a row further below it. For example, the expression *p++ is parsed as *(p++), and not as (*p)++.

+

Operators that are in the same cell (there may be several rows of operators listed in a cell) are evaluated with the same precedence, in the given direction. For example, the expression a=b=c is parsed as a=(b=c), and not as (a=b)=c because of right-to-left associativity.

+

Notes

Precedence and associativity are independent from order of evaluation.

+

The standard itself doesn't specify precedence levels. They are derived from the grammar.

+

In C++, the conditional operator has the same precedence as assignment operators, and prefix ++ and -- and assignment operators don't have the restrictions about their operands.

+

Associativity specification is redundant for unary operators and is only shown for completeness: unary prefix operators always associate right-to-left (sizeof ++*p is sizeof(++(*p))) and unary postfix operators always associate left-to-right (a[1][2]++ is ((a[1])[2])++). Note that the associativity is meaningful for member access operators, even though they are grouped with unary postfix operators: a.b++ is parsed (a.b)++ and not a.(b++).

+

References

See also

Order of evaluation of operator arguments at run time.

+ + + +
Common operators
assignment increment
decrement 		arithmetic logical comparison member
access 		other

a = b a += b a -= b a *= b a /= b a %= b a &= b a |= b a ^= b a <<= b a >>= b

+

++a --a a++ a--

+

+a -a a + b a - b a * b a / b a % b ~a a & b a | b a ^ b a << b a >> b

+

!a a && b a || b

+

a == b a != b a < b a > b a <= b a >= b

+

a[b] *a &a a->b a.b

+

a(...) a, b (type) a a ? b : c sizeof

_Alignof
(since C11)

+
+
C++ documentation for C++ operator precedence
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/operator_precedence +

+
diff --git a/devdocs/c/language%2Fpointer.html b/devdocs/c/language%2Fpointer.html new file mode 100644 index 00000000..5c39408c --- /dev/null +++ b/devdocs/c/language%2Fpointer.html @@ -0,0 +1,95 @@ +

Pointer declaration

Pointer is a type of an object that refers to a function or an object of another type, possibly adding qualifiers. Pointer may also refer to nothing, which is indicated by the special null pointer value.

+

Syntax

In the declaration grammar of a pointer declaration, the type-specifier sequence designates the pointed-to type (which may be function or object type and may be incomplete), and the declarator has the form:

+ + +
* attr-spec-seq(optional) qualifiers(optional) declarator

where declarator may be the identifier that names the pointer being declared, including another pointer declarator (which would indicate a pointer to a pointer):

+
float *p, **pp; // p is a pointer to float
+                // pp is a pointer to a pointer to float
+int (*fp)(int); // fp is a pointer to function with type int(int)

The qualifiers that appear between * and the identifier (or other nested declarator) qualify the type of the pointer that is being declared:

+
int n;
+const int * pc = &n; // pc is a non-const pointer to a const int
+// *pc = 2; // Error: n cannot be changed through pc without a cast
+pc = NULL; // OK: pc itself can be changed
+ 
+int * const cp = &n; // cp is a const pointer to a non-const int
+*cp = 2; // OK to change n through cp
+// cp = NULL; // Error: cp itself cannot be changed
+ 
+int * const * pcp = &cp; // non-const pointer to const pointer to non-const int

The attr-spec-seq(C23) is an optional list of attributes, applied to the declared pointer.

+

Explanation

Pointers are used for indirection, which is a ubiquitous programming technique; they can be used to implement pass-by-reference semantics, to access objects with dynamic storage duration, to implement "optional" types (using the null pointer value), aggregation relationship between structs, callbacks (using pointers to functions), generic interfaces (using pointers to void), and much more.

+

Pointers to objects

A pointer to object can be initialized with the result of the address-of operator applied to an expression of object type (which may be incomplete):

+
int n;
+int *np = &n; // pointer to int
+int *const *npp = &np; // non-const pointer to const pointer to non-const int
+ 
+int a[2];
+int (*ap)[2] = &a; // pointer to array of int
+ 
+struct S { int n; } s = {1}
+int* sp = &s.n; // pointer to the int that is a member of s

Pointers may appear as operands to the indirection operator (unary *), which returns the lvalue identifying the pointed-to object:

+
int n;
+int* p = &n;     // pointer p is pointing to n
+*p = 7;         // stores 7 in n
+printf("%d\n", *p); // lvalue-to-rvalue conversion reads the value from n

Pointers to objects of struct and union type may also appear as the left-hand operands of the member access through pointer operator ->.

+

Because of the array-to-pointer implicit conversion, pointer to the first element of an array can be initialized with an expression of array type:

+
int a[2];
+int *p = a; // pointer to a[0]
+ 
+int b[3][3];
+int (*row)[3] = b; // pointer to b[0]

Certain addition, subtraction, compound assignment, increment, and decrement operators are defined for pointers to elements of arrays.

+

Comparison operators are defined for pointers to objects in some situations: two pointers that represent the same address compare equal, two null pointer values compare equal, pointers to elements of the same array compare the same as the array indexes of those elements, and pointers to struct members compare in order of declaration of those members.

+

Many implementations also provide strict total ordering of pointers of random origin, e.g. if they are implemented as addresses within continuous ("flat") virtual address space.

+

Pointers to functions

A pointer to function can be initialized with an address of a function. Because of the function-to-pointer conversion, the address-of operator is optional:

+
void f(int);
+void (*pf1)(int) = &f;
+void (*pf2)(int) = f; // same as &f

Unlike functions, pointers to functions are objects and thus can be stored in arrays, copied, assigned, passed to other functions as arguments, etc.

+

A pointer to function can be used on the left-hand side of the function call operator; this invokes the pointed-to function:

+
#include <stdio.h>
+int f(int n)
+{
+    printf("%d\n", n);
+    return n*n;
+}
+int main(void)
+{
+    int (*p)(int) = f;
+    int x = p(7);
+}

Dereferencing a function pointer yields the function designator for the pointed-to function:

+
int f();
+int (*p)() = f;    // pointer p is pointing to f
+(*p)(); // function f invoked through the function designator
+p();    // function f invoked directly through the pointer

Equality comparison operators are defined for pointers to functions (they compare equal if pointing to the same function).

+

Because compatibility of function types ignores top-level qualifiers of the function parameters, pointers to functions whose parameters only differ in their top-level qualifiers are interchangeable:

+
int f(int), fc(const int);
+int (*pc)(const int) = f; // OK
+int (*p)(int) = fc;       // OK
+pc = p;                   // OK

Pointers to void

Pointer to object of any type can be implicitly converted to pointer to void (optionally const or volatile-qualified), and vice versa:

+
int n=1, *p=&n;
+void* pv = p; // int* to void*
+int* p2 = pv; // void* to int*
+printf("%d\n", *p2); // prints 1

Pointers to void are used to pass objects of unknown type, which is common in generic interfaces: malloc returns void*, qsort expects a user-provided callback that accepts two const void* arguments. pthread_create expects a user-provided callback that accepts and returns void*. In all cases, it is the caller's responsibility to convert the pointer to the correct type before use.

+

Null pointers

Pointers of every type have a special value known as null pointer value of that type. A pointer whose value is null does not point to an object or a function (dereferencing a null pointer is undefined behavior), and compares equal to all pointers of the same type whose value is also null.

+

To initialize a pointer to null or to assign the null value to an existing pointer, a null pointer constant (NULL, or any other integer constant with the value zero) may be used. static initialization also initializes pointers to their null values.

+

Null pointers can indicate the absence of an object or can be used to indicate other types of error conditions. In general, a function that receives a pointer argument almost always needs to check if the value is null and handle that case differently (for example, free does nothing when a null pointer is passed).

+

Notes

Although any pointer to object can be cast to pointer to object of a different type, dereferencing a pointer to the type different from the declared type of the object is almost always undefined behavior. See strict aliasing for details.

+ + +

It is possible to indicate to a function that accesses objects through pointers that those pointers do not alias. See restrict for details.

+		 (since C99)

lvalue expressions of array type, when used in most contexts, undergo an implicit conversion to the pointer to the first element of the array. See array for details.

+
char *str = "abc"; // "abc" is a char[4] array, str is a pointer to 'a'

Pointers to char are often used to represent strings. To represent a valid byte string, a pointer must be pointing at a char that is an element of an array of char, and there must be a char with the value zero at some index greater or equal to the index of the element referenced by the pointer.

+

References

See also

+
C++ documentation for Pointer declaration
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/pointer +

+
diff --git a/devdocs/c/language%2Fpunctuators.html b/devdocs/c/language%2Fpunctuators.html new file mode 100644 index 00000000..50b603d2 --- /dev/null +++ b/devdocs/c/language%2Fpunctuators.html @@ -0,0 +1,175 @@ +

Punctuation

These are the punctuation symbols in C. The meaning of each symbol is detailed in the linked pages.

+

{ } +

[ ] +

# +

## +

( ) +

; +

: +

... +

? +

:: +

. +

-> +

~ +

! +

+ +

- +

* +

/ +

% +

^ +

& +

| +

= +

+= +

-= +

*= +

/= +

%= +

^= +

&= +

|= +

== +

!= +

< +

> +

<= +

>= +

&& +

|| +

<< +

>> +

<<= +

>>= +

++ +

-- +

, +

References

See also

+ +
Alternative representations (C95) alternative spellings for certain operators
C++ documentation for Punctuation
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/punctuators +

+
diff --git a/devdocs/c/language%2Frestrict.html b/devdocs/c/language%2Frestrict.html new file mode 100644 index 00000000..10843a1a --- /dev/null +++ b/devdocs/c/language%2Frestrict.html @@ -0,0 +1,160 @@ +

restrict type qualifier (since C99) +

Each individual type in the C type system has several qualified versions of that type, corresponding to one, two, or all three of the const, volatile, and, for pointers to object types, restrict qualifiers. This page describes the effects of the restrict qualifier.

+

Only a pointer to an object type or a (possibly multi-dimensional) array thereof(since C23) may be restrict-qualified; in particular, the following are erroneous:

+

Restrict semantics apply to lvalue expressions only; for example, a cast to restrict-qualified pointer or a function call returning a restrict-qualified pointer are not lvalues and the qualifier has no effect.

+

During each execution of a block in which a restricted pointer P is declared (typically each execution of a function body in which P is a function parameter), if some object that is accessible through P (directly or indirectly) is modified, by any means, then all accesses to that object (both reads and writes) in that block must occur through P (directly or indirectly), otherwise the behavior is undefined:

+
void f(int n, int * restrict p, int * restrict q)
+{
+    while (n-- > 0)
+        *p++ = *q++; // none of the objects modified through *p is the same
+                     // as any of the objects read through *q
+                     // compiler free to optimize, vectorize, page map, etc.
+}
+ 
+void g(void)
+{
+    extern int d[100];
+    f(50, d + 50, d); // OK
+    f(50, d + 1, d);  // Undefined behavior: d[1] is accessed through both p and q in f
+}

If the object is never modified, it may be aliased and accessed through different restrict-qualified pointers (note that if the objects pointed to by aliased restrict-qualified pointers are, in turn, pointers, this aliasing can inhibit optimization).

+

Assignment from one restricted pointer to another is undefined behavior, except when assigning from a pointer to an object in some outer block to a pointer in some inner block (including using a restricted pointer argument when calling a function with a restricted pointer parameter) or when returning from a function (and otherwise when the block of the from-pointer ended):

+
int* restrict p1 = &a;
+int* restrict p2 = &b;
+p1 = p2; // undefined behavior

Restricted pointers can be assigned to unrestricted pointers freely, the optimization opportunities remain in place as long as the compiler is able to analyze the code:

+
void f(int n, float * restrict r, float * restrict s)
+{
+    float *p = r, *q = s; // OK
+    while (n-- > 0)
+        *p++ = *q++; // almost certainly optimized just like *r++ = *s++
+}
+ + + +

If an array type is declared with the restrict type qualifier (through the use of typedef), the array type is not restrict-qualified, but its element type is:

+		 (until C23)

An array type and its element type are always considered to be identically restrict-qualified:

+		 (since C23)
typedef int *array_t[10];
+ 
+restrict array_t a; // the type of a is int *restrict[10]
+// Notes: clang and icc reject this on the grounds that array_t is not a pointer type
+ 
+void *unqual_ptr = &a; // OK until C23; error since C23
+// Notes: clang applies the rule in C++/C23 even in C89-C17 modes

In a function declaration, the keyword restrict may appear inside the square brackets that are used to declare an array type of a function parameter. It qualifies the pointer type to which the array type is transformed:

+
void f(int m, int n, float a[restrict m][n], float b[restrict m][n]);
+ 
+void g12(int n, float (*p)[n])
+{
+   f(10, n, p, p+10); // OK
+   f(20, n, p, p+10); // possibly undefined behavior (depending on what f does)
+}

Notes

The intended use of the restrict qualifier (like the register storage class) is to promote optimization, and deleting all instances of the qualifier from all preprocessing translation units composing a conforming program does not change its meaning (i.e., observable behavior).

+

The compiler is free to ignore any or all aliasing implications of uses of restrict.

+

To avoid undefined behavior, the programmer must ensure that the aliasing assertions made by the restrict-qualified pointers are not violated.

+

Many compilers provide, as a language extension, the opposite of restrict: an attribute indicating that pointers may alias even if their types differ: may_alias (gcc),

+

Usage patterns

There are several common usage patterns for restrict-qualified pointers:

+

File scope

A file-scope restrict-qualified pointer has to point into a single array object for the duration of the program. That array object may not be referenced both through the restricted pointer and through either its declared name (if it has one) or another restricted pointer.

+

File scope restricted pointers are useful in providing access to dynamically allocated global arrays; the restrict semantics make it possible to optimize references through this pointer as effectively as references to a static array through its declared name:

+
float *restrict a, *restrict b;
+float c[100];
+ 
+int init(int n)
+{
+   float * t = malloc(2*n*sizeof(float));
+   a = t;      // a refers to 1st half
+   b = t + n;  // b refers to 2nd half
+}
+// compiler can deduce from the restrict qualifiers that
+// there is no potential aliasing among the names a, b, and c

Function parameter

The most popular use case for restrict-qualified pointers is the use as function parameters.

+

In the following example, the compiler may infer that there is no aliasing of modified objects, and so optimize the loop aggressively. Upon entry to f, the restricted pointer a must provide exclusive access to its associated array. In particular, within f neither b nor c may point into the array associated with a, because neither is assigned a pointer value based on a. For b, this is evident from the const-qualifier in its declaration, but for c, an inspection of the body of f is required:

+
float x[100];
+float *c;
+ 
+void f(int n, float * restrict a, float * const b)
+{
+    int i;
+    for ( i=0; i<n; i++ )
+       a[i] = b[i] + c[i];
+}
+ 
+void g3(void)
+{
+    float d[100], e[100];
+    c = x; f(100,   d,    e); // OK
+           f( 50,   d, d+50); // OK
+           f( 99, d+1,    d); // undefined behavior
+    c = d; f( 99, d+1,    e); // undefined behavior
+           f( 99,   e,  d+1); // OK
+}

Note that it is permitted for c to point into the array associated with b. Note also that, for these purposes, the "array" associated with a particular pointer means only that portion of an array object which is actually referenced through that pointer.

+

Note that in the example above, the compiler can infer that a and b do not alias because b's constness guarantees that it cannot become dependent on a in the body of the function. Equivalently, the programmer could write void f(int n, float * a, float const * restrict b), in which case the compiler can reason that objects referenced through b cannot be modified, and so no modified object can be referenced using both b and a. If the programmer were to write void f(int n, float * restrict a, float * b), the compiler would be unable to infer non-aliasing of a and b without examining the body of the function.

+

In general, it is best to explicitly annotate all non-aliasing pointers in a function's prototype with restrict.

+

Block scope

A block scope restrict-qualified pointer makes an aliasing assertion that is limited to its block. It allows local assertions that apply only to important blocks, such as tight loops. It also makes it possible to convert a function that takes restrict-qualified pointers into a macro:

+
float x[100];
+float *c;
+ 
+#define f3(N, A, B)                                    \
+do                                                     \
+{   int n = (N);                                       \
+    float * restrict a = (A);                          \
+    float * const    b = (B);                          \
+    int i;                                             \
+    for ( i=0; i<n; i++ )                              \
+        a[i] = b[i] + c[i];                            \
+} while(0)

Struct members

The scope of the aliasing assertion made by a restrict-qualified pointer that is a member of a struct is the scope of the identifier used to access the struct.

+

Even if the struct is declared at file scope, when the identifier used to access the struct has block scope, the aliasing assertions in the struct also have block scope; the aliasing assertions are only in effect within a block execution or a function call, depending on how the object of this struct type was created:

+
struct t      // Restricted pointers assert that
+{
+   int n;     // members point to disjoint storage.
+   float * restrict p;
+   float * restrict q;
+};
+ 
+void ff(struct t r, struct t s)
+{
+   struct t u;
+   // r,s,u have block scope
+   // r.p, r.q, s.p, s.q, u.p, u.q should all point to
+   // disjoint storage during each execution of ff.
+   // ...
+}

Keywords

restrict

+

Example

code generation example; compile with -S (gcc, clang, etc) or /FA (visual studio)

+
int foo(int *a, int *b)
+{
+    *a = 5;
+    *b = 6;
+    return *a + *b;
+}
+ 
+int rfoo(int *restrict a, int *restrict b)
+{
+    *a = 5;
+    *b = 6;
+    return *a + *b;
+}

Possible output:

+
; generated code on 64bit Intel platform:
+foo:
+    movl    $5, (%rdi)    ; store 5 in *a
+    movl    $6, (%rsi)    ; store 6 in *b
+    movl    (%rdi), %eax  ; read back from *a in case previous store modified it
+    addl    $6, %eax      ; add 6 to the value read from *a
+    ret
+ 
+rfoo:
+    movl      $11, %eax   ; the result is 11, a compile-time constant
+    movl      $5, (%rdi)  ; store 5 in *a
+    movl      $6, (%rsi)  ; store 6 in *b
+    ret

References

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/restrict +

+
diff --git a/devdocs/c/language%2Freturn.html b/devdocs/c/language%2Freturn.html new file mode 100644 index 00000000..33a0ef72 --- /dev/null +++ b/devdocs/c/language%2Freturn.html @@ -0,0 +1,70 @@ +

return statement

Terminates current function and returns specified value to the caller function.

+

Syntax

+ + +
attr-spec-seq(optional) return expression ; (1)
attr-spec-seq(optional) return ; (2)
+ + +
expression - expression used for initializing the return value of the function
attr-spec-seq - (C23)optional list of attributes, applied to the return statement

Explanation

+1) Evaluates the expression, terminates the current function and returns the result of the expression to the caller (the value returned becomes the value of the function call expression). Only valid if the function return type is not void.
+2) Terminates the current function. Only valid if the function return type is void.

If the type of the expression is different from the return type of the function, its value is converted as if by assignment to an object whose type is the return type of the function, except that overlap between object representations is permitted:

+
struct s { double i; } f(void); // function returning struct s
+union { struct { int f1; struct s f2; } u1;
+        struct { struct s f3; int f4; } u2; } g;
+struct s f(void)
+{
+    return g.u1.f2;
+}
+int main(void)
+{
+// g.u2.f3 = g.u1.f2; // undefined behavior (overlap in assignment)
+   g.u2.f3 = f();     // well-defined
+}

If the return type is a real floating type, the result may be represented in greater range and precision than implied by the new type.

+

Reaching the end of a function returning void is equivalent to return;. Reaching the end of any other value-returning function is undefined behavior if the result of the function is used in an expression (it is allowed to discard such return value). For main, see main function.

+ + +

Executing the return statement in a no-return function is undefined behavior.

+		 (since C11)

Keywords

return

+

Example

#include <stdio.h>
+ 
+void fa(int i)
+{
+    if (i == 2)
+       return;
+    printf("fa():   %d\n", i);
+} // implied return;
+ 
+int fb(int i)
+{
+    if (i > 4)
+       return 4;
+    printf("fb():   %d\n", i);
+    return 2;
+}
+ 
+int main(void)
+{
+    fa(2);
+    fa(1);
+    int i = fb(5);   // the return value 4 used to initializes i
+    i = fb(i);       // the return value 2 used as rhs of assignment
+    printf("main(): %d\n", i);
+}

Output:

+
fa():   1
+fb():   4
+main(): 2

References

See also

+
C++ documentation for return statement
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/return +

+
diff --git a/devdocs/c/language%2Fscalar_initialization.html b/devdocs/c/language%2Fscalar_initialization.html new file mode 100644 index 00000000..d0fd3411 --- /dev/null +++ b/devdocs/c/language%2Fscalar_initialization.html @@ -0,0 +1,50 @@ +

Scalar initialization

When initializing an object of scalar type, the initializer must be a single expression

+

The initializer for a scalar (an object of integer type including booleans and enumerated types, floating type including complex and imaginary, and pointer type including pointer to function) must be a single expression, optionally enclosed in braces, or an empty initializer(since C23):

+ + + + +
= expression (1)
= { expression } (2)
= { } (3) (since C23)
+1,2) The expression is evaluated, and its value, after conversion as if by assignment to the type of the object, becomes the initial value of the object being initialized.
+3) The object is empty-initialized, i.e. initialized to numeric zero for an object of an arithmetic or enumeration type, or null pointer value for an object of a pointer type.

Notes

Because of the rules that apply to conversions as if by assignment, const and volatile qualifiers on the declared type are ignored when determining which type to convert the expression to.

+

See initialization for the rules that apply when no initializer is used.

+

As with all other initializations, expression must be a constant expression when initializing objects of static or thread-local storage duration.

+

The expression cannot be a comma operator (unless parenthesized) because the comma at the top level would be interpreted as the beginning of the next declarator.

+

When initializing objects of floating-point type, all computations for the objects with automatic storage duration are done as-if at execution time and are affected by the current rounding; floating-point errors are reported as specified in math_errhandling. For objects of static and thread-local storage duration, computations are done as-if at compile time, and no exceptions are raised:

+
void f(void)
+{
+#pragma STDC FENV_ACCESS ON
+    static float v = 1.1e75; // does not raise exceptions: static init
+ 
+    float u[] = { 1.1e75 }; // raises FE_INEXACT
+    float w = 1.1e75;       // raises FE_INEXACT
+ 
+    double x = 1.1e75; // may raise FE_INEXACT (depends on FLT_EVAL_METHOD)
+    float y = 1.1e75f; // may raise FE_INEXACT (depends on FLT_EVAL_METHOD)
+ 
+    long double z = 1.1e75; // does not raise exceptions (conversion is exact)
+}

Example

#include <stdbool.h>
+int main(void)
+{
+    bool b = true;
+    const double d = 3.14;
+    int k = 3.15; // conversion from double to int
+    int n = {12}, // optional braces
+       *p = &n,   // non-constant expression OK for automatic variable
+       (*fp)(void) = main;
+    enum {RED, BLUE} e = RED; // enumerations are scalar types as well
+}

References

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/scalar_initialization +

+
diff --git a/devdocs/c/language%2Fscope.html b/devdocs/c/language%2Fscope.html new file mode 100644 index 00000000..654166df --- /dev/null +++ b/devdocs/c/language%2Fscope.html @@ -0,0 +1,128 @@ +

Scope

Each identifier that appears in a C program is visible (that is, may be used) only in some possibly discontiguous portion of the source code called its scope.

+

Within a scope, an identifier may designate more than one entity only if the entities are in different name spaces.

+

C has four kinds of scopes:

+

Nested scopes

If two different entities named by the same identifier are in scope at the same time, and they belong to the same name space, the scopes are nested (no other form of scope overlap is allowed), and the declaration that appears in the inner scope hides the declaration that appears in the outer scope:

+
// The name space here is ordinary identifiers.
+ 
+int a;   // file scope of name a begins here
+ 
+void f(void)
+{
+    int a = 1; // the block scope of the name a begins here; hides file-scope a
+    {
+      int a = 2;         // the scope of the inner a begins here, outer a is hidden
+      printf("%d\n", a); // inner a is in scope, prints 2
+    }                    // the block scope of the inner a ends here
+    printf("%d\n", a);   // the outer a is in scope, prints 1
+}                        // the scope of the outer a ends here
+ 
+void g(int a);   // name a has function prototype scope; hides file-scope a

Block scope

The scope of any identifier declared inside a compound statement, including function bodies, or in any expression, declaration, or statement appearing in if, switch, for, while, or do-while statement(since C99), or within the parameter list of a function definition begins at the point of declaration and ends at the end of the block or statement in which it was declared.

+
void f(int n)  // scope of the function parameter 'n' begins
+{         // the body of the function begins
+   ++n;   // 'n' is in scope and refers to the function parameter
+// int n = 2; // error: cannot redeclare identifier in the same scope
+   for(int n = 0; n<10; ++n) { // scope of loop-local 'n' begins
+       printf("%d\n", n); // prints 0 1 2 3 4 5 6 7 8 9
+   } // scope of the loop-local 'n' ends
+     // the function parameter 'n' is back in scope
+   printf("%d\n", n); // prints the value of the parameter
+} // scope of function parameter 'n' ends
+int a = n; // Error: name 'n' is not in scope
+ +

Until C99, selection and iteration statements did not establish their own block scopes (although if a compound statement was used in the statement, it had its usual block scope):

+
enum {a, b};
+int different(void)
+{
+    if (sizeof(enum {b, a}) != sizeof(int))
+        return a; // a == 1
+    return b; // b == 0 in C89, b == 1 in C99
+}
 (since C99)

Block-scope variables have no linkage and automatic storage duration by default. Note that storage duration for non-VLA local variables begins when the block is entered, but until the declaration is seen, the variable is not in scope and cannot be accessed.

+

File scope

The scope of any identifier declared outside of any block or parameter list begins at the point of declaration and ends at the end of the translation unit.

+
int i; // scope of i begins
+static int g(int a) { return a; } // scope of g begins (note, "a" has block scope)
+int main(void)
+{
+    i = g(2); // i and g are in scope
+}

File-scope identifiers have external linkage and static storage duration by default.

+

Function scope

A label (and only a label) declared inside a function is in scope everywhere in that function, in all nested blocks, before and after its own declaration. Note: a label is declared implicitly, by using an otherwise unused identifier before the colon character before any statement.

+
void f()
+{
+   {   
+       goto label; // label in scope even though declared later
+label:;
+   }
+   goto label; // label ignores block scope
+}
+ 
+void g()
+{
+    goto label; // error: label not in scope in g()
+}

Function prototype scope

The scope of a name introduced in the parameter list of a function declaration that is not a definition ends at the end of the function declarator.

+
int f(int n,
+      int a[n]); // n is in scope and refers to the first parameter

Note that if there are multiple or nested declarators in the declaration, the scope ends at the end of the nearest enclosing function declarator:

+
void f ( // function name 'f' is at file scope
+ long double f,            // the identifier 'f' is now in scope, file-scope 'f' is hidden
+ char (**a)[10 * sizeof f] // 'f' refers to the first parameter, which is in scope
+);
+ 
+enum{ n = 3 };
+int (*(*g)(int n))[n]; // the scope of the function parameter 'n'
+                       // ends at the end of its function declarator
+                       // in the array declarator, global n is in scope
+// (this declares a pointer to function returning a pointer to an array of 3 int)

Point of declaration

The scope of structure, union, and enumeration tags begins immediately after the appearance of the tag in a type specifier that declares the tag.

+
struct Node {
+   struct Node* next; // Node is in scope and refers to this struct
+};

The scope of enumeration constant begins immediately after the appearance of its defining enumerator in an enumerator list.

+
enum { x = 12 };
+{
+    enum { x = x + 1, // new x is not in scope until the comma, x is initialized to 13
+           y = x + 1  // the new enumerator x is now in scope, y is initialized to 14
+         };
+}

The scope of any other identifier begins just after the end of its declarator and before the initializer, if any:

+
int x = 2; // scope of the first 'x' begins
+{
+    int x[x]; // scope of the newly declared x begins after the declarator (x[x]).
+              // Within the declarator, the outer 'x' is still in scope.
+              // This declares a VLA array of 2 int.
+}
unsigned char x = 32; // scope of the outer 'x' begins
+{
+    unsigned char x = x;
+            // scope of the inner 'x' begins before the initializer (= x)
+            // this does not initialize the inner 'x' with the value 32, 
+            // this initializes the inner 'x' with its own, indeterminate, value
+}
+ 
+unsigned long factorial(unsigned long n)
+// declarator ends, 'factorial' is in scope from this point
+{
+   return n<2 ? 1 : n*factorial(n-1); // recursive call
+}

As a special case, the scope of a type name that is not a declaration of an identifier is considered to begin just after the place within the type name where the identifier would appear were it not omitted.

+

Notes

Prior to C89, identifiers with external linkage had file scope even when introduced within a block, and because of that, a C89 compiler is not required to diagnose the use of an extern identifier that has gone out of scope (such use is undefined behavior).

+

Local variables within a loop body can hide variables declared in the init clause of a for loop in C (their scope is nested), but cannot do that in C++.

+

Unlike C++, C has no struct scope: names declared within a struct/union/enum declaration are in the same scope as the struct declaration (except that data members are in their own member name space):

+
struct foo {
+    struct baz {};
+    enum color {RED, BLUE};
+};
+struct baz b; // baz is in scope
+enum color x = RED; // color and RED are in scope

References

See also

+
C++ documentation for Scope
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/scope +

+
diff --git a/devdocs/c/language%2Fsizeof.html b/devdocs/c/language%2Fsizeof.html new file mode 100644 index 00000000..afac1a41 --- /dev/null +++ b/devdocs/c/language%2Fsizeof.html @@ -0,0 +1,69 @@ +

sizeof operator

Queries size of the object or type.

+

Used when actual size of the object must be known.

+

Syntax

+ + +
sizeof( type ) (1)
sizeof expression (2)

Both versions return a value of type size_t.

+

Explanation

+1) Returns the size, in bytes, of the object representation of type +
+2) Returns the size, in bytes, of the object representation of the type of expression. No implicit conversions are applied to expression.

Notes

Depending on the computer architecture, a byte may consist of 8 or more bits, the exact number provided as CHAR_BIT.

+

sizeof(char), sizeof(signed char), and sizeof(unsigned char) always return 1.

+

sizeof cannot be used with function types, incomplete types (including void), or bit-field lvalues.

+

When applied to an operand that has structure or union type, the result is the total number of bytes in such an object, including internal and trailing padding. The trailing padding is such that if the object were an element of an array, the alignment requirement of the next element of this array would be satisfied, in other words, sizeof(T) returns the size of an element of a T[] array.

+ + +

If type is a VLA type and changing the value of its size expression would not affect the result of sizeof, it is unspecified whether or not the size expression is evaluated.

+		 (since C99)

Except if the type of expression is a VLA,(since C99)expression is not evaluated and the sizeof operator may be used in an integer constant expression.

+ + +

If the type of expression is a variable-length array type, expression is evaluated and the size of the array it evaluates to is calculated at run time.

+		 (since C99)

Number of elements in any array a including VLA(since C99) may be determined with the expression sizeof a / sizeof a[0]. Note that if a has pointer type (such as after array-to-pointer conversion of function parameter type adjustment), this expression would simply divide the number of bytes in a pointer type by the number of bytes in the pointed type.

+

Keywords

sizeof

+

Example

+

Sample output corresponds to a platform with 64-bit pointers and 32-bit int

+
#include <stdio.h>
+ 
+int main(void)
+{
+    short x;
+    // type argument:
+    printf("sizeof(float)          = %zu\n", sizeof(float));
+    printf("sizeof(void(*)(void))  = %zu\n", sizeof(void(*)(void)));
+    printf("sizeof(char[10])       = %zu\n", sizeof(char[10]));
+//  printf("sizeof(void(void))     = %zu\n", sizeof(void(void))); // Error: function type
+//  printf("sizeof(char[])         = %zu\n", sizeof(char[])); // Error: incomplete type
+ 
+    // expression argument:
+    printf("sizeof 'a'             = %zu\n", sizeof 'a'); // type of 'a' is int
+//  printf("sizeof main            = %zu\n", sizeof main); // Error: Function type
+    printf("sizeof &main           = %zu\n", sizeof &main);
+    printf("sizeof \"hello\"         = %zu\n", sizeof "hello"); // type is char[6]
+    printf("sizeof x               = %zu\n", sizeof x); // type of x is short
+    printf("sizeof (x+1)           = %zu\n", sizeof(x + 1)); // type of x+1 is int
+}

Possible output:

+
sizeof(float)          = 4
+sizeof(void(*)(void))  = 8
+sizeof(char[10])       = 10
+sizeof 'a'             = 4
+sizeof &main           = 8
+sizeof "hello"         = 6
+sizeof x               = 2
+sizeof (x+1)           = 4

References

See also

+
C++ documentation for sizeof operator
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/sizeof +

+
diff --git a/devdocs/c/language%2Fstatements.html b/devdocs/c/language%2Fstatements.html new file mode 100644 index 00000000..09713f6a --- /dev/null +++ b/devdocs/c/language%2Fstatements.html @@ -0,0 +1,113 @@ +

Statements

Statements are fragments of the C program that are executed in sequence. The body of any function is a compound statement, which, in turn is a sequence of statements and declarations:

+
int main(void)
+{ // start of a compound statement
+    int n = 1; // declaration (not a statement)
+    n = n+1; // expression statement
+    printf("n = %d\n", n); // expression statement
+    return 0; // return statement
+} // end of compound statement, end of function body


There are five types of statements:

+
+1) compound statements +
+2) expression statements +
+3) selection statements +
+4) iteration statements +
+5) jump statements +
+ +

An attribute specifier sequence (attr-spec-seq) can be applied to an unlabeled statement, in which case (except for an expression statement) the attributes are applied to the respective statement.

+		 (since C23)

Labels

Any statement can be labeled, by providing a name followed by a colon before the statement itself.

+ + + + +
attr-spec-seq(optional)(since C23) identifier : (1)
attr-spec-seq(optional)(since C23) case constant-expression : (2)
attr-spec-seq(optional)(since C23) default : (3)
+1) Target for goto.
+2) Case label in a switch statement.
+3) Default label in a switch statement.

Any statement (but not a declaration) may be preceded by any number of labels, each of which declares identifier to be a label name, which must be unique within the enclosing function (in other words, label names have function scope).

+

Label declaration has no effect on its own, does not alter the flow of control, or modify the behavior of the statement that follows in any way.

+ + + + +

A label shall be followed by a statement.

+		 (until C23)

A label can appear without its following statement. If a label appears alone in a block, it behaves as if it is followed by a null statement.

+

The optional attr-spec-seq is applied to the label.

+		 (since C23)

Compound statements

A compound statement, or block, is a brace-enclosed sequence of statements and declarations.

+ + + +
{ statement | declaration...(optional) } (until C23)
attr-spec-seq(optional) { unlabeled-statement | label | declaration...(optional) } (since C23)

The compound statement allows a set of declarations and statements to be grouped into one unit that can be used anywhere a single statement is expected (for example, in an if statement or an iteration statement):

+
if (expr) // start of if-statement
+{ // start of block
+  int n = 1; // declaration
+  printf("%d\n", n); // expression statement
+} // end of block, end of if-statement

Each compound statement introduces its own block scope.

+

The initializers of the variables with automatic storage duration declared inside a block and the VLA declarators are executed when flow of control passes over these declarations in order, as if they were statements:

+
int main(void)
+{ // start of block
+  { // start of block
+       puts("hello"); // expression statement
+       int n = printf("abc\n"); // declaration, prints "abc", stores 4 in n
+       int a[n*printf("1\n")]; // declaration, prints "1", allocates 8*sizeof(int)
+       printf("%zu\n", sizeof(a)); // expression statement
+  } // end of block, scope of n and a ends
+  int n = 7; // n can be reused
+}

Expression statements

An expression followed by a semicolon is a statement.

+ + + +
expression(optional) ; (1)
attr-spec-seq expression ; (2) (since C23)

Most statements in a typical C program are expression statements, such as assignments or function calls.

+

An expression statement without an expression is called a null statement. It is often used to provide an empty body to a for or while loop. It can also be used to carry a label in the end of a compound statement or before a declaration:

+
puts("hello"); // expression statement
+char *s;
+while (*s++ != '\0')
+    ; // null statement
+ +

The optional attr-spec-seq is applied to the expression.

+

An attr-spec-seq followed by ; does not form an expression statement. It forms an attribute declaration instead.

+		 (since C23)

Selection statements

The selection statements choose between one of several statements depending on the value of an expression.

+ + + + +
attr-spec-seq(optional)(since C23) if ( expression ) statement (1)
attr-spec-seq(optional)(since C23) if ( expression ) statement else statement (2)
attr-spec-seq(optional)(since C23) switch ( expression ) statement (3)
+1) if statement
+2) if statement with an else clause
+3) switch statement

Iteration statements

The iteration statements repeatedly execute a statement.

+ + + + +
attr-spec-seq(optional)(since C23) while ( expression ) statement (1)
attr-spec-seq(optional)(since C23) do statement while ( expression ) ; (2)
attr-spec-seq(optional)(since C23) for ( init-clause ; expression(optional) ; expression(optional) ) statement (3)
+1) while loop
+2) do-while loop
+3) for loop

Jump statements

The jump statements unconditionally transfer flow control.

+ + + + + +
attr-spec-seq(optional)(since C23) break ; (1)
attr-spec-seq(optional)(since C23) continue ; (2)
attr-spec-seq(optional)(since C23) return expression(optional) ; (3)
attr-spec-seq(optional)(since C23) goto identifier ; (4)
+1) break statement
+2) continue statement
+3) return statement with an optional expression
+4) goto statement

References

See also

+
C++ documentation for Statements
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/statements +

+
diff --git a/devdocs/c/language%2Fstatic_assert.html b/devdocs/c/language%2Fstatic_assert.html new file mode 100644 index 00000000..edc18201 --- /dev/null +++ b/devdocs/c/language%2Fstatic_assert.html @@ -0,0 +1,58 @@ +

Static assertion (since C11) +

Syntax

+ + + + +
_Static_assert ( expression , message ) (since C11)(deprecated in C23)
static_assert ( expression , message ) (since C23)
_Static_assert ( expression ) (since C23)(deprecated in C23)
static_assert ( expression ) (since C23)
+ + +
expression - any integer constant expression
message - any string literal
+ + + +

This keyword is also available as convenience macro static_assert, available in the header <assert.h>.

+		 (until C23)

Both of static_assert and _Static_assert have the same effects. _Static_assert is a deprecated spelling that is kept for compatibility.

+

An implementation may also define static_assert and/or _Static_assert as predefined macros, and static_assert is no longer provided by <assert.h>.

+		 (since C23)

Explanation

The constant expression is evaluated at compile time and compared to zero. If it compares equal to zero, a compile-time error occurs and the compiler must display message as part of the error message (except that characters not in basic character set are not required to be displayed)(until C23)should display message (if provided) as part of the error message(since C23).

+

Otherwise, if expression does not equal zero, nothing happens; no code is emitted.

+

Keywords

_Static_assert, static_assert

+

Example

#include <assert.h> // no longer needed since C23
+ 
+int main(void)
+{
+    // Test if math works, C23:
+    static_assert((2 + 2) % 3 == 1, "Whoa dude, you knew!");
+    // Pre-C23 alternative:
+    _Static_assert(2 + 2 * 2 == 6, "Lucky guess!?");
+ 
+    // This will produce an error at compile time.
+    // static_assert(sizeof(int) < sizeof(char), "Unmet condition!");
+ 
+    constexpr int _42 = 2 * 3 * 2 * 3 + 2 * 3;
+    static_assert(_42 == 42); // the message string can be omitted.
+ 
+    // const int _13 = 13;
+    // Compile time error - not an integer constant expression:
+    // static_assert(_13 == 13);
+}

References

See also

+ +
aborts the program if the user-specified condition is not true. May be disabled for release builds
(function macro)
C++ documentation for static_assert declaration
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/static_assert +

+
diff --git a/devdocs/c/language%2Fstatic_storage_duration.html b/devdocs/c/language%2Fstatic_storage_duration.html new file mode 100644 index 00000000..2ca1a227 --- /dev/null +++ b/devdocs/c/language%2Fstatic_storage_duration.html @@ -0,0 +1,32 @@ +

Static storage duration

An object whose identifier is declared without the storage-class specifier _Thread_local, and either with external or internal linkage or with the storage-class specifier static, has static storage duration. Its lifetime is the entire execution of the program and its stored value is initialized only once, prior to program startup.

+

Notes

Since its stored value is initialized only once, an object with static storage duration can profile the invocations of a function.

+

The other use of the keyword static is file scope.

+

Example

#include <stdio.h>
+ 
+void f (void)
+{
+    static int count = 0;   // static variable   
+    int i = 0;              // automatic variable
+    printf("%d %d\n", i++, count++);
+}
+ 
+int main(void)
+{
+    for (int ndx=0; ndx<10; ++ndx)
+        f();
+}

Output:

+
0 0
+0 1
+0 2
+0 3
+0 4
+0 5
+0 6
+0 7
+0 8
+0 9
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/static_storage_duration +

+
diff --git a/devdocs/c/language%2Fstorage_duration.html b/devdocs/c/language%2Fstorage_duration.html new file mode 100644 index 00000000..558ffa50 --- /dev/null +++ b/devdocs/c/language%2Fstorage_duration.html @@ -0,0 +1,144 @@ +

Storage-class specifiers

Specify storage duration and linkage of objects and functions:

+ + +
  • +_Thread_local(until C23)thread_local(since C23) - thread storage duration
(since C11)

Explanation

Storage-class specifiers appear in declarations and compound literal expressions(since C23). At most one specifier may be used, except that _Thread_local(until C23)thread_local(since C23) may be combined with static or extern to adjust linkage(since C11). The storage-class specifiers determine two independent properties of the names they declare: storage duration and linkage.

+
+1) The auto specifier is only allowed for objects declared at block scope (except function parameter lists). It indicates automatic storage duration and no linkage, which are the defaults for these kinds of declarations.
+2) The register specifier is only allowed for objects declared at block scope, including function parameter lists. It indicates automatic storage duration and no linkage (which is the default for these kinds of declarations), but additionally hints the optimizer to store the value of this variable in a CPU register if possible. Regardless of whether this optimization takes place or not, variables declared register cannot be used as arguments to the address-of operator, cannot use alignas(since C11), and register arrays are not convertible to pointers.
+3) The static specifier specifies both static storage duration (unless combined with _Thread_local)(since C11) and internal linkage (unless used at block scope). It can be used with functions at file scope and with variables at both file and block scope, but not in function parameter lists.
+4) The extern specifier specifies static storage duration (unless combined with _Thread_local(until C23)thread_local(since C23))(since C11) and external linkage. It can be used with function and object declarations in both file and block scope (excluding function parameter lists). If extern appears on a redeclaration of an identifier that was already declared with internal linkage, the linkage remains internal. Otherwise (if the prior declaration was external, no-linkage, or is not in scope), the linkage is external.
+ +
5) _Thread_local(until C23)thread_local(since C23) indicates thread storage duration. It cannot be used with function declarations. If it is used on a declaration of an object, it must be present on every declaration of the same object. If it is used on a block-scope declaration, it must be combined with either static or extern to decide linkage. (since C11)

If no storage-class specifier is provided, the defaults are:

+
+
extern for all functions
+
extern for objects at file scope
+
auto for objects at block scope
+

For any struct or union declared with a storage-class specifier, the storage duration (but not linkage) applies to their members, recursively.

+

Function declarations at block scope can use extern or none at all. Function declarations at file scope can use extern or static.

+

Function parameters cannot use any storage-class specifiers other than register. Note that static has special meaning in function parameters of array type.

+

Storage duration

Every object has a property called storage duration, which limits the object lifetime. There are four kinds of storage duration in C:

+ + +
  • +thread storage duration. The storage duration is the entire execution of the thread in which it was created, and the value stored in the object is initialized when the thread is started. Each thread has its own, distinct, object. If the thread that executes the expression that accesses this object is not the thread that executed its initialization, the behavior is implementation-defined. All objects declared _Thread_local(until C23)thread_local(since C23) have this storage duration.
(since C11)

Linkage

Linkage refers to the ability of an identifier (variable or function) to be referred to in other scopes. If a variable or function with the same identifier is declared in several scopes, but cannot be referred to from all of them, then several instances of the variable are generated. The following linkages are recognized:

+

If the same identifier appears with both internal and external linkage in the same translation unit, the behavior is undefined. This is possible when tentative definitions are used.

+

Linkage and libraries

Declarations with external linkage are commonly made available in header files so that all translation units that #include the file may refer to the same identifier that are defined elsewhere.

+

Any declaration with internal linkage that appears in a header file results in a separate and distinct object in each translation unit that includes that file.

+ + +

Library interface, header file "flib.h":

+
#ifndef FLIB_H
+#define FLIB_H
+void f(void);              // function declaration with external linkage
+extern int state;          // variable declaration with external linkage
+static const int size = 5; // definition of a read-only variable with internal linkage
+enum { MAX = 10 };         // constant definition
+inline int sum (int a, int b) { return a + b; } // inline function definition
+#endif // FLIB_H

Library implementation, source file "flib.c":

+
#include "flib.h"
+ 
+static void local_f(int s) {} // definition with internal linkage (only used in this file)
+static int local_state;       // definition with internal linkage (only used in this file)
+ 
+int state;                       // definition with external linkage (used by main.c)
+void f(void) { local_f(state); } // definition with external linkage (used by main.c)

Application code, source file "main.c":

+
#include "flib.h"
+ 
+int main(void)
+{
+    int x[MAX] = {size}; // uses the constant and the read-only variable
+    state = 7;           // modifies state in flib.c
+    f();                 // calls f() in flib.c
+}

Keywords

auto, register, static, extern, _Thread_local thread_local

+

Notes

+ +

The keyword _Thread_local is usually used through the convenience macro thread_local, defined in the header <threads.h>.

+		 (until C23)

The typedef and constexpr(since C23) specifiers are formally listed as storage-class specifiers in the C language grammar, but do not specify storage.

+ + +

The auto specifier is also used for type inference.

+		 (since C23)

Names at file scope that are const and not extern have external linkage in C (as the default for all file-scope declarations), but internal linkage in C++.

+

Example

#include <stdio.h>
+#include <stdlib.h>
+ 
+// static storage duration
+int A;
+ 
+int main(void)
+{
+    printf("&A = %p\n", (void*)&A);
+ 
+    // automatic storage duration
+    int A = 1;   // hides global A
+    printf("&A = %p\n", (void*)&A);
+ 
+    // allocated storage duration
+    int* ptr_1 = malloc(sizeof(int));   // start allocated storage duration
+    printf("address of int in allocated memory = %p\n", (void*)ptr_1);
+    free(ptr_1);                        // stop allocated storage duration
+}

Possible output:

+
&A = 0x600ae4
+&A = 0x7ffefb064f5c
+address of int in allocated memory = 0x1f28c30

References

See also

+
C++ documentation for Storage class specifiers
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/storage_duration +

+
diff --git a/devdocs/c/language%2Fstring_literal.html b/devdocs/c/language%2Fstring_literal.html new file mode 100644 index 00000000..39b28812 --- /dev/null +++ b/devdocs/c/language%2Fstring_literal.html @@ -0,0 +1,123 @@ +

String literals

Constructs an unnamed object of specified character array type in-place, used when a character string needs to be embedded in source code.

+

Syntax

+ + + + + +
" s-char-sequence " (1)
u8" s-char-sequence " (2) (since C11)
u" s-char-sequence " (3) (since C11)
U" s-char-sequence " (4) (since C11)
L" s-char-sequence " (5)

where

+ + +
s-char-sequence - zero or more characters, each of which is either a multibyte character from the source character set (excluding ("), \, and newline), or character escape, hex escape, octal escape, or universal character name(since C99) as defined in escape sequences.
+1) character string literal: The type of the literal is char[N], where N is the size of the string in code units of the execution narrow encoding, including the null terminator. Each char element in the array is initialized from the next character in s-char-sequence using the execution character set.
+2) UTF-8 string literal: The type of the literal is char[N](until C23)char8_t[N](since C23), where N is the size of the string in UTF-8 code units including the null terminator. Each char(until C23)char8_t(since C23) element in the array is initialized from the next multibyte character in s-char-sequence using UTF-8 encoding.
+ + + +
3) 16-bit wide string literal: The type of the literal is char16_t[N], where N is the size of the string in code units of implementation-defined 16-bit encoding (typically UTF-16), including the null terminator. Each char16_t element in the array is initialized as if by executing mbrtoc16 in implementation-defined locale. 4) 32-bit wide string literal: The type of the literal is char32_t[N], where N is the size of the string in code units of implementation-defined 32-bit encoding (typically UTF-32), including the null terminator. Each char32_t element in the array is initialized as if by executing mbrtoc32 in implementation-defined locale. (until C23)
3) UTF-16 string literal: The type of the literal is char16_t[N], where N is the size of the string in UTF-16 code units including the null terminator. Each char16_t element in the array is initialized from the next multibyte character in s-char-sequence using UTF-16 encoding. 4) UTF-32 string literal: The type of the literal is char32_t[N], where N is the size of the string in UTF-32 code units including the null terminator. Each char32_t element in the array is initialized from the next multibyte character in s-char-sequence using UTF-32 encoding. (since C23)
+5) wide string literal: The type of the literal is wchar_t[N], where N is the size of the string in code units of the execution wide encoding, including the null terminator. Each wchar_t element in the array is initialized as if by executing mbstowcs in implementation-defined locale.

Explanation

First, at translation phase 6 (after macro expansion), the adjacent string literals (that is, string literals separated by whitespace only) are concatenated.

+ + + + +

Only two narrow or two wide string literals may be concatenated.

+		 (until C99)

If one literal is unprefixed, the resulting string literal has the width/encoding specified by the prefixed literal.

+
L"Δx = %" PRId16 // at phase 4, PRId16 expands to "d"
+                 // at phase 6, L"Δx = %" and "d" form L"Δx = %d"
 (since C99)
+ + + +

If the two string literals have different encoding prefixes, concatenation is implementation-defined, except that a UTF-8 string literal and a wide string literal cannot be concatenated.

+		 +(since C11)
(until C23) +

If the two string literals have different encoding prefixes, concatenation is ill-formed.

+		 (since C23)

Secondly, at translation phase 7, a terminating null character is added to each string literal, and then each literal initializes an unnamed array with static storage duration and length just enough to contain the contents of the string literal plus one for the null terminator.

+
char* p = "\x12" "3"; // creates a static char[3] array holding {'\x12', '3', '\0'}
+                      // sets p to point to the first element of the array

String literals are not modifiable (and in fact may be placed in read-only memory such as .rodata). If a program attempts to modify the static array formed by a string literal, the behavior is undefined.

+
char* p = "Hello";
+p[1] = 'M'; // Undefined behavior
+char a[] = "Hello";
+a[1] = 'M'; // OK: a is not a string literal

It is neither required nor forbidden for identical string literals to refer to the same location in memory. Moreover, overlapping string literals or string literals that are substrings of other string literals may be combined.

+
"def" == 3+"abcdef"; // may be 1 or 0, implementation-defined

Notes

A string literal is not necessarily a string; if a string literal has embedded null characters, it represents an array which contains more than one string:

+
char* p = "abc\0def"; // strlen(p) == 3, but the array has size 8

If a valid hex digit follows a hex escape in a string literal, it would fail to compile as an invalid escape sequence, but string concatenation can be used as a workaround:

+
//char* p = "\xfff"; // error: hex escape sequence out of range
+char* p = "\xff""f"; // okay, the literal is char[3] holding {'\xff', 'f', '\0'}

String literals can be used to initialize arrays, and if the size of the array is one less the size of the string literal, the null terminator is ignored:

+
char a1[] = "abc"; // a1 is char[4] holding {'a', 'b', 'c', '\0'}
+char a2[4] = "abc"; // a2 is char[4] holding {'a', 'b', 'c', '\0'}
+char a3[3] = "abc"; // a3 is char[3] holding {'a', 'b', 'c'}

The encoding of character string literals (1) and wide string literals (5) is implementation-defined. For example, gcc selects them with the commandline options -fexec-charset and -fwide-exec-charset.

+

Although mixed wide string literal concatenation is allowed in C11, almost all compilers reject such concatenation (the only known exception is SDCC), and its usage experience is unknown. As a result, allowance of mixed wide string literal concatenation is removed in C23.

+

Example

#include <inttypes.h>
+#include <locale.h>
+#include <stddef.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <uchar.h>
+ 
+int main(void)
+{
+    char s1[] = "a猫🍌"; // or "a\u732B\U0001F34C"
+#if __STDC_VERSION__ >= 202311L
+    char8_t
+#else
+    char
+#endif
+    s2[] = u8"a猫🍌";
+    char16_t s3[] = u"a猫🍌";
+    char32_t s4[] = U"a猫🍌";
+    wchar_t s5[] = L"a猫🍌";
+ 
+    setlocale(LC_ALL, "en_US.utf8");
+    printf("  \"%s\" is a char[%zu] holding     { ", s1, sizeof s1 / sizeof *s1);
+    for(size_t n = 0; n < sizeof s1 / sizeof *s1; ++n)
+        printf("0x%02X ", +(unsigned char)s1[n]);
+    puts("}");
+    printf(
+#if __STDC_VERSION__ >= 202311L
+    "u8\"%s\" is a char8_t[%zu] holding  { "
+#else
+    "u8\"%s\" is a char[%zu] holding     { "
+#endif
+, s2, sizeof s2 / sizeof *s2);
+    for(size_t n = 0; n < sizeof s2 / sizeof *s2; ++n)
+#if __STDC_VERSION__ >= 202311L
+       printf("0x%02X ", s2[n]);
+#else
+       printf("0x%02X ", +(unsigned char)s2[n]);
+#endif
+    puts("}");
+    printf(" u\"a猫🍌\" is a char16_t[%zu] holding { ", sizeof s3 / sizeof *s3);
+    for(size_t n = 0; n < sizeof s3 / sizeof *s3; ++n)
+       printf("0x%04" PRIXLEAST16" ", s3[n]);
+    puts("}");
+    printf(" U\"a猫🍌\" is a char32_t[%zu] holding { ", sizeof s4 / sizeof *s4);
+    for(size_t n = 0; n < sizeof s4 / sizeof *s4; ++n)
+       printf("0x%08" PRIXLEAST32" ", s4[n]);
+    puts("}");
+    printf(" L\"%ls\" is a wchar_t[%zu] holding  { ", s5, sizeof s5 / sizeof *s5);
+    for(size_t n = 0; n < sizeof s5 / sizeof *s5; ++n)
+       printf("0x%08X ", (unsigned)s5[n]);
+    puts("}");
+}

Possible output:

+
+  "a猫🍌" is a char[9] holding     { 0x61 0xE7 0x8C 0xAB 0xF0 0x9F 0x8D 0x8C 0x00 }
+u8"a猫🍌" is a char[9] holding     { 0x61 0xE7 0x8C 0xAB 0xF0 0x9F 0x8D 0x8C 0x00 }
+ u"a猫🍌" is a char16_t[5] holding { 0x0061 0x732B 0xD83C 0xDF4C 0x0000 }
+ U"a猫🍌" is a char32_t[4] holding { 0x00000061 0x0000732B 0x0001F34C 0x00000000 }
+ L"a猫🍌" is a wchar_t[4] holding  { 0x00000061 0x0000732B 0x0001F34C 0x00000000 }

References

See also

+
C++ documentation for string literal
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/string_literal +

+
diff --git a/devdocs/c/language%2Fstruct.html b/devdocs/c/language%2Fstruct.html new file mode 100644 index 00000000..3e59cdb5 --- /dev/null +++ b/devdocs/c/language%2Fstruct.html @@ -0,0 +1,163 @@ +

Struct declaration

A struct is a type consisting of a sequence of members whose storage is allocated in an ordered sequence (as opposed to union, which is a type consisting of a sequence of members whose storage overlaps).

+

The type specifier for a struct is identical to the union type specifier except for the keyword used:

+

Syntax

+ + +
struct attr-spec-seq (optional) name (optional) { struct-declaration-list } (1)
struct attr-spec-seq (optional) name (2)
+1) Struct definition: introduces the new type struct name and defines its meaning
+2) If used on a line of its own, as in struct name ;, declares but doesn't define the struct name (see forward declaration below). In other contexts, names the previously-declared struct, and attr-spec-seq is not allowed.
+ + + +
name - the name of the struct that's being defined
struct-declaration-list - any number of variable declarations, bit-field declarations, and static assert declarations. Members of incomplete type and members of function type are not allowed (except for the flexible array member described below)
attr-spec-seq - (C23)optional list of attributes, applied to the struct type

Explanation

Within a struct object, addresses of its elements (and the addresses of the bit-field allocation units) increase in order in which the members were defined. A pointer to a struct can be cast to a pointer to its first member (or, if the member is a bit-field, to its allocation unit). Likewise, a pointer to the first member of a struct can be cast to a pointer to the enclosing struct. There may be unnamed padding between any two members of a struct or after the last member, but not before the first member. The size of a struct is at least as large as the sum of the sizes of its members.

+ + +

If a struct defines at least one named member, it is allowed to additionally declare its last member with incomplete array type. When an element of the flexible array member is accessed (in an expression that uses operator . or -> with the flexible array member's name as the right-hand-side operand), then the struct behaves as if the array member had the longest size fitting in the memory allocated for this object. If no additional storage was allocated, it behaves as if an array with 1 element, except that the behavior is undefined if that element is accessed or a pointer one past that element is produced. Initialization and the assignment operator ignore the flexible array member. sizeof omits it, but may have more trailing padding than the omission would imply. Structures with flexible array members (or unions who have a recursive-possibly structure member with flexible array member) cannot appear as array elements or as members of other structures.

+
struct s { int n; double d[]; }; // s.d is a flexible array member
+ 
+struct s t1 = { 0 };          // OK, d is as if double d[1], but UB to access
+struct s t2 = { 1, { 4.2 } }; // error: initialization ignores flexible array
+ 
+// if sizeof (double) == 8
+struct s *s1 = malloc(sizeof (struct s) + 64); // as if d was double d[8]
+struct s *s2 = malloc(sizeof (struct s) + 40); // as if d was double d[5]
+ 
+s1 = malloc(sizeof (struct s) + 10); // now as if d was double d[1]. Two bytes excess.
+double *dp = &(s1->d[0]);    // OK
+*dp = 42;                    // OK
+s1->d[1]++;                  // Undefined behavior. 2 excess bytes can't be accessed
+                             // as double.
+ 
+s2 = malloc(sizeof (struct s) + 6);  // same, but UB to access because 2 bytes are
+                                     // missing to complete 1 double
+dp = &(s2->d[0]);            //  OK, can take address just fine
+*dp = 42;                    //  undefined behavior
+ 
+*s1 = *s2; // only copies s.n, not any element of s.d
+           // except those caught in sizeof (struct s)
 (since C99)
+ +

Similar to union, an unnamed member of a struct whose type is a struct without name is known as anonymous struct. Every member of an anonymous struct is considered to be a member of the enclosing struct or union, keeping their structure layout. This applies recursively if the enclosing struct or union is also anonymous.

+
struct v
+{
+   union // anonymous union
+   {
+      struct { int i, j; }; // anonymous structure
+      struct { long k, l; } w;
+   };
+   int m;
+} v1;
+ 
+v1.i = 2;   // valid
+v1.k = 3;   // invalid: inner structure is not anonymous
+v1.w.k = 5; // valid

Similar to union, the behavior of the program is undefined if struct is defined without any named members (including those obtained via anonymous nested structs or unions).

+		 (since C11)

Forward declaration

A declaration of the following form

+ + +
struct attr-spec-seq (optional) name ;

hides any previously declared meaning for the name name in the tag name space and declares name as a new struct name in current scope, which will be defined later. Until the definition appears, this struct name has incomplete type.

+

This allows structs that refer to each other:

+
struct y;
+struct x { struct y *p; /* ... */ };
+struct y { struct x *q; /* ... */ };

Note that a new struct name may also be introduced just by using a struct tag within another declaration, but if a previously declared struct with the same name exists in the tag name space, the tag would refer to that name

+
struct s* p = NULL; // tag naming an unknown struct declares it
+struct s { int a; }; // definition for the struct pointed to by p
+void g(void)
+{
+    struct s; // forward declaration of a new, local struct s
+              // this hides global struct s until the end of this block
+    struct s *p;  // pointer to local struct s
+                  // without the forward declaration above,
+                  // this would point at the file-scope s
+    struct s { char* p; }; // definitions of the local struct s
+}

Keywords

struct

+

Notes

See struct initialization for the rules regarding the initializers for structs.

+

Because members of incomplete type are not allowed, and a struct type is not complete until the end of the definition, a struct cannot have a member of its own type. A pointer to its own type is allowed, and is commonly used to implement nodes in linked lists or trees.

+

Because a struct declaration does not establish scope, nested types, enumerations and enumerators introduced by declarations within struct-declaration-list are visible in the surrounding scope where the struct is defined.

+

Example

#include <stddef.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    // Declare the struct type.
+    struct car
+    {
+        char* make;
+        int year;
+    };
+    // Declare and initialize an object of a previously-declared struct type.
+    struct car c = {.year = 1923, .make = "Nash"};
+    printf("1) Car: %d %s\n", c.year, c.make);
+ 
+    // Declare a struct type, an object of that type, and a pointer to it.
+    struct spaceship
+    {
+        char* model;
+        int max_speed;
+    } ship = {"T-65 X-wing starfighter", 1050},
+    *pship = &ship;
+    printf("2) Spaceship: %s. Max speed: %d km/h\n\n", ship.model, ship.max_speed);
+ 
+    // Address increase in order of definition. Padding may be inserted.
+    struct A { char a; double b; char c; };
+    printf(
+        "3) Offset of char a = %zu\n"
+        "4) Offset of double b = %zu\n"
+        "5) Offset of char c = %zu\n"
+        "6) Size of struct A = %zu\n\n",
+        offsetof(struct A, a),
+        offsetof(struct A, b),
+        offsetof(struct A, c),
+        sizeof(struct A)
+    );
+    struct B { char a; char b; double c; };
+    printf(
+        "7) Offset of char a = %zu\n"
+        "8) Offset of char b = %zu\n"
+        "9) Offset of double c = %zu\n"
+        "A) Size of struct B = %zu\n\n",
+        offsetof(struct B, a),
+        offsetof(struct B, b),
+        offsetof(struct B, c),
+        sizeof(struct B)
+    );
+ 
+    // A pointer to a struct can be cast to a pointer
+    // to its first member and vice versa.
+    char** pmodel = (char **)pship;
+    printf("B) %s\n", *pmodel);
+    pship = (struct spaceship *)pmodel;
+}

Possible output:

+
1) Car: 1923 Nash
+2) Spaceship: T-65 X-wing starfighter. Max speed: 1050 km/h
+ 
+3) Offset of char a = 0
+4) Offset of double b = 8
+5) Offset of char c = 16
+6) Size of struct A = 24
+ 
+7) Offset of char a = 0
+8) Offset of char b = 1
+9) Offset of double c = 8
+A) Size of struct B = 16
+ 
+B) T-65 X-wing starfighter

References

See also

+
C++ documentation for Class declaration
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/struct +

+
diff --git a/devdocs/c/language%2Fstruct_initialization.html b/devdocs/c/language%2Fstruct_initialization.html new file mode 100644 index 00000000..f97f90ae --- /dev/null +++ b/devdocs/c/language%2Fstruct_initialization.html @@ -0,0 +1,125 @@ +

Struct and union initialization

When initializing an object of struct or union type, the initializer must be a non-empty,(until C23) brace-enclosed, comma-separated list of initializers for the members:

+ + + + +
= { expression , ... } (1) (until C99)
= { designator(optional) expression , ... } (2) (since C99)
= { } (3) (since C23)

where the designator is a sequence (whitespace-separated or adjacent) of individual member designators of the form . member and array designators of the form [ index ].

+

All members that are not initialized explicitly are empty-initialized.

+

Explanation

When initializing a union, the initializer list must have only one member, which initializes the first member of the union unless a designated initializer is used(since C99).

+
union { int x; char c[4]; }
+  u = {1},           // makes u.x active with value 1
+ u2 = { .c={'\1'} }; // makes u2.c active with value {'\1','\0','\0','\0'}

When initializing a struct, the first initializer in the list initializes the first declared member (unless a designator is specified)(since C99), and all subsequent initializers without designators (since C99)initialize the struct members declared after the one initialized by the previous expression.

+
struct point {double x,y,z;} p = {1.2, 1.3}; // p.x=1.2, p.y=1.3, p.z=0.0
+div_t answer = {.quot = 2, .rem = -1 };      // order of elements in div_t may vary
+ +

A designator causes the following initializer to initialize the struct member described by the designator. Initialization then continues forward in order of declaration, beginning with the next element declared after the one described by the designator.

+
struct {int sec,min,hour,day,mon,year;} z
+   = {.day=31,12,2014,.sec=30,15,17}; // initializes z to {30,15,17,31,12,2014}
 (since C99)

It's an error to provide more initializers than members.

+

Nested initialization

If the members of the struct or union are arrays, structs, or unions, the corresponding initializers in the brace-enclosed list of initializers are any initializers that are valid for those members, except that their braces may be omitted as follows:

+

If the nested initializer begins with an opening brace, the entire nested initializer up to its closing brace initializes the corresponding member object. Each left opening brace establishes a new current object. The members of the current object are initialized in their natural order, unless designators are used(since C99): array elements in subscript order, struct members in declaration order, only the first declared member of any union. The subobjects within the current object that are not explicitly initialized by the closing brace are empty-initialized.

+
struct example {
+    struct addr_t {
+       uint32_t port;
+    } addr;
+    union {
+       uint8_t a8[4];
+       uint16_t a16[2];
+    } in_u;
+};
+struct example ex = { // start of initializer list for struct example
+                     { // start of initializer list for ex.addr
+                        80 // initialized struct's only member
+                     }, // end of initializer list for ex.addr
+                     { // start of initializer-list for ex.in_u
+                        {127,0,0,1} // initializes first element of the union
+                     } };

If the nested initializer does not begin with an opening brace, only enough initializers from the list are taken to account for the elements or members of the member array, struct or union; any remaining initializers are left to initialize the next struct member:

+
struct example ex = {80, 127, 0, 0, 1}; // 80 initializes ex.addr.port
+                                        // 127 initializes ex.in_u.a8[0]
+                                        // 0 initializes ex.in_u.a8[1]
+                                        // 0 initializes ex.in_u.a8[2]
+                                        // 1 initializes ex.in_u.a8[3]
+ +

When designators are nested, the designators for the members follow the designators for the enclosing structs/unions/arrays. Within any nested bracketed initializer list, the outermost designator refers to the current object and selects the subobject to be initialized within the current object only.

+
struct example ex2 = { // current object is ex2, designators are for members of example
+                       .in_u.a8[0]=127, 0, 0, 1, .addr=80}; 
+struct example ex3 = {80, .in_u={ // changes current object to the union ex.in_u
+                           127,
+                           .a8[2]=1 // this designator refers to the member of in_u
+                      } };

If any subobject is explicitly initialized twice (which may happen when designators are used), the initializer that appears later in the list is the one used (the earlier initializer may not be evaluated):

+
struct {int n;} s = {printf("a\n"), // this may be printed or skipped
+                     .n=printf("b\n")}; // always printed

Although any non-initialized subobjects are initialized implicitly, implicit initialization of a subobject never overrides explicit initialization of the same subobject if it appeared earlier in the initializer list (choose clang to observe the correct output):

+
#include <stdio.h>
+typedef struct { int k; int l; int a[2]; } T;
+typedef struct { int i;  T t; } S;
+T x = {.l = 43, .k = 42, .a[1] = 19, .a[0] = 18 };
+ // x initialized to {42, 43, {18, 19} }
+int main(void)
+{
+    S l = { 1,          // initializes l.i to 1
+           .t = x,      // initializes l.t to {42, 43, {18, 19} }
+           .t.l = 41,   // changes l.t to {42, 41, {18, 19} }
+           .t.a[1] = 17 // changes l.t to {42, 41, {18, 17} }
+          };
+    printf("l.t.k is %d\n", l.t.k); // .t = x sets l.t.k to 42 explicitly
+                                    // .t.l = 41 would zero out l.t.k implicitly
+}

Output:

+
l.t.k is 42

However, when an initializer begins with a left open brace, its current object is fully re-initialized and any prior explicit initializers for any of its subobjects are ignored:

+
struct fred { char s[4]; int n; };
+struct fred x[ ] = { { { "abc" }, 1 }, // inits x[0] to { {'a','b','c','\0'}, 1 }
+                      [0].s[0] = 'q'   // changes x[0] to { {'q','b','c','\0'}, 1 }
+                   };
+struct fred y[ ] = { { { "abc" }, 1 }, // inits y[0] to { {'a','b','c','\0'}, 1 }
+                     [0] = { // current object is now the entire y[0] object
+                             .s[0] = 'q' 
+                            } // replaces y[0] with { {'q','\0','\0','\0'}, 0 }
+                    };
 (since C99)

Notes

The initializer list may have a trailing comma, which is ignored.

+
struct {double x,y;} p = {1.0,
+                          2.0, // trailing comma OK
+                          };
+ + + +

In C, the braced list of initializers cannot be empty (note that C++ allows empty lists, and also note that a struct in C cannot be empty):

+		 (until C23)

The initializer list can be empty in C as in C++:

+		 (since C23)
struct {int n;} s = {0}; // OK
+struct {int n;} s = {}; // Error until C23: initializer-list cannot be empty
+                        // OK since C23: s.n is initialized to 0
+struct {} s = {}; // Error: struct cannot be empty
+ + + +

Every expression in the initializer list must be a constant expression when initializing aggregates of any storage duration.

+		 (until C99)

As with all other initialization, every expression in the initializer list must be a constant expression when initializing aggregates of static or thread-local(since C11) storage duration:

+
static struct {char* p} s = {malloc(1)}; // error

The order of evaluation of the subexpressions in any initializer is indeterminately sequenced (but not in C++ since C++11):

+
int n = 1;
+struct {int x,y;} p = {n++, n++}; // unspecified, but well-defined behavior:
+                                  // n is incremented twice in arbitrary order
+                                  // p equal {1,2} and {2,1} are both valid
 (since C99)

Example

#include <stdio.h>
+#include <time.h>
+ 
+int main(void)
+{
+    char buff[70];
+    // designated initializers simplify the use of structs whose
+    // order of members is unspecified
+    struct tm my_time = { .tm_year=2012-1900, .tm_mon=9, .tm_mday=9,
+                          .tm_hour=8, .tm_min=10, .tm_sec=20 };
+    strftime(buff, sizeof buff, "%A %c", &my_time);
+    puts(buff);
+}

Possible output:

+
Sunday Sun Oct  9 08:10:20 2012

References

See also

+
C++ documentation for Aggregate initialization
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/struct_initialization +

+
diff --git a/devdocs/c/language%2Fswitch.html b/devdocs/c/language%2Fswitch.html new file mode 100644 index 00000000..83c773e6 --- /dev/null +++ b/devdocs/c/language%2Fswitch.html @@ -0,0 +1,88 @@ +

switch statement

Executes code according to the value of an integral argument.

+

Used where one or several out of many branches of code need to be executed according to an integral value.

+

Syntax

+ +
attr-spec-seq(optional) switch ( expression ) statement
+ + + +
attr-spec-seq - (C23)optional list of attributes, applied to the switch statement
expression - any expression of integer type (char, signed or unsigned integer, or enumeration)
statement - any statement (typically a compound statement). case: and default: labels are permitted in statement, and break; statement has special meaning.
+ + + + +
case constant-expression : statement (1) (until C23)
attr-spec-seq(optional) case constant-expression : statement(optional) (1) (since C23)
default : statement (2) (until C23)
attr-spec-seq(optional) default : statement(optional) (2) (since C23)
+ + +
constant-expression - any integer constant expression
attr-spec-seq - (C23)optional list of attributes, applied to the label

Explanation

The body of a switch statement may have an arbitrary number of case: labels, as long as the values of all constant-expressions are unique (after conversion to the promoted type of expression). At most one default: label may be present (although nested switch statements may use their own default: labels or have case: labels whose constants are identical to the ones used in the enclosing switch).

+

If expression evaluates to the value that is equal to the value of one of constant-expressions after conversion to the promoted type of expression, then control is transferred to the statement that is labeled with that constant-expression.

+

If expression evaluates to a value that doesn't match any of the case: labels, and the default: label is present, control is transferred to the statement labeled with the default: label.

+

If expression evaluates to a value that doesn't match any of the case: labels, and the default: label is not present, none of the switch body is executed.

+

The break statement, when encountered anywhere in statement, exits the switch statement:

+
switch(1) {
+    case 1 : puts("1"); // prints "1",
+    case 2 : puts("2"); // then prints "2" ("fall-through")
+}
switch(1) {
+    case 1 : puts("1"); // prints "1"
+             break;     // and exits the switch
+    case 2 : puts("2");
+             break;
+}
+ +

As with all other selection and iteration statements, the switch statement establishes block scope: any identifier introduced in the expression goes out of scope after the statement.

+

If a VLA or another identifier with variably-modified type has a case: or a default: label within its scope, the entire switch statement must be in its scope (in other words, a VLA must be declared either before the entire switch or after the last label):

+
switch (expr)
+{
+        int i = 4; // not a VLA; OK to declare here
+        f(i); // never called
+//      int a[i]; // error: VLA cannot be declared here
+    case 0:
+        i = 17;
+    default:
+        int a[i]; // OK to declare VLA here
+        printf("%d\n", i); // prints 17 if expr == 0, prints indeterminate value otherwise
+}
 (since C99)

Keywords

switch, case, default

+

Example

#include <stdio.h>
+ 
+void func(int x)
+{
+   printf("func(%d): ", x);
+   switch(x)
+   {
+      case 1: printf("case 1, ");
+      case 2: printf("case 2, ");
+      case 3: printf("case 3.\n"); break;
+      case 4: printf("case 4, ");
+      case 5:
+      case 6: printf("case 5 or case 6, ");
+      default: printf("default.\n");
+   }
+}
+ 
+int main(void)
+{
+   for(int i = 1; i < 9; ++i) func(i);
+}

Output:

+
func(1): case 1, case 2, case 3.
+func(2): case 2, case 3.
+func(3): case 3.
+func(4): case 4, case 5 or case 6, default.
+func(5): case 5 or case 6, default.
+func(6): case 5 or case 6, default.
+func(7): default.
+func(8): default.

References

See also

+
C++ documentation for switch statement
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/switch +

+
diff --git a/devdocs/c/language%2Fthread_storage_duration.html b/devdocs/c/language%2Fthread_storage_duration.html new file mode 100644 index 00000000..8f92d562 --- /dev/null +++ b/devdocs/c/language%2Fthread_storage_duration.html @@ -0,0 +1,14 @@ +

Thread storage duration

An object whose identifier is declared with the storage-class specifier _Thread_local (since C11) has thread storage duration. Its lifetime is the entire execution of the thread for which it is created, and its stored value is initialized when the thread is started. There is a distinct object per thread, and use of the declared name in an expression refers to the object associated with the thread evaluating the expression. The result of attempting to indirectly access an object with thread storage duration from a thread other than the one with which the object is associated is implementation-defined.

+

Example

const double PI = 3.14159;         /* const variable is global to all threads  */
+_Thread_local unsigned int seed;   /* seed is a thread-specific variable       */
+ 
+int main(void)
+{
+    return 0;
+}

Possible output:

+
(none)
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/thread_storage_duration +

+
diff --git a/devdocs/c/language%2Ftranslation_phases.html b/devdocs/c/language%2Ftranslation_phases.html new file mode 100644 index 00000000..2f629e71 --- /dev/null +++ b/devdocs/c/language%2Ftranslation_phases.html @@ -0,0 +1,105 @@ +

Phases of translation

The C source file is processed by the compiler as if the following phases take place, in this exact order. Actual implementation may combine these actions or process them differently as long as the behavior is the same.

+

Phase 1

+1) The individual bytes of the source code file (which is generally a text file in some multibyte encoding such as UTF-8) are mapped, in implementation defined manner, to the characters of the source character set. In particular, OS-dependent end-of-line indicators are replaced by newline characters. The source character set is a multibyte character set which includes the basic source character set as a single-byte subset, consisting of the following 96 characters:
+a) 5 whitespace characters (space, horizontal tab, vertical tab, form feed, new-line)
+b) 10 digit characters from '0' to '9' +
+c) 52 letters from 'a' to 'z' and from 'A' to 'Z' +
+d) 29 punctuation characters: _ { } [ ] # ( ) < > % : ; . ? * + - / ^ & | ~ ! = , \ " ' +
+2) Trigraph sequences are replaced by corresponding single-character representations.(until C23) +

Phase 2

+1) Whenever backslash appears at the end of a line (immediately followed by the newline character), both backslash and newline are deleted, combining two physical source lines into one logical source line. This is a single-pass operation: a line ending in two backslashes followed by an empty line does not combine three lines into one. 
#include <stdio.h>
+ 
+#define PUTS p\
+u\
+t\
+s
+/* Line splicing is in phase 2 while macros
+ * are tokenized in phase 3 and expanded in phase 4,
+ * so the above is equivalent to #define PUTS puts
+ */
+ 
+int main(void)
+{
+ /* Use line splicing to call puts */ PUT\
+S\
+("Output ends here\\
+0Not printed" /* After line splicing, the remaining backslash
+               * escapes the 0, ending the string early.
+               */
+);
+}
+
+2) If a non-empty source file does not end with a newline character after this step (whether it had no newline originally, or it ended with a backslash), the behavior is undefined.

Phase 3

+1) The source file is decomposed into comment, sequences of whitespace characters (space, horizontal tab, new-line, vertical tab, and form-feed), and preprocessing tokens, which are the following
+a) header names: <stdio.h> or "myfile.h" +
+b) identifiers +
+c) preprocessing numbers, which cover integer constants and floating constants, but also cover some invalid tokens such as 1..E+3.foo or 0JBK +
+d) character constants and string literals +
+e) operators and punctuators, such as +, <<=, <%, or ##.
+f) individual non-whitespace characters that do not fit in any other category
+2) Each comment is replaced by one space character
+3) Newlines are kept, and it's implementation-defined whether non-newline whitespace sequences may be collapsed into single space characters.

If the input has been parsed into preprocessing tokens up to a given character, the next preprocessing token is generally taken to be the longest sequence of characters that could constitute a preprocessing token, even if that would cause subsequent analysis to fail. This is commonly known as maximal munch.

+
int foo = 1;
+// int bar = 0xE+foo; // error: invalid preprocessing number 0xE+foo
+int bar = 0xE/*Comment expands to a space*/+foo; // OK: 0xE + foo
+int baz = 0xE + foo; // OK: 0xE + foo
+int pub = bar+++baz; // OK: bar++ + baz
+int ham = bar++-++baz; // OK: bar++ - ++baz
+// int qux = bar+++++baz; // error: bar++ ++ +baz, not bar++ + ++baz
+int qux = bar+++/*Saving comment*/++baz; // OK: bar++ + ++baz

The sole exception to the maximal munch rule is:

+ 
#define MACRO_1 1
+#define MACRO_2 2
+#define MACRO_3 3
+#define MACRO_EXPR (MACRO_1 <MACRO_2> MACRO_3) // OK: <MACRO_2> is not a header-name

Phase 4

+1) Preprocessor is executed.
+2) Each file introduced with the #include directive goes through phases 1 through 4, recursively.
+3) At the end of this phase, all preprocessor directives are removed from the source.

Phase 5

+1) All characters and escape sequences in character constants and string literals are converted from source character set to execution character set (which may be a multibyte character set such as UTF-8, as long as all 96 characters from the basic source character set listed in phase 1 have single-byte representations). If the character specified by an escape sequence isn't a member of the execution character set, the result is implementation-defined, but is guaranteed to not be a null (wide) character.

Note: the conversion performed at this stage can be controlled by command line options in some implementations: gcc and clang use -finput-charset to specify the encoding of the source character set, -fexec-charset and -fwide-exec-charset to specify the encodings of the execution character set in the string literals and character constants that don't have an encoding prefix(since C11).

+

Phase 6

Adjacent string literals are concatenated.

+

Phase 7

Compilation takes place: the tokens are syntactically and semantically analyzed and translated as a translation unit.

+

Phase 8

Linking takes place: Translation units and library components needed to satisfy external references are collected into a program image which contains information needed for execution in its execution environment (the OS).

+

References

See also

+
C++ documentation for Phases of translation
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/translation_phases +

+
diff --git a/devdocs/c/language%2Ftype.html b/devdocs/c/language%2Ftype.html new file mode 100644 index 00000000..c7b398c4 --- /dev/null +++ b/devdocs/c/language%2Ftype.html @@ -0,0 +1,233 @@ +

Type

(See also arithmetic types for the details on most built-in types and the list of type-related utilities that are provided by the C library.)

+

Objects, functions, and expressions have a property called type, which determines the interpretation of the binary value stored in an object or evaluated by the expression.

+

Type classification

The C type system consists of the following types:

+ + + + +
  • bit-precise: _BitInt(N) where N is an integer constant expression that specifies the number of bits that are used to represent the type, including the sign bit. Each value of N designates a distinct type.
(since C23)
  • extended: implementation defined, e.g. __int128
(since C99)
+ + + +
  • bit-precise: unsigned _BitInt(N) where N is an integer constant expression that specifies the number of bits that are used to represent the type. Each value of N designates a distinct type. This category includes the type unsigned _BitInt(1) which does not have a corresponding bit-precise signed integer type
(since C23)
  • extended: implementation-defined, e.g. __uint128
(since C99)
+ + + +
  • decimal real floating-point types: _Decimal32, _Decimal64, _Decimal128
(since C23)
    +
  • complex types: float _Complex, double _Complex, long double _Complex
    • +
  • imaginary types: float _Imaginary, double _Imaginary, long double _Imaginary
    • +
 (since C99)
+ +
(since C11)

For every type listed above several qualified versions of its type may exist, corresponding to the combinations of one, two, or all three of the const, volatile, and restrict qualifiers (where allowed by the qualifier's semantics).

+

Type groups

Constructing a complete object type such that the number of bytes in its object representation is not representable in the type size_t (i.e. the result type of sizeof operator), including forming such a VLA type at runtime,(since C99) is undefined behavior.

+

Compatible types

In a C program, the declarations referring to the same object or function in different translation units do not have to use the same type. They only have to use sufficiently similar types, formally known as compatible types. Same applies to function calls and lvalue accesses; argument types must be compatible with parameter types and lvalue expression type must be compatible with the object type that is accessed.

+

The types T and U are compatible, if

+ + +
    +
  • one is an old-style (parameter-less) definition, the other has a parameter list, the parameter list does not use an ellipsis and each parameter is compatible (after function parameter type adjustment) with the corresponding old-style parameter after default argument promotions
    • +
  • one is an old-style (parameter-less) declaration, the other has a parameter list, the parameter list does not use an ellipsis, and all parameters (after function parameter type adjustment) are unaffected by default argument promotions
    • +
 (until C23)

The type char is not compatible with signed char and not compatible with unsigned char.

+

If two declarations refer to the same object or function and do not use compatible types, the behavior of the program is undefined.

+
// Translation Unit 1
+struct S { int a; };
+extern struct S *x; // compatible with TU2's x, but not with TU3's x
+ 
+// Translation Unit 2
+struct S;
+extern struct S *x; // compatible with both x's
+ 
+// Translation Unit 3
+struct S { float a; };
+extern struct S *x; // compatible with TU2's x, but not with TU1's x
+ 
+// the behavior is undefined
// Translation Unit 1
+#include <stdio.h>
+ 
+struct s { int i; }; // compatible with TU3's s, but not TU2's
+extern struct s x = {0}; // compatible with TU3's x
+extern void f(void); // compatible with TU2's f
+ 
+int main()
+{
+    f();
+    return x.i;
+}
+ 
+// Translation Unit 2
+struct s { float f; }; // compatible with TU4's s, but not TU1's s
+extern struct s y = {3.14}; // compatible with TU4's y
+void f() // compatible with TU1's f
+{
+    return;
+}
+ 
+// Translation Unit 3
+struct s { int i; }; // compatible with TU1's s, but not TU2's s
+extern struct s x; // compatible with TU1's x
+ 
+// Translation Unit 4
+struct s { float f; }; // compatible with TU2's s, but not TU1's s
+extern struct s y; // compatible with TU2's y
+ 
+// the behavior is well-defined: only multiple declarations
+// of objects and functions must have compatible types, not the types themselves

Note: C++ has no concept of compatible types. A C program that declares two types that are compatible but not identical in different translation units is not a valid C++ program.

+

Composite types

A composite type can be constructed from two types that are compatible; it is a type that is compatible with both of the two types and satisfies the following conditions:

+ + +
    +
  • Otherwise, if one type is a VLA whose size is specified by an expression that is not evaluated, a program necessitating the composite type of both types has undefined behavior.
    • +
  • Otherwise, if one type is a VLA whose size is specified, the composite type is a VLA of that size.
    • +
  • Otherwise, if one type is a VLA of unspecified size, the composite type is a VLA of unspecified size.
    • +
 (since C99)
The element type of the composite type is the composite type of the two element types. + +
  • If only one type is a function type with a parameter type list (a function prototype), the composite type is a function prototype with the parameter type list.
(until C23)

These rules apply recursively to the types from which the two types are derived.

+
// Given the following two file scope declarations:
+int f(int (*)(), double (*)[3]);
+int f(int (*)(char *), double (*)[]); // C23: Error: conflicting types for 'f'
+// The resulting composite type for the function is:
+int f(int (*)(char *), double (*)[3]);

For an identifier with internal or external linkage declared in a scope in which a prior declaration of that identifier is visible, if the prior declaration specifies internal or external linkage, the type of the identifier at the later declaration becomes the composite type.

+

Incomplete types

An incomplete type is an object type that lacks sufficient information to determine the size of the objects of that type. An incomplete type may be completed at some point in the translation unit.

+

The following types are incomplete:

+ 
extern char a[]; // the type of a is incomplete (this typically appears in a header)
+char a[10];      // the type of a is now complete (this typically appears in a source file)
struct node
+{
+    struct node *next; // struct node is incomplete at this point
+}; // struct node is complete at this point

Type names

A type may have to be named in context other than the declaration. In these situations, type name is used, which is, grammatically, exactly the same as a list of type-specifiers and type-qualifiers, followed by the declarator (see declarations) as would be used to declare a single object or function of this type, except that the identifier is omitted:

+
int n; // declaration of an int
+sizeof(int); // use of type name
+ 
+int *a[3]; // declaration of an array of 3 pointers to int
+sizeof(int *[3]); // use of type name
+ 
+int (*p)[3]; // declaration of a pointer to array of 3 int
+sizeof(int (*)[3]); // use of type name
+ 
+int (*a)[*] // declaration of pointer to VLA (in a function parameter)
+sizeof(int (*)[*]) // use of type name (in a function parameter)
+ 
+int *f(void); // declaration of function
+sizeof(int *(void)); // use of type name
+ 
+int (*p)(void); // declaration of pointer to function
+sizeof(int (*)(void)); // use of type name
+ 
+int (*const a[])(unsigned int, ...) = {0}; // array of pointers to functions
+sizeof(int (*const [])(unsigned int, ...)); // use of type name

Except the redundant parentheses around the identifier are meaningful in a type-name and represent "function with no parameter specification":

+
int (n); // declares n of type int
+sizeof(int ()); // uses type "function returning int"

Type names are used in the following situations:

+ + + + +
(since C99)
(since C11)


A type name may introduce a new type:

+
void* p = (void*)(struct X { int i; } *)0;
+// type name "struct X {int i;}*" used in the cast expression
+// introduces the new type "struct X"
+struct X x = {1}; // struct X is now in scope

References

See also

+
C++ documentation for Type
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/type +

+
diff --git a/devdocs/c/language%2Ftypedef.html b/devdocs/c/language%2Ftypedef.html new file mode 100644 index 00000000..5deaefd3 --- /dev/null +++ b/devdocs/c/language%2Ftypedef.html @@ -0,0 +1,60 @@ +

Typedef declaration

The typedef declaration provides a way to declare an identifier as a type alias, to be used to replace a possibly complex type name

+

The keyword typedef is used in a declaration, in the grammatical position of a storage-class specifier, except that it does not affect storage or linkage:

+
typedef int int_t; // declares int_t to be an alias for the type int
+typedef char char_t, *char_p, (*fp)(void); // declares char_t to be an alias for char
+                                           // char_p to be an alias for char*
+                                           // fp to be an alias for char(*)(void)

Explanation

If a declaration uses typedef as storage-class specifier, every declarator in it defines an identifier as an alias to the type specified. Since only one storage-class specifier is permitted in a declaration, typedef declaration cannot be static or extern.

+

typedef declaration does not introduce a distinct type, it only establishes a synonym for an existing type, thus typedef names are compatible with the types they alias. Typedef names share the name space with ordinary identifiers such as enumerators, variables and function.

+ + +

A typedef for a VLA can only appear at block scope. The length of the array is evaluated each time the flow of control passes over the typedef declaration, as opposed to the declaration of the array itself:

+
void copyt(int n)
+{
+    typedef int B[n]; // B is a VLA, its size is n, evaluated now
+    n += 1;
+    B a; // size of a is n from before +=1
+    int b[n]; // a and b are different sizes
+    for (int i = 1; i < n; i++)
+        a[i-1] = b[i];
+}
 (since C99)

Notes

typedef name may be an incomplete type, which may be completed as usual:

+
typedef int A[]; // A is int[]
+A a = {1, 2}, b = {3,4,5}; // type of a is int[2], type of b is int[3]

typedef declarations are often used to inject names from the tag name space into the ordinary name space:

+
typedef struct tnode tnode; // tnode in ordinary name space
+                            // is an alias to tnode in tag name space
+struct tnode {
+    int count;
+    tnode *left, *right; // same as struct tnode *left, *right;
+}; // now tnode is also a complete type
+tnode s, *sp; // same as struct tnode s, *sp;

They can even avoid using the tag name space at all:

+
typedef struct { double hi, lo; } range;
+range z, *zp;

Typedef names are also commonly used to simplify the syntax of complex declarations:

+
// array of 5 pointers to functions returning pointers to arrays of 3 ints
+int (*(*callbacks[5])(void))[3]
+ 
+// same with typedefs
+typedef int arr_t[3]; // arr_t is array of 3 int
+typedef arr_t* (*fp)(void); // pointer to function returning arr_t*
+fp callbacks[5];

Libraries often expose system-dependent or configuration-dependent types as typedef names, to present a consistent interface to the users or to other library components:

+
#if defined(_LP64)
+typedef int     wchar_t;
+#else
+typedef long    wchar_t;
+#endif

References

Keywords

typedef

+

See also

+
C++ documentation for typedef declaration
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/typedef +

+
diff --git a/devdocs/c/language%2Ftypeof.html b/devdocs/c/language%2Ftypeof.html new file mode 100644 index 00000000..b9f1c4e0 --- /dev/null +++ b/devdocs/c/language%2Ftypeof.html @@ -0,0 +1,21 @@ +

typeof operators (since C23) +

Determines the type of an object.

+

Syntax

+ + + + +
typeof( type ) (1)
typeof( expression ) (2)
typeof_unqual( type ) (3)
typeof_unqual( expression ) (4)

Explanation

+1) produces the type-name with any nested typeof-specifier evaluated
+2) yields the type-name representing the type of its operand. No implicit conversions are applied to expression.
+3,4) the same as (1) and (2) respectively but remove qualifiers

Notes

typeof and typeof_unqual are collectively called the typeof operators. The typeof operators cannot be applied to bit-field members. If the type of the operand is a variably modified type, the operand is evaluated; otherwise, the operand is not evaluated. The result of the typeof_unqual operator is the non-atomic unqualified type that would result from the typeof operator. The typeof operator preserves all qualifiers.

+

Example

References

See also

+
C++ documentation for decltype
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/typeof +

+
diff --git a/devdocs/c/language%2Ftypes.html b/devdocs/c/language%2Ftypes.html new file mode 100644 index 00000000..9c57b336 --- /dev/null +++ b/devdocs/c/language%2Ftypes.html @@ -0,0 +1,233 @@ +

Type

(See also arithmetic types for the details on most built-in types and the list of type-related utilities that are provided by the C library.)

+

Objects, functions, and expressions have a property called type, which determines the interpretation of the binary value stored in an object or evaluated by the expression.

+

Type classification

The C type system consists of the following types:

+ + + + +
  • bit-precise: _BitInt(N) where N is an integer constant expression that specifies the number of bits that are used to represent the type, including the sign bit. Each value of N designates a distinct type.
(since C23)
  • extended: implementation defined, e.g. __int128
(since C99)
+ + + +
  • bit-precise: unsigned _BitInt(N) where N is an integer constant expression that specifies the number of bits that are used to represent the type. Each value of N designates a distinct type. This category includes the type unsigned _BitInt(1) which does not have a corresponding bit-precise signed integer type
(since C23)
  • extended: implementation-defined, e.g. __uint128
(since C99)
+ + + +
  • decimal real floating-point types: _Decimal32, _Decimal64, _Decimal128
(since C23)
    +
  • complex types: float _Complex, double _Complex, long double _Complex
    • +
  • imaginary types: float _Imaginary, double _Imaginary, long double _Imaginary
    • +
 (since C99)
+ +
(since C11)

For every type listed above several qualified versions of its type may exist, corresponding to the combinations of one, two, or all three of the const, volatile, and restrict qualifiers (where allowed by the qualifier's semantics).

+

Type groups

Constructing a complete object type such that the number of bytes in its object representation is not representable in the type size_t (i.e. the result type of sizeof operator), including forming such a VLA type at runtime,(since C99) is undefined behavior.

+

Compatible types

In a C program, the declarations referring to the same object or function in different translation units do not have to use the same type. They only have to use sufficiently similar types, formally known as compatible types. Same applies to function calls and lvalue accesses; argument types must be compatible with parameter types and lvalue expression type must be compatible with the object type that is accessed.

+

The types T and U are compatible, if

+ + +
    +
  • one is an old-style (parameter-less) definition, the other has a parameter list, the parameter list does not use an ellipsis and each parameter is compatible (after function parameter type adjustment) with the corresponding old-style parameter after default argument promotions
    • +
  • one is an old-style (parameter-less) declaration, the other has a parameter list, the parameter list does not use an ellipsis, and all parameters (after function parameter type adjustment) are unaffected by default argument promotions
    • +
 (until C23)

The type char is not compatible with signed char and not compatible with unsigned char.

+

If two declarations refer to the same object or function and do not use compatible types, the behavior of the program is undefined.

+
// Translation Unit 1
+struct S { int a; };
+extern struct S *x; // compatible with TU2's x, but not with TU3's x
+ 
+// Translation Unit 2
+struct S;
+extern struct S *x; // compatible with both x's
+ 
+// Translation Unit 3
+struct S { float a; };
+extern struct S *x; // compatible with TU2's x, but not with TU1's x
+ 
+// the behavior is undefined
// Translation Unit 1
+#include <stdio.h>
+ 
+struct s { int i; }; // compatible with TU3's s, but not TU2's
+extern struct s x = {0}; // compatible with TU3's x
+extern void f(void); // compatible with TU2's f
+ 
+int main()
+{
+    f();
+    return x.i;
+}
+ 
+// Translation Unit 2
+struct s { float f; }; // compatible with TU4's s, but not TU1's s
+extern struct s y = {3.14}; // compatible with TU4's y
+void f() // compatible with TU1's f
+{
+    return;
+}
+ 
+// Translation Unit 3
+struct s { int i; }; // compatible with TU1's s, but not TU2's s
+extern struct s x; // compatible with TU1's x
+ 
+// Translation Unit 4
+struct s { float f; }; // compatible with TU2's s, but not TU1's s
+extern struct s y; // compatible with TU2's y
+ 
+// the behavior is well-defined: only multiple declarations
+// of objects and functions must have compatible types, not the types themselves

Note: C++ has no concept of compatible types. A C program that declares two types that are compatible but not identical in different translation units is not a valid C++ program.

+

Composite types

A composite type can be constructed from two types that are compatible; it is a type that is compatible with both of the two types and satisfies the following conditions:

+ + +
    +
  • Otherwise, if one type is a VLA whose size is specified by an expression that is not evaluated, a program necessitating the composite type of both types has undefined behavior.
    • +
  • Otherwise, if one type is a VLA whose size is specified, the composite type is a VLA of that size.
    • +
  • Otherwise, if one type is a VLA of unspecified size, the composite type is a VLA of unspecified size.
    • +
 (since C99)
The element type of the composite type is the composite type of the two element types. + +
  • If only one type is a function type with a parameter type list (a function prototype), the composite type is a function prototype with the parameter type list.
(until C23)

These rules apply recursively to the types from which the two types are derived.

+
// Given the following two file scope declarations:
+int f(int (*)(), double (*)[3]);
+int f(int (*)(char *), double (*)[]); // C23: Error: conflicting types for 'f'
+// The resulting composite type for the function is:
+int f(int (*)(char *), double (*)[3]);

For an identifier with internal or external linkage declared in a scope in which a prior declaration of that identifier is visible, if the prior declaration specifies internal or external linkage, the type of the identifier at the later declaration becomes the composite type.

+

Incomplete types

An incomplete type is an object type that lacks sufficient information to determine the size of the objects of that type. An incomplete type may be completed at some point in the translation unit.

+

The following types are incomplete:

+ 
extern char a[]; // the type of a is incomplete (this typically appears in a header)
+char a[10];      // the type of a is now complete (this typically appears in a source file)
struct node
+{
+    struct node *next; // struct node is incomplete at this point
+}; // struct node is complete at this point

Type names

A type may have to be named in context other than the declaration. In these situations, type name is used, which is, grammatically, exactly the same as a list of type-specifiers and type-qualifiers, followed by the declarator (see declarations) as would be used to declare a single object or function of this type, except that the identifier is omitted:

+
int n; // declaration of an int
+sizeof(int); // use of type name
+ 
+int *a[3]; // declaration of an array of 3 pointers to int
+sizeof(int *[3]); // use of type name
+ 
+int (*p)[3]; // declaration of a pointer to array of 3 int
+sizeof(int (*)[3]); // use of type name
+ 
+int (*a)[*] // declaration of pointer to VLA (in a function parameter)
+sizeof(int (*)[*]) // use of type name (in a function parameter)
+ 
+int *f(void); // declaration of function
+sizeof(int *(void)); // use of type name
+ 
+int (*p)(void); // declaration of pointer to function
+sizeof(int (*)(void)); // use of type name
+ 
+int (*const a[])(unsigned int, ...) = {0}; // array of pointers to functions
+sizeof(int (*const [])(unsigned int, ...)); // use of type name

Except the redundant parentheses around the identifier are meaningful in a type-name and represent "function with no parameter specification":

+
int (n); // declares n of type int
+sizeof(int ()); // uses type "function returning int"

Type names are used in the following situations:

+ + + + +
(since C99)
(since C11)


A type name may introduce a new type:

+
void* p = (void*)(struct X { int i; } *)0;
+// type name "struct X {int i;}*" used in the cast expression
+// introduces the new type "struct X"
+struct X x = {1}; // struct X is now in scope

References

See also

+
C++ documentation for Type
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/types +

+
diff --git a/devdocs/c/language%2Funion.html b/devdocs/c/language%2Funion.html new file mode 100644 index 00000000..bd3b949b --- /dev/null +++ b/devdocs/c/language%2Funion.html @@ -0,0 +1,80 @@ +

Union declaration

A union is a type consisting of a sequence of members whose storage overlaps (as opposed to struct, which is a type consisting of a sequence of members whose storage is allocated in an ordered sequence). The value of at most one of the members can be stored in a union at any one time.

+

The type specifier for a union is identical to the struct type specifier except for the keyword used:

+

Syntax

+ + +
union attr-spec-seq (optional) name (optional) { struct-declaration-list } (1)
union attr-spec-seq (optional) name (2)
+ + + +
name - the name of the union that's being defined
struct-declaration-list - any number of variable declarations, bit-field declarations, and static assert declarations. Members of incomplete type and members of function type are not allowed.
attr-spec-seq - (C23)optional list of attributes, applied to the union type, not allowed for (2) if such form is not followed by a ; (i.e. not a forward declaration).

Explanation

The union is only as big as necessary to hold its largest member (additional unnamed trailing padding may also be added). The other members are allocated in the same bytes as part of that largest member.

+

A pointer to a union can be cast to a pointer to each of its members (if a union has bit-field members, the pointer to a union can be cast to the pointer to the bit-field's underlying type). Likewise, a pointer to any member of a union can be cast to a pointer to the enclosing union.

+ + +

If the member used to access the contents of a union is not the same as the member last used to store a value, the object representation of the value that was stored is reinterpreted as an object representation of the new type (this is known as type punning). If the size of the new type is larger than the size of the last-written type, the contents of the excess bytes are unspecified (and may be a trap representation). Before C99 TC3 (DR 283) this behaviour was undefined, but commonly implemented this way.

+		 (since C99)
+ +

Similar to struct, an unnamed member of a union whose type is a union without name is known as anonymous union. Every member of an anonymous union is considered to be a member of the enclosing struct or union keeping their union layout. This applies recursively if the enclosing struct or union is also anonymous.

+
struct v
+{
+   union // anonymous union
+   {
+       struct { int i, j; }; // anonymous structure
+       struct { long k, l; } w;
+   };
+   int m;
+} v1;
+ 
+v1.i = 2;   // valid
+v1.k = 3;   // invalid: inner structure is not anonymous
+v1.w.k = 5; // valid

Similar to struct, the behavior of the program is undefined if union is defined without any named members (including those obtained via anonymous nested structs or unions).

+		 (since C11)

Keywords

union

+

Notes

See struct initialization for the rules about initialization of structs and unions.

+

Example

#include <assert.h>
+#include <stdint.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    union S
+    {
+        uint32_t u32;
+        uint16_t u16[2];
+        uint8_t  u8;
+    } s = {0x12345678}; // s.u32 is now the active member
+    printf("Union S has size %zu and holds %x\n", sizeof s, s.u32);
+    s.u16[0] = 0x0011;  // s.u16 is now the active member
+    // reading from s.u32 or from s.u8 reinterprets the object representation
+//  printf("s.u8 is now %x\n", s.u8); // unspecified, typically 11 or 00
+//  printf("s.u32 is now %x\n", s.u32); // unspecified, typically 12340011 or 00115678
+ 
+    // pointers to all members of a union compare equal to themselves and the union
+    assert((uint8_t*)&s == &s.u8);
+ 
+    // this union has 3 bytes of trailing padding
+    union pad
+    {
+       char  c[5];   // occupies 5 bytes
+       float f;      // occupies 4 bytes, imposes alignment 4
+    } p = {.f = 1.23}; // the size is 8 to satisfy float's alignment
+    printf("size of union of char[5] and float is %zu\n", sizeof p);
+}

Possible output:

+
Union S has size 4 and holds 12345678
+size of union of char[5] and float is 8

References

See also

+
C++ documentation for Union declaration
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/union +

+
diff --git a/devdocs/c/language%2Fvalue_category.html b/devdocs/c/language%2Fvalue_category.html new file mode 100644 index 00000000..8306ec83 --- /dev/null +++ b/devdocs/c/language%2Fvalue_category.html @@ -0,0 +1,58 @@ +

Value categories

Each expression in C (an operator with its arguments, a function call, a constant, a variable name, etc) is characterized by two independent properties: a type and a value category.

+

Every expression belongs to one of three value categories: lvalue, non-lvalue object (rvalue), and function designator.

+

Lvalue expressions

Lvalue expression is any expression with object type other than the type void, which potentially designates an object (the behavior is undefined if an lvalue does not actually designate an object when it is evaluated). In other words, lvalue expression evaluates to the object identity. The name of this value category ("left value") is historic and reflects the use of lvalue expressions as the left-hand operand of the assignment operator in the CPL programming language.

+

Lvalue expressions can be used in the following lvalue contexts:

+

If an lvalue expression is used in any context other than sizeof, _Alignof, or the operators listed above, non-array lvalues of any complete type undergo lvalue conversion, which models the memory load of the value of the object from its location. Similarly, array lvalues undergo array-to-pointer conversion when used in any context other than sizeof, _Alignof, address-of operator, or array initialization from a string literal.

+

The semantics of const/volatile/restrict-qualifiers and atomic types apply to lvalues only (lvalue conversion strips the qualifiers and removes atomicity).

+

The following expressions are lvalues:

+

Modifiable lvalue expressions

A modifiable lvalue is any lvalue expression of complete, non-array type which is not const-qualified, and, if it's a struct/union, has no members that are const-qualified, recursively.

+

Only modifiable lvalue expressions may be used as arguments to increment/decrement, and as left-hand arguments of assignment and compound assignment operators.

+

Non-lvalue object expressions

Known as rvalues, non-lvalue object expressions are the expressions of object types that do not designate objects, but rather values that have no object identity or storage location. The address of a non-lvalue object expression cannot be taken.

+

The following expressions are non-lvalue object expressions:

+

As a special case, expressions of type void are assumed to be non-lvalue object expressions that yield a value which has no representation and requires no storage.

+

Note that a struct/union rvalue that has a member (possibly nested) of array type does in fact designate an object with temporary lifetime. This object can be accessed through lvalue expressions that form by indexing the array member or by indirection through the pointer obtained by array-to-pointer conversion of the array member.

+

Function designator expression

A function designator (the identifier introduced by a function declaration) is an expression of function type. When used in any context other than the address-of operator, sizeof, and _Alignof (the last two generate compile errors when applied to functions), the function designator is always converted to a non-lvalue pointer to function. Note that the function-call operator is defined for pointers to functions and not for function designators themselves.

+

References

See also

+
C++ documentation for Value categories
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/value_category +

+
diff --git a/devdocs/c/language%2Fvariadic.html b/devdocs/c/language%2Fvariadic.html new file mode 100644 index 00000000..610036e5 --- /dev/null +++ b/devdocs/c/language%2Fvariadic.html @@ -0,0 +1,73 @@ +

Variadic arguments

Variadic functions are functions that may be called with different number of arguments.

+

Only prototyped function declarations may be variadic. This is indicated by the parameter of the form ... which must appear last in the parameter list and must follow at least one named parameter(until C23). The ellipsis parameter and the proceeding parameter must be delimited by ,.

+
// Prototyped declaration
+int printx(const char* fmt, ...); // function declared this way
+printx("hello world");     // may be called with one
+printx("a=%d b=%d", a, b); // or more arguments
+ 
+int printz(...); // OK since C23 and in C++
+// Error until C23: ... must follow at least one named parameter
+ 
+// int printy(..., const char* fmt); // Error: ... must be the last
+// int printa(const char* fmt...);   // Error in C: ',' is required; OK in C++

At the function call, each argument that is a part of the variable argument list undergoes special implicit conversions known as default argument promotions.

+

Within the body of a function that uses variadic arguments, the values of these arguments may be accessed using the <stdarg.h> library facilities:

+ + + + + + +
Defined in header <stdarg.h>
enables access to variadic function arguments
(function macro)
accesses the next variadic function argument
(function macro)
+
(C99)
 makes a copy of the variadic function arguments
(function macro)
ends traversal of the variadic function arguments
(function macro)
holds the information needed by va_start, va_arg, va_end, and va_copy
(typedef)

Notes

Although old-style (prototype-less) function declarations allow the subsequent function calls to use any number of arguments, they are not allowed to be variadic (as of C89). The definition of such function must specify a fixed number of parameters and cannot use the stdarg.h macros.

+
// old-style declaration, removed in C23
+int printx(); // function declared this way
+printx("hello world");     // may be called with one
+printx("a=%d b=%d", a, b); // or more arguments
+// the behavior of at least one of these calls is undefined, depending on
+// the number of parameters the function is defined to take

Example

#include <stdio.h>
+#include <time.h>
+#include <stdarg.h>
+ 
+void tlog(const char* fmt,...)
+{
+    char msg[50];
+    strftime(msg, sizeof msg, "%T", localtime(&(time_t){time(NULL)}));
+    printf("[%s] ", msg);
+    va_list args;
+    va_start(args, fmt);
+    vprintf(fmt, args);
+    va_end(args);
+}
+ 
+int main(void)
+{
+   tlog("logging %d %d %d...\n", 1, 2, 3);
+}

Output:

+
[10:21:38] logging 1 2 3...

References

See also

+
C++ documentation for Variadic arguments
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/variadic +

+
diff --git a/devdocs/c/language%2Fvolatile.html b/devdocs/c/language%2Fvolatile.html new file mode 100644 index 00000000..fa12c267 --- /dev/null +++ b/devdocs/c/language%2Fvolatile.html @@ -0,0 +1,86 @@ +

volatile type qualifier

Each individual type in the C type system has several qualified versions of that type, corresponding to one, two, or all three of the const, volatile, and, for pointers to object types, restrict qualifiers. This page describes the effects of the volatile qualifier.

+

Every access (both read and write) made through an lvalue expression of volatile-qualified type is considered an observable side effect for the purpose of optimization and is evaluated strictly according to the rules of the abstract machine (that is, all writes are completed at some time before the next sequence point). This means that within a single thread of execution, a volatile access cannot be optimized out or reordered relative to another visible side effect that is separated by a sequence point from the volatile access.

+

A cast of a non-volatile value to a volatile type has no effect. To access a non-volatile object using volatile semantics, its address must be cast to a pointer-to-volatile and then the access must be made through that pointer.

+

Any attempt to read or write to an object whose type is volatile-qualified through a non-volatile lvalue results in undefined behavior:

+
volatile int n = 1; // object of volatile-qualified type
+int* p = (int*)&n;
+int val = *p; // undefined behavior

A member of a volatile-qualified structure or union type acquires the qualification of the type it belongs to (both when accessed using the . operator or the -> operator):

+
struct s { int i; const int ci; } s;
+// the type of s.i is int, the type of s.ci is const int
+volatile struct s vs;
+// the types of vs.i and vs.ci are volatile int and const volatile int
+ + + +

If an array type is declared with the volatile type qualifier (through the use of typedef), the array type is not volatile-qualified, but its element type is.

+		 (until C23)

An array type and its element type are always considered to be identically volatile-qualified.

+		 (since C23)
typedef int A[2][3];
+volatile A a = {{4, 5, 6}, {7, 8, 9}}; // array of array of volatile int
+int* pi = a[0]; // Error: a[0] has type volatile int*
+void *unqual_ptr = a; // OK until C23; error since C23
+// Notes: clang applies the rule in C++/C23 even in C89-C17 modes

If a function type is declared with the volatile type qualified (through the use of typedef), the behavior is undefined.

+ + +

In a function declaration, the keyword volatile may appear inside the square brackets that are used to declare an array type of a function parameter. It qualifies the pointer type to which the array type is transformed.

+

The following two declarations declare the same function:

+
void f(double x[volatile], const double y[volatile]);
+void f(double * volatile x, const double * volatile y);
 (since C99)

A pointer to a non-volatile type can be implicitly converted to a pointer to the volatile-qualified version of the same or compatible type. The reverse conversion requires a cast expression.

+
int* p = 0;
+volatile int* vp = p; // OK: adds qualifiers (int to volatile int)
+p = vp; // Error: discards qualifiers (volatile int to int)
+p = (int*)vp; // OK: cast

Note that pointer to pointer to T is not convertible to pointer to pointer to volatile T; for two types to be compatible, their qualifications must be identical:

+
char *p = 0;
+volatile char **vpp = &p; // Error: char* and volatile char* are not compatible types
+char * volatile *pvp = &p; // OK, adds qualifiers (char* to char*volatile)

Uses of volatile

+1) static volatile objects model memory-mapped I/O ports, and static const volatile objects model memory-mapped input ports, such as a real-time clock: 
volatile short *ttyport = (volatile short*)TTYPORT_ADDR;
+for(int i = 0; i < N; ++i)
+    *ttyport = a[i]; // *ttyport is an lvalue of type volatile short
+
+2) static volatile objects of type sig_atomic_t are used for communication with signal handlers.
+3) volatile variables that are local to a function that contains an invocation of the setjmp macro are the only local variables guaranteed to retain their values after longjmp returns.
+4) In addition, volatile variables can be used to disable certain forms of optimization, e.g. to disable dead store elimination or constant folding for micro-benchmarks.

Note that volatile variables are not suitable for communication between threads; they do not offer atomicity, synchronization, or memory ordering. A read from a volatile variable that is modified by another thread without synchronization or concurrent modification from two unsynchronized threads is undefined behavior due to a data race.

+

Keywords

volatile

+

Example

+

demonstrates the use of volatile to disable optimizations

+
#include <stdio.h>
+#include <time.h>
+ 
+int main(void)
+{
+    clock_t t = clock();
+    double d = 0.0;
+    for (int n = 0; n < 10000; ++n)
+        for (int m = 0; m < 10000; ++m)
+            d += d * n * m; // reads from and writes to a non-volatile 
+    printf("Modified a non-volatile variable 100m times. "
+           "Time used: %.2f seconds\n",
+           (double)(clock() - t)/CLOCKS_PER_SEC);
+ 
+    t = clock();
+    volatile double vd = 0.0;
+    for (int n = 0; n < 10000; ++n)
+        for (int m = 0; m < 10000; ++m) {
+            double prod = vd * n * m; // reads from a volatile
+            vd += prod; // reads from and writes to a volatile
+        } 
+    printf("Modified a volatile variable 100m times. "
+           "Time used: %.2f seconds\n",
+           (double)(clock() - t)/CLOCKS_PER_SEC);
+}

Possible output:

+
Modified a non-volatile variable 100m times. Time used: 0.00 seconds
+Modified a volatile variable 100m times. Time used: 0.79 seconds

References

See also

+
C++ documentation for cv (const and volatile) type qualifiers
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/volatile +

+
diff --git a/devdocs/c/language%2Fwhile.html b/devdocs/c/language%2Fwhile.html new file mode 100644 index 00000000..72920439 --- /dev/null +++ b/devdocs/c/language%2Fwhile.html @@ -0,0 +1,59 @@ +

while loop

Executes a statement repeatedly, until the value of expression becomes equal to zero. The test takes place before each iteration.

+

Syntax

+ +
attr-spec-seq(optional) while ( expression ) statement
+ + + +
expression - any expression of scalar type. This expression is evaluated before each iteration, and if it compares equal to zero, the loop is exited.
statement - any statement, typically a compound statement, which serves as the body of the loop
attr-spec-seq - (C23)optional list of attributes, applied to the loop statement

Explanation

A while statement causes the statement (also called the loop body) to be executed repeatedly until the expression (also called controlling expression) compares equal to zero. The repetition occurs regardless of whether the loop body is entered normally or by a goto into the middle of statement.

+

The evaluation of expression takes place before each execution of statement (unless entered by a goto). If the controlling expression needs to be evaluated after the loop body, the do-while loop may be used.

+

If the execution of the loop needs to be terminated at some point, break statement can be used as a terminating statement.

+

If the execution of the loop needs to be continued at the end of the loop body, continue statement can be used as a shortcut.

+

A program with an endless loop has undefined behavior if the loop has no observable behavior (I/O, volatile accesses, atomic or synchronization operation) in any part of its statement or expression. This allows the compilers to optimize out all unobservable loops without proving that they terminate. The only exceptions are the loops where expression is a constant expression; while(true) is always an endless loop.

+ + +

As with all other selection and iteration statements, the while statement establishes block scope: any identifier introduced in the expression goes out of scope after the statement.

+		 (since C99)

Notes

Boolean and pointer expressions are often used as loop controlling expressions. The boolean value false and the null pointer value of any pointer type compare equal to zero.

+

Keywords

while

+

Example

#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+enum { SIZE = 8 };
+int main(void)
+{
+    // trivial example
+    int array[SIZE], n = 0;
+    while(n < SIZE) array[n++] = rand() % 2;
+    puts("Array filled!");
+    n = 0;
+    while(n < SIZE) printf("%d ", array[n++]);
+    printf("\n");
+ 
+    // classic strcpy() implementation
+    // (copies a null-terminated string from src to dst)
+    char src[] = "Hello, world", dst[sizeof src], *p = dst, *q = src;
+    while((*p++ = *q++)) // double parentheses (that are not strictly necessary)
+                         // used to suppress warnings, ensuring that this is an
+                         // assignment (as opposed to a comparison) by intention,
+                         // whose result is used as a truth value
+        ; // null statement
+    puts(dst);
+}

Output:

+
Array filled!
+1 0 1 1 1 1 0 0 
+Hello, world

References

See also

+
C++ documentation for while loop
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language/while +

+
diff --git a/devdocs/c/language.html b/devdocs/c/language.html new file mode 100644 index 00000000..a06d6090 --- /dev/null +++ b/devdocs/c/language.html @@ -0,0 +1,27 @@ +

C language

This is a reference of the core C language constructs.

+ + +

Basic concepts

+

Comments
ASCII chart
Character sets and encodings
Translation phases
Punctuation
Identifier - Scope - Lifetime
Lookup and Name Spaces
Type - Arithmetic types
Objects and Alignment
The main function
As-if rule
Undefined behavior
Memory model and Data races

+

Keywords

+

Preprocessor

+

#if - #ifdef - #ifndef - #elif
#elifdef - #elifndef(C23)
#define - # - ##
#include - #pragma
#line - #error
#warning(C23) - #embed(C23)

+

Statements

+

if - switch
for
while - do-while
continue - break
goto - return

+

Expressions

+

Value categories
Evaluation order and sequencing
Constants and literals
Integer constants
Floating constants
Character constants
true/false(C23)
nullptr(C23)
String literals
Compound literals(C99)
Constant expressions
Implicit conversions
Operators
Member access and indirection
Logical - Comparison
Arithmetic - Assignment
Increment and Decrement
Call, Comma, Ternary
sizeof - _Alignof(C11)
Cast operators
Operator precedence
Generic selection(C11)

+

Initialization

+

Scalar
Array
Structure/Union

+

Declarations

+

Pointers - Arrays
Enumerations
Storage duration and Linkage
const - volatile - restrict(C99)
struct - union - Bit-fields
_Alignas(C11) - typedef
_Static_assert(C11)
Atomic types(C11)
External and tentative definitions
Attributes(C23)

+

Functions

+

Function declaration
Function definition
inline(C99)
_Noreturn(C11)(deprecated in C23)
Variadic arguments

+

Miscellaneous

+

History of C
Conformance
Inline assembly
Signal handling
Analyzability(C11)

+

See also

+
C++ documentation for C++ language constructs
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/language +

+
diff --git a/devdocs/c/locale%2Flc_categories.html b/devdocs/c/locale%2Flc_categories.html new file mode 100644 index 00000000..a4a55fb5 --- /dev/null +++ b/devdocs/c/locale%2Flc_categories.html @@ -0,0 +1,50 @@ +

LC_ALL, LC_COLLATE, LC_CTYPE, LC_MONETARY, LC_NUMERIC, LC_TIME

Defined in header <locale.h> 
#define LC_ALL      /*implementation defined*/
+		 
#define LC_COLLATE  /*implementation defined*/
+		 
#define LC_CTYPE    /*implementation defined*/
+		 
#define LC_MONETARY /*implementation defined*/
+		 
#define LC_NUMERIC  /*implementation defined*/
+		 
#define LC_TIME     /*implementation defined*/
+

Each of the above macro constants expand to integer constant expressions with distinct values that are suitable for use as the first argument of setlocale.

+ + + + + + + +
Constant Explanation
LC_ALL selects the entire C locale
LC_COLLATE selects the collation category of the C locale
LC_CTYPE selects the character classification category of the C locale
LC_MONETARY selects the monetary formatting category of the C locale
LC_NUMERIC selects the numeric formatting category of the C locale
LC_TIME selects the time formatting category of the C locale

Additional macro constants, with names that begin with LC_ followed by at least one uppercase letter, may be defined in locale.h. For example, the POSIX specification requires LC_MESSAGES (which controls, among other things, perror and strerror), ISO/IEC 30112:2014 (2014 draft) additionally defines LC_IDENTIFICATION, LC_XLITERATE, LC_NAME, LC_ADDRESS, LC_TELEPHONE, LC_PAPER, LC_MEASUREMENT, and LC_KEYBOARD, which are supported by the GNU C library (except for LC_XLITERATE).

+

Example

#include <locale.h>
+#include <stdio.h>
+#include <time.h>
+#include <wchar.h>
+ 
+int main(void)
+{
+    setlocale(LC_ALL, "en_US.UTF-8"); // the C locale will be the UTF-8 enabled English
+    setlocale(LC_NUMERIC, "de_DE.utf8"); // decimal dot will be German
+    setlocale(LC_TIME, "ja_JP.utf8");    // date/time formatting will be Japanese
+    wchar_t str[100];
+    time_t t = time(NULL);
+    wcsftime(str, 100, L"%A %c", localtime(&t));
+    wprintf(L"Number: %.2f\nDate: %Ls\n", 3.14, str);
+}

Possible output:

+
Number: 3,14
+Date: 金曜日 2023年09月15日 20時04分14秒

References

See also

+ +
gets and sets the current C locale
(function)
C++ documentation for locale categories
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/locale/LC_categories +

+
diff --git a/devdocs/c/locale%2Flconv.html b/devdocs/c/locale%2Flconv.html new file mode 100644 index 00000000..1194b651 --- /dev/null +++ b/devdocs/c/locale%2Flconv.html @@ -0,0 +1,71 @@ +

lconv

Defined in header <locale.h> 
struct lconv;
+

The struct lconv contains numeric and monetary formatting rules as defined by a C locale. Objects of this struct may be obtained with localeconv. The members of lconv are values of type char and of type char*. Each char* member except decimal_point may be pointing at a null character (that is, at an empty C-string). The members of type char are all non-negative numbers, any of which may be CHAR_MAX if the corresponding value is not available in the current C locale.

+

Member objects

Non-monetary numeric formatting parameters

+ + +
char* decimal_point
 the character used as the decimal point
(public member object)
char* thousands_sep
 the character used to separate groups of digits before the decimal point
(public member object)
char* grouping
 a string whose elements indicate the sizes of digit groups
(public member object)

Monetary numeric formatting parameters

+ + + + +
char* mon_decimal_point
 the character used as the decimal point
(public member object)
char* mon_thousands_sep
 the character used to separate groups of digits before the decimal point
(public member object)
char* mon_grouping
 a string whose elements indicate the sizes of digit groups
(public member object)
char* positive_sign
 a string used to indicate non-negative monetary quantity
(public member object)
char* negative_sign
 a string used to indicate negative monetary quantity
(public member object)

Local monetary numeric formatting parameters

+ + + + + + + +
char* currency_symbol
 the symbol used for currency in the current C locale
(public member object)
char frac_digits
 the number of digits after the decimal point to display in a monetary quantity
(public member object)
char p_cs_precedes
 1 if currency_symbol is placed before non-negative value, ​0​ if after
(public member object)
char n_cs_precedes
 1 if currency_symbol is placed before negative value, ​0​ if after
(public member object)
char p_sep_by_space
 indicates the separation of currency_symbol, positive_sign, and the non-negative monetary value
(public member object)
char n_sep_by_space
 indicates the separation of currency_symbol, negative_sign, and the negative monetary value
(public member object)
char p_sign_posn
 indicates the position of positive_sign in a non-negative monetary value
(public member object)
char n_sign_posn
 indicates the position of negative_sign in a negative monetary value
(public member object)

International monetary numeric formatting parameters

+ + + + + + + +
char* int_curr_symbol
 the string used as international currency name in the current C locale
(public member object)
char int_frac_digits
 the number of digits after the decimal point to display in an international monetary quantity
(public member object)
char int_p_cs_precedes
+
(C99)
 1 if int_curr_symbol is placed before non-negative international monetary value, ​0​ if after
(public member object)
char int_n_cs_precedes
+
(C99)
 1 if int_curr_symbol is placed before negative international monetary value, ​0​ if after
(public member object)
char int_p_sep_by_space
+
(C99)
 indicates the separation of int_curr_symbol, positive_sign, and the non-negative international monetary value
(public member object)
char int_n_sep_by_space
+
(C99)
 indicates the separation of int_curr_symbol, negative_sign, and the negative international monetary value
(public member object)
char int_p_sign_posn
+
(C99)
 indicates the position of positive_sign in a non-negative international monetary value
(public member object)
char int_n_sign_posn
+
(C99)
 indicates the position of negative_sign in a negative international monetary value
(public member object)


The characters of the C-strings pointed to by grouping and mon_grouping are interpreted according to their numeric values. When the terminating '\0' is encountered, the last value seen is assumed to repeat for the remainder of digits. If CHAR_MAX is encountered, no further digits are grouped. The typical grouping of three digits at a time is "\003".

+

The values of p_sep_by_space, n_sep_by_space, int_p_sep_by_space, int_n_sep_by_space are interpreted as follows:

+ + + +
0 no space separates the currency symbol and the value
1 sign sticks to the currency symbol, value is separated by a space
2 sign sticks to the value. Currency symbol is separated by a space

The values of p_sign_posn, n_sign_posn, int_p_sign_posn, int_n_sign_posn are interpreted as follows:

+ + + + + +
0 parentheses around the value and the currency symbol are used to represent the sign
1 sign before the value and the currency symbol
2 sign after the value and the currency symbol
3 sign before the currency symbol
4 sign after the currency symbol

Example

#include <locale.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    setlocale(LC_ALL, "ja_JP.UTF-8");
+    struct lconv *lc = localeconv();
+    printf("Japanese currency symbol: %s(%s)\n", lc->currency_symbol, lc->int_curr_symbol);
+}

Possible output:

+
Japanese currency symbol: ￥(JPY )

References

See also

+ +
queries numeric and monetary formatting details of the current locale
(function)
C++ documentation for lconv
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/locale/lconv +

+
diff --git a/devdocs/c/locale%2Flocaleconv.html b/devdocs/c/locale%2Flocaleconv.html new file mode 100644 index 00000000..d4222e7d --- /dev/null +++ b/devdocs/c/locale%2Flocaleconv.html @@ -0,0 +1,33 @@ +

localeconv

Defined in header <locale.h> 
struct lconv *localeconv(void);
+

The localeconv function obtains a pointer to a static object of type lconv, which represents numeric and monetary formatting rules of the current C locale.

+

Parameters

(none)

+

Return value

pointer to the current lconv object.

+

Notes

Modifying the object references through the returned pointer is undefined behavior.

+

localeconv modifies a static object, calling it from different threads without synchronization is undefined behavior.

+

Example

#include <stdio.h>
+#include <locale.h>
+ 
+int main(void)
+{
+  setlocale(LC_MONETARY, "en_IN.utf8");
+  struct lconv *lc = localeconv();
+  printf("Local Currency Symbol        : %s\n", lc->currency_symbol);
+  printf("International Currency Symbol: %s\n", lc->int_curr_symbol);
+}

Output:

+
Local Currency Symbol        : ₹
+International Currency Symbol: INR

References

See also

+ + +
gets and sets the current C locale
(function)
formatting details, returned by localeconv
(struct)
C++ documentation for localeconv
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/locale/localeconv +

+
diff --git a/devdocs/c/locale%2Fsetlocale.html b/devdocs/c/locale%2Fsetlocale.html new file mode 100644 index 00000000..23244989 --- /dev/null +++ b/devdocs/c/locale%2Fsetlocale.html @@ -0,0 +1,49 @@ +

setlocale

Defined in header <locale.h> 
char* setlocale( int category, const char* locale );
+

The setlocale function installs the specified system locale or its portion as the new C locale. The modifications remain in effect and influences the execution of all locale-sensitive C library functions until the next call to setlocale. If locale is a null pointer, setlocale queries the current C locale without modifying it.

+

Parameters

+ + +
category - locale category identifier, one of the LC_xxx macros. May be null.
locale - system-specific locale identifier. Can be "" for the user-preferred locale or "C" for the minimal locale

Return value

pointer to a narrow null-terminated string identifying the C locale after applying the changes, if any, or null pointer on failure.

+

A copy of the returned string along with the category used in this call to setlocale may be used later in the program to restore the locale back to the state at the end of this call.

+

Notes

During program startup, the equivalent of setlocale(LC_ALL, "C"); is executed before any user code is run.

+

Although the return type is char*, modifying the pointed-to characters is undefined behavior.

+

Because setlocale modifies global state which affects execution of locale-dependent functions, it is undefined behavior to call it from one thread, while another thread is executing any of the following functions: fprintf, isprint, iswdigit, localeconv, tolower, fscanf, ispunct, iswgraph, mblen, toupper, isalnum, isspace, iswlower, mbstowcs, towlower, isalpha, isupper, iswprint, mbtowc, towupper, isblank, iswalnum, iswpunct, setlocale, wcscoll, iscntrl, iswalpha, iswspace, strcoll, wcstod, isdigit, iswblank, iswupper, strerror, wcstombs, isgraph, iswcntrl, iswxdigit, strtod, wcsxfrm, islower, iswctype, isxdigit.

+

POSIX also defines a locale named "POSIX", which is always accessible and is exactly equivalent to the default minimal "C" locale.

+

POSIX also specifies that the returned pointer, not just the contents of the pointed-to string, may be invalidated by subsequent calls to setlocale.

+

Example

#include <stdio.h>
+#include <locale.h>
+#include <time.h>
+#include <wchar.h>
+ 
+int main(void)
+{
+    // the C locale will be UTF-8 enabled English;
+    // decimal dot will be German
+    // date and time formatting will be Japanese
+    setlocale(LC_ALL, "en_US.UTF-8");
+    setlocale(LC_NUMERIC, "de_DE.utf8");
+    setlocale(LC_TIME, "ja_JP.utf8");
+ 
+    wchar_t str[100];
+    time_t t = time(NULL);
+    wcsftime(str, 100, L"%A %c", localtime(&t));
+    wprintf(L"Number: %.2f\nDate: %ls\n", 3.14, str);
+}

Possible output:

+
Number: 3,14
+Date: 月曜日 2017年09月25日 13時00分15秒

References

See also

+ +
locale categories for setlocale
(macro constant)
C++ documentation for setlocale
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/locale/setlocale +

+
diff --git a/devdocs/c/locale.html b/devdocs/c/locale.html new file mode 100644 index 00000000..5fd68956 --- /dev/null +++ b/devdocs/c/locale.html @@ -0,0 +1,29 @@ +

Localization support

+ + + + + +
Defined in header <locale.h>
gets and sets the current C locale
(function)
queries numeric and monetary formatting details of the current locale
(function)
formatting details, returned by localeconv
(struct)
Locale categories
locale categories for setlocale
(macro constant)

References

See also

+
C++ documentation for Localization library
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/locale +

+
diff --git a/devdocs/c/memory%2Faligned_alloc.html b/devdocs/c/memory%2Faligned_alloc.html new file mode 100644 index 00000000..839438f0 --- /dev/null +++ b/devdocs/c/memory%2Faligned_alloc.html @@ -0,0 +1,42 @@ +

aligned_alloc

Defined in header <stdlib.h> 
void *aligned_alloc( size_t alignment, size_t size );
+		 (since C11)

Allocate size bytes of uninitialized storage whose alignment is specified by alignment. The size parameter must be an integral multiple of alignment.

+

aligned_alloc is thread-safe: it behaves as though only accessing the memory locations visible through its argument, and not any static storage.

+

A previous call to free or realloc that deallocates a region of memory synchronizes-with a call to aligned_alloc that allocates the same or a part of the same region of memory. This synchronization occurs after any access to the memory by the deallocating function and before any access to the memory by aligned_alloc. There is a single total order of all allocation and deallocation functions operating on each particular region of memory.

+

Parameters

+ + +
alignment - specifies the alignment. Must be a valid alignment supported by the implementation.
size - number of bytes to allocate. An integral multiple of alignment

Return value

On success, returns the pointer to the beginning of newly allocated memory. To avoid a memory leak, the returned pointer must be deallocated with free or realloc.

+

On failure, returns a null pointer.

+

Notes

Passing a size which is not an integral multiple of alignment or an alignment which is not valid or not supported by the implementation causes the function to fail and return a null pointer (C11, as published, specified undefined behavior in this case, this was corrected by DR460). Removal of size restrictions to make it possible to allocate small objects at restrictive alignment boundaries (similar to alignas) has been proposed by N2072.

+

As an example of the "supported by the implementation" requirement, POSIX function posix_memalign accepts any alignment that is a power of two and a multiple of sizeof(void *), and POSIX-based implementations of aligned_alloc inherit this requirements.

+

Fundamental alignments are always supported. If alignment is a power of two and not greater than _Alignof(max_align_t), aligned_alloc may simply call malloc.

+

Regular malloc aligns memory suitable for any object type with a fundamental alignment. The aligned_alloc is useful for over-aligned allocations, such as to SSE, cache line, or VM page boundary.

+

This function is not supported in Microsoft C Runtime library because its implementation of std::free is unable to handle aligned allocations of any kind. Instead, MS CRT provides _aligned_malloc (to be freed with _aligned_free).

+

Example

#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    int *p1 = malloc(10*sizeof *p1);
+    printf("default-aligned addr:   %p\n", (void*)p1);
+    free(p1);
+ 
+    int *p2 = aligned_alloc(1024, 1024*sizeof *p2);
+    printf("1024-byte aligned addr: %p\n", (void*)p2);
+    free(p2);
+}

Possible output:

+
default-aligned addr:   0x1e40c20
+1024-byte aligned addr: 0x1e41000

References

See also

+
C++ documentation for aligned_alloc
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/memory/aligned_alloc +

+
diff --git a/devdocs/c/memory%2Fcalloc.html b/devdocs/c/memory%2Fcalloc.html new file mode 100644 index 00000000..4c0abf87 --- /dev/null +++ b/devdocs/c/memory%2Fcalloc.html @@ -0,0 +1,62 @@ +

calloc

Defined in header <stdlib.h> 
void* calloc( size_t num, size_t size );
+

Allocates memory for an array of num objects of size and initializes all bytes in the allocated storage to zero.

+

If allocation succeeds, returns a pointer to the lowest (first) byte in the allocated memory block that is suitably aligned for any object type with fundamental alignment.

+

If size is zero, the behavior is implementation defined (null pointer may be returned, or some non-null pointer may be returned that may not be used to access storage).

+ + +

calloc is thread-safe: it behaves as though only accessing the memory locations visible through its argument, and not any static storage.

+

A previous call to free or realloc that deallocates a region of memory synchronizes-with a call to calloc that allocates the same or a part of the same region of memory. This synchronization occurs after any access to the memory by the deallocating function and before any access to the memory by calloc. There is a single total order of all allocation and deallocation functions operating on each particular region of memory.

+		 (since C11)

Parameters

+ + +
num - number of objects
size - size of each object

Return value

On success, returns the pointer to the beginning of newly allocated memory. To avoid a memory leak, the returned pointer must be deallocated with free() or realloc().

+

On failure, returns a null pointer.

+

Notes

Due to the alignment requirements, the number of allocated bytes is not necessarily equal to num * size.

+

Initialization to all bits zero does not guarantee that a floating-point or a pointer would be initialized to 0.0 and the null pointer value, respectively (although that is true on all common platforms).

+

Originally (in C89), support for zero size was added to accommodate code such as

+
OBJ* p = calloc(0, sizeof(OBJ)); // "zero-length" placeholder
+...
+while(1)
+{
+    p = realloc(p, c * sizeof(OBJ)); // reallocations until size settles
+    ... // code that may change c or break out of loop
+}

Example

#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    int* p1 = calloc(4, sizeof(int));    // allocate and zero out an array of 4 int
+    int* p2 = calloc(1, sizeof(int[4])); // same, naming the array type directly
+    int* p3 = calloc(4, sizeof *p3);     // same, without repeating the type name
+ 
+    if (p2)
+    {
+        for (int n = 0; n < 4; ++n) // print the array
+            printf("p2[%d] == %d\n", n, p2[n]);
+    }
+ 
+    free(p1);
+    free(p2);
+    free(p3);
+}

Output:

+
p2[0] == 0
+p2[1] == 0
+p2[2] == 0
+p2[3] == 0

References

See also

+
C++ documentation for calloc
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/memory/calloc +

+
diff --git a/devdocs/c/memory%2Ffree.html b/devdocs/c/memory%2Ffree.html new file mode 100644 index 00000000..47298dbf --- /dev/null +++ b/devdocs/c/memory%2Ffree.html @@ -0,0 +1,50 @@ +

free

Defined in header <stdlib.h> 
void free( void *ptr );
+

Deallocates the space previously allocated by malloc(), calloc(), aligned_alloc(),(since C11) or realloc().

+

If ptr is a null pointer, the function does nothing.

+

The behavior is undefined if the value of ptr does not equal a value returned earlier by malloc(), calloc(), realloc(), or aligned_alloc()(since C11).

+

The behavior is undefined if the memory area referred to by ptr has already been deallocated, that is, free(), free_sized(), free_aligned_sized()(since C23), or realloc() has already been called with ptr as the argument and no calls to malloc(), calloc(), realloc(), or aligned_alloc()(since C11) resulted in a pointer equal to ptr afterwards.

+

The behavior is undefined if after free() returns, an access is made through the pointer ptr (unless another allocation function happened to result in a pointer value equal to ptr).

+ + +

free is thread-safe: it behaves as though only accessing the memory locations visible through its argument, and not any static storage.

+

A call to free that deallocates a region of memory synchronizes-with a call to any subsequent allocation function that allocates the same or a part of the same region of memory. This synchronization occurs after any access to the memory by the deallocating function and before any access to the memory by the allocation function. There is a single total order of all allocation and deallocation functions operating on each particular region of memory.

+		 (since C11)

Parameters

+ +
ptr - pointer to the memory to deallocate

Return value

(none)

+

Notes

The function accepts (and does nothing with) the null pointer to reduce the amount of special-casing. Whether allocation succeeds or not, the pointer returned by an allocation function can be passed to free().

+

Example

#include <stdlib.h>
+ 
+int main(void)
+{
+    int *p1 = malloc(10*sizeof *p1);
+    free(p1); // every allocated pointer must be freed
+ 
+    int *p2 = calloc(10, sizeof *p2);
+    int *p3 = realloc(p2, 1000*sizeof *p3);
+    if(p3) // p3 not null means p2 was freed by realloc
+       free(p3);
+    else // p3 null means p2 was not freed
+       free(p2);
+}

References

See also

+ + + +
allocates memory
(function)
+
(C23)
 deallocates previously allocated sized memory
(function)
+
(C23)
 deallocates previously allocated sized and aligned memory
(function)
C++ documentation for free
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/memory/free +

+
diff --git a/devdocs/c/memory%2Ffree_aligned_sized.html b/devdocs/c/memory%2Ffree_aligned_sized.html new file mode 100644 index 00000000..f4aeba49 --- /dev/null +++ b/devdocs/c/memory%2Ffree_aligned_sized.html @@ -0,0 +1,20 @@ +

free_aligned_sized

Defined in header <stdlib.h> 
void free_aligned_sized( void* ptr, size_t alignment, size_t size);
+		 (since C23)

If ptr is a null pointer or the result obtained from a call to aligned_alloc, where alignment is equal to the requested allocation alignment and size is equal to the requested allocation size, this function is equivalent to free(ptr). Otherwise, the behavior is undefined.

+

Note: The result of an malloc, calloc, or realloc call may not be passed to free_aligned_sized.

+

Parameters

+ + + +
ptr - pointer to the memory to deallocate
alignment - alignment of memory to deallocate
size - size of memory to deallocate

Return value

(none)

+

Example

See also

+ + + +
+
(C11)
 allocates aligned memory
(function)
deallocates previously allocated memory
(function)
+
(C23)
 deallocates previously allocated sized memory
(function)
allocates memory
(function)
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/memory/free_aligned_sized +

+
diff --git a/devdocs/c/memory%2Ffree_sized.html b/devdocs/c/memory%2Ffree_sized.html new file mode 100644 index 00000000..36a5ad8f --- /dev/null +++ b/devdocs/c/memory%2Ffree_sized.html @@ -0,0 +1,70 @@ +

free_sized

Defined in header <stdlib.h> 
void free_sized( void* ptr, size_t size );
+		 (since C23)

Deallocates the space previously allocated by malloc(), calloc(), or realloc() (but not aligned_alloc()).

+

Parameters

+ + +
ptr - pointer to the memory to deallocate
size - size of memory previously passed to an allocation function

Return value

(none)

+

Notes

Possible implementation

void free_sized(void* ptr, size_t /*size*/)
+{
+    free(ptr);
+}

Example

#include <stddef.h>
+#include <stdio.h>
+#include <stdlib.h>
+ 
+typedef struct
+{
+    size_t size;     // current number of elements
+    size_t capacity; // reserved number of elements
+    void** data;
+} PtrVector;
+ 
+PtrVector vector_create(size_t initial_capacity)
+{
+    PtrVector ret =
+    {
+        .capacity = initial_capacity,
+        .data = (void**) malloc(initial_capacity * sizeof(void*))
+    };
+    return ret;
+}
+ 
+void vector_delete(PtrVector* self)
+{
+    free_sized(self->data, self->capacity * sizeof(void*));
+}
+ 
+void vector_push_back(PtrVector* self, void* value)
+{
+    if (self->size == self->capacity)
+    {
+        self->capacity *= 2;
+        self->data = (void**) realloc(self->data, self->capacity * sizeof(void*));
+    }
+    self->data[self->size++] = value;
+}
+ 
+int main()
+{
+    int data = 42;
+    float pi = 3.141592f;
+    PtrVector v = vector_create(8);
+    vector_push_back(&v, &data);
+    vector_push_back(&v, &pi);
+    printf("data[0] = %i\n", *(int*)v.data[0]);
+    printf("data[1] = %f\n", *(float*)v.data[1]);
+    vector_delete(&v);
+}

Output:

+
data[0] = 42
+data[1] = 3.141592

References

See also

+ + +
deallocates previously allocated memory
(function)
+
(C23)
 deallocates previously allocated sized and aligned memory
(function)
allocates memory
(function)
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/memory/free_sized +

+
diff --git a/devdocs/c/memory%2Fmalloc.html b/devdocs/c/memory%2Fmalloc.html new file mode 100644 index 00000000..05f8d1f2 --- /dev/null +++ b/devdocs/c/memory%2Fmalloc.html @@ -0,0 +1,52 @@ +

malloc

Defined in header <stdlib.h> 
void *malloc( size_t size );
+

Allocates size bytes of uninitialized storage.

+

If allocation succeeds, returns a pointer that is suitably aligned for any object type with fundamental alignment.

+

If size is zero, the behavior of malloc is implementation-defined. For example, a null pointer may be returned. Alternatively, a non-null pointer may be returned; but such a pointer should not be dereferenced, and should be passed to free to avoid memory leaks.

+ + +

malloc is thread-safe: it behaves as though only accessing the memory locations visible through its argument, and not any static storage.

+

A previous call to free or realloc that deallocates a region of memory synchronizes-with a call to malloc that allocates the same or a part of the same region of memory. This synchronization occurs after any access to the memory by the deallocating function and before any access to the memory by malloc. There is a single total order of all allocation and deallocation functions operating on each particular region of memory.

+		 (since C11)

Parameters

+ +
size - number of bytes to allocate

Return value

On success, returns the pointer to the beginning of newly allocated memory. To avoid a memory leak, the returned pointer must be deallocated with free() or realloc().

+

On failure, returns a null pointer.

+

Example

#include <stdio.h>   
+#include <stdlib.h> 
+ 
+int main(void) 
+{
+    int *p1 = malloc(4*sizeof(int));  // allocates enough for an array of 4 int
+    int *p2 = malloc(sizeof(int[4])); // same, naming the type directly
+    int *p3 = malloc(4*sizeof *p3);   // same, without repeating the type name
+ 
+    if(p1) {
+        for(int n=0; n<4; ++n) // populate the array
+            p1[n] = n*n;
+        for(int n=0; n<4; ++n) // print it back out
+            printf("p1[%d] == %d\n", n, p1[n]);
+    }
+ 
+    free(p1);
+    free(p2);
+    free(p3);
+}

Output:

+
p1[0] == 0
+p1[1] == 1
+p1[2] == 4
+p1[3] == 9

References

See also

+ +
deallocates previously allocated memory
(function)
C++ documentation for malloc
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/memory/malloc +

+
diff --git a/devdocs/c/memory%2Frealloc.html b/devdocs/c/memory%2Frealloc.html new file mode 100644 index 00000000..65d5948d --- /dev/null +++ b/devdocs/c/memory%2Frealloc.html @@ -0,0 +1,102 @@ +

realloc

Defined in header <stdlib.h> 
void *realloc( void *ptr, size_t new_size );
+

Reallocates the given area of memory. If ptr is not NULL, it must be previously allocated by malloc, calloc or realloc and not yet freed with a call to free or realloc. Otherwise, the results are undefined.

+

The reallocation is done by either:

+
+a) expanding or contracting the existing area pointed to by ptr, if possible. The contents of the area remain unchanged up to the lesser of the new and old sizes. If the area is expanded, the contents of the new part of the array are undefined.
+b) allocating a new memory block of size new_size bytes, copying memory area with size equal the lesser of the new and the old sizes, and freeing the old block.

If there is not enough memory, the old memory block is not freed and null pointer is returned.

+

If ptr is NULL, the behavior is the same as calling malloc(new_size).

+

Otherwise,

+ + + + +

if new_size is zero, the behavior is implementation defined (null pointer may be returned (in which case the old memory block may or may not be freed), or some non-null pointer may be returned that may not be used to access storage). Such usage is deprecated (via C DR 400).(since C17)

+		 (until C23)

if new_size is zero, the behavior is undefined.

+		 (since C23)
+ +

realloc is thread-safe: it behaves as though only accessing the memory locations visible through its argument, and not any static storage.

+

A previous call to free or realloc that deallocates a region of memory synchronizes-with a call to any allocation function, including realloc that allocates the same or a part of the same region of memory. This synchronization occurs after any access to the memory by the deallocating function and before any access to the memory by realloc. There is a single total order of all allocation and deallocation functions operating on each particular region of memory.

+		 (since C11)

Parameters

+ + +
ptr - pointer to the memory area to be reallocated
new_size - new size of the array in bytes

Return value

On success, returns the pointer to the beginning of newly allocated memory. To avoid a memory leak, the returned pointer must be deallocated with free or realloc. The original pointer ptr is invalidated and any access to it is undefined behavior (even if reallocation was in-place).

+

On failure, returns a null pointer. The original pointer ptr remains valid and may need to be deallocated with free or realloc.

+

Notes

Originally (in C89), support for zero size was added to accommodate code such as

+
OBJ *p = calloc(0, sizeof(OBJ)); // "zero-length" placeholder
+/*...*/
+while (1)
+{
+    p = realloc(p, c * sizeof(OBJ)); // reallocations until size settles
+    /* code that may change c or break out of loop */
+}

Example

#include <assert.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+ 
+void print_storage_info(const int* next, const int* prev, int ints)
+{
+    if (next)
+        printf("%s location: %p. Size: %d ints (%ld bytes).\n",
+               (next != prev ? "New" : "Old"), (void*)next, ints, ints * sizeof(int));
+    else
+        printf("Allocation failed.\n");
+}
+ 
+int main(void)
+{
+    const int pattern[] = {1, 2, 3, 4, 5, 6, 7, 8};
+    const int pattern_size = sizeof pattern / sizeof(int);
+    int *next = NULL, *prev = NULL;
+ 
+    if ((next = (int*)malloc(pattern_size * sizeof *next))) // allocates an array
+    {
+        memcpy(next, pattern, sizeof pattern); // fills the array
+        print_storage_info(next, prev, pattern_size);
+    }
+    else
+        return EXIT_FAILURE;
+ 
+    // Reallocate in cycle using the following values as a new storage size.
+    const int realloc_size[] = {10, 12, 512, 32768, 65536, 32768};
+ 
+    for (int i = 0; i != sizeof realloc_size / sizeof(int); ++i)
+    {
+        if ((next = (int*)realloc(prev = next, realloc_size[i] * sizeof(int))))
+        {
+            print_storage_info(next, prev, realloc_size[i]);
+            assert(!memcmp(next, pattern, sizeof pattern));  // is pattern held
+        }
+        else // if realloc failed, the original pointer needs to be freed
+        {
+            free(prev);
+            return EXIT_FAILURE;
+        }
+    }
+ 
+    free(next); // finally, frees the storage
+    return EXIT_SUCCESS;
+}

Possible output:

+
New location: 0x144c010. Size: 8 ints (32 bytes).
+Old location: 0x144c010. Size: 10 ints (40 bytes).
+New location: 0x144c450. Size: 12 ints (48 bytes).
+Old location: 0x144c450. Size: 512 ints (2048 bytes).
+Old location: 0x144c450. Size: 32768 ints (131072 bytes).
+New location: 0x7f490c5bd010. Size: 65536 ints (262144 bytes).
+Old location: 0x7f490c5bd010. Size: 32768 ints (131072 bytes).

References

See also

+
C++ documentation for realloc
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/memory/realloc +

+
diff --git a/devdocs/c/memory.html b/devdocs/c/memory.html new file mode 100644 index 00000000..9fd74682 --- /dev/null +++ b/devdocs/c/memory.html @@ -0,0 +1,18 @@ +

Dynamic memory management

Functions

+ + + + + + + +
Defined in header <stdlib.h>
allocates memory
(function)
allocates and zeroes memory
(function)
expands previously allocated memory block
(function)
deallocates previously allocated memory
(function)
+
(C23)
 deallocates previously allocated sized memory
(function)
+
(C23)
 deallocates previously allocated sized and aligned memory
(function)
+
(C11)
 allocates aligned memory
(function)

See also

+
C++ documentation for C memory management library
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/memory +

+
diff --git a/devdocs/c/metadata b/devdocs/c/metadata new file mode 100644 index 00000000..b6a53b3c --- /dev/null +++ b/devdocs/c/metadata @@ -0,0 +1,2 @@ +(1 (name . "C") (slug . "c") (type . "cppref") (mtime . 1704475550) (db_size . 4722426) (attribution . "© cppreference.com
+ Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.")) \ No newline at end of file diff --git a/devdocs/c/numeric%2Fcomplex%2Fcabs.html b/devdocs/c/numeric%2Fcomplex%2Fcabs.html new file mode 100644 index 00000000..5db11848 --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcabs.html @@ -0,0 +1,47 @@ +

cabsf, cabs, cabsl

Defined in header <complex.h> 
float       cabsf( float complex z );
+		 (1) (since C99) 
double      cabs( double complex z );
+		 (2) (since C99) 
long double cabsl( long double complex z );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define fabs( z )
+		 (4) (since C99)
+1-3) Computes the complex absolute value (also known as norm, modulus, or magnitude) of z.
+4) Type-generic macro: if z has type long double complex or long double imaginary, cabsl is called. If z has type float complex or float imaginary, cabsf is called. If z has type double complex or double imaginary, cabs is called. For real and integer types, the corresponding version of fabs is called.

Parameters

+ +
z - complex argument

Return value

If no errors occur, returns the absolute value (norm, magnitude) of z.

+

Errors and special cases are handled as if the function is implemented as hypot(creal(z), cimag(z))

+

Example

#include <stdio.h>
+#include <complex.h>
+ 
+int main(void)
+{
+    double complex z = 1.0 + 1.0*I;
+    printf("%.1f%+.1fi cartesian is rho=%f theta=%f polar\n",
+           creal(z), cimag(z), cabs(z), carg(z));
+}

Output:

+
1.0+1.0i cartesian is rho=1.414214 theta=0.785398 polar

References

See also

+ + + + +
+
(C99)(C99)(C99)
 computes the phase angle of a complex number
(function)
+
(C99)
 computes absolute value of an integral value (\(\small{|x|}\)|x|)
(function)
+
(C99)(C99)
 computes absolute value of a floating-point value (\(\small{|x|}\)|x|)
(function)
+
(C99)(C99)(C99)
 computes square root of the sum of the squares of two given numbers (\(\scriptsize{\sqrt{x^2+y^2} }\)√x2+y2)
(function)
C++ documentation for abs
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/complex/cabs +

+
diff --git a/devdocs/c/numeric%2Fcomplex%2Fcacos.html b/devdocs/c/numeric%2Fcomplex%2Fcacos.html new file mode 100644 index 00000000..d5f7cc0a --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcacos.html @@ -0,0 +1,76 @@ +

cacosf, cacos, cacosl

Defined in header <complex.h> 
float complex       cacosf( float complex z );
+		 (1) (since C99) 
double complex      cacos( double complex z );
+		 (2) (since C99) 
long double complex cacosl( long double complex z );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define acos( z )
+		 (4) (since C99)
+1-3) Computes the complex arc cosine of z with branch cuts outside the interval [−1,+1] along the real axis.
+4) Type-generic macro: If z has type long double complex, cacosl is called. if z has type double complex, cacos is called, if z has type float complex, cacosf is called. If z is real or integer, then the macro invokes the corresponding real function (acosf, acos, acosl). If z is imaginary, then the macro invokes the corresponding complex number version.

Parameters

+ +
z - complex argument

Return value

If no errors occur, complex arc cosine of z is returned, in the range a strip unbounded along the imaginary axis and in the interval [0; π] along the real axis.

+

Error handling and special values

Errors are reported consistent with math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic,

+

Notes

Inverse cosine (or arc cosine) is a multivalued function and requires a branch cut on the complex plane. The branch cut is conventially placed at the line segments (-∞,-1) and (1,∞) of the real axis. The mathematical definition of the principal value of arc cosine is acos z =

+1/2π + iln(iz + √1-z2)

For any z, acos(z) = π - acos(-z)

+

Example

#include <stdio.h>
+#include <math.h>
+#include <complex.h>
+ 
+int main(void)
+{
+    double complex z = cacos(-2);
+    printf("cacos(-2+0i) = %f%+fi\n", creal(z), cimag(z));
+ 
+    double complex z2 = cacos(conj(-2)); // or CMPLX(-2, -0.0)
+    printf("cacos(-2-0i) (the other side of the cut) = %f%+fi\n", creal(z2), cimag(z2));
+ 
+    // for any z, acos(z) = pi - acos(-z)
+    double pi = acos(-1);
+    double complex z3 = ccos(pi-z2);
+    printf("ccos(pi - cacos(-2-0i) = %f%+fi\n", creal(z3), cimag(z3));
+}

Output:

+
cacos(-2+0i) = 3.141593-1.316958i
+cacos(-2-0i) (the other side of the cut) = 3.141593+1.316958i
+ccos(pi - cacos(-2-0i) = 2.000000+0.000000i

References

See also

+ + + + +
+
(C99)(C99)(C99)
 computes the complex arc sine
(function)
+
(C99)(C99)(C99)
 computes the complex arc tangent
(function)
+
(C99)(C99)(C99)
 computes the complex cosine
(function)
+
(C99)(C99)
 computes arc cosine (\({\small\arccos{x} }\)arccos(x))
(function)
C++ documentation for acos
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/complex/cacos +

+
diff --git a/devdocs/c/numeric%2Fcomplex%2Fcacosh.html b/devdocs/c/numeric%2Fcomplex%2Fcacosh.html new file mode 100644 index 00000000..9da0e7a1 --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcacosh.html @@ -0,0 +1,80 @@ +

cacoshf, cacosh, cacoshl

Defined in header <complex.h> 
float complex       cacoshf( float complex z );
+		 (1) (since C99) 
double complex      cacosh( double complex z );
+		 (2) (since C99) 
long double complex cacoshl( long double complex z );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define acosh( z )
+		 (4) (since C99)
+1-3) Computes complex arc hyperbolic cosine of a complex value z with branch cut at values less than 1 along the real axis.
+4) Type-generic macro: If z has type long double complex, cacoshl is called. if z has type double complex, cacosh is called, if z has type float complex, cacoshf is called. If z is real or integer, then the macro invokes the corresponding real function (acoshf, acosh, acoshl). If z is imaginary, then the macro invokes the corresponding complex number version and the return type is complex.

Parameters

+ +
z - complex argument

Return value

The complex arc hyperbolic cosine of z in the interval [0; ∞) along the real axis and in the interval [−iπ; +iπ] along the imaginary axis.

+

Error handling and special values

Errors are reported consistent with math_errhandling

+

If the implementation supports IEEE floating-point arithmetic,

+

Notes

Although the C standard names this function "complex arc hyperbolic cosine", the inverse functions of the hyperbolic functions are the area functions. Their argument is the area of a hyperbolic sector, not an arc. The correct name is "complex inverse hyperbolic cosine", and, less common, "complex area hyperbolic cosine".

+

Inverse hyperbolic cosine is a multivalued function and requires a branch cut on the complex plane. The branch cut is conventionally placed at the line segment (-∞,+1) of the real axis.

+

The mathematical definition of the principal value of the inverse hyperbolic cosine is acosh z = ln(z + √z+1 √z-1) For any z, acosh(z) =

+√z-1/√1-z acos(z), or simply i acos(z) in the upper half of the complex plane.

Example

#include <stdio.h>
+#include <complex.h>
+ 
+int main(void)
+{
+    double complex z = cacosh(0.5);
+    printf("cacosh(+0.5+0i) = %f%+fi\n", creal(z), cimag(z));
+ 
+    double complex z2 = conj(0.5); // or cacosh(CMPLX(0.5, -0.0)) in C11
+    printf("cacosh(+0.5-0i) (the other side of the cut) = %f%+fi\n", creal(z2), cimag(z2));
+ 
+    // in upper half-plane, acosh(z) = i*acos(z) 
+    double complex z3 = casinh(1+I);
+    printf("casinh(1+1i) = %f%+fi\n", creal(z3), cimag(z3));
+    double complex z4 = I*casin(1+I);
+    printf("I*asin(1+1i) = %f%+fi\n", creal(z4), cimag(z4));
+}

Output:

+
cacosh(+0.5+0i) = 0.000000-1.047198i
+cacosh(+0.5-0i) (the other side of the cut) = 0.500000-0.000000i
+casinh(1+1i) = 1.061275+0.666239i
+I*asin(1+1i) = -1.061275+0.666239i

References

See also

+ + + + + +
+
(C99)(C99)(C99)
 computes the complex arc cosine
(function)
+
(C99)(C99)(C99)
 computes the complex arc hyperbolic sine
(function)
+
(C99)(C99)(C99)
 computes the complex arc hyperbolic tangent
(function)
+
(C99)(C99)(C99)
 computes the complex hyperbolic cosine
(function)
+
(C99)(C99)(C99)
 computes inverse hyperbolic cosine (\({\small\operatorname{arcosh}{x} }\)arcosh(x))
(function)
C++ documentation for acosh
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/complex/cacosh +

+
diff --git a/devdocs/c/numeric%2Fcomplex%2Fcarg.html b/devdocs/c/numeric%2Fcomplex%2Fcarg.html new file mode 100644 index 00000000..608d566f --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcarg.html @@ -0,0 +1,55 @@ +

cargf, carg, cargl

Defined in header <complex.h> 
float       cargf( float complex z );
+		 (1) (since C99) 
double      carg( double complex z );
+		 (2) (since C99) 
long double cargl( long double complex z );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define carg( z )
+		 (4) (since C99)
+1-3) Computes the argument (also called phase angle) of z, with a branch cut along the negative real axis.
+4) Type-generic macro: if z has type long double complex, long double imaginary, or long double, cargl is called. If z has type float complex, float imaginary, or float, cargf is called. If z has type double complex, double imaginary, double, or any integer type, carg is called.

Parameters

+ +
z - complex argument

Return value

If no errors occur, returns the phase angle of z in the interval [−π; π].

+

Errors and special cases are handled as if the function is implemented as atan2(cimag(z), creal(z))

+

Example

#include <stdio.h>
+#include <complex.h>
+ 
+int main(void) 
+{
+    double complex z1 = 1.0+0.0*I;
+    printf("phase angle of %.1f%+.1fi is %f\n", creal(z1), cimag(z1), carg(z1));
+ 
+    double complex z2 = 0.0+1.0*I;
+    printf("phase angle of %.1f%+.1fi is %f\n", creal(z2), cimag(z2), carg(z2));
+ 
+    double complex z3 = -1.0+0.0*I;
+    printf("phase angle of %.1f%+.1fi is %f\n", creal(z3), cimag(z3), carg(z3));
+ 
+    double complex z4 = conj(z3); // or CMPLX(-1, -0.0)
+    printf("phase angle of %.1f%+.1fi (the other side of the cut) is %f\n",
+             creal(z4), cimag(z4), carg(z4));
+}

Output:

+
phase angle of 1.0+0.0i is 0.000000
+phase angle of 0.0+1.0i is 1.570796
+phase angle of -1.0+0.0i is 3.141593
+phase angle of -1.0-0.0i (the other side of the cut) is -3.141593

References

See also

+ + +
+
(C99)(C99)(C99)
 computes the magnitude of a complex number
(function)
+
(C99)(C99)
 computes arc tangent, using signs to determine quadrants
(function)
C++ documentation for arg
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/complex/carg +

+
diff --git a/devdocs/c/numeric%2Fcomplex%2Fcasin.html b/devdocs/c/numeric%2Fcomplex%2Fcasin.html new file mode 100644 index 00000000..379708be --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcasin.html @@ -0,0 +1,59 @@ +

casinf, casin, casinl

Defined in header <complex.h> 
float complex       casinf( float complex z );
+		 (1) (since C99) 
double complex      casin( double complex z );
+		 (2) (since C99) 
long double complex casinl( long double complex z );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define asin( z )
+		 (4) (since C99)
+1-3) Computes the complex arc sine of z with branch cuts outside the interval [−1,+1] along the real axis.
+4) Type-generic macro: If z has type long double complex, casinl is called. if z has type double complex, casin is called, if z has type float complex, casinf is called. If z is real or integer, then the macro invokes the corresponding real function (asinf, asin, asinl). If z is imaginary, then the macro invokes the corresponding real version of the function asinh, implementing the formula \(\small \arcsin({\rm i}y) = {\rm i}{\rm arsinh}(y)\)arcsin(iy) = i arsinh(y), and the return type of the macro is imaginary.

Parameters

+ +
z - complex argument

Return value

If no errors occur, complex arc sine of z is returned, in the range of a strip unbounded along the imaginary axis and in the interval [−π/2; +π/2] along the real axis.

+

Errors and special cases are handled as if the operation is implemented by -I * casinh(I*z)

+

Notes

Inverse sine (or arc sine) is a multivalued function and requires a branch cut on the complex plane. The branch cut is conventionally placed at the line segments (-∞,-1) and (1,∞) of the real axis.

+

The mathematical definition of the principal value of arc sine is \(\small \arcsin z = -{\rm i}\ln({\rm i}z+\sqrt{1-z^2})\)arcsin z = -iln(iz + √1-z2) For any z, \(\small{ \arcsin(z) = \arccos(-z) - \frac{\pi}{2} }\)arcsin(z) = acos(-z) -

+π/2

Example

#include <stdio.h>
+#include <math.h>
+#include <complex.h>
+ 
+int main(void)
+{
+    double complex z = casin(-2);
+    printf("casin(-2+0i) = %f%+fi\n", creal(z), cimag(z));
+ 
+    double complex z2 = casin(conj(-2)); // or CMPLX(-2, -0.0)
+    printf("casin(-2-0i) (the other side of the cut) = %f%+fi\n", creal(z2), cimag(z2));
+ 
+    // for any z, asin(z) = acos(-z) - pi/2
+    double pi = acos(-1);
+    double complex z3 = csin(cacos(conj(-2))-pi/2);
+    printf("csin(cacos(-2-0i)-pi/2) = %f%+fi\n", creal(z3), cimag(z3));
+}

Output:

+
casin(-2+0i) = -1.570796+1.316958i
+casin(-2-0i) (the other side of the cut) = -1.570796-1.316958i
+csin(cacos(-2-0i)-pi/2) = 2.000000+0.000000i

References

See also

+ + + + +
+
(C99)(C99)(C99)
 computes the complex arc cosine
(function)
+
(C99)(C99)(C99)
 computes the complex arc tangent
(function)
+
(C99)(C99)(C99)
 computes the complex sine
(function)
+
(C99)(C99)
 computes arc sine (\({\small\arcsin{x} }\)arcsin(x))
(function)
C++ documentation for asin
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/complex/casin +

+
diff --git a/devdocs/c/numeric%2Fcomplex%2Fcasinh.html b/devdocs/c/numeric%2Fcomplex%2Fcasinh.html new file mode 100644 index 00000000..9ef02d9c --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcasinh.html @@ -0,0 +1,77 @@ +

casinhf, casinh, casinhl

Defined in header <complex.h> 
float complex       casinhf( float complex z );
+		 (1) (since C99) 
double complex      casinh( double complex z );
+		 (2) (since C99) 
long double complex casinhl( long double complex z );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define asinh( z )
+		 (4) (since C99)
+1-3) Computes the complex arc hyperbolic sine of z with branch cuts outside the interval [−i; +i] along the imaginary axis.
+4) Type-generic macro: If z has type long double complex, casinhl is called. if z has type double complex, casinh is called, if z has type float complex, casinhf is called. If z is real or integer, then the macro invokes the corresponding real function (asinhf, asinh, asinhl). If z is imaginary, then the macro invokes the corresponding real version of the function asin, implementing the formula asinh(iy) = i asin(y), and the return type is imaginary.

Parameters

+ +
z - complex argument

Return value

If no errors occur, the complex arc hyperbolic sine of z is returned, in the range of a strip mathematically unbounded along the real axis and in the interval [−iπ/2; +iπ/2] along the imaginary axis.

+

Error handling and special values

Errors are reported consistent with math_errhandling

+

If the implementation supports IEEE floating-point arithmetic,

+

Notes

Although the C standard names this function "complex arc hyperbolic sine", the inverse functions of the hyperbolic functions are the area functions. Their argument is the area of a hyperbolic sector, not an arc. The correct name is "complex inverse hyperbolic sine", and, less common, "complex area hyperbolic sine".

+

Inverse hyperbolic sine is a multivalued function and requires a branch cut on the complex plane. The branch cut is conventionally placed at the line segments (-i∞,-i) and (i,i∞) of the imaginary axis.

+

The mathematical definition of the principal value of the inverse hyperbolic sine is asinh z = ln(z + √1+z2) For any z, asinh(z) =

+asin(iz)/i

Example

#include <stdio.h>
+#include <complex.h>
+ 
+int main(void)
+{
+    double complex z = casinh(0+2*I);
+    printf("casinh(+0+2i) = %f%+fi\n", creal(z), cimag(z));
+ 
+    double complex z2 = casinh(-conj(2*I)); // or casinh(CMPLX(-0.0, 2)) in C11
+    printf("casinh(-0+2i) (the other side of the cut) = %f%+fi\n", creal(z2), cimag(z2));
+ 
+    // for any z, asinh(z) = asin(iz)/i
+    double complex z3 = casinh(1+2*I);
+    printf("casinh(1+2i) = %f%+fi\n", creal(z3), cimag(z3));
+    double complex z4 = casin((1+2*I)*I)/I;
+    printf("casin(i * (1+2i))/i = %f%+fi\n", creal(z4), cimag(z4));
+}

Output:

+
casinh(+0+2i) = 1.316958+1.570796i
+casinh(-0+2i) (the other side of the cut) = -1.316958+1.570796i
+casinh(1+2i) = 1.469352+1.063440i
+casin(i * (1+2i))/i =  1.469352+1.063440i

References

See also

+ + + + +
+
(C99)(C99)(C99)
 computes the complex arc hyperbolic cosine
(function)
+
(C99)(C99)(C99)
 computes the complex arc hyperbolic tangent
(function)
+
(C99)(C99)(C99)
 computes the complex hyperbolic sine
(function)
+
(C99)(C99)(C99)
 computes inverse hyperbolic sine (\({\small\operatorname{arsinh}{x} }\)arsinh(x))
(function)
C++ documentation for asinh
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/complex/casinh +

+
diff --git a/devdocs/c/numeric%2Fcomplex%2Fcatan.html b/devdocs/c/numeric%2Fcomplex%2Fcatan.html new file mode 100644 index 00000000..c74f6eef --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcatan.html @@ -0,0 +1,56 @@ +

catanf, catan, catanl

Defined in header <complex.h> 
float complex       catanf( float complex z );
+		 (1) (since C99) 
double complex      catan( double complex z );
+		 (2) (since C99) 
long double complex catanl( long double complex z );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define atan( z )
+		 (4) (since C99)
+1-3) Computes the complex arc tangent of z with branch cuts outside the interval [−i,+i] along the imaginary axis.
+4) Type-generic macro: If z has type long double complex, catanl is called. if z has type double complex, catan is called, if z has type float complex, catanf is called. If z is real or integer, then the macro invokes the corresponding real function (atanf, atan, atanl). If z is imaginary, then the macro invokes the corresponding real version of the function atanh, implementing the formula atan(iy) = i atanh(y), and the return type of the macro is imaginary.

Parameters

+ +
z - complex argument

Return value

If no errors occur, complex arc tangent of z is returned, in the range of a strip unbounded along the imaginary axis and in the interval [−π/2; +π/2] along the real axis.

+

Errors and special cases are handled as if the operation is implemented by -I * catanh(I*z).

+

Notes

Inverse tangent (or arc tangent) is a multivalued function and requires a branch cut on the complex plane. The branch cut is conventionally placed at the line segments (-∞i,-i) and (+i,+∞i) of the imaginary axis. The mathematical definition of the principal value of inverse tangent is atan z = -

+1/2 i [ln(1 - iz) - ln (1 + iz]

Example

#include <stdio.h>
+#include <float.h>
+#include <complex.h>
+ 
+int main(void)
+{
+    double complex z = catan(2*I);
+    printf("catan(+0+2i) = %f%+fi\n", creal(z), cimag(z));
+ 
+    double complex z2 = catan(-conj(2*I)); // or CMPLX(-0.0, 2)
+    printf("catan(-0+2i) (the other side of the cut) = %f%+fi\n", creal(z2), cimag(z2));
+ 
+    double complex z3 = 2*catan(2*I*DBL_MAX); // or CMPLX(0, INFINITY)
+    printf("2*catan(+0+i*Inf) = %f%+fi\n", creal(z3), cimag(z3));
+}

Output:

+
catan(+0+2i) = 1.570796+0.549306i
+catan(-0+2i) (the other side of the cut) = -1.570796+0.549306i
+2*catan(+0+i*Inf) = 3.141593+0.000000i

References

See also

+ + + + +
+
(C99)(C99)(C99)
 computes the complex arc sine
(function)
+
(C99)(C99)(C99)
 computes the complex arc cosine
(function)
+
(C99)(C99)(C99)
 computes the complex tangent
(function)
+
(C99)(C99)
 computes arc tangent (\({\small\arctan{x} }\)arctan(x))
(function)
C++ documentation for atan
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/complex/catan +

+
diff --git a/devdocs/c/numeric%2Fcomplex%2Fcatanh.html b/devdocs/c/numeric%2Fcomplex%2Fcatanh.html new file mode 100644 index 00000000..23fd8cf7 --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcatanh.html @@ -0,0 +1,78 @@ +

catanhf, catanh, catanhl

Defined in header <complex.h> 
float complex       catanhf( float complex z );
+		 (1) (since C99) 
double complex      catanh( double complex z );
+		 (2) (since C99) 
long double complex catanhl( long double complex z );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define atanh( z )
+		 (4) (since C99)
+1-3) Computes the complex arc hyperbolic tangent of z with branch cuts outside the interval [−1; +1] along the real axis.
+4) Type-generic macro: If z has type long double complex, catanhl is called. if z has type double complex, catanh is called, if z has type float complex, catanhf is called. If z is real or integer, then the macro invokes the corresponding real function (atanhf, atanh, atanhl). If z is imaginary, then the macro invokes the corresponding real version of atan, implementing the formula atanh(iy) = i atan(y), and the return type is imaginary.

Parameters

+ +
z - complex argument

Return value

If no errors occur, the complex arc hyperbolic tangent of z is returned, in the range of a half-strip mathematically unbounded along the real axis and in the interval [−iπ/2; +iπ/2] along the imaginary axis.

+

Error handling and special values

Errors are reported consistent with math_errhandling

+

If the implementation supports IEEE floating-point arithmetic,

+

Notes

Although the C standard names this function "complex arc hyperbolic tangent", the inverse functions of the hyperbolic functions are the area functions. Their argument is the area of a hyperbolic sector, not an arc. The correct name is "complex inverse hyperbolic tangent", and, less common, "complex area hyperbolic tangent".

+

Inverse hyperbolic tangent is a multivalued function and requires a branch cut on the complex plane. The branch cut is conventionally placed at the line segmentd (-∞,-1] and [+1,+∞) of the real axis. The mathematical definition of the principal value of the inverse hyperbolic tangent is atanh z =

+ln(1+z)-ln(z-1)/2.


For any z, atanh(z) =

+atan(iz)/i

Example

#include <stdio.h>
+#include <complex.h>
+ 
+int main(void)
+{
+    double complex z = catanh(2);
+    printf("catanh(+2+0i) = %f%+fi\n", creal(z), cimag(z));
+ 
+    double complex z2 = catanh(conj(2)); // or catanh(CMPLX(2, -0.0)) in C11
+    printf("catanh(+2-0i) (the other side of the cut) = %f%+fi\n", creal(z2), cimag(z2));
+ 
+    // for any z, atanh(z) = atan(iz)/i
+    double complex z3 = catanh(1+2*I);
+    printf("catanh(1+2i) = %f%+fi\n", creal(z3), cimag(z3));
+    double complex z4 = catan((1+2*I)*I)/I;
+    printf("catan(i * (1+2i))/i = %f%+fi\n", creal(z4), cimag(z4));
+}

Output:

+
catanh(+2+0i) = 0.549306+1.570796i
+catanh(+2-0i) (the other side of the cut) = 0.549306-1.570796i
+catanh(1+2i) = 0.173287+1.178097i
+catan(i * (1+2i))/i = 0.173287+1.178097i

References

See also

+ + + + +
+
(C99)(C99)(C99)
 computes the complex arc hyperbolic sine
(function)
+
(C99)(C99)(C99)
 computes the complex arc hyperbolic cosine
(function)
+
(C99)(C99)(C99)
 computes the complex hyperbolic tangent
(function)
+
(C99)(C99)(C99)
 computes inverse hyperbolic tangent (\({\small\operatorname{artanh}{x} }\)artanh(x))
(function)
C++ documentation for atanh
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/complex/catanh +

+
diff --git a/devdocs/c/numeric%2Fcomplex%2Fccos.html b/devdocs/c/numeric%2Fcomplex%2Fccos.html new file mode 100644 index 00000000..99cece77 --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fccos.html @@ -0,0 +1,52 @@ +

ccosf, ccos, ccosl

Defined in header <complex.h> 
float complex       ccosf( float complex z );
+		 (1) (since C99) 
double complex      ccos( double complex z );
+		 (2) (since C99) 
long double complex ccosl( long double complex z );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define cos( z )
+		 (4) (since C99)
+1-3) Computes the complex cosine of z.
+4) Type-generic macro: If z has type long double complex, ccosl is called. if z has type double complex, ccos is called, if z has type float complex, ccosf is called. If z is real or integer, then the macro invokes the corresponding real function (cosf, cos, cosl). If z is imaginary, then the macro invokes the corresponding real version of the function cosh, implementing the formula cos(iy) = cosh(y), and the return type is real.

Parameters

+ +
z - complex argument

Return value

If no errors occur, the complex cosine of z is returned.

+

Errors and special cases are handled as if the operation is implemented by ccosh(I*z).

+

Notes

The cosine is an entire function on the complex plane, and has no branch cuts. Mathematical definition of the cosine is cos z =

+eiz+e-iz/2

Example

#include <stdio.h>
+#include <math.h>
+#include <complex.h>
+ 
+int main(void)
+{
+    double complex z = ccos(1);  // behaves like real cosine along the real line
+    printf("cos(1+0i) = %f%+fi ( cos(1)=%f)\n", creal(z), cimag(z), cos(1));
+ 
+    double complex z2 = ccos(I); // behaves like real cosh along the imaginary line
+    printf("cos(0+1i) = %f%+fi (cosh(1)=%f)\n", creal(z2), cimag(z2), cosh(1));
+}

Output:

+
cos(1+0i) = 0.540302-0.000000i ( cos(1)=0.540302)
+cos(0+1i) = 1.543081-0.000000i (cosh(1)=1.543081)

References

See also

+ + + + +
+
(C99)(C99)(C99)
 computes the complex sine
(function)
+
(C99)(C99)(C99)
 computes the complex tangent
(function)
+
(C99)(C99)(C99)
 computes the complex arc cosine
(function)
+
(C99)(C99)
 computes cosine (\({\small\cos{x} }\)cos(x))
(function)
C++ documentation for cos
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/complex/ccos +

+
diff --git a/devdocs/c/numeric%2Fcomplex%2Fccosh.html b/devdocs/c/numeric%2Fcomplex%2Fccosh.html new file mode 100644 index 00000000..5c6efd4b --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fccosh.html @@ -0,0 +1,71 @@ +

ccoshf, ccosh, ccoshl

Defined in header <complex.h> 
float complex       ccoshf( float complex z );
+		 (1) (since C99) 
double complex      ccosh( double complex z );
+		 (2) (since C99) 
long double complex ccoshl( long double complex z );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define cosh( z )
+		 (4) (since C99)
+1-3) Computes the complex hyperbolic cosine of z.
+4) Type-generic macro: If z has type long double complex, ccoshl is called. if z has type double complex, ccosh is called, if z has type float complex, ccoshf is called. If z is real or integer, then the macro invokes the corresponding real function (coshf, cosh, coshl). If z is imaginary, then the macro invokes the corresponding real version of the function cos, implementing the formula cosh(iy) = cos(y), and the return type is real.

Parameters

+ +
z - complex argument

Return value

If no errors occur, complex hyperbolic cosine of z is returned

+

Error handling and special values

Errors are reported consistent with math_errhandling

+

If the implementation supports IEEE floating-point arithmetic,

+

where cis(y) is cos(y) + i sin(y)

+

Notes

Mathematical definition of hyperbolic cosine is cosh z = ez+e-z/2

Hyperbolic cosine is an entire function in the complex plane and has no branch cuts. It is periodic with respect to the imaginary component, with period 2πi

+

Example

#include <stdio.h>
+#include <math.h>
+#include <complex.h>
+ 
+int main(void)
+{
+    double complex z = ccosh(1);  // behaves like real cosh along the real line
+    printf("cosh(1+0i) = %f%+fi (cosh(1)=%f)\n", creal(z), cimag(z), cosh(1));
+ 
+    double complex z2 = ccosh(I); // behaves like real cosine along the imaginary line
+    printf("cosh(0+1i) = %f%+fi ( cos(1)=%f)\n", creal(z2), cimag(z2), cos(1));
+}

Output:

+
cosh(1+0i) = 1.543081+0.000000i (cosh(1)=1.543081)
+cosh(0+1i) = 0.540302+0.000000i ( cos(1)=0.540302)

References

See also

+ + + + +
+
(C99)(C99)(C99)
 computes the complex hyperbolic sine
(function)
+
(C99)(C99)(C99)
 computes the complex hyperbolic tangent
(function)
+
(C99)(C99)(C99)
 computes the complex arc hyperbolic cosine
(function)
+
(C99)(C99)
 computes hyperbolic cosine (\({\small\cosh{x} }\)cosh(x))
(function)
C++ documentation for cosh
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/complex/ccosh +

+
diff --git a/devdocs/c/numeric%2Fcomplex%2Fcexp.html b/devdocs/c/numeric%2Fcomplex%2Fcexp.html new file mode 100644 index 00000000..a8c4195b --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcexp.html @@ -0,0 +1,66 @@ +

cexpf, cexp, cexpl

Defined in header <complex.h> 
float complex       cexpf( float complex z );
+		 (1) (since C99) 
double complex      cexp( double complex z );
+		 (2) (since C99) 
long double complex cexpl( long double complex z );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define exp( z )
+		 (4) (since C99)
+1-3) Computes the complex base-e exponential of z.
+4) Type-generic macro: If z has type long double complex, cexpl is called. if z has type double complex, cexp is called, if z has type float complex, cexpf is called. If z is real or integer, then the macro invokes the corresponding real function (expf, exp, expl). If z is imaginary, the corresponding complex argument version is called.

Parameters

+ +
z - complex argument

Return value

If no errors occur, e raised to the power of z, \(\small e^z\)ez is returned.

+

Error handling and special values

Errors are reported consistent with math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic,

+

where \(\small{\rm cis}(y)\)cis(y) is \(\small \cos(y)+{\rm i}\sin(y)\)cos(y) + i sin(y)

+

Notes

The complex exponential function \(\small e^z\)ez for \(\small z = x + {\rm i}y\)z = x+iy equals \(\small e^x {\rm cis}(y)\)ex cis(y), or, \(\small e^x (\cos(y)+{\rm i}\sin(y))\)ex (cos(y) + i sin(y))

+

The exponential function is an entire function in the complex plane and has no branch cuts.

+

Example

#include <stdio.h>
+#include <math.h>
+#include <complex.h>
+ 
+int main(void)
+{
+    double PI = acos(-1);
+    double complex z = cexp(I * PI); // Euler's formula
+    printf("exp(i*pi) = %.1f%+.1fi\n", creal(z), cimag(z));
+ 
+}

Output:

+
exp(i*pi) = -1.0+0.0i

References

See also

+ + +
+
(C99)(C99)(C99)
 computes the complex natural logarithm
(function)
+
(C99)(C99)
 computes e raised to the given power (\({\small e^x}\)ex)
(function)
C++ documentation for exp
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/complex/cexp +

+
diff --git a/devdocs/c/numeric%2Fcomplex%2Fcimag.html b/devdocs/c/numeric%2Fcomplex%2Fcimag.html new file mode 100644 index 00000000..4218e76c --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcimag.html @@ -0,0 +1,41 @@ +

cimagf, cimag, cimagl

Defined in header <complex.h> 
float       cimagf( float complex z );
+		 (1) (since C99) 
double      cimag( double complex z );
+		 (2) (since C99) 
long double cimagl( long double complex z );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define cimag( z )
+		 (4) (since C99)
+1-3) Returns the imaginary part of z.
+4) Type-generic macro: if z has type long double complex, long double imaginary, or long double, cimagl is called. If z has type float complex, float imaginary, or float, cimagf is called. If z has type double complex, double imaginary, double, or any integer type, cimag is called.

Parameters

+ +
z - complex argument

Return value

The imaginary part of z.

+

This function is fully specified for all possible inputs and is not subject to any errors described in math_errhandling

+

Notes

For any complex variable z, z == creal(z) + I*cimag(z).

+

Example

#include <stdio.h>
+#include <complex.h>
+ 
+int main(void)
+{    
+    double complex z = 1.0 + 2.0*I;
+    printf("%f%+fi\n", creal(z), cimag(z));
+}

Output:

+
1.000000+2.000000i

References

See also

+ +
+
(C99)(C99)(C99)
 computes the real part of a complex number
(function)
C++ documentation for imag
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/complex/cimag +

+
diff --git a/devdocs/c/numeric%2Fcomplex%2Fclog.html b/devdocs/c/numeric%2Fcomplex%2Fclog.html new file mode 100644 index 00000000..3cc04584 --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fclog.html @@ -0,0 +1,74 @@ +

clogf, clog, clogl

Defined in header <complex.h> 
float complex       clogf( float complex z );
+		 (1) (since C99) 
double complex      clog( double complex z );
+		 (2) (since C99) 
long double complex clogl( long double complex z );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define log( z )
+		 (4) (since C99)
+1-3) Computes the complex natural (base-e) logarithm of z with branch cut along the negative real axis.
+4) Type-generic macro: If z has type long double complex, clogl is called. if z has type double complex, clog is called, if z has type float complex, clogf is called. If z is real or integer, then the macro invokes the corresponding real function (logf, log, logl). If z is imaginary, the corresponding complex number version is called.

Parameters

+ +
z - complex argument

Return value

If no errors occur, the complex natural logarithm of z is returned, in the range of a strip in the interval [−iπ, +iπ] along the imaginary axis and mathematically unbounded along the real axis.

+

Error handling and special values

Errors are reported consistent with math_errhandling

+

If the implementation supports IEEE floating-point arithmetic,

+

Notes

The natural logarithm of a complex number z with polar coordinate components (r,θ) equals ln r + i(θ+2nπ), with the principal value ln r + iθ

+

Example

#include <stdio.h>
+#include <math.h>
+#include <complex.h>
+ 
+int main(void)
+{
+    double complex z = clog(I); // r = 1, θ = pi/2
+    printf("2*log(i) = %.1f%+fi\n", creal(2*z), cimag(2*z));
+ 
+    double complex z2 = clog(sqrt(2)/2 + sqrt(2)/2*I); // r = 1, θ = pi/4
+    printf("4*log(sqrt(2)/2+sqrt(2)i/2) = %.1f%+fi\n", creal(4*z2), cimag(4*z2));
+ 
+    double complex z3 = clog(-1); // r = 1, θ = pi
+    printf("log(-1+0i) = %.1f%+fi\n", creal(z3), cimag(z3));
+ 
+    double complex z4 = clog(conj(-1)); // or clog(CMPLX(-1, -0.0)) in C11
+    printf("log(-1-0i) (the other side of the cut) = %.1f%+fi\n", creal(z4), cimag(z4));
+}

Output:

+
2*log(i) = 0.0+3.141593i
+4*log(sqrt(2)/2+sqrt(2)i/2) = 0.0+3.141593i
+log(-1+0i) = 0.0+3.141593i
+log(-1-0i) (the other side of the cut) = 0.0-3.141593i

References

See also

+ + +
+
(C99)(C99)(C99)
 computes the complex base-e exponential
(function)
+
(C99)(C99)
 computes natural (base-e) logarithm (\({\small \ln{x} }\)ln(x))
(function)
C++ documentation for log
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/complex/clog +

+
diff --git a/devdocs/c/numeric%2Fcomplex%2Fcmplx.html b/devdocs/c/numeric%2Fcomplex%2Fcmplx.html new file mode 100644 index 00000000..12dde11f --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcmplx.html @@ -0,0 +1,33 @@ +

CMPLXF, CMPLX, CMPLXL

Defined in header <complex.h> 
float complex       CMPLXF( float real, float imag );
+		 (since C11) 
double complex      CMPLX( double real, double imag );
+		 (since C11) 
long double complex CMPLXL( long double real, long double imag );
+		 (since C11)

Each of these macros expands to an expression that evaluates to the value of the specified complex type, with the real part having the value of real (converted to the specified argument type) and the imaginary part having the value of imag (converted to the specified argument type)

+

The expressions are suitable for use as initializers for objects with static or thread storage duration, as long as the expressions real and imag are also suitable.

+

Parameters

+ + +
real - the real part of the complex number to return
imag - the imaginary part of the complex number to return

Return value

A complex number composed of real and imag as the real and imaginary parts.

+

Notes

These macros are implemented as if the imaginary types are supported (even if they are otherwise not supported and _Imaginary_I is actually undefined) and as if defined as follows:

+
#define CMPLX(x, y) ((double complex)((double)(x) + _Imaginary_I * (double)(y)))
+#define CMPLXF(x, y) ((float complex)((float)(x) + _Imaginary_I * (float)(y)))
+#define CMPLXL(x, y) ((long double complex)((long double)(x) + \
+                      _Imaginary_I * (long double)(y)))

Example

#include <stdio.h>
+#include <complex.h>
+ 
+int main(void)
+{
+    double complex z = CMPLX(0.0, -0.0);
+    printf("z = %.1f%+.1fi\n", creal(z), cimag(z));
+}

Output:

+
z = 0.0-0.0i

References

See also

+ +
+
(C99)
 the imaginary unit constant i
(macro constant)
C++ documentation for complex
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/complex/CMPLX +

+
diff --git a/devdocs/c/numeric%2Fcomplex%2Fcomplex.html b/devdocs/c/numeric%2Fcomplex%2Fcomplex.html new file mode 100644 index 00000000..9ca58d2c --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcomplex.html @@ -0,0 +1,37 @@ +

complex

Defined in header <complex.h> 
#define complex _Complex
+		 (since C99)

This macro expands to a type specifier used to identify complex types.

+

A program may undefine and perhaps then redefine the complex macro.

+

Example

#include <stdio.h>
+#include <complex.h>
+#include <math.h>
+ 
+void print_complex(const char* note, complex z)
+{
+    printf("%s %f%+f*i\n", note, creal(z), cimag(z));
+}
+ 
+int main(void)
+{
+    double complex z = -1.0 + 2.0*I;
+    print_complex("z  =", z);
+    print_complex("z\u00B2 =", z * z);
+    double complex z2 = ccos(2.0 * carg(z)) + csin(2.0 * carg(z))*I;
+    print_complex("z\u00B2 =", cabs(z) * cabs(z) * z2);
+}

Output:

+
z  = -1.000000+2.000000*i
+z² = -3.000000-4.000000*i
+z² = -3.000000-4.000000*i

References

See also

+
+
(C99)
 imaginary type macro
(keyword macro)
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/complex/complex +

+
diff --git a/devdocs/c/numeric%2Fcomplex%2Fcomplex_i.html b/devdocs/c/numeric%2Fcomplex%2Fcomplex_i.html new file mode 100644 index 00000000..9ccc4b52 --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcomplex_i.html @@ -0,0 +1,40 @@ +

_Complex_I

Defined in header <complex.h> 
#define _Complex_I /* unspecified */
+		 (since C99)

The _Complex_I macro expands to a value of type const float _Complex with the value of the imaginary unit.

+

Notes

This macro may be used when I is not available, such as when it has been undefined by the application.

+

Unlike _Imaginary_I and CMPLX, use of this macro to construct a complex number may lose the sign of zero on the imaginary part.

+

Example

#include <stdio.h>
+#include <complex.h>
+ 
+#undef I
+#define J _Complex_I // can be used to redefine I
+ 
+int main(void)
+{
+    // can be used to construct a complex number
+    double complex z = 1.0 + 2.0 * _Complex_I;
+    printf("1.0 + 2.0 * _Complex_I = %.1f%+.1fi\n", creal(z), cimag(z));
+ 
+    // sign of zero may not be preserved
+    double complex z2 = 0.0 + -0.0 * _Complex_I;
+    printf("0.0 + -0.0 * _Complex_I = %.1f%+.1fi\n", creal(z2), cimag(z2));
+}

Possible output:

+
1.0 + 2.0 * _Complex_I = 1.0+2.0i
+0.0 + -0.0 * _Complex_I = 0.0+0.0i

References

See also

+ +
+
(C99)
 the imaginary unit constant i
(macro constant)
+
(C99)
 the complex or imaginary unit constant i
(macro constant)
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/complex/Complex_I +

+
diff --git a/devdocs/c/numeric%2Fcomplex%2Fconj.html b/devdocs/c/numeric%2Fcomplex%2Fconj.html new file mode 100644 index 00000000..f59d1427 --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fconj.html @@ -0,0 +1,43 @@ +

conjf, conj, conjl

Defined in header <complex.h> 
float complex       conjf( float complex z );
+		 (1) (since C99) 
double complex      conj( double complex z );
+		 (2) (since C99) 
long double complex conjl( long double complex z );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define conj( z )
+		 (4) (since C99)
+1-3) Computes the complex conjugate of z by reversing the sign of the imaginary part.
+4) Type-generic macro: if z has type long double complex, long double imaginary, or long double, conjl is called. If z has type float complex, float imaginary, or float, conjf is called. If z has type double complex, double imaginary, double, or any integer type, conj is called.

Parameters

+ +
z - complex argument

Return value

The complex conjugate of z.

+

Notes

On C99 implementations that do not implement I as _Imaginary_I, conj may be used to obtain complex numbers with negative zero imaginary part. In C11, the macro CMPLX is used for that purpose.

+

Example

#include <stdio.h>
+#include <complex.h>
+ 
+int main(void)
+{
+    double complex z = 1.0 + 2.0*I;
+    double complex z2 = conj(z);
+    printf("The conjugate of %.1f%+.1fi is %.1f%+.1fi\n",
+            creal(z), cimag(z), creal(z2), cimag(z2));
+ 
+    printf("Their product is %.1f%+.1fi\n", creal(z*z2), cimag(z*z2));
+}

Output:

+
The conjugate of 1.0+2.0i is 1.0-2.0i
+Their product is 5.0+0.0i

References

See also

+
C++ documentation for conj
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/complex/conj +

+
diff --git a/devdocs/c/numeric%2Fcomplex%2Fcpow.html b/devdocs/c/numeric%2Fcomplex%2Fcpow.html new file mode 100644 index 00000000..6a1e6196 --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcpow.html @@ -0,0 +1,56 @@ +

cpowf, cpow, cpowl

Defined in header <complex.h> 
float complex       cpowf( float complex x, float complex y );
+		 (1) (since C99) 
double complex      cpow( double complex x, double complex y );
+		 (2) (since C99) 
long double complex cpowl( long double complex x, long double complex y );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define pow( x, y )
+		 (4) (since C99)
+1-3) Computes the complex power function xy, with branch cut for the first parameter along the negative real axis.
+4) Type-generic macro: If any argument has type long double complex, cpowl is called. if any argument has type double complex, cpow is called, if any argument has type float complex, cpowf is called. If the arguments are real or integer, then the macro invokes the corresponding real function (powf, pow, powl). If any argument is imaginary, the corresponding complex number version is called.

Parameters

+ +
x, y - complex argument

Return value

If no errors occur, the complex power xy, is returned.

+

Errors and special cases are handled as if the operation is implemented by cexp(y*clog(x)), except that the implementation is allowed to treat special cases more carefully.

+

Example

#include <stdio.h>
+#include <complex.h>
+ 
+int main(void)
+{    
+    double complex z = cpow(1.0+2.0*I, 2);
+    printf("(1+2i)^2 = %.1f%+.1fi\n", creal(z), cimag(z));
+ 
+    double complex z2 = cpow(-1, 0.5);
+    printf("(-1+0i)^0.5 = %.1f%+.1fi\n", creal(z2), cimag(z2));
+ 
+    double complex z3 = cpow(conj(-1), 0.5); // other side of the cut
+    printf("(-1-0i)^0.5 = %.1f%+.1fi\n", creal(z3), cimag(z3));
+ 
+    double complex z4 = cpow(I, I); // i^i = exp(-pi/2)
+    printf("i^i = %f%+fi\n", creal(z4), cimag(z4));
+}

Output:

+
(1+2i)^2 = -3.0+4.0i
+(-1+0i)^0.5 = 0.0+1.0i
+(-1-0i)^0.5 = 0.0-1.0i
+i^i = 0.207880+0.000000i

References

See also

+ + +
+
(C99)(C99)(C99)
 computes the complex square root
(function)
+
(C99)(C99)
 computes a number raised to the given power (\(\small{x^y}\)xy)
(function)
C++ documentation for pow
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/complex/cpow +

+
diff --git a/devdocs/c/numeric%2Fcomplex%2Fcproj.html b/devdocs/c/numeric%2Fcomplex%2Fcproj.html new file mode 100644 index 00000000..f74622ea --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcproj.html @@ -0,0 +1,49 @@ +

cprojf, cproj, cprojl

Defined in header <complex.h> 
float complex       cprojf( float complex z );
+		 (1) (since C99) 
double complex      cproj( double complex z );
+		 (2) (since C99) 
long double complex cprojl( long double complex z );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define cproj( z )
+		 (4) (since C99)
+1-3) Computes the projection of z on the Riemann sphere.
+4) Type-generic macro: if z has type long double complex, long double imaginary, or long double, cprojl is called. If z has type float complex, float imaginary, or float, cprojf is called. If z has type double complex, double imaginary, double, or any integer type, cproj is called.

For most z, cproj(z)==z, but all complex infinities, even the numbers where one component is infinite and the other is NaN, become positive real infinity, INFINITY+0.0*I or INFINITY-0.0*I. The sign of the imaginary (zero) component is the sign of cimag(z).

+

Parameters

+ +
z - complex argument

Return value

The projection of z on the Riemann sphere.

+

This function is fully specified for all possible inputs and is not subject to any errors described in math_errhandling

+

Notes

The cproj function helps model the Riemann sphere by mapping all infinities to one (give or take the sign of the imaginary zero), and should be used just before any operation, especially comparisons, that might give spurious results for any of the other infinities.

+

Example

#include <stdio.h>
+#include <complex.h>
+#include <math.h>
+ 
+int main(void)
+{
+    double complex z1 = cproj(1 + 2*I);
+    printf("cproj(1+2i) = %.1f%+.1fi\n", creal(z1),cimag(z1));
+ 
+    double complex z2 = cproj(INFINITY+2.0*I);
+    printf("cproj(Inf+2i) = %.1f%+.1fi\n", creal(z2),cimag(z2));
+ 
+    double complex z3 = cproj(INFINITY-2.0*I);
+    printf("cproj(Inf-2i) = %.1f%+.1fi\n", creal(z3),cimag(z3));
+}

Output:

+
cproj(1+2i) = 1.0+2.0i
+cproj(Inf+2i) = inf+0.0i
+cproj(Inf-2i) = inf-0.0i

References

See also

+
C++ documentation for proj
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/complex/cproj +

+
diff --git a/devdocs/c/numeric%2Fcomplex%2Fcreal.html b/devdocs/c/numeric%2Fcomplex%2Fcreal.html new file mode 100644 index 00000000..e0d77c3f --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcreal.html @@ -0,0 +1,41 @@ +

crealf, creal, creall

Defined in header <complex.h> 
float       crealf( float complex z );
+		 (1) (since C99) 
double      creal( double complex z );
+		 (2) (since C99) 
long double creall( long double complex z );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define creal( z )
+		 (4) (since C99)
+1-3) Returns the real part of z.
+4) Type-generic macro: if z has type long double complex, long double imaginary, or long double, creall is called. If z has type float complex, float imaginary, or float, crealf is called. If z has type double complex, double imaginary, double, or any integer type, creal is called.

Parameters

+ +
z - complex argument

Return value

The real part of z.

+

This function is fully specified for all possible inputs and is not subject to any errors described in math_errhandling

+

Notes

For any complex variable z, z == creal(z) + I*cimag(z).

+

Example

#include <stdio.h>
+#include <complex.h>
+ 
+int main(void)
+{    
+    double complex z = 1.0 + 2.0*I;
+    printf("%f%+fi\n", creal(z), cimag(z));
+}

Output:

+
1.000000+2.000000i

References

See also

+ +
+
(C99)(C99)(C99)
 computes the imaginary part a complex number
(function)
C++ documentation for real
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/complex/creal +

+
diff --git a/devdocs/c/numeric%2Fcomplex%2Fcsin.html b/devdocs/c/numeric%2Fcomplex%2Fcsin.html new file mode 100644 index 00000000..5e69806e --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcsin.html @@ -0,0 +1,58 @@ +

csinf, csin, csinl

Defined in header <complex.h> 
float complex       csinf( float complex z );
+		 (1) (since C99) 
double complex      csin( double complex z );
+		 (2) (since C99) 
long double complex csinl( long double complex z );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define sin( z )
+		 (4) (since C99)
+1-3) Computes the complex sine of z.
+4) Type-generic macro: If z has type long double complex, csinl is called. if z has type double complex, csin is called, if z has type float complex, csinf is called. If z is real or integer, then the macro invokes the corresponding real function (sinf, sin, sinl). If z is imaginary, then the macro invokes the corresponding real version of the function sinh, implementing the formula sin(iy) = i ∙ sinh(y), and the return type of the macro is imaginary.

Parameters

+ +
z - complex argument

Return value

If no errors occur, the complex sine of z.

+

Errors and special cases are handled as if the operation is implemented by -I * csinh(I*z)

+

Notes

The sine is an entire function on the complex plane, and has no branch cuts. Mathematical definition of the sine is sin z =

+eiz-e-iz/2i

Example

#include <stdio.h>
+#include <math.h>
+#include <complex.h>
+ 
+int main(void)
+{
+    double complex z = csin(1);  // behaves like real sine along the real line
+    printf("sin(1+0i) = %f%+fi ( sin(1)=%f)\n", creal(z), cimag(z), sin(1));
+ 
+    double complex z2 = csin(I); // behaves like sinh along the imaginary line 
+    printf("sin(0+1i) = %f%+fi (sinh(1)=%f)\n", creal(z2), cimag(z2), sinh(1));
+}

Output:

+
sin(1+0i) = 0.841471+0.000000i ( sin(1)=0.841471)
+sin(0+1i) = 0.000000+1.175201i (sinh(1)=1.175201)

References

See also

+ + + + +
+
(C99)(C99)(C99)
 computes the complex cosine
(function)
+
(C99)(C99)(C99)
 computes the complex tangent
(function)
+
(C99)(C99)(C99)
 computes the complex arc sine
(function)
+
(C99)(C99)
 computes sine (\({\small\sin{x} }\)sin(x))
(function)
C++ documentation for sin
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/complex/csin +

+
diff --git a/devdocs/c/numeric%2Fcomplex%2Fcsinh.html b/devdocs/c/numeric%2Fcomplex%2Fcsinh.html new file mode 100644 index 00000000..49d937e5 --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcsinh.html @@ -0,0 +1,71 @@ +

csinhf, csinh, csinhl

Defined in header <complex.h> 
float complex       csinhf( float complex z );
+		 (1) (since C99) 
double complex      csinh( double complex z );
+		 (2) (since C99) 
long double complex csinhl( long double complex z );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define sinh( z )
+		 (4) (since C99)
+1-3) Computes the complex hyperbolic sine of z.
+4) Type-generic macro: If z has type long double complex, csinhl is called. if z has type double complex, csinh is called, if z has type float complex, csinhf is called. If z is real or integer, then the macro invokes the corresponding real function (sinhf, sinh, sinhl). If z is imaginary, then the macro invokes the corresponding real version of the function sin, implementing the formula sinh(iy) = i sin(y), and the return type is imaginary.

Parameters

+ +
z - complex argument

Return value

If no errors occur, complex hyperbolic sine of z is returned

+

Error handling and special values

Errors are reported consistent with math_errhandling

+

If the implementation supports IEEE floating-point arithmetic,

+

where cis(y) is cos(y) + i sin(y)

+

Notes

Mathematical definition of hyperbolic sine is sinh z = ez-e-z/2

Hyperbolic sine is an entire function in the complex plane and has no branch cuts. It is periodic with respect to the imaginary component, with period 2πi

+

Example

#include <stdio.h>
+#include <math.h>
+#include <complex.h>
+ 
+int main(void)
+{
+    double complex z = csinh(1);  // behaves like real sinh along the real line
+    printf("sinh(1+0i) = %f%+fi (sinh(1)=%f)\n", creal(z), cimag(z), sinh(1));
+ 
+    double complex z2 = csinh(I); // behaves like sine along the imaginary line
+    printf("sinh(0+1i) = %f%+fi ( sin(1)=%f)\n", creal(z2), cimag(z2), sin(1));
+}

Output:

+
sinh(1+0i) = 1.175201+0.000000i (sinh(1)=1.175201)
+sinh(0+1i) = 0.000000+0.841471i ( sin(1)=0.841471)

References

See also

+ + + + +
+
(C99)(C99)(C99)
 computes the complex hyperbolic cosine
(function)
+
(C99)(C99)(C99)
 computes the complex hyperbolic tangent
(function)
+
(C99)(C99)(C99)
 computes the complex arc hyperbolic sine
(function)
+
(C99)(C99)
 computes hyperbolic sine (\({\small\sinh{x} }\)sinh(x))
(function)
C++ documentation for sinh
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/complex/csinh +

+
diff --git a/devdocs/c/numeric%2Fcomplex%2Fcsqrt.html b/devdocs/c/numeric%2Fcomplex%2Fcsqrt.html new file mode 100644 index 00000000..66c0b835 --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcsqrt.html @@ -0,0 +1,62 @@ +

csqrtf, csqrt, csqrtl

Defined in header <complex.h> 
float complex       csqrtf( float complex z );
+		 (1) (since C99) 
double complex      csqrt( double complex z );
+		 (2) (since C99) 
long double complex csqrtl( long double complex z );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define sqrt( z )
+		 (4) (since C99)
+1-3) Computes the complex square root of z with branch cut along the negative real axis.
+4) Type-generic macro: If z has type long double complex, csqrtl is called. if z has type double complex, csqrt is called, if z has type float complex, csqrtf is called. If z is real or integer, then the macro invokes the corresponding real function (sqrtf, sqrt, sqrtl). If z is imaginary, the corresponding complex number version is called.

Parameters

+ +
z - complex argument

Return value

If no errors occur, returns the square root of z, in the range of the right half-plane, including the imaginary axis ([0; +∞) along the real axis and (−∞; +∞) along the imaginary axis.)

+

Error handling and special values

Errors are reported consistent with math_errhandling

+

If the implementation supports IEEE floating-point arithmetic,

+

Example

#include <stdio.h>
+#include <complex.h>
+ 
+int main(void)
+{
+    double complex z1 = csqrt(-4);
+    printf("Square root of -4 is %.1f%+.1fi\n", creal(z1), cimag(z1));
+ 
+    double complex z2 = csqrt(conj(-4)); // or, in C11, CMPLX(-4, -0.0)
+    printf("Square root of -4-0i, the other side of the cut, is "
+           "%.1f%+.1fi\n", creal(z2), cimag(z2));
+}

Output:

+
Square root of -4 is 0.0+2.0i
+Square root of -4-0i, the other side of the cut, is 0.0-2.0i

References

See also

+ + +
+
(C99)(C99)(C99)
 computes the complex power function
(function)
+
(C99)(C99)
 computes square root (\(\small{\sqrt{x} }\)√x)
(function)
C++ documentation for sqrt
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/complex/csqrt +

+
diff --git a/devdocs/c/numeric%2Fcomplex%2Fctan.html b/devdocs/c/numeric%2Fcomplex%2Fctan.html new file mode 100644 index 00000000..7eff9416 --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fctan.html @@ -0,0 +1,54 @@ +

ctanf, ctan, ctanl

Defined in header <complex.h> 
float complex       ctanf( float complex z );
+		 (1) (since C99) 
double complex      ctan( double complex z );
+		 (2) (since C99) 
long double complex ctanl( long double complex z );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define tan( z )
+		 (4) (since C99)
+1-3) Computes the complex tangent of z.
+4) Type-generic macro: If z has type long double complex, ctanl is called. if z has type double complex, ctan is called, if z has type float complex, ctanf is called. If z is real or integer, then the macro invokes the corresponding real function (tanf, tan, tanl). If z is imaginary, then the macro invokes the corresponding real version of the function tanh, implementing the formula tan(iy) = i tanh(y), and the return type is imaginary.

Parameters

+ +
z - complex argument

Return value

If no errors occur, the complex tangent of z is returned.

+

Errors and special cases are handled as if the operation is implemented by -i * ctanh(i*z), where i is the imaginary unit.

+

Notes

Tangent is an analytical function on the complex plain and has no branch cuts. It is periodic with respect to the real component, with period πi, and has poles of the first order along the real line, at coordinates (π(1/2 + n), 0). However no common floating-point representation is able to represent π/2 exactly, thus there is no value of the argument for which a pole error occurs. Mathematical definition of the tangent is tan z =

+i(e-iz-eiz)/e-iz+eiz

Example

#include <stdio.h>
+#include <math.h>
+#include <complex.h>
+ 
+int main(void)
+{
+    double complex z = ctan(1);  // behaves like real tangent along the real line
+    printf("tan(1+0i) = %f%+fi ( tan(1)=%f)\n", creal(z), cimag(z), tan(1));
+ 
+    double complex z2 = ctan(I); // behaves like tanh along the imaginary line 
+    printf("tan(0+1i) = %f%+fi (tanh(1)=%f)\n", creal(z2), cimag(z2), tanh(1));
+}

Output:

+
tan(1+0i) = 1.557408+0.000000i ( tan(1)=1.557408)
+tan(0+1i) = 0.000000+0.761594i (tanh(1)=0.761594)

References

See also

+ + + + + +
+
(C99)(C99)(C99)
 computes the complex hyperbolic tangent
(function)
+
(C99)(C99)(C99)
 computes the complex sine
(function)
+
(C99)(C99)(C99)
 computes the complex cosine
(function)
+
(C99)(C99)(C99)
 computes the complex arc tangent
(function)
+
(C99)(C99)
 computes tangent (\({\small\tan{x} }\)tan(x))
(function)
C++ documentation for tan
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/complex/ctan +

+
diff --git a/devdocs/c/numeric%2Fcomplex%2Fctanh.html b/devdocs/c/numeric%2Fcomplex%2Fctanh.html new file mode 100644 index 00000000..d3d586b4 --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fctanh.html @@ -0,0 +1,67 @@ +

ctanhf, ctanh, ctanhl

Defined in header <complex.h> 
float complex       ctanhf( float complex z );
+		 (1) (since C99) 
double complex      ctanh( double complex z );
+		 (2) (since C99) 
long double complex ctanhl( long double complex z );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define tanh( z )
+		 (4) (since C99)
+1-3) Computes the complex hyperbolic tangent of z.
+4) Type-generic macro: If z has type long double complex, ctanhl is called. if z has type double complex, ctanh is called, if z has type float complex, ctanhf is called. If z is real or integer, then the macro invokes the corresponding real function (tanhf, tanh, tanhl). If z is imaginary, then the macro invokes the corresponding real version of the function tan, implementing the formula tanh(iy) = i tan(y), and the return type is imaginary.

Parameters

+ +
z - complex argument

Return value

If no errors occur, complex hyperbolic tangent of z is returned

+

Error handling and special values

Errors are reported consistent with math_errhandling

+

If the implementation supports IEEE floating-point arithmetic,

+
  1. per DR471, this only holds for non-zero x. If z is 0+∞i, the result should be 0+NaNi
  2. per DR471, this only holds for non-zero x. If z is 0+NaNi, the result should be 0+NaNi

Notes

Mathematical definition of hyperbolic tangent is tanh z = ez-e-z/ez+e-z

Hyperbolic tangent is an analytical function on the complex plane and has no branch cuts. It is periodic with respect to the imaginary component, with period πi, and has poles of the first order along the imaginary line, at coordinates (0, π(1/2 + n)). However no common floating-point representation is able to represent π/2 exactly, thus there is no value of the argument for which a pole error occurs.

+

Example

#include <stdio.h>
+#include <math.h>
+#include <complex.h>
+ 
+int main(void)
+{
+    double complex z = ctanh(1);  // behaves like real tanh along the real line
+    printf("tanh(1+0i) = %f%+fi (tanh(1)=%f)\n", creal(z), cimag(z), tanh(1));
+ 
+    double complex z2 = ctanh(I); // behaves like tangent along the imaginary line
+    printf("tanh(0+1i) = %f%+fi ( tan(1)=%f)\n", creal(z2), cimag(z2), tan(1));
+}

Output:

+
tanh(1+0i) = 0.761594+0.000000i (tanh(1)=0.761594)
+tanh(0+1i) = 0.000000+1.557408i ( tan(1)=1.557408)

References

See also

+ + + + +
+
(C99)(C99)(C99)
 computes the complex hyperbolic sine
(function)
+
(C99)(C99)(C99)
 computes the complex hyperbolic cosine
(function)
+
(C99)(C99)(C99)
 computes the complex arc hyperbolic tangent
(function)
+
(C99)(C99)
 computes hyperbolic tangent (\({\small\tanh{x} }\)tanh(x))
(function)
C++ documentation for tanh
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/complex/ctanh +

+
diff --git a/devdocs/c/numeric%2Fcomplex%2Fi.html b/devdocs/c/numeric%2Fcomplex%2Fi.html new file mode 100644 index 00000000..d1d3f90d --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fi.html @@ -0,0 +1,45 @@ +

I

Defined in header <complex.h> 
#define I /* unspecified */
+		 (since C99)

The I macro expands to either _Complex_I or _Imaginary_I. If the implementation does not support imaginary types, then the macro always expands to _Complex_I.

+

A program may undefine and perhaps then redefine the macro I.

+

Notes

The macro is not named i, which is the name of the imaginary unit in mathematics, because the name i was already used in many C programs, e.g. as a loop counter variable.

+

The macro I is often used to form complex numbers, with expressions such as x + y*I. If I is defined as _Complex_I, then such expression may create a value with imaginary component +0.0 even when y is -0.0, which is significant for complex number functions with branch cuts. The macro CMPLX provides a way to construct a complex number precisely.

+

GCC provides a non-portable extension that allows imaginary constants to be specified with the suffix i on integer literals: 1.0fi, 1.0i, and 1.0li are imaginary units in GNU C. A similar approach is part of standard C++ as of C++14 (1.0if, 1.0i, and 1.0il are the imaginary units in C++)

+

Example

#include <stdio.h>
+#include <complex.h>
+ 
+int main(void)
+{
+    printf("I = %.1f%+.1fi\n", creal(I), cimag(I));
+ 
+    double complex z1 = I * I;     // imaginary unit squared
+    printf("I * I = %.1f%+.1fi\n", creal(z1), cimag(z1));
+ 
+    double complex z = 1.0 + 2.0*I; // usual way to form a complex number pre-C11
+    printf("z = %.1f%+.1fi\n", creal(z), cimag(z));
+}

Output:

+
I = 0.0+1.0i
+I * I = -1.0+0.0i
+z = 1.0+2.0i

References

See also

+ + + +
+
(C99)
 the imaginary unit constant i
(macro constant)
+
(C99)
 the complex unit constant i
(macro constant)
+
(C11)(C11)(C11)
 constructs a complex number from real and imaginary parts
(function macro)
C++ documentation for operator""i
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/complex/I +

+
diff --git a/devdocs/c/numeric%2Fcomplex%2Fimaginary.html b/devdocs/c/numeric%2Fcomplex%2Fimaginary.html new file mode 100644 index 00000000..5b1db5b0 --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fimaginary.html @@ -0,0 +1,47 @@ +

imaginary

Defined in header <complex.h> 
#define imaginary _Imaginary
+		 (since C99)

This macro expands to the keyword _Imaginary.

+

This is a convenience macro that makes it possible to use float imaginary, double imaginary, and long double imaginary as an alternative way to write the three pure imaginary C types float _Imaginary, double _Imaginary, and long double _Imaginary

+

As with any pure imaginary number support in C, this macro is only defined if the imaginary numbers are supported.

+ + + + +

A compiler that defines __STDC_IEC_559_COMPLEX__ is not required to support imaginary numbers. POSIX recommends checking if the macro _Imaginary_I is defined to identify imaginary number support.

+		 +(since C99)
(until C11) +

Imaginary numbers are supported if __STDC_IEC_559_COMPLEX__ is defined.

+		 (since C11)

Notes

Programs are allowed to undefine and perhaps redefine the imaginary macro.

+

Example

#include <stdio.h>
+#include <complex.h>
+ 
+int main(void)
+{
+    double imaginary i = -2.0*I; // pure imaginary
+    double f = 1.0; // pure real
+    double complex z = f + i; // complex number
+    printf("z = %.1f%+.1fi\n", creal(z), cimag(z));
+}

Output:

+
z = 1.0-2.0i

References

See also

+
+
(C99)
 complex type macro
(keyword macro)
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/complex/imaginary +

+
diff --git a/devdocs/c/numeric%2Fcomplex%2Fimaginary_i.html b/devdocs/c/numeric%2Fcomplex%2Fimaginary_i.html new file mode 100644 index 00000000..553a7a26 --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fimaginary_i.html @@ -0,0 +1,46 @@ +

_Imaginary_I

Defined in header <complex.h> 
#define _Imaginary_I /* unspecified */
+		 (since C99)

The _Imaginary_I macro expands to a value of type const float _Imaginary with the value of the imaginary unit.

+

As with any pure imaginary number support in C, this macro is only defined if the imaginary numbers are supported.

+ + + + +

A compiler that defines __STDC_IEC_559_COMPLEX__ is not required to support imaginary numbers. POSIX recommends checking if the macro _Imaginary_I is defined to identify imaginary number support.

+		 +(since C99)
(until C11) +

Imaginary numbers are supported if __STDC_IEC_559_COMPLEX__ is defined.

+		 (since C11)

Notes

This macro allows for the precise way to assemble a complex number from its real and imaginary components, e.g. with (double complex)((double)x + _Imaginary_I * (double)y). This pattern was standardized in C11 as the macro CMPLX. Note that if _Complex_I is used instead, this expression is allowed to convert negative zero to positive zero in the imaginary position.

+

Example

#include <stdio.h>
+#include <complex.h>
+#include <math.h>
+ 
+int main(void)
+{
+    double complex z1 = 0.0 + INFINITY * _Imaginary_I;
+    printf("z1 = %.1f%+.1fi\n", creal(z1), cimag(z1));
+ 
+    double complex z2 = 0.0 + INFINITY * _Complex_I;
+    printf("z2 = %.1f%+.1fi\n", creal(z2), cimag(z2));
+}

Output:

+
z1 = 0.0+Infi 
+z2 = NaN+Infi

References

See also

+ +
+
(C99)
 the complex unit constant i
(macro constant)
+
(C99)
 the complex or imaginary unit constant i
(macro constant)
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/complex/Imaginary_I +

+
diff --git a/devdocs/c/numeric%2Fcomplex.html b/devdocs/c/numeric%2Fcomplex.html new file mode 100644 index 00000000..70ae214f --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex.html @@ -0,0 +1,139 @@ +

Complex number arithmetic

+ +

If the macro constant __STDC_NO_COMPLEX__ is defined by the implementation, the complex types, the header <complex.h> and all of the names listed here are not provided.

+		 (since C11)

The C programming language, as of C99, supports complex number math with the three built-in types double _Complex, float _Complex, and long double _Complex (see _Complex). When the header <complex.h> is included, the three complex number types are also accessible as double complex, float complex, long double complex.

+

In addition to the complex types, the three imaginary types may be supported: double _Imaginary, float _Imaginary, and long double _Imaginary (see _Imaginary). When the header <complex.h> is included, the three imaginary types are also accessible as double imaginary, float imaginary, and long double imaginary.

+

Standard arithmetic operators +, -, *, / can be used with real, complex, and imaginary types in any combination.

+ + + + +

A compiler that defines __STDC_IEC_559_COMPLEX__ is recommended, but not required to support imaginary numbers. POSIX recommends checking if the macro _Imaginary_I is defined to identify imaginary number support.

+		 +(since C99)
(until C11) +

Imaginary numbers are supported if __STDC_IEC_559_COMPLEX__ or __STDC_IEC_60559_COMPLEX__(since C23) is defined.

+		 (since C11)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Defined in header <complex.h>
Types
+
(C99)
 imaginary type macro
(keyword macro)
+
(C99)
 complex type macro
(keyword macro)
The imaginary constant
+
(C99)
 the imaginary unit constant i
(macro constant)
+
(C99)
 the complex unit constant i
(macro constant)
+
(C99)
 the complex or imaginary unit constant i
(macro constant)
Manipulation
+
(C11)(C11)(C11)
 constructs a complex number from real and imaginary parts
(function macro)
+
(C99)(C99)(C99)
 computes the real part of a complex number
(function)
+
(C99)(C99)(C99)
 computes the imaginary part a complex number
(function)
+
(C99)(C99)(C99)
 computes the magnitude of a complex number
(function)
+
(C99)(C99)(C99)
 computes the phase angle of a complex number
(function)
+
(C99)(C99)(C99)
 computes the complex conjugate
(function)
+
(C99)(C99)(C99)
 computes the projection on Riemann sphere
(function)
Exponential functions
+
(C99)(C99)(C99)
 computes the complex base-e exponential
(function)
+
(C99)(C99)(C99)
 computes the complex natural logarithm
(function)
Power functions
+
(C99)(C99)(C99)
 computes the complex power function
(function)
+
(C99)(C99)(C99)
 computes the complex square root
(function)
Trigonometric functions
+
(C99)(C99)(C99)
 computes the complex sine
(function)
+
(C99)(C99)(C99)
 computes the complex cosine
(function)
+
(C99)(C99)(C99)
 computes the complex tangent
(function)
+
(C99)(C99)(C99)
 computes the complex arc sine
(function)
+
(C99)(C99)(C99)
 computes the complex arc cosine
(function)
+
(C99)(C99)(C99)
 computes the complex arc tangent
(function)
Hyperbolic functions
+
(C99)(C99)(C99)
 computes the complex hyperbolic sine
(function)
+
(C99)(C99)(C99)
 computes the complex hyperbolic cosine
(function)
+
(C99)(C99)(C99)
 computes the complex hyperbolic tangent
(function)
+
(C99)(C99)(C99)
 computes the complex arc hyperbolic sine
(function)
+
(C99)(C99)(C99)
 computes the complex arc hyperbolic cosine
(function)
+
(C99)(C99)(C99)
 computes the complex arc hyperbolic tangent
(function)

Notes

The following function names are potentially(since C23) reserved for future addition to complex.h and are not available for use in the programs that include that header: cerf, cerfc, cexp2, cexpm1, clog10, clog1p, clog2, clgamma, ctgamma, csinpi, ccospi, ctanpi, casinpi, cacospi, catanpi, ccompoundn, cpown, cpowr, crootn, crsqrt, cexp10m1, cexp10, cexp2m1, clog10p1, clog2p1, clogp1(since C23), along with their -f and -l suffixed variants.

+

Although the C standard names the inverse hyperbolics with "complex arc hyperbolic sine" etc., the inverse functions of the hyperbolic functions are the area functions. Their argument is the area of a hyperbolic sector, not an arc. The correct names are "complex inverse hyperbolic sine" etc. Some authors use "complex area hyperbolic sine" etc.

+

A complex or imaginary number is infinite if one of its parts is infinite, even if the other part is NaN.

+

A complex or imaginary number is finite if both parts are neither infinities nor NaNs.

+

A complex or imaginary number is a zero if both parts are positive or negative zeroes.

+

Example

#include <stdio.h>
+#include <complex.h>
+#include <tgmath.h>
+ 
+int main(void)
+{
+    double complex z1 = I * I;     // imaginary unit squared
+    printf("I * I = %.1f%+.1fi\n", creal(z1), cimag(z1));
+ 
+    double complex z2 = pow(I, 2); // imaginary unit squared
+    printf("pow(I, 2) = %.1f%+.1fi\n", creal(z2), cimag(z2));
+ 
+    double PI = acos(-1);
+    double complex z3 = exp(I * PI); // Euler's formula
+    printf("exp(I*PI) = %.1f%+.1fi\n", creal(z3), cimag(z3));
+ 
+    double complex z4 = 1+2*I, z5 = 1-2*I; // conjugates
+    printf("(1+2i)*(1-2i) = %.1f%+.1fi\n", creal(z4*z5), cimag(z4*z5));
+}

Output:

+
I * I = -1.0+0.0i
+pow(I, 2) = -1.0+0.0i
+exp(I*PI) = -1.0+0.0i
+(1+2i)*(1-2i) = 5.0+0.0i

References

See also

+
C++ documentation for Complex number arithmetic
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/complex +

+
diff --git a/devdocs/c/numeric%2Ffenv%2Ffe_dfl_env.html b/devdocs/c/numeric%2Ffenv%2Ffe_dfl_env.html new file mode 100644 index 00000000..bbc17453 --- /dev/null +++ b/devdocs/c/numeric%2Ffenv%2Ffe_dfl_env.html @@ -0,0 +1,80 @@ +

FE_DFL_ENV

Defined in header <fenv.h> 
#define FE_DFL_ENV  /*implementation defined*/
+		 (since C99)

The macro constant FE_DFL_ENV expands to an expression of type const fenv_t*, which points to a full copy of the default floating-point environment, that is, the environment as loaded at program startup.

+

Additional macros that begin with FE_ followed by uppercase letters, and have the type const fenv_t*, may be supported by an implementation.

+

Example

#include <stdio.h>
+#include <fenv.h>
+ 
+#pragma STDC FENV_ACCESS ON
+ 
+void show_fe_exceptions(void)
+{
+    printf("current exceptions raised: ");
+    if(fetestexcept(FE_DIVBYZERO))     printf(" FE_DIVBYZERO");
+    if(fetestexcept(FE_INEXACT))       printf(" FE_INEXACT");
+    if(fetestexcept(FE_INVALID))       printf(" FE_INVALID");
+    if(fetestexcept(FE_OVERFLOW))      printf(" FE_OVERFLOW");
+    if(fetestexcept(FE_UNDERFLOW))     printf(" FE_UNDERFLOW");
+    if(fetestexcept(FE_ALL_EXCEPT)==0) printf(" none");
+    printf("\n");
+}
+ 
+void show_fe_rounding_method(void)
+{
+    printf("current rounding method:    ");
+    switch (fegetround()) {
+           case FE_TONEAREST:  printf ("FE_TONEAREST");  break;
+           case FE_DOWNWARD:   printf ("FE_DOWNWARD");   break;
+           case FE_UPWARD:     printf ("FE_UPWARD");     break;
+           case FE_TOWARDZERO: printf ("FE_TOWARDZERO"); break;
+           default:            printf ("unknown");
+    };
+    printf("\n");
+}
+ 
+void show_fe_environment(void)
+{
+    show_fe_exceptions();
+    show_fe_rounding_method();
+} 
+ 
+int main()
+{
+    printf("On startup:\n");
+    show_fe_environment();
+ 
+    // Change environment
+    fesetround(FE_DOWNWARD);     // change rounding mode
+    feraiseexcept(FE_INVALID);   // raise exception
+    printf("\nBefore restoration:\n");
+    show_fe_environment();
+ 
+    fesetenv(FE_DFL_ENV);    // restore
+    printf("\nAfter restoring default environment:\n");
+    show_fe_environment();
+}

Output:

+
On startup:
+current exceptions raised:  none
+current rounding method:    FE_TONEAREST
+ 
+Before restoration:
+current exceptions raised:  FE_INVALID
+current rounding method:    FE_DOWNWARD
+ 
+After restoring default environment:
+current exceptions raised:  none
+current rounding method:    FE_TONEAREST

References

See also

+ + +
+
(C99)
 saves or restores the current floating-point environment
(function)
+
(C99)
 restores the floating-point environment and raises the previously raise exceptions
(function)
C++ documentation for FE_DFL_ENV
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/fenv/FE_DFL_ENV +

+
diff --git a/devdocs/c/numeric%2Ffenv%2Ffe_exceptions.html b/devdocs/c/numeric%2Ffenv%2Ffe_exceptions.html new file mode 100644 index 00000000..aa31da7a --- /dev/null +++ b/devdocs/c/numeric%2Ffenv%2Ffe_exceptions.html @@ -0,0 +1,87 @@ +

FE_DIVBYZERO, FE_INEXACT, FE_INVALID, FE_OVERFLOW, FE_UNDERFLOW, FE_ALL_EXCEPT

Defined in header <fenv.h> 
#define FE_DIVBYZERO    /*implementation defined power of 2*/
+		 (since C99) 
#define FE_INEXACT      /*implementation defined power of 2*/
+		 (since C99) 
#define FE_INVALID      /*implementation defined power of 2*/
+		 (since C99) 
#define FE_OVERFLOW     /*implementation defined power of 2*/
+		 (since C99) 
#define FE_UNDERFLOW    /*implementation defined power of 2*/
+		 (since C99) 
#define FE_ALL_EXCEPT  FE_DIVBYZERO | FE_INEXACT | \
+                       FE_INVALID | FE_OVERFLOW |  \
+                       FE_UNDERFLOW
+		 (since C99)

All these macro constants (except FE_ALL_EXCEPT) expand to integer constant expressions that are distinct powers of 2, which uniquely identify all supported floating-point exceptions. Each macro is only defined if it is supported.

+

The macro constant FE_ALL_EXCEPT, which expands to the bitwise OR of all other FE_*, is always defined and is zero if floating-point exceptions are not supported by the implementation.

+ + + + + + + +
Constant Explanation
FE_DIVBYZERO pole error occurred in an earlier floating-point operation
FE_INEXACT inexact result: rounding was necessary to store the result of an earlier floating-point operation
FE_INVALID domain error occurred in an earlier floating-point operation
FE_OVERFLOW the result of an earlier floating-point operation was too large to be representable
FE_UNDERFLOW the result of an earlier floating-point operation was subnormal with a loss of precision
FE_ALL_EXCEPT bitwise OR of all supported floating-point exceptions

The implementation may define additional macro constants in <fenv.h> to identify additional floating-point exceptions. All such constants begin with FE_ followed by at least one uppercase letter.

+

See math_errhandling for further details.

+

Example

#include <stdio.h>
+#include <math.h>
+#include <float.h>
+#include <fenv.h>
+ 
+#pragma STDC FENV_ACCESS ON
+void show_fe_exceptions(void)
+{
+    printf("exceptions raised:");
+    if(fetestexcept(FE_DIVBYZERO)) printf(" FE_DIVBYZERO");
+    if(fetestexcept(FE_INEXACT))   printf(" FE_INEXACT");
+    if(fetestexcept(FE_INVALID))   printf(" FE_INVALID");
+    if(fetestexcept(FE_OVERFLOW))  printf(" FE_OVERFLOW");
+    if(fetestexcept(FE_UNDERFLOW)) printf(" FE_UNDERFLOW");
+    feclearexcept(FE_ALL_EXCEPT);
+    printf("\n");
+}
+ 
+int main(void)
+{
+    printf("MATH_ERREXCEPT is %s\n",
+           math_errhandling & MATH_ERREXCEPT ? "set" : "not set");
+ 
+    printf("0.0/0.0 = %f\n", 0.0/0.0);
+    show_fe_exceptions();
+ 
+    printf("1.0/0.0 = %f\n", 1.0/0.0);
+    show_fe_exceptions();
+ 
+    printf("1.0/10.0 = %f\n", 1.0/10.0);
+    show_fe_exceptions();
+ 
+    printf("sqrt(-1) = %f\n", sqrt(-1));
+    show_fe_exceptions();
+ 
+    printf("DBL_MAX*2.0 = %f\n", DBL_MAX*2.0);
+    show_fe_exceptions();
+ 
+    printf("nextafter(DBL_MIN/pow(2.0,52),0.0) = %.1f\n",
+                      nextafter(DBL_MIN/pow(2.0,52),0.0));
+    show_fe_exceptions();
+}

Possible output:

+
MATH_ERREXCEPT is set
+0.0/0.0 = nan
+exceptions raised: FE_INVALID
+1.0/0.0 = inf
+exceptions raised: FE_DIVBYZERO
+1.0/10.0 = 0.100000
+exceptions raised: FE_INEXACT
+sqrt(-1) = -nan
+exceptions raised: FE_INVALID
+DBL_MAX*2.0 = inf
+exceptions raised: FE_INEXACT FE_OVERFLOW
+nextafter(DBL_MIN/pow(2.0,52),0.0) = 0.0
+exceptions raised: FE_INEXACT FE_UNDERFLOW

References

See also

+ +
+
(C99)(C99)(C99)
 defines the error handling mechanism used by the common mathematical functions
(macro constant)
C++ documentation for floating-point exception macros
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/fenv/FE_exceptions +

+
diff --git a/devdocs/c/numeric%2Ffenv%2Ffe_round.html b/devdocs/c/numeric%2Ffenv%2Ffe_round.html new file mode 100644 index 00000000..716eed9d --- /dev/null +++ b/devdocs/c/numeric%2Ffenv%2Ffe_round.html @@ -0,0 +1,71 @@ +

FE_DOWNWARD, FE_TONEAREST, FE_TOWARDZERO, FE_UPWARD

Defined in header <fenv.h> 
#define FE_DOWNWARD     /*implementation defined*/
+		 (since C99) 
#define FE_TONEAREST    /*implementation defined*/
+		 (since C99) 
#define FE_TOWARDZERO   /*implementation defined*/
+		 (since C99) 
#define FE_UPWARD       /*implementation defined*/
+		 (since C99)

Each of these macro constants expands to a nonnegative integer constant expression, which can be used with fesetround and fegetround to indicate one of the supported floating-point rounding modes. The implementation may define additional rounding mode constants in <fenv.h>, which should all begin with FE_ followed by at least one uppercase letter. Each macro is only defined if it is supported.

+ + + + + +
Constant Explanation
FE_DOWNWARD rounding towards negative infinity
FE_TONEAREST rounding towards nearest representable value
FE_TOWARDZERO rounding towards zero
FE_UPWARD rounding towards positive infinity

Additional rounding modes may be supported by an implementation.

+

The current rounding mode affects the following:

+ 
double x = 1;
+x / 10; // 0.09999999999999999167332731531132594682276248931884765625 or
+        // 0.1000000000000000055511151231257827021181583404541015625
sqrt(2); // 1.41421356237309492343001693370752036571502685546875 or
+         // 1.4142135623730951454746218587388284504413604736328125
double d = 1 + DBL_EPSILON;
+float f = d; // 1.00000000000000000000000 or
+             // 1.00000011920928955078125
strtof("0.1", NULL); // 0.0999999940395355224609375 or
+                     // 0.100000001490116119384765625
lrint(2.1); // 2 or 3

The current rounding mode does NOT affect the following:

+

As with any floating-point environment functionality, rounding is only guaranteed if #pragma STDC FENV_ACCESS ON is set.

+

Compilers that do not support the pragma may offer their own ways to support current rounding mode. For example Clang and GCC have the option -frounding-math intended to disable optimizations that would change the meaning of rounding-sensitive code.

+

Example

#include <fenv.h>
+#include <math.h>
+#include <stdio.h>
+#include <stdlib.h>
+ 
+// #pragma STDC FENV_ACCESS ON
+ 
+int main()
+{
+    fesetround(FE_DOWNWARD);
+    puts("rounding down: ");
+    printf("           pi = %.22f\n", acosf(-1));
+    printf("strtof(\"1.1\") = %.22f\n", strtof("1.1", NULL));
+    printf("    rint(2.1) = %.22f\n\n", rintf(2.1));
+    fesetround(FE_UPWARD);
+    puts("rounding up: ");
+    printf("           pi = %.22f\n", acosf(-1));
+    printf("strtof(\"1.1\") = %.22f\n", strtof("1.1", NULL));
+    printf("    rint(2.1) = %.22f\n", rintf(2.1));
+}

Output:

+
rounding down:
+           pi = 3.1415925025939941406250
+strtof("1.1") = 1.0999999046325683593750
+    rint(2.1) = 2.0000000000000000000000
+ 
+rounding up:
+           pi = 3.1415927410125732421875
+strtof("1.1") = 1.1000000238418579101563
+    rint(2.1) = 3.0000000000000000000000

References

See also

+ +
+
(C99)(C99)
 gets or sets rounding direction
(function)
C++ documentation for floating-point rounding macros
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/fenv/FE_round +

+
diff --git a/devdocs/c/numeric%2Ffenv%2Ffeclearexcept.html b/devdocs/c/numeric%2Ffenv%2Ffeclearexcept.html new file mode 100644 index 00000000..04dbc3ee --- /dev/null +++ b/devdocs/c/numeric%2Ffenv%2Ffeclearexcept.html @@ -0,0 +1,63 @@ +

feclearexcept

Defined in header <fenv.h> 
int feclearexcept( int excepts );
+		 (since C99)

Attempts to clear the floating-point exceptions that are listed in the bitmask argument excepts, which is a bitwise OR of the floating-point exception macros.

+

Parameters

+ +
excepts - bitmask listing the exception flags to clear

Return value

​0​ if all indicated exceptions were successfully cleared or if excepts is zero. Returns a non-zero value on error.

+

Example

#include <fenv.h>
+#include <stdio.h>
+#include <math.h>
+#include <float.h>
+ 
+/*
+ * A possible implementation of hypot which makes use of many advanced
+ * floating-point features.
+ */
+double hypot_demo(double a, double b) {
+  const int range_problem = FE_OVERFLOW | FE_UNDERFLOW;
+  feclearexcept(range_problem);
+  // try a fast algorithm
+  double result = sqrt(a * a + b * b);
+  if (!fetestexcept(range_problem))  // no overflow or underflow
+    return result;                   // return the fast result
+  // do a more complicated calculation to avoid overflow or underflow
+  int a_exponent,b_exponent;
+  frexp(a, &a_exponent);
+  frexp(b, &b_exponent);
+ 
+  if (a_exponent - b_exponent > DBL_MAX_EXP)
+    return fabs(a) + fabs(b);        // we can ignore the smaller value
+  // scale so that fabs(a) is near 1
+  double a_scaled = scalbn(a, -a_exponent);
+  double b_scaled = scalbn(b, -a_exponent);
+  // overflow and underflow is now impossible 
+  result = sqrt(a_scaled * a_scaled + b_scaled * b_scaled);
+  // undo scaling
+  return scalbn(result, a_exponent);
+}
+ 
+int main(void)
+{
+  // Normal case takes the fast route
+  printf("hypot(%f, %f) = %f\n", 3.0, 4.0, hypot_demo(3.0, 4.0));
+  // Extreme case takes the slow but more accurate route
+  printf("hypot(%e, %e) = %e\n", DBL_MAX / 2.0, 
+                                DBL_MAX / 2.0, 
+                                hypot_demo(DBL_MAX / 2.0, DBL_MAX / 2.0));
+ 
+  return 0;
+}

Output:

+
hypot(3.000000, 4.000000) = 5.000000
+hypot(8.988466e+307, 8.988466e+307) = 1.271161e+308

References

See also

+ +
+
(C99)
 determines which of the specified floating-point status flags are set
(function)
C++ documentation for feclearexcept
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/fenv/feclearexcept +

+
diff --git a/devdocs/c/numeric%2Ffenv%2Ffeenv.html b/devdocs/c/numeric%2Ffenv%2Ffeenv.html new file mode 100644 index 00000000..55c9bb86 --- /dev/null +++ b/devdocs/c/numeric%2Ffenv%2Ffeenv.html @@ -0,0 +1,116 @@ +

fegetenv, fesetenv

Defined in header <fenv.h> 
int fegetenv( fenv_t* envp );
+		 (1) (since C99) 
int fesetenv( const fenv_t* envp );
+		 (2) (since C99)

1) Attempts to store the status of the floating-point environment in the object pointed to by envp.

+

2) Attempts to establish the floating-point environment from the object pointed to by envp. The value of that object must be previously obtained by a call to feholdexcept or fegetenv or be a floating-point macro constant. If any of the floating-point status flags are set in envp, they become set in the environment (and are then testable with fetestexcept), but the corresponding floating-point exceptions are not raised (execution continues uninterrupted)

+

Parameters

+ +
envp - pointer to the object of type fenv_t which holds the status of the floating-point environment

Return value

​0​ on success, non-zero otherwise.

+

Example

#include <stdio.h>
+#include <math.h>
+#include <fenv.h>
+ 
+#pragma STDC FENV_ACCESS ON
+ 
+void show_fe_exceptions(void)
+{
+    printf("current exceptions raised: ");
+    if(fetestexcept(FE_DIVBYZERO))     printf(" FE_DIVBYZERO");
+    if(fetestexcept(FE_INEXACT))       printf(" FE_INEXACT");
+    if(fetestexcept(FE_INVALID))       printf(" FE_INVALID");
+    if(fetestexcept(FE_OVERFLOW))      printf(" FE_OVERFLOW");
+    if(fetestexcept(FE_UNDERFLOW))     printf(" FE_UNDERFLOW");
+    if(fetestexcept(FE_ALL_EXCEPT)==0) printf(" none");
+    printf("\n");
+}
+ 
+void show_fe_rounding_method(void)
+{
+    printf("current rounding method:    ");
+    switch (fegetround()) {
+           case FE_TONEAREST:  printf ("FE_TONEAREST");  break;
+           case FE_DOWNWARD:   printf ("FE_DOWNWARD");   break;
+           case FE_UPWARD:     printf ("FE_UPWARD");     break;
+           case FE_TOWARDZERO: printf ("FE_TOWARDZERO"); break;
+           default:            printf ("unknown");
+    };
+    printf("\n");
+}
+ 
+void show_fe_environment(void)
+{
+    show_fe_exceptions();
+    show_fe_rounding_method();
+}    
+ 
+int main(void)
+{
+    fenv_t curr_env;
+    int rtn;
+ 
+    /* Show default environment. */
+    show_fe_environment();
+    printf("\n");
+ 
+    /* Perform some computation under default environment. */
+    printf("+11.5 -> %+4.1f\n", rint(+11.5)); /* midway between two integers */
+    printf("+12.5 -> %+4.1f\n", rint(+12.5)); /* midway between two integers */
+    show_fe_environment();
+    printf("\n");
+ 
+    /* Save current environment. */
+    rtn = fegetenv(&curr_env);
+ 
+    /* Perform some computation with new rounding method. */
+    feclearexcept(FE_ALL_EXCEPT);
+    fesetround(FE_DOWNWARD);
+    printf("1.0/0.0 = %f\n", 1.0/0.0);
+    printf("+11.5 -> %+4.1f\n", rint(+11.5));
+    printf("+12.5 -> %+4.1f\n", rint(+12.5));
+    show_fe_environment();
+    printf("\n");
+ 
+    /* Restore previous environment. */
+    rtn = fesetenv(&curr_env);
+    show_fe_environment();
+ 
+    return 0;
+}

Output:

+
current exceptions raised: none
+current rounding method:   FE_TONEAREST
+ 
++11.5 -> +12.0
++12.5 -> +12.0
+current exceptions raised: FE_INEXACT
+current rounding method:   FE_TONEAREST
+ 
+1.0/0.0 = inf
++11.5 -> +11.0
++12.5 -> +12.0
+current exceptions raised: FE_DIVBYZERO FE_INEXACT
+current rounding method:   FE_DOWNWARD
+ 
+current exceptions raised: FE_INEXACT
+current rounding method:   FE_TONEAREST

References

See also

+ + + +
+
(C99)
 saves the environment, clears all status flags and ignores all future errors
(function)
+
(C99)
 restores the floating-point environment and raises the previously raise exceptions
(function)
+
(C99)
 default floating-point environment
(macro constant)
C++ documentation for fegetenv, fesetenv
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/fenv/feenv +

+
diff --git a/devdocs/c/numeric%2Ffenv%2Ffeexceptflag.html b/devdocs/c/numeric%2Ffenv%2Ffeexceptflag.html new file mode 100644 index 00000000..04da8f88 --- /dev/null +++ b/devdocs/c/numeric%2Ffenv%2Ffeexceptflag.html @@ -0,0 +1,68 @@ +

fegetexceptflag, fesetexceptflag

Defined in header <fenv.h> 
int fegetexceptflag( fexcept_t* flagp, int excepts );
+		 (1) (since C99) 
int fesetexceptflag( const fexcept_t* flagp, int excepts );
+		 (2) (since C99)

1) Attempts to obtain the full contents of the floating-point exception flags that are listed in the bitmask argument excepts, which is a bitwise OR of the floating-point exception macros.

+

2) Attempts to copy the full contents of the floating-point exception flags that are listed in excepts from flagp into the floating-point environment. Does not raise any exceptions, only modifies the flags.

+

The full contents of a floating-point exception flag is not necessarily a boolean value indicating whether the exception is raised or cleared. For example, it may be a struct which includes the boolean status and the address of the code that triggered the exception. These functions obtain all such content and obtain/store it in flagp in implementation-defined format.

+

Parameters

+ + +
flagp - pointer to an fexcept_t object where the flags will be stored or read from
excepts - bitmask listing the exception flags to get/set

Return value

​0​ on success, non-zero otherwise.

+

Example

#include <stdio.h>
+#include <fenv.h>
+ 
+#pragma STDC FENV_ACCESS ON
+ 
+void show_fe_exceptions(void)
+{
+    printf("current exceptions raised: ");
+    if(fetestexcept(FE_DIVBYZERO))     printf(" FE_DIVBYZERO");
+    if(fetestexcept(FE_INEXACT))       printf(" FE_INEXACT");
+    if(fetestexcept(FE_INVALID))       printf(" FE_INVALID");
+    if(fetestexcept(FE_OVERFLOW))      printf(" FE_OVERFLOW");
+    if(fetestexcept(FE_UNDERFLOW))     printf(" FE_UNDERFLOW");
+    if(fetestexcept(FE_ALL_EXCEPT)==0) printf(" none");
+    printf("\n");
+}
+ 
+int main(void)
+{
+    fexcept_t excepts;
+ 
+    /* Setup a "current" set of exception flags. */
+    feraiseexcept(FE_INVALID);
+    show_fe_exceptions();
+ 
+    /* Save current exception flags. */
+    fegetexceptflag(&excepts,FE_ALL_EXCEPT);
+ 
+    /* Temporarily raise two other exceptions. */
+    feclearexcept(FE_ALL_EXCEPT);
+    feraiseexcept(FE_OVERFLOW | FE_INEXACT);
+    show_fe_exceptions();
+ 
+    /* Restore previous exception flags. */
+    fesetexceptflag(&excepts,FE_ALL_EXCEPT);
+    show_fe_exceptions();
+ 
+    return 0;
+}

Output:

+
current exceptions raised: FE_INVALID
+current exceptions raised: FE_INEXACT FE_OVERFLOW
+current exceptions raised: FE_INVALID

References

See also

+
C++ documentation for fegetexceptflag, fesetexceptflag
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/fenv/feexceptflag +

+
diff --git a/devdocs/c/numeric%2Ffenv%2Ffeholdexcept.html b/devdocs/c/numeric%2Ffenv%2Ffeholdexcept.html new file mode 100644 index 00000000..bb870968 --- /dev/null +++ b/devdocs/c/numeric%2Ffenv%2Ffeholdexcept.html @@ -0,0 +1,74 @@ +

feholdexcept

Defined in header <fenv.h> 
int feholdexcept( fenv_t* envp );
+		 (since C99)

First, saves the current floating-point environment to the object pointed to by envp (similar to fegetenv), then clears all floating-point status flags, and then installs the non-stop mode: future floating-point exceptions will not interrupt execution (will not trap), until the floating-point environment is restored by feupdateenv or fesetenv.

+

This function may be used in the beginning of a subroutine that must hide the floating-point exceptions it may raise from the caller. If only some exceptions must be suppressed, while others must be reported, the non-stop mode is usually ended with a call to feupdateenv after clearing the unwanted exceptions.

+

Parameters

+ +
envp - pointer to the object of type fenv_t where the floating-point environment will be stored

Return value

​0​ on success, non-zero otherwise.

+

Example

#include <stdio.h>
+#include <fenv.h>
+#include <float.h>
+ 
+#pragma STDC FENV_ACCESS ON
+ 
+void show_fe_exceptions(void)
+{
+    printf("current exceptions raised: ");
+    if(fetestexcept(FE_DIVBYZERO))     printf(" FE_DIVBYZERO");
+    if(fetestexcept(FE_INEXACT))       printf(" FE_INEXACT");
+    if(fetestexcept(FE_INVALID))       printf(" FE_INVALID");
+    if(fetestexcept(FE_OVERFLOW))      printf(" FE_OVERFLOW");
+    if(fetestexcept(FE_UNDERFLOW))     printf(" FE_UNDERFLOW");
+    if(fetestexcept(FE_ALL_EXCEPT)==0) printf(" none");
+    printf("\n");
+}
+ 
+double x2 (double x)   /* times two */
+{
+    fenv_t curr_excepts;
+ 
+    /* Save and clear current f-p environment. */
+    feholdexcept(&curr_excepts);
+ 
+    /* Raise inexact and overflow exceptions. */
+    printf("In x2():  x = %f\n", x=x*2.0);
+    show_fe_exceptions();
+    feclearexcept(FE_INEXACT);   /* hide inexact exception from caller */
+ 
+    /* Merge caller's exceptions (FE_INVALID)        */
+    /* with remaining x2's exceptions (FE_OVERFLOW). */
+    feupdateenv(&curr_excepts);
+    return x;
+}
+ 
+int main(void)
+{    
+    feclearexcept(FE_ALL_EXCEPT);
+    feraiseexcept(FE_INVALID);   /* some computation with invalid argument */
+    show_fe_exceptions();
+    printf("x2(DBL_MAX) = %f\n", x2(DBL_MAX));
+    show_fe_exceptions();
+ 
+    return 0;
+}

Output:

+
current exceptions raised:  FE_INVALID
+In x2():  x = inf
+current exceptions raised:  FE_INEXACT FE_OVERFLOW
+x2(DBL_MAX) = inf
+current exceptions raised:  FE_INVALID FE_OVERFLOW

References

See also

+ + + +
+
(C99)
 restores the floating-point environment and raises the previously raise exceptions
(function)
+
(C99)
 saves or restores the current floating-point environment
(function)
+
(C99)
 default floating-point environment
(macro constant)
C++ documentation for feholdexcept
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/fenv/feholdexcept +

+
diff --git a/devdocs/c/numeric%2Ffenv%2Fferaiseexcept.html b/devdocs/c/numeric%2Ffenv%2Fferaiseexcept.html new file mode 100644 index 00000000..ca35e49d --- /dev/null +++ b/devdocs/c/numeric%2Ffenv%2Fferaiseexcept.html @@ -0,0 +1,55 @@ +

feraiseexcept

Defined in header <fenv.h> 
int feraiseexcept( int excepts );
+		 (since C99)

Attempts to raise all floating-point exceptions listed in excepts (a bitwise OR of the floating-point exception macros). If one of the exceptions is FE_OVERFLOW or FE_UNDERFLOW, this function may additionally raise FE_INEXACT. The order in which the exceptions are raised is unspecified, except that FE_OVERFLOW and FE_UNDERFLOW are always raised before FE_INEXACT.

+

Parameters

+ +
excepts - bitmask listing the exception flags to raise

Return value

​0​ if all listed exceptions were raised, non-zero value otherwise.

+

Example

#include <stdio.h>
+#include <fenv.h>
+ 
+#pragma STDC FENV_ACCESS ON
+ 
+void show_fe_exceptions(void)
+{
+    printf("current exceptions raised: ");
+    if(fetestexcept(FE_DIVBYZERO))     printf(" FE_DIVBYZERO");
+    if(fetestexcept(FE_INEXACT))       printf(" FE_INEXACT");
+    if(fetestexcept(FE_INVALID))       printf(" FE_INVALID");
+    if(fetestexcept(FE_OVERFLOW))      printf(" FE_OVERFLOW");
+    if(fetestexcept(FE_UNDERFLOW))     printf(" FE_UNDERFLOW");
+    if(fetestexcept(FE_ALL_EXCEPT)==0) printf(" none");
+    feclearexcept(FE_ALL_EXCEPT);
+    printf("\n");
+}
+ 
+double some_computation(void)
+{
+    /* Computation reaches a state that causes overflow. */
+    int r = feraiseexcept(FE_OVERFLOW | FE_INEXACT);
+    printf("feraiseexcept() %s\n", (r?"fails":"succeeds"));
+    return 0.0;
+}
+ 
+int main(void)
+{
+    some_computation();
+    show_fe_exceptions();
+ 
+    return 0;
+}

Output:

+
feraiseexcept() succeeds
+current exceptions raised:  FE_INEXACT FE_OVERFLOW

References

See also

+ + +
+
(C99)
 clears the specified floating-point status flags
(function)
+
(C99)
 determines which of the specified floating-point status flags are set
(function)
C++ documentation for feraiseexcept
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/fenv/feraiseexcept +

+
diff --git a/devdocs/c/numeric%2Ffenv%2Fferound.html b/devdocs/c/numeric%2Ffenv%2Fferound.html new file mode 100644 index 00000000..7bbe06b4 --- /dev/null +++ b/devdocs/c/numeric%2Ffenv%2Fferound.html @@ -0,0 +1,88 @@ +

fegetround, fesetround

Defined in header <fenv.h> 
int fesetround( int round );
+		 (1) (since C99) 
int fegetround();
+		 (2) (since C99)

1) Attempts to establish the floating-point rounding direction equal to the argument round, which is expected to be one of the floating-point rounding macros.

+

2) Returns the value of the floating-point rounding macro that corresponds to the current rounding direction.

+

Parameters

+ +
round - rounding direction, one of floating-point rounding macros

Return value

1) ​0​ on success, non-zero otherwise.

+

2) the floating-point rounding macro describing the current rounding direction or a negative value if the direction cannot be determined.

+

Notes

The current rounding mode, reflecting the effects of the most recent fesetround, can also be queried with FLT_ROUNDS.

+

Example

#include <fenv.h>
+#include <math.h>
+#include <stdio.h>
+ 
+// #pragma STDC FENV_ACCESS ON
+ 
+void show_fe_current_rounding_direction(void)
+{
+    printf("current rounding direction:  ");
+    switch (fegetround()) {
+           case FE_TONEAREST:  printf ("FE_TONEAREST");  break;
+           case FE_DOWNWARD:   printf ("FE_DOWNWARD");   break;
+           case FE_UPWARD:     printf ("FE_UPWARD");     break;
+           case FE_TOWARDZERO: printf ("FE_TOWARDZERO"); break;
+           default:            printf ("unknown");
+    };
+    printf("\n");
+}
+ 
+int main(void)
+{
+    /* Default rounding direction */
+    show_fe_current_rounding_direction();
+    printf("+11.5 -> %+4.1f\n", rint(+11.5)); /* midway between two integers */
+    printf("+12.5 -> %+4.1f\n", rint(+12.5)); /* midway between two integers */
+ 
+    /* Save current rounding direction. */
+    int curr_direction = fegetround();
+ 
+    /* Temporarily change current rounding direction. */
+    fesetround(FE_DOWNWARD);
+    show_fe_current_rounding_direction();
+    printf("+11.5 -> %+4.1f\n", rint(+11.5));
+    printf("+12.5 -> %+4.1f\n", rint(+12.5));
+ 
+    /* Restore default rounding direction. */
+    fesetround(curr_direction);
+    show_fe_current_rounding_direction();
+ 
+    return 0;
+}

Possible output:

+
current rounding direction:  FE_TONEAREST
++11.5 -> +12.0
++12.5 -> +12.0
+current rounding direction:  FE_DOWNWARD
++11.5 -> +11.0
++12.5 -> +12.0
+current rounding direction:  FE_TONEAREST

References

See also

+ + +
+
(C99)(C99)(C99)
 rounds to an integer using current rounding mode
(function)
+
(C99)(C99)(C99)(C99)(C99)(C99)(C99)(C99)(C99)
 rounds to an integer using current rounding mode with
exception if the result differs
(function)
C++ documentation for fegetround, fesetround
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/fenv/feround +

+
diff --git a/devdocs/c/numeric%2Ffenv%2Ffetestexcept.html b/devdocs/c/numeric%2Ffenv%2Ffetestexcept.html new file mode 100644 index 00000000..6e100461 --- /dev/null +++ b/devdocs/c/numeric%2Ffenv%2Ffetestexcept.html @@ -0,0 +1,60 @@ +

fetestexcept

Defined in header <fenv.h> 
int fetestexcept( int excepts );
+		 (since C99)

Determines which of the specified subset of the floating-point exceptions are currently set. The argument excepts is a bitwise OR of the floating-point exception macros.

+

Parameters

+ +
excepts - bitmask listing the exception flags to test

Return value

Bitwise OR of the floating-point exception macros that are both included in excepts and correspond to floating-point exceptions currently set.

+

Example

#include <stdio.h>
+#include <math.h>
+#include <fenv.h>
+#include <float.h>
+ 
+#pragma STDC FENV_ACCESS ON
+ 
+void show_fe_exceptions(void)
+{
+    printf("current exceptions raised: ");
+    if(fetestexcept(FE_DIVBYZERO))     printf(" FE_DIVBYZERO");
+    if(fetestexcept(FE_INEXACT))       printf(" FE_INEXACT");
+    if(fetestexcept(FE_INVALID))       printf(" FE_INVALID");
+    if(fetestexcept(FE_OVERFLOW))      printf(" FE_OVERFLOW");
+    if(fetestexcept(FE_UNDERFLOW))     printf(" FE_UNDERFLOW");
+    if(fetestexcept(FE_ALL_EXCEPT)==0) printf(" none");
+    printf("\n");
+}
+ 
+int main(void)
+{
+    /* Show default set of exception flags. */
+    show_fe_exceptions();
+ 
+    /* Perform some computations which raise exceptions. */
+    printf("1.0/0.0     = %f\n", 1.0/0.0);        /* FE_DIVBYZERO            */
+    printf("1.0/10.0    = %f\n", 1.0/10.0);       /* FE_INEXACT              */
+    printf("sqrt(-1)    = %f\n", sqrt(-1));       /* FE_INVALID              */
+    printf("DBL_MAX*2.0 = %f\n", DBL_MAX*2.0);    /* FE_INEXACT FE_OVERFLOW  */
+    printf("nextafter(DBL_MIN/pow(2.0,52),0.0) = %.1f\n",
+           nextafter(DBL_MIN/pow(2.0,52),0.0));   /* FE_INEXACT FE_UNDERFLOW */
+    show_fe_exceptions();
+ 
+    return 0;
+}

Output:

+
current exceptions raised:  none
+1.0/0.0     = inf
+1.0/10.0    = 0.100000
+sqrt(-1)    = -nan
+DBL_MAX*2.0 = inf
+nextafter(DBL_MIN/pow(2.0,52),0.0) = 0.0
+current exceptions raised:  FE_DIVBYZERO FE_INEXACT FE_INVALID FE_OVERFLOW FE_UNDERFLOW

References

See also

+ +
+
(C99)
 clears the specified floating-point status flags
(function)
C++ documentation for fetestexcept
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/fenv/fetestexcept +

+
diff --git a/devdocs/c/numeric%2Ffenv%2Ffeupdateenv.html b/devdocs/c/numeric%2Ffenv%2Ffeupdateenv.html new file mode 100644 index 00000000..e05e65a3 --- /dev/null +++ b/devdocs/c/numeric%2Ffenv%2Ffeupdateenv.html @@ -0,0 +1,74 @@ +

feupdateenv

Defined in header <fenv.h> 
int feupdateenv( const fenv_t* envp );
+		 (since C99)

First, remembers the currently raised floating-point exceptions, then restores the floating-point environment from the object pointed to by envp (similar to fesetenv), then raises the floating-point exceptions that were saved.

+

This function may be used to end the non-stop mode established by an earlier call to feholdexcept.

+

Parameters

+ +
envp - pointer to the object of type fenv_t set by an earlier call to feholdexcept or fegetenv or equal to FE_DFL_ENV

Return value

​0​ on success, non-zero otherwise.

+

Example

#include <stdio.h>
+#include <fenv.h>
+#include <float.h>
+ 
+#pragma STDC FENV_ACCESS ON
+ 
+void show_fe_exceptions(void)
+{
+    printf("current exceptions raised: ");
+    if(fetestexcept(FE_DIVBYZERO))     printf(" FE_DIVBYZERO");
+    if(fetestexcept(FE_INEXACT))       printf(" FE_INEXACT");
+    if(fetestexcept(FE_INVALID))       printf(" FE_INVALID");
+    if(fetestexcept(FE_OVERFLOW))      printf(" FE_OVERFLOW");
+    if(fetestexcept(FE_UNDERFLOW))     printf(" FE_UNDERFLOW");
+    if(fetestexcept(FE_ALL_EXCEPT)==0) printf(" none");
+    printf("\n");
+}
+ 
+double x2 (double x)   /* times two */
+{
+    fenv_t curr_excepts;
+ 
+    /* Save and clear current f-p environment. */
+    feholdexcept(&curr_excepts);
+ 
+    /* Raise inexact and overflow exceptions. */
+    printf("In x2():  x = %f\n", x=x*2.0);
+    show_fe_exceptions();
+    feclearexcept(FE_INEXACT);   /* hide inexact exception from caller */
+ 
+    /* Merge caller's exceptions (FE_INVALID)        */
+    /* with remaining x2's exceptions (FE_OVERFLOW). */
+    feupdateenv(&curr_excepts);
+    return x;
+}
+ 
+int main(void)
+{    
+    feclearexcept(FE_ALL_EXCEPT);
+    feraiseexcept(FE_INVALID);   /* some computation with invalid argument */
+    show_fe_exceptions();
+    printf("x2(DBL_MAX) = %f\n", x2(DBL_MAX));
+    show_fe_exceptions();
+ 
+    return 0;
+}

Output:

+
current exceptions raised:  FE_INVALID
+In x2():  x = inf
+current exceptions raised:  FE_INEXACT FE_OVERFLOW
+x2(DBL_MAX) = inf
+current exceptions raised:  FE_INVALID FE_OVERFLOW

References

See also

+ + + +
+
(C99)
 saves the environment, clears all status flags and ignores all future errors
(function)
+
(C99)
 saves or restores the current floating-point environment
(function)
+
(C99)
 default floating-point environment
(macro constant)
C++ documentation for feupdateenv
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/fenv/feupdateenv +

+
diff --git a/devdocs/c/numeric%2Ffenv.html b/devdocs/c/numeric%2Ffenv.html new file mode 100644 index 00000000..6cec45e9 --- /dev/null +++ b/devdocs/c/numeric%2Ffenv.html @@ -0,0 +1,52 @@ +

Floating-point environment

The floating-point environment is the set of floating-point status flags and control modes supported by the implementation. It is thread-local, each thread inherits the initial state of its floating-point environment from the parent thread. Floating-point operations modify the floating-point status flags to indicate abnormal results or auxiliary information. The state of floating-point control modes affects the outcomes of some floating-point operations.

+

The floating-point environment access and modification is only meaningful when #pragma STDC FENV_ACCESS is set to ON. Otherwise the implementation is free to assume that floating-point control modes are always the default ones and that floating-point status flags are never tested or modified. In practice, few current compilers, such as HP aCC, Oracle Studio, and IBM XL, support the #pragma explicitly, but most compilers allow meaningful access to the floating-point environment anyway.

+

Types

+ + +
Defined in header <fenv.h>
fenv_t The type representing the entire floating-point environment
fexcept_t The type representing all floating-point status flags collectively

Functions

+ + + + + + + +
+
(C99)
 clears the specified floating-point status flags
(function)
+
(C99)
 determines which of the specified floating-point status flags are set
(function)
+
(C99)
 raises the specified floating-point exceptions
(function)
+
(C99)(C99)
 copies the state of the specified floating-point status flags from or to the floating-point environment
(function)
+
(C99)(C99)
 gets or sets rounding direction
(function)
+
(C99)
 saves or restores the current floating-point environment
(function)
+
(C99)
 saves the environment, clears all status flags and ignores all future errors
(function)
+
(C99)
 restores the floating-point environment and raises the previously raise exceptions
(function)

Macros

+ + +
+
(C99)
 floating-point exceptions
(macro constant)
+
(C99)
 floating-point rounding direction
(macro constant)
+
(C99)
 default floating-point environment
(macro constant)

References

See also

+
C++ documentation for Floating-point environment
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/fenv +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fabs.html b/devdocs/c/numeric%2Fmath%2Fabs.html new file mode 100644 index 00000000..8564aeff --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fabs.html @@ -0,0 +1,53 @@ +

abs, labs, llabs, imaxabs

Defined in header <stdlib.h> 
int        abs( int n );
+		 
long       labs( long n );
+		 
long long llabs( long long n );
+		 (since C99)
Defined in header <inttypes.h> 
intmax_t imaxabs( intmax_t n );
+		 (since C99)

Computes the absolute value of an integer number. The behavior is undefined if the result cannot be represented by the return type.

+

Parameters

+ +
n - integer value

Return value

The absolute value of n (i.e. |n|), if it is representable.

+

Notes

In 2's complement systems, the absolute value of the most-negative value is out of range, e.g. for 32-bit 2's complement type int, INT_MIN is -2147483648, but the would-be result 2147483648 is greater than INT_MAX, which is 2147483647.

+

Example

#include <stdio.h>
+#include <stdlib.h>
+#include <limits.h>
+ 
+int main(void)
+{
+    printf("abs(+3) = %d\n", abs(+3));
+    printf("abs(-3) = %d\n", abs(-3));
+ 
+//  printf("%+d\n", abs(INT_MIN)); // undefined behavior on 2's complement systems
+}

Output:

+
abs(+3) = 3
+abs(-3) = 3

References

See also

+ + +
+
(C99)(C99)
 computes absolute value of a floating-point value (\(\small{|x|}\)|x|)
(function)
+
(C99)(C99)(C99)
 computes the magnitude of a complex number
(function)
C++ documentation for abs
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/abs +

+
diff --git a/devdocs/c/numeric%2Fmath%2Facos.html b/devdocs/c/numeric%2Fmath%2Facos.html new file mode 100644 index 00000000..f697b7ed --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Facos.html @@ -0,0 +1,99 @@ +

acos, acosf, acosl

Defined in header <math.h> 
float       acosf( float arg );
+		 (1) (since C99) 
double      acos( double arg );
+		 (2) 
long double acosl( long double arg );
+		 (3) (since C99) 
_Decimal32  acosd32( _Decimal32 arg );
+		 (4) (since C23) 
_Decimal64  acosd64( _Decimal64 arg );
+		 (5) (since C23) 
_Decimal128 acosd128( _Decimal128 arg );
+		 (6) (since C23)
Defined in header <tgmath.h> 
#define acos( arg )
+		 (7) (since C99)
+1-6) Computes the principal value of the arc cosine of arg.
+7) Type-generic macro: If the argument has type long double, (3) (acosl) is called. Otherwise, if the argument has integer type or the type double, (2) (acos) is called. Otherwise, (1) (acosf) is called. If the argument is complex, then the macro invokes the corresponding complex function (cacosf, cacos, cacosl).
+ +

The functions (4-6) are declared if and only if the implementation predefines __STDC_IEC_60559_DFP__ (i.e. the implementation supports decimal floating-point numbers).

+		 (since C23)

Parameters

+ +
arg - floating-point value

Return value

If no errors occur, the arc cosine of arg (arccos(arg)) in the range [0 ; π], is returned.

+

If a domain error occurs, an implementation-defined value is returned (NaN where supported).

+

If a range error occurs due to underflow, the correct result (after rounding) is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

Domain error occurs if arg is outside the range [-1.0; 1.0].

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559):

+

Example

#include <errno.h>
+#include <fenv.h>
+#include <math.h>
+#include <stdio.h>
+#include <string.h>
+ 
+#ifndef __GNUC__
+#pragma STDC FENV_ACCESS ON
+#endif
+ 
+int main(void)
+{
+    printf("acos(-1) = %f\n", acos(-1));
+    printf("acos(0.0) = %f 2*acos(0.0) = %f\n", acos(0), 2 * acos(0));
+    printf("acos(0.5) = %f 3*acos(0.5) = %f\n", acos(0.5), 3 * acos(0.5));
+    printf("acos(1) = %f\n", acos(1));
+ 
+    // error handling
+    errno = 0; feclearexcept(FE_ALL_EXCEPT);
+    printf("acos(1.1) = %f\n", acos(1.1));
+    if (errno == EDOM)
+        perror("    errno == EDOM");
+    if (fetestexcept(FE_INVALID))
+        puts("    FE_INVALID raised");
+}

Possible output:

+
acos(-1) = 3.141593
+acos(0.0) = 1.570796 2*acos(0.0) = 3.141593
+acos(0.5) = 1.047198 3*acos(0.5) = 3.141593
+acos(1) = 0.000000
+acos(1.1) = nan
+    errno == EDOM: Numerical argument out of domain
+    FE_INVALID raised

References

See also

+ + + + + +
+
(C99)(C99)
 computes arc sine (\({\small\arcsin{x} }\)arcsin(x))
(function)
+
(C99)(C99)
 computes arc tangent (\({\small\arctan{x} }\)arctan(x))
(function)
+
(C99)(C99)
 computes arc tangent, using signs to determine quadrants
(function)
+
(C99)(C99)
 computes cosine (\({\small\cos{x} }\)cos(x))
(function)
+
(C99)(C99)(C99)
 computes the complex arc cosine
(function)
C++ documentation for acos
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/acos +

+
diff --git a/devdocs/c/numeric%2Fmath%2Facosh.html b/devdocs/c/numeric%2Fmath%2Facosh.html new file mode 100644 index 00000000..2288743c --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Facosh.html @@ -0,0 +1,87 @@ +

acosh, acoshf, acoshl

Defined in header <math.h> 
float       acoshf( float arg );
+		 (1) (since C99) 
double      acosh( double arg );
+		 (2) (since C99) 
long double acoshl( long double arg );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define acosh( arg )
+		 (4) (since C99)
+1-3) Computes the inverse hyperbolic cosine of arg.
+4) Type-generic macro: If the argument has type long double, acoshl is called. Otherwise, if the argument has integer type or the type double, acosh is called. Otherwise, acoshf is called. If the argument is complex, then the macro invokes the corresponding complex function (cacoshf, cacosh, cacoshl).

Parameters

+ +
arg - floating point value representing the area of a hyperbolic sector

Return value

If no errors occur, the inverse hyperbolic cosine of arg (cosh-1(arg), or arcosh(arg)) on the interval [0, +∞], is returned.

+

If a domain error occurs, an implementation-defined value is returned (NaN where supported).

+

Error handling

Errors are reported as specified in math_errhandling.

+

If the argument is less than 1, a domain error occurs.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

Although the C standard names this function "arc hyperbolic cosine", the inverse functions of the hyperbolic functions are the area functions. Their argument is the area of a hyperbolic sector, not an arc. The correct name is "inverse hyperbolic cosine" (used by POSIX) or "area hyperbolic cosine".

+

Example

#include <stdio.h>
+#include <math.h>
+#include <float.h>
+#include <errno.h>
+#include <fenv.h>
+#pragma STDC FENV_ACCESS ON
+ 
+int main(void)
+{
+    printf("acosh(1) = %f\nacosh(10) = %f\n", acosh(1), acosh(10));
+    printf("acosh(DBL_MAX) = %f\nacosh(Inf) = %f\n", acosh(DBL_MAX), acosh(INFINITY));
+    // error handling
+    errno = 0; feclearexcept(FE_ALL_EXCEPT);
+    printf("acosh(0.5) = %f\n", acosh(0.5));
+    if (errno == EDOM)
+        perror("    errno == EDOM");
+    if (fetestexcept(FE_INVALID))
+        puts("    FE_INVALID raised");
+}

Possible output:

+
acosh(1) = 0.000000
+acosh(10) = 2.993223
+acosh(DBL_MAX) = 710.475860
+acosh(Inf) = inf
+acosh(0.5) = -nan
+    errno == EDOM: Numerical argument out of domain
+    FE_INVALID raised

References

See also

+ + + + +
+
(C99)(C99)(C99)
 computes inverse hyperbolic sine (\({\small\operatorname{arsinh}{x} }\)arsinh(x))
(function)
+
(C99)(C99)(C99)
 computes inverse hyperbolic tangent (\({\small\operatorname{artanh}{x} }\)artanh(x))
(function)
+
(C99)(C99)
 computes hyperbolic cosine (\({\small\cosh{x} }\)cosh(x))
(function)
+
(C99)(C99)(C99)
 computes the complex arc hyperbolic cosine
(function)
C++ documentation for acosh
+ +
+Weisstein, Eric W. "Inverse Hyperbolic Cosine." From MathWorld — A Wolfram Web Resource.
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/acosh +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fasin.html b/devdocs/c/numeric%2Fmath%2Fasin.html new file mode 100644 index 00000000..bef4c96d --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fasin.html @@ -0,0 +1,98 @@ +

asin, asinf, asinl

Defined in header <math.h> 
float       asinf( float arg );
+		 (1) (since C99) 
double      asin( double arg );
+		 (2) 
long double asinl( long double arg );
+		 (3) (since C99) 
_Decimal32  asind32( _Decimal32 arg );
+		 (4) (since C23) 
_Decimal64  asind64( _Decimal64 arg );
+		 (5) (since C23) 
_Decimal128 asind128( _Decimal128 arg );
+		 (6) (since C23)
Defined in header <tgmath.h> 
#define asin( arg )
+		 (7) (since C99)
+1-6) Computes the principal values of the arc sine of arg.
+7) Type-generic macro: If the argument has type long double, (3) (asinl) is called. Otherwise, if the argument has integer type or the type double, (2) (asin) is called. Otherwise, (1) (asinf) is called. If the argument is complex, then the macro invokes the corresponding complex function (casinf, casin, casinl).
+ +

The functions (4-6) are declared if and only if the implementation predefines __STDC_IEC_60559_DFP__ (i.e. the implementation supports decimal floating-point numbers).

+		 (since C23)

Parameters

+ +
arg - floating-point value

Return value

If no errors occur, the arc sine of arg (arcsin(arg)) in the range [-π/2 ; +π/2], is returned.

If a domain error occurs, an implementation-defined value is returned (NaN where supported).

+

If a range error occurs due to underflow, the correct result (after rounding) is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

Domain error occurs if arg is outside the range [-1.0; 1.0].

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559):

+

Example

#include <errno.h>
+#include <fenv.h>
+#include <math.h>
+#include <stdio.h>
+#include <string.h>
+ 
+#ifndef __GNUC__
+#pragma STDC FENV_ACCESS ON
+#endif
+ 
+int main(void)
+{
+    printf("asin( 1.0) = %+f, 2*asin( 1.0)=%+f\n", asin(1), 2 * asin(1));
+    printf("asin(-0.5) = %+f, 6*asin(-0.5)=%+f\n", asin(-0.5), 6 * asin(-0.5));
+ 
+    // special values
+    printf("asin(0.0) = %1f, asin(-0.0)=%f\n", asin(+0.0), asin(-0.0));
+ 
+    // error handling
+    errno = 0; feclearexcept(FE_ALL_EXCEPT);
+    printf("asin(1.1) = %f\n", asin(1.1));
+    if (errno == EDOM)
+        perror("    errno == EDOM");
+    if (fetestexcept(FE_INVALID))
+        puts("    FE_INVALID raised");
+}

Possible output:

+
asin( 1.0) = +1.570796, 2*asin( 1.0)=+3.141593
+asin(-0.5) = -0.523599, 6*asin(-0.5)=-3.141593
+asin(0.0) = 0.000000, asin(-0.0)=-0.000000
+asin(1.1) = nan
+    errno == EDOM: Numerical argument out of domain
+    FE_INVALID raised

References

See also

+ + + + + +
+
(C99)(C99)
 computes arc cosine (\({\small\arccos{x} }\)arccos(x))
(function)
+
(C99)(C99)
 computes arc tangent (\({\small\arctan{x} }\)arctan(x))
(function)
+
(C99)(C99)
 computes arc tangent, using signs to determine quadrants
(function)
+
(C99)(C99)
 computes sine (\({\small\sin{x} }\)sin(x))
(function)
+
(C99)(C99)(C99)
 computes the complex arc sine
(function)
C++ documentation for asin
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/asin +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fasinh.html b/devdocs/c/numeric%2Fmath%2Fasinh.html new file mode 100644 index 00000000..9944cbc7 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fasinh.html @@ -0,0 +1,59 @@ +

asinh, asinhf, asinhl

Defined in header <math.h> 
float       asinhf( float arg );
+		 (1) (since C99) 
double      asinh( double arg );
+		 (2) (since C99) 
long double asinhl( long double arg );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define asinh( arg )
+		 (4) (since C99)
+1-3) Computes the inverse hyperbolic sine of arg.
+4) Type-generic macro: If the argument has type long double, asinhl is called. Otherwise, if the argument has integer type or the type double, asinh is called. Otherwise, asinhf is called. If the argument is complex, then the macro invokes the corresponding complex function (casinhf, casinh, casinhl).

Parameters

+ +
arg - floating point value representing the area of a hyperbolic sector

Return value

If no errors occur, the inverse hyperbolic sine of arg (sinh-1(arg), or arsinh(arg)), is returned.

+

If a range error occurs due to underflow, the correct result (after rounding) is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

Although the C standard names this function "arc hyperbolic sine", the inverse functions of the hyperbolic functions are the area functions. Their argument is the area of a hyperbolic sector, not an arc. The correct name is "inverse hyperbolic sine" (used by POSIX) or "area hyperbolic sine".

+

Example

#include <stdio.h>
+#include <math.h>
+ 
+int main(void)
+{
+    printf("asinh(1) = %f\nasinh(-1) = %f\n", asinh(1), asinh(-1));
+    // special values
+    printf("asinh(+0) = %f\nasinh(-0) = %f\n", asinh(0.0), asinh(-0.0));
+}

Output:

+
asinh(1) = 0.881374
+asinh(-1) = -0.881374
+asinh(+0) = 0.000000
+asinh(-0) = -0.000000

References

See also

+ + + + +
+
(C99)(C99)(C99)
 computes inverse hyperbolic cosine (\({\small\operatorname{arcosh}{x} }\)arcosh(x))
(function)
+
(C99)(C99)(C99)
 computes inverse hyperbolic tangent (\({\small\operatorname{artanh}{x} }\)artanh(x))
(function)
+
(C99)(C99)
 computes hyperbolic sine (\({\small\sinh{x} }\)sinh(x))
(function)
+
(C99)(C99)(C99)
 computes the complex arc hyperbolic sine
(function)
C++ documentation for asinh
+ +
+Weisstein, Eric W. "Inverse Hyperbolic Sine." From MathWorld — A Wolfram Web Resource.
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/asinh +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fatan.html b/devdocs/c/numeric%2Fmath%2Fatan.html new file mode 100644 index 00000000..4ba682e3 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fatan.html @@ -0,0 +1,79 @@ +

atan, atanf, atanl

Defined in header <math.h> 
float       atanf( float arg );
+		 (1) (since C99) 
double      atan( double arg );
+		 (2) 
long double atanl( long double arg );
+		 (3) (since C99) 
_Decimal32  atand32( _Decimal32 arg );
+		 (4) (since C23) 
_Decimal64  atand64( _Decimal64 arg );
+		 (5) (since C23) 
_Decimal128 atand128( _Decimal128 arg );
+		 (6) (since C23)
Defined in header <tgmath.h> 
#define atan( arg )
+		 (7) (since C99)
+1-6) Computes the principal value of the arc tangent of arg.
+7) Type-generic macro: If the argument has type long double, (3) (atanl) is called. Otherwise, if the argument has integer type or the type double, (2) (atan) is called. Otherwise, (1) (atanf) is called. If the argument is complex, then the macro invokes the corresponding complex function (catanf, catan, catanl).
+ +

The functions (4-6) are declared if and only if the implementation predefines __STDC_IEC_60559_DFP__ (i.e. the implementation supports decimal floating-point numbers).

+		 (since C23)

Parameters

+ +
arg - floating point value

Return value

If no errors occur, the arc tangent of arg (arctan(arg)) in the range [- π/2 ; +π/2] radians, is returned.

If a range error occurs due to underflow, the correct result (after rounding) is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559):

+

Notes

POSIX specifies that in case of underflow, arg is returned unmodified, and if that is not supported, an implementation-defined value no greater than DBL_MIN, FLT_MIN, and LDBL_MIN is returned.

+

Example

#include <math.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    printf("atan(1) = %f, 4*atan(1)=%f\n", atan(1), 4 * atan(1));
+    // special values
+    printf("atan(Inf) = %f, 2*atan(Inf) = %f\n", atan(INFINITY), 2 * atan(INFINITY));
+    printf("atan(-0.0) = %+f, atan(+0.0) = %+f\n", atan(-0.0), atan(0));
+}

Output:

+
atan(1) = 0.785398, 4*atan(1)=3.141593
+atan(Inf) = 1.570796, 2*atan(Inf) = 3.141593
+atan(-0.0) = -0.000000, atan(+0.0) = +0.000000

References

See also

+ + + + + +
+
(C99)(C99)
 computes arc tangent, using signs to determine quadrants
(function)
+
(C99)(C99)
 computes arc sine (\({\small\arcsin{x} }\)arcsin(x))
(function)
+
(C99)(C99)
 computes arc cosine (\({\small\arccos{x} }\)arccos(x))
(function)
+
(C99)(C99)
 computes tangent (\({\small\tan{x} }\)tan(x))
(function)
+
(C99)(C99)(C99)
 computes the complex arc tangent
(function)
C++ documentation for atan
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/atan +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fatan2.html b/devdocs/c/numeric%2Fmath%2Fatan2.html new file mode 100644 index 00000000..94dcdd22 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fatan2.html @@ -0,0 +1,103 @@ +

atan2, atan2f, atan2l

Defined in header <math.h> 
float       atan2f( float y, float x );
+		 (1) (since C99) 
double      atan2( double y, double x );
+		 (2) 
long double atan2l( long double y, long double x );
+		 (3) (since C99) 
_Decimal32  atan2d32( _Decimal32 y, _Decimal32 x );
+		 (4) (since C23) 
_Decimal64  atan2d64( _Decimal64 y, _Decimal64 x );
+		 (5) (since C23) 
_Decimal128 atan2d128( _Decimal128 y, _Decimal128 x );
+		 (6) (since C23)
Defined in header <tgmath.h> 
#define atan2( y, x )
+		 (7) (since C99)
+1-6) Computes the arc tangent of y / x using the signs of arguments to determine the correct quadrant.
+7) Type-generic macro: If any argument has type long double, (3) (atan2l) is called. Otherwise, if any argument has integer type or has type double, (2) (atan2) is called. Otherwise, (1) (atan2f) is called.
+ +

The functions (4-6) are declared if and only if the implementation predefines __STDC_IEC_60559_DFP__ (i.e. the implementation supports decimal floating-point numbers).

+		 (since C23)

Parameters

+ +
x, y - floating-point value

Return value

If no errors occur, the arc tangent of y / x (arctan(y/x)) in the range [-π ; +π] radians, is returned.
Y argument
Return value
math-atan2.png
X argument

If a domain error occurs, an implementation-defined value is returned.

+

If a range error occurs due to underflow, the correct result (after rounding) is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

Domain error may occur if x and y are both zero.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559):

+

Notes

atan2(y, x) is equivalent to carg(x + I*y).

+

POSIX specifies that in case of underflow, y / x is the value returned, and if that is not supported, an implementation-defined value no greater than DBL_MIN, FLT_MIN, and LDBL_MIN is returned.

+

Example

#include <math.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    // normal usage: the signs of the two arguments determine the quadrant
+    // atan2(1,1) = +pi/4, Quad I
+    printf("(+1,+1) cartesian is (%f,%f) polar\n", hypot( 1, 1), atan2( 1, 1));
+    // atan2(1, -1) = +3pi/4, Quad II
+    printf("(+1,-1) cartesian is (%f,%f) polar\n", hypot( 1,-1), atan2( 1,-1));
+    // atan2(-1,-1) = -3pi/4, Quad III
+    printf("(-1,-1) cartesian is (%f,%f) polar\n", hypot(-1,-1), atan2(-1,-1));
+    // atan2(-1,-1) = -pi/4, Quad IV
+    printf("(-1,+1) cartesian is (%f,%f) polar\n", hypot(-1, 1), atan2(-1, 1));
+ 
+    // special values
+    printf("atan2(0, 0) = %f atan2(0, -0)=%f\n", atan2(0,0), atan2(0,-0.0));
+    printf("atan2(7, 0) = %f atan2(7, -0)=%f\n", atan2(7,0), atan2(7,-0.0));
+}

Output:

+
(+1,+1) cartesian is (1.414214,0.785398) polar
+(+1,-1) cartesian is (1.414214,2.356194) polar
+(-1,-1) cartesian is (1.414214,-2.356194) polar
+(-1,+1) cartesian is (1.414214,-0.785398) polar
+atan2(0, 0) = 0.000000 atan2(0, -0)=3.141593
+atan2(7, 0) = 1.570796 atan2(7, -0)=1.570796

References

See also

+ + + + +
+
(C99)(C99)
 computes arc sine (\({\small\arcsin{x} }\)arcsin(x))
(function)
+
(C99)(C99)
 computes arc cosine (\({\small\arccos{x} }\)arccos(x))
(function)
+
(C99)(C99)
 computes arc tangent (\({\small\arctan{x} }\)arctan(x))
(function)
+
(C99)(C99)(C99)
 computes the phase angle of a complex number
(function)
C++ documentation for atan2
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/atan2 +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fatanh.html b/devdocs/c/numeric%2Fmath%2Fatanh.html new file mode 100644 index 00000000..68ec0eb7 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fatanh.html @@ -0,0 +1,84 @@ +

atanh, atanhf, atanhl

Defined in header <math.h> 
float       atanhf( float arg );
+		 (1) (since C99) 
double      atanh( double arg );
+		 (2) (since C99) 
long double atanhl( long double arg );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define atanh( arg )
+		 (4) (since C99)
+1-3) Computes the inverse hyperbolic tangent of arg.
+4) Type-generic macro: If the argument has type long double, atanhl is called. Otherwise, if the argument has integer type or the type double, atanh is called. Otherwise, atanhf is called. If the argument is complex, then the macro invokes the corresponding complex function (catanhf, catanh, catanhl).

Parameters

+ +
arg - floating point value representing the area of a hyperbolic sector

Return value

If no errors occur, the inverse hyperbolic tangent of arg (tanh-1(arg), or artanh(arg)), is returned.

+

If a domain error occurs, an implementation-defined value is returned (NaN where supported).

+

If a pole error occurs, ±HUGE_VAL, ±HUGE_VALF, or ±HUGE_VALL is returned (with the correct sign).

+

If a range error occurs due to underflow, the correct result (after rounding) is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

If the argument is not on the interval [-1, +1], a range error occurs.

+

If the argument is ±1, a pole error occurs.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

Although the C standard names this function "arc hyperbolic tangent", the inverse functions of the hyperbolic functions are the area functions. Their argument is the area of a hyperbolic sector, not an arc. The correct name is "inverse hyperbolic tangent" (used by POSIX) or "area hyperbolic tangent".

+

POSIX specifies that in case of underflow, arg is returned unmodified, and if that is not supported, an implementation-defined value no greater than DBL_MIN, FLT_MIN, and LDBL_MIN is returned.

+

Example

#include <stdio.h>
+#include <math.h>
+#include <float.h>
+#include <errno.h>
+#include <fenv.h>
+// #pragma STDC FENV_ACCESS ON
+ 
+int main(void)
+{
+    printf("atanh(0) = %f\natanh(-0) = %f\n", atanh(0), atanh(-0.0));
+    printf("atanh(0.9) = %f\n", atanh(0.9));
+    //error handling
+    errno = 0; feclearexcept(FE_ALL_EXCEPT);
+    printf("atanh(-1) = %f\n", atanh(-1));
+    if (errno == ERANGE)
+        perror("    errno == ERANGE");
+    if (fetestexcept(FE_DIVBYZERO))
+        puts("    FE_DIVBYZERO raised");
+}

Possible output:

+
atanh(0) = 0.000000
+atanh(-0) = -0.000000
+atanh(0.9) = 1.472219
+atanh(-1) = -inf
+    errno == ERANGE: Numerical result out of range
+    FE_DIVBYZERO raised

References

See also

+ + + + +
+
(C99)(C99)(C99)
 computes inverse hyperbolic sine (\({\small\operatorname{arsinh}{x} }\)arsinh(x))
(function)
+
(C99)(C99)(C99)
 computes inverse hyperbolic cosine (\({\small\operatorname{arcosh}{x} }\)arcosh(x))
(function)
+
(C99)(C99)
 computes hyperbolic tangent (\({\small\tanh{x} }\)tanh(x))
(function)
+
(C99)(C99)(C99)
 computes the complex arc hyperbolic tangent
(function)
C++ documentation for atanh
+ +
+Weisstein, Eric W. "Inverse Hyperbolic Tangent." From MathWorld — A Wolfram Web Resource.
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/atanh +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fcbrt.html b/devdocs/c/numeric%2Fmath%2Fcbrt.html new file mode 100644 index 00000000..bb548272 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fcbrt.html @@ -0,0 +1,71 @@ +

cbrt, cbrtf, cbrtl

Defined in header <math.h> 
float       cbrtf( float arg );
+		 (1) (since C99) 
double      cbrt( double arg );
+		 (2) (since C99) 
long double cbrtl( long double arg );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define cbrt( arg )
+		 (4) (since C99)
+1-3) Computes the cube root of arg.
+4) Type-generic macro: If arg has type long double, cbrtl is called. Otherwise, if arg has integer type or the type double, cbrt is called. Otherwise, cbrtf is called.

Parameters

+ +
arg - floating point value

Return value

If no errors occur, the cube root of arg (\(\small{\sqrt[3]{arg} }\)3√arg), is returned.

+

If a range error occurs due to underflow, the correct result (after rounding) is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

cbrt(arg) is not equivalent to pow(arg, 1.0/3) because the rational number \(\small{\frac1{3} }\)1/3 is typically not equal to 1.0/3 and std::pow cannot raise a negative base to a fractional exponent. Moreover, cbrt(arg) usually gives more accurate results than pow(arg, 1.0/3) (see example).

Example

#include <stdio.h>
+#include <float.h>
+#include <math.h>
+ 
+int main(void)
+{
+    printf("Normal use:\n"
+           "cbrt(729)      = %f\n", cbrt(729));
+    printf("cbrt(-0.125)   = %f\n", cbrt(-0.125));
+    printf("Special values:\n"
+           "cbrt(-0)       = %f\n", cbrt(-0.0));
+    printf("cbrt(+inf)     = %f\n", cbrt(INFINITY));
+    printf("Accuracy:\n"
+           "cbrt(343)      = %.*f\n", DBL_DECIMAL_DIG, cbrt(343));
+    printf("pow(343,1.0/3) = %.*f\n", DBL_DECIMAL_DIG, pow(343, 1.0/3));
+}

Possible output:

+
Normal use:
+cbrt(729)      = 9.000000
+cbrt(-0.125)   = -0.500000
+Special values:
+cbrt(-0)       = -0.000000
+cbrt(+inf)     = inf
+Accuracy:
+cbrt(343)      = 7.00000000000000000
+pow(343,1.0/3) = 6.99999999999999911

References

See also

+ + + +
+
(C99)(C99)
 computes a number raised to the given power (\(\small{x^y}\)xy)
(function)
+
(C99)(C99)
 computes square root (\(\small{\sqrt{x} }\)√x)
(function)
+
(C99)(C99)(C99)
 computes square root of the sum of the squares of two given numbers (\(\scriptsize{\sqrt{x^2+y^2} }\)√x2+y2)
(function)
C++ documentation for cbrt
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/cbrt +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fceil.html b/devdocs/c/numeric%2Fmath%2Fceil.html new file mode 100644 index 00000000..76c99e95 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fceil.html @@ -0,0 +1,74 @@ +

ceil, ceilf, ceill

Defined in header <math.h> 
float       ceilf( float arg );
+		 (1) (since C99) 
double      ceil( double arg );
+		 (2) 
long double ceill( long double arg );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define ceil( arg )
+		 (4) (since C99)
+1-3) Computes the smallest integer value not less than arg.
+4) Type-generic macro: If arg has type long double, ceill is called. Otherwise, if arg has integer type or the type double, ceil is called. Otherwise, ceilf is called.

Parameters

+ +
arg - floating point value

Return value

If no errors occur, the smallest integer value not less than arg, that is ⌈arg⌉, is returned.

+
Return value
math-ceil.svg
Argument

Error handling

Errors are reported as specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

FE_INEXACT may be (but isn't required to be) raised when rounding a non-integer finite value.

+

The largest representable floating-point values are exact integers in all standard floating-point formats, so this function never overflows on its own; however the result may overflow any integer type (including intmax_t), when stored in an integer variable.

+

This function (for double argument) behaves as if (except for the freedom to not raise FE_INEXACT) implemented by

+
#include <math.h>
+#include <fenv.h>
+#pragma STDC FENV_ACCESS ON
+double ceil(double x)
+{
+    double result;
+    int save_round = fegetround();
+    fesetround(FE_UPWARD);
+    result = rint(x); // or nearbyint 
+    fesetround(save_round);
+    return result;
+}

Example

#include <math.h>
+#include <stdio.h>
+int main(void)
+{
+    printf("ceil(+2.4) = %+.1f\n", ceil(2.4));
+    printf("ceil(-2.4) = %+.1f\n", ceil(-2.4));
+    printf("ceil(-0.0) = %+.1f\n", ceil(-0.0));
+    printf("ceil(-Inf) = %+f\n",   ceil(-INFINITY));
+}

Possible output:

+
ceil(+2.4) = +3.0
+ceil(-2.4) = -2.0
+ceil(-0.0) = -0.0
+ceil(-Inf) = -inf

References

See also

+ + + + + +
+
(C99)(C99)
 computes largest integer not greater than the given value
(function)
+
(C99)(C99)(C99)
 rounds to nearest integer not greater in magnitude than the given value
(function)
+
(C99)(C99)(C99)(C99)(C99)(C99)(C99)(C99)(C99)
 rounds to nearest integer, rounding away from zero in halfway cases
(function)
+
(C99)(C99)(C99)
 rounds to an integer using current rounding mode
(function)
+
(C99)(C99)(C99)(C99)(C99)(C99)(C99)(C99)(C99)
 rounds to an integer using current rounding mode with
exception if the result differs
(function)
C++ documentation for ceil
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/ceil +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fcopysign.html b/devdocs/c/numeric%2Fmath%2Fcopysign.html new file mode 100644 index 00000000..3e67f811 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fcopysign.html @@ -0,0 +1,51 @@ +

copysign, copysignf, copysignl

Defined in header <math.h> 
float       copysignf( float x, float y );
+		 (1) (since C99) 
double      copysign( double x, double y );
+		 (2) (since C99) 
long double copysignl( long double x, long double y );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define copysign(x, y)
+		 (4) (since C99)
+1-3) Composes a floating point value with the magnitude of x and the sign of y.
+4) Type-generic macro: If any argument has type long double, copysignl is called. Otherwise, if any argument has integer type or has type double, copysign is called. Otherwise, copysignf is called.

Parameters

+ +
x, y - floating point values

Return value

If no errors occur, the floating point value with the magnitude of x and the sign of y is returned.

+

If x is NaN, then NaN with the sign of y is returned.

+

If y is -0, the result is only negative if the implementation supports the signed zero consistently in arithmetic operations.

+

Error handling

This function is not subject to any errors specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

copysign is the only portable way to manipulate the sign of a NaN value (to examine the sign of a NaN, signbit may also be used).

+

Example

#include <stdio.h>
+#include <math.h>
+ 
+int main(void)
+{
+    printf("copysign(1.0,+2.0)      = %+.1f\n", copysign(1.0,+2.0));
+    printf("copysign(1.0,-2.0)      = %+.1f\n", copysign(1.0,-2.0));
+    printf("copysign(INFINITY,-2.0) = %f\n",    copysign(INFINITY,-2.0));
+    printf("copysign(NAN,-2.0)      = %f\n",    copysign(NAN,-2.0));
+}

Possible output:

+
copysign(1.0,+2.0)      = +1.0
+copysign(1.0,-2.0)      = -1.0
+copysign(INFINITY,-2.0) = -inf
+copysign(NAN,-2.0)      = -nan

References

See also

+ + +
+
(C99)(C99)
 computes absolute value of a floating-point value (\(\small{|x|}\)|x|)
(function)
+
(C99)
 checks if the given number is negative
(function macro)
C++ documentation for copysign
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/copysign +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fcos.html b/devdocs/c/numeric%2Fmath%2Fcos.html new file mode 100644 index 00000000..7dea37f1 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fcos.html @@ -0,0 +1,103 @@ +

cos, cosf, cosl

Defined in header <math.h> 
float       cosf( float arg );
+		 (1) (since C99) 
double      cos( double arg );
+		 (2) 
long double cosl( long double arg );
+		 (3) (since C99) 
_Decimal32  cosd32( _Decimal32 arg );
+		 (4) (since C23) 
_Decimal64  cosd64( _Decimal64 arg );
+		 (5) (since C23) 
_Decimal128 cosd128( _Decimal128 arg );
+		 (6) (since C23)
Defined in header <tgmath.h> 
#define cos( arg )
+		 (7) (since C99)
+1-6) Computes the cosine of arg (measured in radians).
+7) Type-generic macro: If the argument has type long double, (3) (cosl) is called. Otherwise, if the argument has integer type or the type double, (2) (cos) is called. Otherwise, (1) (cosf) is called. If the argument is complex, then the macro invokes the corresponding complex function (ccosf, ccos, ccosl).
+ +

The functions (4-6) are declared if and only if the implementation predefines __STDC_IEC_60559_DFP__ (i.e. the implementation supports decimal floating-point numbers).

+		 (since C23)

Parameters

+ +
arg - floating-point value representing angle in radians

Return value

If no errors occur, the cosine of arg (cos(arg)) in the range [-1 ; +1], is returned.

+ + +

The result may have little or no significance if the magnitude of arg is large.

+		 (until C99)

If a domain error occurs, an implementation-defined value is returned (NaN where supported).

+

If a range error occurs due to underflow, the correct result (after rounding) is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559):

+

Notes

The case where the argument is infinite is not specified to be a domain error in C, but it is defined as a domain error in POSIX.

+

Example

#include <errno.h>
+#include <fenv.h>
+#include <math.h>
+#include <stdio.h>
+ 
+#ifndef __GNUC__
+#pragma STDC FENV_ACCESS ON
+#endif
+ 
+int main(void)
+{
+    const double pi = acos(-1);
+ 
+    // typical usage
+    printf("cos(pi/3) = %f\n", cos(pi / 3));
+    printf("cos(pi/2) = %f\n", cos(pi / 2));
+    printf("cos(-3*pi/4) = %f\n", cos(-3 * pi / 4));
+ 
+    // special values
+    printf("cos(+0) = %f\n", cos(0.0));
+    printf("cos(-0) = %f\n", cos(-0.0));
+ 
+    // error handling
+    feclearexcept(FE_ALL_EXCEPT);
+    printf("cos(INFINITY) = %f\n", cos(INFINITY));
+    if (fetestexcept(FE_INVALID))
+        puts("    FE_INVALID raised");
+}

Possible output:

+
cos(pi/3) = 0.500000
+cos(pi/2) = 0.000000
+cos(-3*pi/4) = -0.707107
+cos(+0) = 1.000000
+cos(-0) = 1.000000
+cos(INFINITY) = -nan
+    FE_INVALID raised

References

See also

+ + + + +
+
(C99)(C99)
 computes sine (\({\small\sin{x} }\)sin(x))
(function)
+
(C99)(C99)
 computes tangent (\({\small\tan{x} }\)tan(x))
(function)
+
(C99)(C99)
 computes arc cosine (\({\small\arccos{x} }\)arccos(x))
(function)
+
(C99)(C99)(C99)
 computes the complex cosine
(function)
C++ documentation for cos
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/cos +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fcosh.html b/devdocs/c/numeric%2Fmath%2Fcosh.html new file mode 100644 index 00000000..493b5d19 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fcosh.html @@ -0,0 +1,77 @@ +

cosh, coshf, coshl

Defined in header <math.h> 
float       coshf( float arg );
+		 (1) (since C99) 
double      cosh( double arg );
+		 (2) 
long double coshl( long double arg );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define cosh( arg )
+		 (4) (since C99)
+1-3) Computes the hyperbolic cosine of arg.
+4) Type-generic macro: If the argument has type long double, coshl is called. Otherwise, if the argument has integer type or the type double, cosh is called. Otherwise, coshf is called. If the argument is complex, then the macro invokes the corresponding complex function (ccoshf, ccosh, ccoshl).

Parameters

+ +
arg - floating point value representing a hyperbolic angle

Return value

If no errors occur, the hyperbolic cosine of arg (cosh(arg), or earg+e-arg/2) is returned.

If a range error due to overflow occurs, +HUGE_VAL, +HUGE_VALF, or +HUGE_VALL is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

For the IEEE-compatible type double, if |arg| > 710.5, then cosh(arg) overflows.

+

Example

#include <stdio.h>
+#include <math.h>
+#include <errno.h>
+#include <fenv.h>
+ 
+// #pragma STDC FENV_ACCESS ON
+int main(void)
+{
+    printf("cosh(1) = %f\ncosh(-1)= %f\n", cosh(1), cosh(-1));
+    printf("log(sinh(1) + cosh(1))=%f\n", log(sinh(1)+cosh(1)));
+    // special values
+    printf("cosh(+0) = %f\ncosh(-0) = %f\n", cosh(0.0), cosh(-0.0));
+    // error handling 
+    errno=0; feclearexcept(FE_ALL_EXCEPT);
+    printf("cosh(710.5) = %f\n", cosh(710.5));
+    if(errno == ERANGE) perror("    errno == ERANGE");
+    if(fetestexcept(FE_OVERFLOW)) puts("    FE_OVERFLOW raised");
+}

Possible output:

+
cosh(1) = 1.543081
+cosh(-1)= 1.543081
+log(sinh(1) + cosh(1))=1.000000
+cosh(+0) = 1.000000
+cosh(-0) = 1.000000
+cosh(710.5) = inf
+    errno == ERANGE: Numerical result out of range
+    FE_OVERFLOW raised

References

See also

+ + + + +
+
(C99)(C99)
 computes hyperbolic sine (\({\small\sinh{x} }\)sinh(x))
(function)
+
(C99)(C99)
 computes hyperbolic tangent (\({\small\tanh{x} }\)tanh(x))
(function)
+
(C99)(C99)(C99)
 computes inverse hyperbolic cosine (\({\small\operatorname{arcosh}{x} }\)arcosh(x))
(function)
+
(C99)(C99)(C99)
 computes the complex hyperbolic cosine
(function)
C++ documentation for cosh
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/cosh +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fcospi.html b/devdocs/c/numeric%2Fmath%2Fcospi.html new file mode 100644 index 00000000..f260c5fb --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fcospi.html @@ -0,0 +1,77 @@ +

cospi, cospif, cospil, cospid32, cospid64, cospid128

Defined in header <math.h> 
float       cospif( float arg );
+		 (1) (since C23) 
double      cospi( double arg );
+		 (2) (since C23) 
long double cospil( long double arg );
+		 (3) (since C23) 
_Decimal32  cospid32( _Decimal32 arg );
+		 (4) (since C23) 
_Decimal64  cospid64( _Decimal64 arg );
+		 (5) (since C23) 
_Decimal128 cospid128( _Decimal128 arg );
+		 (6) (since C23)
Defined in header <tgmath.h> 
#define cospi( arg )
+		 (7) (since C23)
+1-6) Computes the cosine of π·arg measured in radians, thus regarding arg as a measurement in half-revolutions.
+7) Type-generic macro: calls the correct function based on the type of arg. If the argument has integer type, (2) (cospi) is called.
+ +

The functions (4-6) are declared if and only if the implementation predefines __STDC_IEC_60559_DFP__ (i.e. the implementation supports decimal floating-point numbers).

+		 (since C23)

Parameters

+ +
arg - floating-point value whose product with π represents an angle in radians

Return value

If no errors occur, the cosine of π·arg (cos(π×arg)) in the range [-1, +1], is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559):

+

Example

#include <errno.h>
+#include <fenv.h>
+#include <math.h>
+#include <stdio.h>
+ 
+#ifndef __GNUC__
+#pragma STDC FENV_ACCESS ON
+#endif
+ 
+#if __STDC_VERSION__ < 202311L
+// A naive implementation of a subset of cospi family
+double cospi(double arg)
+{
+    return cos(arg * (double)3.1415926535897932384626433);
+}
+#endif
+ 
+int main(void)
+{
+    const double pi = acos(-1);
+ 
+    // typical usage
+    printf("cospi(1) = %f, cos(pi) = %f\n", cospi(1), cos(pi));
+    printf("cospi(0.5) = %f, cos(pi/2) = %f\n", cospi(0.5), cos(pi / 2));
+    printf("cospi(-0.75) = %f, cos(-3*pi/4) = %f\n", cospi(-0.75), cos(-3 * pi / 4));
+ 
+    // special values
+    printf("cospi(+0) = %f\n", cospi(0.0));
+    printf("cospi(-0) = %f\n", cospi(-0.0));
+ 
+    // error handling
+    feclearexcept(FE_ALL_EXCEPT);
+    printf("cospi(INFINITY) = %f\n", cospi(INFINITY));
+    if (fetestexcept(FE_INVALID))
+        puts("    FE_INVALID raised");
+}

Possible output:

+
cospi(1) = -1.000000, cos(pi) = -1.000000
+cospi(0.5) = 0.000000, cos(pi/2) = 0.000000
+cospi(-0.75) = -0.707107, cos(-3*pi/4) = -0.707107
+cospi(+0) = 1.000000
+cospi(-0) = 1.000000
+cospi(INFINITY) = -nan
+    FE_INVALID raised

References

See also

+
+
(C99)(C99)
 computes cosine (\({\small\cos{x} }\)cos(x))
(function)
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/cospi +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fdiv.html b/devdocs/c/numeric%2Fmath%2Fdiv.html new file mode 100644 index 00000000..529a3c32 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fdiv.html @@ -0,0 +1,120 @@ +

div, ldiv, lldiv, imaxdiv

Defined in header <stdlib.h> 
div_t     div( int x, int y );
+		 (1) 
ldiv_t    ldiv( long x, long y );
+		 (2) 
lldiv_t   lldiv( long long x, long long y );
+		 (3) (since C99)
Defined in header <inttypes.h> 
imaxdiv_t imaxdiv( intmax_t x, intmax_t y );
+		 (4) (since C99)

Computes both the quotient and the remainder of the division of the numerator x by the denominator y.

+ + + + +

Computes quotient and remainder simultaneously. The quotient is the algebraic quotient with any fractional part discarded (truncated towards zero). The remainder is such that quot * y + rem == x.

+		 (until C99)

Computes the quotient (the result of the expression x / y) and remainder (the result of the expression x % y) simultaneously.

+		 (since C99)

Parameters

+ +
x, y - integer values

Return value

If both the remainder and the quotient can be represented as objects of the corresponding type (int, long, long long, intmax_t, respectively), returns both as an object of type div_t, ldiv_t, lldiv_t, imaxdiv_t defined as follows:

+

div_t

struct div_t { int quot; int rem; };

or

+
struct div_t { int rem; int quot; };

ldiv_t

struct ldiv_t { long quot; long rem; };

or

+
struct ldiv_t { long rem; long quot; };

lldiv_t

struct lldiv_t { long long quot; long long rem; };

or

+
struct lldiv_t { long long rem; long long quot; };

imaxdiv_t

struct imaxdiv_t { intmax_t quot; intmax_t rem; };

or

+
struct imaxdiv_t { intmax_t rem; intmax_t quot; };

If either the remainder or the quotient cannot be represented, the behavior is undefined.

+

Notes

Until C99, the rounding direction of the quotient and the sign of the remainder in the built-in division and remainder operators was implementation-defined if either of the operands was negative, but it was well-defined in div and ldiv.

+

On many platforms, a single CPU instruction obtains both the quotient and the remainder, and this function may leverage that, although compilers are generally able to merge nearby / and % where suitable.

+

Example

#include <assert.h>
+#include <limits.h>
+#include <math.h>
+#include <stdio.h>
+#include <stdlib.h>
+ 
+void reverse(char* first, char* last)
+{
+    for (--last; first < last; ++first, --last)
+    {
+        char c = *last;
+        *last = *first;
+        *first = c;
+    }
+}
+ 
+// returns empty buffer in case of buffer overflow
+char* itoa(int n, int base, char* buf, size_t buf_size)
+{
+    assert(2 <= base && base <= 16 && buf && buf_size);
+    div_t dv = {.quot = n};
+    char* p = buf;
+    do
+    {
+        if (!--buf_size)
+            return (*buf = '\0'), buf;
+        dv = div(dv.quot, base);
+        *p++ = "0123456789abcdef"[abs(dv.rem)];
+    }
+    while(dv.quot);
+    if (n < 0)
+        *p++ = '-';
+    *p = '\0';
+    reverse(buf, p);
+    return buf;
+}
+ 
+int main(void)
+{
+    char buf[16];
+    printf("%s\n", itoa(0, 2, buf, sizeof buf));
+    printf("%s\n", itoa(007, 3, buf, sizeof buf));
+    printf("%s\n", itoa(12346, 10, buf, sizeof buf));
+    printf("%s\n", itoa(-12346, 10, buf, sizeof buf));
+    printf("%s\n", itoa(-42, 2, buf, sizeof buf));
+    printf("%s\n", itoa(INT_MAX, 16, buf, sizeof buf));
+    printf("%s\n", itoa(INT_MIN, 16, buf, sizeof buf));
+}

Possible output:

+
0
+21
+12346
+-12346
+-101010
+7fffffff
+-80000000

References

See also

+ + + +
+
(C99)(C99)
 computes remainder of the floating-point division operation
(function)
+
(C99)(C99)(C99)
 computes signed remainder of the floating-point division operation
(function)
+
(C99)(C99)(C99)
 computes signed remainder as well as the three last bits of the division operation
(function)
C++ documentation for div
+ + +
1. +Euclidean division — From Wikipedia.
2. +Modulo (and Truncated division) — From Wikipedia.
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/div +

+
diff --git a/devdocs/c/numeric%2Fmath%2Ferf.html b/devdocs/c/numeric%2Fmath%2Ferf.html new file mode 100644 index 00000000..a4223e04 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ferf.html @@ -0,0 +1,69 @@ +

erf, erff, erfl

Defined in header <math.h> 
float       erff( float arg );
+		 (1) (since C99) 
double      erf( double arg );
+		 (2) (since C99) 
long double erfl( long double arg );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define erf( arg )
+		 (4) (since C99)
+1-3) Computes the error function of arg.
+4) Type-generic macro: If arg has type long double, erfl is called. Otherwise, if arg has integer type or the type double, erf is called. Otherwise, erff is called.

Parameters

+ +
arg - floating point value

Return value

If no errors occur, value of the error function of arg, that is \(\frac{2}{\sqrt{\pi} }\int_{0}^{arg}{e^{-{t^2} }\mathsf{d}t}\)2/√π∫arg0e-t2dt, is returned. If a range error occurs due to underflow, the correct result (after rounding), that is \(\frac{2\cdot arg}{\sqrt{\pi} }\)2*arg/√π, is returned.

Error handling

Errors are reported as specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

Underflow is guaranteed if |arg| < DBL_MIN*(sqrt(π)/2). \(\operatorname{erf}(\frac{x}{\sigma \sqrt{2} })\)erf(

+x/σ√2) is the probability that a measurement whose errors are subject to a normal distribution with standard deviation \(\sigma\)σ is less than \(x\)x away from the mean value.

Example

#include <math.h>
+#include <stdio.h>
+ 
+double phi(double x1, double x2)
+{
+    return (erf(x2 / sqrt(2)) - erf(x1 / sqrt(2))) / 2;
+}
+ 
+int main(void)
+{
+    puts("normal variate probabilities:");
+    for (int n = -4; n < 4; ++n)
+        printf("[%2d:%2d]: %5.2f%%\n", n, n + 1, 100 * phi(n, n + 1));
+ 
+    puts("special values:");
+    printf("erf(-0) = %f\n", erf(-0.0));
+    printf("erf(Inf) = %f\n", erf(INFINITY));
+}

Output:

+
normal variate probabilities:
+[-4:-3]:  0.13%
+[-3:-2]:  2.14%
+[-2:-1]: 13.59%
+[-1: 0]: 34.13%
+[ 0: 1]: 34.13%
+[ 1: 2]: 13.59%
+[ 2: 3]:  2.14%
+[ 3: 4]:  0.13%
+special values:
+erf(-0) = -0.000000
+erf(Inf) = 1.000000

References

See also

+ +
+
(C99)(C99)(C99)
 computes complementary error function
(function)
C++ documentation for erf
+ +
+Weisstein, Eric W. "Erf." From MathWorld — A Wolfram Web Resource.
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/erf +

+
diff --git a/devdocs/c/numeric%2Fmath%2Ferfc.html b/devdocs/c/numeric%2Fmath%2Ferfc.html new file mode 100644 index 00000000..cbbc7e72 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ferfc.html @@ -0,0 +1,75 @@ +

erfc, erfcf, erfcl

Defined in header <math.h> 
float       erfcf( float arg );
+		 (1) (since C99) 
double      erfc( double arg );
+		 (2) (since C99) 
long double erfcl( long double arg );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define erfc( arg )
+		 (4) (since C99)
+1-3) Computes the complementary error function of arg, that is 1.0 - erf(arg), but without loss of precision for large arg.
+4) Type-generic macro: If arg has type long double, erfcl is called. Otherwise, if arg has integer type or the type double, erfc is called. Otherwise, erfcf is called.

Parameters

+ +
arg - floating point value

Return value

If no errors occur, value of the complementary error function of arg, that is \(\frac{2}{\sqrt{\pi} }\int_{arg}^{\infty}{e^{-{t^2} }\mathsf{d}t}\)2/√π∫∞arge-t2dt or \({\small 1-\operatorname{erf}(arg)}\)1-erf(arg), is returned.

If a range error occurs due to underflow, the correct result (after rounding) is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

For the IEEE-compatible type double, underflow is guaranteed if arg > 26.55.

+

Example

#include <stdio.h>
+#include <math.h>
+ 
+double normalCDF(double x) // Phi(-∞, x) aka N(x)
+{
+    return erfc(-x / sqrt(2)) / 2;
+}
+ 
+int main(void)
+{
+    puts("normal cumulative distribution function:");
+    for(double n = 0; n < 1; n += 0.1)
+        printf("normalCDF(%.2f) %5.2f%%\n", n, 100 * normalCDF(n));
+ 
+    printf("special values:\n"
+           "erfc(-Inf) = %f\n"
+           "erfc(Inf) = %f\n",
+           erfc(-INFINITY),
+           erfc(INFINITY));
+}

Output:

+
normal cumulative distribution function:
+normalCDF(0.00) 50.00%
+normalCDF(0.10) 53.98%
+normalCDF(0.20) 57.93%
+normalCDF(0.30) 61.79%
+normalCDF(0.40) 65.54%
+normalCDF(0.50) 69.15%
+normalCDF(0.60) 72.57%
+normalCDF(0.70) 75.80%
+normalCDF(0.80) 78.81%
+normalCDF(0.90) 81.59%
+normalCDF(1.00) 84.13%
+special values:
+erfc(-Inf) = 2.000000
+erfc(Inf) = 0.000000

References

See also

+ +
+
(C99)(C99)(C99)
 computes error function
(function)
C++ documentation for erfc
+ +
+Weisstein, Eric W. "Erfc." From MathWorld — A Wolfram Web Resource.
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/erfc +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fexp.html b/devdocs/c/numeric%2Fmath%2Fexp.html new file mode 100644 index 00000000..0d02bb24 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fexp.html @@ -0,0 +1,90 @@ +

exp, expf, expl

Defined in header <math.h> 
float       expf( float arg );
+		 (1) (since C99) 
double      exp( double arg );
+		 (2) 
long double expl( long double arg );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define exp( arg )
+		 (4) (since C99)
+1-3) Computes e (Euler's number, 2.7182818...) raised to the given power arg.
+4) Type-generic macro: If arg has type long double, expl is called. Otherwise, if arg has integer type or the type double, exp is called. Otherwise, expf is called. If arg is complex or imaginary, then the macro invokes the corresponding complex function (cexpf, cexp, cexpl).

Parameters

+ +
arg - floating point value

Return value

If no errors occur, the base-e exponential of arg (earg) is returned.

+

If a range error occurs due to overflow, +HUGE_VAL, +HUGE_VALF, or +HUGE_VALL is returned.

+

If a range error occurs due to underflow, the correct result (after rounding) is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

For IEEE-compatible type double, overflow is guaranteed if 709.8 < arg, and underflow is guaranteed if arg < -708.4.

+

Example

#include <errno.h>
+#include <fenv.h>
+#include <float.h>
+#include <math.h>
+#include <stdio.h>
+// #pragma STDC FENV_ACCESS ON
+ 
+int main(void)
+{
+    printf("exp(1) = %f\n", exp(1));
+    printf("FV of $100, continuously compounded at 3%% for 1 year = %f\n",
+            100*exp(0.03));
+    // special values
+    printf("exp(-0) = %f\n", exp(-0.0));
+    printf("exp(-Inf) = %f\n", exp(-INFINITY));
+    //error handling
+    errno = 0; feclearexcept(FE_ALL_EXCEPT);
+    printf("exp(710) = %f\n", exp(710));
+    if (errno == ERANGE)
+        perror("    errno == ERANGE");
+    if (fetestexcept(FE_OVERFLOW))
+        puts("    FE_OVERFLOW raised");
+}

Possible output:

+
exp(1) = 2.718282
+FV of $100, continuously compounded at 3% for 1 year = 103.045453
+exp(-0) = 1.000000
+exp(-Inf) = 0.000000
+exp(710) = inf
+    errno == ERANGE: Numerical result out of range
+    FE_OVERFLOW raised

References

See also

+ + + + +
+
(C99)(C99)(C99)
 computes 2 raised to the given power (\({\small 2^x}\)2x)
(function)
+
(C99)(C99)(C99)
 computes e raised to the given power, minus one (\({\small e^x-1}\)ex-1)
(function)
+
(C99)(C99)
 computes natural (base-e) logarithm (\({\small \ln{x} }\)ln(x))
(function)
+
(C99)(C99)(C99)
 computes the complex base-e exponential
(function)
C++ documentation for exp
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/exp +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fexp2.html b/devdocs/c/numeric%2Fmath%2Fexp2.html new file mode 100644 index 00000000..66fa43ca --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fexp2.html @@ -0,0 +1,77 @@ +

exp2, exp2f, exp2l

Defined in header <math.h> 
float       exp2f( float n );
+		 (1) (since C99) 
double      exp2( double n );
+		 (2) (since C99) 
long double exp2l( long double n );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define exp2( n )
+		 (4) (since C99)
+1-3) Computes 2 raised to the given power n.
+4) Type-generic macro: If n has type long double, exp2l is called. Otherwise, if n has integer type or the type double, exp2 is called. Otherwise, exp2f is called.

Parameters

+ +
n - floating point value

Return value

If no errors occur, the base-2 exponential of n (2n) is returned.

+

If a range error due to overflow occurs, +HUGE_VAL, +HUGE_VALF, or +HUGE_VALL is returned.

+

If a range error occurs due to underflow, the correct result (after rounding) is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Example

#include <stdio.h>
+#include <math.h>
+#include <float.h>
+#include <errno.h>
+#include <fenv.h>
+// #pragma STDC FENV_ACCESS ON
+int main(void)
+{
+    printf("exp2(5) = %f\n", exp2(5));
+    printf("exp2(0.5) = %f\n", exp2(0.5));
+    printf("exp2(-4) = %f\n", exp2(-4));
+    // special values
+    printf("exp2(-0.9) = %f\n", exp2(-0.9));
+    printf("exp2(-Inf) = %f\n", exp2(-INFINITY));
+    //error handling
+    errno = 0; feclearexcept(FE_ALL_EXCEPT);
+    printf("exp2(1024) = %f\n", exp2(1024));
+    if(errno == ERANGE) perror("    errno == ERANGE");
+    if(fetestexcept(FE_OVERFLOW)) puts("    FE_OVERFLOW raised");
+}

Possible output:

+
exp2(5) = 32.000000
+exp2(0.5) = 1.414214
+exp2(-4) = 0.062500
+exp2(-0.9) = 0.535887
+exp2(-Inf) = 0.000000
+exp2(1024) = Inf
+    errno == ERANGE: Result too large
+    FE_OVERFLOW raised

References

See also

+ + + +
+
(C99)(C99)
 computes e raised to the given power (\({\small e^x}\)ex)
(function)
+
(C99)(C99)(C99)
 computes e raised to the given power, minus one (\({\small e^x-1}\)ex-1)
(function)
+
(C99)(C99)(C99)
 computes base-2 logarithm (\({\small \log_{2}{x} }\)log2(x))
(function)
C++ documentation for exp2
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/exp2 +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fexpm1.html b/devdocs/c/numeric%2Fmath%2Fexpm1.html new file mode 100644 index 00000000..75918aa8 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fexpm1.html @@ -0,0 +1,83 @@ +

expm1, expm1f, expm1l

Defined in header <math.h> 
float       expm1f( float arg );
+		 (1) (since C99) 
double      expm1( double arg );
+		 (2) (since C99) 
long double expm1l( long double arg );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define expm1( arg )
+		 (4) (since C99)
+1-3) Computes the e (Euler's number, 2.7182818) raised to the given power arg, minus 1.0. This function is more accurate than the expression exp(arg)-1.0 if arg is close to zero.
+4) Type-generic macro: If arg has type long double, expm1l is called. Otherwise, if arg has integer type or the type double, expm1 is called. Otherwise, expm1f is called.

Parameters

+ +
arg - floating point value

Return value

If no errors occur earg-1 is returned.

+

If a range error due to overflow occurs, +HUGE_VAL, +HUGE_VALF, or +HUGE_VALL is returned.

+

If a range error occurs due to underflow, the correct result (after rounding) is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

The functions expm1 and log1p are useful for financial calculations, for example, when calculating small daily interest rates: (1+x)n-1 can be expressed as expm1(n * log1p(x)). These functions also simplify writing accurate inverse hyperbolic functions.

+

For IEEE-compatible type double, overflow is guaranteed if 709.8 < arg.

+

Example

#include <stdio.h>
+#include <math.h>
+#include <float.h>
+#include <errno.h>
+#include <fenv.h>
+// #pragma STDC FENV_ACCESS ON
+int main(void)
+{
+    printf("expm1(1) = %f\n", expm1(1));
+    printf("Interest earned in 2 days on $100, compounded daily at 1%%\n"
+           " on a 30/360 calendar = %f\n",
+           100*expm1(2*log1p(0.01/360)));
+    printf("exp(1e-16)-1 = %g, but expm1(1e-16) = %g\n",
+           exp(1e-16)-1, expm1(1e-16));
+    // special values
+    printf("expm1(-0) = %f\n", expm1(-0.0));
+    printf("expm1(-Inf) = %f\n", expm1(-INFINITY));
+    //error handling
+    errno = 0; feclearexcept(FE_ALL_EXCEPT);
+    printf("expm1(710) = %f\n", expm1(710));
+    if(errno == ERANGE) perror("    errno == ERANGE");
+    if(fetestexcept(FE_OVERFLOW)) puts("    FE_OVERFLOW raised");
+}

Possible output:

+
expm1(1) = 1.718282
+Interest earned in 2 days on $100, compounded daily at 1%
+ on a 30/360 calendar = 0.005556
+exp(1e-16)-1 = 0, but expm1(1e-16) = 1e-16
+expm1(-0) = -0.000000
+expm1(-Inf) = -1.000000
+expm1(710) = inf
+    errno == ERANGE: Result too large
+    FE_OVERFLOW raised

References

See also

+ + + +
+
(C99)(C99)
 computes e raised to the given power (\({\small e^x}\)ex)
(function)
+
(C99)(C99)(C99)
 computes 2 raised to the given power (\({\small 2^x}\)2x)
(function)
+
(C99)(C99)(C99)
 computes natural (base-e) logarithm of 1 plus the given number (\({\small \ln{(1+x)} }\)ln(1+x))
(function)
C++ documentation for expm1
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/expm1 +

+
diff --git a/devdocs/c/numeric%2Fmath%2Ffabs.html b/devdocs/c/numeric%2Fmath%2Ffabs.html new file mode 100644 index 00000000..a4944087 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ffabs.html @@ -0,0 +1,96 @@ +

fabs, fabsf, fabsl, fabsd32, fabsd64, fabsd128

Defined in header <math.h> 
float       fabsf( float arg );
+		 (1) (since C99) 
double      fabs( double arg );
+		 (2) 
long double fabsl( long double arg );
+		 (3) (since C99) 
_Decimal32  fabsd32( _Decimal32 arg );
+		 (4) (since C23) 
_Decimal64  fabsd64( _Decimal64 arg );
+		 (5) (since C23) 
_Decimal128 fabsd128( _Decimal128 arg );
+		 (6) (since C23)
Defined in header <tgmath.h> 
#define fabs( arith )
+		 (7) (since C99)
+1-6) Computes the absolute value of a floating point value arg. + +

The functions with decimal floating point parameters are declared if and only if the implementation predefines __STDC_IEC_60559_DFP__ (i.e. the implementation supports decimal floating point numbers).

+		 (since C23)
+
+7) Type-generic macro: If the argument has type _Decimal128, _Decimal64, _Decimal32,(since C23)long double, double, or float, fabsd128, fabsd64, fabsd32,(since C23)fabsl, fabs, or fabsf is called, respectively. Otherwise, if the argument has integer type, fabs is called. Otherwise, if the argument is complex, then the macro invokes the corresponding complex function (cabsf, cabs, cabsl). Otherwise, the behavior is undefined.

Parameters

+ + +
arg - floating point value
arith - floating point or integer value

Return value

If successful, returns the absolute value of arg (\(\small |arg| \)|arg|). The value returned is exact and does not depend on any rounding modes.

+

Error handling

This function is not subject to any of the error conditions specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Example

#include <math.h>
+#include <stdio.h>
+ 
+#define PI 3.14159
+ 
+// This numerical integration assumes all area is positive.
+double integrate(double f(double),
+                 double a, double b, // assume a < b
+                 unsigned steps) // assume steps > 0
+{
+    const double dx = (b - a) / steps;
+    double sum = 0.0;
+    for (double x = a; x < b; x += dx)
+        sum += fabs(f(x));
+    return dx * sum;
+}
+ 
+int main(void)
+{
+    printf("fabs(+3) = %f\n", fabs(+3.0));
+    printf("fabs(-3) = %f\n", fabs(-3.0));
+    // special values
+    printf("fabs(-0) = %f\n", fabs(-0.0));
+    printf("fabs(-Inf) = %f\n", fabs(-INFINITY));
+ 
+    printf("Area under sin(x) in [-PI, PI] = %f\n", integrate(sin, -PI, PI, 5101));
+}

Output:

+
fabs(+3) = 3.000000
+fabs(-3) = 3.000000
+fabs(-0) = 0.000000
+fabs(-Inf) = inf
+Area under sin(x) in [-PI, PI] = 4.000000

References

See also

+ + + + +
+
(C99)
 computes absolute value of an integral value (\(\small{|x|}\)|x|)
(function)
+
(C99)(C99)(C99)
 produces a value with the magnitude of a given value and the sign of another given value
(function)
+
(C99)
 checks if the given number is negative
(function macro)
+
(C99)(C99)(C99)
 computes the magnitude of a complex number
(function)
C++ documentation for fabs
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/fabs +

+
diff --git a/devdocs/c/numeric%2Fmath%2Ffdim.html b/devdocs/c/numeric%2Fmath%2Ffdim.html new file mode 100644 index 00000000..4d64f3ac --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ffdim.html @@ -0,0 +1,63 @@ +

fdim, fdimf, fdiml

Defined in header <math.h> 
float       fdimf( float x, float y );
+		 (1) (since C99) 
double      fdim( double x, double y );
+		 (2) (since C99) 
long double fdiml( long double x, long double y );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define fdim( x, y )
+		 (4) (since C99)
+1-3) Returns the positive difference between x and y, that is, if x>y, returns x-y, otherwise (if x≤y), returns +0.
+4) Type-generic macro: If any argument has type long double, fdiml is called. Otherwise, if any argument has integer type or has type double, fdim is called. Otherwise, fdimf is called.

Parameters

+ +
x, y - floating point value

Return value

If successful, returns the positive difference between x and y.

+

If a range error due to overflow occurs, +HUGE_VAL, +HUGE_VALF, or +HUGE_VALL is returned.

+

If a range error due to underflow occurs, the correct value (after rounding) is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

Equivalent to fmax(x-y, 0) except for the NaN handling requirements.

+

Example

#include <stdio.h>
+#include <math.h>
+#include <errno.h>
+#include <fenv.h>
+// #pragma STDC FENV_ACCESS ON
+int main(void)
+{
+    printf("fdim(4, 1) = %f, fdim(1, 4)=%f\n", fdim(4,1), fdim(1,4));
+    printf("fdim(4,-1) = %f, fdim(1,-4)=%f\n", fdim(4,-1), fdim(1,-4));
+    //error handling
+    errno = 0; feclearexcept(FE_ALL_EXCEPT);
+    printf("fdim(1e308, -1e308) = %f\n", fdim(1e308, -1e308));
+    if(errno == ERANGE) perror("    errno == ERANGE");
+    if(fetestexcept(FE_OVERFLOW)) puts("    FE_OVERFLOW raised");
+}

Possible output:

+
fdim(4, 1) = 3.000000, fdim(1, 4)=0.000000
+fdim(4,-1) = 5.000000, fdim(1,-4)=5.000000
+fdim(1e308, -1e308) = inf
+    errno == ERANGE: Numerical result out of range
+    FE_OVERFLOW raised

References

See also

+ + +
+
(C99)
 computes absolute value of an integral value (\(\small{|x|}\)|x|)
(function)
+
(C99)(C99)(C99)
 determines larger of two floating-point values
(function)
C++ documentation for fdim
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/fdim +

+
diff --git a/devdocs/c/numeric%2Fmath%2Ffloat_t.html b/devdocs/c/numeric%2Fmath%2Ffloat_t.html new file mode 100644 index 00000000..e9783b11 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ffloat_t.html @@ -0,0 +1,34 @@ +

float_t, double_t

Defined in header <math.h> 
typedef /*implementation defined*/ float_t
+		 (since C99) 
typedef /*implementation defined*/ double_t
+		 (since C99)

The types float_t and double_t are floating types at least as wide as float and double, respectively, and such that double_t is at least as wide as float_t. The value of FLT_EVAL_METHOD determines the types of float_t and double_t.

+ + + + + +
FLT_EVAL_METHOD Explanation
0 float_t and double_t are equivalent to float and double, respectively
1 both float_t and double_t are equivalent to double
2 both float_t and double_t are equivalent to long double
other both float_t and double_t are implementation defined

Example

#include <float.h>
+#include <math.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    printf("%d\n", FLT_EVAL_METHOD);
+    printf("%zu  %zu\n", sizeof(float),sizeof(float_t));
+    printf("%zu  %zu\n", sizeof(double),sizeof(double_t));
+    return 0;
+}

Possible output:

+
0
+4  4
+8  8

References

See also

+
+
(C99)
 use of extended precision for intermediate results: 0 not used, 1 double is used instead of float, 2: long double is used
(macro constant)
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/float_t +

+
diff --git a/devdocs/c/numeric%2Fmath%2Ffloor.html b/devdocs/c/numeric%2Fmath%2Ffloor.html new file mode 100644 index 00000000..54153acb --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ffloor.html @@ -0,0 +1,58 @@ +

floor, floorf, floorl

Defined in header <math.h> 
float       floorf( float arg );
+		 (1) (since C99) 
double      floor( double arg );
+		 (2) 
long double floorl( long double arg );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define floor( arg )
+		 (4) (since C99)
+1-3) Computes the largest integer value not greater than arg.
+4) Type-generic macro: If arg has type long double, floorl is called. Otherwise, if arg has integer type or the type double, floor is called. Otherwise, floorf is called.

Parameters

+ +
arg - floating point value

Return value

If no errors occur, the largest integer value not greater than arg, that is ⌊arg⌋, is returned.

+
Return value
math-floor.svg
Argument

Error handling

Errors are reported as specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

FE_INEXACT may be (but isn't required to be) raised when rounding a non-integer finite value.

+

The largest representable floating-point values are exact integers in all standard floating-point formats, so this function never overflows on its own; however the result may overflow any integer type (including intmax_t), when stored in an integer variable.

+

Example

#include <math.h>
+#include <stdio.h>
+int main(void)
+{
+    printf("floor(+2.7) = %+.1f\n", floor(2.7));
+    printf("floor(-2.7) = %+.1f\n", floor(-2.7));
+    printf("floor(-0.0) = %+.1f\n", floor(-0.0));
+    printf("floor(-Inf) = %+f\n",   floor(-INFINITY));
+}

Possible output:

+
floor(+2.7) = +2.0
+floor(-2.7) = -3.0
+floor(-0.0) = -0.0
+floor(-Inf) = -inf

References

See also

+ + + +
+
(C99)(C99)
 computes smallest integer not less than the given value
(function)
+
(C99)(C99)(C99)
 rounds to nearest integer not greater in magnitude than the given value
(function)
+
(C99)(C99)(C99)(C99)(C99)(C99)(C99)(C99)(C99)
 rounds to nearest integer, rounding away from zero in halfway cases
(function)
C++ documentation for floor
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/floor +

+
diff --git a/devdocs/c/numeric%2Fmath%2Ffma.html b/devdocs/c/numeric%2Fmath%2Ffma.html new file mode 100644 index 00000000..ce600c3f --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ffma.html @@ -0,0 +1,94 @@ +

fma, fmaf, fmal

Defined in header <math.h> 
float       fmaf( float x, float y, float z );
+		 (1) (since C99) 
double      fma( double x, double y, double z );
+		 (2) (since C99) 
long double fmal( long double x, long double y, long double z );
+		 (3) (since C99) 
#define FP_FAST_FMA  /* implementation-defined */
+		 (4) (since C99) 
#define FP_FAST_FMAF /* implementation-defined */
+		 (5) (since C99) 
#define FP_FAST_FMAL /* implementation-defined */
+		 (6) (since C99)
Defined in header <tgmath.h> 
#define fma( x, y, z )
+		 (7) (since C99)
+1-3) Computes (x*y) + z as if to infinite precision and rounded only once to fit the result type.
+4-6) If the macro constants FP_FAST_FMA, FP_FAST_FMAF, or FP_FAST_FMAL are defined, the corresponding function fmaf, fma, or fmal evaluates faster (in addition to being more precise) than the expression x*y+z for float, double, and long double arguments, respectively. If defined, these macros evaluate to integer 1.
+7) Type-generic macro: If any argument has type long double, fmal is called. Otherwise, if any argument has integer type or has type double, fma is called. Otherwise, fmaf is called.

Parameters

+ +
x, y, z - floating point values

Return value

If successful, returns the value of (x*y) + z as if calculated to infinite precision and rounded once to fit the result type (or, alternatively, calculated as a single ternary floating-point operation).

+

If a range error due to overflow occurs, ±HUGE_VAL, ±HUGE_VALF, or ±HUGE_VALL is returned.

+

If a range error due to underflow occurs, the correct value (after rounding) is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

This operation is commonly implemented in hardware as fused multiply-add CPU instruction. If supported by hardware, the appropriate FP_FAST_FMA* macros are expected to be defined, but many implementations make use of the CPU instruction even when the macros are not defined.

+

POSIX specifies that the situation where the value x*y is invalid and z is a NaN is a domain error.

+

Due to its infinite intermediate precision, fma is a common building block of other correctly-rounded mathematical operations, such as sqrt or even the division (where not provided by the CPU, e.g. Itanium).

+

As with all floating-point expressions, the expression (x*y) + z may be compiled as a fused mutiply-add unless the #pragma STDC FP_CONTRACT is off.

+

Example

#include <stdio.h>
+#include <math.h>
+#include <float.h>
+#include <fenv.h>
+#pragma STDC FENV_ACCESS ON
+int main(void)
+{
+    // demo the difference between fma and built-in operators
+    double in = 0.1;
+    printf("0.1 double is %.23f (%a)\n", in, in);
+    printf("0.1*10 is 1.0000000000000000555112 (0x8.0000000000002p-3),"
+           " or 1.0 if rounded to double\n");
+    double expr_result = 0.1 * 10 - 1;
+    printf("0.1 * 10 - 1 = %g : 1 subtracted after "
+           "intermediate rounding to 1.0\n", expr_result);
+    double fma_result = fma(0.1, 10, -1);
+    printf("fma(0.1, 10, -1) = %g (%a)\n", fma_result, fma_result);
+ 
+    // fma use in double-double arithmetic
+    printf("\nin double-double arithmetic, 0.1 * 10 is representable as ");
+    double high = 0.1 * 10;
+    double low = fma(0.1, 10, -high);
+    printf("%g + %g\n\n", high, low);
+ 
+    //error handling
+    feclearexcept(FE_ALL_EXCEPT);
+    printf("fma(+Inf, 10, -Inf) = %f\n", fma(INFINITY, 10, -INFINITY));
+    if(fetestexcept(FE_INVALID)) puts("    FE_INVALID raised");
+}

Possible output:

+
0.1 double is 0.10000000000000000555112 (0x1.999999999999ap-4)
+0.1*10 is 1.0000000000000000555112 (0x8.0000000000002p-3), or 1.0 if rounded to double
+0.1 * 10 - 1 = 0 : 1 subtracted after intermediate rounding to 1.0
+fma(0.1, 10, -1) = 5.55112e-17 (0x1p-54)
+ 
+in double-double arithmetic, 0.1 * 10 is representable as 1 + 5.55112e-17
+ 
+fma(+Inf, 10, -Inf) = -nan
+    FE_INVALID raised

References

See also

+ + +
+
(C99)(C99)(C99)
 computes signed remainder of the floating-point division operation
(function)
+
(C99)(C99)(C99)
 computes signed remainder as well as the three last bits of the division operation
(function)
C++ documentation for fma
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/fma +

+
diff --git a/devdocs/c/numeric%2Fmath%2Ffmax.html b/devdocs/c/numeric%2Fmath%2Ffmax.html new file mode 100644 index 00000000..899bbddd --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ffmax.html @@ -0,0 +1,56 @@ +

fmax, fmaxf, fmaxl

Defined in header <math.h> 
float       fmaxf( float x, float y );
+		 (1) (since C99) 
double      fmax( double x, double y );
+		 (2) (since C99) 
long double fmaxl( long double x, long double y );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define fmax( x, y )
+		 (4) (since C99)
+1-3) Returns the larger of two floating point arguments, treating NaNs as missing data (between a NaN and a numeric value, the numeric value is chosen).
+4) Type-generic macro: If any argument has type long double, fmaxl is called. Otherwise, if any argument has integer type or has type double, fmax is called. Otherwise, fmaxf is called.

Parameters

+ +
x, y - floating point values

Return value

If successful, returns the larger of two floating point values. The value returned is exact and does not depend on any rounding modes.

+

Error handling

This function is not subject to any of the error conditions specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

This function is not required to be sensitive to the sign of zero, although some implementations additionally enforce that if one argument is +0 and the other is -0, then +0 is returned.

+

Example

#include <stdio.h>
+#include <math.h>
+ 
+int main(void)
+{
+    printf("fmax(2,1)    = %f\n", fmax(2,1));
+    printf("fmax(-Inf,0) = %f\n", fmax(-INFINITY,0));
+    printf("fmax(NaN,-1) = %f\n", fmax(NAN,-1));
+}

Output:

+
fmax(2,1)    = 2.000000
+fmax(-Inf,0) = 0.000000
+fmax(NaN,-1) = -1.000000

References

See also

+ + +
+
(C99)
 checks if the first floating-point argument is greater than the second
(function macro)
+
(C99)(C99)(C99)
 determines smaller of two floating-point values
(function)
C++ documentation for fmax
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/fmax +

+
diff --git a/devdocs/c/numeric%2Fmath%2Ffmin.html b/devdocs/c/numeric%2Fmath%2Ffmin.html new file mode 100644 index 00000000..bec5d0b4 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ffmin.html @@ -0,0 +1,50 @@ +

fmin, fminf, fminl

Defined in header <math.h> 
float       fminf( float x, float y );
+		 (1) (since C99) 
double      fmin( double x, double y );
+		 (2) (since C99) 
long double fminl( long double x, long double y );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define fmin( x, y )
+		 (4) (since C99)
+1-3) Returns the smaller of two floating point arguments, treating NaNs as missing data (between a NaN and a numeric value, the numeric value is chosen).
+4) Type-generic macro: If any argument has type long double, fminl is called. Otherwise, if any argument has integer type or has type double, fmin is called. Otherwise, fminf is called.

Parameters

+ +
x, y - floating point values

Return value

If successful, returns the smaller of two floating point values. The value returned is exact and does not depend on any rounding modes.

+

Error handling

This function is not subject to any of the error conditions specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

This function is not required to be sensitive to the sign of zero, although some implementations additionally enforce that if one argument is +0 and the other is -0, then -0 is returned.

+

Example

#include <stdio.h>
+#include <math.h>
+ 
+int main(void)
+{
+    printf("fmin(2,1)    = %f\n", fmin(2,1));
+    printf("fmin(-Inf,0) = %f\n", fmin(-INFINITY,0));
+    printf("fmin(NaN,-1) = %f\n", fmin(NAN,-1));
+}

Possible output:

+
fmin(2,1)    = 1.000000
+fmin(-Inf,0) = -inf
+fmin(NaN,-1) = -1.000000

References

See also

+ + +
+
(C99)
 checks if the first floating-point argument is less than the second
(function macro)
+
(C99)(C99)(C99)
 determines larger of two floating-point values
(function)
C++ documentation for fmin
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/fmin +

+
diff --git a/devdocs/c/numeric%2Fmath%2Ffmod.html b/devdocs/c/numeric%2Fmath%2Ffmod.html new file mode 100644 index 00000000..e43577a0 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ffmod.html @@ -0,0 +1,95 @@ +

fmod, fmodf, fmodl

Defined in header <math.h> 
float       fmodf( float x, float y );
+		 (1) (since C99) 
double      fmod( double x, double y );
+		 (2) 
long double fmodl( long double x, long double y );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define fmod( x, y )
+		 (4) (since C99)
+1-3) Computes the floating-point remainder of the division operation x/y.
+4) Type-generic macro: If any argument has type long double, fmodl is called. Otherwise, if any argument has integer type or has type double, fmod is called. Otherwise, fmodf is called.

The floating-point remainder of the division operation x/y calculated by this function is exactly the value x - n*y, where n is x/y with its fractional part truncated.

+

The returned value has the same sign as x and is less or equal to y in magnitude.

+

Parameters

+ +
x, y - floating point values

Return value

If successful, returns the floating-point remainder of the division x/y as defined above.

+

If a domain error occurs, an implementation-defined value is returned (NaN where supported).

+

If a range error occurs due to underflow, the correct result (after rounding) is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

Domain error may occur if y is zero.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

POSIX requires that a domain error occurs if x is infinite or y is zero.

+

fmod, but not remainder is useful for doing silent wrapping of floating-point types to unsigned integer types: (0.0 <= (y = fmod(rint(x), 65536.0 )) ? y : 65536.0 + y) is in the range [-0.0 .. 65535.0], which corresponds to unsigned short, but remainder(rint(x), 65536.0) is in the range [-32767.0, +32768.0], which is outside of the range of signed short.

+

The double version of fmod behaves as if implemented as follows:

+
double fmod(double x, double y)
+{
+#pragma STDC FENV_ACCESS ON
+    double result = remainder(fabs(x), (y = fabs(y)));
+    if (signbit(result)) result += y;
+    return copysign(result, x);
+}

Example

#include <stdio.h>
+#include <math.h>
+#include <fenv.h>
+ 
+// #pragma STDC FENV_ACCESS ON
+int main(void)
+{
+    printf("fmod(+5.1, +3.0) = %.1f\n", fmod(5.1,3));
+    printf("fmod(-5.1, +3.0) = %.1f\n", fmod(-5.1,3));
+    printf("fmod(+5.1, -3.0) = %.1f\n", fmod(5.1,-3));
+    printf("fmod(-5.1, -3.0) = %.1f\n", fmod(-5.1,-3));
+ 
+    // special values
+    printf("fmod(+0.0, 1.0) = %.1f\n", fmod(0, 1));
+    printf("fmod(-0.0, 1.0) = %.1f\n", fmod(-0.0, 1));
+    printf("fmod(+5.1, Inf) = %.1f\n", fmod(5.1, INFINITY));
+ 
+    // error handling
+    feclearexcept(FE_ALL_EXCEPT);
+    printf("fmod(+5.1, 0) = %.1f\n", fmod(5.1, 0));
+    if(fetestexcept(FE_INVALID)) puts("    FE_INVALID raised");
+}

Possible output:

+
fmod(+5.1, +3.0) = 2.1
+fmod(-5.1, +3.0) = -2.1
+fmod(+5.1, -3.0) = 2.1
+fmod(-5.1, -3.0) = -2.1
+fmod(+0.0, 1.0) = 0.0
+fmod(-0.0, 1.0) = -0.0
+fmod(+5.1, Inf) = 5.1
+fmod(+5.1, 0) = nan
+    FE_INVALID raised

References

See also

+ + + +
+
(C99)
 computes quotient and remainder of integer division
(function)
+
(C99)(C99)(C99)
 computes signed remainder of the floating-point division operation
(function)
+
(C99)(C99)(C99)
 computes signed remainder as well as the three last bits of the division operation
(function)
C++ documentation for fmod
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/fmod +

+
diff --git a/devdocs/c/numeric%2Fmath%2Ffp_categories.html b/devdocs/c/numeric%2Fmath%2Ffp_categories.html new file mode 100644 index 00000000..520ed9eb --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ffp_categories.html @@ -0,0 +1,54 @@ +

FP_NORMAL, FP_SUBNORMAL, FP_ZERO, FP_INFINITE, FP_NAN

Defined in header <math.h> 
#define FP_NORMAL    /*implementation defined*/
+		 (since C99) 
#define FP_SUBNORMAL /*implementation defined*/
+		 (since C99) 
#define FP_ZERO      /*implementation defined*/
+		 (since C99) 
#define FP_INFINITE  /*implementation defined*/
+		 (since C99) 
#define FP_NAN       /*implementation defined*/
+		 (since C99)

The FP_NORMAL, FP_SUBNORMAL, FP_ZERO, FP_INFINITE, FP_NAN macros each represent a distinct category of floating-point numbers. They all expand to an integer constant expression.

+ + + + + + +
Constant Explanation
FP_NORMAL indicates that the value is normal, i.e. not an infinity, subnormal, not-a-number or zero
FP_SUBNORMAL indicates that the value is subnormal
FP_ZERO indicates that the value is positive or negative zero
FP_INFINITE indicates that the value is not representable by the underlying type (positive or negative infinity)
FP_NAN indicates that the value is not-a-number (NaN)

Example

#include <stdio.h>
+#include <math.h>
+#include <float.h>
+ 
+const char *show_classification(double x) {
+    switch(fpclassify(x)) {
+        case FP_INFINITE:  return "Inf";
+        case FP_NAN:       return "NaN";
+        case FP_NORMAL:    return "normal";
+        case FP_SUBNORMAL: return "subnormal";
+        case FP_ZERO:      return "zero";
+        default:           return "unknown";
+    }
+}
+int main(void)
+{
+    printf("1.0/0.0 is %s\n", show_classification(1/0.0));
+    printf("0.0/0.0 is %s\n", show_classification(0.0/0.0));
+    printf("DBL_MIN/2 is %s\n", show_classification(DBL_MIN/2));
+    printf("-0.0 is %s\n", show_classification(-0.0));
+    printf(" 1.0 is %s\n", show_classification(1.0));
+}

Output:

+
1.0/0.0 is Inf
+0.0/0.0 is NaN
+DBL_MIN/2 is subnormal
+-0.0 is zero
+ 1.0 is normal

References

See also

+ +
+
(C99)
 classifies the given floating-point value
(function macro)
C++ documentation for FP_categories
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/FP_categories +

+
diff --git a/devdocs/c/numeric%2Fmath%2Ffpclassify.html b/devdocs/c/numeric%2Fmath%2Ffpclassify.html new file mode 100644 index 00000000..0014938b --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ffpclassify.html @@ -0,0 +1,52 @@ +

fpclassify

Defined in header <math.h> 
#define fpclassify(arg) /* implementation defined */
+		 (since C99)

Categorizes floating point value arg into the following categories: zero, subnormal, normal, infinite, NAN, or implementation-defined category. The macro returns an integral value.

+

FLT_EVAL_METHOD is ignored: even if the argument is evaluated with more range and precision than its type, it is first converted to its semantic type, and the classification is based on that: a normal long double value might become subnormal when converted to double and zero when converted to float.

+

Parameters

+ +
arg - floating point value

Return value

One of FP_INFINITE, FP_NAN, FP_NORMAL, FP_SUBNORMAL, FP_ZERO or implementation-defined type, specifying the category of arg.

+

Example

#include <stdio.h>
+#include <math.h>
+#include <float.h>
+ 
+const char *show_classification(double x) {
+    switch(fpclassify(x)) {
+        case FP_INFINITE:  return "Inf";
+        case FP_NAN:       return "NaN";
+        case FP_NORMAL:    return "normal";
+        case FP_SUBNORMAL: return "subnormal";
+        case FP_ZERO:      return "zero";
+        default:           return "unknown";
+    }
+}
+int main(void)
+{
+    printf("1.0/0.0 is %s\n", show_classification(1/0.0));
+    printf("0.0/0.0 is %s\n", show_classification(0.0/0.0));
+    printf("DBL_MIN/2 is %s\n", show_classification(DBL_MIN/2));
+    printf("-0.0 is %s\n", show_classification(-0.0));
+    printf("1.0 is %s\n", show_classification(1.0));
+}

Output:

+
1.0/0.0 is Inf
+0.0/0.0 is NaN
+DBL_MIN/2 is subnormal
+-0.0 is zero
+1.0 is normal

References

See also

+ + + + +
+
(C99)
 checks if the given number has finite value
(function macro)
+
(C99)
 checks if the given number is infinite
(function macro)
+
(C99)
 checks if the given number is NaN
(function macro)
+
(C99)
 checks if the given number is normal
(function macro)
C++ documentation for fpclassify
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/fpclassify +

+
diff --git a/devdocs/c/numeric%2Fmath%2Ffrexp.html b/devdocs/c/numeric%2Fmath%2Ffrexp.html new file mode 100644 index 00000000..60c85cff --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ffrexp.html @@ -0,0 +1,79 @@ +

frexp, frexpf, frexpl

Defined in header <math.h> 
float       frexpf( float arg, int* exp );
+		 (1) (since C99) 
double      frexp( double arg, int* exp );
+		 (2) 
long double frexpl( long double arg, int* exp );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define frexp( arg, exp )
+		 (4) (since C99)
+1-3) Decomposes given floating point value x into a normalized fraction and an integral power of two.
+4) Type-generic macro: If arg has type long double, frexpl is called. Otherwise, if arg has integer type or the type double, frexp is called. Otherwise, frexpf is called, respectively.

Parameters

+ + +
arg - floating point value
exp - pointer to integer value to store the exponent to

Return value

If arg is zero, returns zero and stores zero in *exp.

+

Otherwise (if arg is not zero), if no errors occur, returns the value x in the range (-1;-0.5], [0.5; 1) and stores an integer value in *exp such that x×2(*exp)=arg.

+

If the value to be stored in *exp is outside the range of int, the behavior is unspecified.

+

If arg is not a floating-point number, the behavior is unspecified.

+

Error handling

This function is not subject to any errors specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

On a binary system (where FLT_RADIX is 2), frexp may be implemented as

+
{
+    *exp = (value == 0) ? 0 : (int)(1 + logb(value));
+    return scalbn(value, -(*exp));
+}

The function frexp, together with its dual, ldexp, can be used to manipulate the representation of a floating-point number without direct bit manipulations.

+

Example

#include <stdio.h>
+#include <math.h>
+#include <float.h>
+ 
+int main(void)
+{
+    double f = 123.45;
+    printf("Given the number %.2f or %a in hex,\n", f, f);
+ 
+    double f3;
+    double f2 = modf(f, &f3);
+    printf("modf() makes %.0f + %.2f\n", f3, f2);
+ 
+    int i;
+    f2 = frexp(f, &i);
+    printf("frexp() makes %f * 2^%d\n", f2, i);
+ 
+    i = ilogb(f);
+    printf("logb()/ilogb() make %f * %d^%d\n", f/scalbn(1.0, i), FLT_RADIX, i);
+}

Possible output:

+
Given the number 123.45 or 0x1.edccccccccccdp+6 in hex,
+modf() makes 123 + 0.45
+frexp() makes 0.964453 * 2^7
+logb()/ilogb() make 1.92891 * 2^6

References

See also

+ + + + +
+
(C99)(C99)
 multiplies a number by 2 raised to a power
(function)
+
(C99)(C99)(C99)
 extracts exponent of the given number
(function)
+
(C99)(C99)(C99)
 extracts exponent of the given number
(function)
+
(C99)(C99)
 breaks a number into integer and fractional parts
(function)
C++ documentation for frexp
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/frexp +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fhuge_val.html b/devdocs/c/numeric%2Fmath%2Fhuge_val.html new file mode 100644 index 00000000..d95e528b --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fhuge_val.html @@ -0,0 +1,52 @@ +

HUGE_VALF, HUGE_VAL, HUGE_VALL

Defined in header <math.h> 
#define HUGE_VALF /*implementation defined*/
+		 (since C99) 
#define HUGE_VAL  /*implementation defined*/
+		 
#define HUGE_VALL /*implementation defined*/
+		 (since C99)

The HUGE_VALF, HUGE_VAL and HUGE_VALL macros expand to positive floating point constant expressions which compare equal to the values returned by floating-point functions and operators in case of overflow (see math_errhandling).

+ + + + +
Constant Explanation
HUGE_VALF Expands to positive float expression that indicates overflow
HUGE_VAL Expands to positive double expression that indicates overflow, not necessarily representable as a float
HUGE_VALL Expands to positive long double expression that indicates overflow, not necessarily representable as a float or double

On implementations that support floating-point infinities, these macros always expand to the positive infinities of float, double, and long double, respectively.

+

Example

#include <math.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    const double result = 1.0 / 0.0;
+    printf("1.0/0.0 == %f\n", result);
+    if (result == HUGE_VAL)
+        puts("1.0/0.0 == HUGE_VAL");
+}

Possible output:

+
1.0/0.0 == inf
+1.0/0.0 == HUGE_VAL

References

See also

+ +
+
(C99)
 evaluates to positive infinity or the value guaranteed to overflow a float
(macro constant)
C++ documentation for HUGE_VAL
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/HUGE_VAL +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fhypot.html b/devdocs/c/numeric%2Fmath%2Fhypot.html new file mode 100644 index 00000000..bd94e763 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fhypot.html @@ -0,0 +1,81 @@ +

hypot, hypotf, hypotl

Defined in header <math.h> 
float       hypotf( float x, float y );
+		 (1) (since C99) 
double      hypot( double x, double y );
+		 (2) (since C99) 
long double hypotl( long double x, long double y );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define hypot( x, y )
+		 (4) (since C99)
+1-3) Computes the square root of the sum of the squares of x and y, without undue overflow or underflow at intermediate stages of the computation.
+4) Type-generic macro: If any argument has type long double, the long double version of the function is called. Otherwise, if any argument has integer type or has type double, the double version of the function is called. Otherwise, the float version of the function is called.

The value computed by this function is the length of the hypotenuse of a right-angled triangle with sides of length x and y, or the distance of the point (x,y) from the origin (0,0), or the magnitude of a complex number x+iy.

+

Parameters

+ + +
x - floating point value
y - floating point value

Return value

If no errors occur, the hypotenuse of a right-angled triangle, \(\scriptsize{\sqrt{x^2+y^2} }\)√x2+y2, is returned.

+

If a range error due to overflow occurs, +HUGE_VAL, +HUGE_VALF, or +HUGE_VALL is returned.

+

If a range error due to underflow occurs, the correct result (after rounding) is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

Implementations usually guarantee precision of less than 1 ulp (units in the last place): GNU, BSD.

+

hypot(x, y) is equivalent to cabs(x + I*y).

+

POSIX specifies that underflow may only occur when both arguments are subnormal and the correct result is also subnormal (this forbids naive implementations).

+

hypot(INFINITY, NAN) returns +∞, but sqrt(INFINITY*INFINITY+NAN*NAN) returns NaN.

+

Example

#include <stdio.h>
+#include <math.h>
+#include <errno.h>
+#include <fenv.h>
+#include <float.h>
+ 
+// #pragma STDC FENV_ACCESS ON
+int main(void)
+{
+    // typical usage
+    printf("(1,1) cartesian is (%f,%f) polar\n", hypot(1,1), atan2(1,1));
+    // special values
+    printf("hypot(NAN,INFINITY) = %f\n", hypot(NAN,INFINITY));
+    // error handling 
+    errno = 0; feclearexcept(FE_ALL_EXCEPT);
+    printf("hypot(DBL_MAX,DBL_MAX) = %f\n", hypot(DBL_MAX,DBL_MAX));
+    if(errno == ERANGE)         perror("    errno == ERANGE");
+    if(fetestexcept(FE_OVERFLOW)) puts("    FE_OVERFLOW raised");
+}

Possible output:

+
(1,1) cartesian is (1.414214,0.785398) polar
+hypot(NAN,INFINITY) = inf
+hypot(DBL_MAX,DBL_MAX) = inf
+    errno == ERANGE: Numerical result out of range
+    FE_OVERFLOW raised

References

See also

+ + + + +
+
(C99)(C99)
 computes a number raised to the given power (\(\small{x^y}\)xy)
(function)
+
(C99)(C99)
 computes square root (\(\small{\sqrt{x} }\)√x)
(function)
+
(C99)(C99)(C99)
 computes cube root (\(\small{\sqrt[3]{x} }\)3√x)
(function)
+
(C99)(C99)(C99)
 computes the magnitude of a complex number
(function)
C++ documentation for hypot
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/hypot +

+
diff --git a/devdocs/c/numeric%2Fmath%2Filogb.html b/devdocs/c/numeric%2Fmath%2Filogb.html new file mode 100644 index 00000000..75847df0 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Filogb.html @@ -0,0 +1,91 @@ +

ilogb, ilogbf, ilogbl

Defined in header <math.h> 
int ilogbf( float arg );
+		 (1) (since C99) 
int ilogb( double arg );
+		 (2) (since C99) 
int ilogbl( long double arg );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define ilogb( arg )
+		 (4) (since C99)
Defined in header <math.h> 
#define FP_ILOGB0 /*implementation-defined*/
+		 (5) (since C99) 
#define FP_ILOGBNAN /*implementation-defined*/
+		 (6) (since C99)
+1-3) Extracts the value of the unbiased exponent from the floating-point argument arg, and returns it as a signed integer value.
+4) Type-generic macros: If arg has type long double, ilogbl is called. Otherwise, if arg has integer type or the type double, ilogb is called. Otherwise, ilogbf is called.
+5) Expands to integer constant expression whose value is either INT_MIN or -INT_MAX.
+6) Expands to integer constant expression whose value is either INT_MIN or +INT_MAX.

Formally, the unbiased exponent is the integral part of logr|arg| as a signed integral value, for non-zero arg, where r is FLT_RADIX.

+

Parameters

+ +
arg - floating point value

Return value

If no errors occur, the unbiased exponent of arg is returned as a signed int value.

+

If arg is zero, FP_ILOGB0 is returned.

+

If arg is infinite, INT_MAX is returned.

+

If arg is a NaN, FP_ILOGBNAN is returned.

+

If the correct result is greater than INT_MAX or smaller than INT_MIN, the return value is unspecified and a domain error or range error may occur

+

Error handling

Errors are reported as specified in math_errhandling.

+

A domain error or range error may occur if arg is zero, infinite, or NaN.

+

If the correct result is greater than INT_MAX or smaller than INT_MIN, a domain error or a range error may occur

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

If arg is not zero, infinite, or NaN, the value returned is exactly equivalent to (int)logb(arg).

+

POSIX requires that a domain error occurs if arg is zero, infinite, NaN, or if the correct result is outside of the range of int.

+

POSIX also requires that, on XSI-conformant systems, the value returned when the correct result is greater than INT_MAX is INT_MAX and the value returned when the correct result is less than INT_MIN is INT_MIN.

+

The correct result can be represented as int on all known implementations. For overflow to occur, INT_MAX must be less than LDBL_MAX_EXP*log2(FLT_RADIX) or INT_MIN must be greater than LDBL_MIN_EXP-LDBL_MANT_DIG)*log2(FLT_RADIX).

+

The value of the exponent returned by ilogb is always 1 less than the exponent retuned by frexp because of the different normalization requirements: for the exponent e returned by ilogb, |arg*r-e| is between 1 and r (typically between 1 and 2), but for the exponent e returned by frexp, |arg*2-e| is between 0.5 and 1.

+

Example

#include <stdio.h>
+#include <math.h>
+#include <float.h>
+#include <fenv.h>
+ 
+#pragma STDC FENV_ACCESS ON
+int main(void)
+{
+    double f = 123.45;
+    printf("Given the number %.2f or %a in hex,\n", f, f);
+ 
+    double f3;
+    double f2 = modf(f, &f3);
+    printf("modf() makes %.0f + %.2f\n", f3, f2);
+ 
+    int i;
+    f2 = frexp(f, &i);
+    printf("frexp() makes %f * 2^%d\n", f2, i);
+ 
+    i = ilogb(f);
+    printf("logb()/ilogb() make %f * %d^%d\n", f/scalbn(1.0, i), FLT_RADIX, i);
+ 
+    // error handling
+    feclearexcept(FE_ALL_EXCEPT);
+    printf("ilogb(0) = %d\n", ilogb(0));
+    if(fetestexcept(FE_INVALID)) puts("    FE_INVALID raised");
+}

Possible output:

+
Given the number 123.45 or 0x1.edccccccccccdp+6 in hex,
+modf() makes 123 + 0.45
+frexp() makes 0.964453 * 2^7
+logb()/ilogb() make 1.92891 * 2^6
+ilogb(0) = -2147483648
+    FE_INVALID raised

References

See also

+ + + +
+
(C99)(C99)
 breaks a number into significand and a power of 2
(function)
+
(C99)(C99)(C99)
 extracts exponent of the given number
(function)
+
(C99)(C99)(C99)(C99)(C99)(C99)
 computes efficiently a number times FLT_RADIX raised to a power
(function)
C++ documentation for ilogb
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/ilogb +

+
diff --git a/devdocs/c/numeric%2Fmath%2Finfinity.html b/devdocs/c/numeric%2Fmath%2Finfinity.html new file mode 100644 index 00000000..e9559f1f --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Finfinity.html @@ -0,0 +1,33 @@ +

INFINITY

Defined in header <math.h> 
#define INFINITY /*implementation defined*/
+		 (since C99)

If the implementation supports floating-point infinities, the macro INFINITY expands to constant expression of type float which evaluates to positive or unsigned infinity.

+

If the implementation does not support floating-point infinities, the macro INFINITY expands to a positive value that is guaranteed to overflow a float at compile time, and the use of this macro generates a compiler warning.

+

The style used to print an infinity is implementation defined.

+

Example

Show style used to print an infinity and IEEE format.

+
#include <stdio.h>
+#include <math.h>
+#include <stdint.h>
+#include <inttypes.h>
+#include <string.h>
+ 
+int main(void)
+{
+    double f = INFINITY;
+    uint64_t fn; memcpy(&fn, &f, sizeof f);
+    printf("INFINITY:   %f %" PRIx64 "\n", f, fn);
+}

Possible output:

+
INFINITY:   inf 7ff0000000000000

References

See also

+ + +
+
(C99)
 checks if the given number is infinite
(function macro)
+
(C99)(C99)
 indicates value too big to be representable (infinity) by float, double and long double respectively
(macro constant)
C++ documentation for INFINITY
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/INFINITY +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fisfinite.html b/devdocs/c/numeric%2Fmath%2Fisfinite.html new file mode 100644 index 00000000..f700b213 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fisfinite.html @@ -0,0 +1,44 @@ +

isfinite

Defined in header <math.h> 
#define isfinite(arg) /* implementation defined */
+		 (since C99)

Determines if the given floating point number arg has finite value i.e. it is normal, subnormal or zero, but not infinite or NaN. The macro returns an integral value.

+

FLT_EVAL_METHOD is ignored: even if the argument is evaluated with more range and precision than its type, it is first converted to its semantic type, and the classification is based on that.

+

Parameters

+ +
arg - floating point value

Return value

Nonzero integral value if arg has finite value, ​0​ otherwise.

+

Example

#include <stdio.h>
+#include <math.h>
+#include <float.h>
+ 
+int main(void)
+{
+    printf("isfinite(NAN)         = %d\n", isfinite(NAN));
+    printf("isfinite(INFINITY)    = %d\n", isfinite(INFINITY));
+    printf("isfinite(0.0)         = %d\n", isfinite(0.0));
+    printf("isfinite(DBL_MIN/2.0) = %d\n", isfinite(DBL_MIN/2.0));
+    printf("isfinite(1.0)         = %d\n", isfinite(1.0));
+    printf("isfinite(exp(800))    = %d\n", isfinite(exp(800)));
+}

Possible output:

+
isfinite(NAN)         = 0
+isfinite(INFINITY)    = 0
+isfinite(0.0)         = 1
+isfinite(DBL_MIN/2.0) = 1
+isfinite(1.0)         = 1
+isfinite(exp(800))    = 0

References

See also

+ + + + +
+
(C99)
 classifies the given floating-point value
(function macro)
+
(C99)
 checks if the given number is infinite
(function macro)
+
(C99)
 checks if the given number is NaN
(function macro)
+
(C99)
 checks if the given number is normal
(function macro)
C++ documentation for isfinite
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/isfinite +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fisgreater.html b/devdocs/c/numeric%2Fmath%2Fisgreater.html new file mode 100644 index 00000000..51bca156 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fisgreater.html @@ -0,0 +1,44 @@ +

isgreater

Defined in header <math.h> 
#define isgreater(x, y) /* implementation defined */
+		 (since C99)

Determines if the floating point number x is greater than the floating-point number (y), without setting floating-point exceptions.

+

Parameters

+ + +
x - floating point value
y - floating point value

Return value

Nonzero integral value if x > y, ​0​ otherwise.

+

Notes

The built-in operator> for floating-point numbers may set FE_INVALID if one or both of the arguments is NaN. This function is a "quiet" version of operator>.

+

Example

#include <stdio.h>
+#include <math.h>
+ 
+int main(void)
+{
+    printf("isgreater(2.0,1.0)      = %d\n", isgreater(2.0,1.0));
+    printf("isgreater(1.0,2.0)      = %d\n", isgreater(1.0,2.0));
+    printf("isgreater(INFINITY,1.0) = %d\n", isgreater(INFINITY,1.0));
+    printf("isgreater(1.0,NAN)      = %d\n", isgreater(1.0,NAN));
+ 
+    return 0;
+}

Possible output:

+
isgreater(2.0,1.0)      = 1
+isgreater(1.0,2.0)      = 0
+isgreater(INFINITY,1.0) = 1
+isgreater(1.0,NAN)      = 0

References

See also

+ +
+
(C99)
 checks if the first floating-point argument is less than the second
(function macro)
C++ documentation for isgreater
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/isgreater +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fisgreaterequal.html b/devdocs/c/numeric%2Fmath%2Fisgreaterequal.html new file mode 100644 index 00000000..d9c44c9c --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fisgreaterequal.html @@ -0,0 +1,41 @@ +

isgreaterequal

Defined in header <math.h> 
#define isgreaterequal(x, y) /* implementation defined */
+		 (since C99)

Determines if the floating point number x is greater than or equal to the floating-point number y, without setting floating-point exceptions.

+

Parameters

+ + +
x - floating point value
y - floating point value

Return value

Nonzero integral value if x >= y, ​0​ otherwise.

+

Notes

The built-in operator>= for floating-point numbers may raise FE_INVALID if one or both of the arguments is NaN. This function is a "quiet" version of operator>=.

+

Example

#include <stdio.h>
+#include <math.h>
+ 
+int main(void)
+{
+    printf("isgreaterequal(2.0,1.0)      = %d\n", isgreaterequal(2.0,1.0));
+    printf("isgreaterequal(1.0,2.0)      = %d\n", isgreaterequal(1.0,2.0));
+    printf("isgreaterequal(1.0,1.0)      = %d\n", isgreaterequal(1.0,1.0));
+    printf("isgreaterequal(INFINITY,1.0) = %d\n", isgreaterequal(INFINITY,1.0));
+    printf("isgreaterequal(1.0,NAN)      = %d\n", isgreaterequal(1.0,NAN));
+ 
+    return 0;
+}

Possible output:

+
isgreaterequal(2.0,1.0)      = 1
+isgreaterequal(1.0,2.0)      = 0
+isgreaterequal(1.0,1.0)      = 1
+isgreaterequal(INFINITY,1.0) = 1
+isgreaterequal(1.0,NAN)      = 0

References

See also

+ +
+
(C99)
 checks if the first floating-point argument is less or equal than the second
(function macro)
C++ documentation for isgreaterequal
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/isgreaterequal +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fisinf.html b/devdocs/c/numeric%2Fmath%2Fisinf.html new file mode 100644 index 00000000..57713b0e --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fisinf.html @@ -0,0 +1,46 @@ +

isinf

Defined in header <math.h> 
#define isinf(arg) /* implementation defined */
+		 (since C99)

Determines if the given floating-point number arg is positive or negative infinity. The macro returns an integral value.

+

FLT_EVAL_METHOD is ignored: even if the argument is evaluated with more range and precision than its type, it is first converted to its semantic type, and the classification is based on that.

+

Parameters

+ +
arg - floating-point value

Return value

Nonzero integral value if arg has an infinite value, ​0​ otherwise.

+

Example

#include <stdio.h>
+#include <math.h>
+#include <float.h>
+ 
+int main(void)
+{
+    printf("isinf(NAN)         = %d\n", isinf(NAN));
+    printf("isinf(INFINITY)    = %d\n", isinf(INFINITY));
+    printf("isinf(0.0)         = %d\n", isinf(0.0));
+    printf("isinf(DBL_MIN/2.0) = %d\n", isinf(DBL_MIN/2.0));
+    printf("isinf(1.0)         = %d\n", isinf(1.0));
+    printf("isinf(exp(800))    = %d\n", isinf(exp(800)));
+}

Possible output:

+
isinf(NAN)         = 0
+isinf(INFINITY)    = 1
+isinf(0.0)         = 0
+isinf(DBL_MIN/2.0) = 0
+isinf(1.0)         = 0
+isinf(exp(800))    = 1

References

See also

+ + + + +
+
(C99)
 classifies the given floating-point value
(function macro)
+
(C99)
 checks if the given number has finite value
(function macro)
+
(C99)
 checks if the given number is NaN
(function macro)
+
(C99)
 checks if the given number is normal
(function macro)
C++ documentation for isinf
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/isinf +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fisless.html b/devdocs/c/numeric%2Fmath%2Fisless.html new file mode 100644 index 00000000..8da4a04d --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fisless.html @@ -0,0 +1,39 @@ +

isless

Defined in header <math.h> 
#define isless(x, y) /* implementation defined */
+		 (since C99)

Determines if the floating point number x is less than the floating-point number y, without setting floating-point exceptions.

+

Parameters

+ + +
x - floating point value
y - floating point value

Return value

Nonzero integral value if x < y, ​0​ otherwise.

+

Notes

The built-in operator< for floating-point numbers may raise FE_INVALID if one or both of the arguments is NaN. This function is a "quiet" version of operator<.

+

Example

#include <stdio.h>
+#include <math.h>
+ 
+int main(void)
+{
+    printf("isless(2.0,1.0)      = %d\n", isless(2.0,1.0));
+    printf("isless(1.0,2.0)      = %d\n", isless(1.0,2.0));
+    printf("isless(INFINITY,1.0) = %d\n", isless(INFINITY,1.0));
+    printf("isless(1.0,NAN)      = %d\n", isless(1.0,NAN));
+ 
+    return 0;
+}

Possible output:

+
isless(2.0,1.0)      = 0
+isless(1.0,2.0)      = 1
+isless(INFINITY,1.0) = 0
+isless(1.0,NAN)      = 0

References

See also

+ +
+
(C99)
 checks if the first floating-point argument is greater than the second
(function macro)
C++ documentation for isless
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/isless +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fislessequal.html b/devdocs/c/numeric%2Fmath%2Fislessequal.html new file mode 100644 index 00000000..588f3473 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fislessequal.html @@ -0,0 +1,41 @@ +

islessequal

Defined in header <math.h> 
#define islessequal(x, y) /* implementation defined */
+		 (since C99)

Determines if the floating point number x is less than or equal to the floating-point number y, without setting floating-point exceptions.

+

Parameters

+ + +
x - floating point value
y - floating point value

Return value

Nonzero integral value if x <= y, ​0​ otherwise.

+

Notes

The built-in operator<= for floating-point numbers may raise FE_INVALID if one or both of the arguments is NaN. This function is a "quiet" version of operator<=.

+

Example

#include <stdio.h>
+#include <math.h>
+ 
+int main(void)
+{
+    printf("islessequal(2.0,1.0)      = %d\n", islessequal(2.0,1.0));
+    printf("islessequal(1.0,2.0)      = %d\n", islessequal(1.0,2.0));
+    printf("islessequal(1.0,1.0)      = %d\n", islessequal(1.0,1.0));
+    printf("islessequal(INFINITY,1.0) = %d\n", islessequal(INFINITY,1.0));
+    printf("islessequal(1.0,NAN)      = %d\n", islessequal(1.0,NAN));
+ 
+    return 0;
+}

Possible output:

+
islessequal(2.0,1.0)      = 0
+islessequal(1.0,2.0)      = 1
+islessequal(1.0,1.0)      = 1
+islessequal(INFINITY,1.0) = 0
+islessequal(1.0,NAN)      = 0

References

See also

+ +
+
(C99)
 checks if the first floating-point argument is greater or equal than the second
(function macro)
C++ documentation for islessequal
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/islessequal +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fislessgreater.html b/devdocs/c/numeric%2Fmath%2Fislessgreater.html new file mode 100644 index 00000000..a508962c --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fislessgreater.html @@ -0,0 +1,43 @@ +

islessgreater

Defined in header <math.h> 
#define islessgreater(x, y) /* implementation defined */
+		 (since C99)

Determines if the floating point number x is less than or greater than the floating-point number y, without setting floating-point exceptions.

+

Parameters

+ + +
x - floating point value
y - floating point value

Return value

Nonzero integral value if x < y || x > y, ​0​ otherwise.

+

Notes

The built-in operator< and operator> for floating-point numbers may raise FE_INVALID if one or both of the arguments is NaN. This function is a "quiet" version of the expression x < y || x > y. The macro does not evaluate x and y twice.

+

Example

#include <stdio.h>
+#include <math.h>
+ 
+int main(void)
+{
+    printf("islessgreater(2.0,1.0)      = %d\n", islessgreater(2.0,1.0));
+    printf("islessgreater(1.0,2.0)      = %d\n", islessgreater(1.0,2.0));
+    printf("islessgreater(1.0,1.0)      = %d\n", islessgreater(1.0,1.0));
+    printf("islessgreater(INFINITY,1.0) = %d\n", islessgreater(INFINITY,1.0));
+    printf("islessgreater(1.0,NAN)      = %d\n", islessgreater(1.0,NAN));
+ 
+    return 0;
+}

Possible output:

+
islessgreater(2.0,1.0)      = 1
+islessgreater(1.0,2.0)      = 1
+islessgreater(1.0,1.0)      = 0
+islessgreater(INFINITY,1.0) = 1
+islessgreater(1.0,NAN)      = 0

References

See also

+ + +
+
(C99)
 checks if the first floating-point argument is less than the second
(function macro)
+
(C99)
 checks if the first floating-point argument is greater than the second
(function macro)
C++ documentation for islessgreater
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/islessgreater +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fisnan.html b/devdocs/c/numeric%2Fmath%2Fisnan.html new file mode 100644 index 00000000..f9b432de --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fisnan.html @@ -0,0 +1,51 @@ +

isnan

Defined in header <math.h> 
#define isnan(arg) /* implementation defined */
+		 (since C99)

Determines if the given floating point number arg is a not-a-number (NaN) value. The macro returns an integral value.

+

FLT_EVAL_METHOD is ignored: even if the argument is evaluated with more range and precision than its type, it is first converted to its semantic type, and the classification is based on that (this matters if the evaluation type supports NaNs, while the semantic type does not).

+

Parameters

+ +
arg - floating point value

Return value

Nonzero integral value if arg is a NaN, ​0​ otherwise.

+

Notes

There are many different NaN values with different sign bits and payloads, see nan.

+

NaN values never compare equal to themselves or to other NaN values. Copying a NaN may change its bit pattern.

+

Another way to test if a floating-point value is NaN is to compare it with itself: bool is_nan(double x) { return x != x; }

+

Example

#include <stdio.h>
+#include <math.h>
+#include <float.h>
+ 
+int main(void)
+{
+    printf("isnan(NAN)         = %d\n", isnan(NAN));
+    printf("isnan(INFINITY)    = %d\n", isnan(INFINITY));
+    printf("isnan(0.0)         = %d\n", isnan(0.0));
+    printf("isnan(DBL_MIN/2.0) = %d\n", isnan(DBL_MIN/2.0));
+    printf("isnan(0.0 / 0.0)   = %d\n", isnan(0.0/0.0));
+    printf("isnan(Inf - Inf)   = %d\n", isnan(INFINITY - INFINITY));
+}

Possible output:

+
isnan(NAN)         = 1
+isnan(INFINITY)    = 0
+isnan(0.0)         = 0
+isnan(DBL_MIN/2.0) = 0
+isnan(0.0 / 0.0)   = 1
+isnan(Inf - Inf)   = 1

References

See also

+ + + + + + +
+
(C99)(C99)(C99)
 returns a NaN (not-a-number)
(function)
+
(C99)
 classifies the given floating-point value
(function macro)
+
(C99)
 checks if the given number has finite value
(function macro)
+
(C99)
 checks if the given number is infinite
(function macro)
+
(C99)
 checks if the given number is normal
(function macro)
+
(C99)
 checks if two floating-point values are unordered
(function macro)
C++ documentation for isnan
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/isnan +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fisnormal.html b/devdocs/c/numeric%2Fmath%2Fisnormal.html new file mode 100644 index 00000000..0a2a19cd --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fisnormal.html @@ -0,0 +1,42 @@ +

isnormal

Defined in header <math.h> 
#define isnormal(arg) /* implementation defined */
+		 (since C99)

Determines if the given floating point number arg is normal, i.e. is neither zero, subnormal, infinite, nor NaN. The macro returns an integral value.

+

FLT_EVAL_METHOD is ignored: even if the argument is evaluated with more range and precision than its type, it is first converted to its semantic type, and the classification is based on that.

+

Parameters

+ +
arg - floating point value

Return value

Nonzero integral value if arg is normal, ​0​ otherwise.

+

Example

#include <stdio.h>
+#include <math.h>
+#include <float.h>
+ 
+int main(void)
+{
+    printf("isnormal(NAN)         = %d\n", isnormal(NAN));
+    printf("isnormal(INFINITY)    = %d\n", isnormal(INFINITY));
+    printf("isnormal(0.0)         = %d\n", isnormal(0.0));
+    printf("isnormal(DBL_MIN/2.0) = %d\n", isnormal(DBL_MIN/2.0));
+    printf("isnormal(1.0)         = %d\n", isnormal(1.0));
+}

Output:

+
isnormal(NAN)         = 0
+isnormal(INFINITY)    = 0
+isnormal(0.0)         = 0
+isnormal(DBL_MIN/2.0) = 0
+isnormal(1.0)         = 1

References

See also

+ + + + +
+
(C99)
 classifies the given floating-point value
(function macro)
+
(C99)
 checks if the given number has finite value
(function macro)
+
(C99)
 checks if the given number is infinite
(function macro)
+
(C99)
 checks if the given number is NaN
(function macro)
C++ documentation for isnormal
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/isnormal +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fisunordered.html b/devdocs/c/numeric%2Fmath%2Fisunordered.html new file mode 100644 index 00000000..5341387f --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fisunordered.html @@ -0,0 +1,40 @@ +

isunordered

Defined in header <math.h> 
#define isunordered(x, y) /* implementation defined */
+		 (since C99)

Determines if the floating point numbers x and y are unordered, that is, one or both are NaN and thus cannot be meaningfully compared with each other.

+

Parameters

+ + +
x - floating point value
y - floating point value

Return value

Nonzero integral value if either x or y is NaN, ​0​ otherwise.

+

Example

#include <stdio.h>
+#include <math.h>
+ 
+int main(void)
+{
+    printf("isunordered(NAN,1.0) = %d\n", isunordered(NAN,1.0));
+    printf("isunordered(1.0,NAN) = %d\n", isunordered(1.0,NAN));
+    printf("isunordered(NAN,NAN) = %d\n", isunordered(NAN,NAN));
+    printf("isunordered(1.0,0.0) = %d\n", isunordered(1.0,0.0));
+ 
+    return 0;
+}

Possible output:

+
isunordered(NAN,1.0) = 1
+isunordered(1.0,NAN) = 1
+isunordered(NAN,NAN) = 1
+isunordered(1.0,0.0) = 0

References

See also

+ + +
+
(C99)
 classifies the given floating-point value
(function macro)
+
(C99)
 checks if the given number is NaN
(function macro)
C++ documentation for isunordered
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/isunordered +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fldexp.html b/devdocs/c/numeric%2Fmath%2Fldexp.html new file mode 100644 index 00000000..b2e09059 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fldexp.html @@ -0,0 +1,79 @@ +

ldexp, ldexpf, ldexpl

Defined in header <math.h> 
float       ldexpf( float arg, int exp );
+		 (1) (since C99) 
double      ldexp( double arg, int exp );
+		 (2) 
long double ldexpl( long double arg, int exp );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define ldexp( arg, exp )
+		 (4) (since C99)
+1-3) Multiplies a floating point value arg by the number 2 raised to the exp power.
+4) Type-generic macro: If arg has type long double, ldexpl is called. Otherwise, if arg has integer type or the type double, ldexp is called. Otherwise, ldexpf is called, respectively.

Parameters

+ + +
arg - floating point value
exp - integer value

Return value

If no errors occur, arg multiplied by 2 to the power of exp (arg×2exp) is returned.

+

If a range error due to overflow occurs, ±HUGE_VAL, ±HUGE_VALF, or ±HUGE_VALL is returned.

+

If a range error due to underflow occurs, the correct result (after rounding) is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

On binary systems (where FLT_RADIX is 2), ldexp is equivalent to scalbn.

+

The function ldexp ("load exponent"), together with its dual, frexp, can be used to manipulate the representation of a floating-point number without direct bit manipulations.

+

On many implementations, ldexp is less efficient than multiplication or division by a power of two using arithmetic operators.

+

Example

#include <stdio.h>
+#include <math.h>
+#include <float.h>
+#include <errno.h>
+#include <fenv.h>
+#pragma STDC FENV_ACCESS ON
+int main(void)
+{
+    printf("ldexp(7, -4) = %f\n", ldexp(7, -4));
+    printf("ldexp(1, -1074) = %g (minimum positive subnormal double)\n",
+            ldexp(1, -1074));
+    printf("ldexp(nextafter(1,0), 1024) = %g (largest finite double)\n",
+            ldexp(nextafter(1,0), 1024));
+    // special values
+    printf("ldexp(-0, 10) = %f\n", ldexp(-0.0, 10));
+    printf("ldexp(-Inf, -1) = %f\n", ldexp(-INFINITY, -1));
+    //error handling
+    errno = 0; feclearexcept(FE_ALL_EXCEPT);
+    printf("ldexp(1, 1024) = %f\n", ldexp(1, 1024));
+    if(errno == ERANGE) perror("    errno == ERANGE");
+    if(fetestexcept(FE_OVERFLOW)) puts("    FE_OVERFLOW raised");
+}

Possible output:

+
ldexp(7, -4) = 0.437500
+ldexp(1, -1074) = 4.94066e-324 (minimum positive subnormal double)
+ldexp(nextafter(1,0), 1024) = 1.79769e+308 (largest finite double)
+ldexp(-0, 10) = -0.000000
+ldexp(-Inf, -1) = -inf
+ldexp(1, 1024) = inf
+    errno == ERANGE: Numerical result out of range
+    FE_OVERFLOW raised

References

See also

+ + +
+
(C99)(C99)
 breaks a number into significand and a power of 2
(function)
+
(C99)(C99)(C99)(C99)(C99)(C99)
 computes efficiently a number times FLT_RADIX raised to a power
(function)
C++ documentation for ldexp
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/ldexp +

+
diff --git a/devdocs/c/numeric%2Fmath%2Flgamma.html b/devdocs/c/numeric%2Fmath%2Flgamma.html new file mode 100644 index 00000000..5dbfcbd3 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Flgamma.html @@ -0,0 +1,85 @@ +

lgamma, lgammaf, lgammal

Defined in header <math.h> 
float       lgammaf( float arg );
+		 (1) (since C99) 
double      lgamma( double arg );
+		 (2) (since C99) 
long double lgammal( long double arg );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define lgamma( arg )
+		 (4) (since C99)
+1-3) Computes the natural logarithm of the absolute value of the gamma function of arg.
+4) Type-generic macro: If arg has type long double, lgammal is called. Otherwise, if arg has integer type or the type double, lgamma is called. Otherwise, lgammaf is called.

Parameters

+ +
arg - floating point value

Return value

If no errors occur, the value of the logarithm of the gamma function of arg, that is \(\log_{e}|{\int_0^\infty t^{arg-1} e^{-t} \mathsf{d}t}|\)loge|∫∞0targ-1 e-t dt|, is returned.

+

If a pole error occurs, +HUGE_VAL, +HUGE_VALF, or +HUGE_VALL is returned.

+

If a range error due to overflow occurs, ±HUGE_VAL, ±HUGE_VALF, or ±HUGE_VALL is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

If arg is zero or is an integer less than zero, a pole error may occur.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

If arg is a natural number, lgamma(arg) is the logarithm of the factorial of arg - 1.

+

The POSIX version of lgamma is not thread-safe: each execution of the function stores the sign of the gamma function of arg in the static external variable signgam. Some implementations provide lgamma_r, which takes a pointer to user-provided storage for singgam as the second parameter, and is thread-safe.

+

There is a non-standard function named gamma in various implementations, but its definition is inconsistent. For example, glibc and 4.2BSD version of gamma executes lgamma, but 4.4BSD version of gamma executes tgamma.

+

Example

#include <stdio.h>
+#include <math.h>
+#include <float.h>
+#include <errno.h>
+#include <fenv.h>
+// #pragma STDC FENV_ACCESS ON
+ 
+int main(void)
+{
+    printf("lgamma(10) = %f, log(9!) = %f\n", lgamma(10), log(2*3*4*5*6*7*8*9));
+    const double pi = acos(-1);
+    printf("lgamma(0.5) = %f, log(sqrt(pi)) = %f\n", log(sqrt(pi)), lgamma(0.5));
+    // special values
+    printf("lgamma(1) = %f\n", lgamma(1));
+    printf("lgamma(+Inf) = %f\n", lgamma(INFINITY));
+ 
+    // error handling
+    errno = 0; feclearexcept(FE_ALL_EXCEPT);
+    printf("lgamma(0) = %f\n", lgamma(0));
+    if (errno == ERANGE)
+        perror("    errno == ERANGE");
+    if (fetestexcept(FE_DIVBYZERO))
+        puts("    FE_DIVBYZERO raised");
+}

Possible output:

+
lgamma(10) = 12.801827, log(9!) = 12.801827
+lgamma(0.5) = 0.572365, log(sqrt(pi)) = 0.572365
+lgamma(1) = 0.000000
+lgamma(+Inf) = inf
+lgamma(0) = inf
+    errno == ERANGE: Numerical result out of range
+    FE_DIVBYZERO raised

References

See also

+ +
+
(C99)(C99)(C99)
 computes gamma function
(function)
C++ documentation for lgamma
+ +
+Weisstein, Eric W. "Log Gamma Function." From MathWorld — A Wolfram Web Resource.
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/lgamma +

+
diff --git a/devdocs/c/numeric%2Fmath%2Flog.html b/devdocs/c/numeric%2Fmath%2Flog.html new file mode 100644 index 00000000..297dca2b --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Flog.html @@ -0,0 +1,84 @@ +

log, logf, logl

Defined in header <math.h> 
float       logf( float arg );
+		 (1) (since C99) 
double      log( double arg );
+		 (2) 
long double logl( long double arg );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define log( arg )
+		 (4) (since C99)
+1-3) Computes the natural (base e) logarithm of arg.
+4) Type-generic macro: If arg has type long double, logl is called. Otherwise, if arg has integer type or the type double, log is called. Otherwise, logf is called. If arg is complex or imaginary, then the macro invokes the corresponding complex function (clogf, clog, clogl).

Parameters

+ +
arg - floating point value

Return value

If no errors occur, the natural (base-e) logarithm of arg (ln(arg) or loge(arg)) is returned.

+

If a domain error occurs, an implementation-defined value is returned (NaN where supported).

+

If a pole error occurs, -HUGE_VAL, -HUGE_VALF, or -HUGE_VALL is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

Domain error occurs if arg is less than zero.

+

Pole error may occur if arg is zero.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Example

#include <stdio.h>
+#include <math.h>
+#include <float.h>
+#include <errno.h>
+#include <fenv.h>
+// #pragma STDC FENV_ACCESS ON
+int main(void)
+{
+    printf("log(1) = %f\n", log(1));
+    printf("base-5 logarithm of 125 = %f\n", log(125)/log(5));
+    // special values
+    printf("log(1) = %f\n", log(1));
+    printf("log(+Inf) = %f\n", log(INFINITY));
+    //error handling
+    errno = 0; feclearexcept(FE_ALL_EXCEPT);
+    printf("log(0) = %f\n", log(0));
+    if(errno == ERANGE) perror("    errno == ERANGE");
+    if(fetestexcept(FE_DIVBYZERO)) puts("    FE_DIVBYZERO raised");
+}

Output:

+
log(1) = 0.000000
+base-5 logarithm of 125 = 3.000000
+log(1) = 0.000000
+log(+Inf) = inf
+log(0) = -inf
+    errno == ERANGE: Numerical result out of range
+    FE_DIVBYZERO raised

References

See also

+ + + + + +
+
(C99)(C99)
 computes common (base-10) logarithm (\({\small \log_{10}{x} }\)log10(x))
(function)
+
(C99)(C99)(C99)
 computes base-2 logarithm (\({\small \log_{2}{x} }\)log2(x))
(function)
+
(C99)(C99)(C99)
 computes natural (base-e) logarithm of 1 plus the given number (\({\small \ln{(1+x)} }\)ln(1+x))
(function)
+
(C99)(C99)
 computes e raised to the given power (\({\small e^x}\)ex)
(function)
+
(C99)(C99)(C99)
 computes the complex natural logarithm
(function)
C++ documentation for log
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/log +

+
diff --git a/devdocs/c/numeric%2Fmath%2Flog10.html b/devdocs/c/numeric%2Fmath%2Flog10.html new file mode 100644 index 00000000..5f9bfc00 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Flog10.html @@ -0,0 +1,83 @@ +

log10, log10f, log10l

Defined in header <math.h> 
float       log10f( float arg );
+		 (1) (since C99) 
double      log10( double arg );
+		 (2) 
long double log10l( long double arg );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define log10( arg )
+		 (4) (since C99)
+1-3) Computes the common (base-10) logarithm of arg.
+4) Type-generic macro: If arg has type long double, log10l is called. Otherwise, if arg has integer type or the type double, log10 is called. Otherwise, log10f is called.

Parameters

+ +
arg - floating point value

Return value

If no errors occur, the common (base-10) logarithm of arg (log10(arg) or lg(arg)) is returned.

+

If a domain error occurs, an implementation-defined value is returned (NaN where supported).

+

If a pole error occurs, -HUGE_VAL, -HUGE_VALF, or -HUGE_VALL is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

Domain error occurs if arg is less than zero.

+

Pole error may occur if arg is zero.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Example

#include <stdio.h>
+#include <math.h>
+#include <float.h>
+#include <errno.h>
+#include <fenv.h>
+ 
+// #pragma STDC FENV_ACCESS ON
+int main(void)
+{
+    printf("log10(1000) = %f\n", log10(1000));
+    printf("log10(0.001) = %f\n", log10(0.001));
+    printf("base-5 logarithm of 125 = %f\n", log10(125)/log10(5));
+    // special values
+    printf("log10(1) = %f\n", log10(1));
+    printf("log10(+Inf) = %f\n", log10(INFINITY));
+    //error handling
+    errno = 0; feclearexcept(FE_ALL_EXCEPT);
+    printf("log10(0) = %f\n", log10(0));
+    if(errno == ERANGE) perror("    errno == ERANGE");
+    if(fetestexcept(FE_DIVBYZERO)) puts("    FE_DIVBYZERO raised");
+}

Possible output:

+
log10(1000) = 3.000000
+log10(0.001) = -3.000000
+base-5 logarithm of 125 = 3.000000
+log10(1) = 0.000000
+log10(+Inf) = inf
+log10(0) = -inf
+    errno == ERANGE: Numerical result out of range
+    FE_DIVBYZERO raised

References

See also

+ + + +
+
(C99)(C99)
 computes natural (base-e) logarithm (\({\small \ln{x} }\)ln(x))
(function)
+
(C99)(C99)(C99)
 computes base-2 logarithm (\({\small \log_{2}{x} }\)log2(x))
(function)
+
(C99)(C99)(C99)
 computes natural (base-e) logarithm of 1 plus the given number (\({\small \ln{(1+x)} }\)ln(1+x))
(function)
C++ documentation for log10
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/log10 +

+
diff --git a/devdocs/c/numeric%2Fmath%2Flog1p.html b/devdocs/c/numeric%2Fmath%2Flog1p.html new file mode 100644 index 00000000..792b8a08 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Flog1p.html @@ -0,0 +1,82 @@ +

log1p, log1pf, log1pl

Defined in header <math.h> 
float       log1pf( float arg );
+		 (1) (since C99) 
double      log1p( double arg );
+		 (2) (since C99) 
long double log1pl( long double arg );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define log1p( arg )
+		 (4) (since C99)
+1-3) Computes the natural (base e) logarithm of 1+arg. This function is more precise than the expression log(1+arg) if arg is close to zero.
+4) Type-generic macro: If arg has type long double, log1pl is called. Otherwise, if arg has integer type or the type double, log1p is called. Otherwise, log1pf is called.

Parameters

+ +
arg - floating point value

Return value

If no errors occur ln(1+arg) is returned.

+

If a domain error occurs, an implementation-defined value is returned (NaN where supported).

+

If a pole error occurs, -HUGE_VAL, -HUGE_VALF, or -HUGE_VALL is returned.

+

If a range error occurs due to underflow, the correct result (after rounding) is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

Domain error occurs if arg is less than -1.

+

Pole error may occur if arg is -1.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

The functions expm1 and log1p are useful for financial calculations, for example, when calculating small daily interest rates: (1+x)n-1 can be expressed as expm1(n * log1p(x)). These functions also simplify writing accurate inverse hyperbolic functions.

+

Example

#include <stdio.h>
+#include <math.h>
+#include <float.h>
+#include <errno.h>
+#include <fenv.h>
+#pragma STDC FENV_ACCESS ON
+int main(void)
+{
+    printf("log1p(0) = %f\n", log1p(0));
+    printf("Interest earned in 2 days on $100, compounded daily at 1%%\n"
+           " on a 30/360 calendar = %f\n",
+           100*expm1(2*log1p(0.01/360)));
+    printf("log(1+1e-16) = %g, but log1p(1e-16) = %g\n",
+           log(1+1e-16), log1p(1e-16));
+    // special values
+    printf("log1p(-0) = %f\n", log1p(-0.0));
+    printf("log1p(+Inf) = %f\n", log1p(INFINITY));
+    //error handling
+    errno = 0; feclearexcept(FE_ALL_EXCEPT);
+    printf("log1p(-1) = %f\n", log1p(-1));
+    if(errno == ERANGE) perror("    errno == ERANGE");
+    if(fetestexcept(FE_DIVBYZERO)) puts("    FE_DIVBYZERO raised");
+}

Possible output:

+
log1p(0) = 0.000000
+Interest earned in 2 days on $100, compounded daily at 1%
+ on a 30/360 calendar = 0.005556
+log(1+1e-16) = 0, but log1p(1e-16) = 1e-16
+log1p(-0) = -0.000000
+log1p(+Inf) = Inf
+log1p(-1) = -Inf
+    errno == ERANGE: Result too large
+    FE_DIVBYZERO raised

References

See also

+ + + + +
+
(C99)(C99)
 computes natural (base-e) logarithm (\({\small \ln{x} }\)ln(x))
(function)
+
(C99)(C99)
 computes common (base-10) logarithm (\({\small \log_{10}{x} }\)log10(x))
(function)
+
(C99)(C99)(C99)
 computes base-2 logarithm (\({\small \log_{2}{x} }\)log2(x))
(function)
+
(C99)(C99)(C99)
 computes e raised to the given power, minus one (\({\small e^x-1}\)ex-1)
(function)
C++ documentation for log1p
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/log1p +

+
diff --git a/devdocs/c/numeric%2Fmath%2Flog2.html b/devdocs/c/numeric%2Fmath%2Flog2.html new file mode 100644 index 00000000..14c569b3 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Flog2.html @@ -0,0 +1,85 @@ +

log2, log2f, log2l

Defined in header <math.h> 
float       log2f( float arg );
+		 (1) (since C99) 
double      log2( double arg );
+		 (2) (since C99) 
long double log2l( long double arg );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define log2( arg )
+		 (4) (since C99)
+1-3) Computes the base 2 logarithm of arg.
+4) Type-generic macro: If arg has type long double, log2l is called. Otherwise, if arg has integer type or the type double, log2 is called. Otherwise, log2f is called.

Parameters

+ +
arg - floating point value

Return value

If no errors occur, the base-2 logarithm of arg (log2(arg) or lb(arg)) is returned.

+

If a domain error occurs, an implementation-defined value is returned (NaN where supported).

+

If a pole error occurs, -HUGE_VAL, -HUGE_VALF, or -HUGE_VALL is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

Domain error occurs if arg is less than zero.

+

Pole error may occur if arg is zero.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

For integer arg, the binary logarithm can be interpreted as the zero-based index of the most significant 1 bit in the input.

+

Example

#include <stdio.h>
+#include <math.h>
+#include <float.h>
+#include <errno.h>
+#include <fenv.h>
+// #pragma STDC FENV_ACCESS ON
+int main(void)
+{
+    printf("log2(65536) = %f\n", log2(65536));
+    printf("log2(0.125) = %f\n", log2(0.125));
+    printf("log2(0x020f) = %f (highest set bit is in position 9)\n", log2(0x020f));
+    printf("base-5 logarithm of 125 = %f\n", log2(125)/log2(5));
+    // special values
+    printf("log2(1) = %f\n", log2(1));
+    printf("log2(+Inf) = %f\n", log2(INFINITY));
+    //error handling
+    errno = 0; feclearexcept(FE_ALL_EXCEPT);
+    printf("log2(0) = %f\n", log2(0));
+    if(errno == ERANGE) perror("    errno == ERANGE");
+    if(fetestexcept(FE_DIVBYZERO)) puts("    FE_DIVBYZERO raised");
+}

Possible output:

+
log2(65536) = 16.000000
+log2(0.125) = -3.000000
+log2(0x020f) = 9.041659 (highest set bit is in position 9)
+base-5 logarithm of 125 = 3.000000
+log2(1) = 0.000000
+log2(+Inf) = inf
+log2(0) = -inf
+    errno == ERANGE: Numerical result out of range
+    FE_DIVBYZERO raised

References

See also

+ + + + +
+
(C99)(C99)
 computes natural (base-e) logarithm (\({\small \ln{x} }\)ln(x))
(function)
+
(C99)(C99)
 computes common (base-10) logarithm (\({\small \log_{10}{x} }\)log10(x))
(function)
+
(C99)(C99)(C99)
 computes natural (base-e) logarithm of 1 plus the given number (\({\small \ln{(1+x)} }\)ln(1+x))
(function)
+
(C99)(C99)(C99)
 computes 2 raised to the given power (\({\small 2^x}\)2x)
(function)
C++ documentation for log2
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/log2 +

+
diff --git a/devdocs/c/numeric%2Fmath%2Flogb.html b/devdocs/c/numeric%2Fmath%2Flogb.html new file mode 100644 index 00000000..79b5b473 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Flogb.html @@ -0,0 +1,88 @@ +

logb, logbf, logbl

Defined in header <math.h> 
float       logbf( float arg );
+		 (1) (since C99) 
double      logb( double arg );
+		 (2) (since C99) 
long double logbl( long double arg );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define logb( arg )
+		 (4) (since C99)
+1-3) Extracts the value of the unbiased radix-independent exponent from the floating-point argument arg, and returns it as a floating-point value.
+4) Type-generic macros: If arg has type long double, logbl is called. Otherwise, if arg has integer type or the type double, logb is called. Otherwise, logbf is called.

Formally, the unbiased exponent is the signed integral part of logr|arg| (returned by this function as a floating-point value), for non-zero arg, where r is FLT_RADIX. If arg is subnormal, it is treated as though it was normalized.

+

Parameters

+ +
arg - floating point value

Return value

If no errors occur, the unbiased exponent of arg is returned as a signed floating-point value.

+

If a domain error occurs, an implementation-defined value is returned

+

If a pole error occurs, -HUGE_VAL, -HUGE_VALF, or -HUGE_VALL is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

Domain or range error may occur if arg is zero.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

POSIX requires that a pole error occurs if arg is ±0.

+

The value of the exponent returned by logb is always 1 less than the exponent retuned by frexp because of the different normalization requirements: for the exponent e returned by logb, |arg*r-e| is between 1 and r (typically between 1 and 2), but for the exponent e returned by frexp, |arg*2-e| is between 0.5 and 1.

+

Example

+

Compares different floating-point decomposition functions.

+
#include <stdio.h>
+#include <math.h>
+#include <float.h>
+#include <fenv.h>
+ 
+// #pragma STDC FENV_ACCESS ON
+int main(void)
+{
+    double f = 123.45;
+    printf("Given the number %.2f or %a in hex,\n", f, f);
+ 
+    double f3;
+    double f2 = modf(f, &f3);
+    printf("modf() makes %.0f + %.2f\n", f3, f2);
+ 
+    int i;
+    f2 = frexp(f, &i);
+    printf("frexp() makes %f * 2^%d\n", f2, i);
+ 
+    i = logb(f);
+    printf("logb()/logb() make %f * %d^%d\n", f/scalbn(1.0, i), FLT_RADIX, i);
+ 
+    // error handling
+    feclearexcept(FE_ALL_EXCEPT);
+    printf("logb(0) = %f\n", logb(0));
+    if(fetestexcept(FE_DIVBYZERO)) puts("    FE_DIVBYZERO raised");
+}

Possible output:

+
Given the number 123.45 or 0x1.edccccccccccdp+6 in hex,
+modf() makes 123 + 0.45
+frexp() makes 0.964453 * 2^7
+logb()/logb() make 1.928906 * 2^6
+logb(0) = -Inf
+    FE_DIVBYZERO raised

References

See also

+ + + +
+
(C99)(C99)
 breaks a number into significand and a power of 2
(function)
+
(C99)(C99)(C99)
 extracts exponent of the given number
(function)
+
(C99)(C99)(C99)(C99)(C99)(C99)
 computes efficiently a number times FLT_RADIX raised to a power
(function)
C++ documentation for logb
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/logb +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fmath_errhandling.html b/devdocs/c/numeric%2Fmath%2Fmath_errhandling.html new file mode 100644 index 00000000..49d3048d --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fmath_errhandling.html @@ -0,0 +1,81 @@ +

MATH_ERRNO, MATH_ERREXCEPT, math_errhandling

Defined in header <math.h> 
#define MATH_ERRNO        1
+		 (since C99) 
#define MATH_ERREXCEPT    2
+		 (since C99) 
#define math_errhandling  /*implementation defined*/
+		 (since C99)

The macro constant math_errhandling expands to an expression of type int that is either equal to MATH_ERRNO, or equal to MATH_ERREXCEPT, or equal to their bitwise OR (MATH_ERRNO | MATH_ERREXCEPT).

+

The value of math_errhandling indicates the type of error handling that is performed by the floating-point operators and functions:

+ + + +
Constant Explanation
MATH_ERREXCEPT indicates that floating-point exceptions are used: at least FE_DIVBYZERO, FE_INVALID, and FE_OVERFLOW are defined in <fenv.h>.
MATH_ERRNO indicates that floating-point operations use the variable errno to report errors.

If the implementation supports IEEE floating-point arithmetic (IEC 60559), math_errhandling & MATH_ERREXCEPT is required to be non-zero.

+

The following floating-point error conditions are recognized:

+ + + + + + + +
Condition Explanation errno floating-point exception Example
Domain error the argument is outside the range in which the operation is mathematically defined (the description of each function lists the required domain errors) +EDOM +FE_INVALID +acos(2)
Pole error the mathematical result of the function is exactly infinite or undefined +ERANGE +FE_DIVBYZERO +log(0.0), 1.0/0.0
Range error due to overflow the mathematical result is finite, but becomes infinite after rounding, or becomes the largest representable finite value after rounding down +ERANGE +FE_OVERFLOW +pow(DBL_MAX,2)
Range error due to underflow the result is non-zero, but becomes zero after rounding, or becomes subnormal with a loss of precision +ERANGE or unchanged (implementation-defined) +FE_UNDERFLOW or nothing (implementation-defined) +DBL_TRUE_MIN/2
Inexact result the result has to be rounded to fit in the destination type unchanged +FE_INEXACT or nothing (unspecified) +sqrt(2), 1.0/10.0

Notes

Whether FE_INEXACT is raised by the mathematical library functions is unspecified in general, but may be explicitly specified in the description of the function (e.g. rint vs nearbyint).

+

Before C99, floating-point exceptions were not specified, EDOM was required for any domain error, ERANGE was required for overflows and implementation-defined for underflows.

+

Example

#include <stdio.h>
+#include <fenv.h>
+#include <math.h>
+#include <errno.h>
+#pragma STDC FENV_ACCESS ON
+int main(void)
+{
+    printf("MATH_ERRNO is %s\n", math_errhandling & MATH_ERRNO ? "set" : "not set");
+    printf("MATH_ERREXCEPT is %s\n",
+           math_errhandling & MATH_ERREXCEPT ? "set" : "not set");
+    feclearexcept(FE_ALL_EXCEPT);
+    errno = 0;
+    printf("log(0) = %f\n", log(0));
+    if(errno == ERANGE)
+        perror("errno == ERANGE");
+    if(fetestexcept(FE_DIVBYZERO))
+        puts("FE_DIVBYZERO (pole error) reported");
+}

Possible output:

+
MATH_ERRNO is set
+MATH_ERREXCEPT is set
+log(0) = -inf
+errno = ERANGE: Numerical result out of range
+FE_DIVBYZERO (pole error) reported

References

See also

+ + +
+
(C99)
 floating-point exceptions
(macro constant)
macro which expands to POSIX-compatible thread-local error number variable
(macro variable)
C++ documentation for math_errhandling
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/math_errhandling +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fmodf.html b/devdocs/c/numeric%2Fmath%2Fmodf.html new file mode 100644 index 00000000..7ee360cd --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fmodf.html @@ -0,0 +1,78 @@ +

modf, modff, modfl

Defined in header <math.h> 
float       modff( float arg, float* iptr );
+		 (1) (since C99) 
double      modf( double arg, double* iptr );
+		 (2) 
long double modfl( long double arg, long double* iptr );
+		 (3) (since C99)
+1-3) Decomposes given floating point value arg into integral and fractional parts, each having the same type and sign as arg. The integral part (in floating-point format) is stored in the object pointed to by iptr.

Parameters

+ + +
arg - floating point value
iptr - pointer to floating point value to store the integral part to

Return value

If no errors occur, returns the fractional part of x with the same sign as x. The integral part is put into the value pointed to by iptr.

+

The sum of the returned value and the value stored in *iptr gives arg (allowing for rounding).

+

Error handling

This function is not subject to any errors specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

This function behaves as if implemented as follows:

+
double modf(double value, double *iptr)
+{
+#pragma STDC FENV_ACCESS ON
+    int save_round = fegetround();
+    fesetround(FE_TOWARDZERO);
+    *iptr = std::nearbyint(value);
+    fesetround(save_round);
+    return copysign(isinf(value) ? 0.0 : value - (*iptr), value);
+}

Example

#include <stdio.h>
+#include <math.h>
+#include <float.h>
+ 
+int main(void)
+{
+    double f = 123.45;
+    printf("Given the number %.2f or %a in hex,\n", f, f);
+ 
+    double f3;
+    double f2 = modf(f, &f3);
+    printf("modf() makes %.2f + %.2f\n", f3, f2);
+ 
+    int i;
+    f2 = frexp(f, &i);
+    printf("frexp() makes %f * 2^%d\n", f2, i);
+ 
+    i = ilogb(f);
+    printf("logb()/ilogb() make %f * %d^%d\n", f/scalbn(1.0, i), FLT_RADIX, i);
+ 
+    // special values
+    f2 = modf(-0.0, &f3);
+    printf("modf(-0) makes %.2f + %.2f\n", f3, f2);
+    f2 = modf(-INFINITY, &f3);
+    printf("modf(-Inf) makes %.2f + %.2f\n", f3, f2);
+}

Possible output:

+
Given the number 123.45 or 0x1.edccccccccccdp+6 in hex,
+modf() makes 123.00 + 0.45
+frexp() makes 0.964453 * 2^7
+logb()/ilogb() make 1.92891 * 2^6
+modf(-0) makes -0.00 + -0.00
+modf(-Inf) makes -INF + -0.00

References

See also

+ +
+
(C99)(C99)(C99)
 rounds to nearest integer not greater in magnitude than the given value
(function)
C++ documentation for modf
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/modf +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fnan.html b/devdocs/c/numeric%2Fmath%2Fnan.html new file mode 100644 index 00000000..b8bdd8b4 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fnan.html @@ -0,0 +1,74 @@ +

nan, nanf, nanl, nand32, nand64, nand128

Defined in header <math.h> 
float       nanf( const char* arg );
+		 (1) (since C99) 
double      nan( const char* arg );
+		 (2) (since C99) 
long double nanl( const char* arg );
+		 (3) (since C99) 
_Decimal32  nand32( const char* arg );
+		 (4) (since C23) 
_Decimal64  nand64( const char* arg );
+		 (5) (since C23) 
_Decimal128 nand128( const char* arg );
+		 (6) (since C23)

Converts the implementation-defined character string arg into the corresponding quiet NaN value, as if by calling the appropriate parsing function strtoX, as follows:

+
+1) The parsing function is strtof.
+2) The parsing function is strtod.
+3) The parsing function is strtold.
+4) The parsing function is strtod32.
+5) The parsing function is strtod64.
+6) The parsing function is strtod128.
+ +

The functions returning decimal floating point values are declared if and only the implementation predefines __STDC_IEC_60559_DFP__ (i.e. the implementation supports decimal floating point numbers).

+		 (since C23)

Parameters

+ +
arg - narrow character string identifying the contents of a NaN

Return value

The quiet NaN value that corresponds to the identifying string arg or zero if the implementation does not support quiet NaNs.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559), it also supports quiet NaNs.

+

Error handling

This function is not subject to any of the error conditions specified in math_errhandling.

+

Example

#include <stdio.h>
+#include <math.h>
+#include <stdint.h>
+#include <inttypes.h>
+#include <string.h>
+ 
+int main(void)
+{
+    double f1 = nan("1");
+    uint64_t f1n; memcpy(&f1n, &f1, sizeof f1);
+    printf("nan(\"1\")   = %f (%" PRIx64 ")\n", f1, f1n);
+ 
+    double f2 = nan("2");
+    uint64_t f2n; memcpy(&f2n, &f2, sizeof f2);
+    printf("nan(\"2\")   = %f (%" PRIx64 ")\n", f2, f2n);
+ 
+    double f3 = nan("0xF");
+    uint64_t f3n; memcpy(&f3n, &f3, sizeof f3);
+    printf("nan(\"0xF\") = %f (%" PRIx64 ")\n", f3, f3n);
+}

Possible output:

+
nan("1")   = nan (7ff8000000000001)
+nan("2")   = nan (7ff8000000000002)
+nan("0xF") = nan (7ff800000000000f)

References

See also

+ + +
+
(C99)
 checks if the given number is NaN
(function macro)
+
(C99)
 evaluates to a quiet NaN of type float
(macro constant)
C++ documentation for nanf, nan, nanl
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/nan +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fnearbyint.html b/devdocs/c/numeric%2Fmath%2Fnearbyint.html new file mode 100644 index 00000000..4f551258 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fnearbyint.html @@ -0,0 +1,78 @@ +

nearbyint, nearbyintf, nearbyintl

Defined in header <math.h> 
float       nearbyintf( float arg );
+		 (1) (since C99) 
double      nearbyint( double arg );
+		 (2) (since C99) 
long double nearbyintl( long double arg );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define nearbyint( arg )
+		 (4) (since C99)
+1-3) Rounds the floating-point argument arg to an integer value in floating-point format, using the current rounding mode.
+4) Type-generic macro: If arg has type long double, nearbyintl is called. Otherwise, if arg has integer type or the type double, nearbyint is called. Otherwise, nearbyintf is called, respectively.

Parameters

+ +
arg - floating point value

Return value

The nearest integer value to arg, according to the current rounding mode, is returned.

+

Error handling

This function is not subject to any of the errors specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

The only difference between nearbyint and rint is that nearbyint never raises FE_INEXACT.

+

The largest representable floating-point values are exact integers in all standard floating-point formats, so nearbyint never overflows on its own; however the result may overflow any integer type (including intmax_t), when stored in an integer variable.

+

If the current rounding mode is FE_TONEAREST, this function rounds to even in halfway cases (like rint, but unlike round).

+

Example

#include <stdio.h>
+#include <math.h>
+#include <fenv.h>
+ 
+int main(void)
+{
+#pragma STDC FENV_ACCESS ON
+    fesetround(FE_TONEAREST);
+    printf("rounding to nearest:\nnearbyint(+2.3) = %+.1f  ", nearbyint(2.3));
+    printf("nearbyint(+2.5) = %+.1f  ", nearbyint(2.5));
+    printf("nearbyint(+3.5) = %+.1f\n", nearbyint(3.5));
+    printf("nearbyint(-2.3) = %+.1f  ", nearbyint(-2.3));
+    printf("nearbyint(-2.5) = %+.1f  ", nearbyint(-2.5));
+    printf("nearbyint(-3.5) = %+.1f\n", nearbyint(-3.5));
+ 
+    fesetround(FE_DOWNWARD);
+    printf("rounding down: \nnearbyint(+2.3) = %+.1f  ", nearbyint(2.3));
+    printf("nearbyint(+2.5) = %+.1f  ", nearbyint(2.5));
+    printf("nearbyint(+3.5) = %+.1f\n", nearbyint(3.5));
+    printf("nearbyint(-2.3) = %+.1f  ", nearbyint(-2.3));
+    printf("nearbyint(-2.5) = %+.1f  ", nearbyint(-2.5));
+    printf("nearbyint(-3.5) = %+.1f\n", nearbyint(-3.5));
+ 
+    printf("nearbyint(-0.0) = %+.1f\n", nearbyint(-0.0));
+    printf("nearbyint(-Inf) = %+.1f\n", nearbyint(-INFINITY));
+}

Output:

+
rounding to nearest:
+nearbyint(+2.3) = +2.0  nearbyint(+2.5) = +2.0  nearbyint(+3.5) = +4.0
+nearbyint(-2.3) = -2.0  nearbyint(-2.5) = -2.0  nearbyint(-3.5) = -4.0
+rounding down: 
+nearbyint(+2.3) = +2.0  nearbyint(+2.5) = +2.0  nearbyint(+3.5) = +3.0
+nearbyint(-2.3) = -3.0  nearbyint(-2.5) = -3.0  nearbyint(-3.5) = -4.0
+nearbyint(-0.0) = -0.0
+nearbyint(-Inf) = -inf

References

See also

+ + + +
+
(C99)(C99)(C99)(C99)(C99)(C99)(C99)(C99)(C99)
 rounds to an integer using current rounding mode with
exception if the result differs
(function)
+
(C99)(C99)(C99)(C99)(C99)(C99)(C99)(C99)(C99)
 rounds to nearest integer, rounding away from zero in halfway cases
(function)
+
(C99)(C99)
 gets or sets rounding direction
(function)
C++ documentation for nearbyint
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/nearbyint +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fnextafter.html b/devdocs/c/numeric%2Fmath%2Fnextafter.html new file mode 100644 index 00000000..ad038edc --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fnextafter.html @@ -0,0 +1,109 @@ +

nextafter, nextafterf, nextafterl, nexttoward, nexttowardf, nexttowardl

Defined in header <math.h> 
float       nextafterf( float from, float to );
+		 (1) (since C99) 
double      nextafter( double from, double to );
+		 (2) (since C99) 
long double nextafterl( long double from, long double to );
+		 (3) (since C99) 
float       nexttowardf( float from, long double to );
+		 (4) (since C99) 
double      nexttoward( double from, long double to );
+		 (5) (since C99) 
long double nexttowardl( long double from, long double to );
+		 (6) (since C99)
Defined in header <tgmath.h> 
#define nextafter(from, to)
+		 (7) (since C99) 
#define nexttoward(from, to)
+		 (8) (since C99)
+1-3) First, converts both arguments to the type of the function, then returns the next representable value of from in the direction of to. If from equals to to, to is returned.
+4-6) First, converts the first argument to the type of the function, then returns the next representable value of from in the direction of to. If from equals to to, to is returned, converted from long double to the return type of the function without loss of range or precision.
+7) Type-generic macro: If any argument has type long double, nextafterl is called. Otherwise, if any argument has integer type or has type double, nextafter is called. Otherwise, nextafterf is called.
+8) Type-generic macro: If the argument from has type long double, nexttowardl is called. Otherwise, if from has integer type or the type double, nexttoward is called. Otherwise, nexttowardf is called.

Parameters

+ +
from, to - floating point values

Return value

If no errors occur, the next representable value of from in the direction of to. is returned. If from equals to, then to is returned, converted to the type of the function.

+

If a range error due to overflow occurs, ±HUGE_VAL, ±HUGE_VALF, or ±HUGE_VALL is returned (with the same sign as from).

+

If a range error occurs due to underflow, the correct result is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

POSIX specifies that the overflow and the underflow conditions are range errors (errno may be set).

+

IEC 60559 recommends that from is returned whenever from == to. These functions return to instead, which makes the behavior around zero consistent: nextafter(-0.0, +0.0) returns +0.0 and nextafter(+0.0, -0.0) returns -0.0.

+

nextafter is typically implemented by manipulation of IEEE representation (glibc musl).

+

Example

#include <math.h>
+#include <stdio.h>
+#include <float.h>
+#include <fenv.h>
+ 
+int main(void)
+{
+    float from1 = 0, to1 = nextafterf(from1, 1);
+    printf("The next representable float after %.2f is %.20g (%a)\n", from1, to1, to1);
+ 
+    float from2 = 1, to2 = nextafterf(from2, 2);
+    printf("The next representable float after %.2f is %.20f (%a)\n", from2, to2, to2);
+ 
+    double from3 = nextafter(0.1, 0), to3 = 0.1;
+    printf("The number 0.1 lies between two valid doubles:\n"
+           "    %.56f (%a)\nand %.55f  (%a)\n", from3, from3, to3, to3);
+ 
+    // difference between nextafter and nexttoward:
+    long double dir = nextafterl(from1, 1); // first subnormal long double
+    float x = nextafterf(from1, dir); // first converts dir to float, giving 0
+    printf("Using nextafter, next float after %.2f (%a) is %.20g (%a)\n",
+           from1, from1, x, x);
+    x = nexttowardf(from1, dir);
+    printf("Using nexttoward, next float after %.2f (%a) is %.20g (%a)\n",
+           from1, from1, x, x);
+ 
+    // special values
+    {
+        #pragma STDC FENV_ACCESS ON
+        feclearexcept(FE_ALL_EXCEPT);
+        double from4 = DBL_MAX, to4 = nextafter(from4, INFINITY);
+        printf("The next representable double after %.2g (%a) is %.23f (%a)\n",
+               from4, from4, to4, to4);
+        if(fetestexcept(FE_OVERFLOW)) puts("   raised FE_OVERFLOW");
+        if(fetestexcept(FE_INEXACT)) puts("   raised FE_INEXACT");
+    } // end FENV_ACCESS block
+ 
+    float from5 = 0.0, to5 = nextafter(from5, -0.0);
+    printf("nextafter(+0.0, -0.0) gives %.2g (%a)\n", to5, to5);
+}

Output:

+
The next representable float after 0.00 is 1.4012984643248170709e-45 (0x1p-149)
+The next representable float after 1.00 is 1.00000011920928955078 (0x1.000002p+0)
+The number 0.1 lies between two valid doubles:
+    0.09999999999999999167332731531132594682276248931884765625 (0x1.9999999999999p-4)
+and 0.1000000000000000055511151231257827021181583404541015625  (0x1.999999999999ap-4)
+Using nextafter, next float after 0.00 (0x0p+0) is 0 (0x0p+0)
+Using nexttoward, next float after 0.00 (0x0p+0) is 1.4012984643248170709e-45 (0x1p-149)
+The next representable double after 1.8e+308 (0x1.fffffffffffffp+1023) is inf (inf)
+   raised FE_OVERFLOW
+   raised FE_INEXACT
+nextafter(+0.0, -0.0) gives -0 (-0x0p+0)

References

See also

+
C++ documentation for nextafter
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/nextafter +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fpow.html b/devdocs/c/numeric%2Fmath%2Fpow.html new file mode 100644 index 00000000..c0edd34b --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fpow.html @@ -0,0 +1,122 @@ +

pow, powf, powl

Defined in header <math.h> 
float powf( float base, float exponent );
+		 (1) (since C99) 
double pow( double base, double exponent );
+		 (2) 
long double powl( long double base, long double exponent );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define pow( base, exponent )
+		 (4) (since C99)
+1-3) Computes the value of base raised to the power exponent.
+4) Type-generic macro: If any argument has type long double, powl is called. Otherwise, if any argument has integer type or has type double, pow is called. Otherwise, powf is called. If at least one argument is complex or imaginary, then the macro invokes the corresponding complex function (cpowf, cpow, cpowl).

Parameters

+ + +
base - base as floating point value
exponent - exponent as floating point value

Return value

If no errors occur, base raised to the power of exponent (baseexponent) is returned.

+

If a domain error occurs, an implementation-defined value is returned (NaN where supported).

+

If a pole error or a range error due to overflow occurs, ±HUGE_VAL, ±HUGE_VALF, or ±HUGE_VALL is returned.

+

If a range error occurs due to underflow, the correct result (after rounding) is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

If base is finite and negative and exponent is finite and non-integer, a domain error occurs and a range error may occur.

+

If base is zero and exponent is zero, a domain error may occur.

+

If base is zero and exponent is negative, a domain error or a pole error may occur.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

Although pow cannot be used to obtain a root of a negative number, cbrt is provided for the common case where exponent is 1/3.

+

Example

#include <stdio.h>
+#include <math.h>
+#include <errno.h>
+#include <fenv.h>
+ 
+#pragma STDC FENV_ACCESS ON
+int main(void)
+{
+    // typical usage
+    printf("pow(2, 10) = %f\n", pow(2,10));
+    printf("pow(2, 0.5) = %f\n", pow(2,0.5));
+    printf("pow(-2, -3) = %f\n", pow(-2,-3));
+    // special values
+    printf("pow(-1, NAN) = %f\n", pow(-1,NAN));
+    printf("pow(+1, NAN) = %f\n", pow(+1,NAN));
+    printf("pow(INFINITY, 2) = %f\n", pow(INFINITY, 2));
+    printf("pow(INFINITY, -1) = %f\n", pow(INFINITY, -1));
+    // error handling 
+    errno = 0; feclearexcept(FE_ALL_EXCEPT);
+    printf("pow(-1, 1/3) = %f\n", pow(-1, 1.0/3));
+    if(errno == EDOM)         perror("    errno == EDOM");
+    if(fetestexcept(FE_INVALID)) puts("    FE_INVALID raised");
+ 
+    feclearexcept(FE_ALL_EXCEPT);
+    printf("pow(-0, -3) = %f\n", pow(-0.0, -3));
+    if(fetestexcept(FE_DIVBYZERO)) puts("    FE_DIVBYZERO raised");
+}

Possible output:

+
pow(2, 10) = 1024.000000
+pow(2, 0.5) = 1.414214
+pow(-2, -3) = -0.125000
+pow(-1, NAN) = nan
+pow(+1, NAN) = 1.000000
+pow(INFINITY, 2) = inf
+pow(INFINITY, -1) = 0.000000
+pow(-1, 1/3) = -nan
+    errno == EDOM: Numerical argument out of domain
+    FE_INVALID raised
+pow(-0, -3) = -inf
+    FE_DIVBYZERO raised

References

See also

+ + + + +
+
(C99)(C99)
 computes square root (\(\small{\sqrt{x} }\)√x)
(function)
+
(C99)(C99)(C99)
 computes cube root (\(\small{\sqrt[3]{x} }\)3√x)
(function)
+
(C99)(C99)(C99)
 computes square root of the sum of the squares of two given numbers (\(\scriptsize{\sqrt{x^2+y^2} }\)√x2+y2)
(function)
+
(C99)(C99)(C99)
 computes the complex power function
(function)
C++ documentation for pow
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/pow +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fremainder.html b/devdocs/c/numeric%2Fmath%2Fremainder.html new file mode 100644 index 00000000..1abb2995 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fremainder.html @@ -0,0 +1,87 @@ +

remainder, remainderf, remainderl

Defined in header <math.h> 
float       remainderf( float x, float y );
+		 (1) (since C99) 
double      remainder( double x, double y );
+		 (2) (since C99) 
long double remainderl( long double x, long double y );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define remainder( x, y )
+		 (4) (since C99)
+1-3) Computes the IEEE remainder of the floating point division operation x/y.
+4) Type-generic macro: If any argument has type long double, remainderl is called. Otherwise, if any argument has integer type or has type double, remainder is called. Otherwise, remainderf is called.

The IEEE floating-point remainder of the division operation x/y calculated by this function is exactly the value x - n*y, where the value n is the integral value nearest the exact value x/y. When |n-x/y| = ½, the value n is chosen to be even.

+

In contrast to fmod(), the returned value is not guaranteed to have the same sign as x.

+

If the returned value is 0, it will have the same sign as x.

+

Parameters

+ +
x, y - floating point values

Return value

If successful, returns the IEEE floating-point remainder of the division x/y as defined above.

+

If a domain error occurs, an implementation-defined value is returned (NaN where supported).

+

If a range error occurs due to underflow, the correct result is returned.

+

If y is zero, but the domain error does not occur, zero is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

Domain error may occur if y is zero.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

POSIX requires that a domain error occurs if x is infinite or y is zero.

+

fmod, but not remainder is useful for doing silent wrapping of floating-point types to unsigned integer types: (0.0 <= (y = fmod(rint(x), 65536.0)) ? y : 65536.0 + y) is in the range [-0.0 .. 65535.0], which corresponds to unsigned short, but remainder(rint(x), 65536.0) is in the range [-32767.0, +32768.0], which is outside of the range of signed short.

+

Example

#include <stdio.h>
+#include <math.h>
+#include <fenv.h>
+ 
+#pragma STDC FENV_ACCESS ON
+int main(void)
+{
+    printf("remainder(+5.1, +3.0) = %.1f\n", remainder(5.1,3));
+    printf("remainder(-5.1, +3.0) = %.1f\n", remainder(-5.1,3));
+    printf("remainder(+5.1, -3.0) = %.1f\n", remainder(5.1,-3));
+    printf("remainder(-5.1, -3.0) = %.1f\n", remainder(-5.1,-3));
+ 
+    // special values
+    printf("remainder(-0.0, 1.0) = %.1f\n", remainder(-0.0, 1));
+    printf("remainder(+5.1, Inf) = %.1f\n", remainder(5.1, INFINITY));
+ 
+    // error handling
+    feclearexcept(FE_ALL_EXCEPT);
+    printf("remainder(+5.1, 0) = %.1f\n", remainder(5.1, 0));
+    if(fetestexcept(FE_INVALID)) puts("    FE_INVALID raised");
+}

Output:

+
remainder(+5.1, +3.0) = -0.9
+remainder(-5.1, +3.0) = 0.9
+remainder(+5.1, -3.0) = -0.9
+remainder(-5.1, -3.0) = 0.9
+remainder(+0.0, 1.0) = 0.0
+remainder(-0.0, 1.0) = -0.0
+remainder(+5.1, Inf) = 5.1
+remainder(+5.1, 0) = -nan
+    FE_INVALID raised

References

See also

+ + + +
+
(C99)
 computes quotient and remainder of integer division
(function)
+
(C99)(C99)
 computes remainder of the floating-point division operation
(function)
+
(C99)(C99)(C99)
 computes signed remainder as well as the three last bits of the division operation
(function)
C++ documentation for remainder
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/remainder +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fremquo.html b/devdocs/c/numeric%2Fmath%2Fremquo.html new file mode 100644 index 00000000..aef01c0a --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fremquo.html @@ -0,0 +1,99 @@ +

remquo, remquof, remquol

Defined in header <math.h> 
float       remquof( float x, float y, int *quo );
+		 (1) (since C99) 
double      remquo( double x, double y, int *quo );
+		 (2) (since C99) 
long double remquol( long double x, long double y, int *quo );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define remquo( x, y, quo )
+		 (4) (since C99)
+1-3) Computes the floating-point remainder of the division operation x/y as the remainder() function does. Additionally, the sign and at least the three of the last bits of x/y will be stored in quo, sufficient to determine the octant of the result within a period.
+4) Type-generic macro: If any non-pointer argument has type long double, remquol is called. Otherwise, if any non-pointer argument has integer type or has type double, remquo is called. Otherwise, remquof is called.

Parameters

+ + +
x, y - floating point values
quo - pointer to an integer value to store the sign and some bits of x/y

Return value

If successful, returns the floating-point remainder of the division x/y as defined in remainder, and stores, in *quo, the sign and at least three of the least significant bits of x/y (formally, stores a value whose sign is the sign of x/y and whose magnitude is congruent modulo 2n to the magnitude of the integral quotient of x/y, where n is an implementation-defined integer greater than or equal to 3).

+

If y is zero, the value stored in *quo is unspecified.

+

If a domain error occurs, an implementation-defined value is returned (NaN where supported).

+

If a range error occurs due to underflow, the correct result is returned if subnormals are supported.

+

If y is zero, but the domain error does not occur, zero is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

Domain error may occur if y is zero.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

POSIX requires that a domain error occurs if x is infinite or y is zero.

+

This function is useful when implementing periodic functions with the period exactly representable as a floating-point value: when calculating sin(πx) for a very large x, calling sin directly may result in a large error, but if the function argument is first reduced with remquo, the low-order bits of the quotient may be used to determine the sign and the octant of the result within the period, while the remainder may be used to calculate the value with high precision.

+

On some platforms this operation is supported by hardware (and, for example, on Intel CPU, FPREM1 leaves exactly 3 bits of precision in the quotient)

+

Example

#include <stdio.h>
+#include <math.h>
+#include <fenv.h>
+#ifndef __GNUC__
+#pragma STDC FENV_ACCESS ON
+#endif
+double cos_pi_x_naive(double x)
+{
+    const double pi = acos(-1);
+    return cos(pi * x);
+}
+// the period is 2, values are (0;0.5) positive, (0.5;1.5) negative, (1.5,2) positive
+double cos_pi_x_smart(double x)
+{
+    const double pi = acos(-1);
+    int extremum;
+    double rem = remquo(x, 1, &extremum);
+    extremum = (unsigned)extremum % 2; // keep 1 bit to determine nearest extremum
+    return extremum ? -cos(pi * rem) : cos(pi * rem);
+}
+int main(void)
+{
+    printf("cos(pi * 0.25) = %f\n", cos_pi_x_naive(0.25));
+    printf("cos(pi * 1.25) = %f\n", cos_pi_x_naive(1.25));
+    printf("cos(pi * 1000000000000.25) = %f\n", cos_pi_x_naive(1000000000000.25));
+    printf("cos(pi * 1000000000001.25) = %f\n", cos_pi_x_naive(1000000000001.25));
+    printf("cos(pi * 1000000000000.25) = %f\n", cos_pi_x_smart(1000000000000.25));
+    printf("cos(pi * 1000000000001.25) = %f\n", cos_pi_x_smart(1000000000001.25));
+    // error handling
+    feclearexcept(FE_ALL_EXCEPT);
+    int quo;
+    printf("remquo(+Inf, 1) = %.1f\n", remquo(INFINITY, 1, &quo));
+    if(fetestexcept(FE_INVALID)) puts("    FE_INVALID raised");
+}

Possible output:

+
cos(pi * 0.25) = 0.707107
+cos(pi * 1.25) = -0.707107
+cos(pi * 1000000000000.25) = 0.707123
+cos(pi * 1000000000001.25) = -0.707117
+cos(pi * 1000000000000.25) = 0.707107
+cos(pi * 1000000000001.25) = -0.707107 
+remquo(+Inf, 1) = -nan
+    FE_INVALID raised

References

See also

+ + + +
+
(C99)
 computes quotient and remainder of integer division
(function)
+
(C99)(C99)
 computes remainder of the floating-point division operation
(function)
+
(C99)(C99)(C99)
 computes signed remainder of the floating-point division operation
(function)
C++ documentation for remquo
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/remquo +

+
diff --git a/devdocs/c/numeric%2Fmath%2Frint.html b/devdocs/c/numeric%2Fmath%2Frint.html new file mode 100644 index 00000000..cd195c3e --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Frint.html @@ -0,0 +1,134 @@ +

rint, rintf, rintl, lrint, lrintf, lrintl, llrint, llrintf, llrintl

Defined in header <math.h> 
float rintf( float arg );
+		 (1) (since C99) 
double rint( double arg );
+		 (2) (since C99) 
long double rintl( long double arg );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define rint( arg )
+		 (4) (since C99)
Defined in header <math.h> 
long lrintf( float arg );
+		 (5) (since C99) 
long lrint( double arg );
+		 (6) (since C99) 
long lrintl( long double arg );
+		 (7) (since C99)
Defined in header <tgmath.h> 
#define lrint( arg )
+		 (8) (since C99)
Defined in header <math.h> 
long long llrintf( float arg );
+		 (9) (since C99) 
long long llrint( double arg );
+		 (10) (since C99) 
long long llrintl( long double arg );
+		 (11) (since C99)
Defined in header <tgmath.h> 
#define llrint( arg )
+		 (12) (since C99)
+1-3) Rounds the floating-point argument arg to an integer value in floating-point format, using the current rounding mode.
+5-7, 9-11) Rounds the floating-point argument arg to an integer value in integer format, using the current rounding mode.
+4,8,12) Type-generic macros: If arg has type long double, rintl, lrintl, llrintl is called. Otherwise, if arg has integer type or the type double, rint, lrint, llrint is called. Otherwise, rintf, lrintf, llrintf is called, respectively.

Parameters

+ +
arg - floating point value

Return value

If no errors occur, the nearest integer value to arg, according to the current rounding mode, is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

If the result of lrint or llrint is outside the range representable by the return type, a domain error or a range error may occur.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559), For the rint function:

+ For lrint and llrint functions:

Notes

POSIX specifies that all cases where lrint or llrint raise FE_INEXACT are domain errors.

+

As specified in math_errhandling, FE_INEXACT may be (but isn't required to be on non-IEEE floating-point platforms) raised by rint when rounding a non-integer finite value.

+

The only difference between rint and nearbyint is that nearbyint never raises FE_INEXACT.

+

The largest representable floating-point values are exact integers in all standard floating-point formats, so rint never overflows on its own; however the result may overflow any integer type (including intmax_t), when stored in an integer variable.

+

If the current rounding mode is...

+

Example

#include <stdio.h>
+#include <math.h>
+#include <fenv.h>
+#include <limits.h>
+ 
+int main(void)
+{
+#pragma STDC FENV_ACCESS ON
+    fesetround(FE_TONEAREST);
+    printf("rounding to nearest (halfway cases to even):\n"
+           "rint(+2.3) = %+.1f  ", rint(2.3));
+    printf("rint(+2.5) = %+.1f  ", rint(2.5));
+    printf("rint(+3.5) = %+.1f\n", rint(3.5));
+    printf("rint(-2.3) = %+.1f  ", rint(-2.3));
+    printf("rint(-2.5) = %+.1f  ", rint(-2.5));
+    printf("rint(-3.5) = %+.1f\n", rint(-3.5));
+ 
+    fesetround(FE_DOWNWARD);
+    printf("rounding down: \nrint(+2.3) = %+.1f  ", rint(2.3));
+    printf("rint(+2.5) = %+.1f  ", rint(2.5));
+    printf("rint(+3.5) = %+.1f\n", rint(3.5));
+    printf("rint(-2.3) = %+.1f  ", rint(-2.3));
+    printf("rint(-2.5) = %+.1f  ", rint(-2.5));
+    printf("rint(-3.5) = %+.1f\n", rint(-3.5));
+    printf("rounding down with lrint: \nlrint(+2.3) = %ld  ", lrint(2.3));
+    printf("lrint(+2.5) = %ld  ", lrint(2.5));
+    printf("lrint(+3.5) = %ld\n", lrint(3.5));
+    printf("lrint(-2.3) = %ld  ", lrint(-2.3));
+    printf("lrint(-2.5) = %ld  ", lrint(-2.5));
+    printf("lrint(-3.5) = %ld\n", lrint(-3.5));
+ 
+    printf("lrint(-0.0) = %ld\n", lrint(-0.0));
+    printf("lrint(-Inf) = %ld\n", lrint(-INFINITY)); // FE_INVALID raised
+ 
+    // error handling
+    feclearexcept(FE_ALL_EXCEPT);
+    printf("rint(1.1) = %.1f\n", rint(1.1));
+    if(fetestexcept(FE_INEXACT)) puts("    FE_INEXACT was raised");
+ 
+    feclearexcept(FE_ALL_EXCEPT);
+    printf("lrint(LONG_MIN-2048.0) = %ld\n", lrint(LONG_MIN-2048.0));
+    if(fetestexcept(FE_INVALID)) puts("    FE_INVALID was raised");
+}

Possible output:

+
rounding to nearest (halfway cases to even):
+rint(+2.3) = +2.0  rint(+2.5) = +2.0  rint(+3.5) = +4.0
+rint(-2.3) = -2.0  rint(-2.5) = -2.0  rint(-3.5) = -4.0
+rounding down: 
+rint(+2.3) = +2.0  rint(+2.5) = +2.0  rint(+3.5) = +3.0
+rint(-2.3) = -3.0  rint(-2.5) = -3.0  rint(-3.5) = -4.0
+rounding down with lrint: 
+lrint(+2.3) = 2  lrint(+2.5) = 2  lrint(+3.5) = 3
+lrint(-2.3) = -3  lrint(-2.5) = -3  lrint(-3.5) = -4
+lrint(-0.0) = 0
+lrint(-Inf) = -9223372036854775808
+rint(1.1) = 1.0
+    FE_INEXACT was raised
+lrint(LONG_MIN-2048.0) = -9223372036854775808
+    FE_INVALID was raised

References

See also

+ + + +
+
(C99)(C99)(C99)
 rounds to nearest integer not greater in magnitude than the given value
(function)
+
(C99)(C99)(C99)
 rounds to an integer using current rounding mode
(function)
+
(C99)(C99)
 gets or sets rounding direction
(function)
C++ documentation for rint
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/rint +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fround.html b/devdocs/c/numeric%2Fmath%2Fround.html new file mode 100644 index 00000000..119c6750 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fround.html @@ -0,0 +1,124 @@ +

round, roundf, roundl, lround, lroundf, lroundl, llround, llroundf, llroundl

Defined in header <math.h> 
float       roundf( float arg );
+		 (1) (since C99) 
double      round( double arg );
+		 (2) (since C99) 
long double roundl( long double arg );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define round( arg )
+		 (4) (since C99)
Defined in header <math.h> 
long      lroundf( float arg );
+		 (5) (since C99) 
long      lround( double arg );
+		 (6) (since C99) 
long      lroundl( long double arg );
+		 (7) (since C99)
Defined in header <tgmath.h> 
#define lround( arg )
+		 (8) (since C99)
Defined in header <math.h> 
long long llroundf( float arg );
+		 (9) (since C99) 
long long llround( double arg );
+		 (10) (since C99) 
long long llroundl( long double arg );
+		 (11) (since C99)
Defined in header <tgmath.h> 
#define llround( arg )
+		 (12) (since C99)
+1-3) Computes the nearest integer value to arg (in floating-point format), rounding halfway cases away from zero, regardless of the current rounding mode.
+5-7, 9-11) Computes the nearest integer value to arg (in integer format), rounding halfway cases away from zero, regardless of the current rounding mode.
+4,8,12) Type-generic macros: If arg has type long double, roundl, lroundl, llroundl is called. Otherwise, if arg has integer type or the type double, round, lround, llround is called. Otherwise, roundf, lroundf, llroundf is called, respectively.

Parameters

+ +
arg - floating point value

Return value

If no errors occur, the nearest integer value to arg, rounding halfway cases away from zero, is returned.

+
Return value
math-round away zero.svg
Argument

If a domain error occurs, an implementation-defined value is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

If the result of lround or llround is outside the range representable by the return type, a domain error or a range error may occur.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559), For the round, roundf, and roundl function:

+ For lround and llround families of functions:

Notes

FE_INEXACT may be (but isn't required to be) raised by round when rounding a non-integer finite value.

+

The largest representable floating-point values are exact integers in all standard floating-point formats, so round never overflows on its own; however the result may overflow any integer type (including intmax_t), when stored in an integer variable.

+

POSIX specifies that all cases where lround or llround raise FE_INVALID are domain errors.

+

The double version of round behaves as if implemented as follows:

+
#include <math.h>
+double round(double x)
+{
+    return signbit(x) ? ceil(x - 0.5) : floor(x + 0.5);
+}

Example

#include <stdio.h>
+#include <math.h>
+#include <fenv.h>
+#include <limits.h>
+ 
+// #pragma STDC FENV_ACCESS ON
+ 
+int main(void)
+{
+    // round
+    printf("round(+2.3) = %+.1f  ", round(2.3));
+    printf("round(+2.5) = %+.1f  ", round(2.5));
+    printf("round(+2.7) = %+.1f\n", round(2.7));
+    printf("round(-2.3) = %+.1f  ", round(-2.3));
+    printf("round(-2.5) = %+.1f  ", round(-2.5));
+    printf("round(-2.7) = %+.1f\n", round(-2.7));
+ 
+    printf("round(-0.0) = %+.1f\n", round(-0.0));
+    printf("round(-Inf) = %+f\n",   round(-INFINITY));
+ 
+    // lround
+    printf("lround(+2.3) = %ld  ", lround(2.3));
+    printf("lround(+2.5) = %ld  ", lround(2.5));
+    printf("lround(+2.7) = %ld\n", lround(2.7));
+    printf("lround(-2.3) = %ld  ", lround(-2.3));
+    printf("lround(-2.5) = %ld  ", lround(-2.5));
+    printf("lround(-2.7) = %ld\n", lround(-2.7));
+ 
+    printf("lround(-0.0) = %ld\n", lround(-0.0));
+    printf("lround(-Inf) = %ld\n", lround(-INFINITY)); // FE_INVALID raised
+ 
+    // error handling
+    feclearexcept(FE_ALL_EXCEPT);
+    printf("lround(LONG_MAX+1.5) = %ld\n", lround(LONG_MAX+1.5));
+    if(fetestexcept(FE_INVALID)) puts("    FE_INVALID was raised");
+}

Possible output:

+
round(+2.3) = +2.0  round(+2.5) = +3.0  round(+2.7) = +3.0
+round(-2.3) = -2.0  round(-2.5) = -3.0  round(-2.7) = -3.0
+round(-0.0) = -0.0
+round(-Inf) = -inf
+lround(+2.3) = 2  lround(+2.5) = 3  lround(+2.7) = 3
+lround(-2.3) = -2  lround(-2.5) = -3  lround(-2.7) = -3
+lround(-0.0) = 0
+lround(-Inf) = -9223372036854775808
+lround(LONG_MAX+1.5) = -9223372036854775808
+    FE_INVALID was raised

References

See also

+ + + +
+
(C99)(C99)
 computes largest integer not greater than the given value
(function)
+
(C99)(C99)
 computes smallest integer not less than the given value
(function)
+
(C99)(C99)(C99)
 rounds to nearest integer not greater in magnitude than the given value
(function)
C++ documentation for round
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/round +

+
diff --git a/devdocs/c/numeric%2Fmath%2Froundeven.html b/devdocs/c/numeric%2Fmath%2Froundeven.html new file mode 100644 index 00000000..418b93ae --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Froundeven.html @@ -0,0 +1,57 @@ +

roundeven, roundevenf, roundevenl

Defined in header <math.h> 
float       roundevenf( float arg );
+		 (1) (since C23) 
double      roundeven( double arg );
+		 (2) (since C23) 
long double roundevenl( long double arg );
+		 (3) (since C23)
Defined in header <tgmath.h> 
#define roundeven( arg )
+		 (4) (since C23)
+1-3) Computes the nearest integer value to arg (in floating-point format), rounding halfway cases to nearest even integer, regardless of the current rounding mode.
+4) Type-generic macro: If arg has type long double, roundevenl is called. Otherwise, if arg has integer type or the type double, roundeven is called. Otherwise, roundevenf is called, respectively.

Parameters

+ +
arg - floating point value

Return value

If no errors occur, the nearest integer value to arg, rounding halfway cases to nearest even integer, is returned.

+

Error handling

This function is not subject to any of the errors specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Example

#include <math.h>
+#include <stdio.h>
+int main(void)
+{
+    printf("roundeven(+2.4) = %+.1f\n", roundeven(2.4));
+    printf("roundeven(-2.4) = %+.1f\n", roundeven(-2.4));
+    printf("roundeven(+2.5) = %+.1f\n", roundeven(2.5));
+    printf("roundeven(-2.5) = %+.1f\n", roundeven(-2.5));
+    printf("roundeven(+2.6) = %+.1f\n", roundeven(2.6));
+    printf("roundeven(-2.6) = %+.1f\n", roundeven(-2.6));
+    printf("roundeven(+3.5) = %+.1f\n", roundeven(3.5));
+    printf("roundeven(-3.5) = %+.1f\n", roundeven(-3.5));
+    printf("roundeven(-0.0) = %+.1f\n", roundeven(-0.0));
+    printf("roundeven(-Inf) = %+f\n",   roundeven(-INFINITY));
+}

Possible output:

+
roundeven(+2.4) = +2.0
+roundeven(-2.4) = -2.0
+roundeven(+2.5) = +2.0
+roundeven(-2.5) = -2.0
+roundeven(+2.6) = +3.0
+roundeven(-2.6) = -3.0
+roundeven(+3.5) = +4.0
+roundeven(-3.5) = -4.0
+roundeven(-0.0) = -0.0
+roundeven(-Inf) = -inf

References

See also

+ +
+
(C99)(C99)(C99)(C99)(C99)(C99)(C99)(C99)(C99)
 rounds to an integer using current rounding mode with
exception if the result differs
(function)
+
(C99)(C99)(C99)(C99)(C99)(C99)(C99)(C99)(C99)
 rounds to nearest integer, rounding away from zero in halfway cases
(function)
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/roundeven +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fscalbn.html b/devdocs/c/numeric%2Fmath%2Fscalbn.html new file mode 100644 index 00000000..0a6b35c7 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fscalbn.html @@ -0,0 +1,99 @@ +

scalbn, scalbnf, scalbnl, scalbln, scalblnf, scalblnl

Defined in header <math.h> 
float       scalbnf( float arg, int exp );
+		 (1) (since C99) 
double      scalbn( double arg, int exp );
+		 (2) (since C99) 
long double scalbnl( long double arg, int exp );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define scalbn( arg, exp )
+		 (4) (since C99)
Defined in header <math.h> 
float       scalblnf( float arg, long exp );
+		 (5) (since C99) 
double      scalbln( double arg, long exp );
+		 (6) (since C99) 
long double scalblnl( long double arg, long exp );
+		 (7) (since C99)
Defined in header <tgmath.h> 
#define scalbln( arg, exp )
+		 (8) (since C99)
+1-3,5-7) Multiplies a floating point value arg by FLT_RADIX raised to power exp.
+4,8) Type-generic macros: If arg has type long double, scalbnl or scalblnl is called. Otherwise, if arg has integer type or the type double, scalbn or scalbln is called. Otherwise, scalbnf or scalblnf is called, respectively.

Parameters

+ + +
arg - floating point value
exp - integer value

Return value

If no errors occur, arg multiplied by FLT_RADIX to the power of exp (arg×FLT_RADIXexp) is returned.

+

If a range error due to overflow occurs, ±HUGE_VAL, ±HUGE_VALF, or ±HUGE_VALL is returned.

+

If a range error due to underflow occurs, the correct result (after rounding) is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

On binary systems (where FLT_RADIX is 2), scalbn is equivalent to ldexp.

+

Although scalbn and scalbln are specified to perform the operation efficiently, on many implementations they are less efficient than multiplication or division by a power of two using arithmetic operators.

+

The scalbln function is provided because the factor required to scale from the smallest positive floating-point value to the largest finite one may be greater than 32767, the standard-guaranteed INT_MAX. In particular, for the 80-bit long double, the factor is 32828.

+

Example

#include <errno.h>
+#include <fenv.h>
+#include <float.h>
+#include <math.h>
+#include <stdio.h>
+ 
+// #pragma STDC FENV_ACCESS ON
+ 
+int main(void)
+{
+    printf("scalbn(7, -4) = %f\n", scalbn(7, -4));
+    printf("scalbn(1, -1074) = %g (minimum positive subnormal double)\n",
+            scalbn(1, -1074));
+    printf("scalbn(nextafter(1,0), 1024) = %g (largest finite double)\n",
+            scalbn(nextafter(1,0), 1024));
+ 
+    // special values
+    printf("scalbn(-0, 10) = %f\n", scalbn(-0.0, 10));
+    printf("scalbn(-Inf, -1) = %f\n", scalbn(-INFINITY, -1));
+ 
+    // error handling
+    errno = 0; feclearexcept(FE_ALL_EXCEPT);
+    printf("scalbn(1, 1024) = %f\n", scalbn(1, 1024));
+    if (errno == ERANGE)
+        perror("    errno == ERANGE");
+    if (fetestexcept(FE_OVERFLOW))
+        puts("    FE_OVERFLOW raised");
+}

Possible output:

+
scalbn(7, -4) = 0.437500
+scalbn(1, -1074) = 4.94066e-324 (minimum positive subnormal double)
+scalbn(nextafter(1,0), 1024) = 1.79769e+308 (largest finite double)
+scalbn(-0, 10) = -0.000000
+scalbn(-Inf, -1) = -inf
+scalbn(1, 1024) = inf
+    errno == ERANGE: Numerical result out of range
+    FE_OVERFLOW raised

References

See also

+ + +
+
(C99)(C99)
 breaks a number into significand and a power of 2
(function)
+
(C99)(C99)
 multiplies a number by 2 raised to a power
(function)
C++ documentation for scalbn
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/scalbn +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fsignbit.html b/devdocs/c/numeric%2Fmath%2Fsignbit.html new file mode 100644 index 00000000..dc7e42da --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fsignbit.html @@ -0,0 +1,35 @@ +

signbit

Defined in header <math.h> 
#define signbit( arg ) /* implementation defined */
+		 (since C99)

Determines if the given floating point number arg is negative. The macro returns an integral value.

+

Parameters

+ +
arg - floating point value

Return value

Nonzero integral value if arg is negative, ​0​ otherwise.

+

Notes

This macro detects the sign bit of zeroes, infinities, and NaNs. Along with copysign, this macro is one of the only two portable ways to examine the sign of a NaN.

+

Example

#include <math.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    printf("signbit(+0.0) = %d\n", signbit(+0.0));
+    printf("signbit(-0.0) = %d\n", signbit(-0.0));
+}

Possible output:

+
signbit(+0.0) = 0
+signbit(-0.0) = 128

References

See also

+ + +
+
(C99)(C99)
 computes absolute value of a floating-point value (\(\small{|x|}\)|x|)
(function)
+
(C99)(C99)(C99)
 produces a value with the magnitude of a given value and the sign of another given value
(function)
C++ documentation for signbit
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/signbit +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fsin.html b/devdocs/c/numeric%2Fmath%2Fsin.html new file mode 100644 index 00000000..18a0ebb1 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fsin.html @@ -0,0 +1,104 @@ +

sin, sinf, sinl

Defined in header <math.h> 
float       sinf( float arg );
+		 (1) (since C99) 
double      sin( double arg );
+		 (2) 
long double sinl( long double arg );
+		 (3) (since C99) 
_Decimal32  sind32( _Decimal32 arg );
+		 (4) (since C23) 
_Decimal64  sind64( _Decimal64 arg );
+		 (5) (since C23) 
_Decimal128 sind128( _Decimal128 arg );
+		 (6) (since C23)
Defined in header <tgmath.h> 
#define sin( arg )
+		 (7) (since C99)
+1-3) Computes the sine of arg (measured in radians).
+7) Type-generic macro: If the argument has type long double, (3) (sinl) is called. Otherwise, if the argument has integer type or the type double, (2) (sin) is called. Otherwise, (1) (sinf) is called. If the argument is complex, then the macro invokes the corresponding complex function (csinl, csin, csinf).
+ +

The functions (4-6) are declared if and only if the implementation predefines __STDC_IEC_60559_DFP__ (i.e. the implementation supports decimal floating-point numbers).

+		 (since C23)

Parameters

+ +
arg - floating-point value representing an angle in radians

Return value

If no errors occur, the sine of arg (sin(arg)) in the range [-1 ; +1], is returned.

+ + +

The result may have little or no significance if the magnitude of arg is large.

+		 (until C99)

If a domain error occurs, an implementation-defined value is returned (NaN where supported).

+

If a range error occurs due to underflow, the correct result (after rounding) is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559):

+

Notes

The case where the argument is infinite is not specified to be a domain error in C, but it is defined as a domain error in POSIX.

+

POSIX also specifies that in case of underflow, arg is returned unmodified, and if that is not supported, an implementation-defined value no greater than DBL_MIN, FLT_MIN, and LDBL_MIN is returned.

+

Example

#include <errno.h>
+#include <fenv.h>
+#include <math.h>
+#include <stdio.h>
+ 
+#ifndef __GNUC__
+#pragma STDC FENV_ACCESS ON
+#endif
+ 
+int main(void)
+{
+    const double pi = acos(-1);
+ 
+    // typical usage
+    printf("sin(pi/6) = %f\n", sin(pi / 6));
+    printf("sin(pi/2) = %f\n", sin(pi / 2));
+    printf("sin(-3*pi/4) = %f\n", sin(-3 * pi / 4));
+ 
+    // special values
+    printf("sin(+0) = %f\n", sin(0.0));
+    printf("sin(-0) = %f\n", sin(-0.0));
+ 
+    // error handling
+    feclearexcept(FE_ALL_EXCEPT);
+    printf("sin(INFINITY) = %f\n", sin(INFINITY));
+    if (fetestexcept(FE_INVALID))
+        puts("    FE_INVALID raised");
+}

Possible output:

+
sin(pi/6) = 0.500000
+sin(pi/2) = 1.000000
+sin(-3*pi/4) = -0.707107
+sin(+0) = 0.000000
+sin(-0) = -0.000000
+sin(INFINITY) = -nan
+    FE_INVALID raised

References

See also

+ + + + +
+
(C99)(C99)
 computes cosine (\({\small\cos{x} }\)cos(x))
(function)
+
(C99)(C99)
 computes tangent (\({\small\tan{x} }\)tan(x))
(function)
+
(C99)(C99)
 computes arc sine (\({\small\arcsin{x} }\)arcsin(x))
(function)
+
(C99)(C99)(C99)
 computes the complex sine
(function)
C++ documentation for sin
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/sin +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fsinh.html b/devdocs/c/numeric%2Fmath%2Fsinh.html new file mode 100644 index 00000000..bedcb5d3 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fsinh.html @@ -0,0 +1,77 @@ +

sinh, sinhf, sinhl

Defined in header <math.h> 
float       sinhf( float arg );
+		 (1) (since C99) 
double      sinh( double arg );
+		 (2) 
long double sinhl( long double arg );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define sinh( arg )
+		 (4) (since C99)
+1-3) Computes hyperbolic sine of arg.
+4) Type-generic macro: If the argument has type long double, sinhl is called. Otherwise, if the argument has integer type or the type double, sinh is called. Otherwise, sinhf is called. If the argument is complex, then the macro invokes the corresponding complex function (csinhf, csinh, csinhl).

Parameters

+ +
arg - floating point value representing a hyperbolic angle

Return value

If no errors occur, the hyperbolic sine of arg (sinh(arg), or earg-e-arg/2) is returned.

If a range error due to overflow occurs, ±HUGE_VAL, ±HUGE_VALF, or ±HUGE_VALL is returned.

+

If a range error occurs due to underflow, the correct result (after rounding) is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

POSIX specifies that in case of underflow, arg is returned unmodified, and if that is not supported, an implementation-defined value no greater than DBL_MIN, FLT_MIN, and LDBL_MIN is returned.

+

Example

#include <stdio.h>
+#include <math.h>
+#include <errno.h>
+#include <fenv.h>
+ 
+// #pragma STDC FENV_ACCESS ON
+int main(void)
+{
+    printf("sinh(1) = %f\nsinh(-1)=%f\n", sinh(1), sinh(-1));
+    printf("log(sinh(1) + cosh(1))=%f\n", log(sinh(1)+cosh(1)));
+    // special values
+    printf("sinh(+0) = %f\nsinh(-0)=%f\n", sinh(0.0), sinh(-0.0));
+    // error handling 
+    errno=0; feclearexcept(FE_ALL_EXCEPT);
+    printf("sinh(710.5) = %f\n", sinh(710.5));
+    if(errno == ERANGE) perror("    errno == ERANGE");
+    if(fetestexcept(FE_OVERFLOW)) puts("    FE_OVERFLOW raised");
+}

Possible output:

+
sinh(1) = 1.175201
+sinh(-1)=-1.175201
+log(sinh(1) + cosh(1))=1.000000
+sinh(+0) = 0.000000
+sinh(-0)=-0.000000
+sinh(710.5) = inf
+    errno == ERANGE: Numerical result out of range
+    FE_OVERFLOW raised

References

See also

+ + + + +
+
(C99)(C99)
 computes hyperbolic cosine (\({\small\cosh{x} }\)cosh(x))
(function)
+
(C99)(C99)
 computes hyperbolic tangent (\({\small\tanh{x} }\)tanh(x))
(function)
+
(C99)(C99)(C99)
 computes inverse hyperbolic sine (\({\small\operatorname{arsinh}{x} }\)arsinh(x))
(function)
+
(C99)(C99)(C99)
 computes the complex hyperbolic sine
(function)
C++ documentation for sinh
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/sinh +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fsinpi.html b/devdocs/c/numeric%2Fmath%2Fsinpi.html new file mode 100644 index 00000000..c6d70ab9 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fsinpi.html @@ -0,0 +1,77 @@ +

sinpi, sinpif, sinpil, sinpid32, sinpid64, sinpid128

Defined in header <math.h> 
float       sinpif( float arg );
+		 (1) (since C23) 
double      sinpi( double arg );
+		 (2) (since C23) 
long double sinpil( long double arg );
+		 (3) (since C23) 
_Decimal32  sinpid32( _Decimal32 arg );
+		 (4) (since C23) 
_Decimal64  sinpid64( _Decimal64 arg );
+		 (5) (since C23) 
_Decimal128 sinpid128( _Decimal128 arg );
+		 (6) (since C23)
Defined in header <tgmath.h> 
#define sinpi( arg )
+		 (7) (since C23)
+1-6) Computes the sine of π·arg measured in radians, thus regarding arg as a measurement in half-revolutions.
+7) Type-generic macro: calls the correct function based on the type of arg. If the argument has integer type, (2) is called.
+ +

The functions (4-6) are declared if and only if the implementation predefines __STDC_IEC_60559_DFP__ (i.e. the implementation supports decimal floating-point numbers).

+		 (since C23)

Parameters

+ +
arg - floating-point value whose product with π represents an angle in radians

Return value

If no errors occur, the sine of π·arg (sin(π×arg)) in the range [-1, +1], is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559):

+

Example

#include <errno.h>
+#include <fenv.h>
+#include <math.h>
+#include <stdio.h>
+ 
+#ifndef __GNUC__
+#pragma STDC FENV_ACCESS ON
+#endif
+ 
+#if __STDC_VERSION__ < 202311L
+// A naive implementation of a subset of sinpi family
+double sinpi(double arg)
+{
+    return sin(arg * (double)3.1415926535897932384626433);
+}
+#endif
+ 
+int main(void)
+{
+    const double pi = acos(-1);
+ 
+    // typical usage
+    printf("sinpi(1) = %f, sin(pi) = %f\n", sinpi(1), sin(pi));
+    printf("sinpi(0.5) = %f, sin(pi/2) = %f\n", sinpi(0.5), sin(pi / 2));
+    printf("sinpi(-0.75) = %f, sin(-3*pi/4) = %f\n", sinpi(-0.75), sin(-3 * pi / 4));
+ 
+    // special values
+    printf("sinpi(+0) = %f\n", sinpi(0.0));
+    printf("sinpi(-0) = %f\n", sinpi(-0.0));
+ 
+    // error handling
+    feclearexcept(FE_ALL_EXCEPT);
+    printf("sinpi(INFINITY) = %f\n", sinpi(INFINITY));
+    if (fetestexcept(FE_INVALID))
+        puts("    FE_INVALID raised");
+}

Possible output:

+
sinpi(1) = 0.000000, sin(pi) = 0.000000
+sinpi(0.5) = 1.000000, sin(pi/2) = 1.000000
+sinpi(-0.75) = -0.707107, sin(-3*pi/4) = -0.707107
+sinpi(+0) = 0.000000
+sinpi(-0) = -0.000000
+sinpi(INFINITY) = -nan
+    FE_INVALID raised

References

See also

+
+
(C99)(C99)
 computes sine (\({\small\sin{x} }\)sin(x))
(function)
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/sinpi +

+
diff --git a/devdocs/c/numeric%2Fmath%2Fsqrt.html b/devdocs/c/numeric%2Fmath%2Fsqrt.html new file mode 100644 index 00000000..460db07c --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fsqrt.html @@ -0,0 +1,76 @@ +

sqrt, sqrtf, sqrtl

Defined in header <math.h> 
float       sqrtf( float arg );
+		 (1) (since C99) 
double      sqrt( double arg );
+		 (2) 
long double sqrtl( long double arg );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define sqrt( arg )
+		 (4) (since C99)
+1-3) Computes square root of arg.
+4) Type-generic macro: If arg has type long double, sqrtl is called. Otherwise, if arg has integer type or the type double, sqrt is called. Otherwise, sqrtf is called. If arg is complex or imaginary, then the macro invokes the corresponding complex function (csqrtf, csqrt, csqrtl).

Parameters

+ +
arg - floating point value

Return value

If no errors occur, square root of arg (\({\small \sqrt{arg} }\)√arg), is returned.

+

If a domain error occurs, an implementation-defined value is returned (NaN where supported).

+

If a range error occurs due to underflow, the correct result (after rounding) is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

Domain error occurs if arg is less than zero.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

sqrt is required by the IEEE standard to be correctly rounded from the infinitely precise result. In particular, the exact result is produced if it can be represented in the floating-point type. The only other operations which require this are the arithmetic operators and the function fma. Other functions, including pow, are not so constrained.

+

Example

#include <stdio.h>
+#include <math.h>
+#include <errno.h>
+#include <fenv.h>
+ 
+#pragma STDC FENV_ACCESS ON
+ 
+int main(void)
+{
+    // normal use
+    printf("sqrt(100) = %f\n", sqrt(100));
+    printf("sqrt(2) = %f\n", sqrt(2));
+    printf("golden ratio = %f\n", (1+sqrt(5))/2);
+    // special values
+    printf("sqrt(-0) = %f\n", sqrt(-0.0));
+    // error handling
+    errno = 0; feclearexcept(FE_ALL_EXCEPT);
+    printf("sqrt(-1.0) = %f\n", sqrt(-1));
+    if(errno == EDOM) perror("    errno == EDOM");
+    if(fetestexcept(FE_INVALID)) puts("    FE_INVALID was raised");
+}

Possible output:

+
sqrt(100) = 10.000000
+sqrt(2) = 1.414214
+golden ratio = 1.618034
+sqrt(-0) = -0.000000
+sqrt(-1.0) = -nan
+    errno = EDOM: Numerical argument out of domain
+    FE_INVALID was raised

References

See also

+ + + + +
+
(C99)(C99)
 computes a number raised to the given power (\(\small{x^y}\)xy)
(function)
+
(C99)(C99)(C99)
 computes cube root (\(\small{\sqrt[3]{x} }\)3√x)
(function)
+
(C99)(C99)(C99)
 computes square root of the sum of the squares of two given numbers (\(\scriptsize{\sqrt{x^2+y^2} }\)√x2+y2)
(function)
+
(C99)(C99)(C99)
 computes the complex square root
(function)
C++ documentation for sqrt
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/sqrt +

+
diff --git a/devdocs/c/numeric%2Fmath%2Ftan.html b/devdocs/c/numeric%2Fmath%2Ftan.html new file mode 100644 index 00000000..74007697 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ftan.html @@ -0,0 +1,106 @@ +

tan, tanf, tanl

Defined in header <math.h> 
float       tanf( float arg );
+		 (1) (since C99) 
double      tan( double arg );
+		 (2) 
long double tanl( long double arg );
+		 (3) (since C99) 
_Decimal32  tand32( _Decimal32 arg );
+		 (4) (since C23) 
_Decimal64  tand64( _Decimal64 arg );
+		 (5) (since C23) 
_Decimal128 tand128( _Decimal128 arg );
+		 (6) (since C23)
Defined in header <tgmath.h> 
#define tan( arg )
+		 (7) (since C99)
+1-6) Computes the tangent of arg (measured in radians).
+7) Type-generic macro: If the argument has type long double, (3) (tanl) is called. Otherwise, if the argument has integer type or the type double, (2) (tan) is called. Otherwise, (1) (tanf) is called. If the argument is complex, then the macro invokes the corresponding complex function (ctanf, ctan, ctanl).
+ +

The functions (4-6) are declared if and only if the implementation predefines __STDC_IEC_60559_DFP__ (i.e. the implementation supports decimal floating-point numbers).

+		 (since C23)

Parameters

+ +
arg - floating-point value representing angle in radians

Return value

If no errors occur, the tangent of arg (tan(arg)) is returned.

+ + +

The result may have little or no significance if the magnitude of arg is large.

+		 (until C99)

If a domain error occurs, an implementation-defined value is returned (NaN where supported).

+

If a range error occurs due to underflow, the correct result (after rounding) is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559):

+

Notes

The case where the argument is infinite is not specified to be a domain error in C, but it is defined as a domain error in POSIX.

+

The function has mathematical poles at π(1/2 + n); however no common floating-point representation is able to represent π/2 exactly, thus there is no value of the argument for which a pole error occurs.

+

Example

#include <errno.h>
+#include <fenv.h>
+#include <math.h>
+#include <stdio.h>
+ 
+#ifndef __GNUC__
+#pragma STDC FENV_ACCESS ON
+#endif
+ 
+int main(void)
+{
+    const double pi = acos(-1);
+ 
+    // typical usage
+    printf("tan(pi*1/4) = %+f\n", tan(pi * 1 / 4)); //   45 deg
+    printf("tan(pi*3/4) = %+f\n", tan(pi * 3 / 4)); //  135 deg
+    printf("tan(pi*5/4) = %+f\n", tan(pi * 5 / 4)); // -135 deg
+    printf("tan(pi*7/4) = %+f\n", tan(pi * 7 / 4)); //  -45 deg
+ 
+    // special values
+    printf("tan(+0) = %f\n", tan(0.0));
+    printf("tan(-0) = %f\n", tan(-0.0));
+ 
+    // error handling
+    feclearexcept(FE_ALL_EXCEPT);
+    printf("tan(INFINITY) = %f\n", tan(INFINITY));
+    if (fetestexcept(FE_INVALID))
+        puts("    FE_INVALID raised");
+}

Possible output:

+
tan(pi*1/4) = +1.000000
+tan(pi*3/4) = -1.000000
+tan(pi*5/4) = +1.000000
+tan(pi*7/4) = -1.000000
+tan(+0) = 0.000000
+tan(-0) = -0.000000
+tan(INFINITY) = -nan
+    FE_INVALID raised

References

See also

+ + + + +
+
(C99)(C99)
 computes sine (\({\small\sin{x} }\)sin(x))
(function)
+
(C99)(C99)
 computes cosine (\({\small\cos{x} }\)cos(x))
(function)
+
(C99)(C99)
 computes arc tangent (\({\small\arctan{x} }\)arctan(x))
(function)
+
(C99)(C99)(C99)
 computes the complex tangent
(function)
C++ documentation for tan
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/tan +

+
diff --git a/devdocs/c/numeric%2Fmath%2Ftanh.html b/devdocs/c/numeric%2Fmath%2Ftanh.html new file mode 100644 index 00000000..15b20f0b --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ftanh.html @@ -0,0 +1,60 @@ +

tanh, tanhf, tanhl

Defined in header <math.h> 
float       tanhf( float arg );
+		 (1) (since C99) 
double      tanh( double arg );
+		 (2) 
long double tanhl( long double arg );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define tanh( arg )
+		 (4) (since C99)
+1-3) Computes the hyperbolic tangent of arg.
+4) Type-generic macro: If the argument has type long double, tanhl is called. Otherwise, if the argument has integer type or the type double, tanh is called. Otherwise, tanhf is called. If the argument is complex, then the macro invokes the corresponding complex function (ctanhf, ctanh, ctanhl).

Parameters

+ +
arg - floating point value representing a hyperbolic angle

Return value

If no errors occur, the hyperbolic tangent of arg (tanh(arg), or earg-e-arg/earg+e-arg) is returned.

If a range error occurs due to underflow, the correct result (after rounding) is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

POSIX specifies that in case of underflow, arg is returned unmodified, and if that is not supported, an implementation-defined value no greater than DBL_MIN, FLT_MIN, and LDBL_MIN is returned.

+

Example

#include <stdio.h>
+#include <math.h>
+ 
+int main(void)
+{
+    printf("tanh(1) = %f\ntanh(-1) = %f\n", tanh(1), tanh(-1));
+    printf("tanh(0.1)*sinh(0.2)-cosh(0.2) = %f\n", tanh(0.1) * sinh(0.2) - cosh(0.2));
+    // special values
+    printf("tanh(+0) = %f\ntanh(-0) = %f\n", tanh(0.0), tanh(-0.0));
+}

Output:

+
tanh(1) = 0.761594
+tanh(-1) = -0.761594
+tanh(0.1)*sinh(0.2)-cosh(0.2) = -1.000000
+tanh(+0) = 0.000000
+tanh(-0) = -0.000000

References

See also

+ + + + +
+
(C99)(C99)
 computes hyperbolic sine (\({\small\sinh{x} }\)sinh(x))
(function)
+
(C99)(C99)
 computes hyperbolic cosine (\({\small\cosh{x} }\)cosh(x))
(function)
+
(C99)(C99)(C99)
 computes inverse hyperbolic tangent (\({\small\operatorname{artanh}{x} }\)artanh(x))
(function)
+
(C99)(C99)(C99)
 computes the complex hyperbolic tangent
(function)
C++ documentation for tanh
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/tanh +

+
diff --git a/devdocs/c/numeric%2Fmath%2Ftgamma.html b/devdocs/c/numeric%2Fmath%2Ftgamma.html new file mode 100644 index 00000000..5b7fec6f --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ftgamma.html @@ -0,0 +1,83 @@ +

tgamma, tgammaf, tgammal

Defined in header <math.h> 
float       tgammaf( float arg );
+		 (1) (since C99) 
double      tgamma( double arg );
+		 (2) (since C99) 
long double tgammal( long double arg );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define tgamma( arg )
+		 (4) (since C99)
+1-3) Computes the gamma function of arg.
+4) Type-generic macro: If arg has type long double, tgammal is called. Otherwise, if arg has integer type or the type double, tgamma is called. Otherwise, tgammaf is called.

Parameters

+ +
arg - floating point value

Return value

If no errors occur, the value of the gamma function of arg, that is \(\Gamma(\mathtt{arg}) = \displaystyle\int_0^\infty\!\! t^{\mathtt{arg}-1} e^{-t}\, dt\)∫∞0targ-1 e-t dt, is returned.

+

If a domain error occurs, an implementation-defined value (NaN where supported) is returned.

+

If a pole error occurs, ±HUGE_VAL, ±HUGE_VALF, or ±HUGE_VALL is returned.

+

If a range error due to overflow occurs, ±HUGE_VAL, ±HUGE_VALF, or ±HUGE_VALL is returned.

+

If a range error due to underflow occurs, the correct value (after rounding) is returned.

+

Error handling

Errors are reported as specified in math_errhandling.

+

If arg is zero or is an integer less than zero, a pole error or a domain error may occur.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559):

+

Notes

If arg is a natural number, tgamma(arg) is the factorial of arg - 1. Many implementations calculate the exact integer-domain factorial if the argument is a sufficiently small integer.

+

For IEEE-compatible type double, overflow happens if 0 < x < 1/DBL_MAX or if x > 171.7.

+

POSIX requires that a pole error occurs if the argument is zero, but a domain error occurs when the argument is a negative integer. It also specifies that in future, domain errors may be replaced by pole errors for negative integer arguments (in which case the return value in those cases would change from NaN to ±∞).

+

There is a non-standard function named gamma in various implementations, but its definition is inconsistent. For example, glibc and 4.2BSD version of gamma executes lgamma, but 4.4BSD version of gamma executes tgamma.

+

Example

#include <stdio.h>
+#include <math.h>
+#include <float.h>
+#include <errno.h>
+#include <fenv.h>
+// #pragma STDC FENV_ACCESS ON
+ 
+int main(void)
+{
+    printf("tgamma(10) = %f, 9!=%f\n", tgamma(10), 2 * 3 * 4 * 5 * 6 * 7 * 8 * 9.0);
+    printf("tgamma(0.5) = %f, sqrt(pi) = %f\n", tgamma(0.5), sqrt(acos(-1)));
+ 
+    // special values
+    printf("tgamma(+Inf) = %f\n", tgamma(INFINITY));
+ 
+    // error handling
+    errno = 0; feclearexcept(FE_ALL_EXCEPT);
+    printf("tgamma(-1) = %f\n", tgamma(-1));
+    if (errno == ERANGE)
+        perror("    errno == ERANGE");
+    else
+        if (errno == EDOM)   perror("    errno == EDOM");
+    if (fetestexcept(FE_DIVBYZERO))
+        puts("    FE_DIVBYZERO raised");
+    else if (fetestexcept(FE_INVALID))
+        puts("    FE_INVALID raised");
+}

Possible output:

+
tgamma(10) = 362880.000000, 9!=362880.000000
+tgamma(0.5) = 1.772454, sqrt(pi) = 1.772454
+tgamma(+Inf) = inf
+tgamma(-1) = nan
+    errno == EDOM: Numerical argument out of domain
+    FE_INVALID raised

References

See also

+ +
+
(C99)(C99)(C99)
 computes natural (base-e) logarithm of the gamma function
(function)
C++ documentation for tgamma
+ +
+Weisstein, Eric W. "Gamma Function." From MathWorld — A Wolfram Web Resource.
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/tgamma +

+
diff --git a/devdocs/c/numeric%2Fmath%2Ftrunc.html b/devdocs/c/numeric%2Fmath%2Ftrunc.html new file mode 100644 index 00000000..a86f0ec6 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ftrunc.html @@ -0,0 +1,57 @@ +

trunc, truncf, truncl

Defined in header <math.h> 
float       truncf( float arg );
+		 (1) (since C99) 
double      trunc( double arg );
+		 (2) (since C99) 
long double truncl( long double arg );
+		 (3) (since C99)
Defined in header <tgmath.h> 
#define trunc( arg )
+		 (4) (since C99)
+1-3) Computes the nearest integer not greater in magnitude than arg.
+4) Type-generic macro: If arg has type long double, truncl is called. Otherwise, if arg has integer type or the type double, trunc is called. Otherwise, truncf is called.

Parameters

+ +
arg - floating point value

Return value

If no errors occur, the nearest integer value not greater in magnitude than arg (in other words, arg rounded towards zero), is returned.

+
Return value
math-trunc.svg
Argument

Error handling

Errors are reported as specified in math_errhandling.

+

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

+

Notes

FE_INEXACT may be (but isn't required to be) raised when truncating a non-integer finite value.

+

The largest representable floating-point values are exact integers in all standard floating-point formats, so this function never overflows on its own; however the result may overflow any integer type (including intmax_t), when stored in an integer variable.

+

The implicit conversion from floating-point to integral types also rounds towards zero, but is limited to the values that can be represented by the target type.

+

Example

#include <math.h>
+#include <stdio.h>
+int main(void)
+{
+    printf("trunc(+2.7) = %+.1f\n", trunc(2.7));
+    printf("trunc(-2.7) = %+.1f\n", trunc(-2.7));
+    printf("trunc(-0.0) = %+.1f\n", trunc(-0.0));
+    printf("trunc(-Inf) = %+f\n",   trunc(-INFINITY));
+}

Possible output:

+
trunc(+2.7) = +2.0
+trunc(-2.7) = -2.0
+trunc(-0.0) = -0.0
+trunc(-Inf) = -inf

References

See also

+ + + +
+
(C99)(C99)
 computes largest integer not greater than the given value
(function)
+
(C99)(C99)
 computes smallest integer not less than the given value
(function)
+
(C99)(C99)(C99)(C99)(C99)(C99)(C99)(C99)(C99)
 rounds to nearest integer, rounding away from zero in halfway cases
(function)
C++ documentation for trunc
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math/trunc +

+
diff --git a/devdocs/c/numeric%2Fmath.html b/devdocs/c/numeric%2Fmath.html new file mode 100644 index 00000000..aeb71314 --- /dev/null +++ b/devdocs/c/numeric%2Fmath.html @@ -0,0 +1,212 @@ +

Common mathematical functions

Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Defined in header <stdlib.h>
+
(C99)
 computes absolute value of an integral value (\(\small{|x|}\)|x|)
(function)
+
(C99)
 computes quotient and remainder of integer division
(function)
Defined in header <inttypes.h>
+
(C99)
 computes absolute value of an integral value (\(\small{|x|}\)|x|)
(function)
+
(C99)
 computes quotient and remainder of integer division
(function)
Defined in header <math.h>
Basic operations
+
(C99)(C99)
 computes absolute value of a floating-point value (\(\small{|x|}\)|x|)
(function)
+
(C99)(C99)
 computes remainder of the floating-point division operation
(function)
+
(C99)(C99)(C99)
 computes signed remainder of the floating-point division operation
(function)
+
(C99)(C99)(C99)
 computes signed remainder as well as the three last bits of the division operation
(function)
+
(C99)(C99)(C99)
 computes fused multiply-add operation
(function)
+
(C99)(C99)(C99)
 determines larger of two floating-point values
(function)
+
(C99)(C99)(C99)
 determines smaller of two floating-point values
(function)
+
(C99)(C99)(C99)
 determines positive difference of two floating-point values (\({\small\max{(0, x-y)} }\)max(0, x-y))
(function)
+
(C99)(C99)(C99)
 returns a NaN (not-a-number)
(function)
Exponential functions
+
(C99)(C99)
 computes e raised to the given power (\({\small e^x}\)ex)
(function)
+
(C99)(C99)(C99)
 computes 2 raised to the given power (\({\small 2^x}\)2x)
(function)
+
(C99)(C99)(C99)
 computes e raised to the given power, minus one (\({\small e^x-1}\)ex-1)
(function)
+
(C99)(C99)
 computes natural (base-e) logarithm (\({\small \ln{x} }\)ln(x))
(function)
+
(C99)(C99)
 computes common (base-10) logarithm (\({\small \log_{10}{x} }\)log10(x))
(function)
+
(C99)(C99)(C99)
 computes base-2 logarithm (\({\small \log_{2}{x} }\)log2(x))
(function)
+
(C99)(C99)(C99)
 computes natural (base-e) logarithm of 1 plus the given number (\({\small \ln{(1+x)} }\)ln(1+x))
(function)
Power functions
+
(C99)(C99)
 computes a number raised to the given power (\(\small{x^y}\)xy)
(function)
+
(C99)(C99)
 computes square root (\(\small{\sqrt{x} }\)√x)
(function)
+
(C99)(C99)(C99)
 computes cube root (\(\small{\sqrt[3]{x} }\)3√x)
(function)
+
(C99)(C99)(C99)
 computes square root of the sum of the squares of two given numbers (\(\scriptsize{\sqrt{x^2+y^2} }\)√x2+y2)
(function)
Trigonometric functions
+
(C99)(C99)
 computes sine (\({\small\sin{x} }\)sin(x))
(function)
+
(C99)(C99)
 computes cosine (\({\small\cos{x} }\)cos(x))
(function)
+
(C99)(C99)
 computes tangent (\({\small\tan{x} }\)tan(x))
(function)
+
(C99)(C99)
 computes arc sine (\({\small\arcsin{x} }\)arcsin(x))
(function)
+
(C99)(C99)
 computes arc cosine (\({\small\arccos{x} }\)arccos(x))
(function)
+
(C99)(C99)
 computes arc tangent (\({\small\arctan{x} }\)arctan(x))
(function)
+
(C99)(C99)
 computes arc tangent, using signs to determine quadrants
(function)
Hyperbolic functions
+
(C99)(C99)
 computes hyperbolic sine (\({\small\sinh{x} }\)sinh(x))
(function)
+
(C99)(C99)
 computes hyperbolic cosine (\({\small\cosh{x} }\)cosh(x))
(function)
+
(C99)(C99)
 computes hyperbolic tangent (\({\small\tanh{x} }\)tanh(x))
(function)
+
(C99)(C99)(C99)
 computes inverse hyperbolic sine (\({\small\operatorname{arsinh}{x} }\)arsinh(x))
(function)
+
(C99)(C99)(C99)
 computes inverse hyperbolic cosine (\({\small\operatorname{arcosh}{x} }\)arcosh(x))
(function)
+
(C99)(C99)(C99)
 computes inverse hyperbolic tangent (\({\small\operatorname{artanh}{x} }\)artanh(x))
(function)
Error and gamma functions
+
(C99)(C99)(C99)
 computes error function
(function)
+
(C99)(C99)(C99)
 computes complementary error function
(function)
+
(C99)(C99)(C99)
 computes gamma function
(function)
+
(C99)(C99)(C99)
 computes natural (base-e) logarithm of the gamma function
(function)
Nearest integer floating-point operations
+
(C99)(C99)
 computes smallest integer not less than the given value
(function)
+
(C99)(C99)
 computes largest integer not greater than the given value
(function)
+
(C99)(C99)(C99)
 rounds to nearest integer not greater in magnitude than the given value
(function)
+
(C99)(C99)(C99)(C99)(C99)(C99)(C99)(C99)(C99)
 rounds to nearest integer, rounding away from zero in halfway cases
(function)
+
(C99)(C99)(C99)
 rounds to an integer using current rounding mode
(function)
+
(C99)(C99)(C99)(C99)(C99)(C99)(C99)(C99)(C99)
 rounds to an integer using current rounding mode with
exception if the result differs
(function)
Floating-point manipulation functions
+
(C99)(C99)
 breaks a number into significand and a power of 2
(function)
+
(C99)(C99)
 multiplies a number by 2 raised to a power
(function)
+
(C99)(C99)
 breaks a number into integer and fractional parts
(function)
+
(C99)(C99)(C99)(C99)(C99)(C99)
 computes efficiently a number times FLT_RADIX raised to a power
(function)
+
(C99)(C99)(C99)
 extracts exponent of the given number
(function)
+
(C99)(C99)(C99)
 extracts exponent of the given number
(function)
+
(C99)(C99)(C99)(C99)(C99)(C99)
 determines next representable floating-point value towards the given value
(function)
+
(C99)(C99)(C99)
 produces a value with the magnitude of a given value and the sign of another given value
(function)
Classification and comparison
+
(C99)
 classifies the given floating-point value
(function macro)
+
(C99)
 checks if the given number has finite value
(function macro)
+
(C99)
 checks if the given number is infinite
(function macro)
+
(C99)
 checks if the given number is NaN
(function macro)
+
(C99)
 checks if the given number is normal
(function macro)
+
(C99)
 checks if the given number is negative
(function macro)
+
(C99)
 checks if the first floating-point argument is greater than the second
(function macro)
+
(C99)
 checks if the first floating-point argument is greater or equal than the second
(function macro)
+
(C99)
 checks if the first floating-point argument is less than the second
(function macro)
+
(C99)
 checks if the first floating-point argument is less or equal than the second
(function macro)
+
(C99)
 checks if the first floating-point argument is less or greater than the second
(function macro)
+
(C99)
 checks if two floating-point values are unordered
(function macro)

Types

+ + + + + + + +
Defined in header <stdlib.h>
structure type, return of the div function
(typedef)
structure type, return of the ldiv function
(typedef)
+
(C99)
 structure type, return of the lldiv function
(typedef)
Defined in header <inttypes.h>
+
(C99)
 structure type, return of the imaxdiv function
(typedef)
Defined in header <math.h>
+
(C99)(C99)
 most efficient floating-point type at least as wide as float or double
(typedef)

Macro constants

+ + + + + + + + +
Defined in header <math.h>
+
(C99)(C99)
 indicates value too big to be representable (infinity) by float, double and long double respectively
(macro constant)
+
(C99)
 evaluates to positive infinity or the value guaranteed to overflow a float
(macro constant)
+
(C99)
 evaluates to a quiet NaN of type float
(macro constant)
+
(C99)(C99)(C99)
 indicates that the fma function generally executes about as fast as, or faster than, a multiply and an add of double operands
(macro constant)
+
(C99)(C99)
 evaluates to ilogb(x) if x is zero or NaN, respectively
(macro constant)
+
(C99)(C99)(C99)
 defines the error handling mechanism used by the common mathematical functions
(macro constant)
Classification
+
(C99)(C99)(C99)(C99)(C99)
 indicates a floating-point category
(macro constant)

References

See also

+
C++ documentation for Common mathematical functions
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/math +

+
diff --git a/devdocs/c/numeric%2Frandom%2Frand.html b/devdocs/c/numeric%2Frandom%2Frand.html new file mode 100644 index 00000000..cd6aaf4c --- /dev/null +++ b/devdocs/c/numeric%2Frandom%2Frand.html @@ -0,0 +1,46 @@ +

rand

Defined in header <stdlib.h> 
int rand();
+

Returns a pseudo-random integer value between ​0​ and RAND_MAX (0 and RAND_MAX included).

+

srand() seeds the pseudo-random number generator used by rand(). If rand() is used before any calls to srand(), rand() behaves as if it was seeded with srand(1). Each time rand() is seeded with srand(), it must produce the same sequence of values.

+

rand() is not guaranteed to be thread-safe.

+

Parameters

(none)

+

Return value

Pseudo-random integer value between ​0​ and RAND_MAX, inclusive.

+

Notes

There are no guarantees as to the quality of the random sequence produced. In the past, some implementations of rand() have had serious shortcomings in the randomness, distribution and period of the sequence produced (in one well-known example, the low-order bit simply alternated between 1 and 0 between calls). rand() is not recommended for serious random-number generation needs, like cryptography.

+

POSIX requires that the period of the pseudo-random number generator used by rand be at least 232.

+

POSIX offered a thread-safe version of rand called rand_r, which is obsolete in favor of the drand48 family of functions.

+

Example

#include <stdio.h>
+#include <stdlib.h>
+#include <time.h>
+ 
+int main(void)
+{
+    srand(time(NULL)); // use current time as seed for random generator
+    int random_variable = rand();
+    printf("Random value on [0,%d]: %d\n", RAND_MAX, random_variable);
+ 
+    // roll a 6-sided die 20 times
+    for (int n=0; n != 20; ++n) {
+        int x = 7;
+        while(x > 6) 
+            x = 1 + rand()/((RAND_MAX + 1u)/6); // Note: 1+rand()%6 is biased
+        printf("%d ",  x); 
+    }
+}

Possible output:

+
Random value on [0,2147483647]: 448749574
+3 1 3 1 4 2 2 1 3 6 4 4 3 1 6 2 3 2 6 1

References

See also

+ + +
seeds pseudo-random number generator
(function)
maximum possible value generated by rand()
(macro constant)
C++ documentation for rand
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/random/rand +

+
diff --git a/devdocs/c/numeric%2Frandom%2Frand_max.html b/devdocs/c/numeric%2Frandom%2Frand_max.html new file mode 100644 index 00000000..3e146e2f --- /dev/null +++ b/devdocs/c/numeric%2Frandom%2Frand_max.html @@ -0,0 +1,34 @@ +

RAND_MAX

Defined in header <stdlib.h> 
#define RAND_MAX /*implementation defined*/
+

Expands to an integer constant expression equal to the maximum value returned by the function rand(). This value is implementation dependent. It's guaranteed that this value is at least 32767.

+

Example

#include <limits.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <time.h>
+ 
+int main(void)
+{
+    srand(time(NULL)); // use current time as seed for random generator
+    printf("RAND_MAX: %i\n", RAND_MAX);
+    printf("INT_MAX: %i\n", INT_MAX);
+    printf("Random value on [0,1]: %f\n", (double)rand() / RAND_MAX);
+}

Possible output:

+
RAND_MAX: 2147483647
+INT_MAX: 2147483647
+Random value on [0,1]: 0.362509

References

See also

+ + +
generates a pseudo-random number
(function)
seeds pseudo-random number generator
(function)
C++ documentation for RAND_MAX
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/random/RAND_MAX +

+
diff --git a/devdocs/c/numeric%2Frandom%2Fsrand.html b/devdocs/c/numeric%2Frandom%2Fsrand.html new file mode 100644 index 00000000..b51663b0 --- /dev/null +++ b/devdocs/c/numeric%2Frandom%2Fsrand.html @@ -0,0 +1,38 @@ +

srand

Defined in header <stdlib.h> 
void srand( unsigned seed );
+

Seeds the pseudo-random number generator used by rand() with the value seed.

+

If rand() is used before any calls to srand(), rand() behaves as if it was seeded with srand(1).

+

Each time rand() is seeded with the same seed, it must produce the same sequence of values.

+

srand() is not guaranteed to be thread-safe.

+

Parameters

+ +
seed - the seed value

Return value

(none)

+

Notes

Generally speaking, the pseudo-random number generator should only be seeded once, before any calls to rand(), and the start of the program. It should not be repeatedly seeded, or reseeded every time you wish to generate a new batch of pseudo-random numbers.

+

Standard practice is to use the result of a call to time(0) as the seed. However, time() returns a time_t value, and time_t is not guaranteed to be an integral type. In practice, though, every major implementation defines time_t to be an integral type, and this is also what POSIX requires.

+

Example

#include <stdio.h>
+#include <stdlib.h>
+#include <time.h>
+ 
+int main(void)
+{
+    srand(time(NULL)); //use current time as seed for random generator
+    int random_variable = rand();
+    printf("Random value on [0,%d]: %d\n", RAND_MAX, random_variable);
+}

Possible output:

+
Random value on [0 2147483647]: 1373858591

References

See also

+ + +
generates a pseudo-random number
(function)
maximum possible value generated by rand()
(macro constant)
C++ documentation for srand
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/random/srand +

+
diff --git a/devdocs/c/numeric%2Frandom.html b/devdocs/c/numeric%2Frandom.html new file mode 100644 index 00000000..93b1fb6a --- /dev/null +++ b/devdocs/c/numeric%2Frandom.html @@ -0,0 +1,20 @@ +

Pseudo-random number generation

+ + + +
Defined in header <stdlib.h>
generates a pseudo-random number
(function)
seeds pseudo-random number generator
(function)
maximum possible value generated by rand()
(macro constant)

References

See also

+
C++ documentation for Pseudo-random number generation
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/random +

+
diff --git a/devdocs/c/numeric%2Ftgmath.html b/devdocs/c/numeric%2Ftgmath.html new file mode 100644 index 00000000..2e53991e --- /dev/null +++ b/devdocs/c/numeric%2Ftgmath.html @@ -0,0 +1,138 @@ +

Type-generic math

The header <tgmath.h> includes the headers <math.h> and <complex.h> and defines several type-generic macros that determine which real or, when applicable, complex function to call based on the types of the arguments.

+

For each macro, the parameters whose corresponding real type in the unsuffixed math.h function is double are known as generic parameters (for example, both parameters of pow are generic parameters, but only the first parameter of scalbn is a generic parameter).

+

When a <tgmath.h> macro is used the types of the arguments passed to the generic parameters determine which function is selected by the macro as described below. If the types of the arguments are not compatible with the parameter types of the selected function, the behavior is undefined (e.g. if a complex argument is passed into a real-only <tgmath.h>'s macro: float complex fc; ceil(fc); or double complex dc; double d; fmax(dc, d); are examples of undefined behavior).

+

Note: type-generic macros were implemented in implementation-defined manner in C99, but C11 keyword _Generic makes it possible to implement these macros in portable manner.

+

Complex/real type-generic macros

For all functions that have both real and complex counterparts, a type-generic macro XXX exists, which calls either of:

+

An exception to the above rule is the fabs macro (see the table below).

+

The function to call is determined as follows:

+

The type-generic macros are as follows:

+ + + + + + + + + + + + + + + + + + + + +
Type-generic macro Real function
variants 		Complex function
variants
float
double
long double
float
double
long double
fabs fabsf fabs fabsl cabsf cabs cabsl
exp expf exp expl cexpf cexp cexpl
log logf log logl clogf clog clogl
pow powf pow powl cpowf cpow cpowl
sqrt sqrtf sqrt sqrtl csqrtf csqrt csqrtl
sin sinf sin sinl csinf csin csinl
cos cosf cos cosl ccosf ccos ccosl
tan tanf tan tanl ctanf ctan ctanl
asin asinf asin asinl casinf casin casinl
acos acosf acos acosl cacosf cacos cacosl
atan atanf atan atanl catanf catan catanl
sinh sinhf sinh sinhl csinhf csinh csinhl
cosh coshf cosh coshl ccoshf ccosh ccoshl
tanh tanhf tanh tanhl ctanhf ctanh ctanhl
asinh asinhf asinh asinhl casinhf casinh casinhl
acosh acoshf acosh acoshl cacoshf cacosh cacoshl
atanh atanhf atanh atanhl catanhf catanh catanhl

Real-only functions

For all functions that do not have complex counterparts, with the exception of modf, a type-generic macro XXX exists, which calls either of the variants of a real function:

+

The function to call is determined as follows:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Type-generic macro Real function
variants
float
double
long double
atan2 atan2f atan2 atan2l
cbrt cbrtf cbrt cbrtl
ceil ceilf ceil ceill
copysign copysignf copysign copysignl
erf erff erf erfl
erfc erfcf erfc erfcl
exp2 exp2f exp2 exp2l
expm1 expm1f expm1 expm1l
fdim fdimf fdim fdiml
floor floorf floor floorl
fma fmaf fma fmal
fmax fmaxf fmax fmaxl
fmin fminf fmin fminl
fmod fmodf fmod fmodl
frexp frexpf frexp frexpl
hypot hypotf hypot hypotl
ilogb ilogbf ilogb ilogbl
ldexp ldexpf ldexp ldexpl
lgamma lgammaf lgamma lgammal
llrint llrintf llrint llrintl
llround llroundf llround llroundl
log10 log10f log10 log10l
log1p log1pf log1p log1pl
log2 log2f log2 log2l
logb logbf logb logbl
lrint lrintf lrint lrintl
lround lroundf lround lroundl
nearbyint nearbyintf nearbyint nearbyintl
nextafter nextafterf nextafter nextafterl
nexttoward nexttowardf nexttoward nexttowardl
remainder remainderf remainder remainderl
remquo remquof remquo remquol
rint rintf rint rintl
round roundf round roundl
scalbln scalblnf scalbln scalblnl
scalbn scalbnf scalbn scalbnl
tgamma tgammaf tgamma tgammal
trunc truncf trunc truncl

Complex-only functions

For all complex number functions that do not have real counterparts, a type-generic macro cXXX exists, which calls either of the variants of a complex function:

+

The function to call is determined as follows:

+ + + + + + + + +
Type-generic macro Complex function
variants
float
double
long double
carg cargf carg cargl
conj conjf conj conjl
creal crealf creal creall
cimag cimagf cimag cimagl
cproj cprojf cproj cprojl

Example 

#include <stdio.h>
+#include <tgmath.h>
+ 
+int main(void)
+{
+    int i = 2;
+    printf("sqrt(2) = %f\n", sqrt(i)); // argument type is int, calls sqrt
+ 
+    float f = 0.5;
+    printf("sin(0.5f) = %f\n", sin(f));   // argument type is float, calls sinf
+ 
+    float complex dc = 1 + 0.5*I;
+    float complex z = sqrt(dc);      // argument type is float complex, calls csqrtf
+    printf("sqrt(1 + 0.5i) = %f+%fi\n",
+           creal(z),  // argument type is float complex, calls crealf
+           cimag(z)); // argument type is float complex, calls cimagf
+}

Output:

+
sqrt(2) = 1.414214
+sin(0.5f) = 0.479426
+sqrt(1 + 0.5i) = 1.029086+0.242934i

References

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric/tgmath +

+
diff --git a/devdocs/c/numeric.html b/devdocs/c/numeric.html new file mode 100644 index 00000000..82bd12e9 --- /dev/null +++ b/devdocs/c/numeric.html @@ -0,0 +1,31 @@ +

Numerics

The C numerics library includes common mathematical functions and types, as well as support for random number generation.

+

Common mathematical functions +

The header math.h provides standard C library mathematical functions such as fabs, sqrt, and sin.

+

Floating-point environment +

The header fenv.h defines flags and functions related to exceptional floating-point state, such as overflow and division by zero.

+

Pseudo-random number generation +

The header stdlib.h also includes C-style random number generation via srand and rand.

+

Complex number arithmetic +

The header complex.h provides types and functions about complex numbers.

+

Type-generic math +

The header tgmath.h provides some macros for a function which names XXX:

+

See also

+
C++ documentation for Numerics library
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/numeric +

+
diff --git a/devdocs/c/preprocessor%2Fconditional.html b/devdocs/c/preprocessor%2Fconditional.html new file mode 100644 index 00000000..2b4496f2 --- /dev/null +++ b/devdocs/c/preprocessor%2Fconditional.html @@ -0,0 +1,89 @@ +

Conditional inclusion

The preprocessor supports conditional compilation of parts of source file. This behavior is controlled by #if, #else, #elif, #ifdef, #ifndef, #elifdef, #elifndef(since C23), and #endif directives.

+

Syntax

+ + + + + + + + +
#if expression
#ifdef identifier
#ifndef identifier
#elif expression
#elifdef identifier (since C23)
#elifndef identifier (since C23)
#else
#endif

Explanation

The conditional preprocessing block starts with #if, #ifdef or #ifndef directive, then optionally includes any number of #elif, #elifdef, or #elifndef(since C23) directives, then optionally includes at most one #else directive and is terminated with #endif directive. Any inner conditional preprocessing blocks are processed separately.

+

Each of #if, #ifdef, #ifndef, #elif, #elifdef, #elifndef(since C23), and #else directives control code block until first #elif, #elifdef, #elifndef(since C23), #else, #endif directive not belonging to any inner conditional preprocessing blocks.

+

#if, #ifdef and #ifndef directives test the specified condition (see below) and if it evaluates to true, compiles the controlled code block. In that case subsequent #else, #elifdef, #elifndef,(since C23) and #elif directives are ignored. Otherwise, if the specified condition evaluates false, the controlled code block is skipped and the subsequent #else, #elifdef, #elifndef,(since C23) or #elif directive (if any) is processed. If the subsequent directive is #else, the code block controlled by the #else directive is unconditionally compiled. Otherwise, the #elif, #elifdef, or #elifndef(since C23) directive acts as if it was #if directive: checks for condition, compiles or skips the controlled code block based on the result, and in the latter case processes subsequent #elif, #elifdef, #elifndef,(since C23) and #else directives. The conditional preprocessing block is terminated by #endif directive.

+

Conditional evaluation

#if, #elif +

The expression is a constant expression, using only constants and identifiers, defined using #define directive. Any identifier, which is not literal, non defined using #define directive, evaluates to ​0​ except true which evaluates to 1(since C23).

+

The expression may contain unary operators in form defined identifier or defined (identifier) which return 1 if the identifier was defined using #define directive and ​0​ otherwise. In this context, __has_include, __has_embed and __has_c_attribute are treated as if they were the name of defined macros.(since C23) If the expression evaluates to nonzero value, the controlled code block is included and skipped otherwise. If any used identifier is not a constant, it is replaced with ​0​.

+ + +

In context of a preprocessor directive, a __has_c_attribute expression detects whether a given attribute token is supported and its supported version. See Attribute testing.

+		 (since C23)

Note: Until DR 412, #if cond1 ... #elif cond2 is different from #if cond1 ... #else followed by #if cond3 because if cond1 is true, the second #if is skipped and cond3 does not need to be well-formed, while #elif's cond2 must be a valid expression. As of DR 412, #elif that leads the skipped code block is also skipped.

+

Combined directives

Checks if the identifier was defined as a macro name.

+

#ifdef identifier is essentially equivalent to #if defined identifier.

+

#ifndef identifier is essentially equivalent to #if !defined identifier.

+ + +

#elifdef identifier is essentially equivalent to #elif defined identifier.

+

#elifndef identifier is essentially equivalent to #elif !defined identifier.

+		 (since C23)

Notes

While #elifdef and #elifndef directives target C23, implementations may backport them to the older language modes as conforming extensions.

+

Example

#define ABCD 2
+#include <stdio.h>
+ 
+int main(void)
+{
+ 
+#ifdef ABCD
+    printf("1: yes\n");
+#else
+    printf("1: no\n");
+#endif
+ 
+#ifndef ABCD
+    printf("2: no1\n");
+#elif ABCD == 2
+    printf("2: yes\n");
+#else
+    printf("2: no2\n");
+#endif
+ 
+#if !defined(DCBA) && (ABCD < 2 * 4 - 3)
+    printf("3: yes\n");
+#endif
+ 
+// C23 directives #elifdef/#elifndef
+#ifdef CPU
+    printf("4: no1\n");
+#elifdef GPU
+    printf("4: no2\n");
+#elifndef RAM
+    printf("4: yes\n"); // selected in C23 mode, may be selected in pre-C23 mode
+#else
+    printf("4: no3\n"); // may be selected in pre-C23 mode
+#endif
+}

Possible output:

+
1: yes
+2: yes
+3: yes
+4: yes

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C standards.

+ + + +
DR Applied to Behavior as published Correct behavior
+DR 412 C89 failed #elif's expression was required to be valid failed #elif is skipped

References

See also

+
C++ documentation for Conditional inclusion
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/preprocessor/conditional +

+
diff --git a/devdocs/c/preprocessor%2Fembed.html b/devdocs/c/preprocessor%2Fembed.html new file mode 100644 index 00000000..62c39019 --- /dev/null +++ b/devdocs/c/preprocessor%2Fembed.html @@ -0,0 +1,112 @@ +

Binary resource inclusion (since C23) +

#embed is a preprocessor directive to include (binary) resources in the build, where a resource is defined as a source of data accessible from the translation environment.

+

Syntax

+ + + + + +
#embed < h-char-sequence > embed-parameter-sequence (optional) new-line (1)
#embed " q-char-sequence " embed-parameter-sequence (optional) new-line (2)
#embed pp-tokens new-line (3)
__has_embed ( " q-char-sequence " embed-parameter-sequence (optional) )
__has_embed ( < h-char-sequence > embed-parameter-sequence (optional) ) 		(4)
__has_embed ( string-literal pp-balanced-token-sequence (optional) )
__has_embed ( < h-pp-tokens > pp-balanced-token-sequence (optional) ) 		(5)
+1) Searches for a resource identified uniquely by h-char-sequence and replaces the directive by a comma separated list of integers corresponding to the data of the resource.
+2) Searches for a resource identified by q-char-sequence and replaces the directive by a list of integers corresponding to the data of the resource. It may fallback to (1).
+3) If neither (1) nor (2) is matched, pp-tokens will undergo macro replacement. The directive after replacement will be tried to match with (1) or (2) again.
+4) Checks whether a resource is available for embedding, whether it is empty or not and whether the parameters passed are supported by the implementation.
+5) If (4) is not matched, h-pp-tokens and pp-balanced-token-sequence will undergo macro replacement. The directive after replacement will be tried to match with (4) again.
+ + + + + + + + + + + +
new-line - The new-line character
h-char-sequence - A sequence of one or more h-chars, where the appearance of any of the following causes undefined behavior:
    +
  • the character '
    • +
  • the character "
    • +
  • the character \
    • +
  • the character sequence //
    • +
  • the character sequence /*
    • +
h-char - Any member of the source character set except new-line and >
q-char-sequence - A sequence of one or more q-chars, where the appearance of any of the following causes undefined behavior:
    +
  • the character '
    • +
  • the character \
    • +
  • the character sequence //
    • +
  • the character sequence /*
    • +
q-char - Any member of the source character set except new-line and "
pp-tokens - A sequence of one or more preprocessing tokens
string-literal - A string literal
h-pp-tokens - A sequence of one or more preprocessing tokens except >
embed-parameter-sequence - A sequence of one or more pp-parameter s. Note that unlike an attribute-list, this sequence is not comma separated.
pp-parameter - An attribute-token (see: attributes) but comprised of preprocessing tokens instead of tokens.
pp-balanced-token-sequence - A balanced-token-sequence (see: attributes) but comprised of preprocessing tokens instead of tokens

Explanation

+1) Searches for the resource identified by h-char-sequence in implementation-defined manner.
+2) Searches for the resource identified by q-char-sequence in implementation-defined manner. For (1,2), the implementations typically use a mechanism similar to, but distinct from, the implementation-defined search paths used for source file inclusion. The construct __has_embed(__FILE__ ... appears in one of the examples in the standard, suggesting, in case (2) at least, that the directory where the current file resides is expected to be searched.
+3) The preprocessing tokens after embed in the directive are processed just as in normal text (i.e., each identifier currently defined as a macro name is replaced by its replacement list of preprocessing tokens). The directive resulting after all replacements shall match one of the two previous forms. The method by which a sequence of preprocessing tokens between < and > preprocessing token pair or a pair of " characters is combined into a single header name preprocessing token is implementation-defined.
+4) The resource identified by h-char-sequence or q-char-sequence is searched for as if that preprocessing token sequence were the pp-tokens in syntax (3), except that no further macro expansion is performed. If such a directive would not satisfy the syntactic requirements of an #embed directive, the program is ill-formed. The __has__embed expression evaluates to __STDC_EMBED_FOUND__ if the search for the resource succeeds, the resource is non empty and all the parameters are supported, to __STDC_EMBED_EMPTY__ if the resource is empty and all the parameters are supported, and to __STDC_EMBED_NOT_FOUND__ if the search fails or one of the parameters passed is not supported by the implementation.
+5) This form is considered only if syntax (4) does not match, in which case the preprocessing tokens are processed just as in normal text.

In the case the resource is not found or one of the parameters is not supported by the implementation, the program is ill-formed.

+

__has_embed can be expanded in the expression of #if and #elif. It is treated as a defined macro by #ifdef, #ifndef, #elifdef, #elifndef and defined but cannot be used anywhere else.

+

A resource has an implementation resource width which is the implementation-defined size in bits of the located resource. Its resource width is the implementation resource width unless modified by a limit parameter. If the resource width is 0, the resource is considered empty. The embed element width is equal to CHAR_BIT unless modified by an implementation defined parameter. The resource width must be divisible by the embed element width.

+

The expansion of a #embed directive is a token sequence formed from the list of integer constant expressions described below. The group of tokens for each integer constant expression in the list is separated in the token sequence from the group of tokens for the previous integer constant expression in the list by a comma. The sequence neither begins nor ends in a comma. If the list of integer constant expressions is empty, the token sequence is empty. The directive is replaced by its expansion and, with the presence of certain embed parameters, additional or replacement token sequences.

+

The values of the integer constant expressions in the expanded sequence are determined by an implementation-defined mapping of the resource’s data. Each integer constant expression’s value is in the range [0, 2embed element width). If:

+
    +
  1. The list of integer constant expressions is used to initialize an array of a type compatible with unsigned char, or compatible with char if char cannot hold negative values, and
    2. +
  2. The embed element width is equal to CHAR_BIT,
    3. +

then the contents of the initialized elements of the array are as-if the resource’s binary data is fread into the array at translation time.

+

Implementations are encouraged to take into account translation-time bit and byte orders as well as execution-time bit and byte orders to more appropriately represent the resource’s binary data from the directive. This maximizes the chance that, if the resource referenced at translation time through the #embed directive is the same one accessed through execution-time means, the data that is e.g. fread or similar into contiguous storage will compare bit-for-bit equal to an array of character type initialized from an #embed directive’s expanded contents.

+

Parameters

The standard defines the parameters limit, prefix, suffix and if_empty. Any other parameter that appears in the directive must be implementation-defined, or the program is ill-formed. Implementation-defined embed parameters may change the semantics of the directive.

+

limit

+ + +
limit( constant-expression ) (1)
__limit__( constant-expression ) (2)

The limit embed parameter can appear at most once in the embed parameter sequence. It must have an argument, which must be an integer (preprocessor) constant expression that evaluates to a non negative number and does not contain the token defined. The resource width is set to the minimum of the integer constant expression multiplied by the embed element width and the implementation resource width.

+

suffix

+ + +
suffix( pp-balanced-token-sequence (optional) ) (1)
__suffix__( pp-balanced-token-sequence (optional) ) (2)

The suffix embed parameter can appear at most once in the embed parameter sequence. It must have a (possibly empty) preprocessor argument clause. If the resource is non empty, the contents of the parameter clause are placed immediately after the expansion of the directive. Otherwise, it has no effect.

+

prefix

+ + +
prefix( pp-balanced-token-sequence (optional) ) (1)
__prefix__( pp-balanced-token-sequence (optional) ) (2)

The prefix embed parameter can appear at most once in the embed parameter sequence. It must have a (possibly empty) preprocessor argument clause. If the resource is non empty, the contents of the parameter clause are placed immediately before the expansion of the directive. Otherwise, it has no effect.

+

if_empty

+ + +
if_empty( pp-balanced-token-sequence (optional) ) (1)
__if_empty__( pp-balanced-token-sequence (optional) ) (2)

The if_empty embed parameter can appear at most once in the embed parameter sequence. It must have a (possibly empty) preprocessor argument clause. If the resource is empty, the contents of the parameter clause replace the directive. Otherwise, it has no effect.

+

Example

#include <stdint.h>
+#include <stdio.h>
+ 
+const uint8_t image_data[] = {
+#embed "image.png"
+};
+ 
+const char message[] = {
+#embed "message.txt" if_empty('M', 'i', 's', 's', 'i', 'n', 'g', '\n')
+,'\0' // null terminator
+};
+ 
+void dump(const uint8_t arr[], size_t size)
+{
+    for (size_t i = 0; i != size; ++i)
+        printf("%02X%c", arr[i], (i + 1) % 16 ? ' ' : '\n');
+    puts("");
+}
+ 
+int main()
+{
+    puts("image_data[]:");
+    dump(image_data, sizeof image_data);
+    puts("message[]:");
+    dump((const uint8_t*)message, sizeof message);
+}

Possible output:

+
image_data[]:
+89 50 4E 47 0D 0A 1A 0A 00 00 00 0D 49 48 44 52
+00 00 00 01 00 00 00 01 01 03 00 00 00 25 DB 56
+...
+message[]:
+4D 69 73 73 69 6E 67 0A 00

References

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/preprocessor/embed +

+
diff --git a/devdocs/c/preprocessor%2Ferror.html b/devdocs/c/preprocessor%2Ferror.html new file mode 100644 index 00000000..decd26b2 --- /dev/null +++ b/devdocs/c/preprocessor%2Ferror.html @@ -0,0 +1,37 @@ +

Diagnostic directives

Shows the given error message and renders the program ill-formed, or given warning message without affect the validity of the program(since C23).

+

Syntax

+ + +
#error diagnostic-message (1)
#warning diagnostic-message (2) (since C23)

Explanation

+1) After encountering the #error directive, an implementation displays the message diagnostic-message and renders the program ill-formed (the compilation stops).
+2) Same as (1), except that the validity of the program is not affected and the compilation continues.

diagnostic-message can consist of several words not necessarily in quotes.

+

Notes

Before its standardization in C23, #warning has been provided by many compilers in all modes as a conforming extension.

+

Example

#if __STDC__ != 1
+#  error "Not a standard compliant compiler"
+#endif
+ 
+#if __STDC_VERSION__ >= 202311L
+#  warning "Using #warning as a standard feature"
+#endif
+ 
+#include <stdio.h>
+int main (void)
+{
+    printf("The compiler used conforms to the ISO C Standard !!");
+}

Possible output:

+
The compiler used conforms to the ISO C Standard !!

References

See also

+
C++ documentation for Diagnostic directives
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/preprocessor/error +

+
diff --git a/devdocs/c/preprocessor%2Fimpl.html b/devdocs/c/preprocessor%2Fimpl.html new file mode 100644 index 00000000..3ef1cf4a --- /dev/null +++ b/devdocs/c/preprocessor%2Fimpl.html @@ -0,0 +1,82 @@ +

Implementation defined behavior control

Implementation defined behavior is controlled by #pragma directive.

+

Syntax

+ + +
#pragma pragma_params (1)
_Pragma ( string-literal ) (2) (since C99)
+1) Behaves in an implementation-defined manner (unless pragma_params is one of the standard pragmas shown below).
+2) Removes the encoding prefix (if any), the outer quotes, and leading/trailing whitespace from string-literal, replaces each \" with " and each \\ with \, then tokenizes the result (as in translation stage 3), and then uses the result as if the input to #pragma in (1).

Explanation

The pragma directive controls implementation-specific behavior of the compiler, such as disabling compiler warnings or changing alignment requirements. Any pragma that is not recognized is ignored.

+

Standard pragmas

The following three pragmas are defined by the language standard:

+ + + + +
#pragma STDC FENV_ACCESS arg (1) (since C99)
#pragma STDC FP_CONTRACT arg (2) (since C99)
#pragma STDC CX_LIMITED_RANGE arg (3) (since C99)

where arg is either ON or OFF or DEFAULT.

+
+1) If set to ON, informs the compiler that the program will access or modify floating-point environment, which means that optimizations that could subvert flag tests and mode changes (e.g., global common subexpression elimination, code motion, and constant folding) are prohibited. The default value is implementation-defined, usually OFF.
+2) Allows contracting of floating-point expressions, that is optimizations that omit rounding errors and floating-point exceptions that would be observed if the expression was evaluated exactly as written. For example, allows the implementation of (x * y) + z with a single fused multiply-add CPU instruction. The default value is implementation-defined, usually ON.
+3) Informs the compiler that multiplication, division, and absolute value of complex numbers may use simplified mathematical formulas (x+iy)×(u+iv) = (xu-yv)+i(yu+xv), (x+iy)/(u+iv) = [(xu+yv)+i(yu-xv)]/(u2+v2), and |x+iy| = √x2+y2, despite the possibility of intermediate overflow. In other words, the programmer guarantees that the range of the values that will be passed to those function is limited. The default value is OFF +

Note: compilers that do not support these pragmas may provide equivalent compile-time options, such as gcc's -fcx-limited-range and -ffp-contract.

+

Non-standard pragmas

#pragma once +

#pragma once is a non-standard pragma that is supported by the vast majority of modern compilers. If it appears in a header file, it indicates that it is only to be parsed once, even if it is (directly or indirectly) included multiple times in the same source file.

+

Standard approach to preventing multiple inclusion of the same header is by using include guards:

+
#ifndef LIBRARY_FILENAME_H
+#define LIBRARY_FILENAME_H
+// contents of the header
+#endif /* LIBRARY_FILENAME_H */

So that all but the first inclusion of the header in any translation unit are excluded from compilation. All modern compilers record the fact that a header file uses an include guard and do not re-parse the file if it is encountered again, as long as the guard is still defined (see e.g. gcc).

+

With #pragma once, the same header appears as

+
#pragma once
+// contents of the header

Unlike header guards, this pragma makes it impossible to erroneously use the same macro name in more than one file. On the other hand, since with #pragma once files are excluded based on their filesystem-level identity, this can't protect against including a header twice if it exists in more than one location in a project.

+

#pragma pack +

This family of pragmas control the maximum alignment for subsequently defined structure and union members.

+ + + + + + +
#pragma pack(arg) (1)
#pragma pack() (2)
#pragma pack(push) (3)
#pragma pack(push, arg) (4)
#pragma pack(pop) (5)

where arg is a small power of two and specifies the new alignment in bytes.

+
+1) Sets the current alignment to value arg.
+2) Sets the current alignment to the default value (specified by a command-line option).
+3) Pushes the value of the current alignment on an internal stack.
+4) Pushes the value of the current alignment on the internal stack and then sets the current alignment to value arg.
+5) Pops the top entry from the internal stack and then sets (restores) the current alignment to that value.

#pragma pack may decrease the alignment of a structure, however, it cannot make a structure overaligned.

+

See also specific details for GCC and MSVC.

+

References

See also

+
C++ documentation for Implementation defined behavior control
+ + + + + + +
1. +C++ pragmas in Visual Studio 2019
2. +Pragmas accepted by GCC
3. +Individual pragma descriptions and Standard pragmas in IBM AIX XL C 16.1
4. +Appendix B. Pragmas in Sun Studio 11 C++ User's Guide
5. +Intel C++ compiler pragmas
6. +HP aCC compiler pragmas
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/preprocessor/impl +

+
diff --git a/devdocs/c/preprocessor%2Finclude.html b/devdocs/c/preprocessor%2Finclude.html new file mode 100644 index 00000000..b4bf7c7b --- /dev/null +++ b/devdocs/c/preprocessor%2Finclude.html @@ -0,0 +1,72 @@ +

Source file inclusion

Includes another source file into the current source file at the line immediately after the directive.

+

Syntax

+ + + + + +
#include < h-char-sequence > new-line (1)
#include " q-char-sequence " new-line (2)
#include pp-tokens new-line (3)
__has_include ( " q-char-sequence " )
__has_include ( < h-char-sequence > ) 		(4) (since C23)
__has_include ( string-literal )
__has_include ( < h-pp-tokens > ) 		(5) (since C23)
+1) Searches for a header identified uniquely by h-char-sequence and replaces the directive by the entire contents of the header.
+2) Searches for a source file identified by q-char-sequence and replaces the directive by the entire contents of the source file. It may fallback to (1) and treat q-char-sequence as a header identifier.
+3) If neither (1) nor (2) is matched, pp-tokens will undergo macro replacement. The directive after replacement will be tried to match with (1) or (2) again.
+4) Checks whether a header or source file is available for inclusion.
+5) If (4) is not matched, h-pp-tokens will undergo macro replacement. The directive after replacement will be tried to match with (4) again.
+ + + + + + + + +
new-line - The new-line character
h-char-sequence - A sequence of one or more h-chars, where the appearance of any of the following causes undefined behavior:
    +
  • the character '
    • +
  • the character "
    • +
  • the character \
    • +
  • the character sequence //
    • +
  • the character sequence /*
    • +
h-char - Any member of the source character set except new-line and >
q-char-sequence - A sequence of one or more q-chars, where the appearance of any of the following causes undefined behavior:
    +
  • the character '
    • +
  • the character \
    • +
  • the character sequence //
    • +
  • the character sequence /*
    • +
q-char - Any member of the source character set except new-line and "
pp-tokens - A sequence of one or more preprocessing tokens
string-literal - A string literal
h-pp-tokens - A sequence of one or more preprocessing tokens except >

Explanation

+1) Searches for the file identified by h-char-sequence in implementation-defined manner. The intent of this syntax is to search for the files under control of the implementation. Typical implementations search only standard include directories. The standard C library is implicitly included in these standard include directories. The standard include directories usually can be controlled by the user through compiler options.
+2) Searches for the file identified by q-char-sequence in implementation-defined manner. The intent of this syntax is to search for the files that are not controlled by the implementation. Typical implementations first search the directory where the current file resides and, only if the file is not found, search the standard include directories as with (1).
+3) The preprocessing tokens after include in the directive are processed just as in normal text (i.e., each identifier currently defined as a macro name is replaced by its replacement list of preprocessing tokens). The directive resulting after all replacements shall match one of the two previous forms. The method by which a sequence of preprocessing tokens between < and > preprocessing token pair or a pair of " characters is combined into a single header name preprocessing token is implementation-defined.
+4) The header or source file identified by h-char-sequence or q-char-sequence is searched for as if that preprocessing token sequence were the pp-tokens in syntax (3), except that no further macro expansion is performed. If such a directive would not satisfy the syntactic requirements of an #include directive, the program is ill-formed. The __has_include expression evaluates to 1 if the search for the source file succeeds, and to ​0​ if the search fails.
+5) This form is considered only if syntax (4) does not match, in which case the preprocessing tokens are processed just as in normal text.

In the case the file is not found, the program is ill-formed.

+ + +

__has_include can be expanded in the expression of #if and #elif. It is treated as a defined macro by #ifdef, #ifndef, #elifdef, #elifndef and defined but cannot be used anywhere else.

+		 (since C23)

Notes

Typical implementations search only standard include directories for syntax (1). The standard C library is implicitly included in these standard include directories. The standard include directories usually can be controlled by the user through compiler options.

+

The intent of syntax (2) is to search for the files that are not controlled by the implementation. Typical implementations first search the directory where the current file resides then falls back to (1).

+

When a file is included, it is processed by translation phases 1-4, which may include, recursively, expansion of the nested #include directives, up to an implementation-defined nesting limit. To avoid repeated inclusion of the same file and endless recursion when a file includes itself, perhaps transitively, header guards are commonly used: the entire header is wrapped in

+
#ifndef FOO_H_INCLUDED /* any name uniquely mapped to file name */
+#define FOO_H_INCLUDED
+// contents of the file are here
+#endif

Many compilers also implement the non-standard pragma #pragma once with similar effects: it disables processing of a file if the same file (where file identity is determined in OS-specific way) has already been included.

+

A __has_include result of 1 only means that a header or source file with the specified name exists. It does not mean that the header or source file, when included, would not cause an error or would contain anything useful.

+

Example

References

See also

+ +
A list of C Standard Library header files
C++ documentation for Source file inclusion
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/preprocessor/include +

+
diff --git a/devdocs/c/preprocessor%2Fline.html b/devdocs/c/preprocessor%2Fline.html new file mode 100644 index 00000000..92993911 --- /dev/null +++ b/devdocs/c/preprocessor%2Fline.html @@ -0,0 +1,37 @@ +

Filename and line information

Changes the current line number and file name in the preprocessor.

+

Syntax

+ + +
#line lineno (1)
#line lineno "filename" (2)

Explanation

+1) Changes the current preprocessor line number to lineno. Occurrences of the macro __LINE__ beyond this point will expand to lineno plus the number of actual source code lines encountered since.
+2) Also changes the current preprocessor file name to filename. Occurrences of the macro __FILE__ beyond this point will produce filename.

Any preprocessing tokens (macro constants or expressions) are permitted as arguments to #line as long as they expand to a valid decimal integer optionally following a valid character string.

+

lineno must be a sequence of at least one decimal digit (the program is ill-formed, otherwise) and is always interpreted as decimal (even if it starts with 0).

+

If lineno is 0 or greater than 32767(until C99)2147483647(since C99), the behavior is undefined.

+

Notes

This directive is used by some automatic code generation tools which produce C source files from a file written in another language. In that case, #line directives may be inserted in the generated C file referencing line numbers and the file name of the original (human-editable) source file.

+

The line number following the directive #line __LINE__ is unspecified (there are two possible values that __LINE__ can expand to in this case: number of endlines seen so far, or number of endlines seen so far plus the endline that ends the #line directive). This is the result of DR 464, which applies retroactively.

+

Example

#include <assert.h>
+#define FNAME "test.c"
+int main(void)
+{
+#line 777 FNAME
+        assert(2+2 == 5);
+}

Possible output:

+
test: test.c:777: int main(): Assertion `2+2 == 5' failed.

References

See also

+
C++ documentation for Filename and line information
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/preprocessor/line +

+
diff --git a/devdocs/c/preprocessor%2Freplace.html b/devdocs/c/preprocessor%2Freplace.html new file mode 100644 index 00000000..19c051cf --- /dev/null +++ b/devdocs/c/preprocessor%2Freplace.html @@ -0,0 +1,160 @@ +

Replacing text macros

The preprocessor supports text macro replacement and function-like text macro replacement.

+

Syntax

+ + + + + +
#define identifier replacement-list (optional) (1)
#define identifier ( parameters ) replacement-list (2)
#define identifier ( parameters, ... ) replacement-list (3) (since C99)
#define identifier ( ... ) replacement-list (4) (since C99)
#undef identifier (5)

Explanation

#define directives

The #define directives define the identifier as a macro, that is they instruct the compiler to replace all successive occurrences of identifier with replacement-list, which can be optionally additionally processed. If the identifier is already defined as any type of macro, the program is ill-formed unless the definitions are identical.

+
Object-like macros

Object-like macros replace every occurrence of a defined identifier with replacement-list. Version (1) of the #define directive behaves exactly like that.

+
Function-like macros

Function-like macros replace each occurrence of a defined identifier with replacement-list, additionally taking a number of arguments, which then replace corresponding occurrences of any of the parameters in the replacement-list.

+

The syntax of a function-like macro invocation is similar to the syntax of a function call: each instance of the macro name followed by a ( as the next preprocessing token introduces the sequence of tokens that is replaced by the replacement-list. The sequence is terminated by the matching ) token, skipping intervening matched pairs of left and right parentheses.

+

The number of arguments must be the same as the number of arguments in the macro definition (parameters) or the program is ill-formed. If the identifier is not in functional-notation, i.e. does not have parentheses after itself, it is not replaced at all.

+

Version (2) of the #define directive defines a simple function-like macro.

+

Version (3) of the #define directive defines a function-like macro with variable number of arguments. The additional arguments can be accessed using __VA_ARGS__ identifier, which is then replaced with arguments, supplied with the identifier to be replaced.

+

Version (4) of the #define directive defines a function-like macro with variable number of arguments, but no regular arguments. The arguments can be accessed only with __VA_ARGS__ identifier, which is then replaced with arguments, supplied with identifier to be replaced.

+ + +

For versions (3,4), replacement-list may contain the token sequence __VA_OPT__ ( content ), which is replaced by content if __VA_ARGS__ is non-empty, and expands to nothing otherwise.

+
#define F(...) f(0 __VA_OPT__(,) __VA_ARGS__)
+F(a, b, c) // replaced by f(0, a, b, c)
+F()        // replaced by f(0)
+ 
+#define G(X, ...) f(0, X __VA_OPT__(,) __VA_ARGS__)
+G(a, b, c) // replaced by f(0, a, b, c)
+G(a, )     // replaced by f(0, a)
+G(a)       // replaced by f(0, a)
+ 
+#define SDEF(sname, ...) S sname __VA_OPT__(= { __VA_ARGS__ })
+SDEF(foo);       // replaced by S foo;
+SDEF(bar, 1, 2); // replaced by S bar = { 1, 2 };
 (since C23)


Note: if an argument of a function-like macro includes commas that are not protected by matched pairs of left and right parentheses (such as macro(array[x = y, x + 1]) or atomic_store (p, (struct S){ a, b });), the comma is interpreted as macro argument separator, causing a compilation failure due to argument count mismatch.

+

# and ## operators

In function-like macros, a # operator before an identifier in the replacement-list runs the identifier through parameter replacement and encloses the result in quotes, effectively creating a string literal. In addition, the preprocessor adds backslashes to escape the quotes surrounding embedded string literals, if any, and doubles the backslashes within the string as necessary. All leading and trailing whitespace is removed, and any sequence of whitespace in the middle of the text (but not inside embedded string literals) is collapsed to a single space. This operation is called "stringification". If the result of stringification is not a valid string literal, the behavior is undefined.

+ + +

When # appears before __VA_ARGS__, the entire expanded __VA_ARGS__ is enclosed in quotes:

+
#define showlist(...) puts(#__VA_ARGS__)
+showlist();            // expands to puts("")
+showlist(1, "x", int); // expands to puts("1, \"x\", int")
 (since C99)

A ## operator between any two successive identifiers in the replacement-list runs parameter replacement on the two identifiers and then concatenates the result. This operation is called "concatenation" or "token pasting". Only tokens that form a valid token together may be pasted: identifiers that form a longer identifier, digits that form a number, or operators + and = that form a +=. A comment cannot be created by pasting / and * because comments are removed from text before macro substitution is considered. If the result of concatenation is not a valid token, the behavior is undefined.

+

Note: Some compilers offer an extension that allows ## to appear after a comma and before __VA_ARGS__, in which case the ## does nothing when __VA_ARGS__ is non-empty, but removes the comma when __VA_ARGS__ is empty: this makes it possible to define macros such as fprintf (stderr, format, ##__VA_ARGS__).

+

The order of evaluation of # and ## operators is unspecified.

+

#undef directive

The #undef directive undefines the identifier, that is it cancels the previous definition of the identifier by #define directive. If the identifier does not have an associated macro, the directive is ignored.

+

Predefined macros

The following macro names are predefined in any translation unit:

+ + + + + + + + + + +
__STDC__
 expands to the integer constant 1. This macro is intended to indicate a conforming implementation
(macro constant)
__STDC_VERSION__
+
(C95)
 expands to an integer constant of type long whose value increases with each version of the C standard:
    +
  • 199409L (C95)
    • +
  • 199901L (C99)
    • +
  • 201112L (C11)
    • +
  • 201710L (C17)
    • +
  • 202311L (C23)
    (macro constant)
    • +
__STDC_HOSTED__
+
(C99)
 expands to the integer constant 1 if the implementation is hosted (runs under an OS), ​0​ if freestanding (runs without an OS)
(macro constant)
__FILE__
 expands to the name of the current file, as a character string literal, can be changed by the #line directive
(macro constant)
__LINE__
 expands to the source file line number, an integer constant, can be changed by the #line directive
(macro constant)
__DATE__
 expands to the date of translation, a character string literal of the form "Mmm dd yyyy". The name of the month is as if generated by asctime and the first character of "dd" is a space if the day of the month is less than 10
(macro constant)
__TIME__
 expands to the time of translation, a character string literal of the form "hh:mm:ss", as in the time generated by asctime()
(macro constant)
__STDC_UTF_16__
+
(C23)
 expands to 1 to indicate that char16_t use UTF-16 encoding
(macro constant)
__STDC_UTF_32__
+
(C23)
 expands to 1 to indicate that char32_t use UTF-32 encoding
(macro constant)
__STDC_EMBED_NOT_FOUND____STDC_EMBED_FOUND____STDC_EMBED_EMPTY__
+
(C23)
 expand to ​0​, 1, and 2, respectively
(macro constant)

The following additional macro names may be predefined by an implementation:

+ + + + + + + + + + + + + + + + +
__STDC_ISO_10646__
+
(C99)
 expands to an integer constant of the form yyyymmL, if wchar_t uses Unicode; the date indicates the latest revision of Unicode supported
(macro constant)
__STDC_IEC_559__
+
(C99)
 expands to 1 if IEC 60559 is supported (deprecated)(since C23)
(macro constant)
__STDC_IEC_559_COMPLEX__
+
(C99)
 expands to 1 if IEC 60559 complex arithmetic is supported (deprecated)(since C23)
(macro constant)
__STDC_UTF_16__
+
(C11)
 expands to 1 if char16_t use UTF-16 encoding
(macro constant)
__STDC_UTF_32__
+
(C11)
 expands to 1 if char32_t use UTF-32 encoding
(macro constant)
__STDC_MB_MIGHT_NEQ_WC__
+
(C99)
 expands to 1 if 'x' == L'x' might be false for a member of the basic character set, such as on EBCDIC-based systems that use Unicode for wchar_t
(macro constant)
__STDC_ANALYZABLE__
+
(C11)
 expands to 1 if analyzability is supported
(macro constant)
__STDC_LIB_EXT1__
+
(C11)
 expands to an integer constant 201112L if bounds-checking interfaces are supported
(macro constant)
__STDC_NO_ATOMICS__
+
(C11)
 expands to 1 if atomic types and atomic operations library are not supported
(macro constant)
__STDC_NO_COMPLEX__
+
(C11)
 expands to 1 if complex types and complex math library are not supported
(macro constant)
__STDC_NO_THREADS__
+
(C11)
 expands to 1 if multithreading is not supported
(macro constant)
__STDC_NO_VLA__
+
(C11)
 expands to 1 if variable-length arrays and variably-modified types(until C23)of automatic storage duration(since C23) are not supported
(macro constant)
__STDC_IEC_60559_BFP__
+
(C23)
 expands to 202311L if IEC 60559 binary floating-point arithmetic is supported
(macro constant)
__STDC_IEC_60559_DFP__
+
(C23)
 expands to 202311L if IEC 60559 decimal floating-point arithmetic is supported
(macro constant)
__STDC_IEC_60559_COMPLEX__
+
(C23)
 expands to 202311L if IEC 60559 complex arithmetic is supported
(macro constant)
__STDC_IEC_60559_TYPES__
+
(C23)
 expands to 202311L if IEC 60559 interchange and extended types are supported
(macro constant)

The values of these macros (except for __FILE__ and __LINE__) remain constant throughout the translation unit. Attempts to redefine or undefine these macros result in undefined behavior.

+ + +

The predefined variable __func__ (see function definition for details) is not a preprocessor macro, even though it is sometimes used together with __FILE__ and __LINE__, e.g. by assert.

+		 (since C99)

Example

#include <stdio.h>
+ 
+// make function factory and use it
+#define FUNCTION(name, a) int fun_##name(int x) { return (a) * x; }
+ 
+FUNCTION(quadruple, 4)
+FUNCTION(double, 2)
+ 
+#undef FUNCTION
+#define FUNCTION 34
+#define OUTPUT(a) puts( #a )
+ 
+int main(void)
+{
+    printf("quadruple(13): %d\n", fun_quadruple(13) );
+    printf("double(21): %d\n", fun_double(21) );
+    printf("%d\n", FUNCTION);
+    OUTPUT(billion);               // note the lack of quotes
+}

Output:

+
quadruple(13): 52
+double(21): 42
+34
+billion

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C standards.

+ + + +
DR Applied to Behavior as published Correct behavior
+DR 321 C99 it was unclear if L'x' == 'x' always holds
among the basic character set 		+__STDC_MB_MIGHT_NEQ_WC__ added for the purpose

References

See also

+
C++ documentation for Replacing text macros
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/preprocessor/replace +

+
diff --git a/devdocs/c/preprocessor.html b/devdocs/c/preprocessor.html new file mode 100644 index 00000000..1300711b --- /dev/null +++ b/devdocs/c/preprocessor.html @@ -0,0 +1,36 @@ +

Preprocessor

The preprocessor is executed at translation phase 4, before the compilation. The result of preprocessing is a single file which is then passed to the actual compiler.

+

Directives

The preprocessing directives control the behavior of the preprocessor. Each directive occupies one line and has the following format:

+

The null directive (# followed by a line break) is allowed and has no effect.

+

Capabilities

The preprocessor has the source file translation capabilities:

+

The following aspects of the preprocessor can be controlled:

+

Footnotes

  1. These are the directives defined by the standard. The standard does not define behavior for other directives: they might be ignored, have some useful meaning, or make the program ill-formed. Even if otherwise ignored, they are removed from the source code when the preprocessor is done. A common non-standard extension is the directive #warning which emits a user-defined message during compilation.(until C23)

References

See also

+ + +
C documentation for Predefined Macro Symbols
C documentation for Macro Symbol Index
C++ documentation for Preprocessor
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/preprocessor +

+
diff --git a/devdocs/c/program%2F_exit.html b/devdocs/c/program%2F_exit.html new file mode 100644 index 00000000..4fc7cd21 --- /dev/null +++ b/devdocs/c/program%2F_exit.html @@ -0,0 +1,48 @@ +

_Exit

Defined in header <stdlib.h> 
void _Exit( int exit_code );
 +(since C99)
(until C11) +		 
_Noreturn void _Exit( int exit_code );
+		 (since C11)
(until C23) 
[[noreturn]] void _Exit( int exit_code );
+		 (since C23)

Causes normal program termination to occur without completely cleaning the resources.

+

Functions passed to at_quick_exit() or atexit() are not called. Whether open streams with unwritten buffered data are flushed, open streams are closed, or temporary files are removed is implementation-defined.

+

If exit_code is 0 or EXIT_SUCCESS, an implementation-defined status indicating successful termination is returned to the host environment. If exit_code is EXIT_FAILURE, an implementation-defined status, indicating unsuccessful termination, is returned. In other cases an implementation-defined status value is returned.

+

Parameters

+ +
exit_code - exit status of the program

Return value

(none)

+

Example

#include <stdlib.h>
+#include <stdio.h>
+ 
+/* _Exit does not call functions registered with atexit. */
+void f1(void)
+{
+    puts("pushed first");
+}
+ 
+void f2(void)
+{
+    puts("pushed second");
+}
+ 
+int main(void)
+{
+    printf("Enter main()\n");
+    atexit(f1);
+    atexit(f2);
+    fflush(stdout);   /* _Exit may not flush unwritten buffered data */
+    _Exit(0);
+}

Output:

+
Enter main()

References

See also

+ + +
causes abnormal program termination (without cleaning up)
(function)
causes normal program termination with cleaning up
(function)
C++ documentation for _Exit
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/program/_Exit +

+
diff --git a/devdocs/c/program%2Fabort.html b/devdocs/c/program%2Fabort.html new file mode 100644 index 00000000..8755f11c --- /dev/null +++ b/devdocs/c/program%2Fabort.html @@ -0,0 +1,45 @@ +

abort

Defined in header <stdlib.h> 
void abort(void);
 (until C11) 
_Noreturn void abort(void);
+		 (since C11)
(until C23) 
[[noreturn]] void abort(void);
+		 (since C23)

Causes abnormal program termination unless SIGABRT is being caught by a signal handler passed to signal and the handler does not return.

+

Functions passed to atexit() are not called. Whether open resources such as files are closed is implementation defined. An implementation defined status is returned to the host environment that indicates unsuccessful execution.

+

Parameters

(none)

+

Return value

(none)

+

Notes

POSIX specifies that the abort() function overrides blocking or ignoring the SIGABRT signal.

+

Some compiler intrinsics, e.g. __builtin_trap (gcc, clang, and icc) or __fastfail/__debugbreak (msvc), can be used to terminate the program as fast as possible.

+

Example

#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    FILE *fp = fopen("data.txt","r");
+    if (fp == NULL)
+    {
+        fprintf(stderr, "error opening file data.txt in function main()\n");
+        abort();
+    }
+ 
+    /* Normal processing continues here. */
+    fclose(fp);
+    printf("Normal Return\n");
+    return 0;
+}

Output:

+
error opening file data.txt in function main()

References

See also

+ + + +
causes normal program termination with cleaning up
(function)
registers a function to be called on exit() invocation
(function)
+
(C11)
 causes normal program termination without completely cleaning up
(function)
C++ documentation for abort
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/program/abort +

+
diff --git a/devdocs/c/program%2Fat_quick_exit.html b/devdocs/c/program%2Fat_quick_exit.html new file mode 100644 index 00000000..fd003acf --- /dev/null +++ b/devdocs/c/program%2Fat_quick_exit.html @@ -0,0 +1,45 @@ +

at_quick_exit

Defined in header <stdlib.h> 
int at_quick_exit( void (*func)(void) );
+		 (since C11)

Registers the function pointed to by func to be called on quick program termination (via quick_exit).

+

Calling the function from several threads does not induce a data race. The implementation is guaranteed to support the registration of at least 32 functions. The exact limit is implementation-defined.

+

The registered functions will not be called on normal program termination. If a function need to be called in that case, atexit must be used.

+

Parameters

+ +
func - pointer to a function to be called on quick program termination

Return value

​0​ if the registration succeeds, nonzero value otherwise.

+

Example

#include <stdlib.h>
+#include <stdio.h>
+ 
+void f1(void)
+{
+    puts("pushed first");
+    fflush(stdout);
+}
+ 
+void f2(void)
+{
+    puts("pushed second");
+}
+ 
+int main(void)
+{
+    at_quick_exit(f1);
+    at_quick_exit(f2);
+    quick_exit(0);
+}

Output:

+
pushed second
+pushed first

References

See also

+ + + + +
causes abnormal program termination (without cleaning up)
(function)
causes normal program termination with cleaning up
(function)
registers a function to be called on exit() invocation
(function)
+
(C11)
 causes normal program termination without completely cleaning up
(function)
C++ documentation for at_quick_exit
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/program/at_quick_exit +

+
diff --git a/devdocs/c/program%2Fatexit.html b/devdocs/c/program%2Fatexit.html new file mode 100644 index 00000000..c9cebb8e --- /dev/null +++ b/devdocs/c/program%2Fatexit.html @@ -0,0 +1,50 @@ +

atexit

Defined in header <stdlib.h> 
int atexit( void (*func)(void) );
+

Registers the function pointed to by func to be called on normal program termination (via exit() or returning from main()). The functions will be called in reverse order they were registered, i.e. the function registered last will be executed first.

+

The same function may be registered more than once.

+

atexit is thread-safe: calling the function from several threads does not induce a data race.

+

The implementation is guaranteed to support the registration of at least 32 functions. The exact limit is implementation-defined.

+

Parameters

+ +
func - pointer to a function to be called on normal program termination

Return value

​0​ if the registration succeeds, nonzero value otherwise.

+

Example

#include <stdlib.h>
+#include <stdio.h>
+ 
+void f1(void)
+{
+    puts("f1");
+}
+ 
+void f2(void)
+{
+    puts("f2");
+}
+ 
+int main(void)
+{
+    if ( ! atexit(f1) && ! atexit(f2) && ! atexit(f2) )
+        return EXIT_SUCCESS ;
+ 
+    // atexit registration failed
+    return EXIT_FAILURE ;
+ 
+}   // <- if registration was successful calls f2, f2, f1

Output:

+
f2
+f2
+f1

References

See also

+ +
+
(C11)
 registers a function to be called on quick_exit invocation
(function)
C++ documentation for atexit
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/program/atexit +

+
diff --git a/devdocs/c/program%2Fexit.html b/devdocs/c/program%2Fexit.html new file mode 100644 index 00000000..a7ae5e4f --- /dev/null +++ b/devdocs/c/program%2Fexit.html @@ -0,0 +1,51 @@ +

exit

Defined in header <stdlib.h> 
void exit( int exit_code );
 (until C11) 
_Noreturn void exit( int exit_code );
+		 (since C11)
(until C23) 
[[noreturn]] void exit( int exit_code );
+		 (since C23)

Causes normal program termination to occur.

+

Several cleanup steps are performed:

+

Notes

The functions registered with at_quick_exit are not called.

+

The behavior is undefined if a program calls exit more than once, or if it calls exit and quick_exit

+

The behavior is undefined if during a call to a function registered with atexit, the function exits with longjmp.

+

Returning from the the main function, either by a return statement or by reaching the end of the function, executes exit(), passing the argument of the return statement (or ​0​ if implicit return was used) as exit_code.

+

Parameters

+ +
exit_code - exit status of the program

Return value

(none)

+

Example

#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    FILE *fp = fopen("data.txt","r");
+    if (fp == NULL)
+    {
+       fprintf(stderr, "error opening file data.txt in function main()\n");
+       exit( EXIT_FAILURE );
+    }
+    fclose(fp);
+    printf("Normal Return\n");
+    return EXIT_SUCCESS ;
+}

Possible output:

+
error opening file data.txt in function main()

References

See also

+ + + +
causes abnormal program termination (without cleaning up)
(function)
registers a function to be called on exit() invocation
(function)
+
(C11)
 causes normal program termination without completely cleaning up
(function)
C++ documentation for exit
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/program/exit +

+
diff --git a/devdocs/c/program%2Fexit_status.html b/devdocs/c/program%2Fexit_status.html new file mode 100644 index 00000000..89cd2252 --- /dev/null +++ b/devdocs/c/program%2Fexit_status.html @@ -0,0 +1,41 @@ +

EXIT_SUCCESS, EXIT_FAILURE

Defined in header <stdlib.h> 
#define EXIT_SUCCESS /*implementation defined*/
+		 
#define EXIT_FAILURE /*implementation defined*/
+

The EXIT_SUCCESS and EXIT_FAILURE macros expand into integral expressions that can be used as arguments to the exit function (and, therefore, as the values to return from the main function), and indicate program execution status.

+ + + +
Constant Explanation
EXIT_SUCCESS successful execution of a program
EXIT_FAILURE unsuccessful execution of a program

Notes

Both EXIT_SUCCESS and the value zero indicate successful program execution status (see exit), although it is not required that EXIT_SUCCESS equals zero.

+

Example

#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    FILE *fp = fopen("data.txt","r");
+    if (fp == NULL)
+    {
+       fprintf(stderr, "fopen() failed in file %s at line # %d", __FILE__,__LINE__);
+       exit(EXIT_FAILURE);
+    }
+ 
+    /* Normal processing continues here. */
+    fclose(fp);
+    printf("Normal Return\n");
+ 
+    return EXIT_SUCCESS;
+}

Output:

+
fopen() failed in file main.cpp at line # 9

References

See also

+
C++ documentation for EXIT_SUCCESS, EXIT_FAILURE
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/program/EXIT_status +

+
diff --git a/devdocs/c/program%2Fgetenv.html b/devdocs/c/program%2Fgetenv.html new file mode 100644 index 00000000..912fe7b3 --- /dev/null +++ b/devdocs/c/program%2Fgetenv.html @@ -0,0 +1,62 @@ +

getenv, getenv_s

Defined in header <stdlib.h> 
char *getenv( const char *name );
+		 (1) 
errno_t getenv_s( size_t *restrict len, char *restrict value,
+                  rsize_t valuesz, const char *restrict name );
+		 (2) (since C11)
+1) Searches for an environmental variable with name name in the host-specified environment list and returns a pointer to the string that is associated with the matched environment variable. The set of environmental variables and methods of altering it are implementation-defined.
+ This function is not required to be thread-safe. Another call to getenv, as well as a call to the POSIX functions setenv(), unsetenv(), and putenv() may invalidate the pointer returned by a previous call or modify the string obtained from a previous call.
+ Modifying the string returned by getenv invokes undefined behavior.
+2) Same as (1), except that the values of the environment variable is written to the user-provided buffer value (unless null) and the number of bytes written is stored in the user-provided location *len (unless null). If the environment variable is not set in the environment, zero is written to *len (unless null) and '\0' is written to value[0] (unless null). In addition, the following errors are detected at runtime and call the currently installed constraint handler function:
+
+
    +
  • name is a null pointer
    • +
  • valuesz is greater than RSIZE_MAX
    • +
  • value is a null pointer and valuesz is not zero
    • +
+
As with all bounds-checked functions, getenv_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <stdlib.h>.
+
+

Parameters

+ + + + +
name - null-terminated character string identifying the name of the environmental variable to look for
len - pointer to a user-provided location where getenv_s will store the length of the environment variable
value - pointer to a user-provided character array where getenv_s will store the contents of the environment variable
valuesz - maximum number of characters that getenv_s is allowed to write to dest (size of the buffer)

Return value

+1) character string identifying the value of the environmental variable or null pointer if such variable is not found.
+2) zero if the environment variable was found, non-zero if it was not found or if a runtime constraint violation occurred. On any error, writes zero to *len (unless len is a null pointer).

Notes

On POSIX systems, the environment variables are also accessible through the global variable environ, declared as extern char **environ; in <unistd.h>, and through the optional third argument, envp, of the main function.

+

The call to getenv_s with a null pointer for value and zero for valuesz is used to determine the size of the buffer required to hold the entire result.

+

Example

#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    const char *name = "PATH";
+    const char *env_p = getenv(name);
+    if (env_p)
+        printf("Your %s is %s\n", name, env_p);
+}

Possible output:

+
Your PATH is /home/gamer/.local/bin:/usr/local/bin:/usr/bin:/bin:/usr/share/games

References

See also

+
C++ documentation for getenv
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/program/getenv +

+
diff --git a/devdocs/c/program%2Fjmp_buf.html b/devdocs/c/program%2Fjmp_buf.html new file mode 100644 index 00000000..2ebd106e --- /dev/null +++ b/devdocs/c/program%2Fjmp_buf.html @@ -0,0 +1,20 @@ +

jmp_buf

Defined in header <setjmp.h> 
typedef /* unspecified */ jmp_buf;
+

The jmp_buf type is an array type suitable for storing information to restore a calling environment. The stored information is sufficient to restore execution at the correct block of the program and invocation of that block. The state of floating-point status flags, or open files, or any other data is not stored in an object of type jmp_buf.

+

References

See also

+ + +
saves the context
(function macro)
jumps to specified location
(function)
C++ documentation for jmp_buf
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/program/jmp_buf +

+
diff --git a/devdocs/c/program%2Flongjmp.html b/devdocs/c/program%2Flongjmp.html new file mode 100644 index 00000000..2ccde1dd --- /dev/null +++ b/devdocs/c/program%2Flongjmp.html @@ -0,0 +1,64 @@ +

longjmp

Defined in header <setjmp.h> 
void longjmp( jmp_buf env, int status );
+		 (until C11) 
_Noreturn void longjmp( jmp_buf env, int status );
+		 (since C11)
(until C23) 
[[noreturn]] void longjmp( jmp_buf env, int status );
+		 (since C23)

Loads the execution context env saved by a previous call to setjmp. This function does not return. Control is transferred to the call site of the macro setjmp that set up env. That setjmp then returns the value, passed as the status.

+

If the function that called setjmp has exited (whether by return or by a different longjmp higher up the stack), the behavior is undefined. In other words, only long jumps up the call stack are allowed.

+ + +

Jumping across threads (if the function that called setjmp was executed by another thread) is also undefined behavior.

+		 (since C11)
+ +

If when setjmp was called, a VLA or another variably-modified type variable was in scope and control left that scope, longjmp to that setjmp invokes undefined behavior even if control remained within the function.

+

On the way up the stack, longjmp does not deallocate any VLAs, memory leaks may occur if their lifetimes are terminated in this way:

+
void g(int n)
+{
+    int a[n]; // a may remain allocated
+    h(n); // does not return
+}
+void h(int n)
+{
+    int b[n]; // b may remain allocated
+    longjmp(buf, 2); // might cause a memory leak for h's b and g's a
+}
 (since C99)

Parameters

+ + +
env - variable referring to the execution state of the program saved by setjmp
status - the value to return from setjmp. If it is equal to ​0​, 1 is used instead

Return value

(none)

+

Notes

longjmp is intended for handling unexpected error conditions where the function cannot return meaningfully. This is similar to exception handling in other programming languages.

+

Example

#include <stdio.h>
+#include <setjmp.h>
+#include <stdnoreturn.h>
+ 
+jmp_buf my_jump_buffer;
+ 
+noreturn void foo(int status) 
+{
+    printf("foo(%d) called\n", status);
+    longjmp(my_jump_buffer, status + 1); // will return status+1 out of setjmp
+}
+ 
+int main(void)
+{
+    volatile int count = 0; // modified local vars in setjmp scope must be volatile
+    if (setjmp(my_jump_buffer) != 5) // compare against constant in an if
+        foo(++count);
+}

Output:

+
foo(1) called
+foo(2) called
+foo(3) called
+foo(4) called

References

See also

+ +
saves the context
(function macro)
C++ documentation for longjmp
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/program/longjmp +

+
diff --git a/devdocs/c/program%2Fquick_exit.html b/devdocs/c/program%2Fquick_exit.html new file mode 100644 index 00000000..2527ca17 --- /dev/null +++ b/devdocs/c/program%2Fquick_exit.html @@ -0,0 +1,52 @@ +

quick_exit

Defined in header <stdlib.h> 
_Noreturn void quick_exit( int exit_code );
 +(since C11)
(until C23) +		 
[[noreturn]] void quick_exit( int exit_code );
+		 (since C23)

Causes normal program termination to occur without completely cleaning the resources.

+

Functions passed to at_quick_exit are called in reverse order of their registration. After calling the registered functions, calls _Exit(exit_code).

+

Functions passed to atexit or signal handlers passed to signal are not called.

+

Parameters

+ +
exit_code - exit status of the program

Return value

(none)

+

Example

#include <stdlib.h>
+#include <stdio.h>
+ 
+void f1(void)
+{
+    puts("pushed first");
+    fflush(stdout);
+}
+ 
+void f2(void)
+{
+    puts("pushed second");
+}
+ 
+void f3(void)
+{
+    puts("won't be called");
+}
+ 
+int main(void)
+{
+    at_quick_exit(f1);
+    at_quick_exit(f2);
+    atexit(f3);
+    quick_exit(0);
+}

Output:

+
pushed second
+pushed first

References

See also

+ + + +
causes abnormal program termination (without cleaning up)
(function)
registers a function to be called on exit() invocation
(function)
+
(C11)
 registers a function to be called on quick_exit invocation
(function)
C++ documentation for quick_exit
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/program/quick_exit +

+
diff --git a/devdocs/c/program%2Fraise.html b/devdocs/c/program%2Fraise.html new file mode 100644 index 00000000..5aa1e9e2 --- /dev/null +++ b/devdocs/c/program%2Fraise.html @@ -0,0 +1,43 @@ +

raise

Defined in header <signal.h> 
int raise( int sig );
+

Sends signal sig to the program. The signal handler, specified using signal(), is invoked.

+

If the user-defined signal handling strategy is not set using signal() yet, it is implementation-defined whether the signal will be ignored or default handler will be invoked.

+

Parameters

+ +
sig - the signal to be sent. It can be an implementation-defined value or one of the following values: +
defines signal types
(macro constant)

Return value

​0​ upon success, non-zero value on failure.

+

Example

#include <signal.h>
+#include <stdio.h>
+ 
+void signal_handler(int signal)
+{
+    printf("Received signal %d\n", signal);
+}
+ 
+int main(void)
+{
+    // Install a signal handler.
+    signal(SIGTERM, signal_handler);
+ 
+    printf("Sending signal %d\n", SIGTERM);
+    raise(SIGTERM);
+    printf("Exit main()\n");
+}

Output:

+
Sending signal 15
+Received signal 15
+Exit main()

References

See also

+ +
sets a signal handler for particular signal
(function)
C++ documentation for raise
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/program/raise +

+
diff --git a/devdocs/c/program%2Fsetjmp.html b/devdocs/c/program%2Fsetjmp.html new file mode 100644 index 00000000..b0fedd15 --- /dev/null +++ b/devdocs/c/program%2Fsetjmp.html @@ -0,0 +1,56 @@ +

setjmp

Defined in header <setjmp.h> 
#define setjmp(env) /* implementation-defined */
+

Saves the current execution context into a variable env of type jmp_buf. This variable can later be used to restore the current execution context by longjmp function. That is, when a call to longjmp function is made, the execution continues at the particular call site that constructed the jmp_buf variable passed to longjmp. In that case setjmp returns the value passed to longjmp.

+

The invocation of setjmp must appear only in one of the following contexts:

+
    +
  1. The entire controlling expression of if, switch, while, do-while, for.
    switch(setjmp(env)) { // ...
    2. +
  2. One operand of a relational or equality operator with the other operand an integer constant expression, with the resulting expression being the entire controlling expression of if, switch, while, do-while, for.
    if(setjmp(env) > 10) { // ...
    3. +
  3. The operand of a unary ! operator with the resulting expression being the entire controlling expression of if, switch, while, do-while, for.
    while(!setjmp(env)) { // ...
    4. +
  4. The entire expression of an expression statement (possibly cast to void).
    setjmp(env);
    5. +

If setjmp appears in any other context, the behavior is undefined.

+

Upon return to the scope of setjmp:

+

Parameters

+ +
env - variable to save the execution state of the program to.

Return value

​0​ if the macro was called by the original code and the execution context was saved to env.

+

Non-zero value if a non-local jump was just performed. The return value is the same as passed to longjmp.

+

Notes

Above requirements forbid using return value of setjmp in data flow (e.g. to initialize or assign an object with it). The return value can only be either used in control flow or discarded.

+

Example

#include <stdio.h>
+#include <setjmp.h>
+#include <stdnoreturn.h>
+ 
+jmp_buf my_jump_buffer;
+ 
+noreturn void foo(int status) 
+{
+    printf("foo(%d) called\n", status);
+    longjmp(my_jump_buffer, status + 1); // will return status+1 out of setjmp
+}
+ 
+int main(void)
+{
+    volatile int count = 0; // modified local vars in setjmp scope must be volatile
+    if (setjmp(my_jump_buffer) != 5) // compare against constant in an if
+        foo(++count);
+}

Output:

+
foo(1) called
+foo(2) called
+foo(3) called
+foo(4) called

References

See also

+ +
jumps to specified location
(function)
C++ documentation for setjmp
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/program/setjmp +

+
diff --git a/devdocs/c/program%2Fsig_atomic_t.html b/devdocs/c/program%2Fsig_atomic_t.html new file mode 100644 index 00000000..f791b620 --- /dev/null +++ b/devdocs/c/program%2Fsig_atomic_t.html @@ -0,0 +1,41 @@ +

sig_atomic_t

Defined in header <signal.h> 
typedef /* unspecified */ sig_atomic_t;
+

An integer type which can be accessed as an atomic entity even in the presence of asynchronous interrupts made by signals.

+

Example

#include <signal.h>
+#include <stdio.h>
+ 
+volatile sig_atomic_t gSignalStatus = 0;
+ 
+void signal_handler(int status)
+{
+    gSignalStatus = status;
+}
+ 
+int main(void)
+{
+    /* Install a signal handler. */
+    signal(SIGINT, signal_handler);
+ 
+    printf("SignalValue:    %d\n", gSignalStatus);
+    printf("Sending signal: %d\n", SIGINT);
+    raise(SIGINT);
+    printf("SignalValue:    %d\n", gSignalStatus);
+}

Possible output:

+
SignalValue:    0
+Sending signal: 2
+SignalValue:    2

References

See also

+ +
sets a signal handler for particular signal
(function)
C++ documentation for sig_atomic_t
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/program/sig_atomic_t +

+
diff --git a/devdocs/c/program%2Fsig_err.html b/devdocs/c/program%2Fsig_err.html new file mode 100644 index 00000000..5e2118d6 --- /dev/null +++ b/devdocs/c/program%2Fsig_err.html @@ -0,0 +1,49 @@ +

SIG_ERR

Defined in header <signal.h> 
#define SIG_ERR /* implementation defined */
+

A value of type void (*)(int). When returned by signal, indicates that an error has occurred.

+

Example

#include <stdio.h>
+#include <stdlib.h>
+#include <signal.h>
+ 
+void signal_handler(int sig)
+{
+    printf("Received signal: %d\n", sig);
+}
+ 
+int main(void)
+{
+    /* Install a signal handler. */
+    if (signal(SIGTERM, signal_handler) == SIG_ERR)
+    {
+        printf("Error while installing a signal handler.\n");
+        exit(EXIT_FAILURE);
+    }
+ 
+    printf("Sending signal: %d\n", SIGTERM);
+    if (raise(SIGTERM) != 0)
+    {
+        printf("Error while raising the SIGTERM signal.\n");
+        exit(EXIT_FAILURE);
+    }
+ 
+    printf("Exit main()\n");
+    return EXIT_SUCCESS;
+}

Output:

+
Sending signal: 15
+Received signal: 15
+Exit main()

References

See also

+ +
sets a signal handler for particular signal
(function)
C++ documentation for SIG_ERR
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/program/SIG_ERR +

+
diff --git a/devdocs/c/program%2Fsig_strategies.html b/devdocs/c/program%2Fsig_strategies.html new file mode 100644 index 00000000..f4a8f245 --- /dev/null +++ b/devdocs/c/program%2Fsig_strategies.html @@ -0,0 +1,41 @@ +

SIG_DFL, SIG_IGN

Defined in header <signal.h> 
#define SIG_DFL /*implementation defined*/
+		 
#define SIG_IGN /*implementation defined*/
+

The SIG_DFL and SIG_IGN macros expand into integral expressions that are not equal to an address of any function. The macros define signal handling strategies for signal() function.

+ + + +
Constant Explanation
SIG_DFL default signal handling
SIG_IGN signal is ignored

Example

#include <signal.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    /* using the default signal handler */
+    raise(SIGTERM);
+    printf("Exit main()\n");   /* never reached */
+}

Output:

+
(none)

Example

#include <signal.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    /* ignoring the signal */
+    signal(SIGTERM, SIG_IGN);
+    raise(SIGTERM);
+    printf("Exit main()\n");
+}

Output:

+
Exit main()

References

See also

+
C++ documentation for SIG_DFL, SIG_IGN
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/program/SIG_strategies +

+
diff --git a/devdocs/c/program%2Fsig_types.html b/devdocs/c/program%2Fsig_types.html new file mode 100644 index 00000000..12f7b29f --- /dev/null +++ b/devdocs/c/program%2Fsig_types.html @@ -0,0 +1,32 @@ +

SIGTERM, SIGSEGV, SIGINT, SIGILL, SIGABRT, SIGFPE

Defined in header <signal.h> 
#define SIGTERM /*implementation defined*/
+		 
#define SIGSEGV /*implementation defined*/
+		 
#define SIGINT /*implementation defined*/
+		 
#define SIGILL /*implementation defined*/
+		 
#define SIGABRT /*implementation defined*/
+		 
#define SIGFPE /*implementation defined*/
+

Each of the above macro constants expands to an integer constant expression with distinct values, which represent different signals sent to the program.

+ + + + + + + +
Constant Explanation
SIGTERM termination request, sent to the program
SIGSEGV invalid memory access (segmentation fault)
SIGINT external interrupt, usually initiated by the user
SIGILL invalid program image, such as invalid instruction
SIGABRT abnormal termination condition, as is e.g. initiated by abort()
SIGFPE erroneous arithmetic operation such as divide by zero

References

See also

+ + +
sets a signal handler for particular signal
(function)
runs the signal handler for particular signal
(function)
C++ documentation for signal types
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/program/SIG_types +

+
diff --git a/devdocs/c/program%2Fsignal.html b/devdocs/c/program%2Fsignal.html new file mode 100644 index 00000000..4dfb42f4 --- /dev/null +++ b/devdocs/c/program%2Fsignal.html @@ -0,0 +1,78 @@ +

signal

Defined in header <signal.h> 
void (*signal( int sig, void (*handler) (int))) (int);
+

Sets the error handler for signal sig. The signal handler can be set so that default handling will occur, signal is ignored, or a user-defined function is called.

+

When signal handler is set to a function and a signal occurs, it is implementation defined whether signal(sig, SIG_DFL) will be executed immediately before the start of signal handler. Also, the implementation can prevent some implementation-defined set of signals from occurring while the signal handler runs.

+

Parameters

+ + +
sig - the signal to set the signal handler to. It can be an implementation-defined value or one of the following values: +
defines signal types
(macro constant)
handler - the signal handler. This must be one of the following:
    +
  • +SIG_DFL macro. The signal handler is set to default signal handler.
    • +
  • +SIG_IGN macro. The signal is ignored.
    • +
  • pointer to a function. The signature of the function must be equivalent to the following:
    • +
void fun(int sig);
+

Return value

Previous signal handler on success or SIG_ERR on failure (setting a signal handler can be disabled on some implementations).

+

Signal handler

The following limitations are imposed on the user-defined function that is installed as a signal handler.

+

If the user defined function returns when handling SIGFPE, SIGILL or SIGSEGV, the behavior is undefined.

+

If the signal handler is called as a result of abort or raise, the behavior is undefined if the signal handler calls raise.

+

If the signal handler is called NOT as a result of abort or raise (in other words, the signal handler is asynchronous), the behavior is undefined if

+

On entry to the signal handler, the state of the floating-point environment and the values of all objects is unspecified, except for

+

On return from a signal handler, the value of any object modified by the signal handler that is not volatile sig_atomic_t or lock-free atomic(since C11) is undefined.

+

The behavior is undefined if signal is used in a multithreaded program. It is not required to be thread-safe.

+

Notes

POSIX requires that signal is thread-safe, and specifies a list of async-signal-safe library functions that may be called from any signal handler.

+

Besides abort and raise, POSIX specifies that kill, pthread_kill, and sigqueue generate synchronous signals.

+

POSIX recommends sigaction instead of signal, due to its underspecified behavior and significant implementation variations, regarding signal delivery while a signal handler is executed.

+

Example

#include <signal.h>
+#include <stdio.h>
+ 
+volatile sig_atomic_t gSignalStatus;
+ 
+void signal_handler(int signal)
+{
+  gSignalStatus = signal;
+}
+ 
+int main(void)
+{
+  signal(SIGINT, signal_handler);
+ 
+  printf("SignalValue: %d\n", gSignalStatus);
+  printf("Sending signal: %d\n", SIGINT);
+  raise(SIGINT);
+  printf("SignalValue: %d\n", gSignalStatus);
+}

Output:

+
SignalValue: 0
+Sending signal: 2
+SignalValue: 2

References

See also

+ +
runs the signal handler for particular signal
(function)
C++ documentation for signal
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/program/signal +

+
diff --git a/devdocs/c/program%2Fsystem.html b/devdocs/c/program%2Fsystem.html new file mode 100644 index 00000000..40e60354 --- /dev/null +++ b/devdocs/c/program%2Fsystem.html @@ -0,0 +1,33 @@ +

system

Defined in header <stdlib.h> 
int system( const char *command );
+

Calls the host environment's command processor with the parameter command. Returns an implementation-defined value (usually the value that the invoked program returns).

+

If command is a null pointer, checks if the host environment has a command processor and returns a nonzero value if and only if the command processor exists.

+

Parameters

+ +
command - character string identifying the command to be run in the command processor. If a null pointer is given, command processor is checked for existence

Return value

Implementation-defined value. If command is a null pointer, returns a nonzero value if and only if the command processor exists.

+

Notes

On POSIX systems, the return value can be decomposed using WEXITSTATUS and WSTOPSIG.

+

The related POSIX function popen makes the output generated by command available to the caller.

+

Example

In this example there is a system call of the unix command date +%A and a system call to (possibly installed) gcc compiler with command-line argument (--version):

+
#include <stdlib.h>
+ 
+int main(void) {
+    system("date +%A");
+    system("gcc --version");
+}

Possible output:

+
Wednesday
+gcc (GCC) 11.2.0
+...

References

See also

+
C++ documentation for system
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/program/system +

+
diff --git a/devdocs/c/program%2Funreachable.html b/devdocs/c/program%2Funreachable.html new file mode 100644 index 00000000..09e33e03 --- /dev/null +++ b/devdocs/c/program%2Funreachable.html @@ -0,0 +1,79 @@ +

unreachable

Defined in header <stddef.h> 
#define unreachable() /* see below */
+		 (since C23)

The function-like macro unreachable expands to a void expression. Executing unreachable() results in undefined behavior.

+

An implementation may use this to optimize impossible code branches away (typically, in optimized builds) or to trap them to prevent further execution (typically, in debug builds).

+

Possible implementation

+ +
// Uses compiler specific extensions if possible.
+#ifdef __GNUC__ // GCC, Clang, ICC
+ 
+#define unreachable() (__builtin_unreachable())
+ 
+#elifdef _MSC_VER // MSVC
+ 
+#define unreachable() (__assume(false))
+ 
+#else
+// Even if no extension is used, undefined behavior is still raised by
+// the empty function body and the noreturn attribute.
+ 
+// The external definition of unreachable_impl must be emitted in a separated TU
+// due to the rule for inline functions in C.
+ 
+[[noreturn]] inline void unreachable_impl() {}
+#define unreachable() (unreachable_impl())
+ 
+#endif

Example

#include <assert.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdlib.h>
+ 
+struct Color { uint8_t r, g, b, a; };
+struct ColorSpan { struct Color* data; size_t size; };
+ 
+// Assume that only restricted set of texture caps is supported.
+struct ColorSpan allocate_texture(size_t xy)
+{
+    switch (xy)
+    {
+    case 128: [[fallthrough]];
+    case 256: [[fallthrough]];
+    case 512:
+    {
+        /* ... */
+        struct ColorSpan result = {
+            .data = malloc(xy * xy * sizeof(struct Color)),
+            .size = xy * xy
+        };
+        if (!result.data)
+            result.size = 0;
+        return result;
+    }
+    default:
+        unreachable();
+    }
+}
+ 
+int main(void)
+{
+    struct ColorSpan tex = allocate_texture(128); // OK
+    assert(tex.size == 128 * 128);
+ 
+    struct ColorSpan badtex = allocate_texture(32);  // Undefined behavior
+ 
+    free(badtex.data);
+    free(tex.data);
+}

Possible output:

+
Segmentation fault

See also

+
C++ documentation for unreachable
+ + + +
1. +GCC docs: __builtin_unreachable
2. +Clang docs: __builtin_unreachable
3. +MSVC docs: __assume
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/program/unreachable +

+
diff --git a/devdocs/c/program.html b/devdocs/c/program.html new file mode 100644 index 00000000..95464568 --- /dev/null +++ b/devdocs/c/program.html @@ -0,0 +1,73 @@ +

Program support utilities

Program termination

The following functions manage program termination and resources cleanup.

+ + + + + + + + +
Defined in header <stdlib.h>
causes abnormal program termination (without cleaning up)
(function)
causes normal program termination with cleaning up
(function)
+
(C11)
 causes normal program termination without completely cleaning up
(function)
+
(C99)
 causes normal program termination without cleaning up
(function)
registers a function to be called on exit() invocation
(function)
+
(C11)
 registers a function to be called on quick_exit invocation
(function)
indicates program execution execution status
(macro constant)

Unreachable control flow

+ +
Defined in header <stddef.h>
+
(C23)
 marks unreachable point of execution
(function macro)

Communicating with the environment

+ + +
Defined in header <stdlib.h>
calls the host environment's command processor
(function)
+
(C11)
 access to the list of environment variables
(function)

Signals

Several functions and macro constants for signal management are provided.

+ + + + + + + + +
Defined in header <signal.h>
sets a signal handler for particular signal
(function)
runs the signal handler for particular signal
(function)
the integer type that can be accessed as an atomic entity from an asynchronous signal handler
(typedef)
defines signal handling strategies
(macro constant)
error was encountered
(macro constant)
Signal types
defines signal types
(macro constant)

Non-local jumps

+ + + + +
Defined in header <setjmp.h>
saves the context
(function macro)
jumps to specified location
(function)
Types
execution context type
(typedef)

References

See also

+
C++ documentation for Program support utilities
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/program +

+
diff --git a/devdocs/c/string%2Fbyte%2Fatof.html b/devdocs/c/string%2Fbyte%2Fatof.html new file mode 100644 index 00000000..54760677 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fatof.html @@ -0,0 +1,73 @@ +

atof

Defined in header <stdlib.h> 
double atof( const char* str );
+

Interprets a floating-point value in a byte string pointed to by str.

+

Function discards any whitespace characters (as determined by isspace) until first non-whitespace character is found. Then it takes as many characters as possible to form a valid floating-point representation and converts them to a floating-point value. The valid floating-point value can be one of the following:

+ + +
    +
  • hexadecimal floating-point expression. It consists of the following parts:
    • +
      +
    • (optional) plus or minus sign
      • +
    • 0x or 0X
      • +
    • nonempty sequence of hexadecimal digits optionally containing a decimal-point character (as determined by the current C locale) (defines significand)
      • +
    • (optional) p or P followed with optional minus or plus sign and nonempty sequence of decimal digits (defines exponent to base 2)
      • +
    +
  • infinity expression. It consists of the following parts:
    • +
      +
    • (optional) plus or minus sign
      • +
    • INF or INFINITY ignoring case
      • +
    +
  • not-a-number expression. It consists of the following parts:
    • +
      +
    • (optional) plus or minus sign
      • +
    • NAN or NAN(char_sequence) ignoring case of the NAN part. char_sequence can only contain digits, Latin letters, and underscores. The result is a quiet NaN floating-point value.
      • +
    +
 (since C99)

Parameters

+ +
str - pointer to the null-terminated byte string to be interpreted

Return value

double value corresponding to the contents of str on success. If the converted value falls out of range of the return type, the return value is undefined. If no conversion can be performed, 0.0 is returned.

+

Notes

The name stands for "ASCII to float".

+

Example

#include <stdlib.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    printf("%g\n", atof("  -0.0000000123junk"));
+    printf("%g\n", atof("0.012"));
+    printf("%g\n", atof("15e16"));
+    printf("%g\n", atof("-0x1afp-2"));
+    printf("%g\n", atof("inF"));
+    printf("%g\n", atof("Nan"));
+    printf("%g\n", atof("1.0e+309"));   // UB: out of range of double
+    printf("%g\n", atof("0.0"));
+    printf("%g\n", atof("junk"));       // no conversion can be performed
+}

Possible output:

+
-1.23e-08
+0.012
+1.5e+17
+-107.75
+inf
+nan
+inf
+0
+0

References

See also

+ +
+
(C99)(C99)
 converts a byte string to a floating point value
(function)
C++ documentation for atof
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/atof +

+
diff --git a/devdocs/c/string%2Fbyte%2Fatoi.html b/devdocs/c/string%2Fbyte%2Fatoi.html new file mode 100644 index 00000000..b4a114d3 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fatoi.html @@ -0,0 +1,60 @@ +

atoi, atol, atoll

Defined in header <stdlib.h> 
int       atoi( const char *str );
+		 
long      atol( const char *str );
+		 
long long atoll( const char *str );
+		 (since C99)

Interprets an integer value in a byte string pointed to by str. The implied radix is always 10.

+

Discards any whitespace characters until the first non-whitespace character is found, then takes as many characters as possible to form a valid integer number representation and converts them to an integer value. The valid integer value consists of the following parts:

+

If the value of the result cannot be represented, i.e. the converted value falls out of range of the corresponding return type, the behavior is undefined.

+

Parameters

+ +
str - pointer to the null-terminated byte string to be interpreted

Return value

Integer value corresponding to the contents of str on success.

+

If no conversion can be performed, ​0​ is returned.

+

Notes

The name stands for "ASCII to integer".

+

Example

#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    printf("%i\n", atoi(" -123junk"));
+    printf("%i\n", atoi(" +321dust"));
+    printf("%i\n", atoi("0"));
+    printf("%i\n", atoi("0042")); // treated as a decimal number with leading zeros
+    printf("%i\n", atoi("0x2A")); // only leading zero is converted discarding "x2A"
+    printf("%i\n", atoi("junk")); // no conversion can be performed
+    printf("%i\n", atoi("2147483648")); // UB: out of range of int
+}

Possible output:

+
-123
+321
+0
+42
+0
+0
+-2147483648

References

See also

+ + + + +
+
(C99)
 converts a byte string to an integer value
(function)
+
(C99)
 converts a byte string to an unsigned integer value
(function)
+
(C95)(C99)
 converts a wide string to an integer value
(function)
+
(C95)(C99)
 converts a wide string to an unsigned integer value
(function)
C++ documentation for atoi, atol, atoll
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/atoi +

+
diff --git a/devdocs/c/string%2Fbyte%2Fisalnum.html b/devdocs/c/string%2Fbyte%2Fisalnum.html new file mode 100644 index 00000000..98f04421 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fisalnum.html @@ -0,0 +1,124 @@ +

isalnum

Defined in header <ctype.h> 
int isalnum( int ch );
+

Checks if the given character is an alphanumeric character as classified by the current C locale. In the default locale, the following characters are alphanumeric:

+

The behavior is undefined if the value of ch is not representable as unsigned char and is not equal to EOF.

+

Parameters

+ +
ch - character to classify

Return value

Non-zero value if the character is an alphanumeric character, 0 otherwise.

+

Example

+

Demonstrates the use of isalnum with different locales (OS-specific).

+
#include <stdio.h>
+#include <ctype.h>
+#include <locale.h>
+ 
+int main(void)
+{
+    unsigned char c = '\xdf'; // German letter ß in ISO-8859-1
+ 
+    printf("isalnum('\\xdf') in default C locale returned %d\n", !!isalnum(c));
+ 
+    if(setlocale(LC_CTYPE, "de_DE.iso88591"))
+        printf("isalnum('\\xdf') in ISO-8859-1 locale returned %d\n", !!isalnum(c));
+}

Possible output:

+
isalnum('\xdf') in default C locale returned 0
+isalnum('\xdf') in ISO-8859-1 locale returned 1

References

See also

+ +
+
(C95)
 checks if a wide character is alphanumeric
(function)
C++ documentation for isalnum
+ + + + + + + + + + + + + + + + + +
ASCII values characters

iscntrl
iswcntrl

+

isprint
iswprint

+

isspace
iswspace

+

isblank
iswblank

+

isgraph
iswgraph

+

ispunct
iswpunct

+

isalnum
iswalnum

+

isalpha
iswalpha

+

isupper
iswupper

+

islower
iswlower

+

isdigit
iswdigit

+

isxdigit
iswxdigit

+
decimal hexadecimal octal
0–8 \x0–\x8 \0–\10 control codes (NUL, etc.) +≠0 0 0 0 0 0 0 0 0 0 0 0
9 \x9 \11 tab (\t) +≠0 0 +≠0 +≠0 0 0 0 0 0 0 0 0
10–13 \xA–\xD \12–\15 whitespaces (\n, \v, \f, \r) +≠0 0 +≠0 0 0 0 0 0 0 0 0 0
14–31 \xE–\x1F \16–\37 control codes +≠0 0 0 0 0 0 0 0 0 0 0 0
32 \x20 \40 space 0 +≠0 +≠0 +≠0 0 0 0 0 0 0 0 0
33–47 \x21–\x2F \41–\57 !"#$%&'()*+,-./ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
48–57 \x30–\x39 \60–\71 0123456789 0 +≠0 0 0 +≠0 0 +≠0 0 0 0 +≠0 +≠0
58–64 \x3A–\x40 \72–\100 :;<=>?@ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
65–70 \x41–\x46 \101–\106 ABCDEF 0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 +≠0
71–90 \x47–\x5A \107–\132 GHIJKLMNOP
QRSTUVWXYZ 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 0
91–96 \x5B–\x60 \133–\140 [\]^_` 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
97–102 \x61–\x66 \141–\146 abcdef 0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 +≠0
103–122 \x67–\x7A \147–\172 ghijklmnop
qrstuvwxyz 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 0
123–126 \x7B–\x7E \172–\176 {|}~ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
127 \x7F \177 backspace character (DEL) +≠0 0 0 0 0 0 0 0 0 0 0 0
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/isalnum +

+
diff --git a/devdocs/c/string%2Fbyte%2Fisalpha.html b/devdocs/c/string%2Fbyte%2Fisalpha.html new file mode 100644 index 00000000..3e6a7c4c --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fisalpha.html @@ -0,0 +1,121 @@ +

isalpha

Defined in header <ctype.h> 
int isalpha( int ch );
+

Checks if the given character is an alphabetic character, i.e. either an uppercase letter (ABCDEFGHIJKLMNOPQRSTUVWXYZ), or a lowercase letter (abcdefghijklmnopqrstuvwxyz).

+

In locales other than "C", an alphabetic character is a character for which isupper() or islower() returns true or any other character considered alphabetic by the locale. In any case, iscntrl(), isdigit(), ispunct() and isspace() will return false for this character.

+

The behavior is undefined if the value of ch is not representable as unsigned char and is not equal to EOF.

+

Parameters

+ +
ch - character to classify

Return value

Non-zero value if the character is an alphabetic character, zero otherwise.

+

Example

+

Demonstrates the use of isalpha with different locales (OS-specific).

+
#include <ctype.h>
+#include <stdio.h>
+#include <locale.h>
+ 
+int main(void)
+{
+    unsigned char c = '\xdf'; // German letter ß in ISO-8859-1
+ 
+    printf("isalpha('\\xdf') in default C locale returned %d\n", !!isalpha(c));
+ 
+    setlocale(LC_CTYPE, "de_DE.iso88591");
+    printf("isalpha('\\xdf') in ISO-8859-1 locale returned %d\n", !!isalpha(c));
+}

Possible output:

+
isalpha('\xdf') in default C locale returned 0
+isalpha('\xdf') in ISO-8859-1 locale returned 1

References

See also

+ +
+
(C95)
 checks if a wide character is alphabetic
(function)
C++ documentation for isalpha
+ + + + + + + + + + + + + + + + + +
ASCII values characters

iscntrl
iswcntrl

+

isprint
iswprint

+

isspace
iswspace

+

isblank
iswblank

+

isgraph
iswgraph

+

ispunct
iswpunct

+

isalnum
iswalnum

+

isalpha
iswalpha

+

isupper
iswupper

+

islower
iswlower

+

isdigit
iswdigit

+

isxdigit
iswxdigit

+
decimal hexadecimal octal
0–8 \x0–\x8 \0–\10 control codes (NUL, etc.) +≠0 0 0 0 0 0 0 0 0 0 0 0
9 \x9 \11 tab (\t) +≠0 0 +≠0 +≠0 0 0 0 0 0 0 0 0
10–13 \xA–\xD \12–\15 whitespaces (\n, \v, \f, \r) +≠0 0 +≠0 0 0 0 0 0 0 0 0 0
14–31 \xE–\x1F \16–\37 control codes +≠0 0 0 0 0 0 0 0 0 0 0 0
32 \x20 \40 space 0 +≠0 +≠0 +≠0 0 0 0 0 0 0 0 0
33–47 \x21–\x2F \41–\57 !"#$%&'()*+,-./ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
48–57 \x30–\x39 \60–\71 0123456789 0 +≠0 0 0 +≠0 0 +≠0 0 0 0 +≠0 +≠0
58–64 \x3A–\x40 \72–\100 :;<=>?@ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
65–70 \x41–\x46 \101–\106 ABCDEF 0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 +≠0
71–90 \x47–\x5A \107–\132 GHIJKLMNOP
QRSTUVWXYZ 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 0
91–96 \x5B–\x60 \133–\140 [\]^_` 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
97–102 \x61–\x66 \141–\146 abcdef 0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 +≠0
103–122 \x67–\x7A \147–\172 ghijklmnop
qrstuvwxyz 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 0
123–126 \x7B–\x7E \172–\176 {|}~ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
127 \x7F \177 backspace character (DEL) +≠0 0 0 0 0 0 0 0 0 0 0 0
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/isalpha +

+
diff --git a/devdocs/c/string%2Fbyte%2Fisblank.html b/devdocs/c/string%2Fbyte%2Fisblank.html new file mode 100644 index 00000000..76e4d54e --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fisblank.html @@ -0,0 +1,112 @@ +

isblank

Defined in header <ctype.h> 
int isblank( int ch );
+		 (since C99)

Checks if the given character is a blank character in the current C locale. In the default C locale, only space (0x20) and horizontal tab (0x09) are classified as blank.

+

The behavior is undefined if the value of ch is not representable as unsigned char and is not equal to EOF.

+

Parameters

+ +
ch - character to classify

Return value

Non-zero value if the character is a blank character, zero otherwise.

+

Example

#include <stdio.h>
+#include <ctype.h>
+#include <limits.h>
+ 
+int main(void)
+{
+    for (int ndx=0; ndx<=UCHAR_MAX; ndx++)
+        if (isblank(ndx)) printf("0x%02x\n", ndx);
+}

Output:

+
0x09
+0x20

References

See also

+ +
+
(C99)
 checks if a wide character is a blank character
(function)
C++ documentation for isblank
+ + + + + + + + + + + + + + + + + +
ASCII values characters

iscntrl
iswcntrl

+

isprint
iswprint

+

isspace
iswspace

+

isblank
iswblank

+

isgraph
iswgraph

+

ispunct
iswpunct

+

isalnum
iswalnum

+

isalpha
iswalpha

+

isupper
iswupper

+

islower
iswlower

+

isdigit
iswdigit

+

isxdigit
iswxdigit

+
decimal hexadecimal octal
0–8 \x0–\x8 \0–\10 control codes (NUL, etc.) +≠0 0 0 0 0 0 0 0 0 0 0 0
9 \x9 \11 tab (\t) +≠0 0 +≠0 +≠0 0 0 0 0 0 0 0 0
10–13 \xA–\xD \12–\15 whitespaces (\n, \v, \f, \r) +≠0 0 +≠0 0 0 0 0 0 0 0 0 0
14–31 \xE–\x1F \16–\37 control codes +≠0 0 0 0 0 0 0 0 0 0 0 0
32 \x20 \40 space 0 +≠0 +≠0 +≠0 0 0 0 0 0 0 0 0
33–47 \x21–\x2F \41–\57 !"#$%&'()*+,-./ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
48–57 \x30–\x39 \60–\71 0123456789 0 +≠0 0 0 +≠0 0 +≠0 0 0 0 +≠0 +≠0
58–64 \x3A–\x40 \72–\100 :;<=>?@ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
65–70 \x41–\x46 \101–\106 ABCDEF 0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 +≠0
71–90 \x47–\x5A \107–\132 GHIJKLMNOP
QRSTUVWXYZ 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 0
91–96 \x5B–\x60 \133–\140 [\]^_` 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
97–102 \x61–\x66 \141–\146 abcdef 0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 +≠0
103–122 \x67–\x7A \147–\172 ghijklmnop
qrstuvwxyz 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 0
123–126 \x7B–\x7E \172–\176 {|}~ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
127 \x7F \177 backspace character (DEL) +≠0 0 0 0 0 0 0 0 0 0 0 0
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/isblank +

+
diff --git a/devdocs/c/string%2Fbyte%2Fiscntrl.html b/devdocs/c/string%2Fbyte%2Fiscntrl.html new file mode 100644 index 00000000..54078772 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fiscntrl.html @@ -0,0 +1,118 @@ +

iscntrl

Defined in header <ctype.h> 
int iscntrl( int ch );
+

Checks if the given character is a control character, i.e. codes 0x00-0x1F and 0x7F.

+

The behavior is undefined if the value of ch is not representable as unsigned char and is not equal to EOF.

+

Parameters

+ +
ch - character to classify

Return value

Non-zero value if the character is a control character, zero otherwise.

+

Example

#include <stdio.h>
+#include <ctype.h>
+#include <locale.h>
+ 
+int main(void)
+{
+    unsigned char c = '\x94'; // the control code CCH in ISO-8859-1
+    printf("In the default C locale, \\x94 is %sa control character\n",
+           iscntrl(c) ? "" : "not " );
+    setlocale(LC_ALL, "en_GB.iso88591");
+    printf("In ISO-8859-1 locale, \\x94 is %sa control character\n",
+           iscntrl(c) ? "" : "not " );
+}

Possible output:

+
In the default C locale, \x94 is not a control character
+In ISO-8859-1 locale, \x94 is a control character

References

See also

+ +
+
(C95)
 checks if a wide character is a control character
(function)
C++ documentation for iscntrl
+ + + + + + + + + + + + + + + + + +
ASCII values characters

iscntrl
iswcntrl

+

isprint
iswprint

+

isspace
iswspace

+

isblank
iswblank

+

isgraph
iswgraph

+

ispunct
iswpunct

+

isalnum
iswalnum

+

isalpha
iswalpha

+

isupper
iswupper

+

islower
iswlower

+

isdigit
iswdigit

+

isxdigit
iswxdigit

+
decimal hexadecimal octal
0–8 \x0–\x8 \0–\10 control codes (NUL, etc.) +≠0 0 0 0 0 0 0 0 0 0 0 0
9 \x9 \11 tab (\t) +≠0 0 +≠0 +≠0 0 0 0 0 0 0 0 0
10–13 \xA–\xD \12–\15 whitespaces (\n, \v, \f, \r) +≠0 0 +≠0 0 0 0 0 0 0 0 0 0
14–31 \xE–\x1F \16–\37 control codes +≠0 0 0 0 0 0 0 0 0 0 0 0
32 \x20 \40 space 0 +≠0 +≠0 +≠0 0 0 0 0 0 0 0 0
33–47 \x21–\x2F \41–\57 !"#$%&'()*+,-./ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
48–57 \x30–\x39 \60–\71 0123456789 0 +≠0 0 0 +≠0 0 +≠0 0 0 0 +≠0 +≠0
58–64 \x3A–\x40 \72–\100 :;<=>?@ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
65–70 \x41–\x46 \101–\106 ABCDEF 0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 +≠0
71–90 \x47–\x5A \107–\132 GHIJKLMNOP
QRSTUVWXYZ 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 0
91–96 \x5B–\x60 \133–\140 [\]^_` 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
97–102 \x61–\x66 \141–\146 abcdef 0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 +≠0
103–122 \x67–\x7A \147–\172 ghijklmnop
qrstuvwxyz 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 0
123–126 \x7B–\x7E \172–\176 {|}~ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
127 \x7F \177 backspace character (DEL) +≠0 0 0 0 0 0 0 0 0 0 0 0
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/iscntrl +

+
diff --git a/devdocs/c/string%2Fbyte%2Fisdigit.html b/devdocs/c/string%2Fbyte%2Fisdigit.html new file mode 100644 index 00000000..b3c3ec37 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fisdigit.html @@ -0,0 +1,115 @@ +

isdigit

Defined in header <ctype.h> 
int isdigit( int ch );
+

Checks if the given character is a numeric character (0123456789).

+

The behavior is undefined if the value of ch is not representable as unsigned char and is not equal to EOF.

+

Parameters

+ +
ch - character to classify

Return value

Non-zero value if the character is a numeric character, zero otherwise.

+

Notes

isdigit and isxdigit are the only standard narrow character classification functions that are not affected by the currently installed C locale, although some implementations (e.g. Microsoft in 1252 codepage) may classify additional single-byte characters as digits.

+

Example

#include <stdio.h>
+#include <ctype.h>
+#include <limits.h>
+ 
+int main(void)
+{
+    for (int ndx=0; ndx<=UCHAR_MAX; ndx++)
+        if (isdigit(ndx)) printf("%c", ndx);
+    printf("\n");
+}

Output:

+
0123456789

References

See also

+ +
+
(C95)
 checks if a wide character is a digit
(function)
C++ documentation for isdigit
+ + + + + + + + + + + + + + + + + +
ASCII values characters

iscntrl
iswcntrl

+

isprint
iswprint

+

isspace
iswspace

+

isblank
iswblank

+

isgraph
iswgraph

+

ispunct
iswpunct

+

isalnum
iswalnum

+

isalpha
iswalpha

+

isupper
iswupper

+

islower
iswlower

+

isdigit
iswdigit

+

isxdigit
iswxdigit

+
decimal hexadecimal octal
0–8 \x0–\x8 \0–\10 control codes (NUL, etc.) +≠0 0 0 0 0 0 0 0 0 0 0 0
9 \x9 \11 tab (\t) +≠0 0 +≠0 +≠0 0 0 0 0 0 0 0 0
10–13 \xA–\xD \12–\15 whitespaces (\n, \v, \f, \r) +≠0 0 +≠0 0 0 0 0 0 0 0 0 0
14–31 \xE–\x1F \16–\37 control codes +≠0 0 0 0 0 0 0 0 0 0 0 0
32 \x20 \40 space 0 +≠0 +≠0 +≠0 0 0 0 0 0 0 0 0
33–47 \x21–\x2F \41–\57 !"#$%&'()*+,-./ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
48–57 \x30–\x39 \60–\71 0123456789 0 +≠0 0 0 +≠0 0 +≠0 0 0 0 +≠0 +≠0
58–64 \x3A–\x40 \72–\100 :;<=>?@ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
65–70 \x41–\x46 \101–\106 ABCDEF 0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 +≠0
71–90 \x47–\x5A \107–\132 GHIJKLMNOP
QRSTUVWXYZ 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 0
91–96 \x5B–\x60 \133–\140 [\]^_` 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
97–102 \x61–\x66 \141–\146 abcdef 0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 +≠0
103–122 \x67–\x7A \147–\172 ghijklmnop
qrstuvwxyz 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 0
123–126 \x7B–\x7E \172–\176 {|}~ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
127 \x7F \177 backspace character (DEL) +≠0 0 0 0 0 0 0 0 0 0 0 0
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/isdigit +

+
diff --git a/devdocs/c/string%2Fbyte%2Fisgraph.html b/devdocs/c/string%2Fbyte%2Fisgraph.html new file mode 100644 index 00000000..b6a983b4 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fisgraph.html @@ -0,0 +1,118 @@ +

isgraph

Defined in header <ctype.h> 
int isgraph( int ch );
+

Checks if the given character has a graphical representation, i.e. it is either a number (0123456789), an uppercase letter (ABCDEFGHIJKLMNOPQRSTUVWXYZ), a lowercase letter (abcdefghijklmnopqrstuvwxyz), or a punctuation character (!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~), or any graphical character specific to the current C locale.

+

The behavior is undefined if the value of ch is not representable as unsigned char and is not equal to EOF.

+

Parameters

+ +
ch - character to classify

Return value

Non-zero value if the character has a graphical representation character, zero otherwise.

+

Example

#include <stdio.h>
+#include <ctype.h>
+#include <locale.h>
+ 
+int main(void)
+{
+    unsigned char c = '\xb6'; // the character ¶ in ISO-8859-1
+    printf("In the default C locale, \\xb6 is %sgraphical\n",
+           isgraph(c) ? "" : "not " );
+    setlocale(LC_ALL, "en_GB.iso88591");
+    printf("In ISO-8859-1 locale, \\xb6 is %sgraphical\n",
+           isgraph(c) ? "" : "not " );
+}

Possible output:

+
In the default C locale, \xb6 is not graphical
+In ISO-8859-1 locale, \xb6 is graphical

References

See also

+ +
+
(C95)
 checks if a wide character is a graphical character
(function)
C++ documentation for isgraph
+ + + + + + + + + + + + + + + + + +
ASCII values characters

iscntrl
iswcntrl

+

isprint
iswprint

+

isspace
iswspace

+

isblank
iswblank

+

isgraph
iswgraph

+

ispunct
iswpunct

+

isalnum
iswalnum

+

isalpha
iswalpha

+

isupper
iswupper

+

islower
iswlower

+

isdigit
iswdigit

+

isxdigit
iswxdigit

+
decimal hexadecimal octal
0–8 \x0–\x8 \0–\10 control codes (NUL, etc.) +≠0 0 0 0 0 0 0 0 0 0 0 0
9 \x9 \11 tab (\t) +≠0 0 +≠0 +≠0 0 0 0 0 0 0 0 0
10–13 \xA–\xD \12–\15 whitespaces (\n, \v, \f, \r) +≠0 0 +≠0 0 0 0 0 0 0 0 0 0
14–31 \xE–\x1F \16–\37 control codes +≠0 0 0 0 0 0 0 0 0 0 0 0
32 \x20 \40 space 0 +≠0 +≠0 +≠0 0 0 0 0 0 0 0 0
33–47 \x21–\x2F \41–\57 !"#$%&'()*+,-./ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
48–57 \x30–\x39 \60–\71 0123456789 0 +≠0 0 0 +≠0 0 +≠0 0 0 0 +≠0 +≠0
58–64 \x3A–\x40 \72–\100 :;<=>?@ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
65–70 \x41–\x46 \101–\106 ABCDEF 0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 +≠0
71–90 \x47–\x5A \107–\132 GHIJKLMNOP
QRSTUVWXYZ 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 0
91–96 \x5B–\x60 \133–\140 [\]^_` 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
97–102 \x61–\x66 \141–\146 abcdef 0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 +≠0
103–122 \x67–\x7A \147–\172 ghijklmnop
qrstuvwxyz 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 0
123–126 \x7B–\x7E \172–\176 {|}~ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
127 \x7F \177 backspace character (DEL) +≠0 0 0 0 0 0 0 0 0 0 0 0
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/isgraph +

+
diff --git a/devdocs/c/string%2Fbyte%2Fislower.html b/devdocs/c/string%2Fbyte%2Fislower.html new file mode 100644 index 00000000..1d68c8db --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fislower.html @@ -0,0 +1,119 @@ +

islower

Defined in header <ctype.h> 
int islower( int ch );
+

Checks if the given character is classified as a lowercase character according to the current C locale. In the default "C" locale, islower returns true only for the lowercase letters (abcdefghijklmnopqrstuvwxyz).

+

If islower returns true, it is guaranteed that iscntrl, isdigit, ispunct, and isspace return false for the same character in the same C locale.

+

The behavior is undefined if the value of ch is not representable as unsigned char and is not equal to EOF.

+

Parameters

+ +
ch - character to classify

Return value

Non-zero value if the character is a lowercase letter, zero otherwise.

+

Example

#include <stdio.h>
+#include <ctype.h>
+#include <locale.h>
+ 
+int main(void)
+{
+    unsigned char c = '\xe5'; // letter å in ISO-8859-1
+    printf("In the default C locale, \\xe5 is %slowercase\n",
+           islower(c) ? "" : "not " );
+    setlocale(LC_ALL, "en_GB.iso88591");
+    printf("In ISO-8859-1 locale, \\xe5 is %slowercase\n",
+           islower(c) ? "" : "not " );
+}

Possible output:

+
In the default C locale, \xe5 is not lowercase
+In ISO-8859-1 locale, \xe5 is lowercase

References

See also

+ +
+
(C95)
 checks if a wide character is an lowercase character
(function)
C++ documentation for islower
+ + + + + + + + + + + + + + + + + +
ASCII values characters

iscntrl
iswcntrl

+

isprint
iswprint

+

isspace
iswspace

+

isblank
iswblank

+

isgraph
iswgraph

+

ispunct
iswpunct

+

isalnum
iswalnum

+

isalpha
iswalpha

+

isupper
iswupper

+

islower
iswlower

+

isdigit
iswdigit

+

isxdigit
iswxdigit

+
decimal hexadecimal octal
0–8 \x0–\x8 \0–\10 control codes (NUL, etc.) +≠0 0 0 0 0 0 0 0 0 0 0 0
9 \x9 \11 tab (\t) +≠0 0 +≠0 +≠0 0 0 0 0 0 0 0 0
10–13 \xA–\xD \12–\15 whitespaces (\n, \v, \f, \r) +≠0 0 +≠0 0 0 0 0 0 0 0 0 0
14–31 \xE–\x1F \16–\37 control codes +≠0 0 0 0 0 0 0 0 0 0 0 0
32 \x20 \40 space 0 +≠0 +≠0 +≠0 0 0 0 0 0 0 0 0
33–47 \x21–\x2F \41–\57 !"#$%&'()*+,-./ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
48–57 \x30–\x39 \60–\71 0123456789 0 +≠0 0 0 +≠0 0 +≠0 0 0 0 +≠0 +≠0
58–64 \x3A–\x40 \72–\100 :;<=>?@ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
65–70 \x41–\x46 \101–\106 ABCDEF 0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 +≠0
71–90 \x47–\x5A \107–\132 GHIJKLMNOP
QRSTUVWXYZ 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 0
91–96 \x5B–\x60 \133–\140 [\]^_` 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
97–102 \x61–\x66 \141–\146 abcdef 0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 +≠0
103–122 \x67–\x7A \147–\172 ghijklmnop
qrstuvwxyz 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 0
123–126 \x7B–\x7E \172–\176 {|}~ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
127 \x7F \177 backspace character (DEL) +≠0 0 0 0 0 0 0 0 0 0 0 0
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/islower +

+
diff --git a/devdocs/c/string%2Fbyte%2Fisprint.html b/devdocs/c/string%2Fbyte%2Fisprint.html new file mode 100644 index 00000000..9a1efa2b --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fisprint.html @@ -0,0 +1,116 @@ +

isprint

Defined in header <ctype.h> 
int isprint( int ch );
+

Checks if the given character can be printed, i.e. it is either a number (0123456789), an uppercase letter (ABCDEFGHIJKLMNOPQRSTUVWXYZ), a lowercase letter (abcdefghijklmnopqrstuvwxyz), a punctuation character(!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~), or space, or any character classified as printable by the current C locale.

+

The behavior is undefined if the value of ch is not representable as unsigned char and is not equal to EOF.

+

Parameters

+ +
ch - character to classify

Return value

Non-zero value if the character can be printed, zero otherwise.

+

Example

#include <stdio.h>
+#include <ctype.h>
+#include <locale.h>
+ 
+int main(void)
+{
+    unsigned char c = '\xa0'; // the non-breaking space in ISO-8859-1
+    printf("In the default C locale, \\xa0 is %sprintable\n", isprint(c)?"":"not ");
+    setlocale(LC_ALL, "en_GB.iso88591");
+    printf("In ISO-8859-1 locale, \\xa0 is %sprintable\n", isprint(c)?"":"not ");
+}

Possible output:

+
In the default C locale, \xa0 is not printable
+In ISO-8859-1 locale, \xa0 is printable

References

See also

+ +
+
(C95)
 checks if a wide character is a printing character
(function)
C++ documentation for isprint
+ + + + + + + + + + + + + + + + + +
ASCII values characters

iscntrl
iswcntrl

+

isprint
iswprint

+

isspace
iswspace

+

isblank
iswblank

+

isgraph
iswgraph

+

ispunct
iswpunct

+

isalnum
iswalnum

+

isalpha
iswalpha

+

isupper
iswupper

+

islower
iswlower

+

isdigit
iswdigit

+

isxdigit
iswxdigit

+
decimal hexadecimal octal
0–8 \x0–\x8 \0–\10 control codes (NUL, etc.) +≠0 0 0 0 0 0 0 0 0 0 0 0
9 \x9 \11 tab (\t) +≠0 0 +≠0 +≠0 0 0 0 0 0 0 0 0
10–13 \xA–\xD \12–\15 whitespaces (\n, \v, \f, \r) +≠0 0 +≠0 0 0 0 0 0 0 0 0 0
14–31 \xE–\x1F \16–\37 control codes +≠0 0 0 0 0 0 0 0 0 0 0 0
32 \x20 \40 space 0 +≠0 +≠0 +≠0 0 0 0 0 0 0 0 0
33–47 \x21–\x2F \41–\57 !"#$%&'()*+,-./ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
48–57 \x30–\x39 \60–\71 0123456789 0 +≠0 0 0 +≠0 0 +≠0 0 0 0 +≠0 +≠0
58–64 \x3A–\x40 \72–\100 :;<=>?@ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
65–70 \x41–\x46 \101–\106 ABCDEF 0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 +≠0
71–90 \x47–\x5A \107–\132 GHIJKLMNOP
QRSTUVWXYZ 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 0
91–96 \x5B–\x60 \133–\140 [\]^_` 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
97–102 \x61–\x66 \141–\146 abcdef 0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 +≠0
103–122 \x67–\x7A \147–\172 ghijklmnop
qrstuvwxyz 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 0
123–126 \x7B–\x7E \172–\176 {|}~ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
127 \x7F \177 backspace character (DEL) +≠0 0 0 0 0 0 0 0 0 0 0 0
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/isprint +

+
diff --git a/devdocs/c/string%2Fbyte%2Fispunct.html b/devdocs/c/string%2Fbyte%2Fispunct.html new file mode 100644 index 00000000..c9986542 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fispunct.html @@ -0,0 +1,118 @@ +

ispunct

Defined in header <ctype.h> 
int ispunct( int ch );
+

Checks if the given character is a punctuation character in the current C locale. The default C locale classifies the characters !"#$%&'()*+,-./:;<=>?@[\]^_`{|}~ as punctuation.

+

The behavior is undefined if the value of ch is not representable as unsigned char and is not equal to EOF.

+

Parameters

+ +
ch - character to classify

Return value

Non-zero value if the character is a punctuation character, zero otherwise.

+

Example

#include <stdio.h>
+#include <ctype.h>
+#include <locale.h>
+ 
+int main(void)
+{
+    unsigned char c = '\xd7'; // the character × (multiplication sign) in ISO-8859-1
+    printf("In the default C locale, \\xd7 is %spunctuation\n",
+           ispunct(c) ? "" : "not " );
+    setlocale(LC_ALL, "en_GB.iso88591");
+    printf("In ISO-8859-1 locale, \\xd7 is %spunctuation\n",
+           ispunct(c) ? "" : "not " );
+}

Possible output:

+
In the default C locale, \xd7 is not punctuation
+In ISO-8859-1 locale, \xd7 is punctuation

References

See also

+ +
+
(C95)
 checks if a wide character is a punctuation character
(function)
C++ documentation for ispunct
+ + + + + + + + + + + + + + + + + +
ASCII values characters

iscntrl
iswcntrl

+

isprint
iswprint

+

isspace
iswspace

+

isblank
iswblank

+

isgraph
iswgraph

+

ispunct
iswpunct

+

isalnum
iswalnum

+

isalpha
iswalpha

+

isupper
iswupper

+

islower
iswlower

+

isdigit
iswdigit

+

isxdigit
iswxdigit

+
decimal hexadecimal octal
0–8 \x0–\x8 \0–\10 control codes (NUL, etc.) +≠0 0 0 0 0 0 0 0 0 0 0 0
9 \x9 \11 tab (\t) +≠0 0 +≠0 +≠0 0 0 0 0 0 0 0 0
10–13 \xA–\xD \12–\15 whitespaces (\n, \v, \f, \r) +≠0 0 +≠0 0 0 0 0 0 0 0 0 0
14–31 \xE–\x1F \16–\37 control codes +≠0 0 0 0 0 0 0 0 0 0 0 0
32 \x20 \40 space 0 +≠0 +≠0 +≠0 0 0 0 0 0 0 0 0
33–47 \x21–\x2F \41–\57 !"#$%&'()*+,-./ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
48–57 \x30–\x39 \60–\71 0123456789 0 +≠0 0 0 +≠0 0 +≠0 0 0 0 +≠0 +≠0
58–64 \x3A–\x40 \72–\100 :;<=>?@ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
65–70 \x41–\x46 \101–\106 ABCDEF 0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 +≠0
71–90 \x47–\x5A \107–\132 GHIJKLMNOP
QRSTUVWXYZ 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 0
91–96 \x5B–\x60 \133–\140 [\]^_` 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
97–102 \x61–\x66 \141–\146 abcdef 0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 +≠0
103–122 \x67–\x7A \147–\172 ghijklmnop
qrstuvwxyz 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 0
123–126 \x7B–\x7E \172–\176 {|}~ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
127 \x7F \177 backspace character (DEL) +≠0 0 0 0 0 0 0 0 0 0 0 0
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/ispunct +

+
diff --git a/devdocs/c/string%2Fbyte%2Fisspace.html b/devdocs/c/string%2Fbyte%2Fisspace.html new file mode 100644 index 00000000..4e44c6b0 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fisspace.html @@ -0,0 +1,127 @@ +

isspace

Defined in header <ctype.h> 
int isspace( int ch );
+

Checks if the given character is either

+

The behavior is undefined if the value of ch is not representable as unsigned char and is not equal to EOF.

+

Parameters

+ +
ch - character to classify

Return value

Non-zero value if the character is a whitespace character, zero otherwise.

+

Example

#include <ctype.h>
+#include <limits.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    for (int ndx = 0; ndx <= UCHAR_MAX; ndx++)
+        if (isspace(ndx))
+            printf("0x%02x ", ndx);
+}

Output:

+
0x09 0x0a 0x0b 0x0c 0x0d 0x20

References

See also

+ +
+
(C95)
 checks if a wide character is a space character
(function)
C++ documentation for isspace
+ + + + + + + + + + + + + + + + + +
ASCII values characters

iscntrl
iswcntrl

+

isprint
iswprint

+

isspace
iswspace

+

isblank
iswblank

+

isgraph
iswgraph

+

ispunct
iswpunct

+

isalnum
iswalnum

+

isalpha
iswalpha

+

isupper
iswupper

+

islower
iswlower

+

isdigit
iswdigit

+

isxdigit
iswxdigit

+
decimal hexadecimal octal
0–8 \x0–\x8 \0–\10 control codes (NUL, etc.) +≠0 0 0 0 0 0 0 0 0 0 0 0
9 \x9 \11 tab (\t) +≠0 0 +≠0 +≠0 0 0 0 0 0 0 0 0
10–13 \xA–\xD \12–\15 whitespaces (\n, \v, \f, \r) +≠0 0 +≠0 0 0 0 0 0 0 0 0 0
14–31 \xE–\x1F \16–\37 control codes +≠0 0 0 0 0 0 0 0 0 0 0 0
32 \x20 \40 space 0 +≠0 +≠0 +≠0 0 0 0 0 0 0 0 0
33–47 \x21–\x2F \41–\57 !"#$%&'()*+,-./ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
48–57 \x30–\x39 \60–\71 0123456789 0 +≠0 0 0 +≠0 0 +≠0 0 0 0 +≠0 +≠0
58–64 \x3A–\x40 \72–\100 :;<=>?@ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
65–70 \x41–\x46 \101–\106 ABCDEF 0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 +≠0
71–90 \x47–\x5A \107–\132 GHIJKLMNOP
QRSTUVWXYZ 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 0
91–96 \x5B–\x60 \133–\140 [\]^_` 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
97–102 \x61–\x66 \141–\146 abcdef 0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 +≠0
103–122 \x67–\x7A \147–\172 ghijklmnop
qrstuvwxyz 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 0
123–126 \x7B–\x7E \172–\176 {|}~ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
127 \x7F \177 backspace character (DEL) +≠0 0 0 0 0 0 0 0 0 0 0 0
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/isspace +

+
diff --git a/devdocs/c/string%2Fbyte%2Fisupper.html b/devdocs/c/string%2Fbyte%2Fisupper.html new file mode 100644 index 00000000..52479559 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fisupper.html @@ -0,0 +1,119 @@ +

isupper

Defined in header <ctype.h> 
int isupper( int ch );
+

Checks if the given character is an uppercase character according to the current C locale. In the default "C" locale, isupper returns true only for the uppercase letters (ABCDEFGHIJKLMNOPQRSTUVWXYZ).

+

If isupper returns true, it is guaranteed that iscntrl, isdigit, ispunct, and isspace return false for the same character in the same C locale.

+

The behavior is undefined if the value of ch is not representable as unsigned char and is not equal to EOF.

+

Parameters

+ +
ch - character to classify

Return value

Non-zero value if the character is an uppercase letter, zero otherwise.

+

Example

#include <stdio.h>
+#include <ctype.h>
+#include <locale.h>
+ 
+int main(void)
+{
+    unsigned char c = '\xc6'; // letter Æ in ISO-8859-1
+    printf("In the default C locale, \\xc6 is %suppercase\n",
+           isupper(c) ? "" : "not " );
+    setlocale(LC_ALL, "en_GB.iso88591");
+    printf("In ISO-8859-1 locale, \\xc6 is %suppercase\n",
+           isupper(c) ? "" : "not " );
+}

Possible output:

+
In the default C locale, \xc6 is not uppercase
+In ISO-8859-1 locale, \xc6 is uppercase

References

See also

+ +
+
(C95)
 checks if a wide character is an uppercase character
(function)
C++ documentation for isupper
+ + + + + + + + + + + + + + + + + +
ASCII values characters

iscntrl
iswcntrl

+

isprint
iswprint

+

isspace
iswspace

+

isblank
iswblank

+

isgraph
iswgraph

+

ispunct
iswpunct

+

isalnum
iswalnum

+

isalpha
iswalpha

+

isupper
iswupper

+

islower
iswlower

+

isdigit
iswdigit

+

isxdigit
iswxdigit

+
decimal hexadecimal octal
0–8 \x0–\x8 \0–\10 control codes (NUL, etc.) +≠0 0 0 0 0 0 0 0 0 0 0 0
9 \x9 \11 tab (\t) +≠0 0 +≠0 +≠0 0 0 0 0 0 0 0 0
10–13 \xA–\xD \12–\15 whitespaces (\n, \v, \f, \r) +≠0 0 +≠0 0 0 0 0 0 0 0 0 0
14–31 \xE–\x1F \16–\37 control codes +≠0 0 0 0 0 0 0 0 0 0 0 0
32 \x20 \40 space 0 +≠0 +≠0 +≠0 0 0 0 0 0 0 0 0
33–47 \x21–\x2F \41–\57 !"#$%&'()*+,-./ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
48–57 \x30–\x39 \60–\71 0123456789 0 +≠0 0 0 +≠0 0 +≠0 0 0 0 +≠0 +≠0
58–64 \x3A–\x40 \72–\100 :;<=>?@ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
65–70 \x41–\x46 \101–\106 ABCDEF 0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 +≠0
71–90 \x47–\x5A \107–\132 GHIJKLMNOP
QRSTUVWXYZ 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 0
91–96 \x5B–\x60 \133–\140 [\]^_` 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
97–102 \x61–\x66 \141–\146 abcdef 0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 +≠0
103–122 \x67–\x7A \147–\172 ghijklmnop
qrstuvwxyz 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 0
123–126 \x7B–\x7E \172–\176 {|}~ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
127 \x7F \177 backspace character (DEL) +≠0 0 0 0 0 0 0 0 0 0 0 0
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/isupper +

+
diff --git a/devdocs/c/string%2Fbyte%2Fisxdigit.html b/devdocs/c/string%2Fbyte%2Fisxdigit.html new file mode 100644 index 00000000..86d2cfd9 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fisxdigit.html @@ -0,0 +1,116 @@ +

isxdigit

Defined in header <ctype.h> 
int isxdigit( int ch );
+

Checks if the given character is a hexadecimal numeric character (0123456789abcdefABCDEF) or is classified as a hexadecimal character.

+

The behavior is undefined if the value of ch is not representable as unsigned char and is not equal to EOF.

+

Parameters

+ +
ch - character to classify

Return value

Non-zero value if the character is an hexadecimal numeric character, zero otherwise.

+

Notes

isdigit and isxdigit are the only standard narrow character classification functions that are not affected by the currently installed C locale, although some implementations (e.g. Microsoft in 1252 codepage) may classify additional single-byte characters as digits.

+

Example

#include <ctype.h>
+#include <limits.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    for (int ndx = 0; UCHAR_MAX >= ndx; ++ndx)
+        if (isxdigit(ndx))
+            printf("%c", ndx);
+    printf("\n");
+}

Output:

+
0123456789ABCDEFabcdef

References

See also

+ +
+
(C95)
 checks if a wide character is a hexadecimal character
(function)
C++ documentation for isxdigit
+ + + + + + + + + + + + + + + + + +
ASCII values characters

iscntrl
iswcntrl

+

isprint
iswprint

+

isspace
iswspace

+

isblank
iswblank

+

isgraph
iswgraph

+

ispunct
iswpunct

+

isalnum
iswalnum

+

isalpha
iswalpha

+

isupper
iswupper

+

islower
iswlower

+

isdigit
iswdigit

+

isxdigit
iswxdigit

+
decimal hexadecimal octal
0–8 \x0–\x8 \0–\10 control codes (NUL, etc.) +≠0 0 0 0 0 0 0 0 0 0 0 0
9 \x9 \11 tab (\t) +≠0 0 +≠0 +≠0 0 0 0 0 0 0 0 0
10–13 \xA–\xD \12–\15 whitespaces (\n, \v, \f, \r) +≠0 0 +≠0 0 0 0 0 0 0 0 0 0
14–31 \xE–\x1F \16–\37 control codes +≠0 0 0 0 0 0 0 0 0 0 0 0
32 \x20 \40 space 0 +≠0 +≠0 +≠0 0 0 0 0 0 0 0 0
33–47 \x21–\x2F \41–\57 !"#$%&'()*+,-./ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
48–57 \x30–\x39 \60–\71 0123456789 0 +≠0 0 0 +≠0 0 +≠0 0 0 0 +≠0 +≠0
58–64 \x3A–\x40 \72–\100 :;<=>?@ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
65–70 \x41–\x46 \101–\106 ABCDEF 0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 +≠0
71–90 \x47–\x5A \107–\132 GHIJKLMNOP
QRSTUVWXYZ 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 0
91–96 \x5B–\x60 \133–\140 [\]^_` 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
97–102 \x61–\x66 \141–\146 abcdef 0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 +≠0
103–122 \x67–\x7A \147–\172 ghijklmnop
qrstuvwxyz 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 0
123–126 \x7B–\x7E \172–\176 {|}~ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
127 \x7F \177 backspace character (DEL) +≠0 0 0 0 0 0 0 0 0 0 0 0
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/isxdigit +

+
diff --git a/devdocs/c/string%2Fbyte%2Fmemccpy.html b/devdocs/c/string%2Fbyte%2Fmemccpy.html new file mode 100644 index 00000000..a487a5ec --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fmemccpy.html @@ -0,0 +1,106 @@ +

memccpy

Defined in header <string.h> 
void* memccpy( void* restrict dest, const void* restrict src, int c, size_t count );
+		 (since C23)

Copies bytes from the object pointed to by src to the object pointed to by dest, stopping after any of the next two conditions are satisfied:

+

The src and dest objects are interpreted as arrays of unsigned char.

+

The behavior is undefined if any condition is met:

+

Parameters

+ + + + +
dest - pointer to the object to copy to
src - pointer to the object to copy from
c - terminating byte, converted to unsigned char at first
count - number of bytes to copy

Return value

If the byte (unsigned char)c was found, memccpy returns a pointer to the next byte in dest after (unsigned char)c. Otherwise it returns a null pointer.

+

Notes

The function is identical to the POSIX memccpy.

+

memccpy(dest, src, 0, count) behaves similar to strncpy(dest, src, count), except that the former returns a pointer to the end of the buffer written, and does not zero-pad the destination array. Thus, memccpy is useful for efficiently concatenating multiple strings.

+
char bigString[1000];
+char* end = bigString + sizeof bigString;
+ 
+char* p = memccpy(bigString, "John, ", '\0', sizeof bigString - 1);
+if (p)
+    p = memccpy(p - 1, "Paul, ", '\0', end - p);
+if (p)
+    p = memccpy(p - 1, "George, ", '\0', end - p);
+if (p)
+    p = memccpy(p - 1, "Joel ", '\0', end - p);
+if (!p)
+    end[-1] = '\0';
+ 
+puts(bigString); // John, Paul, George, Joel

Example

#include <ctype.h>
+#include <stdio.h>
+#include <string.h>
+ 
+int main(void)
+{
+    const char src[] = "Stars: Altair, Sun, Vega.";
+    const char terminal[] = {':', ' ', ',', '.', '!'};
+    char dest[sizeof src];
+    const char alt = '@';
+ 
+    for (size_t i = 0; i != sizeof terminal; ++i)
+    {
+        void* to = memccpy(dest, src, terminal[i], sizeof dest);
+ 
+        printf("Terminal '%c' (%s):\t\"", terminal[i], to ? "found" : "absent");
+ 
+        // if `terminal` character was not found - print the whole `dest`
+        to = to ? to : dest + sizeof dest;
+ 
+        for (char* from = dest; from != to; ++from)
+            putchar(isprint(*from) ? *from : alt);
+ 
+        puts("\"");
+    }
+ 
+ 
+    puts("\n" "Separate star names from distances (ly):");
+    const char *star_distance[] = {
+        "Arcturus : 37", "Vega : 25", "Capella : 43", "Rigel : 860", "Procyon : 11"
+    };
+    char names_only[64];
+    char *first = names_only;
+    char *last = names_only + sizeof names_only;
+ 
+    for (size_t t = 0; t != (sizeof star_distance) / (sizeof star_distance[0]); ++t)
+    {
+        if (first)
+            first = memccpy(first, star_distance[t], ' ', last - first);
+        else
+            break;
+    }
+ 
+    if (first)
+    {
+        *first = '\0';
+        puts(names_only);
+    }
+    else
+        puts("Buffer is too small.");
+}

Output:

+
Terminal ':' (found):   "Stars:"
+Terminal ' ' (found):   "Stars: "
+Terminal ',' (found):   "Stars: Altair,"
+Terminal '.' (found):   "Stars: Altair, Sun, Vega."
+Terminal '!' (absent):  "Stars: Altair, Sun, Vega.@"
+ 
+Separate star names from distances (ly):
+Arcturus Vega Capella Rigel Procyon

See also

+ + + + +
+
(C11)
 copies one buffer to another
(function)
+
(C95)(C11)
 copies a certain amount of wide characters between two non-overlapping arrays
(function)
+
(C11)
 moves one buffer to another
(function)
+
(C11)
 copies one string to another
(function)
+
(C11)
 concatenates two strings
(function)
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/memccpy +

+
diff --git a/devdocs/c/string%2Fbyte%2Fmemchr.html b/devdocs/c/string%2Fbyte%2Fmemchr.html new file mode 100644 index 00000000..79724ecd --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fmemchr.html @@ -0,0 +1,51 @@ +

memchr

Defined in header <string.h> 
void *memchr( const void *ptr, int ch, size_t count );
+		 (1) 
/*QVoid*/ *memchr( /*QVoid*/ *ptr, int ch, size_t count );
+		 (2) (since C23)
+1) Finds the first occurrence of (unsigned char)ch in the initial count bytes (each interpreted as unsigned char) of the object pointed to by ptr.
+2) Type-generic function equivalent to (1). Let T be an unqualified object type (including void). If a macro definition of each of these generic functions is suppressed to access an actual function (e.g. if (memchr) or a function pointer is used), the actual function declaration (1) becomes visible.

The behavior is undefined if access occurs beyond the end of the array searched. The behavior is undefined if ptr is a null pointer.

+ + +

This function behaves as if it reads the bytes sequentially and stops as soon as a matching bytes is found: if the array pointed to by ptr is smaller than count, but the match is found within the array, the behavior is well-defined.

+		 (since C11)

Parameters

+ + + +
ptr - pointer to the object to be examined
ch - bytes to search for
count - max number of bytes to examine

Return value

Pointer to the location of the byte, or a null pointer if no such byte is found.

+

Example

#include <stdio.h>
+#include <string.h>
+ 
+int main(void)
+{
+    const char str[] = "ABCDEFG";
+    const int chars[] = {'D', 'd'};
+    for (size_t i = 0; i < sizeof chars / (sizeof chars[0]); ++i)
+    {
+        const int c = chars[i];   
+        const char *ps = memchr(str, c, strlen(str));
+        ps ? printf ("character '%c'(%i) found: %s\n", c, c, ps)
+           : printf ("character '%c'(%i) not found\n", c, c);
+    }
+    return 0;
+}

Possible output:

+
character 'D'(68) found: DEFG
+character 'd'(100) not found

References

See also

+ +
finds the first occurrence of a character
(function)
C++ documentation for memchr
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/memchr +

+
diff --git a/devdocs/c/string%2Fbyte%2Fmemcmp.html b/devdocs/c/string%2Fbyte%2Fmemcmp.html new file mode 100644 index 00000000..4d8d372f --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fmemcmp.html @@ -0,0 +1,57 @@ +

memcmp

Defined in header <string.h> 
int memcmp( const void* lhs, const void* rhs, size_t count );
+

Compares the first count bytes of the objects pointed to by lhs and rhs. The comparison is done lexicographically.

+

The sign of the result is the sign of the difference between the values of the first pair of bytes (both interpreted as unsigned char) that differ in the objects being compared.

+

The behavior is undefined if access occurs beyond the end of either object pointed to by lhs and rhs. The behavior is undefined if either lhs or rhs is a null pointer.

+

Parameters

+ + +
lhs, rhs - pointers to the objects to compare
count - number of bytes to examine

Return value

Negative value if lhs appears before rhs in lexicographical order.

+

Zero if lhs and rhs compare equal, or if count is zero.

+

Positive value if lhs appears after rhs in lexicographical order.

+

Notes

This function reads object representations, not the object values, and is typically meaningful for byte arrays only: structs may have padding bytes whose values are indeterminate, the values of any bytes beyond the last stored member in a union are indeterminate, and a type may have two or more representations for the same value (different encodings for +0 and -0 or for +0.0 and –0.0, indeterminate padding bits within the type).

+

Example

#include <stdio.h>
+#include <string.h>
+ 
+void demo(const char* lhs, const char* rhs, size_t sz)
+{
+    for(size_t n = 0; n < sz; ++n)
+        putchar(lhs[n]);
+ 
+    int rc = memcmp(lhs, rhs, sz);
+    const char *rel = rc < 0 ? " precedes " : rc > 0 ? " follows " : " compares equal ";
+    fputs(rel, stdout);
+ 
+    for(size_t n = 0; n < sz; ++n)
+        putchar(rhs[n]);
+    puts(" in lexicographical order");
+}
+ 
+int main(void)
+{
+    char a1[] = {'a','b','c'};
+    char a2[sizeof a1] = {'a','b','d'};
+ 
+    demo(a1, a2, sizeof a1);
+    demo(a2, a1, sizeof a1);
+    demo(a1, a1, sizeof a1);
+}

Output:

+
abc precedes abd in lexicographical order
+abd follows abc in lexicographical order
+abc compares equal to abc in lexicographical order

References

See also

+ + +
compares two strings
(function)
compares a certain amount of characters of two strings
(function)
C++ documentation for memcmp
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/memcmp +

+
diff --git a/devdocs/c/string%2Fbyte%2Fmemcpy.html b/devdocs/c/string%2Fbyte%2Fmemcpy.html new file mode 100644 index 00000000..d2483fba --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fmemcpy.html @@ -0,0 +1,94 @@ +

memcpy, memcpy_s

Defined in header <string.h>
(1) 
void* memcpy( void *dest, const void *src, size_t count );
+		 (until C99) 
void* memcpy( void *restrict dest, const void *restrict src, size_t count );
+		 (since C99) 
errno_t memcpy_s( void *restrict dest, rsize_t destsz,
+                  const void *restrict src, rsize_t count );
+		 (2) (since C11)
+1) Copies count characters from the object pointed to by src to the object pointed to by dest. Both objects are interpreted as arrays of unsigned char.
+ The behavior is undefined if access occurs beyond the end of the dest array. If the objects overlap (which is a violation of the restrict contract)(since C99), the behavior is undefined. The behavior is undefined if either dest or src is an invalid or null pointer.
+2) Same as (1), except that the following errors are detected at runtime and cause the entire destination range [dest, dest+destsz) to be zeroed out (if both dest and destsz are valid), as well as call the currently installed constraint handler function: +
+ The behavior is undefined if the size of the character array pointed to by dest < count <= destsz; in other words, an erroneous value of destsz does not expose the impending buffer overflow. As with all bounds-checked functions, memcpy_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <string.h>.

Parameters

+ + + + +
dest - pointer to the object to copy to
destsz - max number of bytes to modify in the destination (typically the size of the destination object)
src - pointer to the object to copy from
count - number of bytes to copy

Return value

+1) Returns a copy of dest +
+2) Returns zero on success and non-zero value on error. Also on error, if dest is not a null pointer and destsz is valid, writes destsz zero bytes in to the destination array.

Notes

memcpy may be used to set the effective type of an object obtained by an allocation function.

+

memcpy is the fastest library routine for memory-to-memory copy. It is usually more efficient than strcpy, which must scan the data it copies or memmove, which must take precautions to handle overlapping inputs.

+

Several C compilers transform suitable memory-copying loops to memcpy calls.

+

Where strict aliasing prohibits examining the same memory as values of two different types, memcpy may be used to convert the values.

+

Example

#define __STDC_WANT_LIB_EXT1__ 1
+#include <stdio.h>
+#include <stdint.h>
+#include <inttypes.h>
+#include <string.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    // simple usage
+    char source[] = "once upon a midnight dreary...", dest[4];
+    memcpy(dest, source, sizeof dest);
+    for(size_t n = 0; n < sizeof dest; ++n)
+        putchar(dest[n]);
+ 
+    // setting effective type of allocated memory to be int
+    int *p = malloc(3*sizeof(int));   // allocated memory has no effective type
+    int arr[3] = {1,2,3};
+    memcpy(p,arr,3*sizeof(int));      // allocated memory now has an effective type
+ 
+    // reinterpreting data
+    double d = 0.1;
+//    int64_t n = *(int64_t*)(&d); // strict aliasing violation
+    int64_t n;
+    memcpy(&n, &d, sizeof d); // OK
+    printf("\n%a is %" PRIx64 " as an int64_t\n", d, n);
+ 
+#ifdef __STDC_LIB_EXT1__
+    set_constraint_handler_s(ignore_handler_s);
+    char src[] = "aaaaaaaaaa";
+    char dst[] = "xyxyxyxyxy";
+    int r = memcpy_s(dst,sizeof dst,src,5);
+    printf("dst = \"%s\", r = %d\n", dst,r);
+    r = memcpy_s(dst,5,src,10);            //  count is greater than destsz  
+    printf("dst = \"");
+    for(size_t ndx=0; ndx<sizeof dst; ++ndx) {
+        char c = dst[ndx];
+        c ? printf("%c", c) : printf("\\0");
+    }
+    printf("\", r = %d\n", r);
+#endif
+}

Possible output:

+
once
+0x1.999999999999ap-4 is 3fb999999999999a as an int64_t
+dst = "aaaaayxyxy", r = 0
+dst = "\0\0\0\0\0yxyxy", r = 22

References

See also

+ + + +
+
(C23)
 copies one buffer to another, stopping after the specified delimiter
(function)
+
(C11)
 moves one buffer to another
(function)
+
(C95)(C11)
 copies a certain amount of wide characters between two non-overlapping arrays
(function)
C++ documentation for memcpy
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/memcpy +

+
diff --git a/devdocs/c/string%2Fbyte%2Fmemmove.html b/devdocs/c/string%2Fbyte%2Fmemmove.html new file mode 100644 index 00000000..2fbb10a9 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fmemmove.html @@ -0,0 +1,93 @@ +

memmove, memmove_s

Defined in header <string.h> 
void* memmove( void* dest, const void* src, size_t count );
+		 (1) 
errno_t memmove_s(void *dest, rsize_t destsz, const void *src, rsize_t count);
+		 (2) (since C11)
+1) Copies count characters from the object pointed to by src to the object pointed to by dest. Both objects are interpreted as arrays of unsigned char. The objects may overlap: copying takes place as if the characters were copied to a temporary character array and then the characters were copied from the array to dest.
+ The behavior is undefined if access occurs beyond the end of the dest array. The behavior is undefined if either dest or src is an invalid or null pointer.
+2) Same as (1), except when detecting the following errors at runtime, it zeroes out the entire destination range [dest, dest+destsz) (if both dest and destsz are valid) and calls the currently installed constraint handler function: +
+ The behavior is undefined if the size of the character array pointed to by dest < count <= destsz; in other words, an erroneous value of destsz does not expose the impending buffer overflow. As with all bounds-checked functions, memmove_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <string.h>.

Parameters

+ + + + +
dest - pointer to the object to copy to
destsz - max number of bytes to modify in the destination (typically the size of the destination object)
src - pointer to the object to copy from
count - number of bytes to copy

Return value

+1) Returns a copy of dest +
+2) Returns zero on success and non-zero value on error. Also on error, if dest is not a null pointer and destsz is valid, writes destsz zero bytes in to the destination array.

Notes

memmove may be used to set the effective type of an object obtained by an allocation function.

+

Despite being specified "as if" a temporary buffer is used, actual implementations of this function do not incur the overhead or double copying or extra memory. A common approach (glibc and bsd libc) is to copy bytes forwards from the beginning of the buffer if the destination starts before the source, and backwards from the end otherwise, with a fall back to the more efficient memcpy when there is no overlap at all.

+

Where strict aliasing prohibits examining the same memory as values of two different types, memmove may be used to convert the values.

+

Example

#define __STDC_WANT_LIB_EXT1__ 1
+#include <stdio.h>
+#include <stdint.h>
+#include <inttypes.h>
+#include <string.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    char str[] = "1234567890";
+    puts(str);
+    memmove(str+4, str+3, 3); // copy from [4,5,6] to [5,6,7]
+    puts(str);
+ 
+    // setting effective type of allocated memory to be int
+    int *p = malloc(3*sizeof(int));   // allocated memory has no effective type
+    int arr[3] = {1,2,3};
+    memmove(p,arr,3*sizeof(int));     // allocated memory now has an effective type
+ 
+    // reinterpreting data
+    double d = 0.1;
+//    int64_t n = *(int64_t*)(&d); // strict aliasing violation
+    int64_t n;
+    memmove(&n, &d, sizeof d); // OK
+    printf("%a is %" PRIx64 " as an int64_t\n", d, n);
+ 
+#ifdef __STDC_LIB_EXT1__
+    set_constraint_handler_s(ignore_handler_s);
+    char src[] = "aaaaaaaaaa";
+    char dst[] = "xyxyxyxyxy";
+    int r = memmove_s(dst,sizeof dst,src,5);
+    printf("dst = \"%s\", r = %d\n", dst,r);
+    r = memmove_s(dst,5,src,10);            //  count is greater than destsz  
+    printf("dst = \"");
+    for(size_t ndx=0; ndx<sizeof dst; ++ndx) {
+        char c = dst[ndx];
+        c ? printf("%c", c) : printf("\\0");
+    }
+    printf("\", r = %d\n", r);
+#endif
+}

Possible output:

+
1234567890
+1234456890
+0x1.999999999999ap-4 is 3fb999999999999a as an int64_t
+dst = "aaaaayxyxy", r = 0
+dst = "\0\0\0\0\0yxyxy", r = 22

References

See also

+ + +
+
(C11)
 copies one buffer to another
(function)
+
(C95)(C11)
 copies a certain amount of wide characters between two, possibly overlapping, arrays
(function)
C++ documentation for memmove
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/memmove +

+
diff --git a/devdocs/c/string%2Fbyte%2Fmemset.html b/devdocs/c/string%2Fbyte%2Fmemset.html new file mode 100644 index 00000000..cf822c20 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fmemset.html @@ -0,0 +1,73 @@ +

memset, memset_explicit, memset_s

Defined in header <string.h> 
void *memset( void *dest, int ch, size_t count );
+		 (1) 
void *memset_explicit( void *dest, int ch, size_t count );
+		 (2) (since C23) 
errno_t memset_s( void *dest, rsize_t destsz, int ch, rsize_t count );
+		 (3) (since C11)
+1) Copies the value (unsigned char)ch into each of the first count characters of the object pointed to by dest.
+ The behavior is undefined if access occurs beyond the end of the dest array. The behavior is undefined if dest is a null pointer.
+2) Same as (1), except that is safe for sensitive information.
+3) Same as (1), except that the following errors are detected at runtime and call the currently installed constraint handler function after storing ch in every location of the destination range [dest, dest+destsz) if dest and destsz are themselves valid: +
+ The behavior is undefined if the size of the character array pointed to by dest < count <= destsz; in other words, an erroneous value of destsz does not expose the impending buffer overflow. As with all bounds-checked functions, memset_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <string.h>.

Parameters

+ + + + +
dest - pointer to the object to fill
ch - fill byte
count - number of bytes to fill
destsz - size of the destination array

Return value

+1,2) A copy of dest +
+3) zero on success, non-zero on error. Also on error, if dest is not a null pointer and destsz is valid, writes destsz fill bytes ch to the destination array.

Notes

memset may be optimized away (under the as-if rules) if the object modified by this function is not accessed again for the rest of its lifetime (e.g., gcc bug 8537). For that reason, this function cannot be used to scrub memory (e.g., to fill an array that stored a password with zeroes).

+

This optimization is prohibited for memset_explicit and memset_s: they are guaranteed to perform the memory write.

+

Third-party solutions for that include FreeBSD explicit_bzero or Microsoft SecureZeroMemory.

+

Example

#define __STDC_WANT_LIB_EXT1__ 1
+#include <stdio.h>
+#include <string.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    char str[] = "ghghghghghghghghghghgh";
+    puts(str);
+    memset(str,'a',5);
+    puts(str);
+ 
+#ifdef __STDC_LIB_EXT1__
+    set_constraint_handler_s(ignore_handler_s);
+    int r = memset_s(str, sizeof str, 'b', 5);
+    printf("str = \"%s\", r = %d\n", str, r);
+    r = memset_s(str, 5, 'c', 10);   // count is greater than destsz  
+    printf("str = \"%s\", r = %d\n", str, r);
+#endif
+}

Possible output:

+
ghghghghghghghghghghgh
+aaaaahghghghghghghghgh
+str = "bbbbbhghghghghghghghgh", r = 0
+str = "ccccchghghghghghghghgh", r = 22

References

See also

+ + +
+
(C11)
 copies one buffer to another
(function)
+
(C95)
 copies the given wide character to every position in a wide character array
(function)
C++ documentation for memset
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/memset +

+
diff --git a/devdocs/c/string%2Fbyte%2Fstrcat.html b/devdocs/c/string%2Fbyte%2Fstrcat.html new file mode 100644 index 00000000..08ce3a04 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrcat.html @@ -0,0 +1,76 @@ +

strcat, strcat_s

Defined in header <string.h>
(1) 
char *strcat( char *dest, const char *src );
+		 (until C99) 
char *strcat( char *restrict dest, const char *restrict src );
+		 (since C99) 
errno_t strcat_s(char *restrict dest, rsize_t destsz, const char *restrict src);
+		 (2) (since C11)
+1) Appends a copy of the null-terminated byte string pointed to by src to the end of the null-terminated byte string pointed to by dest. The character src[0] replaces the null terminator at the end of dest. The resulting byte string is null-terminated.
+ The behavior is undefined if the destination array is not large enough for the contents of both src and dest and the terminating null character. The behavior is undefined if the strings overlap. The behavior is undefined if either dest or src is not a pointer to a null-terminated byte string.
+2) Same as (1), except that it may clobber the rest of the destination array (from the last character written to destsz) with unspecified values and that the following errors are detected at runtime and call the currently installed constraint handler function: +
+ The behavior is undefined if the size of the character array pointed to by dest < strlen(dest)+strlen(src)+1 <= destsz; in other words, an erroneous value of destsz does not expose the impending buffer overflow. As with all bounds-checked functions, strcat_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <string.h>.

Parameters

+ + + +
dest - pointer to the null-terminated byte string to append to
src - pointer to the null-terminated byte string to copy from
destsz - maximum number of characters to write, typically the size of the destination buffer

Return value

+1) returns a copy of dest +
+2) returns zero on success, returns non-zero on error. Also, on error, writes zero to dest[0] (unless dest is a null pointer or destsz is zero or greater than RSIZE_MAX).

Notes

Because strcat needs to seek to the end of dest on each call, it is inefficient to concatenate many strings into one using strcat.

+

strcat_s is allowed to clobber the destination array from the last character written up to destsz in order to improve efficiency: it may copy in multibyte blocks and then check for null bytes.

+

The function strcat_s is similar to the BSD function strlcat, except that

+

Although strcat_s prohibits truncation due to potential security risks, it's possible to truncate a string using bounds-checked strncat_s instead.

+

Example

#define __STDC_WANT_LIB_EXT1__ 1
+#include <string.h> 
+#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void) 
+{
+    char str[50] = "Hello ";
+    char str2[50] = "World!";
+    strcat(str, str2);
+    strcat(str, " ...");
+    strcat(str, " Goodbye World!");
+    puts(str);
+ 
+#ifdef __STDC_LIB_EXT1__
+    set_constraint_handler_s(ignore_handler_s);
+    int r = strcat_s(str, sizeof str, " ... ");
+    printf("str = \"%s\", r = %d\n", str, r);
+    r = strcat_s(str, sizeof str, " and this is too much");
+    printf("str = \"%s\", r = %d\n", str, r);
+#endif
+}

Possible output:

+
Hello World! ... Goodbye World!
+str = "Hello World! ... Goodbye World! ... ", r = 0
+str = "", r = 22

References

See also

+ + + +
+
(C11)
 concatenates a certain amount of characters of two strings
(function)
+
(C11)
 copies one string to another
(function)
+
(C23)
 copies one buffer to another, stopping after the specified delimiter
(function)
C++ documentation for strcat
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/strcat +

+
diff --git a/devdocs/c/string%2Fbyte%2Fstrchr.html b/devdocs/c/string%2Fbyte%2Fstrchr.html new file mode 100644 index 00000000..39e66671 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrchr.html @@ -0,0 +1,45 @@ +

strchr

Defined in header <string.h> 
char *strchr( const char *str, int ch );
+		 (1) 
/*QChar*/ *strchr( /*QChar*/ *str, int ch );
+		 (2) (since C23)
+1) Finds the first occurrence of ch (after conversion to char as if by (char)ch) in the null-terminated byte string pointed to by str (each character interpreted as unsigned char). The terminating null character is considered to be a part of the string and can be found when searching for '\0'.
+2) Type-generic function equivalent to (1). Let T be an unqualified character object type. If a macro definition of each of these generic functions is suppressed to access an actual function (e.g. if (strchr) or a function pointer is used), the actual function declaration (1) becomes visible.

The behavior is undefined if str is not a pointer to a null-terminated byte string.

+

Parameters

+ + +
str - pointer to the null-terminated byte string to be analyzed
ch - character to search for

Return value

Pointer to the found character in str, or null pointer if no such character is found.

+

Example

#include <stdio.h>
+#include <string.h>
+ 
+int main(void)
+{
+  const char *str = "Try not. Do, or do not. There is no try.";
+  char target = 'T';
+  const char *result = str;
+ 
+  while((result = strchr(result, target)) != NULL) {
+    printf("Found '%c' starting at '%s'\n", target, result);
+    ++result; // Increment result, otherwise we'll find target at the same location
+  }
+}

Output:

+
Found 'T' starting at 'Try not. Do, or do not. There is no try.'
+Found 'T' starting at 'There is no try.'

References

See also

+ + + +
searches an array for the first occurrence of a character
(function)
finds the last occurrence of a character
(function)
finds the first location of any character in one string, in another string
(function)
C++ documentation for strchr
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/strchr +

+
diff --git a/devdocs/c/string%2Fbyte%2Fstrcmp.html b/devdocs/c/string%2Fbyte%2Fstrcmp.html new file mode 100644 index 00000000..40219714 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrcmp.html @@ -0,0 +1,50 @@ +

strcmp

Defined in header <string.h> 
int strcmp( const char *lhs, const char *rhs );
+

Compares two null-terminated byte strings lexicographically.

+

The sign of the result is the sign of the difference between the values of the first pair of characters (both interpreted as unsigned char) that differ in the strings being compared.

+

The behavior is undefined if lhs or rhs are not pointers to null-terminated byte strings.

+

Parameters

+ +
lhs, rhs - pointers to the null-terminated byte strings to compare

Return value

Negative value if lhs appears before rhs in lexicographical order.

+

Zero if lhs and rhs compare equal.

+

Positive value if lhs appears after rhs in lexicographical order.

+

Notes

This function is not locale-sensitive, unlike strcoll and strxfrm.

+

Example

#include <string.h>
+#include <stdio.h>
+ 
+void demo(const char* lhs, const char* rhs)
+{
+    int rc = strcmp(lhs, rhs);
+    const char *rel = rc < 0 ? "precedes" : rc > 0 ? "follows" : "equals";
+    printf("[%s] %s [%s]\n", lhs, rel, rhs);
+}
+ 
+int main(void)
+{
+    const char* string = "Hello World!";
+    demo(string, "Hello!");
+    demo(string, "Hello");
+    demo(string, "Hello there");
+    demo("Hello, everybody!" + 12, "Hello, somebody!" + 11);
+}

Output:

+
[Hello World!] precedes [Hello!]
+[Hello World!] follows [Hello]
+[Hello World!] precedes [Hello there]
+[body!] equals [body!]

References

See also

+ + + + +
compares a certain amount of characters of two strings
(function)
+
(C95)
 compares two wide strings
(function)
compares two buffers
(function)
compares two strings in accordance to the current locale
(function)
C++ documentation for strcmp
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/strcmp +

+
diff --git a/devdocs/c/string%2Fbyte%2Fstrcoll.html b/devdocs/c/string%2Fbyte%2Fstrcoll.html new file mode 100644 index 00000000..8c19e000 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrcoll.html @@ -0,0 +1,60 @@ +

strcoll

Defined in header <string.h> 
int strcoll( const char* lhs, const char* rhs );
+

Compares two null-terminated byte strings according to the current locale as defined by the LC_COLLATE category.

+

Parameters

+ +
lhs, rhs - pointers to the null-terminated byte strings to compare

Return value

Notes

Collation order is the dictionary order: the position of the letter in the national alphabet (its equivalence class) has higher priority than its case or variant. Within an equivalence class, lowercase characters collate before their uppercase equivalents and locale-specific order may apply to the characters with diacritics. In some locales, groups of characters compare as single collation units. For example, "ch" in Czech follows "h" and precedes "i", and "dzs" in Hungarian follows "dz" and precedes "g".

+

Example

#include <locale.h>
+#include <stdio.h>
+#include <string.h>
+ 
+int main(void)
+{
+    setlocale(LC_COLLATE, "cs_CZ.utf8");
+    // Alternatively, ISO-8859-2 (a.k.a. Latin-2)
+    // may also work on some OS:
+    // setlocale(LC_COLLATE, "cs_CZ.iso88592");
+ 
+    const char* s1 = "hrnec";
+    const char* s2 = "chrt";
+ 
+    printf("In the Czech locale: ");
+    if (strcoll(s1, s2) < 0)
+        printf("%s before %s\n", s1, s2);
+    else
+        printf("%s before %s\n", s2, s1);
+ 
+    printf("In lexicographical comparison: ");
+    if (strcmp(s1, s2) < 0)
+        printf("%s before %s\n", s1, s2);
+    else
+        printf("%s before %s\n", s2, s1);
+}

Output:

+
In the Czech locale: hrnec before chrt
+In lexicographical comparison: chrt before hrnec

References

See also

+ + + + +
+
(C95)
 compares two wide strings in accordance to the current locale
(function)
transform a string so that strcmp would produce the same result as strcoll
(function)
+
(C95)
 transform a wide string so that wcscmp would produce the same result as wcscoll
(function)
compares two strings
(function)
C++ documentation for strcoll
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/strcoll +

+
diff --git a/devdocs/c/string%2Fbyte%2Fstrcpy.html b/devdocs/c/string%2Fbyte%2Fstrcpy.html new file mode 100644 index 00000000..723ef82b --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrcpy.html @@ -0,0 +1,82 @@ +

strcpy, strcpy_s

Defined in header <string.h>
(1) 
char *strcpy( char *dest, const char *src );
+		 (until C99) 
char *strcpy( char *restrict dest, const char *restrict src );
+		 (since C99) 
errno_t strcpy_s( char *restrict dest, rsize_t destsz, const char *restrict src );
+		 (2) (since C11)
+1) Copies the null-terminated byte string pointed to by src, including the null terminator, to the character array whose first element is pointed to by dest.
+ The behavior is undefined if the dest array is not large enough. The behavior is undefined if the strings overlap. The behavior is undefined if either dest is not a pointer to a character array or src is not a pointer to a null-terminated byte string.
+2) Same as (1), except that it may clobber the rest of the destination array with unspecified values and that the following errors are detected at runtime and call the currently installed constraint handler function: +
+ The behavior is undefined if the size of the character array pointed to by dest <= strnlen_s(src, destsz) < destsz; in other words, an erroneous value of destsz does not expose the impending buffer overflow. As with all bounds-checked functions, strcpy_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <string.h>.

Parameters

+ + + +
dest - pointer to the character array to write to
src - pointer to the null-terminated byte string to copy from
destsz - maximum number of characters to write, typically the size of the destination buffer

Return value

+1) returns a copy of dest +
+2) returns zero on success, returns non-zero on error. Also, on error, writes zero to dest[0] (unless dest is a null pointer or destsz is zero or greater than RSIZE_MAX).

Notes

strcpy_s is allowed to clobber the destination array from the last character written up to destsz in order to improve efficiency: it may copy in multibyte blocks and then check for null bytes.

+

The function strcpy_s is similar to the BSD function strlcpy, except that

+

Although strcpy_s prohibits truncation due to potential security risks, it's possible to truncate a string using bounds-checked strncpy_s instead.

+

Example

#define __STDC_WANT_LIB_EXT1__ 1
+#include <string.h>
+#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    const char *src = "Take the test.";
+//  src[0] = 'M' ; // this would be undefined behavior
+    char dst[strlen(src) + 1]; // +1 to accommodate for the null terminator
+    strcpy(dst, src);
+    dst[0] = 'M'; // OK
+    printf("src = %s\ndst = %s\n", src, dst);
+ 
+#ifdef __STDC_LIB_EXT1__
+    set_constraint_handler_s(ignore_handler_s);
+    int r = strcpy_s(dst, sizeof dst, src);
+    printf("dst = \"%s\", r = %d\n", dst, r);
+    r = strcpy_s(dst, sizeof dst, "Take even more tests.");
+    printf("dst = \"%s\", r = %d\n", dst, r);
+#endif
+}

Possible output:

+
src = Take the test.
+dst = Make the test.
+dst = "Take the test.", r = 0
+dst = "", r = 22

References

See also

+ + + + +
+
(C11)
 copies a certain amount of characters from one string to another
(function)
+
(C11)
 copies one buffer to another
(function)
+
(C95)(C11)
 copies one wide string to another
(function)
+
(dynamic memory TR)
 allocate a copy of a string
(function)
C++ documentation for strcpy
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/strcpy +

+
diff --git a/devdocs/c/string%2Fbyte%2Fstrcspn.html b/devdocs/c/string%2Fbyte%2Fstrcspn.html new file mode 100644 index 00000000..43666174 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrcspn.html @@ -0,0 +1,39 @@ +

strcspn

Defined in header <string.h> 
size_t strcspn( const char *dest, const char *src );
+

Returns the length of the maximum initial segment of the null-terminated byte string pointed to by dest, that consists of only the characters not found in the null-terminated byte string pointed to by src.

+

The behavior is undefined if either dest or src is not a pointer to a null-terminated byte string.

+

Parameters

+ + +
dest - pointer to the null-terminated byte string to be analyzed
src - pointer to the null-terminated byte string that contains the characters to search for

Return value

The length of the maximum initial segment that contains only characters not found in the null-terminated byte string pointed to by src

+

Notes

The function name stands for "complementary span" because the function searches for characters not found in src, that is the complement of src.

+

Example

#include <string.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    const char *string = "abcde312$#@";
+    const char *invalid = "*$#";
+ 
+    size_t valid_len = strcspn(string, invalid);
+    if(valid_len != strlen(string))
+       printf("'%s' contains invalid chars starting at position %zu\n",
+               string, valid_len);
+}

Output:

+
'abcde312$#@' contains invalid chars starting at position 8

References

See also

+ + + +
returns the length of the maximum initial segment that consists
of only the characters found in another byte string
(function)
+
(C95)
 returns the length of the maximum initial segment that consists
of only the wide chars not found in another wide string
(function)
finds the first location of any character in one string, in another string
(function)
C++ documentation for strcspn
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/strcspn +

+
diff --git a/devdocs/c/string%2Fbyte%2Fstrdup.html b/devdocs/c/string%2Fbyte%2Fstrdup.html new file mode 100644 index 00000000..9b2114c8 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrdup.html @@ -0,0 +1,30 @@ +

strdup

Defined in header <string.h> 
char *strdup( const char *src );
+		 (since C23)

Returns a pointer to a null-terminated byte string, which is a duplicate of the string pointed to by src. The space for the new string is obtained as if the malloc was invoked. The returned pointer must be passed to free to avoid a memory leak.

+

If an error occurs, a null pointer is returned and errno might be set.

+

Parameters

+ +
src - pointer to the null-terminated byte string to duplicate

Return value

A pointer to the newly allocated string, or a null pointer if an error occurred.

+

Notes

The function is identical to the POSIX strdup.

+

Example

#include <string.h>
+#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    const char *s1 = "Duplicate me!";
+    char *s2 = strdup(s1);
+    printf("s2 = \"%s\"\n", s2);
+    free(s2);
+}

Output:

+
s2 = "Duplicate me!"

See also

+ + + +
+
(C23)
 allocates a copy of a string of specified size
(function)
+
(C11)
 copies one string to another
(function)
allocates memory
(function)
deallocates previously allocated memory
(function)
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/strdup +

+
diff --git a/devdocs/c/string%2Fbyte%2Fstrerror.html b/devdocs/c/string%2Fbyte%2Fstrerror.html new file mode 100644 index 00000000..ffa63b45 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrerror.html @@ -0,0 +1,67 @@ +

strerror, strerror_s, strerrorlen_s

Defined in header <string.h> 
char* strerror( int errnum );
+		 (1) 
errno_t strerror_s( char *buf, rsize_t bufsz, errno_t errnum );
+		 (2) (since C11) 
size_t strerrorlen_s( errno_t errnum );
+		 (3) (since C11)
+1) Returns a pointer to the textual description of the system error code errnum, identical to the description that would be printed by perror().
+ errnum is usually acquired from the errno variable, however the function accepts any value of type int. The contents of the string are locale-specific.
+ The returned string must not be modified by the program, but may be overwritten by a subsequent call to the strerror function. strerror is not required to be thread-safe. Implementations may be returning different pointers to static read-only string literals or may be returning the same pointer over and over, pointing at a static buffer in which strerror places the string.
+2) Same as (1), except that the message is copied into user-provided storage buf. No more than bufsz-1 bytes are written, the buffer is always null-terminated. If the message had to be truncated to fit the buffer and bufsz is greater than 3, then only bufsz-4 bytes are written, and the characters "..." are appended before the null terminator. In addition, the following errors are detected at runtime and call the currently installed constraint handler function: +
+ The behavior is undefined if writing to buf occurs past the end of the array, which can happen when the size of the buffer pointed to by buf is less than the number of characters in the error message which in turn is less than bufsz.
+3) Computes the length of the untruncated locale-specific error message that strerror_s would write if it were called with errnum. The length does not include the null terminator. As with all bounds-checked functions, strerror_s and strerrorlen_s are only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <string.h>.

Parameters

+ + + +
errnum - integral value referring to an error code
buf - pointer to a user-provided buffer
bufsz - size of the user-provided buffer

Return value

+1) Pointer to a null-terminated byte string corresponding to the errno error code errnum.
+2) Zero if the entire message was successfully stored in buf, non-zero otherwise.
+3) Length (not including the null terminator) of the message that strerror_s would return

Notes

POSIX allows subsequent calls to strerror to invalidate the pointer value returned by an earlier call. It also specifies that it is the LC_MESSAGES locale facet that controls the contents of these messages.

+

strerror_s is the only bounds-checked function that allows truncation, because providing as much information as possible about a failure was deemed to be more desirable. POSIX also defines strerror_r for similar purposes.

+

Example

#define __STDC_WANT_LIB_EXT1__ 1
+#include <stdio.h>
+#include <errno.h>
+#include <string.h>
+#include <locale.h>
+ 
+int main(void)
+{
+    FILE *fp = fopen(tmpnam((char[L_tmpnam]){0}), "r");
+    if(fp==NULL) {
+        printf("File opening error: %s\n", strerror(errno));
+        setlocale(LC_MESSAGES, "de_DE.utf8");
+        printf("Now in German: %s\n", strerror(errno));
+#ifdef __STDC_LIB_EXT1__
+        setlocale(LC_ALL, "ja_JP.utf8"); // printf needs CTYPE for multibyte output
+        size_t errmsglen = strerrorlen_s(errno) + 1;
+        char errmsg[errmsglen]; 
+        strerror_s(errmsg, errmsglen, errno);
+        printf("Now in Japanese: %s\n", errmsg);
+#endif
+    }
+}

Possible output:

+
File opening error: No such file or directory
+Now in German: Datei oder Verzeichnis nicht gefunden
+Now in Japanese: そのようなファイル、又はディレクトリはありません

References

See also

+ + +
displays a character string corresponding of the current error to stderr
(function)
macro which expands to POSIX-compatible thread-local error number variable
(macro variable)
C++ documentation for strerror
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/strerror +

+
diff --git a/devdocs/c/string%2Fbyte%2Fstrfromf.html b/devdocs/c/string%2Fbyte%2Fstrfromf.html new file mode 100644 index 00000000..ce768ba4 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrfromf.html @@ -0,0 +1,24 @@ +

strfromf, strfromd, strfromld

Defined in header <stdlib.h> 
int strfromf( char *restrict s, size_t n, const char *restrict format, float fp );
+		 (since C23) 
int strfromd( char *restrict s, size_t n, const char *restrict format, double fp );
+		 (since C23) 
int strfroml( char *restrict s, size_t n, const char *restrict format, long double fp );
+		 (since C23)

Converts a floating-point value to a byte string.

+

The functions are equivalent to snprintf(s, n, format, fp), except that the format string shall only contain the character %, an optional precision that does not contain an asterisk *, and one of the conversion specifiers a, A, e, E, f, F, g, or G, which applies to the type double, float, or long double) indicated by the function suffix (rather than by a length modifier). Use of these functions with any other format string results in undefined behavior.

+

Parameters

+ + + + +
s - pointer to a character string to write to
n - up to n - 1 characters may be written, plus the null terminator
format - pointer to a null-terminated byte string specifying how to interpret the data
fp - floating-point value to convert

Return value

The number of characters that would have been written had n been sufficiently large, not counting the terminating null character. Thus, the null-terminated output has been completely written if and only if the returned value is both nonnegative and less than n.

+

Example

Reference

See also

+ +
+
(C99)(C11)(C11)(C11)(C11)
 prints formatted output to stdout, a file stream or a buffer
(function)
+
(C99)(C99)
 converts a byte string to a floating point value
(function)
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/strfromf +

+
diff --git a/devdocs/c/string%2Fbyte%2Fstrlen.html b/devdocs/c/string%2Fbyte%2Fstrlen.html new file mode 100644 index 00000000..e8a60fbc --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrlen.html @@ -0,0 +1,49 @@ +

strlen, strnlen_s

Defined in header <string.h> 
size_t strlen( const char *str );
+		 (1) 
size_t strnlen_s( const char *str, size_t strsz );
+		 (2) (since C11)
+1) Returns the length of the given null-terminated byte string, that is, the number of characters in a character array whose first element is pointed to by str up to and not including the first null character.
+ The behavior is undefined if str is not a pointer to a null-terminated byte string.
+2) Same as (1), except that the function returns zero if str is a null pointer and returns strsz if the null character was not found in the first strsz bytes of str.
+ The behavior is undefined if both str points to a character array which lacks the null character and the size of that character array < strsz; in other words, an erroneous value of strsz does not expose the impending buffer overflow. As with all bounds-checked functions, strnlen_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <string.h>.

Parameters

+ + +
str - pointer to the null-terminated byte string to be examined
strsz - maximum number of characters to examine

Return value

+1) The length of the null-terminated byte string str.
+2) The length of the null-terminated byte string str on success, zero if str is a null pointer, strsz if the null character was not found.

Notes

strnlen_s and wcsnlen_s are the only bounds-checked functions that do not invoke the runtime constraints handler. They are pure utility functions used to provide limited support for non-null terminated strings.

+

Example

#define __STDC_WANT_LIB_EXT1__ 1
+#include <string.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    const char str[] = "How many characters does this string contain?";
+ 
+    printf("without null character: %zu\n", strlen(str));
+    printf("with null character:    %zu\n", sizeof str);
+ 
+#ifdef __STDC_LIB_EXT1__
+    printf("without null character: %zu\n", strnlen_s(str, sizeof str));
+#endif
+}

Possible output:

+
without null character: 45
+with null character:    46
+without null character: 45

References

See also

+ + +
+
(C95)(C11)
 returns the length of a wide string
(function)
returns the number of bytes in the next multibyte character
(function)
C++ documentation for strlen
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/strlen +

+
diff --git a/devdocs/c/string%2Fbyte%2Fstrncat.html b/devdocs/c/string%2Fbyte%2Fstrncat.html new file mode 100644 index 00000000..282db51e --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrncat.html @@ -0,0 +1,93 @@ +

strncat, strncat_s

Defined in header <string.h>
(1) 
char *strncat( char *dest, const char *src, size_t count );
+		 (until C99) 
char *strncat( char *restrict dest, const char *restrict src, size_t count );
+		 (since C99) 
errno_t strncat_s( char *restrict dest, rsize_t destsz,
+                   const char *restrict src, rsize_t count );
+		 (2) (since C11)
+1) Appends at most count characters from the character array pointed to by src, stopping if the null character is found, to the end of the null-terminated byte string pointed to by dest. The character src[0] replaces the null terminator at the end of dest. The terminating null character is always appended in the end (so the maximum number of bytes the function may write is count+1).
+ The behavior is undefined if the destination array does not have enough space for the contents of both dest and the first count characters of src, plus the terminating null character. The behavior is undefined if the source and destination objects overlap. The behavior is undefined if either dest is not a pointer to a null-terminated byte string or src is not a pointer to a character array,
+2) Same as (1), except that this function may clobber the remainder of the destination array (from the last byte written to destsz) and that the following errors are detected at runtime and call the currently installed constraint handler function: +
+ The behavior is undefined if the size of the character array pointed to by dest < strnlen(dest,destsz)+strnlen(src,count)+1 < destsz; in other words, an erroneous value of destsz does not expose the impending buffer overflow. The behavior is undefined if the size of the character array pointed to by src < strnlen(src,count) < destsz; in other words, an erroneous value of count does not expose the impending buffer overflow. As with all bounds-checked functions, strncat_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <string.h>.

Parameters

+ + + + +
dest - pointer to the null-terminated byte string to append to
src - pointer to the character array to copy from
count - maximum number of characters to copy
destsz - the size of the destination buffer

Return value

+1) returns a copy of dest +
+2) returns zero on success, returns non-zero on error. Also, on error, writes zero to dest[0] (unless dest is a null pointer or destsz is zero or greater than RSIZE_MAX).

Notes

Because strncat needs to seek to the end of dest on each call, it is inefficient to concatenate many strings into one using strncat.

+

Although truncation to fit the destination buffer is a security risk and therefore a runtime constraints violation for strncat_s, it is possible to get the truncating behavior by specifying count equal to the size of the destination array minus one: it will copy the first count bytes and append the null terminator as always: strncat_s(dst, sizeof dst, src, (sizeof dst)-strnlen_s(dst, sizeof dst)-1);

+

Example

#define __STDC_WANT_LIB_EXT1__ 1
+#include <string.h>
+#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    char str[50] = "Hello ";
+    char str2[50] = "World!";
+    strcat(str, str2);
+    strncat(str, " Goodbye World!", 3);
+    puts(str);
+ 
+#ifdef __STDC_LIB_EXT1__
+    set_constraint_handler_s(ignore_handler_s);
+    char s1[100] = "good";
+    char s5[1000] = "bye";
+    int r1 = strncat_s(s1, 100, s5, 1000); // r1 is 0, s1 holds "goodbye\0"
+    printf("s1 = %s, r1 = %d\n", s1, r1);
+    char s2[6] = "hello";
+    int r2 = strncat_s(s2, 6, "", 1); // r2 is 0, s2 holds "hello\0"
+    printf("s2 = %s, r2 = %d\n", s2, r2);
+    char s3[6] = "hello";
+    int r3 = strncat_s(s3, 6, "X", 2); // r3 is non-zero, s3 holds "\0"
+    printf("s3 = %s, r3 = %d\n", s3, r3);
+    // the strncat_s truncation idiom:
+    char s4[7] = "abc";
+    int r4 = strncat_s(s4, 7, "defghijklmn", 3); // r4 is 0, s4 holds "abcdef\0"
+    printf("s4 = %s, r4 = %d\n", s4, r4);
+#endif
+}

Possible output:

+
Hello World! Go
+s1 = goodbye, r1 = 0
+s2 = hello, r2 = 0
+s3 = , r3 = 22
+s4 = abcdef, r4 = 0

References

See also

+ + + +
+
(C11)
 concatenates two strings
(function)
+
(C11)
 copies one string to another
(function)
+
(C23)
 copies one buffer to another, stopping after the specified delimiter
(function)
C++ documentation for strncat
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/strncat +

+
diff --git a/devdocs/c/string%2Fbyte%2Fstrncmp.html b/devdocs/c/string%2Fbyte%2Fstrncmp.html new file mode 100644 index 00000000..d2dc2071 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrncmp.html @@ -0,0 +1,58 @@ +

strncmp

Defined in header <string.h> 
int strncmp( const char* lhs, const char* rhs, size_t count );
+

Compares at most count characters of two possibly null-terminated arrays. The comparison is done lexicographically. Characters following the null character are not compared.

+

The sign of the result is the sign of the difference between the values of the first pair of characters (both interpreted as unsigned char) that differ in the arrays being compared.

+

The behavior is undefined when access occurs past the end of either array lhs or rhs. The behavior is undefined when either lhs or rhs is the null pointer.

+

Parameters

+ + +
lhs, rhs - pointers to the possibly null-terminated arrays to compare
count - maximum number of characters to compare

Return value

Negative value if lhs appears before rhs in lexicographical order.

+

Zero if lhs and rhs compare equal, or if count is zero.

+

Positive value if lhs appears after rhs in lexicographical order.

+

Notes

This function is not locale-sensitive, unlike strcoll and strxfrm.

+

Example

#include <stdio.h>
+#include <string.h>
+ 
+void demo(const char* lhs, const char* rhs, int sz)
+{
+    const int rc = strncmp(lhs, rhs, sz);
+    if (rc < 0)
+        printf("First %d chars of [%s] precede [%s]\n", sz, lhs, rhs);
+    else if (rc > 0)
+        printf("First %d chars of [%s] follow [%s]\n", sz, lhs, rhs);
+    else
+        printf("First %d chars of [%s] equal [%s]\n", sz, lhs, rhs);
+}
+int main(void)
+{
+    const char* string = "Hello World!";
+    demo(string, "Hello!", 5);
+    demo(string, "Hello", 10);
+    demo(string, "Hello there", 10);
+    demo("Hello, everybody!" + 12, "Hello, somebody!" + 11, 5);
+}

Output:

+
First 5 chars of [Hello World!] equal [Hello!]
+First 10 chars of [Hello World!] follow [Hello]
+First 10 chars of [Hello World!] precede [Hello there]
+First 5 chars of [body!] equal [body!]

References

See also

+ + + + +
compares two strings
(function)
+
(C95)
 compares a certain amount of characters from two wide strings
(function)
compares two buffers
(function)
compares two strings in accordance to the current locale
(function)
C++ documentation for strncmp
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/strncmp +

+
diff --git a/devdocs/c/string%2Fbyte%2Fstrncpy.html b/devdocs/c/string%2Fbyte%2Fstrncpy.html new file mode 100644 index 00000000..45076374 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrncpy.html @@ -0,0 +1,101 @@ +

strncpy, strncpy_s

Defined in header <string.h>
(1) 
char *strncpy( char *dest, const char *src, size_t count );
+		 (until C99) 
char *strncpy( char *restrict dest, const char *restrict src, size_t count );
+		 (since C99) 
errno_t strncpy_s( char *restrict dest, rsize_t destsz,
+                   const char *restrict src, rsize_t count );
+		 (2) (since C11)
+1) Copies at most count characters of the character array pointed to by src (including the terminating null character, but not any of the characters that follow the null character) to character array pointed to by dest.
+ If count is reached before the entire array src was copied, the resulting character array is not null-terminated.
+ If, after copying the terminating null character from src, count is not reached, additional null characters are written to dest until the total of count characters have been written.
+ The behavior is undefined if the character arrays overlap, if either dest or src is not a pointer to a character array (including if dest or src is a null pointer), if the size of the array pointed to by dest is less than count, or if the size of the array pointed to by src is less than count and it does not contain a null character.
+2) Same as (1), except that the function does not continue writing zeroes into the destination array to pad up to count, it stops after writing the terminating null character (if there was no null in the source, it writes one at dest[count] and then stops). Also, the following errors are detected at runtime and call the currently installed constraint handler function: +
+ The behavior is undefined if the size of the character array pointed to by dest < strnlen_s(src, destsz) <= destsz; in other words, an erroneous value of destsz does not expose the impending buffer overflow. The behavior is undefined if the size of the character array pointed to by src < strnlen_s(src, count) < destsz; in other words, an erroneous value of count does not expose the impending buffer overflow. As with all bounds-checked functions, strncpy_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <string.h>.

Parameters

+ + + + +
dest - pointer to the character array to copy to
src - pointer to the character array to copy from
count - maximum number of characters to copy
destsz - the size of the destination buffer

Return value

+1) returns a copy of dest +
+2) returns zero on success, returns non-zero on error. Also, on error, writes zero to dest[0] (unless dest is a null pointer or destsz is zero or greater than RSIZE_MAX) and may clobber the rest of the destination array with unspecified values.

Notes

As corrected by the post-C11 DR 468, strncpy_s, unlike strcpy_s, is only allowed to clobber the remainder of the destination array if an error occurs.

+

Unlike strncpy, strncpy_s does not pad the destination array with zeroes, This is a common source of errors when converting existing code to the bounds-checked version.

+

Although truncation to fit the destination buffer is a security risk and therefore a runtime constraints violation for strncpy_s, it is possible to get the truncating behavior by specifying count equal to the size of the destination array minus one: it will copy the first count bytes and append the null terminator as always: strncpy_s(dst, sizeof dst, src, (sizeof dst)-1);

+

Example

#define __STDC_WANT_LIB_EXT1__ 1
+#include <string.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <errno.h>
+ 
+int main(void)
+{
+    char src[] = "hi";
+    char dest[6] = "abcdef"; // no null terminator
+    strncpy(dest, src, 5); // writes five characters 'h', 'i', '\0', '\0', '\0' to dest
+    printf("strncpy(dest, src, 5) to a 6-byte dest gives : ");
+    for (size_t n = 0; n < sizeof dest; ++n) {
+        char c = dest[n];
+        c ? printf("'%c' ", c) : printf("'\\0' ");
+    }
+ 
+    printf("\nstrncpy(dest2, src, 2) to a 2-byte dst gives : ");
+    char dest2[2];
+    strncpy(dest2, src, 2); // truncation: writes two characters 'h', 'i', to dest2
+    for (size_t n = 0; n < sizeof dest2; ++n) {
+        char c = dest2[n];
+        c ? printf("'%c' ", c) : printf("'\\0' ");
+    }
+    printf("\n");
+ 
+#ifdef __STDC_LIB_EXT1__
+    set_constraint_handler_s(ignore_handler_s);
+    char dst1[6], src1[100] = "hello";
+    errno_t r1 = strncpy_s(dst1, 6, src1, 100);  // writes 0 to r1, 6 characters to dst1
+    printf("dst1 = \"%s\", r1 = %d\n", dst1,r1); // 'h','e','l','l','o','\0' to dst1
+ 
+    char dst2[5], src2[7] = {'g','o','o','d','b','y','e'};
+    errno_t r2 = strncpy_s(dst2, 5, src2, 7);    // copy overflows the destination array
+    printf("dst2 = \"%s\", r2 = %d\n", dst2,r2); // writes nonzero to r2,'\0' to dst2[0]
+ 
+    char dst3[5];
+    errno_t r3 = strncpy_s(dst3, 5, src2, 4);    // writes 0 to r3, 5 characters to dst3
+    printf("dst3 = \"%s\", r3 = %d\n", dst3,r3); // 'g', 'o', 'o', 'd', '\0' to dst3
+#endif
+}

Possible output:

+
strncpy(dest, src, 5) to a 6-byte dst gives : 'h' 'i' '\0' '\0' '\0' 'f'
+strncpy(dest2, src, 2) to a 2-byte dst gives : 'h' 'i'
+dst1 = "hello", r1 = 0
+dst2 = "", r2 = 22
+dst3 = "good", r3 = 0

References

See also

+ + + +
+
(C11)
 copies one string to another
(function)
+
(C11)
 copies one buffer to another
(function)
+
(dynamic memory TR)
 allocate a copy of a string up to specified size
(function)
C++ documentation for strncpy
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/strncpy +

+
diff --git a/devdocs/c/string%2Fbyte%2Fstrndup.html b/devdocs/c/string%2Fbyte%2Fstrndup.html new file mode 100644 index 00000000..74cb2101 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrndup.html @@ -0,0 +1,46 @@ +

strndup

Defined in header <string.h> 
char *strndup( const char *src, size_t size );
+		 (since C23)

Returns a pointer to a null-terminated byte string, which contains copies of at most size bytes from the string pointed to by src. The space for the new string is obtained as if malloc was called. If the null terminator is not encountered in the first size bytes, it is appended to the duplicated string.

+

The returned pointer must be passed to free to avoid a memory leak.

+

If an error occurs, a null pointer is returned and errno might be set.

+

Parameters

+ + +
src - pointer to the null-terminated byte string to duplicate
size - max number of bytes to copy from src

Return value

A pointer to the newly allocated string, or a null pointer if an error occurred.

+

Notes

The function is identical to the POSIX strndup except that it is allowed, but not required to set errno on error.

+

Example

#include <string.h>
+#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    const size_t n = 3;
+ 
+    const char *src = "Replica";
+    char *dup = strndup(src, n);
+    printf("strndup(\"%s\", %lu) == \"%s\"\n", src, n, dup);
+    free(dup);
+ 
+    src = "Hi";
+    dup = strndup(src, n);
+    printf("strndup(\"%s\", %lu) == \"%s\"\n", src, n, dup);
+    free(dup);
+ 
+    const char arr[] = {'A','B','C','D'}; // NB: no trailing '\0'
+    dup = strndup(arr, n);
+    printf("strndup({'A','B','C','D'}, %lu) == \"%s\"\n", n, dup);
+    free(dup);
+}

Output:

+
strndup("Replica", 3) == "Rep"
+strndup("Hi", 3) == "Hi"
+strndup({'A','B','C','D'}, 3) == "ABC"

See also

+ + + +
+
(C23)
 allocates a copy of a string
(function)
+
(C11)
 copies one string to another
(function)
allocates memory
(function)
deallocates previously allocated memory
(function)
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/strndup +

+
diff --git a/devdocs/c/string%2Fbyte%2Fstrpbrk.html b/devdocs/c/string%2Fbyte%2Fstrpbrk.html new file mode 100644 index 00000000..7b5f44dc --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrpbrk.html @@ -0,0 +1,49 @@ +

strpbrk

Defined in header <string.h> 
char *strpbrk( const char *dest, const char *breakset );
+		 (1) 
/*QChar*/ *strpbrk( /*QChar*/ *dest, const char *breakset );
+		 (2) (since C23)
+1 ) Scans the null-terminated byte string pointed to by dest for any character from the null-terminated byte string pointed to by breakset, and returns a pointer to that character.
+2) Type-generic function equivalent to (1). Let T be an unqualified character object type. If a macro definition of each of these generic functions is suppressed to access an actual function (e.g. if (strpbrk) or a function pointer is used), the actual function declaration (1) becomes visible.

The behavior is undefined if either dest or breakset is not a pointer to a null-terminated byte string.

+

Parameters

+ + +
dest - pointer to the null-terminated byte string to be analyzed
breakset - pointer to the null-terminated byte string that contains the characters to search for

Return value

Pointer to the first character in dest, that is also in breakset, or null pointer if no such character exists.

+

Notes

The name stands for "string pointer break", because it returns a pointer to the first of the separator ("break") characters.

+

Example

#include <stdio.h>
+#include <string.h>
+ 
+int main(void)
+{
+    const char* str = "hello world, friend of mine!";
+    const char* sep = " ,!";
+ 
+    unsigned int cnt = 0;
+    do {
+       str = strpbrk(str, sep); // find separator
+       if(str) str += strspn(str, sep); // skip separator
+       ++cnt; // increment word count
+    } while(str && *str);
+ 
+    printf("There are %u words\n", cnt);
+}

Output:

+
There are 5 words

References

See also

+ + + +
returns the length of the maximum initial segment that consists
of only the characters not found in another byte string
(function)
finds the first occurrence of a character
(function)
+
(C11)
 finds the next token in a byte string
(function)
C++ documentation for strpbrk
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/strpbrk +

+
diff --git a/devdocs/c/string%2Fbyte%2Fstrrchr.html b/devdocs/c/string%2Fbyte%2Fstrrchr.html new file mode 100644 index 00000000..62efabfe --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrrchr.html @@ -0,0 +1,39 @@ +

strrchr

Defined in header <string.h> 
char *strrchr( const char *str, int ch );
+		 (1) 
/*QChar*/ *strrchr( /*QChar*/ *str, int ch );
+		 (2) (since C23)
+1) Finds the last occurrence of ch (after conversion to char as if by (char)ch) in the null-terminated byte string pointed to by str (each character interpreted as unsigned char). The terminating null character is considered to be a part of the string and can be found if searching for '\0'.
+2) Type-generic function equivalent to (1). Let T be an unqualified character object type. If a macro definition of each of these generic functions is suppressed to access an actual function (e.g. if (strrchr) or a function pointer is used), the actual function declaration (1) becomes visible.

The behavior is undefined if str is not a pointer to a null-terminated byte string.

+

Parameters

+ + +
str - pointer to the null-terminated byte string to be analyzed
ch - character to search for

Return value

Pointer to the found character in str, or null pointer if no such character is found.

+

Example

#include <string.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    char szSomeFileName[] = "foo/bar/foobar.txt";
+    char *pLastSlash = strrchr(szSomeFileName, '/');
+    char *pszBaseName = pLastSlash ? pLastSlash + 1 : szSomeFileName;
+    printf("Base Name: %s", pszBaseName);
+}

Output:

+
Base Name: foobar.txt

References

See also

+ + +
finds the first occurrence of a character
(function)
finds the first location of any character in one string, in another string
(function)
C++ documentation for strrchr
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/strrchr +

+
diff --git a/devdocs/c/string%2Fbyte%2Fstrspn.html b/devdocs/c/string%2Fbyte%2Fstrspn.html new file mode 100644 index 00000000..1d11b48e --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrspn.html @@ -0,0 +1,38 @@ +

strspn

Defined in header <string.h> 
size_t strspn( const char *dest, const char *src );
+

Returns the length of the maximum initial segment (span) of the null-terminated byte string pointed to by dest, that consists of only the characters found in the null-terminated byte string pointed to by src.

+

The behavior is undefined if either dest or src is not a pointer to a null-terminated byte string.

+

Parameters

+ + +
dest - pointer to the null-terminated byte string to be analyzed
src - pointer to the null-terminated byte string that contains the characters to search for

Return value

The length of the maximum initial segment that contains only characters from the null-terminated byte string pointed to by src

+

Example

#include <string.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    const char *string = "abcde312$#@";
+    const char *low_alpha = "qwertyuiopasdfghjklzxcvbnm";
+ 
+    size_t spnsz = strspn(string, low_alpha);
+    printf("After skipping initial lowercase letters from '%s'\n"
+           "The remainder is '%s'\n", string, string+spnsz);
+}

Output:

+
After skipping initial lowercase letters from 'abcde312$#@'
+The remainder is '312$#@'

References

See also

+ + + +
returns the length of the maximum initial segment that consists
of only the characters not found in another byte string
(function)
+
(C95)
 returns the length of the maximum initial segment that consists
of only the wide characters found in another wide string
(function)
finds the first location of any character in one string, in another string
(function)
C++ documentation for strspn
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/strspn +

+
diff --git a/devdocs/c/string%2Fbyte%2Fstrstr.html b/devdocs/c/string%2Fbyte%2Fstrstr.html new file mode 100644 index 00000000..0d03ea16 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrstr.html @@ -0,0 +1,56 @@ +

strstr

Defined in header <string.h> 
char *strstr( const char *str, const char *substr );
+		 (1) 
/*QChar*/ *strstr( /*QChar*/ *str, const char *substr );
+		 (2) (since C23)
+1) Finds the first occurrence of the null-terminated byte string pointed to by substr in the null-terminated byte string pointed to by str. The terminating null characters are not compared.
+2) Type-generic function equivalent to (1). Let T be an unqualified character object type. If a macro definition of each of these generic functions is suppressed to access an actual function (e.g. if (strstr) or a function pointer is used), the actual function declaration (1) becomes visible.

The behavior is undefined if either str or substr is not a pointer to a null-terminated byte string.

+

Parameters

+ + +
str - pointer to the null-terminated byte string to examine
substr - pointer to the null-terminated byte string to search for

Return value

Pointer to the first character of the found substring in str, or a null pointer if such substring is not found. If substr points to an empty string, str is returned.

+

Example

#include <string.h>
+#include <stdio.h>
+ 
+void find_str(char const *str, char const *substr)
+{
+    char *pos = strstr(str, substr);
+    pos ? printf("found the string '%s' in '%s' at position %td\n",
+                 substr, str, pos - str)
+        : printf("the string '%s' was not found in '%s'\n",
+                 substr, str);
+}
+ 
+int main(void)
+{
+    char *str = "one two three";
+    find_str(str, "two");
+    find_str(str, "");
+    find_str(str, "nine");
+    find_str(str, "n");
+ 
+    return 0;
+}

Output:

+
found the string 'two' in 'one two three' at position 4
+found the string '' in 'one two three' at position 0
+the string 'nine' was not found in 'one two three'
+found the string 'n' in 'one two three' at position 1

References

See also

+ + +
finds the first occurrence of a character
(function)
finds the last occurrence of a character
(function)
C++ documentation for strstr
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/strstr +

+
diff --git a/devdocs/c/string%2Fbyte%2Fstrtof.html b/devdocs/c/string%2Fbyte%2Fstrtof.html new file mode 100644 index 00000000..b3be49b7 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrtof.html @@ -0,0 +1,90 @@ +

strtof, strtod, strtold

Defined in header <stdlib.h> 
float       strtof( const char *restrict str, char **restrict str_end );
+		 (since C99) 
double      strtod( const char          *str, char          **str_end );
 (until C99) 
double      strtod( const char *restrict str, char **restrict str_end );
+		 (since C99) 
long double strtold( const char *restrict str, char **restrict str_end );
+		 (since C99)

Interprets a floating-point value in a byte string pointed to by str.

+

Function discards any whitespace characters (as determined by isspace) until first non-whitespace character is found. Then it takes as many characters as possible to form a valid floating-point representation and converts them to a floating-point value. The valid floating-point value can be one of the following:

+ + +
    +
  • hexadecimal floating-point expression. It consists of the following parts:
    • +
      +
    • (optional) plus or minus sign
      • +
    • 0x or 0X
      • +
    • nonempty sequence of hexadecimal digits optionally containing a decimal-point character (as determined by the current C locale) (defines significand)
      • +
    • (optional) p or P followed with optional minus or plus sign and nonempty sequence of decimal digits (defines exponent to base 2)
      • +
    +
  • infinity expression. It consists of the following parts:
    • +
      +
    • (optional) plus or minus sign
      • +
    • INF or INFINITY ignoring case
      • +
    +
  • not-a-number expression. It consists of the following parts:
    • +
      +
    • (optional) plus or minus sign
      • +
    • NAN or NAN(char_sequence) ignoring case of the NAN part. char_sequence can only contain digits, Latin letters, and underscores. The result is a quiet NaN floating-point value.
      • +
    +
 (since C99)

The functions sets the pointer pointed to by str_end to point to the character past the last character interpreted. If str_end is a null pointer, it is ignored.

+

Parameters

+ + +
str - pointer to the null-terminated byte string to be interpreted
str_end - pointer to a pointer to character.

Return value

Floating-point value corresponding to the contents of str on success. If the converted value falls out of range of corresponding return type, range error occurs (errno is set to ERANGE) and HUGE_VAL, HUGE_VALF or HUGE_VALL is returned. If no conversion can be performed, ​0​ is returned.

+

Example

#include <stdio.h>
+#include <errno.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    // parsing with error handling
+    const char *p = "111.11 -2.22 Nan nan(2) inF 0X1.BC70A3D70A3D7P+6  1.18973e+4932zzz";
+    printf("Parsing '%s':\n", p);
+    char *end;
+    for (double f = strtod(p, &end); p != end; f = strtod(p, &end))
+    {
+        printf("'%.*s' -> ", (int)(end-p), p);
+        p = end;
+        if (errno == ERANGE){
+            printf("range error, got ");
+            errno = 0;
+        }
+        printf("%f\n", f);
+    }
+ 
+    // parsing without error handling
+    printf("\"  -0.0000000123junk\"  -->  %g\n", strtod("  -0.0000000123junk", NULL));
+    printf("\"junk\"                 -->  %g\n", strtod("junk", NULL));
+}

Possible output:

+
Parsing '111.11 -2.22 Nan nan(2) inF 0X1.BC70A3D70A3D7P+6  1.18973e+4932zzz':
+'111.11' -> 111.110000
+' -2.22' -> -2.220000
+' Nan' -> nan
+' nan(2)' -> nan
+' inF' -> inf
+' 0X1.BC70A3D70A3D7P+6' -> 111.110000
+'  1.18973e+4932' -> range error, got inf
+"  -0.0000000123junk"  -->  -1.23e-08
+"junk"                 -->  0

References

See also

+ + +
converts a byte string to a floating-point value
(function)
+
(C99)(C95)(C99)
 converts a wide string to a floating-point value
(function)
C++ documentation for strtof, strtod, strtold
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/strtof +

+
diff --git a/devdocs/c/string%2Fbyte%2Fstrtoimax.html b/devdocs/c/string%2Fbyte%2Fstrtoimax.html new file mode 100644 index 00000000..2e199efe --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrtoimax.html @@ -0,0 +1,78 @@ +

strtoimax, strtoumax

Defined in header <inttypes.h> 
intmax_t strtoimax( const char *restrict nptr,
+                    char **restrict endptr, int base );
+		 (since C99) 
uintmax_t strtoumax( const char *restrict nptr,
+                     char **restrict endptr, int base );
+		 (since C99)

Interprets an integer value in a byte string pointed to by nptr.

+

Discards any whitespace characters (as identified by calling isspace) until the first non-whitespace character is found, then takes as many characters as possible to form a valid base-n (where n=base) integer number representation and converts them to an integer value. The valid integer value consists of the following parts:

+

The set of valid values for base is {0,2,3,...,36}. The set of valid digits for base-2 integers is {0,1}, for base-3 integers is {0,1,2}, and so on. For bases larger than 10, valid digits include alphabetic characters, starting from Aa for base-11 integer, to Zz for base-36 integer. The case of the characters is ignored.

+

Additional numeric formats may be accepted by the currently installed C locale.

+

If the value of base is ​0​, the numeric base is auto-detected: if the prefix is 0, the base is octal, if the prefix is 0x or 0X, the base is hexadecimal, otherwise the base is decimal.

+

If the minus sign was part of the input sequence, the numeric value calculated from the sequence of digits is negated as if by unary minus in the result type.

+

The functions sets the pointer pointed to by endptr to point to the character past the last character interpreted. If endptr is a null pointer, it is ignored.

+

If the nptr is empty or does not have the expected form, no conversion is performed, and (if endptr is not a null pointer) the value of nptr is stored in the object pointed to by endptr.

+

Parameters

+ + + +
nptr - pointer to the null-terminated byte string to be interpreted
endptr - pointer to a pointer to character.
base - base of the interpreted integer value

Return value

Example

#include <errno.h>
+#include <inttypes.h>
+#include <stdio.h>
+#include <string.h>
+ 
+int main(void)
+{
+    char* endptr;
+ 
+    printf("%ld\n", strtoimax(" -123junk",&endptr,10)); /* base 10                    */
+    printf("%ld\n", strtoimax("11111111",&endptr,2));   /* base 2                     */
+    printf("%ld\n", strtoimax("XyZ",&endptr,36));       /* base 36                    */
+    printf("%ld\n", strtoimax("010",&endptr,0));        /* octal auto-detection       */
+    printf("%ld\n", strtoimax("10",&endptr,0));         /* decimal auto-detection     */
+    printf("%ld\n", strtoimax("0x10",&endptr,0));       /* hexadecimal auto-detection */
+ 
+    /* range error             */
+    /* LONG_MAX+1 --> LONG_MAX */
+    errno = 0;
+    printf("%ld\n", strtoimax("9223372036854775808",&endptr,10));
+    printf("%s\n", strerror(errno));
+ 
+    return 0;
+}

Output:

+
-123
+255
+44027
+8
+10
+16
+9223372036854775807
+Numerical result out of range

References

See also

+ + + +
+
(C99)(C99)
 converts a wide string to intmax_t or uintmax_t
(function)
+
(C99)
 converts a byte string to an integer value
(function)
+
(C99)
 converts a byte string to an unsigned integer value
(function)
C++ documentation for strtoimax, strtoumax
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/strtoimax +

+
diff --git a/devdocs/c/string%2Fbyte%2Fstrtok.html b/devdocs/c/string%2Fbyte%2Fstrtok.html new file mode 100644 index 00000000..09405556 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrtok.html @@ -0,0 +1,108 @@ +

strtok, strtok_s

Defined in header <string.h>
(1) 
char *strtok( char *str, const char *delim );
 (until C99) 
char *strtok( char *restrict str, const char *restrict delim );
+		 (since C99) 
char *strtok_s(char *restrict str, rsize_t *restrict strmax,
+     const char *restrict delim, char **restrict ptr);
+		 (2) (since C11)
+1) Finds the next token in a null-terminated byte string pointed to by str. The separator characters are identified by null-terminated byte string pointed to by delim.
+ This function is designed to be called multiple times to obtain successive tokens from the same string.
+ The behavior is undefined if either str or delim is not a pointer to a null-terminated byte string.
+2) Same as (1), except that on every step, writes the number of characters left to see in str into *strmax and writes the tokenizer's internal state to *ptr. Repeat calls (with null str) must pass strmax and ptr with the values stored by the previous call. Also, the following errors are detected at runtime and call the currently installed constraint handler function, without storing anything in the object pointed to by ptr +
+ The behavior is undefined if both str points to a character array which lacks the null character and strmax points to a value which is greater than the size of that character array. As with all bounds-checked functions, strtok_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <string.h>.

Parameters

+ + + + +
str - pointer to the null-terminated byte string to tokenize
delim - pointer to the null-terminated byte string identifying delimiters
strmax - pointer to an object which initially holds the size of str: strtok_s stores the number of characters that remain to be examined
ptr - pointer to an object of type char*, which is used by strtok_s to store its internal state

Return value

Returns pointer to the beginning of the next token or a null pointer if there are no more tokens.

+

Note

This function is destructive: it writes the '\0' characters in the elements of the string str. In particular, a string literal cannot be used as the first argument of strtok.

+

Each call to strtok modifies a static variable: is not thread safe.

+

Unlike most other tokenizers, the delimiters in strtok can be different for each subsequent token, and can even depend on the contents of the previous tokens.

+

The strtok_s function differs from the POSIX strtok_r function by guarding against storing outside of the string being tokenized, and by checking runtime constraints. The Microsoft CRT strtok_s signature matches this POSIX strtok_r definition, not the C11 strtok_s.

+

Example

#define __STDC_WANT_LIB_EXT1__ 1
+#include <string.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    char input[] = "A bird came down the walk";
+    printf("Parsing the input string '%s'\n", input);
+    char *token = strtok(input, " ");
+    while(token) {
+        puts(token);
+        token = strtok(NULL, " ");
+    }
+ 
+    printf("Contents of the input string now: '");
+    for(size_t n = 0; n < sizeof input; ++n)
+        input[n] ? putchar(input[n]) : fputs("\\0", stdout);
+    puts("'");
+ 
+#ifdef __STDC_LIB_EXT1__
+    char str[] = "A bird came down the walk";
+    rsize_t strmax = sizeof str;
+    const char *delim = " ";
+    char *next_token;
+    printf("Parsing the input string '%s'\n", str);
+    token = strtok_s(str, &strmax, delim, &next_token);
+    while(token) {
+        puts(token);
+        token = strtok_s(NULL, &strmax, delim, &next_token);
+    }
+ 
+    printf("Contents of the input string now: '");
+    for(size_t n = 0; n < sizeof str; ++n)
+        str[n] ? putchar(str[n]) : fputs("\\0", stdout);
+    puts("'");
+#endif
+}

Possible output:

+
Parsing the input string 'A bird came down the walk'
+A
+bird
+came
+down
+the
+walk
+Contents of the input string now: 'A\0bird\0came\0down\0the\0walk\0'
+Parsing the input string 'A bird came down the walk'
+A
+bird
+came
+down
+the
+walk
+Contents of the input string now: 'A\0bird\0came\0down\0the\0walk\0'

References

See also

+ + + + +
finds the first location of any character in one string, in another string
(function)
returns the length of the maximum initial segment that consists
of only the characters not found in another byte string
(function)
returns the length of the maximum initial segment that consists
of only the characters found in another byte string
(function)
+
(C95)(C11)
 finds the next token in a wide string
(function)
C++ documentation for strtok
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/strtok +

+
diff --git a/devdocs/c/string%2Fbyte%2Fstrtol.html b/devdocs/c/string%2Fbyte%2Fstrtol.html new file mode 100644 index 00000000..5b16e65b --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrtol.html @@ -0,0 +1,105 @@ +

strtol, strtoll

Defined in header <stdlib.h> 
long      strtol( const char          *str, char          **str_end, int base );
 (until C99) 
long      strtol( const char *restrict str, char **restrict str_end, int base );
+		 (since C99) 
long long strtoll( const char *restrict str, char **restrict str_end, int base );
+		 (since C99)

Interprets an integer value in a byte string pointed to by str.

+

Discards any whitespace characters (as identified by calling isspace) until the first non-whitespace character is found, then takes as many characters as possible to form a valid base-n (where n=base) integer number representation and converts them to an integer value. The valid integer value consists of the following parts:

+

The set of valid values for base is {0,2,3,...,36}. The set of valid digits for base-2 integers is {0,1}, for base-3 integers is {0,1,2}, and so on. For bases larger than 10, valid digits include alphabetic characters, starting from Aa for base-11 integer, to Zz for base-36 integer. The case of the characters is ignored.

+

Additional numeric formats may be accepted by the currently installed C locale.

+

If the value of base is ​0​, the numeric base is auto-detected: if the prefix is 0, the base is octal, if the prefix is 0x or 0X, the base is hexadecimal, otherwise the base is decimal.

+

If the minus sign was part of the input sequence, the numeric value calculated from the sequence of digits is negated as if by unary minus in the result type.

+

The functions set the pointer pointed to by str_end to point to the character past the last numeric character interpreted. If str_end is a null pointer, it is ignored.

+

If the str is empty or does not have the expected form, no conversion is performed, and (if str_end is not a null pointer) the value of str is stored in the object pointed to by str_end.

+

Parameters

+ + + +
str - pointer to the null-terminated byte string to be interpreted
str_end - pointer to a pointer to character.
base - base of the interpreted integer value

Return value

Example

#include <errno.h>
+#include <limits.h>
+#include <stdbool.h>
+#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    // parsing with error handling
+    const char *p = "10 200000000000000000000000000000 30 -40 junk";
+    printf("Parsing '%s':\n", p);
+ 
+    for (;;)
+    {
+        // errno can be set to any non-zero value by a library function call
+        // regardless of whether there was an error, so it needs to be cleared
+        // in order to check the error set by strtol
+        errno = 0;
+        char *end;
+        const long i = strtol(p, &end, 10);
+        if (p == end)
+            break;
+ 
+        const bool range_error = errno == ERANGE;
+        printf("Extracted '%.*s', strtol returned %ld.", (int)(end-p), p, i);
+        p = end;
+ 
+        if (range_error)
+            printf("\n --> Range error occurred.");
+ 
+        putchar('\n');
+    }
+ 
+    printf("Unextracted leftover: '%s'\n\n", p);
+ 
+    // parsing without error handling
+    printf("\"1010\" in binary  --> %ld\n", strtol("1010", NULL, 2));
+    printf("\"12\"   in octal   --> %ld\n", strtol("12",   NULL, 8));
+    printf("\"A\"    in hex     --> %ld\n", strtol("A",    NULL, 16));
+    printf("\"junk\" in base-36 --> %ld\n", strtol("junk", NULL, 36));
+    printf("\"012\"  in auto-detected base --> %ld\n", strtol("012",  NULL, 0));
+    printf("\"0xA\"  in auto-detected base --> %ld\n", strtol("0xA",  NULL, 0));
+    printf("\"junk\" in auto-detected base --> %ld\n", strtol("junk", NULL, 0));
+}

Possible output:

+
Parsing '10 200000000000000000000000000000 30 -40 junk':
+Extracted '10', strtol returned 10.
+Extracted ' 200000000000000000000000000000', strtol returned 9223372036854775807.
+ --> Range error occurred.
+Extracted ' 30', strtol returned 30.
+Extracted ' -40', strtol returned -40.
+Unextracted leftover: ' junk'
+ 
+"1010" in binary  --> 10
+"12"   in octal   --> 10
+"A"    in hex     --> 10
+"junk" in base-36 --> 926192
+"012"  in auto-detected base --> 10
+"0xA"  in auto-detected base --> 10
+"junk" in auto-detected base --> 0

References

See also

+ + + + +
+
(C99)
 converts a byte string to an integer value
(function)
+
(C99)
 converts a byte string to an unsigned integer value
(function)
+
(C95)(C99)
 converts a wide string to an integer value
(function)
+
(C95)(C99)
 converts a wide string to an unsigned integer value
(function)
C++ documentation for strtol, strtoll
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/strtol +

+
diff --git a/devdocs/c/string%2Fbyte%2Fstrtoul.html b/devdocs/c/string%2Fbyte%2Fstrtoul.html new file mode 100644 index 00000000..e27953c9 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrtoul.html @@ -0,0 +1,75 @@ +

strtoul, strtoull

Defined in header <stdlib.h> 
unsigned long      strtoul( const char          *str, char          **str_end, 
+                            int base );
 (until C99) 
unsigned long      strtoul( const char *restrict str, char **restrict str_end, 
+                            int base );
+		 (since C99) 
unsigned long long strtoull( const char *restrict str, char **restrict str_end,
+                             int base );
+		 (since C99)

Interprets an unsigned integer value in a byte string pointed to by str.

+

Discards any whitespace characters (as identified by calling isspace) until the first non-whitespace character is found, then takes as many characters as possible to form a valid base-n (where n=base) unsigned integer number representation and converts them to an integer value. The valid unsigned integer value consists of the following parts:

+

The set of valid values for base is {0,2,3,...,36}. The set of valid digits for base-2 integers is {0,1}, for base-3 integers is {0,1,2}, and so on. For bases larger than 10, valid digits include alphabetic characters, starting from Aa for base-11 integer, to Zz for base-36 integer. The case of the characters is ignored.

+

Additional numeric formats may be accepted by the currently installed C locale.

+

If the value of base is ​0​, the numeric base is auto-detected: if the prefix is 0, the base is octal, if the prefix is 0x or 0X, the base is hexadecimal, otherwise the base is decimal.

+

If the minus sign was part of the input sequence, the numeric value calculated from the sequence of digits is negated as if by unary minus in the result type, which applies unsigned integer wraparound rules.

+

The functions sets the pointer pointed to by str_end to point to the character past the last character interpreted. If str_end is a null pointer, it is ignored.

+

Parameters

+ + + +
str - pointer to the null-terminated byte string to be interpreted
str_end - pointer to a pointer to character, might be set to a position past the last character interpreted
base - base of the interpreted integer value

Return value

Integer value corresponding to the contents of str on success. If the converted value falls out of range of corresponding return type, range error occurs (errno is set to ERANGE) and ULONG_MAX or ULLONG_MAX is returned. If no conversion can be performed, ​0​ is returned.

+

Example

#include <errno.h>
+#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    const char *p = "10 200000000000000000000000000000 30 -40 - 42";
+    printf("Parsing '%s':\n", p);
+    char *end = NULL;
+    for (unsigned long i = strtoul(p, &end, 10);
+         p != end;
+         i = strtoul(p, &end, 10))
+    {
+        printf("'%.*s' -> ", (int)(end - p), p);
+        p = end;
+        if (errno == ERANGE)
+        {
+            errno = 0;
+            printf("range error, got ");
+        }
+        printf("%lu\n", i);
+    }
+    printf("After the loop p points to '%s'\n", p);
+}

Output:

+
Parsing '10 200000000000000000000000000000 30 -40 - 42':
+'10' -> 10
+' 200000000000000000000000000000' -> range error, got 18446744073709551615
+' 30' -> 30
+' -40' -> 18446744073709551576
+After the loop p points to ' - 42'

References

See also

+ + + +
+
(C95)(C99)
 converts a wide string to an unsigned integer value
(function)
+
(C99)
 converts a byte string to an integer value
(function)
+
(C99)
 converts a byte string to an integer value
(function)
C++ documentation for strtoul
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/strtoul +

+
diff --git a/devdocs/c/string%2Fbyte%2Fstrxfrm.html b/devdocs/c/string%2Fbyte%2Fstrxfrm.html new file mode 100644 index 00000000..15aa44a8 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrxfrm.html @@ -0,0 +1,65 @@ +

strxfrm

Defined in header <string.h> 
size_t strxfrm( char          *dest, const char          *src, size_t count );
+		 (until C99) 
size_t strxfrm( char *restrict dest, const char *restrict src, size_t count );
+		 (since C99)

Transforms the null-terminated byte string pointed to by src into the implementation-defined form such that comparing two transformed strings with strcmp gives the same result as comparing the original strings with strcoll, in the current C locale.

+

The first count characters of the transformed string are written to destination, including the terminating null character, and the length of the full transformed string is returned, excluding the terminating null character.

+

The behavior is undefined if the dest array is not large enough. The behavior is undefined if dest and src overlap.

+

If count is ​0​, then dest is allowed to be a null pointer.

+

Notes

The correct length of the buffer that can receive the entire transformed string is 1+strxfrm(NULL, src, 0)

+

This function is used when making multiple locale-dependent comparisons using the same string or set of strings, because it is more efficient to use strxfrm to transform all the strings just once, and subsequently compare the transformed strings with strcmp.

+

Parameters

+ + + +
dest - pointer to the first element of the array where the transformed string will be written
src - pointer to the first character of a null-terminated byte string to transform
count - maximum number of characters to be written

Return value

The length of the transformed string, not including the terminating null-character.

+

Example

#include <stdio.h>
+#include <string.h>
+#include <locale.h>
+ 
+int main(void)
+{
+    setlocale(LC_COLLATE, "cs_CZ.iso88592");
+ 
+    const char *in1 = "hrnec";
+    char out1[1+strxfrm(NULL, in1, 0)];
+    strxfrm(out1, in1, sizeof out1);
+ 
+    const char *in2 = "chrt";
+    char out2[1+strxfrm(NULL, in2, 0)];
+    strxfrm(out2, in2, sizeof out2);
+ 
+    printf("In the Czech locale: ");
+    if(strcmp(out1, out2) < 0)
+         printf("%s before %s\n",in1, in2);
+    else
+         printf("%s before %s\n",in2, in1);
+ 
+    printf("In lexicographical comparison: ");
+    if(strcmp(in1, in2)<0)
+         printf("%s before %s\n",in1, in2);
+    else
+         printf("%s before %s\n",in2, in1);
+ 
+}

Possible output:

+
In the Czech locale: hrnec before chrt
+In lexicographical comparison: chrt before hrnec

References

See also

+ + + + +
compares two strings in accordance to the current locale
(function)
+
(C95)
 compares two wide strings in accordance to the current locale
(function)
compares two strings
(function)
+
(C95)
 transform a wide string so that wcscmp would produce the same result as wcscoll
(function)
C++ documentation for strxfrm
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/strxfrm +

+
diff --git a/devdocs/c/string%2Fbyte%2Ftolower.html b/devdocs/c/string%2Fbyte%2Ftolower.html new file mode 100644 index 00000000..5e9a1f90 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Ftolower.html @@ -0,0 +1,49 @@ +

tolower

Defined in header <ctype.h> 
int tolower( int ch );
+

Converts the given character to lowercase according to the character conversion rules defined by the currently installed C locale.

+

In the default "C" locale, the following uppercase letters ABCDEFGHIJKLMNOPQRSTUVWXYZ are replaced with respective lowercase letters abcdefghijklmnopqrstuvwxyz.

+

Parameters

+ +
ch - character to be converted. If the value of ch is not representable as unsigned char and does not equal EOF, the behavior is undefined.

Return value

Lowercase version of ch or unmodified ch if no lowercase version is listed in the current C locale.

+

Example

#include <stdio.h>
+#include <ctype.h>
+#include <locale.h>
+#include <limits.h>
+ 
+int main(void)
+{
+    /* In the default locale: */
+    for (unsigned char u = 0; u < UCHAR_MAX; u++) {
+        unsigned char l = tolower(u);
+        if (l != u) printf("%c%c ", u, l);
+    }
+    printf("\n\n");
+ 
+    unsigned char c = '\xb4'; // the character Ž in ISO-8859-15
+                              // but ´ (acute accent) in ISO-8859-1
+    setlocale(LC_ALL, "en_US.iso88591");
+    printf("in iso8859-1, tolower('0x%x') gives 0x%x\n", c, tolower(c));
+    setlocale(LC_ALL, "en_US.iso885915");
+    printf("in iso8859-15, tolower('0x%x') gives 0x%x\n", c, tolower(c));
+}

Possible output:

+
Aa Bb Cc Dd Ee Ff Gg Hh Ii Jj Kk Ll Mm Nn Oo Pp Qq Rr Ss Tt Uu Vv Ww Xx Yy Zz
+ 
+in iso8859-1, tolower('0xb4') gives 0xb4
+in iso8859-15, tolower('0xb4') gives 0xb8

References

See also

+ + +
converts a character to uppercase
(function)
+
(C95)
 converts a wide character to lowercase
(function)
C++ documentation for tolower
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/tolower +

+
diff --git a/devdocs/c/string%2Fbyte%2Ftoupper.html b/devdocs/c/string%2Fbyte%2Ftoupper.html new file mode 100644 index 00000000..6e38516f --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Ftoupper.html @@ -0,0 +1,49 @@ +

toupper

Defined in header <ctype.h> 
int toupper( int ch );
+

Converts the given character to uppercase according to the character conversion rules defined by the currently installed C locale.

+

In the default "C" locale, the following lowercase letters abcdefghijklmnopqrstuvwxyz are replaced with respective uppercase letters ABCDEFGHIJKLMNOPQRSTUVWXYZ.

+

Parameters

+ +
ch - character to be converted. If the value of ch is not representable as unsigned char and does not equal EOF, the behavior is undefined.

Return value

Uppercase version of ch or unmodified ch if no uppercase version is listed in the current C locale.

+

Example

#include <stdio.h>
+#include <ctype.h>
+#include <locale.h>
+#include <limits.h>
+ 
+int main(void)
+{
+    /* In the default locale: */
+    for (unsigned char l = 0; l < UCHAR_MAX; l++) {
+        unsigned char u = toupper(l);
+        if (u != l) printf("%c%c ", l, u);
+    }
+    printf("\n\n");
+ 
+    unsigned char c = '\xb8'; // the character Ž in ISO-8859-15
+                              // but ´ (acute accent) in ISO-8859-1 
+    setlocale(LC_ALL, "en_US.iso88591");
+    printf("in iso8859-1, toupper('0x%x') gives 0x%x\n", c, toupper(c));
+    setlocale(LC_ALL, "en_US.iso885915");
+    printf("in iso8859-15, toupper('0x%x') gives 0x%x\n", c, toupper(c));
+}

Possible output:

+
aA bB cC dD eE fF gG hH iI jJ kK lL mM nN oO pP qQ rR sS tT uU vV wW xX yY zZ 
+ 
+in iso8859-1, toupper('0xb8') gives 0xb8
+in iso8859-15, toupper('0xb8') gives 0xb4

References

See also

+ + +
converts a character to lowercase
(function)
+
(C95)
 converts a wide character to uppercase
(function)
C++ documentation for toupper
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte/toupper +

+
diff --git a/devdocs/c/string%2Fbyte.html b/devdocs/c/string%2Fbyte.html new file mode 100644 index 00000000..154cff0a --- /dev/null +++ b/devdocs/c/string%2Fbyte.html @@ -0,0 +1,203 @@ +

Null-terminated byte strings

A null-terminated byte string (NTBS) is a sequence of nonzero bytes followed by a byte with value zero (the terminating null character). Each byte in a byte string encodes one character of some character set. For example, the character array {'\x63','\x61','\x74','\0'} is an NTBS holding the string "cat" in ASCII encoding.

+

Functions

+ + + + + + + + + + + + + + + + +
Character classification
Defined in header <ctype.h>
checks if a character is alphanumeric
(function)
checks if a character is alphabetic
(function)
checks if a character is lowercase
(function)
checks if a character is an uppercase character
(function)
checks if a character is a digit
(function)
checks if a character is a hexadecimal character
(function)
checks if a character is a control character
(function)
checks if a character is a graphical character
(function)
checks if a character is a space character
(function)
+
(C99)
 checks if a character is a blank character
(function)
checks if a character is a printing character
(function)
checks if a character is a punctuation character
(function)
Character manipulation
converts a character to lowercase
(function)
converts a character to uppercase
(function)

Note: additional functions whose names begin with either to or is, followed by a lowercase letter, may be added to the header ctype.h in future and should not be defined by programs that include that header.

+ + + + + + + + + + + + + + + + + + +
ASCII values characters

iscntrl
iswcntrl

+

isprint
iswprint

+

isspace
iswspace

+

isblank
iswblank

+

isgraph
iswgraph

+

ispunct
iswpunct

+

isalnum
iswalnum

+

isalpha
iswalpha

+

isupper
iswupper

+

islower
iswlower

+

isdigit
iswdigit

+

isxdigit
iswxdigit

+
decimal hexadecimal octal
0–8 \x0–\x8 \0–\10 control codes (NUL, etc.) +≠0 0 0 0 0 0 0 0 0 0 0 0
9 \x9 \11 tab (\t) +≠0 0 +≠0 +≠0 0 0 0 0 0 0 0 0
10–13 \xA–\xD \12–\15 whitespaces (\n, \v, \f, \r) +≠0 0 +≠0 0 0 0 0 0 0 0 0 0
14–31 \xE–\x1F \16–\37 control codes +≠0 0 0 0 0 0 0 0 0 0 0 0
32 \x20 \40 space 0 +≠0 +≠0 +≠0 0 0 0 0 0 0 0 0
33–47 \x21–\x2F \41–\57 !"#$%&'()*+,-./ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
48–57 \x30–\x39 \60–\71 0123456789 0 +≠0 0 0 +≠0 0 +≠0 0 0 0 +≠0 +≠0
58–64 \x3A–\x40 \72–\100 :;<=>?@ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
65–70 \x41–\x46 \101–\106 ABCDEF 0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 +≠0
71–90 \x47–\x5A \107–\132 GHIJKLMNOP
QRSTUVWXYZ 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 0
91–96 \x5B–\x60 \133–\140 [\]^_` 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
97–102 \x61–\x66 \141–\146 abcdef 0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 +≠0
103–122 \x67–\x7A \147–\172 ghijklmnop
qrstuvwxyz 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 0
123–126 \x7B–\x7E \172–\176 {|}~ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
127 \x7F \177 backspace character (DEL) +≠0 0 0 0 0 0 0 0 0 0 0 0
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Conversions to and from numeric formats
Defined in header <stdlib.h>
converts a byte string to a floating-point value
(function)
+
(C99)
 converts a byte string to an integer value
(function)
+
(C99)
 converts a byte string to an integer value
(function)
+
(C99)
 converts a byte string to an unsigned integer value
(function)
+
(C99)(C99)
 converts a byte string to a floating point value
(function)
+
(C23)(C23)(C23)
 converts a floating point value to a byte string
(function)
Defined in header <inttypes.h>
+
(C99)(C99)
 converts a byte string to intmax_t or uintmax_t
(function)
String manipulation
Defined in header <string.h>
+
(C11)
 copies one string to another
(function)
+
(C11)
 copies a certain amount of characters from one string to another
(function)
+
(C11)
 concatenates two strings
(function)
+
(C11)
 concatenates a certain amount of characters of two strings
(function)
transform a string so that strcmp would produce the same result as strcoll
(function)
+
(C23)
 allocates a copy of a string
(function)
+
(C23)
 allocates a copy of a string of specified size
(function)
String examination
Defined in header <string.h>
+
(C11)
 returns the length of a given string
(function)
compares two strings
(function)
compares a certain amount of characters of two strings
(function)
compares two strings in accordance to the current locale
(function)
finds the first occurrence of a character
(function)
finds the last occurrence of a character
(function)
returns the length of the maximum initial segment that consists
of only the characters found in another byte string
(function)
returns the length of the maximum initial segment that consists
of only the characters not found in another byte string
(function)
finds the first location of any character in one string, in another string
(function)
finds the first occurrence of a substring of characters
(function)
+
(C11)
 finds the next token in a byte string
(function)
Character array manipulation
Defined in header <string.h>
searches an array for the first occurrence of a character
(function)
compares two buffers
(function)
+
(C23)(C11)
 fills a buffer with a character
(function)
+
(C11)
 copies one buffer to another
(function)
+
(C11)
 moves one buffer to another
(function)
+
(C23)
 copies one buffer to another, stopping after the specified delimiter
(function)
Miscellaneous
Defined in header <string.h>
+
(C11)(C11)
 returns a text version of a given error code
(function)

References

See also

+
C++ documentation for Null-terminated byte strings
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/byte +

+
diff --git a/devdocs/c/string%2Fmultibyte%2Fbtowc.html b/devdocs/c/string%2Fmultibyte%2Fbtowc.html new file mode 100644 index 00000000..a30db92f --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fbtowc.html @@ -0,0 +1,57 @@ +

btowc

Defined in header <wchar.h> 
wint_t btowc( int c );
+		 (since C95)

Widens a single-byte character c (reinterpreted as unsigned char) to its wide character equivalent.

+

Most multibyte character encodings use single-byte codes to represent the characters from the ASCII character set. This function may be used to convert such characters to wchar_t.

+

Parameters

+ +
c - single-byte character to widen

Return value

WEOF if c is EOF

+

wide character representation of c if (unsigned char)c is a valid single-byte character in the initial shift state, WEOF otherwise.

+

Example

#include <stdio.h>
+#include <wchar.h>
+#include <locale.h>
+#include <assert.h>
+ 
+void try_widen(unsigned char c)
+{
+    wint_t w = btowc(c);
+    if(w != WEOF)
+        printf("The single-byte character %#x widens to %#x\n", c, w);
+    else
+        printf("The single-byte character %#x failed to widen\n", c);
+}
+ 
+int main(void)
+{
+    char *loc = setlocale(LC_ALL, "lt_LT.iso88594");
+    assert(loc);
+    printf("In Lithuanian ISO-8859-4 locale:\n");
+    try_widen('A');
+    try_widen('\xdf'); // German letter ß (U+00df) in ISO-8859-4
+    try_widen('\xf9'); // Lithuanian letter ų (U+0173) in ISO-8859-4
+ 
+    setlocale(LC_ALL, "lt_LT.utf8");
+    printf("In Lithuanian UTF-8 locale:\n");
+    try_widen('A');
+    try_widen('\xdf');
+    try_widen('\xf9');
+}

Possible output:

+
In Lithuanian ISO-8859-4 locale:
+The single-byte character 0x41 widens to 0x41
+The single-byte character 0xdf widens to 0xdf
+The single-byte character 0xf9 widens to 0x173
+In Lithuanian UTF-8 locale:
+The single-byte character 0x41 widens to 0x41
+The single-byte character 0xdf failed to widen
+The single-byte character 0xf9 failed to widen

References

See also

+ +
+
(C95)
 narrows a wide character to a single-byte narrow character, if possible
(function)
C++ documentation for btowc
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/multibyte/btowc +

+
diff --git a/devdocs/c/string%2Fmultibyte%2Fc16rtomb.html b/devdocs/c/string%2Fmultibyte%2Fc16rtomb.html new file mode 100644 index 00000000..5f1da1ad --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fc16rtomb.html @@ -0,0 +1,67 @@ +

c16rtomb

Defined in header <uchar.h> 
size_t c16rtomb( char* restrict s, char16_t c16, mbstate_t* restrict ps );
+		 (since C11)

Converts a single code point from its variable-length 16-bit wide character representation (typically, UTF-16) to its narrow multibyte character representation.

+

If s is not a null pointer and c16 is the last 16-bit code unit in a valid variable-length encoding of a code point, the function determines the number of bytes necessary to store the multibyte character representation of that code point (including any shift sequences, and taking into account the current multibyte conversion state *ps), and stores the multibyte character representation in the character array whose first element is pointed to by s, updating *ps as necessary. At most MB_CUR_MAX bytes can be written by this function.

+

If s is a null pointer, the call is equivalent to c16rtomb(buf, u'\0', ps) for some internal buffer buf.

+

If c16 is the null wide character u'\0', a null byte is stored, preceded by any shift sequence necessary to restore the initial shift state and the conversion state parameter *ps is updated to represent the initial shift state.

+

If c16 is not the final code unit in a 16-bit representation of a wide character, it does not write to the array pointed to by s, only *ps is updated.

+

If the macro __STDC_UTF_16__ is defined, the 16-bit encoding used by this function is UTF-16; otherwise, it is implementation-defined. The macro is always defined and the encoding is always UTF-16.(since C23) In any case, the multibyte character encoding used by this function is specified by the currently active C locale.

+

Parameters

+ + + +
s - pointer to narrow character array where the multibyte character will be stored
c16 - the 16-bit wide character to convert
ps - pointer to the conversion state object used when interpreting the multibyte string

Return value

On success, returns the number of bytes (including any shift sequences) written to the character array whose first element is pointed to by s. This value may be ​0​, e.g. when processing the leading char16_t units in a multi-char16_t-unit sequence (occurs when processing the leading surrogate in a surrogate pair of UTF-16).

+

On failure (if c16 is not a valid 16-bit code unit), returns -1, stores EILSEQ in errno, and leaves *ps in unspecified state.

+

Notes

In C11 as published, unlike mbrtoc16, which converts variable-width multibyte (such as UTF-8) to variable-width 16-bit (such as UTF-16) encoding, this function can only convert single-unit 16-bit encoding, meaning it cannot convert UTF-16 to UTF-8 despite that being the original intent of this function. This was corrected by the post-C11 defect report DR488.

+

Example

+

Note: this example assumes the fix for the defect report DR488 is applied

+
#include <locale.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <uchar.h>
+ 
+mbstate_t state;
+ 
+int main(void)
+{
+    setlocale(LC_ALL, "en_US.utf8");
+    const char16_t in[] = u"zß水🍌"; // or "z\u00df\u6c34\U0001F34C"
+    const size_t in_sz = sizeof in / sizeof *in;
+ 
+    printf("Processing %zu UTF-16 code units: [ ", in_sz);
+    for (size_t n = 0; n < in_sz; ++n)
+        printf("%#x ", in[n]);
+    puts("]");
+ 
+    char out[MB_CUR_MAX * in_sz];
+    char *p = out;
+    for (size_t n = 0; n < in_sz; ++n)
+    {
+        size_t rc = c16rtomb(p, in[n], &state);
+        if (rc == (size_t)-1)
+            break;
+        p += rc;
+    }
+ 
+    size_t out_sz = p - out;
+    printf("into %zu UTF-8 code units: [ ", out_sz);
+    for (size_t x = 0; x < out_sz; ++x)
+        printf("%#x ", +(unsigned char)out[x]);
+    puts("]");
+}

Output:

+
Processing 6 UTF-16 code units: [ 0x7a 0xdf 0x6c34 0xd83c 0xdf4c 0 ]
+into 11 UTF-8 code units: [ 0x7a 0xc3 0x9f 0xe6 0xb0 0xb4 0xf0 0x9f 0x8d 0x8c 0 ]

References

See also

+ +
+
(C11)
 generates the next 16-bit wide character from a narrow multibyte string
(function)
C++ documentation for c16rtomb
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/multibyte/c16rtomb +

+
diff --git a/devdocs/c/string%2Fmultibyte%2Fc32rtomb.html b/devdocs/c/string%2Fmultibyte%2Fc32rtomb.html new file mode 100644 index 00000000..c6b285c5 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fc32rtomb.html @@ -0,0 +1,60 @@ +

c32rtomb

Defined in header <uchar.h> 
size_t c32rtomb( char* restrict s, char32_t c32, mbstate_t* restrict ps );
+		 (since C11)

Converts a single code point from its variable-length 32-bit wide character representation (but typically, UTF-32) to its narrow multibyte character representation.

+

If s is not a null pointer, the function determines the number of bytes necessary to store the multibyte character representation of c32 (including any shift sequences, and taking into account the current multibyte conversion state *ps), and stores the multibyte character representation in the character array whose first element is pointed to by s, updating *ps as necessary. At most MB_CUR_MAX bytes can be written by this function.

+

If s is a null pointer, the call is equivalent to c32rtomb(buf, U'\0', ps) for some internal buffer buf.

+

If c32 is the null wide character U'\0', a null byte is stored, preceded by any shift sequence necessary to restore the initial shift state and the conversion state parameter *ps is updated to represent the initial shift state.

+

If the macro __STDC_UTF_32__ is defined, the 32-bit encoding used by this function is UTF-32; otherwise, it is implementation-defined. The macro is always defined and the encoding is always UTF-32.(since C23) In any case, the multibyte character encoding used by this function is specified by the currently active C locale.

+

Parameters

+ + + +
s - pointer to narrow character array where the multibyte character will be stored
c32 - the 32-bit wide character to convert
ps - pointer to the conversion state object used when interpreting the multibyte string

Return value

On success, returns the number of bytes (including any shift sequences) written to the character array whose first element is pointed to by s. This value may be ​0​, e.g. when processing the leading char32_t units in a multi-char32_t-unit sequence (does not occur in UTF-32).

+

On failure (if c32 is not a valid 32-bit wide character), returns -1, stores EILSEQ in errno, and leaves *ps in unspecified state.

+

Example

#include <locale.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <uchar.h>
+ 
+mbstate_t state;
+ 
+int main(void)
+{
+    setlocale(LC_ALL, "en_US.utf8");
+    const char32_t in[] = U"zß水🍌"; // or "z\u00df\u6c34\U0001F34C"
+    size_t in_sz = sizeof in / sizeof *in;
+ 
+    printf("Processing %zu UTF-32 code units: [ ", in_sz);
+    for (size_t n = 0; n < in_sz; ++n)
+        printf("%#x ", in[n]);
+    puts("]");
+ 
+    char out[MB_CUR_MAX * in_sz];
+    char* p = out;
+    for (size_t n = 0; n < in_sz; ++n)
+    {
+        size_t rc = c32rtomb(p, in[n], &state);
+        if(rc == (size_t)-1) break;
+        p += rc;
+    }
+ 
+    size_t out_sz = p - out;
+    printf("into %zu UTF-8 code units: [ ", out_sz);
+    for (size_t x = 0; x < out_sz; ++x)
+        printf("%#x ", +(unsigned char)out[x]);
+    puts("]");
+}

Output:

+
Processing 5 UTF-32 code units: [ 0x7a 0xdf 0x6c34 0x1f34c 0 ]
+into 11 UTF-8 code units: [ 0x7a 0xc3 0x9f 0xe6 0xb0 0xb4 0xf0 0x9f 0x8d 0x8c 0 ]

References

See also

+ +
+
(C11)
 generates the next 32-bit wide character from a narrow multibyte string
(function)
C++ documentation for c32rtomb
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/multibyte/c32rtomb +

+
diff --git a/devdocs/c/string%2Fmultibyte%2Fc8rtomb.html b/devdocs/c/string%2Fmultibyte%2Fc8rtomb.html new file mode 100644 index 00000000..3060f056 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fc8rtomb.html @@ -0,0 +1,23 @@ +

c8rtomb

Defined in header <uchar.h> 
size_t c8rtomb( char* restrict s, char8_t c8, mbstate_t* restrict ps );
+		 (since C23)

Converts a single code point from UTF-8 to a narrow multibyte character representation.

+

If s is not a null pointer and c8 is the last code unit in a valid UTF-8 encoding of a code point, the function determines the number of bytes necessary to store the multibyte character representation of that code point (including any shift sequences, and taking into account the current multibyte conversion state *ps), and stores the multibyte character representation in the character array whose first element is pointed to by s, updating *ps as necessary. At most MB_CUR_MAX bytes can be written by this function.

+

If c8 is not the final UTF-8 code unit in a representation of a code point, the function does not write to the array pointed to by s, only *ps is updated.

+

If s is a null pointer, the call is equivalent to c8rtomb(buf, u8'\0', ps) for some internal buffer buf.

+

If c8 is the null character u8'\0', a null byte is stored, preceded by any shift sequence necessary to restore the initial shift state and the conversion state parameter *ps is updated to represent the initial shift state.

+

The multibyte encoding used by this function is specified by the currently active C locale.

+

Parameters

+ + + +
s - pointer to narrow character array where the multibyte character will be stored
c8 - the UTF-8 code unit to convert
ps - pointer to the conversion state object used when interpreting the multibyte string

Return value

The number of bytes stored in the array object (including any shift sequences). This may be zero when c8 is not the final code unit in the UTF-8 representation of a code point.

+

If c8 is invalid (does not contribute to a sequence of char8_t corresponding to a valid multibyte character), the value of the macro EILSEQ is stored in errno, (size_t)-1 is returned, and the conversion state is unspecified.

+

Notes

Calls to c8rtomb with a null pointer argument for s may introduce a data race with other calls to c8rtomb with a null pointer argument for s.

+

Example

See also

+ +
+
(C23)
 converts a narrow multibyte character to UTF-8 encoding
(function)
C++ documentation for c8rtomb
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/multibyte/c8rtomb +

+
diff --git a/devdocs/c/string%2Fmultibyte%2Fchar16_t.html b/devdocs/c/string%2Fmultibyte%2Fchar16_t.html new file mode 100644 index 00000000..b31287af --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fchar16_t.html @@ -0,0 +1,35 @@ +

char16_t

Defined in header <uchar.h> 
typedef uint_least16_t char16_t;
+		 (since C11)

char16_t is an unsigned integer type used for 16-bit wide characters and is the same type as uint_least16_t.

+

Notes

On any given platform, by the definition of uint_least16_t, the width of type char16_t can be greater than 16 bits, but the actual values stored in an object of type char16_t will always have a width of 16 bits.

+

Example

#include <stdio.h>
+#include <uchar.h>
+ 
+int main(void)
+{
+    const char16_t wcs[] = u"zß水🍌"; // or "z\u00df\u6c34\U0001f34c"
+    const size_t wcs_sz = sizeof wcs / sizeof *wcs;
+    printf("%zu UTF-16 code units: [ ", wcs_sz);
+    for (size_t n = 0; n < wcs_sz; ++n)
+        printf("%#x ", wcs[n]);
+    printf("]\n");
+}

Possible output:

+
6 UTF-16 code units: [ 0x7a 0xdf 0x6c34 0xd83c 0xdf4c 0 ]

References

See also

+
C++ documentation for Fundamental types
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/multibyte/char16_t +

+
diff --git a/devdocs/c/string%2Fmultibyte%2Fchar32_t.html b/devdocs/c/string%2Fmultibyte%2Fchar32_t.html new file mode 100644 index 00000000..a6895bb4 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fchar32_t.html @@ -0,0 +1,35 @@ +

char32_t

Defined in header <uchar.h> 
typedef uint_least32_t char32_t;
+		 (since C11)

char32_t is an unsigned integer type used for 32-bit wide characters and is the same type as uint_least32_t.

+

Notes

On any given platform, by the definition of uint_least32_t, the width of type char32_t can be greater than 32 bits, but the actual values stored in an object of type char32_t will always have a width of 32 bits.

+

Example

#include <stdio.h>
+#include <uchar.h>
+ 
+int main(void)
+{
+    const char32_t wc[] = U"zß水🍌"; // or "z\u00df\u6c34\U0001f34c"
+    const size_t wc_sz = sizeof wc / sizeof *wc;
+    printf("%zu UTF-32 code units: [ ", wc_sz);
+    for (size_t n = 0; n < wc_sz; ++n)
+        printf("%#x ", wc[n]);
+    printf("]\n");
+}

Possible output:

+
5 UTF-32 code units: [ 0x7a 0xdf 0x6c34 0x1f34c 0 ]

References

See also

+
C++ documentation for Fundamental types
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/multibyte/char32_t +

+
diff --git a/devdocs/c/string%2Fmultibyte%2Fchar8_t.html b/devdocs/c/string%2Fmultibyte%2Fchar8_t.html new file mode 100644 index 00000000..56ae4d71 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fchar8_t.html @@ -0,0 +1,24 @@ +

char8_t

Defined in header <uchar.h> 
typedef unsigned char char8_t;
+		 (since C23)

char8_t is an unsigned integer type used for UTF-8 and is the same type as unsigned char.

+

Example

#include <uchar.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    char8_t str[] = u8"zß水🍌"; // or "z\u00df\u6c34\U0001f34c"
+    size_t str_sz = sizeof str; // sizeof *str == 1 by definition
+    printf("%zu UTF-8 code units: [ ", str_sz);
+    for (size_t n = 0; n < str_sz; ++n)
+        printf("%02X ", str[n]);
+    printf("]\n");
+}

Possible output:

+
11 UTF-8 code units: [ 7A C3 9F E6 B0 B4 F0 9F 8D 8C 00 ]

References

See also

+
C++ documentation for Fundamental types
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/multibyte/char8_t +

+
diff --git a/devdocs/c/string%2Fmultibyte%2Fmblen.html b/devdocs/c/string%2Fmultibyte%2Fmblen.html new file mode 100644 index 00000000..46facf2a --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fmblen.html @@ -0,0 +1,73 @@ +

mblen

Defined in header <stdlib.h> 
int mblen( const char* s, size_t n );
+

Determines the size, in bytes, of the multibyte character whose first byte is pointed to by s.

+

If s is a null pointer, resets the global conversion state and(until C23) determined whether shift sequences are used.

+

This function is equivalent to the call mbtowc((wchar_t*)0, s, n), except that conversion state of mbtowc is unaffected.

+

Parameters

+ + +
s - pointer to the multibyte character
n - limit on the number of bytes in s that can be examined

Return value

If s is not a null pointer, returns the number of bytes that are contained in the multibyte character or -1 if the first bytes pointed to by s do not form a valid multibyte character or ​0​ if s is pointing at the null charcter '\0'.

+

If s is a null pointer, resets its internal conversion state to represent the initial shift state and(until C23) returns ​0​ if the current multibyte encoding is not state-dependent (does not use shift sequences) or a non-zero value if the current multibyte encoding is state-dependent (uses shift sequences).

+

Notes

+ + + +

Each call to mblen updates the internal global conversion state (a static object of type mbstate_t, only known to this function). If the multibyte encoding uses shift states, care must be taken to avoid backtracking or multiple scans. In any case, multiple threads should not call mblen without synchronization: mbrlen may be used instead.

+		 (until C23)

mblen is not allowed to have an internal state.

+		 (since C23)

Example

#include <locale.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+ 
+// the number of characters in a multibyte string is the sum of mblen()'s
+// note: the simpler approach is mbstowcs(NULL, str, sz)
+size_t strlen_mb(const char* ptr)
+{
+    size_t result = 0;
+    const char* end = ptr + strlen(ptr);
+    mblen(NULL, 0); // reset the conversion state
+    while(ptr < end) {
+        int next = mblen(ptr, end - ptr);
+        if (next == -1) {
+           perror("strlen_mb");
+           break;
+        }
+        ptr += next;
+        ++result;
+    }
+    return result;
+}
+ 
+void dump_bytes(const char* str)
+{
+    for (const char* end = str + strlen(str); str != end; ++str)
+        printf("%02X ", (unsigned char)str[0]);
+    printf("\n");
+}
+ 
+int main(void)
+{
+    setlocale(LC_ALL, "en_US.utf8");
+    const char* str = "z\u00df\u6c34\U0001f34c";
+    printf("The string \"%s\" consists of %zu characters, but %zu bytes: ",
+            str, strlen_mb(str), strlen(str));
+    dump_bytes(str);
+}

Possible output:

+
The string "zß水🍌" consists of 4 characters, but 10 bytes: 7A C3 9F E6 B0 B4 F0 9F 8D 8C

References

See also

+ + +
converts the next multibyte character to wide character
(function)
+
(C95)
 returns the number of bytes in the next multibyte character, given state
(function)
C++ documentation for mblen
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/multibyte/mblen +

+
diff --git a/devdocs/c/string%2Fmultibyte%2Fmbrlen.html b/devdocs/c/string%2Fmultibyte%2Fmbrlen.html new file mode 100644 index 00000000..cf7c2914 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fmbrlen.html @@ -0,0 +1,58 @@ +

mbrlen

Defined in header <wchar.h> 
size_t mbrlen( const char *s, size_t n, mbstate_t *ps );
+		 (since C95)
(until C99) 
size_t mbrlen( const char *restrict s, size_t n, mbstate_t *restrict ps );
+		 (since C99)

Determines the size, in bytes, of the representation of a multibyte character.

+

This function is equivalent to the call mbrtowc(NULL, s, n, ps?ps:&internal) for some hidden object internal of type mbstate_t, except that the expression ps is evaluated only once.

+

Parameters

+ + + +
s - pointer to an element of a multibyte character string
n - limit on the number of bytes in s that can be examined
ps - pointer to the variable holding the conversion state

Return value

The first of the following that applies:

+

Example

#include <locale.h>
+#include <string.h>
+#include <stdio.h>
+#include <wchar.h>
+ 
+int main(void)
+{   
+    // allow mbrlen() to work with UTF-8 multibyte encoding
+    setlocale(LC_ALL, "en_US.utf8");
+    // UTF-8 narrow multibyte encoding
+    const char* str = u8"水";
+    size_t sz = strlen(str);
+ 
+    mbstate_t mb;
+    memset(&mb, 0, sizeof mb);
+    int len1 = mbrlen(str, 1, &mb);
+    if(len1 == -2) 
+        printf("The first 1 byte of %s is an incomplete multibyte char"
+               " (mbrlen returns -2)\n", str);
+ 
+    int len2 = mbrlen(str+1, sz-1, &mb);
+    printf("The remaining %zu  bytes of %s hold %d bytes of the multibyte"
+           " character\n", sz-1, str, len2);
+ 
+    printf("Attempting to call mbrlen() in the middle of %s while in initial"
+           " shift state returns %zd\n", str, mbrlen(str+1, sz-1, &mb));
+}

Output:

+
The first 1 byte of 水 is an incomplete multibyte char (mbrlen returns -2)
+The remaining 2  bytes of 水 hold 2 bytes of the multibyte character
+Attempting to call mbrlen() in the middle of 水 while in initial shift state returns -1

References

See also

+ + +
+
(C95)
 converts the next multibyte character to wide character, given state
(function)
returns the number of bytes in the next multibyte character
(function)
C++ documentation for mbrlen
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/multibyte/mbrlen +

+
diff --git a/devdocs/c/string%2Fmultibyte%2Fmbrtoc16.html b/devdocs/c/string%2Fmultibyte%2Fmbrtoc16.html new file mode 100644 index 00000000..df3061d9 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fmbrtoc16.html @@ -0,0 +1,76 @@ +

mbrtoc16

Defined in header <uchar.h> 
size_t mbrtoc16( char16_t* restrict pc16, const char* restrict s,
+                 size_t n, mbstate_t* restrict ps );
+		 (since C11)

Converts a single code point from its narrow multibyte character representation to its variable-length 16-bit wide character representation (typically, UTF-16).

+

If s is not a null pointer, inspects at most n bytes of the multibyte character string, beginning with the byte pointed to by s to determine the number of bytes necessary to complete the next multibyte character (including any shift sequences, and taking into account the current multibyte conversion state *ps). If the function determines that the next multibyte character in s is complete and valid, converts it to the corresponding 16-bit wide character and stores it in *pc16 (if pc16 is not null).

+

If the multibyte character in *s corresponds to a multi-char16_t sequence (e.g. a surrogate pair in UTF-16), then after the first call to this function, *ps is updated in such a way that the next call to mbrtoc16 will write out the additional char16_t, without considering *s.

+

If s is a null pointer, the values of n and pc16 are ignored and the call is equivalent to mbrtoc16(NULL, "", 1, ps).

+

If the wide character produced is the null character, the conversion state *ps represents the initial shift state.

+

If the macro __STDC_UTF_16__ is defined, the 16-bit encoding used by this function is UTF-16; otherwise, it is implementation-defined. The macro is always defined and the encoding is always UTF-16.(since C23) In any case, the multibyte character encoding used by this function is specified by the currently active C locale.

+

Parameters

+ + + + +
pc16 - pointer to the location where the resulting 16-bit wide character will be written
s - pointer to the multibyte character string used as input
n - limit on the number of bytes in s that can be examined
ps - pointer to the conversion state object used when interpreting the multibyte string

Return value

The first of the following that applies:

+

Example

#include <locale.h>
+#include <stdio.h>
+#include <uchar.h>
+ 
+mbstate_t state;
+ 
+int main(void)
+{
+    setlocale(LC_ALL, "en_US.utf8");
+    const char in[] = u8"zß水🍌"; // or "z\u00df\u6c34\U0001F34C"
+    const size_t in_sz = sizeof in / sizeof *in;
+ 
+    printf("Processing %zu UTF-8 code units: [ ", in_sz);
+    for (size_t n = 0; n < in_sz; ++n)
+        printf("%#x ", (unsigned char)in[n]);
+    puts("]");
+ 
+    char16_t out[in_sz];
+    const char *p_in = in, *end = in + in_sz;
+    char16_t *p_out = out;
+    for (size_t rc; (rc = mbrtoc16(p_out, p_in, end - p_in, &state));)
+    {
+        if (rc == (size_t)-1)     // invalid input
+            break;
+        else if(rc == (size_t)-2) // truncated input
+            break;
+        else if(rc == (size_t)-3) // UTF-16 high surrogate
+            p_out += 1;
+        else
+        {
+            p_in += rc;
+            p_out += 1;
+        };
+    }
+ 
+    const size_t out_sz = p_out - out + 1;
+    printf("into %zu UTF-16 code units: [ ", out_sz);
+    for (size_t x = 0; x < out_sz; ++x)
+        printf("%#x ", out[x]);
+    puts("]");
+}

Output:

+
Processing 11 UTF-8 code units: [ 0x7a 0xc3 0x9f 0xe6 0xb0 0xb4 0xf0 0x9f 0x8d 0x8c 0 ]
+into 6 UTF-16 code units: [ 0x7a 0xdf 0x6c34 0xd83c 0xdf4c 0 ]

References

See also

+ +
+
(C11)
 converts a 16-bit wide character to narrow multibyte string
(function)
C++ documentation for mbrtoc16
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/multibyte/mbrtoc16 +

+
diff --git a/devdocs/c/string%2Fmultibyte%2Fmbrtoc32.html b/devdocs/c/string%2Fmultibyte%2Fmbrtoc32.html new file mode 100644 index 00000000..f67e7de6 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fmbrtoc32.html @@ -0,0 +1,77 @@ +

mbrtoc32

Defined in header <uchar.h> 
size_t mbrtoc32( char32_t restrict * pc32, const char * restrict s,
+                 size_t n, mbstate_t * restrict ps );
+		 (since C11)

Converts a single code point from its narrow multibyte character representation to its variable-length 32-bit wide character representation (but typically, UTF-32).

+

If s is not a null pointer, inspects at most n bytes of the multibyte character string, beginning with the byte pointed to by s to determine the number of bytes necessary to complete the next multibyte character (including any shift sequences, and taking into account the current multibyte conversion state *ps). If the function determines that the next multibyte character in s is complete and valid, converts it to the corresponding 32-bit wide character and stores it in *pc32 (if pc32 is not null).

+

If the multibyte character in *s corresponds to a multi-char32_t sequence (not possible with UTF-32), then after the first call to this function, *ps is updated in such a way that the next calls to mbrtoc32 will write out the additional char32_t, without considering *s.

+

If s is a null pointer, the values of n and pc32 are ignored and the call is equivalent to mbrtoc32(NULL, "", 1, ps).

+

If the wide character produced is the null character, the conversion state *ps represents the initial shift state.

+

If the macro __STDC_UTF_32__ is defined, the 32-bit encoding used by this function is UTF-32; otherwise, it is implementation-defined. The macro is always defined and the encoding is always UTF-32.(since C23) In any case, the multibyte character encoding used by this function is specified by the currently active C locale.

+

Parameters

+ + + + +
pc32 - pointer to the location where the resulting 32-bit wide character will be written
s - pointer to the multibyte character string used as input
n - limit on the number of bytes in s that can be examined
ps - pointer to the conversion state object used when interpreting the multibyte string

Return value

The first of the following that applies:

+

Example

#include <stdio.h>
+#include <locale.h>
+#include <string.h>
+#include <uchar.h>
+#include <assert.h>
+ 
+int main(void)
+{
+    setlocale(LC_ALL, "en_US.utf8");
+    char in[] = u8"zß水🍌"; // or "z\u00df\u6c34\U0001F34C"
+    const size_t in_size = sizeof in / sizeof *in;
+ 
+    printf("Processing %zu UTF-8 code units: [ ", in_size);
+    for (size_t i = 0; i < in_size; ++i)
+        printf("0x%02x ", (unsigned char)in[i]);
+ 
+    puts("]");
+ 
+    char32_t out[in_size];
+    char32_t *p_out = out;
+    char *p_in = in, *end = in + in_size;
+    mbstate_t state;
+    memset(&state, 0, sizeof(state));
+    size_t rc;
+    while ((rc = mbrtoc32(p_out, p_in, end - p_in, &state)))
+    {
+        assert(rc != (size_t)-3); // no surrogate pairs in UTF-32
+        if (rc == (size_t)-1) break; // invalid input
+        if (rc == (size_t)-2) break; // truncated input
+        p_in += rc;
+        ++p_out;
+    }
+ 
+    size_t out_size = p_out+1 - out;
+    printf("into %zu UTF-32 code units: [ ", out_size);
+    for (size_t i = 0; i < out_size; ++i)
+        printf("0x%08X ", out[i]);
+ 
+    puts("]");
+}

Output:

+
Processing 11 UTF-8 code units: [ 0x7a 0xc3 0x9f 0xe6 0xb0 0xb4 0xf0 0x9f 0x8d 0x8c 0x00 ]
+into 5 UTF-32 code units: [ 0x0000007A 0x000000DF 0x00006C34 0x0001F34C 0x00000000 ]

References

See also

+ +
+
(C11)
 converts a 32-bit wide character to narrow multibyte string
(function)
C++ documentation for mbrtoc32
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/multibyte/mbrtoc32 +

+
diff --git a/devdocs/c/string%2Fmultibyte%2Fmbrtoc8.html b/devdocs/c/string%2Fmultibyte%2Fmbrtoc8.html new file mode 100644 index 00000000..826b97a4 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fmbrtoc8.html @@ -0,0 +1,29 @@ +

mbrtoc8

Defined in header <uchar.h> 
size_t mbrtoc8( char8_t * restrict pc8, const char * restrict s,
+                size_t n, mbstate_t * restrict ps );
+		 (since C23)

Converts a narrow multibyte character to UTF-8 encoding.

+

If s is not a null pointer, inspects at most n bytes of the multibyte character string, beginning with the byte pointed to by s to determine the number of bytes necessary to complete the next multibyte character (including any shift sequences). If the function determines that the next multibyte character in s is complete and valid, converts it to UTF-8 and stores the first UTF-8 code unit in *pc8 (if pc8 is not null).

+

If UTF-8 encoding of the multibyte character in *s consists of more than one UTF-8 code unit, then after the first call to this function, *ps is updated in such a way that the next call to mbrtoc8 will write out the additional UTF-8 code units, without considering *s.

+

If s is a null pointer, the values of n and pc8 are ignored and the call is equivalent to mbrtoc8(nullptr, "", 1, ps).

+

If UTF-8 code unit produced is u8'\0', the conversion state *ps represents the initial shift state.

+

The multibyte encoding used by this function is specified by the currently active C locale.

+

Parameters

+ + + + +
pc8 - pointer to the location where the resulting UTF-8 code units will be written
s - pointer to the multibyte character string used as input
n - limit on the number of bytes in s that can be examined
ps - pointer to the conversion state object used when interpreting the multibyte string

Return value

The first of the following that applies:

+

Example

See also

+ +
+
(C23)
 converts UTF-8 string to narrow multibyte encoding
(function)
C++ documentation for mbrtoc8
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/multibyte/mbrtoc8 +

+
diff --git a/devdocs/c/string%2Fmultibyte%2Fmbrtowc.html b/devdocs/c/string%2Fmultibyte%2Fmbrtowc.html new file mode 100644 index 00000000..9f8d4dea --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fmbrtowc.html @@ -0,0 +1,67 @@ +

mbrtowc

Defined in header <wchar.h> 
size_t mbrtowc( wchar_t* pwc, const char* s, size_t n, mbstate_t* ps );
+		 (since C95) 
size_t mbrtowc( wchar_t *restrict pwc, const char *restrict s, size_t n,
+                mbstate_t *restrict ps );
+		 (since C99)

Converts a narrow multibyte character to its wide character representation.

+

If s is not a null pointer, inspects at most n bytes of the multibyte character string, beginning with the byte pointed to by s to determine the number of bytes necessary to complete the next multibyte character (including any shift sequences, and taking into account the current multibyte conversion state *ps). If the function determines that the next multibyte character in s is complete and valid, converts it to the corresponding wide character and stores it in *pwc (if pwc is not null).

+

If s is a null pointer, the values of n and pwc are ignored and call is equivalent to mbrtowc(NULL, "", 1, ps).

+

If the wide character produced is the null character, the conversion state stored in *ps is the initial shift state.

+

If the environment macro __STDC_ISO_10646__ is defined, the values of type wchar_t are the same as the short identifiers of the characters in the Unicode required set (typically UTF-32 encoding); otherwise, it is implementation-defined. In any case, the multibyte character encoding used by this function is specified by the currently active C locale.

+

Parameters

+ + + + +
pwc - pointer to the location where the resulting wide character will be written
s - pointer to the multibyte character string used as input
n - limit on the number of bytes in s that can be examined
ps - pointer to the conversion state used when interpreting the multibyte character string

Return value

The first of the following that applies:

+

Example

#include <stdio.h>
+#include <locale.h>
+#include <string.h>
+#include <wchar.h>
+ 
+int main(void)
+{
+    setlocale(LC_ALL, "en_US.utf8");
+    mbstate_t state;
+    memset(&state, 0, sizeof state);
+    char in[] = u8"z\u00df\u6c34\U0001F34C"; // or u8"zß水🍌"
+    size_t in_sz = sizeof in / sizeof *in;
+ 
+    printf("Processing %zu UTF-8 code units: [ ", in_sz);
+    for(size_t n = 0; n < in_sz; ++n) printf("%#x ", (unsigned char)in[n]);
+    puts("]");
+ 
+    wchar_t out[in_sz];
+    char *p_in = in, *end = in + in_sz;
+    wchar_t *p_out = out;
+    int rc;
+    while((rc = mbrtowc(p_out, p_in, end - p_in, &state)) > 0)
+    {
+        p_in += rc;
+        p_out += 1;
+    }
+ 
+    size_t out_sz = p_out - out + 1;
+    printf("into %zu wchar_t units: [ ", out_sz);
+    for(size_t x = 0; x < out_sz; ++x) printf("%#x ", out[x]);
+    puts("]");
+}

Output:

+
Processing 11 UTF-8 code units: [ 0x7a 0xc3 0x9f 0xe6 0xb0 0xb4 0xf0 0x9f 0x8d 0x8c 0 ]
+into 5 wchar_t units: [ 0x7a 0xdf 0x6c34 0x1f34c 0 ]

References

See also

+ + +
converts the next multibyte character to wide character
(function)
+
(C95)(C11)
 converts a wide character to its multibyte representation, given state
(function)
C++ documentation for mbrtowc
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/multibyte/mbrtowc +

+
diff --git a/devdocs/c/string%2Fmultibyte%2Fmbsinit.html b/devdocs/c/string%2Fmultibyte%2Fmbsinit.html new file mode 100644 index 00000000..0f1c9207 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fmbsinit.html @@ -0,0 +1,50 @@ +

mbsinit

Defined in header <wchar.h> 
int mbsinit( const mbstate_t* ps);
+		 (since C95)

If ps is not a null pointer, the mbsinit function determines whether the pointed-to mbstate_t object describes the initial conversion state.

+

Notes

Although a zero-initialized mbstate_t always represents the initial conversion state, there may be other values of mbstate_t that also represent the initial conversion state.

+

Parameters

+ +
ps - pointer to the mbstate_t object to examine

Return value

​0​ if ps is not a null pointer and does not represent the initial conversion state, nonzero value otherwise.

+

Example

#include <locale.h>
+#include <string.h>
+#include <stdio.h>
+#include <wchar.h>
+ 
+int main(void)
+{
+    // allow mbrlen() to work with UTF-8 multibyte encoding
+    setlocale(LC_ALL, "en_US.utf8");
+    // UTF-8 narrow multibyte encoding
+    const char* str = u8"水"; // or u8"\u6c34" or "\xe6\xb0\xb4"
+    static mbstate_t mb; // zero-initialize
+    (void)mbrlen(&str[0], 1, &mb);
+    if (!mbsinit(&mb)) {
+        printf("After processing the first 1 byte of %s,\n"
+               "the conversion state is not initial\n\n", str);
+    }
+ 
+    (void)mbrlen(&str[1], strlen(str), &mb);
+    if (mbsinit(&mb)) {
+        printf("After processing the remaining 2 bytes of %s,\n"
+               "the conversion state is initial conversion state\n", str);
+    }
+}

Output:

+
After processing the first 1 byte of 水,
+the conversion state is not initial
+ 
+After processing the remaining 2 bytes of 水,
+the conversion state is initial conversion state

References

See also

+ +
+
(C95)
 conversion state information necessary to iterate multibyte character strings
(class)
C++ documentation for mbsinit
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/multibyte/mbsinit +

+
diff --git a/devdocs/c/string%2Fmultibyte%2Fmbsrtowcs.html b/devdocs/c/string%2Fmultibyte%2Fmbsrtowcs.html new file mode 100644 index 00000000..8154ac0a --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fmbsrtowcs.html @@ -0,0 +1,79 @@ +

mbsrtowcs, mbsrtowcs_s

Defined in header <wchar.h>
(1) 
size_t mbsrtowcs( wchar_t* dst, const char** src, size_t len, mbstate_t* ps );
 +(since C95)
(until C99) +		 
size_t mbsrtowcs( wchar_t *restrict dst, const char **restrict src, size_t len,
+                  mbstate_t *restrict ps );
+		 (since C99) 
errno_t mbsrtowcs_s( size_t *restrict retval,
+                     wchar_t *restrict dst, rsize_t dstsz,
+                     const char **restrict src, rsize_t len,
+                     mbstate_t *restrict ps );
+		 (2) (since C11)
1) Converts a null-terminated multibyte character sequence, which begins in the conversion state described by *ps, from the array whose first element is pointed to by *src to its wide character representation. If dst is not null, converted characters are stored in the successive elements of the wchar_t array pointed to by dst. No more than len wide characters are written to the destination array. Each multibyte character is converted as if by a call to mbrtowc. The conversion stops if: 2) Same as (1), except that
+
+
    +
  • retval, ps, src, or *src is a null pointer
    • +
  • dstsz or len is greater than RSIZE_MAX/sizeof(wchar_t) (unless dst is null)
    • +
  • dstsz is not zero (unless dst is null)
    • +
  • There is no null character in the first dstsz multibyte characters in the *src array and len is greater than dstsz (unless dst is null)
    • +
+
As with all bounds-checked functions, mbsrtowcs_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <wchar.h>.
+

Parameters

+ + + + + + +
dst - pointer to wide character array where the results will be stored
src - pointer to pointer to the first element of a null-terminated multibyte string
len - number of wide characters available in the array pointed to by dst
ps - pointer to the conversion state object
dstsz - max number of wide characters that will be written (size of the dst array)
retval - pointer to a size_t object where the result will be stored

Return value

+1) On success, returns the number of wide characters, excluding the terminating L'\0', written to the character array. If dst is a null pointer, returns the number of wide characters that would have been written given unlimited length. On conversion error (if invalid multibyte character was encountered), returns (size_t)-1, stores EILSEQ in errno, and leaves *ps in unspecified state.
+2) zero on success (in which case the number of wide characters excluding terminating zero that were, or would be written to dst, is stored in *retval), non-sero on error. In case of a runtime constraint violation, stores (size_t)-1 in *retval (unless retval is null) and sets dst[0] to L'\0' (unless dst is null or dstmax is zero or greater than RSIZE_MAX)

Example

#include <stdio.h>
+#include <locale.h>
+#include <wchar.h>
+#include <string.h>
+ 
+void print_as_wide(const char* mbstr)
+{
+    mbstate_t state;
+    memset(&state, 0, sizeof state);
+    size_t len = 1 + mbsrtowcs(NULL, &mbstr, 0, &state);
+    wchar_t wstr[len];
+    mbsrtowcs(&wstr[0], &mbstr, len, &state);
+    wprintf(L"Wide string: %ls \n", wstr);
+    wprintf(L"The length, including L'\\0': %zu\n", len);
+}
+ 
+int main(void)
+{
+    setlocale(LC_ALL, "en_US.utf8");
+    print_as_wide(u8"z\u00df\u6c34\U0001f34c"); // u8"zß水🍌"
+}

Output:

+
Wide string: zß水🍌
+The length, including L'\0': 5

References

See also

+ + + +
+
(C11)
 converts a narrow multibyte character string to wide string
(function)
+
(C95)
 converts the next multibyte character to wide character, given state
(function)
+
(C95)(C11)
 converts a wide string to narrow multibyte character string, given state
(function)
C++ documentation for mbsrtowcs
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/multibyte/mbsrtowcs +

+
diff --git a/devdocs/c/string%2Fmultibyte%2Fmbstate_t.html b/devdocs/c/string%2Fmultibyte%2Fmbstate_t.html new file mode 100644 index 00000000..bed230ed --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fmbstate_t.html @@ -0,0 +1,18 @@ +

mbstate_t

Defined in header <uchar.h> (since C11)
Defined in header <wchar.h> 
struct mbstate_t;
+		 (since C95)

The type mbstate_t is a trivial non-array type that can represent any of the conversion states that can occur in an implementation-defined set of supported multibyte character encoding rules. Zero-initialized value of mbstate_t represents the initial conversion state, although other values of mbstate_t may exist that also represent the initial conversion state.

+

Possible implementation of mbstate_t is a struct type holding an array representing the incomplete multibyte character, an integer counter indicating the number of bytes in the array that have been processed, and a representation of the current shift state.

+

The following functions should not be called from multiple threads without synchronization with the mbstate_t* argument of a null pointer due to possible data races: mbrlen, mbrtowc, mbsrtowcs, mbtowc, wcrtomb, wcsrtombs, wctomb.

+

References

See also

+ +
+
(C95)
 checks if the mbstate_t object represents initial shift state
(function)
C++ documentation for mbstate_t
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/multibyte/mbstate_t +

+
diff --git a/devdocs/c/string%2Fmultibyte%2Fmbstowcs.html b/devdocs/c/string%2Fmultibyte%2Fmbstowcs.html new file mode 100644 index 00000000..80b28999 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fmbstowcs.html @@ -0,0 +1,78 @@ +

mbstowcs, mbstowcs_s

Defined in header <stdlib.h>
(1) 
size_t mbstowcs( wchar_t          *dst, const char          *src, size_t len)
+		 (until C99) 
size_t mbstowcs( wchar_t *restrict dst, const char *restrict src, size_t len)
+		 (since C99) 
errno_t mbstowcs_s(size_t *restrict retval, wchar_t *restrict dst,
+                  rsize_t dstsz, const char *restrict src, rsize_t len);
+		 (2) (since C11)
+1) Converts a multibyte character string from the array whose first element is pointed to by src to its wide character representation. Converted characters are stored in the successive elements of the array pointed to by dst. No more than len wide characters are written to the destination array.
+ Each character is converted as if by a call to mbtowc, except that the mbtowc conversion state is unaffected. The conversion stops if:
+ * The multibyte null character was converted and stored.
+ * An invalid (in the current C locale) multibyte character was encountered.
+ * The next wide character to be stored would exceed len.
+ If src and dst overlap, the behavior is undefined
+2) Same as (1), except that
+ * conversion is as-if by mbrtowc, not mbtowc +
+ * the function returns its result as an out-parameter retval +
+ * if no null character was written to dst after len wide characters were written, then L'\0' is stored in dst[len], which means len+1 total wide characters are written
+ * if dst is a null pointer, the number of wide characters that would be produced is stored in *retval +
+ * the function clobbers the destination array from the terminating null and until dstsz +
+ * If src and dst overlap, the behavior is unspecified.
+ * the following errors are detected at runtime and call the currently installed constraint handler function:
+
+
    +
  • retval or src is a null pointer
    • +
  • dstsz or len is greater than RSIZE_MAX/sizeof(wchar_t) (unless dst is null)
    • +
  • dstsz is not zero (unless dst is null)
    • +
  • There is no null character in the first dstsz multibyte characters in the src array and len is greater than dstsz (unless dst is null)
    • +
+
As with all bounds-checked functions, mbstowcs_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <stdlib.h>.
+
+

Notes

In most implementations, mbstowcs updates a global static object of type mbstate_t as it processes through the string, and cannot be called simultaneously by two threads, mbsrtowcs should be used in such cases.

+

POSIX specifies a common extension: if dst is a null pointer, this function returns the number of wide characters that would be written to dst, if converted. Similar behavior is standard for mbstowcs_s and for mbsrtowcs.

+

Parameters

+ + + + + +
dst - pointer to wide character array where the wide string will be stored
src - pointer to the first element of a null-terminated multibyte string to convert
len - number of wide characters available in the array pointed to by dst
dstsz - max number of wide characters that will be written (size of the dst array)
retval - pointer to a size_t object where the result will be stored

Return value

+1) On success, returns the number of wide characters, excluding the terminating L'\0', written to the destination array. On conversion error (if invalid multibyte character was encountered), returns (size_t)-1.
+2) zero on success (in which case the number of wide characters excluding terminating zero that were, or would be written to dst, is stored in *retval), non-zero on error. In case of a runtime constraint violation, stores (size_t)-1 in *retval (unless retval is null) and sets dst[0] to L'\0' (unless dst is null or dstmax is zero or greater than RSIZE_MAX)

Example

#include <stdio.h>
+#include <locale.h>
+#include <stdlib.h>
+#include <wchar.h>
+ 
+int main(void)
+{
+    setlocale(LC_ALL, "en_US.utf8");
+    const char* mbstr = u8"z\u00df\u6c34\U0001F34C"; // or u8"zß水🍌"
+    wchar_t wstr[5];
+    mbstowcs(wstr, mbstr, 5);
+    wprintf(L"MB string: %s\n", mbstr);
+    wprintf(L"Wide string: %ls\n", wstr);
+}

Output:

+
MB string: zß水🍌
+Wide string: zß水🍌

References

See also

+ + +
+
(C95)(C11)
 converts a narrow multibyte character string to wide string, given state
(function)
+
(C11)
 converts a wide string to narrow multibyte character string
(function)
C++ documentation for mbstowcs
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/multibyte/mbstowcs +

+
diff --git a/devdocs/c/string%2Fmultibyte%2Fmbtowc.html b/devdocs/c/string%2Fmultibyte%2Fmbtowc.html new file mode 100644 index 00000000..7eed6100 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fmbtowc.html @@ -0,0 +1,56 @@ +

mbtowc

Defined in header <stdlib.h> 
int mbtowc( wchar_t          *pwc, const char          *s, size_t n )
+		 (until C99) 
int mbtowc( wchar_t *restrict pwc, const char *restrict s, size_t n )
+		 (since C99)

Converts a multibyte character whose first byte is pointed to by s to a wide character, written to *pwc if pwc is not null.

+

If s is a null pointer, resets the global conversion state and determines whether shift sequences are used.

+

Notes

Each call to mbtowc updates the internal global conversion state (a static object of type mbstate_t, known only to this function). If the multibyte encoding uses shift states, care must be taken to avoid backtracking or multiple scans. In any case, multiple threads should not call mbtowc without synchronization: mbrtowc may be used instead.

+

Parameters

+ + + +
pwc - pointer to the wide character for output
s - pointer to the multibyte character
n - limit on the number of bytes in s that can be examined

Return value

If s is not a null pointer, returns the number of bytes that are contained in the multibyte character or -1 if the first bytes pointed to by s do not form a valid multibyte character or ​0​ if s is pointing at the null character '\0'.

+

If s is a null pointer, resets its internal conversion state to represent the initial shift state and returns ​0​ if the current multibyte encoding is not state-dependent (does not use shift sequences) or a non-zero value if the current multibyte encoding is state-dependent (uses shift sequences).

+

Example

#include <locale.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <wchar.h>
+ 
+// print multibyte string to wide-oriented stdout
+// equivalent to wprintf(L"%s\n", ptr);
+void print_mb(const char* ptr)
+{
+    mbtowc(NULL, 0, 0); // reset the conversion state
+    const char* end = ptr + strlen(ptr);
+    int ret = 0;
+    for (wchar_t wc; (ret = mbtowc(&wc, ptr, end - ptr)) > 0; ptr += ret)
+        wprintf(L"%lc", wc);
+    wprintf(L"\n");
+}
+ 
+int main(void)
+{
+    setlocale(LC_ALL, "en_US.utf8");
+    // UTF-8 narrow multibyte encoding
+    print_mb(u8"z\u00df\u6c34\U0001F34C"); // or u8"zß水🍌"
+}

Output:

+
zß水🍌

References

See also

+ + +
+
(C95)
 converts the next multibyte character to wide character, given state
(function)
returns the number of bytes in the next multibyte character
(function)
C++ documentation for mbtowc
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/multibyte/mbtowc +

+
diff --git a/devdocs/c/string%2Fmultibyte%2Fwcrtomb.html b/devdocs/c/string%2Fmultibyte%2Fwcrtomb.html new file mode 100644 index 00000000..1addcb02 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fwcrtomb.html @@ -0,0 +1,84 @@ +

wcrtomb, wcrtomb_s

Defined in header <wchar.h>
(1) 
size_t wcrtomb( char *s, wchar_t wc, mbstate_t *ps);
+		 (since C95) 
size_t wcrtomb( char *restrict s, wchar_t wc, mbstate_t *restrict ps);
+		 (since C99) 
errno_t wcrtomb_s(size_t *restrict retval, char *restrict s, rsize_t ssz,
+                  wchar_t wc, mbstate_t *restrict ps);
+		 (2) (since C11)

Converts a wide character to its narrow multibyte representation.

+
+1) If s is not a null pointer, the function determines the number of bytes necessary to store the multibyte character representation of wc (including any shift sequences, and taking into account the current multibyte conversion state *ps), and stores the multibyte character representation in the character array whose first element is pointed to by s, updating *ps as necessary. At most MB_CUR_MAX bytes can be written by this function.
+ If s is a null pointer, the call is equivalent to wcrtomb(buf, L'\0', ps) for some internal buffer buf.
+ If wc is the null wide character L'\0', a null byte is stored, preceded by any shift sequence necessary to restore the initial shift state and the conversion state parameter *ps is updated to represent the initial shift state.
+ If the environment macro __STDC_ISO_10646__ is defined, the values of type wchar_t are the same as the short identifiers of the characters in the Unicode required set (typically UTF-32 encoding); otherwise, it is implementation-defined. In any case, the multibyte character encoding used by this function is specified by the currently active C locale.
+2) Same as (1), except that
+ if s is a null pointer, the call is equivalent to wcrtomb_s(&retval, buf, sizeof buf, L'\0', ps) with internal variables retval and buf (whose size is greater than MB_CUR_MAX)
+ the result is returned in the out-parameter retval +
+ the following errors are detected at runtime and call the currently installed constraint handler function:
+
+
    +
  • retval or ps is a null pointer.
    • +
  • ssz is zero or greater than RSIZE_MAX (unless s is null)
    • +
  • ssz is less than the number of bytes that would be written (unless s is null)
    • +
  • s is a null pointer but ssz is not zero
    • +
+
As with all bounds-checked functions, wcrtomb_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <wchar.h>.
+
+

Parameters

+ + + + + +
s - pointer to narrow character array where the multibyte character will be stored
wc - the wide character to convert
ps - pointer to the conversion state object used when interpreting the multibyte string
ssz - max number of bytes to write (the size of the buffer s)
retval - pointer to an out-parameter where the result (number of bytes in the multibyte string including any shift sequences) will be stored

Return value

+1) On success, returns the number of bytes (including any shift sequences) written to the character array whose first element is pointed to by s.
+ On failure (if wc is not a valid wide character), returns (size_t)-1, stores EILSEQ in errno, and leaves *ps in unspecified state.
+2) Returns zero on success and non-zero on failure, in which case, s[0] is set to '\0' (unless s is null or ssz is zero or greater than RSIZE_MAX) and *retval is set to (size_t)-1 (unless retval is null)

Example

#include <stdio.h>
+#include <locale.h>
+#include <string.h>
+#include <wchar.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    setlocale(LC_ALL, "en_US.utf8");
+    mbstate_t state;
+    memset(&state, 0, sizeof state);
+    wchar_t in[] = L"zß水🍌"; // or "z\u00df\u6c34\U0001F34C"
+    size_t in_sz = sizeof in / sizeof *in;
+ 
+    printf("Processing %zu wchar_t units: [ ", in_sz);
+    for(size_t n = 0; n < in_sz; ++n) printf("%#x ", (unsigned int)in[n]);
+    puts("]");
+ 
+    char out[MB_CUR_MAX * in_sz];
+    char *p = out;
+    for(size_t n = 0; n < in_sz; ++n) {
+        int rc = wcrtomb(p, in[n], &state); 
+        if(rc == -1) break;
+        p += rc;
+    }
+ 
+    size_t out_sz = p - out;
+    printf("into %zu UTF-8 code units: [ ", out_sz);
+    for(size_t x = 0; x < out_sz; ++x) printf("%#x ", +(unsigned char)out[x]);
+    puts("]");
+}

Output:

+
Processing 5 wchar_t units: [ 0x7a 0xdf 0x6c34 0x1f34c 0 ]
+into 11 UTF-8 code units: [ 0x7a 0xc3 0x9f 0xe6 0xb0 0xb4 0xf0 0x9f 0x8d 0x8c 0 ]

References

See also

+ + +
+
(C11)
 converts a wide character to its multibyte representation
(function)
+
(C95)
 converts the next multibyte character to wide character, given state
(function)
C++ documentation for wcrtomb
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/multibyte/wcrtomb +

+
diff --git a/devdocs/c/string%2Fmultibyte%2Fwcsrtombs.html b/devdocs/c/string%2Fmultibyte%2Fwcsrtombs.html new file mode 100644 index 00000000..fd435f8a --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fwcsrtombs.html @@ -0,0 +1,83 @@ +

wcsrtombs, wcsrtombs_s

Defined in header <wchar.h>
(1) 
size_t wcsrtombs( char *dst, const wchar_t **src, size_t len, mbstate_t* ps );
 +(since C95)
(until C99) +		 
size_t wcsrtombs( char *restrict dst, const wchar_t **restrict src, size_t len,
+                  mbstate_t *restrict ps );
+		 (since C99) 
errno_t wcsrtombs_s( size_t *restrict retval, char *restrict dst, rsize_t dstsz,
+                     const wchar_t **restrict src, rsize_t len,
+                     mbstate_t *restrict ps );
+		 (2) (since C11)
1) Converts a sequence of wide characters from the array whose first element is pointed to by *src to its narrow multibyte representation that begins in the conversion state described by *ps. If dst is not null, converted characters are stored in the successive elements of the char array pointed to by dst. No more than len bytes are written to the destination array. Each character is converted as if by a call to wcrtomb. The conversion stops if: 2) Same as (1), except that
+
+
    +
  • retval, ps, src, or *src is a null pointer
    • +
  • dstsz or len is greater than RSIZE_MAX (unless dst is null)
    • +
  • dstsz is not zero (unless dst is null)
    • +
  • len is greater than dstsz and the conversion does not encounter null or encoding error in the src array by the time dstsz is reached (unless dst is null)
    • +
+
As with all bounds-checked functions, wcsrtombs_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <wchar.h>.
+

Parameters

+ + + + + + +
dst - pointer to narrow character array where the multibyte characters will be stored
src - pointer to pointer to the first element of a null-terminated wide string
len - number of bytes available in the array pointed to by dst
ps - pointer to the conversion state object
dstsz - max number of bytes that will be written (size of the dst array)
retval - pointer to a size_t object where the result will be stored

Return value

+1) On success, returns the number of bytes (including any shift sequences, but excluding the terminating '\0') written to the character array whose first element is pointed to by dst. If dst is a null pointer, returns the number of bytes that would have been written. On conversion error (if invalid wide character was encountered), returns (size_t)-1, stores EILSEQ in errno, and leaves *ps in unspecified state.
+2) Returns zero on success (in which case the number of bytes excluding terminating zero that were, or would be written to dst, is stored in *retval), non-zero on error. In case of a runtime constraint violation, stores (size_t)-1 in *retval (unless retval is null) and sets dst[0] to '\0' (unless dst is null or dstmax is zero or greater than RSIZE_MAX)

Example

#include <stdio.h>
+#include <locale.h>
+#include <string.h>
+#include <wchar.h>
+ 
+void print_wide(const wchar_t* wstr)
+{
+    mbstate_t state;
+    memset(&state, 0, sizeof state);
+    size_t len = 1 + wcsrtombs(NULL, &wstr, 0, &state);
+    char mbstr[len];
+    wcsrtombs(mbstr, &wstr, len, &state);
+    printf("Multibyte string: %s\n", mbstr);
+    printf("Length, including '\\0': %zu\n", len);
+}
+ 
+int main(void)
+{
+    setlocale(LC_ALL, "en_US.utf8");
+    print_wide(L"z\u00df\u6c34\U0001f34c"); // or L"zß水🍌"
+}

Output:

+
Multibyte string: zß水🍌
+Length, including '\0': 11

References

See also

+ + + +
+
(C11)
 converts a wide string to narrow multibyte character string
(function)
+
(C95)(C11)
 converts a wide character to its multibyte representation, given state
(function)
+
(C95)(C11)
 converts a narrow multibyte character string to wide string, given state
(function)
C++ documentation for wcsrtombs
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/multibyte/wcsrtombs +

+
diff --git a/devdocs/c/string%2Fmultibyte%2Fwcstombs.html b/devdocs/c/string%2Fmultibyte%2Fwcstombs.html new file mode 100644 index 00000000..ae8b6652 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fwcstombs.html @@ -0,0 +1,104 @@ +

wcstombs, wcstombs_s

Defined in header <stdlib.h>
(1) 
size_t wcstombs( char          *dst, const wchar_t          *src, size_t len );
+		 (until C99) 
size_t wcstombs( char *restrict dst, const wchar_t *restrict src, size_t len );
+		 (since C99) 
errno_t wcstombs_s( size_t *restrict retval, char *restrict dst, rsize_t dstsz,
+                    const wchar_t *restrict src, rsize_t len );
+		 (2) (since C11)
+1) Converts a sequence of wide characters from the array whose first element is pointed to by src to its narrow multibyte representation that begins in the initial shift state. Converted characters are stored in the successive elements of the char array pointed to by dst. No more than len bytes are written to the destination array.
+ Each character is converted as if by a call to wctomb, except that the wctomb's conversion state is unaffected. The conversion stops if:
+ * The null character L'\0' was converted and stored. The bytes stored in this case are the unshift sequence (if necessary) followed by '\0',
+ * A wchar_t was found that does not correspond to a valid character in the current C locale.
+ * The next multibyte character to be stored would exceed len.
+ If src and dst overlap, the behavior is unspecified.
+2) Same as (1), except that
+ * conversion is as-if by wcrtomb, not wctomb +
+ * the function returns its result as an out-parameter retval +
+ * if the conversion stops without writing a null character, the function will store '\0' in the next byte in dst, which may be dst[len] or dst[dstsz], whichever comes first (meaning up to len+1/dstsz+1 total bytes may be written). In this case, there may be no unshift sequence written before the terminating null.
+ * if dst is a null pointer, the number of bytes that would be produced is stored in *retval +
+ * the function clobbers the destination array from the terminating null and until dstsz +
+ * If src and dst overlap, the behavior is unspecified.
+ * the following errors are detected at runtime and call the currently installed constraint handler function:
+
+
    +
  • retval or src is a null pointer
    • +
  • dstsz or len is greater than RSIZE_MAX (unless dst is null)
    • +
  • dstsz is not zero (unless dst is null)
    • +
  • len is greater than dstsz and the conversion does not encounter null or encoding error in the src array by the time dstsz is reached (unless dst is null)
    • +
+
As with all bounds-checked functions, wcstombs_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <stdlib.h>.
+
+

Notes

In most implementations, wcstombs updates a global static object of type mbstate_t as it processes through the string, and cannot be called simultaneously by two threads, wcsrtombs or wcstombs_s should be used in such cases.

+

POSIX specifies a common extension: if dst is a null pointer, this function returns the number of bytes that would be written to dst, if converted. Similar behavior is standard for wcsrtombs and wcstombs_s.

+

Parameters

+ + + + + +
dst - pointer to narrow character array where the multibyte character will be stored
src - pointer to the first element of a null-terminated wide string to convert
len - number of bytes available in the array pointed to by dst
dstsz - max number of bytes that will be written (size of the dst array)
retval - pointer to a size_t object where the result will be stored

Return value

+1) On success, returns the number of bytes (including any shift sequences, but excluding the terminating '\0') written to the character array whose first element is pointed to by dst. On conversion error (if invalid wide character was encountered), returns (size_t)-1.
+2) Returns zero on success (in which case the number of bytes excluding terminating zero that were, or would be written to dst, is stored in *retval), non-zero on error. In case of a runtime constraint violation, stores (size_t)-1 in *retval (unless retval is null) and sets dst[0] to '\0' (unless dst is null or dstmax is zero or greater than RSIZE_MAX)

Example

#include <stdio.h>
+#include <stdlib.h>
+#include <locale.h>
+ 
+int main(void)
+{
+    // 4 wide characters
+    const wchar_t src[] = L"z\u00df\u6c34\U0001f34c";
+    // they occupy 10 bytes in UTF-8
+    char dst[11];
+ 
+    setlocale(LC_ALL, "en_US.utf8");
+    printf("wide-character string: '%ls'\n",src);
+    for (size_t ndx=0; ndx < sizeof src/sizeof src[0]; ++ndx)
+        printf("   src[%2zu] = %#8x\n", ndx, src[ndx]);
+ 
+    int rtn_val = wcstombs(dst, src, sizeof dst);
+    printf("rtn_val = %d\n", rtn_val);
+    if (rtn_val > 0)
+        printf("multibyte string:  '%s'\n",dst);
+    for (size_t ndx=0; ndx<sizeof dst; ++ndx)
+        printf("   dst[%2zu] = %#2x\n", ndx, (unsigned char)dst[ndx]);
+}

Output:

+
wide-character string: 'zß水🍌'
+   src[ 0] =     0x7a
+   src[ 1] =     0xdf
+   src[ 2] =   0x6c34
+   src[ 3] =  0x1f34c
+   src[ 4] =        0
+rtn_val = 10
+multibyte string:  'zß水🍌'
+   dst[ 0] = 0x7a
+   dst[ 1] = 0xc3
+   dst[ 2] = 0x9f
+   dst[ 3] = 0xe6
+   dst[ 4] = 0xb0
+   dst[ 5] = 0xb4
+   dst[ 6] = 0xf0
+   dst[ 7] = 0x9f
+   dst[ 8] = 0x8d
+   dst[ 9] = 0x8c
+   dst[10] =  0

References

See also

+ + +
+
(C95)(C11)
 converts a wide string to narrow multibyte character string, given state
(function)
+
(C11)
 converts a narrow multibyte character string to wide string
(function)
C++ documentation for wcstombs
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/multibyte/wcstombs +

+
diff --git a/devdocs/c/string%2Fmultibyte%2Fwctob.html b/devdocs/c/string%2Fmultibyte%2Fwctob.html new file mode 100644 index 00000000..c942d365 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fwctob.html @@ -0,0 +1,54 @@ +

wctob

Defined in header <wchar.h> 
int wctob( wint_t c );
+		 (since C95)

Narrows a wide character c if its multibyte character equivalent in the initial shift state is a single byte.

+

This is typically possible for the characters from the ASCII character set, since most multibyte encodings (such as UTF-8) use single bytes to encode those characters.

+

Parameters

+ +
c - wide character to narrow

Return value

EOF if c does not represent a multibyte character with length 1 in initial shift state.

+

otherwise, the single-byte representation of c as unsigned char converted to int

+

Example

#include <locale.h>
+#include <wchar.h>
+#include <stdio.h>
+#include <assert.h>
+ 
+void try_narrowing(wchar_t c)
+{
+    int cn = wctob(c);
+    if(cn != EOF)
+        printf("%#x narrowed to %#x\n", c, cn);
+    else
+        printf("%#x could not be narrowed\n", c);
+}
+ 
+int main(void)
+{
+    char* utf_locale_present = setlocale(LC_ALL, "th_TH.utf8");
+    assert(utf_locale_present);
+    puts("In Thai UTF-8 locale:");
+    try_narrowing(L'a');
+    try_narrowing(L'๛');
+ 
+    char* tis_locale_present = setlocale(LC_ALL, "th_TH.tis620");
+    assert(tis_locale_present);
+    puts("In Thai TIS-620 locale:");
+    try_narrowing(L'a');
+    try_narrowing(L'๛');
+}

Possible output:

+
In Thai UTF-8 locale:
+0x61 narrowed to 0x61
+0xe5b could not be narrowed
+In Thai TIS-620 locale:
+0x61 narrowed to 0x61
+0xe5b narrowed to 0xfb

References

See also

+ +
+
(C95)
 widens a single-byte narrow character to wide character, if possible
(function)
C++ documentation for wctob
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/multibyte/wctob +

+
diff --git a/devdocs/c/string%2Fmultibyte%2Fwctomb.html b/devdocs/c/string%2Fmultibyte%2Fwctomb.html new file mode 100644 index 00000000..0c17d262 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fwctomb.html @@ -0,0 +1,82 @@ +

wctomb, wctomb_s

Defined in header <stdlib.h> 
int wctomb( char *s, wchar_t wc );
+		 (1) 
errno_t wctomb_s( int *restrict status, char *restrict s, rsize_t ssz, wchar_t wc );
+		 (2) (since C11)
+1) Converts a wide character wc to multibyte encoding and stores it (including any shift sequences) in the char array whose first element is pointed to by s. No more than MB_CUR_MAX characters are stored. The conversion is affected by the current locale's LC_CTYPE category.
+ If wc is the null character, the null byte is written to s, preceded by any shift sequences necessary to restore the initial shift state.
+ If s is a null pointer, this function resets the global conversion state and determines whether shift sequences are used.
+2) Same as (1), except that the result is returned in the out-parameter status and the following errors are detected at runtime and call the currently installed constraint handler function:
+
+
    +
  • ssz is less than the number of bytes that would be written (unless s is null)
    • +
  • ssz is greater than RSIZE_MAX (unless s is null)
    • +
  • s is a null pointer but ssz is not zero
    • +
+
As with all bounds-checked functions, wctomb_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <stdlib.h>.
+
+

Notes

Each call to wctomb updates the internal global conversion state (a static object of type mbstate_t, known only to this function). If the multibyte encoding uses shift states, this function is not reentrant. In any case, multiple threads should not call wctomb without synchronization: wcrtomb or wctomb_s may be used instead.

+

Unlike most bounds-checked functions, wctomb_s does not null-terminate its output, because it is designed to be used in loops that process strings character-by-character.

+

Parameters

+ + + + +
s - pointer to the character array for output
wc - wide character to convert
ssz - maximum number of bytes to write to s (size of the array s)
status - pointer to an out-parameter where the result (length of the multibyte sequence or the shift sequence status) will be stored

Return value

+1) If s is not a null pointer, returns the number of bytes that are contained in the multibyte representation of wc or -1 if wc is not a valid character.
+ If s is a null pointer, resets its internal conversion state to represent the initial shift state and returns ​0​ if the current multibyte encoding is not state-dependent (does not use shift sequences) or a non-zero value if the current multibyte encoding is state-dependent (uses shift sequences).
+2) zero on success, in which case the multibyte representation of wc is stored in s and its length is stored in *status, or, if s is null, the shift sequence status is stored in status). Non-zero on encoding error or runtime constraint violation, in which case (size_t)-1 is stored in *status. The value stored in *status never exceeds MB_CUR_MAX +

Example

#include <stdio.h>
+#include <stdlib.h>
+#include <locale.h>
+ 
+void demo(wchar_t wc)
+{
+    const char* dep = wctomb(NULL, wc) ? "Yes" : "No";
+    printf("State-dependent encoding? %s.\n", dep);
+ 
+    char mb[MB_CUR_MAX];
+    int len = wctomb(mb, wc);
+    printf("wide char '%lc' -> multibyte char [", wc);
+    for (int idx = 0; idx < len; ++idx)
+        printf("%s%#2x", idx ? " " : "", (unsigned char)mb[idx]);
+    printf("]\n");
+}
+ 
+int main(void)
+{
+    setlocale(LC_ALL, "en_US.utf8");
+    printf("MB_CUR_MAX = %zu\n", MB_CUR_MAX);
+    demo(L'A');
+    demo(L'\u00df');
+    demo(L'\U0001d10b');
+}

Possible output:

+
MB_CUR_MAX = 6
+State-dependent encoding? No.
+wide char 'A' -> multibyte char [0x41]
+State-dependent encoding? No.
+wide char 'ß' -> multibyte char [0xc3 0x9f]
+State-dependent encoding? No.
+wide char '𝄋' -> multibyte char [0xf0 0x9d 0x84 0x8b]

References

See also

+ + +
converts the next multibyte character to wide character
(function)
+
(C95)(C11)
 converts a wide character to its multibyte representation, given state
(function)
C++ documentation for wctomb
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/multibyte/wctomb +

+
diff --git a/devdocs/c/string%2Fmultibyte.html b/devdocs/c/string%2Fmultibyte.html new file mode 100644 index 00000000..554581e6 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte.html @@ -0,0 +1,90 @@ +

Null-terminated multibyte strings

A null-terminated multibyte string (NTMBS), or "multibyte string", is a sequence of nonzero bytes followed by a byte with value zero (the terminating null character).

+

Each character stored in the string may occupy more than one byte. The encoding used to represent characters in a multibyte character string is locale-specific: it may be UTF-8, GB18030, EUC-JP, Shift-JIS, etc. For example, the char array {'\xe4','\xbd','\xa0','\xe5','\xa5','\xbd','\0'} is an NTMBS holding the string "你好" in UTF-8 multibyte encoding: the first three bytes encode the character 你, the next three bytes encode the character 好. The same string encoded in GB18030 is the char array {'\xc4', '\xe3', '\xba', '\xc3', '\0'}, where each of the two characters is encoded as a two-byte sequence.

+

In some multibyte encodings, any given multibyte character sequence may represent different characters depending on the previous byte sequences, known as "shift sequences". Such encodings are known as state-dependent: knowledge of the current shift state is required to interpret each character. An NTMBS is only valid if it begins and ends in the initial shift state: if a shift sequence was used, the corresponding unshift sequence has to be present before the terminating null character. Examples of such encodings are BOCU-1 and SCSU.

+

A multibyte character string is layout-compatible with null-terminated byte string (NTBS), that is, can be stored, copied, and examined using the same facilities, except for calculating the number of characters. If the correct locale is in effect, I/O functions also handle multibyte strings. Multibyte strings can be converted to and from wide strings using the following locale-dependent conversion functions:

+

Multibyte/wide character conversions

+ + + + + + + + + + + + + + + + + + + + + +
Defined in header <stdlib.h>
returns the number of bytes in the next multibyte character
(function)
converts the next multibyte character to wide character
(function)
+
(C11)
 converts a wide character to its multibyte representation
(function)
+
(C11)
 converts a narrow multibyte character string to wide string
(function)
+
(C11)
 converts a wide string to narrow multibyte character string
(function)
Defined in header <wchar.h>
+
(C95)
 checks if the mbstate_t object represents initial shift state
(function)
+
(C95)
 widens a single-byte narrow character to wide character, if possible
(function)
+
(C95)
 narrows a wide character to a single-byte narrow character, if possible
(function)
+
(C95)
 returns the number of bytes in the next multibyte character, given state
(function)
+
(C95)
 converts the next multibyte character to wide character, given state
(function)
+
(C95)(C11)
 converts a wide character to its multibyte representation, given state
(function)
+
(C95)(C11)
 converts a narrow multibyte character string to wide string, given state
(function)
+
(C95)(C11)
 converts a wide string to narrow multibyte character string, given state
(function)
Defined in header <uchar.h>
+
(C23)
 converts a narrow multibyte character to UTF-8 encoding
(function)
+
(C23)
 converts UTF-8 string to narrow multibyte encoding
(function)
+
(C11)
 generates the next 16-bit wide character from a narrow multibyte string
(function)
+
(C11)
 converts a 16-bit wide character to narrow multibyte string
(function)
+
(C11)
 generates the next 32-bit wide character from a narrow multibyte string
(function)
+
(C11)
 converts a 32-bit wide character to narrow multibyte string
(function)

Types

+ + + + + +
Defined in header <wchar.h>
+
(C95)
 conversion state information necessary to iterate multibyte character strings
(class)
Defined in header <uchar.h>
+
(C23)
 UTF-8 character type, an alias for unsigned char
(typedef)
+
(C11)
 16-bit wide character type
(typedef)
+
(C11)
 32-bit wide character type
(typedef)

Macros

+ + + +
Defined in header <limits.h>
MB_LEN_MAX
 maximum number of bytes in a multibyte character, for any supported locale
(macro constant)
Defined in header <stdlib.h>
MB_CUR_MAX
 maximum number of bytes in a multibyte character, in the current locale
(macro variable)

References

See also

+
C++ documentation for Null-terminated multibyte strings
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/multibyte +

+
diff --git a/devdocs/c/string%2Fwide%2Fiswalnum.html b/devdocs/c/string%2Fwide%2Fiswalnum.html new file mode 100644 index 00000000..26a33e71 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fiswalnum.html @@ -0,0 +1,116 @@ +

iswalnum

Defined in header <wctype.h> 
int iswalnum( wint_t ch );
+		 (since C95)

Checks if the given wide character is an alphanumeric character, i.e. either a number (0123456789), an uppercase letter (ABCDEFGHIJKLMNOPQRSTUVWXYZ), a lowercase letter (abcdefghijklmnopqrstuvwxyz) or any alphanumeric character specific to the current locale.

+

Parameters

+ +
ch - wide character

Return value

Non-zero value if the wide character is an alphanumeric character, zero otherwise.

+

Notes

ISO 30112 specifies which Unicode characters are include in POSIX alnum category.

+

Example

#include <stdio.h>
+#include <locale.h>
+#include <wchar.h>
+#include <wctype.h>
+ 
+int main(void)
+{
+    wchar_t c = L'\u13ad'; // the Cherokee letter HA ('Ꭽ')
+    printf("in the default locale, iswalnum(%#x) = %d\n", c, !!iswalnum(c));
+    setlocale(LC_ALL, "en_US.utf8");
+    printf("in Unicode locale, iswalnum(%#x) = %d\n", c, !!iswalnum(c));
+}

Possible output:

+
in the default locale, iswalnum(0x13ad) = 0
+in Unicode locale, iswalnum(0x13ad) = 1

References

See also

+ +
checks if a character is alphanumeric
(function)
C++ documentation for iswalnum
+ + + + + + + + + + + + + + + + + +
ASCII values characters

iscntrl
iswcntrl

+

isprint
iswprint

+

isspace
iswspace

+

isblank
iswblank

+

isgraph
iswgraph

+

ispunct
iswpunct

+

isalnum
iswalnum

+

isalpha
iswalpha

+

isupper
iswupper

+

islower
iswlower

+

isdigit
iswdigit

+

isxdigit
iswxdigit

+
decimal hexadecimal octal
0–8 \x0–\x8 \0–\10 control codes (NUL, etc.) +≠0 0 0 0 0 0 0 0 0 0 0 0
9 \x9 \11 tab (\t) +≠0 0 +≠0 +≠0 0 0 0 0 0 0 0 0
10–13 \xA–\xD \12–\15 whitespaces (\n, \v, \f, \r) +≠0 0 +≠0 0 0 0 0 0 0 0 0 0
14–31 \xE–\x1F \16–\37 control codes +≠0 0 0 0 0 0 0 0 0 0 0 0
32 \x20 \40 space 0 +≠0 +≠0 +≠0 0 0 0 0 0 0 0 0
33–47 \x21–\x2F \41–\57 !"#$%&'()*+,-./ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
48–57 \x30–\x39 \60–\71 0123456789 0 +≠0 0 0 +≠0 0 +≠0 0 0 0 +≠0 +≠0
58–64 \x3A–\x40 \72–\100 :;<=>?@ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
65–70 \x41–\x46 \101–\106 ABCDEF 0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 +≠0
71–90 \x47–\x5A \107–\132 GHIJKLMNOP
QRSTUVWXYZ 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 0
91–96 \x5B–\x60 \133–\140 [\]^_` 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
97–102 \x61–\x66 \141–\146 abcdef 0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 +≠0
103–122 \x67–\x7A \147–\172 ghijklmnop
qrstuvwxyz 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 0
123–126 \x7B–\x7E \172–\176 {|}~ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
127 \x7F \177 backspace character (DEL) +≠0 0 0 0 0 0 0 0 0 0 0 0
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/iswalnum +

+
diff --git a/devdocs/c/string%2Fwide%2Fiswalpha.html b/devdocs/c/string%2Fwide%2Fiswalpha.html new file mode 100644 index 00000000..6bf6e2f0 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fiswalpha.html @@ -0,0 +1,116 @@ +

iswalpha

Defined in header <wctype.h> 
int iswalpha( wint_t ch );
+		 (since C95)

Checks if the given wide character is an alphabetic character, i.e. either an uppercase letter (ABCDEFGHIJKLMNOPQRSTUVWXYZ), a lowercase letter (abcdefghijklmnopqrstuvwxyz) or any alphabetic character specific to the current locale.

+

Parameters

+ +
ch - wide character

Return value

Non-zero value if the wide character is an alphabetic character, zero otherwise.

+

Notes

ISO 30112 specifies which Unicode characters are include in POSIX alpha category.

+

Example

#include <locale.h>
+#include <stdio.h>
+#include <wchar.h>
+#include <wctype.h>
+ 
+int main(void)
+{
+    wchar_t c = L'\u0b83'; // Tamil sign Visarga ('ஃ')
+    printf("in the default locale, iswalpha(%#x) = %d\n", c, !!iswalpha(c));
+    setlocale(LC_ALL, "en_US.utf8");
+    printf("in Unicode locale, iswalpha(%#x) = %d\n", c, !!iswalpha(c));
+}

Possible output:

+
in the default locale, iswalpha(0xb83) = 0
+in Unicode locale, iswalpha(0xb83) = 1

References

See also

+ +
checks if a character is alphabetic
(function)
C++ documentation for iswalpha
+ + + + + + + + + + + + + + + + + +
ASCII values characters

iscntrl
iswcntrl

+

isprint
iswprint

+

isspace
iswspace

+

isblank
iswblank

+

isgraph
iswgraph

+

ispunct
iswpunct

+

isalnum
iswalnum

+

isalpha
iswalpha

+

isupper
iswupper

+

islower
iswlower

+

isdigit
iswdigit

+

isxdigit
iswxdigit

+
decimal hexadecimal octal
0–8 \x0–\x8 \0–\10 control codes (NUL, etc.) +≠0 0 0 0 0 0 0 0 0 0 0 0
9 \x9 \11 tab (\t) +≠0 0 +≠0 +≠0 0 0 0 0 0 0 0 0
10–13 \xA–\xD \12–\15 whitespaces (\n, \v, \f, \r) +≠0 0 +≠0 0 0 0 0 0 0 0 0 0
14–31 \xE–\x1F \16–\37 control codes +≠0 0 0 0 0 0 0 0 0 0 0 0
32 \x20 \40 space 0 +≠0 +≠0 +≠0 0 0 0 0 0 0 0 0
33–47 \x21–\x2F \41–\57 !"#$%&'()*+,-./ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
48–57 \x30–\x39 \60–\71 0123456789 0 +≠0 0 0 +≠0 0 +≠0 0 0 0 +≠0 +≠0
58–64 \x3A–\x40 \72–\100 :;<=>?@ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
65–70 \x41–\x46 \101–\106 ABCDEF 0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 +≠0
71–90 \x47–\x5A \107–\132 GHIJKLMNOP
QRSTUVWXYZ 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 0
91–96 \x5B–\x60 \133–\140 [\]^_` 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
97–102 \x61–\x66 \141–\146 abcdef 0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 +≠0
103–122 \x67–\x7A \147–\172 ghijklmnop
qrstuvwxyz 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 0
123–126 \x7B–\x7E \172–\176 {|}~ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
127 \x7F \177 backspace character (DEL) +≠0 0 0 0 0 0 0 0 0 0 0 0
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/iswalpha +

+
diff --git a/devdocs/c/string%2Fwide%2Fiswblank.html b/devdocs/c/string%2Fwide%2Fiswblank.html new file mode 100644 index 00000000..a1531a59 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fiswblank.html @@ -0,0 +1,117 @@ +

iswblank

Defined in header <wctype.h> 
int iswblank( wint_t ch );
+		 (since C99)

Checks if the given wide character is classified as blank character (that is, a whitespace character used to separate words in a sentence) by the current C locale. In the default C locale, only space (0x20) and horizontal tab (0x09) are blank characters.

+

Parameters

+ +
ch - wide character

Return value

Non-zero value if the wide character is a blank character, zero otherwise.

+

Notes

ISO 30112 defines POSIX blank characters as Unicode characters U+0009, U+0020, U+1680, U+180E, U+2000..U+2006, U+2008, U+200A, U+205F, and U+3000.

+

Example

#include <locale.h>
+#include <stdio.h>
+#include <wchar.h>
+#include <wctype.h>
+ 
+int main(void)
+{
+    wchar_t c = L'\u3000'; // Ideographic space ('　')
+    printf("In the default locale, iswblank(%#x) = %d\n", c, !!iswblank(c));
+    setlocale(LC_ALL, "en_US.utf8");
+    printf("In Unicode locale, iswblank(%#x) = %d\n", c, !!iswblank(c));
+}

Output:

+
In the default locale, iswblank(0x3000) = 0
+In Unicode locale, iswblank(0x3000) = 1

References

See also

+ +
+
(C99)
 checks if a character is a blank character
(function)
C++ documentation for iswblank
+ + + + + + + + + + + + + + + + + +
ASCII values characters

iscntrl
iswcntrl

+

isprint
iswprint

+

isspace
iswspace

+

isblank
iswblank

+

isgraph
iswgraph

+

ispunct
iswpunct

+

isalnum
iswalnum

+

isalpha
iswalpha

+

isupper
iswupper

+

islower
iswlower

+

isdigit
iswdigit

+

isxdigit
iswxdigit

+
decimal hexadecimal octal
0–8 \x0–\x8 \0–\10 control codes (NUL, etc.) +≠0 0 0 0 0 0 0 0 0 0 0 0
9 \x9 \11 tab (\t) +≠0 0 +≠0 +≠0 0 0 0 0 0 0 0 0
10–13 \xA–\xD \12–\15 whitespaces (\n, \v, \f, \r) +≠0 0 +≠0 0 0 0 0 0 0 0 0 0
14–31 \xE–\x1F \16–\37 control codes +≠0 0 0 0 0 0 0 0 0 0 0 0
32 \x20 \40 space 0 +≠0 +≠0 +≠0 0 0 0 0 0 0 0 0
33–47 \x21–\x2F \41–\57 !"#$%&'()*+,-./ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
48–57 \x30–\x39 \60–\71 0123456789 0 +≠0 0 0 +≠0 0 +≠0 0 0 0 +≠0 +≠0
58–64 \x3A–\x40 \72–\100 :;<=>?@ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
65–70 \x41–\x46 \101–\106 ABCDEF 0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 +≠0
71–90 \x47–\x5A \107–\132 GHIJKLMNOP
QRSTUVWXYZ 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 0
91–96 \x5B–\x60 \133–\140 [\]^_` 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
97–102 \x61–\x66 \141–\146 abcdef 0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 +≠0
103–122 \x67–\x7A \147–\172 ghijklmnop
qrstuvwxyz 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 0
123–126 \x7B–\x7E \172–\176 {|}~ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
127 \x7F \177 backspace character (DEL) +≠0 0 0 0 0 0 0 0 0 0 0 0
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/iswblank +

+
diff --git a/devdocs/c/string%2Fwide%2Fiswcntrl.html b/devdocs/c/string%2Fwide%2Fiswcntrl.html new file mode 100644 index 00000000..0b94ae30 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fiswcntrl.html @@ -0,0 +1,116 @@ +

iswcntrl

Defined in header <wctype.h> 
int iswcntrl( wint_t ch );
+		 (since C95)

Checks if the given wide character is a control character, i.e. codes 0x00-0x1F and 0x7F and any control characters specific to the current locale.

+

Parameters

+ +
ch - wide character

Return value

Non-zero value if the wide character is a control character, zero otherwise.

+

Notes

ISO 30112 defines POSIX control characters as Unicode characters U+0000..U+001F, U+007F..U+009F, U+2028, and U+2029 (Unicode classes Cc, Zl, and Zp)

+

Example

#include <locale.h>
+#include <stdio.h>
+#include <wchar.h>
+#include <wctype.h>
+ 
+int main(void)
+{
+    wchar_t c = L'\u2028'; // the Unicode character "line separator"
+    printf("In the default locale, iswcntrl(%#x) = %d\n", c, !!iswcntrl(c));
+    setlocale(LC_ALL, "en_US.utf8");
+    printf("In Unicode locale, iswcntrl(%#x) = %d\n", c, !!iswcntrl(c));
+}

Output:

+
In the default locale, iswcntrl(0x2028) = 0
+In Unicode locale, iswcntrl(0x2028) = 1

References

See also

+ +
checks if a character is a control character
(function)
C++ documentation for iswcntrl
+ + + + + + + + + + + + + + + + + +
ASCII values characters

iscntrl
iswcntrl

+

isprint
iswprint

+

isspace
iswspace

+

isblank
iswblank

+

isgraph
iswgraph

+

ispunct
iswpunct

+

isalnum
iswalnum

+

isalpha
iswalpha

+

isupper
iswupper

+

islower
iswlower

+

isdigit
iswdigit

+

isxdigit
iswxdigit

+
decimal hexadecimal octal
0–8 \x0–\x8 \0–\10 control codes (NUL, etc.) +≠0 0 0 0 0 0 0 0 0 0 0 0
9 \x9 \11 tab (\t) +≠0 0 +≠0 +≠0 0 0 0 0 0 0 0 0
10–13 \xA–\xD \12–\15 whitespaces (\n, \v, \f, \r) +≠0 0 +≠0 0 0 0 0 0 0 0 0 0
14–31 \xE–\x1F \16–\37 control codes +≠0 0 0 0 0 0 0 0 0 0 0 0
32 \x20 \40 space 0 +≠0 +≠0 +≠0 0 0 0 0 0 0 0 0
33–47 \x21–\x2F \41–\57 !"#$%&'()*+,-./ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
48–57 \x30–\x39 \60–\71 0123456789 0 +≠0 0 0 +≠0 0 +≠0 0 0 0 +≠0 +≠0
58–64 \x3A–\x40 \72–\100 :;<=>?@ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
65–70 \x41–\x46 \101–\106 ABCDEF 0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 +≠0
71–90 \x47–\x5A \107–\132 GHIJKLMNOP
QRSTUVWXYZ 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 0
91–96 \x5B–\x60 \133–\140 [\]^_` 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
97–102 \x61–\x66 \141–\146 abcdef 0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 +≠0
103–122 \x67–\x7A \147–\172 ghijklmnop
qrstuvwxyz 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 0
123–126 \x7B–\x7E \172–\176 {|}~ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
127 \x7F \177 backspace character (DEL) +≠0 0 0 0 0 0 0 0 0 0 0 0
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/iswcntrl +

+
diff --git a/devdocs/c/string%2Fwide%2Fiswctype.html b/devdocs/c/string%2Fwide%2Fiswctype.html new file mode 100644 index 00000000..36141d09 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fiswctype.html @@ -0,0 +1,46 @@ +

iswctype

Defined in header <wctype.h> 
int iswctype( wint_t wc, wctype_t desc );
+		 (since C95)

Classifies the wide character wc using the current C locale's LC_CTYPE category identified by desc.

+

Parameters

+ + +
wc - the wide character to classify
desc - the LC_CTYPE category, obtained from a call to wctype

Return value

Non-zero if the character wc has the property identified by desc in LC_CTYPE facet of the current C locale, zero otherwise.

+

Example

#include <locale.h>
+#include <stdio.h>
+#include <wchar.h>
+#include <wctype.h>
+ 
+const char* classify(wchar_t wc, const char* cat)
+{
+    return iswctype(wc, wctype(cat)) ? "true" : "false";
+}
+ 
+int main(void)
+{
+    setlocale(LC_ALL, "ja_JP.UTF-8");
+    puts("The character \u6c34 is...");
+    const char* cats[] = {"digit", "alpha", "space", "cntrl", "jkanji"};
+    for (int n = 0; n < 5; ++n)
+        printf("%s?\t%s\n", cats[n], classify(L'\u6c34', cats[n]));
+}

Output:

+
The character 水 is...
+digit?  false
+alpha?  true
+space?  false
+cntrl?  false
+jkanji? true

References

See also

+
+
(C95)
 looks up a character classification category in the current C locale
(function)
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/iswctype +

+
diff --git a/devdocs/c/string%2Fwide%2Fiswdigit.html b/devdocs/c/string%2Fwide%2Fiswdigit.html new file mode 100644 index 00000000..f65568b9 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fiswdigit.html @@ -0,0 +1,145 @@ +

iswdigit

Defined in header <wctype.h> 
int iswdigit( wint_t ch );
+		 (since C95)

Checks if the given wide character corresponds (if narrowed) to one of the ten decimal digit characters 0123456789.

+

Parameters

+ +
ch - wide character

Return value

Non-zero value if the wide character is a numeric character, zero otherwise.

+

Notes

iswdigit and iswxdigit are the only standard wide character classification functions that are not affected by the currently installed C locale.

+

Example

+

Some locales offer additional character classes that detect non-ASCII digits

+
#include <locale.h>
+#include <stdio.h>
+#include <wchar.h>
+#include <wctype.h>
+ 
+void test(wchar_t a3, wchar_t u3, wchar_t j3)
+{
+    printf("\t '%lc'  '%lc' '%lc'\n", a3, u3, j3);
+    printf("iswdigit: %d    %d    %d\n",
+           !!iswdigit(a3),
+           !!iswdigit(u3),
+           !!iswdigit(j3));
+    printf("jdigit:   %d    %d    %d\n",
+           !!iswctype(a3, wctype("jdigit")),
+           !!iswctype(u3, wctype("jdigit")),
+           !!iswctype(j3, wctype("jdigit")));
+}
+ 
+int main(void)
+{
+    wchar_t a3 = L'3';  // the ASCII digit 3
+    wchar_t u3 = L'三'; // the CJK numeral 3
+    wchar_t j3 = L'３'; // the full-width digit 3
+ 
+    setlocale(LC_ALL, "en_US.utf8");
+    puts("In American locale:");
+    test(a3, u3, j3);
+ 
+    setlocale(LC_ALL, "ja_JP.utf8");
+    puts("\nIn Japanese locale:");
+    test(a3, u3, j3);
+}

Possible output:

+
In American locale:
+         '3'  '三' '３'
+iswdigit: 1    0    0
+jdigit:   0    0    0
+ 
+In Japanese locale:
+         '3'  '三' '３'
+iswdigit: 1    0    0
+jdigit:   0    0    1

References

See also

+ +
checks if a character is a digit
(function)
C++ documentation for iswdigit
+ + + + + + + + + + + + + + + + + +
ASCII values characters

iscntrl
iswcntrl

+

isprint
iswprint

+

isspace
iswspace

+

isblank
iswblank

+

isgraph
iswgraph

+

ispunct
iswpunct

+

isalnum
iswalnum

+

isalpha
iswalpha

+

isupper
iswupper

+

islower
iswlower

+

isdigit
iswdigit

+

isxdigit
iswxdigit

+
decimal hexadecimal octal
0–8 \x0–\x8 \0–\10 control codes (NUL, etc.) +≠0 0 0 0 0 0 0 0 0 0 0 0
9 \x9 \11 tab (\t) +≠0 0 +≠0 +≠0 0 0 0 0 0 0 0 0
10–13 \xA–\xD \12–\15 whitespaces (\n, \v, \f, \r) +≠0 0 +≠0 0 0 0 0 0 0 0 0 0
14–31 \xE–\x1F \16–\37 control codes +≠0 0 0 0 0 0 0 0 0 0 0 0
32 \x20 \40 space 0 +≠0 +≠0 +≠0 0 0 0 0 0 0 0 0
33–47 \x21–\x2F \41–\57 !"#$%&'()*+,-./ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
48–57 \x30–\x39 \60–\71 0123456789 0 +≠0 0 0 +≠0 0 +≠0 0 0 0 +≠0 +≠0
58–64 \x3A–\x40 \72–\100 :;<=>?@ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
65–70 \x41–\x46 \101–\106 ABCDEF 0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 +≠0
71–90 \x47–\x5A \107–\132 GHIJKLMNOP
QRSTUVWXYZ 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 0
91–96 \x5B–\x60 \133–\140 [\]^_` 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
97–102 \x61–\x66 \141–\146 abcdef 0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 +≠0
103–122 \x67–\x7A \147–\172 ghijklmnop
qrstuvwxyz 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 0
123–126 \x7B–\x7E \172–\176 {|}~ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
127 \x7F \177 backspace character (DEL) +≠0 0 0 0 0 0 0 0 0 0 0 0
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/iswdigit +

+
diff --git a/devdocs/c/string%2Fwide%2Fiswgraph.html b/devdocs/c/string%2Fwide%2Fiswgraph.html new file mode 100644 index 00000000..993fade3 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fiswgraph.html @@ -0,0 +1,116 @@ +

iswgraph

Defined in header <wctype.h> 
int iswgraph( wint_t ch );
+		 (since C95)

Checks if the given wide character has a graphical representation, i.e. it is either a number (0123456789), an uppercase letter (ABCDEFGHIJKLMNOPQRSTUVWXYZ), a lowercase letter (abcdefghijklmnopqrstuvwxyz), a punctuation character (!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~) or any graphical character specific to the current C locale.

+

Parameters

+ +
ch - wide character

Return value

Non-zero value if the wide character has a graphical representation character, zero otherwise.

+

Notes

ISO 30112 specifies which Unicode characters are include in POSIX graph category.

+

Example

#include <locale.h>
+#include <stdio.h>
+#include <wchar.h>
+#include <wctype.h>
+ 
+int main(void)
+{
+    wchar_t c = L'\u2602'; // the Unicode character Umbrella ('☂')
+    printf("in the default locale, iswgraph(%#x) = %d\n", c, !!iswgraph(c));
+    setlocale(LC_ALL, "en_US.utf8");
+    printf("in Unicode locale, iswgraph(%#x) = %d\n", c, !!iswgraph(c));
+}

Output:

+
in the default locale, iswgraph(0x2602) = 0
+in Unicode locale, iswgraph(0x2602) = 1

References

See also

+ +
checks if a character is a graphical character
(function)
C++ documentation for iswgraph
+ + + + + + + + + + + + + + + + + +
ASCII values characters

iscntrl
iswcntrl

+

isprint
iswprint

+

isspace
iswspace

+

isblank
iswblank

+

isgraph
iswgraph

+

ispunct
iswpunct

+

isalnum
iswalnum

+

isalpha
iswalpha

+

isupper
iswupper

+

islower
iswlower

+

isdigit
iswdigit

+

isxdigit
iswxdigit

+
decimal hexadecimal octal
0–8 \x0–\x8 \0–\10 control codes (NUL, etc.) +≠0 0 0 0 0 0 0 0 0 0 0 0
9 \x9 \11 tab (\t) +≠0 0 +≠0 +≠0 0 0 0 0 0 0 0 0
10–13 \xA–\xD \12–\15 whitespaces (\n, \v, \f, \r) +≠0 0 +≠0 0 0 0 0 0 0 0 0 0
14–31 \xE–\x1F \16–\37 control codes +≠0 0 0 0 0 0 0 0 0 0 0 0
32 \x20 \40 space 0 +≠0 +≠0 +≠0 0 0 0 0 0 0 0 0
33–47 \x21–\x2F \41–\57 !"#$%&'()*+,-./ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
48–57 \x30–\x39 \60–\71 0123456789 0 +≠0 0 0 +≠0 0 +≠0 0 0 0 +≠0 +≠0
58–64 \x3A–\x40 \72–\100 :;<=>?@ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
65–70 \x41–\x46 \101–\106 ABCDEF 0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 +≠0
71–90 \x47–\x5A \107–\132 GHIJKLMNOP
QRSTUVWXYZ 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 0
91–96 \x5B–\x60 \133–\140 [\]^_` 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
97–102 \x61–\x66 \141–\146 abcdef 0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 +≠0
103–122 \x67–\x7A \147–\172 ghijklmnop
qrstuvwxyz 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 0
123–126 \x7B–\x7E \172–\176 {|}~ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
127 \x7F \177 backspace character (DEL) +≠0 0 0 0 0 0 0 0 0 0 0 0
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/iswgraph +

+
diff --git a/devdocs/c/string%2Fwide%2Fiswlower.html b/devdocs/c/string%2Fwide%2Fiswlower.html new file mode 100644 index 00000000..07d7193f --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fiswlower.html @@ -0,0 +1,116 @@ +

iswlower

Defined in header <wctype.h> 
int iswlower( wint_t ch );
+		 (since C95)

Checks if the given wide character is a lowercase letter, i.e. one of abcdefghijklmnopqrstuvwxyz or any lowercase letter specific to the current locale.

+

Parameters

+ +
ch - wide character

Return value

Non-zero value if the wide character is an lowercase letter, zero otherwise.

+

Notes

ISO 30112 specifies which Unicode characters are include in POSIX lower category.

+

Example

#include <locale.h>
+#include <stdio.h>
+#include <wchar.h>
+#include <wctype.h>
+ 
+int main(void)
+{
+    wchar_t c = L'\u0444'; // Cyrillic small letter ef ('ф')
+    printf("In the default locale, iswlower(%#x) = %d\n", c, !!iswlower(c));
+    setlocale(LC_ALL, "en_US.utf8");
+    printf("In Unicode locale, iswlower(%#x) = %d\n", c, !!iswlower(c));
+}

Output:

+
In the default locale, iswlower(0x444) = 0
+In Unicode locale, iswlower(0x444) = 1

References

See also

+ +
checks if a character is lowercase
(function)
C++ documentation for iswlower
+ + + + + + + + + + + + + + + + + +
ASCII values characters

iscntrl
iswcntrl

+

isprint
iswprint

+

isspace
iswspace

+

isblank
iswblank

+

isgraph
iswgraph

+

ispunct
iswpunct

+

isalnum
iswalnum

+

isalpha
iswalpha

+

isupper
iswupper

+

islower
iswlower

+

isdigit
iswdigit

+

isxdigit
iswxdigit

+
decimal hexadecimal octal
0–8 \x0–\x8 \0–\10 control codes (NUL, etc.) +≠0 0 0 0 0 0 0 0 0 0 0 0
9 \x9 \11 tab (\t) +≠0 0 +≠0 +≠0 0 0 0 0 0 0 0 0
10–13 \xA–\xD \12–\15 whitespaces (\n, \v, \f, \r) +≠0 0 +≠0 0 0 0 0 0 0 0 0 0
14–31 \xE–\x1F \16–\37 control codes +≠0 0 0 0 0 0 0 0 0 0 0 0
32 \x20 \40 space 0 +≠0 +≠0 +≠0 0 0 0 0 0 0 0 0
33–47 \x21–\x2F \41–\57 !"#$%&'()*+,-./ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
48–57 \x30–\x39 \60–\71 0123456789 0 +≠0 0 0 +≠0 0 +≠0 0 0 0 +≠0 +≠0
58–64 \x3A–\x40 \72–\100 :;<=>?@ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
65–70 \x41–\x46 \101–\106 ABCDEF 0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 +≠0
71–90 \x47–\x5A \107–\132 GHIJKLMNOP
QRSTUVWXYZ 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 0
91–96 \x5B–\x60 \133–\140 [\]^_` 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
97–102 \x61–\x66 \141–\146 abcdef 0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 +≠0
103–122 \x67–\x7A \147–\172 ghijklmnop
qrstuvwxyz 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 0
123–126 \x7B–\x7E \172–\176 {|}~ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
127 \x7F \177 backspace character (DEL) +≠0 0 0 0 0 0 0 0 0 0 0 0
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/iswlower +

+
diff --git a/devdocs/c/string%2Fwide%2Fiswprint.html b/devdocs/c/string%2Fwide%2Fiswprint.html new file mode 100644 index 00000000..0fb25886 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fiswprint.html @@ -0,0 +1,119 @@ +

iswprint

Defined in header <wctype.h> 
int iswprint( wint_t ch );
+		 (since C95)

Checks if the given wide character can be printed, i.e. it is either a number (0123456789), an uppercase letter (ABCDEFGHIJKLMNOPQRSTUVWXYZ), a lowercase letter (abcdefghijklmnopqrstuvwxyz), a punctuation character (!"#$%&'()*+,-./:;<=>?@[\]^_`{!}~), space or any printable character specific to the current C locale.

+

Parameters

+ +
ch - wide character

Return value

Non-zero value if the wide character can be printed, zero otherwise.

+

Notes

ISO 30112 specifies which Unicode characters are included in POSIX print category.

+

Example

#include <locale.h>
+#include <stdio.h>
+#include <wchar.h>
+#include <wctype.h>
+ 
+int main(void)
+{
+    wchar_t c = L'\u2002'; // Unicode character 'EN SPACE'
+    printf("in the default locale, iswprint(%#x) = %d\n", c, !!iswprint(c));
+    setlocale(LC_ALL, "en_US.utf8");
+    printf("in Unicode locale, iswprint(%#x) = %d\n", c, !!iswprint(c));
+    wchar_t c2 = L'\x82'; // break permitted
+    printf("in Unicode locale, iswprint(%#x) = %d\n", c2, !!iswprint(c2));
+}

Output:

+
in the default locale, iswprint(0x2002) = 0
+in Unicode locale, iswprint(0x2002) = 1
+in Unicode locale, iswprint(0x82) = 0

References

See also

+ +
checks if a character is a printing character
(function)
C++ documentation for iswprint
+ + + + + + + + + + + + + + + + + +
ASCII values characters

iscntrl
iswcntrl

+

isprint
iswprint

+

isspace
iswspace

+

isblank
iswblank

+

isgraph
iswgraph

+

ispunct
iswpunct

+

isalnum
iswalnum

+

isalpha
iswalpha

+

isupper
iswupper

+

islower
iswlower

+

isdigit
iswdigit

+

isxdigit
iswxdigit

+
decimal hexadecimal octal
0–8 \x0–\x8 \0–\10 control codes (NUL, etc.) +≠0 0 0 0 0 0 0 0 0 0 0 0
9 \x9 \11 tab (\t) +≠0 0 +≠0 +≠0 0 0 0 0 0 0 0 0
10–13 \xA–\xD \12–\15 whitespaces (\n, \v, \f, \r) +≠0 0 +≠0 0 0 0 0 0 0 0 0 0
14–31 \xE–\x1F \16–\37 control codes +≠0 0 0 0 0 0 0 0 0 0 0 0
32 \x20 \40 space 0 +≠0 +≠0 +≠0 0 0 0 0 0 0 0 0
33–47 \x21–\x2F \41–\57 !"#$%&'()*+,-./ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
48–57 \x30–\x39 \60–\71 0123456789 0 +≠0 0 0 +≠0 0 +≠0 0 0 0 +≠0 +≠0
58–64 \x3A–\x40 \72–\100 :;<=>?@ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
65–70 \x41–\x46 \101–\106 ABCDEF 0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 +≠0
71–90 \x47–\x5A \107–\132 GHIJKLMNOP
QRSTUVWXYZ 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 0
91–96 \x5B–\x60 \133–\140 [\]^_` 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
97–102 \x61–\x66 \141–\146 abcdef 0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 +≠0
103–122 \x67–\x7A \147–\172 ghijklmnop
qrstuvwxyz 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 0
123–126 \x7B–\x7E \172–\176 {|}~ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
127 \x7F \177 backspace character (DEL) +≠0 0 0 0 0 0 0 0 0 0 0 0
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/iswprint +

+
diff --git a/devdocs/c/string%2Fwide%2Fiswpunct.html b/devdocs/c/string%2Fwide%2Fiswpunct.html new file mode 100644 index 00000000..8aa2b1d1 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fiswpunct.html @@ -0,0 +1,116 @@ +

iswpunct

Defined in header <wctype.h> 
int iswpunct( wint_t ch );
+		 (since C95)

Checks if the given wide character is a punctuation character, i.e. it is one of !"#$%&'()*+,-./:;<=>?@[\]^_`{|}~ or any punctuation character specific to the current locale.

+

Parameters

+ +
ch - wide character

Return value

Non-zero value if the wide character is a punctuation character, zero otherwise.

+

Notes

ISO 30112 specifies which Unicode characters are include in POSIX punct category.

+

Example

#include <stdio.h>
+#include <wchar.h>
+#include <wctype.h>
+#include <locale.h>
+ 
+int main(void)
+{
+    const wchar_t c = L'\u2051'; // Two asterisks ('⁑')
+    printf("in the default locale, iswpunct(%#x) = %d\n", c, !!iswpunct(c));
+    setlocale(LC_ALL, "en_US.utf8");
+    printf("in Unicode locale, iswpunct(%#x) = %d\n", c, !!iswpunct(c));
+}

Output:

+
in the default locale, iswpunct(0x2051) = 0
+in Unicode locale, iswpunct(0x2051) = 1

References

See also

+ +
checks if a character is a punctuation character
(function)
C++ documentation for iswpunct
+ + + + + + + + + + + + + + + + + +
ASCII values characters

iscntrl
iswcntrl

+

isprint
iswprint

+

isspace
iswspace

+

isblank
iswblank

+

isgraph
iswgraph

+

ispunct
iswpunct

+

isalnum
iswalnum

+

isalpha
iswalpha

+

isupper
iswupper

+

islower
iswlower

+

isdigit
iswdigit

+

isxdigit
iswxdigit

+
decimal hexadecimal octal
0–8 \x0–\x8 \0–\10 control codes (NUL, etc.) +≠0 0 0 0 0 0 0 0 0 0 0 0
9 \x9 \11 tab (\t) +≠0 0 +≠0 +≠0 0 0 0 0 0 0 0 0
10–13 \xA–\xD \12–\15 whitespaces (\n, \v, \f, \r) +≠0 0 +≠0 0 0 0 0 0 0 0 0 0
14–31 \xE–\x1F \16–\37 control codes +≠0 0 0 0 0 0 0 0 0 0 0 0
32 \x20 \40 space 0 +≠0 +≠0 +≠0 0 0 0 0 0 0 0 0
33–47 \x21–\x2F \41–\57 !"#$%&'()*+,-./ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
48–57 \x30–\x39 \60–\71 0123456789 0 +≠0 0 0 +≠0 0 +≠0 0 0 0 +≠0 +≠0
58–64 \x3A–\x40 \72–\100 :;<=>?@ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
65–70 \x41–\x46 \101–\106 ABCDEF 0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 +≠0
71–90 \x47–\x5A \107–\132 GHIJKLMNOP
QRSTUVWXYZ 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 0
91–96 \x5B–\x60 \133–\140 [\]^_` 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
97–102 \x61–\x66 \141–\146 abcdef 0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 +≠0
103–122 \x67–\x7A \147–\172 ghijklmnop
qrstuvwxyz 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 0
123–126 \x7B–\x7E \172–\176 {|}~ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
127 \x7F \177 backspace character (DEL) +≠0 0 0 0 0 0 0 0 0 0 0 0
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/iswpunct +

+
diff --git a/devdocs/c/string%2Fwide%2Fiswspace.html b/devdocs/c/string%2Fwide%2Fiswspace.html new file mode 100644 index 00000000..8b141acc --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fiswspace.html @@ -0,0 +1,116 @@ +

iswspace

Defined in header <wctype.h> 
int iswspace( wint_t ch );
+		 (since C95)

Checks if the given wide character is a whitespace character, i.e. either space (0x20), form feed (0x0c), line feed (0x0a), carriage return (0x0d), horizontal tab (0x09), vertical tab (0x0b) or any whitespace character specific to the current locale.

+

Parameters

+ +
ch - wide character

Return value

Non-zero value if the wide character is a whitespace character, zero otherwise.

+

Notes

ISO 30112 defines POSIX space characters as Unicode characters U+0009..U+000D, U+0020, U+1680, U+180E, U+2000..U+2006, U+2008..U+200A, U+2028, U+2029, U+205F, and U+3000.

+

Example

#include <locale.h>
+#include <stdio.h>
+#include <wchar.h>
+#include <wctype.h>
+ 
+int main(void)
+{
+    wchar_t c = L'\u2003'; // Unicode character 'EM SPACE'
+    printf("In the default locale, iswspace(%#x) = %d\n", c, !!iswspace(c));
+    setlocale(LC_ALL, "en_US.utf8");
+    printf("In Unicode locale, iswspace(%#x) = %d\n", c, !!iswspace(c));
+}

Output:

+
In the default locale, iswspace(0x2003) = 0
+In Unicode locale, iswspace(0x2003) = 1

References

See also

+ +
checks if a character is a space character
(function)
C++ documentation for iswspace
+ + + + + + + + + + + + + + + + + +
ASCII values characters

iscntrl
iswcntrl

+

isprint
iswprint

+

isspace
iswspace

+

isblank
iswblank

+

isgraph
iswgraph

+

ispunct
iswpunct

+

isalnum
iswalnum

+

isalpha
iswalpha

+

isupper
iswupper

+

islower
iswlower

+

isdigit
iswdigit

+

isxdigit
iswxdigit

+
decimal hexadecimal octal
0–8 \x0–\x8 \0–\10 control codes (NUL, etc.) +≠0 0 0 0 0 0 0 0 0 0 0 0
9 \x9 \11 tab (\t) +≠0 0 +≠0 +≠0 0 0 0 0 0 0 0 0
10–13 \xA–\xD \12–\15 whitespaces (\n, \v, \f, \r) +≠0 0 +≠0 0 0 0 0 0 0 0 0 0
14–31 \xE–\x1F \16–\37 control codes +≠0 0 0 0 0 0 0 0 0 0 0 0
32 \x20 \40 space 0 +≠0 +≠0 +≠0 0 0 0 0 0 0 0 0
33–47 \x21–\x2F \41–\57 !"#$%&'()*+,-./ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
48–57 \x30–\x39 \60–\71 0123456789 0 +≠0 0 0 +≠0 0 +≠0 0 0 0 +≠0 +≠0
58–64 \x3A–\x40 \72–\100 :;<=>?@ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
65–70 \x41–\x46 \101–\106 ABCDEF 0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 +≠0
71–90 \x47–\x5A \107–\132 GHIJKLMNOP
QRSTUVWXYZ 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 0
91–96 \x5B–\x60 \133–\140 [\]^_` 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
97–102 \x61–\x66 \141–\146 abcdef 0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 +≠0
103–122 \x67–\x7A \147–\172 ghijklmnop
qrstuvwxyz 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 0
123–126 \x7B–\x7E \172–\176 {|}~ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
127 \x7F \177 backspace character (DEL) +≠0 0 0 0 0 0 0 0 0 0 0 0
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/iswspace +

+
diff --git a/devdocs/c/string%2Fwide%2Fiswupper.html b/devdocs/c/string%2Fwide%2Fiswupper.html new file mode 100644 index 00000000..206895ca --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fiswupper.html @@ -0,0 +1,116 @@ +

iswupper

Defined in header <wctype.h> 
int iswupper( wint_t ch );
+		 (since C95)

Checks if the given wide character is an uppercase letter, i.e. one of ABCDEFGHIJKLMNOPQRSTUVWXYZ or any uppercase letter specific to the current locale.

+

Parameters

+ +
ch - wide character

Return value

Non-zero value if the wide character is an uppercase letter, zero otherwise.

+

Notes

ISO 30112 specifies which Unicode characters are include in POSIX upper category.

+

Example

#include <locale.h>
+#include <stdio.h>
+#include <wchar.h>
+#include <wctype.h>
+ 
+int main(void)
+{
+    wchar_t c = L'\u053d'; // Armenian capital letter xeh ('Խ')
+    printf("In the default locale, iswupper(%#x) = %d\n", c, !!iswupper(c));
+    setlocale(LC_ALL, "en_US.utf8");
+    printf("In Unicode locale, iswupper(%#x) = %d\n", c, !!iswupper(c));
+}

Output:

+
In the default locale, iswupper(0x53d) = 0
+In Unicode locale, iswupper(0x53d) = 1

References

See also

+ +
checks if a character is an uppercase character
(function)
C++ documentation for iswupper
+ + + + + + + + + + + + + + + + + +
ASCII values characters

iscntrl
iswcntrl

+

isprint
iswprint

+

isspace
iswspace

+

isblank
iswblank

+

isgraph
iswgraph

+

ispunct
iswpunct

+

isalnum
iswalnum

+

isalpha
iswalpha

+

isupper
iswupper

+

islower
iswlower

+

isdigit
iswdigit

+

isxdigit
iswxdigit

+
decimal hexadecimal octal
0–8 \x0–\x8 \0–\10 control codes (NUL, etc.) +≠0 0 0 0 0 0 0 0 0 0 0 0
9 \x9 \11 tab (\t) +≠0 0 +≠0 +≠0 0 0 0 0 0 0 0 0
10–13 \xA–\xD \12–\15 whitespaces (\n, \v, \f, \r) +≠0 0 +≠0 0 0 0 0 0 0 0 0 0
14–31 \xE–\x1F \16–\37 control codes +≠0 0 0 0 0 0 0 0 0 0 0 0
32 \x20 \40 space 0 +≠0 +≠0 +≠0 0 0 0 0 0 0 0 0
33–47 \x21–\x2F \41–\57 !"#$%&'()*+,-./ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
48–57 \x30–\x39 \60–\71 0123456789 0 +≠0 0 0 +≠0 0 +≠0 0 0 0 +≠0 +≠0
58–64 \x3A–\x40 \72–\100 :;<=>?@ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
65–70 \x41–\x46 \101–\106 ABCDEF 0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 +≠0
71–90 \x47–\x5A \107–\132 GHIJKLMNOP
QRSTUVWXYZ 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 0
91–96 \x5B–\x60 \133–\140 [\]^_` 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
97–102 \x61–\x66 \141–\146 abcdef 0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 +≠0
103–122 \x67–\x7A \147–\172 ghijklmnop
qrstuvwxyz 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 0
123–126 \x7B–\x7E \172–\176 {|}~ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
127 \x7F \177 backspace character (DEL) +≠0 0 0 0 0 0 0 0 0 0 0 0
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/iswupper +

+
diff --git a/devdocs/c/string%2Fwide%2Fiswxdigit.html b/devdocs/c/string%2Fwide%2Fiswxdigit.html new file mode 100644 index 00000000..4382bde0 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fiswxdigit.html @@ -0,0 +1,145 @@ +

iswxdigit

Defined in header <wctype.h> 
int iswxdigit( wint_t ch );
+		 (since C95)

Checks if the given wide character corresponds (if narrowed) to a hexadecimal numeric character, i.e. one of 0123456789abcdefABCDEF.

+

Parameters

+ +
ch - wide character

Return value

Non-zero value if the wide character is a hexadecimal numeric character, zero otherwise.

+

Notes

iswdigit and iswxdigit are the only standard wide character classification functions that are not affected by the currently installed C locale.

+

Example

+

Some locales offer additional character classes that detect non-ASCII digits

+
#include <locale.h>
+#include <stdio.h>
+#include <wchar.h>
+#include <wctype.h>
+ 
+void test(wchar_t a3, wchar_t u3, wchar_t j3)
+{
+    printf("\t  '%lc'  '%lc' '%lc'\n", a3, u3, j3);
+    printf("iswxdigit: %d    %d    %d\n",
+           !!iswxdigit(a3),
+           !!iswxdigit(u3),
+           !!iswxdigit(j3));
+    printf("jdigit:    %d    %d    %d\n",
+           !!iswctype(a3, wctype("jdigit")),
+           !!iswctype(u3, wctype("jdigit")),
+           !!iswctype(j3, wctype("jdigit")));
+}
+ 
+int main(void)
+{
+    wchar_t a3 = L'9';  // the ASCII digit 9
+    wchar_t u3 = L'〩'; // the CJK numeral 9
+    wchar_t j3 = L'９'; // the full-width digit 9
+ 
+    setlocale(LC_ALL, "en_US.utf8");
+    puts("In American locale:");
+    test(a3, u3, j3);
+ 
+    setlocale(LC_ALL, "ja_JP.utf8");
+    puts("\nIn Japanese locale:");
+    test(a3, u3, j3);
+}

Possible output:

+
In American locale:
+          '9'  '〩' '９'
+iswxdigit: 1    0    0
+jdigit:    0    0    0
+ 
+In Japanese locale:
+          '9'  '〩' '９'
+iswxdigit: 1    0    0
+jdigit:    0    0    1

References

See also

+ +
checks if a character is a hexadecimal character
(function)
C++ documentation for iswxdigit
+ + + + + + + + + + + + + + + + + +
ASCII values characters

iscntrl
iswcntrl

+

isprint
iswprint

+

isspace
iswspace

+

isblank
iswblank

+

isgraph
iswgraph

+

ispunct
iswpunct

+

isalnum
iswalnum

+

isalpha
iswalpha

+

isupper
iswupper

+

islower
iswlower

+

isdigit
iswdigit

+

isxdigit
iswxdigit

+
decimal hexadecimal octal
0–8 \x0–\x8 \0–\10 control codes (NUL, etc.) +≠0 0 0 0 0 0 0 0 0 0 0 0
9 \x9 \11 tab (\t) +≠0 0 +≠0 +≠0 0 0 0 0 0 0 0 0
10–13 \xA–\xD \12–\15 whitespaces (\n, \v, \f, \r) +≠0 0 +≠0 0 0 0 0 0 0 0 0 0
14–31 \xE–\x1F \16–\37 control codes +≠0 0 0 0 0 0 0 0 0 0 0 0
32 \x20 \40 space 0 +≠0 +≠0 +≠0 0 0 0 0 0 0 0 0
33–47 \x21–\x2F \41–\57 !"#$%&'()*+,-./ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
48–57 \x30–\x39 \60–\71 0123456789 0 +≠0 0 0 +≠0 0 +≠0 0 0 0 +≠0 +≠0
58–64 \x3A–\x40 \72–\100 :;<=>?@ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
65–70 \x41–\x46 \101–\106 ABCDEF 0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 +≠0
71–90 \x47–\x5A \107–\132 GHIJKLMNOP
QRSTUVWXYZ 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 0
91–96 \x5B–\x60 \133–\140 [\]^_` 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
97–102 \x61–\x66 \141–\146 abcdef 0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 +≠0
103–122 \x67–\x7A \147–\172 ghijklmnop
qrstuvwxyz 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 0
123–126 \x7B–\x7E \172–\176 {|}~ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
127 \x7F \177 backspace character (DEL) +≠0 0 0 0 0 0 0 0 0 0 0 0
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/iswxdigit +

+
diff --git a/devdocs/c/string%2Fwide%2Ftowctrans.html b/devdocs/c/string%2Fwide%2Ftowctrans.html new file mode 100644 index 00000000..36a38b2b --- /dev/null +++ b/devdocs/c/string%2Fwide%2Ftowctrans.html @@ -0,0 +1,39 @@ +

towctrans

Defined in header <wctype.h> 
wint_t towctrans( wint_t wc, wctrans_t desc );
+		 (since C95)

Maps the wide character wc using the current C locale's LC_CTYPE mapping category identified by desc.

+

Parameters

+ + +
wc - the wide character to map
desc - the LC_CTYPE mapping, obtained from a call to wctrans

Return value

The mapped value of wc using the mapping identified by desc in LC_CTYPE facet of the current C locale.

+

Example

#include <locale.h>
+#include <wctype.h>
+#include <wchar.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    setlocale(LC_ALL, "ja_JP.UTF-8");
+    const wchar_t kana[] = L"ヒラガナ";
+    size_t sz = sizeof kana / sizeof *kana;
+    wchar_t hira[sz];
+    for (size_t n = 0; n < sz; ++n)
+        hira[n] = towctrans(kana[n], wctrans("tojhira"));
+    printf("katakana characters %ls are %ls in hiragana\n", kana, hira);
+}

Output:

+
katakana characters ヒラガナ are ひらがな in hiragana

References

See also

+ +
+
(C95)
 looks up a character mapping category in the current C locale
(function)
C++ documentation for towctrans
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/towctrans +

+
diff --git a/devdocs/c/string%2Fwide%2Ftowlower.html b/devdocs/c/string%2Fwide%2Ftowlower.html new file mode 100644 index 00000000..0d1bdad4 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Ftowlower.html @@ -0,0 +1,39 @@ +

towlower

Defined in header <wctype.h> 
wint_t towlower( wint_t wc );
+		 (since C95)

Converts the given wide character to lowercase, if possible.

+

Parameters

+ +
wc - wide character to be converted

Return value

Lowercase version of wc or unmodified wc if no lowercase version is listed in the current C locale.

+

Notes

Only 1:1 character mapping can be performed by this function, e.g. the Greek uppercase letter 'Σ' has two lowercase forms, depending on the position in a word: 'σ' and 'ς'. A call to towlower cannot be used to obtain the correct lowercase form in this case.

+

ISO 30112 specifies which pairs of Unicode characters are included in this mapping.

+

Example

#include <locale.h>
+#include <stdio.h>
+#include <wchar.h>
+#include <wctype.h>
+ 
+int main(void)
+{
+    wchar_t wc = L'\u0190'; // Latin capital open E ('Ɛ')
+    printf("in the default locale, towlower(%#x) = %#x\n", wc, towlower(wc));
+    setlocale(LC_ALL, "en_US.utf8");
+    printf("in Unicode locale, towlower(%#x) = %#x\n", wc, towlower(wc));
+}

Output:

+
in the default locale, towlower(0x190) = 0x190
+in Unicode locale, towlower(0x190) = 0x25b

References

See also

+ + +
+
(C95)
 converts a wide character to uppercase
(function)
converts a character to lowercase
(function)
C++ documentation for towlower
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/towlower +

+
diff --git a/devdocs/c/string%2Fwide%2Ftowupper.html b/devdocs/c/string%2Fwide%2Ftowupper.html new file mode 100644 index 00000000..4e0cdeb3 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Ftowupper.html @@ -0,0 +1,35 @@ +

towupper

Defined in header <wctype.h> 
wint_t towupper( wint_t wc );
+		 (since C95)

Converts the given wide character to uppercase, if possible.

+

Parameters

+ +
wc - wide character to be converted

Return value

Uppercase version of wc or unmodified wc if no uppercase version is listed in the current C locale.

+

Notes

Only 1:1 character mapping can be performed by this function, e.g. the uppercase form of 'ß' is (with some exceptions) the two-character string "SS", which cannot be obtained by towupper.

+

ISO 30112 specifies which pairs of Unicode characters are included in this mapping.

+

Example

#include <stdio.h>
+#include <wchar.h>
+#include <wctype.h>
+#include <locale.h>
+ 
+int main(void)
+{
+    wchar_t wc =  L'\u017f'; // Latin small letter Long S ('ſ')
+    printf("in the default locale, towupper(%#x) = %#x\n", wc, towupper(wc));
+    setlocale(LC_ALL, "en_US.utf8");
+    printf("in Unicode locale, towupper(%#x) = %#x\n", wc, towupper(wc));
+}

Output:

+
in the default locale, towupper(0x17f) = 0x17f
+in Unicode locale, towupper(0x17f) = 0x53

References

See also

+ + +
+
(C95)
 converts a wide character to lowercase
(function)
converts a character to uppercase
(function)
C++ documentation for towupper
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/towupper +

+
diff --git a/devdocs/c/string%2Fwide%2Fwcscat.html b/devdocs/c/string%2Fwide%2Fwcscat.html new file mode 100644 index 00000000..038a0a54 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcscat.html @@ -0,0 +1,62 @@ +

wcscat, wcscat_s

Defined in header <wchar.h>
(1) 
wchar_t *wcscat( wchar_t *dest, const wchar_t *src );
+		 (since C95)
(until C99) 
wchar_t *wcscat( wchar_t *restrict dest, const wchar_t *restrict src );
+		 (since C99) 
errno_t wcscat_s( wchar_t *restrict dest, rsize_t destsz,
+                  const wchar_t *restrict src );
+		 (2) (since C11)
+1) Appends a copy of the wide string pointed to by src to the end of the wide string pointed to by dest. The wide character src[0] replaces the null terminator at the end of dest. The resulting wide string is null-terminated. The behavior is undefined if the destination array is not large enough for the contents of both str and dest and the terminating null wide character. The behavior is undefined if the strings overlap.
+2) Same as (1), except that it may clobber the rest of the destination array (from the last character written to destsz) with unspecified values and that the following errors are detected at runtime and call the currently installed constraint handler function:
+
+
    +
  • src or dest is a null pointer
    • +
  • destsz is zero or greater than RSIZE_MAX/sizeof(wchar_t)
    • +
  • there is no null terminator in the first destsz wide characters of dest
    • +
  • truncation would occur (the available space at the end of dest would not fit every wide character, including the null terminator, of src)
    • +
  • overlap would occur between the source and the destination strings
    • +
+
As with all bounds-checked functions, wcscat_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <wchar.h>.
+
+

Parameters

+ + + +
dest - pointer to the null-terminated wide string to append to
src - pointer to the null-terminated wide string to copy from
destsz - maximum number of characters to write, typically the size of the destination buffer

Return value

+1) returns a copy of dest +
+2) returns zero on success, returns non-zero on error. Also, on error, writes L'\0' to dest[0] (unless dest is a null pointer or destsz is zero or greater than RSIZE_MAX/sizeof(wchar_t)).

Example

#include <wchar.h> 
+#include <stdio.h>
+#include <locale.h>
+ 
+int main(void) 
+{
+    wchar_t str[50] = L"Земля, прощай.";
+    wcscat(str, L" ");
+    wcscat(str, L"В добрый путь.");
+    setlocale(LC_ALL, "en_US.utf8");
+    printf("%ls", str);
+}

Output:

+
Земля, прощай. В добрый путь.

References

See also

+ + + +
+
(C95)(C11)
 appends a certain amount of wide characters from one wide string to another
(function)
+
(C11)
 concatenates two strings
(function)
+
(C95)(C11)
 copies one wide string to another
(function)
C++ documentation for wcscat
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/wcscat +

+
diff --git a/devdocs/c/string%2Fwide%2Fwcschr.html b/devdocs/c/string%2Fwide%2Fwcschr.html new file mode 100644 index 00000000..586441d6 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcschr.html @@ -0,0 +1,50 @@ +

wcschr

Defined in header <wchar.h> 
wchar_t *wcschr( const wchar_t *str, wchar_t ch );
+		 (1) (since C95) 
/*QWchar_t*/ *wcschr( /*QWchar_t*/ *str, wchar_t ch );
+		 (2) (since C23)
+1) Finds the first occurrence of the wide character ch in the wide string pointed to by str.
+2) Type-generic function equivalent to (1). Let T be an unqualified wide character object type. If a macro definition of each of these generic functions is suppressed to access an actual function (e.g. if (wcschr) or a function pointer is used), the actual function declaration (1) becomes visible.

Parameters

+ + +
str - pointer to the null-terminated wide string to be analyzed
ch - wide character to search for

Return value

Pointer to the found character in str, or a null pointer if no such character is found.

+

Example

#include <wchar.h>
+#include <stdio.h>
+#include <locale.h>
+ 
+int main(void)
+{
+    wchar_t arr[] = L"白猫 黒猫 кошки";
+    wchar_t *cat = wcschr(arr, L'猫');
+    wchar_t *dog = wcschr(arr, L'犬');
+ 
+    setlocale(LC_ALL, "en_US.utf8");
+    if(cat)
+        printf("The character 猫 found at position %td\n", cat-arr);
+    else
+        puts("The character 猫 not found");
+ 
+    if(dog)
+        printf("The character 犬 found at position %td\n", dog-arr);
+    else
+        puts("The character 犬 not found");
+}

Output:

+
The character 猫 found at position 1
+The character 犬 not found

References

See also

+ + +
+
(C95)
 finds the last occurrence of a wide character in a wide string
(function)
+
(C95)
 finds the first location of any wide character in one wide string, in another wide string
(function)
C++ documentation for wcschr
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/wcschr +

+
diff --git a/devdocs/c/string%2Fwide%2Fwcscmp.html b/devdocs/c/string%2Fwide%2Fwcscmp.html new file mode 100644 index 00000000..297be2b0 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcscmp.html @@ -0,0 +1,55 @@ +

wcscmp

Defined in header <wchar.h> 
int wcscmp( const wchar_t* lhs, const wchar_t* rhs );
+		 (since C95)

Compares two null-terminated wide strings lexicographically.

+

The sign of the result is the sign of the difference between the values of the first pair of wide characters that differ in the strings being compared.

+

The behavior is undefined if lhs or rhs are not pointers to null-terminated wide strings.

+

Parameters

+ +
lhs, rhs - pointers to the null-terminated wide strings to compare

Return value

Negative value if lhs appears before rhs in lexicographical order.

+

Zero if lhs and rhs compare equal.

+

Positive value if lhs appears after rhs in lexicographical order.

+

Notes

This function is not locale-sensitive, unlike wcscoll, and the order may not be meaningful when characters from different Unicode blocks are used together or when the order of code units does not match any collation order.

+

Example

#include <locale.h>
+#include <stdio.h>
+#include <wchar.h>
+ 
+void demo(const wchar_t* lhs, const wchar_t* rhs)
+{
+    int rc = wcscmp(lhs, rhs);
+    const char *rel = rc < 0 ? "precedes" : rc > 0 ? "follows" : "equals";
+ 
+    setlocale(LC_ALL, "en_US.utf8");
+    printf("[%ls] %s [%ls]\n", lhs, rel, rhs);
+}
+ 
+int main(void)
+{
+    const wchar_t* string = L"どうもありがとうございます";
+    demo(string, L"どうも");
+    demo(string, L"助かった");
+    demo(string + 9, L"ありがとうございます" + 6);
+}

Possible output:

+
[どうもありがとうございます] follows [どうも]
+[どうもありがとうございます] precedes [助かった]
+[ざいます] equals [ざいます]

References

See also

+ + + + +
+
(C95)
 compares a certain amount of characters from two wide strings
(function)
+
(C95)
 compares a certain amount of wide characters from two arrays
(function)
compares two strings
(function)
+
(C95)
 compares two wide strings in accordance to the current locale
(function)
C++ documentation for wcscmp
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/wcscmp +

+
diff --git a/devdocs/c/string%2Fwide%2Fwcscoll.html b/devdocs/c/string%2Fwide%2Fwcscoll.html new file mode 100644 index 00000000..d011acc3 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcscoll.html @@ -0,0 +1,58 @@ +

wcscoll

Defined in header <wchar.h> 
int wcscoll( const wchar_t *lhs, const wchar_t *rhs );
+		 (since C95)

Compares two null-terminated wide strings according to the collation order defined by the LC_COLLATE category of the currently installed locale.

+

Parameters

+ +
lhs, rhs - pointers to the null-terminated wide strings to compare

Return value

Negative value if lhs is less than (precedes) rhs.

+

​0​ if lhs is equal to rhs.

+

Positive value if lhs is greater than (follows) rhs.

+

Notes

Collation order is the dictionary order: the position of the letter in the national alphabet (its equivalence class) has higher priority than its case or variant. Within an equivalence class, lowercase characters collate before their uppercase equivalents and locale-specific order may apply to the characters with diacritics. In some locales, groups of characters compare as single collation units. For example, "ch" in Czech follows "h" and precedes "i", and "dzs" in Hungarian follows "dz" and precedes "g".

+

Example

#include <stdio.h>
+#include <wchar.h>
+#include <locale.h>
+ 
+void try_compare(const wchar_t* p1, const wchar_t* p2)
+{
+    if(wcscoll(p1, p2) < 0)
+        printf("%ls before %ls\n", p1, p2);
+    else
+        printf("%ls before %ls\n", p2, p1);
+}
+ 
+int main(void)
+{
+    setlocale(LC_ALL, "en_US.utf8");
+    printf("In the American locale: ");
+    try_compare(L"hrnec", L"chrt");
+ 
+    setlocale(LC_COLLATE, "cs_CZ.utf8");
+    printf("In the Czech locale: ");
+    try_compare(L"hrnec", L"chrt");
+ 
+    setlocale(LC_COLLATE, "en_US.utf8");
+    printf("In the American locale: ");
+    try_compare(L"år", L"ängel");
+ 
+    setlocale(LC_COLLATE, "sv_SE.utf8");
+    printf("In the Swedish locale: ");
+    try_compare(L"år", L"ängel");
+}

Possible output:

+
In the American locale: chrt before hrnec
+In the Czech locale: hrnec before chrt
+In the American locale: ängel before år
+In the Swedish locale: år before ängel

References

See also

+ + + +
compares two strings in accordance to the current locale
(function)
+
(C95)
 transform a wide string so that wcscmp would produce the same result as wcscoll
(function)
+
(C95)
 compares two wide strings
(function)
C++ documentation for wcscoll
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/wcscoll +

+
diff --git a/devdocs/c/string%2Fwide%2Fwcscpy.html b/devdocs/c/string%2Fwide%2Fwcscpy.html new file mode 100644 index 00000000..0242fb59 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcscpy.html @@ -0,0 +1,70 @@ +

wcscpy, wcscpy_s

Defined in header <wchar.h>
(1) 
wchar_t* wcscpy( wchar_t* dest, const wchar_t* src );
+		 (since C95)
(until C99) 
wchar_t* wcscpy( wchar_t* restrict dest, const wchar_t* restrict src );
+		 (since C99) 
errno_t wcscpy_s( wchar_t* restrict dest, rsize_t destsz,
+                  const wchar_t* restrict src );
+		 (2) (since C11)
+1) Copies the wide string pointed to by src (including the terminating null wide character) to wide character array pointed to by dest. The behavior is undefined if the dest array is not large enough. The behavior is undefined if the strings overlap.
+2) Same as (1), except that it may clobber the rest of the destination array with unspecified values and that the following errors are detected at runtime and call the currently installed constraint handler function:
+
+
    +
  • src or dest is a null pointer
    • +
  • destsz is zero or greater than RSIZE_MAX / sizeof(wchar_t)
    • +
  • destsz is less or equal wcsnlen_s(src, destsz), in other words, truncation would occur
    • +
  • overlap would occur between the source and the destination strings
    • +
+
As with all bounds-checked functions, wcscpy_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <wchar.h>.
+
+

Parameters

+ + + +
dest - pointer to the wide character array to copy to
src - pointer to the null-terminated wide string to copy from
destsz - maximum number of characters to write, typically the size of the destination buffer

Return value

+1) returns a copy of dest +
+2) returns zero on success, returns non-zero on error. Also, on error, writes L'\0' to dest[0] (unless dest is a null pointer or destsz is zero or greater than RMAX_SIZE / sizeof(wchar_t)).

Example

#include <locale.h>
+#include <stdio.h>
+#include <wchar.h>
+ 
+int main(void)
+{
+    wchar_t* src = L"犬 means dog";
+//  src[0] = L'狗' ; // this would be undefined behavior
+    wchar_t dst[wcslen(src) + 1]; // +1 for the null terminator
+    wcscpy(dst, src);
+    dst[0] = L'狗'; // OK
+ 
+    setlocale(LC_ALL, "en_US.utf8");
+    printf("src = %ls\ndst = %ls\n", src, dst);
+}

Output:

+
src = 犬 means dog
+dst = 狗 means dog

References

See also

+ + + +
+
(C95)(C11)
 copies a certain amount of wide characters from one string to another
(function)
+
(C95)(C11)
 copies a certain amount of wide characters between two non-overlapping arrays
(function)
+
(C11)
 copies one string to another
(function)
C++ documentation for wcscpy
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/wcscpy +

+
diff --git a/devdocs/c/string%2Fwide%2Fwcscspn.html b/devdocs/c/string%2Fwide%2Fwcscspn.html new file mode 100644 index 00000000..2cafb850 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcscspn.html @@ -0,0 +1,39 @@ +

wcscspn

Defined in header <wchar.h> 
size_t wcscspn( const wchar_t* dest, const wchar_t* src );
+		 (since C95)

Returns the length of the maximum initial segment of the wide string pointed to by dest, that consists of only the characters not found in wide string pointed to by src.

+

Parameters

+ + +
dest - pointer to the null-terminated wide string to be analyzed
src - pointer to the null-terminated wide string that contains the characters to search for

Return value

The length of the maximum initial segment that contains only characters not found in the character string pointed to by src

+

Example

#include <locale.h>
+#include <wchar.h>
+ 
+int main(void)
+{
+    wchar_t dest[] = L"白猫 黑狗 甲虫";
+    /*                      └───┐   */
+    const wchar_t *src = L"甲虫,黑狗";
+ 
+    const size_t len = wcscspn(dest, src);
+    dest[len] = L'\0'; /* terminates the segment to print it out */
+ 
+    setlocale(LC_ALL, "en_US.utf8");
+    wprintf(L"The length of maximum initial segment is %td.\n"
+            L"The segment is \"%ls\".\n", len, dest);
+}

Output:

+
The length of maximum initial segment is 3.
+The segment is "白猫 ".

References

See also

+ + +
+
(C95)
 returns the length of the maximum initial segment that consists
of only the wide characters found in another wide string
(function)
+
(C95)
 finds the first location of any wide character in one wide string, in another wide string
(function)
C++ documentation for wcscspn
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/wcscspn +

+
diff --git a/devdocs/c/string%2Fwide%2Fwcslen.html b/devdocs/c/string%2Fwide%2Fwcslen.html new file mode 100644 index 00000000..efb4dde8 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcslen.html @@ -0,0 +1,38 @@ +

wcslen, wcsnlen_s

Defined in header <wchar.h> 
size_t wcslen( const wchar_t *str );
+		 (1) (since C95) 
size_t wcsnlen_s(const wchar_t *str, size_t strsz);
+		 (2) (since C11)
+1) Returns the length of a wide string, that is the number of non-null wide characters that precede the terminating null wide character.
+2) Same as (1), except that the function returns zero if str is a null pointer and returns strsz if the null wide character was not found in the first strsz wide characters of src As with all bounds-checked functions, wcslen_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <stdio.h>..

Parameters

+ + +
str - pointer to the null-terminated wide string to be examined
strsz - maximum number of wide characters to examine

Return value

+1) The length of the null-terminated wide string str.
+2) The length of the null-terminated wide string str on success, zero if str is a null pointer, strsz if the null wide character was not found.

Notes

strnlen_s and wcsnlen_s are the only bounds-checked functions that do not invoke the runtime constraints handler. They are pure utility functions used to provide limited support for non-null terminated strings.

+

Example

#include <wchar.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    wchar_t str[] = L"How many wide characters does this string contain?";
+ 
+    printf("without null character: %zu\n", wcslen(str));
+    printf("with null character: %zu\n", sizeof str / sizeof *str);
+}

Output:

+
without null character: 50
+with null character: 51

References

See also

+ +
+
(C11)
 returns the length of a given string
(function)
C++ documentation for wcslen
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/wcslen +

+
diff --git a/devdocs/c/string%2Fwide%2Fwcsncat.html b/devdocs/c/string%2Fwide%2Fwcsncat.html new file mode 100644 index 00000000..17540682 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcsncat.html @@ -0,0 +1,67 @@ +

wcsncat, wcsncat_s

Defined in header <wchar.h>
(1) 
wchar_t *wcsncat( wchar_t *dest, const wchar_t *src, size_t count );
+		 (since C95)
(until C99) 
wchar_t *wcsncat( wchar_t *restrict dest,
+                  const wchar_t *restrict src, size_t count );
+		 (since C99) 
errno_t wcsncat_s( wchar_t *restrict dest, rsize_t destsz,
+                   const wchar_t *restrict src, rsize_t count );
+		 (2) (since C11)
+1) Appends at most count wide characters from the wide string pointed to by src, stopping if the null terminator is copied, to the end of the character string pointed to by dest. The wide character src[0] replaces the null terminator at the end of dest. The null terminator is always appended in the end (so the maximum number of wide characters the function may write is count+1).
+ The behavior is undefined if the destination array is not large enough for the contents of both str and dest and the terminating null wide character.
+ The behavior is undefined if the strings overlap.
+2) Same as (1), except that this function may clobber the remainder of the destination array (from the last wide character written to destsz) and that the following errors are detected at runtime and call the currently installed constraint handler function:
+
+
    +
  • src or dest is a null pointer
    • +
  • destsz or count is zero or greater than RSIZE_MAX/sizeof(wchar_t)
    • +
  • there is no null wide character in the first destsz wide characters of dest
    • +
  • truncation would occur: count or the length of src, whichever is less, exceeds the space available between the null terminator of dest and destsz.
    • +
  • overlap would occur between the source and the destination strings
    • +
+
As with all bounds-checked functions, wcsncat_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <wchar.h>.
+
+

Parameters

+ + + + +
dest - pointer to the null-terminated wide string to append to
src - pointer to the null-terminated wide string to copy from
count - maximum number of wide characters to copy
destsz - the size of the destination buffer

Return value

+1) returns a copy of dest +
+2) returns zero on success, returns non-zero on error. Also, on error, writes L'\0' to dest[0] (unless dest is a null pointer or destsz is zero or greater than RSIZE_MAX/sizeof(wchar_t)).

Notes

Although truncation to fit the destination buffer is a security risk and therefore a runtime constraints violation for wcsncat_s, it is possible to get the truncating behavior by specifying count equal to the size of the destination array minus one: it will copy the first count wide characters and append the null terminator as always: wcsncat_s(dst, sizeof dst/sizeof *dst, src, (sizeof dst/sizeof *dst)-wcsnlen_s(dst, sizeof dst/sizeof *dst)-1);

+

Example

#include <wchar.h> 
+#include <stdio.h>
+#include <locale.h>
+ 
+int main(void) 
+{
+    wchar_t str[50] = L"Земля, прощай.";
+    wcsncat(str, L" ", 1);
+    wcsncat(str, L"В добрый путь.", 8); // only append the first 8 wide chars
+    setlocale(LC_ALL, "en_US.utf8");
+    printf("%ls", str);
+}

Possible output:

+
Земля, прощай. В добрый

References

See also

+ + + +
+
(C95)(C11)
 appends a copy of one wide string to another
(function)
+
(C11)
 concatenates a certain amount of characters of two strings
(function)
+
(C95)(C11)
 copies one wide string to another
(function)
C++ documentation for wcsncat
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/wcsncat +

+
diff --git a/devdocs/c/string%2Fwide%2Fwcsncmp.html b/devdocs/c/string%2Fwide%2Fwcsncmp.html new file mode 100644 index 00000000..33c62955 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcsncmp.html @@ -0,0 +1,56 @@ +

wcsncmp

Defined in header <wchar.h> 
int wcsncmp( const wchar_t* lhs, const wchar_t* rhs, size_t count );
+		 (since C95)

Compares at most count wide characters of two null-terminated wide strings. The comparison is done lexicographically.

+

The sign of the result is the sign of the difference between the values of the first pair of wide characters that differ in the strings being compared.

+

The behavior is undefined if lhs or rhs are not pointers to null-terminated strings.

+

Parameters

+ + +
lhs, rhs - pointers to the null-terminated wide strings to compare
count - maximum number of characters to compare

Return value

Negative value if lhs appears before rhs in lexicographical order.

+

Zero if lhs and rhs compare equal.

+

Positive value if lhs appears after rhs in lexicographical order.

+

Notes

This function is not locale-sensitive, unlike wcscoll and wcsxfrm.

+

Example

#include <stdio.h>
+#include <wchar.h>
+#include <locale.h>
+ 
+void demo(const wchar_t *lhs, const wchar_t *rhs, int sz)
+{
+    int rc = wcsncmp(lhs, rhs, sz);
+    if(rc == 0)
+        printf("First %d characters of [%ls] equal [%ls]\n", sz, lhs, rhs);
+    else if(rc < 0)
+        printf("First %d characters of [%ls] precede [%ls]\n", sz, lhs, rhs);
+    else if(rc > 0)
+        printf("First %d characters of [%ls] follow [%ls]\n", sz, lhs, rhs);
+}
+ 
+int main(void)
+{
+    const wchar_t *str1 = L"안녕하세요";
+    const wchar_t *str2 = L"안녕히 가십시오";
+ 
+    setlocale(LC_ALL, "en_US.utf8");
+    demo(str1, str2, 5);
+    demo(str2, str1, 8);
+    demo(str1, str2, 2);
+}

Output:

+
First 5 characters of [안녕하세요] precede [안녕히 가십시오]
+First 8 characters of [안녕히 가십시오] follow [안녕하세요]
+First 2 characters of [안녕하세요] equal [안녕히 가십시오]

References

See also

+ + + +
+
(C95)
 compares two wide strings
(function)
+
(C95)
 compares a certain amount of wide characters from two arrays
(function)
+
(C95)
 compares two wide strings in accordance to the current locale
(function)
C++ documentation for wcsncmp
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/wcsncmp +

+
diff --git a/devdocs/c/string%2Fwide%2Fwcsncpy.html b/devdocs/c/string%2Fwide%2Fwcsncpy.html new file mode 100644 index 00000000..7cc3efa4 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcsncpy.html @@ -0,0 +1,76 @@ +

wcsncpy, wcsncpy_s

Defined in header <wchar.h>
(1) 
wchar_t* wcsncpy( wchar_t* dest, const wchar_t* src, size_t count );
+		 (since C95)
(until C99) 
wchar_t *wcsncpy( wchar_t *restrict dest, const wchar_t *restrict src, size_t count );
+		 (since C99) 
errno_t wcsncpy_s( wchar_t *restrict dest, rsize_t destsz,
+                   const wchar_t *restrict src, rsize_t count);
+		 (2) (since C11)
+1) Copies at most count characters of the wide string pointed to by src (including the terminating null wide character) to wide character array pointed to by dest.
+ If count is reached before the entire string src was copied, the resulting wide character array is not null-terminated.
+ If, after copying the terminating null wide character from src, count is not reached, additional null wide characters are written to dest until the total of count characters have been written.
+ If the strings overlap, the behavior is undefined.
+2) Same as (1), except that the function does not continue writing zeroes into the destination array to pad up to count, it stops after writing the terminating null character (if there was no null in the source, it writes one at dest[count] and then stops). Also, the following errors are detected at runtime and call the currently installed constraint handler function:
+
+
    +
  • src or dest is a null pointer
    • +
  • destsz or count is zero or greater than RSIZE_MAX/sizeof(wchar_t)
    • +
  • count is greater or equal destsz, but destsz is less or equal wcsnlen_s(src, count), in other words, truncation would occur
    • +
  • overlap would occur between the source and the destination strings
    • +
+
As with all bounds-checked functions, wcsncpy_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <wchar.h>.
+
+

Parameters

+ + + + +
dest - pointer to the wide character array to copy to
src - pointer to the wide string to copy from
count - maximum number of wide characters to copy
destsz - the size of the destination buffer

Return value

+1) returns a copy of dest +
+2) returns zero on success, returns non-zero on error. Also, on error, writes L'\0' to dest[0] (unless dest is a null pointer or destsz is zero or greater than RSIZE_MAX/sizeof(wchar_t)) and may clobber the rest of the destination array with unspecified values.

Notes

In typical usage, count is the number of elements in the destination array.

+

Although truncation to fit the destination buffer is a security risk and therefore a runtime constraints violation for wcsncpy_s, it is possible to get the truncating behavior by specifying count equal to the size of the destination array minus one: it will copy the first count wide characters and append the null wide terminator as always: wcsncpy_s(dst, sizeof dst / sizeof *dst, src, (sizeof dst / sizeof *dst)-1);

+

Example

#include <stdio.h>
+#include <wchar.h>
+#include <locale.h>
+ 
+int main(void)
+{
+    const wchar_t src[] = L"わゐ";
+    wchar_t dest[6] = {L'あ', L'い', L'う', L'え', L'お'};
+ 
+    wcsncpy(dest, src, 4); // this will copy わゐ and repeat L'\0' two times
+ 
+    puts("The contents of dest are: ");
+    setlocale(LC_ALL, "en_US.utf8");
+ 
+    const long dest_size = sizeof dest / sizeof *dest;
+    for(wchar_t* p = dest; p-dest != dest_size; ++p) {
+        *p ? printf("%lc ", *p)
+           : printf("\\0 ");
+    }
+}

Possible output:

+
The contents of dest are: 
+わ ゐ \0 \0 お \0

References

See also

+ + + +
+
(C95)(C11)
 copies one wide string to another
(function)
+
(C95)(C11)
 copies a certain amount of wide characters between two non-overlapping arrays
(function)
+
(C11)
 copies a certain amount of characters from one string to another
(function)
C++ documentation for wcsncpy
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/wcsncpy +

+
diff --git a/devdocs/c/string%2Fwide%2Fwcspbrk.html b/devdocs/c/string%2Fwide%2Fwcspbrk.html new file mode 100644 index 00000000..f6d7a55a --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcspbrk.html @@ -0,0 +1,47 @@ +

wcspbrk

Defined in header <wchar.h> 
wchar_t *wcspbrk( const wchar_t *dest, const wchar_t *str );
+		 (1) (since C95) 
/*QWchar_t*/ *wcspbrk( /*QWchar_t*/ *dest, const wchar_t *str );
+		 (2) (since C23)
+1) Finds the first character in wide string pointed to by dest, that is also in wide string pointed to by str.
+2) Type-generic function equivalent to (1). Let T be an unqualified wide character object type. If a macro definition of each of these generic functions is suppressed to access an actual function (e.g. if (wcspbrk) or a function pointer is used), the actual function declaration (1) becomes visible.

Parameters

+ + +
dest - pointer to the null-terminated wide string to be analyzed
src - pointer to the null-terminated wide string that contains the characters to search for

Return value

Pointer to the first character in dest, that is also in str, or a null pointer if no such character exists.

+

Notes

The name stands for "wide character string pointer break", because it returns a pointer to the first of the separator ("break") characters.

+

Example

#include <stdio.h>
+#include <wchar.h>
+ 
+int main(void)
+{
+    const wchar_t* str = L"Hello world, friend of mine!";
+    const wchar_t* sep = L" ,!";
+ 
+    unsigned int cnt = 0;
+    do {
+       str = wcspbrk(str, sep); // find separator
+       if (str) str += wcsspn(str, sep); // skip separator
+       ++cnt; // increment word count
+    } while (str && *str);
+ 
+    wprintf(L"There are %u words.\n", cnt);
+}

Output:

+
There are 5 words.

References

See also

+ + + +
+
(C95)
 returns the length of the maximum initial segment that consists
of only the wide chars not found in another wide string
(function)
+
(C95)
 finds the first occurrence of a wide character in a wide string
(function)
finds the first location of any character in one string, in another string
(function)
C++ documentation for wcspbrk
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/wcspbrk +

+
diff --git a/devdocs/c/string%2Fwide%2Fwcsrchr.html b/devdocs/c/string%2Fwide%2Fwcsrchr.html new file mode 100644 index 00000000..7cfeb461 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcsrchr.html @@ -0,0 +1,51 @@ +

wcsrchr

Defined in header <wchar.h> 
wchar_t *wcsrchr( const wchar_t *str, wchar_t ch );
+		 (1) (since C95) 
/*QWchar_t*/ *wcsrchr( /*QWchar_t*/ *str, wchar_t ch );
+		 (2) (since C23)
+1) Finds the last occurrence of the wide character ch in the wide string pointed to by str.
+2) Type-generic function equivalent to (1). Let T be an unqualified wide character object type. If a macro definition of each of these generic functions is suppressed to access an actual function (e.g. if (wcsrchr) or a function pointer is used), the actual function declaration (1) becomes visible.

Parameters

+ + +
str - pointer to the null-terminated wide string to be analyzed
ch - wide character to search for

Return value

Pointer to the found character in str, or a null pointer if no such character is found.

+

Example

#include <locale.h>
+#include <stdio.h>
+#include <wchar.h>
+ 
+int main(void)
+{
+    wchar_t arr[] = L"白猫 黒猫 кошки";
+    wchar_t *cat = wcsrchr(arr, L'猫');
+    wchar_t *dog = wcsrchr(arr, L'犬');
+ 
+    setlocale(LC_ALL, "en_US.utf8");
+ 
+    cat ? printf("The character 猫 found at position %td\n", cat - arr)
+        : puts("The character 猫 not found");
+ 
+    dog ? printf("The character 犬 found at position %td\n", dog - arr)
+        : puts("The character 犬 not found");
+}

Output:

+
The character 猫 found at position 4
+The character 犬 not found

References

See also

+ + +
+
(C95)
 finds the first occurrence of a wide character in a wide string
(function)
+
(C95)
 finds the first location of any wide character in one wide string, in another wide string
(function)
C++ documentation for wcsrchr
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/wcsrchr +

+
diff --git a/devdocs/c/string%2Fwide%2Fwcsspn.html b/devdocs/c/string%2Fwide%2Fwcsspn.html new file mode 100644 index 00000000..1fc9c8b2 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcsspn.html @@ -0,0 +1,37 @@ +

wcsspn

Defined in header <wchar.h> 
size_t wcsspn( const wchar_t* dest, const wchar_t* src );
+		 (since C95)

Returns the length of the maximum initial segment of the wide string pointed to by dest, that consists of only the characters found in wide string pointed to by src.

+

Parameters

+ + +
dest - pointer to the null-terminated wide string to be analyzed
src - pointer to the null-terminated wide string that contains the characters to search for

Return value

The length of the maximum initial segment that contains only characters from wide string pointed to by src

+

Example

#include <locale.h>
+#include <wchar.h>
+ 
+int main(void)
+{
+    wchar_t dest[] = L"白猫 黑狗 甲虫";
+    const wchar_t src[] = L" 狗猫 白黑 ";
+    const size_t len = wcsspn(dest, src);
+    dest[len] = L'\0'; /* terminates the segment to print it out */
+ 
+    setlocale(LC_ALL, "en_US.utf8");
+    wprintf(L"The length of maximum initial segment is %td.\n"
+            L"The segment is \"%ls\".\n", len, dest);
+}

Output:

+
The length of maximum initial segment is 6.
+The segment is "白猫 黑狗 ".

References

See also

+ + +
+
(C95)
 returns the length of the maximum initial segment that consists
of only the wide chars not found in another wide string
(function)
+
(C95)
 finds the first location of any wide character in one wide string, in another wide string
(function)
C++ documentation for wcsspn
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/wcsspn +

+
diff --git a/devdocs/c/string%2Fwide%2Fwcsstr.html b/devdocs/c/string%2Fwide%2Fwcsstr.html new file mode 100644 index 00000000..d6afb5a4 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcsstr.html @@ -0,0 +1,50 @@ +

wcsstr

Defined in header <wchar.h> 
wchar_t *wcsstr( const wchar_t *dest, const wchar_t *src );
+		 (1) (since C95) 
/*QWchar_t*/ *wcsstr( /*QWchar_t*/ *dest, const wchar_t *src );
+		 (2) (since C23)
+1) Finds the first occurrence of the wide string src in the wide string pointed to by dest. The terminating null characters are not compared.
+2) Type-generic function equivalent to (1). Let T be an unqualified wide character object type. If a macro definition of each of these generic functions is suppressed to access an actual function (e.g. if (wcsstr) or a function pointer is used), the actual function declaration (1) becomes visible.

Parameters

+ + +
dest - pointer to the null-terminated wide string to examine
src - pointer to the null-terminated wide string to search for

Return value

Pointer to the first character of the found substring in dest, or a null pointer if no such substring is found. If src points to an empty string, dest is returned.

+

Example

#include <stdio.h>
+#include <locale.h>
+#include <wchar.h>
+ 
+int main(void)
+{
+    setlocale(LC_ALL, "ru_RU.UTF-8");
+ 
+    wchar_t str[5][64] = {
+        L"Строка, где есть подстрока 'но'.",
+        L"Строка, где такой подстроки нет.",
+        L"Он здесь.",
+        L"Здесь он.",
+        L"Его нет."
+    };
+ 
+    for (size_t i = 0; i < 5; ++i) {
+        if (wcsstr(str[i], L"но")) {
+            wprintf(L"%ls\n", str[i]);
+        }
+    }
+}

Output:

+
Строка, где есть подстрока 'но'.

References

See also

+ + +
+
(C95)
 finds the first occurrence of a wide character in a wide string
(function)
+
(C95)
 finds the last occurrence of a wide character in a wide string
(function)
C++ documentation for wcsstr
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/wcsstr +

+
diff --git a/devdocs/c/string%2Fwide%2Fwcstof.html b/devdocs/c/string%2Fwide%2Fwcstof.html new file mode 100644 index 00000000..30bf2d82 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcstof.html @@ -0,0 +1,77 @@ +

wcstof, wcstod, wcstold

Defined in header <wchar.h> 
float       wcstof( const wchar_t * restrict str, wchar_t ** restrict str_end );
+		 (since C99) 
double      wcstod( const wchar_t * str, wchar_t ** str_end );
 +(since C95)
(until C99) +		 
double      wcstod( const wchar_t * restrict str, wchar_t ** restrict str_end );
+		 (since C99) 
long double wcstold( const wchar_t * restrict str, wchar_t ** restrict str_end );
+		 (since C99)

Interprets a floating point value in a wide string pointed to by str.

+

Function discards any whitespace characters (as determined by iswspace) until first non-whitespace character is found. Then it takes as many characters as possible to form a valid floating-point representation and converts them to a floating-point value. The valid floating-point value can be one of the following:

+ + +
    +
  • hexadecimal floating-point expression. It consists of the following parts:
    • +
      +
    • (optional) plus or minus sign
      • +
    • 0x or 0X
      • +
    • nonempty sequence of hexadecimal digits optionally containing a decimal-point character (as determined by the current C locale) (defines significand)
      • +
    • (optional) p or P followed with optional minus or plus sign and nonempty sequence of decimal digits (defines exponent to base 2)
      • +
    +
  • infinity expression. It consists of the following parts:
    • +
      +
    • (optional) plus or minus sign
      • +
    • INF or INFINITY ignoring case
      • +
    +
  • not-a-number expression. It consists of the following parts:
    • +
      +
    • (optional) plus or minus sign
      • +
    • NAN or NAN(char_sequence) ignoring case of the NAN part. char_sequence can only contain digits, Latin letters, and underscores. The result is a quiet NaN floating-point value.
      • +
    +
 (since C99)

The functions sets the pointer pointed to by str_end to point to the wide character past the last character interpreted. If str_end is a null pointer, it is ignored.

+

Parameters

+ + +
str - pointer to the null-terminated wide string to be interpreted
str_end - pointer to a pointer to a wide character.

Return value

Floating point value corresponding to the contents of str on success. If the converted value falls out of range of corresponding return type, range error occurs and HUGE_VAL, HUGE_VALF or HUGE_VALL is returned. If no conversion can be performed, ​0​ is returned.

+

Example

#include <stdio.h>
+#include <errno.h>
+#include <wchar.h>
+ 
+int main(void)
+{
+    const wchar_t *p = L"111.11 -2.22 0X1.BC70A3D70A3D7P+6  1.18973e+4932zzz";
+    printf("Parsing L\"%ls\":\n", p);
+    wchar_t *end;
+    for (double f = wcstod(p, &end); p != end; f = wcstod(p, &end))
+    {
+        printf("'%.*ls' -> ", (int)(end-p), p);
+        p = end;
+        if (errno == ERANGE){
+            printf("range error, got ");
+            errno = 0;
+        }
+        printf("%f\n", f);
+    }
+}

Output:

+
Parsing L"111.11 -2.22 0X1.BC70A3D70A3D7P+6  1.18973e+4932zzz":
+'111.11' -> 111.110000
+' -2.22' -> -2.220000
+' 0X1.BC70A3D70A3D7P+6' -> 111.110000
+'  1.18973e+4932' -> range error, got inf

References

See also

+ +
+
(C99)(C99)
 converts a byte string to a floating point value
(function)
C++ documentation for wcstof, wcstod, wcstold
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/wcstof +

+
diff --git a/devdocs/c/string%2Fwide%2Fwcstoimax.html b/devdocs/c/string%2Fwide%2Fwcstoimax.html new file mode 100644 index 00000000..f5e07d38 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcstoimax.html @@ -0,0 +1,69 @@ +

wcstoimax, wcstoumax

Defined in header <inttypes.h> 
intmax_t wcstoimax( const wchar_t *restrict nptr, 
+                    wchar_t **restrict endptr, int base );
+		 (since C99) 
uintmax_t wcstoumax( const wchar_t *restrict nptr,
+                     wchar_t **restrict endptr, int base );
+		 (since C99)

Interprets an unsigned integer value in a wide string pointed to by nptr.

+

Discards any whitespace characters (as identified by calling iswspace) until the first non-whitespace character is found, then takes as many characters as possible to form a valid base-n (where n=base) unsigned integer number representation and converts them to an integer value. The valid unsigned integer value consists of the following parts:

+

The set of valid values for base is {0,2,3,...,36}. The set of valid digits for base-2 integers is {0,1}, for base-3 integers is {0,1,2}, and so on. For bases larger than 10, valid digits include alphabetic characters, starting from Aa for base-11 integer, to Zz for base-36 integer. The case of the characters is ignored.

+

Additional numeric formats may be accepted by the currently installed C locale.

+

If the value of base is ​0​, the numeric base is auto-detected: if the prefix is 0, the base is octal, if the prefix is 0x or 0X, the base is hexadecimal, otherwise the base is decimal.

+

If the minus sign was part of the input sequence, the numeric value calculated from the sequence of digits is negated as if by unary minus in the result type, which applies unsigned integer wraparound rules.

+

The functions sets the pointer pointed to by endptr to point to the wide character past the last character interpreted. If endptr is a null pointer, it is ignored.

+

Parameters

+ + + +
nptr - pointer to the null-terminated wide string to be interpreted
endptr - pointer to a pointer to a wide character.
base - base of the interpreted integer value

Return value

Integer value corresponding to the contents of str on success. If the converted value falls out of range of corresponding return type, range error occurs and INTMAX_MAX, INTMAX_MIN, UINTMAX_MAX, or ​0​ is returned, as appropriate. If no conversion can be performed, ​0​ is returned.

+

Example

#include <errno.h>
+#include <inttypes.h>
+#include <stdio.h>
+#include <string.h>
+#include <wchar.h>
+ 
+int main(void)
+{
+  wchar_t* endptr;
+ 
+  wprintf(L"%ld\n", wcstoimax(L" -123junk", &endptr, 10)); /* base 10                    */
+  wprintf(L"%ld\n", wcstoimax(L"11111111", &endptr, 2));   /* base 2                     */
+  wprintf(L"%ld\n", wcstoimax(L"XyZ", &endptr, 36));       /* base 36                    */
+  wprintf(L"%ld\n", wcstoimax(L"010", &endptr, 0));        /* octal auto-detection       */
+  wprintf(L"%ld\n", wcstoimax(L"10", &endptr, 0));         /* decimal auto-detection     */
+  wprintf(L"%ld\n", wcstoimax(L"0x10", &endptr, 0));       /* hexadecimal auto-detection */
+ 
+  /* range error             */
+  /* LONG_MAX+1 --> LONG_MAX */
+  errno = 0;
+  wprintf(L"%ld\n", wcstoimax(L"9223372036854775808", &endptr, 10));
+  wprintf(L"%s\n", strerror(errno));
+}

Output:

+
-123
+255
+44027
+8
+10
+16
+9223372036854775807
+Numerical result out of range

References

See also

+ + + +
+
(C99)(C99)
 converts a byte string to intmax_t or uintmax_t
(function)
+
(C95)(C99)
 converts a wide string to an integer value
(function)
+
(C95)(C99)
 converts a wide string to an unsigned integer value
(function)
C++ documentation for wcstoimax, wcstoumax
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/wcstoimax +

+
diff --git a/devdocs/c/string%2Fwide%2Fwcstok.html b/devdocs/c/string%2Fwide%2Fwcstok.html new file mode 100644 index 00000000..fe2e5786 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcstok.html @@ -0,0 +1,80 @@ +

wcstok, wcstok_s

Defined in header <wchar.h>
(1) 
wchar_t* wcstok( wchar_t* str, const wchar_t* delim, wchar_t **ptr );
+		 (since C95)
(until C99) 
wchar_t *wcstok(wchar_t * restrict str, const wchar_t * restrict delim,
+                wchar_t **restrict ptr);
+		 (since C99) 
wchar_t *wcstok_s( wchar_t *restrict str, rsize_t *restrict strmax,
+                   const wchar_t *restrict delim, wchar_t **restrict ptr);
+		 (2) (since C11)
+1) Finds the next token in a null-terminated wide string pointed to by str. The separator characters are identified by null-terminated wide string pointed to by delim.
+ This function is designed to be called multiples times to obtain successive tokens from the same string.
+2) Same as (1), except that on every step, writes the number of characters left to see in str into *strmax. Repeat calls (with null str) must pass both strmax and ptr with the values stored by the previous call. Also, the following errors are detected at runtime and call the currently installed constraint handler function, without storing anything in the object pointed to by ptr
+
+
    +
  • strmax, delim, or ptr is a null pointer
    • +
  • on a non-initial call (with null str), *ptr is a null pointer
    • +
  • on the first call, *strmax is zero or greater than RSIZE_MAX/sizeof(wchar_t)
    • +
  • search for the end of a token reaches the end of the source string (as measured by the initial value of *strmax)) without encountering the null terminator
    • +
+
As all bounds-checked functions, wcstok_s is only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including wchar.h.
+
+

Parameters

+ + + + +
str - pointer to the null-terminated wide string to tokenize
delim - pointer to the null-terminated wide string identifying delimiters
ptr - pointer to an object of type wchar_t*, which is used by both wcstok and wcstok_s to store the internal state of the parser
strmax - pointer to an object which initially holds the size of str: wcstok_s stores the number of characters that remain to be examined

Return value

Returns pointer to the beginning of the next token or null pointer if there are no more tokens.

+

Note

This function is destructive: it writes the L'\0' characters in the elements of the string str. In particular, a wide string literal cannot be used as the first argument of wcstok.

+

Unlike strtok, wcstok does not update static storage: it stores the parser state in the user-provided location.

+

Unlike most other tokenizers, the delimiters in wcstok can be different for each subsequent token, and can even depend on the contents of the previous tokens.

+

Example

#include <wchar.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    wchar_t input[] = L"A bird came down the walk";
+    printf("Parsing the input string '%ls'\n", input);
+    wchar_t *buffer;
+    wchar_t *token = wcstok(input, L" ", &buffer);
+    while(token) {
+        printf("%ls\n", token);
+        token = wcstok(NULL, L" ", &buffer);
+    }
+ 
+    printf("Contents of the input string now: '");
+    for(size_t n = 0; n < sizeof input / sizeof *input; ++n)
+        input[n] ? printf("%lc", input[n]) : printf("\\0");
+    puts("'");
+}

Output:

+
Parsing the input string 'A bird came down the walk'
+A
+bird
+came
+down
+the
+walk
+Contents of the input string now: 'A\0bird\0came\0down\0the\0walk\0'

References

See also

+ +
+
(C11)
 finds the next token in a byte string
(function)
C++ documentation for wcstok
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/wcstok +

+
diff --git a/devdocs/c/string%2Fwide%2Fwcstol.html b/devdocs/c/string%2Fwide%2Fwcstol.html new file mode 100644 index 00000000..d9da4632 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcstol.html @@ -0,0 +1,65 @@ +

wcstol, wcstoll

Defined in header <wchar.h> 
long      wcstol( const wchar_t * str, wchar_t ** str_end, int base );
 +(since C95)
(until C99) +		 
long      wcstol( const wchar_t * restrict str, wchar_t ** restrict str_end,
+                  int base );
+		 (since C99) 
long long wcstoll( const wchar_t * restrict str, wchar_t ** restrict str_end,
+                   int base );
+		 (since C99)

Interprets an integer value in a wide string pointed to by str.

+

Discards any whitespace characters (as identified by calling iswspace) until the first non-whitespace character is found, then takes as many characters as possible to form a valid base-n (where n=base) integer number representation and converts them to an integer value. The valid integer value consists of the following parts:

+

The set of valid values for base is {0,2,3,...,36}. The set of valid digits for base-2 integers is {0,1}, for base-3 integers is {0,1,2}, and so on. For bases larger than 10, valid digits include alphabetic characters, starting from Aa for base-11 integer, to Zz for base-36 integer. The case of the characters is ignored.

+

Additional numeric formats may be accepted by the currently installed C locale.

+

If the value of base is ​0​, the numeric base is auto-detected: if the prefix is 0, the base is octal, if the prefix is 0x or 0X, the base is hexadecimal, otherwise the base is decimal.

+

If the minus sign was part of the input sequence, the numeric value calculated from the sequence of digits is negated as if by unary minus in the result type.

+

The functions sets the pointer pointed to by str_end to point to the wide character past the last character interpreted. If str_end is a null pointer, it is ignored.

+

Parameters

+ + + +
str - pointer to the null-terminated wide string to be interpreted
str_end - pointer to a pointer to wide character
base - base of the interpreted integer value

Return value

Integer value corresponding to the contents of str on success. If the converted value falls out of range of corresponding return type, range error occurs and LONG_MAX, LONG_MIN, LLONG_MAX or LLONG_MIN is returned. If no conversion can be performed, ​0​ is returned.

+

Example

#include <stdio.h>
+#include <errno.h>
+#include <wchar.h>
+ 
+int main(void)
+{
+    const wchar_t *p = L"10 200000000000000000000000000000 30 -40";
+    printf("Parsing L'%ls':\n", p);
+    wchar_t *end;
+    for (long i = wcstol(p, &end, 10);
+         p != end;
+         i = wcstol(p, &end, 10))
+    {
+        printf("'%.*ls' -> ", (int)(end-p), p);
+        p = end;
+        if (errno == ERANGE){
+            printf("range error, got ");
+            errno = 0;
+        }
+        printf("%ld\n", i);
+    }
+}

Output:

+
Parsing L'10 200000000000000000000000000000 30 -40':
+'10' -> 10
+' 200000000000000000000000000000' -> range error, got 9223372036854775807
+' 30' -> 30
+' -40' -> -40

References

See also

+ + +
+
(C99)
 converts a byte string to an integer value
(function)
+
(C95)(C99)
 converts a wide string to an unsigned integer value
(function)
C++ documentation for wcstol, wcstoll
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/wcstol +

+
diff --git a/devdocs/c/string%2Fwide%2Fwcstoul.html b/devdocs/c/string%2Fwide%2Fwcstoul.html new file mode 100644 index 00000000..2740a717 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcstoul.html @@ -0,0 +1,65 @@ +

wcstoul, wcstoull

Defined in header <wchar.h> 
unsigned long      wcstoul( const wchar_t* str, wchar_t** str_end, int base );
 +(since C95)
(until C99) +		 
unsigned long      wcstoul( const wchar_t * restrict str,
+                            wchar_t ** restrict str_end, int base );
+		 (since C99) 
unsigned long long wcstoull( const wchar_t * restrict str,
+                             wchar_t ** restrict str_end, int base );
+		 (since C99)

Interprets an unsigned integer value in a wide string pointed to by str.

+

Discards any whitespace characters (as identified by calling iswspace) until the first non-whitespace character is found, then takes as many characters as possible to form a valid base-n (where n=base) unsigned integer number representation and converts them to an integer value. The valid unsigned integer value consists of the following parts:

+

The set of valid values for base is {0,2,3,...,36}. The set of valid digits for base-2 integers is {0,1}, for base-3 integers is {0,1,2}, and so on. For bases larger than 10, valid digits include alphabetic characters, starting from Aa for base-11 integer, to Zz for base-36 integer. The case of the characters is ignored.

+

Additional numeric formats may be accepted by the currently installed C locale.

+

If the value of base is ​0​, the numeric base is auto-detected: if the prefix is 0, the base is octal, if the prefix is 0x or 0X, the base is hexadecimal, otherwise the base is decimal.

+

If the minus sign was part of the input sequence, the numeric value calculated from the sequence of digits is negated as if by unary minus in the result type, which applies unsigned integer wraparound rules.

+

The functions sets the pointer pointed to by str_end to point to the wide character past the last character interpreted. If str_end is a null pointer, it is ignored.

+

Parameters

+ + + +
str - pointer to the null-terminated wide string to be interpreted
str_end - pointer to a pointer to a wide character.
base - base of the interpreted integer value

Return value

Integer value corresponding to the contents of str on success. If the converted value falls out of range of corresponding return type, range error occurs and ULONG_MAX or ULLONG_MAX is returned. If no conversion can be performed, ​0​ is returned.

+

Example

#include <stdio.h>
+#include <errno.h>
+#include <wchar.h>
+ 
+int main(void)
+{
+    const wchar_t *p = L"10 200000000000000000000000000000 30 40";
+    printf("Parsing L'%ls':\n", p);
+    wchar_t *end;
+    for (unsigned long i = wcstoul(p, &end, 10);
+         p != end;
+         i = wcstoul(p, &end, 10))
+    {
+        printf("'%.*ls' -> ", (int)(end-p), p);
+        p = end;
+        if (errno == ERANGE){
+            printf("range error, got ");
+            errno = 0;
+        }
+        printf("%lu\n", i);
+    }
+}

Output:

+
Parsing '10 200000000000000000000000000000 30 40':
+'10' -> 10
+' 200000000000000000000000000000' -> range error, got 18446744073709551615
+' 30' -> 30
+' 40' -> 40

References

See also

+ + +
+
(C99)
 converts a byte string to an unsigned integer value
(function)
+
(C95)(C99)
 converts a wide string to an integer value
(function)
C++ documentation for wcstoul, wcstoull
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/wcstoul +

+
diff --git a/devdocs/c/string%2Fwide%2Fwcsxfrm.html b/devdocs/c/string%2Fwide%2Fwcsxfrm.html new file mode 100644 index 00000000..5ed66168 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcsxfrm.html @@ -0,0 +1,59 @@ +

wcsxfrm

Defined in header <wchar.h> 
size_t wcsxfrm( wchar_t* dest, const wchar_t* src, size_t count );
+		 (until C99)
(since C95) 
size_t wcsxfrm( wchar_t* restrict dest, const wchar_t* restrict src, size_t count );
+		 (since C99)

Transforms the null-terminated wide string pointed to by src into the implementation-defined form such that comparing two transformed strings with wcscmp gives the same result as comparing the original strings with wcscoll, in the current C locale.

+

The first count characters of the transformed string are written to destination, including the terminating null character, and the length of the full transformed string is returned, excluding the terminating null character.

+

If count is ​0​, then dest is allowed to be a null pointer.

+

Notes

The correct length of the buffer that can receive the entire transformed string is 1+wcsxfrm(NULL, src, 0)

+

This function is used when making multiple locale-dependent comparisons using the same wide string or set of wide strings, because it is more efficient to use wcsxfrm to transform all the strings just once, and subsequently compare the transformed wide strings with wcscmp.

+

Parameters

+ + + +
dest - pointer to the first element of a wide null-terminated string to write the transformed string to
src - pointer to the null-terminated wide character string to transform
count - maximum number of characters to output

Return value

The length of the transformed wide string, not including the terminating null-character.

+

Example

#include <stdio.h>
+#include <wchar.h>
+#include <locale.h>
+ 
+int main(void)
+{
+    setlocale(LC_ALL, "sv_SE.utf8");
+ 
+    const wchar_t *in1 = L"\u00e5r";
+    wchar_t out1[1+wcsxfrm(NULL, in1, 0)];
+    wcsxfrm(out1, in1, sizeof out1/sizeof *out1);
+ 
+    const wchar_t *in2 = L"\u00e4ngel";
+    wchar_t out2[1+wcsxfrm(NULL, in2, 0)];
+    wcsxfrm(out2, in2, sizeof out2/sizeof *out2);
+ 
+    printf("In the Swedish locale: ");
+    if(wcscmp(out1, out2) < 0)
+         printf("%ls before %ls\n", in1, in2);
+    else
+         printf("%ls before %ls\n", in2, in1);
+ 
+    printf("In lexicographical comparison: ");
+    if(wcscmp(in1, in2) < 0)
+         printf("%ls before %ls\n", in1, in2);
+    else
+         printf("%ls before %ls\n", in2, in1);
+}

Output:

+
In the Swedish locale: år before ängel
+In lexicographical comparison: ängel before år

References

See also

+ + + + +
compares two strings in accordance to the current locale
(function)
+
(C95)
 compares two wide strings in accordance to the current locale
(function)
+
(C95)
 compares two wide strings
(function)
transform a string so that strcmp would produce the same result as strcoll
(function)
C++ documentation for wcsxfrm
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/wcsxfrm +

+
diff --git a/devdocs/c/string%2Fwide%2Fwctrans.html b/devdocs/c/string%2Fwide%2Fwctrans.html new file mode 100644 index 00000000..16a392f1 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwctrans.html @@ -0,0 +1,27 @@ +

wctrans

Defined in header <wctype.h> 
wctrans_t wctrans( const char* str );
+		 (since C95)

Constructs a value of type wctrans_t that describes a LC_CTYPE category of wide character mapping. It may be one of the standard mappings, or a locale-specific mapping, such as "tojhira" or "tojkata".

+

Parameters

+ +
str - C string holding the name of the desired mapping.

The following values of str are supported in all C locales:

+ + + +
Value of str Effect
"toupper" identifies the mapping used by towupper
"tolower" identifies the mapping used by towlower

Return value

wctrans_t object suitable for use with towctrans to map wide characters according to the named mapping of the current C locale or zero if str does not name a mapping supported by the current C locale.

+

References

See also

+ +
+
(C95)
 performs character mapping according to the specified LC_CTYPE mapping category
(function)
C++ documentation for wctrans
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/wctrans +

+
diff --git a/devdocs/c/string%2Fwide%2Fwctype.html b/devdocs/c/string%2Fwide%2Fwctype.html new file mode 100644 index 00000000..a0891b98 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwctype.html @@ -0,0 +1,36 @@ +

wctype

Defined in header <wctype.h> 
wctype_t wctype( const char* str );
+		 (since C95)

Constructs a value of type wctype_t that describes a LC_CTYPE category of wide character classification. It may be one of the standard classification categories, or a locale-specific category, such as "jkanji".

+

Parameters

+ +
str - C string holding the name of the desired category

The following values of str are supported in all C locales:

+ + + + + + + + + + + + +
value of str effect
"alnum" identifies the category used by iswalnum
"alpha" identifies the category used by iswalpha
"blank" identifies the category used by iswblank (C99)
"cntrl" identifies the category used by iswcntrl
"digit" identifies the category used by iswdigit
"graph" identifies the category used by iswgraph
"lower" identifies the category used by iswlower
"print" identifies the category used by iswprint
"space" identifies the category used by iswspace
"upper" identifies the category used by iswupper
"xdigit" identifies the category used by iswxdigit

Return value

wctype_t object suitable for use with iswctype to classify wide characters according to the named category of the current C locale or zero if str does not name a category supported by the current C locale.

+

References

See also

+ +
+
(C95)
 classifies a wide character according to the specified LC_CTYPE category
(function)
C++ documentation for wctype
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/wctype +

+
diff --git a/devdocs/c/string%2Fwide%2Fwmemchr.html b/devdocs/c/string%2Fwide%2Fwmemchr.html new file mode 100644 index 00000000..d2d9a2db --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwmemchr.html @@ -0,0 +1,51 @@ +

wmemchr

Defined in header <wchar.h> 
wchar_t *wmemchr( const wchar_t *ptr, wchar_t ch, size_t count );
+		 (1) (since C95) 
/*QWchar_t*/ *wmemchr( /*Qwchar_t*/ *ptr, wchar_t ch, size_t count );
+		 (2) (since C23)
+1) Locates the first occurrence of wide character ch in the initial count wide characters of the wide character array or integer array of compatible type, pointed to by ptr.
+2) Type-generic function equivalent to (1). Let T be an unqualified wide character object type. If a macro definition of each of these generic functions is suppressed to access an actual function (e.g. if (wmemchr) or a function pointer is used), the actual function declaration (1) becomes visible.

If count is zero, the function returns a null pointer.

+

Parameters

+ + + +
ptr - pointer to the wide character array to be examined
ch - wide character to search for
count - number of wide characters to examine

Return value

Pointer to the location of the wide character, or a null pointer if no such character is found.

+

Example

#include <locale.h>
+#include <stdio.h>
+#include <wchar.h>
+ 
+int main(void)
+{
+    wchar_t str[] = L"诺不轻信，故人不负我\0诺不轻许，故我不负人。";
+    size_t sz = sizeof str / sizeof *str;
+ 
+    wchar_t target = L'许';
+    wchar_t* result = wmemchr(str, target, sz);
+ 
+    if (result)
+    {
+        setlocale(LC_ALL, "en_US.utf8");
+        printf("Found '%lc' at position %td\n",target, result - str);
+    }
+}

Possible output:

+
Found '许' at position 14

References

See also

+ + +
searches an array for the first occurrence of a character
(function)
+
(C95)
 finds the first occurrence of a wide character in a wide string
(function)
C++ documentation for wmemchr
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/wmemchr +

+
diff --git a/devdocs/c/string%2Fwide%2Fwmemcmp.html b/devdocs/c/string%2Fwide%2Fwmemcmp.html new file mode 100644 index 00000000..656ec979 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwmemcmp.html @@ -0,0 +1,68 @@ +

wmemcmp

Defined in header <wchar.h> 
int wmemcmp( const wchar_t* lhs, const wchar_t* rhs, size_t count );
+		 (since C95)

Compares the first count wide characters of the wide character (or compatible integer type) arrays pointed to by lhs and rhs. The comparison is done lexicographically.

+

The sign of the result is the sign of the difference between the values of the first pair of wide characters that differ in the arrays being compared.

+

If count is zero, the function does nothing.

+

Parameters

+ + +
lhs, rhs - pointers to the wide character arrays to compare
count - number of wide characters to examine

Return value

Negative value if the value of the first differing wide character in lhs is less than the value of the corresponding wide character in rhs: lhs precedes rhs in lexicographical order.

+

​0​ if all count wide characters of lhs and rhs are equal.

+

Positive value if the value of the first differing wide character in lhs is greater than the value of the corresponding wide character in rhs: rhs precedes lhs in lexicographical order.

+

Notes

This function is not locale-sensitive and pays no attention to the values of the wchar_t objects it examines: nulls as well as invalid wide characters are compared too.

+

Example

#include <locale.h>
+#include <stdio.h>
+#include <wchar.h>
+ 
+void demo(const wchar_t* lhs, const wchar_t* rhs, size_t sz)
+{
+    for (size_t n = 0; n < sz; ++n)
+        putwchar(lhs[n]);
+ 
+    int rc = wmemcmp(lhs, rhs, sz);
+    if (rc == 0)
+        wprintf(L" compares equal to ");
+    else if(rc < 0)
+        wprintf(L" precedes ");
+    else if(rc > 0)
+        wprintf(L" follows ");
+ 
+    for (size_t n = 0; n < sz; ++n)
+        putwchar(rhs[n]);
+    wprintf(L" in lexicographical order\n");
+}
+ 
+int main(void)
+{
+    setlocale(LC_ALL, "en_US.utf8");
+ 
+    wchar_t a1[] = {L'α',L'β',L'γ'};
+    wchar_t a2[] = {L'α',L'β',L'δ'};
+ 
+    size_t sz = sizeof a1 / sizeof *a1;
+    demo(a1, a2, sz);
+    demo(a2, a1, sz);
+    demo(a1, a1, sz);
+}

Output:

+
αβγ precedes αβδ in lexicographical order
+αβδ follows αβγ in lexicographical order
+αβγ compares equal to αβγ in lexicographical order

References

See also

+ + + +
+
(C95)
 compares two wide strings
(function)
compares two buffers
(function)
+
(C95)
 compares a certain amount of characters from two wide strings
(function)
C++ documentation for wmemcmp
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/wmemcmp +

+
diff --git a/devdocs/c/string%2Fwide%2Fwmemcpy.html b/devdocs/c/string%2Fwide%2Fwmemcpy.html new file mode 100644 index 00000000..6ab00226 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwmemcpy.html @@ -0,0 +1,69 @@ +

wmemcpy, wmemcpy_s

Defined in header <wchar.h>
(1) 
wchar_t* wmemcpy( wchar_t* dest, const wchar_t* src, size_t count );
+		 (since C95)
(until C99) 
wchar_t *wmemcpy(wchar_t *restrict dest, const wchar_t *restrict src,
+                 size_t count );
+		 (since C99) 
errno_t wmemcpy_s( wchar_t *restrict dest, rsize_t destsz,
+                   const wchar_t *restrict src, rsize_t count );
+		 (2) (since C11)
+1) Copies exactly count successive wide characters from the wide character array pointed to by src to the wide character array pointed to by dest. If the objects overlap, the behavior is undefined. If count is zero, the function does nothing.
+2) Same as (1), except that the following errors are detected at runtime and call the currently installed constraint handler function:
+
+
    +
  • src or dest is a null pointer
    • +
  • destsz or count is greater than RSIZE_MAX/sizeof(wchar_t)
    • +
  • count is greater than destsz (overflow would occur)
    • +
  • overlap would occur between the source and the destination arrays
    • +
+
As with all bounds-checked functions, wmemcpy_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <wchar.h>.
+
+

Parameters

+ + + + +
dest - pointer to the wide character array to copy to
src - pointer to the wide character array to copy from
count - number of wide characters to copy
destsz - max number of wide characters to write (the size of the destination buffer)

Return value

+1) returns a copy of dest +
+2) returns zero on success, returns non-zero on error. Also, on error, fills the entire dst up to and not including dst+dstsz with null wide characters, L'\0' (unless dest is null or destsz is greater than RSIZE_MAX/sizeof(wchar_t))

Notes

This function's analog for byte strings is strncpy, not strcpy.

+

This function is not locale-sensitive and pays no attention to the values of the wchar_t objects it copies: nulls as well as invalid characters are copied too.

+

Example

#include <stdio.h>
+#include <wchar.h>
+#include <locale.h>
+ 
+int main(void)
+{
+    wchar_t from1[] = L"नमस्ते";
+    size_t sz1 = sizeof from1 / sizeof *from1;
+    wchar_t from2[] = L"Բարև";
+    size_t sz2 = sizeof from2 / sizeof *from2;
+    wchar_t to[sz1 + sz2];
+    wmemcpy(to, from1, sz1); // copy from1, along with its null terminator
+    wmemcpy(to + sz1, from2, sz2); // append from2, along with its null terminator
+ 
+    setlocale(LC_ALL, "en_US.utf8");
+    printf("Wide array contains: ");
+    for(size_t n = 0; n < sizeof to / sizeof *to; ++n)
+        if(to[n])
+            printf("%lc", to[n]);
+        else
+            printf("\\0");
+    printf("\n");
+}

Possible output:

+
Wide array contains: नमस्ते\0Բարև\0

References

See also

+ + +
+
(C95)(C11)
 copies a certain amount of wide characters between two, possibly overlapping, arrays
(function)
+
(C11)
 copies a certain amount of characters from one string to another
(function)
C++ documentation for wmemcpy
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/wmemcpy +

+
diff --git a/devdocs/c/string%2Fwide%2Fwmemmove.html b/devdocs/c/string%2Fwide%2Fwmemmove.html new file mode 100644 index 00000000..5b6a969c --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwmemmove.html @@ -0,0 +1,66 @@ +

wmemmove, wmemmove_s

Defined in header <wchar.h> 
wchar_t* wmemmove( wchar_t* dest, const wchar_t* src, size_t count );
+		 (1) (since C95) 
errno_t wmemmove_s( wchar_t *dest, rsize_t destsz,
+                    const wchar_t *src, rsize_t count);
+		 (2) (since C11)
+1) Copies exactly count successive wide characters from the wide character array pointed to by src to the wide character array pointed to by dest. If count is zero, the function does nothing. The arrays may overlap: copying takes place as if the wide characters were copied to a temporary wide character array and then copied from the temporary array to dest.
+2) Same as (1), except that the following errors are detected at runtime and call the currently installed constraint handler function:
+
+
    +
  • src or dest is a null pointer
    • +
  • destsz or count is greater than RSIZE_MAX / sizeof(wchar_t)
    • +
  • count is greater than destsz (overflow would occur)
    • +
+
As with all bounds-checked functions, wmemcpy_s only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <wchar.h>.
+
+

Parameters

+ + + + +
dest - pointer to the wide character array to copy to
src - pointer to the wide character array to copy from
destsz - max number of wide characters to write (the size of the destination buffer)
count - number of wide characters to copy

Return value

+1) Returns a copy of dest +
+2) Returns zero on success, returns non-zero on error. Also, on error, fills the entire dst up to and not including dst+dstsz with null wide characters, L'\0' (unless dest is null or destsz is greater than RSIZE_MAX/sizeof(wchar_t))

Notes

This function is not locale-sensitive and pays no attention to the values of the wchar_t objects it copies: nulls as well as invalid characters are copied too.

+

Example

#include <locale.h>
+#include <stdio.h>
+#include <wchar.h>
+ 
+int main(void)
+{
+    setlocale(LC_ALL, "en_US.utf8");
+ 
+    wchar_t str[] = L"αβγδεζηθικλμνξοπρστυφχψω";
+    printf("%ls\n", str);
+    wmemmove(str + 4, str + 3, 3); // copy from [δεζ] to [εζη]
+    printf("%ls\n", str);
+}

Output:

+
αβγδεζηθικλμνξοπρστυφχψω
+αβγδδεζθικλμνξοπρστυφχψω

References

See also

+ + +
+
(C11)
 moves one buffer to another
(function)
+
(C95)(C11)
 copies a certain amount of wide characters between two non-overlapping arrays
(function)
C++ documentation for wmemmove
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/wmemmove +

+
diff --git a/devdocs/c/string%2Fwide%2Fwmemset.html b/devdocs/c/string%2Fwide%2Fwmemset.html new file mode 100644 index 00000000..76e41a84 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwmemset.html @@ -0,0 +1,45 @@ +

wmemset

Defined in header <wchar.h> 
wchar_t* wmemset( wchar_t* dest, wchar_t ch, size_t count );
+		 (since C95)

Copies the wide character ch into each of the first count wide characters of the wide character array (or integer array of compatible type) pointed to by dest.

+

If overflow occurs, the behavior is undefined.

+

If count is zero, the function does nothing.

+

Parameters

+ + + +
dest - pointer to the wide character array to fill
ch - fill wide character
count - number of wide characters to fill

Return value

Returns a copy of dest

+

Notes

This function is not locale-sensitive and pays no attention to the values of the wchar_t objects it writes: nulls as well as invalid wide characters are written too.

+

Example

#include <locale.h>
+#include <stdio.h>
+#include <wchar.h>
+ 
+int main(void)
+{
+    wchar_t ar[10] = L"1234567890"; // no trailing null in the array
+    wmemset(ar, L'\U0001f34c', 5); // replaces [12345] with the 🍌 bananas
+    wmemset(ar + 5, L'蕉', 5); // replaces [67890] with the 蕉 bananas
+ 
+    setlocale(LC_ALL, "en_US.utf8");
+    for (size_t n = 0; n < sizeof ar / sizeof *ar; ++n)
+        putwchar(ar[n]);
+    putwchar(L'\n');
+}

Output:

+
🍌🍌🍌🍌🍌蕉蕉蕉蕉蕉

References

See also

+ + +
+
(C23)(C11)
 fills a buffer with a character
(function)
+
(C95)(C11)
 copies a certain amount of wide characters between two non-overlapping arrays
(function)
C++ documentation for wmemset
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide/wmemset +

+
diff --git a/devdocs/c/string%2Fwide.html b/devdocs/c/string%2Fwide.html new file mode 100644 index 00000000..3367609f --- /dev/null +++ b/devdocs/c/string%2Fwide.html @@ -0,0 +1,231 @@ +

Null-terminated wide strings

A null-terminated wide string is a sequence of valid wide characters, ending with a null-character.

+

Functions

+ + + + + + + + + + + + + + + + + + + + + +
Character classification
Defined in header <wctype.h>
+
(C95)
 checks if a wide character is alphanumeric
(function)
+
(C95)
 checks if a wide character is alphabetic
(function)
+
(C95)
 checks if a wide character is an lowercase character
(function)
+
(C95)
 checks if a wide character is an uppercase character
(function)
+
(C95)
 checks if a wide character is a digit
(function)
+
(C95)
 checks if a wide character is a hexadecimal character
(function)
+
(C95)
 checks if a wide character is a control character
(function)
+
(C95)
 checks if a wide character is a graphical character
(function)
+
(C95)
 checks if a wide character is a space character
(function)
+
(C99)
 checks if a wide character is a blank character
(function)
+
(C95)
 checks if a wide character is a printing character
(function)
+
(C95)
 checks if a wide character is a punctuation character
(function)
+
(C95)
 classifies a wide character according to the specified LC_CTYPE category
(function)
+
(C95)
 looks up a character classification category in the current C locale
(function)
Character manipulation
Defined in header <wctype.h>
+
(C95)
 converts a wide character to lowercase
(function)
+
(C95)
 converts a wide character to uppercase
(function)
+
(C95)
 performs character mapping according to the specified LC_CTYPE mapping category
(function)
+
(C95)
 looks up a character mapping category in the current C locale
(function)
+ + + + + + + + + + + + + + + + + +
ASCII values characters

iscntrl
iswcntrl

+

isprint
iswprint

+

isspace
iswspace

+

isblank
iswblank

+

isgraph
iswgraph

+

ispunct
iswpunct

+

isalnum
iswalnum

+

isalpha
iswalpha

+

isupper
iswupper

+

islower
iswlower

+

isdigit
iswdigit

+

isxdigit
iswxdigit

+
decimal hexadecimal octal
0–8 \x0–\x8 \0–\10 control codes (NUL, etc.) +≠0 0 0 0 0 0 0 0 0 0 0 0
9 \x9 \11 tab (\t) +≠0 0 +≠0 +≠0 0 0 0 0 0 0 0 0
10–13 \xA–\xD \12–\15 whitespaces (\n, \v, \f, \r) +≠0 0 +≠0 0 0 0 0 0 0 0 0 0
14–31 \xE–\x1F \16–\37 control codes +≠0 0 0 0 0 0 0 0 0 0 0 0
32 \x20 \40 space 0 +≠0 +≠0 +≠0 0 0 0 0 0 0 0 0
33–47 \x21–\x2F \41–\57 !"#$%&'()*+,-./ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
48–57 \x30–\x39 \60–\71 0123456789 0 +≠0 0 0 +≠0 0 +≠0 0 0 0 +≠0 +≠0
58–64 \x3A–\x40 \72–\100 :;<=>?@ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
65–70 \x41–\x46 \101–\106 ABCDEF 0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 +≠0
71–90 \x47–\x5A \107–\132 GHIJKLMNOP
QRSTUVWXYZ 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 +≠0 0 0 0
91–96 \x5B–\x60 \133–\140 [\]^_` 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
97–102 \x61–\x66 \141–\146 abcdef 0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 +≠0
103–122 \x67–\x7A \147–\172 ghijklmnop
qrstuvwxyz 		0 +≠0 0 0 +≠0 0 +≠0 +≠0 0 +≠0 0 0
123–126 \x7B–\x7E \172–\176 {|}~ 0 +≠0 0 0 +≠0 +≠0 0 0 0 0 0 0
127 \x7F \177 backspace character (DEL) +≠0 0 0 0 0 0 0 0 0 0 0 0
+ + + + + + +
Conversions to numeric formats
Defined in header <wchar.h>
+
(C95)(C99)
 converts a wide string to an integer value
(function)
+
(C95)(C99)
 converts a wide string to an unsigned integer value
(function)
+
(C99)(C95)(C99)
 converts a wide string to a floating-point value
(function)
Defined in header <inttypes.h>
+
(C99)(C99)
 converts a wide string to intmax_t or uintmax_t
(function)
+ + + + + + + + + + + + + + + + + + + +
String manipulation
Defined in header <wchar.h>
+
(C95)(C11)
 copies one wide string to another
(function)
+
(C95)(C11)
 copies a certain amount of wide characters from one string to another
(function)
+
(C95)(C11)
 appends a copy of one wide string to another
(function)
+
(C95)(C11)
 appends a certain amount of wide characters from one wide string to another
(function)
+
(C95)
 transform a wide string so that wcscmp would produce the same result as wcscoll
(function)
String examination
Defined in header <wchar.h>
+
(C95)(C11)
 returns the length of a wide string
(function)
+
(C95)
 compares two wide strings
(function)
+
(C95)
 compares a certain amount of characters from two wide strings
(function)
+
(C95)
 compares two wide strings in accordance to the current locale
(function)
+
(C95)
 finds the first occurrence of a wide character in a wide string
(function)
+
(C95)
 finds the last occurrence of a wide character in a wide string
(function)
+
(C95)
 returns the length of the maximum initial segment that consists
of only the wide characters found in another wide string
(function)
+
(C95)
 returns the length of the maximum initial segment that consists
of only the wide chars not found in another wide string
(function)
+
(C95)
 finds the first location of any wide character in one wide string, in another wide string
(function)
+
(C95)
 finds the first occurrence of a wide string within another wide string
(function)
+
(C95)(C11)
 finds the next token in a wide string
(function)
+ + + + + + +
Wide character array manipulation
Defined in header <wchar.h>
+
(C95)(C11)
 copies a certain amount of wide characters between two non-overlapping arrays
(function)
+
(C95)(C11)
 copies a certain amount of wide characters between two, possibly overlapping, arrays
(function)
+
(C95)
 compares a certain amount of wide characters from two arrays
(function)
+
(C95)
 finds the first occurrence of a wide character in a wide character array
(function)
+
(C95)
 copies the given wide character to every position in a wide character array
(function)

Types

+ + + + + + + + + +
Defined in header <stddef.h>
Defined in header <stdlib.h>
Defined in header <wchar.h>
wchar_t
 integer type that can hold any valid wide character
(typedef)
Defined in header <wchar.h>
Defined in header <wctype.h>
wint_t
+
(C95)
 integer type that can hold any valid wide character and at least one more value
(typedef)
Defined in header <wctype.h>
wctrans_t
+
(C95)
 scalar type that holds locale-specific character mapping
(typedef)
wctype_t
+
(C95)
 scalar type that holds locale-specific character classification
(typedef)

Macros

+ + + + + + +
Defined in header <wchar.h>
Defined in header <wctype.h>
WEOF
+
(C95)
 a non-character value of type wint_t used to indicate errors
(macro constant)
Defined in header <wchar.h>
Defined in header <stdint.h>
WCHAR_MIN
+
(C95)
 the smallest valid value of wchar_t
(macro constant)
WCHAR_MAX
+
(C95)
 the largest valid value of wchar_t
(macro constant)

References

See also

+
C++ documentation for Null-terminated wide strings
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string/wide +

+
diff --git a/devdocs/c/string.html b/devdocs/c/string.html new file mode 100644 index 00000000..77b470d2 --- /dev/null +++ b/devdocs/c/string.html @@ -0,0 +1,10 @@ +

Strings library

Null-terminated byte string management +

Null-terminated multibyte string management +

Null-terminated wide string management +

See also

+
C++ documentation for Strings library
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/string +

+
diff --git a/devdocs/c/thread%2Fcall_once.html b/devdocs/c/thread%2Fcall_once.html new file mode 100644 index 00000000..c49a1c35 --- /dev/null +++ b/devdocs/c/thread%2Fcall_once.html @@ -0,0 +1,55 @@ +

call_once, once_flag, ONCE_FLAG_INIT

Defined in header <threads.h> 
void call_once( once_flag* flag, void (*func)(void) );
+		 (1) (since C11) 
typedef /* unspecified */ once_flag
+		 (2) (since C11) 
#define ONCE_FLAG_INIT /* unspecified */
+		 (3) (since C11)
+1) Calls function func exactly once, even if invoked from several threads. The completion of the function func synchronizes with all previous or subsequent calls to call_once with the same flag variable.
+2) Complete object type capable of holding a flag used by call_once.
+3) Expands to a value that can be used to initialize an object of type once_flag.

Parameters

+ + +
flag - pointer to an object of type call_once that is used to ensure func is called only once
func - the function to execute only once

Return value

(none)

+

Notes

The POSIX equivalent of this function is pthread_once.

+

Example

#include <stdio.h>
+#include <threads.h>
+ 
+void do_once(void) {
+    puts("called once");
+}
+ 
+static once_flag flag = ONCE_FLAG_INIT;
+int func(void* data)
+{
+    call_once(&flag, do_once);
+}
+ 
+int main(void)
+{
+    thrd_t t1, t2, t3, t4;
+    thrd_create(&t1, func, NULL);
+    thrd_create(&t2, func, NULL);
+    thrd_create(&t3, func, NULL);
+    thrd_create(&t4, func, NULL);
+ 
+    thrd_join(t1, NULL);
+    thrd_join(t2, NULL);
+    thrd_join(t3, NULL);
+    thrd_join(t4, NULL);
+}

Output:

+
called once

References

See also

+
C++ documentation for call_once
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/thread/call_once +

+
diff --git a/devdocs/c/thread%2Fcnd_broadcast.html b/devdocs/c/thread%2Fcnd_broadcast.html new file mode 100644 index 00000000..e007c0bc --- /dev/null +++ b/devdocs/c/thread%2Fcnd_broadcast.html @@ -0,0 +1,20 @@ +

cnd_broadcast

Defined in header <threads.h> 
int cnd_broadcast( cnd_t *cond );
+		 (since C11)

Unblocks all threads that are blocked on condition variable cond at the time of the call. If no threads are blocked on cond, the function does nothing and returns thrd_success.

+

Parameters

+ +
cond - pointer to a condition variable

Return value

thrd_success if successful, thrd_error otherwise.

+

References

See also

+ + +
+
(C11)
 unblocks one thread blocked on a condition variable
(function)
C++ documentation for condition_variable::notify_all
C++ documentation for condition_variable_any::notify_all
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/thread/cnd_broadcast +

+
diff --git a/devdocs/c/thread%2Fcnd_destroy.html b/devdocs/c/thread%2Fcnd_destroy.html new file mode 100644 index 00000000..91a9bfb1 --- /dev/null +++ b/devdocs/c/thread%2Fcnd_destroy.html @@ -0,0 +1,19 @@ +

cnd_destroy

Defined in header <threads.h> 
void cnd_destroy( cnd_t* cond );
+		 (since C11)

Destroys the condition variable pointed to by cond.

+

If there are threads waiting on cond, the behavior is undefined.

+

Parameters

+ +
cond - pointer to the condition variable to destroy

Return value

(none)

+

References

See also

+ +
C++ documentation for ~condition_variable
C++ documentation for ~condition_variable_any
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/thread/cnd_destroy +

+
diff --git a/devdocs/c/thread%2Fcnd_init.html b/devdocs/c/thread%2Fcnd_init.html new file mode 100644 index 00000000..c9527ac5 --- /dev/null +++ b/devdocs/c/thread%2Fcnd_init.html @@ -0,0 +1,18 @@ +

cnd_init

Defined in header <threads.h> 
int cnd_init( cnd_t* cond );
+		 (since C11)

Initializes new condition variable. The object pointed to by cond will be set to value that identifies the condition variable.

+

Parameters

+ +
cond - pointer to a variable to store identifier of the condition variable to

Return value

thrd_success if the condition variable was successfully created. Otherwise returns thrd_nomem if there was insufficient amount of memory or thrd_error if another error occurred.

+

References

See also

+ +
C++ documentation for condition_variable
C++ documentation for condition_variable_any
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/thread/cnd_init +

+
diff --git a/devdocs/c/thread%2Fcnd_signal.html b/devdocs/c/thread%2Fcnd_signal.html new file mode 100644 index 00000000..37a894ce --- /dev/null +++ b/devdocs/c/thread%2Fcnd_signal.html @@ -0,0 +1,20 @@ +

cnd_signal

Defined in header <threads.h> 
int cnd_signal( cnd_t *cond );
+		 (since C11)

Unblocks one thread that currently waits on condition variable pointed to by cond. If no threads are blocked, does nothing and returns thrd_success.

+

Parameters

+ +
cond - pointer to a condition variable

Return value

thrd_success if successful, thrd_error otherwise.

+

References

See also

+ + +
+
(C11)
 unblocks all threads blocked on a condition variable
(function)
C++ documentation for condition_variable::notify_one
C++ documentation for condition_variable_any::notify_one
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/thread/cnd_signal +

+
diff --git a/devdocs/c/thread%2Fcnd_timedwait.html b/devdocs/c/thread%2Fcnd_timedwait.html new file mode 100644 index 00000000..96b61762 --- /dev/null +++ b/devdocs/c/thread%2Fcnd_timedwait.html @@ -0,0 +1,24 @@ +

cnd_timedwait

Defined in header <threads.h> 
int cnd_timedwait( cnd_t* restrict cond, mtx_t* restrict mutex,
+                   const struct timespec* restrict time_point );
+		 (since C11)

Atomically unlocks the mutex pointed to by mutex and blocks on the condition variable pointed to by cond until the thread is signalled by cnd_signal or cnd_broadcast, or until the TIME_UTC based time point pointed to by time_point has been reached, or until a spurious wake-up occurs. The mutex is locked again before the function returns.

+

The behavior is undefined if the mutex is not already locked by the calling thread.

+

Parameters

+ + + +
cond - pointer to the condition variable to block on
mutex - pointer to the mutex to unlock for the duration of the block
time_point - pointer to an object specifying timeout time to wait until

Return value

thrd_success if successful, thrd_timedout if the timeout time has been reached before the mutex is locked, or thrd_error if an error occurred.

+

References

See also

+ + +
+
(C11)
 blocks on a condition variable
(function)
C++ documentation for condition_variable::wait_until
C++ documentation for condition_variable_any::wait_until
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/thread/cnd_timedwait +

+
diff --git a/devdocs/c/thread%2Fcnd_wait.html b/devdocs/c/thread%2Fcnd_wait.html new file mode 100644 index 00000000..6bbb3ede --- /dev/null +++ b/devdocs/c/thread%2Fcnd_wait.html @@ -0,0 +1,22 @@ +

cnd_wait

Defined in header <threads.h> 
int cnd_wait( cnd_t* cond, mtx_t* mutex );
+		 (since C11)

Atomically unlocks the mutex pointed to by mutex and blocks on the condition variable pointed to by cond until the thread is signalled by cnd_signal or cnd_broadcast, or until a spurious wake-up occurs. The mutex is locked again before the function returns.

+

The behavior is undefined if the mutex is not already locked by the calling thread.

+

Parameters

+ + +
cond - pointer to the condition variable to block on
mutex - pointer to the mutex to unlock for the duration of the block

Return value

thrd_success if successful, thrd_error otherwise.

+

References

See also

+ + +
+
(C11)
 blocks on a condition variable, with a timeout
(function)
C++ documentation for condition_variable::wait
C++ documentation for condition_variable_any::wait
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/thread/cnd_wait +

+
diff --git a/devdocs/c/thread%2Fmtx_destroy.html b/devdocs/c/thread%2Fmtx_destroy.html new file mode 100644 index 00000000..eb5bc679 --- /dev/null +++ b/devdocs/c/thread%2Fmtx_destroy.html @@ -0,0 +1,21 @@ +

mtx_destroy

Defined in header <threads.h> 
void mtx_destroy( mtx_t *mutex );
+		 (since C11)

Destroys the mutex pointed to by mutex.

+

If there are threads waiting on mutex, the behavior is undefined.

+

Parameters

+ +
mutex - pointer to the mutex to destroy

Return value

(none)

+

References

See also

+ + + +
C++ documentation for ~mutex
C++ documentation for ~timed_mutex
C++ documentation for ~recursive_mutex
C++ documentation for ~recursive_timed_mutex
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/thread/mtx_destroy +

+
diff --git a/devdocs/c/thread%2Fmtx_init.html b/devdocs/c/thread%2Fmtx_init.html new file mode 100644 index 00000000..b500c70e --- /dev/null +++ b/devdocs/c/thread%2Fmtx_init.html @@ -0,0 +1,31 @@ +

mtx_init

Defined in header <threads.h> 
int mtx_init( mtx_t* mutex, int type );
+		 (since C11)

Creates a new mutex object with type. The object pointed to by mutex is set to an identifier of the newly created mutex.

+

type must have one of the following values:

+

Parameters

+ + +
mutex - pointer to the mutex to initialize
type - the type of the mutex

Return value

thrd_success if successful, thrd_error otherwise.

+

References

See also

+ + + +
C++ documentation for mutex
C++ documentation for timed_mutex
C++ documentation for recursive_mutex
C++ documentation for recursive_timed_mutex
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/thread/mtx_init +

+
diff --git a/devdocs/c/thread%2Fmtx_lock.html b/devdocs/c/thread%2Fmtx_lock.html new file mode 100644 index 00000000..88ff3dfe --- /dev/null +++ b/devdocs/c/thread%2Fmtx_lock.html @@ -0,0 +1,28 @@ +

mtx_lock

Defined in header <threads.h> 
int mtx_lock( mtx_t* mutex );
+		 (since C11)

Blocks the current thread until the mutex pointed to by mutex is locked.

+

The behavior is undefined if the current thread has already locked the mutex and the mutex is not recursive.

+

Prior calls to mtx_unlock on the same mutex synchronize-with this operation, and all lock/unlock operations on any given mutex form a single total order (similar to the modification order of an atomic)

+

Parameters

+ +
mutex - pointer to the mutex to lock

Return value

thrd_success if successful, thrd_error otherwise.

+

References

See also

+ + + + + + +
+
(C11)
 blocks until locks a mutex or times out
(function)
+
(C11)
 locks a mutex or returns without blocking if already locked
(function)
+
(C11)
 unlocks a mutex
(function)
C++ documentation for mutex::lock
C++ documentation for timed_mutex::lock
C++ documentation for recursive_mutex::lock
C++ documentation for recursive_timed_mutex::lock
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/thread/mtx_lock +

+
diff --git a/devdocs/c/thread%2Fmtx_timedlock.html b/devdocs/c/thread%2Fmtx_timedlock.html new file mode 100644 index 00000000..706bf816 --- /dev/null +++ b/devdocs/c/thread%2Fmtx_timedlock.html @@ -0,0 +1,35 @@ +

mtx_timedlock

Defined in header <threads.h> 
int mtx_timedlock( mtx_t *restrict mutex,
+                   const struct timespec *restrict time_point );
+		 (since C11)

Blocks the current thread until the mutex pointed to by mutex is locked or until the TIME_UTC based absolute calendar time point pointed to by time_point has been reached.

+

Since this function takes an absolute time, if a duration is required, the calendar time point must be calculated manually.

+

The behavior is undefined if the current thread has already locked the mutex and the mutex is not recursive.

+

The behavior is undefined if the mutex does not support timeout.

+

Prior calls to mtx_unlock on the same mutex synchronize-with this operation (if this operation succeeds), and all lock/unlock operations on any given mutex form a single total order (similar to the modification order of an atomic)

+

Parameters

+ + +
mutex - pointer to the mutex to lock
time_point - pointer to the absolute calendar time until which to wait for the timeout

Return value

thrd_success if successful, thrd_timedout if the timeout time has been reached before the mutex is locked, thrd_error if an error occurs.

+

References

See also

+ + + + + +
+
(C11)
 time in seconds and nanoseconds
(struct)
+
(C11)
 blocks until locks a mutex
(function)
+
(C11)
 locks a mutex or returns without blocking if already locked
(function)
+
(C11)
 unlocks a mutex
(function)
C++ documentation for timed_mutex::try_lock_until
C++ documentation for recursive_timed_mutex::try_lock_until
+ +
+GNU GCC Libc Manual: ISO-C-Mutexes
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/thread/mtx_timedlock +

+
diff --git a/devdocs/c/thread%2Fmtx_trylock.html b/devdocs/c/thread%2Fmtx_trylock.html new file mode 100644 index 00000000..04c49311 --- /dev/null +++ b/devdocs/c/thread%2Fmtx_trylock.html @@ -0,0 +1,33 @@ +

mtx_trylock

Defined in header <threads.h> 
int mtx_trylock( mtx_t *mutex );
+		 (since C11)

Tries to lock the mutex pointed to by mutex without blocking. Returns immediately if the mutex is already locked.

+

Prior calls to mtx_unlock on the same mutex synchronize-with this operation (if this operation succeeds), and all lock/unlock operations on any given mutex form a single total order (similar to the modification order of an atomic)

+

Parameters

+ +
mutex - pointer to the mutex to lock

Return value

thrd_success if successful, thrd_busy if the mutex has already been locked or due to a spurious failure to acquire an available mutex, thrd_error if an error occurs.

+

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C standards.

+ + + +
DR Applied to Behavior as published Correct behavior
+DR 470 C11 +mtx_trylock was not allowed to fail spuriously allowed

References

See also

+ + + + + + +
+
(C11)
 blocks until locks a mutex
(function)
+
(C11)
 blocks until locks a mutex or times out
(function)
+
(C11)
 unlocks a mutex
(function)
C++ documentation for mutex::try_lock
C++ documentation for timed_mutex::try_lock
C++ documentation for recursive_mutex::try_lock
C++ documentation for recursive_timed_mutex::try_lock
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/thread/mtx_trylock +

+
diff --git a/devdocs/c/thread%2Fmtx_types.html b/devdocs/c/thread%2Fmtx_types.html new file mode 100644 index 00000000..ecd98707 --- /dev/null +++ b/devdocs/c/thread%2Fmtx_types.html @@ -0,0 +1,23 @@ +

mtx_plain, mtx_recursive, mtx_timed

Defined in header <threads.h> 
enum {
+    mtx_plain = /* unspecified */,
+    mtx_recursive = /* unspecified */,
+    mtx_timed = /* unspecified */
+};
+		 (since C11)

When passed to mtx_init, identifies the type of a mutex to create.

+ + + + +
Constant Explanation
mtx_plain plain mutex
mtx_recursive recursive mutex
mtx_timed timed mutex

References

See also

+
+
(C11)
 creates a mutex
(function)
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/thread/mtx_types +

+
diff --git a/devdocs/c/thread%2Fmtx_unlock.html b/devdocs/c/thread%2Fmtx_unlock.html new file mode 100644 index 00000000..14d4a14f --- /dev/null +++ b/devdocs/c/thread%2Fmtx_unlock.html @@ -0,0 +1,28 @@ +

mtx_unlock

Defined in header <threads.h> 
int mtx_unlock( mtx_t *mutex );
+		 (since C11)

Unlocks the mutex pointed to by mutex.

+

The behavior is undefined if the mutex is not locked by the calling thread.

+

This function synchronizes-with subsequent mtx_lock, mtx_trylock, or mtx_timedlock on the same mutex. All lock/unlock operations on any given mutex form a single total order (similar to the modification order of an atomic).

+

Parameters

+ +
mutex - pointer to the mutex to unlock

Return value

thrd_success if successful, thrd_error otherwise.

+

References

See also

+ + + + + + +
+
(C11)
 blocks until locks a mutex
(function)
+
(C11)
 blocks until locks a mutex or times out
(function)
+
(C11)
 locks a mutex or returns without blocking if already locked
(function)
C++ documentation for mutex::unlock
C++ documentation for timed_mutex::unlock
C++ documentation for recursive_mutex::unlock
C++ documentation for recursive_timed_mutex::unlock
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/thread/mtx_unlock +

+
diff --git a/devdocs/c/thread%2Fthrd_create.html b/devdocs/c/thread%2Fthrd_create.html new file mode 100644 index 00000000..f81cb8fa --- /dev/null +++ b/devdocs/c/thread%2Fthrd_create.html @@ -0,0 +1,29 @@ +

thrd_create

Defined in header <threads.h> 
int thrd_create( thrd_t *thr, thrd_start_t func, void *arg );
+		 (since C11)

Creates a new thread executing the function func. The function is invoked as func(arg).

+

If successful, the object pointed to by thr is set to the identifier of the new thread.

+

The completion of this function synchronizes-with the beginning of the thread.

+

Parameters

+ + + +
thr - pointer to memory location to put the identifier of the new thread
func - function to execute
arg - argument to pass to the function

Return value

thrd_success if the creation of the new thread was successful. Otherwise returns thrd_nomem if there was insufficient amount of memory or thrd_error if another error occurred.

+

Notes

The thread identifiers may be reused for new threads once the thread has finished and joined or detached.

+

The type thrd_start_t is a typedef of int(*)(void*), which differs from the POSIX equivalent void*(*)(void*)

+

All thread-specific storage values (see tss_create) are initialized to NULL.

+

Return from the function func is equivalent to calling thrd_exit with the argument equal to the return value of func.

+

References

See also

+ + +
+
(C11)
 detaches a thread
(function)
+
(C11)
 blocks until a thread terminates
(function)
C++ documentation for thread
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/thread/thrd_create +

+
diff --git a/devdocs/c/thread%2Fthrd_current.html b/devdocs/c/thread%2Fthrd_current.html new file mode 100644 index 00000000..3d5512bc --- /dev/null +++ b/devdocs/c/thread%2Fthrd_current.html @@ -0,0 +1,16 @@ +

thrd_current

Defined in header <threads.h> 
thrd_t thrd_current( void );
+		 (since C11)

Returns the identifier of the calling thread.

+

Parameters

(none)

+

Return value

The identifier of the calling thread.

+

References

See also

+
C++ documentation for get_id
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/thread/thrd_current +

+
diff --git a/devdocs/c/thread%2Fthrd_detach.html b/devdocs/c/thread%2Fthrd_detach.html new file mode 100644 index 00000000..4708224e --- /dev/null +++ b/devdocs/c/thread%2Fthrd_detach.html @@ -0,0 +1,19 @@ +

thrd_detach

Defined in header <threads.h> 
int thrd_detach( thrd_t thr );
+		 (since C11)

Detaches the thread identified by thr from the current environment. The resources held by the thread will be freed automatically once the thread exits.

+

Parameters

+ +
thr - identifier of the thread to detach

Return value

thrd_success if successful, thrd_error otherwise.

+

References

See also

+ +
+
(C11)
 blocks until a thread terminates
(function)
C++ documentation for detach
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/thread/thrd_detach +

+
diff --git a/devdocs/c/thread%2Fthrd_equal.html b/devdocs/c/thread%2Fthrd_equal.html new file mode 100644 index 00000000..e0d3c1f6 --- /dev/null +++ b/devdocs/c/thread%2Fthrd_equal.html @@ -0,0 +1,17 @@ +

thrd_equal

Defined in header <threads.h> 
int thrd_equal( thrd_t lhs, thrd_t rhs );
+		 (since C11)

Checks whether lhs and rhs refer to the same thread.

+

Parameters

+ +
lhs, rhs - threads to compare

Return value

Non-zero value if lhs and rhs refer to the same value, ​0​ otherwise.

+

References

See also

+
C++ documentation for operator_cmp
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/thread/thrd_equal +

+
diff --git a/devdocs/c/thread%2Fthrd_errors.html b/devdocs/c/thread%2Fthrd_errors.html new file mode 100644 index 00000000..afdded4d --- /dev/null +++ b/devdocs/c/thread%2Fthrd_errors.html @@ -0,0 +1,25 @@ +

thrd_success, thrd_timedout, thrd_busy, thrd_nomem, thrd_error

Defined in header <threads.h> 
enum {
+    thrd_success = /* unspecified */,
+    thrd_nomem = /* unspecified */,
+    thrd_timedout = /* unspecified */,
+    thrd_busy = /* unspecified */,
+    thrd_error = /* unspecified */
+};
+		 (since C11)

Identifiers for thread states and errors.

+ + + + + + +
Constant Explanation
thrd_success indicates successful return value
thrd_nomem indicates unsuccessful return value due to out of memory condition
thrd_timedout indicates timed out return value
thrd_busy indicates unsuccessful return value due to resource temporary unavailable
thrd_error indicates unsuccessful return value

References

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/thread/thrd_errors +

+
diff --git a/devdocs/c/thread%2Fthrd_exit.html b/devdocs/c/thread%2Fthrd_exit.html new file mode 100644 index 00000000..03680641 --- /dev/null +++ b/devdocs/c/thread%2Fthrd_exit.html @@ -0,0 +1,25 @@ +

thrd_exit

Defined in header <threads.h> 
_Noreturn void thrd_exit( int res );
 +(since C11)
(until C23) +		 
[[noreturn]] void thrd_exit( int res );
+		 (since C23)

First, for every thread-specific storage key which was created with a non-null destructor and for which the associated value is non-null (see tss_create), thrd_exit sets the value associated with the key to NULL and then invokes the destructor with the previous value of the key. The order in which the destructors are invoked is unspecified.

+

If, after this, there remain keys with both non-null destructors and values (e.g. if a destructor executed tss_set), the process is repeated up to TSS_DTOR_ITERATIONS times.

+

Finally, the thrd_exit function terminates execution of the calling thread and sets its result code to res.

+

If the last thread in the program is terminated with thrd_exit, the entire program terminates as if by calling exit with EXIT_SUCCESS as the argument (so the functions registered by atexit are executed in the context of that last thread)

+

Parameters

+ +
res - the result value to return

Return value

(none)

+

References

See also

+ +
+
(C11)
 blocks until a thread terminates
(function)
+
(C11)
 detaches a thread
(function)
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/thread/thrd_exit +

+
diff --git a/devdocs/c/thread%2Fthrd_join.html b/devdocs/c/thread%2Fthrd_join.html new file mode 100644 index 00000000..e4764b63 --- /dev/null +++ b/devdocs/c/thread%2Fthrd_join.html @@ -0,0 +1,25 @@ +

thrd_join

Defined in header <threads.h> 
int thrd_join( thrd_t thr, int *res );
+		 (since C11)

Blocks the current thread until the thread identified by thr finishes execution.

+

If res is not a null pointer, the result code of the thread is put to the location pointed to by res.

+

The termination of the thread synchronizes-with the completion of this function.

+

The behavior is undefined if the thread was previously detached or joined by another thread.

+

Parameters

+ + +
thr - identifier of the thread to join
res - location to put the result code to

Return value

thrd_success if successful, thrd_error otherwise.

+

References

See also

+ + +
+
(C11)
 detaches a thread
(function)
+
(C11)
 terminates the calling thread
(function)
C++ documentation for join
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/thread/thrd_join +

+
diff --git a/devdocs/c/thread%2Fthrd_sleep.html b/devdocs/c/thread%2Fthrd_sleep.html new file mode 100644 index 00000000..2c7cd59a --- /dev/null +++ b/devdocs/c/thread%2Fthrd_sleep.html @@ -0,0 +1,36 @@ +

thrd_sleep

Defined in header <threads.h> 
int thrd_sleep( const struct timespec* duration,
+                struct timespec* remaining );
+		 (since C11)

Blocks the execution of the current thread for at least until the TIME_UTC based duration pointed to by duration has elapsed.

+

The sleep may resume earlier if a signal that is not ignored is received. In such case, if remaining is not NULL, the remaining time duration is stored into the object pointed to by remaining.

+

Parameters

+ + +
duration - pointer to the duration to sleep for
remaining - pointer to the object to put the remaining time on interruption. May be NULL, in which case it is ignored

Return value

​0​ on successful sleep, -1 if a signal occurred, other negative value if an error occurred.

+

Notes

duration and remaining may point at the same object, which simplifies re-running the function after a signal.

+

The actual sleep time may be longer than requested because it is rounded up to the timer granularity and because of scheduling and context switching overhead.

+

The POSIX equivalent of this function is nanosleep.

+

Example

#include <threads.h>
+#include <time.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    printf("Time: %s", ctime(&(time_t){time(NULL)}));
+    thrd_sleep(&(struct timespec){.tv_sec=1}, NULL); // sleep 1 sec
+    printf("Time: %s", ctime(&(time_t){time(NULL)}));
+}

Output:

+
Time: Mon Feb  2 16:18:41 2015
+Time: Mon Feb  2 16:18:42 2015

References

See also

+ +
+
(C11)
 yields the current time slice
(function)
C++ documentation for sleep_for
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/thread/thrd_sleep +

+
diff --git a/devdocs/c/thread%2Fthrd_yield.html b/devdocs/c/thread%2Fthrd_yield.html new file mode 100644 index 00000000..7eb8bcad --- /dev/null +++ b/devdocs/c/thread%2Fthrd_yield.html @@ -0,0 +1,52 @@ +

thrd_yield

Defined in header <threads.h> 
void thrd_yield(void);
+		 (since C11)

Provides a hint to the implementation to reschedule the execution of threads, allowing other threads to run.

+

Parameters

(none)

+

Return value

(none)

+

Notes

The exact behavior of this function depends on the implementation, in particular on the mechanics of the OS scheduler in use and the state of the system. For example, a first-in-first-out realtime scheduler (SCHED_FIFO in Linux) would suspend the current thread and put it on the back of the queue of the same-priority threads that are ready to run (and if there are no other threads at the same priority, yield has no effect).

+

The POSIX equivalent of this function is sched_yield.

+

Example

#include <stdio.h>
+#include <time.h>
+#include <threads.h>
+ 
+// utility function: difference between timespecs in microseconds
+double usdiff(struct timespec s, struct timespec e)
+{
+    double sdiff = difftime(e.tv_sec, s.tv_sec);
+    long nsdiff = e.tv_nsec - s.tv_nsec;
+    if(nsdiff < 0) return 1000000*(sdiff-1) + (1000000000L+nsdiff)/1000.0;
+    else return 1000000*(sdiff) + nsdiff/1000.0;
+}
+ 
+// busy wait while yielding
+void sleep_100us()
+{
+    struct timespec start, end;
+    timespec_get(&start, TIME_UTC);
+    do {
+        thrd_yield();
+        timespec_get(&end, TIME_UTC);
+    } while(usdiff(start, end) < 100.0);
+}
+ 
+int main()
+{
+    struct timespec start, end;
+    timespec_get(&start, TIME_UTC);
+    sleep_100us();
+    timespec_get(&end, TIME_UTC);
+    printf("Waited for %.3f us\n", usdiff(start, end));
+}

Possible output:

+
Waited for 100.344 us

References

See also

+ +
+
(C11)
 suspends execution of the calling thread for the given period of time
(function)
C++ documentation for yield
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/thread/thrd_yield +

+
diff --git a/devdocs/c/thread%2Fthread_local.html b/devdocs/c/thread%2Fthread_local.html new file mode 100644 index 00000000..7d760252 --- /dev/null +++ b/devdocs/c/thread%2Fthread_local.html @@ -0,0 +1,15 @@ +

thread_local

Defined in header <threads.h> 
#define thread_local _Thread_local
+		 (since C11)
(removed in C23)

Convenience macro which can be used to specify that an object has thread-local storage duration.

+

Notes

Since C23, thread_local is itself a keyword, which may also be a predefined macro, so <threads.h> no longer provides it.

+

References

See also

+
C++ documentation for thread_local
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/thread/thread_local +

+
diff --git a/devdocs/c/thread%2Ftss_create.html b/devdocs/c/thread%2Ftss_create.html new file mode 100644 index 00000000..749b3ebd --- /dev/null +++ b/devdocs/c/thread%2Ftss_create.html @@ -0,0 +1,27 @@ +

tss_create

Defined in header <threads.h> 
int tss_create( tss_t* tss_key, tss_dtor_t destructor );
+		 (since C11)

Creates new thread-specific storage key and stores it in the object pointed to by tss_key. Although the same key value may be used by different threads, the values bound to the key by tss_set are maintained on a per-thread basis and persist for the life of the calling thread.

+

The value NULL is associated with the newly created key in all existing threads, and upon thread creation, the values associated with all TSS keys is initialized to NULL.

+

If destructor is not a null pointer, then also associates the destructor which is called when the storage is released by thrd_exit (but not by tss_delete and not at program termination by exit).

+

A call to tss_create from within a thread-specific storage destructor results in undefined behavior.

+

Parameters

+ + +
tss_key - pointer to memory location to store the new thread-specific storage key
destructor - pointer to a function to call at thread exit

Notes

The POSIX equivalent of this function is pthread_key_create.

+

Return value

thrd_success if successful, thrd_error otherwise.

+

Example

int thread_func(void *arg) {
+    tss_t key;
+    if (thrd_success == tss_create(&key, free)) {
+        tss_set(key, malloc(4)); // stores a pointer on TSS
+        // ...
+    }
+} // calls free() for the pointer stored on TSS

References

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/thread/tss_create +

+
diff --git a/devdocs/c/thread%2Ftss_delete.html b/devdocs/c/thread%2Ftss_delete.html new file mode 100644 index 00000000..3540ac07 --- /dev/null +++ b/devdocs/c/thread%2Ftss_delete.html @@ -0,0 +1,21 @@ +

tss_delete

Defined in header <threads.h> 
void tss_delete( tss_t tss_id );
+		 (since C11)

Destroys the thread-specific storage identified by tss_id.

+

The destructor, if one was registered by tss_create, is not called (they are only called at thread exit, either by thrd_exit or by returning from the thread function), it is the responsibility of the programmer to ensure that every thread that is aware of tss_id performed all necessary cleanup, before the call to tss_delete is made.

+

If tss_delete is called while another thread is executing destructors for tss_id, it's unspecified whether this changes the number of invocations to the associated destructor.

+

If tss_delete is called while the calling thread is executing destructors, then the destructor associated with tss_id will not be executed again on this thread.

+

Parameters

+ +
tss_id - thread-specific storage key previously returned by tss_create and not yet deleted by tss_delete

Return value

(none)

+

Notes

The POSIX equivalent of this function is pthread_key_delete.

+

The reason tss_delete never calls destructors is that the destructors (called at thread exit) are normally intended to be executed by the same thread that originally set the value (via tss_set) that the destructor will be dealing with, and may even rely on the values of that or other thread-specific data as seen by that thread. The thread executing tss_delete has no access to other threads' TSS. Even if it were possible to call the destructor for each thread's own value associated with tss_id, tss_delete would have to synchronize with every thread if only to examine whether the value of this TSS in that thread is null (destructors are only called against non-null values).

+

Example

References

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/thread/tss_delete +

+
diff --git a/devdocs/c/thread%2Ftss_dtor_iterations.html b/devdocs/c/thread%2Ftss_dtor_iterations.html new file mode 100644 index 00000000..265b360d --- /dev/null +++ b/devdocs/c/thread%2Ftss_dtor_iterations.html @@ -0,0 +1,14 @@ +

TSS_DTOR_ITERATIONS

Defined in header <threads.h> 
#define TSS_DTOR_ITERATIONS /* unspecified */
+		 (since C11)

Expands to a positive integral constant expression defining the maximum number of times a destructor for thread-local storage pointer will be called by thrd_exit.

+

This constant is equivalent to the POSIX PTHREAD_DESTRUCTOR_ITERATIONS.

+

References

+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/thread/TSS_DTOR_ITERATIONS +

+
diff --git a/devdocs/c/thread%2Ftss_get.html b/devdocs/c/thread%2Ftss_get.html new file mode 100644 index 00000000..195f2ef1 --- /dev/null +++ b/devdocs/c/thread%2Ftss_get.html @@ -0,0 +1,20 @@ +

tss_get

Defined in header <threads.h> 
void *tss_get( tss_t tss_key );
+		 (since C11)

Returns the value held in thread-specific storage for the current thread identified by tss_key. Different threads may get different values identified by the same key.

+

On thread startup (see thrd_create), the values associated with all TSS keys are NULL. Different value may be placed in the thread-specific storage with tss_set.

+

Parameters

+ +
tss_key - thread-specific storage key, obtained from tss_create and not deleted by tss_delete

Return value

The value on success, NULL on failure.

+

Notes

The POSIX equivalent for this function is pthread_getspecific.

+

Example

References

See also

+
+
(C11)
 write to thread-specific storage
(function)
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/thread/tss_get +

+
diff --git a/devdocs/c/thread%2Ftss_set.html b/devdocs/c/thread%2Ftss_set.html new file mode 100644 index 00000000..88b4629a --- /dev/null +++ b/devdocs/c/thread%2Ftss_set.html @@ -0,0 +1,29 @@ +

tss_set

Defined in header <threads.h> 
int tss_set( tss_t tss_id, void *val );
+		 (since C11)

Sets the value of the thread-specific storage identified by tss_id for the current thread to val. Different threads may set different values to the same key.

+

The destructor, if available, is not invoked.

+

Parameters

+ + +
tss_id - thread-specific storage key, obtained from tss_create and not deleted by tss_delete
val - value to set thread-specific storage to

Return value

thrd_success if successful, thrd_error otherwise.

+

Notes

The POSIX equivalent of this function is pthread_setspecific.

+

Typically TSS is used to store pointers to blocks of dynamically allocated memory that have been reserved for use by the calling thread.

+

tss_set may be called in the TSS destructor. If the destructor exits with non-NULL value in the TSS storage, it will be retried by thrd_exit up to TSS_DTOR_ITERATIONS times, after which the storage will be lost.

+

Example

int thread_func(void *arg) {
+    tss_t key;
+    if (thrd_success == tss_create(&key, free)) {
+        tss_set(key, malloc(4)); // stores a pointer on TSS
+        // ...
+    }
+} // calls free() for the pointer stored on TSS

References

See also

+
+
(C11)
 reads from thread-specific storage
(function)
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/thread/tss_set +

+
diff --git a/devdocs/c/thread.html b/devdocs/c/thread.html new file mode 100644 index 00000000..0eca97fb --- /dev/null +++ b/devdocs/c/thread.html @@ -0,0 +1,205 @@ +

Concurrency support library

C includes built-in support for threads, atomic operations, mutual exclusion, condition variables, and thread-specific storages.

+

These features are optionally provided:

+

See also _Atomic type specifier and qualifier.

+

Threads

+ + + + + + + + + + + +
Defined in header <threads.h>
thrd_t implementation-defined complete object type identifying a thread
+
(C11)
 creates a thread
(function)
+
(C11)
 checks if two identifiers refer to the same thread
(function)
+
(C11)
 obtains the current thread identifier
(function)
+
(C11)
 suspends execution of the calling thread for the given period of time
(function)
+
(C11)
 yields the current time slice
(function)
+
(C11)
 terminates the calling thread
(function)
+
(C11)
 detaches a thread
(function)
+
(C11)
 blocks until a thread terminates
(function)
+
(C11)
 indicates a thread error status
(constant)
thrd_start_t
+
(C11)
 a typedef of the function pointer type int(*)(void*), used by thrd_create
(typedef)

Atomic operations

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Defined in header <stdatomic.h>
Operations on atomic types
+
(C11)
 indicates that the given atomic type is lock-free
(macro constant)
+
(C11)
 indicates whether the atomic object is lock-free
(function)
+
(C11)
 stores a value in an atomic object
(function)
+
(C11)
 reads a value from an atomic object
(function)
+
(C11)
 swaps a value with the value of an atomic object
(function)
+
(C11)
 swaps a value with an atomic object if the old value is what is expected, otherwise reads the old value
(function)
+
(C11)
 atomic addition
(function)
+
(C11)
 atomic subtraction
(function)
+
(C11)
 atomic bitwise OR
(function)
+
(C11)
 atomic bitwise exclusive OR
(function)
+
(C11)
 atomic bitwise AND
(function)
Flag type and operations
+
(C11)
 lock-free atomic boolean flag
(struct)
+
(C11)
 sets an atomic_flag to true and returns the old value
(function)
+
(C11)
 sets an atomic_flag to false
(function)
Initialization
+
(C11)
 initializes an existing atomic object
(function)
+
(C11)(deprecated in C17)(removed in C23)
 initializes a new atomic object
(function macro)
+
(C11)
 initializes a new atomic_flag
(macro constant)
Memory synchronization ordering
+
(C11)
 defines memory ordering constraints
(enum)
+
(C11)
 breaks a dependency chain for memory_order_consume
(function macro)
+
(C11)
 generic memory order-dependent fence synchronization primitive
(function)
+
(C11)
 fence between a thread and a signal handler executed in the same thread
(function)
Convenience type aliases
Typedef name Full type name
atomic_bool(C11) _Atomic _Bool
atomic_char(C11) _Atomic char
atomic_schar(C11) _Atomic signed char
atomic_uchar(C11) _Atomic unsigned char
atomic_short(C11) _Atomic short
atomic_ushort(C11) _Atomic unsigned short
atomic_int(C11) _Atomic int
atomic_uint(C11) _Atomic unsigned int
atomic_long(C11) _Atomic long
atomic_ulong(C11) _Atomic unsigned long
atomic_llong(C11) _Atomic long long
atomic_ullong(C11) _Atomic unsigned long long
atomic_char8_t(C23) _Atomic char8_t
atomic_char16_t(C11) _Atomic char16_t
atomic_char32_t(C11) _Atomic char32_t
atomic_wchar_t(C11) _Atomic wchar_t
atomic_int_least8_t(C11) _Atomic int_least8_t
atomic_uint_least8_t(C11) _Atomic uint_least8_t
atomic_int_least16_t(C11) _Atomic int_least16_t
atomic_uint_least16_t(C11) _Atomic uint_least16_t
atomic_int_least32_t(C11) _Atomic int_least32_t
atomic_uint_least32_t(C11) _Atomic uint_least32_t
atomic_int_least64_t(C11) _Atomic int_least64_t
atomic_uint_least64_t(C11) _Atomic uint_least64_t
atomic_int_fast8_t(C11) _Atomic int_fast8_t
atomic_uint_fast8_t(C11) _Atomic uint_fast8_t
atomic_int_fast16_t(C11) _Atomic int_fast16_t
atomic_uint_fast16_t(C11) _Atomic uint_fast16_t
atomic_int_fast32_t(C11) _Atomic int_fast32_t
atomic_uint_fast32_t(C11) _Atomic uint_fast32_t
atomic_int_fast64_t(C11) _Atomic int_fast64_t
atomic_uint_fast64_t(C11) _Atomic uint_fast64_t
atomic_intptr_t(C11) _Atomic intptr_t
atomic_uintptr_t(C11) _Atomic uintptr_t
atomic_size_t(C11) _Atomic size_t
atomic_ptrdiff_t(C11) _Atomic ptrdiff_t
atomic_intmax_t(C11) _Atomic intmax_t
atomic_uintmax_t(C11) _Atomic uintmax_t

Mutual exclusion

+ + + + + + + + + + +
Defined in header <threads.h>
mtx_t mutex identifier
+
(C11)
 creates a mutex
(function)
+
(C11)
 blocks until locks a mutex
(function)
+
(C11)
 blocks until locks a mutex or times out
(function)
+
(C11)
 locks a mutex or returns without blocking if already locked
(function)
+
(C11)
 unlocks a mutex
(function)
+
(C11)
 destroys a mutex
(function)
+
(C11)(C11)(C11)
 defines the type of a mutex
(enum)
Call once
+
(C11)
 calls a function exactly once
(function)

Condition variables

+ + + + + + + +
Defined in header <threads.h>
cnd_t condition variable identifier
+
(C11)
 creates a condition variable
(function)
+
(C11)
 unblocks one thread blocked on a condition variable
(function)
+
(C11)
 unblocks all threads blocked on a condition variable
(function)
+
(C11)
 blocks on a condition variable
(function)
+
(C11)
 blocks on a condition variable, with a timeout
(function)
+
(C11)
 destroys a condition variable
(function)

Thread-local storage

+ + + + + + + + +
Defined in header <threads.h>
+
(C11)(removed in C23)
 convenience macro for storage-class specifier _Thread_local
(keyword macro)
tss_t thread-specific storage pointer
+
(C11)
 maximum number of times destructors are called
(macro constant)
tss_dtor_t
+
(C11)
 function pointer type void(*)(void*), used for TSS destructor
(typedef)
+
(C11)
 creates thread-specific storage pointer with a given destructor
(function)
+
(C11)
 reads from thread-specific storage
(function)
+
(C11)
 write to thread-specific storage
(function)
+
(C11)
 releases the resources held by a given thread-specific pointer
(function)

Reserved identifiers

In future revisions of the C standard:

+

Identifiers reserved for functions names are always potentially(since C23) reserved for use as identifiers with external linkage, while other identifiers list here are potentially(since C23) reserved when <stdatomic.h> is included.

+

Declaring, defining, or #undefing such an identifier results in undefined behavior if it is provided by the standard or implementation(since C23). Portable programs should not use those identifiers.

+

References

See also

+
C++ documentation for Concurrency support library
+ +
+GNU GCC Libc Manual: ISO C Mutexes
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/thread +

+
diff --git a/devdocs/c/types%2Finteger.html b/devdocs/c/types%2Finteger.html new file mode 100644 index 00000000..2815d35d --- /dev/null +++ b/devdocs/c/types%2Finteger.html @@ -0,0 +1,140 @@ +

Fixed width integer types (since C99) +

Types

+ + + + + + + + + + +
Defined in header <stdint.h>
int8_t
int16_t
int32_t
int64_t 		signed integer type with width of
exactly 8, 16, 32 and 64 bits respectively
with no padding bits and using 2's complement for negative values
(provided only if the implementation directly supports the type)
int_fast8_t
int_fast16_t
int_fast32_t
int_fast64_t 		fastest signed integer type with width of
at least 8, 16, 32 and 64 bits respectively
int_least8_t
int_least16_t
int_least32_t
int_least64_t 		smallest signed integer type with width of
at least 8, 16, 32 and 64 bits respectively
intmax_t maximum width integer type
intptr_t integer type capable of holding a pointer
uint8_t
uint16_t
uint32_t
uint64_t 		unsigned integer type with width of
exactly 8, 16, 32 and 64 bits respectively
(provided only if the implementation directly supports the type)
uint_fast8_t
uint_fast16_t
uint_fast32_t
uint_fast64_t 		fastest unsigned integer type with width of
at least 8, 16, 32 and 64 bits respectively
uint_least8_t
uint_least16_t
uint_least32_t
uint_least64_t 		smallest unsigned integer type with width of
at least 8, 16, 32 and 64 bits respectively
uintmax_t maximum width unsigned integer type
uintptr_t unsigned integer type capable of holding a pointer

The implementation may define typedef names intN_t, int_fastN_t, int_leastN_t, uintN_t, uint_fastN_t, and uint_leastN_t when N is not 8, 16, 32 or 64. Typedef names of the form intN_t may only be defined if the implementation supports an integer type of that width with no padding. Thus, uint24_t denotes an unsigned integer type with a width of exactly 24 bits.

+

Each of the macros listed in below is defined if and only if the implementation defines the corresponding typedef name. The macros INTN_C and UINTN_C correspond to the typedef names int_leastN_t and uint_leastN_t, respectively.

+

Macro constants

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Defined in header <stdint.h>
Signed integers : width
INT8_WIDTHINT16_WIDTHINT32_WIDTHINT64_WIDTH
+
(C23)(optional)
 bit width of an object of type int8_t, int16_t, int32_t, int64_t (exactly 8, 16, 32, 64)
(macro constant)
INT_FAST8_WIDTHINT_FAST16_WIDTHINT_FAST32_WIDTHINT_FAST64_WIDTH
+
(C23)
 bit width of an object of type int_fast8_t, int_fast16_t, int_fast32_t, int_fast64_t
(macro constant)
INT_LEAST8_WIDTHINT_LEAST16_WIDTHINT_LEAST32_WIDTHINT_LEAST64_WIDTH
+
(C23)
 bit width of an object of type int_least8_t, int_least16_t, int_least32_t, int_least64_t
(macro constant)
INTPTR_WIDTH
+
(C23)(optional)
 bit width of an object of type intptr_t
(macro constant)
INTMAX_WIDTH
+
(C23)
 bit width of an object of type intmax_t
(macro constant)
Signed integers : minimum value
INT8_MININT16_MININT32_MININT64_MIN
 minimum value of an object of type int8_t, int16_t, int32_t, int64_t
(macro constant)
INT_FAST8_MININT_FAST16_MININT_FAST32_MININT_FAST64_MIN
 minimum value of an object of type int_fast8_t, int_fast16_t, int_fast32_t, int_fast64_t
(macro constant)
INT_LEAST8_MININT_LEAST16_MININT_LEAST32_MININT_LEAST64_MIN
 minimum value of an object of type int_least8_t, int_least16_t, int_least32_t, int_least64_t
(macro constant)
INTPTR_MIN
 minimum value of an object of type intptr_t
(macro constant)
INTMAX_MIN
 minimum value of an object of type intmax_t
(macro constant)
Signed integers : maximum value
INT8_MAXINT16_MAXINT32_MAXINT64_MAX
 maximum value of an object of type int8_t, int16_t, int32_t, int64_t
(macro constant)
INT_FAST8_MAXINT_FAST16_MAXINT_FAST32_MAXINT_FAST64_MAX
 maximum value of an object of type int_fast8_t, int_fast16_t, int_fast32_t, int_fast64_t
(macro constant)
INT_LEAST8_MAXINT_LEAST16_MAXINT_LEAST32_MAXINT_LEAST64_MAX
 maximum value of an object of type int_least8_t, int_least16_t, int_least32_t, int_least64_t
(macro constant)
INTPTR_MAX
 maximum value of an object of type intptr_t
(macro constant)
INTMAX_MAX
 maximum value of an object of type intmax_t
(macro constant)
Unsigned integers : width
UINT8_WIDTHUINT16_WIDTHUINT32_WIDTHUINT64_WIDTH
+
(C23)(optional)
 bit width of an object of type uint8_t, uint16_t, uint32_t, uint64_t (exactly 8, 16, 32, 64)
(macro constant)
UINT_FAST8_WIDTHUINT_FAST16_WIDTHUINT_FAST32_WIDTHUINT_FAST64_WIDTH
+
(C23)
 bit width of an object of type uint_fast8_t, uint_fast16_t, uint_fast32_t, uint_fast64_t
(macro constant)
UINT_LEAST8_WIDTHUINT_LEAST16_WIDTHUINT_LEAST32_WIDTHUINT_LEAST64_WIDTH
+
(C23)
 bit width of an object of type uint_least8_t, uint_least16_t, uint_least32_t, uint_least64_t
(macro constant)
UINTPTR_WIDTH
+
(C23)(optional)
 bit width of an object of type uintptr_t
(macro constant)
UINTMAX_WIDTH
+
(C23)
 bit width of an object of type uintmax_t
(macro constant)
Unsigned integers : maximum value
UINT8_MAXUINT16_MAXUINT32_MAXUINT64_MAX
 maximum value of an object of type uint8_t, uint16_t, uint32_t, uint64_t
(macro constant)
UINT_FAST8_MAXUINT_FAST16_MAXUINT_FAST32_MAXUINT_FAST64_MAX
 maximum value of an object of type uint_fast8_t, uint_fast16_t, uint_fast32_t, uint_fast64_t
(macro constant)
UINT_LEAST8_MAXUINT_LEAST16_MAXUINT_LEAST32_MAXUINT_LEAST64_MAX
 maximum value of an object of type uint_least8_t, uint_least16_t, uint_least32_t, uint_least64_t
(macro constant)
UINTPTR_MAX
 maximum value of an object of type uintptr_t
(macro constant)
UINTMAX_MAX
 maximum value of an object of type uintmax_t
(macro constant)

Function macros for minimum-width integer constants

+ + + +
INT8_CINT16_CINT32_CINT64_C
 expands to an integer constant expression having the value specified by its argument and the type int_least8_t, int_least16_t, int_least32_t, int_least64_t respectively
(function macro)
INTMAX_C
 expands to an integer constant expression having the value specified by its argument and the type intmax_t
(function macro)
UINT8_CUINT16_CUINT32_CUINT64_C
 expands to an integer constant expression having the value specified by its argument and the type uint_least8_t, uint_least16_t, uint_least32_t, uint_least64_t respectively
(function macro)
UINTMAX_C
 expands to an integer constant expression having the value specified by its argument and the type uintmax_t
(function macro) 
#include <stdint.h>
+UINT64_C(0x123) // might expand to 0x123ULL or 0x123UL

Format macro constants

+
Defined in header <inttypes.h>

Format constants for the fprintf family of functions

Each of the PRI macros listed here is defined if and only if the implementation defines the corresponding typedef name.

+ + + + + + + + + +
Equivalent
for int or
unsigned int 		Description Macros for data types
+



[u]intx_t
+



 +
[u]int_leastx_t
 +
[u]int_fastx_t
 +
[u]intmax_t
 +
[u]intptr_t
d output of a signed decimal integer value PRIdx PRIdLEASTx PRIdFASTx PRIdMAX PRIdPTR
i PRIix PRIiLEASTx PRIiFASTx PRIiMAX PRIiPTR
u output of an unsigned decimal integer value PRIux PRIuLEASTx PRIuFASTx PRIuMAX PRIuPTR
o output of an unsigned octal integer value PRIox PRIoLEASTx PRIoFASTx PRIoMAX PRIoPTR
x output of an unsigned lowercase hexadecimal integer value PRIxx PRIxLEASTx PRIxFASTx PRIxMAX PRIxPTR
X output of an unsigned uppercase hexadecimal integer value PRIXx PRIXLEASTx PRIXFASTx PRIXMAX PRIXPTR

Format constants for the fscanf family of functions

Each of the SCN macros listed in here is defined if and only if the implementation defines the corresponding typedef name and has a suitable fscanf length modifier for the type.

+ + + + + + + + +
Equivalent
for int or
unsigned int 		Description Macros for data types
+



[u]intx_t
+



 +
[u]int_leastx_t
 +
[u]int_fastx_t
 +
[u]intmax_t
 +
[u]intptr_t
d input of a signed decimal integer value SCNdx SCNdLEASTx SCNdFASTx SCNdMAX SCNdPTR
i input of a signed integer value (base is determined by the first characters parsed) SCNix SCNiLEASTx SCNiFASTx SCNiMAX SCNiPTR
u input of an unsigned decimal integer value SCNux SCNuLEASTx SCNuFASTx SCNuMAX SCNuPTR
o input of an unsigned octal integer value SCNox SCNoLEASTx SCNoFASTx SCNoMAX SCNoPTR
x input of an unsigned hexadecimal integer value SCNxx SCNxLEASTx SCNxFASTx SCNxMAX SCNxPTR

Example

+

See also C++ compatibility note regarding spaces before format macros used in this example.

+
#include <inttypes.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    printf("%zu\n", sizeof(int64_t));
+    printf("%s\n", PRId64);
+    printf("%+" PRId64 "\n", INT64_MIN);
+    printf("%+" PRId64 "\n", INT64_MAX);
+ 
+    int64_t n = 7;
+    printf("%+" PRId64 "\n", n);
+}

Possible output:

+
8
+lld
+-9223372036854775808
++9223372036854775807
++7

References

See also

+ +
C++ documentation for Fixed width integer types
C++ documentation for User-defined literals (formatting macros note)
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/types/integer +

+
diff --git a/devdocs/c/types%2Flimits%2Fflt_eval_method.html b/devdocs/c/types%2Flimits%2Fflt_eval_method.html new file mode 100644 index 00000000..805e2a66 --- /dev/null +++ b/devdocs/c/types%2Flimits%2Fflt_eval_method.html @@ -0,0 +1,19 @@ +

FLT_EVAL_METHOD

Defined in header <float.h> 
#define FLT_EVAL_METHOD /* implementation defined */
+		 (since C99)

Specifies range and precision of floating-point values obtained from floating-point constants and from all operations (operators, implicit conversions of operands) except assignment, cast, and library function call.

+ + + + + + +
Value Explanation
negative values except -1 implementation-defined behavior
-1 the default precision is not known
0 all operations and constants evaluate in the range and precision of the type used. Additionally, float_t and double_t are equivalent to float and double respectively
1 all operations and constants evaluate in the range and precision of double. Additionally, both float_t and double_t are equivalent to double
2 all operations and constants evaluate in the range and precision of long double. Additionally, both float_t and double_t are equivalent to long double

Notes

Regardless of the value of FLT_EVAL_METHOD, any floating-point expression may be contracted, that is, calculated as if all intermediate results have infinite range and precision (unless #pragma STDC FP_CONTRACT is off)

+

Cast and assignment strip away any extraneous range and precision: this models the action of storing a value from an extended-precision FPU register into a standard-sized memory location.

+

See also

+ +
+
(C99)(C99)
 most efficient floating-point type at least as wide as float or double
(typedef)
C++ documentation for FLT_EVAL_METHOD
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/types/limits/FLT_EVAL_METHOD +

+
diff --git a/devdocs/c/types%2Flimits%2Fflt_rounds.html b/devdocs/c/types%2Flimits%2Fflt_rounds.html new file mode 100644 index 00000000..0386877f --- /dev/null +++ b/devdocs/c/types%2Flimits%2Fflt_rounds.html @@ -0,0 +1,21 @@ +

FLT_ROUNDS

Defined in header <float.h> 
#define FLT_ROUNDS /* implementation defined */
+

Returns the current rounding direction of floating-point arithmetic operations.

+ + + + + + + +
Value Explanation
-1 the default rounding direction is not known
0 toward zero; same meaning as FE_TOWARDZERO
1 to nearest; same meaning as FE_TONEAREST
2 towards positive infinity; same meaning as FE_UPWARD
3 towards negative infinity; same meaning as FE_DOWNWARD
other values implementation-defined behavior

Notes

The rounding mode can be changed with fesetround and FLT_ROUNDS reflects that change.

+

See also

+ + +
+
(C99)(C99)
 gets or sets rounding direction
(function)
+
(C99)
 floating-point rounding direction
(macro constant)
C++ documentation for FLT_ROUNDS
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/types/limits/FLT_ROUNDS +

+
diff --git a/devdocs/c/types%2Flimits.html b/devdocs/c/types%2Flimits.html new file mode 100644 index 00000000..ea79ff4c --- /dev/null +++ b/devdocs/c/types%2Flimits.html @@ -0,0 +1,218 @@ +

Numeric limits

Limits of integer types

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Limits of core language integer types
Defined in header <limits.h>
BOOL_WIDTH
+
(C23)
 bit width of _Bool
(macro constant)
CHAR_BIT
 number of bits in a byte
(macro constant)
MB_LEN_MAX
 maximum number of bytes in a multibyte character
(macro constant)
CHAR_WIDTH
+
(C23)
 bit width of char, same as CHAR_BIT
(macro constant)
CHAR_MIN
 minimum value of char
(macro constant)
CHAR_MAX
 maximum value of char
(macro constant)
SCHAR_WIDTHSHRT_WIDTHINT_WIDTHLONG_WIDTHLLONG_WIDTH
+
(C23)(C23)(C23)(C23)(C23)
 bit width of signed char, short, int, long, and long long respectively
(macro constant)
SCHAR_MINSHRT_MININT_MINLONG_MINLLONG_MIN
+
(C99)
 minimum value of signed char, short, int, long and long long respectively
(macro constant)
SCHAR_MAXSHRT_MAXINT_MAXLONG_MAXLLONG_MAX
+
(C99)
 maximum value of signed char, short, int, long and long long respectively
(macro constant)
UCHAR_WIDTHUSHRT_WIDTHUINT_WIDTHULONG_WIDTHULLONG_WIDTH
+
(C23)(C23)(C23)(C23)(C23)
 bit width of unsigned char, unsigned short, unsigned int, unsigned long, and unsigned long long respectively
(macro constant)
UCHAR_MAXUSHRT_MAXUINT_MAXULONG_MAXULLONG_MAX
+
(C99)
 maximum value of unsigned char, unsigned short, unsigned int,
unsigned long and unsigned long long respectively
(macro constant)
BITINT_MAXWIDTH
+
(C23)
 maximum width N supported by the declaration of a bit-precise integer in the type specifier _BitInt(N), greater than or equal to ULLONG_WIDTH
(macro constant)
Limits of library type aliases
Defined in header <stdint.h>
PTRDIFF_WIDTH
+
(C23)
 bit width of object of ptrdiff_t type
(macro constant)
PTRDIFF_MIN
+
(C99)
 minimum value of ptrdiff_t
(macro constant)
PTRDIFF_MAX
+
(C99)
 maximum value of ptrdiff_t
(macro constant)
SIZE_WIDTH
+
(C23)
 bit width of object of size_t type
(macro constant)
SIZE_MAX
+
(C99)
 maximum value of size_t
(macro constant)
SIG_ATOMIC_WIDTH
+
(C23)
 bit width of object of sig_atomic_t type
(macro constant)
SIG_ATOMIC_MIN
+
(C99)
 minimum value of sig_atomic_t
(macro constant)
SIG_ATOMIC_MAX
+
(C99)
 maximum value of sig_atomic_t
(macro constant)
WINT_WIDTH
+
(C23)
 bit width of object of wint_t type
(macro constant)
WINT_MIN
+
(C99)
 minimum value of wint_t
(macro constant)
WINT_MAX
+
(C99)
 maximum value of wint_t
(macro constant)
Defined in header <wchar.h>
Defined in header <stdint.h>
WCHAR_WIDTH
+
(C23)
 bit width of object of wchar_t type
(macro constant)
WCHAR_MIN
+
(C99)
 minimum value of wchar_t
(macro constant)
WCHAR_MAX
+
(C99)
 maximum value of wchar_t
(macro constant)

Notes

The types of these constants, other than CHAR_BIT and MB_LEN_MAX, are required to match the results of the integral promotions as applied to objects of the types they describe: CHAR_MAX may have type int or unsigned int, but never char. Similarly USHRT_MAX may not be of an unsigned type: its type may be int.

+

A freestanding implementation may lack sig_atomic_t and/or wint_t typedef names, in which case the SIG_ATOMIC_* and/or WINT_* macros are correspondingly absent.

+

Example

#include <limits.h>
+#include <stdint.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    printf("CHAR_BIT       = %d\n", CHAR_BIT);
+    printf("MB_LEN_MAX     = %d\n\n", MB_LEN_MAX);
+ 
+    printf("CHAR_MIN       = %+d\n", CHAR_MIN);
+    printf("CHAR_MAX       = %+d\n", CHAR_MAX);
+    printf("SCHAR_MIN      = %+d\n", SCHAR_MIN);
+    printf("SCHAR_MAX      = %+d\n", SCHAR_MAX);
+    printf("UCHAR_MAX      = %u\n\n", UCHAR_MAX);
+ 
+    printf("SHRT_MIN       = %+d\n", SHRT_MIN);
+    printf("SHRT_MAX       = %+d\n", SHRT_MAX);
+    printf("USHRT_MAX      = %u\n\n", USHRT_MAX);
+ 
+    printf("INT_MIN        = %+d\n", INT_MIN);
+    printf("INT_MAX        = %+d\n", INT_MAX);
+    printf("UINT_MAX       = %u\n\n", UINT_MAX);
+ 
+    printf("LONG_MIN       = %+ld\n", LONG_MIN);
+    printf("LONG_MAX       = %+ld\n", LONG_MAX);
+    printf("ULONG_MAX      = %lu\n\n", ULONG_MAX);
+ 
+    printf("LLONG_MIN      = %+lld\n", LLONG_MIN);
+    printf("LLONG_MAX      = %+lld\n", LLONG_MAX);
+    printf("ULLONG_MAX     = %llu\n\n", ULLONG_MAX);
+ 
+    printf("PTRDIFF_MIN    = %td\n", PTRDIFF_MIN);
+    printf("PTRDIFF_MAX    = %+td\n", PTRDIFF_MAX);
+    printf("SIZE_MAX       = %zu\n", SIZE_MAX);
+    printf("SIG_ATOMIC_MIN = %+jd\n",(intmax_t)SIG_ATOMIC_MIN);
+    printf("SIG_ATOMIC_MAX = %+jd\n",(intmax_t)SIG_ATOMIC_MAX);
+    printf("WCHAR_MIN      = %+jd\n",(intmax_t)WCHAR_MIN);
+    printf("WCHAR_MAX      = %+jd\n",(intmax_t)WCHAR_MAX);
+    printf("WINT_MIN       = %jd\n", (intmax_t)WINT_MIN);
+    printf("WINT_MAX       = %jd\n", (intmax_t)WINT_MAX);
+}

Possible output:

+
CHAR_BIT       = 8
+MB_LEN_MAX     = 16
+ 
+CHAR_MIN       = -128
+CHAR_MAX       = +127
+SCHAR_MIN      = -128
+SCHAR_MAX      = +127
+UCHAR_MAX      = 255
+ 
+SHRT_MIN       = -32768
+SHRT_MAX       = +32767
+USHRT_MAX      = 65535
+ 
+INT_MIN        = -2147483648
+INT_MAX        = +2147483647
+UINT_MAX       = 4294967295
+ 
+LONG_MIN       = -9223372036854775808
+LONG_MAX       = +9223372036854775807
+ULONG_MAX      = 18446744073709551615
+ 
+LLONG_MIN      = -9223372036854775808
+LLONG_MAX      = +9223372036854775807
+ULLONG_MAX     = 18446744073709551615
+ 
+PTRDIFF_MIN    = -9223372036854775808
+PTRDIFF_MAX    = +9223372036854775807
+SIZE_MAX       = 18446744073709551615
+SIG_ATOMIC_MIN = -2147483648
+SIG_ATOMIC_MAX = +2147483647
+WCHAR_MIN      = -2147483648
+WCHAR_MAX      = +2147483647
+WINT_MIN       = 0
+WINT_MAX       = 4294967295

Limits of floating-point types

+ + + + + + + + + + + + + + + +
Defined in header <float.h>
FLT_RADIX
 the radix (integer base) used by the representation of all three floating-point types
(macro constant)
DECIMAL_DIG
+
(C99)
 conversion from long double to decimal with at least DECIMAL_DIG digits and back to long double is the identity conversion: this is the decimal precision required to serialize/deserialize a long double
(macro constant)
FLT_DECIMAL_DIGDBL_DECIMAL_DIGLDBL_DECIMAL_DIG
+
(C11)
 conversion from float/double/long double to decimal with at least FLT_DECIMAL_DIG/DBL_DECIMAL_DIG/LDBL_DECIMAL_DIG digits and back is the identity conversion: this is the decimal precision required to serialize/deserialize a floating-point value. Defined to at least 6, 10, and 10 respectively, or 9 for IEEE float and 17 for IEEE double (see also the C++ analog: max_digits10)
(macro constant)
FLT_MINDBL_MINLDBL_MIN
 minimum, normalized, positive value of float, double and long double respectively
(macro constant)
FLT_TRUE_MINDBL_TRUE_MINLDBL_TRUE_MIN
+
(C11)
 minimum positive value of float, double and long double respectively
(macro constant)
FLT_MAXDBL_MAXLDBL_MAX
 maximum finite value of float, double and long double respectively
(macro constant)
FLT_EPSILONDBL_EPSILONLDBL_EPSILON
 absolute value difference between 1.0 and the next representable value for float, double and long double respectively
(macro constant)
FLT_DIGDBL_DIGLDBL_DIG
 number of decimal digits that are guaranteed to be preserved in text → float/double/long double → text roundtrip without change due to rounding or overflow (see the C++ analog digits10 for detail)
(macro constant)
FLT_MANT_DIGDBL_MANT_DIGLDBL_MANT_DIG
 number of base-FLT_RADIX digits that are in the floating-point mantissa and that can be represented without losing precision for float, double and long double respectively
(macro constant)
FLT_MIN_EXPDBL_MIN_EXPLDBL_MIN_EXP
 minimum negative integer such that FLT_RADIX raised by power one less than that integer is a normalized float, double and long double respectively
(macro constant)
FLT_MIN_10_EXPDBL_MIN_10_EXPLDBL_MIN_10_EXP
 minimum negative integer such that 10 raised by power one less than that integer is a normalized float, double and long double respectively
(macro constant)
FLT_MAX_EXPDBL_MAX_EXPLDBL_MAX_EXP
 maximum positive integer such that FLT_RADIX raised by power one less than that integer is a representable finite float, double and long double respectively
(macro constant)
FLT_MAX_10_EXPDBL_MAX_10_EXPLDBL_MAX_10_EXP
 maximum positive integer such that 10 raised by power one less than that integer is a representable finite float, double and long double respectively
(macro constant)
rounding mode of floating-point arithmetic
(macro constant)
+
(C99)
 use of extended precision for intermediate results:
​0​ – not used, 1 – double is used instead of float, 2 – long double is used
(macro constant)
+
FLT_HAS_SUBNORMDBL_HAS_SUBNORMLDBL_HAS_SUBNORM
+
(C11)(deprecated in C23)
 whether the type supports subnormal (denormal) numbers:
-1 – indeterminable, ​0​ – absent, 1 – present
(macro constant)

Example

#include <float.h>
+#include <math.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    printf("DECIMAL_DIG     = %d\n", DECIMAL_DIG);
+    printf("FLT_DECIMAL_DIG = %d\n", FLT_DECIMAL_DIG);
+    printf("FLT_RADIX       = %d\n", FLT_RADIX);
+    printf("FLT_MIN         = %e\n", FLT_MIN);
+    printf("FLT_MAX         = %e\n", FLT_MAX);
+    printf("FLT_EPSILON     = %e\n", FLT_EPSILON);
+    printf("FLT_DIG         = %d\n", FLT_DIG);
+    printf("FLT_MANT_DIG    = %d\n", FLT_MANT_DIG);
+    printf("FLT_MIN_EXP     = %d\n", FLT_MIN_EXP);
+    printf("FLT_MIN_10_EXP  = %d\n", FLT_MIN_10_EXP);
+    printf("FLT_MAX_EXP     = %d\n", FLT_MAX_EXP);
+    printf("FLT_MAX_10_EXP  = %d\n", FLT_MAX_10_EXP);
+    printf("FLT_ROUNDS      = %d\n", FLT_ROUNDS);
+    printf("FLT_EVAL_METHOD = %d\n", FLT_EVAL_METHOD);
+    printf("FLT_HAS_SUBNORM = %d\n", FLT_HAS_SUBNORM);
+}

Possible output:

+
DECIMAL_DIG     = 37
+FLT_DECIMAL_DIG = 9
+FLT_RADIX       = 2
+FLT_MIN         = 1.175494e-38
+FLT_MAX         = 3.402823e+38
+FLT_EPSILON     = 1.192093e-07
+FLT_DIG         = 6
+FLT_MANT_DIG    = 24
+FLT_MIN_EXP     = -125
+FLT_MIN_10_EXP  = -37
+FLT_MAX_EXP     = 128
+FLT_MAX_10_EXP  = 38
+FLT_ROUNDS      = 1
+FLT_EVAL_METHOD = 1
+FLT_HAS_SUBNORM = 1

References

See also

+
C++ documentation for C numeric limits interface
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/types/limits +

+
diff --git a/devdocs/c/types%2Fmax_align_t.html b/devdocs/c/types%2Fmax_align_t.html new file mode 100644 index 00000000..32a94bae --- /dev/null +++ b/devdocs/c/types%2Fmax_align_t.html @@ -0,0 +1,34 @@ +

max_align_t

Defined in header <stddef.h> 
typedef /*implementation-defined*/ max_align_t;
+		 (since C11)

max_align_t is a type whose alignment requirement is at least as strict (as large) as that of every scalar type.

+

Notes

Pointers returned by allocation functions such as malloc are suitably aligned for any object, which means they are aligned at least as strictly as max_align_t.

+

max_align_t is usually synonymous with the largest scalar type, which is long double on most platforms, and its alignment requirement is either 8 or 16.

+

Example

#include <stdio.h>
+#include <stddef.h>
+#include <stdalign.h>
+#include <stdlib.h>
+#include <stdint.h>
+#include <inttypes.h>
+ 
+int main(void)
+{
+    size_t a = alignof(max_align_t);
+    printf("Alignment of max_align_t is %zu (%#zx)\n", a, a);
+ 
+    void *p = malloc(123);
+    printf("The address obtained from malloc(123) is %#" PRIxPTR"\n",
+            (uintptr_t)p);
+    free(p);
+}

Possible output:

+
Alignment of max_align_t is 16 (0x10)
+The address obtained from malloc(123) is 0x1fa67010

References

See also

+
C++ documentation for max_align_t
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/types/max_align_t +

+
diff --git a/devdocs/c/types%2Fnull.html b/devdocs/c/types%2Fnull.html new file mode 100644 index 00000000..fc9462a8 --- /dev/null +++ b/devdocs/c/types%2Fnull.html @@ -0,0 +1,47 @@ +

NULL

Defined in header <locale.h>
Defined in header <stddef.h>
Defined in header <stdio.h>
Defined in header <stdlib.h>
Defined in header <string.h>
Defined in header <time.h>
Defined in header <wchar.h> 
#define NULL /*implementation-defined*/
+

The macro NULL is an implementation-defined null pointer constant, which may be

+ + +
(since C23)

A null pointer constant may be converted to any pointer type; such conversion results in the null pointer value of that type.

+

Possible implementation

+ +
// C++ compatible:
+#define NULL 0
+// C++ incompatible:
+#define NULL (10*2 - 20)
+#define NULL ((void*)0)
+// since C23 (compatible with C++11 and later)
+#define NULL nullptr

Example

#include <inttypes.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+ 
+int main(void)
+{
+    // any kind of pointer can be set to NULL
+    int* p = NULL;
+    struct S *s = NULL;
+    void(*f)(int, double) = NULL;
+    printf("%p %p %p\n", (void*)p, (void*)s, (void*)(long)f);
+ 
+    // many pointer-returning functions use null pointers to indicate error
+    char *ptr = malloc(0xFULL);
+    if (ptr == NULL)
+        printf("Out of memory");
+    else
+        printf("ptr = %#" PRIxPTR"\n", (uintptr_t)ptr);
+    free(ptr);
+}

Possible output:

+
(nil) (nil) (nil)
+ptr = 0xc001cafe

See also

+ +
+
(C23)
 the type of the predefined null pointer constant nullptr
(typedef)
C++ documentation for NULL
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/types/NULL +

+
diff --git a/devdocs/c/types%2Fnullptr_t.html b/devdocs/c/types%2Fnullptr_t.html new file mode 100644 index 00000000..ea058783 --- /dev/null +++ b/devdocs/c/types%2Fnullptr_t.html @@ -0,0 +1,32 @@ +

nullptr_t

Defined in header <stddef.h> 
typedef typeof(nullptr) nullptr_t;
+		 (since C23)

nullptr_t is the type of the predefined null pointer constant, nullptr. It is a distinct type that is not itself a pointer type. It can be implicitly converted to any pointer type or bool, and the result is the null pointer value of that type or false respectively. No type other than nullptr_t itself can be converted or explicitly cast to nullptr_t.

+

sizeof(nullptr_t) and alignof(nullptr_t) are equal to sizeof(void*) and alignof(void*) respectively.

+

nullptr_t has only one valid value, i.e., nullptr. The object representation of nullptr is same as that of (void*)0. If a program produces a nullptr_t value with a different object representation, the behavior is undefined.

+

Example

+

Demonstrate that nullptr_t is a distinct type.

+
#include <stddef.h>
+#include <stdio.h>
+ 
+#define DETECT_NULL_POINTER_CONSTANT(e) \
+    _Generic(e,                         \
+        void* : puts("void*"),          \
+        nullptr_t : puts("nullptr_t"),  \
+        default : puts("other")       \
+    )
+ 
+int main()
+{
+    DETECT_NULL_POINTER_CONSTANT(((void*)0));
+    DETECT_NULL_POINTER_CONSTANT(0);
+    DETECT_NULL_POINTER_CONSTANT(nullptr);
+}

Output:

+
void*
+other
+nullptr_t

See also

+ +
implementation-defined null pointer constant
(macro constant)
C++ documentation for nullptr_t
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/types/nullptr_t +

+
diff --git a/devdocs/c/types%2Foffsetof.html b/devdocs/c/types%2Foffsetof.html new file mode 100644 index 00000000..b8739a55 --- /dev/null +++ b/devdocs/c/types%2Foffsetof.html @@ -0,0 +1,39 @@ +

offsetof

Defined in header <stddef.h> 
#define offsetof(type, member) /*implementation-defined*/
+

The macro offsetof expands to an integer constant expression of type size_t, the value of which is the offset, in bytes, from the beginning of an object of specified type to its specified subobject, including padding if any.

+

Given an object o of type type with static storage duration, &(o.member) shall be an address constant expression and point to a subobject of o. Otherwise, the behavior is undefined.

+ + +

If the type name specified in type contains a comma not between matching parentheses, the behavior is undefined.

+		 (since C23)

Notes

If offsetof is applied to a bit-field member, the behavior is undefined, because the address of a bit-field cannot be taken.

+

member is not restricted to a direct member. It can denote a subobject of a given member, such as an element of an array member.

+

Even though it is specified in C23 that specifying a new type containg an unparenthesized comma in offsetof is undefined behavior, such usage is generally not supported even in earlier modes: offsetof(struct Foo { int a, b; }, a) generally fails to compile.

+ + +

typeof can be used to avoid the bad effect of commas in the definition of a new type, e.g. offsetof(typeof(struct { int i, j; }), i) is well-defined.

+		 (since C23)

Example

#include <stdio.h>
+#include <stddef.h>
+ 
+struct S {
+    char c;
+    double d;
+};
+ 
+int main(void)
+{
+    printf("the first element is at offset %zu\n", offsetof(struct S, c));
+    printf("the double is at offset %zu\n", offsetof(struct S, d));
+}

Possible output:

+
the first element is at offset 0
+the double is at offset 8

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C standards.

+ + + +
DR Applied to Behavior as published Correct behavior
+DR 496 C89 only structs and struct members were mentioned unions and other subobjects are also supported

See also

+ +
unsigned integer type returned by the sizeof operator
(typedef)
C++ documentation for offsetof
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/types/offsetof +

+
diff --git a/devdocs/c/types%2Fptrdiff_t.html b/devdocs/c/types%2Fptrdiff_t.html new file mode 100644 index 00000000..a576a926 --- /dev/null +++ b/devdocs/c/types%2Fptrdiff_t.html @@ -0,0 +1,56 @@ +

ptrdiff_t

Defined in header <stddef.h> 
typedef /*implementation-defined*/ ptrdiff_t;
+

ptrdiff_t is the signed integer type of the result of subtracting two pointers.

+ + + + +

The bit width of ptrdiff_t is not less than 17.

+		 +(since C99)
(until C23) +

The bit width of ptrdiff_t is not less than 16.

+		 (since C23)

Notes

ptrdiff_t is used for pointer arithmetic and array indexing, if negative values are possible. Programs that use other types, such as int, may fail on, e.g. 64-bit systems when the index exceeds INT_MAX or if it relies on 32-bit modular arithmetic.

+

Only pointers to elements of the same array (including the pointer one past the end of the array) may be subtracted from each other.

+

If an array is so large (greater than PTRDIFF_MAX elements, but equal to or less than SIZE_MAX bytes), that the difference between two pointers may not be representable as ptrdiff_t, the result of subtracting two such pointers is undefined.

+

For char arrays shorter than PTRDIFF_MAX, ptrdiff_t acts as the signed counterpart of size_t: it can store the size of the array of any type and is, on most platforms, synonymous with intptr_t).

+

Example

#include <stddef.h>
+#include <stdint.h>
+#include <stdio.h>
+ 
+int main(void)
+{
+    const size_t N = 100;
+    int numbers[N];
+ 
+    printf("PTRDIFF_MAX = %ld\n", PTRDIFF_MAX);
+    int *p1 = &numbers[18], *p2 = &numbers[23];
+    ptrdiff_t diff = p2 - p1;
+    printf("p2-p1 = %td\n", diff);
+}

Possible output:

+
PTRDIFF_MAX = 9223372036854775807
+p2-p1 = 5

References

See also

+ + +
unsigned integer type returned by the sizeof operator
(typedef)
byte offset from the beginning of a struct type to specified member
(function macro)
C++ documentation for ptrdiff_t
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/types/ptrdiff_t +

+
diff --git a/devdocs/c/types%2Fsize_t.html b/devdocs/c/types%2Fsize_t.html new file mode 100644 index 00000000..de4fdb66 --- /dev/null +++ b/devdocs/c/types%2Fsize_t.html @@ -0,0 +1,49 @@ +

size_t

Defined in header <stddef.h>
Defined in header <stdio.h>
Defined in header <stdlib.h>
Defined in header <string.h>
Defined in header <time.h>
Defined in header <uchar.h> (since C11)
Defined in header <wchar.h> (since C95) 
typedef /*implementation-defined*/ size_t;
+

size_t is the unsigned integer type of the result of sizeof , _Alignof(since C11) and offsetof, depending on the data model.

+ + +

The bit width of size_t is not less than 16.

+		 (since C99)

Notes

size_t can store the maximum size of a theoretically possible object of any type (including array).

+

size_t is commonly used for array indexing and loop counting. Programs that use other types, such as unsigned int, for array indexing may fail on, e.g. 64-bit systems when the index exceeds UINT_MAX or if it relies on 32-bit modular arithmetic.

+

Example

#include <stdio.h>
+#include <stddef.h>
+#include <stdint.h>
+ 
+int main(void)
+{
+    const size_t N = 100;
+    int numbers[N];
+    for (size_t ndx = 0; ndx < N; ++ndx)
+        numbers[ndx] = ndx;
+    printf("SIZE_MAX = %zu\n", SIZE_MAX);
+    size_t size = sizeof numbers;
+    printf("size = %zu\n", size);
+}

Possible output:

+
SIZE_MAX = 18446744073709551615
+size = 400

References

See also

+ + +
signed integer type returned when subtracting two pointers
(typedef)
byte offset from the beginning of a struct type to specified member
(function macro)
C++ documentation for size_t
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/types/size_t +

+
diff --git a/devdocs/c/types.html b/devdocs/c/types.html new file mode 100644 index 00000000..7f02a985 --- /dev/null +++ b/devdocs/c/types.html @@ -0,0 +1,87 @@ +

Type support

See also type system overview and arithmetic types defined by the language.

+

Basic types

Additional basic types and convenience macros

+ + + + + + + + + + + + + + + + + + +
Defined in header <stddef.h>
unsigned integer type returned by the sizeof operator
(typedef)
signed integer type returned when subtracting two pointers
(typedef)
+
(C23)
 the type of the predefined null pointer constant nullptr
(typedef)
implementation-defined null pointer constant
(macro constant)
+
(C11)
 a type with alignment requirement as great as any other scalar type
(typedef)
byte offset from the beginning of a struct type to specified member
(function macro)
Defined in header <stdbool.h>
bool
+
(C99)(removed in C23)
 convenience macro, expands to _Bool
(keyword macro)
true
+
(C99)(removed in C23)
 expands to integer constant 1
(macro constant)
false
+
(C99)(removed in C23)
 expands to integer constant 0
(macro constant)
__bool_true_false_are_defined
+
(C99)(deprecated in C23)
 expands to integer constant 1
(macro constant)
Defined in header <stdalign.h>
alignas
+
(C11)(removed in C23)
 convenience macro, expands to keyword _Alignas
(keyword macro)
alignof
+
(C11)(removed in C23)
 convenience macro, expands to keyword _Alignof
(keyword macro)
__alignas_is_defined
+
(C11)(removed in C23)
 expands to integer constant 1
(macro constant)
__alignof_is_defined
+
(C11)(removed in C23)
 expands to integer constant 1
(macro constant)
Defined in header <stdnoreturn.h>
noreturn
+
(C11)(deprecated in C23)
 convenience macro, expands to _Noreturn
(keyword macro)

Fixed width integer types (since C99) +

Numeric limits +

Notes

+ + + +

The type of true and false is int rather than _Bool.

+

A program may undefine and perhaps then redefine the macros bool, true and false. However, such ability is a deprecated feature.

+		 +(since C99)
(until C23) +

The type of true and false is bool. It is unspecified whether any of bool, _Bool, true, or false is implemented as a predefined macro.

+

If bool, true, or false (but not _Bool) is defined as a predefined macro, a program may undefine and perhaps redefine it.

+		 (since C23)

Example

#include <stdio.h>
+#include <stdbool.h>
+#include <stdalign.h>
+ 
+int main(void)
+{
+    printf("%d %d %d\n", true && false, true || false, !false);
+    printf("%d %d\n", true ^ true, true + true);
+    printf("%zu\n", alignof(short));
+}

Possible output:

+
0 1 1
+0 2
+2

References

See also

+
C++ documentation for Type support library
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/types +

+
diff --git a/devdocs/c/variadic%2Fva_arg.html b/devdocs/c/variadic%2Fva_arg.html new file mode 100644 index 00000000..841667fa --- /dev/null +++ b/devdocs/c/variadic%2Fva_arg.html @@ -0,0 +1,54 @@ +

va_arg

Defined in header <stdarg.h> 
T va_arg( va_list ap, T );
+

The va_arg macro expands to an expression of type T that corresponds to the next parameter from the va_list ap.

+

Prior to calling va_arg, ap must be initialized by a call to either va_start or va_copy, with no intervening call to va_end. Each invocation of the va_arg macro modifies ap to point to the next variable argument.

+

If the type of the next argument in ap (after promotions) is not compatible with T, the behavior is undefined, unless:

+

If va_arg is called when there are no more arguments in ap, the behavior is undefined.

+

Parameters

+ + +
ap - an instance of the va_list type
T - the type of the next parameter in ap

Expanded value

the next variable parameter in ap

+

Example

#include <stdio.h>
+#include <stdarg.h>
+#include <math.h>
+ 
+double stddev(int count, ...) 
+{
+    double sum = 0;
+    double sum_sq = 0;
+    va_list args;
+    va_start(args, count);
+    for (int i = 0; i < count; ++i) {
+        double num = va_arg(args, double);
+        sum += num;
+        sum_sq += num*num;
+    }
+    va_end(args);
+    return sqrt(sum_sq/count - (sum/count)*(sum/count));
+}
+ 
+int main(void) 
+{
+    printf("%f\n", stddev(4, 25.0, 27.3, 26.9, 25.7));
+}

Output:

+
0.920258

References

See also

+ + + + +
+
(C99)
 makes a copy of the variadic function arguments
(function macro)
ends traversal of the variadic function arguments
(function macro)
holds the information needed by va_start, va_arg, va_end, and va_copy
(typedef)
enables access to variadic function arguments
(function macro)
C++ documentation for va_arg
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/variadic/va_arg +

+
diff --git a/devdocs/c/variadic%2Fva_copy.html b/devdocs/c/variadic%2Fva_copy.html new file mode 100644 index 00000000..fe57eb4c --- /dev/null +++ b/devdocs/c/variadic%2Fva_copy.html @@ -0,0 +1,56 @@ +

va_copy

Defined in header <stdarg.h> 
void va_copy( va_list dest, va_list src );
+		 (since C99)

The va_copy macro copies src to dest.

+

va_end should be called on dest before the function returns or any subsequent re-initialization of dest (via calls to va_start or va_copy).

+

Parameters

+ + +
dest - an instance of the va_list type to initialize
src - the source va_list that will be used to initialize dest

Expanded value

(none)

+

Example

#include <stdio.h>
+#include <stdarg.h>
+#include <math.h>
+ 
+double sample_stddev(int count, ...) 
+{
+    /* Compute the mean with args1. */
+    double sum = 0;
+    va_list args1;
+    va_start(args1, count);
+    va_list args2;
+    va_copy(args2, args1);   /* copy va_list object */
+    for (int i = 0; i < count; ++i) {
+        double num = va_arg(args1, double);
+        sum += num;
+    }
+    va_end(args1);
+    double mean = sum / count;
+ 
+    /* Compute standard deviation with args2 and mean. */
+    double sum_sq_diff = 0;
+    for (int i = 0; i < count; ++i) {
+        double num = va_arg(args2, double);
+        sum_sq_diff += (num-mean) * (num-mean);
+    }
+    va_end(args2);
+    return sqrt(sum_sq_diff / count);
+}
+ 
+int main(void) 
+{
+    printf("%f\n", sample_stddev(4, 25.0, 27.3, 26.9, 25.7));
+}

Possible output:

+
0.920258

References

See also

+ + + + +
accesses the next variadic function argument
(function macro)
ends traversal of the variadic function arguments
(function macro)
holds the information needed by va_start, va_arg, va_end, and va_copy
(typedef)
enables access to variadic function arguments
(function macro)
C++ documentation for va_copy
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/variadic/va_copy +

+
diff --git a/devdocs/c/variadic%2Fva_end.html b/devdocs/c/variadic%2Fva_end.html new file mode 100644 index 00000000..d6c1cddf --- /dev/null +++ b/devdocs/c/variadic%2Fva_end.html @@ -0,0 +1,25 @@ +

va_end

Defined in header <stdarg.h> 
void va_end( va_list ap );
+

The va_end macro performs cleanup for an ap object initialized by a call to va_start or va_copy. va_end may modify ap so that it is no longer usable.

+

If there is no corresponding call to va_start or va_copy, or if va_end is not called before a function that calls va_start or va_copy returns, the behavior is undefined.

+

Parameters

+ +
ap - an instance of the va_list type to clean up

Expanded value

(none)

+

References

See also

+ + + + +
accesses the next variadic function argument
(function macro)
+
(C99)
 makes a copy of the variadic function arguments
(function macro)
holds the information needed by va_start, va_arg, va_end, and va_copy
(typedef)
enables access to variadic function arguments
(function macro)
C++ documentation for va_end
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/variadic/va_end +

+
diff --git a/devdocs/c/variadic%2Fva_list.html b/devdocs/c/variadic%2Fva_list.html new file mode 100644 index 00000000..507162c4 --- /dev/null +++ b/devdocs/c/variadic%2Fva_list.html @@ -0,0 +1,23 @@ +

va_list

Defined in header <stdarg.h> 
/* unspecified */ va_list;
+

va_list is a complete object type suitable for holding the information needed by the macros va_start, va_copy, va_arg, and va_end.

+

If a va_list instance is created, passed to another function, and used via va_arg in that function, then any subsequent use in the calling function should be preceded by a call to va_end.

+

It is legal to pass a pointer to a va_list object to another function and then use that object after the function returns.

+

References

See also

+ + + + +
accesses the next variadic function argument
(function macro)
+
(C99)
 makes a copy of the variadic function arguments
(function macro)
ends traversal of the variadic function arguments
(function macro)
enables access to variadic function arguments
(function macro)
C++ documentation for va_list
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/variadic/va_list +

+
diff --git a/devdocs/c/variadic%2Fva_start.html b/devdocs/c/variadic%2Fva_start.html new file mode 100644 index 00000000..8dd8a365 --- /dev/null +++ b/devdocs/c/variadic%2Fva_start.html @@ -0,0 +1,77 @@ +

va_start

Defined in header <stdarg.h> 
void va_start( va_list ap, parmN );
 (until C23) 
void va_start( va_list ap, ... );
+		 (since C23)

The va_start macro enables access to the variable arguments following the named argument parmN(until C23).

+

va_start shall be invoked with an instance to a valid va_list object ap before any calls to va_arg.

+ + + + +

If parmN is declared with register storage class specifier, with an array type, with a function type, or with a type not compatible with the type that results from default argument promotions, the behavior is undefined.

+		 (until C23)

Only the first argument passed to va_start is evaluated. Any additional arguments are neither expanded nor used in any way.

+		 (since C23)

Parameters

+ + +
ap - an instance of the va_list type
parmN - the named parameter preceding the first variable parameter

Expanded value

(none)

+

Example

#include <stdio.h>
+#include <stdarg.h>
+ 
+int add_nums_C99(int count, ...)
+{
+    int result = 0;
+    va_list args;
+    va_start(args, count); // count can be omitted since C23
+ 
+    for (int i = 0; i < count; ++i) {
+        result += va_arg(args, int);
+    }
+ 
+    va_end(args);
+    return result;
+}
+ 
+#if __STDC_VERSION__ > 201710L
+// Same as above, valid since C23
+int add_nums_C23(...)
+{
+    int result = 0;
+    va_list args;
+    va_start(args);
+ 
+    int count = va_arg(args, int);
+    for (int i = 0; i < count; ++i) {
+        result += va_arg(args, int);
+    }
+ 
+    va_end(args);
+    return result;
+}
+#endif
+ 
+int main(void)
+{
+    printf("%d\n", add_nums_C99(4, 25, 25, 50, 50));
+#if __STDC_VERSION__ > 201710L
+    printf("%d\n", add_nums_C23(4, 25, 25, 50, 50));
+#endif
+}

Possible output:

+
150
+150

References

See also

+ + + + +
accesses the next variadic function argument
(function macro)
+
(C99)
 makes a copy of the variadic function arguments
(function macro)
ends traversal of the variadic function arguments
(function macro)
holds the information needed by va_start, va_arg, va_end, and va_copy
(typedef)
C++ documentation for va_start
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/variadic/va_start +

+
diff --git a/devdocs/c/variadic.html b/devdocs/c/variadic.html new file mode 100644 index 00000000..a824c453 --- /dev/null +++ b/devdocs/c/variadic.html @@ -0,0 +1,62 @@ +

Variadic functions

Variadic functions are functions (e.g. printf) which take a variable number of arguments.

+

The declaration of a variadic function uses an ellipsis as the last parameter, e.g. int printf(const char* format, ...);. See variadic arguments for additional detail on the syntax and automatic argument conversions.

+

Accessing the variadic arguments from the function body uses the following library facilities:

+ + + + + + + + +
Macros
Defined in header <stdarg.h>
enables access to variadic function arguments
(function macro)
accesses the next variadic function argument
(function macro)
+
(C99)
 makes a copy of the variadic function arguments
(function macro)
ends traversal of the variadic function arguments
(function macro)
Type
holds the information needed by va_start, va_arg, va_end, and va_copy
(typedef)

Example

+

Print values of different types.

+
#include <stdio.h>
+#include <stdarg.h>
+ 
+void simple_printf(const char* fmt, ...)
+{
+    va_list args;
+    va_start(args, fmt);
+ 
+    while (*fmt != '\0') {
+        if (*fmt == 'd') {
+            int i = va_arg(args, int);
+            printf("%d\n", i);
+        } else if (*fmt == 'c') {
+            // A 'char' variable will be promoted to 'int'
+            // A character literal in C is already 'int' by itself
+            int c = va_arg(args, int);
+            printf("%c\n", c);
+        } else if (*fmt == 'f') {
+            double d = va_arg(args, double);
+            printf("%f\n", d);
+        }
+        ++fmt;
+    }
+ 
+    va_end(args);
+}
+ 
+int main(void)
+{
+    simple_printf("dcff", 3, 'a', 1.999, 42.5); 
+}

Output:

+
3
+a
+1.999000
+42.50000

References

See also

+
C++ documentation for Variadic functions
+

+ © cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
+ https://en.cppreference.com/w/c/variadic +

+
-- cgit v1.2.3