secure/lib/libcrypto/man/X509_NAME_get_index_by_NID.3

   1 .rn '' }`
   2 ''' $RCSfile$$Revision$$Date$
   3 '''
   4 ''' $Log$
   5 '''
   6 .de Sh
   7 .br
   8 .if t .Sp
   9 .ne 5
  10 .PP
  11 \fB\\$1\fR
  12 .PP
  13 ..
  14 .de Sp
  15 .if t .sp .5v
  16 .if n .sp
  17 ..
  18 .de Ip
  19 .br
  20 .ie \\n(.$>=3 .ne \\$3
  21 .el .ne 3
  22 .IP "\\$1" \\$2
  23 ..
  24 .de Vb
  25 .ft CW
  26 .nf
  27 .ne \\$1
  28 ..
  29 .de Ve
  30 .ft R
  31
  32 .fi
  33 ..
  34 '''
  35 '''
  36 '''     Set up \*(-- to give an unbreakable dash;
  37 '''     string Tr holds user defined translation string.
  38 '''     Bell System Logo is used as a dummy character.
  39 '''
  40 .tr \(*W-|\(bv\*(Tr
  41 .ie n \{\
  42 .ds -- \(*W-
  43 .ds PI pi
  44 .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  45 .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
  46 .ds L" ""
  47 .ds R" ""
  48 '''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
  49 '''   \*(L" and \*(R", except that they are used on ".xx" lines,
  50 '''   such as .IP and .SH, which do another additional levels of
  51 '''   double-quote interpretation
  52 .ds M" """
  53 .ds S" """
  54 .ds N" """""
  55 .ds T" """""
  56 .ds L' '
  57 .ds R' '
  58 .ds M' '
  59 .ds S' '
  60 .ds N' '
  61 .ds T' '
  62 'br\}
  63 .el\{\
  64 .ds -- \(em\|
  65 .tr \*(Tr
  66 .ds L" ``
  67 .ds R" ''
  68 .ds M" ``
  69 .ds S" ''
  70 .ds N" ``
  71 .ds T" ''
  72 .ds L' `
  73 .ds R' '
  74 .ds M' `
  75 .ds S' '
  76 .ds N' `
  77 .ds T' '
  78 .ds PI \(*p
  79 'br\}
  80 .\"     If the F register is turned on, we'll generate
  81 .\"     index entries out stderr for the following things:
  82 .\"             TH      Title
  83 .\"             SH      Header
  84 .\"             Sh      Subsection
  85 .\"             Ip      Item
  86 .\"             X<>     Xref  (embedded
  87 .\"     Of course, you have to process the output yourself
  88 .\"     in some meaninful fashion.
  89 .if \nF \{
  90 .de IX
  91 .tm Index:\\$1\t\\n%\t"\\$2"
  92 ..
  93 .nr % 0
  94 .rr F
  95 .\}
  96 .TH X509_NAME_get_index_by_NID 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
  97 .UC
  98 .if n .hy 0
  99 .if n .na
 100 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
 101 .de CQ          \" put $1 in typewriter font
 102 .ft CW
 103 'if n "\c
 104 'if t \\&\\$1\c
 105 'if n \\&\\$1\c
 106 'if n \&"
 107 \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
 108 '.ft R
 109 ..
 110 .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
 111 .       \" AM - accent mark definitions
 112 .bd B 3
 113 .       \" fudge factors for nroff and troff
 114 .if n \{\
 115 .       ds #H 0
 116 .       ds #V .8m
 117 .       ds #F .3m
 118 .       ds #[ \f1
 119 .       ds #] \fP
 120 .\}
 121 .if t \{\
 122 .       ds #H ((1u-(\\\\n(.fu%2u))*.13m)
 123 .       ds #V .6m
 124 .       ds #F 0
 125 .       ds #[ \&
 126 .       ds #] \&
 127 .\}
 128 .       \" simple accents for nroff and troff
 129 .if n \{\
 130 .       ds ' \&
 131 .       ds ` \&
 132 .       ds ^ \&
 133 .       ds , \&
 134 .       ds ~ ~
 135 .       ds ? ?
 136 .       ds ! !
 137 .       ds /
 138 .       ds q
 139 .\}
 140 .if t \{\
 141 .       ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 142 .       ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 143 .       ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 144 .       ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 145 .       ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 146 .       ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
 147 .       ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
 148 .       ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 149 .       ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
 150 .\}
 151 .       \" troff and (daisy-wheel) nroff accents
 152 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 153 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 154 .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
 155 .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
 156 .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
 157 .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
 158 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 159 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 160 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 161 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 162 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 163 .ds ae a\h'-(\w'a'u*4/10)'e
 164 .ds Ae A\h'-(\w'A'u*4/10)'E
 165 .ds oe o\h'-(\w'o'u*4/10)'e
 166 .ds Oe O\h'-(\w'O'u*4/10)'E
 167 .       \" corrections for vroff
 168 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 169 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 170 .       \" for low resolution devices (crt and lpr)
 171 .if \n(.H>23 .if \n(.V>19 \
 172 \{\
 173 .       ds : e
 174 .       ds 8 ss
 175 .       ds v \h'-1'\o'\(aa\(ga'
 176 .       ds _ \h'-1'^
 177 .       ds . \h'-1'.
 178 .       ds 3 3
 179 .       ds o a
 180 .       ds d- d\h'-1'\(ga
 181 .       ds D- D\h'-1'\(hy
 182 .       ds th \o'bp'
 183 .       ds Th \o'LP'
 184 .       ds ae ae
 185 .       ds Ae AE
 186 .       ds oe oe
 187 .       ds Oe OE
 188 .\}
 189 .rm #[ #] #H #V #F C
 190 .SH "NAME"
 191 X509_NAME_get_index_by_NID, X509_NAME_get_index_by_OBJ, X509_NAME_get_entry,
 192 X509_NAME_entry_count, X509_NAME_get_text_by_NID, X509_NAME_get_text_by_OBJ \-
 193 X509_NAME lookup and enumeration functions
 194 .SH "SYNOPSIS"
 195 int \fIX509_NAME_get_index_by_NID\fR\|(X509_NAME *name,int nid,int lastpos);
 196 int \fIX509_NAME_get_index_by_OBJ\fR\|(X509_NAME *name,ASN1_OBJECT *obj, int lastpos);
 197 .PP
 198 int \fIX509_NAME_entry_count\fR\|(X509_NAME *name);
 199 X509_NAME_ENTRY *\fIX509_NAME_get_entry\fR\|(X509_NAME *name, int loc);
 200 .PP
 201 int \fIX509_NAME_get_text_by_NID\fR\|(X509_NAME *name, int nid, char *buf,int len);
 202 int \fIX509_NAME_get_text_by_OBJ\fR\|(X509_NAME *name, ASN1_OBJECT *obj, char *buf,int len);
 203 .SH "DESCRIPTION"
 204 These functions allow an \fBX509_NAME\fR structure to be examined. The
 205 \fBX509_NAME\fR structure is the same as the \fBName\fR type defined in
 206 RFC2459 (and elsewhere) and used for example in certificate subject
 207 and issuer names.
 208 .PP
 209 \fIX509_NAME_get_index_by_NID()\fR and \fIX509_NAME_get_index_by_OBJ()\fR retrieve
 210 the next index matching \fBnid\fR or \fBobj\fR after \fBlastpos\fR. \fBlastpos\fR
 211 should initially be set to \-1. If there are no more entries \-1 is returned.
 212 .PP
 213 \fIX509_NAME_entry_count()\fR returns the total number of entries in \fBname\fR.
 214 .PP
 215 \fIX509_NAME_get_entry()\fR retrieves the \fBX509_NAME_ENTRY\fR from \fBname\fR
 216 corresponding to index \fBloc\fR. Acceptable values for \fBloc\fR run from
 217 0 to (\fIX509_NAME_entry_count\fR\|(name) \- 1). The value returned is an
 218 internal pointer which must not be freed.
 219 .PP
 220 \fIX509_NAME_get_text_by_NID()\fR, \fIX509_NAME_get_text_by_OBJ()\fR retrieve
 221 the \*(L"text\*(R" from the first entry in \fBname\fR which matches \fBnid\fR or
 222 \fBobj\fR, if no such entry exists \-1 is returned. At most \fBlen\fR bytes
 223 will be written and the text written to \fBbuf\fR will be null
 224 terminated. The length of the output string written is returned
 225 excluding the terminating null. If \fBbuf\fR is <NULL> then the amount
 226 of space needed in \fBbuf\fR (excluding the final null) is returned.
 227 .SH "NOTES"
 228 \fIX509_NAME_get_text_by_NID()\fR and \fIX509_NAME_get_text_by_OBJ()\fR are
 229 legacy functions which have various limitations which make them
 230 of minimal use in practice. They can only find the first matching
 231 entry and will copy the contents of the field verbatim: this can
 232 be highly confusing if the target is a muticharacter string type
 233 like a BMPString or a UTF8String.
 234 .PP
 235 For a more general solution \fIX509_NAME_get_index_by_NID()\fR or
 236 \fIX509_NAME_get_index_by_OBJ()\fR should be used followed by
 237 \fIX509_NAME_get_entry()\fR on any matching indices and then the
 238 various \fBX509_NAME_ENTRY\fR utility functions on the result.
 239 .SH "EXAMPLES"
 240 Process all entries:
 241 .PP
 242 .Vb 2
 243 \& int i;
 244 \& X509_NAME_ENTRY *e;
 245 .Ve
 246 .Vb 5
 247 \& for (i = 0; i < X509_NAME_entry_count(nm); i++)
 248 \&        {
 249 \&        e = X509_NAME_get_entry(nm, i);
 250 \&        /* Do something with e */
 251 \&        }
 252 .Ve
 253 Process all commonName entries:
 254 .PP
 255 .Vb 2
 256 \& int loc;
 257 \& X509_NAME_ENTRY *e;
 258 .Ve
 259 .Vb 9
 260 \& loc = -1;
 261 \& for (;;)
 262 \&        {
 263 \&        lastpos = X509_NAME_get_index_by_NID(nm, NID_commonName, lastpos);
 264 \&        if (lastpos == -1)
 265 \&                break;
 266 \&        e = X509_NAME_get_entry(nm, lastpos);
 267 \&        /* Do something with e */
 268 \&        }
 269 .Ve
 270 .SH "RETURN VALUES"
 271 \fIX509_NAME_get_index_by_NID()\fR and \fIX509_NAME_get_index_by_OBJ()\fR
 272 return the index of the next matching entry or \-1 if not found.
 273 .PP
 274 \fIX509_NAME_entry_count()\fR returns the total number of entries.
 275 .PP
 276 \fIX509_NAME_get_entry()\fR returns an \fBX509_NAME\fR pointer to the
 277 requested entry or \fBNULL\fR if the index is invalid.
 278 .SH "SEE ALSO"
 279 ERR_get_error(3), d2i_X509_NAME(3)
 280 .SH "HISTORY"
 281 TBA
 282
 283 .rn }` ''
 284 .IX Title "X509_NAME_get_index_by_NID 3"
 285 .IX Name "X509_NAME_get_index_by_NID, X509_NAME_get_index_by_OBJ, X509_NAME_get_entry,
 286 X509_NAME_entry_count, X509_NAME_get_text_by_NID, X509_NAME_get_text_by_OBJ - X509_NAME lookup and enumeration functions"
 287
 288 .IX Header "NAME"
 289
 290 .IX Header "SYNOPSIS"
 291
 292 .IX Header "DESCRIPTION"
 293
 294 .IX Header "NOTES"
 295
 296 .IX Header "EXAMPLES"
 297
 298 .IX Header "RETURN VALUES"
 299
 300 .IX Header "SEE ALSO"
 301
 302 .IX Header "HISTORY"
 303