Initial import from FreeBSD RELENG_4:
[dragonfly.git] / secure / lib / libcrypto / man / X509_NAME_get_index_by_NID.3
CommitLineData
984263bc
MD
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"
144X509_NAME_get_index_by_NID, X509_NAME_get_index_by_OBJ, X509_NAME_get_entry,
145X509_NAME_entry_count, X509_NAME_get_text_by_NID, X509_NAME_get_text_by_OBJ \-
146X509_NAME lookup and enumeration functions
147.SH "SYNOPSIS"
148.IX Header "SYNOPSIS"
149int X509_NAME_get_index_by_NID(X509_NAME *name,int nid,int lastpos);
150int X509_NAME_get_index_by_OBJ(X509_NAME *name,ASN1_OBJECT *obj, int lastpos);
151.PP
152int X509_NAME_entry_count(X509_NAME *name);
153X509_NAME_ENTRY *X509_NAME_get_entry(X509_NAME *name, int loc);
154.PP
155int X509_NAME_get_text_by_NID(X509_NAME *name, int nid, char *buf,int len);
156int 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"
159These 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
162and issuer names.
163.PP
164\&\fIX509_NAME_get_index_by_NID()\fR and \fIX509_NAME_get_index_by_OBJ()\fR retrieve
165the next index matching \fBnid\fR or \fBobj\fR after \fBlastpos\fR. \fBlastpos\fR
166should 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
171corresponding to index \fBloc\fR. Acceptable values for \fBloc\fR run from
1720 to (X509_NAME_entry_count(name) \- 1). The value returned is an
173internal pointer which must not be freed.
174.PP
175\&\fIX509_NAME_get_text_by_NID()\fR, \fIX509_NAME_get_text_by_OBJ()\fR retrieve
176the \*(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
178will be written and the text written to \fBbuf\fR will be null
179terminated. The length of the output string written is returned
180excluding the terminating null. If \fBbuf\fR is <\s-1NULL\s0> then the amount
181of 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
185legacy functions which have various limitations which make them
186of minimal use in practice. They can only find the first matching
187entry and will copy the contents of the field verbatim: this can
188be highly confusing if the target is a muticharacter string type
189like a BMPString or a UTF8String.
190.PP
191For 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
194various \fBX509_NAME_ENTRY\fR utility functions on the result.
195.SH "EXAMPLES"
196.IX Header "EXAMPLES"
197Process 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
210Process 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
230return 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
235requested entry or \fB\s-1NULL\s0\fR if the index is invalid.
236.SH "SEE ALSO"
237.IX Header "SEE ALSO"
238ERR_get_error(3), d2i_X509_NAME(3)
239.SH "HISTORY"
240.IX Header "HISTORY"
241\&\s-1TBA\s0