GETNETCONFIG(3)

💖 GETNETCONFIG(3) 💖 — the group chat guide to the netconfig database

okay bestie, this one lives in the Library Functions Manual and it's basically the whole friend group of functions that let your app go shopping in the system network configuration database. seven functions, one page, let's go 🛍️✨

🌸 NAME 🌸

getnetconfig, setnetconfig, endnetconfig, getnetconfigent, freenetconfigent, nc_perror, nc_sperror — get network configuration database entry

🎀 SYNOPSIS 🎀

#include <netconfig.h>

struct netconfig *
getnetconfig(void *handlep);

void *
setnetconfig(void);

int
endnetconfig(void *handlep);

struct netconfig *
getnetconfigent(const char *netid);

void
freenetconfigent(struct netconfig *netconfigp);

void
nc_perror(const char *msg);

char *
nc_sperror(void);

✨ DESCRIPTION ✨

so the whole point of this little library crew is giving your application access to the system network configuration database, which lives at /etc/netconfig. that's the vibe. 💅

The getnetconfig() function hands you a pointer to the current entry in the netconfig database, all formatted pretty as a struct netconfig. Call it again? You get the next entry. Again? Next one. It's giving "keep swiping" energy 🔁. You can literally walk the entire netconfig file with it, and when you hit the end of the file, getnetconfig() returns NULL. The handlep argument is the handle you got from setnetconfig().

A call to setnetconfig() is basically binding to or rewinding the netconfig database — like scrolling all the way back to the top of the feed 🌀. You must call setnetconfig() before your very first getnetconfig() call, and honestly you can call it whenever else you want too. But bestie, listen: you do not need to call setnetconfig() before calling getnetconfigent(). Different lane, different rules. setnetconfig() returns a unique handle, and that handle is what getnetconfig() needs.

The endnetconfig() function is your "okay we're done here, clean up" moment — call it when processing is complete so resources can be released and reused. The handlep argument is the handle you got from setnetconfig(). But ⚠️ programmers should be aware: the last call to endnetconfig() frees all the memory that getnetconfig() allocated for the struct netconfig data structure. All of it. Gone. So don't be out here holding pointers like they're still valid 👀. Also endnetconfig() may not be called before setnetconfig() — no skipping steps, that's not the vibe.

The getnetconfigent() function returns a pointer to the netconfig structure that corresponds to netid. If netid is invalid — meaning it doesn't name an entry in the netconfig database — you get NULL. that's it, that's the deal 🙈

The freenetconfigent() function frees the netconfig structure pointed to by netconfigp, which should be something you previously got back from getnetconfigent(). recycle your pointers, queen ♻️

The nc_perror() function prints a message to standard error explaining why any of the above routines failed. The message gets the string msg and a colon prepended to it, and a newline character gets appended at the end. nice and tidy, no notes 💅

The nc_sperror() function is basically nc_perror()'s twin, except instead of yeeting the message to standard error, it returns a pointer to a string containing the error message. same energy, different delivery method 🎁

Oh and btw, nc_perror() and nc_sperror() can also be used with the NETPATH access routines defined in getnetpath(3). they're versatile like that, they get along with everyone 🫶

🔥 RETURN VALUES 🔥

• setnetconfig() returns a unique handle for getnetconfig() to use. If something goes wrong, it returns NULL, and you can hit up nc_perror() or nc_sperror() to find out why it failed. spill the tea, error message 📢
• getnetconfig() returns a pointer to the current entry in the netconfig database, formatted as a struct netconfig. It returns NULL at the end of the file, or if it just... fails. 😭
• endnetconfig() returns 0 on success and -1 on failure — for example, if setnetconfig() was never called before it. rude of you, honestly.
• On success, getnetconfigent() returns a pointer to the struct netconfig structure corresponding to netid; otherwise it returns NULL. periodt.
• nc_sperror() returns a pointer to a buffer containing the error message string. ⚠️ heads up: this buffer is overwritten on each call. And in multithreaded applications, this buffer is implemented as thread-specific data. so like, don't expect it to remember things, it's very much a "living in the moment" buffer 🦋

🗂️ FILES 🗂️

• /etc/netconfig

🌈 AVAILABILITY 🌈

These functions are part of libtirpc. iconic of them, honestly 👑

👀 SEE ALSO 👀

• getnetpath(3)
• netconfig(5)

and that's the whole page bestie, you ate it 💖 this one came from Debian, dated April 22, 2000 — yeah, vintage, but the slay is timeless ✨🎀🦋