secure/lib/libcrypto/man/X509_NAME_get_index_by_NID.3

   1 .\" Automatically generated by Pod::Man version 1.15
   2 .\" Wed Feb 19 16:43:00 2003
   3 .\"
   4 .\" Standard preamble:
   5 .\" ======================================================================
   6 .de Sh \" Subsection heading
   7 .br
   8 .if t .Sp
   9 .ne 5
  10 .PP
  11 \fB\\$1\fR
  12 .PP
  13 ..
  14 .de Sp \" Vertical space (when we can't use .PP)
  15 .if t .sp .5v
  16 .if n .sp
  17 ..
  18 .de Ip \" List item
  19 .br
  20 .ie \\n(.$>=3 .ne \\$3
  21 .el .ne 3
  22 .IP "\\$1" \\$2
  23 ..
  24 .de Vb \" Begin verbatim text
  25 .ft CW
  26 .nf
  27 .ne \\$1
  28 ..
  29 .de Ve \" End verbatim text
  30 .ft R
  31
  32 .fi
  33 ..
  34 .\" Set up some character translations and predefined strings.  \*(-- will
  35 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  36 .\" double quote, and \*(R" will give a right double quote.  | will give a
  37 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used
  38 .\" to do unbreakable dashes and therefore won't be available.  \*(C` and
  39 .\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
  40 .tr \(*W-|\(bv\*(Tr
  41 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  42 .ie n \{\
  43 .    ds -- \(*W-
  44 .    ds PI pi
  45 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  46 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  47 .    ds L" ""
  48 .    ds R" ""
  49 .    ds C` ""
  50 .    ds C' ""
  51 'br\}
  52 .el\{\
  53 .    ds -- \|\(em\|
  54 .    ds PI \(*p
  55 .    ds L" ``
  56 .    ds R" ''
  57 'br\}
  58 .\"
  59 .\" If the F register is turned on, we'll generate index entries on stderr
  60 .\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
  61 .\" index entries marked with X<> in POD.  Of course, you'll have to process
  62 .\" the output yourself in some meaningful fashion.
  63 .if \nF \{\
  64 .    de IX
  65 .    tm Index:\\$1\t\\n%\t"\\$2"
  66 ..
  67 .    nr % 0
  68 .    rr F
  69 .\}
  70 .\"
  71 .\" For nroff, turn off justification.  Always turn off hyphenation; it
  72 .\" makes way too many mistakes in technical documents.
  73 .hy 0
  74 .if n .na
  75 .\"
  76 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  77 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  78 .bd B 3
  79 .    \" fudge factors for nroff and troff
  80 .if n \{\
  81 .    ds #H 0
  82 .    ds #V .8m
  83 .    ds #F .3m
  84 .    ds #[ \f1
  85 .    ds #] \fP
  86 .\}
  87 .if t \{\
  88 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  89 .    ds #V .6m
  90 .    ds #F 0
  91 .    ds #[ \&
  92 .    ds #] \&
  93 .\}
  94 .    \" simple accents for nroff and troff
  95 .if n \{\
  96 .    ds ' \&
  97 .    ds ` \&
  98 .    ds ^ \&
  99 .    ds , \&
 100 .    ds ~ ~
 101 .    ds /
 102 .\}
 103 .if t \{\
 104 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 105 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 106 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 107 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 108 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 109 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 110 .\}
 111 .    \" troff and (daisy-wheel) nroff accents
 112 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 113 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 114 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 115 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 116 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 117 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 118 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 119 .ds ae a\h'-(\w'a'u*4/10)'e
 120 .ds Ae A\h'-(\w'A'u*4/10)'E
 121 .    \" corrections for vroff
 122 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 123 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 124 .    \" for low resolution devices (crt and lpr)
 125 .if \n(.H>23 .if \n(.V>19 \
 126 \{\
 127 .    ds : e
 128 .    ds 8 ss
 129 .    ds o a
 130 .    ds d- d\h'-1'\(ga
 131 .    ds D- D\h'-1'\(hy
 132 .    ds th \o'bp'
 133 .    ds Th \o'LP'
 134 .    ds ae ae
 135 .    ds Ae AE
 136 .\}
 137 .rm #[ #] #H #V #F C
 138 .\" ======================================================================
 139 .\"
 140 .IX Title "X509_NAME_get_index_by_NID 3"
 141 .TH X509_NAME_get_index_by_NID 3 "0.9.7a" "2003-02-19" "OpenSSL"
 142 .UC
 143 .SH "NAME"
 144 X509_NAME_get_index_by_NID, X509_NAME_get_index_by_OBJ, X509_NAME_get_entry,
 145 X509_NAME_entry_count, X509_NAME_get_text_by_NID, X509_NAME_get_text_by_OBJ \-
 146 X509_NAME lookup and enumeration functions
 147 .SH "SYNOPSIS"
 148 .IX Header "SYNOPSIS"
 149 int X509_NAME_get_index_by_NID(X509_NAME *name,int nid,int lastpos);
 150 int X509_NAME_get_index_by_OBJ(X509_NAME *name,ASN1_OBJECT *obj, int lastpos);
 151 .PP
 152 int X509_NAME_entry_count(X509_NAME *name);
 153 X509_NAME_ENTRY *X509_NAME_get_entry(X509_NAME *name, int loc);
 154 .PP
 155 int X509_NAME_get_text_by_NID(X509_NAME *name, int nid, char *buf,int len);
 156 int X509_NAME_get_text_by_OBJ(X509_NAME *name, \s-1ASN1_OBJECT\s0 *obj, char *buf,int len);
 157 .SH "DESCRIPTION"
 158 .IX Header "DESCRIPTION"
 159 These functions allow an \fBX509_NAME\fR structure to be examined. The
 160 \&\fBX509_NAME\fR structure is the same as the \fBName\fR type defined in
 161 \&\s-1RFC2459\s0 (and elsewhere) and used for example in certificate subject
 162 and issuer names.
 163 .PP
 164 \&\fIX509_NAME_get_index_by_NID()\fR and \fIX509_NAME_get_index_by_OBJ()\fR retrieve
 165 the next index matching \fBnid\fR or \fBobj\fR after \fBlastpos\fR. \fBlastpos\fR
 166 should initially be set to \-1. If there are no more entries \-1 is returned.
 167 .PP
 168 \&\fIX509_NAME_entry_count()\fR returns the total number of entries in \fBname\fR.
 169 .PP
 170 \&\fIX509_NAME_get_entry()\fR retrieves the \fBX509_NAME_ENTRY\fR from \fBname\fR
 171 corresponding to index \fBloc\fR. Acceptable values for \fBloc\fR run from
 172 0 to (X509_NAME_entry_count(name) \- 1). The value returned is an
 173 internal pointer which must not be freed.
 174 .PP
 175 \&\fIX509_NAME_get_text_by_NID()\fR, \fIX509_NAME_get_text_by_OBJ()\fR retrieve
 176 the \*(L"text\*(R" from the first entry in \fBname\fR which matches \fBnid\fR or
 177 \&\fBobj\fR, if no such entry exists \-1 is returned. At most \fBlen\fR bytes
 178 will be written and the text written to \fBbuf\fR will be null
 179 terminated. The length of the output string written is returned
 180 excluding the terminating null. If \fBbuf\fR is <\s-1NULL\s0> then the amount
 181 of space needed in \fBbuf\fR (excluding the final null) is returned.
 182 .SH "NOTES"
 183 .IX Header "NOTES"
 184 \&\fIX509_NAME_get_text_by_NID()\fR and \fIX509_NAME_get_text_by_OBJ()\fR are
 185 legacy functions which have various limitations which make them
 186 of minimal use in practice. They can only find the first matching
 187 entry and will copy the contents of the field verbatim: this can
 188 be highly confusing if the target is a muticharacter string type
 189 like a BMPString or a UTF8String.
 190 .PP
 191 For a more general solution \fIX509_NAME_get_index_by_NID()\fR or
 192 \&\fIX509_NAME_get_index_by_OBJ()\fR should be used followed by
 193 \&\fIX509_NAME_get_entry()\fR on any matching indices and then the
 194 various \fBX509_NAME_ENTRY\fR utility functions on the result.
 195 .SH "EXAMPLES"
 196 .IX Header "EXAMPLES"
 197 Process all entries:
 198 .PP
 199 .Vb 2
 200 \& int i;
 201 \& X509_NAME_ENTRY *e;
 202 .Ve
 203 .Vb 5
 204 \& for (i = 0; i < X509_NAME_entry_count(nm); i++)
 205 \&        {
 206 \&        e = X509_NAME_get_entry(nm, i);
 207 \&        /* Do something with e */
 208 \&        }
 209 .Ve
 210 Process all commonName entries:
 211 .PP
 212 .Vb 2
 213 \& int loc;
 214 \& X509_NAME_ENTRY *e;
 215 .Ve
 216 .Vb 9
 217 \& loc = -1;
 218 \& for (;;)
 219 \&        {
 220 \&        lastpos = X509_NAME_get_index_by_NID(nm, NID_commonName, lastpos);
 221 \&        if (lastpos == -1)
 222 \&                break;
 223 \&        e = X509_NAME_get_entry(nm, lastpos);
 224 \&        /* Do something with e */
 225 \&        }
 226 .Ve
 227 .SH "RETURN VALUES"
 228 .IX Header "RETURN VALUES"
 229 \&\fIX509_NAME_get_index_by_NID()\fR and \fIX509_NAME_get_index_by_OBJ()\fR
 230 return the index of the next matching entry or \-1 if not found.
 231 .PP
 232 \&\fIX509_NAME_entry_count()\fR returns the total number of entries.
 233 .PP
 234 \&\fIX509_NAME_get_entry()\fR returns an \fBX509_NAME\fR pointer to the
 235 requested entry or \fB\s-1NULL\s0\fR if the index is invalid.
 236 .SH "SEE ALSO"
 237 .IX Header "SEE ALSO"
 238 ERR_get_error(3), d2i_X509_NAME(3)
 239 .SH "HISTORY"
 240 .IX Header "HISTORY"
 241 \&\s-1TBA\s0