From 77f18fb6e2cdebea32af9779744685f1e035fd8c Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Mon, 18 Aug 2008 12:58:37 +0000 Subject: [PATCH] Documents getnetent_r(), getnetbyname_r(), and getnetbyaddr_r(), the reentrant equivalents of getnetent(), getnetbyname(), and getnetbyaddr(). --- man3/getnetent_r.3 | 145 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 145 insertions(+) create mode 100644 man3/getnetent_r.3 diff --git a/man3/getnetent_r.3 b/man3/getnetent_r.3 new file mode 100644 index 000000000..4d3d7df57 --- /dev/null +++ b/man3/getnetent_r.3 @@ -0,0 +1,145 @@ +.\" Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH GETNETENT_R 3 2008-08-19 "GNU" "Linux Programmer's Manual" +.SH NAME +getnetent_r, getnetbyname_r, getnetbynumber_r \- get +network entry (reentrant) +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int getnetent_r(struct netent *" result_buf ", char *" buf , +.BI " size_t " buflen ", struct netent **" result , +.BI " int *" h_errnop ); +.sp +.BI "int getnetbyname_r(const char *" name , +.BI " struct netent *" result_buf ", char *" buf , +.BI " size_t " buflen ", struct netent **" result , +.BI " int *" h_errnop ); +.sp +.BI "int getnetbyaddr_r(uint32_t " net ", int " type , +.BI " struct netent *" result_buf ", char *" buf , +.BI " size_t " buflen ", struct netent **" result , +.BI " int *" h_errnop ); +.sp +.fi +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.ad l +.in +.sp +.BR getnetent_r (), +.BR getnetbyname_r (), +.BR getnetbynumber_r (): +_BSD_SOURCE || _SVID_SOURCE +.ad b +.SH DESCRIPTION +The +.BR getnetent_r (), +.BR getnetbyname_r (), +and +.BR getnetbynumber_r () +functions are the reentrant equivalents of, respectively, +.BR getnetent (3), +.BR getnetbyname (3), +and +.BR getnetbynumber (3). +They differ in the way that the +.I netent +structure is returned, +and in the function calling signature and return value. +This manual page describes just the differences from +the non-reentrant functions. + +Instead of returning a pointer to a statically allocated +.I netent +structure as the function result, +these functions copy the structure into the location pointed to by +.IR result_buf . + +The +.I buf +array is used to store the string fields pointed to by the returned +.I netent +structure. +(The non-reentrant functions allocate these strings in static storage.) +The size of this array is specified in +.IR buflen . +If +.I buf +is too small, the call fails with the error +.BR ERANGE , +and the caller must try again with a larger buffer. +(A buffer of length 1024 bytes should be sufficient for most applications.) +.\" I can find no information on the required/recommended buffer size; +.\" the non-reentrant functions use a 1024 byte buffer -- mtk. + +If the function call successfully obtains a network record, then +.I *result +is set pointing to +.IR result_buf ; +otherwise, +.I *result +is set to NULL. + +The buffer pointed to by +.I h_errnop +is used to return the value that would be stored in the global variable +.I h_errno +by the non-reentrant versions of these functions. +.\" getnetent.3 doesn't document any use of h_errno, but nevertheless +.\" the non-reentrant functions no seem to set h_errno. +.SH "RETURN VALUE" +On success, these functions return 0. +On error, a positive error number is returned. + +On error, record not found +.RB ( getnetbyname_r (), +.BR getnetbynumber_r ()), +or end of input +.RB ( getnetent_r ()) +.I result +is set to NULL. +.SH ERRORS +.TP +.B ENOENT +.RB ( getnetent_r ()) +No more records in database. +.TP +.B ERANGE +.I buf +is too small. +Try again with a larger buffer +(and increased +.IR buflen ). +.SH "CONFORMING TO" +These functions are GNU extensions. +Functions with similar names exist on some other systems, +though typically with different calling signatures. +.SH "SEE ALSO" +.BR getnetent (3), +.\" FIXME . Add SEE ALSO from the above page to this page. +.\" FIXME make links for this page. +.BR networks (5)