FSETPOS(3POSIX)

✨ FSETPOS(3POSIX) ✨

okay bestie, gather round, because today we're talking about fsetpos — the little glow-up function that sets your current file position 💅 and honestly? she's iconic. this page is part of the POSIX Programmer's Manual, so quick heads up before we dive in: the Linux implementation of this interface may differ (so pls consult the corresponding Linux manual page for the deets on Linux behavior), or honestly it might not even be implemented on Linux at all. no cap. 🫶

---

🌸 PROLOG 🌸

so like, real talk first: this whole page is chillin' inside the POSIX Programmer's Manual. that means the Linux version of this interface may behave differently, and if you're on Linux you should go read the matching Linux man page instead. and yeah — it's also possible this interface just straight up isn't implemented on Linux. vibe check accordingly. 💀

---

🎀 NAME 🎀

fsetpos — set current file position

---

🦋 SYNOPSIS 🦋

#include <stdio.h>

int fsetpos(FILE *stream, const fpos_t *pos);

---

💖 DESCRIPTION 💖

okay so the functionality on this page is aligned with the ISO C standard. and if anything here ever conflicts with the ISO C standard? that was not on purpose, fr fr. this volume of POSIX.1‐2017 defers to the ISO C standard, periodt.

so what does the girl actually do? the fsetpos() function shall set the file position and state indicators for the stream pointed to by stream, according to the value of the object pointed to by pos. and here's the thing — your application shall ensure that pos is a value you got from an earlier call to fgetpos() on the same stream. like, same stream, bestie, don't be out here mixing them up 🙈. if a read or write error happens, the error indicator for the stream shall be set and fsetpos() fails.

now the slay part ✨: a successful call to fsetpos() shall clear the end-of-file indicator for the stream and undo any effects of ungetc() on that same stream. undoing, not me 💅. and after an fsetpos() call, the next operation on an update stream may be either input or output — she's flexible like that.

lowkey important caveat tho: the behavior of fsetpos() on devices which are incapable of seeking is implementation-defined. and the value of the file offset associated with such a device is undefined. so like… don't. 🙈

one more lil gem: the fsetpos() function shall not change the setting of errno if it succeeds. so if errno looks weird after a win, that's not her. 😌

---

🔥 RETURN VALUE 🔥

• the fsetpos() function shall return 0 if it succeeds 🎉
• otherwise? it shall return a non-zero value and set errno to indicate the error. rip. 😭

---

👑 ERRORS 👑

so the fsetpos() function shall fail if — either the stream is unbuffered, or the stream's buffer needed to be flushed — and the call to fsetpos() causes an underlying lseek() or write() to be invoked, and:

• EAGAIN — the O_NONBLOCK flag is set for the file descriptor and the thread would be delayed in the write operation.
• EBADF — the file descriptor underlying the stream file is not open for writing, or the stream's buffer needed to be flushed and the file is not open.
• EFBIG — an attempt was made to write a file that exceeds the maximum file size.
• EFBIG — an attempt was made to write a file that exceeds the file size limit of the process.
• EFBIG — the file is a regular file and an attempt was made to write at or beyond the offset maximum associated with the corresponding stream.
• EINTR — the write operation was terminated due to the receipt of a signal, and no data was transferred.
• EIO — a physical I/O error has occurred, or the process is a member of a background process group attempting to perform a write() to its controlling terminal, TOSTOP is set, the calling thread is not blocking SIGTTOU, the process is not ignoring SIGTTOU, and the process group of the process is orphaned. this error may also be returned under implementation-defined conditions.
• ENOSPC — there was no free space remaining on the device containing the file.
• EPIPE — an attempt was made to write to a pipe or FIFO that is not open for reading by any process; a SIGPIPE signal shall also be sent to the thread.
• ESPIPE — the file descriptor underlying stream is associated with a pipe, FIFO, or socket.

and the fsetpos() function may fail if:

• ENXIO — a request was made of a nonexistent device, or the request was outside the capabilities of the device.

heads up bestie: the following sections are informative — they're the chill extra reading, not the requirements. 🍓

---

🌈 EXAMPLES 🌈

None. like, literally none. she's mysterious. 💀

---

🧚 APPLICATION USAGE 🧚

None. nothing here either. the silence is loud. 🫶

---

💜 RATIONALE 💜

None. (we love a low-maintenance queen.) ✨

---

⭐ FUTURE DIRECTIONS ⭐

None. no notes, no plans, just vibes. 🦋

---

🌸 SEE ALSO 🌸

• Section 2.5, Standard I/O Streams
• fopen()
• ftell()
• lseek()
• rewind()
• ungetc()
• write()
• The Base Definitions volume of POSIX.1‐2017, <stdio.h>

---

🎀 COPYRIGHT 🎀

portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. in the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. the original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. to report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .

---

and that's the whole page bestie!! 🥳💖 this lil gem came to you from IEEE/The Open Group, 2017, and her whole entire name is FSETPOS(3POSIX). go set some file positions, stay hydrated, and don't forget: if errno is fine, she didn't touch it. periodt. 💅✨🎀