Commit manual pages after running 'man-update' and add new manual pages.
[dragonfly.git] / secure / lib / libcrypto / man / X509_NAME_get_index_by_NID.3
CommitLineData
74dab6c2
JR
1.rn '' }`
2''' $RCSfile$$Revision$$Date$
3'''
4''' $Log$
5'''
6.de Sh
984263bc
MD
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
74dab6c2 14.de Sp
984263bc
MD
15.if t .sp .5v
16.if n .sp
17..
74dab6c2 18.de Ip
984263bc
MD
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
74dab6c2 24.de Vb
984263bc
MD
25.ft CW
26.nf
27.ne \\$1
28..
74dab6c2 29.de Ve
984263bc
MD
30.ft R
31
32.fi
33..
74dab6c2
JR
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'''
984263bc 40.tr \(*W-|\(bv\*(Tr
984263bc 41.ie n \{\
74dab6c2
JR
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' '
984263bc
MD
62'br\}
63.el\{\
74dab6c2
JR
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
984263bc 79'br\}
74dab6c2
JR
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"
984263bc 92..
74dab6c2
JR
93.nr % 0
94.rr F
984263bc 95.\}
74dab6c2
JR
96.TH X509_NAME_get_index_by_NID 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97.UC
98.if n .hy 0
984263bc 99.if n .na
74dab6c2
JR
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
984263bc 112.bd B 3
74dab6c2 113. \" fudge factors for nroff and troff
984263bc 114.if n \{\
74dab6c2
JR
115. ds #H 0
116. ds #V .8m
117. ds #F .3m
118. ds #[ \f1
119. ds #] \fP
984263bc
MD
120.\}
121.if t \{\
74dab6c2
JR
122. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123. ds #V .6m
124. ds #F 0
125. ds #[ \&
126. ds #] \&
984263bc 127.\}
74dab6c2 128. \" simple accents for nroff and troff
984263bc 129.if n \{\
74dab6c2
JR
130. ds ' \&
131. ds ` \&
132. ds ^ \&
133. ds , \&
134. ds ~ ~
135. ds ? ?
136. ds ! !
137. ds /
138. ds q
984263bc
MD
139.\}
140.if t \{\
74dab6c2
JR
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'
984263bc 150.\}
74dab6c2 151. \" troff and (daisy-wheel) nroff accents
984263bc
MD
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'
74dab6c2
JR
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'\*(#]
984263bc
MD
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
74dab6c2
JR
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
984263bc
MD
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'
74dab6c2 170. \" for low resolution devices (crt and lpr)
984263bc
MD
171.if \n(.H>23 .if \n(.V>19 \
172\{\
74dab6c2
JR
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
984263bc
MD
188.\}
189.rm #[ #] #H #V #F C
984263bc
MD
190.SH "NAME"
191X509_NAME_get_index_by_NID, X509_NAME_get_index_by_OBJ, X509_NAME_get_entry,
192X509_NAME_entry_count, X509_NAME_get_text_by_NID, X509_NAME_get_text_by_OBJ \-
193X509_NAME lookup and enumeration functions
194.SH "SYNOPSIS"
74dab6c2
JR
195int \fIX509_NAME_get_index_by_NID\fR\|(X509_NAME *name,int nid,int lastpos);
196int \fIX509_NAME_get_index_by_OBJ\fR\|(X509_NAME *name,ASN1_OBJECT *obj, int lastpos);
984263bc 197.PP
74dab6c2
JR
198int \fIX509_NAME_entry_count\fR\|(X509_NAME *name);
199X509_NAME_ENTRY *\fIX509_NAME_get_entry\fR\|(X509_NAME *name, int loc);
984263bc 200.PP
74dab6c2
JR
201int \fIX509_NAME_get_text_by_NID\fR\|(X509_NAME *name, int nid, char *buf,int len);
202int \fIX509_NAME_get_text_by_OBJ\fR\|(X509_NAME *name, ASN1_OBJECT *obj, char *buf,int len);
984263bc 203.SH "DESCRIPTION"
984263bc 204These functions allow an \fBX509_NAME\fR structure to be examined. The
74dab6c2
JR
205\fBX509_NAME\fR structure is the same as the \fBName\fR type defined in
206RFC2459 (and elsewhere) and used for example in certificate subject
984263bc
MD
207and issuer names.
208.PP
74dab6c2 209\fIX509_NAME_get_index_by_NID()\fR and \fIX509_NAME_get_index_by_OBJ()\fR retrieve
984263bc
MD
210the next index matching \fBnid\fR or \fBobj\fR after \fBlastpos\fR. \fBlastpos\fR
211should initially be set to \-1. If there are no more entries \-1 is returned.
212.PP
74dab6c2 213\fIX509_NAME_entry_count()\fR returns the total number of entries in \fBname\fR.
984263bc 214.PP
74dab6c2 215\fIX509_NAME_get_entry()\fR retrieves the \fBX509_NAME_ENTRY\fR from \fBname\fR
984263bc 216corresponding to index \fBloc\fR. Acceptable values for \fBloc\fR run from
74dab6c2 2170 to (\fIX509_NAME_entry_count\fR\|(name) \- 1). The value returned is an
984263bc
MD
218internal pointer which must not be freed.
219.PP
74dab6c2 220\fIX509_NAME_get_text_by_NID()\fR, \fIX509_NAME_get_text_by_OBJ()\fR retrieve
984263bc 221the \*(L"text\*(R" from the first entry in \fBname\fR which matches \fBnid\fR or
74dab6c2 222\fBobj\fR, if no such entry exists \-1 is returned. At most \fBlen\fR bytes
984263bc
MD
223will be written and the text written to \fBbuf\fR will be null
224terminated. The length of the output string written is returned
74dab6c2 225excluding the terminating null. If \fBbuf\fR is <NULL> then the amount
984263bc
MD
226of space needed in \fBbuf\fR (excluding the final null) is returned.
227.SH "NOTES"
74dab6c2 228\fIX509_NAME_get_text_by_NID()\fR and \fIX509_NAME_get_text_by_OBJ()\fR are
984263bc
MD
229legacy functions which have various limitations which make them
230of minimal use in practice. They can only find the first matching
231entry and will copy the contents of the field verbatim: this can
232be highly confusing if the target is a muticharacter string type
233like a BMPString or a UTF8String.
234.PP
235For a more general solution \fIX509_NAME_get_index_by_NID()\fR or
74dab6c2
JR
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
984263bc
MD
238various \fBX509_NAME_ENTRY\fR utility functions on the result.
239.SH "EXAMPLES"
984263bc
MD
240Process 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
253Process 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"
74dab6c2 271\fIX509_NAME_get_index_by_NID()\fR and \fIX509_NAME_get_index_by_OBJ()\fR
984263bc
MD
272return the index of the next matching entry or \-1 if not found.
273.PP
74dab6c2 274\fIX509_NAME_entry_count()\fR returns the total number of entries.
984263bc 275.PP
74dab6c2
JR
276\fIX509_NAME_get_entry()\fR returns an \fBX509_NAME\fR pointer to the
277requested entry or \fBNULL\fR if the index is invalid.
984263bc 278.SH "SEE ALSO"
984263bc
MD
279ERR_get_error(3), d2i_X509_NAME(3)
280.SH "HISTORY"
74dab6c2
JR
281TBA
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,
286X509_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
984263bc 302.IX Header "HISTORY"
74dab6c2 303