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