KAL
Menu

Membaca Man Page dan Dokumentasi

Struktur man page, cppreference, dan draf standar sebagai kebiasaan kerja mandiri.

Daftar isi

Semua jawaban tentang pustaka standar C pada akhirnya bermuara pada tiga sumber, yaitu halaman manual (man page) di mesin kerja, situs referensi cppreference untuk kebutuhan cepat, dan draf standar untuk ketelitian penuh. Topik ini membahas struktur ketiganya beserta cara membacanya dengan efisien, karena kemampuan mencari jawaban sendiri menentukan kecepatan belajar setelah jalur ini selesai. Dokumentasi yang dibaca dengan benar juga menjadi pengganti ingatan, karena tidak ada pengembang yang menghafal prototipe seluruh fungsi pustaka standar.

Struktur halaman man#

Halaman man disusun dengan pola tetap, sehingga letak informasi dapat ditebak setelah polanya dikenali. Bagian NAME berisi nama fungsi dalam satu baris, dan SYNOPSIS menyajikan prototipe lengkap beserta header-nya. DESCRIPTION menjelaskan perilakunya, RETURN VALUE menegaskan nilai kembali dalam keadaan berhasil maupun gagal, sedangkan ERRORS mendaftar kode errno beserta pemicunya. Bagian lain seperti ATTRIBUTES, VERSIONS, EXAMPLES, dan SEE ALSO melengkapi sesuai kebutuhan halamannya.

Nomor bagian pada nama halaman menunjukkan kategori isinya, dan notasi seperti printf(3) berarti halaman printf pada bagian 3. Pemisahan ini penting karena satu nama bisa muncul di beberapa bagian, misalnya printf sebagai perintah shell berada di bagian 1 sedangkan printf sebagai fungsi pustaka berada di bagian 3. Tabel berikut merangkum nomor bagian yang paling relevan:

BagianIsi
1Program yang dijalankan pengguna dari shell
2Panggilan sistem (syscall) kepada kernel
3Fungsi pustaka, termasuk seluruh pustaka standar C
4Berkas perangkat khusus di /dev
5Format berkas dan konvensinya, misalnya /etc/passwd
7Lain-lain, misalnya konvensi dan ikhtisar paket
8Perintah administrasi sistem

Perintah man menerima nomor bagian sebagai argumen pertama, sehingga man 3 printf langsung membuka halaman pustaka tanpa tersesat ke halaman perintah shell. Pada sandbox ini perintah man tidak terinstal, meskipun pohon direktori halamannya tetap dapat dilihat:

bash 
# daftar bagian halaman man yang tersedia di sandbox ini
ls -d /usr/share/man/man*
text Keluaran 
/usr/share/man/man1
/usr/share/man/man3
/usr/share/man/man5
/usr/share/man/man7
/usr/share/man/man8

Direktori bernomor itulah tempat halaman-halaman tersimpan, dan sandbox ini hanya memuat sebagian karena perpustakaan halamannya tidak lengkap. Bentuk pemanggilan lengkapnya berikut ini ditandai tidak-dijalankan, karena perintah man memang tersedia pada mesin kerja pada umumnya:

bash 
# tidak-dijalankan
# perintah man belum terinstal di sandbox, jalankan pada mesin sendiri
man 3 printf

Membaca SYNOPSIS dengan teliti#

Bagian SYNOPSIS adalah kontrak singkat sebuah fungsi, dan membacanya dengan teliti mencegah kesalahan tipe sejak awal. Man-pages untuk strlen misalnya menyajikan dua baris berikut:

text Contoh: bagian SYNOPSIS halaman strlen 
#include <string.h>
size_t strlen(const char *s);

Baris pertama menyatakan header yang wajib disertakan, dan baris kedua memuat prototipe lengkap. Dari prototipe itu terbaca bahwa parameter tidak pernah diubah karena bertipe const, dan panjang yang dihitung ditampung tipe size_t yang tidak bertanda. Karena nilai kembinya size_t, pencetakannya memakai %zu. Pada tampilan man asli, nama fungsi dicetak tebal dan nama parameternya dicetak miring, sedangkan penentu seperti const dan tipe tetap ditulis normal. Pola visual itu membantu mata membedakan bagian yang tetap dari bagian yang bebas diganti.

Bagian RETURN VALUE dan ERRORS melengkapi kontrak tersebut. RETURN VALUE menyatakan nilai yang ditandai kegagalan, misalnya NULL untuk fopen atau -1 untuk keluarga fungsi POSIX, sedangkan ERRORS memetakan kode errno ke sebab-sebabnya. Membaca kedua bagian itu sebelum menulis kode berarti pemeriksaan error yang diperlukan sudah diketahui sejak awal, bukan ditambal setelah program gagal diam-diam.

cppreference sebagai rujukan harian#

Situs cppreference menyusun pustaka standar C dalam bentuk yang mudah ditelusuri, dengan halaman akar pada en.cppreference.com/w/c yang memetakan seluruh header menurut kategori. Setiap halaman fungsi memuat prototipe lengkap pada beberapa versi standar, penjelasan perilakunya, catatan khusus termasuk kasus yang tidak terdefinisi, dan contoh yang dapat disalin. Halaman header seperti inttypes.h menampilkan tabel makro yang jauh lebih mudah dibaca sekilas daripada halaman man yang berurut baris demi baris.

Situs ini menyajikan C dan C++ berdampingan, sehingga alamat yang diawali /w/c wajib diperiksa terlebih dahulu sebelum menyalin contohnya, karena sebagian fitur C++ tidak ada di C. Setiap halaman juga mencantumkan sejak versi standar mana fiturnya ada, dan keterangan itu berguna ketika program harus dijaga kompatibel dengan C11 atau C17. Untuk kebutuhan sehari-hari, cppreference adalah titik awal yang cepat, sedangkan pemeriksaan yang menuntut ketelitian dipindahkan ke sumber berikutnya.

Draf standar sebagai sumber terakhir#

Teks resmi standar C diterbitkan ISO dengan nomor ISO/IEC 9899, dan versi terbarunya dikenal sebagai C23, tetapi berkas resminya berbayar. Namun, kelompok kerja WG14 yang menulis standar itu menyediakan draf kerja (working draft) secara gratis di situs open-std.org, dan draf akhir hampir selalu berbeda dari teks resmi hanya pada hal administratif. Berkas N3220 adalah draf kerja C23, sedangkan N1570 adalah draf C11 yang masih sering dirujuk karena banyak platform menargetkan versi itu.

Draf standar menjadi sumber terakhir untuk pertanyaan yang tidak dijawab dokumentasi biasa, misalnya daftar lengkap perilaku tak terdefinisi, semantik tepat urutan pengevaluasian, dan definisi resmi istilah seperti sequence point. Dokumen POSIX.1-2024 yang dipublikasikan gratis oleh The Open Group melengkapi susunan ini untuk sisi lingkungan Unix. Halaman-halamannya memuat kontrak yang lebih terperinci untuk fungsi seperti fopen dan thread pada platform mengikuti POSIX. Dengan tiga lapis rujukan ini, yaitu man page untuk kerja harian, cppreference untuk kecepatan, dan draf standar untuk ketelitian, hampir seluruh pertanyaan tentang perilaku C dapat dijawab dari sumber primer.

Kesalahan umum#

Tiga kesalahan berikut paling sering muncul pada kebiasaan membaca dokumentasi yang baru terbentuk.

  • Membaca contoh tanpa membaca kontraknya. Contoh yang berhasil disalin belum tentu memuat pemeriksaan error yang disyaratkan, sehingga programnya rapuh. Selalu telusuri RETURN VALUE dan ERRORS sebelum pola dari contoh dipakai di kode sendiri.
  • Mencampur halaman C dan C++. Halaman cppreference untuk C++ memuat fitur yang tidak ada di C, dan sebaliknya. Pastikan alamatnya berawalan /w/c dan pilih bahasa C pada penelusurannya.
  • Membuka halaman yang salah bagian. Notasi man tanpa nomor bagian membuka halaman pertama yang ditemukannya, sehingga man printf bisa membuka perintah shell alih-alih fungsi pustakanya. Biasakan menyebut nomor bagiannya secara eksplisit, misalnya man 3 printf.
  • Menganggap draf sebagai teks resmi. Perbedaan kecil antara draf dan standar yang diterbitkan tetap ada, sehingga draf cukup untuk menelusuri perilaku teknis, tetapi kutipan formal sebaiknya tetap merujuk nomor bagian standar resminya.

Ringkasan#

  • Halaman man berstruktur tetap dengan NAME, SYNOPSIS, DESCRIPTION, RETURN VALUE, dan ERRORS, dan nomor bagiannya memisahkan perintah shell, panggilan sistem, serta fungsi pustaka.
  • SYNOPSIS adalah kontrak fungsi yang memuat header wajib, prototipe, dan konvensi tipe, sedangkan RETURN VALUE dengan ERRORS menyatakan cara kegagalannya dilaporkan.
  • cppreference menyajikan pustaka standar C pada alamat /w/c dengan tabel dan contoh yang mudah dipindai, lengkap dengan catatan versi standar fiturnya.
  • Draf kerja WG14 seperti N3220 memberi akses gratis ke isi standar C23, dan POSIX.1-2024 dari The Open Group melengkapinya untuk lingkungan Unix.

Referensi#